AlertOps

AlertOps MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 AlertOps 事件告警/值班 API MCP 服务，涵盖告警、消息主题、用户及其联系方式、群组、已配置的入站集成和 on-call 排班。

身份验证

AlertOps 的 REST API（https://api.alertops.com/api/...，对应其发布于 api.alertops.com/swagger/v1/swagger.json 的 OpenAPI 规范）使用静态的账户级 API 密钥进行身份验证。该密钥在 Account Settings -> Configurations -> Integrations -> API 下生成。与大多数 WYRE Conduit sidecar 不同，该密钥不会作为 bearer token 或自定义身份验证标头发送；AlertOps 要求将其作为 APIKey 查询字符串参数附加到每个请求中，GET 和 POST 请求均如此（已于 2026-09-20 实时验证：无效密钥会在此连接器调用的每个端点上返回干净的 {"reason":"Invalid API Key"} HTTP 401）。此连接器通过自定义标头按请求接收密钥（绝不使用 OAuth，与其他所有静态密钥 WYRE Conduit sidecar 的形式相同），并在调用 AlertOps API 时自行附加 ?APIKey=<key>。在网关模式下，密钥通过 X-AlertOps-Api-Key 标头按请求传入；在本地/stdio 模式下，则从 ALERTOPS_API_KEY 读取一次。HTTP /mcp 还需要 X-Gateway-S2S 签名（见下文的 HTTP 身份验证）。如果没有有效的 CONDUIT_S2S_SECRET，HTTP 服务将拒绝启动。

以下是两个彼此独立、置信程度刻意不同的说法——不要将它们合并成一句笼统的“只读”声明：

• 结构上已验证（直接检查过，可完全确认）： 此连接器自身的代码不会调用任何会写入/修改 AlertOps 数据的端点。client.ts 中的每个函数都调用下方工具列表中列出的 11 个已文档化 GET 操作之一；src/ 中不存在任何 POST 调用。
• 厂商文档有所说明，但未经独立验证（刻意保留限定）： AlertOps 提供基于角色的访问控制，内置角色和自定义角色均由可单独授予的只读权限组成（例如 Messages_View_GlobalAccess、User_View_GlobalAccess、Groups_View_GlobalAccess）。AlertOps 自己的文档称，以这种方式构建的自定义角色允许用户“浏览事件、报告、用户和群组，但不能创建、修改或删除任何内容”（help.alertops.com，Role Based Access Control）。AlertOps 的其他文档将一种独立的 User API Key（显示在用户自己的 Profile 页面上）描述为受 UserAPIKey_Add 权限控制，这意味着通过这种方式签发的 API 密钥会继承签发用户的角色/权限。WYRE 尚未测试这些权限是否真的会在服务端针对本连接器使用的 APIKey 查询参数及其写入端点生效——也就是说，AlertOps 后端是否会拒绝使用只读权限用户的密钥发出的写入调用（创建告警、关闭告警、分配等），还是此类限制仅会在 AlertOps 自身的 UI 中体现。 没有人使用有效密钥发出写入调用进行检查，这是正确的做法：这样做可能会向真实的值班人员发送实际的页面通知/提醒，不应在未经同意的情况下执行。不要认为此连接器或本 README 已证明以只读权限配置的 AlertOps API 密钥在技术上无法执行写入操作——我们只能确认此连接器自身的代码从不尝试写入，并且 AlertOps 的文档所述角色系统支持以这种方式配置密钥。

配置

复制 .env.example。将该文件中的 CONDUIT_S2S_SECRET 留空。

环境变量	描述
ALERTOPS_API_KEY	在 Account Settings -> Configurations -> Integrations -> API 下签发的 API 密钥。stdio 和 AUTH_MODE=env 时的 HTTP 均使用此密钥。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（本地默认值；读取 ALERTOPS_API_KEY）或 gateway（Docker 镜像和 Compose 默认值）。Gateway 模式要求每个 /mcp 请求都携带 X-AlertOps-Api-Key。
CONDUIT_S2S_SECRET	启动 HTTP 传输所必需。空值和已知占位值（changeme、replace-with-a-real-secret、your-s2s-secret 等）都会被拒绝：进程会记录错误并以非零状态退出。此值绝不会被记录到日志中。未设置此值时，Compose 不会启动。
MCP_ALLOW_INSECURE_DEV	仅用于本地开发，设为 1 可在 CONDUIT_S2S_SECRET 为空时启动 HTTP。程序会记录警告、跳过 X-Gateway-S2S 检查，并且只监听 127.0.0.1。在此模式下，非环回地址的 MCP_HTTP_HOST 会被忽略。已知占位密钥仍会被拒绝。
MCP_HTTP_HOST	HTTP 绑定地址。未设置时默认为 127.0.0.1。设置了 CONDUIT_S2S_SECRET 时，会遵循此值（容器镜像设为 0.0.0.0）。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

/health 不需要身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。其值为：

t=<unix seconds>,v1=<hex hmac-sha256>

v1 是对 ASCII 消息 t=<unix seconds>（与标头中出现的 t= 前缀相同）进行 HMAC-SHA256 运算的结果，以 CONDUIT_S2S_SECRET 为密钥，并编码为 64 个小写十六进制字符。缺少标头或标头无效时，会返回 401。密钥绝不会被记录到日志中。

在 AUTH_MODE=gateway 模式下，/mcp 还要求 X-AlertOps-Api-Key。缺少此标头的请求会返回 401。Gateway 模式会将此标头作为该请求唯一的 AlertOps 凭据。

