Aryan-Pardeshi/CiteProof-AI-MCP · 上手攻略
- 仓库：Aryan-Pardeshi/CiteProof-AI-MCP
- 链接：https://github.com/Aryan-Pardeshi/CiteProof-AI-MCP
- 分类：agent / 学术研究工具（MCP + 多智能体流水线）
- 作者：spark
- 更新：2026-10-23
§0 自检（三证 checklist）
- [x] GitHub URL 已 fetch：README 经 web_fetch 拉取（2026-10-23，HTTP 200；内容截断于 Repository layout 段，末段 Contributing / Licence 未读到）
- [x] README 子模块 anchor：
MCP/README.md、MCP/docs/SPEC.md（工具参考）、MCP/docs/CLAUDE_SCIENCE.md、MCP/scripts/build_claude_science_bundle.py、visualizer类比目录结构均已核对 - [ ] 顶会 venue + 年份：⚠️ 无 arXiv、无会议 anchor。作者在仓库卡上的「学术状态 accepted」是知识库内部标注，README 中未见任何论文接收记录，不作为学术背书使用。
- 在线 Demo：https://deep-research-ai-xi.vercel.app/
- 许可：MIT（仓库卡记录，README 末段 Licence 因截断未直接读到，⚠️ 以仓库 LICENSE 文件为准）
§1 是什么 / 解决什么问题
CiteProof 瞄准的是 AI 做文献综述时最要命、也最少被工具解决的一环——举证。
作者的开篇判断很直接：「AI research agents are now good at finding and reading papers. They are less good at proving their work」：搜了哪些库、筛了多少条记录、引的那句话到底在不在原文里、两个审阅者是否一致。
所以 CiteProof 有两个相互独立的部分：
| CiteProof MCP | CiteProof Research（App） | |
|---|---|---|
| 是什么 | 24 个审计工具的 MCP server | 24-agent 研究流水线 Web 应用 |
| 谁做研究 | 你的 agent（Claude Science 或任意 MCP 客户端） | 应用自带的 agent |
| 内置语言模型 | 无，不需要 API key | 有，任意 OpenAI 兼容端点 |
| 擅长 | 需要审计痕迹的系统综述 | 快速带引文报告、完整有证据支撑的论文 |
| 代码位置 | MCP/ |
backend/ + frontend/ |
关键设计取向：MCP server 内部不带语言模型。它不搜索、不判断、不读 PDF。搜索/阅读/决定/写作都由外层 agent 做，server 只负责三件事——存下每个决策、检查它指向的证据、算数、拒收坏输入。
作者还坦白了一个负面发现（值得单独标出）：「A small first benchmark (two reviews against Claude Science) showed that agents with strong search find far more of the known included studies than CiteProof Research does.」——即搜索能力强的 agent 检索覆盖明显优于本项目的 app。正因如此，MCP server 刻意不做检索，只审计那个擅长检索的 agent 的产出。
§2 快速安装
2.1 只装 MCP server
git clone https://github.com/Aryan-Pardeshi/CiteProof-AI-MCP.git
cd CiteProof-AI-MCP
pip install ./MCP
MCP 客户端配置（stdio）：
{
"mcpServers": {
"citeproof": {
"command": "citeproof-mcp",
"env": { "CITEPROOF_MCP_HOME": "/path/to/your/review-data" }
}
}
}
审阅文件写到 CITEPROOF_MCP_HOME；未设置时落到 ~/.citeproof-mcp。
⚠️ README 原话：「Other clients were not tested for this release.」——本次发布只验证过 Claude Science。
2.2 装 Research App
cp .env.example .env
.env 最小配置：
LLM_API_KEY="your_api_key_here"
LLM_BASE_URL="https://api.deepseek.com"
TAVILY_API_KEY="your_tavily_key_here"
OPENALEX_EMAIL="you@example.com"
NCBI_EMAIL="you@example.com"
NCBI_TOOL_NAME="your_tool_name"
可选：SEMANTIC_SCHOLAR_API_KEY / NCBI_API_KEY / CORE_API_KEY / ORCID_AUTHOR_ENRICHMENT=0
Docker 起：
docker compose up -d --build
# UI: http://localhost:8000
不用 Docker：
python -m venv .venv
.venv\Scripts\activate # Windows（Unix 用 source .venv/bin/activate）
pip install -r requirements.txt
uvicorn backend.app.main:app --reload --port 8000
§3 核心用法
3.1 MCP server 检查什么
| 检查项 | 机制 |
|---|---|
| 引文真在原文里 | agent 发来引文与原文，server 归一化大小写、空白、引号、破折号、断行连字符后按词边界匹配，结果存为 quote_verified |
| 证据表的数字来自引文 | 样本量、估计值、置信区间必须写在引文里；落在区间外的估计值直接拒收 |
| PRISMA 数字对得上 | 计数来自记录的检索、去重、筛选决策，每次调用都校验流程不变量 |
| 两位审阅者一致 | 对双方都判过的论文算 Cohen's kappa，并列出分歧 |
| DOI 存在且未撤稿 | 走 Crossref 与 doi.org 查询；注册表不可达时返回 unverified，绝不返回 not found |
| 引文与参考文献表匹配 | 按 DOI / 作者+年份 / 标题匹配。「Resolved」仅表示匹配上，不表示被支撑 |
| 偏倚风险总评符合规则 | RoB 2、ROBINS-I、Newcastle-Ottawa（AHRQ 阈值） |
| 去重 | 按 DOI、PMID，再按 标题+年份+第一作者 做确定性聚类 |
3.2 24 个工具分组
| 组 | 工具 |
|---|---|
| 建立与状态 | review_create、review_list、protocol_record、review_status |
| 检索与去重 | prisma_record_search、dedup_papers、prisma_record_dedup |
| 筛选 | screening_record、screening_record_many、screening_list、screening_agreement |
| PRISMA | prisma_status、prisma_flow_diagram、prisma_checklist |
| 证据与偏倚 | evidence_record、evidence_table、claim_record、claim_report、rob_record、rob_summary |
| 引文与行文 | verify_dois、resolve_citations、lint_prose |
| 导出 | export_bundle |
3.3 Claude Science 专用安装（Local connector）
Claude Science 的 Local command connector 跑在读不到你项目目录的沙箱里，所以安装要把 server 复制进 connector 自己的 workspace：
python MCP/scripts/build_claude_science_bundle.py "<connector workspace folder>/bundle"
然后加一个 connector，命令为 python3 <connector workspace folder>/bundle/run.py。具体步骤见 MCP/docs/CLAUDE_SCIENCE.md。
3.4 App 的两种模式
| DeepSearch | Research Mode（Evidence-First） | |
|---|---|---|
| 目标 | 从实时 web 回答问题 | 写完整的有证据支撑的学术论文 |
| 来源 | Tavily web search | OpenAlex · Semantic Scholar · Crossref · PubMed · arXiv · Europe PMC · DOAJ · DataCite · OpenCitations |
| Agent | 5（并行 fan-out） | 24 个专业 agent，分 5 个证据阶段 |
| HITL | 1（计划审批） | 3 道质量闸（Protocol / Evidence Corpus / Hypotheses） |
| 数据不变量 | LLM web summary | 确定性 EvidenceRecord 存储（引文、指标、baseline） |
| PRISMA | N/A | 确定性 PRISMA 2020 流程计数与断言 |
| 完整性审计 | 引文正则 | 自动引文与数值声明的 grounding 校验 |
| 耗时 | ~1–2 分钟 | ~5–15 分钟 |
| 输出 | 结构化 markdown 报告 | 完整论文 + PRISMA 流程图 + 证据映射矩阵 |
| 导出 | .md |
.pdf · .docx |
流水线：研究问题 → 范围与方案 → 文献检索 → 证据抽取 → 综合 → 校验与导出。
三道闸用 LangGraph 的 interrupt() 真正暂停图执行，作者可用自然语言批准或要求定点修订：
- Gate 1 规划与方案（Phase 1）：PICOC 方案、目标、研究问题、布尔关键词 —— 在多源检索启动前防止查询跑偏
- Gate 2 证据与语料（Phase 3）：PRISMA 流程跟踪、已筛文献、抽取的 EvidenceRecord —— 在理论综合开始前验证实证 grounding
- Gate 3 假设与框架（Phase 4）：概念框架、研究缺口、形成的假设 H1..H5 —— 在提交全文生成前确认理论有效性
3.5 技术栈
- 编排：LangGraph（StateGraph、
interrupt()HITL、Send()fan-out、SQLite 持久化） - 结构化 LLM：Pydantic v2 schemas +
ainvoke_structured_with_retry - 学术源：OpenAlex / Semantic Scholar / Crossref / PubMed / arXiv / Europe PMC / DOAJ / DataCite / OpenCitations
- 作者增强：可选 ORCID（设
ORCID_AUTHOR_ENRICHMENT=1） - 全文获取：Unpaywall → Europe PMC → CORE 回退链
- 后端：FastAPI + SSE（含 keep-alive 心跳）
- 前端：Vanilla JS + CSS（Swiss Modernism 2.0，零构建，响应式）
- 图表：matplotlib（PRISMA 2020 流程图、假设-证据矩阵）
- 导出：FPDF2（.pdf，APA 悬挂缩进）· python-docx（.docx）
- MCP：mcp SDK（1.27 与 2.x）、SQLite、Pydantic v2、httpx
§4 典型适用场景
- 做系统综述（systematic review）且需要可审计痕迹。PRISMA 记录、筛选日志、双人一致性（kappa）、偏倚评估、导出 bundle 一条龙。审稿人或期刊要 PRISMA checklist 时，这是现成的。
- 写论文时数字与引文要能对账。
claim_validator把定量句里的数字与 EvidenceRecord 里的 benchmark 指标做数值匹配，citation_validator沿 claim → evidence → paper → DOI/URL 链逐级解析。 - 综述型团队协作。确定性 ID（
{paper_id}_ev001、{section}_cl001）让审阅记录可 diff、可追溯。 - 想用 AI 写东西但担心编造引文。把它当「AI 综述的 lint 层」接在 Claude Science 后面。
不适合：只要一份快速带引文的报告（直接用 App 的 DeepSearch 即可，不必上 MCP）；需要它自己去检索（它明确不搜索）。
§5 坑与注意（三段式：现象 / 影响 / 修复）
坑 1｜「Resolved」≠「被支撑」，这条最容易被误读
- 现象：README 明确——引文解析只是解析检查（matched），「a resolving claim is marked resolved, never verified」。passed_all_gates 只意味着解析与数值匹配过了，不代表源支持你的论断。
- 影响：把「全绿」当成「论文经得起查」，实际上引文可能真实存在却完全不支持那句话——这恰恰是学术写作最常见的翻车方式。
- 修复：把 CiteProof 当下限门槛（滤掉解析失败与数字不符），语义层面的支撑性仍需人工判断；关键结论务必回原文核对。
坑 2｜PRISMA 不变量是内部守恒式，不等于完整 PRISMA 2020
- 现象：README 坦承——full_text_requested 是「the tracker's internal shortcut for PRISMA's reports sought for retrieval」；PRISMA 中「reports not retrieved（full_text_unavailable）」与「reports assessed for eligibility（full_text_assessed）」虽分字段跟踪，但两者之间的交接没有被断言。原文：「the equations above are internal invariants rather than the complete PRISMA 2020 flow」。
- 影响：生成的 PRISMA 流程图可能在严格期刊审阅时被指出阶段缺失或不规范。
- 修复：投稿前对照目标期刊的 PRISMA 2020 checklist 逐项人工核对；别把 prisma_checklist 的通过当成合规证明——README 自己也说 checklist 是关键词检查，「show what is mentioned, not whether it is reported well」。
坑 3｜MCP server 不搜索，作者已量化过它的短板 - 现象：作者的小规模基准（两篇综述 vs Claude Science）显示，搜索能力强的 agent 找到的已知纳入研究远多于 CiteProof Research。 - 影响：误以为「装上 CiteProof 就能做完整综述」——实际上文献覆盖要靠外层 agent，MCP 只管审计。 - 修复：把 MCP server 配到搜索能力最强的 agent 上（Claude Science），让它做检索，CiteProof 做守门。
坑 4｜它明确不做四件事 - 现象：README 单列「What it does not do」：不搜论文、不做判断、不读 PDF（文本由 agent 提供）、checklist 与报告编号只是关键词检查。 - 影响：期待它端到端从 PDF 里抽数据的人会落空。 - 修复：把 agent 的全文提取环节做扎实（PDF → 文本质量直接决定 quote 匹配成功率），CiteProof 只接管审计层。
坑 5｜引文匹配依赖 agent 供文的准确性
- 现象：quote_verified 的前提是「The agent sends the quote and the text」，server 在 agent 给的文本里做归一化匹配。
- 影响：agent 若供了截断或改写的文本，匹配结果就失去意义——server 只能验证「在这份文本里」，无法验证「这份文本忠实于原文」。
- 修复：全文获取走官方回退链（Unpaywall → Europe PMC → CORE），尽量取原始全文而非摘要；抽样人工比对原文。
坑 6｜数字必须写在引文里，否则拒收
- 现象：「Sample size, estimate and confidence limits must be written in the quote. Estimates outside their interval are refused.」
- 影响：抽取环节没把统计量写进引文，evidence_record 会被直接拒收，agent 侧会收到报错而非静默通过。
- 修复：在抽取方案里明确要求引文包含样本量/估计值/置信区间；被拒时回上游修抽取，不要绕。
坑 7｜DOI 注册表不可达 ≠ 不存在
- 现象：设计上「An unreachable registry gives "unverified", never "not found"」。
- 影响：若你的流程把 unverified 当作 not found 处理（很多脚本默认如此），会把网络故障误报成「引用了假文献」，造成误删。
- 修复：显式区分 unverified 与 not found 两态，前者重试不否决。
坑 8｜Claude Science 安装路径特殊，且验证覆盖有限
- 现象：Local connector 沙箱读不到项目目录，必须用 build_claude_science_bundle.py 打包进 connector workspace。README 注明：「The server was checked on Claude Science 0.1.67 on Windows: it starts, and all 24 tools are listed. A full review run with every tool in Claude Science has not been benchmarked yet.」
- 影响：工具能列出来 ≠ 完整综述流程在 Claude Science 里跑通过；其他 MCP 客户端完全未测。
- 修复：升级 Claude Science 后重验；非 Claude Science 客户端按 MCP/README.md 自行适配 stdio 接入；关键流程先小规模试跑。
坑 9｜App 的数据不变量与文献 ID 都是「截断/派生」的确定性 ID
- 现象：paper_id 是 SHA-256 摘要的前 16 位十六进制（README 明确写「a truncated representation, not the full digest」），key 为 doi: 或回退的 title::年份；evidence_id 为 {paper_id}_ev001 这样的复合 ID（本身不再哈希）；claim_id 为 {section}_cl001（section slug 截到 8 字符）。
- 影响：极低概率碰撞；且归一化标题不假定唯一，所以回退 key 额外折入出版年份（未知记 nd）——同名同年不同文的论文仍可能撞。
- 修复：证据表入库时保留原始 DOI/PMID 字段做二次校验，不要只靠 paper_id 判重。
坑 10｜多 API key 与礼貌池配置项多，缺一项就降级
- 现象：OpenAlex、Crossref 共用 OPENALEX_EMAIL 走 polite pool；PubMed 要 NCBI_EMAIL + NCBI_TOOL_NAME（可选 NCBI_API_KEY）；Unpaywall 也用 OPENALEX_EMAIL；ORCID 需 ORCID_AUTHOR_ENRICHMENT=1。
- 影响：少配会静默走非礼貌池、被限流，或作者身份去重失效（同名作者混在一起）。
- 修复：按 README 表逐项配齐；运行前用 app 的作者增强结果抽查是否把两个同名作者合并了。
坑 11｜模式选择容易选错 - 现象：DeepSearch 产物是「LLM web summary」，Research Mode 才有确定性 EvidenceRecord 存储与 PRISMA 断言。 - 影响：为了写论文却跑了 DeepSearch，得到的报告没有证据不变量与流程断言。 - 修复：要投稿级材料就走 Research Mode（接受 5–15 分钟耗时与三道人工闸）；只做快速问答才用 DeepSearch。
坑 12｜上游服务与版本漂移
- 现象：依赖 8 个学术 API + Tavily + 任意 OpenAI 兼容 LLM 端点；mcp SDK 同时兼容 1.27 与 2.x；作者已在 Vercel 托管 Demo（deep-research-ai-xi.vercel.app）。
- 影响：任一上游改接口或限流策略都会打断流水线；托管 Demo 是他人账号，不保证长期可用或符合你的数据合规要求。
- 修复：自建部署优先（Docker Compose 或 uvicorn），别把严肃工作流绑在公开 Demo 上；⚠️ 本文核对基于 2026-10-23 的 main 分支 README，README 末段 Contributing / Licence 因抓取截断未读到，落地前请复核仓库现状。
§6 与同类对比
| 工具 | 核心能力 | 内置 LLM | 学术严谨性机制 | 适合 |
|---|---|---|---|---|
| CiteProof MCP | 审计已做的综述 | 无 | PRISMA、quote 校验、kappa、RoB 2/ROBINS-I、NOS、确定性 ID | 已有强检索 agent，加一层审计 |
| CiteProof Research App | 24-agent 端到端写论文 | 有 | EvidenceRecord + PRISMA 断言 + 3 道 HITL 闸 | 快速产出有证据的稿件 |
| Claude Science + 通用检索 | 检索与阅读强 | 有 | 依赖 agent 自觉 | 文献发现（作者实测覆盖最好） |
| Elicit / Consensus 类 | 论文检索与筛选 SaaS | 内部 | 筛选可追溯、抽取较弱 | 快速文献筛选 |
| Zotero + 手动 | 引用管理 | 无 | 全靠人 | 个人文献库管理 |
| 通用 MCP（如 filesystem/db 类） | 通用工具接入 | 无 | 无领域不变量 | 通用 agent 工具层 |
CiteProof 的稀缺之处在于领域不变量：它把「PRISMA 计数必须守恒」「引文必须在原文里」「区间外的估计值拒收」「两人筛选要算 kappa」写成硬校验，而不是提示词里的软建议。同类工具多数只做检索与摘要，严谨性靠人守。它的短板也对称——完全不碰检索，所以必须配一个检索强的 agent 才完整。
§7 一句话推荐结论
如果你（或你的 agent）已经在做系统综述、但苦于没有可交差的审计痕迹，装 CiteProof MCP 是当下少见的正确选择——它不含模型、只做硬校验，PRISMA 与引文 ground 这一层补得很扎实；但请记住「resolved 不等于被验证」，且它不搜索，务必配一个检索强的 agent 才好用。
来源：GitHub README（web_fetch，2026-10-23，HTTP 200，尾部截断于 Repository layout 段）+ repo card organized/repo_cards/4505-aryan-pardeshi-citeproof-ai-mcp.md。Live demo 未访问；未 clone、未运行代码；许可与 README 末段已标 ⚠️ 待核。