mcp-a2a-bridge

一个 MCP 服务器，可让编码代理 — GitHub Copilot CLI、Claude Code、Codex 和 Hermes — 调用远程 A2A 代理。它还包含一个可选的只读活动仪表板。

仓库：https://github.com/TonPC64/mcp-a2a-bridge

采用 MIT 许可证 授权。

关于编码代理的说明，请先阅读 AGENTS.md，然后使用 skills/setup/SKILL.md 进行安装，或使用 skills/contribute/SKILL.md 进行更改和提交 PR。

仪表板 UI 展示

可选的仪表板采用未来感 Liquid Glass 界面，包含紧凑的代理卡片、实时任务活动、双栏任务摘要、状态指示器和响应式布局。此截图使用选用式前端模拟数据模式，因此无需连接真实代理或暴露日志即可安全重现。

要在本地运行相同的模拟 UI：

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev:mock -- --host 127.0.0.1

模拟模式仅用于 UI 开发和截图；正常构建使用实时仪表板 API 和 SSE。

Related MCP server: agntcy-mcp-server

快速开始

选择你的安装配置

两种配置都需要 Python 3.11 或更高版本以及 uv。可选的仪表板前端需要 Node.js 24.15 或更高版本；CI 使用最新的 Node.js 24 版本。

仅 MCP

仅安装并运行 MCP 桥接器。这不需要 Node.js/npm 或仪表板前端构建。

git clone https://github.com/TonPC64/mcp-a2a-bridge.git mcp-a2a-bridge
cd mcp-a2a-bridge
uv sync --locked

MCP + 仪表板

安装可选的仪表板 Web 运行时，然后构建其打包的前端资源。Node.js 和 npm 仅在此构建（或前端开发）时需要，运行已构建好的仪表板则不需要。

git clone https://github.com/TonPC64/mcp-a2a-bridge.git mcp-a2a-bridge
cd mcp-a2a-bridge
uv sync --extra dashboard --locked
npm --prefix dashboard ci
npm --prefix dashboard run build

对于开发与测试，请使用 uv sync --all-extras --locked；它包含仪表板测试套件所需的 Python 包。下面的命令使用 /absolute/path/to/mcp-a2a-bridge。请将其替换为你克隆的绝对路径；不要复制其他用户的路径。

配置 A2A 代理

在仓库根目录创建 .a2a-agents.json：

{
  "agents": {
    "example-agent": {
      "url": "https://agent.example.invalid",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_YOUR_TOKEN"
      }
    }
  }
}

使用 A2A 代理的基本 URL；桥接器会自动请求其 /.well-known/agent-card.json。当代理不需要身份验证时，请移除 Authorization（或使用空的 headers 对象）。注册表可能包含机密信息，因此请勿提交它，并在适当情况下限制其文件权限。

注册表位置按以下顺序解析：

1. A2A_BRIDGE_CONFIG

2. 桥接器进程当前目录中的 .a2a-agents.json

3. ~/.config/a2a-bridge/agents.json

对于在仓库之外启动 MCP 命令的主机，请在该主机的 MCP 环境中将 A2A_BRIDGE_CONFIG 设置为绝对路径。你也可以在运行时使用 a2a_add_agent 添加已验证的代理；默认情况下它会写入已解析的注册表文件。

注册 MCP 服务器

每个主机都应运行相同的本地检出命令：

uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

这会使用上面创建的可编辑（editable）安装。请使用以下可移植路径占位符配置主机。

GitHub Copilot CLI — 将此服务器添加到 ~/.copilot/mcp-config.json：

{
  "mcpServers": {
    "a2a": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-a2a-bridge",
        "mcp-a2a-bridge"
      ]
    }
  }
}

Claude Code：

claude mcp add a2a -- uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

Codex — 将此添加到 ~/.codex/config.toml：

[mcp_servers.a2a]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/mcp-a2a-bridge", "mcp-a2a-bridge"]

**Hermes：**使用其 MCP 服务器注册 UI 或命令，选择 stdio 服务器，并提供命令 uv 及以下参数：

run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

注册后重启主机，然后调用 a2a_list_agents 以确认注册表可用且代理可访问。

工具

