{
  "markdown": "# methods-mcp\n\n<!-- mcp-name: io.github.FlynnLachendro/methods-mcp -->\n\n[![PyPI](https://img.shields.io/pypi/v/methods-mcp.svg)](https://pypi.org/project/methods-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/methods-mcp.svg)](https://pypi.org/project/methods-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n> Lightweight, on-demand MCP server for **structured methods extraction** + **reproducibility heuristics** on academic papers. Built for the [Worldwide AI Science Fellowship](https://www.aisciencesummit.com/) build challenge.\n\n> ⚠️ **Status: alpha (0.1.x).** The tool surface and output shapes may shift between minor versions. **Pin to an exact version** in production. Bug reports very welcome via [GitHub Issues](https://github.com/FlynnLachendro/methods-mcp/issues).\n\n## Quick demo\n\n```text\n$ uvx --from methods-mcp methods-mcp --version\nmethods-mcp 0.1.6\n\n# In a Claude Code session:\n> /mcp add methods-mcp methods-mcp\n> Run methods_repro_review on https://arxiv.org/abs/2509.06917\n\n  → tool: methods_repro_review({\"input_str\":\"https://arxiv.org/abs/2509.06917\"})\n\n# Returns a MethodsReproReview object. Read `narrative` first — it explains\n# everything else in plain English, so no tool-learning is required:\n\n{\n  \"status\": \"ok\",\n  \"narrative\":\n    \"Resolved the paper: 'Paper2Agent' by Miao et al. (arxiv 2509.06917, \"\n    \"2025-09-08). Extracted 11 methods steps at moderate self-reported \"\n    \"confidence (0.72) — the procedure is clearly described but hyperparameters \"\n    \"and software versions are absent. Detected the associated code repository \"\n    \"https://github.com/jmiao24/Paper2Agent from an inline link in the paper \"\n    \"text (detection confidence 0.94). The repo scored 0.90/1.00 on the \"\n    \"reproducibility heuristic — verdict: likely reproducible. Present signals: \"\n    \"substantive README, dependencies file, notebooks, figure-plotting script, \"\n    \"recent activity, permissive license. Missing: data/fixtures directory. \"\n    \"Suggested entrypoint: `python make_figures.py`.\",\n  \"metadata\":          { ... },   # PaperMetadata\n  \"methods\":           { ... },   # MethodsStructured (null if extraction failed)\n  \"code_repo\":         { ... },   # CodeRepo           (null only if input unresolvable)\n  \"repro_assessment\":  { ... },   # ReproAssessment   (null if no repo detected)\n  \"errors\":            []         # [{step, error_type, message, hint}] on partial\n}\n```\n\n---\n\n`methods-mcp` is a small, sharply-scoped [Model Context Protocol](https://modelcontextprotocol.io) server. It gives any AI agent (Claude Code, Claude Desktop, your Agent SDK script, etc.) eight tools that turn an academic paper URL into:\n\n- canonical metadata,\n- best-effort full text + section split,\n- a **Pydantic-validated structured methods object** (steps / reagents / equipment / analyses),\n- the paper's associated **code repository** (best-effort discovery),\n- a **no-execution-required reproducibility verdict** for that repo, and\n- a multi-mode summary.\n\nThe wedge: heavyweight pipelines like [Paper2Agent](https://arxiv.org/abs/2509.06917) (Stanford) take 30 minutes to hours to digest a paper into agent-ready tools. `methods-mcp` is the **agent-callable, on-demand** complement — every tool returns in seconds, no clone, no execution.\n\n---\n\n## Install\n\n```bash\nuv add methods-mcp\n# or, install globally:\nuv tool install methods-mcp\n# or, classic pip:\npip install methods-mcp\n```\n\n### API keys\n\nFor best performance, set **both**:\n\n| Variable | Required? | What you get without it |\n|---|---|---|\n| `ANTHROPIC_API_KEY` | **Required** for `extract_methods`, `summarize_paper`, `methods_repro_review` | Those tools raise `RuntimeError: ANTHROPIC_API_KEY not set`. Non-LLM tools (`fetch_paper_text`, `find_code_repo`, `assess_repo_reproducibility`) still work fine. |\n| `GITHUB_TOKEN` | **Optional but recommended** for `assess_repo_reproducibility` / `methods_repro_review` | You're capped at the GitHub unauthenticated rate limit (**60 req/hr per IP**). Each repo assessment is ~3 calls, so you'll hit the ceiling after ~15–20 repos/hr. With a token: **5,000 req/hr** (effectively unlimited). |\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\nexport GITHUB_TOKEN=ghp_...          # optional but recommended\n```\n\nNeither key is logged or persisted — they're sent only to `api.anthropic.com` and `api.github.com` respectively. See [`SECURITY.md`](SECURITY.md).\n\n## Use it from Claude Code\n\n```\n/mcp add methods-mcp methods-mcp\n```\n\nThen in any Claude Code chat:\n\n> Take https://arxiv.org/abs/2509.06917 and run `methods_repro_review`. Summarise what the paper does, the methods steps, and how reproducible the repo looks.\n\n## Use it from the Claude Agent SDK\n\n```python\nfrom claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient\n\noptions = ClaudeAgentOptions(\n    mcp_servers={\n        \"methods-mcp\": {\n            \"type\": \"stdio\",\n            \"command\": \"methods-mcp\",\n            \"args\": [],\n        }\n    },\n    allowed_tools=[\"mcp__methods-mcp__methods_repro_review\"],\n)\n\nasync with ClaudeSDKClient(options=options) as client:\n    await client.query(\n        \"Run methods_repro_review on https://arxiv.org/abs/2509.06917 \"\n        \"and tell me whether the repo looks reproducible.\"\n    )\n    async for msg in client.receive_response():\n        print(msg)\n```\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `health` | Server liveness + config check. |\n| `get_paper_metadata(input_str)` | Resolve URL / arXiv ID / DOI to canonical metadata. arXiv inputs hit the arXiv export API for title/authors/abstract. |\n| `fetch_paper_text(input_str, prefer=\"auto\"\\|\"html\"\\|\"pdf\")` | Full text + section split. Defaults to ar5iv HTML for arXiv papers (cheap, structured), PDF fallback otherwise. |\n| `extract_methods(input_str, model=None)` | LLM-driven, Pydantic-validated structured methods extraction. Returns `{steps, reagents, equipment, analyses, confidence}`. |\n| `find_code_repo(input_str)` | Discover the paper's code repo via paper text → abstract → Papers With Code. |\n| `assess_repo_reproducibility(repo_url, paper_id=None)` | Heuristic, no-clone reproducibility assessment via the GitHub REST API. Weighted signals (README, deps, fixtures, notebooks, figure scripts, recent maintenance, license) → `{verdict, score, recommended_entrypoint}`. |\n| `summarize_paper(input_str, mode=\"tldr\"\\|\"abstract\"\\|\"exec\")` | LLM summary in three depths. |\n| `methods_repro_review(input_str)` | Composite — metadata + methods + repo + repro in one call. |\n\nAll tools return Pydantic v2 models (validated, JSON-serialisable). See [`src/methods_mcp/schemas.py`](src/methods_mcp/schemas.py) for the full type surface.\n\n## Design notes\n\n- **`extract_methods` uses Anthropic tool-use to coerce the model into emitting an instance of the `MethodsStructured` Pydantic schema.** On validation failure we send one repair message with the validation error and try again before raising.\n- **`assess_repo_reproducibility` does not clone or execute anything.** It scores the repo from publicly-readable GitHub metadata + the recursive tree listing. This is the deliberate wedge against batch tools that try to actually rerun the paper.\n- **`fetch_paper_text` prefers ar5iv HTML over PDF parsing for arXiv papers.** Falls back to `pypdf` for non-arXiv inputs.\n- **The default model is `claude-sonnet-4-6`.** Override via `METHODS_MCP_MODEL` env var or per-call `model=` arg.\n- **`methods_repro_review` returns a self-describing response.** Every call sets a top-level `status` (`\"ok\"` / `\"partial\"` / `\"empty\"`) and a `narrative` string that summarises everything retrieved in plain English — including every numeric score in context. A reader who reads only `narrative` + `status` gets the full picture without needing to learn the sub-object shapes. Sub-objects can be `null` when unavailable (e.g. `repro_assessment: null` on a paper with no detected repo — `status` stays `\"ok\"` because \"no repo\" isn't a failure). Failed sub-steps contribute a structured entry to `errors` with `{step, error_type, message, hint}`, where `hint` is an actionable plain-English suggestion for recognised patterns (missing API keys, rate-limits, 404s, timeouts, etc.) and `null` otherwise.\n\n## Scores & verdicts explained\n\nTool outputs contain three numeric fields that look similar but mean very different things. They are **triage signals for an agent deciding whether a paper is worth digging into**, not calibrated claims about correctness.\n\n| Field | Range | How it's computed | How to read it |\n|---|---|---|---|\n| `methods.confidence` | 0–1 | **LLM self-report.** The extractor model sets it per instructions in the system prompt: `≥0.8` only if the paper gives explicit reagents/volumes/equipment, `~0.3` if the methods section is sparse. Uncalibrated. | Soft signal for *\"is this a wet-lab paper with concrete procedure, or a sparse systems paper?\"* Useful as a flag; don't treat as a trust percentage. |\n| `code_repo.confidence` | 0–1 | **Varies by `detection_method`.** `papers-with-code`: fixed `0.95` (authoritative paper→repo API). `paper-text`: computed as `0.6 + 0.2·(strong-phrase-present) + 0.015·score_margin`, capped at `0.95`. `abstract-link`: fixed `0.85`. `none`: `0.0`. | Tells you **how** the repo was found and how decisively. High score + `paper-text` means a strong phrase like *\"code is available at …\"* sat next to the URL. |\n| `repro_assessment.overall_score` | 0–1 | **Weighted sum of 8 binary signals**, all computed from the GitHub REST API (no clone, no execution): `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). Each present signal contributes its weight. | The only fully-deterministic score of the three. Still a heuristic, not a proof — a high score means the repo **looks** well-structured for reproduction. For actual validation see [Paper2Agent](https://arxiv.org/abs/2509.06917). |\n\n**Verdict buckets** (`repro_assessment.verdict`) are thresholds on `overall_score`:\n\n| Verdict | Score | Meaning |\n|---|---|---|\n| `likely-reproducible` | ≥ 0.70 | Most repro-friendly signals present. Worth trying to run. |\n| `partial` | ≥ 0.45 | Some infrastructure, likely gaps. Expect to fill in missing pieces. |\n| `unlikely` | ≥ 0.20 | Minimal signal. Possible code dump without the scaffolding to rerun it. |\n| `insufficient-info` | < 0.20 *or* repo unreachable | Not enough to tell. Don't draw conclusions either way. |\n\n**Enum values you'll see in outputs:**\n\n- `code_repo.detection_method`: `paper-text` | `abstract-link` | `papers-with-code` | `metadata` | `none`\n- `metadata.source`: `arxiv` | `biorxiv` | `doi` | `url` | `unknown`\n\n## Security & limitations\n\nWhat this server *actually* does when you install and run it:\n\n- **Network calls only to**: `export.arxiv.org`, `ar5iv.labs.arxiv.org`, `arxiv.org` (PDFs), `api.github.com`, `paperswithcode.com`, `api.anthropic.com`. No telemetry, no analytics, no phone-home.\n- **Reads** `ANTHROPIC_API_KEY` (required for LLM tools) and optionally `GITHUB_TOKEN` from environment variables. These are sent only to Anthropic / GitHub respectively. Never logged, never persisted to disk.\n- **Writes** nothing to your filesystem. No cache directories, no downloaded PDFs, no temp files.\n- **Executes** no user-supplied code. No `eval`, `exec`, `subprocess`, `pickle.loads`, or shell-outs. The reproducibility tool deliberately *does not* clone or run repositories — it scores from the GitHub REST API only.\n\n**Limitations to be aware of:**\n\n- **Adversarial papers may produce misleading structured output.** The `extract_methods` tool sends paper text to Claude. A paper containing prompt-injection content could yield wrong (but schema-valid) structured methods. Treat the output as a research aid, not ground truth.\n- **The reproducibility verdict is a heuristic, not a proof.** A high score means the repo *looks* well-structured for reproduction; it does not guarantee that running the code reproduces the paper. For full validation see [Paper2Agent](https://arxiv.org/abs/2509.06917).\n- **Intended for local stdio use.** The HTTP/SSE transports are provided for development convenience but should only be exposed on trusted networks (no SSRF protection beyond what httpx provides).\n\n**Reporting issues:**\n\nSecurity issues: please email flynnlachendro@hotmail.co.uk (also see [`SECURITY.md`](SECURITY.md)). Functional bugs: open a [GitHub issue](https://github.com/FlynnLachendro/methods-mcp/issues).\n\n## Pair with `paper-mcp`\n\nFor broader paper search / citation graph tooling, run [`paper-mcp` (Bhvaik)](https://pypi.org/project/paper-mcp/) alongside in the same Claude Code session. `paper-mcp` does title-keyed search, full-text fetch, citations, and references; `methods-mcp` adds the structured-methods + reproducibility layer on top. The two were intentionally designed to compose.\n\n## Develop locally\n\n```bash\ngit clone https://github.com/FlynnLachendro/methods-mcp\ncd methods-mcp\nuv sync --extra dev --extra agent\n\nuv run pytest                      # 49 tests, offline (respx-mocked httpx + unittest.mock for Anthropic)\nuv run ruff format .\nuv run ruff check . --fix\nuv run mypy src\n\nuv run methods-mcp --help\n```\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n\n## Acknowledgements\n\nBuilt for the [Worldwide AI Science Fellowship](https://www.aisciencesummit.com/) inaugural cohort. Thanks to Michael Raspuzzi for the open-ended brief.\n\nBuilt on:\n- [FastMCP 3.x](https://github.com/jlowin/fastmcp) — the MCP server scaffold.\n- [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) — the agent loop in the demo.\n- [ar5iv.labs.arxiv.org](https://ar5iv.labs.arxiv.org/) — clean HTML for arXiv papers.\n- [Anthropic Claude](https://platform.claude.com) — the LLM behind structured extraction.\n",
  "bytes": 13910,
  "sha": "52a57745635061279f09bf7459dbec7a2742d6c7c0ac7732e905c6680baf5167",
  "repo_slug": "flynnlachendro/methods-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_flynnlachendro_methods_mcp_7b5f6dc3/readme"
}