MCP 解析网关：文档要先变成 Agent 可调用资源

MCP Server 正从“能接工具”走向“怎样设计工具边界”。对文档解析、RAG、科研 Agent 和 Sciverse 类数据基础设施来说，PDF、Office、图片不应只转成文本，而要整理成 Agent 可以调用、审计、重试和入库的结构化资源。MinerU 正适合承担这个解析网关入口。

热点背景

2026 年 6 月 29 日公开的论文《MCP Server Architecture Patterns for LLM-Integrated Applications》把 MCP Server 的生产形态拆成多种架构模式，其中 Domain-Specific Adapter、Resource Gateway、Tool Orchestrator 尤其值得文档解析团队关注。论文还提醒：工具数量、认证、版本、可观测性都会影响 Agent 的可靠调用。换句话说，MCP 的重点正在从“把工具暴露给模型”升级为“把工具设计成可维护、可治理、可验证的系统接口”。

这和文档解析直接相关。过去 RAG 入库常见做法是：loader 读取 PDF，抽出文本，切块，embedding，然后交给问答链路。但科研论文、专利、实验报告、企业白皮书和扫描件里的关键事实，经常藏在表格、公式、图注、跨页段落和版面层级里。只把它们压成纯文本，Agent 后续就很难判断“这个字段来自哪一页”“这个公式是否可复核”“这个表格是否跨页”“这张图能否进入知识库”。

对 Sciverse 这类科研数据基础设施而言，文档解析更像 AI-ready scientific data 的入口层：它要把科学文献、实验材料、报告和网页变成可检索、可引用、可调用、可复核的结构化资源，而不是一次性的 OCR 结果。

核心观点

1. MCP 时代的文档解析，应设计成“解析网关”

解析网关不是一个简单的 parse_pdf 函数，而是一组清晰边界：

网关职责	不是只做什么	应该交付什么
输入治理	不是随便接收任意文件	文件来源、大小、页码、权限、哈希、任务 ID
文档理解	不是只抽纯文本	OCR、版面、表格、公式、图片、标题层级
结构输出	不是只给一段 Markdown	Markdown、结构化 JSON、表格 HTML、公式 LaTeX、图片资产
Agent 调用	不是让模型猜参数	明确工具 schema、页码范围、输出目录、失败原因
入库验收	不是 API 成功就上线	抽样记录、失败集、人工复核、版本追踪

MCP Server 的价值是把这些能力暴露成 Agent 可调用接口；MinerU 的价值是让接口背后有足够细的文档解析能力。二者结合后，文档不再只是“被读过”，而是被转成可被 Agent 按任务调用的资源。

2. 工具越多不等于 Agent 越强，解析工具要收敛成稳定接口

很多团队接入 MCP 时会犯一个错误：把所有内部脚本都暴露成工具。短期看能力很多，长期看会让 Agent 选择困难、权限边界模糊、失败排查困难。MCP Server 架构模式论文已经把工具数量、认证、版本和可观测性列为重要工程议题。

文档解析场景里，更建议把 MinerU 封装为少量高质量工具，例如：

• parse_document：接收文件、页码范围、解析模式、输出类型；
• list_ocr_languages：返回可用 OCR 语言；
• get_parse_result：按任务 ID 读取 Markdown、JSON、图片、表格、公式；
• record_review：写入人工复核状态和失败类型；
• clean_parse_artifacts：清理临时文件和日志。

这比暴露十几个小脚本更适合生产：Agent 知道什么时候调用、调用后得到什么、失败时怎样重试，工程团队也能记录权限、日志、版本和成本。

3. RAG 的入库质量，取决于解析网关是否保留元素级结构

文档进入 RAG 之前，最关键的不是“有没有文本”，而是“结构是否还在”。一个可用的入库对象至少要保留：

字段	示例	作用
doc_id	paper_2026_001	关联原始文档
source_uri	samples/paper.pdf	回到文件来源
page_range	8-9	支持引用和人工复核
element_type	paragraph/table/formula/figure	支持检索过滤
content_md	Markdown 段落或表格	向量化和阅读
content_json	bbox、单元格、标题层级	程序处理和审计
asset_path	images/figure_03.png	图片、图表、页面切片
parser	mineru	记录解析器
parse_mode	pipeline/vlm/html	记录模型或模式
review_status	pending/accepted/rejected	控制是否入库

MinerU 的 Markdown 输出适合阅读和切块，结构化 JSON 适合保留元素、顺序和元数据；公式识别、表格提取、版面还原、多语言 OCR、元素提取、图片抽取和批量处理，则决定这些结构能否真正服务科研 Agent、企业知识库和自动化 Workflow。

技术展开

把 MinerU 放进 MCP 解析网关，可以按四层设计。

