Document Understanding MCP Server

文档理解 MCP 服务

⚠️ WARNING：此服务目前处于 alpha 阶段，仅用于本地开发和测试。请勿将其部署在生产环境中，也不要暴露给不可信网络。运行此服务前，请阅读 SECURITY.md，了解重要的安全注意事项。

此 MCP 服务提供用于提取文档（主要是 PDF）的文本、元数据、布局信息和搜索文档的工具。此服务实现了 Model Context Protocol（MCP）规范，使 AI 模型能够通过标准化接口与 PDF 文档交互。

概览

文档理解 MCP 服务提供了一组用于从 PDF 文档中提取信息的工具，包括：

• 文本内容提取（扫描文档时回退到 OCR）
• 元数据提取（作者、标题、创建日期等）
• 布局信息提取（文本块、图像、图形）
• 表格提取
• 图像提取
• 文档大纲／书签提取
• 文本搜索功能
• 语言检测

AI 模型可以使用这些工具分析和理解 PDF 文档，从而实现更复杂的文档处理工作流。

未来计划：我们正在努力扩展支持范围，使其涵盖 PDF 以外的多种文档类型。有关即将进行的架构变更的详情，请参阅 docs/plans/README.md。

设置和安装

1. 克隆代码仓库：

   git clone <repo-url>
   cd document-understanding-mcp-server
   

2. **安装 Python：**确保已安装 Python 3.11+。
3. **安装 uv：**建议使用 uv 管理环境。

   pip install uv
   

4. 创建并同步虚拟环境：

   uv venv # Create .venv
   # Install core dependencies
   uv pip sync pyproject.toml
   # For development/testing, install optional extras:
   uv pip install -e '.[dev,test]'
   

5. （表格提取所必需）安装 Java：extract_tables 工具依赖 tabula-py，而它需要 Java 运行时环境（JRE）。请为你的系统安装合适的 JRE（例如 OpenJDK），并确保系统的 PATH 中可以访问 java。
6. （OCR 回退所必需）安装 Tesseract：extract_pdf_contents 中的 OCR 回退功能依赖 pytesseract，而它需要 Tesseract OCR 引擎本身。请为你的操作系统安装 Tesseract（参见 Tesseract 安装说明），并确保系统的 PATH 中包含 tesseract 命令。
7. 配置基础路径（除非覆盖，否则为必需）：定义 DOCUMENT_UNDERSTANDING_BASE_PATH 环境变量。默认情况下，这是服务读取 PDF 文件的唯一目录。例如：

   export DOCUMENT_UNDERSTANDING_BASE_PATH=/path/to/your/pdf_working_directory
   

配置

• DOCUMENT_UNDERSTANDING_BASE_PATH（环境变量，必填）：* 指定服务器有权读取 PDF 的目录绝对路径。若未设置，服务器将拒绝启动，除非使用 --allow-any-path。
• DOCUMENT_UNDERSTANDING_LOG_LEVEL（环境变量）： 设置控制台输出的最低日志级别（例如，DEBUG、INFO、WARNING）。默认值=INFO。
• DOCUMENT_UNDERSTANDING_LOG_FORMAT（环境变量）： 设置控制台日志格式（plain 或 json）。默认值=plain。
• DOCUMENT_UNDERSTANDING_LOG_FILE（环境变量）： 若已设置，则指定结构化 JSON 日志的写入路径（例如，.tmp/logs/server.log）。目录将自动创建。默认值=禁用。
• DOCUMENT_UNDERSTANDING_LOG_FILE_LEVEL（环境变量）： 文件日志的最低级别（例如，DEBUG、INFO）。默认值=INFO。
• DOCUMENT_UNDERSTANDING_DEFAULT_LANG（环境变量）： 设置默认 OCR 语言（例如，eng、fra）。若未设置，则默认为 eng。
• ENABLE_SAVE_IMAGES_TO_FILES（环境变量）： 设置为 true 时，使用带有 output_directory 参数的 extract_images 工具可将提取的图像保存到文件。默认值=false。
• SAFE_OUTPUT_DIRECTORIES（环境变量）： 以冒号分隔的目录列表。当 ENABLE_SAVE_IMAGES_TO_FILES=true 且 ALLOW_ANY_PATH=false 时，图像可以保存到这些目录。例如：/tmp:/var/output:/data/images。
• 能力覆盖 / 启用标志（命令行）：
  • --allow-no-java：若未找到 Java 运行时（extract_tables 所需），服务器通常会退出。使用此标志可允许服务器启动，但 extract_tables 工具将被禁用。
  • --allow-no-tesseract：若未找到 Tesseract 可执行文件（OCR 回退所需），服务器通常会退出。使用此标志可允许服务器启动，但 extract_pdf_contents 中的 OCR 回退将被禁用。
  • --enable-experimental：启用默认禁用的实验性工具（例如 find_nearby_content）。
  • --allow-any-path：（安全风险） 若设置，将禁用 PDF_SERVER_BASE_PATH 限制，并允许服务器尝试读取工具参数中提供的任意路径下的文件。请格外谨慎，仅在可信环境中使用。

