Ringosystems/TractorBeeam-MCP

# TractorBeeam365 MCP 一个用于 **Veeam Backup for Microsoft 365 (VB365)** 的 Model Context Protocol 服务器。 它**直接**与 VB365 REST API 通信，因此 MCP 客户端（Claude Code / Claude Desktop）可以**审查您的备份配置、发现保护漏洞、发现趋势、验证云端不可变性——并且在您明确选择加入时，可以运行作业并执行恢复编排。** ## 两个层级 | 层级 | 默认状态 | 功能 | |------|---------|----------------| | **只读审查** | ✅ 始终开启 | 仅限 GET 请求。无法进行任何更改。配置/健康状态、漏洞分析、趋势、云端锁定交叉检查。 | | **操作 / 恢复** | ⛔ 关闭 | 通过 `TB_*` 环境变量选择加入。运行/停止作业、生成报告、同步组织，**定义 + 执行恢复**。每一次写入都受确认令牌控制并接受审计。 | 如果您从未设置过 `TB_*` 标志，这就是一个纯粹的只读审查器，在*物理层面上无法*修改您的环境——操作/恢复工具甚至都没有被注册。 ## 只读工具（始终可用） | 工具 | 返回内容 | |------|-----------------| | `vb365_health_summary` | 一次性审查：组织、作业 + 最近状态、存储库、**云存储 (B2/S3/Azure)**、代理、许可证、**趋势异常**，以及一个 `flags` 列表。**从这里开始。** | | `vb365_trends` | 每个作业的成功/失败**漂移**，存储库**容量耗尽预测**，每个组织的**恢复测试频率**，**RPO 合规性**。 | | `gap_coverage_summary` / `gap_unprotected_objects` | **备份覆盖率 %** 和**未受保护的**实时 M365 对象，通过将 Microsoft Graph 与作业保护的内容进行比较得出 *（需要 `GRAPH_*`）*。 | | `cloud_lock_audit` | 交叉检查 **bucket** 层面的 **Object Lock** 模式/保留/版本控制，与 VB365 报告的内容进行对比 *（需要 `B2_*`/`S3_*`）*。 | | `vb365_api_root` | 资源列表 + 版本（确认连通性）。 | | `vb365_list_organizations` / `vb365_org_inventory` | 受保护的组织；组织下的用户/群组/站点/团队。 | | `vb365_list_jobs` / `vb365_get_job` / `vb365_job_scope` | 作业列表、单个作业的配置，以及作业确切保护的内容（已选/已排除）。 | | `vb365_list_job_sessions` | 最近的运行结果（可选特定作业）。 | | `vb365_list_repositories` / `vb365_list_restore_points` | 存储库（容量/保留/不可变性）；还原点。 | | `vb365_list_object_storage` / `vb365_get_object_storage` | 云/对象存储 (B2/S3/Azure/Wasabi/IBM/Glacier)。 | | `vb365_list_proxies` / `vb365_license` | 代理 + 状态；许可证/版本/到期时间。 | | `vb365_get` | 对任何其他 `//...` 资源执行只读 GET 请求。 | ## 操作 / 恢复工具（需主动开启，受安全限制） 仅在设置了相应标志时才会被注册。**双重确认模式：** 第一次调用用于获取预览和一次性的 `confirm_token`；再次带上 `confirm=` 进行调用以执行。每次执行都会被追加到 `TB_AUDIT_LOG` 中。 | 工具 (标志) | 功能 | |-------------|--------------| | `action_job` (`TB_ALLOW_JOB_CONTROL`) | 启动 / 停止 / 启用 / 禁用备份作业 | | `action_generate_report` (`TB_ALLOW_REPORTS`) | 邮箱/onedrive/sharepoint/teams/用户保护、许可证、存储报告 → 文件 | | `action_org_sync` (`TB_ALLOW_ORG_SYNC`) | 为组织触发目录重新同步 | | `action_proxy` (`TB_ALLOW_PROXY`) | 重新扫描 / 将代理置于维护模式 | | `restore_session_start` → `restore_browse` / `restore_search` → `restore_define` → `restore_execute` → `restore_status` → `restore_session_stop` (`TB_ALLOW_RESTORE`) | 跨 Exchange / OneDrive / SharePoint / Teams 的**全面恢复编排**：开启一个时间点会话，浏览/搜索可恢复的项目，然后**定义**（选择项目 + 目标 + 选项）并**执行**恢复。 | ### 恢复：定义**内容**、**目标位置**、**方式** ``` restore_session_start(scope="job", scope_id="", workload="exchange") → { session_id } # opens a point-in-time explore session restore_browse(session_id) # list mailboxes restore_browse(session_id, parent_id=) # list items in a mailbox restore_define(session_id, parent_id=, item_ids=[...], target="export") → { confirm_token, preview } # DRY RUN — nothing changed restore_execute(session_id, confirm=) # executes + audits restore_session_stop(session_id) ``` - **目标位置** = `export`（最安全 —— 将备份数据读取到本地文件；不需要 M365 凭据），`alternate`（写入到一个*不同的* M365 位置），或者 `original`（写回到**原始**位置 —— 具有破坏性；还必须传入 `confirm_overwrite_original=True`）。 - **选项** 可以携带备用 `mailbox`/`folder` 以及 VB365 用于写回的 M365 目标凭据（`userName`/`userPassword`/`applicationId`），或者在 `.env` 中设置 `VB365_RESTORE_*`。 - **PST 导出要求在 VB365 服务器上安装了 64 位的 Outlook 2010+**（这是 Veeam 的要求）；如果没有，`exportToPst` 会返回服务器端错误。 ## 设置 1. **安装 Python 3.10+** 到运行 Claude Code 的位置。 2. 从此文件夹中执行： python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt 3. 将 `.env.example` 复制到 `.env` 并填写 `VB365_HOST`、`VB365_USERNAME`、`VB365_PASSWORD`（除非您的情况不同，否则请保持 `VB365_PORT=4443`、`VB365_API_VERSION=v8` 不变）。可选择性地添加 `GRAPH_*`、`B2_*`/`S3_*` 以及 `TB_*` 标志。 ## 注册到 Claude Code ``` # 将 替换为你克隆的绝对路径。 claude mcp add tractorbeeam365 --scope user -- "\.venv\Scripts\python.exe" "\server.py" ``` 它也已发布到 [MCP Registry](https://registry.modelcontextprotocol.io) ，名称为 `io.github.Ringosystems/tractorbeeam-mcp`（GHCR 上的 OCI 镜像），因此支持该注册表的 MCP 客户端可以直接安装。若要以 stdio 服务器方式运行已发布的镜像： ``` docker run -i --rm \ -e VB365_HOST=... -e VB365_USERNAME=... -e VB365_PASSWORD=... \ ghcr.io/ringosystems/tractorbeeam-mcp:latest ``` 然后询问：**"Run a VB365 health summary and tell me if anything is misconfigured."** ## 启用操作 / 恢复层级 在您选择加入之前，操作/恢复工具将保持隐藏状态。在 `.env` 中： ``` TB_ENABLE_ACTIONS=true # master switch TB_ALLOW_JOB_CONTROL=true # + any of the per-category flags you want TB_ALLOW_RESTORE=true TB_AUDIT_LOG=audit/actions.jsonl ``` 安全模型：工具**仅在启用后被注册**，每一次修改都需要**第二次调用并带有一次的确认令牌**，恢复**默认使用安全目标位置**（覆盖原始位置需要明确确认），并且**每一次操作都会写入只追加的审计日志中**。建议：运行一个单独开启标志的 "operator" 实例，而默认实例保持只读。 ## 作为持久服务运行 (Docker / UNRAID) 该镜像在容器内的 `0.0.0.0:8000` 运行 `streamable-http`，**为只读模式**（未开启 `TB_*` 标志）。不会内置任何凭据。HTTP 传输**默认安全关闭 (fails closed)**：除非您设置了 `MCP_AUTH_TOKEN`（客户端随后会发送 `Authorization: Bearer `），否则它将拒绝启动；或者您通过 `MCP_ALLOW_UNAUTHENTICATED_HTTP=true` 明确接受风险。 ``` # 首先将 MCP_AUTH_TOKEN= 放入 .env 中。 docker compose up -d --build # builds locally and runs read-only # MCP 运行在 http://:8766/mcp ；通过以下方式连接： claude mcp add --transport http tractorbeeam365 http://:8766/mcp \ --header "Authorization: Bearer " ``` ### 预构建镜像 每次 GitHub Release 都会通过 CI ([.github/workflows/publish.yml](.github/workflows/publish.yml)) 发布多标签镜像： ``` # GitHub Container Registry（在每次发布时自动发布）： docker pull ghcr.io/ringosystems/tractorbeeam-mcp:latest # Docker Hub（在配置了 DOCKERHUB_USERNAME / DOCKERHUB_TOKEN repo # secrets 后发布）： docker pull ringosystems/tractorbeeam365-mcp:latest ``` 如果需要手动发布： ``` docker build -t /tractorbeeam365-mcp:latest . docker push /tractorbeeam365-mcp:latest ``` ## 快速连通性测试（无需 MCP 客户端） ``` .\.venv\Scripts\Activate.ps1 python -c "import server; print(server.vb365_api_root())" ``` ## 注意事项 - `.gitignore` 排除了 `.env`、venv 以及操作层级的 `audit/`、`downloads/`、`*.pst` 产物。切勿提交凭据或已恢复的数据。 - VB365 附带自签名证书，因此 `VB365_VERIFY_SSL` 默认为 `false`。这会使指向 VB365 的链路容易受到主动中间人攻击，因此建议将 `VB365_CA_BUNDLE` 设置为服务器的证书（对其进行验证开启），或者在使用受信任证书时设置 `VB365_VERIFY_SSL=true`。当通道未验证时，服务器会在启动时发出警告。 - Endpoint 名称因 VB365 版本而略有不同。如果特定的工具返回 404 错误，请调用 `vb365_api_root` 并使用带有确切资源名称的 `vb365_get`。 ## 商标 这是一个独立项目，不附属于、不受认可或不受赞助于以下任何公司。产品名称仅用于识别（指示性使用）。 - "Veeam" 是 Veeam Software 的注册商标。本文使用的 "Beeam" 拼写是故意的、截然不同的文字游戏，并非该商标。 - Microsoft、Microsoft 365、Microsoft Graph、Outlook 和 Office Deployment Tool 是微软集团公司的商标。 - Backblaze 和 B2 是 Backblaze, Inc. 的商标。 - Amazon Web Services、AWS、Amazon S3 和 S3 Glacier 是 Amazon.com, Inc. 或其附属公司的商标。 - Wasabi、IBM 和 IBM Cloud、Azure 以及 Google Cloud 是其各自所有者的商标。 ## 许可证 基于 [MIT License](LICENSE) 发布。有关安全模型和报告，请参阅 [SECURITY.md](SECURITY.md)；如需做出贡献，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。