incidentrelay-mcp

一个 MCP 服务器，用于 IncidentRelay——自托管的值班排班、警报路由和事件管理。

它通过两层将 IncidentRelay 的 完整 REST API（279 个操作） 暴露给 MCP 客户端（Claude Desktop、Claude Code、Cursor、……）：

• 3 个网关工具，由服务器自身的 OpenAPI 文档驱动，使 每个 操作都可达。

• 25 个精选工具：以类型化、符合人体工程学的输入封装常见值班工作流（确认/解决警报、事件、值班排班、静默、维护窗口）。

该服务器绝不会修改 IncidentRelay。它是一个纯粹的 REST 客户端，使用你提供的 bearer 令牌进行身份验证。

运行

无需安装——使用 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 和一个 bearer 令牌（JWT 访问令牌或在 IncidentRelay 的 个人资料 → API 令牌 下创建的 个人 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，否则 不会 运行。没有它，工具会返回 dry-run 预览。

• 只读模式。 设置 IR_READONLY=true 可在工具层拒绝所有非 GET 操作。

• 令牌脱敏。 Bearer 令牌会从日志和错误输出中移除。

安全

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