methods-mcp

Servidor MCP ligero y bajo demanda para extracción estructurada de métodos + heurísticas de reproducibilidad en artículos académicos. Construido para el reto de construcción de la Worldwide AI Science Fellowship.

⚠️ Estado: alpha (0.1.x). La superficie de herramientas y las formas de salida pueden cambiar entre versiones menores. Fija una versión exacta en producción. Los informes de errores son muy bienvenidos a través de GitHub Issues.

Demo rápida

$ 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 es un servidor Model Context Protocol pequeño y de alcance muy definido. Proporciona a cualquier agente de IA (Claude Code, Claude Desktop, tu script del Agent SDK, etc.) ocho herramientas que convierten la URL de un artículo académico en:

• metadatos canónicos,

• texto completo con mejor esfuerzo + división en secciones,

• un objeto de métodos estructurado validado con Pydantic (pasos / reactivos / equipos / análisis),

• el repositorio de código asociado al artículo (descubrimiento con mejor esfuerzo),

• un veredicto de reproducibilidad sin necesidad de ejecución para ese repositorio, y

• un resumen multimodo.

La cuña: pipelines de gran peso como Paper2Agent (Stanford) tardan de 30 minutos a horas en digerir un artículo en herramientas listas para agentes. methods-mcp es el complemento invocable por agentes y bajo demanda — cada herramienta devuelve resultados en segundos, sin clonar ni ejecutar.

Related MCP server: paperstack

Instalación

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

Claves de API

Para un mejor rendimiento, configura ambas:

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

Ninguna clave se registra ni se persiste; se envían únicamente a api.anthropic.com y api.github.com respectivamente. Consulta SECURITY.md.

Úsalo desde Claude Code

/mcp add methods-mcp methods-mcp

Luego, en cualquier chat de Claude Code:

Toma https://arxiv.org/abs/2509.06917 y ejecuta methods_repro_review. Resume qué hace el artículo, los pasos de los métodos y cuán reproducible parece el repositorio.

Úsalo desde el 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)

Herramientas

Todas las herramientas devuelven modelos Pydantic v2 (validados, serializables a JSON). Consulta src/methods_mcp/schemas.py para la superficie completa de tipos.

Notas de diseño

• extract_methods usa el uso de herramientas de Anthropic para forzar al modelo a emitir una instancia del esquema Pydantic MethodsStructured. Ante un fallo de validación, enviamos un mensaje de reparación con el error de validación y lo intentamos de nuevo antes de lanzar una excepción.

• assess_repo_reproducibility no clona ni ejecuta nada. Puntúa el repositorio a partir de metadatos de GitHub legibles públicamente + el listado recursivo del árbol. Esta es la cuña deliberada contra las herramientas por lotes que intentan reejecutar el artículo.

• fetch_paper_text prefiere HTML de ar5iv sobre el análisis de PDF para artículos de arXiv. Usa pypdf como respaldo para entradas que no son de arXiv.

• El modelo por defecto es claude-sonnet-4-6. Se puede sobrescribir con la variable de entorno METHODS_MCP_MODEL o con el argumento model= por llamada.

• methods_repro_review devuelve una respuesta autodescriptiva. Cada llamada establece un status de nivel superior ("ok" / "partial" / "empty") y una cadena narrative que resume todo lo recuperado en inglés sencillo, incluida cada puntuación numérica en contexto. Un lector que lea solo narrative + status obtiene la imagen completa sin necesidad de aprender las formas de los subobjetos. Los subobjetos pueden ser null cuando no están disponibles (por ejemplo, repro_assessment: null en un artículo sin repositorio detectado — status permanece "ok" porque "no hay repositorio" no es un fallo). Los subpasos fallidos contribuyen con una entrada estructurada a errors con {step, error_type, message, hint}, donde hint es una sugerencia accionable en inglés sencillo para patrones reconocidos (claves de API faltantes, límites de tasa, 404, tiempos de espera, etc.) y null en caso contrario.

Puntuaciones y veredictos explicados

Las salidas de las herramientas contienen tres campos numéricos que parecen similares pero significan cosas muy diferentes. Son señales de triaje para un agente que decide si vale la pena profundizar en un artículo, no afirmaciones calibradas sobre corrección.

Categorías de veredicto (repro_assessment.verdict) son umbrales sobre overall_score:

Valores de enumeración que verás en las salidas:

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

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

Seguridad y limitaciones

Lo que este servidor realmente hace cuando lo instalas y ejecutas:

• Llamadas de red solo a: export.arxiv.org, ar5iv.labs.arxiv.org, arxiv.org (PDFs), api.github.com, paperswithcode.com, api.anthropic.com. Sin telemetría, sin análisis, sin llamadas a casa.

• Lee ANTHROPIC_API_KEY (necesaria para las herramientas LLM) y opcionalmente GITHUB_TOKEN de las variables de entorno. Estos se envían solo a Anthropic / GitHub respectivamente. Nunca se registran ni se persisten en disco.

• Escribe nada en tu sistema de archivos. Sin directorios de caché, sin PDFs descargados, sin archivos temporales.

• Ejecuta ningún código proporcionado por el usuario. Sin eval, exec, subprocess, pickle.loads ni llamadas al shell. La herramienta de reproducibilidad deliberadamente no clona ni ejecuta repositorios: solo puntúa desde la API REST de GitHub.

Limitaciones a tener en cuenta:

• Los artículos adversarios pueden producir salida estructurada engañosa. La herramienta extract_methods envía el texto del artículo a Claude. Un artículo que contenga contenido de inyección de prompts podría producir métodos estructurados incorrectos (pero válidos según el esquema). Trata la salida como una ayuda de investigación, no como una verdad absoluta.

• El veredicto de reproducibilidad es una heurística, no una prueba. Una puntuación alta significa que el repositorio parece bien estructurado para la reproducción; no garantiza que ejecutar el código reproduzca el artículo. Para una validación completa, consulta Paper2Agent.

• Diseñado para uso local con stdio. Los transportes HTTP/SSE se proporcionan por conveniencia de desarrollo, pero solo deben exponerse en redes de confianza (sin protección SSRF más allá de la que proporciona httpx).

Informe de problemas:

Problemas de seguridad: envía un correo a flynnlachendro@hotmail.co.uk (consulta también SECURITY.md). Errores funcionales: abre un issue en GitHub.

Combínalo con paper-mcp

Para un conjunto de herramientas más amplio de búsqueda de artículos / grafo de citas, ejecuta paper-mcp (Bhvaik) junto con el mismo en la misma sesión de Claude Code. paper-mcp realiza búsqueda por título, obtención de texto completo, citas y referencias; methods-mcp añade la capa de métodos estructurados + reproducibilidad encima. Los dos fueron diseñados intencionalmente para componerse.

Desarrollo local

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

Licencia

MIT — consulta LICENSE.

Agradecimientos

Construido para la cohorte inaugural de la Worldwide AI Science Fellowship. Gracias a Michael Raspuzzi por el encargo abierto.

Construido sobre:

• FastMCP 3.x — el andamiaje del servidor MCP.

• Claude Agent SDK — el bucle de agente en la demo.

• ar5iv.labs.arxiv.org — HTML limpio para artículos de arXiv.

• Anthropic Claude — el LLM detrás de la extracción estructurada.