methods-mcp

methods-mcp

学術論文から構造化された手法の抽出と再現性のヒューリスティック評価を行う、軽量で必要なときに使える MCP サーバーです。Worldwide AI Science Fellowship のビルドチャレンジ向けに開発されました。

⚠️ ステータス：アルファ版（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 エージェント（Claude Code、Claude Desktop、Agent SDK スクリプトなど）から8つのツールを利用でき、学術論文の URL から以下を取得できます。

• 標準化されたメタデータ
• ベストエフォートで取得した全文とセクション分割
• Pydantic で検証された構造化手法オブジェクト（手順／試薬／機器／分析）
• 論文に関連するコードリポジトリ（ベストエフォートで検出）
• そのリポジトリの実行不要の再現性判定
• 複数モードの要約

このツールの強みは、Paper2Agent（Stanford）のような大規模なパイプラインでは、論文をエージェントですぐに利用できるツールへ変換するのに30分から数時間かかる点です。methods-mcp は、エージェントから呼び出せるオンデマンド型の補完ツールです。各ツールは数秒で応答し、クローンも実行も必要ありません。

---

インストール

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 を発生させます。LLM を使わないツール（fetch_paper_text、find_code_repo、assess_repo_reproducibility）は引き続き正常に動作します。
GITHUB_TOKEN	assess_repo_reproducibility／methods_repro_review では任意ですが推奨	GitHub の未認証レート制限（IP あたり60 req/hr）が適用されます。リポジトリの評価には約3回の呼び出しが必要なため、約15～20件/時で上限に達します。トークンを設定すると5,000 req/hrとなり、実質的に無制限です。

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 export API にアクセスして、タイトル／著者／要旨を取得します。
fetch_paper_text(input_str, prefer="auto"|"html"|"pdf")	全文とセクション分割を取得します。arXiv 論文では既定で ar5iv HTML を使用します（低コストで構造化されています）。それ以外の場合は PDF にフォールバックします。
extract_methods(input_str, model=None)	LLM を使用し、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")	3 段階の詳しさで LLM による要約を生成します。
methods_repro_review(input_str)	複合ツールです。メタデータ、手法、リポジトリ、再現性を 1 回の呼び出しで取得します。

すべてのツールは Pydantic v2 モデル（検証済みで JSON シリアライズ可能）を返します。型の全容については src/methods_mcp/schemas.py を参照してください。

設計上の注意点

• extract_methods は Anthropic の tool-use を使用して、モデルに MethodsStructured Pydantic スキーマのインスタンスを出力させます。 検証に失敗した場合は、検証エラーを含む修正メッセージを 1 回送信して再試行し、その後エラーを発生させます。
• assess_repo_reproducibility は何もクローンまたは実行しません。 公開されている GitHub メタデータと再帰的なツリー一覧からリポジトリを評価します。これは、論文を実際に再実行しようとするバッチツールに対抗するための意図的な差別化要因です。
• fetch_paper_text は arXiv 論文で PDF の解析より ar5iv HTML を優先します。 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" のままです）。失敗したサブステップは {step, error_type, message, hint} を含む構造化エントリーとして errors に追加されます。hint は、認識されたパターン（API キーの不足、レート制限、404、タイムアウトなど）に対する実行可能な提案をわかりやすい英語で示し、それ以外の場合は null です。

スコアと判定の説明

ツールの出力には、似ているように見えて意味が大きく異なる3つの数値フィールドがあります。これらは、論文を詳しく調べる価値があるかをエージェントが判断するためのトリアージ指標であり、正しさを較正して示すものではありません。

フィールド	範囲	算出方法	読み取り方
methods.confidence	0–1	LLM による自己申告。 抽出モデルは、システムプロンプトの指示に従って値を設定します。論文に試薬、分量、機器が明記されている場合のみ≥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·スコア差で算出し、上限は0.95です。abstract-link：固定値0.85。none：0.0。	リポジトリがどのように見つかったか、またその特定がどれほど確実かを示します。高いスコアと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 or リポジトリにアクセスできない	判断に必要な情報が不十分です。どちらの結論も出さないでください。

出力に表示される列挙値：

• 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、シェルコマンドの実行はありません。再現性ツールは、意図的にリポジトリのクローンや実行を行わず、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はその上に構造化手法と再現性のレイヤーを追加します。この2つは、連携して使えるよう意図的に設計されています。

ローカルで開発する

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の第1期参加者向けに開発されました。自由度の高い企画概要を提供してくれたMichael Raspuzziに感謝します。

以下を基盤として構築されています。

• FastMCP 3.x — MCP サーバーのひな型。
• Claude Agent SDK — デモのエージェントループ。
• ar5iv.labs.arxiv.org — arXiv論文の読みやすいHTML。
• Anthropic Claude — 構造化抽出を担うLLM。