incidentrelay-mcp

IncidentRelay용 MCP 서버 — 자체 호스팅 온콜 스케줄링, 알림 라우팅, 인시던트 관리를 위한 도구입니다.

IncidentRelay의 **전체 REST API(279개 작업)**을 MCP 클라이언트(Claude Desktop, Claude Code, Cursor, …)에 두 계층을 통해 노출합니다:

• 3개의 게이트웨이 도구 — 서버 자체 OpenAPI 문서를 기반으로 모든 작업에 접근할 수 있게 합니다.

• 25개의 큐레이션 도구 — 일반적인 온콜 워크플로(알림 확인/해결, 인시던트, 온콜 일정, 사일런스, 유지보수 창)를 타입이 지정된 인체공학적 입력으로 감쌉니다.

서버는 IncidentRelay를 절대 수정하지 않습니다. 사용자가 제공한 베어러 토큰으로 인증하는 순수 REST 클라이언트입니다.

실행

설치할 필요 없음 — npx(Node.js ≥ 20)로 실행하세요:

# from GitHub (works today)
IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=<token> \
  npx -y github:NikGariel/IncidentRelay-mcp

# from npm (after the package is published)
IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=<token> \
  npx -y incidentrelay-mcp

npx는 첫 실행 시 패키지를 자동으로 빌드합니다(prepare 스크립트가 TypeScript를 컴파일), 별도의 빌드 단계가 필요하지 않습니다.

소스에서

npm install   # runs the build via the prepare script
npm start

구성

서버에는 IncidentRelay 기본 URL과 베어러 토큰(IncidentRelay의 Profile → API tokens에서 허용하려는 범위로 생성한 JWT 액세스 토큰 또는 개인 API 토큰)이 필요합니다.

¹ 토큰은 쓰기 작업을 호출하지 않는 경우에만 선택 사항입니다.

시작 시 서버는 {IR_BASE_URL}/api/openapi.json(공개 엔드포인트)을 가져와 작업 카탈로그를 구축하므로 항상 배포된 IncidentRelay 버전과 일치합니다. 이 가져오기가 실패하면 번들된 스냅샷으로 대체하고 경고를 기록합니다.

Claude Desktop / Claude Code와 함께 사용(stdio)

MCP 클라이언트 설정(예: claude_desktop_config.json)에 추가하세요.

권장 — 사전 빌드된 바이너리를 직접 실행 (0.5초 이내 시작되므로 클라이언트의 시작 제한 시간에 걸리지 않습니다):

{
  "mcpServers": {
    "incidentrelay": {
      "command": "node",
      "args": ["/absolute/path/to/incidentrelay-mcp/dist/index.js"],
      "env": {
        "IR_BASE_URL": "https://incidentrelay.example.com",
        "IR_TOKEN": "<personal-api-token>"
      }
    }
  }
}

npm install && npm run build(또는 npm install -g .)로 한 번 빌드하세요.

대안 — npx. npm에 게시된 후:

{ "command": "npx", "args": ["-y", "incidentrelay-mcp"], "env": { "…": "…" } }

⚠️ 클라이언트 설정에서 npx -y github:…를 피하세요: 첫 실행 시 저장소를 클론하고 의존성을 설치하며 TypeScript를 컴파일하므로, 콜드 캐시에서 MCP 클라이언트의 ~30초 연결 제한 시간을 초과할 수 있습니다. 필요할 때 서버를 생성하는 클라이언트에는 사전 빌드된 바이너리(또는 게시 후 npm 형태)를 사용하세요.

서버 자체는 네트워크와 무관하게 즉시 시작됩니다: 번들된 OpenAPI 스냅샷을 동기적으로 로드한 다음, 백그라운드에서 라이브 서버의 카탈로그를 새로 고칩니다.

HTTP를 통한 사용(Streamable HTTP)

IR_BASE_URL=https://incidentrelay.example.com IR_TOKEN=... \
  npx -y github:NikGariel/IncidentRelay-mcp --transport http --port 3000
# serves MCP at http://127.0.0.1:3000/mcp

HTTP 전송 방식은 상태가 없으며(요청당 서버 하나), 기본적으로 127.0.0.1에 바인딩되고 DNS 리바인딩 보호가 활성화되어 있습니다.

도구

게이트웨이(모든 279개 작업 포함)

일반적인 흐름: ir_list_operations → ir_describe_operation → ir_call.

큐레이션(일반적인 온콜 워크플로)

알림: ir_list_alerts, ir_get_alert, ir_ack_alert, ir_resolve_alert, ir_comment_alert · 인시던트: ir_list_incidents, ir_get_incident, ir_create_incident, ir_add_incident_responder, ir_set_incident_priority · 온콜: ir_who_is_on_call, ir_oncall_health, ir_list_rotations, ir_create_rotation_override · 사일런스: ir_list_silences, ir_create_silence, ir_remove_silence · 유지보수: ir_list_maintenance_windows, ir_create_maintenance_window · 컨텍스트: ir_list_teams, ir_list_routes, ir_list_channels, ir_whoami · 하트비트: ir_list_heartbeats, ir_send_heartbeat.

안전

• 확인 가드. 파괴적인 작업(DELETE, 그리고 disable/remove/delete/reset/regenerate-token/intake-token/cancel/merge/revoke 경로)은 confirm: true를 전달하지 않으면 실행되지 않습니다. 이 값을 전달하지 않으면 도구는 드라이런 미리보기를 반환합니다.

• 읽기 전용 모드. IR_READONLY=true로 설정하면 도구 계층에서 모든 비-GET 작업을 거부합니다.

• 토큰 비식별화. 베어러 토큰은 로그와 오류 출력에서 제거됩니다.

보안

IR_VERIFY_TLS=false는 IncidentRelay로의 아웃바운드 호출에 대한 TLS 인증서 검증을 비활성화합니다. 이는 트래픽을 중간자 공격에 노출시키므로 신뢰할 수 있는 네트워크에서만 사용해야 합니다. 자체 호스팅 자체 서명 인증서의 경우 검증을 비활성화하는 대신 서버의 CA를 신뢰 저장소에 추가하는 것을 선호하세요(또는 올바르게 발급된 인증서를 사용). 비활성화하면 서버는 시작 시 경고를 출력합니다.

개발

npm test          # run the vitest suite
npm run dev       # run from source with tsx
npm run build     # typecheck + emit dist/ + copy the OpenAPI snapshot

번들된 OpenAPI 스냅샷 재생성: scripts/generate-snapshot.md를 참조하세요.

설계 및 계획

• 설계 사양: docs/superpowers/specs/2026-08-17-incidentrelay-mcp-design.md

• 구현 계획: docs/superpowers/plans/2026-08-17-incidentrelay-mcp.md