Doc Extract Mcp

io.github.koraynarPublished by GitHub account koraynarv0.1.0Updated Oct 27, 2026

Document tooling for AI agents: PDF/text reading, chunking, schema-validated JSON output.

VerifiedSTDIODesktop onlyFiles & StorageData & Analytics

Overview

AI-generated overview

Local MCP server giving an assistant deterministic document tooling: listing, reading and chunking PDFs and text files, validating JSON against a schema, and…

What you can do
  • List files under an allowed root, including recursive glob patterns
  • Read document text from PDFs (with page markers and page ranges), text, Markdown, JSON and CSV
  • Inspect metadata such as type, size, page count and line count
  • Split long documents into ordered overlapping chunks with page hints
  • Validate JSON against a JSON Schema and report every error with a JSON Pointer path
  • Write extracted data as JSON or CSV inside the allowed root, returning row and byte counts
When to use it
Useful when an assistant must turn messy PDFs such as invoices, purchase orders or reports into schema-validated JSON, and you want file access confined to one folder with deterministic chunking and validation instead of relying on the model to read files itself.
Requirements
Runs locally over stdio; needs Python 3.11+ and uv, installed from the project's repository. The DOC_EXTRACT_ROOT environment variable sets the single folder that can be read and written; it defaults to the server's working directory if unset. Desktop MCP clients only.
Before you install
The server writes files: save_structured creates JSON or CSV output inside the allowed root, so point DOC_EXTRACT_ROOT at a dedicated folder rather than a sensitive one. The author states it is new, has no production mileage and is not hardened beyond tests and a path-confinement guard. Only text-based PDFs work; scanned PDFs yield empty text and there is no OCR.

Installation

In SourceWeft

  1. Open Doc Extract Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

doc-extract-mcp

An MCP (Model Context Protocol) server that gives an LLM deterministic document tooling for structured-data extraction workflows. The LLM does the reading and extraction reasoning; this server provides the parts that should never be left to a language model: reliable file access, parsing, chunking, JSON Schema validation, and guarded file output.

Built by Koray Nar as a portfolio project for the AI document-automation workflows he is building — the target use case is turning messy PDFs (purchase orders, invoices, reports) into schema-validated JSON. Published as part of a public portfolio. Pairs with Claude Code and Claude Desktop, and with any other MCP client.

Why

An extraction agent fails in predictable places: it hallucinates file contents, loses track of long documents, silently produces JSON that almost matches the target schema, and writes output wherever it likes. This server removes those failure modes:

  • File access is confined to one allowed root (DOC_EXTRACT_ROOT).
  • PDF text arrives with explicit --- page N --- markers, so citations of "page 3" mean page 3.
  • Long documents are chunked deterministically with overlap and page hints.
  • Extracted JSON is checked against a JSON Schema (Draft 2020-12) and every error is reported with a JSON Pointer path — not just the first — so the model can fix all mistakes in one pass.
  • Output is written by the server (JSON or CSV), inside the same root, with a verifiable row/byte count.

Tools

ToolArgumentsWhat it does
list_documentsdirectory, glob_pattern='*'List files under a directory inside the allowed root, with size and modified time. Supports recursive globs like **/*.pdf. Patterns must be relative and free of ..; matches resolving outside the root are dropped.
read_documentpath, pages=''Return a document's text. .pdf via pypdf with --- page N --- markers and optional 1-indexed page selection ('3', '1-5', '1-3,7'); .txt/.md/.json read directly; .csv rendered as an aligned text table. Clear error for unsupported types.
document_infopathMetadata without full content: type, size, modified time; page count and PDF metadata for PDFs; line count for text files.
chunk_documentpath, max_chars=4000, overlap=200Split a document into ordered overlapping chunks, each with an index, start offset, and (for PDFs) a page hint.
validate_jsondata, json_schemaValidate a JSON string against a JSON Schema (Draft 2020-12). Returns every validation error with a JSON Pointer path via Draft202012Validator.iter_errors.
save_structuredpath, data, format='json'|'csv'Write extracted data inside the allowed root. CSV expects a JSON array of flat objects. Returns written path, row count, and byte count.

All path arguments are resolved and refused if they escape the allowed root (path traversal guard). The glob_pattern argument is confined the same way: absolute patterns and patterns containing .. are rejected, and any match that resolves outside the root (for example through a symlink) is silently dropped from the listing. Guard failures are raised as MCP tool errors, so the calling model sees the actual reason, not a masked generic error.

Quickstart

Requires Python 3.11+ and uv.

bash
git clone https://github.com/koraynar/doc-extract-mcp.gitcd doc-extract-mcpuv venvuv pip install -e .

Run standalone (stdio transport):

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

Claude Code

bash
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

Add to claude_desktop_config.json:

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 defaults to the server's working directory if unset. Set it to the folder your documents live in; nothing outside it can be read or written.

Typical workflow

  1. list_documents(".", "*.pdf") — find the invoices.
  2. document_info("invoice.pdf") — check the page count.
  3. read_document("invoice.pdf", "1-3") or chunk_document(...) — get text.
  4. The LLM extracts fields into JSON.
  5. validate_json(data, json_schema) — fix every reported error, revalidate.
  6. save_structured("out/invoice.json", data, "json") — write the result.

Limitations (honest ones)

  • Text-based PDFs only. Extraction uses pypdf; scanned/image-only PDFs yield empty text. There is no OCR.
  • Extraction quality varies with how the PDF was produced. Complex layouts (multi-column, heavy tables) may come out with imperfect reading order — that is a pypdf characteristic this server inherits.
  • No .docx / .xlsx support. Supported types are .pdf, .txt, .md, .csv, .json.
  • The server does no extraction reasoning. It will not find your invoice total; it makes sure the model that does is working from real text and that the result matches your schema.
  • This is a working tool, built for the AI-automation work I'm building up and published as part of my portfolio — it is new and has no production mileage yet. It has tests and a path-confinement guard, but it has not been hardened beyond that — review before pointing it at sensitive directories.

Development

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

The test suite builds a small two-page PDF fixture in-memory (a minimal hand-constructed PDF, no extra dependencies) and covers all six tools, the path-traversal guard, glob-pattern confinement (including symlink escapes), page-range errors, multi-error schema validation, a CSV round-trip, and tool registration plus error propagation through the MCP server object.

License

MIT © 2026 Koray Nar

Source: README.md at commit 409da2e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts