methods-mcp

Leichtgewichtiger, bedarfsorientierter MCP-Server für strukturierte Methodenextraktion + Reproduzierbarkeits-Heuristiken bei wissenschaftlichen Arbeiten. Gebaut für die Worldwide AI Science Fellowship Build Challenge.

⚠️ Status: Alpha (0.1.x). Die Tool-Oberfläche und die Ausgabeformen können sich zwischen Minor-Versionen ändern. In Produktion auf eine exakte Version pinnen. Bug-Meldungen sind über GitHub Issues sehr willkommen.

Kurzdemo

$ 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 ist ein kleiner, klar abgegrenzter Model Context Protocol-Server. Er gibt jedem KI-Agenten (Claude Code, Claude Desktop, dein Agent-SDK-Skript usw.) acht Tools, die eine URL einer wissenschaftlichen Arbeit in Folgendes verwandeln:

• kanonische Metadaten,

• Volltext mit bestmöglicher Qualität + Abschnittsaufteilung,

• ein Pydantic-validiertes, strukturiertes Methodenobjekt (Schritte / Reagenzien / Ausrüstung / Analysen),

• das zugehörige Code-Repository der Arbeit (bestmögliche Erkennung),

• ein ohne Ausführung auskommendes Reproduzierbarkeits-Urteil für dieses Repository, und

• eine Zusammenfassung in mehreren Modi.

Der Hebel: Schwergewichtige Pipelines wie Paper2Agent (Stanford) brauchen 30 Minuten bis Stunden, um eine Arbeit in agentenbereite Tools zu verdauen. methods-mcp ist die agentenaufrufbare, bedarfsorientierte Ergänzung — jedes Tool liefert in Sekunden Ergebnisse, ohne Klonen, ohne Ausführung.

Related MCP server: paperstack

Installation

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

API-Schlüssel

Für beste Leistung beide setzen:

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

Keiner der Schlüssel wird protokolliert oder gespeichert — sie werden nur an api.anthropic.com bzw. api.github.com gesendet. Siehe SECURITY.md.

Verwendung mit Claude Code

/mcp add methods-mcp methods-mcp

Dann in einem beliebigen Claude-Code-Chat:

Nimm https://arxiv.org/abs/2509.06917 und führe methods_repro_review aus. Fasse zusammen, was die Arbeit tut, die Methodenschritte und wie reproduzierbar das Repository aussieht.

Verwendung mit dem 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)

Tools

Alle Tools geben Pydantic-v2-Modelle zurück (validiert, JSON-serialisierbar). Siehe src/methods_mcp/schemas.py für die vollständige Typschnittstelle.

Design-Anmerkungen

• extract_methods verwendet Anthropic-Tool-Use, um das Modell dazu zu bringen, eine Instanz des MethodsStructured-Pydantic-Schemas auszugeben. Bei Validierungsfehlern senden wir eine Reparaturnachricht mit dem Validierungsfehler und versuchen es erneut, bevor wir eine Ausnahme auslösen.

• assess_repo_reproducibility klont oder führt nichts aus. Es bewertet das Repository anhand öffentlich lesbarer GitHub-Metadaten + der rekursiven Baumauflistung. Das ist der bewusste Hebel gegen Batch-Tools, die versuchen, die Arbeit tatsächlich erneut auszuführen.

• fetch_paper_text bevorzugt ar5iv-HTML gegenüber PDF-Parsing für arXiv-Arbeiten. Fällt für Nicht-arXiv-Eingaben auf pypdf zurück.

• Das Standardmodell ist claude-sonnet-4-6. Überschreibbar über die Umgebungsvariable METHODS_MCP_MODEL oder das model=-Argument pro Aufruf.

• methods_repro_review gibt eine selbstbeschreibende Antwort zurück. Jeder Aufruf setzt einen status auf oberster Ebene ("ok" / "partial" / "empty") und einen narrative-String, der alles Abgerufene in einfachem Englisch zusammenfasst — einschließlich jedes numerischen Scores im Kontext. Ein Leser, der nur narrative + status liest, erhält das vollständige Bild, ohne die Formen der Unterobjekte lernen zu müssen. Unterobjekte können null sein, wenn nicht verfügbar (z. B. repro_assessment: null bei einer Arbeit ohne erkanntes Repository — status bleibt "ok", weil „kein Repository“ kein Fehler ist). Fehlgeschlagene Teilschritte tragen einen strukturierten Eintrag zu errors bei mit {step, error_type, message, hint}, wobei hint ein umsetzbarer Vorschlag in einfachem Englisch für erkannte Muster ist (fehlende API-Schlüssel, Ratenlimits, 404s, Timeouts usw.) und sonst null.

Scores & Urteile erklärt

