Slide

Slide MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 Slide 备份/BDR（业务连续性/灾难恢复）API MCP 服务，可查看账户、Agent、设备、网络、备份、快照和还原信息。

身份验证

Slide 使用静态 Bearer API 令牌进行身份验证，该令牌在 Slide Console（Settings > API Keys）中按账户签发，不使用 OAuth。此连接器不会生成或刷新任何内容：它只持有有效令牌，并将其作为 Authorization: Bearer <token> 发送至 api.slide.tech。在网关模式下，令牌通过每个请求的 X-Slide-Api-Token 标头传入，缺少该标头的请求会被拒绝。在本地/stdio 模式以及 HTTP AUTH_MODE=env 模式下，令牌从 SLIDE_API_TOKEN 读取。

配置

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

Env var	Description
SLIDE_API_TOKEN	静态 Bearer API 令牌，在 Slide Console 中签发。stdio 和 HTTP AUTH_MODE=env 模式必须设置。网关 Compose 服务不会设置此变量。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，从 SLIDE_API_TOKEN 读取）或 gateway（每个 /mcp 请求都必须携带 X-Slide-Api-Token，且绝不会回退到环境变量）。Docker 镜像和 Compose 文件会将其设为 gateway。
CONDUIT_S2S_SECRET	HTTP 模式必需。用于 /mcp 上 X-Gateway-S2S 的 HMAC 密钥。使用 openssl rand -hex 32 生成。如果该变量为空或使用了已知占位值（changeme、your-s2s-secret、replace-with-a-real-secret 及其他公开示例值），HTTP 服务端会记录错误并以非零状态码退出。该值绝不会被记录。未设置或为空时，Compose 不会启动。
MCP_ALLOW_INSECURE_DEV	必须恰好设为 1，才能在未设置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。服务会记录警告，不会强制要求 X-Gateway-S2S，且仅绑定到 127.0.0.1（更宽泛的 MCP_HTTP_HOST 设置会被忽略）。使用已知占位密钥时仍会拒绝启动。仅限本地开发。
MCP_HTTP_HOST	MCP_TRANSPORT=http 时的绑定地址。默认为 127.0.0.1。设置了 CONDUIT_S2S_SECRET 时此项生效。容器镜像将其设为 0.0.0.0。未设置密钥时，仅监听 127.0.0.1。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

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

HTTP 身份验证

当设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须携带 X-Gateway-S2S。校验逻辑位于 src/s2s-verify.ts 的 verifyS2sHeader 中：标头值格式为 t=<unix seconds>,v1=<hex>，其中 hex 是以 CONDUIT_S2S_SECRET 为密钥，对字面字符串 t=<unix seconds> 计算的 HMAC-SHA256 值（64 个小写十六进制字符）。时间戳与服务器时钟的差值必须在 300 秒以内。标头缺失或无效时会返回 HTTP 401，且在此之前不会读取 Slide 令牌。

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}" \
  -H "X-Slide-Api-Token: $SLIDE_API_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求携带 X-Slide-Api-Token。该标头是此请求唯一的凭据来源。标头缺失时会返回 HTTP 401，且不会回退到 SLIDE_API_TOKEN。

AUTH_MODE=env 模式仍要求有效的 X-Gateway-S2S 标头；如果请求未携带 X-Slide-Api-Token，则使用 SLIDE_API_TOKEN。

请求限制

• HTTP 请求正文上限为 256 KiB（262144 字节）。通过 X-Gateway-S2S 检查，以及在 AUTH_MODE=gateway 时通过 X-Slide-Api-Token 存在性检查后，若 Content-Length 超过上限，将返回包含 JSON-RPC 错误的 413 响应。没有 Content-Length 的正文则由 MCP SDK 传输层限制。未认证的请求仍会优先收到 401。
• tools/call 参数上限为 10,000 个元素（包括任意深度的每个数组项和对象键）。超出上限的输入会返回 isError 工具结果，且不会被分发。

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

工具

账户

• slide_list_accounts - 列出账户，可按创建日期筛选。
• slide_get_account - 按 ID 获取单个账户。

Agent

• slide_list_agents - 列出 Agent（受保护的系统），可按设备、客户端、类型和配对日期筛选。
• slide_get_agent - 按 ID 获取单个 Agent（备份计划、保留策略、卷、警报配置）。
• slide_search_agent_files - 搜索 Agent 受保护系统中已索引的文件路径。
• slide_get_agent_file_versions - 获取 Agent 上某个文件路径可用的快照版本。
• slide_get_agent_services - 获取在 Agent 上检测到的已备份服务。