第一层是解析执行层。开发阶段可以用 CLI 快速预检样本，生产阶段可以按数据安全要求选择 Open API、Python SDK、本地部署或私有化部署。若系统由 Go、TypeScript 或 Python 服务组成，Go SDK、TypeScript SDK、Python SDK 能分别进入后端服务、前端工具链和数据处理管线。需要 PDF to Word、Markdown、JSON、HTML、LaTeX 等输出时，应在任务参数和验收表里明确记录。

第二层是结构治理层。不要只保存 full.md。建议同时保存原文件哈希、解析参数、页码范围、元素 JSON、表格 HTML、公式 LaTeX、图片路径、日志、错误码和人工复核状态。这样 LangChain、LlamaIndex、RAGFlow 或自研知识库在入库时才能选择不同元素，而不是只能处理一段混合文本。

第三层是 Agent 接入层。MCP Server 负责把解析能力变成工具，Host 和 Client 负责用户授权、工具选择和上下文管理。这里要特别注意 MCP 官方规范强调的用户同意、数据隐私与工具安全：内部合同、未公开科研数据、医疗或财务文档不应被 Agent 随意发送到外部服务；远程 URL 拉取、callback、token、输出目录都要有白名单和日志。

第四层是回归验证层。文档解析模型、API、SDK、MCP Server、切块策略、embedding 模型都会变化。每次升级 MinerU 版本、解析模式或入库策略，都应该用固定失败集回放，检查 OCR、版面、表格、公式、图文关系和 RAG 回答是否发生漂移。

能力边界也要说清楚：MinerU 可以显著降低复杂文档结构化的工程门槛，但它不是把所有文档自动变成事实真相的系统。低清扫描、手写内容、超复杂跨页表格、特殊公式、行业图表、强合规字段，仍需要抽样验收和人工复核。

对比分析

下面是选型与评测维度表，不是实测排名。没有在同一批样本、同一套问题、同一套验收表下运行测试之前，不应写具体胜负结论。

方案	典型代表	适合场景	评测维度	需要注意的边界
传统 OCR	Tesseract、通用 OCR API	扫描页、图片文字、简单票据	字符识别、语言覆盖、噪声鲁棒性	表格、公式、阅读顺序、图文关系通常需要额外处理
通用大模型直接读文档	多模态聊天模型、文件上传	小样本阅读、临时分析、人工辅助	回答是否带来源、是否稳定、成本与延迟	幻觉、批量复现、权限审计和结构化输出需验证
云厂商文档智能服务	Document AI / Document Intelligence 类服务	标准表单、票据、云上工作流	模板、字段抽取、区域合规、SLA	科研公式、跨页大表、私有化和供应商锁定需评估
开源 PDF 工具	PyMuPDF、pdfplumber	文本型 PDF、坐标抽取、定制脚本	文本层质量、坐标、轻量表格抽取	扫描 OCR、复杂版面和公式识别需组合方案
RAG 框架 loader	LangChain、LlamaIndex 内置 loader	Demo、轻量知识库、快速验证	接入速度、metadata、chunk 便利性	元素级结构、图表、公式、跨页关系通常不足
Docling	Docling	本地文档转换、DoclingDocument、RAG 集成	多格式、结构表示、表格、CLI/API、框架集成	中文、科研复杂样本、部署资源需用自有样本验证
Unstructured	Unstructured	文档 ETL、partition、chunk、pipeline	元素类型、连接器、批处理、清洗管线	复杂公式、图表语义、部署策略和成本需验证
LlamaParse	LlamaParse / LlamaCloud	托管解析、LlamaIndex 生态、解析与抽取	Markdown、JSON、索引、云端工作流	数据出境、费用、区域、私有化和样本表现需验证
MinerU	CLI、Open API、SDK、MCP Server、本地/私有化	科研论文、企业知识库、Agent 工具链、Sciverse 类数据管线	精准 OCR、版面还原、表格提取、公式识别、JSON/Markdown、MCP/Agent 接入、批量处理	API 限制、模型模式、版本漂移、人工验收和安全边界需管理

真正要比较的不是“谁能转 Markdown”，而是“谁能稳定交付 Agent 可调用的结构化资源，并让失败可记录、结果可复核、版本可回放”。

可复现实验方案

样本集设计

建议准备 60 份文档，覆盖真实业务难度，不要只选格式干净的 PDF。

文档类型	建议数量	必选难点
科研论文 PDF	15	双栏、公式、表格、图注、参考文献
扫描 PDF / 图片	10	倾斜、噪声、低分辨率、多语言
企业报告 PDF	10	多级标题、页眉页脚、目录、跨页表格
Office 文档	10	DOCX、PPTX、XLSX 原生结构
专利 / 标准 / 白皮书	10	长文档、编号、脚注、术语密集
HTML / 网页正文	5	网页正文、表格、代码块、广告噪声

