Spanning Cloud Backup

Spanning Cloud Backup MCP 服务

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

功能

直接向 AI 助手展示 M365、Google Workspace 或 Salesforce 租户的 SaaS 备份状态——列出已备份的用户、查看受保护的服务、浏览备份历史记录、排队执行恢复，以及审计管理员活动和许可证使用情况。

• 交互式备份状态卡片（MCP Apps，SEP-1865）：spanning_get_user 会在 MCP Apps 宿主（Claude Desktop/web）中呈现为只读交互式卡片，显示用户的备份状态、许可证状态、上次备份时间以及各服务的覆盖情况；默认采用中性色，可通过 window.__BRAND__ 注入或 MCP_BRAND_* 环境变量自定义品牌 （MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、 MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）。在其他宿主中，纯 JSON 行为保持不变。编辑 ui/ 后，运行 npm run build:ui 重新构建内嵌卡片。

工具

工具	用途
spanning_list_users	列出组织中已备份的用户
spanning_get_user	获取单个用户的详细信息
spanning_list_services	列出某用户受保护的服务
spanning_list_backups	列出某用户和服务的备份运行记录
spanning_queue_restore	排队执行恢复（破坏性操作——需要确认）
spanning_get_restore_status	查看恢复进度
spanning_list_audit_log	管理员审计日志（通过日期范围获取信息）
spanning_get_license_usage	已用席位与已购席位
spanning_status	服务状态／运行状况

凭据

复制 .env.example，并设置以下变量。在示例中将 CONDUIT_S2S_SECRET 留空。切勿提交真实密钥。

本地（env 模式）

export SPANNING_PLATFORM="m365"        # or "gws" or "salesforce"
export SPANNING_ADMIN_EMAIL="..."
export SPANNING_API_TOKEN="..."

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

HTTP 传输

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

MCP_ALLOW_INSECURE_DEV=1 仅用于本地开发。设置后，HTTP 会在未设置 CONDUIT_S2S_SECRET 的情况下启动、记录警告、不检查 X-Gateway-S2S，并且仅监听 127.0.0.1。如果 MCP_HTTP_HOST 配置为非环回地址（包括 0.0.0.0），则会将其覆盖为 127.0.0.1 并记录此次覆盖。已知占位密钥仍会被拒绝。

未设置时，MCP_HTTP_HOST 默认为 127.0.0.1。配置了 CONDUIT_S2S_SECRET 时，会遵循 MCP_HTTP_HOST 的设置。容器镜像将 MCP_HTTP_HOST 设为 0.0.0.0，并将 AUTH_MODE 设为 gateway。

X-Gateway-S2S

设置了真实的 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。检查逻辑位于 src/s2s-verify.ts 的 verifyS2sHeader 中：请求头的值为 t=<unix seconds>,v1=<hex>，其中十六进制值是以 CONDUIT_S2S_SECRET 为密钥，对字面字符串 t=<unix seconds> 计算的 HMAC-SHA256（64 个小写十六进制字符）。时间戳与服务器时钟的偏差必须在 300 秒以内。缺少请求头或请求头无效时，会在读取供应商凭据之前返回 HTTP 401。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

托管（网关模式）

AUTH_MODE=gateway（Docker 镜像和 Compose 默认值）要求每个 /mcp 请求都携带以下三个标头，且不会回退到进程环境中的 SPANNING_*：

• X-Spanning-Platform（必需，取值为 m365 | gws | salesforce 之一）
• X-Spanning-Admin-Email（必需）
• X-Spanning-API-Token（必需，机密）

缺少其中任何一个标头，请求都会返回 HTTP 401。将它们添加到上面的签名 curl 命令中。网关 Compose 服务不会设置 SPANNING_PLATFORM、SPANNING_ADMIN_EMAIL 或 SPANNING_API_TOKEN。

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

单租户 HTTP（AUTH_MODE=env）

/mcp 仍要求有效的 X-Gateway-S2S 标头。供应商凭据来自 SPANNING_PLATFORM、SPANNING_ADMIN_EMAIL 和 SPANNING_API_TOKEN。请在该进程中传入这些变量。不要将它们添加到网关 Compose 服务。

变量	必需	描述
SPANNING_PLATFORM	stdio 和 AUTH_MODE=env	m365、gws 或 salesforce
SPANNING_ADMIN_EMAIL	stdio 和 AUTH_MODE=env	Spanning 管理员账户邮箱
SPANNING_API_TOKEN	stdio 和 AUTH_MODE=env	Spanning API 令牌
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose）或 env。网关模式要求提供 X-Spanning-* 标头，且绝不会回退到 SPANNING_*。
CONDUIT_S2S_SECRET	HTTP 必需	服务间 HMAC 密钥。此值为空或为已知占位值时，HTTP 会记录错误并以非零状态码退出。未设置此值时，Compose 不会启动。切勿提交真实值。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为 1，以便在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。此设置会记录警告、跳过 X-Gateway-S2S 验证，并且只绑定到 127.0.0.1。
MCP_HTTP_HOST	否	MCP_TRANSPORT=http 时的绑定地址。默认为 127.0.0.1。设置 CONDUIT_S2S_SECRET 时，此设置生效。容器镜像会将其设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

运行

npm install
npm run build
npm start                       # stdio

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" 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=gateway。将端口发布到回环地址，并传入 S2S 密钥。在网关模式下，Spanning 凭据通过每个请求的标头传入。

docker build --secret id=npmrc,src=$HOME/.npmrc -t spanning-mcp .
docker run --rm \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  spanning-mcp

未设置 CONDUIT_S2S_SECRET 时，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway、发布 127.0.0.1:8080:8080，且不会注入静态 Spanning 凭据：

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

构建镜像需要 GitHub Packages npmrc（docker build --secret id=npmrc,src=$HOME/.npmrc）。单租户 HTTP 仍要求提供 S2S 密钥，之后使用 SPANNING_*：

docker run --rm \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e SPANNING_PLATFORM=m365 \
  -e [email protected] \
  -e SPANNING_API_TOKEN \
  -p 127.0.0.1:8080:8080 \
  spanning-mcp

许可证

Apache 2.0 — 详见 LICENSE。