WatchGuard Cloud

WatchGuard Cloud MCP 服务

适用于 AI 助手和 WYRE Conduit 网关的 WatchGuard Cloud REST API MCP 服务——用于 MSP 账户管理、设备／许可证激活，以及操作员（用户）管理。

身份验证

在 WatchGuard Cloud 中启用 API 访问（Account Settings > API Access）后，会收到两组独立的凭据：

1. 一组 AccessID／Password，用于通过 POST /oauth/token（grant_type=client_credentials，HTTP Basic 身份验证）换取有效期为 1 小时的 OAuth 访问令牌。本服务会在内部完成此交换，并在令牌过期时刷新令牌。
2. 单独的 WatchGuard-API-Key，每次请求都要将其作为独立标头与 OAuth bearer 令牌一同发送。

调用方只需提供以下三个长期有效的值——无需提供短期访问令牌。

配置

复制 .env.example，并设置以下变量。将该文件中的 CONDUIT_S2S_SECRET 留空。

环境变量	说明
WATCHGUARDCLOUD_ACCESS_ID	WatchGuard Cloud API Access 中的 AccessID。stdio 和 AUTH_MODE=env 必需。
WATCHGUARDCLOUD_PASSWORD	与 AccessID 配套的密码。stdio 和 AUTH_MODE=env 必需。
WATCHGUARDCLOUD_API_KEY	启用 API 访问时生成的 WatchGuard-API-Key。stdio 和 AUTH_MODE=env 必需。
WATCHGUARDCLOUD_REGION	usa（默认值）、deu（EMEA）或 jpn（APAC）——账户的数据存储区域。
MCP_TRANSPORT	stdio（默认值）或 http。
AUTH_MODE	env（默认值，读取上述变量）或 gateway（凭据通过 Conduit 网关注入的 X-WatchGuardCloud-* 标头随每个请求传入）。容器镜像和 Compose 使用 gateway。网关模式绝不会回退到 WATCHGUARDCLOUD_*。
CONDUIT_S2S_SECRET	启动 HTTP 传输必需。若该值为空或为已知占位值（changeme、your-s2s-secret、secret、placeholder 及其他示例值），进程会记录错误并以非零状态退出。未设置时，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 时的绑定地址。未设置时，沿用原有默认值 0.0.0.0。容器镜像和 Compose 使用 0.0.0.0。未设置真实密钥时，监听器仅绑定到 127.0.0.1。
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：

X-Gateway-S2S: t=<unix seconds>,v1=<hex hmac-sha256>

v1 是以 CONDUIT_S2S_SECRET 为密钥、对字面字符串 t=<unix seconds> 计算得到的十六进制 HMAC-SHA256。缺少该标头或标头无效时，会返回 401。时间戳必须与服务器时钟相差不超过 5 分钟。

网关会为每次 /mcp 调用签名：

t=$(date +%s)
sig=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS -X POST http://127.0.0.1:8080/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${t},v1=${sig}" \
  -H "X-WatchGuardCloud-Access-ID: $WATCHGUARDCLOUD_ACCESS_ID" \
  -H "X-WatchGuardCloud-Password: $WATCHGUARDCLOUD_PASSWORD" \
  -H "X-WatchGuardCloud-API-Key: $WATCHGUARDCLOUD_API_KEY" \
  -H "X-WatchGuardCloud-Region: usa" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 下，/mcp 还要求提供 X-WatchGuardCloud-Access-ID、X-WatchGuardCloud-Password 和 X-WatchGuardCloud-API-Key（X-WatchGuardCloud-Region 可选）。缺少这三项中任意一项时，请求会返回 401。这些标头是该请求唯一的凭据来源。

AUTH_MODE=env 仍要求提供有效的 X-Gateway-S2S 标头，然后使用进程环境中的 WATCHGUARDCLOUD_*。

请求限制

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

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

工具

账户

• watchguardcloud_get_account - 获取账户详情。
• watchguardcloud_create_account - 创建托管（子级）账户。
• watchguardcloud_update_account - 更新托管账户的名称 / 主要联系人。
• watchguardcloud_delete_account - 删除托管账户。
• watchguardcloud_list_managed_accounts - 列出由某账户管理（委托）的账户。

激活

• watchguardcloud_create_activation - 使用激活密钥激活 Firebox / 硬件设备或 SaaS 许可证。
• watchguardcloud_list_recent_activations - 列出大约过去 30 天内的激活批次。
• watchguardcloud_get_activation_status - 获取激活批次中各行项目的状态。

操作员管理

• watchguardcloud_create_operator - 创建具有特权角色的操作员（用户）账户。
• watchguardcloud_update_operator - 更新操作员的姓名 / 电话 / 角色。
• watchguardcloud_delete_operator - 删除操作员账户。
• watchguardcloud_get_operator_transaction_status - 查询异步创建 / 更新 / 删除操作的结果。
• watchguardcloud_list_operators - 列出账户的所有操作员及其角色 / MFA 状态。

范围

这是一个 v1 版本，涵盖 WatchGuard Cloud 平台中文档最完善的三类 API（账户、激活和操作员管理）。目前明确不在范围内：Firebox 设备配置 / 管理和 Endpoint Security 策略管理——两者都是独立的 WatchGuard API，但在撰写本文时，其公开文档尚未提供足够具体的请求 / 响应详情，无法有把握地实现。待文档完善后，可作为后续功能添加。

开发

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

在 CONDUIT_S2S_SECRET 设置为有效密钥之前，HTTP 服务不会启动：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

不使用服务间密钥的本地 HTTP 仅供开发使用。它会绑定到 127.0.0.1 并记录警告：

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Docker

镜像会在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。请将端口发布到环回地址并传入 S2S 密钥。在网关模式下，每个请求都会通过标头传入 WatchGuard 凭据；程序不会从环境变量读取这些凭据。

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

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会设置 AUTH_MODE=gateway，发布 127.0.0.1:8080:8080，且不会注入静态供应商凭据：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍然需要 S2S 密钥，随后使用 WATCHGUARDCLOUD_ACCESS_ID、WATCHGUARDCLOUD_PASSWORD 和 WATCHGUARDCLOUD_API_KEY。这与网关 Compose 服务相互独立：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e WATCHGUARDCLOUD_ACCESS_ID="$WATCHGUARDCLOUD_ACCESS_ID" \
  -e WATCHGUARDCLOUD_PASSWORD="$WATCHGUARDCLOUD_PASSWORD" \
  -e WATCHGUARDCLOUD_API_KEY="$WATCHGUARDCLOUD_API_KEY" \
  -e WATCHGUARDCLOUD_REGION=usa \
  -p 127.0.0.1:8080:8080 \
  watchguard-cloud-mcp