A2A MCP Server

🚀 A2A MCP 服务器

A2A MCP 服务器是一个用于连接模型上下文协议（MCP）和代理到代理（A2A）协议的服务器，它能让支持 MCP 的 AI 助手（如 Claude）与 A2A 代理实现无缝交互。

🚀 快速开始

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

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

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

演示

1. 运行 A2A 示例中的货币代理

也支持云部署的代理

2. 使用 Claude 注册货币代理

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

✨ 主要特性

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

📦 安装指南

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude Desktop 的 A2A 桥接服务器，请执行以下命令：

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

选项 1：从 PyPI 安装

pip install a2a-mcp-server

选项 2：本地安装

1. 克隆仓库：

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

2. 设置虚拟环境：

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

3. 安装依赖项：

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 服务器支持多种传输类型：

1. stdio（默认）：使用标准输入/输出进行通信

• 适用于命令行使用和测试
• 不启动 HTTP 服务器
• Claude Desktop 必需

2. streamable - http（推荐用于 Web 客户端）：支持流式传输的 HTTP 传输

• 推荐用于生产部署
• 启动一个 HTTP 服务器来处理 MCP 请求
• 支持大响应的流式传输

3. 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、脚本和仓库路径
• 配置 Claude Desktop 所需的 stdio 传输
• 允许你根据需要添加任何其他环境变量
• 创建或更新你的 Claude Desktop 配置文件

完整示例

以下是一个配置了 A2A - MCP - Server 的完整 claude_desktop_config.json 文件示例：

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

与 MCP 客户端一起使用

Claude

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

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

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

2. 对于 Claude Web：在 Claude 网页界面的“工具”菜单中启用 MCP URL 连接。

• 使用 URL：http://127.0.0.1:8000/mcp

3. 对于 Claude Desktop：按照上述说明将配置添加到你的 claude_desktop_config.json 文件中。最简单的方法是使用提供的 config_creator.py 脚本，它将自动检测路径并创建正确的配置。
4. 在 Claude 中，你现在可以使用以下功能： 注册 A2A 代理：

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

向代理发送消息：

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

检索任务结果：

你能获取任务 ID 为 550e8400 - e29b - 41d4 - a716 - 446655440000 的结果吗？

Cursor IDE

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

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

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

2. 在 Cursor IDE 中，转到“设置”>“AI”>“MCP 服务器”

• 添加一个新的 MCP 服务器，URL 为：http://127.0.0.1:8000/mcp
• 启用该服务器

3. 现在你可以在 Cursor 的 AI 助手中使用 A2A 工具。

Windsurf 浏览器

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

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

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

2. 在 Windsurf 浏览器中，转到“设置”>“MCP 连接”

• 添加一个新的 MCP 连接，URL 为：http://127.0.0.1:8000/mcp
• 启用该连接

3. 现在你可以在 Windsurf 的 AI 助手中使用 A2A 工具。

可用的 MCP 工具

服务器公开了以下 MCP 工具，用于与 Claude 等大语言模型集成：

代理管理

• 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：向代理发送消息并获取响应的任务 ID

{
  "name": "send_message",
  "arguments": {
    "agent_url": "http://localhost:41242",
    "message": "美元兑欧元的汇率是多少？",
    "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. 客户端向代理发送消息（获取任务 ID）
   ↓
3. 客户端使用任务 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：我已发送你的消息。这是任务 ID：b30f3297 - e7ab - 4dd9 - 8ff1 - 877bd7cfb6b1

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

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

🔧 技术细节

架构

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

1. FastMCP 服务器：向 MCP 客户端公开工具
2. A2A 客户端：与已注册的 A2A 代理通信
3. 任务管理器：处理任务转发和管理
4. 代理卡片获取器：检索 A2A 代理的信息

通信流程

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

任务 ID 管理

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

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

错误处理

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

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

故障排除

代理注册问题

如果无法注册代理：

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

消息传递问题

如果消息未送达：

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

任务结果检索问题

如果无法检索任务结果：

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

传输问题

如果特定传输类型出现问题：

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

Claude Desktop 配置问题

如果 Claude Desktop 未启动你的 A2A - MCP - Server：

• 检查 claude_desktop_config.json 中的路径是否正确
• 如果使用 "command": "python"，验证 Python 是否在你的 PATH 中
• 对于本地安装，确保 PYTHONPATH 正确
• 确保 env 部分中的 MCP_TRANSPORT 设置为 "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 提供的 模型上下文协议
• Google 提供的 代理到代理协议
• FastMCP 库的贡献者