SaaS Alerts

saas-alerts-mcp

适用于 Kaseya SaaS Alerts 的 Model Context Protocol 服务——这是一个用于监控 M365 和 Google Workspace 事件的 SaaS 安全平台。

属于 WYRE Technology MCP fleet。

功能

通过 30 个按领域组织的 MCP 工具，开放完整的 SaaS Alerts External Partner API（v0.20.0）：

领域	工具
事件	按严重程度、客户、用户和事件类型查询／统计安全事件；执行高级 Elasticsearch 查询；使用滚动分页；获取建议操作
客户	列出、获取、创建、更新和删除客户；设置 IP／国家和账户白名单
用户	MSP 用户信息、合作伙伴用户、客户用户
设备	统一已映射／未映射／已忽略的设备，以及设备组织
计费	按日期获取计费详情、计费日期历史记录
报告	列出／获取／创建／删除计划报告
合作伙伴	合作伙伴资料、品牌设置

写入／破坏性工具需要通过 MCP elicitation 获得用户确认（失败时放行：如果客户端不支持 elicitation，则继续执行）。

身份验证

SaaS Alerts 使用通过 api_key HTTP 标头发送的 API 密钥。

在 SaaS Alerts 界面中，通过 设置 → API 密钥 生成 API 密钥。

复制 .env.example。将该文件中的 CONDUIT_S2S_SECRET 留空，且绝不要提交真实值。

变量	必填	说明
SAAS_ALERTS_API_KEY	stdio 和 AUTH_MODE=env 时必填	SaaS Alerts API 密钥。网关模式不会读取此变量。
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。网关模式要求每个 /mcp 请求都携带 X-SaaS-Alerts-API-Key，且不会回退使用 SAAS_ALERTS_API_KEY。
CONDUIT_S2S_SECRET	HTTP 模式下必填	服务间密钥。如果该值为空或为已知占位符（changeme、secret、your-s2s-secret 以及其他示例值），HTTP 服务会记录错误并以非零状态码退出。未设置此变量时，Compose 不会启动。不会记录此值。
MCP_ALLOW_INSECURE_DEV	否	仅用于本地开发；设为 1 可在未设置 CONDUIT_S2S_SECRET 时启动 HTTP。进程会记录警告，不会强制验证 X-Gateway-S2S，并且只监听 127.0.0.1。更宽泛的 MCP_HTTP_HOST（包括 0.0.0.0）会被覆盖。占位符密钥仍会被拒绝。
MCP_HTTP_HOST	否	设置了真实 CONDUIT_S2S_SECRET 时的绑定地址。默认值为 127.0.0.1。容器镜像将其设为 0.0.0.0。未设置真实密钥时，监听地址会被强制设为 127.0.0.1。
MCP_HTTP_PORT	否	HTTP 端口。默认值为 8080。

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

X-Gateway-S2S 签名

使用 MCP_TRANSPORT=http 且设置了真实 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。如果缺少该标头或标头无效，则会在读取任何供应商凭据之前返回 401。

标头值为 t=<unix seconds>,v1=<hex hmac-sha256>：

1. 将 t 设为当前 Unix 时间戳（秒）。
2. 使用 CONDUIT_S2S_SECRET 作为密钥，对 ASCII 消息 t=<unix seconds> 进行 HMAC-SHA256 签名。
3. 将摘要编码为十六进制（64 个小写十六进制字符），并发送 t=<unix seconds>,v1=<hex>。

时间戳与服务器时钟的偏差必须在 300 秒以内。示例：

import { createHmac } from 'node:crypto';

const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.CONDUIT_S2S_SECRET).update(`t=${t}`).digest('hex');
const xGatewayS2s = `t=${t},v1=${v1}`;

本地／stdio 模式

export SAAS_ALERTS_API_KEY=your-api-key
node dist/index.js

HTTP 模式

必须设置 CONDUIT_S2S_SECRET。如果该值为空，进程会记录错误并以非零状态码退出。

export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
export SAAS_ALERTS_API_KEY=your-api-key
export MCP_TRANSPORT=http
export AUTH_MODE=env
export MCP_HTTP_PORT=8080
node dist/http.js

未设置密钥的本地 HTTP 仅供开发使用。即使 MCP_HTTP_HOST 为 0.0.0.0，它也会绑定到 127.0.0.1，并记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

WYRE Gateway 模式

通过 WYRE MCP Gateway 运行时，设置 AUTH_MODE=gateway（镜像和 Compose 的默认值）。Gateway 会使用 X-Gateway-S2S 为每个请求签名，并通过 X-SaaS-Alerts-API-Key 注入 API 密钥。请求缺少此凭据标头时会返回 401，且不会使用环境变量中的 SAAS_ALERTS_API_KEY。

await fetch('http://127.0.0.1:8080/mcp', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    accept: 'application/json, text/event-stream',
    'x-gateway-s2s': xGatewayS2s,
    'x-saas-alerts-api-key': apiKey,
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
});

使用 Docker 运行

镜像会在容器内监听 0.0.0.0，且默认设置为 AUTH_MODE=gateway。将端口发布到回环地址，并传入 S2S 密钥。在 gateway 模式下，SaaS Alerts API 密钥随每个请求传入，不会从环境变量中读取。

docker build -t saas-alerts-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  saas-alerts-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会设置 AUTH_MODE=gateway、发布 127.0.0.1:8080:8080，且不会将 SAAS_ALERTS_API_KEY 传入 gateway 服务：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 SAAS_ALERTS_API_KEY：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SAAS_ALERTS_API_KEY=your-key \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/saas-alerts-mcp:latest

开发

npm install
npm run build
npm test
npm run lint
node scripts/lint-destructive-warnings.mjs src

破坏性工具确认

会永久删除数据的工具（删除客户、删除计划报告）包含：

• ⚠ DESTRUCTIVE — IRREVERSIBLE 描述前缀
• annotations.destructiveHint: true
• Elicitation 确认保护机制（附加机制——如果客户端不支持 elicitation，则继续执行）

调用这些工具前，务必先向用户确认。

许可证

Apache-2.0 — 参见 LICENSE。