arXiv Deep Research

arXiv 논문을 검색, 다운로드 및 읽기 위한 Model Context Protocol (MCP) 서버입니다. Microsoft Magentic-UI 및 AutoGen과 같은 다중 에이전트 시스템에 통합하기 위한 전문가 에이전트로 설계되었습니다.

아이디어: arXiv 검색을 단순한 조회 도구로 취급하는 대신, 이 서버는 일류 연구 에이전트로 구조화되어 있습니다. Magentic-One 스타일 팀에 McpAgent로 직접 연결하여 오케스트레이터가 위임 가능한 리소스로서 전체 과학 문헌에 액세스할 수 있도록 합니다.

Magentic-UI와의 통합

Magentic-UI는 구성 파일의 mcp_agent_configs를 통해 사용자 지정 McpAgent 인스턴스를 지원합니다. 이 서버는 다음과 같이 직접 연결됩니다:

# examples/magentic_ui_config.yaml
client:
  mcp_agent_configs:
    - agent_name: ArxivResearcher
      description: >
        Specialist agent for searching and reading arXiv papers.
        Use when the task requires finding academic papers, understanding
        research literature, or retrieving technical details from published work.
      server_params:
        type: StdioServerParams
        command: python
        args: ["-m", "arxiv_mcp_server"]
        env:
          PYTHONPATH: /path/to/arxiv-deep-research/src

등록되면 Magentic-UI 오케스트레이터는 표준 작업 원장(Task Ledger) / 진행 원장(Progress Ledger) 패턴을 통해 이 에이전트에 연구 하위 작업을 위임할 수 있습니다. 이는 WebSurfer가 웹 브라우징을 처리하는 방식과 정확히 같지만, 학술 문헌을 대상으로 합니다.

AutoGen AgentChat과의 통합

3개 에이전트 팀 전체 예제는 examples/autogen_research_team.py를 참조하세요:

Orchestrator (MagenticOneGroupChat)
├── ArxivSurfer  ← this MCP server, wrapped via StdioServerParams + mcp_server_tools
└── Coder        ← synthesizes findings into structured markdown reports

pip install "autogen-agentchat" "autogen-ext[openai]" "mcp>=1.2.0"
export OPENAI_API_KEY=...
python examples/autogen_research_team.py

도구

search_papers

따옴표로 묶인 구문, 부울 연산자, 필드별 검색(ti:, au:, abs:), 카테고리 필터링 등 풍부한 쿼리 구문을 지원합니다:

{
  "query": "\"multi-agent\" AND \"orchestration\" ANDNOT survey",
  "max_results": 10,
  "date_from": "2024-01-01",
  "categories": ["cs.AI", "cs.MA"],
  "sort_by": "relevance"
}

다단계 연구 파이프라인

상위 수준에서 arxiv-deep-research는 간단하지만 강력한 다단계 루프를 실행합니다:

1. 연구 작업 계획

   • 코디네이터 에이전트(예: AutoGen MagenticOneGroupChat 오케스트레이터)가 사용자 목표를 받아 하위 작업으로 나눕니다.

2. 후보 논문 발견

   • 코디네이터가 MCP search_papers 도구를 호출하여 주제, 카테고리, 날짜별로 관련 arXiv 논문을 찾습니다.

3. 콘텐츠 다운로드 및 정규화

   • 선택된 ID에 대해 download_paper를 호출하여 PDF를 가져오고 LLM이 읽을 수 있도록 깔끔한 마크다운으로 변환합니다.

4. 심층 논문 분석

   • 코디네이터(또는 다른 에이전트)가 deep-paper-analysis 프롬프트를 사용하여 특정 논문 ID에 대한 구조화된 분석을 요청하며, 관련 연구를 탐색할 때 여러 번 호출할 수 있습니다.

5. 합성 및 보고

   • Coder(AutoGen 예제)와 같은 다운스트림 에이전트가 이러한 분석을 요약, 비교 표, 미해결 문제 및 다음 단계 제안이 포함된 최종 연구 보고서로 변환합니다.

이 파이프라인은 MCP 인식 클라이언트에서 도구와 프롬프트를 호출하여 수동으로 실행하거나, 샘플 AutoGen 팀을 사용하여 자동으로 실행할 수 있습니다.