能力 / 依赖项矩阵

某些工具是否可用或能否完整运行，取决于外部依赖项或标志。

工具名称	能力	依赖项 / 触发条件	执行检查的时机	控制标志
extract_tables	java_runtime	Java Runtime（JRE）	服务器启动时	--allow-no-java
extract_pdf_contents	tesseract_ocr（可选）	Tesseract OCR	服务器启动时	--allow-no-tesseract
(其他工具)	(无)	Python 包	安装时	(不适用)

*注意： 若 Tesseract OCR 不可用（且使用了 --allow-no-tesseract），则 OCR 回退将被禁用。

工具

服务器实现了以下工具。通过 list_tools 调用向大模型提供的列表是动态的，取决于检测到的能力（例如，Java 是否可用）和启动标志。 请参阅 src/document_understanding/models.py，了解响应架构（例如，TextContentResponse、MetadataResponse 等）。错误响应遵循 ErrorResponse 架构。

指南： 所有工具中的 pdf_path 参数都必须指向服务器环境中可访问的文件路径。

1. extract_pdf_contents

• 描述：从本地 PDF 文件的指定页面提取文本内容。直接提取文本，并在扫描页面或图片较多的页面中无法提取时使用 OCR。
• 参数：
  • pdf_path（string，必填）：本地 PDF 文件的路径。
  • pages（string，可选）：页面指定方式（从 1 开始计数，支持范围和负数索引）。例如，"1, 3-5, -1"。默认值=全部。
  • ocr_language（string，可选）：Tesseract 的 OCR 语言（例如，"eng"、"fra+eng"）。默认值='eng'。
  • password（string，可选）：加密 PDF 的密码。
• 返回：TextContentResponse JSON。
• 使用指南：最适合获取页面的原始文本。需要时会自动处理 OCR。使用 pages 指定特定章节。如果处理的是非英文扫描文本，请设置 ocr_language。

2. extract_pdf_metadata

• 描述：提取 PDF 的元数据（作者、标题、日期），并检查其中是否包含图片或绘图。
• 参数：
  • pdf_path（string，必填）：本地 PDF 文件的路径。
  • password（string，可选）：加密 PDF 的密码。
• 返回：MetadataResponse JSON。
• 使用指南：先使用此工具了解 PDF 的结构和属性（页数、标题、作者等），并查看其中是否包含图片或绘图。

3. search_pdf_text

• 描述：在指定页面中搜索完全匹配的文本，并返回边界框。
• 参数：
  • pdf_path（string，必填）：本地 PDF 文件的路径。
  • query（string，必填）：要搜索的文本（区分大小写）。
  • pages（string，可选）：页面指定方式。默认值=全部。
  • password（string，可选）：加密 PDF 的密码。
• 返回：SearchResponse JSON，包含匹配项列表，其中包括页码和矩形坐标。
• 使用指南：适用于查找特定词语或短语及其位置。

4. extract_pdf_layout

