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 庫的貢獻者