Arxiv MCP Agent

arXiv MCP代理

 

一个完整的模型上下文协议（MCP）实现，具有与arXiv API交互的客户端和服务器。该项目演示了所有三个MCP客户端原语（根、采样、引用），并提供了一个功能齐全的arXiv搜索和下载服务。

MCP的核心优势之一是其可重用的服务器生态系统 -该项目使用arXiv MCP服务器 blazickjp/arxiv mcp服务器，演示了MCP客户端如何与生态系统中的现有服务器无缝集成。

特性

MCP客户端原语

• 根：定义服务器访问权限的文件系统边界
• 采样：使用AWS Bedrock的LLM输出请求
• 引出：交互式操作的用户输入请求

arXiv服务器工具

• search_arxiv：使用灵活的查询选项搜索arXiv数据库
• 获取详细信息：检索有关文章的全面元数据
• 获取_文章_url：获取文章的直接URL
• 下载_文章：将PDF文件下载到本地存储
• load_article_to_context：从PDF中提取LLM上下文的文本内容

项目结构

arxiv-mcp-agent/
├── src/
│   ├── client/               # MCP Client implementation
│   │   ├── __init__.py
│   │   ├── client.py         # MCPClient with all 3 primitives
│   │   └── agent.py          # High-level agent wrapper
│   └── server/               # MCP Server implementation
│       ├── src/
│       │   └── arxiv_server/
│       │       └── server.py # FastMCP server with arXiv tools
│       ├── pyproject.toml
│       └── README.md
├── examples/
│   └── demo.py               # Interactive demo script
├── downloads/                # PDF download directory
├── tests/                    # Test files
├── requirements.txt          
└── README.md                 

内部架构流程

sequenceDiagram
    participant User
    participant Demo
    participant Agent
    participant LLM
    participant Client
    participant Server

    User->>Demo: python demo.py
    Demo->>Client: MCPClient initialization
    Demo->>Client: client.connect()
    Client->>Server: stdio connection established
    
    Demo->>Agent: MCPAgent(client)
    Agent->>Client: client.list_tools()
    Client->>Server: list_tools request
    Server-->>Client: tools list
    Client-->>Agent: tools cached
    
    User->>Demo: Natural language request
"Find papers about AI"
    Demo->>Agent: agent.process_user_request(query)
    
    Note over Agent,LLM: LLM Tool Selection
    Agent->>Agent: _format_tools_for_llm()
    Agent->>LLM: Prompt with tools + user query
    LLM->>LLM: Analyze request & select tool
    LLM-->>Agent: JSON: {"tool_name": "search_arxiv",
"arguments": {...}}
    Agent->>Agent: _extract_json_from_response()
    Agent->>Agent: Validate tool selection
    
    Note over Agent,Server: MCP Tool Execution
    Agent->>Client: client.call_tool(tool_name, arguments)
    Client->>Server: call_tool request
    Server->>Server: arXiv API call
    Server-->>Client: results
    Client-->>Agent: parsed results
    
    Note over Agent,LLM: LLM Result Explanation
    Agent->>LLM: Explain results to user
    LLM-->>Agent: Natural language explanation
    Agent-->>Demo: Explanation
    Demo-->>User: Display results
    
    User->>Demo: Exit
    Demo->>Agent: agent.close()
    Agent->>Client: client.close()
    Client->>Server: connection closed

安装

先决条件

• Python 3.10+
• 具有基岩访问权限的AWS帐户（用于采样图元）
• 虚拟环境（推荐）

设置

1. 克隆存储库：

git clone https://github.com/backnumber19/arxiv-mcp-agent.git
cd arxiv-mcp-agent

1. 创建并激活虚拟环境：

python -m venv venv
source venv/bin/activate

1. 安装依赖项：

pip install -r requirements.txt

1. 创建 .env 文件：

AWS_REGION=us-west-2
BEDROCK_MODEL=anthropic.claude-3-haiku-20240307-v1:0
ARXIV_SERVER_PATH=/absolute/path/to/src/server/src/arxiv_server
DOWNLOAD_PATH=/absolute/path/to/downloads
SSL_VERIFY=false

用法

运行演示

演示脚本展示了所有三个MCP客户端原语，并为arXiv操作提供了一个交互式界面：

python examples/demo.py

演示包括：

1. Roots演示：演示文件系统边界配置
2. 采样演示：测试LLM与基岩的整合
3. 交互菜单：搜索、下载和浏览arXiv文章

以编程方式使用客户端

import asyncio
from src.client.agent import MCPAgent
from src.client.client import MCPClient