a2a_send_message 最多等待 timeout_s（默认 60 秒）。如果任务仍在运行，它会返回 done: false 并附带 task_id；可使用 a2a_get_task 进行轮询。如果代理返回 state: "input_required"，请使用相同的 task_id 再次调用 a2a_send_message。

仪表板

可选的独立仪表板显示已配置的代理、其状态/技能，以及同一台机器上桥接器进程的实时任务活动。它是只读的：绝不会向代理发送消息。

在启动之前安装 dashboard 配置并构建资源：

cd /absolute/path/to/mcp-a2a-bridge
uv sync --extra dashboard --locked
npm --prefix dashboard ci
npm --prefix dashboard run build
uv run mcp-a2a-bridge-dashboard

默认情况下，它只监听 127.0.0.1:9100。请在同一个机器上打开 http://127.0.0.1:9100。

前端模拟数据

要在没有 Python 服务或 SSE 的情况下运行仪表板 UI，请使用选用式模拟模式。它包含用于截图的代表性代理和任务活动：

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev:mock -- --host 0.0.0.0

在同一网络上打开 Vite URL。VITE_USE_MOCK_DATA=true 仅由前端构建/开发服务器使用；正常的 npm run dev 和生产构建继续使用实时仪表板 API 和 SSE。

对于每个希望其活动显示在仪表板中的桥接器进程，请启用上报。将此环境变量添加到 MCP 服务器配置中（或在手动启动时添加）：

A2A_BRIDGE_DASHBOARD=1 uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

没有该标志的桥接器进程会将活动保存在内存中，并且不会出现在共享仪表板中。仪表板可以在此之前或之后启动。

LAN 部署

可以通过设置明确的非回环（non-loopback）绑定，有意将仪表板暴露在受信任的 LAN 上而无需令牌。此模式没有身份验证，因此仅在私有、受信任的网络上使用；切勿将其暴露到公共互联网。

对于受保护的 LAN 访问，请设置强令牌，并将服务置于具有自身网络访问控制的 TLS 终止反向代理之后：

export A2A_BRIDGE_DASHBOARD_HOST=0.0.0.0
export A2A_BRIDGE_DASHBOARD_TOKEN="$(openssl rand -hex 32)"
uv run mcp-a2a-bridge-dashboard

设置令牌后，仪表板 HTML、静态资源、API 路由和 SSE 路由都需要它。浏览器用户只需在 /login 输入一次；由此产生的 HttpOnly、同站（same-site）会话 cookie 让 EventSource 可以正常重新连接。API 客户端也可以改为发送 Authorization: Bearer <token>。该服务绝不会记录令牌。令牌可验证访问身份，但不会加密流量，因此请勿在不受信任的网络中使用直接的 HTTP LAN 端点；请在反向代理处使用 HTTPS。

对于 macOS，launchd/com.example.a2a-bridge-dashboard.plist 模板可以在登录时运行仪表板。在将其作为 LaunchAgent 安装之前，请替换其中的 __REPO__ 和 __HOME__ 占位符。

仪表板前端开发

只有在前端开发或重建其打包资源时才需要 Node.js 24.15+ 和 npm：

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev

Vite 会打印开发 URL（通常是 http://localhost:5173）。使用 npm run build 构建 Python 仪表板所需的资源。

Copilot A2A 服务器

捆绑的服务器需要经过身份验证的 copilot CLI：

copilot-a2a-agent --port 9002 --cwd /path/to/default/repository

它绑定到 127.0.0.1，因为它使用 --allow-all-tools 运行 Copilot。其传入活动可以使用相同的选用式共享 SQLite 存储，并在仪表板中显示来源和目标字段。

仪表板还可以在不修改 Hermes 的情况下读取 Hermes 的原生审计文件。它首先检查 A2A_BRIDGE_HERMES_AUDIT，然后检查 $HERMES_HOME/a2a_audit.jsonl，最后检查 ~/.hermes/a2a_audit.jsonl。

开发与测试

在仓库根目录运行 Python 测试套件：

uv sync --all-extras --locked
uv run pytest -v

从 dashboard/ 运行仪表板测试或进行生产仪表板构建：

npm test
npm run build

CI 在 Python 3.11 上运行 Python 测试套件，验证 uv.lock，并在最新的 Node.js 24 版本上运行仪表板安装、测试和生产构建。

tests/test_integration.py 在进程内运行一个 A2A 代理，并端到端地测试桥接器。