A2A-MCP-服务器

Name: A2A-MCP-服务器
Author: GongRzhe

作者：GongRzhe115 星标更新：2025-06-18

安装使用来源：spider==github.com

项目介绍

A2A MCP Server

这是一个将模型上下文协议（MCP）与代理到代理（A2A）协议桥接的MCP服务器，使兼容MCP的AI助手（如Claude）能够无缝地与A2A代理进行交互。

概述

该项目作为两个前沿AI代理协议之间的集成层：

模型上下文协议（MCP）：由Anthropic开发，MCP允许AI助手连接到外部工具和数据源。它标准化了AI应用程序和大型语言模型如何以安全且可组合的方式连接到外部资源。
代理到代理协议（A2A）：由Google开发，A2A通过一个标准化的JSON-RPC接口实现不同AI代理之间的通信和互操作性。

通过桥接这些协议，该服务器允许MCP客户端（如Claude）通过统一界面发现、注册、与A2A代理通信并管理任务。

示例

1. 运行A2A样本中的货币代理

agent

也支持云部署的代理

cloudAgent

2. 使用Claude注册货币代理

3. 使用Claude向货币代理发送任务并获取结果

task

功能

代理管理
- 注册A2A代理到桥接服务器
- 列出所有已注册的代理
- 当不再需要时注销代理
通信
- 向A2A代理发送消息并接收响应
- 实时流式传输来自A2A代理的响应
任务管理
- 跟踪哪个A2A代理处理哪个任务
- 使用任务ID检索任务结果
- 取消正在运行的任务
传输支持
- 多种传输类型：stdio、streamable-http、SSE
- 使用MCP_TRANSPORT环境变量配置传输类型

安装

通过Smithery安装

要通过Smithery自动安装适用于Claude Desktop的A2A Bridge Server：

npx -y @smithery/cli install @GongRzhe/A2A-MCP-Server --client claude

方案1：从PyPI安装

pip install a2a-mcp-server

方案2：本地安装

克隆仓库：

git clone https://github.com/GongRzhe/A2A-MCP-Server.git
cd A2A-MCP-Server

设置虚拟环境：

python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

安装依赖项：
```
pip install -r requirements.txt
```

配置

环境变量

使用以下环境变量配置MCP服务器的运行方式：

# 传输类型：stdio、streamable-http 或 sse
export MCP_TRANSPORT="streamable-http"

# MCP服务器主机
export MCP_HOST="0.0.0.0"

# MCP服务器端口（当使用HTTP传输时）
export MCP_PORT="8000"

# MCP服务器端点路径（当使用HTTP传输时）
export MCP_PATH="/mcp"

# SSE端点路径（当使用SSE传输时）
export MCP_SSE_PATH="/sse"

# 启用调试日志
export MCP_DEBUG="true"

传输类型

A2A MCP服务器支持多种传输类型：

stdio（默认）：使用标准输入/输出进行通信
- 适合命令行使用和测试
- 不启动HTTP服务器
- 对于Claude Desktop是必需的
streamable-http（推荐用于Web客户端）：具有流式传输支持的HTTP传输
- 推荐用于生产部署
- 启动HTTP服务器来处理MCP请求
- 支持大型响应的流式传输
sse：服务器发送事件传输
- 提供实时事件流
- 对于实时更新很有用

指定传输类型：

# 使用环境变量
export MCP_TRANSPORT="streamable-http"
uvx a2a-mcp-server

# 或直接在命令中
MCP_TRANSPORT=streamable-http uvx a2a-mcp-server

运行服务器

从命令行运行

# 使用默认设置（stdio传输）
uvx a2a-mcp-server

# 使用特定主机和端口的HTTP传输
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8080 uvx a2a-mcp-server

在Claude Desktop中配置

Claude Desktop允许您在claude_desktop_config.json文件中配置MCP服务器。此文件通常位于：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

方法1：PyPI安装（推荐）

在您的claude_desktop_config.json文件的mcpServers部分添加以下内容：

"a2a": {
  "command": "uvx",
  "args": [
    "a2a-mcp-server"
  ]
}

