pdf-extract-mcp

Un servidor del Model Context Protocol (MCP) que extrae datos estructurados de documentos PDF no estructurados de forma determinista: extracción de texto plano más coincidencia de campos mediante regex/heurísticas, sin llamadas a la API de LLM en el momento de la extracción.

Características

• Servidor MCP real — construido sobre el SDK oficial de MCP para Python (2.x), que habla el protocolo a través de stdio, SSE o streamable HTTP. Verificado por una prueba de extremo a extremo que impulsa el servidor real con el cliente oficial.

• Extracción guiada por esquema — apunta extract_fields a cualquier JSON Schema y obtén JSON estructurado con exactamente los campos que pediste.

• Determinista e inspeccionable — coincidencia mediante regex/heurísticas, sin llamadas a la API de LLM, sin costes ocultos, sin caja negra. Cada extracción es repetible y auditable.

• Informes de validación legibles para humanos — validate_against_schema explica por campo por qué pasó, falló o falta.

• Esquemas predefinidos — invoice, resume y purchase_order se incluyen listos para usar, además de PDFs de muestra sintéticos para que todo sea demostrable sin configuración adicional.

• Errores controlados — los PDF corruptos, los archivos inexistentes y los esquemas inválidos devuelven errores estructurados, nunca trazas de pila.

Related MCP server: StructureAI MCP Server

Qué es MCP y por qué es útil

El Model Context Protocol es un estándar abierto que permite a los asistentes de IA (Claude, Cursor, etc.) llamar a herramientas externas a través de una conexión persistente y bidireccional. En lugar de pegar el texto de un PDF en un chat y pedirle al modelo que lo «descifre», un asistente puede llamar a pdf-extract-mcp directamente, recibir JSON estructurado que coincida con un esquema que tú proporcionas, y actuar sobre él. Como la extracción aquí es determinista (regex + heurísticas), no una llamada a un modelo probabilístico, cada resultado es inspeccionable, repetible y barato. Esto lo hace ideal para canalizaciones automatizadas de documentos (facturas a contabilidad, currículos a ATS, órdenes de compra (POs) a adquisiciones) donde necesitas saber por qué un campo se extrajo de determinada manera.

Instalación

cd pdf-extract-mcp
python3 -m venv .venv
source .venv/bin/activate
make install          # pip install -e ".[dev]"  (installs the console script too)

o, con pip simple:

pip install -e ".[dev]"

El servidor utiliza el SDK oficial de MCP para Python (mcp >= 2.x, la línea de versión actual, que proporciona la API MCPServer). pdfplumber se encarga de la extracción de texto, jsonschema de la validación y reportlab genera los PDFs de muestra.

La instalación también proporciona un script de consola pdf-extract-mcp, por lo que puedes ejecutar el servidor desde cualquier lugar con:

pdf-extract-mcp                     # stdio (default)
pdf-extract-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Ejecución

python server.py

Esto sirve MCP a través de stdio (el valor predeterminado, y lo que esperan Claude Code / Claude Desktop). También puedes exponerlo como un servicio de red:

python server.py --transport streamable-http --host 127.0.0.1 --port 8000
python server.py --transport sse --host 127.0.0.1 --port 8001

Conectar con Claude Code / Claude Desktop

Claude Code — añade un .mcp.json a la raíz de tu proyecto:

{
  "mcpServers": {
    "pdf-extract": {
      "command": "python",
      "args": ["/absolute/path/to/pdf-extract-mcp/server.py"],
      "env": {}
    }
  }
}

Claude Desktop — añade el mismo bloque a la configuración de Claude Desktop (claude_desktop_config.json, ubicado en ~/Library/Application Support/Claude/ en macOS):

{
  "mcpServers": {
    "pdf-extract": {
      "command": "python",
      "args": ["/absolute/path/to/pdf-extract-mcp/server.py"]
    }
  }
}

Reinicia el cliente después de guardar. Deberías ver tres nuevas herramientas: extract_fields, validate_against_schema y list_supported_document_types.

Herramientas

El argumento schema de extract_fields acepta un objeto JSON Schema, un nombre de esquema integrado (p. ej. "invoice"), o una ruta a un archivo de esquema .json. Los esquemas integrados se encuentran en schemas/:

• invoice — vendor_name, invoice_number, total_amount, due_date (obligatorio) + issue_date, customer_name

• resume — name, email (obligatorio) + phone, skills

• purchase_order — po_number, vendor_name, total_amount (obligatorio) + issue_date, customer_name

Ejemplo práctico

Primero genera los PDFs de muestra (ya presentes en el repositorio; regenéralos en cualquier momento con):