Tool-Ausgaben enthalten drei numerische Felder, die ähnlich aussehen, aber sehr unterschiedliche Bedeutungen haben. Sie sind Triage-Signale für einen Agenten, der entscheidet, ob sich eine Arbeit lohnt, keine kalibrierten Aussagen über Korrektheit.

Urteils-Kategorien (repro_assessment.verdict) sind Schwellenwerte auf overall_score:

| Urteil | Punktzahl | Bedeutung | | likely-reproducible | ≥ 0.70 | Die meisten reproduktionsfreundlichen Signale sind vorhanden. Es lohnt sich, einen Versuch zu starten. | | partial | ≥ 0.45 | Einige Infrastruktur vorhanden, wahrscheinlich Lücken. Erwarten Sie, fehlende Teile zu ergänzen. | | unlikely | ≥ 0.20 | Minimale Signale. Möglicherweise ein Code-Dump ohne das Gerüst, um ihn erneut auszuführen. | | insufficient-info | < 0.20 oder Repository nicht erreichbar | Nicht genug, um es zu beurteilen. Ziehen Sie keine Schlüsse in die eine oder andere Richtung. |

Enum-Werte, die Sie in den Ausgaben sehen werden:

• code_repo.detection_method: paper-text | abstract-link | papers-with-code | metadata | none

• metadata.source: arxiv | biorxiv | doi | url | unknown

Sicherheit & Einschränkungen

Was dieser Server tatsächlich tut, wenn Sie ihn installieren und ausführen:

• Netzwerkaufrufe nur an: export.arxiv.org, ar5iv.labs.arxiv.org, arxiv.org (PDFs), api.github.com, paperswithcode.com, api.anthropic.com. Keine Telemetrie, keine Analysen, kein Phone-Home.

• Liest ANTHROPIC_API_KEY (erforderlich für LLM-Tools) und optional GITHUB_TOKEN aus Umgebungsvariablen. Diese werden nur an Anthropic bzw. GitHub gesendet. Nie protokolliert, nie auf der Festplatte gespeichert.

• Schreibt nichts in Ihr Dateisystem. Keine Cache-Verzeichnisse, keine heruntergeladenen PDFs, keine temporären Dateien.

• Führt keinen vom Benutzer bereitgestellten Code aus. Kein eval, exec, subprocess, pickle.loads oder Shell-Aufrufe. Das Reproduzierbarkeits-Tool klont oder führt bewusst keine Repositories aus – es bewertet nur über die GitHub-REST-API.

Einschränkungen, die Sie beachten sollten:

• Adversariale Papiere können irreführende strukturierte Ausgaben erzeugen. Das extract_methods-Tool sendet den Papiertext an Claude. Ein Papier mit Prompt-Injection-Inhalten könnte falsche (aber schema-konforme) strukturierte Methoden liefern. Behandeln Sie die Ausgabe als Forschungshilfe, nicht als Grundwahrheit.

• Das Reproduzierbarkeitsurteil ist eine Heuristik, kein Beweis. Ein hoher Wert bedeutet, dass das Repository gut strukturiert für die Reproduktion aussieht; es garantiert nicht, dass die Ausführung des Codes das Papier reproduziert. Für eine vollständige Validierung siehe Paper2Agent.

• Für die lokale stdio-Nutzung gedacht. Die HTTP/SSE-Transports werden für die Entwicklung bereitgestellt, sollten aber nur in vertrauenswürdigen Netzwerken exponiert werden (kein SSRF-Schutz über das hinaus, was httpx bietet).

Probleme melden:

Sicherheitsprobleme: Bitte senden Sie eine E-Mail an flynnlachendro@hotmail.co.uk (siehe auch SECURITY.md). Funktionale Fehler: Eröffnen Sie ein GitHub-Issue.

Kombinieren mit paper-mcp

Für eine breitere Papiersuche / Zitationsgraph-Tooling führen Sie paper-mcp (Bhvaik) in derselben Claude Code-Sitzung aus. paper-mcp bietet titelbasierte Suche, Volltextabruf, Zitationen und Referenzen; methods-mcp fügt die strukturierte Methoden- und Reproduzierbarkeitsebene hinzu. Die beiden wurden absichtlich so konzipiert, dass sie sich ergänzen.

Lokal entwickeln

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

Lizenz

MIT — siehe LICENSE.

Danksagungen

Entwickelt für die erste Kohorte des Worldwide AI Science Fellowship. Dank an Michael Raspuzzi für das offene Briefing.

Basierend auf:

• FastMCP 3.x — das MCP-Server-Gerüst.

• Claude Agent SDK — die Agentenschleife in der Demo.

• ar5iv.labs.arxiv.org — sauberes HTML für arXiv-Papiere.

• Anthropic Claude — das LLM hinter der strukturierten Extraktion.