用途
doc-extract-mcp 是一个 MCP（模型上下文协议）服务器，为 LLM 提供确定性的文档处理工具，专用于结构化数据提取工作流。其设计理念是：LLM 负责阅读和提取推理，而该服务器提供那些绝不应交给语言模型的部分——可靠的文件访问、解析、分块、JSON Schema 校验以及受保护的文件输出。
该项目由 Koray Nar 作为其正在构建的 AI 文档自动化工作流的作品集项目开发，目标用例是将杂乱的 PDF（采购订单、发票、报告）转换为符合 Schema 的 JSON。它可与 Claude Code、Claude Desktop 以及任何其他 MCP 客户端配合使用。
主要能力
该服务器旨在消除提取代理常见的失败模式：
- 文件访问被限制在一个允许的根目录（
DOC_EXTRACT_ROOT）内。 - PDF 文本到达时带有明确的
--- page N ---标记，因此“第 3 页”的引用就对应第 3 页。 - 长文档通过确定性的方式分块，并带有重叠和页面提示。
- 提取的 JSON 会根据 JSON Schema（Draft 2020-12）进行校验，每个错误都会以 JSON Pointer 路径报告——而不仅仅是第一个错误——以便模型可以一次性修正所有错误。
- 输出由服务器写入（JSON 或 CSV），位于同一个根目录内，并带有可验证的行数/字节数计数。
- 所有路径参数都会被解析，如果超出允许的根目录则被拒绝（路径遍历防护）。
glob_pattern参数以相同方式受到限制：绝对模式和包含..的模式会被拒绝，任何解析到根目录之外的匹配项（例如通过符号链接）都会从列表中静默丢弃。防护失败会作为 MCP 工具错误抛出，因此调用模型能看到实际原因，而不是被掩盖的通用错误。
使用方式
需要 Python 3.11+ 和 uv。
独立运行（stdio 传输）：
uvx doc-extract-mcp
添加到 claude_desktop_config.json：
{
"mcpServers": {
"doc-extract-mcp": {
"command": "uvx",
"args": ["doc-extract-mcp"],
"env": {
"DOC_EXTRACT_ROOT": "/path/to/documents"
}
}
}
}
DOC_EXTRACT_ROOT 如果未设置，默认为服务器的工作目录。将其设置为你文档所在的文件夹；该文件夹之外的任何内容都无法被读取或写入。
典型工作流：
list_documents(".", "*.pdf")— 找到发票。document_info("invoice.pdf")— 检查页数。read_document("invoice.pdf", "1-3")或chunk_document(...)— 获取文本。- LLM 将字段提取为 JSON。
validate_json(data, json_schema)— 修正每个报告的错误，重新校验。save_structured("out/invoice.json", data, "json")— 写入结果。
适用场景
- 将 PDF 发票、采购订单、报告转换为结构化 JSON。
- 需要确定性文档处理（分块、校验、输出）的 AI 提取工作流。
- 与 Claude Code、Claude Desktop 或其他 MCP 客户端配合使用。
限制
- 仅支持基于文本的 PDF。提取使用 pypdf；扫描件/纯图片 PDF 将产生空文本。没有 OCR。
- 提取质量因 PDF 生成方式而异。复杂布局（多列、大量表格）可能产生不完美的阅读顺序——这是该服务器继承的 pypdf 特性。
- 不支持 .docx / .xlsx。支持的类型为
.pdf、.txt、.md、.csv、.json。 - 服务器不进行任何提取推理。它不会找到你的发票总额；它确保进行提取的模型基于真实文本工作，并且结果符合你的 Schema。
- 这是一个工作工具，为作者正在构建的 AI 自动化工作而构建，作为作品集的一部分发布——它很新，尚无生产使用记录。它有测试和路径限制防护，但除此之外未经加固——在指向敏感目录之前请先审查。
- 测试套件在内存中构建一个小型两页 PDF 测试夹具（手工构建的最小 PDF，无额外依赖），覆盖全部六个工具、路径遍历防护、glob 模式限制（包括符号链接逃逸）、页面范围错误、多错误 Schema 校验、CSV 往返，以及通过 MCP 服务器对象的工具注册和错误传播。
MIT © 2026 Koray Nar
