TARGET Checklist MCP

TARGET Checklist MCP Server

一个将 TARGET 报告指南（TrAnsparent ReportinG of observational studies Emulating a Target trial；Cashin 等人发表于 JAMA/BMJ，2025 年 9 月）转化为确定性、可追溯评分引擎的 MCP 服务，用于评估目标试验模拟（TTE）研究。

这是可执行的 TARGET：它不是给出主观意见的论文审查器，而是一种测量工具，可生成结构化、逐项且关联证据的矩阵，并固定模型溯源信息，从而确保大规模语料分析结果可复现。

完整设计原理请参阅 ../target-mcp-server-design.md。

状态 — 纵向切片

已构建并通过端到端验证：

• 规范层 — 将已发布的 21 个条目拆解为 39 个可评分的叶级子条目，并编码为带版本号的 YAML（target_mcp/specs/target-0.1.0.yaml），其中包含通俗表述的意图、判定边界、信号词、6x↔7x 规范/模拟配对及适用性规则。加载时进行结构验证（spec.py）。
• 摄取层 — 将 PDF/text/docx 转换为带字符偏移量的 SectionMap，其中包含标记来源的章节范围（正文与 supplement:<file>）、方案表格和流程图检测结果、提取器版本及文本哈希戳，以及对空白不敏感的引文→范围解析。通过 build_bundle（ingest.py）支持多文档包（正文 + 补充材料）。
• 检索层 — 提供语料/批处理及便捷路径：通过 PMCID 从 Europe PMC 获取开放获取文章（JATS 正文及 PMC 托管的补充文件，并合并为一个包）。在手头没有文件时，或需要自动获取开放获取论文的补充材料时使用此路径；对于收到的稿件，直接摄取文件（retrieve.py）。
• 评估层 — 对所有适用叶级子条目进行批量单轮评分。**脚手架模式（默认）**是审阅已发表论文的路径：由已在流程中的 Agent 评分，因此服务会返回精确提示词和架构供其执行，然后验证其提交的判定。评审模式适用于无头/批处理场景（循环中没有大模型）——服务自行调用固定模型，从而确保语料运行可复现且不受调用方影响。两种模式共用一套验证路径，强制要求覆盖所有叶级子条目、使用规定的判定词汇，并提供必需的逐字证据；这些证据会解析到带有 source_document 标签的范围（assess.py）。
• 呈现层 — render_checklist 会将最终评估映射到已发布的 TARGET 清单表单（全部 39 行，依据 CC BY-ND 原样呈现条目措辞，并根据已解析的证据范围填写“报告位置”列；增强视图还会添加判定和证据）。render_checklist_docx 会生成相同内容的可直接提交的 Word 文件（render.py、render_docx.py）。
• 语料与验证层 — aggregate_corpus 会汇总多项评估，计算逐项完整率及覆盖率分母（corpus.py）；validate.py 可生成盲法人工编码表，并针对金标准计算逐叶级一致性（原始一致率、Cohen's κ、Gwet's AC1、敏感度/特异度）。
• 组合层 — FastMCP 服务（server.py）公开了 11 个工具。主要稿件工作流为 parse_manuscript（解析收到的文件，有补充材料时使用 supplements=）→ assess_manuscript → submit_scaffold_verdicts → render_checklist（或 render_checklist_docx）。辅助工具：parse_pmcid（语料/批处理或获取开放获取补充材料）、get_checklist（检查规范）、aggregate_corpus、build_coding_sheet 和 validate_against_gold。

尚未构建（参见设计文档）：assess_item、check_emulation_coherence、export_identifiability_spec、出版商网站补充材料检索（PMC 开放获取层级之外）、更完善的表格提取，以及独立的实质性/设计风险层。

每项评估均附带来源信息

spec_version、解析后的 model id、temperature、prompt_hash、 prompt_template_version、extractor_version、text_sha256、assessed_at、 full_text_available、supplement_status，以及按来源划分的 documents 列表； 每条证据都包含解析后的文本跨度、章节和 source_document。 文本跨度只有结合提取器版本和文本哈希才有意义，因此两者会一并记录。

报告完整度，而非通过／不通过的判定

该工具评估的是稿件对清单要求的报告内容有多完整，而非研究质量，也不会给出通过／不通过的判定。TARGET 将全部 21 个条目列为基本必需项，不设分级，本工具也遵循这一做法：输出包含 39 个叶级条目的判定、证据和完整度统计。（此前曾设置“关键底线”，即对六个叶级条目附加 BSCL 通过／不通过判定；该机制已于 2026-07-19 移除，因为它偏离重点且容易造成混淆，详见 docs/DECISIONS.md。）不要将判定矩阵描述为符合 TARGET 要求。

