arXiv Deep Research

MCP-сервер (Model Context Protocol) для поиска, скачивания и чтения статей с arXiv — разработан как специализированный агент для интеграции в мультиагентные системы, такие как Microsoft Magentic-UI и AutoGen.

Идея: Вместо того чтобы рассматривать поиск по arXiv как простой инструмент поиска, этот сервер структурирован как полноценный исследовательский агент — его можно напрямую подключить к команде в стиле Magentic-One в качестве McpAgent, предоставляя оркестратору доступ ко всей научной литературе как к делегируемому ресурсу.

Интеграция с Magentic-UI

Magentic-UI поддерживает пользовательские экземпляры McpAgent через mcp_agent_configs в файле конфигурации. Этот сервер подключается напрямую:

# 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

См. examples/autogen_research_team.py для примера полноценной команды из 3 агентов:

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. Планирование исследовательской задачи

   • Агент-координатор (например, оркестратор MagenticOneGroupChat в AutoGen) принимает цель пользователя и разбивает ее на подзадачи.

2. Поиск подходящих статей

   • Координатор вызывает инструмент MCP search_papers для поиска релевантных статей на arXiv по теме, категории и дате.

3. Скачивание и нормализация контента

   • Для выбранных ID он вызывает download_paper, который загружает PDF и преобразует его в чистый markdown для чтения LLM.

4. Глубокий анализ статьи

   • Координатор (или другой агент) использует промпт deep-paper-analysis для запроса структурированного анализа статьи по заданному ID, при необходимости выполняя несколько вызовов по мере изучения связанных работ.

5. Синтез и отчетность

   • Агент нижнего уровня, такой как Coder (в примере с AutoGen), превращает эти анализы в итоговый исследовательский отчет: резюме, сравнительные таблицы, открытые проблемы и предложения по следующим шагам.

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

Эталонное тестирование (Benchmark)

Репозиторий включает бенчмарк качества поиска (eval/benchmark.py), измеряющий:

• Precision@K — доля релевантных результатов в топ-K

• Recall@K — доля известных релевантных статей, найденных в топ-K

• MRR — средний обратный ранг первого релевантного результата

Эталонные запросы основаны на знаковых статьях (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 реализует 4-этапный конвейер, который генерирует разнообразные бенчмарк-запросы на основе аннотаций arXiv — повторяя подход AgentInstruct:

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 (повторяет встроенную поддержку OTel в AutoGen v0.4):

# 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 не установлен.

Установка

Требуется 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

Это запускает интерактивный консольный интерфейс, где:

• Оркестратор планирует работу,

• ArxivSurfer ищет и скачивает статьи через MCP, а

• Coder пишет итоговый отчет в формате markdown.

Чтобы возобновить сессию, вы можете:

• запустить скрипт снова и вставить предыдущее резюме как часть новой задачи, или

• оставить ту же консольную сессию открытой и дать команде последующую инструкцию (например, «Теперь сосредоточься на компромиссах в области безопасности»).

2. Прямое использование MCP из таких инструментов, как Claude Desktop или Cursor

Вы также можете напрямую взаимодействовать с 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-сервера, и

• отправку новых вызовов deep-paper-analysis для новых ID статей из того же клиента или рабочей области.

Структура репозитория

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 (gpt-4o / gpt-4o-mini) через Python SDK OpenAI.

  • Пока нет полноценной интеграции с google-genai / Gemini или Gemma, хотя дизайн это позволяет.

• Пока нет ресурсов MCP.

  • Статьи доступны только через инструменты (read_paper), а не как ресурсы MCP со стабильными URI arxiv://. MCP-клиенты, предпочитающие ресурсы, пока не могут перечислять статьи.

• Ограниченное тестирование.

  • Основная логика поиска и оценки имеет очень легкое автоматизированное тестирование; функции метрик и обработчики инструментов должны со временем получить модульные тесты.

Дорожная карта

Планируемые улучшения (могут быть изменены):

• Поддержка Gemini / Gemma через google-genai

  • Добавить опциональную зависимость google-genai и небольшой раннер, который может вызывать модели Gemini/Gemma с использованием GEMINI_API_KEY.

  • Представить это как альтернативный бэкенд для демонстрации исследовательской команды и генератора оценок.

• Ресурсы MCP для скачанных статей

  • Реализовать list_resources / read_resource, чтобы скачанные PDF-файлы отображались как ресурсы arxiv://paper_id в клиентах MCP.

• Более надежное тестирование и оценки

  • Добавить модульные тесты для метрик, помощников поиска и обработчиков промптов.

  • Автоматизировать запуск eval/benchmark.py и отслеживать регрессию с течением времени.

• Более богатые исследовательские сессии

  • Заменить простой глобальный контекст исследования на явные ID сессий и сохраненное состояние, чтобы «возобновление сессии X» стало полноценной функцией после перезапусков.