注意，对于Claude Desktop，您必须使用"MCP_TRANSPORT": "stdio"，因为Claude需要与MCP服务器进行stdio通信。

方法2：本地安装

如果您已经克隆了仓库，并希望从本地安装运行服务器：

"a2a": {
  "command": "C:\\path\\to\\python.exe",
  "args": [
    "C:\\path\\to\\A2A-MCP-Server\\a2a_mcp_server.py"
  ],
  "env": {
    "MCP_TRANSPORT": "stdio",
    "PYTHONPATH": "C:\\path\\to\\A2A-MCP-Server"
  }
}

将C:\\path\\to\\替换为您系统上的实际路径。

使用配置创建器

此仓库包括一个config_creator.py脚本，帮助您生成配置：

# 如果使用本地安装
python config_creator.py

该脚本会：

自动检测Python、脚本和仓库路径（如果可能的话）
配置stdio传输，这是Claude Desktop所必需的
让您可以添加任何额外的环境变量（如有需要）
创建或更新您的Claude Desktop配置文件

完整示例

这里是一个完整的claude_desktop_config.json文件示例，其中配置了A2A-MCP-Server：

{
  "mcpServers": {
    "a2a": {
      "command": "uvx",
      "args": [
        "a2a-mcp-server"
      ]
    }
  }
}

使用MCP客户端

Claude

Claude可以通过此服务器提供的MCP工具使用A2A代理。以下是设置方法：

对于Claude Web：使用streamable-http传输启动MCP服务器：

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

对于Claude Web：在Claude Web界面中，启用Tools菜单中的MCP URL连接。
- 使用URL：http://127.0.0.1:8000/mcp
对于Claude Desktop：按照上述描述将配置添加到您的claude_desktop_config.json文件中。最简单的方法是使用提供的config_creator.py脚本，它会自动检测路径并创建正确的配置。

在Claude中，您可以使用以下函数：

注册一个A2A代理：

我需要注册一个新的代理。你能帮我吗？
（代理URL：http://localhost:41242）

向代理发送消息：

问位于http://localhost:41242的代理它能做什么。

检索任务结果：

你能得到任务ID：550e8400-e29b-41d4-a716-446655440000的结果吗？

Cursor IDE

Cursor IDE可以连接到MCP服务器以在其AI助手中添加工具：

使用streamable-http传输运行您的A2A MCP服务器：

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

在Cursor IDE中，转到Settings > AI > MCP Servers
- 添加一个新的MCP服务器，使用URL：http://127.0.0.1:8000/mcp
- 启用服务器
现在您可以在Cursor的AI助手内部使用A2A工具。

Windsurf浏览器

Windsurf是一款内置MCP支持的浏览器：

使用streamable-http传输运行您的A2A MCP服务器：

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx a2a-mcp-server

在Windsurf浏览器中，转到Settings > MCP Connections
- 添加一个新的MCP连接，使用URL：http://127.0.0.1:8000/mcp
- 启用连接
现在您可以在Windsurf的AI助手内部使用A2A工具。

可用的MCP工具

服务器公开了以下MCP工具，以便与像Claude这样的LLM集成：

代理管理

register_agent：将A2A代理注册到桥接服务器

{
  "name": "register_agent",
  "arguments": {
    "url": "http://localhost:41242"
  }
}

list_agents：获取所有已注册代理的列表
```
{
  "name": "list_agents",
  "arguments": {}
}
```

unregister_agent：从桥接服务器移除A2A代理

{
  "name": "unregister_agent",
  "arguments": {
    "url": "http://localhost:41242"
  }
}

消息处理

send_message：向代理发送消息并获得响应的task_id

{
  "name": "send_message",
  "arguments": {
    "agent_url": "http://localhost:41242",
    "message": "USD到EUR的汇率是多少？",
    "session_id": "可选的会话ID"
  }
}

send_message_stream：发送消息并流式传输响应

{
  "name": "send_message_stream",
  "arguments": {
    "agent_url": "http://localhost:41242",
    "message": "给我讲一个关于AI代理的故事。",
    "session_id": "可选的会话ID"
  }
}

任务管理

get_task_result：使用任务ID检索任务结果

