内容
# Blockbench MCP
让一个LLM **模型、纹理、动画和渲染** 在 [Blockbench](https://blockbench.net) 中通过 [模型上下文协议](https://modelcontextprotocol.io)。
这是一个由两个部分组成的系统，它们相互通信：
```
┌──────────────┐ stdio / MCP ┌────────────────────┐ TCP / NDJSON ┌─────────────────────────┐
│ LLM 客户端 │ ◄─────────────► │ MCP 服务器 │ ◄──────────────► │ Blockbench (桌面端) │
│ (Claude等) │ │ (mcp/server) │ 127.0.0.1 │ + "MCP Bridge" 插件 │
└──────────────┘ └────────────────────┘ └─────────────────────────┘
```
- **`plugin/blockbench_mcp_bridge.js`** — 一个Blockbench插件，在应用程序内运行并托管一个本地TCP控制服务器。它可以完全访问Blockbench的API（`Cube`、`Texture`、`Animation`、`Undo`、`Canvas`等）。
- **`server/`** — 一个独立的Node MCP服务器。您的LLM客户端通过stdio启动它；它连接到插件并将Blockbench的功能暴露为MCP工具。
为什么使用TCP桥而不是普通的MCP进程内服务器？Blockbench的功能存在于运行应用程序的JavaScript上下文中。桥插件在那里运行，具有完全的API访问权限；MCP服务器是一个薄客户端，仅支持stdio。它使用原始TCP（`net`）协议绑定到`127.0.0.1`。
---
## 设置
### 1. 安装Blockbench插件
1. 打开 **Blockbench桌面应用程序** （桥需要Node访问，因此仅限桌面端 — 不是Web应用程序）。
2. `文件 ▸ 插件 ▸` （文件夹图标） **从文件加载插件**。
3. 选择 `mcp/plugin/blockbench_mcp_bridge.js`。 **不要重命名文件** — Blockbench从文件名派生插件ID，它必须保持 `blockbench_mcp_bridge.js`。
4. 第一次，Blockbench会询问网络访问权限（`net`模块）。点击 **允许** （或 *始终允许此插件*）。这只会在`127.0.0.1`上打开一个环回套接字；不会暴露给互联网。
5. 您应该看到一个toast： **“MCP Bridge监听端口19888”**。
该插件添加了三个命令（可通过 `Ctrl/Cmd+F` 或操作搜索）：
`MCP Bridge: 状态`、`MCP Bridge: 重启服务器`、`MCP Bridge: 设置端口`。
> 从文件加载的插件会被记住并在下次启动时自动加载。
#### 获取认证令牌
桥需要一个共享令牌，以便只有您的MCP服务器（而非其他本地程序或网页）可以控制Blockbench。在Blockbench中运行 **`MCP Bridge: 状态`** 并复制 **认证令牌** — 您将在下面的MCP服务器配置中将其粘贴为 `BLOCKBENCH_MCP_TOKEN`。请像密码一样对待它。
### 2. 安装MCP服务器
```bash
cd mcp/server
npm install
```
需要Node ≥ 18。
### 3. 将您的MCP客户端指向它
**Claude Desktop** — 编辑 `claude_desktop_config.json`
（Windows： `%APPDATA%\Claude\claude_desktop_config.json`，
macOS： `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```jsonc
{
"mcpServers": {
"blockbench": {
"command": "node",
"args": ["C:/Users/deadzi/Desktop/blockbench-master/mcp/server/index.js"],
"env": {
"BLOCKBENCH_MCP_TOKEN": "<粘贴从MCP Bridge: 状态获取的令牌>"
}
}
}
}
```
**Claude Code** （CLI）：
```bash
claude mcp add blockbench --env BLOCKBENCH_MCP_TOKEN=<令牌> -- node C:/Users/deadzi/Desktop/blockbench-master/mcp/server/index.js
```
重启客户端。保持Blockbench打开并启用插件 — 然后要求您的助手构建某些内容。
### 配置（环境变量）
| 变量 | 默认值 | 含义 |
|---|---|---|
| `BLOCKBENCH_MCP_TOKEN` | *(必填)* | 共享认证令牌 — 从 `MCP Bridge: 状态` 复制 |
| `BLOCKBENCH_MCP_PORT` | `19888` | TCP端口（必须与插件端口匹配） |
| `BLOCKBENCH_MCP_HOST` | `127.0.0.1` | 桥接主机 |
| `BLOCKBENCH_MCP_TIMEOUT` | `60000` | 每请求超时（毫秒） |
如果您在插件中更改端口（`MCP Bridge: 设置端口`），请设置 `BLOCKBENCH_MCP_PORT` 以匹配。
---
## 工具
| 工具 | 功能 |
|---|---|
| `bb_status` | 连接 + 当前项目摘要（首先调用此工具） |
| `bb_list_formats` | 列出模型格式（`bedrock`、`java_block`、`free`等） |
| `bb_create_project` | 创建一个新的项目/标签，格式为指定格式 |
| `bb_get_project` | 项目详情 + 计数 |
| `bb_save_project` | 将 `.bbmodel` 保存到磁盘 |
| `bb_export_model` | 将原生格式（Java/Bedrock JSON、glTF、OBJ…）导出到磁盘或作为文本 |
| `bb_load_project` | 从路径或原始内容打开模型 |
| `bb_add_cube` | 添加一个盒子（from/to、原点、旋转、父对象、纹理） |
| `bb_add_group` | 添加一个组/骨骼 |
| `bb_add_mesh` | 添加一个自由形式的多边形网格（顶点 + 面） |
| `bb_edit_element` | 更改几何/枢轴/旋转/名称/可见性 |
| `bb_delete_element` | 删除一个元素/组 |
| `bb_duplicate_element` | 复制一个元素/组 |
| `bb_set_parent` | 重新设置一个元素/组的父对象 |
| `bb_list_elements` | 列出所有具有几何形状的元素和组 |
| `bb_create_texture` | 创建一个新的空白（可选填充）纹理 |
| `bb_list_textures` | 列出纹理 |
| `bb_import_texture` | 从PNG数据/ base64添加纹理 |
| `bb_fill_texture` | 用颜色填充整个纹理 |
| `bb_paint_rect` | 绘制一个像素矩形 |
| `bb_paint_pixels` | 设置单个像素（像素艺术） |
| `bb_get_texture` | **查看** 纹理作为图像 |
| `bb_apply_texture` | 将纹理分配给立方体的面 |
| `bb_set_face_uv` | 在立方体面上设置显式UV |
| `bb_auto_uv` | 自动布局UV |
| `bb_get_uv` | 读取立方体的UV布局 |
| `bb_create_animation` | 创建 + 选择动画 |
| `bb_list_animations` | 列出动画/骨骼/关键帧 |
| `bb_select_animation` | 使动画活跃 |
| `bb_add_keyframe` | 在骨骼上添加旋转/位置/缩放关键帧 |
| `bb_set_timeline_time` | 在某个时间（用于渲染帧）对模型进行姿势 |
| `bb_render_view` | **渲染** 模型到PNG（以便LLM可以看到它） |
| `bb_list_actions` | 列出 **所有** Blockbench命令/工具/切换/选择（完整的菜单+工具栏功能集） |
| `bb_get_action` | 有关命令的详细信息 |
| `bb_run_action` | **运行任意** Blockbench命令，ID（通用桥接到整个功能集） |
| `bb_select` | 设置选择的内容（以便基于选择的命令作用于正确的内容） |
| `bb_list_modes` / `bb_set_mode` | 列出/切换编辑器模式（编辑、绘制、动画、显示） |
| `bb_list_settings` / `bb_get_setting` / `bb_set_setting` | 读取/写入任意Blockbench设置 |
| `bb_execute_script` | 运行任意Blockbench JS — 100%覆盖的逃生阀 |
### 完全覆盖
目标是 **所有** Blockbench可以做的事情都可以通过MCP访问。三个层次保证了这一点：
1. **专用工具** （上文）适用于常见的建模/纹理/动画/渲染工作流程。
2. **通用操作桥接** — 每个Blockbench功能都是一个注册命令（`BarItem`）。 `bb_list_actions` 枚举了所有这些（撤销、镜像、居中、转换、父对象、解析、优化、CEM/动画操作、视图模式、每个菜单项...），而 `bb_run_action` 调用任意一个，带有 `value` 用于切换/选择/滑块。结合 `bb_select`、`bb_set_mode` 和设置工具，整个UI都是可驱动的。
3. **`bb_execute_script`** — 针对需要自定义逻辑的任意Blockbench JS。代码是异步函数的正文，因此您可以 `await` 和 `return` 值：
```js
// 返回所有立方体的名称
return Cube.all.map(c => c.name);
```
```js
// 批量操作，带有正确的撤销
Undo.initEdit({ elements: Cube.all });
Cube.all.forEach(c => c.setColor(3));
Canvas.updateView({ elements: Cube.all, element_aspects: { faces: true } });
Undo.finishEdit('Recolor all');
return Cube.all.length;
```
它可以完全访问Blockbench全局变量（`Cube`、`Group`、`Mesh`、`Texture`、`Animation`、`Undo`、`Canvas`、`Project`、`Format`、`BarItems`、`Outliner`、`Painter`、`Timeline`...）。
---
## 示例会话
> *"制作一个Minecraft基岩版鸡：白色身体，带喙的头部，两条腿和一个简单的闲置摇摆动画。*
一个有能力的客户端将大致：
1. `bb_create_project` `{format:"bedrock", name:"chicken", texture_width:16, texture_height:16}`
2. 为 `body`、`head`、`leg_left`、`leg_right` 添加组
3. 为每个部分添加立方体（按正确的分组）
4. 创建纹理 + `bb_paint_rect`/`bb_paint_pixels` 用于皮肤，然后应用纹理
5. 自动布局UV
6. 渲染视图以检查结果，迭代几何/纹理
7. 创建动画 + 在 `body`/`head` 上添加关键帧
8. 设置时间线时间 + 渲染视图以预览帧
9. 保存项目 / 导出模型
---
## 故障排除
- **“Blockbench不可达”/工具超时** — Blockbench是否打开并启用了MCP Bridge插件？在Blockbench中运行 `MCP Bridge: 状态`；它应该显示 *running*。确保端口与 `BLOCKBENCH_MCP_PORT` 匹配。
- **“无效或缺失令牌”/身份验证失败** — 在客户端配置中将 `BLOCKBENCH_MCP_TOKEN` 设置为 `MCP Bridge: 状态` 显示的令牌，然后重启客户端。
- **插件未加载/无toast** — 文件必须命名为 `blockbench_mcp_bridge.js` （ID从文件名派生）。如果您重命名了它，请重命名回原来的名称并重新加载。
- **端口已被占用（EADDRINUSE）** — 另一个Blockbench窗口已经托管了桥接器。关闭它，或使用 `MCP Bridge: 设置端口` 选择一个空闲端口并设置 `BLOCKBENCH_MCP_PORT` 以匹配。
- **“没有打开的项目”** — 首先调用 `bb_create_project` （或打开模型）。
- **动画工具错误** — 当前格式必须支持动画（例如 `bedrock`、`modded_entity`）。使用此类格式创建项目。
- **权限被拒绝** — 重新启用插件并点击 *允许* 请求网络访问时。
- **更改了插件代码** — 使用 `文件 ▸ 插件`，右键单击插件， **重新加载** （或开发 *重新加载插件* 操作）。服务器被干净地终止并重新启动。
## 安全
桥接器仅监听 `127.0.0.1` （不能从网络访问） **并且** 需要共享令牌：每个连接必须完成身份验证握手，其第一行是 `{"type":"auth","token":...}` 才能接受任何命令。这有两个效果：
- **网页无法访问它。** 跨源 `fetch`/WebSocket始终发送HTTP前缀；该前缀无法解析为身份验证握手，因此套接字在任何命令运行之前被丢弃 — 关闭了直接访问/CSRF向量。
- **其他本地程序需要令牌。** 没有 `BLOCKBENCH_MCP_TOKEN` 它们将被拒绝。
尽管如此，`bb_execute_script` 在Blockbench内部运行任意代码（通过应用程序访问文件系统），因此 **请保密令牌** 并仅在您打算使用它时启用插件。要轮换令牌，请在浏览器控制台中清除它（`localStorage.removeItem('mcp_bridge_token')`）并重新加载插件；一个新的令牌将被生成并在 `MCP Bridge: 状态` 中显示。
## 开发
```bash
cd mcp/server
npm test # 端到端烟雾测试对抗模拟桥接器（不需要Blockbench）
node --check ../plugin/blockbench_mcp_bridge.js
```
`server/tools.js` 中的方法名称和参数形状是 `plugin/blockbench_mcp_bridge.js` 实现的契约。要添加功能：在插件中添加处理程序，并在 `tools.js` 中添加匹配的工具。
