AIPI Bridge MCP

Servidor MCP con transporte SSE que expone un subconjunto seleccionado de Bot Army a clientes MCP externos que solo hablan SSE, específicamente la configuración de habilidad "Custom MCPs" de AIPI, que documenta SSE como el único formato compatible actualmente.

Deliberadamente limitado, no es un paso genérico de bridge.*: está pensado para ser accesible desde la nube de un proveedor externo (a través de ngrok), no desde una sesión de desarrollo local de confianza, por lo que expone exactamente tres herramientas en lugar de permitir que un llamador invoque sujetos arbitrarios de bridge. Para clientes MCP locales/de confianza que quieran la superficie completa (cualquier sujeto bridge.*, observación NATS, consultas de registro), usa tools/nats-gateway-mcp en su lugar: transporte stdio, herramienta genérica bridge_request.

Herramientas

Deliberadamente no expuestos: bridge.task.update (un comando de voz malinterpretado podría mutar silenciosamente los campos de una tarea existente sin pantalla de confirmación; si se quiere más adelante, limítalo a status→completed únicamente, es decir, reutiliza la forma de gtd_task_complete en lugar de actualizaciones de campos abiertas) y bridge.project.* (bridge.project.list es un respondedor conocido por estar roto a partir del 2026-08-15: devuelve vacío a pesar de que las tareas llevan project_id).

Related MCP server: Hermes MCP Bridge

Configuración

1. Compilar (desde la raíz del repositorio o desde este directorio):

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

2. Ejecutar

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

   • AIPI_BRIDGE_MCP_TOKEN es obligatorio antes de exponer esto externamente; sin él, el endpoint SSE no está autenticado. El servidor registra una advertencia al inicio si no está configurado.

   • Endpoint SSE: GET /sse (requiere Authorization: Bearer <token>), endpoint de mensajes: POST /messages?sessionId=..., verificación de salud: GET /health (sin autenticación).

3. Exponerlo

   Mismo patrón que todo lo demás accesible externamente en este repositorio: túnel a través de air.ngrok (reserva una etiqueta de puerto, p. ej. surface-aipi-mcp), apunta la configuración de Custom MCP de AIPI a la URL HTTPS resultante + /sse, con el token de portador en el campo de autenticación que exponga su configuración SSE de MCP.

Requisitos

• Node.js 18+

• Servidor NATS accesible en NATS_URL: usa producción (nats://localhost:4222) para respuestas reales del bridge; bridge.chat / bridge.task.* solo tienen respondedores en el clúster de producción, no en desarrollo (4223).

Desarrollo

• npm run build: compila TypeScript a dist/

• npm run dev: ejecuta con tsx (sin compilación) para iteración rápida

• Verificado de extremo a extremo contra NATS de desarrollo (4223) con un cliente MCP desechable: el handshake SSE, tools/list y tools/call funcionan correctamente; las llamadas a herramientas informan correctamente fallos (NATS 503 no responders) en lugar de inventar un éxito, ya que nada escucha en bridge.chat / bridge.task.list en el clúster de desarrollo. La verificación completa del camino feliz requiere una ejecución contra NATS de producción.