使用说明

arXiv深度研究

A. 模型上下文协议（MCP）服务器 用于搜索、下载和阅读arXiv论文——被设计为集成到多代理系统中的专业代理，如微软Magentic用户界面和自动生成.

想法： 该服务器不是将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 Orchestrator可以通过标准的任务分类账/进度分类账模式将研究子任务委托给此代理——这正是WebSurfer处理网页浏览的方式，但适用于学术文献。

与AutoGen AgentChat集成

看 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`	使用高级过滤器查询arXiv：日期范围、类别、按相关性或日期排序
`download_paper`	获取纸质PDF并转换为干净的降价以供LLM使用
`read_paper`	访问以前下载的纸质内容
`list_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 Orchestrator）将用户目标分解为子任务。
发现候选论文
- 协调员呼叫MCP search_papers 该工具按主题、类别和日期查找相关的arXiv论文。
下载并规范内容
- 对于选定的ID，它调用 download_paper，它获取PDF并将其转换为干净的标记，供LLM读取。
深度论文分析
- 协调员（或其他代理）使用 deep-paper-analysis 提示要求对给定的论文ID进行结构化分析，在您探索相关工作时，可以选择进行多次调用。
综合和报告
- 下游代理，如 Coder （在AutoGen示例中）将这些分析转化为最终的研究报告：总结、比较表、未决问题和下一步建议。

您可以通过从任何支持MCP的客户端调用工具和提示来手动运行此管道，也可以使用示例AutoGen团队自动运行此管道。

评价基准

该仓库包括一个检索质量基准(eval/benchmark.py)测量：

Precision@K --前K结果中相关的分数
Recall@K --在top-K中发现的已知相关论文的比例
平均倒数排名 -第一个相关结果的平均倒数排名

从具有里程碑意义的论文（AutoGen 2308.08155，魔法一号 2411.04468，抹布 2005.11401，CoT 2201.11903)并且可以使用下面的合成数据管道自动扩展。

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

综合评估数据生成（代理指令风格）

scripts/generate_eval_tasks.py 实现了一个4级管道，该管道从arXiv摘要生成各种基准查询，反映了代理指令方法：

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

输出包括用于分层评估的简单/中等/困难等级。

可观察性：开放遥测追踪

每个工具调用都使用OpenTetry跨度（镜像）进行检测 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]"

克劳德桌面

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

光标

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

提示

深度纸张分析

涵盖执行摘要、方法、结果、影响和未来方向的综合分析工作流程：

{ "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搜索和下载论文，以及
编码员 撰写最终的降价报告。

到 恢复会话，您可以：

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

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服务器进程处于活动状态，以及
发布新 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

环境变量

变量	默认值	描述
`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`	跟踪中的服务名称

如果您使用可选的eval数据生成器，您还需要：

变量	描述
`OPENAI_API_KEY`	使用人 `scripts/generate_eval_tasks.py` 与之交谈 `gpt-4o-mini`

已知问题

模型支持仅限于OpenAI。
- AutoGen研究团队和合成eval生成器都称之为OpenAI模型(gpt-4o / gpt-4o-mini)通过OpenAI Python SDK。
- 有 没有头等舱 google-genai /Gemini或Gemma尚未整合，尽管设计会支持它。
还没有MCP资源。
- 论文仅通过工具公开(read_paper)而不是作为稳定的MCP资源 arxiv:// URI。更喜欢资源的MCP客户还不能列出论文。
有限的测试。
- 核心检索和评估逻辑具有非常轻的自动化测试；随着时间的推移，度量函数和工具处理程序应该获得单元测试。

路线图

计划改进（可能会发生变化）：

Gemini/Gemma支持通过 google-genai
- 添加可选 google-genai 依赖关系和一个可以使用以下命令调用Gemini/Gemma模型的小型跑步者 GEMINI_API_KEY.
- 将其作为研究团队演示和eval生成器的替代后端。
下载论文的MCP资源
- 实施 list_resources / read_resource 因此下载的PDF显示为 arxiv://paper_id MCP客户端中的资源。
更强的测试和评估
- 为指标、搜索助手和提示处理程序添加单元测试。
- 自动运行 eval/benchmark.py 并跟踪随时间的回归。
更丰富的研究会议
- 将简单的全局研究上下文替换为显式会话ID和持久状态，因此“恢复会话X”在重新启动时成为一项一流功能。