arXiv 深度研究

在 VS Code 中安装在 VS Code Insiders 中安装

一个用于搜索、下载和阅读 arXiv 论文的 模型上下文协议 (MCP) 服务器 —— 旨在作为集成到多智能体系统（如 Microsoft Magentic-UI 和 AutoGen）中的专家智能体。

理念： 该服务器并非将 arXiv 搜索视为简单的查找工具，而是将其构建为一流的研究智能体 —— 你可以直接将其作为 McpAgent 插入到 Magentic-One 风格的团队中，从而为编排器（Orchestrator）提供访问完整科学文献作为可委派资源的能力。

与 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 编排器就可以通过标准的任务分类账 / 进度分类账模式将研究子任务委派给此智能体 —— 这与 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`	使用高级过滤器查询 arXiv：日期范围、类别、按相关性或日期排序
`download_paper`	获取论文 PDF 并将其转换为适合 LLM 使用的纯 Markdown
`read_paper`	访问之前下载的论文内容
`list_papers`	查看本地存储中的所有论文

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 运行一个简单但强大的多阶段循环：

规划研究任务
- 协调智能体（例如 AutoGen MagenticOneGroupChat 编排器）获取用户目标并将其分解为子任务。
发现候选论文
- 协调器调用 MCP search_papers 工具，按主题、类别和日期查找相关的 arXiv 论文。
下载并规范化内容
- 对于选定的 ID，它调用 download_paper，该工具获取 PDF 并将其转换为适合 LLM 阅读的纯 Markdown。
深度论文分析
- 协调器（或另一个智能体）使用 deep-paper-analysis 提示词要求对给定的论文 ID 进行结构化分析，在探索相关工作时，可以选择跨多个调用进行分析。
综合与报告
- 下游智能体（如 AutoGen 示例中的 Coder）将这些分析转化为最终的研究报告：摘要、对比表、未解决的问题以及后续步骤建议。

你可以通过从任何支持 MCP 的客户端调用工具和提示词来手动运行此流水线，或者使用示例 AutoGen 团队自动运行。

评估基准

该仓库包含一个检索质量基准 (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 跨度（span）进行了检测（模仿 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 时，追踪是零成本的空操作。

安装

需要 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，其中：

Orchestrator 规划工作，
ArxivSurfer 通过 MCP 搜索并下载论文，以及
Coder 编写最终的 Markdown 报告。

要 恢复会话，你可以：

再次运行脚本并将之前的摘要作为新任务的一部分粘贴进去，或者
保持同一个控制台会话打开，并给团队下达后续指令（例如，“现在专注于安全权衡”）。

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

环境变量

变量	默认值	描述
`ARXIV_STORAGE_PATH`	`~/.arxiv-mcp-server/papers`	论文存储位置
`ARXIV_MCP_TRACE_CONSOLE`	`false`	启用控制台追踪输出
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	OTLP 端点（例如 `http://localhost:4317`）
`OTEL_SERVICE_NAME`	`arxiv-mcp-server`	追踪中的服务名称

如果你使用可选的评估数据生成器，你还需要：

变量	描述
`OPENAI_API_KEY`	由 `scripts/generate_eval_tasks.py` 用于与 `gpt-4o-mini` 通信

已知问题

目前仅支持 OpenAI 模型。
- AutoGen 研究团队和合成评估生成器都通过 OpenAI Python SDK 调用 OpenAI 模型 (gpt-4o / gpt-4o-mini)。
- 目前还没有一流的 google-genai / Gemini 或 Gemma 集成，尽管设计上是支持的。
尚无 MCP 资源。
- 论文仅通过工具 (read_paper) 公开，而不是作为具有稳定 arxiv:// URI 的 MCP 资源。偏好资源的 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”成为跨重启的一流功能。

ArXiv MCP Server