Runframe Incident Management MCP Server

runframe-mcp-server

Runframe 是面向工程团队的完整事件生命周期平台，涵盖事件响应、值班和状态页面。此 MCP 服务让你可以通过 IDE 或 AI Agent 管理这些工作流。

提供 17 个工具，涵盖事件、值班、服务、事后复盘、团队和人员查询。需要 Node.js 20+。

为什么使用它

• 留在编辑器中 — 无需切换到浏览器，即可确认事件、呼叫响应人员并撰写事后复盘
• 让 Agent 处理日常事务 — AI Agent 可以使用限定范围的 API 密钥自主进行事件分诊、升级和更新
• 无需基础设施 — 通过 npx 运行，本地使用时无需部署服务

工作原理

Your IDE / Agent
    ↓ (stdio or HTTP)
MCP Server (this package)
    ↓ (HTTPS, scoped API key)
Runframe API

该服务是无状态的。它会将 MCP 工具调用转换为 Runframe API 请求，并根据 API 密钥权限限定请求范围。本地不会存储任何数据。

示例

向你的 Agent 提问：

• “确认事件 INC-2026-001” → 调用 runframe_acknowledge_incident
• “现在谁在值班？” → 调用 runframe_get_current_oncall
• “为数据库中断创建事后复盘” → 调用 runframe_create_postmortem
• “针对 API 延迟激增呼叫后端团队负责人” → 调用 runframe_page_someone
• “列出所有未解决的 SEV1 事件” → 调用带严重性筛选条件的 runframe_list_incidents
• “查找 Alex，以便我查看他们未解决的事件” → 调用 runframe_find_user

安装

从 Runframe.io 的设置中获取 API 密钥，然后将其添加到你的 Agent：

Claude Code：

claude mcp add runframe -e RUNFRAME_API_KEY=rf_your_key_here -- npx -y @runframe/mcp-server

Cursor（~/.cursor/mcp.json）· VS Code（.vscode/mcp.json）· Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "runframe": {
      "command": "npx",
      "args": ["-y", "@runframe/mcp-server"],
      "env": { "RUNFRAME_API_KEY": "rf_your_key_here" }
    }
  }
}

其他 MCP 客户端： 将上面的 JSON 配置添加到客户端的 MCP 配置文件中。

交互式设置向导：

npx @runframe/mcp-server --setup

环境变量

变量	必需	默认值	描述
RUNFRAME_API_KEY	是	—	API 密钥（以 rf_ 开头）
RUNFRAME_API_URL	否	https://runframe.io	API 基础 URL
MCP_ACCESS_TOKEN	仅 HTTP	—	HTTP 传输的 Bearer 令牌。轮换时以逗号分隔（new_token,old_token）。

传输方式

stdio（默认）— 由 Claude Code 和 Cursor 等 MCP 客户端使用。不暴露网络。上面的安装命令配置的就是此方式。

Streamable HTTP — 用于容器化或远程部署。Bearer 身份验证需要 MCP_ACCESS_TOKEN：

RUNFRAME_API_KEY=rf_... \
  MCP_ACCESS_TOKEN=your_token \
  npx @runframe/mcp-server --transport http --port 3100 --host 127.0.0.1

安全模型

安全责任划分为三个边界：

• Runframe API 通过 RUNFRAME_API_KEY 处理授权和权限范围。
• 此 MCP 服务 负责进程隔离（stdio）和 Bearer 令牌验证（HTTP）。它还会执行方法过滤、本地主机上的 Host/Origin 检查、声明的 Content-Length 验证（上限 1 MB）、8 KB 请求头上限，以及 15s 上游超时。
• 你的反向代理 负责 TLS、速率限制，以及在将 HTTP 模式暴露到网络时强制执行流式请求体限制。

该服务不会存储任何内容，只会将请求转发到 Runframe API。

工具

事件（9）

工具	范围	描述
runframe_list_incidents	incidents:read	使用筛选条件和分页列出事件
runframe_get_incident	incidents:read	按 ID 或编号获取事件
runframe_create_incident	incidents:write	创建事件
runframe_update_incident	incidents:write	更新标题、描述、严重程度或负责人
runframe_change_incident_status	incidents:write	将事件转为新状态（new、investigating、fixing、monitoring、resolved、closed）
runframe_acknowledge_incident	incidents:write	确认事件（自动分配负责人并跟踪 SLA）
runframe_add_incident_event	incidents:write	添加时间线条目
runframe_escalate_incident	incidents:write	升级至下一级策略
runframe_page_someone	incidents:write	通过 Slack 或电子邮件通知响应人员