• 描述：提取详细的布局信息：文本块、绘图和图片位置（含坐标）。
• 参数：
  • pdf_path（string，必填）：本地 PDF 文件的路径。
  • pages（string，可选）：页面指定方式。默认值=全部。
  • include_images（boolean，可选）：包含图片信息（xref、bbox、大小）。默认值=False。
  • include_drawings（boolean，可选）：包含矢量绘图信息。默认值=False。
  • detail_level（string，可选）：文本详细程度（'blocks'、'lines'、'words'）。默认值='blocks'。
  • password（string，可选）：加密 PDF 的密码。
• 返回：LayoutResponse JSON，包含各页面的布局详情。
• 使用指南：当空间关系很重要或需要了解页面结构时使用。提供文本、图片和矢量绘图的坐标。对于复杂页面，可能会生成较大的响应。

5. extract-images

• 描述：提取图像信息（栅格图像以及 Form XObjects 等其他对象）。
• 参数：
  • pdf_path（string，必填）：本地 PDF 文件的路径。
  • pages（string，可选）：页面规格。默认值为 all。
  • include_data（boolean，可选）：若为 true，则包含 base64 图像数据。默认值为 false。
  • min_width（integer，可选）：结果中包含的图像最小宽度。
  • min_height（integer，可选）：结果中包含的图像最小高度。
  • filter_bbox（array，可选）：用于筛选图像的边界框 [x0, y0, x1, y1]。
  • password（string，可选）：加密 PDF 的密码。
  • output_directory（string，可选）：保存提取图像的目录。需要设置 ENABLE_SAVE_IMAGES_TO_FILES=true 环境变量。
  • save_without_returning_data（boolean，可选）：若为 true，则将图像保存为文件，但不在响应中返回 base64 数据。默认值为 false。
• 返回：ImageExtractionResponse JSON。
• 说明：返回图像尺寸、页码和内部引用（xref）。边界框（bbox）为可选项，检测失败时可能缺失（例如 Form XObjects）。谨慎使用 include_data=True，因为它可能导致响应非常大。指定 output_directory 且设置了 ENABLE_SAVE_IMAGES_TO_FILES=true 时，图像将保存到磁盘，响应中会包含文件路径。使用 save_without_returning_data=True 可将图像保存为文件，而不在响应中包含可能很大的 base64 数据。

6. extract_tables

• 描述：从指定的 PDF 页面中提取表格，并转换为嵌套列表。
• 参数：
  • pdf_path（string，必填）：本地 PDF 文件的路径。
  • pages（string，可选）：'all' 或以逗号分隔的页码（从 1 开始）。默认值为 all。
  • password（string，可选）：加密 PDF 的密码。
• 返回：TableExtractionResponse JSON。（注意：当前实现返回字典列表，详见 docs/KNOWN_ISSUES.md。）
• 说明：使用 tabula-py 尽力检测表格。结果很大程度上取决于表格格式（线条、间距）。处理速度可能较慢。**注意：**此工具需要 Java 运行时。如果服务器启动时未检测到 Java，且使用了 --allow-no-java 标志，则此工具将不可用。

7. detect-language

• 描述：检测从指定页面采样的文本内容所使用的语言（默认采样第 1 页）。
• 参数：
  • pdf_path（string，必填）：本地 PDF 文件的路径。
  • pages（string，可选）：采样用的页面规格。默认值为 '1'。
  • sample_size（integer，可选）：采样的最大字符数。默认值为 2000。
  • password（string，可选）：加密 PDF 的密码。
• 返回：LanguageDetectionResponse JSON。
• 说明：可用于在处理或翻译前确定主要语言。

8. extract_pdf_outline

• 描述：从 PDF 中提取文档大纲（书签/目录）。
• 参数：
  • pdf_path（string，必填）：本地 PDF 文件的路径。
  • password（string，可选）：加密 PDF 的密码。
• 返回：包含分层大纲结构的 OutlineExtractionResponse JSON。
• 说明：用于提取文档目录或书签结构。若文档没有大纲，则返回空列表。

9. get_pdf_working_directory

• 描述：返回用于放置待处理 PDF 文件的指定目录路径。
• 参数：无。
• 返回：包含 status、working_directory（字符串或 null）以及可选 message 的 JSON。
• 说明：调用此工具可查明在调用其他需要 pdf_path 的工具之前，应将 PDF 文件上传或放置到哪里。如果服务器以 --allow-any-path 启动，working_directory 将为 null。

