methods-mcp 0.1.0__tar.gz

methods_mcp-0.1.0/.claude/napkin.md

@@ -0,0 +1,96 @@
+# WWSF Challenge Napkin
+
+Living doc for the Worldwide AI Science Fellowship (WWSF) Build Challenge — Flynn's tryout for the inaugural AI for Science fellowship (cohort runs Apr 15 → Jul 15, 2026).
+
+---
+
+## The Ask (one-screen)
+
+**Challenge:** Build something new in a week using the latest AI tools. Ship a real demo. Share it in public.
+
+**Deliverables (submit by email to Michael Raspuzzi):**
+1. Build-in-public post on socials (X / LinkedIn / YouTube — long or short form, Flynn's choice)
+2. Public GitHub link (code + docs)
+3. 2–3 min Loom walking through process and links
+
+**What they're grading on:**
+1. Real demo — does it actually work
+2. Try new things — reaching into unfamiliar tools / hardware / territory
+3. Process + narration — how Flynn thinks and explains it
+
+**Deadline:** 2026-04-20, 11:59 PT (received Apr 14 ~00:44 PT, so effectively 6.5 days)
+**Time budget:** ≥6 hrs recommended, average fellowship cadence is 8–10 hrs/wk
+
+**Response owed:** reply "Challenge accepted." to lock it in.
+
+## Example prompts they floated
+- OpenClaw agent on a Digital Ocean droplet ($12) + dashboard or LabClaw literature review
+- Claude Code designing a robotic protocol (Opentrons Flex sim)
+- Arduino/ESP32 + sensor (temp, pH, turbidity) → MQTT/serial → live dashboard with threshold alerts
+- Fork OpenSCAD/STEP file from Open Labware, parametrically modify, render, publish
+
+(These are illustrative, not prescriptive — "figure it out" is the vibe.)
+
+## Flynn's edge — use this
+- **Dr. Flynn Lachendro, PhD in Biomedical Engineering.** This is literally "AI for Science" — lean into the science side, not just the engineering side.
+- Already ships AI products fast (Arbor = research workbench; Lattice = AI research intel dashboard; Layers = pop-sci mobile; Model Collapse = prompt-engineering roguelike).
+- Strongest stack: **Python + FastAPI + SQLAlchemy async + Pydantic + React/Next + TS**. Uses Anthropic / OpenAI / Gemini / OpenRouter regularly.
+- Background in research pipelines (arXiv, Semantic Scholar, paper summarization, ingestion crons) → natural fit for LabClaw-style science agents.
+
+## What "try new things" means here
+To avoid this being "Flynn ships another web app," reach into at least one of:
+- Real lab hardware / simulators (Opentrons Flex sim, OpenClaw, OT-2 protocol API)
+- Physical-world I/O (ESP32 / Arduino / Pi, sensors, MQTT)
+- Agentic lab workflows (LabClaw skills, MCP servers for scientific tooling)
+- Parametric CAD / Open Labware (OpenSCAD, STEP manipulation)
+- World models or VLA (video-language-action) perception
+
+---
+
+## Flynn Preferences (general, durable)
+
+**Identity**
+- Dr. Flynn Lachendro — PhD Biomedical Engineering, AI engineer/researcher, Founding Engineer at Nur Opus (Prism). Faculty / OpenKit background. Focus: multi-agent systems, LLM eval, AI safety.
+
+**Collaboration style**
+- **Always wait for explicit go-ahead** before git commit/push, PRs, or any irreversible action. "Should I do X?" ≠ "do X."
+- No destructive-first instincts. `rm -rf`, recreating environments, `--no-verify` — only as last resort, after alternatives fail.
+- No legacy wrappers / backwards-compat shims for internal refactors. Update call sites directly.
+- Commit messages: short, single-line. No `Co-Authored-By`, no multi-paragraph bodies.
+
+**Explanation style (two modes)**
+- **Flynn style:** super concise, 2 ways to explain, simple analogies, minimal code, get the knack across. Used when Flynn says "explain Flynn style."
+- **Claude style:** full clean written explanation in the response, then call the `say_tts` MCP (default voice) to read it aloud. Used when Flynn says "explain Claude style" or "read out Claude style."
+
+**Package / tooling**
+- `uv` for all Python. Avoid venvs.
+- `ruff format .` → `ruff check . --fix` → `mypy <pkg>` → `pytest -v` is the "Linting, Typing and Checking" sequence.
+- Stack defaults: FastAPI + SQLAlchemy 2.0 async + Pydantic + loguru (BE). Next.js + React + TS + Tailwind (web). Expo + RN + Reanimated (mobile). Supabase (auth + Postgres). Vercel (FE) + Railway (BE).
+
+**Code snippets**
+- When showing DB models / architectural primitives: full type annotations, both sides of relationships, `__tablename__` included. No pseudocode for real DB models.
+
+**Root-markdown refresh**
+- When Flynn says "refresh the root markdowns": review root `.md`s against current code, surgical updates (preserve style/tone), don't create new ones, report what changed.
+
+**Granola**
+- "Look through my Granola" → read `~/Library/Application Support/Granola/cache-v6.json`. `cache.state.documents` = meetings, `cache.state.transcripts` = full text keyed by doc ID.
+
+---
+
+## Build Log
+*(fill in as we go — what was tried, what worked, what got cut, links to commits / tweets / Loom)*
+
+- 2026-04-14 — Challenge received. Napkin set up. Planning session in progress.
+- 2026-04-14 — Plan locked: build a FastMCP server primitive, demo via Claude Code live, audience = AI-for-science community (cross-domain).
+- 2026-04-14 — Pivot: `paper-mcp` already exists on PyPI (Bhvaik). Paper2Agent (Stanford) does batch methods+repro. **Wedge: lightweight, on-demand, real-time MCP for methods extraction + reproducibility *heuristics*** — no full re-execution required. Package name: **`methods-mcp`**.
+
+## Open Questions / Decisions
+*(TBD after the plan-mode interview)*
+
+## Submission Checklist
+- [ ] Reply "Challenge accepted." to Michael Raspuzzi
+- [ ] GitHub repo public with README / process docs
+- [ ] Build-in-public post drafted + posted (X / LinkedIn / YouTube)
+- [ ] 2–3 min Loom recorded + link ready
+- [ ] Submission email sent to Michael by **2026-04-20 23:59 PT**

methods_mcp-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:labclaw-ai.github.io)",
+      "WebFetch(domain:docs.opentrons.com)",
+      "WebFetch(domain:gofastmcp.com)",
+      "WebFetch(domain:pypi.org)"
+    ]
+  }
+}

