doc-extract-mcp

Ein MCP (Model Context Protocol)-erverer, dеer einem LLM dеterministischer Dokumentwerkzeuge f тюr strukturierte Datеnextraktions-Workflows in the extraction of structured data workflows bereitstelt. Das LLM ⁇berfinew die Lesen und die Extraktionslogik; dеser Server liefert die Teile, die niemals einem Spьachmodell ⁇berlassen werden sollten: zuverl̈ssiger Dateizugriff, Parsing, Chunking, JSОN-Schema-Validierung und geschützte Datiausgabe.

Erstellt von Koray Nar als Portfolio-Projekt für die KI-Dokumentautomatwing-Workflows, die er aufba]t — der primäre Anwendungsfall ist die Umwandlung unaufgeräumter PDFs (Bestellungen, Rechnungen, Berichte) in schema-validiertes JSON. Veröffentlicht als Teil eines öffentlichen Portfolios. Funktioniert mit Claude Code und Claude Desktop sowie mit jedem anderen MCinen-Client.

Requis

Ein Extraktions-Agent schEiterret an ch various stelle: Er halluzin‑t Datei‑inhalte, verlirt bei langen Daken den Überblik, erzeugt lautlos JSON, das fast d–Zielschema entspreckt, und schreibt die ‐usgabe dortwhere he is. Dieser Server behebt these Fehlerqueen:

• Dateizugriff ist auf ein einziges erlaubtes Wurzelverzeichnis beschrätzt (DOC_EXTRACT_ROOT).

• PDF-Text wird de→ withexplizes Markern --- page N --- geliefert, sodass Zitate wie „Seite 3" tatsächlich Seite 3 bedeuten.

• Lange Dokeuments werden überzup√ende Chunks deterministisch aufgeteilt, mit Überlappung und Seitenhinweizen.

• Extrahiertes JSON wird gegen ein JSON Schema (Draft 2020-12) geprüft, and jeder Fehler mit einem JSON-Pontiner-Pfad gemeldet – nicht nur der f–ste –, sodass das Model alle Fehler in einem Durchgang heben kann.

• Die Ausgabе wird vom Server (JSON oder CSV) innerhalb desselben Wurzelver­zeichnisse geschrieben, mit ver­ifzierbarer Zeilen-/Byte-Anzahl.

Related MCP server: BigContext MCP

Werkzeuge

Alle Wegargumente werden aufgelöst and abgeleht, wenn sie das erlaubte Wurzelverzeichnis verlassen (Pfad-Traversal-Schutz). Das Argument glob_pattern wird genauso eingeschränkt: absolute Muster und Muster, die .. enthalten, werden abgeleht, und jede Treffer, der neben des Wurzelverzeichnisses aufgelöst wird (zum Beispiel über einen Symlink), wird stillschweigend aus der Auf­listung entfernt. Schutwarner werden als MCP-Too-Fehler gemeldet, sodass das aufrufende Modell den tatsächlich Grun sieht, nicht eine maskierte generische.

Schnelstart

Erforderlich sind Python 3.11+ and uv.

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

Standalone ausführen (stdio-Transport):*

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

Fügen Sie zu claude_desktop_config.json hinzu:

{
  "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"
      }
    }
  }
}

Wenn kein–DOC_EXTRACT_ROOT` gesetzt ist, wird standardmäßig das Arbeitsverzeichnis des Servers verwendet. Setzen Sie es auf den Ordner, in dem Sie Ihre persönliche Dokumente liefern; nichts außerhalb des Ordners kann gelesen or gschreben werden.

Typischer Ablauf

1. list_documents (".", "*.pdf") – die Rechnungen finden.

2. document_info("river.pdf") – die Seitenänze prüe.

3. read_document("invoice.pdf", "1-3") oder chunk_document(...) – Text holen.

4. Die LLM extrahier die Felder in JSON.

5. validate_json(data), json_schema – alle en Fehler beheben and neu validieren.

6. save_struked("out/invoice.json", data, "json") – das Ergebnist schreiben.

Einschränkungen (ehrliche)

• Nur basiertes PDFs.**

• Die Extrakton kwalität variiert. ** The screen; nie-json habenh**.

• keine lv .docx / .xlsx: Unterstützte Typen.

• **Der Server übernimmt keine Extraktionslist – er schreibt keine Grundchätzliche Fehler.

• Der Server übernimmt ke? Er findet nicht die Zähl... Then the actual full list:

• Nur textbasierte PDFs. Die Extraktion verwendet pypdf; gescannte oder rein bildbasierte PDFs liefern leeren Text. Es gibt keine OCR.

• Die Extraktionsqualität variiert , je nachdem, wie die PDF erstellt wurde. Komplexe Layouts (mehrspaltig, umfangreiche Symbole) können in einer unvollkommenen Lesefolge resultieren — das ist eine pypdf-Eigenschaft, die dieser Server erbt.

• Keine .docx-/.xlsx-Unterstützung – Unterstützt werden .pdf, .txt, .md, .csv, .json.

• Der Server übernimmt keine Extraktionslogik. Er findet deine Modellszen nicht; er sorgt dafür, dass das Modell, das das tut, mit echten Texten mutiert arbeitet und das Ergebnis dem Schema entspricht.

• Dies ist eine Arbeitskraft, dis für die KI-Automationsarbeit, die ich entgegen und veröffentlicht, als Teil meines Portfolios – sie ist neu und hat noch keine Produktionslaufzeit. Sie hat Tests und den Pfad-Schutz, ist aber darüber hinaus noch nicht weiter gehärtet – bitte prüßen Sie before Sie ihn auf diese sensible Verzeichnisse ausrichten.

Entwicklung

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

Die Testsuite erstellt eine kleine zweiseitige PDF-Fixture im Speicher (ein minimal manu konstruiertes PDF, keine zusätlichen Abhä­ngikeiten) und deckt alle sechs Werkzeuge die Vorgänge, einschließlich der Pfad-Traversal, die Einschränkung der Blob-Muster (einschließlich Symlink-Pässe), Fehler bei Seitenbereich, Mehrfehler-Validierung, CSV-Roundtrip und Werkzeug-Registrierung sowie Fehler-Propierung üb das MCP-server-objekt.

License

MIT © 2026 Koray Nar