mcp-a2a-bridge

Ein MCP-Server, der Coding-Agenten – GitHub Copilot CLI, Claude Code, Codex und Hermes – den Aufruf entfernter A2A-Agenten ermöglicht. Er enthält außerdem ein optionales, schreibgeschütztes Aktivitäts-Dashboard.

Repository: https://github.com/TonPC64/mcp-a2a-bridge

Lizenziert unter der MIT-Lizenz.

Anweisungen für Coding-Agenten finden Sie in AGENTS.md; für die Installation nutzen Sie skills/setup/SKILL.md, für Änderungen und Pull Requests skills/contribute/SKILL.md.

Dashboard-UI-Showcase

Das optionale Dashboard verwendet eine futuristische Liquid-Glass-Oberfläche mit kompakten Agent-Karten, Live-Task-Aktivität, zweispaltigen Task-Zusammenfassungen, Statusanzeigen und responsiven Layouts. Dieser Screenshot verwendet den opt-in Frontend-Mock-Datenmodus, sodass er ohne Verbindung zu echten Agenten oder Offenlegung von Logs reproduziert werden kann.

So führen Sie dieselbe Mock-UI lokal aus:

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

Der Mock-Modus ist nur für die UI-Entwicklung und Screenshots gedacht; normale Builds verwenden die Live-Dashboard-API und SSE.

Related MCP server: agntcy-mcp-server

Erste Schritte

Setup-Variante wählen

Beide Profile benötigen Python 3.11 oder neuer und uv. Das optionale Dashboard-Frontend erfordert Node.js 24.15 oder neuer; CI verwendet die neueste Node.js-24-Version.

Nur MCP

Nur die MCP-Bridge installieren und ausführen. Das erfordert kein Node.js/npm und keinen Dashboard-Frontend-Build.

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

MCP + Dashboard

Die optionale Dashboard-Web-Runtime installieren und anschließend die gebündelten Frontend-Assets erstellen. Node.js und npm werden nur für diesen Build (oder die Frontend-Entwicklung) benötigt, nicht zum Ausführen eines bereits erstellten Dashboards.

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

Für Entwicklung und Tests verwenden Sie uv sync --all-extras --locked; es enthält die Python-Pakete, die die Dashboard-Testsuite benötigt. Die Befehle unten verwenden /absolute/path/to/mcp-a2a-bridge. Ersetzen Sie dies durch den absoluten Pfad zu Ihrem Klon; übernehmen Sie nicht den Pfad eines anderen Benutzers.

A2A-Agenten konfigurieren

Erstellen Sie .a2a-agents.json im Repository-Stammverzeichnis:

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

Verwenden Sie die Basis-URL eines A2A-Agenten; die Bridge ruft dessen /.well-known/agent-card.json automatisch ab. Entfernen Sie Authorization (oder verwenden Sie ein leeres headers-Objekt), wenn der Agent keine Authentifizierung erfordert. Die Registry kann Geheimnisse enthalten – committen Sie sie daher nicht und schränken Sie ihre Dateiberechtigungen gegebenenfalls ein.

Der Registry-Speicherort wird in dieser Reihenfolge aufgelöst:

1. A2A_BRIDGE_CONFIG

2. .a2a-agents.json im aktuellen Verzeichnis des Bridge-Prozesses

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

Für einen Host, der den MCP-Befehl außerhalb des Repositorys startet, setzen Sie A2A_BRIDGE_CONFIG auf einen absoluten Pfad in der MCP-Umgebung dieses Hosts. Sie können zur Laufzeit auch einen verifizierten Agenten mit a2a_add_agent hinzufügen; standardmäßig schreibt dieser in die aufgelöste Registry-Datei.

MCP-Server registrieren

Jeder Host sollte denselben lokalen Checkout-Befehl starten:

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

Dies verwendet die oben erstellte editierbare Installation. Konfigurieren Sie den Host mit dem folgenden portablen Pfad-Platzhalter.

GitHub Copilot CLI – fügen Sie diesen Server zu ~/.copilot/mcp-config.json hinzu:

{
  "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 – fügen Sie dies zu ~/.codex/config.toml hinzu:

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

Hermes: Verwenden Sie die MCP-Server-Registrierungs-UI oder den entsprechenden Befehl, wählen Sie einen stdio-Server und geben Sie den Befehl uv mit diesen Argumenten an:

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

Starten Sie den Host nach der Registrierung neu und rufen Sie a2a_list_agents auf, um zu bestätigen, dass die Registry verfügbar und die Agenten erreichbar sind.

Tools

a2a_send_message wartet bis zu timeout_s (standardmäßig 60 Sekunden). Wenn ein Task noch läuft, gibt es done: false mit einer task_id zurück; fragen Sie ihn mit a2a_get_task ab. Wenn ein Agent state: "input_required" zurückgibt, rufen Sie a2a_send_message erneut mit derselben task_id auf.

Dashboard

Das optionale eigenständige Dashboard zeigt konfigurierte Agenten, deren Status/Skills und Live-Task-Aktivität von Bridge-Prozessen auf demselben Rechner. Es ist schreibgeschützt: Es sendet niemals Nachrichten an Agenten.

Installieren Sie das Profil dashboard und erstellen Sie die Assets, bevor Sie es starten:

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

Es lauscht standardmäßig nur auf 127.0.0.1:9100. Öffnen Sie http://127.0.0.1:9100 auf demselben Rechner.

Frontend-Mock-Daten

Um die Dashboard-UI ohne den Python-Dienst oder SSE auszuführen, verwenden Sie den opt-in Mock-Modus. Er enthält repräsentative Agenten und Task-Aktivität für Screenshots:

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

Öffnen Sie die Vite-URL im selben Netzwerk. VITE_USE_MOCK_DATA=true wird nur vom Frontend-Build/Dev-Server verwendet; normale npm run dev- und Produktions-Builds verwenden weiterhin die Live-Dashboard-API und SSE.

Aktivieren Sie das Reporting für jeden Bridge-Prozess, dessen Aktivität im Dashboard erscheinen soll. Fügen Sie diese Umgebungsvariable zur MCP-Server-Konfiguration hinzu (oder setzen Sie sie beim manuellen Start):

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

Bridge-Prozesse ohne dieses Flag behalten die Aktivität im Arbeitsspeicher und erscheinen nicht im gemeinsamen Dashboard. Das Dashboard kann vor oder nach ihnen gestartet werden.

LAN-Bereitstellung

Das Dashboard kann absichtlich in einem vertrauenswürdigen LAN ohne Token bereitgestellt werden, indem ein expliziter Nicht-Loopback-Bind gesetzt wird. Dieser Modus hat keine Authentifizierung – verwenden Sie ihn nur in einem privaten, vertrauenswürdigen Netzwerk; setzen Sie ihn niemals dem öffentlichen Internet aus.

Für geschützten LAN-Zugriff setzen Sie ein starkes Token und platzieren Sie den Dienst hinter einem TLS-terminierenden Reverse-Proxy mit eigenen Netzwerkzugriffskontrollen:

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

Wenn ein Token gesetzt ist, erfordern Dashboard-HTML, statische Assets, API-Routen und SSE-Routen es alle. Browser-Benutzer geben es einmal unter /login ein; das resultierende HttpOnly-Same-Site-Sitzungscookie ermöglicht EventSource, sich normal zu verbinden. API-Clients können stattdessen Authorization: Bearer <token> senden. Der Dienst protokolliert das Token niemals. Ein Token authentifiziert den Zugriff, verschlüsselt aber keinen Datenverkehr – verwenden Sie den direkten HTTP-LAN-Endpunkt daher nicht über nicht vertrauenswürdige Netzwerke; verwenden Sie HTTPS am Reverse-Proxy.

Für macOS kann die Vorlage launchd/com.example.a2a-bridge-dashboard.plist das Dashboard bei der Anmeldung ausführen. Ersetzen Sie die Platzhalter __REPO__ und __HOME__, bevor Sie sie als LaunchAgent installieren.

Dashboard-Frontend-Entwicklung

Node.js 24.15+ und npm werden nur benötigt, um am Frontend zu arbeiten oder die gebündelten Assets neu zu erstellen:

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

Vite gibt die Entwicklungs-URL aus (normalerweise http://localhost:5173). Erstellen Sie die vom Python-Dashboard verwendeten Assets mit npm run build.

Copilot-A2A-Server

Der gebündelte Server erfordert eine authentifizierte copilot-CLI:

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

Er bindet an 127.0.0.1, weil er Copilot mit --allow-all-tools ausführt. Seine eingehende Aktivität kann denselben opt-in gemeinsam genutzten SQLite-Speicher verwenden und wird im Dashboard mit Quell- und Ziel-Feldern angezeigt.

Das Dashboard kann auch Hermes' native Audit-Datei lesen, ohne Hermes zu verändern. Es prüft A2A_BRIDGE_HERMES_AUDIT, dann $HERMES_HOME/a2a_audit.jsonl, dann ~/.hermes/a2a_audit.jsonl.

Entwicklung und Tests

Führen Sie die Python-Testsuite aus dem Repository-Stammverzeichnis aus:

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

Führen Sie Dashboard-Tests aus oder erstellen Sie einen Produktions-Dashboard- Build aus dashboard/:

npm test
npm run build

CI führt die Python-Suite unter Python 3.11 aus, validiert uv.lock und führt die Dashboard-Installation, Tests und den Produktions-Build unter der neuesten Node.js-24-Version aus.

tests/test_integration.py führt einen A2A-Agenten prozessintern aus und testet die Bridge Ende-zu-Ende.