python sample_pdfs/generate_samples.py

Ahora llama a extract_fields sobre la factura de muestra usando el nombre del esquema integrado invoice. En Claude Code puedes simplemente decir "extrae los campos de sample_pdfs/invoice.pdf usando el esquema invoice"; por debajo, emite una llamada a herramienta equivalente a:

{
  "name": "extract_fields",
  "arguments": {
    "pdf_path": "/absolute/path/to/pdf-extract-mcp/sample_pdfs/invoice.pdf",
    "schema": "invoice"
  }
}

Resultado real esperado:

{
  "ok": true,
  "data": {
    "vendor_name": "Acme Widgets Corp",
    "invoice_number": "INV-2024-0087",
    "total_amount": 1750.0,
    "due_date": "April 1, 2024",
    "issue_date": "March 1, 2024",
    "customer_name": "Globex Industries"
  },
  "text_length": 372
}

Introduciendo los datos en validate_against_schema con el mismo esquema:

{
  "ok": true,
  "valid": true,
  "passed": ["customer_name", "due_date", "invoice_number", "issue_date", "total_amount", "vendor_name"],
  "failed": [],
  "missing": [],
  "summary": "Valid: all 6 present field(s) conform to the schema.",
  "error": null
}

Ejecuta estos ejemplos desde Python directamente para verlo en vivo:

import json
from tools.extract import extract_fields
from tools.validate import validate_against_schema

schema = json.load(open("schemas/invoice.json"))
result = extract_fields("sample_pdfs/invoice.pdf", schema)
print(result["data"])
print(validate_against_schema(result["data"], schema))

Cómo funciona el registro de herramientas MCP en server.py

Esta es la parte central del proyecto, por lo que vale la pena entender exactamente qué hace el SDK por ti.

1. Crea el objeto del servidor.

from mcp.server.mcpserver import MCPServer

mcp = MCPServer(
    "pdf-extract-mcp",
    title="PDF Extract MCP",
    description="Deterministic structured-data extraction from PDF documents",
    version="0.2.0",
)

MCPServer es la clase de servidor del SDK de mcp 2.x. Implementa el protocolo de red MCP: sabe cómo responder a los mensajes JSON-RPC que un cliente envía durante el protocolo de enlace (handshake) de MCP (initialize, tools/list, tools/call, etc.). Los argumentos del constructor son metadatos: el nombre del servidor (requerido para el protocolo de enlace) más título/descripción/versión opcionales que los clientes pueden mostrar al usuario.

2. Registra cada herramienta con un decorador.

@mcp.tool()
def extract_fields(pdf_path: str, schema: dict) -> dict:
    """Extract structured fields from an unstructured PDF ..."""
    return _extract_fields(pdf_path, schema)

El decorador hace tres tareas por ti:

