AIPI Bridge MCP

SSE-Transport-MCP-Server, der einen kuratierten Ausschnitt von Bot Army für externe MCP-Clients bereitstellt, die nur SSE sprechen – insbesondere die „Custom MCPs“-Skill-Konfiguration von AIPI, die SSE als einziges derzeit unterstütztes Format dokumentiert.

Bewusst schmal gehalten, kein generischer bridge.*-Durchgriff: Dies soll aus der Cloud eines Drittanbieters erreichbar sein (über ngrok), nicht aus einer vertrauenswürdigen lokalen Dev-Session. Daher werden genau drei Tools exponiert, statt einem Aufrufer zu erlauben, beliebige Bridge-Subjekte aufzurufen. Für lokale/vertrauenswürdige MCP-Clients, die die volle Oberfläche wünschen (beliebiges bridge.*-Subjekt, NATS observe, Registry-Abfragen), verwende stattdessen tools/nats-gateway-mcp – stdio-Transport, generisches bridge_request-Tool.

Tools

Bewusst nicht exponiert: bridge.task.update (ein falsch verstandener Sprachbefehl könnte stillschweigend Felder einer vorhandenen Aufgabe ändern, ohne Bestätigungsbildschirm – falls später gewünscht, auf status→completed beschränken, d.h. die Form von gtd_task_complete wiederverwenden statt offener Feldaktualisierungen) und bridge.project.* (bridge.project.list ist ein bekanntermaßen defekter Responder Stand 2026-08-15 – gibt leer zurück, obwohl Aufgaben project_ids tragen).

Related MCP server: Hermes MCP Bridge

Setup

1. Build (aus dem Repo-Root oder diesem Verzeichnis):

   cd tools/aipi-bridge-mcp && npm install && npm run build

2. Ausführen

   NATS_URL=nats://localhost:4222 \
   AIPI_BRIDGE_MCP_PORT=39895 \
   AIPI_BRIDGE_MCP_TOKEN=<pick-a-token> \
   npm start

   • AIPI_BRIDGE_MCP_TOKEN ist erforderlich, bevor dies extern getunnelt wird – ohne ist der SSE-Endpunkt unauthentifiziert. Der Server protokolliert beim Start eine Warnung, wenn es nicht gesetzt ist.

   • SSE-Endpunkt: GET /sse (erfordert Authorization: Bearer <token>), Nachrichten-Endpunkt: POST /messages?sessionId=..., Health-Check: GET /health (keine Authentifizierung).

3. Exponieren

   Gleiches Muster wie alles andere extern Erreichbare in diesem Repo: Tunnel über air.ngrok (Port-Label reservieren, z.B. surface-aipi-mcp), AIPIs Custom-MCP-Konfiguration auf die resultierende HTTPS-URL + /sse zeigen, mit dem Bearer-Token in dem Auth-Feld, das ihre SSE-MCP-Konfiguration bereitstellt.

Anforderungen

• Node.js 18+

• NATS-Server erreichbar unter NATS_URL – für echte Bridge-Antworten Produktion verwenden (nats://localhost:4222); bridge.chat / bridge.task.* haben nur Responder auf dem Produktionscluster, nicht auf Dev (4223).

Entwicklung

• npm run build – TypeScript nach dist/ kompilieren

• npm run dev – mit tsx ausführen (ohne Build) für schnelle Iteration

• Ende-zu-Ende gegen Dev-NATS (4223) mit einem Wegwerf-MCP-Client verifiziert: SSE-Handshake, tools/list und tools/call funktionieren alle korrekt; Tool-Aufrufe melden Fehler korrekt (NATS 503 no responders), statt einen Erfolg zu erfinden, da nichts auf bridge.chat / bridge.task.list im Dev-Cluster lauscht. Vollständige Happy-Path-Verifizierung erfordert einen Lauf gegen Produktions-NATS.