methods_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra agent --python ${{ matrix.python-version }}
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Mypy
+        run: uv run mypy src
+
+      - name: Pytest
+        run: uv run pytest tests -v

methods_mcp-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+build/
+dist/
+wheels/
+.venv/
+venv/
+env/
+
+# uv
+uv.lock.bak
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+*.pem
+
+# Project-specific
+fixtures_cache/
+*.local.md

methods_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

methods_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0 — 2026-04-14
+
+Initial release. Built for the Worldwide AI Science Fellowship build challenge.
+
+### Tools shipped
+
+- `health` — server liveness / config check
+- `get_paper_metadata` — URL/ID/DOI → canonical metadata
+- `fetch_paper_text` — ar5iv HTML primary, pypdf fallback
+- `extract_methods` — LLM + Pydantic structured methods
+- `find_code_repo` — paper-text → abstract → Papers With Code
+- `assess_repo_reproducibility` — heuristic, no-clone, GitHub REST API
+- `summarize_paper` — three modes (abstract / tldr / exec)
+- `methods_repro_review` — composite tool
+
+### Notes
+
+- Default model: `claude-sonnet-4-6` (override with `METHODS_MCP_MODEL` env var).
+- All tool returns are Pydantic v2 models.
+- 29 offline tests via respx mocks, mypy strict, ruff lint clean.

methods_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flynn Lachendro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