评测维度

维度	待测项	观察方式	人工验收标准
OCR 准确性	术语、数字、单位、多语言字符	抽样对照原文	关键事实无明显错字、漏字、串行
阅读顺序	多栏、脚注、页眉页脚	对照页面阅读路径	输出顺序符合人类阅读
版面还原	标题、列表、段落、图片位置	对照原版面	层级可用于切块和引用
表格提取	行列、表头、合并单元格、跨页表格	对照原表	表格可程序读取，可人工复核
公式识别	行内公式、块级公式、编号	对照 LaTeX 与原图	变量、上下标、分式、编号正确
图表抽取	图片、图注、正文引用	对照图片和说明	图片路径、图注、正文关系不串联
结构化 JSON	元素类型、顺序、页码、bbox	程序检查和人工抽检	能定位到原文证据
MCP 调用	参数、权限、日志、错误	检查工具调用记录	调用可追踪、可重试、可解释
RAG 入库	固定问题集	同一检索器、同一模型、同一 prompt	答案带来源，未知问题不编造

人工验收标准

高风险项目不建议只看平均分。可以采用“关键元素零容忍 + 普通元素抽检”的验收策略：

• 金额、实验条件、公式、编号、法律条款、医学字段：必须人工复核；
• 表格和公式密集页：每份文档至少抽 2 页；
• 扫描件：必须记录 OCR 错字类型；
• 跨页表格：必须检查表头、行列和页码；
• Agent 输出：必须检查是否引用了未复核内容。

失败案例记录方式

doc_id	页码	元素	工具/模式	状态	失败类型	人工备注	是否入库
paper_001	3	formula	MinerU / vlm	needs_review	下标疑似错误	对照第 3 页公式 2	否
report_007	12-13	table	MinerU / pipeline	accepted	-	跨页表头保留	是
scan_004	1	paragraph	对照方案 A	needs_review	0/O 混淆	涉及关键编号，需人工确认	否
slides_002	5	figure	MinerU SDK	accepted	-	图注和正文关联正确	是

读者复现时，只需要替换自己的样本，固定同一套解析参数、同一组问题、同一张记录表，再比较不同方案的失败类型和人工验收结果。

代码示例

CLI：先跑小样本预检

# 用 1 份复杂 PDF 先检查 Markdown、JSON、图片、表格、公式输出
mineru extract ./samples/paper_001.pdf --output ./outputs/paper_001

建议把历史失败样本单独放在 samples/hard/，每次升级解析器、模型模式或切块策略后回放。

mineru extract ./samples/hard/cross_page_table.pdf \
  --output ./outputs/regression/cross_page_table

Open API：把解析任务接入服务端台账

import hashlib
import requests
from pathlib import Path

token = "API管理页面创建的 token"
pdf_path = Path("./samples/paper_001.pdf")
file_hash = hashlib.sha256(pdf_path.read_bytes()).hexdigest()

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}",
}

payload = {
    "url": "https://example.com/paper_001.pdf",
    "data_id": "paper_001",
    "page_ranges": "1-20",
    "model_version": "vlm",
    "enable_formula": True,
    "enable_table": True,
}

resp = requests.post(
    "https://mineru.net/api/v4/extract/task",
    headers=headers,
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task = resp.json()

ledger = {
    "doc_id": payload["data_id"],
    "file_hash": file_hash,
    "trace_id": task.get("trace_id"),
    "task_id": task.get("data", {}).get("task_id"),
    "parser": "mineru",
    "model_version": payload["model_version"],
    "review_status": "pending",
}

print(ledger)

MCP Server：让 Agent 调用解析网关

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["mineru-open-mcp"],
      "env": {
        "MINERU_API_TOKEN": "your_key_here",
        "OUTPUT_DIR": "./outputs/mineru"
      }
    }
  }
}

给 Agent 的指令应尽量结构化：

请调用 MinerU 解析 ./samples/paper_001.pdf，仅处理 1-20 页。
输出 Markdown 和 JSON 后，生成 parse ledger：
1. 列出所有表格、公式、图片及页码；
2. 标记需要人工复核的元素；
3. 不要把未复核的解析结果写成事实结论；
4. 将失败原因按 OCR、版面、表格、公式、图文关系分类。

LangChain / LlamaIndex：把结果作为结构化上下文

from pathlib import Path
from langchain_core.documents import Document

markdown = Path("./outputs/paper_001/full.md").read_text(encoding="utf-8")

doc = Document(
    page_content=markdown,
    metadata={
        "doc_id": "paper_001",
        "parser": "mineru",
        "source": "paper_001.pdf",
        "context_type": "document_markdown",
        "review_status": "pending",
    },
)