测试

测试套件使用动态生成的 PDF 进行所有测试。仓库中不存储静态 PDF 文件。tests/conftest.py 中的测试夹具会在运行时生成所有必要的测试 PDF，包括：

• 简单文本文档
• 带图像的文档
• 带绘图的文档
• 带表格的文档
• 带大纲／书签的文档
• 空文档
• 加密文档

这种方式确保所有测试无需外部文件即可运行，并使测试套件更具可移植性且自包含。

运行测试

# Run all tests
python -m pytest

# Run specific test categories
python -m pytest tests/unit
python -m pytest tests/integration

# Run tests with coverage
python -m pytest --cov=src

测试架构

测试套件包含以下几类测试：

• 单元测试：单独测试各个组件
• 集成测试：测试组件之间的交互
• 端到端测试：从用户的角度测试整个系统

端到端测试使用 MCP 命令行界面与服务交互，模拟真实场景中的使用方式。这种方式确保服务在各种场景下以及处理不同类型的 PDF 时都能正常工作。

运行服务／调用

此服务使用标准的 MCP stdio 通信运行。可通过多种方式运行此服务：

方法 1：使用提供的可执行文件（推荐）

# Set required base path (if not using sandbox mode)
export DOCUMENT_UNDERSTANDING_BASE_PATH=/path/to/pdf/storage

# Run with default settings (sandbox mode)
bin/document-understanding-mcp-server

# Run with sandbox mode disabled (less restricted)
DOCUMENT_UNDERSTANDING_SANDBOX=false bin/document-understanding-mcp-server

# Run with additional arguments
bin/document-understanding-mcp-server --enable-experimental --port 8000

document-understanding-mcp-server 可执行文件会自动设置安全环境，其中包括：

• 沙盒模式下为每位用户创建隔离目录（默认）
• 根据安全上下文设置适当的权限
• 根据环境智能处理参数

方法 2：使用已安装软件包的入口点

通过 pip 安装软件包后，可以直接使用入口点：

# Run with default settings
document-understanding-mcp-server

# Run with custom arguments
document-understanding-mcp-server --allow-any-path --enable-experimental

方法 3：直接使用 standalone_server.py

# Activate environment
source .venv/bin/activate

# Set required base path
export DOCUMENT_UNDERSTANDING_BASE_PATH=/path/to/pdf/storage

# Run directly (will fail if Java/Tesseract missing and flags not used)
python standalone_server.py

# Run allowing missing Java/Tesseract but restricting path
python standalone_server.py --allow-no-java --allow-no-tesseract

# Run allowing ANY path access (UNSAFE)
# DOCUMENT_UNDERSTANDING_BASE_PATH is ignored here
python standalone_server.py --allow-any-path

# Enable experimental features
python standalone_server.py --enable-experimental

沙盒模式

服务支持安全沙盒模式（默认启用），该模式会：

1. 为文件输出创建隔离的用户专属目录
2. 设置更严格的文件权限（700，仅用户可访问）
3. 禁用 --allow-any-path 标志，以提高安全性

要禁用沙盒模式（不建议在生产环境中这样做）：

export DOCUMENT_UNDERSTANDING_SANDBOX=false

调用命令（mcp.json 示例）

示例 1：基本配置

{
  "mcpServers": {
    "document-understanding": {
      "command": "/path/to/document-understanding-mcp-server",
      "args": [
        "--enable-experimental"
      ]
    }
  }
}

示例 2：直接使用 Python 模块

{
  "mcpServers": {
    "document-understanding": {
      "command": "/path/to/your/.venv/bin/python",
      "args": [
        "-m", "document_understanding.cli"
      ],
      "env": {
        "DOCUMENT_UNDERSTANDING_BASE_PATH": "/path/to/pdf/storage"
      }
    }
  }
}

大模型使用建议

