Unitrends Backup

Unitrends Backup MCP 服务

一个 Model Context Protocol 服务，可将 Unitrends Backup API 提供给 Claude 和其他 MCP 客户端。

功能

将 Unitrends 设备（或 MSP Console）的备份状况直接呈现给 AI 助手 — 列出设备和受保护资产，监控正在运行和历史备份作业，浏览恢复点，排队执行还原和复制，并查看未关闭的警报和 RPO 合规情况。

• 交互式设备卡片（MCP Apps）：unitrends_get_appliance 在 MCP Apps 宿主（Claude Desktop/web）中以交互式卡片形式呈现；默认不带品牌样式，可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量进行品牌定制；在其他宿主中的纯 JSON 行为保持不变

工具

工具	用途
unitrends_list_appliances	列出 MSP Console 下的设备
unitrends_get_appliance	获取单个设备的详细信息（在 MCP Apps 宿主中以交互式卡片形式呈现）
unitrends_list_assets	列出受保护的资产（需要 applianceId — 缺少时会提示填写）
unitrends_get_asset	获取单个资产的详细信息
unitrends_list_running_jobs	当前正在运行和排队中的备份作业
unitrends_list_job_history	历史作业（提示选择日期范围）
unitrends_list_recovery_points	获取资产的恢复点
unitrends_queue_restore	将还原任务加入队列（破坏性操作 — 需要确认）
unitrends_get_restore_status	检查还原进度
unitrends_list_alerts	未关闭的警报
unitrends_get_success_rate	RPO 合规报告（提示选择日期范围）

凭据

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

本地（env 模式和 stdio）

stdio 传输会读取这些变量，且不会使用 CONDUIT_S2S_SECRET。

export UNITRENDS_BASE_URL="https://unitrends.example.com"
export UNITRENDS_USERNAME="..."
export UNITRENDS_PASSWORD="..."
export UNITRENDS_VERIFY_TLS="true"   # 'false' for self-signed appliances

HTTP 服务到服务认证

当 MCP_TRANSPORT=http 时，必须设置 CONDUIT_S2S_SECRET。如果该变量为空，或值为已知占位符（changeme、change-me、placeholder、secret、example、your-s2s-secret、your-secret、replace-me、replace-with-a-real-secret、s2s-secret），进程会记录错误并以非零状态码退出。进程绝不会打印该密钥。使用 openssl rand -hex 32 生成密钥。

只有设置 MCP_ALLOW_INSECURE_DEV=1 才能在没有该密钥的情况下启动 HTTP。该标志必须恰好为 1。进程会记录警告，不会检查 X-Gateway-S2S，并且仅监听 127.0.0.1。在此模式下，非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录该覆盖设置。已知占位符仍会导致启动失败；若要使用此绕过方式，请取消设置该密钥。

设置了真实密钥时，MCP_HTTP_HOST 会生效，包括 0.0.0.0。如果已设置密钥但未设置 MCP_HTTP_HOST，服务会绑定到 0.0.0.0。未设置密钥时，绑定地址为 127.0.0.1。容器映像会设置 MCP_HTTP_HOST=0.0.0.0。

设置了真实密钥后，每个 /mcp 请求都必须包含 X-Gateway-S2S。其值为 t=<unix seconds>,v1=<hex hmac-sha256>。MAC 是对 ASCII 字符串 t=<unix seconds>（即标头中出现的相同前缀）计算的 HMAC-SHA256，密钥为 CONDUIT_S2S_SECRET。时间戳与服务器时钟的偏差不得超过 300 秒。标头缺失或无效时会返回 401，并且在此之前不会读取任何供应商凭据。

/health 不需要身份验证，不会读取凭据，并作为容器健康检查端点。

托管（网关模式）

AUTH_MODE=gateway（Compose 默认值）要求每个 /mcp 请求都携带以下标头。请求缺少任何必需标头时，将返回 401，且不会回退到进程环境中的 UNITRENDS_*。

• X-Unitrends-Base-URL（必需）
• X-Unitrends-Username（必需）
• X-Unitrends-Password（必需，机密）
• X-Unitrends-Verify-TLS（可选，默认值为 true）
• X-Gateway-S2S（设置了 CONDUIT_S2S_SECRET 时必需）

// Gateway injects vendor credentials and the X-Gateway-S2S proof
const response = await fetch("http://gateway:8080/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    "x-gateway-s2s": "<t=unix,v1=hmac-sha256 of t=unix, keyed with CONDUIT_S2S_SECRET>",
    "x-unitrends-base-url": "https://unitrends.example.com",
    "x-unitrends-username": "your_username",
    "x-unitrends-password": "your_password",
  },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
});

单租户 HTTP（AUTH_MODE=env，镜像默认值）仍要求有效的 X-Gateway-S2S 标头；如果请求未携带凭据标头，则会从环境中读取 UNITRENDS_*。

运行

npm install
npm run build
npm start                       # stdio

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http npm start

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Docker

镜像在容器内监听 0.0.0.0，默认使用 AUTH_MODE=env。请将端口发布到回环地址，并传入 S2S 密钥。如果 CONDUIT_S2S_SECRET 为空或为已知占位符，HTTP 将无法启动。

docker build -t unitrends-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e UNITRENDS_BASE_URL="https://unitrends.example.com" \
  -e UNITRENDS_USERNAME="..." \
  -e UNITRENDS_PASSWORD="..." \
  -p 127.0.0.1:8080:8080 \
  unitrends-mcp

网关模式不会读取这些供应商变量。凭据通过每个请求传入，且请求还必须携带使用 CONDUIT_S2S_SECRET 签名的 X-Gateway-S2S：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=gateway \
  -p 127.0.0.1:8080:8080 \
  unitrends-mcp

如果未设置 CONDUIT_S2S_SECRET 或其值为空，Compose 将拒绝启动；同时会设置 AUTH_MODE=gateway，不会注入 UNITRENDS_BASE_URL、UNITRENDS_USERNAME 或 UNITRENDS_PASSWORD，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

许可证

Apache 2.0 — 参见 LICENSE。