# Blender MCP（Hardened）

> 面向 Codex 与其他 MCP 客户端的本地 Blender 自动化插件。它通过经过认证的回环 TCP 桥接连接正在运行的 Blender，并以类型化工具覆盖场景读取、建模、材质、动画、渲染和文件工作流。

**English summary:** A hardened, local-first Blender MCP integration with typed tools, authenticated loopback transport, constrained file access, and optional pre-mutation snapshots.

当前插件版本：`0.1.0-hardened.2`。Python 包使用等价的 PEP 440 版本 `0.1.0+hardened.2`。

## 为什么是 hardened 版本

本仓库以 [`kleer001/blender-mcp`](https://github.com/kleer001/blender-mcp) 固定提交 `12feeb50b49cd5e8a3152b5f9ea71fb3b4558b1d` 为基础，并保留上游 MIT 许可与归属。与该上游快照相比，本版本重点收紧了执行面：

- 不注册任意 Python 执行和表达式求值工具，也不注册对应的 Blender 端处理器。
- MCP 进程与 Blender 插件必须共享 `BLENDER_MCP_BRIDGE_TOKEN`，桥接端使用常量时间比较验证请求。
- 导入、导出和保存类工具受 `BLENDER_MCP_ALLOWED_ROOTS` 约束；未配置时文件工具保持关闭。
- 可在高影响修改前创建带时间戳的 `.blend` 快照。
- 默认插件配置仅暴露读取和发现工具；写操作仍由客户端审批并按需开放。
- FastMCP 约束升级为 `>=3.2,<4`，避开 3.2.0 之前已披露的安装命令注入问题，并移除旧锁文件中的易受攻击依赖链。

差异摘要见 [HARDENING.md](HARDENING.md)，许可与来源见 [NOTICE.md](NOTICE.md)。

## 架构与调用链

```text
Codex / MCP client
  └─ stdio MCP：类型化工具、参数校验、审批
       └─ blendermcp（本机 Python 进程）
            └─ 127.0.0.1:9334 + shared token
                 └─ Blender add-on（UI/数据线程）
                      ├─ bpy 场景与数据 API
                      ├─ 允许根目录校验
                      └─ 可选修改前快照
```

组件职责、信任边界和失败模式详见 [docs/architecture.md](docs/architecture.md)。

## 仓库结构

```text
.
├── .codex-plugin/plugin.json     # Codex 插件元数据
├── .mcp.json                     # 不含本机路径和密钥的可移植 MCP 配置
├── blender_addon/                # 在 Blender 内运行的认证桥接插件
├── src/blendermcp/               # MCP 服务、连接层和类型化工具
├── skills/blender/SKILL.md       # Agent 使用策略与安全约束
├── scripts/                      # 安装、启动、发布前检查
├── tests/                        # 离线单元测试和可选真实 Blender 集成测试
├── docs/                         # 架构、路线图和上游文档
├── .env.example                  # 仅变量名；不含任何值
└── pyproject.toml                # Python 构建与依赖定义
```

## 系统要求

- Python 3.10 或更高版本。
- [`uv`](https://docs.astral.sh/uv/)；发布配置用锁文件复现依赖。
- Blender 4.0+；上游快照重点验证 Blender 4.2 LTS。
- MCP 客户端和 Blender 在同一台可信设备上运行。桥接只接受回环地址。

## 安装

### 1. 获取并安装 Python 环境

```powershell
git clone https://github.com/ZNaiGaomu/blender.git
Set-Location blender
./scripts/setup.ps1
```

如需同时复制 Blender 插件，请传入当前 Blender 版本的 add-ons 目录：

```powershell
./scripts/setup.ps1 -BlenderAddonsDirectory "<your-blender-addons-directory>"
```

脚本默认不会覆盖已有插件；确认替换时显式加 `-Force`。

### 2. 配置本机私密信息

复制 `.env.example` 为 `.env`，只在本机填写：

- `BLENDER_MCP_BRIDGE_TOKEN`：随机生成的共享密钥，并在 Blender 插件首选项中填写相同值。
- `BLENDER_MCP_ALLOWED_ROOTS`：允许文件工具访问的一个或多个工作目录。
- `BLENDER_MCP_SNAPSHOT_DIR`：可选的修改前快照目录。

`.env` 已被忽略，禁止提交真实值。建议用密码管理器生成至少 32 字节的随机令牌。

### 3. 启用 Blender 插件

在 Blender 的 **Edit → Preferences → Add-ons** 中启用安装后的插件，在 3D Viewport 的 MCP 面板中配置端口、共享令牌和可选快照目录，然后点击 **Start Server**。

### 4. 启动 MCP 服务

```powershell
./scripts/start.ps1
```

无需 Blender 的协议测试可使用：

```powershell
./scripts/start.ps1 -Mock
```

仓库根目录的 `.mcp.json` 使用 `uv`、相对工作目录和环境变量名，不包含作者机器路径。若客户端不以仓库根目录解析 `cwd: "."`，请在本机客户端配置中将工作目录指向克隆目录；不要把该本机覆盖文件提交到仓库。

## 工具 profile

发布配置采用最小权限的读取 profile，默认允许：连接探测、场景摘要、对象/材质/集合/相机列表，以及渲染设置读取。完整实现按场景、对象、网格、集合、材质、纹理、节点、灯光、相机、动画、绑定、物理、合成、渲染和 I/O 等域提供类型化工具。

需要写操作时，在本机 MCP 配置中仅增加本次任务所需的工具或域，并保留 `default_tools_approval_mode: "writes"`。不要通过改回任意代码执行工具来扩大权限。

## 权限与风险模型

- **场景修改：** 写工具会改变当前 `.blend` 状态；重要任务应先保存原文件并启用快照。
- **文件系统：** 允许根目录是边界，不应配置用户主目录或磁盘根目录。
- **网络：** 桥接必须保持 `127.0.0.1`；不要将端口暴露到局域网或公网。
- **秘密：** 共享令牌只放在本机环境和 Blender 首选项，不写入配置、日志、Issue 或截图。
- **导入内容：** 外部 Blender 文件和资产可能执行驱动器或包含不可信数据，应只处理可信来源。

安全报告流程见 [SECURITY.md](SECURITY.md)。

## 测试与验证

离线可运行的基础验证：

```powershell
uv run --frozen python scripts/publication_check.py
uv run --frozen python -m pytest -q -m "not integration"
uv run --frozen python -m ruff check src blender_addon tests scripts
```

真实 Blender 集成测试需要用户主动启动 Blender 插件并配置临时工作目录。测试不会自动假定现有生产场景可被修改；执行方法见 `tests/integration/`。

CI 使用只读仓库权限，运行发布前隐私检查、静态检查、单元测试和依赖审计。发布包不包含 `.env`、浏览器状态、虚拟环境、构建缓存、用户场景或下载资产。

## 开发与贡献

提交前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。保持类型化工具接口，新增文件工具必须复用允许根目录校验，新增高影响命令必须纳入快照策略，并为认证失败、路径越界和成功路径添加测试。

## 许可证与免责声明

本项目依据 MIT License 分发；上游版权声明保留在 [LICENSE](LICENSE) 和 [NOTICE.md](NOTICE.md) 中。Blender 是 Blender Foundation 的商标。本项目不是 Blender Foundation 的官方产品。