async def main():
    # Initialize client
    client = MCPClient(
        server_command="python",
        server_args=["/path/to/server.py"],
        server_env={"DOWNLOAD_PATH": "/path/to/downloads"},
        roots=[
            {"uri": "file:///current/dir", "name": "Current Directory"},
            {"uri": "file:///downloads", "name": "Downloads"}
        ]
    )
    
    agent = MCPAgent(client)
    await agent.initialize()
    
    # LLM automatically selects tools
    result1 = await agent.process_user_request("Find papers about machine learning")
    result2 = await agent.process_user_request("Download the paper: Attention Is All You Need")
    result3 = await agent.process_user_request("Get details for transformer architecture")
    
    await agent.close()

asyncio.run(main())

建筑

MCP客户端(src/client/client.py)

核心客户端实现，包括：

• _list_roots_callback()：返回已配置的文件系统根目录
• _sampling_callback()：通过Bedrock处理LLM请求
• connect()：建立与服务器的stdio连接
• call_tool()：调用服务器工具
• list_tools()：枚举可用的服务器工具

MCPAgent(src/client/agent.py)

LLM授权代理提供：

• process_user_request()：自然语言请求的主要入口点
• _llm_select_tool()：基于LLM的自动刀具选择
• _llm_explain_result()：基于LLM的结果解释
• _format_tools_for_llm()：用于LLM理解的可用工具格式
• 工具缓存和验证

服务器(src/server/src/arxiv_server/server.py)

arXiv服务器实现基于 blazickjp/arxiv mcp服务器这体现了MCP的核心理念： 客户端可以利用生态系统中的任何兼容MCP的服务器，实现快速开发和互操作性。

该服务器是基于FastMCP的实现，提供：

• arXiv API通过httpx集成
• 使用PyMuPDF进行PDF处理
• 文章查找的模糊标题匹配
• 错误处理和验证

备注：中的服务器代码 src/server/ 从上游存储库克隆。这展示了MCP客户端如何无需修改即可与现有服务器集成，展示了协议的可组合性和生态系统方法。

配置

环境变量

根配置

根定义了文件系统的安全边界：

ROOTS = [
    {
        "uri": "file:///absolute/path/to/allowed/dir",
        "name": "Human-readable name"
    }
]

依赖项

核心

• mcp==1.20.0 -模型上下文协议SDK
• fastmcp==2.13.0.2 -FastMCP服务器框架
• pydantic==2.12.3 -数据验证

AWS集成

• boto3==1.35.91 -AWS SDK
• langchain-aws==0.2.9 -LangChain AWS集成

arXiv集成

• httpx==0.28.1 -异步HTTP客户端
• feedparser -RSS/Atom提要解析
• PyMuPDF==1.26.5 -PDF文本提取

公用事业

• python-dotenv==1.0.0 -环境变量管理

发展

运行测试

pytest tests/

项目结构指南

• 客户代码： src/client/
• 服务器代码： src/server/src/arxiv_server/
• 示例： examples/
• 测验： tests/

故障排除

常见问题

1. “服务器文件不存在”

- 集 ARXIV_SERVER_PATH 在 .env 绝对路径 - 确保路径指向包含以下内容的目录 server.py

1. 取样中的基岩误差

- 验证AWS凭据是否已配置 - 检查 AWS_REGION 和 BEDROCK_MODEL 在 .env - 确保在AWS帐户中启用基岩访问

1. 下载失败

- 验证 DOWNLOAD_PATH 存在并且可写 - 检查arXiv.org的网络连接 - 查看SSL验证设置

1. 连接错误

- 确保服务器Python路径正确 - 验证是否已安装所有依赖项 - 检查服务器日志以获取详细的错误消息

1. LLM工具选择错误

- 确认基岩配置正确 - 检查LLM响应格式（应该是JSON） - 查看工具说明以确保清晰

输出示例

演示会话

flowchart TD
    A[MCPAgent Initialization
agent = MCPAgent client] --> B[agent.initialize]
    B --> C[MCPClient.connect
stdio connection established]
    C --> D[Server Connected
Connected to MCP server]
    D --> E[Tool List Query
client.list_tools]
    E --> F[Tools Cached
Available tools loaded]
    F --> G[Display Available Tools]
    G --> H[Interactive Menu
1. Custom Request 2. Exit]
    H --> I{User Selection}
    I -->|1| J[User Input
Natural Language Query]
    I -->|2| K[Exit]
    J --> L[Agent
process_user_request]
    L --> M[LLM Tool Selection
_llm_select_tool]
    M --> N[Execute Tool
client.call_tool via MCP]
    N --> O[LLM Result Explanation
_llm_explain_result]
    O --> P[Display Results]
    P --> H
    K --> Q[agent.close
Connection closed]

参考文献

• 模型上下文协议
• arXiv API文档
• MCP Python SDK
• arXiv MCP服务器（blazickjp） -此项目中使用的服务器实现