MCP tool ocr

MCP文档解析器 + OCR（光学字符识别）

这个项目展示了一个文档理解的工作流程，作为 模型上下文协议 (MCP)工具。\ 它可以下载远程文件，执行OCR/表格提取，可选地调用视觉-语言模型（VLM），并为PDF、图片、DOCX、XLSX和PPTX文件返回结构化的JSON数据。

关键特性

• 多格式解析 通过 PyMuPDF、pdfplumber、Camelot、python-docx、pandas/openpyxl 和 python-pptx。
• OCR备用方案 使用可配置语言的Tesseract。
• Qwen3-VL-Plus 集成 通过官方渠道 openai Python SDK（兼容OpenAI的端点）。
• 异步VLM调度 它配备了一个内部任务管理器，将并发的多模态调用限制在五个以内，以最大化吞吐量，同时避免对上游服务造成过载。
• 可配置的PDF解析模式 让您在以OCR为中心的提取功能与VLM驱动的Markdown转换功能之间进行选择。
• MCP工具 parse_document_url 接受单一（输入/参数/等，具体根据上下文确定） options 在保留原有灵活性的同时，使用字典。
• 健康终端点 当通过FastMCP托管时，用于简单的运行时检查。

通过OpenAI SDK配置Qwen3-VL-Plus

VLM客户端使用的是官方 openai 用于与阿里云的OpenAI兼容端点进行通信的包。

1. 导出所需的环境变量（默认值如下）。API密钥可以通过以下两种方式提供： OPENAI_API_KEY 或传统遗留问题 DASHSCOPE_API_KEY 变量。

   export OPENAI_API_KEY="sk-..."
   export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
   export QWEN_VLM_MODEL="qwen3-vl-plus"

异步VLM任务管理器会自动批处理请求，并且遵守最多五个并发调用的硬性限制，因此无需进行额外的调整。

1. 使用所需的解析模式调用MCP工具：

   {
     "tool": "parse_document_url",
     "arguments": {
       "file_url": "https://example.com/sample.pdf",
       "options": {
         "pdf_parse_mode": "vlm",   // or "ocr"
         "use_ocr": true,
         "ocr_lang": "eng+chi_sim"
       }
     }
   }

- pdf_parse_mode="vlm" 将每个PDF页面转换为图像，将这批图像与面向Markdown的提示发送给Qwen3-VL-Plus，并返回模型生成的Markdown响应以及渲染后的页面图像。 - pdf_parse_mode="ocr" 保持混合提取器的运行状态，可选择性地对空白页面执行OCR（光学字符识别），并在需要时使用VLM（视觉语言模型）来转录单个页面。 - 图像解析总是利用视觉语言模型（VLM），并通过调整后的提示来描述场景、表格和公式（以LaTeX渲染）。

注： 在评估环境中，出站网络访问仍然被禁用；自动化测试通过存根（stubs）来调用OpenAI的代码路径。

输出布局保真度

为了帮助下游消费者准确重构文档，每个解析器现在都公开了文本、表格和视觉内容的明确顺序：

• PDF 页面 包括一个 elements 按阅读顺序列出数组，包括识别出的文本、OCR结果、表格、嵌入的图像以及VLM Markdown。
• DOCX 文件 添加一个 content.flow 一个交错排列了段落、表格和提取的图像及其对应索引和有效载荷的数组。
• 图像 暴露（或揭露）a（注：这里的“a”可能代表某个具体的事物或概念，根据上下文具体翻译） content_flow 列表，用于追踪原始图像、可选的OCR输出以及VLM（视觉语言模型）转录内容。
• PPTX 幻灯片 返回一个 elements 每张幻灯片对应的数组，保持文本框、图片和演讲者备注的顺序。
• PDF VLM模式 表面 document_elements 将页面图像集与聚合的Markdown响应进行配对。

这些结构确保在解析输出时，每张图片、表格或文本片段都能重新插入到其原始位置。

开发环境设置

uv sync  # or pip install -r requirements if preferred

使用以下命令运行单元测试：

pytest -q

使用示例报告PDF进行手动测试

该存储库包含一个小型客户端脚本（test.py（用于锻炼的） parse_document_url MCP工具端到端。要使用托管的示例报告重现该流程：

1. 在一个终端中启动MCP服务器：

   uv run python main.py

1. 在第二个终端中，通过客户端调用该工具：

   uv run python test.py

客户端已预配置为获取 https://sample-files.com/downloads/documents/pdf/sample-report.pdf 并将打印工具返回的结构化响应有效载荷。

示例输出（为简洁起见已截断）：

Type: pdf
Keys: ['type', 'filename', 'elapsed_seconds', 'summary', 'markdown']
Elapsed seconds: 1.74
Summary snippet: # Parse Result for sample-report.pdf

- **Type:** PDF
- **Elapsed Seconds:** 1.75

### Warnings
- camelot failed: module 'camelot' has no attribute 'read_pdf'

服务器日志将发出类似这样的警告： Cannot set gray stroke color because /'P6' is an invalid float value这些警告信息来源于PyMuPDF在渲染嵌入图像时产生的，可以在本地测试时安全地忽略。

仓库结构

• main.py – 核心解析器、OCR辅助工具、VLM客户端以及MCP布线。
• tests/test_mcp.py – 依赖存根以及涵盖分发逻辑和解析器行为的单元测试。
• example_files/ – 用于手动实验的样本资产。

扩展/调试技巧

• 该 VLMClient 封装OpenAI Responses API，并返回Markdown文本和原始数据负载，以便进行审核或缓存。
• 要启用详细日志记录，请将MCP服务器（FastMCP在部署之前，请使用您首选的日志记录器进行调用。
• 在运行OCR密集型工作负载时，调整 options["timeout"] 值用于适应缓慢的下载速度。