内容
# Blender MCP 服务器
用于 **Cursor** 控制 **Blender** 的MCP服务器，通过本地HTTP桥接实现。
`bpy` 在 **Blender** 内运行 — 该仓库不直接导入 `bpy` 到 MCP进程中。
**与 [Summit](../summit) 分离** — 准备好时导出 `.glb` 文件到 Summit 的 `Assets/` 目录。
## 架构
```
Cursor 代理 → MCP（此仓库）→ HTTP 桥接 → bpy → Blender
```
| 路径 | 角色 |
|------|------|
| `server.py` | MCP 入口（标准输入/输出） |
| `mcp_server/` | 暴露给代理的工具 |
| `blender_addon/blender_mcp_bridge/` | Blender 插件（HTTP + bpy 命令） |
| `config.json` | 桥接端口，Summit 导出路径，默认 `.blend` 文件 |
Blender 5.1: `/home/juan/blender-5.1.2/blender`
## 快速开始
### 1. 安装 MCP 服务器（Python）
```bash
cd /home/juan/source/blender_mcp_server
./scripts/setup_mcp.sh
cp config.example.json config.json # 根据需要编辑路径
```
### 2. 安装 Blender 插件
```bash
BLENDER_VERSION=5.1 ./scripts/install_addon.sh
# 检测版本: ls ~/.config/blender/
```
在 Blender 中：
1. **编辑 → 首选项 → 插件** → 启用 **Blender MCP Bridge**
2. **N 面板 → MCP 标签 → 启动服务器** （默认 `http://127.0.0.1:9876`）
或使用默认导出 blend 文件启动无界面模式：
```bash
./scripts/start_bridge.sh
```
日志：此仓库中的 `bridge.log`。覆盖 blend 文件：`BLENDER_MCP_BLEND=/path/to/file.blend ./scripts/start_bridge.sh`
### 3. 连接 Cursor
将 `cursor.mcp.example.json` 合并到 `~/.cursor/mcp.json` 中：
```json
{
"mcpServers": {
"blender": {
"command": "/home/juan/source/blender_mcp_server/.venv/bin/python",
"args": ["/home/juan/source/blender_mcp_server/server.py"],
"env": {
"BLENDER_MCP_CONFIG": "/home/juan/source/blender_mcp_server/config.json"
}
}
}
}
```
重启 Cursor。在动画时打开此文件夹作为工作空间。
### 4. 测试
Blender 桥接运行中：
```bash
curl -s http://127.0.0.1:9876/health
```
在 Cursor 聊天（启用 MCP）：
> 使用 `ping_blender`，然后是 `scene_information`
## MCP 工具
**连接：** `ping_blender`，`get_server_config`
**检查：** `scene_information`，`list_objects`，`list_armatures`，`list_bones`，`list_actions`，`get_object_transform`
**动画：** `create_action`，`rename_action`，`set_active_action`，`set_frame`，`set_bone_rotation_keyframe`，`set_action_loop_mode`
**导出/验证：** `export_gltf`，`export_to_summit`，`validate_scene_scale`，`validate_action_root_motion`，`validate_rts_asset`，`render_preview`
**建模（配方）：** `create_summit_bobcat` — 低多边形收获者模型 + `idle` / `harvest` 动画
### 桥接独有命令（尚非 MCP 工具）
通过 `scripts/run_command.py` 或 HTTP 桥接调度调用：
| 命令 | 目的 |
|---------|---------|
| `create_natural_idle_action` | 从姿势帧创建呼吸 idle 动作（四元数偏移） |
| `create_rifle_attack_action` | 前方枪械瞄准 + 后坐力剪辑 |
| `create_idle_action` | 从源动作创建静态保持 |
| `prepare_rifleman_locomotion` | 导入行走 GLB，重新映射骨骼，去除髋部运动，创建 idle |
| `duplicate_action` | 复制动作 |
| `strip_action_root_motion` | 删除根骨骼位置键 |
## 当前人类步兵管道
源 blend 文件位于 `~/Documents/BlenderSaves/summit/`：
| 文件 | 内容 |
|------|---------|
| `riflemenStand.blend` | `idle` — 自然呼吸（~48 帧） |
| `riflemenwalk.blend` | `walk` — 原地 **枪械奔跑** 短跑（22 帧） |
| `riflemenfire.blend` | `attack` — 枪械瞄准 + 后坐力（~24 帧） |
| `riflemenExport.blend` | 合并主 blend（idle + walk + attack） |
| `riflemen-backup-dont-edit.blend` | 安全备份 |
**从站立姿势重新生成行走 + 攻击** （运行 FBX + 程序化射击），然后合并 + 导出：
```bash
/home/juan/blender-5.1.2/blender --background --python scripts/prepare_rifleman_animations.py
```
**身体纹理（Ch36）：** 从 `riflemenStand.blend` 合并导出（绘制网格）。导出程序重建 `Ch36_Body` 以适应 glTF PBR，并将打包图像同步到 GLB。如果 Godot 中的侧车 PNG 看起来过时，请重新导入 `Rifleman.glb` 或运行：
```bash
/home/juan/blender-5.1.2/blender --background --python scripts/fix_and_export_rifleman_body.py
/home/juan/blender-5.1.2/blender --background --python scripts/extract_textures_from_glb.py
```
**仅重新导出** （如果行走/射击 blend 文件已存在）：
```bash
/home/juan/blender-5.1.2/blender --background --python scripts/prepare_rifleman_export.py
```
输出：`/home/juan/source/summit/Assets/Units/Human/Rifleman.glb`
Godot 视图：`Scenes/Units/HumanRiflemanView.tscn`（动画 `idle`，`walk`，`attack`）。
枪械网格在射击 blend 文件中依附于 `mixamorig1:RightHand`。攻击使用显式瞄准四元数（+Y枪管向前），而非复制的行走姿势。
或通过 MCP 从打开的 blend 文件中导出：
```
export_to_summit(target_key="summit_human_units", filename="Rifleman.glb", action_names=["idle","walk","attack"])
```
## Bobcat 收获者（载具配方）
### V2（RTS 零件目录 — 推荐）
从可重复使用的机械零件进行程序化 **Generals-style** 装配：
```bash
BLENDER_VERSION=5.1 ./scripts/install_addon.sh
/home/juan/blender-5.1.2/blender --background --python scripts/create_summit_bobcat_v2.py
```
输出 blend 文件：`~/Documents/BlenderSaves/summit/bobcatExport.blend`
剪影预览：`~/Documents/BlenderSaves/summit/bobcat_v2_silhouette.png`
输出 GLB：`/home/juan/source/summit/Assets/Units/Human/Bobcat.glb` (`idle`，`harvest`)
MCP：`create_summit_bobcat_v2`，`validate_rts_asset`，`validate_rts_silhouette`，`render_rts_silhouette_preview`
零件目录（`modeling/parts/`）：驾驶室，轮子，桶，液压，底盘，挡泥板，排气管，头灯，手臂，格栅。
动画枢轴（稳定的 Godot 合同）：`Bobcat_Arm_L`，`Bobcat_Arm_R`，`Bobcat_Bucket`。
### V1（模型）
```bash
/home/juan/blender-5.1.2/blender --background --python scripts/create_summit_bobcat.py
```
## Summit 导出
`config.json` 中的配置键：
```json
"export_targets": {
"summit_human_units": "/home/juan/source/summit/Assets/Units/Human",
"summit_props": "/home/juan/source/summit/Assets/Props"
}
```
默认 blend 文件：`riflemenExport.blend`（参见 `config` 中的 `default_blend`）。
然后切换工作空间到 `/home/juan/source/summit` 以连接 Godot 视图和模拟。
## Summit 约定
| 规则 | 值 |
|------|--------|
| 缩放 | 1 Blender 单位 = 1 米 |
| 步兵高度 | ~**1.6 米** (`Ch36` 参考网格) |
| 前方 | **+Y** 在 Blender 中 |
| 动画名称 | `idle`，`walk`，`attack`，`death`（步兵）；载具：`idle`，`harvest` |
| 载具三角预算 | **2500** 三角（模型配方） |
| 移动 | 行走 **原地** — 无髋部平移 (`validate_action_root_motion`) |
另请参阅 Summit [玩家身份](../summit/docs/02-Architecture/player-identity.md) 以获取 **团队颜色遮罩**，在创作单位时：
- 在 Blender 中绘制色调区域（顶点颜色或 `*_TeamMask.png`）
- 每个单位类型一个 GLB；在 Godot 中运行时应用玩家颜色
- 人类 = 军事涂装区域；机器人 = LED 发光遮罩；等等
## 无界面模式
```bash
blender mychar.blend --background --python scripts/run_command.py -- '{"command":"scene_information","args":{}}'
```
## 路线图
- [x] 步兵 idle / walk / attack 管道 + `prepare_rifleman_export.py`
- [x] Bobcat 模型配方 + `create_summit_bobcat.py`
- [x] `validate_rts_asset` + MCP 建模工具
- [x] `create_natural_idle_action`，`create_rifle_attack_action`（桥接）
- [x] `start_bridge.sh` 无界面桥接守护进程
- [ ] 将移动命令暴露为 MCP 工具
- [ ] Summit 着色器团队颜色遮罩验证/导出提示
- [ ] 步兵 `death` 动画
- [ ] 绑定辅助工具
- [ ] 自动工具注册审查门控