• 文件路径： 处理 PDF 之前，使用 get_pdf_working_directory 查找允许使用的目录。确保提供的任何 pdf_path 参数都指向该目录（或其子目录）中的文件。除非服务以不安全的方式通过 --allow-any-path 启动，否则路径遍历尝试（../）或指向工作目录之外的绝对路径都会被拒绝。
• 密码： 目前，除表格提取外，服务无法处理受密码保护的 PDF。处理加密文件很可能会失败。请参阅 docs/KNOWN_ISSUES.md。
• 工具可用性： 可用工具列表可能会根据服务环境发生变化（例如，如果缺少 Java 且使用了 --allow-no-java，则不会列出 extract_tables）。请根据 list_tools 的响应判断当前可用的工具。
• 使用专用工具： 如果只需要查找特定内容，请优先使用 search_pdf_text，而不是提取全部内容。如果只需要元数据，请使用 extract_pdf_metadata。
• 处理 JSON： 预期响应为 JSON。将 ToolResponseContent 的 text 字段解析为 JSON。
• 检查 status： 始终检查 JSON 响应中的 status 字段。如果其值为 "error"，请使用 message 和 error_code 字段进行诊断（注意：服务通常会引发异常，而 MCP 客户端会转换这些异常）。
• 版面信息： extract_pdf_layout 工具会提供丰富的结构信息（文本坐标、绘图、图像位置）。这些信息可用于复杂分析（例如，结合 find_nearby_content），但会生成较大的响应。
• 页面指定： 需要限制处理范围时，请有效使用 pages 参数（例如 "1-3, 5, -1"）。
• OCR 语言： 处理非英语文档时，请使用 ocr_language 指定语言（例如，法语和英语使用 "fra+eng"），以提高准确性。
• 错误处理： 如果 pdf_path 不正确，请准备好处理 FileNotFoundError；如果页面指定或处理过程有误，则可能出现 ValueError。加密文件可能会导致各种错误。服务会引发异常，MCP 客户端应将其呈现出来。

复杂用法示例

1. 从扫描件第 2 和第 3 页提取法语文本：

   • get_pdf_working_directory -> 检查响应中的 working_directory。
   • （LLM/用户确保 mydoc.pdf 位于工作目录中）
   • 使用 extract_pdf_contents，并设置 pdf_path="mydoc.pdf"、pages="2-3"、ocr_language="fra"。
   • 解析响应，并处理 pages 列表中的文本。

2. 查找图像附近的文本：

   • get_pdf_working_directory -> 获取 working_directory。
   • （LLM/用户放置 report.pdf）
   • 使用 extract_pdf_layout，并设置 pdf_path="report.pdf"、pages="5"（假设图像位于第 5 页）。
   • 解析版面响应。根据 xref、尺寸或大致的 bbox 确定目标图像。
   • 如果已启用，使用 find_nearby_content，并设置 pdf_path="report.pdf"、pages="5"、将 target_bbox 设为图像的 bbox、content_type="text_block"、direction="below"（例如，用于查找图注）。
   • 解析附近内容响应，获取图注文本。

3. 检查元数据后提取特定表格：

   • get_pdf_working_directory -> 获取 working_directory。
   • （LLM/用户放置 data.pdf）
   • 使用 extract_pdf_metadata，并设置 pdf_path="data.pdf"。
   • 检查响应：确认 page_count，查看元数据字段。
   • 使用 extract_tables，并设置 pdf_path="data.pdf"、pages="2, 4"（例如，仅提取第 2 和第 4 页）。
   • 解析响应。

关键使用流程

1. 提取指定页面：
   • 调用 extract_pdf_contents，并设置 pdf_path 和 pages="2-3"。
   • 解析 JSON 响应，检查 status，并处理提取的内容。

已知问题和限制

有关当前已知问题和限制的列表，请参阅 docs/KNOWN_ISSUES.md。

有关此前已解决问题的列表，请参阅 docs/SOLVED_ISSUES.md。

未来计划

有关计划中的改进和未来开发的信息，请参阅 plans 目录。

贡献

有关如何为此项目做出贡献的信息，请参阅 CONTRIBUTING.md 文件。

许可证

本项目采用 LICENSE 文件中规定的条款授权。