• Registro del nombre — el nombre de la función extract_fields se convierte en el nombre de la herramienta que un cliente usa para invocarla. (Puedes sobrescribirlo con @mcp.tool(name="...").

• Inferencia del esquema — el SDK inspecciona las anotaciones de tipo de la función (pdf_path: str, schema: dict) y genera automáticamente el esquema JSON de entrada de la herramienta. Por eso el cliente MCP sabe, antes de llamar, que pdf_path es una cadena y schema es un objeto. Este es el mismo patrón que usa FastAPI: los tipos son el contrato.

• Descripción — el docstring se convierte en la descripción de la herramienta, que Claude lee para decidir cuándo llamar a la herramienta y con qué argumentos.

3. El cuerpo de la función es solo Python.

Cuando un cliente llama a la herramienta (tools/call con argumentos), el SDK deserializa los argumentos JSON, llama a tu función con ellos y serializa el valor de retorno de vuelta a través del cable. El valor de retorno es lo que ve el cliente — por eso las herramientas siempre devuelven diccionarios JSON simples y nunca lanzan excepciones: una excepción se convertiría en un error de protocolo opaco, mientras que un diccionario estructurado {"ok": false, "error": "..."} es algo que Claude puede leer y al que puede reaccionar. La lógica real de extracción/validación se encuentra en tools/extract.py y tools/validate.py para que siga siendo comprobable mediante pruebas unitarias sin un cliente MCP.

4. Ejecútalo.

if __name__ == "__main__":
    main()   # argparse -> mcp.run(transport="stdio")

mcp.run(transport="stdio") inicia el bucle del protocolo: lee peticiones JSON-RPC delimitadas por saltos de línea desde stdin, las envía a las herramientas registradas y escribe las respuestas en stdout. Ese es todo el servidor — sin framework HTTP, sin rutas, sin manejo manual de peticiones. (Para streamable-http / sse, la misma llamada run() inicia una aplicación ASGI interna.)

Un detalle más que vale la pena señalar: extract_fields usa una pequeña función auxiliar _load_schema que acepta un dict de esquema, un nombre de esquema integrado o una ruta de archivo — de modo que la misma herramienta funciona con "invoice" o con un objeto de esquema completo. La función de extracción real se mantiene estricta (solo dict) y la capa del servidor maneja las conversiones de conveniencia.

Cómo funciona la extracción (determinista e inspeccionable)

1. Extracción de texto — pdfplumber abre el PDF y extrae el texto plano de cada página.

2. Coincidencia de campos — para cada propiedad de tu esquema, se prueba una lista ordenada de regex; la primera coincidencia gana (tools/extract.py -> _FIELD_PATTERNS). Los patrones se ordenan de más específicos a menos específicos, y los nombres de campo desconocidos recurren a una coincidencia genérica "Field Name: value", además de una tabla de sinónimos (_FIELD_ALIASES).

3. Coerción de tipos — las cadenas coincidentes se convierten al tipo del JSON Schema (p. ej. "$1,750.00" -> 1750.0 para "type": "number"; división por comas para arrays). Los fallos de coerción recurren a la cadena original en lugar de perder datos.

4. Validación — validate_against_schema vuelve a comprobar los datos extraídos con el paquete jsonschema e informa, por campo, si pasó, falló (con una razón legible para humanos) o si falta por completo.

Debido a que cada paso es código simple, puedes rastrear exactamente por qué un campo se extrajo o no — no hay caja negra.

Manejo de errores

Las tres herramientas devuelven JSON estructurado en todos los caminos — nunca lanzan una traza de pila a través del límite MCP:

• PDF corrupto/ilegible -> {"ok": false, "error": "Could not read PDF ..."}

• Archivo inexistente -> {"ok": false, "error": "PDF not found: ..."}

• PDF sin texto extraíble -> {"ok": false, "error": "... contains no extractable text."}

• Esquema inválido (vacío, sin propiedades o JSON Schema inválido) -> clave de error estructurado

• Campos obligatorios faltantes -> listados en "missing"; valores malformados -> listados en "failed" con razones

Pruebas

pytest tests/ -v

19 pruebas que cubren:

• Extracción exitosa para los tres tipos de documento (invoice, resume, purchase_order)

• Un PDF al que le faltan campos obligatorios (extracción negativa)

• Validación de esquema que detecta un tipo de campo malformado, campos obligatorios faltantes, violaciones de enum/patrón

• Rutas de error: PDF corrupto, archivo inexistente, PDF sin texto, esquema inválido

• Una prueba MCP real de extremo a extremo (tests/test_mcp_end_to_end.py) que lanza server.py como subproceso, se conecta a través de stdio con el cliente oficial de MCP y llama a las tres herramientas a través del cable — demostrando que es un servidor MCP genuino, no una biblioteca que pretende serlo

Los PDFs de muestra se regeneran automáticamente mediante tests/conftest.py si faltan.

Estructura del repositorio

pdf-extract-mcp/
  server.py                    # MCP server: MCPServer + tool registration + transports
  tools/
    __init__.py
    extract.py                 # pdfplumber text extraction + regex field matching
    validate.py                # jsonschema validation with structured reports
  schemas/
    invoice.json               # pre-built schema: invoice
    resume.json                # pre-built schema: resume
    purchase_order.json        # pre-built schema: purchase_order
  sample_pdfs/
    generate_samples.py        # reportlab generator for the 4 sample PDFs
    invoice.pdf
    invoice_missing_fields.pdf
    resume.pdf
    purchase_order.pdf
  tests/
    conftest.py                # auto-generates sample PDFs if missing
    test_tools.py              # unit tests for extract/validate
    test_mcp_end_to_end.py     # end-to-end test over the real MCP stdio transport
  README.md
  requirements.txt

Solución de problemas

• ModuleNotFoundError: No module named 'mcp' — no estás en el virtualenv: ejecuta source .venv/bin/activate (o usa ./.venv/bin/python server.py).

• Errores de importación de FastMCP — server.py apunta a la API de mcp 2.x (MCPServer). Si tu entorno tiene mcp 1.x, reinstala con pip install -U "mcp>=2.0".

• Las herramientas no aparecen en Claude — reinicia el cliente después de editar la configuración y asegúrate de que "args" apunta a la ruta absoluta de server.py, usando el python del venv como comando si es necesario.

• La extracción no encuentra un campo — añade un patrón para él en _FIELD_PATTERNS en tools/extract.py (o confía en el respaldo genérico "Field Name: value" y en la tabla de sinónimos).