双路抽取 MCP Server（dual-extract-mcp）

把「MinerU 文本/版面路 + Qwen3-VL 视觉路 + 双路融合裁决」封装成 MCP 工具集（8 个 Tool）， 让 Claude Desktop / Cursor 等 MCP 客户端通过 stdio 调用，对本地 PDF 做结构化文档理解 （字段抽取 / 表格 / 公式 / 探查 / 校验）。完全本地、离线、零外部 API。

• 状态：v0.2.1（v0.2.0 GA 之后修复 BUG-4 子区间页号偏移，353 回归全绿；M1-M7 全量完成：8 个 Tool 全注册 + 安全加固 + 降级完善 + 文档，G4 gate 真连验收 PASS；V1.0 增量落地：generation / artifact_id / field_id / quality_report.json / cell_provenance，406 回归全绿）

• 传输：stdio（本期不监听端口）

• 语言：Python 3.11+（受管 3.13.14 实测可用）

1. 功能一览（8 个 Tool）

完整输入/输出契约见 docs/api.md。

Related MCP server: mdify-mcp

2. 环境要求

• Python 3.11+（Windows 优先，Linux 兼容）

• 本地已部署：

  • MinerU 服务 http://127.0.0.1:8000（/health 返回 {"status":"ok"}）

  • Ollama http://127.0.0.1:11434（含 qwen3-vl:30b 视觉模型）

⚠️ 沙箱提示：本沙箱内 python -m venv 会静默失败，须用受管 Python 建 venv （C:\Users\Administrator\.workbuddy\binaries\python\versions\3.13.12\python.exe -m venv .venv）。 用户本机无此坑，按下方标准命令即可。

3. 安装

# 1. 建 venv（受管 Python 3.13.14；用户本机可直接 python -m venv .venv）
C:\Users\Administrator\.workbuddy\binaries\python\versions\3.13.12\python.exe -m venv .venv

# 2. 激活 + 安装（含测试依赖）
.\.venv\Scripts\Activate.ps1
pip install -e ".[test]"

# 3. 复制配置模板并按需修改（可选；不配则用默认值）
Copy-Item .env.example .env

4. 运行

# 开发期直跑（stdio 交互；起几秒确认无报错即可 Ctrl+C）
python -m dual_extract.server
# 或等价的 console script
mcp-server

接入 Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "dual-extract": {
      "command": "D:/Dual-Extract-MCP/.venv/Scripts/python.exe",
      "args": ["D:/Dual-Extract-MCP/src/dual_extract/server.py"]
    }
  }
}

接入 Cursor

~/.cursor/mcp.json：

{
  "mcpServers": {
    "dual-extract": {
      "command": "D:/Dual-Extract-MCP/.venv/Scripts/python.exe",
      "args": ["D:/Dual-Extract-MCP/src/dual_extract/server.py"]
    }
  }
}

B1：MCP 客户端 CWD 不可控，建议在 .env 中把 DUAL_EXTRACT_OUTPUT_DIR 配成绝对路径。

5. 测试

# 单元测试（默认跳过 smoke）
pytest -q

# 冒烟：真连本机 MinerU/Ollama（需服务在线）
pytest -m smoke -q

当前回归：353 passed，9 smoke deselected（2026-08-03 v0.2.1 全量回归核实）； V1.0 增量后：406 passed，9 smoke deselected（2026-08-03 V1.0 全量回归核实）。

5.1 V1.0 增量说明（2026-08-03）

V1.0 在 v0.2.1 基础上新增 5 项可选/默认关能力（全部 additive，schema_version 保持 "1.0"，旧客户端零改动）：

挂接约定（artifact_manifest，V1.0 P2）：产物唯一身份由 artifact_id + manifest.json 的 SHA256 + 相对路径 三元组确定——artifact_id 标识「哪次抽取」，SHA256 保证「内容未被篡改」，相对路径定位「文件在哪」。详见 docs/最终输出说明.md §4 / docs/api.md §2.4。

6. 配置项（全部前缀 DUAL_EXTRACT_，仅 config.py 读取）

7. 真实样例用法

# 1. 探查：先「ls」一份 PDF 再决定抽取策略
#    inspect_document 返回 {pages, tables, images, formulas, text_chars}
#    样例：232 页财报 → 421 图 / 213,232 字符（MinerU 不可达时自动降级 PyMuPDF）

# 2. 双路字段抽取
#    dual_extract(pdf_path="D:/samples/中芯国际_年报.pdf",
#                 fields=["公司代码","公司简称","法定代表人","报告期","资产总计"],
#                 field_types={"资产总计":"money","报告期":"date"})

# 3. 表格（跨页 + 大表分层 + CSV/XLSX）
#    extract_table(pdf_path="D:/samples/中芯国际_年报.pdf", pages=[10,11],
#                  format=["json","csv"], cross_page=true)

