methods-mcp

Легковесный MCP-сервер по требованию для структурированного извлечения методов + эвристик воспроизводимости для академических статей. Создан для челленджа Worldwide AI Science Fellowship.

⚠️ Статус: alpha (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. Он предоставляет любому ИИ-агенту (Claude Code, Claude Desktop, вашему скрипту Agent SDK и т.д.) восемь инструментов, которые превращают URL академической статьи в:

• канонические метаданные,

• полный текст с разбивкой по секциям (best-effort),

• структурированный объект методов, проверенный Pydantic (шаги / реагенты / оборудование / анализы),

• репозиторий кода статьи (обнаружение best-effort),

• вердикт о воспроизводимости без выполнения для этого репозитория,

• сводку в нескольких режимах.

Ключевая идея: тяжёлые пайплайны, такие как Paper2Agent (Stanford), тратят от 30 минут до часов на переработку статьи в готовые к использованию инструменты. methods-mcp — это вызываемый агентом, по требованию комплемент — каждый инструмент возвращает результат за секунды, без клонирования и выполнения.

Related MCP server: paperstack

Установка

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

Ключи API

Для лучшей производительности установите оба:

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

Возьмите 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)

Инструменты

Все инструменты возвращают модели Pydantic v2 (проверенные, сериализуемые в JSON). Полный список типов см. в src/methods_mcp/schemas.py.

Заметки по дизайну

• extract_methods использует tool-use от Anthropic, чтобы заставить модель выдать экземпляр Pydantic-схемы MethodsStructured. При ошибке валидации мы отправляем одно сообщение с ошибкой валидации и пробуем снова перед тем, как поднять исключение.

• assess_repo_reproducibility не клонирует и не выполняет ничего. Он оценивает репозиторий по публично читаемым метаданным GitHub + рекурсивному дереву файлов. Это осознанный компромисс против пакетных инструментов, которые пытаются реально перезапустить статью.

• fetch_paper_text предпочитает ar5iv HTML парсингу PDF для arXiv-статей. Для не-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", потому что "нет репозитория" — не ошибка). Неудачные под-шаги добавляют структурированную запись в errors с {step, error_type, message, hint}, где hint — это практическая подсказка на простом английском для распознанных паттернов (отсутствующие ключи API, лимиты скорости, 404, таймауты и т.д.), и null в противном случае.

Объяснение оценок и вердиктов

Выводы инструментов содержат три числовых поля, которые выглядят похоже, но означают очень разные вещи. Это сигналы для триажа, помогающие агенту решить, стоит ли копать глубже в статью, а не калиброванные утверждения о корректности.

Вердиктные корзины (repro_assessment.verdict) — это пороги на overall_score:

Значения перечислений, которые вы увидите в выводах:

• 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. Статья с контентом для prompt-инъекций может дать неверные (но валидные по схеме) структурированные методы. Относитесь к выводу как к вспомогательному средству исследования, а не к истине в последней инстанции.

• Вердикт о воспроизводимости — это эвристика, а не доказательство. Высокий балл означает, что репозиторий выглядит хорошо структурированным для воспроизведения; это не гарантирует, что запуск кода воспроизведёт статью. Для полной валидации см. Paper2Agent.

• Предназначен для локального использования через stdio. HTTP/SSE-транспорты предоставлены для удобства разработки, но должны быть доступны только в доверенных сетях (нет защиты от SSRF сверх того, что предоставляет httpx).

Сообщение о проблемах:

Проблемы безопасности: пожалуйста, напишите на flynnlachendro@hotmail.co.uk (также см. SECURITY.md). Функциональные ошибки: откройте issue на GitHub.

Совместное использование с paper-mcp

Для более широкого поиска статей / инструментов графа цитирования запустите paper-mcp (Bhvaik) в той же сессии Claude Code. paper-mcp выполняет поиск по заголовкам, получение полных текстов, цитаты и ссылки; methods-mcp добавляет поверх слой структурированных методов + воспроизводимости. Эти два инструмента намеренно спроектированы для совместной работы.

Локальная разработка

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. Спасибо Michael Raspuzzi за свободное техническое задание.

Построено на основе:

• FastMCP 3.x — каркас MCP-сервера.

• Claude Agent SDK — агентский цикл в демо.

• ar5iv.labs.arxiv.org — чистый HTML для статей arXiv.

• Anthropic Claude — LLM, стоящая за структурированным извлечением.