Corpus Pipeline | Agent MCP 工作流手册

Step 0

先确认 Agent 已经接上 corpus MCP

开始处理 PDF 前，不要先上传文件或让 Agent 跑命令。先确认当前 Agent 会话能看到这组受控工具。

0.1

选择连接方式

线上模式：在 Agent 的 MCP 配置中添加 Streamable HTTP 端点 https://corpus.phuyu.cloud/mcp。
本地模式：在你的 Agent 工具里选择本地配置的 corpus-pipeline MCP server（stdio 子进程）。

0.2

检查可用工具

确认 Agent 能调用登记、预检、MinerU job、artifact、Markdown、metadata、QC 和 review 相关 MCP tools。

0.3

先列状态，不做处理

第一次动作只让 Agent 调 list_documents，看当前有哪些 registered、inspected、review_required 或 approved 的文档。

0.4

锁定一个 document_id

一次只处理一个 document_id。没有 document_id 时，先走 register_document；已有时从当前 status 的下一步继续。

Deployment

线上 MCP 服务器 — Streamable HTTP

Corpus Pipeline 同时提供本地 stdio（默认）与线上 Streamable HTTP 两种模式。线上服务器已部署在 corpus.phuyu.cloud，任何 Agent 工具均可通过标准 MCP 协议远程调用。

线上 MCP 端点

https://corpus.phuyu.cloud/mcp

在 Agent 工具的 MCP 配置中选择 Streamable HTTP 传输，填入上方 URL 即可连接。服务器为无状态模式，支持多客户端并发。

健康检查

https://corpus.phuyu.cloud/health

返回服务状态、已注册工具列表。可用于监控和调试。

本地模式（默认）

python -m mcp_server.server

在本地终端启动，使用 stdio 传输。Agent 以子进程方式调用，适合单用户开发和测试。

自部署线上模式

python -m mcp_server.server \
  --transport streamable-http \
  --host 0.0.0.0 --port 8000

也可在任何服务器上独立运行 HTTP 模式，搭配 nginx 反向代理使用。MCP 端点位于 /mcp，健康检查在 /health。

MCP Setup

MCP 客户端配置指南

将 corpus-pipeline MCP 接入你的 Agent 工具。以下介绍 WorkBuddy 和 Codex CLI 两种主流 MCP 客户端的配置方法。

WorkBuddy

Streamable HTTP

方式一：图形界面（推荐）

打开聊天框下方的 "连接器" 按钮
选择 "管理连接器"
点击连接器列表右上角的 "自定义连接器"
点击 "配置 MCP" 按钮
粘贴以下 JSON 配置：

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

保存并返回 MCP 列表页
确认 "corpus-pipeline" 已开启

方式二：配置文件

直接编辑 ~/.workbuddy/mcp.json：

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

保存后重启 WorkBuddy 即可生效。新建会话后，输入"列出 corpus-pipeline 的所有工具"验证是否配置成功。

Codex（桌面版 / CLI）

Streamable HTTP

编辑配置文件

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。

配置说明

字段	值	说明
`transport`	`"http"`	远程 Streamable HTTP 连接
`url`	线上端点	MCP 服务器的 base URL
`enabled`	`true`	启用此 MCP 服务器
`default_tools_approval_mode`	`"auto"`	工具调用自动批准，无需每次确认

保存后重启 Codex 应用或新开会话。Agent 即可调用 corpus-pipeline 的全部 10 个 MCP 工具。

验证配置

在 Codex 中输入：

请通过 corpus-pipeline MCP 调用 list_documents，查看当前文档队列。

如果返回了文档列表 JSON，说明连接成功。

其他 MCP 客户端（Claude Desktop、Cursor、VS Code + MCP 插件等）同理，选择 Streamable HTTP 传输，填入 https://corpus.phuyu.cloud/mcp 即可。本地开发使用 stdio 模式，线上协作使用 HTTP 模式。

First Message

给 Agent 的第一句话

请通过 corpus-pipeline MCP 处理一份授权出版物 PDF。
先调用 list_documents 确认当前队列。
如果我要登记新文件，请先创建稳定 document_id；
如果已有 document_id，请从它当前 status 的下一步继续。

限制：
- 不要直接执行 shell。
- 不要直接读写任意文件夹。
- 不要覆盖 raw PDF。
- 不要自由拼 MinerU 命令。
- MinerU 只能选择已批准 profile。
- metadata 缺失或 QC 异常必须创建 review task。

你要给 Agent 的信息

文件是否已授权、是否已有 document_id、是否是新登记、你希望处理到哪个阶段。

Agent 应该回给你的信息

当前 status、下一步要调用的 MCP tool、预计产生的 artifact URI、需要人工确认的风险。

Runbook

一份 PDF 的完整 MCP 工具顺序

每位成员都从头学这条路径。熟练后也不要跳步骤；跳过状态记录会让后续审计和复核失效。

01
list_documents
先看队列。确认你要处理的是新文档、未完成文档，还是 review_required 文档。
02
register_document
新 PDF 先登记。生成 pub_000001 这类稳定 ID，记录 source_filename、sha256、rights_status。
03
inspect_document
读取页数、文本层密度、hash、疑似扫描件标记。没有 inspect，不提交 MinerU。
04
submit_mineru_job
只传 profile：baseline_auto_v1、ocr_scan_v1 或 debug_page_range_v1。不要让 Agent 暴露命令行参数。
05
get_job_status
查看 queued、running、mineru_done 或 failed。失败时先读 error 和 logs，不要无记录重跑。
06
get_artifacts
拿 artifact URI：output.md、content.json、layout.json、images、tables、logs、manifest.json。
07
normalize_markdown / extract_metadata
生成 clean.md 和 metadata.json。无法确认的 title、publisher、year 不要猜，标 review_required。
08
run_qc / create_review_task
QC 后才允许 approved。Markdown 为空、重复行异常、metadata 缺失或低置信度都要进入 review。

Tool Rules

什么时候该让 Agent 调哪个工具

你现在看到的情况让 Agent 调用下一步判断

不知道队列里有什么 list_documents 选择一个 document_id 或登记新文档。

刚拿到授权 PDF register_document 确认 manifest 和 raw PDF hash。

不知道该用哪个 MinerU profile inspect_document 按文本层和扫描件判断选择 profile。

转换还没开始 submit_mineru_job 记录 job_id，只允许 profile。

不知道转换是否结束 get_job_status mineru_done 后才收 artifact。

产物要交给清洗或 QC get_artifacts 只传 URI 和摘要，不贴整本文本。

准备判断是否可发布 run_qc fail 或低置信度进入 review。

Hard Limits

这些话不要对 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。

Review Queue

什么时候必须让 Agent 创建人工复核任务

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

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

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

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

Delivery

一份 PDF 完成后，把这个清单交出去

完成检查

document_id 和 source hash 已记录 MinerU profile 和 job_id 已记录 clean.md、metadata.json、qc.json 已生成 review_required 项目已有 review task 没有绕过 QC 直接 approved

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

从 Agent 接上 MCP 开始，跑完一份 PDF