Corpus Pipeline

Batch-First MCP Pipeline · corpus.phuyu.cloud/mcp

一条指令，批量处理全部 PDF

Agent 通过 MCP 调用 13 个受控工具，自动完成登记、预检、MinerU 转换、Markdown 清洗、 元数据提取、QC 质检、人工复核的全流程。不碰 shell，不手拼命令，不改 raw PDF。

快速开始 接入指南
Agent + MCP 管线示意图
成员发指令，Agent 走 MCP，管线写受控产物。

Quick Start

快速开始 — 复制这段话给 Agent

连上 corpus-pipeline MCP 后，把下面这段话发给 Agent，它就会自动扫描目录、登记新文件、并行推进所有文档直至 QC 完成。

请批量处理 /data/new_publications 目录下的全部 PDF。

先调用 register_batch 登记新文件，
再对每个新登记的 document_id 调用 run_pipeline（profile=baseline_auto_v1），
最后用 batch_status 汇总全量结果，
把需要人工复核的文档列出来。
1

register_batch

传入一个 PDF 目录路径，Agent 自动扫描所有 .pdf 并分配 pub_000001 等稳定 ID。已登记的自动跳过。

2

run_pipeline

端到端单文档全自动：inspect → mineru → normalize → metadata → QC。mock 模式毫秒级返回，适合测试和批量验证。

3

batch_status

全量进度总览：每个状态多少文档、每个文档到哪一步、next_actions 智能建议下一步该做什么。

4

review / 交付

QC 未通过的自动进入 review。Agent 汇总待复核清单，人类只需审核 title、publisher、year 三个字段。

Setup

接入指南 — 把 corpus-pipeline 接入你的 Agent

Step 0 · 确认连接

线上服务器已部署在 https://corpus.phuyu.cloud/mcp（健康检查 /health）。任何 Agent 工具只需选择 Streamable HTTP 传输，填入这个 URL 即可。

WorkBuddy

图形界面：连接器 → 管理连接器 → 自定义连接器 → 配置 MCP，粘贴如下 JSON：

{
  "mcpServers": {
    "corpus-pipeline": {
      "type": "streamable-http",
      "url": "https://corpus.phuyu.cloud/mcp"
    }
  }
}

或者直接编辑 ~/.workbuddy/mcp.json，保存后重启。

Codex（桌面版 / CLI）

编辑 ~/.codex/config.toml：

[mcp_servers.corpus-pipeline]
transport = "http"
url = "https://corpus.phuyu.cloud/mcp"
enabled = true
default_tools_approval_mode = "auto"

macOS / Linux 路径 ~/.codex/config.toml；Windows 路径 %USERPROFILE%\.codex\config.toml。

Claude Desktop、Cursor、VS Code 等工具同理 — 全部使用 Streamable HTTP + https://corpus.phuyu.cloud/mcp。本地开发可用 python -m mcp_server.server（默认 stdio）。

How It Works

工作流原理 — 13 个工具协同的完整管线

批量模式的 run_pipeline 内部复用了下面这些步骤。了解原理有助于排错和深度定制。

  1. 01
    list_documents / batch_status

    看队列。哪个文档在哪一步，需要新登记还是继续推进。

  2. 02
    register_document / register_batch

    新 PDF 分配 pub_000001 稳定 ID，记录 hash、rights_status。批量版一键扫目录。

  3. 03
    inspect_document

    读页数、文本层密度、hash、疑似扫描件。决定用哪个 MinerU profile。

  4. 04
    submit_mineru_job

    只传 profile：baseline_auto_v1 / ocr_scan_v1 / debug_page_range_v1。Agent 不暴露命令行。

  5. 05
    get_job_status

    查看 queued → running → mineru_done / failed。失败时先读 log，不无记录重跑。

  6. 06
    get_artifacts

    拿产物 URI：output.md、content.json、layout.json、images、tables、logs、manifest。

  7. 07
    normalize_markdown / extract_metadata

    生成 clean.md + metadata.json。无法确认的字段标 review_required，不要猜。

  8. 08
    run_qc / create_review_task

    QC 检查完整性、重复行、metadata 字段。未通过的进入人工复核。

全部 13 个 MCP 工具

工具类型一句话
batch_statusbatch全量进度概览 + 建议
register_batchbatch扫描目录批量登记 PDF
run_pipelinebatch端到端自动走完全流程
list_documentscore列出队列中所有文档及状态
register_documentcore单文档登记，分配稳定 ID
inspect_documentcore预检页数、文本层、扫描件标记
submit_mineru_jobcore提交 MinerU 转换作业
get_job_statuscore查看作业状态
get_artifactscore获取产物 URI 清单
normalize_markdowncore生成 clean.md
extract_metadatacore提取 title / publisher / year
run_qccoreQC 质检
create_review_taskcore创建人工复核任务

禁区 — 这些话不要对 Agent 说

高风险指令

  • “直接进服务器跑一下命令”
  • “把这个目录全扫一遍”
  • “覆盖掉旧 PDF”
  • “所有文件批量重跑”
  • “你自己改 metadata 数据库”

正确说法

  • “通过 MCP 查看这个 document_id 的状态”
  • “用 inspect_document 判断 profile”
  • “提交 baseline_auto_v1 的 MinerU job”
  • “返回 artifact URI 和 QC 摘要”
  • “为缺失字段创建 review task”

出错时

  • 保留 job_id、error、logs
  • 只重跑明确失败阶段
  • 不要删除旧 artifact
  • 把不确定项写入 review.json

Delivery & Review

交付与复核

批量流水线跑完后，Agent 会给出汇总。以下清单帮你确认交付质量。

Review Queue

什么时候必须人工复核

metadata 缺 title、publisher、publication_year，或 confidence 低于团队阈值。

Markdown 为空、重复行比例异常、双栏顺序混乱、页码或章节明显错位。

图片、表格数量与版面预期明显不符，或 OCR 质量不足以直接入库。

成员无法判断时，不让 Agent 猜结论；保留证据并创建 review task。

交付前确认

document_id: pub_000001
current_status: qc_done | review_required | approved
agent_entry: corpus-pipeline MCP
mineru_profile: baseline_auto_v1
job_id: job_000001
artifacts:
  clean_markdown: corpus/cleaned/pub_000001.clean.md
  metadata: corpus/metadata/pub_000001.metadata.json
  qc: corpus/qc/pub_000001.qc.json
review:
  required: true
  reason: Missing publication_year
next_action: human reviewer checks title page