incidentrelay-mcp

IncidentRelay のための MCP サーバー — 自ホスト型のオンコールスケジューリング、アラートルーティング、インシデント管理。

IncidentRelay の REST API 全体(279 オペレーション) を、MCP クライアント(Claude Desktop、Claude Code、Cursor、…)に 2 つのレイヤーを通じて公開します:

• 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 トランスポートはステートレス(リクエストごとに1つのサーバー)で、デフォルトで 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