{
  "name": "get_task_result",
  "arguments": {
    "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1",
    "history_length": null
  }
}

cancel_task：取消正在运行的任务

{
  "name": "cancel_task",
  "arguments": {
    "task_id": "b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1"
  }
}

使用示例

基本工作流程

1. 客户端注册一个A2A代理
   ↓
2. 客户端向代理发送消息（获得task_id）
   ↓
3. 客户端使用task_id检索任务结果

示例：Claude作为MCP客户端

用户：注册一个位于http://localhost:41242的代理

Claude使用：register_agent(url="http://localhost:41242")
Claude：成功注册代理：ReimbursementAgent

用户：问代理它能做什么

Claude使用：send_message(agent_url="http://localhost:41242", message="你能做什么？")
Claude：我已发送您的消息。这是task_id：b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1

用户：获取我的问题的答案

Claude使用：get_task_result(task_id="b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1")
Claude：代理回复：“我可以帮助您处理报销请求。只需告诉我您需要报销什么，包括日期、金额和目的。”

架构

A2A MCP服务器由几个关键组件组成：

FastMCP服务器：向MCP客户端公开工具
A2A客户端：与已注册的A2A代理通信
任务管理器：处理任务转发和管理
代理卡抓取器：检索有关A2A代理的信息

通信流程

MCP客户端 → FastMCP服务器 → A2A客户端 → A2A代理
                   ↑                ↓
                   └──── 响应 ──┘

任务ID管理

当向A2A代理发送消息时，服务器：

生成一个唯一的task_id
将此ID映射到代理的URL，在task_agent_mapping字典中
返回task_id给MCP客户端
使用此映射来路由任务检索和取消请求

错误处理

服务器提供了常见问题的详细错误信息：

代理未注册
任务ID未找到
与代理的连接错误
响应解析错误

故障排除

代理注册问题

如果无法注册代理：

验证代理URL是否正确且可访问
检查代理是否有正确的代理卡在/.well-known/agent.json

消息传递问题

如果消息没有被送达：

确保代理已注册（使用list_agents）
验证代理是否正在运行且可访问

任务结果检索问题

如果无法检索任务结果：

确保您使用的是正确的task_id
检查是否经过了太长时间（某些代理可能会丢弃旧任务）

传输问题

如果遇到特定传输类型的故障：

stdio问题：确保输入/输出流未被重定向或修改
streamable-http问题：检查端口是否可用且未被防火墙阻止
sse问题：验证客户端是否支持服务器发送事件

Claude Desktop配置问题

如果Claude Desktop无法启动您的A2A-MCP-Server：

检查claude_desktop_config.json中的路径是否正确
验证Python是否在PATH中，如果使用"command": "python"
对于本地安装，确保PYTHONPATH正确
确保MCP_TRANSPORT在env部分设置为"stdio"
尝试手动运行命令，看看是否能在Claude之外正常运行
使用config_creator.py脚本进行自动路径检测和配置

开发

添加新工具方法

要为服务器添加新功能，请在a2a_mcp_server.py文件中添加装饰有@mcp.tool()的方法。

自定义任务管理器

服务器使用自定义的A2AServerTaskManager类，该类扩展了InMemoryTaskManager。您可以通过修改此类来自定义其行为。

项目结构

a2a-mcp-server/
├── a2a_mcp_server.py      # 主服务器实现
├── common/                # A2A协议代码（来自google/A2A）
│   ├── client/            # A2A客户端实现
│   ├── server/            # A2A服务器实现
│   ├── types.py           # 公共类型定义
│   └── utils/             # 工具函数
├── config_creator.py      # 帮助创建Claude Desktop配置的脚本
├── .gitignore             # Git忽略文件
├── pyproject.toml         # 项目元数据和依赖项
├── README.md              # 此文件
└── requirements.txt       # 项目依赖项

许可证

本项目根据Apache许可证，第2.0版发布 - 详情见LICENSE文件。

common/目录中的代码来自Google A2A项目，同样根据Apache许可证，第2.0版发布。

致谢

Anthropic为[模型上下文协议](https://modelcontextprotocol.io