doc-extract-mcp

doc-extract-mcp

一个 MCP（Model Context Protocol）服务，为大模型提供确定性的文档工具，支持结构化数据提取工作流。大模型负责阅读和推理提取内容；本服务则提供不应交由语言模型处理的部分：可靠的文件访问、解析、分块、JSON Schema 验证，以及受限的文件输出。

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

原因

提取 Agent 容易在一些可预见的环节出错：幻觉出文件内容、无法跟踪长文档、悄无声息地生成与目标 Schema 几乎匹配的 JSON，以及随意写入输出。本服务可消除这些故障模式：

• 文件访问被限制在一个允许的根目录（DOC_EXTRACT_ROOT）内。
• PDF 文本包含明确的 --- page N --- 标记，因此引用“第 3 页”时指的就是第 3 页。
• 长文档采用确定性分块，并包含重叠内容和页码提示。
• 提取出的 JSON 会根据 JSON Schema（Draft 2020-12）进行检查，并且每个错误都会附带 JSON Pointer 路径报告，而不只是第一个错误，因此模型可以一次性修正所有问题。
• 输出由服务写入（JSON 或 CSV），且位于同一个根目录内，并提供可验证的行数和字节数。

工具

工具	参数	功能
list_documents	directory、glob_pattern='*'	列出允许的根目录中某个目录下的文件，并提供大小和修改时间。支持 **/*.pdf 等递归 glob。模式必须为相对路径且不能包含 ..；解析到根目录之外的匹配项会被过滤掉。
read_document	path、pages=''	返回文档文本。.pdf 通过 pypdf 读取，并带有 --- page N --- 标记，还可选择按从 1 开始的页码读取（'3'、'1-5'、'1-3,7'）；.txt/.md/.json 直接读取；.csv 则渲染为对齐的文本表格。不支持的类型会显示明确错误。
document_info	path	返回不含完整内容的元数据：类型、大小、修改时间；PDF 的页数和 PDF 元数据；文本文件的行数。
chunk_document	path、max_chars=4000、overlap=200	将文档拆分为有序且互相重叠的文本块；每块包含索引、起始偏移量，以及（对于 PDF）页码提示。
validate_json	data、json_schema	根据 JSON Schema（Draft 2020-12）验证 JSON 字符串。通过 Draft202012Validator.iter_errors 返回所有验证错误及其 JSON Pointer 路径。
save_structured	path、data、format='json'|'csv'	在允许的根目录内写入提取的数据。CSV 要求数据为由扁平对象组成的 JSON 数组。返回写入路径、行数和字节数。

所有路径参数都会先解析；如果路径逃出允许的根目录，则会被拒绝（路径遍历防护）。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. 大模型将字段提取为 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。
• 服务不会进行提取推理。 它不会找出发票总额；它会确保负责提取的大模型依据真实文本工作，并确保结果符合你的架构。
• 这是一个正在使用的工具，旨在服务于我正在开展的 AI 自动化工作，并作为我作品集的一部分发布 — 它是新的，尚未经过生产环境的考验。它有测试和路径限制保护，但除此之外尚未经过强化 — 在将其用于敏感目录之前请先进行审查。

开发

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

测试套件会在内存中构建一个小型的两页 PDF 测试样例（手工构造的最简 PDF，无额外依赖），并覆盖全部六个工具、路径遍历保护、glob 模式限制（包括符号链接逃逸）、页面范围错误、多错误架构验证、CSV 往返，以及通过 MCP 服务对象进行的工具注册和错误传播。

许可证

MIT © 2026 Koray Nar