methods-mcp

methods-mcp

面向学术论文的轻量级按需 MCP 服务，用于结构化方法提取和可复现性启发式评估。为 Worldwide AI Science Fellowship 构建挑战而打造。

⚠️ 状态：alpha（0.1.x）。 工具接口和输出格式可能会在次要版本之间发生变化。用于生产环境时，请锁定到确切版本。非常欢迎通过 GitHub Issues 提交错误报告。

快速演示

$ uvx --from methods-mcp methods-mcp --version
methods-mcp 0.1.6

# In a Claude Code session:
> /mcp add methods-mcp methods-mcp
> Run methods_repro_review on https://arxiv.org/abs/2509.06917

  → tool: methods_repro_review({"input_str":"https://arxiv.org/abs/2509.06917"})

# Returns a MethodsReproReview object. Read `narrative` first — it explains
# everything else in plain English, so no tool-learning is required:

{
  "status": "ok",
  "narrative":
    "Resolved the paper: 'Paper2Agent' by Miao et al. (arxiv 2509.06917, "
    "2025-09-08). Extracted 11 methods steps at moderate self-reported "
    "confidence (0.72) — the procedure is clearly described but hyperparameters "
    "and software versions are absent. Detected the associated code repository "
    "https://github.com/jmiao24/Paper2Agent from an inline link in the paper "
    "text (detection confidence 0.94). The repo scored 0.90/1.00 on the "
    "reproducibility heuristic — verdict: likely reproducible. Present signals: "
    "substantive README, dependencies file, notebooks, figure-plotting script, "
    "recent activity, permissive license. Missing: data/fixtures directory. "
    "Suggested entrypoint: `python make_figures.py`.",
  "metadata":          { ... },   # PaperMetadata
  "methods":           { ... },   # MethodsStructured (null if extraction failed)
  "code_repo":         { ... },   # CodeRepo           (null only if input unresolvable)
  "repro_assessment":  { ... },   # ReproAssessment   (null if no repo detected)
  "errors":            []         # [{step, error_type, message, hint}] on partial
}

---

methods-mcp 是一个小巧且范围明确的 Model Context Protocol 服务。它为任何 AI Agent（Claude Code、Claude Desktop、你的 Agent SDK 脚本等）提供八种工具，可将学术论文 URL 转换为：

• 标准元数据，
• 尽力获取的全文和分节内容，
• 经过 Pydantic 验证的结构化方法对象（步骤 / 试剂 / 设备 / 分析），
• 论文关联的代码仓库（尽力发现），
• 对该仓库的无需执行即可得出的可复现性结论，以及
• 多模式摘要。

核心优势：像 Paper2Agent（Stanford）这样的重量级流水线需要 30 分钟到数小时，才能将论文转化为适用于 Agent 的工具。methods-mcp 是可由 Agent 调用、按需使用的补充方案——每种工具都能在数秒内返回，无需克隆，也无需执行。

---

安装

uv add methods-mcp
# or, install globally:
uv tool install methods-mcp
# or, classic pip:
pip install methods-mcp

API 密钥

为获得最佳性能，请同时设置以下两项：

变量	必需？	未设置时的情况
ANTHROPIC_API_KEY	对 extract_methods、summarize_paper、methods_repro_review 必需	这些工具会抛出 RuntimeError: ANTHROPIC_API_KEY not set。非大模型工具（fetch_paper_text、find_code_repo、assess_repo_reproducibility）仍可正常使用。
GITHUB_TOKEN	对 assess_repo_reproducibility / methods_repro_review 可选，但建议设置	你会受限于 GitHub 未认证速率限制（每个 IP 60 次请求/小时）。每次仓库评估约需 3 次调用，因此每小时约评估 15–20 个仓库后就会达到上限。使用令牌后：5,000 次请求/小时（实际上不受限制）。

export ANTHROPIC_API_KEY=sk-ant-...
export GITHUB_TOKEN=ghp_...          # optional but recommended

两个密钥都不会被记录或持久化——它们仅分别发送到 api.anthropic.com 和 api.github.com。请参阅 SECURITY.md。

在 Claude Code 中使用

/mcp add methods-mcp methods-mcp

然后在任意 Claude Code 聊天中输入：

获取 https://arxiv.org/abs/2509.06917，并运行 methods_repro_review。总结这篇论文的研究内容、方法步骤，以及该仓库看起来有多可复现。

在 Claude Agent SDK 中使用

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