请求限制

• HTTP 请求正文上限为 256 KiB（262144 字节）。X-Gateway-S2S 检查通过后，如果 Content-Length 超过上限，会返回带有 JSON-RPC 错误的 413；没有 Content-Length 的正文则由 MCP SDK 传输限制大小。未经身份验证的请求仍会优先收到 401。
• tools/call 参数上限为 10,000 个元素（包括任意深度的每个数组项和对象键）。超出上限的输入会返回 isError 工具结果，且绝不会被分派。

这些限制用于应对 CVE-2026-111768 / GHSA-46jr-4wx8-v453（验证期间的内存耗尽）和 GHSA-f897-62hf-6gxq（缺少请求正文 / 批次上限）。

工具

11 个只读工具，每个对应 AlertOps 已发布 REST API 规范中的一个 GET 操作（总计 25 个操作；其余 14 个为 POST / 写入操作，特意排除在外——请参阅下文的范围）。

告警

• alertops_list_alerts - 列出告警，可按状态 / 日期范围 / 组 / 集成 / 升级筛选，并支持分页。
• alertops_get_alert_id_by_inbound_message_id - 查询入站集成的 messageID 所映射到的 AlertID。
• alertops_get_alert_id_by_unique_inbound_id - 查询入站集成的 uniqueInboundID 所映射到的 AlertID。

用户

• alertops_list_users - 列出用户（用户名、全名、用户类型）。
• alertops_get_user_contact_methods - 列出用户配置的联系方式（电子邮件、电话 / SMS）。包含联系人个人身份信息（PII）。

组

• alertops_list_groups - 列出组（组 ID -> 组名）。

主题

• alertops_list_topics - 列出用于告警路由 / 升级的消息主题。

集成

• alertops_list_integrations - 列出已配置的入站集成（集成规则 ID -> 集成类型）。

排班

• alertops_get_oncall_now - 列出当前值班人员，可查看所有组或指定组。
• alertops_get_user_schedule - 查询用户在指定日期范围内的值班安排（最长 3 个月）。
• alertops_get_group_schedule - 查询组在指定日期范围内的值班安排（最长 3 个月）。

范围

这是一个刻意限定范围、只读的 v1 接口，仅涵盖 AlertOps 已记录的 25 项操作中的 11 项。 AlertOps 是一个实时事件呼叫系统——所有排除的操作要么会更改状态，要么会向真人触发实际呼叫/通知，因此这里都不会实现。这是有意为之，并非疏忽：

明确排除（创建或更改实时告警——可能会呼叫真人）——绝不实现：

• POST /api/alert/Create (Alert_Create) - 创建新告警，并向其接收者发送呼叫/通知。
• POST /api/alert/Close (Alert_Close) - 关闭实时告警。
• POST /api/alert/Update (Alert_Update) - 更新实时告警中的某个字段。
• POST /api/alert/Assign (Alert_Assign) - 将用户分配给告警。
• POST /api/alert/Note (Alert_Note) - 向告警添加备注。
• POST /api/alert/AddRecipients (Alert_AddRecipients) - 向告警添加接收者，即呼叫更多人员。
• POST /api/alert/Reply (Alert_Reply) - 回复告警。

明确排除（配置/更改——用户、组、排班、集成）——绝不实现：

• POST /api/user/CreateUser (User_CreateUser) - 创建新用户。
• POST /api/user/CreateOutOfOffice (User_CreateOutOfOffice) - 创建外出记录，这会改变被呼叫的人员。
• POST /api/group/CreateGroup (Group_CreateGroup) - 创建新组。
• POST /api/group/AddGroupMember (Group_AddGroupMember) - 向组添加成员，这会改变被呼叫的人员。
• POST /api/schedule/CreateFixedSchedule (Schedule_CreateFixedSchedule) - 创建固定值班排班。
• POST /api/schedule/CreateRecurringSchedule (Schedule_CreateRecurringSchedule) - 创建循环值班排班。
• POST /api/integration/CreateMaintenanceWindows (Integration_CreateMaintenanceWindows) - 创建维护时段，以抑制告警。

如有需求，可在经过审慎的范围决策后将这些操作作为后续功能添加，而不是默认加入。

开发

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。请将端口发布到回环地址，并传入生成的 S2S 密钥。启动时会拒绝空的 CONDUIT_S2S_SECRET 和已知占位值（your-s2s-secret、changeme 等），因此以下每条命令都会使用 openssl rand -hex 32 创建一个值，而不是直接写入密钥。在 gateway 模式下，每个请求都会通过 X-AlertOps-Api-Key 传入 AlertOps API 密钥。

docker build -t alertops-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" \
  -p 127.0.0.1:8080:8080 \
  alertops-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动。Compose 服务使用 gateway 模式，不设置 ALERTOPS_API_KEY，并发布 127.0.0.1:8080:8080。如果 gateway 必须使用与容器接收值相同的密钥对请求签名，请导出一个密钥：

export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用环境中的 ALERTOPS_API_KEY。运行命令前，请导出该密钥。

docker run \
  -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" \
  -e AUTH_MODE=env \
  -e ALERTOPS_API_KEY \
  -p 127.0.0.1:8080:8080 \
  alertops-mcp

不带密钥的本地 HTTP 仅用于开发。即使 MCP_HTTP_HOST 为 0.0.0.0，它仍会绑定到 127.0.0.1，并记录一条警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

许可证

Apache-2.0