警报

• slide_list_alerts - 列出警报，可按设备、Agent、解决状态和创建日期筛选。
• slide_get_alert - 按 ID 获取单个警报。

审计

• slide_list_audit_logs - 列出审计日志条目，可按操作、资源类型、客户端和时间范围筛选。
• slide_list_audit_actions - 列出全部审计操作名称。
• slide_list_audit_resource_types - 列出全部审计资源类型名称。
• slide_get_audit_log - 按 ID 获取单个审计日志条目。

备份

• slide_list_backups - 列出备份尝试，可按 Agent、快照、设备和时间范围筛选。
• slide_get_backup - 按 ID 获取单个备份尝试。

账单

• slide_list_billing_credit_memos - 列出账单贷项通知单。
• slide_list_billing_invoices - 列出账单发票。
• slide_list_billing_subscriptions - 列出订阅和设备许可证。

客户端

• slide_list_clients - 列出客户端（MSP 的终端客户），可按创建日期筛选。
• slide_get_client - 按 ID 获取单个客户端。

设备

• slide_list_devices - 列出设备（实体／虚拟 Slide Box），可按客户端和创建日期筛选。
• slide_get_device - 按 ID 获取单个设备。
• slide_get_device_network - 获取设备的网络配置。
• slide_list_device_vlans - 列出设备配置的 VLAN。
• slide_get_device_vlan - 按 ID 获取设备上的单个 VLAN。

网络

• slide_list_networks - 列出灾难恢复网络，可按客户端和创建日期筛选。
• slide_get_network - 按 ID 获取单个网络（端口转发、IPsec 连接、WireGuard 对等节点）。

恢复（文件）

• slide_list_file_restores - 列出文件恢复，可按创建日期筛选。
• slide_get_file_restore - 按 ID 获取单个文件恢复。
• slide_browse_file_restore - 浏览文件恢复所公开的文件／文件夹。
• slide_list_file_restore_pushes - 列出文件恢复的推送操作，可按时间范围筛选。
• slide_get_file_restore_push - 获取单个文件恢复推送的状态。

恢复（映像）

• slide_list_image_exports - 列出映像导出，可按创建日期筛选。
• slide_get_image_export - 按 ID 获取单个映像导出。
• slide_browse_image_export - 浏览映像导出所公开的文件／文件夹。

恢复（虚拟机）

• slide_list_virtual_machines - 列出从快照创建的虚拟机，可按创建日期筛选。
• slide_get_virtual_machine - 按 ID 获取单个虚拟机。

快照

• slide_list_snapshots - 列出快照，可按 Agent、位置／删除状态和时间范围筛选。
• slide_get_snapshot - 按 ID 获取单个快照。
• slide_get_snapshot_service_verification - 获取快照的服务验证结果。

用户

• slide_list_users - 列出用户，可按创建日期筛选。
• slide_get_user - 按 ID 获取单个用户。
• slide_get_user_avatar - 获取用户的头像图像（base64 数据 URL）。

范围

这是一个有意设计为只读且不暴露凭据的 v1 接口面，涵盖 Slide 的全部 43 个不暴露机密的 GET 端点。Slide 是备份／灾难恢复基础设施——它的多个真实端点会返回有效机密，所有变更端点也都不在 v1 范围内。此处未实现任何被排除的内容，这是有意为之，并非疏忽。鉴于备份／灾难恢复基础设施数据（客户端环境、设备清单、网络拓扑）的敏感性，Conduit 接线中的每个工具都被标记为 isAdmin: true。

含机密字段——从原本有用的响应中剥离，绝不作为透传字段实现：

• Agent.passphrases[].passphrase（有效的 Agent 加密口令）——从 slide_list_agents / slide_get_agent 中剥离。保留口令的 name 和 agent_passphrase_id。
• Network.ipsec_conns[].psk（有效的 IPsec 预共享密钥）——从 slide_list_networks / slide_get_network 中剥离。
• Network.wg_peers[].wg_private_key（有效的 WireGuard 私钥）——从上述两个工具中剥离。wg_public_key 并非机密，因此予以保留。
• VirtualMachine.vnc_password（有效的 VNC 密码）——从 slide_list_virtual_machines / slide_get_virtual_machine 中剥离。vnc 连接信息数组（主机／端口／WebSocket URI）和 vnc_enabled 并非机密，因此予以保留。
• ImageExport.password（导出共享目录的有效 Samba 密码）——从 slide_list_image_exports / slide_get_image_export 中剥离。此字段并非 Slide 重点标示的“机密”端点之一，但它与上述四项属于同类有效凭据材料，因此遵循同样的标准。