安装

本仓库同时提供服务端和可选的编排技能，但它们通过两种独立机制启用——安装其中一项不会启用另一项。获取文件（克隆／下载）后，两者都会到手；然后完成以下两个启用步骤。

1. 安装服务端

git clone https://github.com/Black-Swan-Causal-Labs/target-mcp.git
cd target-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

（发布到 PyPI 后：pip install target-mcp。）

单独运行（stdio 传输）进行冒烟测试：

.venv/bin/target-mcp

2. 在 MCP 客户端中注册服务端

使用绝对路径将其添加到客户端的 MCP 配置中。对于 Claude Desktop，该文件为 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）；对于 Claude Code 项目，请使用 .mcp.json：

{
  "mcpServers": {
    "target-checklist": {
      "command": "/ABSOLUTE/PATH/TO/target-mcp/.venv/bin/python",
      "args": ["-m", "target_mcp.server"]
    }
  }
}

重启／重新连接客户端。确认其显示 11 个工具（过时的进程可能显示较少——请重新启动进程）。现在服务端本身已可完整使用：任何 MCP 客户端都可以通过一次脚手架流程运行 parse → assess → submit → render。

3.（可选，仅限 Claude Code）启用扇出技能

.claude/skills/target-checklist-fanout/ 实现了并行子 Agent 编排，可同时评估 39 个叶级条目（约 2 分钟，而非约 20 分钟）。它是加速工具，而非依赖项——仅适用于能够启动子 Agent 的客户端（Claude Code CLI，或 Claude Desktop 的 Code/Cowork 标签页；普通的 Chat 标签页不支持，Codex 等非 Claude 客户端也会忽略它）。没有该技能时，仍可通过单次流程回退方案完成所有操作。

Claude Code 会话在工作目录为本仓库时会发现该技能。若要使其在所有会话中均可用，不受目录限制，请将其复制到用户级目录：

mkdir -p ~/.claude/skills
cp -R .claude/skills/target-checklist-fanout ~/.claude/skills/

要让技能实际运行，以下三项必须全部就绪：服务端（步骤 2）、技能（此步骤）以及支持子 Agent 的客户端。

Judge 模式（无头／批处理，可选）

Judge 模式需要在环境中设置 ANTHROPIC_API_KEY。默认固定使用模型 claude-sonnet-5；可通过 TARGET_JUDGE_MODEL 覆盖。

批量 / 语料库运行

为数百篇论文评分属于无头任务，而不是交互式 MCP 调用（持续数小时的工具调用会超出客户端的请求超时时间）。请使用 target-mcp-corpus 命令行工具：它会并发获取并评审一组 PMCID， 隔离每篇论文的失败，重试暂时性错误，并汇总结果。

# ids.txt: one PMCID per line (#-comments and blanks ignored)
ANTHROPIC_API_KEY=sk-... target-mcp-corpus ids.txt -o out/ -j 12

• -j/--workers 限制并发数（默认为 8；可根据 API 速率限制调高）。 评审每篇论文约需几分钟，因此总耗时 ≈ papers / workers × per-paper——例如，12 个并发评审 300 篇论文约需 1–1.5 小时，而串行处理约需 10–20 小时。
• -o/--out-dir 会为每次评估写入一个 JSON 文件，并生成 aggregate.json 和 summary.json（包含每篇论文的时间戳、判定统计以及任何失败信息）。 若不使用 -o，则会将汇总结果输出到标准输出。
• --model 可覆盖固定的评审模型；--no-supplements 会跳过 补充材料的获取。

评审模式会记录每篇论文实际解析出的模型 ID，因此语料库汇总结果的来源记录准确，且不依赖调用方。随时可以使用 aggregate_corpus MCP 工具重新汇总已保存的评估结果。

测试

.venv/bin/python -m pytest tests/ -q

涵盖规范验证、章节映射和引文解析、最终确认与证据解析流程、证据必需和覆盖不匹配防护、 适用性规则、仅摘要的全文访问限制、语料库汇总、 验证测试框架、检查清单渲染（Markdown + .docx）以及提示词哈希稳定性。

许可 / 共享资源规范

编码后的检查清单是用自己的措辞重新表述条目意图，并附上评估者备注；它不会逐字复现 TARGET 检查清单的措辞。原始检查清单由 TARGET 团队版权所有，采用 CC BY-ND 4.0 许可。Explanation & Elaboration 文档发布后，应重新检查标记为 e_e_pending: true 的叶节点，并将规范升级为稳定的次版本发布。请勿逐字复制 E&E 文本。