arXiv Deep Research

Un servidor del Protocolo de Contexto de Modelo (MCP) para buscar, descargar y leer artículos de arXiv, diseñado como un agente especializado para su integración en sistemas multiagente como Microsoft Magentic-UI y AutoGen.

La idea: En lugar de tratar la búsqueda en arXiv como una simple herramienta de consulta, este servidor está estructurado como un agente de investigación de primer nivel, uno que puedes conectar directamente a un equipo al estilo Magentic-One como un McpAgent, dando a un Orquestador acceso a toda la literatura científica como un recurso delegable.

Integración con Magentic-UI

Magentic-UI admite instancias personalizadas de McpAgent a través de mcp_agent_configs en su archivo de configuración. Este servidor se conecta directamente:

# 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

Una vez registrado, el Orquestador de Magentic-UI puede delegar subtareas de investigación a este agente a través del patrón estándar de Libro de Tareas / Libro de Progreso, exactamente como WebSurfer maneja la navegación web, pero para literatura académica.

Integración con AutoGen AgentChat

Consulta examples/autogen_research_team.py para ver un equipo completo de 3 agentes:

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

Herramientas

search_papers

Admite una sintaxis de consulta rica: frases entre comillas, operadores booleanos, búsqueda específica por campo (ti:, au:, abs:) y filtrado por categoría:

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

Tubería de investigación multietapa

A un nivel alto, arxiv-deep-research ejecuta un bucle multietapa simple pero potente:

1. Planificar la tarea de investigación

   • Un agente coordinador (por ejemplo, el Orquestador MagenticOneGroupChat de AutoGen) toma el objetivo del usuario y lo divide en subtareas.

2. Descubrir artículos candidatos

   • El coordinador llama a la herramienta MCP search_papers para encontrar artículos de arXiv relevantes por tema, categoría y fecha.

3. Descargar y normalizar el contenido

   • Para los IDs seleccionados, llama a download_paper, que obtiene el PDF y lo convierte en markdown limpio para que los LLM lo lean.

4. Análisis profundo de artículos

   • El coordinador (u otro agente) utiliza el prompt deep-paper-analysis para solicitar un análisis estructurado de un ID de artículo dado, opcionalmente a través de múltiples llamadas mientras exploras trabajos relacionados.

5. Síntesis e informes

   • Un agente descendente como Coder (en el ejemplo de AutoGen) convierte estos análisis en un informe de investigación final: resúmenes, tablas comparativas, problemas abiertos y sugerencias de próximos pasos.

Puedes ejecutar esta tubería manualmente llamando a las herramientas y prompts desde cualquier cliente compatible con MCP, o automáticamente usando el equipo de AutoGen de muestra.

Benchmark de evaluación

El repositorio incluye un benchmark de calidad de recuperación (eval/benchmark.py) que mide:

• Precision@K — fracción de los resultados top-K que son relevantes

• Recall@K — fracción de artículos relevantes conocidos encontrados en el top-K

• MRR — Rango Recíproco Medio del primer resultado relevante

Las consultas de verdad fundamental (ground-truth) se obtienen de artículos emblemáticos (AutoGen 2308.08155, Magentic-One 2411.04468, RAG 2005.11401, CoT 2201.11903) y pueden extenderse automáticamente utilizando la tubería de datos sintéticos a continuación.

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

Generación de datos de evaluación sintéticos (estilo AgentInstruct)

scripts/generate_eval_tasks.py implementa una tubería de 4 etapas que genera diversas consultas de benchmark a partir de resúmenes de arXiv, reflejando el enfoque de 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

La salida incluye niveles de dificultad fácil/medio/difícil para una evaluación estratificada.

Observabilidad: Rastreo con OpenTelemetry

Cada llamada a herramienta está instrumentada con spans de OpenTelemetry (refleja el soporte OTel integrado de 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

Spans registrados: mcp.tool.search_papers, mcp.tool.download_paper, mcp.tool.read_paper — cada uno con consulta, categorías, recuento de resultados, latencia y estado de error como atributos.

El rastreo es una operación sin costo cuando opentelemetry-sdk no está instalado.

Instalación

Requiere 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" }
    }
  }
}