평가 벤치마크

이 저장소에는 다음을 측정하는 검색 품질 벤치마크(eval/benchmark.py)가 포함되어 있습니다:

• Precision@K — 상위 K개 결과 중 관련성 있는 결과의 비율

• Recall@K — 상위 K개 결과에서 발견된 알려진 관련 논문의 비율

• MRR — 첫 번째 관련 결과의 평균 상호 순위(Mean Reciprocal Rank)

Ground-truth 쿼리는 랜드마크 논문(AutoGen 2308.08155, Magentic-One 2411.04468, RAG 2005.11401, CoT 2201.11903)에서 시드되며 아래의 합성 데이터 파이프라인을 사용하여 자동으로 확장할 수 있습니다.

python eval/benchmark.py --k 10 --output results.json

합성 평가 데이터 생성 (AgentInstruct 스타일)

scripts/generate_eval_tasks.py는 AgentInstruct 접근 방식을 반영하여 arXiv 초록에서 다양한 벤치마크 쿼리를 생성하는 4단계 파이프라인을 구현합니다:

Stage 1: Seed collection     → fetch paper abstracts from arXiv by category
Stage 2: Content transform   → extract key concepts and problem statements
Stage 3: Instruction gen     → generate realistic research queries via GPT-4o-mini
Stage 4: Instruction refine  → create harder variants at subtopic intersections

export OPENAI_API_KEY=...
python scripts/generate_eval_tasks.py --seed-category cs.AI --num-seeds 20 --output eval/generated_queries.json

출력에는 계층화된 평가를 위한 쉬움/보통/어려움 난이도 등급이 포함됩니다.

관측 가능성: OpenTelemetry 추적

모든 도구 호출은 OpenTelemetry 스팬으로 계측됩니다(AutoGen v0.4의 내장 OTel 지원 반영):

# Console output (no infrastructure needed)
export ARXIV_MCP_TRACE_CONSOLE=true
python -m arxiv_mcp_server

# OTLP export to Jaeger / Azure Monitor
docker run -d --name jaeger -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=arxiv-mcp-server
python -m arxiv_mcp_server
# View traces: http://localhost:16686

기록된 스팬: mcp.tool.search_papers, mcp.tool.download_paper, mcp.tool.read_paper — 각각 쿼리, 카테고리, 결과 수, 지연 시간 및 오류 상태를 속성으로 포함합니다.

opentelemetry-sdk가 설치되지 않은 경우 추적은 비용이 발생하지 않는 no-op입니다.

설치

Python 3.11+ 필요

git clone https://github.com/freyzo/arxiv-deep-research
cd arxiv-deep-research
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Optional: OTel tracing
pip install -e ".[tracing]"

Claude Desktop

{
  "mcpServers": {
    "arxiv": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "arxiv_mcp_server", "--storage-path", "/path/to/papers"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "arxiv": {
      "command": "python",
      "args": ["-m", "arxiv_mcp_server"],
      "env": { "PYTHONPATH": "/path/to/arxiv-deep-research/src" }
    }
  }
}

프롬프트

deep-paper-analysis

요약, 방법론, 결과, 시사점 및 향후 방향을 다루는 포괄적인 분석 워크플로우:

{ "paper_id": "2401.12345" }

연구 세션 실행 및 재개

현재 연구 세션을 실행하는 두 가지 주요 방법이 있습니다.

1. AutoGen 다중 에이전트 팀 (권장 데모)

이 방법은 OpenAI 모델을 사용하여 전체 연구 워크플로우를 조정합니다.

cd arxiv-deep-research
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
pip install "autogen-agentchat" "autogen-ext[openai]" "mcp>=1.2.0"

export OPENAI_API_KEY=your_openai_key
python examples/autogen_research_team.py

이 명령은 대화형 콘솔 UI를 시작하며, 여기서:

• 오케스트레이터가 작업을 계획하고,

• ArxivSurfer가 MCP를 통해 논문을 검색 및 다운로드하며,

• Coder가 최종 마크다운 보고서를 작성합니다.

세션을 재개하려면 다음을 수행할 수 있습니다:

• 스크립트를 다시 실행하고 이전 요약을 새 작업의 일부로 붙여넣거나,

