内容
# ViperMesh for Blender
[](https://github.com/Ker102/vipermesh-blender/actions/workflows/ci.yml)
[](https://github.com/Ker102/vipermesh-blender/releases)
[](LICENSE)
[](https://modelcontextprotocol.io/)
**适用于 AI 代理的持久化 Model Context Protocol 服务器和确定性 Blender 插件**
ViperMesh for Blender 为兼容 MCP 的代理提供结构化的场景检查、可重用的 Blender 操作、有界批次、本地 3D 工作流指导和明确的 Python 回退。它旨在减少重复的 Blender API 代码，同时不阻止真正自定义的几何或场景工作。
## 为什么选择 ViperMesh for Blender？
许多 Blender 代理集成只公开了一小部分检查调用加上任意 Python 执行。ViperMesh 在保留这一出口的同时，为常见操作添加了广泛的确定性工具表面。
| 能力 | 提供内容 |
| --- | --- |
| 持久会话 | 一个 MCP 进程和一个序列化的 Blender 连接，每个代理会话 |
| 确定性工具 | 用于装配、材质、相机、照明、渲染、绑定、UV、重拓扑、导出和检查的结构化操作 |
| 场景验证 | 检查接地、支撑、间隙、空间关系、文件健康和渲染伪影 |
| 紧凑工作流 | 有界批次调用加上单独的构建、检查/修复和完成阶段 |
| 代理入职 | 会话启动、MCP 资源、简洁的操作规则和本地任务指南 |
| 自定义回退 | 当确定性操作不是合适的工具时，`execute_code` 仍然可用 |
## 架构
```text
MCP 兼容代理
|
| 标准输入输出，一个长-lived 进程
v
ViperMesh MCP 服务器
|
| 序列化 loopback 连接
v
ViperMesh Blender 插件 (127.0.0.1:9876)
|
v
Blender 场景
```
MCP 服务器不打开网络监听器。Blender 插件默认监听 loopback 并在 ViperMesh 侧边栏中报告 **Stopped**、**Ready**、**Agent connected** 或 **Error**。
## 要求
- Blender 5.2 作为当前测试版本的目标
- Node.js 20 或更新版本
- 支持 stdio 服务器的 MCP 兼容客户端
## 安装
### 1. 安装 Blender 插件
从 [最新版本](https://github.com/Ker102/vipermesh-blender/releases/latest) 下载 `vipermesh-addon.py`。在 Blender 中：
1. 打开 **编辑 > 首选项 > 插件**。
2. 选择 **从磁盘安装** 并选择下载的 Python 文件。
3. 启用 **ViperMesh for Blender**。
4. 打开 3D 视口侧边栏，选择 **ViperMesh** 并点击 **启动本地桥接**。
保持桥接运行以完成代理会话。
### 2. 安装 MCP 服务器
在 npm 包发布之前，克隆存储库并安装它：
```bash
git clone https://github.com/Ker102/vipermesh-blender.git
cd vipermesh-blender
npm install
npm run build
```
### 3. 配置 MCP 客户端
使用绝对存储库路径：
```json
{
"mcpServers": {
"vipermesh-blender": {
"command": "npm",
"args": ["run", "mcp"],
"cwd": "C:/绝对路径/to/vipermesh-blender"
}
}
}
```
通过 MCP 客户端启动此命令一次。不要为每个 Blender 操作调用 `npm`、`npx` 或 `tsx`。
## 首次代理调用
1. 调用 `bootstrap_vipermesh_session`。
2. 使用 `call_blender_tool(name="get_scene_info")` 检查场景。
3. 使用 `search_3d_guidance` 搜索任务指导。
4. 使用 `list_blender_tools` 发现相关功能。
5. 构建、检查和修复，然后完成并保存。
公共 MCP 接口包括：
- `bootstrap_vipermesh_session`
- `check_blender_connection`
- `list_blender_tools`
- `call_blender_tool`
- `call_blender_tool_batch`
- `run_blender_scene_stage`
- `get_blender_agent_context`
- `search_3d_guidance`
- `get_3d_guidance_document`
阅读 [完整连接手册](docs/portable-blender-mcp.md) 以获取请求形状、批处理规则、分阶段工作流、本地指导和故障排除。
## 安全
此连接器适用于受信任的本地工作站。`execute_code` 可以在 Blender 中运行任意 Python 代码。仅连接受信任的 MCP 客户端，保持桥接在 loopback 上，并审查高影响或破坏性操作。
参见 [SECURITY.md](SECURITY.md) 以获取信任边界和私有漏洞报告流程。
## 公共连接器范围
此存储库包含开源 Blender 插件、便携式 MCP 服务器、本地操作指导和连接器测试。它不包括 ViperMesh 应用程序、身份验证、计费、私有提示、私有 RAG 数据、云模型路由、私有资产或基准证据。
连接器不捆绑商业 3D 生成提供商。可以稍后通过提供商中立的身份验证服务添加神经生成，而无需在 Blender 中嵌入第三方凭证。
## 常见问题
### ViperMesh 是否取代 `execute_code`？
不，它通过提供结构化操作减少了不必要的生成的 Blender Python 代码，但保留了 `execute_code` 用于自定义几何、程序效果、不寻常的节点图和未覆盖的工作流。
### 为什么 MCP 进程必须保持运行？
该进程保留与 Blender 的序列化连接。为每个调用重新启动它会增加不必要的启动、传输和代理-工具开销。
### 公共连接器是否需要 ViperMesh 云身份验证？
不，公共插件和本地 MCP 服务器无需 ViperMesh 身份验证。未来托管模型和专有编排是单独的产品功能。
### 它可以使用已安装的 Blender 插件吗？
连接器可以检查已安装的插件并支持受信任的本地自动化。在将其公开为可调用的代理功能之前，应审查未知的插件操作。
## 开发
```bash
npm install
npm run check
python -m py_compile addon/vipermesh-addon.py
```
在打开拉取请求之前，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证和归属
ViperMesh for Blender 在 [MIT 许可证](LICENSE) 下发布。它包含由 Siddharth Ahuja 衍生的作品，参见 [NOTICE.md](NOTICE.md) 以获取归属和商标通知。
