内容
# 拖拉机梁365 MCP
适用于 **Veeam 备份适用于 Microsoft 365 (VB365)** 的模型上下文协议服务器。
它直接与 VB365 REST API 通信，以便 MCP 客户端（Claude Code / Claude Desktop）可以 **查看您的备份配置、查找保护漏洞、发现趋势、验证云不可变性 — 并在您明确选择加入时，运行作业和编排恢复。**
> **独立项目 — 不隶属于、未得到、也未获得 Veeam Software 的认可或支持。** “Veeam” 是 Veeam Software 的注册商标；“Beeam” 的拼写是一个刻意的、独特的文字游戏。使用风险自负。
>
> 名称：**牵引梁** 将您的数据拉回来 — 而 *Beeam* 则对底层备份产品眨眼。只读审查是安全的默认设置；“拉取”（恢复/操作）是按需加入的。
## 两个层级
| 层级 | 默认 | 功能 |
|------|---------|----------------|
| **只读审查** | ✅ 始终开启 | 仅 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` | 交叉检查 **对象锁定** 模式/保留/版本控制在 **存储桶** 级别和 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 到任何其他 `/<version>/...` 资源。 |
## 操作 / 恢复工具（按需加入，需授权）
仅当设置了匹配的标志时才注册。**双重确认模式：** 调用一次以获取预览 +一次性 `confirm_token`；再次调用并带有 `confirm=<token>` 以执行。每次执行都会追加到 `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：打开一个时间点会话，浏览/搜索可恢复项目，然后 **定义** （选择项目 + 目标 + 选项）和 **执行** 恢复。 |
### 恢复：定义 **什么**、**在哪里**、**如何**
```text
restore_session_start(scope="job", scope_id="<jobId>", workload="exchange")
→ { session_id } # 打开一个时间点探索会话
restore_browse(session_id) # 列出邮箱
restore_browse(session_id, parent_id=<mailboxId>) # 列出邮箱中的项目
restore_define(session_id, parent_id=<mailboxId>, item_ids=[...], target="export")
→ { confirm_token, preview } # 预览 — 不会更改任何内容
restore_execute(session_id, confirm=<confirm_token>) # 执行 + 审计
restore_session_stop(session_id)
```
- **目标** = `export`（最安全 — 读取备份到本地文件；无需 M365 凭证）、`alternate`（写入到 **不同的** M365 位置）或 `original`（写回 **原始** 位置 — 破坏性；还需 `confirm_overwrite_original=True`）。
- **选项** 可能带有备用 `mailbox`/`folder` 和 M365 目标凭证，VB365 使用这些凭证写回 (`userName`/`userPassword`/`applicationId`)，或在 `.env` 中设置 `VB365_RESTORE_*`。
- **PST 导出需要 64 位 Outlook 2010+ 安装在 VB365 服务器上** （Veeam 要求）；如果没有，`exportToPst` 将返回服务器端错误。
## 安装
1. **安装 Python 3.10+**，在 Claude Code 运行的位置。
2. 从此文件夹：
```powershell
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_*` 标志。
> REST API 帐户需要是 VB365 管理员（或恢复操作员）— VB365 没有只读 API 角色。只读 **审查** 工具无论如何都是仅 GET 的。`New-VB365ReviewAccount.ps1` 在 VB365 服务器上创建专用服务帐户。 将 `.env` 存放在源代码控制之外。
## 注册到 Claude Code
```powershell
# 将 <repo> 替换为您的克隆的绝对路径。
claude mcp add tractorbeeam365 --scope user -- "<repo>\.venv\Scripts\python.exe" "<repo>\server.py"
```
> 在 Linux/macOS 上使用正斜杠和 `<repo>/.venv/bin/python`。
它也发布到 [MCP 注册表](https://registry.modelcontextprotocol.io) 作为 `io.github.Ringosystems/tractorbeeam-mcp`（GHCR 上的 OCI 镜像），因此支持注册表的 MCP 客户端可以直接安装它。要以 stdio 服务器运行发布的镜像：
```bash
docker run -i --rm \
-e VB365_HOST=... -e VB365_USERNAME=... -e VB365_PASSWORD=... \
ghcr.io/ringosystems/tractorbeeam-mcp:latest
```
然后询问：**“运行 VB365 健康摘要并告诉我是否有任何配置错误。”**
## 启用操作 / 恢复层级
操作/恢复工具在您选择加入之前保持隐藏。在 `.env` 中：
```ini
TB_ENABLE_ACTIONS=true # 主开关
TB_ALLOW_JOB_CONTROL=true # + 您想要的每个类别的标志
TB_ALLOW_RESTORE=true
TB_AUDIT_LOG=audit/actions.jsonl
```
> 操作/恢复工具 **不会** 通过 HTTP 传输注册，除非您还设置 `TB_ALLOW_WRITE_OVER_HTTP=true`，因为该传输没有每个调用者的身份。仅在自己的身份验证反向代理后面运行操作层。
安全模型：工具 **仅在启用时注册**，每个突变需要 **第二个调用和一次性确认令牌**，恢复 **默认为安全目标**（原始位置覆盖需要明确确认），并且 **每个操作都会写入追加审计日志**。推荐：运行一个单独的“操作员”实例并启用标志，默认实例只读。
## 作为持久服务运行（Docker / UNRAID）
镜像本身默认为 stdio 传输（因此 MCP 客户端可以 `docker run -i` 调用它）。通过 `docker compose`，它在容器内 `0.0.0.0:8000` 上运行 `streamable-http`，**只读**（无 `TB_*` 标志）。没有嵌入凭证。HTTP 传输 **关闭失败**：除非您设置 `MCP_AUTH_TOKEN`（客户端随后发送 `Authorization: Bearer <token>`），否则它会拒绝启动，或者您明确接受风险并设置 `MCP_ALLOW_UNAUTHENTICATED_HTTP=true`。
```bash
# 提前将 MCP_AUTH_TOKEN=<一个长随机密钥> 放入 .env 中。
docker compose up -d --build # 构建本地并运行只读
# MCP 在 http://<host>:8766/mcp 上运行；使用以下命令附加：
claude mcp add --transport http tractorbeeam365 http://<host>:8766/mcp \
--header "Authorization: Bearer <token>"
```
### 预构建镜像
每个 GitHub 版本通过 CI 发布多标签镜像（ [.github/workflows/publish.yml](.github/workflows/publish.yml) ）：
```bash
# GitHub 容器注册表（每个版本自动发布）：
docker pull ghcr.io/ringosystems/tractorbeeam-mcp:latest
# Docker Hub（当配置 DOCKERHUB_USERNAME / DOCKERHUB_TOKEN 存储库密钥时发布）：
docker pull ringosystems/tractorbeeam365-mcp:latest
```
手动发布：
```bash
docker build -t <dockerhubuser>/tractorbeeam365-mcp:latest .
docker push <dockerhubuser>/tractorbeeam365-mcp:latest
```
> **安全：** MCP HTTP 传输没有每个调用者的身份。此构建默认绑定回环，需要 `MCP_AUTH_TOKEN` 才能提供 HTTP 服务，并且除非 `TB_ALLOW_WRITE_OVER_HTTP=true`，否则隐藏写入/恢复工具。仍将端口保留在受信任的网络上，并使用 TLS + 身份验证进行前端。审计日志和生成的 PST/报告文件存放在挂载的 `audit/` 和 `downloads/` 卷中。参见 [SECURITY.md](SECURITY.md)。
## 快速连接测试（无需 MCP 客户端）
```powershell
.\.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` 并使用受信任的证书。服务器在启动时如果通道未经验证，则会发出警告。
- 端点名称因 VB365 版本而略有不同。如果一个精选工具 404，请调用 `vb365_api_root` 并使用 `vb365_get` 和确切的资源名称。
## 商标
本项目是独立的，与以下公司无关、未得到其认可或赞助。
- “Veeam”是 Veeam Software 的注册商标。“Beeam”的拼写是一个刻意的、独特的文字游戏，并非商标。
- Microsoft、Microsoft 365、Microsoft Graph、Outlook 和 Office 部署工具是 Microsoft 公司组的商标。
- 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) 贡献。
