Acronis Cyber Protect Cloud

acronis-mcp

WYRE-AI 托管的封装层，基于 Acronis Cyber Protect Cloud 供应商自己的 MCP 服务 （@acronis-platform/mcp，固定为精确版本 1.0.1）。该封装层补上了上游服务所不具备的功能：

• 精选的分级工具允许列表（上游共 159 个工具，其中 34 个只读工具，3 个需选择启用的写入工具），
• 按租户隔离进程，通过托管方式提供双时代 HTTP 服务（2025 年的 initialize 握手和 2026-07-28 无状态信封），并验证 X-Gateway-S2S，
• 响应净化（大小上限、机密信息／令牌脱敏、统一错误格式），
• 对 Acronis 基础 URL 的 SSRF 防护（WYREAI-454）。

tools/list 是静态的（在构建时生成），因此无需凭据，也无需启动任何子进程即可使用。只有 tools/call 才会启动上游子进程。

上游版本固定策略

@acronis-platform/mcp 在 package.json 中固定为精确版本（不使用 ^／~；测试会强制检查 1.0.1）。版本升级只能通过拉取请求进行。Renovate／Dependabot 可以提出升级，但不得自动合并：升级需要人工完成以下操作：

1. 对比上游的 tools/list 与 research/upstream-tools-1.0.1.json（检查新增、重命名或重复的工具），
2. 运行 npm run gen-tools，重新生成 src/generated/tools.ts，
3. 重新审核 research/tiers.json 和集成测试。

上游 1.0.1 提供了三个名称重复的工具（device_authorization_approval、 fetch_registration_tokens、create_registration_token）；这些工具都不在允许列表中，且生成器会拒绝任何在上游缺失或重名的允许列表工具。

为什么每个租户使用一个子进程

一个上游进程持有一个具有特权的 client_credentials 令牌，并将其用于所有调用方。 在租户之间共享进程，会让一个租户的请求使用另一个租户的令牌。 因此，src/upstream-pool.ts 会通过 stdio 使用 @modelcontextprotocol/client，为每组不同的凭据 （键 = sha256(baseUrl, clientId, clientSecret)；绝不会记录原始值）启动一个子进程， 并将每次调用路由到该租户自己的子进程。

• 子进程二进制文件：require.resolve('@acronis-platform/mcp/package.json') → bin/cli.js，使用 process.execPath 运行。
• 子进程环境从头构建（不继承父进程环境，因此 CONDUIT_S2S_SECRET 等变量不会泄露）： PATH、NODE_ENV、API_BASE_URL、OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET、 MCP_TRANSPORT=stdio、MCP_TOOLS_INCLUDE=<已启用层级的允许列表>。 （MCP 客户端 SDK 还会添加自己的非机密默认变量：HOME、LOGNAME、SHELL、 TERM、USER。）
• LRU 限制为 ACRONIS_POOL_MAX（默认值为 50），空闲 TTL 为 ACRONIS_POOL_IDLE_MS（默认值为 10 分钟），并且关闭服务时会关闭所有子进程。正在处理中、遭到淘汰的子进程会在调用结束时关闭。

需要注意的上游行为：

• 上游 1.0.1 会在启动时立即获取 OAuth 令牌，因此凭据错误（或无法连接数据中心）的子进程会立即退出。调用方随后会收到 {error:{code:"upstream_unavailable",…}} 结果；每个租户的首次调用都需要等待一次令牌往返。
• 每个租户的子进程都会使用独立的一次性 HOME 目录（通过 mkdtemp 创建，权限为 0700，并在子进程退出时删除），因此下文的上游令牌缓存不会在租户间共享。
• 上游会将访问令牌缓存到 ~/.mcp/token-cache（权限为 0600，使用 AES-256-GCM 加密，密钥基于客户端密钥派生）。
• 上游还会注册一个额外的内置工具 get_acronis_skill，不会受 MCP_TOOLS_INCLUDE 过滤。封装层不会列出或转发此工具（调用处理程序会再次强制执行允许列表）。

工具

工具名称由 acronis_ + 上游名称组成。未列入 research/tiers.json 的工具永远不会被列出，也永远无法调用。这通过子进程上的 MCP_TOOLS_INCLUDE 和我们 tools/call 处理程序中的允许列表检查进行双重强制。

• read 工具始终可用（readOnlyHint: true）。
• write 工具仅在 ACRONIS_ENABLE_WRITES=true 时显示并可用（默认值为 false）；标注为 readOnlyHint: false、destructiveHint: false。