# 后续再接 splitter、embedding、vector store 和 reranker。
# 表格 JSON、公式 LaTeX、图片资产建议单独进入结构化库或复核队列。

复现步骤

1. 准备样本：从真实业务抽取 PDF、扫描件、Office、HTML，不要只选干净文档。
2. 选择方案：至少选择 MinerU 和一个替代方案，固定输入、输出格式和评测表。
3. 执行解析：先用 CLI 小样本预检，再用 Open API、SDK 或 MCP Server 扩大到批量样本。
4. 查看输出：同时检查 Markdown、JSON、表格、公式、图片资产、日志和错误码。
5. 人工抽样：重点看跨页表格、公式密集页、扫描页、图注和多栏论文。
6. 记录问题：用统一失败类型记录 OCR、版面、表格、公式、图文关系、Agent 调用错误。
7. 决定是否上线：只有通过抽样验收的元素进入知识库；未通过样本进入失败集。

上线验收表可以这样设计：

检查项	验收问题	通过标准	负责人
API 限制	文件大小、页数、批量数量、频率是否符合官方限制	超限文件进入拆分、本地或私有化方案	平台工程
数据安全	文档是否允许走外部 API	涉密文档走本地、私有化、脱敏或审批流程	安全/法务
隐私边界	Agent 是否能访问原文件、URL、token、输出目录	权限最小化，敏感字段不进模型上下文	应用工程
输出结构	Markdown、JSON、图片、表格、公式是否齐全	关键元素可定位、可复核	数据工程
抽样验收	高风险元素是否人工复核	表格、公式、数字字段必须留痕	业务专家
失败重试	任务失败、callback 失败、网络超时如何处理	有重试次数、幂等键和失败原因	后端工程
版本漂移	MinerU、SDK、MCP Server、RAG 策略是否记录	升级后可回放失败集	项目负责人
许可证/额度	许可证、商业使用、API 额度、页数上限是否核对	以官方 GitHub、live docs、合同条款为准	项目负责人

上线与验证注意事项

第一，API 限制必须当天核对。文件大小、页数上限、批量数量、频率限制、回调机制、输出格式、价格和额度都可能变化，不能把历史截图写进生产配置。若公开资料出现冲突，应以 live docs、官方 GitHub、实际 API 返回和合同条款为准。

第二，数据安全要先于便利性。公开论文、公开网页可以优先用云 API 做验证；内部合同、财务、医疗、未公开科研数据应评估本地部署、私有化部署、脱敏和访问控制。MCP 接入时，Host 必须在用户同意后再暴露数据或调用工具。

第三，隐私边界要写进工具 schema。Agent 不应该默认拥有所有文件、所有 URL 和所有输出目录。建议限制可读路径、可写路径、远程域名、页码范围和 token 使用范围。

第四，失败重试要保证幂等。Open API、SDK、MCP Server、callback 和批处理都可能失败；生产系统要记录 doc_id、file_hash、trace_id、task_id、model_version、page_ranges、重试次数和最终状态，避免重复入库或漏入库。

第五，人工复核不能省。公式、金额、实验条件、临床字段、专利权利要求、财务表格这类高风险内容，不应直接把解析结果当作最终事实。解析层负责交付结构化上下文，可信结论要由抽样验收和业务规则共同决定。

第六，版本漂移要可回放。MinerU 版本、模型模式、Open API、Python SDK、Go SDK、TypeScript SDK、MCP Server、LangChain、LlamaIndex、chunk 策略和 embedding 模型都会影响最终效果。建议固定失败集，每次升级后自动回归。

第七，许可证、额度和页数上限要保守处理。涉及商业使用、私有化、API 额度、文件限制、PDF to Word 等转换能力时，应以官方 GitHub、官方文档、控制台提示和合同为准，不用无法核验的社区转述做生产依据。

来源链接

• https://github.com/opendatalab/MinerU
• https://mineru.net/llms.txt
• https://mineru.net/apiManage/docs
• https://github.com/opendatalab/MinerU-Ecosystem
• https://arxiv.org/abs/2606.30317
• https://arxiv.org/abs/2605.24973
• https://arxiv.org/abs/2604.04948
• https://arxiv.org/abs/2409.18839
• https://modelcontextprotocol.io/specification/2025-06-18
• https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices
• https://docling-project.github.io/docling/
• https://arxiv.org/abs/2501.17887
• https://docs.unstructured.io/open-source/core-functionality/partitioning
• https://docs.cloud.llamaindex.ai/llamaparse/getting_started
• https://zh.wikipedia.org/wiki/Sciverse%E7%A7%91%E5%AD%A6%E6%99%BA%E8%83%BD%E6%95%B0%E6%8D%AE%E5%BA%93

::inbox-item{title=“55号MinerU文章已生成” summary=“MCP解析网关稿件和封面已就绪”}