convez.ai
MCP ServerDados & AnalyticsIntermediário
haoxinm

PDF Chart Parser

haoxinm/pdf-chart-parser

Extrai charts de PDFs com calibração automática de eixos e dados estruturados

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que extrai gráficos de charts de PDFs de contas de energia usando PyMuPDF. Localiza o gráfico, calibra eixos a partir da camada de texto e retorna dados estruturados em série temporal com PNG anotado — totalmente determinístico, sem necessidade de LLM.

Instalação

$npx convez-ai haoxinm/pdf-chart-parser

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Extração automática de dados de gráficos em faturas de energia
  • Processamento em lote de PDFs para análise de consumo
  • Integração com pipelines de automação de documentos

Veredito

Ferramenta sólida e especializada para extração de gráficos de faturas. Implementação determinística com fallback OCR oferece confiabilidade, mas escopo restrito a energy-bill PDFs limita aplicabilidade geral. Excelente para casos de uso muito específicos em automação de contas de utilidade.

README

A tradução para o português deste README ainda está na fila.

pdf-chart-parser

An MCP server and Python library that extracts energy-usage charts from utility-bill PDFs. It locates the chart, calibrates the axes from the PDF's text layer, and returns structured time-series data alongside an annotated PNG for visual verification — entirely deterministic, no LLM required.

Features

  • Bar, line, and hybrid (bar + line, dual y-axis) chart types
  • Vector-first extraction via PyMuPDF get_drawings() / get_text("dict"); OpenCV + OCR raster fallback for scanned PDFs
  • Full page text returned as LLM-friendly Markdown (via pymupdf4llm)
  • MCP tool (extract_usage_chart) compatible with Claude and other MCP-aware LLMs
  • Supports stdio transport (local) and streamable-http (containerized deployment)
  • Returns structured JSON + annotated PNG; numeric data is always text content

Installation

Prerequisites

  • Python 3.12+
  • uv package manager
  • Tesseract OCR (required only for the [raster] extra): apt-get install tesseract-ocr or brew install tesseract

Quickstart

# Install (vector path only)
uv sync

# Install with raster/OCR fallback
uv sync --extra raster

# Run the CLI
uv run pdf-chart-parser --help

# Run the MCP server (stdio)
uv run python -m pdf_chart_parser.server

Usage

Python library

from pdf_chart_parser.pipeline import extract_usage_chart

result = extract_usage_chart(pdf_path="bill.pdf", return_annotated_image=True)
print(result["chart_type"])   # "bar" | "line" | "hybrid"
for series in result["series"]:
    print(series["label"], series["points"])

CLI

uv run pdf-chart-parser extract bill.pdf --output result.json

MCP server

Add to your MCP config (~/.claude/claude_desktop_config.json or similar):

{
  "mcpServers": {
    "pdf-chart-parser": {
      "command": "uv",
      "args": ["run", "python", "-m", "pdf_chart_parser.server"],
      "cwd": "/path/to/pdf-chart-parser"
    }
  }
}

The server exposes the extract_usage_chart tool. It returns:

  1. Page text — full page as Markdown
  2. Chart reading — structured JSON (series, axes, confidence, warnings)
  3. Annotated PNG — cropped chart with calibrated gridlines and data-point markers

Docker / ECR deployment

# Build and run locally
./scripts/run_local_server.sh

# Build and push to ECR (set ECR_REPO first)
export ECR_REPO=<account>.dkr.ecr.<region>.amazonaws.com/pdf-chart-parser
./scripts/build_and_push.sh

The container starts the server on streamable-http at port 8000. A local PDF directory can be bind-mounted to /data for ad-hoc testing (see docker/docker-compose.yml).

Manual testing (no LLM)

# In-process test against fixtures
uv run python scripts/run_manual_tests.py

# Against a running HTTP server
uv run python scripts/run_manual_tests.py --http http://localhost:8000

Output is written to manual_test_output/.

License

AGPL-3.0-or-later. This license is required because the project links against PyMuPDF, which is itself AGPL-3.0 licensed.

Ver o original no GitHub

Bom para

Relacionados