AIPI Bridge MCP

SSE-транспортный MCP-сервер, предоставляющий выбранный срез Bot Army внешним MCP-клиентам, которые говорят только на SSE — в частности, конфигурации навыка "Custom MCPs" от AIPI, в которой указано, что SSE — единственный поддерживаемый на данный момент формат.

Намеренно узкий, не универсальный пропуск bridge.*: он предназначен для доступа из облака стороннего поставщика (через ngrok), а не из доверенной локальной сессии разработки, поэтому он предоставляет ровно три инструмента, а не позволяет вызывающему обращаться к произвольным субъектам bridge. Для локальных/доверенных MCP-клиентов, которым нужна полная поверхность (любой субъект bridge.*, NATS observe, запросы к реестру), используйте tools/nats-gateway-mcp — stdio-транспорт, универсальный инструмент bridge_request.

Tools

Намеренно не предоставляется: bridge.task.update (неправильно расслышанная голосовая команда может молча изменить поля существующей задачи без экрана подтверждения — если понадобится позже, ограничьте его только status→completed, т.е. используйте форму gtd_task_complete, а не открытые обновления полей) и bridge.project.* (bridge.project.list — известный сломанный ответчик по состоянию на 2026-08-15 — возвращает пусто, несмотря на то, что задачи содержат project_ids).

Related MCP server: Hermes MCP Bridge

Setup

1. Build (from repo root or this directory):

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

2. Запуск

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

   • AIPI_BRIDGE_MCP_TOKEN обязателен перед туннелированием этого наружу — без него SSE-эндпоинт не аутентифицирован. Сервер выводит предупреждение при запуске, если он не задан.

   • SSE-эндпоинт: GET /sse (требуется Authorization: Bearer <token>), эндпоинт сообщений: POST /messages?sessionId=..., проверка здоровья: GET /health (без аутентификации).

3. Откройте доступ

   Та же схема, что и для всего остального, доступного извне в этом репозитории: туннелируйте через air.ngrok (зарезервируйте метку порта, например surface-aipi-mcp), укажите конфигурацию Custom MCP от AIPI на полученный HTTPS URL + /sse, с bearer-токеном в том поле аутентификации, которое предоставляет их конфигурация SSE MCP.

Требования

• Node.js 18+

• NATS-сервер, доступный по NATS_URL — используйте прод (nats://localhost:4222) для реальных ответов bridge; bridge.chat / bridge.task.* имеют ответчиков только на производственном кластере, а не на dev (4223).

Разработка

• npm run build — компиляция TypeScript в dist/

• npm run dev — запуск с tsx (без сборки) для быстрой итерации

• Проверено end-to-end против dev NATS (4223) с одноразовым MCP-клиентом: рукопожатие SSE, tools/list и tools/call корректно проходят; вызовы инструментов корректно сообщают об ошибке (NATS 503 no responders), а не фабрикуют успех, поскольку на dev-кластере никто не слушает bridge.chat / bridge.task.list. Полная проверка happy-path требует запуска против прод NATS.