doc-extract-mcp

Un servidor MCP (Model Context Protocol) que proporciona a un LLM herramientas deterministas para trabajar con documentos en flujos de extracción de datos estructurados. El LLM hace la lectura y el razonamiento de extracción; este servidor proporciona las partes que nunca deberían delegarse en un modelo de lenguaje: acceso fiable a archivos, análisis sintáctico, fragmentación en chunks, validación de JSON Schema y salida de archivos protegida.

Construido por Koray Nar como un proyecto de portafolio para los flujos de trabajo de automatización documental con IA que está desarrollando. El caso de uso objetivo es convertir PDFs desordenados (órdenes de compra, facturas, informes) en JSON validado contra esquema. Publicado como parte de un portafolio público. Se integra con Claude Code y Claude Desktop, y con cualquier otro cliente MCP.

Por qué

Un agente de extracción falla en lugares predecibles: alucina contenidos de archivos, pierde la pista de documentos largos, produce silenciosamente JSON que casi coincide con el esquema objetivo y escribe la salida donde le parece. Este servidor elimina estos modos de fallo:

• El acceso a archivos está confinado a una única raíz permitida (DOC_EXTRACT_ROOT).

• El texto de los PDF llega con marcadores explícitos --- page N ---, de modo que las citas de «page 3» significan página 3.

• Los documentos largos se dividen en chunks de forma determinista, con solapamiento y pistas de página.

• El JSON extraído se valida contra un JSON Schema (Draft 2020-12) y se notifican todos los errores con su ruta JSON Pointer — no solo el primero — para que el modelo pueda corregir todos los fallos en una sola pasada.

• La salida la escribe el servidor (JSON o CSV), dentro de la misma raíz, con un recuento verificable de filas y bytes.

Related MCP server: BigContext MCP

Herramientas

Todos los argumentos de ruta se resuelven y se rechazan si se salen de la raíz permitida (protección contra path traversal). El argumento glob_pattern está confinado de la misma manera: se rechazan los patrones absolutos y los que contienen .., y cualquier coincidencia que se resuelva fuera de la raíz (por ejemplo mediante un symlink) se descarta silenciosamente del listado. Los fallos de protección se lanzan como errores de herramienta MCP, de modo que el modelo que llama de la llamada vea el motivo real y no un error genérico enmascarado.

Inicio rápido

Requiere Python 3.11+ y uv.

git clone https://github.com/koraynar/doc-extract-mcp.git
cd doc-extract-mcp
uv venv
uv pip install -e .

Ejecución independiente (transporte stdio):

DOC_EXTRACT_ROOT=/path/to/your/documents uv run doc-extract-mcp

Claude Code

claude mcp add doc-extract --env DOC_EXTRACT_ROOT=/path/to/your/documents \
  -- uv run --directory /absolute/path/to/doc-extract-mcp doc-extract-mcp

Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "doc-extract": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/doc-extract-mcp",
        "doc-extract-mcp"
      ],
      "env": {
        "DOC_EXTRACT_ROOT": "/path/to/your/documents"
      }
    }
  }
}

DOC_EXTRACT_ROOT adopta el directorio de trabajo del servidor si no se define. Pero debe apuntar a la carpeta donde están tus documentos; nada fuera de ella se puede leer ni escribir.

Flujo de trabajo típico

1. list_documents("", "*.pdf") — encuentra las facturas.

2. document_info("invoice.pdf") — comprueba el número de páginas.

3. read_document("invoice.pdf", "1-3") or chunk_document(...) — obtén el texto.

4. El LLM extrae los campos a JSON.

5. validate_json(data, json_schema) — corrige todos los errores notificados y vuelve a validar.

6. save_structured("out/invoice.json", data, "json") — escribe el resultado exacto.

Limitaciones (honestas)

• Solo PDFs con una plantilla de texto. La extracción usa pypdf; los PDF escaneados o solo de imagen devuelven texto vacío. No hay OCR.

• La calidad de extracción varía con la forma de balancear el PDF. Los resúmenes complejos (multiples columnas, tablas pesadas) pueden tener un orden de lectura no perfecto: se hereda de pypdf.

• No hay soporte para .docx/.xlsx. Son compatibles .pdf, .txt, .md, .csv, .json.

• El servidor no hace razonamiento de extracción. No va a encontrar el total de tu factura; solo se asegura de que el modelo que lo haga trabaje con texto real y que el resultado coincida con tu esquema.

• Es una herramienta funcional, pensada para el trabajo de automatización con IA que estoy montando, y publicada como parte de mi portafolio — es nueva y todavía no tiene recorrido en producción. Tiene lituratura de pruebas y una baruna de confinamiento de rutas, pero no ha sido endurecida más allá de eso — revísala antes de poner directorios sensibles.

Desarrollo

uv venv
uv pip install -e '.[dev]'
uv run pytest

El suite de pruebas construye en memoria un fixture PDF de dos páginas (aparato PDF mínimo construido a mano, sin dependencias extra) y cubre las seis herramientas, la protección de path traversal, el confinamiento del glob pattern (incluidos los escapes via symlink), los rangos de página, la validación de esquema con múltiples errores, un round-trip de CSV, y el registro de herramientas y la propagación de errores a través del archivo objeto del servidor MCP.

Licencia

MIT © 2026 Kurt Langer