输入架构原样取自上游。由于 37 个工具超过了工具集约 25 个平铺工具的阈值，描述会截取至首句（最多 300 个字符），并移除 [Account Management API 2] 这类前缀。工具定义位于 src/generated/tools.ts，由 scripts/gen-tools.mjs（npm run gen-tools）根据 research/upstream-tools-1.0.1.json 生成，并通过 research/tiers.json 进行筛选。

tools/list 负载大小（JSON 字节数）：

Surface	Before (upstream, full)	After (wrapper)
上游，全部 159 个工具	298,320	不适用（未公开）
34 个 read 工具	70,343	67,309
37 个工具（read + write）	75,822	72,864

（负载主要由架构构成，且架构保留自上游，因此精简描述可节省约 5%。）

工具	层级	上游 API
acronis_fetch_tenant	read	Account Management API 2
acronis_fetch_tenants_batch	read	Account Management API 2
acronis_fetch_tenant_children	read	Account Management API 2
acronis_fetch_tenant_users	read	Account Management API 2
acronis_fetch_users_batch	read	Account Management API 2
acronis_fetch_user	read	Account Management API 2
acronis_fetch_current_user_info	read	Account Management API 2
acronis_search	read	Account Management API 2
acronis_fetch_tenant_mfa_status	read	Account Management API 2
acronis_fetch_tenant_usages	read	Account Management API 2
acronis_fetch_all_alerts	read	Alert Manager 1.0
acronis_fetch_alert	read	Alert Manager 1.0
acronis_fetch_categories	read	Alert Manager 1.0
acronis_fetch_alert_counters	read	Alert Manager 1.0
acronis_fetch_alerts_grouped_by_scope	read	Alert Manager 1.0
acronis_fetch_all_alert_types	read	Alert Manager 1.0
acronis_fetch_resources_with_top_severity_alerts	read	Alert Manager 1.0
acronis_fetch_alert_counts_per_customer	read	Alert Manager 1.0
acronis_fetch_alerts_grouped_per_customer	read	Alert Manager 1.0
acronis_fetch_active_alert_count	read	Alert Manager 1.0
acronis_fetch_policies	read	Resource and Policy Management API v4
acronis_fetch_policy	read	Resource and Policy Management API v4
acronis_fetch_policy_applications	read	Resource and Policy Management API v4
acronis_fetch_applications_issue_statistics	read	Resource and Policy Management API v4
acronis_fetch_application_statuses_by_policy	read	Resource and Policy Management API v4
acronis_fetch_resources	read	Resource and Policy Management API v4
acronis_fetch_resource_count	read	Resource and Policy Management API v4
acronis_fetch_resource	read	Resource and Policy Management API v4
acronis_fetch_resource_protection_status	read	Resource and Policy Management API v4
acronis_fetch_agents	read	Agent Management REST API 2
acronis_fetch_agent	read	Agent Management REST API 2
acronis_fetch_incidents	read	Endpoint Detection and Response API 1.0
acronis_fetch_incident	read	Endpoint Detection and Response API 1.0
acronis_fetch_response_action_status	read	Endpoint Detection and Response API 1.0
acronis_mark_alert_as_false_positive	write	Alert Manager 1.0
acronis_update_investigation_state	write	Endpoint Detection and Response API 1.0
acronis_execute_protection_policy	write	Resource and Policy Management API v4

排除的类别

无论环境如何，以下内容均不会公开，也无法调用：

• 租户／用户／API 客户端的创建和删除，以及其他所有删除操作
• 定价、产品项目、用量更新、版本（资金相关）
• 令牌、一次性令牌（OTT）、设备授权、IdP／OpenID 配置
• 注册令牌
• 品牌设置
• EDR initiate_response_action
• research/tiers.json 中未列出的所有其他内容

响应净化

每个上游结果都会经过 src/sanitize.ts 处理：文本上限为 100 KB，超出部分会附带截断标记；JSON 中键名匹配 secret|password|token|access_token|refresh_token|api[_-]?key|authorization|client_secret 的值会被隐藏；Bearer 令牌和类似 JWT 的字符串会在任何位置被隐藏；非文本块会被丢弃。错误会以 {"error":{"code","message"}} 的形式返回给调用方，消息上限为 500 个字符，并会清除租户凭据。

凭据

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

• **本地／stdio（Claude Desktop、CLI）：**设置 ACRONIS_BASE_URL、ACRONIS_CLIENT_ID、ACRONIS_CLIENT_SECRET（使用具有 client_credentials 的 Acronis API 客户端）。stdio 不使用 CONDUIT_S2S_SECRET。
• **托管／网关（AUTH_MODE=gateway）：**凭据随每个请求传入，绝不会回退到环境变量。