值班（1）

工具	范围	描述
runframe_get_current_oncall	oncall:read	查询当前值班人员

服务（2）

工具	范围	描述
runframe_list_services	services:read	列出服务
runframe_get_service	services:read	获取服务详情

事后分析（2）

工具	范围	描述
runframe_create_postmortem	postmortems:write	创建事后分析
runframe_get_postmortem	postmortems:read	获取事件的事后分析

团队（2）

工具	范围	描述
runframe_list_teams	teams:read	列出团队
runframe_get_escalation_policy	oncall:read	获取指定严重程度对应的升级策略

用户（1）

工具	范围	描述
runframe_find_user	users:read	按姓名或电子邮件搜索用户；可选择在历史查询中包含非活跃用户

与直接 API 保持一致

此 MCP 服务遵循公开的 Runframe 直接 API 契约。

• 创建事件时，service_ids 必须包含 svc_K7M4Q9TZ2H 这类公开服务键，而非内部 UUID。
• runframe_get_service 现在按公开的 service_key 查找服务，而非 UUID。
• 事件工具现在遵循最新的 V1 契约：在路径参数中使用 INC-2026-001 这类事件编号。
• 事件更新和列表筛选条件在 V1 使用的地方现在采用最新的公开标识符，包括负责人／解决者电子邮件和 team_name。
• runframe_create_incident 接受可选的 idempotency_key；该值会作为 Idempotency-Key 标头转发，以便安全重试创建操作。
• 如果未提供 severity，runframe_create_incident 默认使用 SEV2，与 V1 API 保持一致。
• 事件创建现在遵循 V1 API 的限制：title 长度须为 1–200 个字符，description 最多 10000 个字符，service_ids 最多包含 50 项。
• 创建事件需要所请求严重程度对应的有效 SLA 配置。如果缺少确认或关闭期限，API 会拒绝创建。
• 创建事件前，使用 runframe_list_services 查找有效的 service_key 值。
• runframe_page_someone 现在遵循最新的 V1 投递契约：使用 email、channels 和可选的 message。
• 事后分析工具现在遵循最新的 V1 契约：使用 incident_number，以及 users_affected、owner_email 和 time_to_acknowledge 这类 snake_case 嵌套字段。
• 按 assigned_to 或 resolved_by 筛选事件前，使用 runframe_find_user 将姓名解析为电子邮件地址。
• 如需在历史事件查询中解析前员工，将 runframe_find_user 的 include_inactive=true。
• 如需显式使用 V1 活跃状态筛选条件，将 runframe_find_user 的 is_active 设为 true 或 false。
• 筛选事件前，使用 runframe_list_teams 搭配 search 查找准确的 team_name。

Docker

Docker 镜像默认通过 3100 端口运行 HTTP 传输：

docker build -t runframe-mcp-server .
docker run -e RUNFRAME_API_KEY=rf_... -e MCP_ACCESS_TOKEN=your_token -p 3100:3100 runframe-mcp-server

部署 HTTP 模式

HTTP 模式适用于专用网络。如果将其部署到互联网：

• 在 TLS 后运行（nginx、Caddy、云负载均衡器）。此服务不支持 TLS。
• 使用反向代理进行速率限制和请求缓冲。
• 优先使用专用子网或 VPN，而不是暴露到公网上。
• 定期轮换 MCP_ACCESS_TOKEN。用逗号分隔传入新旧令牌，即可无停机切换。

速率限制

Runframe API 在服务端实施速率限制。如果触发限制，工具会返回 429 错误，并附带重试提示。对于 HTTP 传输部署，反向代理可以添加额外的请求级限流。

令牌轮换

MCP_ACCESS_TOKEN 接受以逗号分隔的令牌：

1. 设置 MCP_ACCESS_TOKEN=new_token,old_token
2. 将客户端更新为使用 new_token
3. 移除旧令牌：MCP_ACCESS_TOKEN=new_token

限制

• 排班只读 — 可以查询值班安排和升级策略，但无法通过 MCP 修改
• 需要 Runframe 账户和 API 密钥

贡献

欢迎在 github.com/runframe/runframe-mcp-server 提交问题和 PR。

许可证

MIT — Runframe · npm