• 동일한 콘솔 세션을 열어두고 팀에 후속 지침을 제공합니다(예: “이제 안전성 트레이드오프에 집중해줘”).

2. Claude Desktop 또는 Cursor와 같은 도구에서 직접 MCP 사용

MCP 서버와 직접 대화하여 나만의 루프를 구축할 수도 있습니다:

cd arxiv-deep-research
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

export ARXIV_MCP_TRACE_CONSOLE=true   # optional
python -m arxiv_mcp_server

이 서버가 실행되는 동안 모든 MCP 인식 클라이언트는 다음을 수행할 수 있습니다:

• search_papers 및 download_paper 호출,

• read_paper를 사용하여 콘텐츠를 채팅으로 가져오기,

• deep-paper-analysis 프롬프트를 여러 번 호출.

프롬프트 핸들러는 간단한 전역 연구 컨텍스트를 유지하므로 동일한 프로세스 내에서 반복 호출하면 이전에 분석된 논문 ID를 언급하고 모델이 이를 연결하도록 유도합니다. 실제로 연구 세션을 “재개”한다는 것은 다음을 의미합니다:

• 동일한 MCP 서버 프로세스를 계속 실행하고,

• 동일한 클라이언트 또는 작업 공간에서 새로운 논문 ID에 대해 새로운 deep-paper-analysis 호출을 발행합니다.

저장소 구조

arxiv-deep-research/
├── src/arxiv_mcp_server/
│   ├── server.py          # MCP server + OTel init
│   ├── tracing.py         # @trace_tool decorator, OTLP + console exporters
│   ├── config.py
│   ├── tools/             # search, download, read, list
│   └── prompts/           # deep research analysis prompt
├── examples/
│   ├── autogen_research_team.py   # Magentic-One-style 3-agent team
│   └── magentic_ui_config.yaml    # McpAgent config for Magentic-UI
├── eval/
│   └── benchmark.py       # Precision@K / Recall@K / MRR harness
├── scripts/
│   └── generate_eval_tasks.py     # AgentInstruct-style query generator
└── pyproject.toml

환경 변수

선택적 평가 데이터 생성기를 사용하는 경우 다음도 필요합니다:

알려진 문제

• 현재 모델 지원은 OpenAI 전용입니다.

  • AutoGen 연구 팀과 합성 평가 생성기 모두 OpenAI Python SDK를 통해 OpenAI 모델(gpt-4o / gpt-4o-mini)을 호출합니다.

  • 설계상 지원할 수 있음에도 불구하고 아직 일류 google-genai / Gemini 또는 Gemma 통합은 없습니다.

• 아직 MCP 리소스가 없습니다.

  • 논문은 안정적인 arxiv:// URI가 있는 MCP 리소스가 아니라 도구(read_paper)를 통해서만 노출됩니다. 리소스를 선호하는 MCP 클라이언트는 아직 논문을 나열할 수 없습니다.

• 제한된 테스트.

  • 핵심 검색 및 평가 로직은 자동화된 테스트가 매우 적습니다. 메트릭 함수와 도구 핸들러는 시간이 지남에 따라 단위 테스트를 추가해야 합니다.

로드맵

계획된 개선 사항(변경될 수 있음):

• google-genai를 통한 Gemini / Gemma 지원

  • 선택적 google-genai 종속성과 GEMINI_API_KEY를 사용하여 Gemini/Gemma 모델을 호출할 수 있는 작은 러너를 추가합니다.

  • 이를 연구 팀 데모 및 평가 생성기를 위한 대체 백엔드로 노출합니다.

• 다운로드된 논문을 위한 MCP 리소스

  • list_resources / read_resource를 구현하여 다운로드된 PDF가 MCP 클라이언트에서 arxiv://paper_id 리소스로 나타나도록 합니다.

• 더 강력한 테스트 및 평가

  • 메트릭, 검색 도우미 및 프롬프트 핸들러에 대한 단위 테스트를 추가합니다.

  • eval/benchmark.py 실행을 자동화하고 시간 경과에 따른 회귀를 추적합니다.

• 더 풍부한 연구 세션

  • 간단한 전역 연구 컨텍스트를 명시적 세션 ID 및 지속 상태로 대체하여 “세션 X 재개”가 재시작 전반에 걸쳐 일류 기능이 되도록 합니다.