网关标头	含义
X-Acronis-Base-Url	数据中心 URL，例如 https://us5-cloud.acronis.com
X-Acronis-Client-Id	API 客户端 ID
X-Acronis-Client-Secret	API 客户端密钥

**基础 URL 验证（SSRF 防护）：**仅限 https；主机名必须以 .acronis.com 结尾；不得包含用户信息、非默认端口、路径／查询字符串／片段。其他情况均会被拒绝（网关模式下返回 401，且不会启动子进程）。

环境变量

变量	必需	说明
ACRONIS_BASE_URL	stdio 和 AUTH_MODE=env	Acronis 数据中心 URL（参见上文的验证规则）
ACRONIS_CLIENT_ID	stdio 和 AUTH_MODE=env	API 客户端 ID
ACRONIS_CLIENT_SECRET	stdio 和 AUTH_MODE=env	API 客户端密钥
ACRONIS_ENABLE_WRITES	否	设为 true 可启用 3 个写入工具。默认为 false。
ACRONIS_POOL_MAX	否	上游子进程的最大并发数（LRU）。默认为 50。
ACRONIS_POOL_IDLE_MS	否	子进程关闭前的空闲时间。默认为 600000（10 分钟）。
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。只有在 S2S 身份验证成功后，env 才会使用 ACRONIS_*。
CONDUIT_S2S_SECRET	HTTP 必需	服务间密钥。如果该值为空或为已知占位符，HTTP 服务会记录错误并以非零状态退出。未设置此值时，Compose 不会启动。切勿提交真实值。可使用 openssl rand -hex 32 生成。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为 1，即可在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告、不强制执行 X-Gateway-S2S，且仅绑定到 127.0.0.1。仍会拒绝占位符密钥。
MCP_HTTP_HOST	否	设置了真实 CONDUIT_S2S_SECRET 时的绑定地址。默认为 127.0.0.1。容器镜像会将其设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。
LOG_LEVEL	否	debug、info（默认）、warn、error

/health 和 /healthz 无需身份验证，且不会读取凭据。

X-Gateway-S2S 签名

使用 MCP_TRANSPORT=http 且设置了 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S：

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

v1 是对 ASCII 消息 t=<unix seconds> 使用 CONDUIT_S2S_SECRET 作为密钥计算的 HMAC-SHA256，并以十六进制编码。时间戳与服务器时钟的偏差不得超过 300 秒。缺少标头或标头无效时，会返回 401。密钥绝不会被记录到日志中。

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 3 个 X-Acronis-* 标头。请求缺少其中任何一个标头（或携带无效的基础 URL）时，都会返回 401，且不会回退到 ACRONIS_*。

本地运行（stdio）

需要 Node >= 22。

npm install
npm run build
ACRONIS_BASE_URL=https://us5-cloud.acronis.com \
ACRONIS_CLIENT_ID=... ACRONIS_CLIENT_SECRET=... npm start

作为 HTTP 运行（网关 / 托管）

CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" MCP_TRANSPORT=http AUTH_MODE=env \
ACRONIS_BASE_URL=https://us5-cloud.acronis.com ACRONIS_CLIENT_ID=... ACRONIS_CLIENT_SECRET=... npm start
# → http://127.0.0.1:8080/mcp, health at http://127.0.0.1:8080/health

不带密钥的本地 HTTP 仅用于开发。它会绑定到 127.0.0.1 并记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Docker

此镜像（node:26-alpine，以用户 acronis 运行）会在容器内监听 0.0.0.0，并默认使用 AUTH_MODE=gateway。无需注册表身份验证或构建密钥。容器需要通过 HTTPS 向 Acronis 数据中心发起出站连接。

docker build --platform linux/amd64 -t acronis-mcp .
docker run -e CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" -p 127.0.0.1:8080:8080 acronis-mcp

当 CONDUIT_S2S_SECRET 未设置时，Compose 会拒绝启动，且不会注入 ACRONIS_*：

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

开发

npm install
npm run lint && npm run typecheck && npm test && npm run build
npm run smoke        # dual-era HTTP smoke test (after build)
npm run gen-tools    # regenerate src/generated/tools.ts

集成测试会启动实际固定版本的软件包。上游版本 1.0.1 在响应 tools/list 前需要令牌端点，因此测试会将 OAUTH_TOKEN_URL（以及临时 HOME）指向本地模拟服务，同时保留 API_BASE_URL=https://example.acronis.com 和虚拟凭据。

许可证

Apache-2.0