methods_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: methods-mcp
+Version: 0.1.0
+Summary: Lightweight, on-demand MCP server for structured methods extraction and reproducibility heuristics on academic papers.
+Project-URL: Homepage, https://github.com/FlynnLachendro/methods-mcp
+Project-URL: Repository, https://github.com/FlynnLachendro/methods-mcp
+Project-URL: Issues, https://github.com/FlynnLachendro/methods-mcp/issues
+Author-email: Flynn Lachendro <flynnlachendro@hotmail.co.uk>
+Maintainer-email: Flynn Lachendro <flynnlachendro@hotmail.co.uk>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: academic-papers,ai-for-science,anthropic,claude,fastmcp,mcp,model-context-protocol,reproducibility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: selectolax>=0.3.20
+Provides-Extra: agent
+Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'agent'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# methods-mcp
+
+[![PyPI](https://img.shields.io/pypi/v/methods-mcp.svg)](https://pypi.org/project/methods-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/methods-mcp.svg)](https://pypi.org/project/methods-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> 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.
+
+`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:
+
+- canonical metadata,
+- best-effort full text + section split,
+- a **Pydantic-validated structured methods object** (steps / reagents / equipment / analyses),
+- the paper's associated **code repository** (best-effort discovery),
+- a **no-execution-required reproducibility verdict** for that repo, and
+- a multi-mode summary.
+
+The 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.
+
+---
+
+## Install
+
+```bash
+uv add methods-mcp
+# or, install globally:
+uv tool install methods-mcp
+# or, classic pip:
+pip install methods-mcp
+```
+
+Set your Anthropic API key (used by the LLM-driven extraction tools):
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# Optional — raises GitHub REST API rate limit for repro assessment:
+export GITHUB_TOKEN=ghp_...
+```
+
+## Use it from Claude Code
+
+```
+/mcp add methods-mcp methods-mcp
+```
+
+Then in any Claude Code chat:
+
+> 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.
+
+See [`examples/claude_code_demo.md`](examples/claude_code_demo.md) for more session prompts.
+
+## Use it from the Claude Agent SDK
+
+```python
+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)
+```
+
+A complete runnable example lives in [`examples/reflexive_demo.py`](examples/reflexive_demo.py).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `health` | Server liveness + config check. |
+| `get_paper_metadata(input_str)` | Resolve URL / arXiv ID / DOI to canonical metadata. arXiv inputs hit the arXiv export API for title/authors/abstract. |
+| `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. |
+| `extract_methods(input_str, model=None)` | LLM-driven, Pydantic-validated structured methods extraction. Returns `{steps, reagents, equipment, analyses, confidence}`. |
+| `find_code_repo(input_str)` | Discover the paper's code repo via paper text → abstract → Papers With Code. |
+| `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}`. |
+| `summarize_paper(input_str, mode="tldr"\|"abstract"\|"exec")` | LLM summary in three depths. |
+| `methods_repro_review(input_str)` | Composite — metadata + methods + repo + repro in one call. |
+
+All tools return Pydantic v2 models (validated, JSON-serialisable). See [`src/methods_mcp/schemas.py`](src/methods_mcp/schemas.py) for the full type surface.
+
+## Design notes
+
+- **`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.
+- **`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.
+- **`fetch_paper_text` prefers ar5iv HTML over PDF parsing for arXiv papers.** Falls back to `pypdf` for non-arXiv inputs.
+- **The default model is `claude-sonnet-4-6`.** Override via `METHODS_MCP_MODEL` env var or per-call `model=` arg.
+
+## Pair with `paper-mcp`
+
+For 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.
+
+## Develop locally
+
+```bash
+git clone https://github.com/FlynnLachendro/methods-mcp
+cd methods-mcp
+uv sync --extra dev --extra agent
+
+uv run pytest                      # 29 tests, offline
+uv run ruff format .
+uv run ruff check . --fix
+uv run mypy src
+
+uv run methods-mcp --help
+```
+
+## Project notes
+
+`project-thoughts.md` (in this repo) is a running log of what we tried, what stuck, and what we cut while building this. Honest write-up for the WWSF Loom narration.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Acknowledgements
+
+Built for the [Worldwide AI Science Fellowship](https://www.aisciencesummit.com/) inaugural cohort. Thanks to Michael Raspuzzi for the open-ended brief.
+
+Built on:
+- [FastMCP 3.x](https://github.com/jlowin/fastmcp) — the MCP server scaffold.
+- [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) — the agent loop in the demo.
+- [ar5iv.labs.arxiv.org](https://ar5iv.labs.arxiv.org/) — clean HTML for arXiv papers.
+- [Anthropic Claude](https://platform.claude.com) — the LLM behind structured extraction.

methods_mcp-0.1.0/README.md

@@ -0,0 +1,136 @@
+# methods-mcp
+
+[![PyPI](https://img.shields.io/pypi/v/methods-mcp.svg)](https://pypi.org/project/methods-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/methods-mcp.svg)](https://pypi.org/project/methods-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> 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.
+
+`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:
+
+- canonical metadata,
+- best-effort full text + section split,
+- a **Pydantic-validated structured methods object** (steps / reagents / equipment / analyses),
+- the paper's associated **code repository** (best-effort discovery),
+- a **no-execution-required reproducibility verdict** for that repo, and
+- a multi-mode summary.
+
+The 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.
+
+---
+
+## Install
+
+```bash
+uv add methods-mcp
+# or, install globally:
+uv tool install methods-mcp
+# or, classic pip:
+pip install methods-mcp
+```
+
+Set your Anthropic API key (used by the LLM-driven extraction tools):
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# Optional — raises GitHub REST API rate limit for repro assessment:
+export GITHUB_TOKEN=ghp_...
+```
+
+## Use it from Claude Code
+
+```
+/mcp add methods-mcp methods-mcp
+```
+
+Then in any Claude Code chat:
+
+> 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.
+
+See [`examples/claude_code_demo.md`](examples/claude_code_demo.md) for more session prompts.
+
+## Use it from the Claude Agent SDK
+
+```python
+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)
+```
+
+A complete runnable example lives in [`examples/reflexive_demo.py`](examples/reflexive_demo.py).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `health` | Server liveness + config check. |
+| `get_paper_metadata(input_str)` | Resolve URL / arXiv ID / DOI to canonical metadata. arXiv inputs hit the arXiv export API for title/authors/abstract. |
+| `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. |
+| `extract_methods(input_str, model=None)` | LLM-driven, Pydantic-validated structured methods extraction. Returns `{steps, reagents, equipment, analyses, confidence}`. |
+| `find_code_repo(input_str)` | Discover the paper's code repo via paper text → abstract → Papers With Code. |
+| `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}`. |
+| `summarize_paper(input_str, mode="tldr"\|"abstract"\|"exec")` | LLM summary in three depths. |
+| `methods_repro_review(input_str)` | Composite — metadata + methods + repo + repro in one call. |
+
+All tools return Pydantic v2 models (validated, JSON-serialisable). See [`src/methods_mcp/schemas.py`](src/methods_mcp/schemas.py) for the full type surface.
+
+## Design notes
+
+- **`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.
+- **`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.
+- **`fetch_paper_text` prefers ar5iv HTML over PDF parsing for arXiv papers.** Falls back to `pypdf` for non-arXiv inputs.
+- **The default model is `claude-sonnet-4-6`.** Override via `METHODS_MCP_MODEL` env var or per-call `model=` arg.
+
+## Pair with `paper-mcp`
+
+For 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.
+
+## Develop locally
+
+```bash
+git clone https://github.com/FlynnLachendro/methods-mcp
+cd methods-mcp
+uv sync --extra dev --extra agent
+
+uv run pytest                      # 29 tests, offline
+uv run ruff format .
+uv run ruff check . --fix
+uv run mypy src
+
+uv run methods-mcp --help
+```
+
+## Project notes
+
+`project-thoughts.md` (in this repo) is a running log of what we tried, what stuck, and what we cut while building this. Honest write-up for the WWSF Loom narration.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Acknowledgements
+
+Built for the [Worldwide AI Science Fellowship](https://www.aisciencesummit.com/) inaugural cohort. Thanks to Michael Raspuzzi for the open-ended brief.
+
+Built on:
+- [FastMCP 3.x](https://github.com/jlowin/fastmcp) — the MCP server scaffold.
+- [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) — the agent loop in the demo.
+- [ar5iv.labs.arxiv.org](https://ar5iv.labs.arxiv.org/) — clean HTML for arXiv papers.
+- [Anthropic Claude](https://platform.claude.com) — the LLM behind structured extraction.

methods_mcp-0.1.0/examples/claude_code_demo.md

@@ -0,0 +1,54 @@
+# Using methods-mcp from Claude Code
+
+This is the path the WWSF Loom demos: install the server, point Claude Code at it, ask a science question.
+
+## 1. Install
+
+```bash
+uv add methods-mcp                # in any uv-managed project
+# or globally:
+uv tool install methods-mcp
+```
+
+## 2. Tell Claude Code about the server
+
+In a Claude Code session:
+
+```
+/mcp add methods-mcp methods-mcp
+```
+
+(Form: `/mcp add <name> <command>`. The second `methods-mcp` is the console-script binary, which lives on your PATH after `uv tool install` or inside any project that ran `uv add methods-mcp` + `uv sync`.)
+
+Set your Anthropic key (used for the LLM-driven extraction tools):
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# Optional, raises GitHub API rate limit for repro assessment:
+export GITHUB_TOKEN=ghp_...
+```
+
+## 3. Ask Claude Code a question that uses the tools
+
+Try one of these:
+
+> 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.
+
+> Compare the reproducibility of the code repos for these three papers: <url1>, <url2>, <url3>. Which has the strongest reproducibility signals?
+
+> Pull the structured methods from this protocol paper [URL] and turn it into a checklist I could hand to a colleague.
+
+Watch the tool calls fire in the Claude Code panel — that's the demo.
+
+## 4. Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `health` | Liveness + config check. |
+| `get_paper_metadata` | Resolve URL/ID/DOI to canonical metadata. |
+| `fetch_paper_text` | Best-effort full text + section split. |
+| `extract_methods` | LLM + Pydantic structured methods extraction. |
+| `find_code_repo` | Discover the paper's GitHub repo. |
+| `assess_repo_reproducibility` | No-clone heuristic repro assessment. |
+| `summarize_paper` | Three modes: abstract / tldr / exec. |
+| `methods_repro_review` | Composite: metadata + methods + repo + repro in one call. |