**严格排除（变更操作）——所有 POST/PATCH/PUT/DELETE 端点均不实现：**创建／更新客户端、网络、设备、Agent、VLAN；启动备份；创建文件／映像／VM 恢复和推送操作；管理 IPsec 连接、端口转发和 WireGuard 对等端；添加／删除 Agent 口令；重启／关闭设备；以及所有标签下的其他写入操作。这些操作会对真实基础设施造成破坏或变更（删除客户端、删除网络、删除恢复任务、重启设备），因此按设计不在 v1 范围内。

不在 v1 范围内（并非凭据／配置操作，只是不属于此连接器的结构化数据接口面）：

• GET /v1/billing/credit-memo/{id}/pdf（BillingCreditMemoPDF）——返回原始 application/pdf 二进制数据，而非结构化数据。
• GET /v1/billing/invoice/{id}/pdf（BillingInvoicePDF）——同上。

如果有需求，可在经过审慎的范围决策后作为后续功能添加——不会默认加入。

凭据范围

此连接器的代码在设计上只能读取数据——但 Slide 也提供了一种真正可行的方式，可让底层凭据本身也只能读取数据，我们建议使用这种方式。

Slide 记录了六种账户角色：账户所有者、账户管理员、业务连续性技术员、账单，以及只读（对所有资源具有只读访问权限）。API 令牌会继承在 Slide Console（Settings → API Keys）中生成令牌的用户角色。

建议：使用具有只读角色的专用用户为此连接器生成 API 令牌，而不是使用账户所有者／管理员用户。这意味着，即使令牌泄露到 Conduit 控制范围之外（例如凭据存储遭到入侵、日志配置错误等），也无法用它删除备份、恢复项、网络或设备——这样一来，连接器自身的只读代码与只读凭据相互配合，而不是仅依赖连接器代码作为唯一保障。

以下两项声明的置信度级别不同：

• **结构上已验证（直接检查，完全确信）：**此连接器的代码不会执行任何修改操作（client.ts 中恰好只有一个 HTTP 动词函数 doGet），并且会在每个响应到达工具结果之前，移除五个实时机密字段（Agent 密语、IPsec PSK、WireGuard 私钥、VM VNC 密码、映像导出 Samba 密码）——请参阅 secret-redaction.test.ts。
• **供应商文档所述，未经独立验证（有意保留谨慎措辞）：**只读角色的限制是否会在服务器端对所有修改端点生效（而非仅在控制台 UI 中隐藏这些端点），尚未通过实际的只读账户进行测试。此角色也需要主动选择，并非默认角色——来自账户所有者／管理员用户的令牌（新账户的常见情况）没有此类限制。

请勿将此连接器或此 README 解读为已证明所有 Slide 令牌都只能读取数据——我们只能确认，此连接器自身的代码从不尝试执行修改操作，而且 Slide 提供了一种（但并非默认启用的）方式，也可以让凭据本身只能读取数据。

开发

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

Docker

映像会在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。请在环回地址上发布端口，并传入 S2S 密钥。在 gateway 模式下，每个请求都会通过 X-Slide-Api-Token 传入 Slide 令牌。令牌不会从环境变量中读取。

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

如果未设置 CONDUIT_S2S_SECRET 或其值为空，Compose 会拒绝启动。gateway 服务不会设置 SLIDE_API_TOKEN，也不会使用 env_file，因此项目的 .env 文件无法注入静态供应商凭据。Compose 仍会从该文件插值获取 CONDUIT_S2S_SECRET。发布的端口为 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍要求提供 S2S 密钥，然后使用 SLIDE_API_TOKEN：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SLIDE_API_TOKEN="$SLIDE_API_TOKEN" \
  -p 127.0.0.1:8080:8080 \
  slide-mcp

不带密钥的本地 HTTP 仅用于开发。它只绑定到 127.0.0.1（非环回地址的 MCP_HTTP_HOST，包括 0.0.0.0，都会被忽略并记录该覆盖设置），并会记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http