AI导哈

arXiv MCP代理

一个完整的模型上下文协议（MCP）实现，提供与arXiv API交互的客户端和服务器，支持搜索、下载和文章内容提取功能。

  • by backnumber19
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 backnumber19/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<br/>"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",<br/>"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客户端如何无需修改即可与现有服务器集成，展示了协议的可组合性和生态系统方法。

配置

环境变量

变量 描述 默认值
AWS_REGION 基岩AWS区域 us-west-2
BEDROCK_MODEL 基岩模型ID anthropic.claude-3-haiku-20240307-v1:0
ARXIV_SERVER_PATH 服务器目录路径 必填
DOWNLOAD_PATH PDF下载目录 ./downloads
SSL_VERIFY 启用SSL验证 false

根配置

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

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

  2. 取样中的基岩误差

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

  3. 下载失败

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

  4. 连接错误

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

  5. LLM工具选择错误

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

输出示例

演示会话

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

参考文献

相关 MCP