# 4. 公式
#    extract_formulas(pdf_path="D:/samples/中芯国际_年报.pdf", pages=[20],
#                     render=true, tex=false)

# 5. 校验结果
#    validate_output(output_dir="D:/Dual-Extract-MCP/outputs/中芯_年报")
#    → {"schema_version": "1.0", "ok": true, "errors": [], "manifest_ok": true}
#    （产物目录含 extraction.json + manifest.json；manifest 记录各产物 SHA256，
#      validate_output 会与磁盘实文件比对，防产物漂移/被篡改）

8. 项目结构（四层架构，依赖单向向下）

MCP Layer       server.py → mcp/{tools,handlers,converters}.py
    ↓
Service Layer   services/*.py（extract/parse/vision/table/formula/inspect/validate/health）
    ↓
Pipeline Layer  pipelines/*.py ＋ fusion/*.py
    ↓
Adapter Layer   adapters/base.py（接口缝）＋ mineru/ollama/storage 实现

• 与外部服务唯一耦合点 = 三个 Adapter 的 Protocol 接口（MinerUAdapter / OllamaAdapter / StorageAdapter）。

• 铁律：不建注册表、不预写第二后端（Docling/云模型/对象存储 v0.4+ 再说）。

• 详见 docs/architecture.md。

9. 常见问题（FAQ）

9.1 VPN 代理导致 localhost 请求 502 / 超时（trust_env 陷阱）

Windows 上挂极光 VPN（端口 29290）时，Python httpx 默认 trust_env=True 会读取系统 注册表代理，把 http://127.0.0.1:8000 的 localhost 请求也走代理 → 502。 本项目所有 Adapter 的 httpx.AsyncClient 一律 trust_env=False，无需手动处理。 若在自定义脚本里直接调 httpx，请同样加 trust_env=False。

9.2 Ollama 冷启动 600s 超时

qwen3-vl:30b（30B 模型）首次加载进显存可能耗时 1-5 分钟，第一请求容易超时。 本项目 DUAL_EXTRACT_OLLAMA_TIMEOUT 默认 600 秒，足够冷启动； 若你的显存/磁盘更慢，可调大该值。探活（health）用固定 8s 短超时，不受此影响。

9.3 3090 24G 显存：默认串行防 OOM

qwen3-vl:30b 在 3090 24G 下并行多页易 OOM。默认 DUAL_EXTRACT_PARALLEL=false（串行）， 页图渲染也是串行（F1）。若显存充裕可开并行，但建议先压测单页显存占用。

9.4 MinerU 不可达时怎么办

• dual_extract / vision_extract / parse_text：自动降级（视觉路单跑或纯文本）， 输出 warnings 标 degraded，不整体失败；

• inspect_document：自动降级为纯 PyMuPDF 本地统计（页数/图片/文本字符）， degraded=true + warnings 标注。

9.5 输出目录找不到产物

MCP 客户端 CWD 不可控，务必在 .env 把 DUAL_EXTRACT_OUTPUT_DIR 配成绝对路径 （如 D:/Dual-Extract-MCP/outputs）。产物按 pdf_stem 分目录： {输出根}/{pdf文件名}/extraction.json + manifest.json。

10. Roadmap

• v0.2-alpha gate（T01-T03 = M1-M3）：骨架 + 单路 + 双路融合闭环 ✅

• T04（M4-M5）：表格 + 公式 ✅

• T05（M6-M7）：inspect/validate + 安全加固 + 降级完善 + 文档 ✅

• v0.2.0（2026-08-03 转正）：G4 gate 真连验收 PASS（8 Tool 真连全通 + 3 P1 修复闭环 + 349 回归全绿）✅

• v0.2.1（2026-08-03 发版）：BUG-4 MinerUAdapter 子区间页号偏移修复（parse(pages=[7]) 时产物 page_idx 从 0 重编号，blocks 全标 page=1；应按 pages[0] 偏移）——commit bec69aa，353 回归全绿（4 个 BUG-4 专项回归）✅

• V1.0（2026-08-03 增量）：meta.generation / artifact_id / fields[].field_id / quality_report.json 自动产出 / tables[].cell_provenance（默认关）——5 项 additive 增量，406 回归全绿，QA 独立验证 PASS ✅

• 模型裁判（C3 默认关）→ v0.4 前不实现

• 多后端注册表（Docling/云模型/对象存储）→ 保持 roadmap

详细设计见 docs/技术方案设计_双路抽取MCP.md / docs/双路抽取MCP_架构设计.md / docs/双路抽取MCP_PRD.md / docs/architecture.md / docs/api.md。 输出质量评估（三层框架 + 可执行脚本）见 docs/输出质量评估指南.md / tools/assess_output_quality.py。