methods-mcp

학술 논문을 위한 구조화된 방법 추출 및 재현성 휴리스틱을 제공하는 가볍고 온디맨드 방식의 MCP 서버입니다. Worldwide AI Science Fellowship 빌드 챌린지를 위해 제작되었습니다.

⚠️ 상태: 알파(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 서버입니다. 모든 AI 에이전트(Claude Code, Claude Desktop, Agent SDK 스크립트 등)에게 학술 논문 URL을 다음으로 변환하는 여덟 가지 도구를 제공합니다:

• 정식 메타데이터,

• 최선의 전체 텍스트 + 섹션 분할,

• Pydantic으로 검증된 구조화된 방법 객체 (단계 / 시약 / 장비 / 분석),

• 논문과 연관된 코드 저장소 (최선의 탐색),

• 해당 저장소에 대한 실행 불필요 재현성 판정, 그리고

• 다중 모드 요약.

핵심 차별점: 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

그런 다음 Claude Code 채팅에서:

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는 Anthropic 도구 사용을 통해 모델이 MethodsStructured Pydantic 스키마의 인스턴스를 출력하도록 강제합니다. 검증 실패 시 검증 오류가 포함된 수리 메시지를 한 번 보내고 다시 시도한 후 오류를 발생시킵니다.

• assess_repo_reproducibility는 클론하거나 실행하지 않습니다. 공개적으로 읽을 수 있는 GitHub 메타데이터와 재귀적 트리 목록을 기반으로 저장소를 점수화합니다. 이는 실제로 논문을 재실행하려는 배치 도구에 대한 의도적인 차별점입니다.

• fetch_paper_text는 arXiv 논문의 경우 PDF 파싱보다 ar5iv HTML을 선호합니다. 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"로 유지됩니다). 실패한 하위 단계는 {step, error_type, message, hint} 형태의 구조화된 항목을 errors에 추가합니다. 여기서 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에 전송함. 프롬프트 인젝션 콘텐츠가 포함된 논문은 잘못된(그러나 스키마는 유효한) 구조화된 메서드를 생성할 수 있음. 출력을 연구 보조 자료로 취급하고, 절대적인 진실로 취급하지 말 것.

• 재현성 판정은 휴리스틱이지 증명이 아님. 높은 점수는 저장소가 재현에 적합한 구조로 보인다는 뜻일 뿐, 코드를 실행하면 논문이 재현된다는 것을 보장하지 않음. 전체 검증은 Paper2Agent를 참조.

• 로컬 stdio 사용을 위한 도구임. HTTP/SSE 전송은 개발 편의를 위해 제공되며 신뢰할 수 있는 네트워크에서만 노출해야 함(httpx가 제공하는 것 이상의 SSRF 보호는 없음).

문제 보고:

보안 문제: flynnlachendro@hotmail.co.uk로 이메일을 보내 주세요(SECURITY.md도 참조). 기능 버그: GitHub 이슈를 열어 주세요.

paper-mcp와 함께 사용

더 넓은 논문 검색 / 인용 그래프 도구를 원한다면 동일한 Claude Code 세션에서 paper-mcp (Bhvaik)를 함께 실행하세요. 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 — arXiv 논문의 깔끔한 HTML.

• Anthropic Claude — 구조화된 추출을 담당하는 LLM.