Prompts

deep-paper-analysis

Flujo de trabajo de análisis integral que cubre resumen ejecutivo, metodología, resultados, implicaciones y direcciones futuras:

{ "paper_id": "2401.12345" }

Ejecución y reanudación de sesiones de investigación

Existen dos formas principales de ejecutar sesiones de investigación hoy en día.

1. Equipo multiagente de AutoGen (demo recomendada)

Esto utiliza modelos de OpenAI para coordinar un flujo de trabajo de investigación completo.

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

Esto inicia una interfaz de consola interactiva donde:

• el Orquestador planifica el trabajo,

• ArxivSurfer busca y descarga artículos a través de MCP, y

• Coder escribe el informe final en markdown.

Para reanudar una sesión, puedes:

• ejecutar el script de nuevo y pegar el resumen anterior como parte de una nueva tarea, o

• mantener abierta la misma sesión de consola y darle al equipo una instrucción de seguimiento (por ejemplo, “Ahora céntrate en las compensaciones de seguridad”).

2. Uso directo de MCP desde herramientas como Claude Desktop o Cursor

También puedes hablar directamente con el servidor MCP y construir tu propio bucle:

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

Mientras este servidor se ejecuta, cualquier cliente compatible con MCP puede:

• llamar a search_papers y download_paper,

• usar read_paper para extraer contenido al chat, y

• llamar al prompt deep-paper-analysis varias veces.

El manejador de prompts mantiene un contexto de investigación global simple, por lo que las llamadas repetidas en el mismo proceso mencionarán los IDs de artículos analizados previamente y animarán al modelo a conectarlos. En la práctica, “reanudar” una sesión de investigación significa:

• mantener vivo el mismo proceso del servidor MCP, y

• emitir nuevas llamadas a deep-paper-analysis para nuevos IDs de artículos desde el mismo cliente o espacio de trabajo.

Estructura del repositorio

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

Variables de entorno

Si utilizas el generador de datos de evaluación opcional, también necesitas:

Problemas conocidos

• El soporte de modelos es solo para OpenAI actualmente.

  • El equipo de investigación de AutoGen y el generador de evaluación sintética llaman a modelos de OpenAI (gpt-4o / gpt-4o-mini) a través del SDK de Python de OpenAI.

  • Aún no hay integración de primer nivel con google-genai / Gemini o Gemma, aunque el diseño lo admitiría.

• Aún no hay Recursos MCP.

  • Los artículos se exponen solo a través de herramientas (read_paper) en lugar de como Recursos MCP con URIs estables arxiv://. Los clientes MCP que prefieren Recursos aún no pueden listar artículos.

• Pruebas limitadas.

  • La lógica central de recuperación y evaluación tiene pruebas automatizadas muy ligeras; las funciones de métricas y los manejadores de herramientas deberían ganar pruebas unitarias con el tiempo.

Hoja de ruta

Mejoras planificadas (sujetas a cambios):

• Soporte para Gemini / Gemma a través de google-genai

  • Agregar una dependencia opcional google-genai y un pequeño ejecutor que pueda llamar a modelos Gemini/Gemma usando GEMINI_API_KEY.

  • Exponer esto como un backend alternativo para la demo del equipo de investigación y el generador de evaluación.

• Recursos MCP para artículos descargados

  • Implementar list_resources / read_resource para que los PDFs descargados aparezcan como recursos arxiv://paper_id en los clientes MCP.

• Pruebas y evaluaciones más sólidas

  • Agregar pruebas unitarias para métricas, ayudantes de búsqueda y manejadores de prompts.

  • Automatizar la ejecución de eval/benchmark.py y realizar un seguimiento de la regresión a lo largo del tiempo.

• Sesiones de investigación más ricas

  • Reemplazar el contexto de investigación global simple con IDs de sesión explícitos y estado persistente, para que “reanudar sesión X” se convierta en una característica de primer nivel entre reinicios.