AIPI Bridge MCP

SSE 전송을 사용하는 MCP 서버로, Bot Army의 선별된 일부를 SSE만 지원하는 외부 MCP 클라이언트에 노출합니다. 특히 AIPI의 "Custom MCPs" 스킬 구성에서 SSE를 현재 유일하게 지원하는 형식으로 문서화하고 있습니다.

의도적으로 좁은 범위로, 일반적인 bridge.* 패스스루가 아닙니다. 이는 신뢰할 수 있는 로컬 개발 세션이 아닌 타사 공급업체의 클라우드(ngrok 통해)에서 접근 가능하도록 설계되었으므로, 호출자가 임의의 bridge 주제를 호출하는 대신 정확히 세 가지 도구만 노출합니다. 전체 표면(모든 bridge.* 주제, NATS observe, 레지스트리 쿼리)을 원하는 로컬/신뢰 MCP 클라이언트는 대신 tools/nats-gateway-mcp를 사용하세요 — stdio 전송, 일반 bridge_request 도구.

도구

의도적으로 노출하지 않음: bridge.task.update (잘못 들은 음성 명령이 확인 화면 없이 기존 작업의 필드를 조용히 변경할 수 있음 — 나중에 필요하다면 status→completed로만 범위를 제한하세요, 즉 gtd_task_complete의 형태를 재사용하고 개방형 필드 업데이트를 피하세요) 및 bridge.project.* (bridge.project.list는 2026-08-15 기준으로 알려진 고장 응답기입니다 — 작업이 project_ids를 가지고 있음에도 빈 값을 반환합니다).

Related MCP server: Hermes MCP Bridge

설정

1. 빌드 (저장소 루트 또는 이 디렉토리에서):

   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), AIPI의 Custom MCP 구성을 결과 HTTPS URL + /sse로 지정하고, SSE MCP 구성이 노출하는 인증 필드에 bearer 토큰을 넣습니다.

요구 사항

• Node.js 18+

• NATS_URL에서 접근 가능한 NATS 서버 — 실제 브리지 응답에는 프로덕션 (nats://localhost:4222)을 사용하세요; bridge.chat / bridge.task.*는 프로덕션 클러스터에만 응답기가 있으며 개발 (4223)에는 없습니다.

개발

• npm run build — TypeScript를 dist/로 컴파일

• npm run dev — 빌드 없이 tsx로 실행하여 빠른 반복

• 개발 NATS (4223)에 대해 임시 MCP 클라이언트로 종단 간 검증 완료: SSE 핸드셰이크, tools/list, tools/call 모두 올바르게 왕복합니다; 도구 호출은 개발 클러스터에서 bridge.chat / bridge.task.list를 수신하는 것이 없으므로 성공을 위조하는 대신 실패 (NATS 503 no responders)를 올바르게 보고합니다. 전체 해피 패스 검증은 프로덕션 NATS에 대한 실행이 필요합니다.