mcp-a2a-bridge

MCP-сервер, который позволяет кодинг-агентам — GitHub Copilot CLI, Claude Code, Codex и Hermes — вызывать удалённых агентов A2A. Он также включает опциональную панель активности в режиме только для чтения.

Репозиторий: https://github.com/TonPC64/mcp-a2a-bridge

Лицензировано на условиях MIT License.

Инструкции для кодинг-агентов: начните с AGENTS.md, затем используйте skills/setup/SKILL.md для установки или skills/contribute/SKILL.md для изменений и PR.

Демонстрация UI дашборда

Опциональный дашборд использует футуристический интерфейс Liquid Glass с компактными карточками агентов, живой активностью задач, двухколоночными сводками задач, индикаторами состояния и адаптивными макетами. На этом скриншоте используется opt-in режим mock-данных фронтенда, поэтому его можно безопасно воспроизводить без подключения к реальным агентам и без раскрытия логов.

Чтобы запустить такой же mock-интерфейс локально:

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

Mock-режим предназначен только для разработки 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 + дашборд

Установите опциональный веб-рантайм дашборда, затем соберите его встроенные ресурсы фронтенда. 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"
      }
    }
  }
}

Используйте базовый URL агента A2A; мост автоматически запрашивает /.well-known/agent-card.json этого агента. Удалите Authorization (или используйте пустой объект headers), если агенту не требуется аутентификация. Реестр может содержать секреты, поэтому не коммитьте его и при необходимости ограничьте права доступа к файлу.

Расположение реестра определяется в следующем порядке:

1. A2A_BRIDGE_CONFIG

2. .a2a-agents.json в текущем каталоге процесса моста

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

Для хоста, который запускает команду MCP вне репозитория, укажите A2A_BRIDGE_CONFIG как абсолютный путь в MCP-окружении этого хоста. Вы также можете добавить проверенного агента во время выполнения с помощью a2a_add_agent; по умолчанию он записывает данные в итоговый файл реестра.

Регистрация MCP-сервера

Каждый хост должен запускать одну и ту же команду для локального клона:

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

Здесь используется установка в режиме редактирования, созданная выше. Настройте хост с помощью следующего переносимого заполнителя пути.

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-сервера, выберите сервер 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", вызовите a2a_send_message ещё раз с тем же task_id.

Дашборд

Опциональный автономный дашборд показывает настроенных агентов, их статусы/навыки и активность задач в реальном времени от процессов моста на той же машине. Он только для чтения: никогда не отправляет сообщения агентам.

Установите профиль 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 на той же машине.

Mock-данные фронтенда

Чтобы запустить UI дашборда без Python-сервиса и SSE, используйте opt-in mock-режим. Он включает репрезентативных агентов и активность задач для скриншотов:

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

Откройте URL-адрес Vite в той же сети. VITE_USE_MOCK_DATA=true используется только фронтенд-сборкой и dev-сервером; обычные npm run dev и продакшн-сборки продолжают использовать живой API дашборда и SSE.

Включите запись активности для каждого процесса моста, чья активность должна отображаться в дашборде. Добавьте эту переменную окружения в конфигурацию MCP-сервера (или при его ручном запуске):

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

Процессы моста без этого флага сохраняют активность в памяти и не отображаются в общем дашборде. Дашборд можно запускать до или после них.

Развёртывание в LAN

Дашборд можно намеренно открыть в доверенной LAN без токена, задав явную привязку не к loopback-адресу. В этом режиме нет аутентификации, поэтому используйте его только в частной доверенной сети; никогда не открывайте его в публичный интернет.

Для защищённого доступа через 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 может запускать дашборд при входе в систему. Замените его плейсхолдеры __REPO__ и __HOME__ перед установкой в качестве LaunchAgent.

Разработка фронтенда дашборда

Node.js 24.15+ и npm требуются только для работы с фронтендом или пересборки его встроенных ресурсов:

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

Vite выводит URL для разработки (обычно http://localhost:5173). Соберите ресурсы, используемые Python-дашбордом, командой npm run build.

A2A-сервер Copilot

Встроенный сервер требует аутентифицированный CLI copilot:

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

Он привязывается к 127.0.0.1, потому что запускает Copilot с флагом --allow-all-tools. Его входящая активность может использовать ту же opt-in общую 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-набор на Python 3.11, проверяет uv.lock и выполняет установку дашборда, тесты и продакшн-сборку на последнем выпуске Node.js 24.

tests/test_integration.py запускает агента A2A в том же процессе и сквозным образом проверяет работу моста.