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）。

Agent 工作流指令 — 多平台安装

除了 MCP 服务器配置，还可以加载一份 工作流指令，让 Agent 严格按标准批量流程执行。 提供三种形式：通用指令文件、WorkBuddy Skill、Codex Plugin。

通用指令（所有 Agent）

  1. 下载 工作流指令（5 KB）
  2. 放入对应位置或直接粘贴到系统提示词

WorkBuddy Skill

将上面下载的文件放到 ~/.workbuddy/skills/corpus-pipeline/SKILL.md，或在对话中说 "安装这个 skill" 并附上文件。

Codex Plugin

  1. 下载 Codex Plugin 包（4 KB）
  2. 解压到任意目录，例如 ~/.codex/plugins/corpus-pipeline/
  3. 用 @plugin-creator 注册到本地 marketplace，或在 Codex 中 /plugins 安装本地插件

Plugin 内含 plugin.json + SKILL.md + .mcp.json，安装后自动配置 MCP 连接 + 加载工作流指令。

对话自动安装

对 Agent 说：

请从 https://corpus.phuyu.cloud/downloads/corpus-pipeline-skill.md
加载 corpus-pipeline 工作流指令

Agent 会读取指令并按标准流程执行后续任务。

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

Downloads

下载 — 本地部署 & Skill 文件

以下资源可直接下载使用，无需注册或认证。

🔌

Codex Plugin

完整 Codex 插件包（4 KB）— 含 plugin.json + SKILL.md + .mcp.json。
解压后通过 /plugins 或 @plugin-creator 安装。

ZIP
🧩

Agent 工作流指令

通用 Markdown 指令文件（5 KB）— 适配 WorkBuddy Skill / Codex / Claude Code 等所有 Agent。
直接放入对应目录或粘贴为系统提示词。

SKILL.md
📦

MCP 服务器（本地部署包）

ZIP 包含 mcp_server/ + pipeline/ + requirements.txt（26 KB）。
本地 stdio 或 HTTP 模式运行，无需外部依赖。

ZIP

本地部署步骤

# 1. 下载并解压
unzip corpus-pipeline-mcp-server.zip -d corpus-pipeline

# 2. 安装依赖（需要 Python ≥ 3.11）
cd corpus-pipeline
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 3. 启动 MCP 服务器（stdio 模式，供本地 Agent 调用）
.venv/bin/python -m mcp_server.server

# 4. 或启动为线上服务器
.venv/bin/python -m mcp_server.server --transport streamable-http --port 8000