A2A MCP Server

🚀 A2A MCP 服务器

本项目是一个 MCP 服务器，它架起了模型上下文协议（MCP）与代理到代理（A2A）协议之间的桥梁，使得兼容 MCP 的 AI 助手（如 Claude）能够与 A2A 代理实现无缝交互。

🚀 快速开始

A2A MCP 服务器作为连接 Model Context Protocol (MCP) 和 Agent-to-Agent (A2A) 协议的桥梁，让 MCP 兼容的 AI 助手（如 Claude）能与 A2A 代理无缝交互。以下是使用该服务器的快速步骤：

1. 安装：可通过 Smithery 自动安装，或从 PyPI 安装，也能进行本地安装。
2. 配置：使用环境变量配置服务器运行方式，并选择合适的传输类型。
3. 运行：从命令行启动服务器，可根据需求指定参数。
4. 配置客户端：在 Claude Desktop、Claude Web、Cursor IDE 或 Windsurf Browser 中配置 MCP 服务器。
5. 使用：在客户端中使用提供的 MCP 工具与 A2A 代理交互。

安装方式

通过 Smithery 安装

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

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

从 PyPI 安装

pip install a2a-mcp-server

本地安装

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

• 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 需要通过 stdio 与 MCP 服务器通信。

方法 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"
      ]
    }
  }
}

✨ 主要特性

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

📦 安装指南

通过 Smithery 安装

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

从 PyPI 安装

pip install a2a-mcp-server

本地安装

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

💻 使用示例

基础用法

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="What can you do?")
Claude：我已发送你的消息。这是任务 ID：b30f3297-e7ab-4dd9-8ff1-877bd7cfb6b1

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

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

📚 详细文档

可用的 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": "What's the exchange rate from USD to EUR?",
    "session_id": "optional-session-id"
  }
}

• send_message_stream：发送消息并流式接收响应

{
  "name": "send_message_stream",
  "arguments": {
    "agent_url": "http://localhost:41242",
    "message": "Tell me a story about AI agents.",
    "session_id": "optional-session-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"
  }
}

与 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 Browser

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 工具。

🔧 技术细节

架构

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

• FastMCP 服务器：向 MCP 客户端暴露工具。
• A2A 客户端：与已注册的 A2A 代理通信。
• 任务管理器：处理任务转发和管理。
• 代理卡片获取器：检索 A2A 代理的信息。

通信流程

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

任务 ID 管理

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

1. 生成唯一的 task_id。
2. 将该 ID 映射到代理的 URL，存储在 task_agent_mapping 字典中。
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 是否在系统路径中。
• 对于本地安装，确保 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 提供的 Model Context Protocol。
• Google 提供的 Agent-to-Agent Protocol。
• FastMCP 库的贡献者。