options = ClaudeAgentOptions(
    mcp_servers={
        "methods-mcp": {
            "type": "stdio",
            "command": "methods-mcp",
            "args": [],
        }
    },
    allowed_tools=["mcp__methods-mcp__methods_repro_review"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query(
        "Run methods_repro_review on https://arxiv.org/abs/2509.06917 "
        "and tell me whether the repo looks reproducible."
    )
    async for msg in client.receive_response():
        print(msg)

工具

工具	功能
health	检查服务是否存活及配置。
get_paper_metadata(input_str)	将 URL / arXiv ID / DOI 解析为规范元数据。对于 arXiv 输入，会调用 arXiv 导出 API 获取标题、作者和摘要。
fetch_paper_text(input_str, prefer="auto"|"html"|"pdf")	获取全文并按章节拆分。对于 arXiv 论文，默认使用 ar5iv HTML（成本低、结构化）；否则回退到 PDF。
extract_methods(input_str, model=None)	由大模型驱动、经 Pydantic 验证的结构化方法提取。返回 {steps, reagents, equipment, analyses, confidence}。
find_code_repo(input_str)	通过论文正文 → 摘要 → Papers With Code，查找论文的代码仓库。
assess_repo_reproducibility(repo_url, paper_id=None)	通过 GitHub REST API 进行启发式可复现性评估，不克隆仓库。加权信号（README、依赖、测试数据、笔记本、图表脚本、近期维护情况、许可证）→ {verdict, score, recommended_entrypoint}。
summarize_paper(input_str, mode="tldr"|"abstract"|"exec")	以三种详细程度生成大模型摘要。
methods_repro_review(input_str)	综合调用——一次性获取元数据、方法、仓库和可复现性信息。

所有工具均返回 Pydantic v2 模型（经过验证、可序列化为 JSON）。完整类型定义见 src/methods_mcp/schemas.py。

设计说明

• extract_methods 使用 Anthropic 工具调用，促使模型输出 MethodsStructured Pydantic 架构的实例。 如果验证失败，我们会发送一条包含验证错误的修正消息并重试，然后再抛出异常。
• assess_repo_reproducibility 不会克隆或执行任何内容。 它根据公开可读的 GitHub 元数据和递归树列表为仓库评分。这是我们有意采用的差异化方向，旨在区别于试图实际重新运行论文的批处理工具。
• 对于 arXiv 论文，fetch_paper_text 优先使用 ar5iv HTML，而不是解析 PDF。 对于非 arXiv 输入，则回退到 pypdf。
• 默认模型为 claude-sonnet-4-6。 可通过 METHODS_MCP_MODEL 环境变量或每次调用时的 model= 参数覆盖。
• methods_repro_review 返回自描述式响应。 每次调用都会设置顶层 status（"ok" / "partial" / "empty"）和 narrative 字符串，以通俗易懂的语言概述检索到的所有信息，并在上下文中说明每个数值评分。只阅读 narrative 和 status，无需了解子对象的结构，也能掌握全部情况。如果子对象不可用，其值可以为 null（例如，论文未检测到仓库时，repro_assessment: null；由于“没有仓库”并非失败，因此 status 仍为 "ok"）。失败的子步骤会在 errors 中生成一条结构化记录，包含 {step, error_type, message, hint}；对于可识别的情况（缺少 API 密钥、速率限制、404、超时等），hint 会提供可执行的通俗建议，否则为 null。

分数与判定说明

工具输出包含 3 个数值字段，它们看起来相似，但含义大不相同。这些字段是供 Agent 判断一篇论文是否值得深入研究的初步信号，并非经过校准的正确性声明。

字段	范围	计算方式	如何解读
methods.confidence	0–1	大模型自我报告。 提取模型根据系统提示词中的指示为其赋值：只有当论文明确列出试剂／用量／设备时才设为 ≥0.8；如果方法部分内容稀少，则设为 ~0.3。未经校准。	这是一个弱信号，用于判断*“这是一篇包含具体流程的湿实验论文，还是一篇内容稀少的系统论文？”* 可用作标记，但不要把它当作可信度百分比。
code_repo.confidence	0–1	因 detection_method 而异。 papers-with-code：固定为 0.95（权威的论文→代码仓库 API）。paper-text：计算方式为 0.6 + 0.2·(是否存在强提示短语) + 0.015·score_margin，上限为 0.95。abstract-link：固定为 0.85。none：0.0。	告诉你代码仓库是如何被找到的，以及判断有多明确。对于高分且 detection_method 为 paper-text 的情况，意味着 URL 旁边有类似 “代码可在……获取” 的强提示短语。
repro_assessment.overall_score	0–1	8 个二元信号的加权总和，全部通过 GitHub REST API 计算（不克隆、不执行）：has_readme（0.10）、readme_substantial（0.15）、has_dependencies_file（0.20）、has_data_or_fixtures（0.10）、has_notebook（0.10）、has_figure_script（0.20）、actively_maintained（0.10）、permissive_license（0.05）。每个存在的信号贡献相应权重。	这是 3 个分数中唯一完全确定性的分数。但它仍是启发式指标，而非证明——高分意味着代码仓库看起来结构良好，适合复现。有关实际验证，请参阅 Paper2Agent。

判定档位（repro_assessment.verdict）由 overall_score 的阈值决定：

判定	分数	含义
likely-reproducible	≥ 0.70	存在大多数有利于复现的信号。值得尝试运行。
partial	≥ 0.45	有一些基础设施，但可能存在缺口。预计需要补齐缺失部分。
unlikely	≥ 0.20	信号很少。可能只是代码转储，缺少重新运行所需的支撑结构。
insufficient-info	< 0.20 或 代码仓库无法访问	信息不足，无法判断。不要据此得出任何结论。

输出中会看到的枚举值：

• code_repo.detection_method：paper-text | abstract-link | papers-with-code | metadata | none
• metadata.source：arxiv | biorxiv | doi | url | unknown

安全性与限制

安装并运行此服务时，它实际会执行以下操作：

• 仅向以下地址发起网络请求：export.arxiv.org、ar5iv.labs.arxiv.org、arxiv.org（PDF）、api.github.com、paperswithcode.com、api.anthropic.com。不进行遥测、分析或电话回传。
• 读取环境变量中的 ANTHROPIC_API_KEY（LLM 工具必需）和可选的 GITHUB_TOKEN。这些信息只会分别发送给 Anthropic / GitHub。绝不会记录日志，也不会持久化到磁盘。
• 不会向你的文件系统写入任何内容。没有缓存目录、下载的 PDF 或临时文件。
• 不会执行用户提供的代码。没有 eval、exec、subprocess、pickle.loads 或调用 shell。可复现性工具有意不克隆或运行代码仓库——它只根据 GitHub REST API 进行评分。

需要注意的限制：

• 对抗性论文可能会生成误导性的结构化输出。 extract_methods 工具会将论文文本发送给 Claude。包含提示注入内容的论文可能导致生成错误（但符合架构）的结构化方法。请将输出视为研究辅助工具，而非事实依据。
• 可复现性判定是一种启发式评估，而非证明。 高分表示代码仓库看起来结构良好，适合复现；但这并不保证运行代码就能复现论文。若要进行全面验证，请参阅 Paper2Agent。
• 此工具适用于本地 stdio 使用。 提供 HTTP/SSE 传输是为了方便开发，但只应在可信网络中公开（除 httpx 提供的保护外，没有 SSRF 防护）。

报告问题：

安全问题：请发送电子邮件至 [email protected]（另请参阅 SECURITY.md）。功能缺陷：请提交 GitHub issue。

与 paper-mcp 搭配使用

若要使用更全面的论文搜索 / 引用图工具，请在同一个 Claude Code 会话中同时运行 paper-mcp (Bhvaik)。paper-mcp 支持按标题搜索、获取全文、查看引用和参考文献；methods-mcp 则在此基础上增加结构化方法和可复现性功能。这两个工具的设计初衷就是协同使用。

本地开发

git clone https://github.com/FlynnLachendro/methods-mcp
cd methods-mcp
uv sync --extra dev --extra agent

uv run pytest                      # 49 tests, offline (respx-mocked httpx + unittest.mock for Anthropic)
uv run ruff format .
uv run ruff check . --fix
uv run mypy src

uv run methods-mcp --help

许可证

MIT — 参见 LICENSE。

致谢

本项目为 Worldwide AI Science Fellowship 首届 cohort 构建。感谢 Michael Raspuzzi 提供开放式项目说明。

基于以下项目构建：

• FastMCP 3.x — MCP 服务脚手架。
• Claude Agent SDK — 演示中的 Agent 循环。
• ar5iv.labs.arxiv.org — arXiv 论文的清晰 HTML 版本。
• Anthropic Claude — 支持结构化提取的大模型。