doc-extract-mcp

一个 MCP（Model Context Protocol）服务器，为结构化数据提取工作流提供确定性的文档工具。LLM 负责阅读和提取推理；这个服务器提供那些绝不该交给语言模型的部分：可靠的文件访问、解析、分块、JSON Schema 校验，以及受保护的文件输出。

由 Koray Nar 作为作品集项目开发，用于他正在构建的 AI 文档自动化工作流——目标用例是将凌乱的 PDF（采购订单、发票、发票）转换为通过 schema 校验的 JSON。作为公开作品集的一部分发布。可与 Claude Code、针对 Claude Desktop 以及任何其他 MCP 客户端搭配使用。

为什么

提取代理会在可预期的地方失败：它凭空捏造文件内容、在长文档里丢失上下文、默默产出几乎符合目标 schema 的 JSON，并把输出写到它喜欢的位置。这个服务器消除了这些失败模式：

• 文件访问被限制在一个允许的根目录下（DOC_EXTRACT_ROOT）。

• PDF 文本带有显式的 --- page N --- 标记，因此“第 3 页”这种引用就是指真正的第 3 页。

• 长文档按确定性规则分块，带重叠和页码提示。

• 提取出的 JSON 会针对 JSON Schema（Draft 2020-12）校验，并且每个错误都会随代码返回——不只是第一个——这样模型可以一次性修复所有问题，并附带 JSON Pointer 路径。

• 输出由服务器写入（JSON 或 CSV），位置处于同一个根目录内，并有可验证的行数/字节数。

Related MCP server: BigContext MCP

工具

所有路径参数都会被解析；如果解析结果超出允许的 root，则被拒绝（路径遍历防护）。glob_pattern 参数同样受限：绝对路径模式和包含 .. 的模式都会被拒绝，任何解析到根目录之外（比如通过符号链接）的匹配都会被静默从结果中移除。防护被触发时会抛出 MCP 工具错误，所以调用模型看到的是真实原因，而不是一笔被掩盖的一般性错误。

快速开始

要求 Python 3.11+ 和 uv。

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

单机运行（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

将下面的内容添加到 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 如果未设置，默认使用服务器的工作目录。请把它设为你的文档所在文件夹；该目录之外的内容不会被读取或写入。

典型工作方式

1. list_documents(".", "*.pdf") —— 找到发票。

2. document_info("invoice.pdf") —— 确认页数。

3. read_document("invoice.pdf", "1-3") 或 chunk_document(...) —— 获取文本。

4. 让 LLM 把字段提取到 JSON。

5. validate_json(data, json_schema) —— 修复安全性，每项报告的错误再重新校验。

6. save_structured("out/invoice.json", data, "json") —— 写入结果。

一些字段限制（直说）

• 只支持基于文本的 PDF。 提取使用 pypdf；扫描件或纯图片 PDF 会得到空文本，并且没有 OCR。

• 提取效果取决于 PDF 的生成方式。 多栏、大表格等复杂布局可能得到顺序不佳的文本，这是当前服务器继承自 pypdf 的特性。

• 不支持 .docx / .xlsx。 反向支持 .pdf、.txt、.md、.csv、.json。

• 服务器本身不做提取推理。 它不会替你找出发票总额；它做的是保证真正去推理的那个模型，基于的是真实文本，且输出符合你的 schema。

• 这是一个可运行的工具，其构建是为了我目前正建设的 AI 自动化工作流，并收支作为我作品集的一部分公开——它很新，还没有生产环境里程。它有测试和路径限制防护，但还没有在此基础上做更多加固——在指向敏感目录之前，请先审查。

开发

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

测试套件在内存中构建了一个很小的两页 PDF 夹具（手工构造、无额外依赖），覆盖所有六种工具、路径遍历防护、glob 模式限制（包括符号链接逃逸）、页码范围错误、多错误 schema 校验、CSV 往返，以及通过 MCP 服务器对象进行的工具注册与错误传播。

许可证

MIT © 2026 Koray Nar