内容
# Substance Painter MCP
一个MCP服务器，封装了Adobe Substance 3D Painter的远程脚本REST API，提供10个工具。允许LLM代理驱动Painter端到端：创建项目、导入纹理、创建带有PBR通道连接的填充层、无需弹出对话框即可烘焙网格图、导出纹理。
单文件`FastMCP`标准输入/输出服务器。唯一的运行时依赖是`mcp`。
## 要求
- Adobe Substance 3D Painter（已针对10.x / 11.x版本进行测试 — 任何带有`--enable-remote-scripting`的版本）
- Python 3.10+
- `mcp`（FastMCP）
## 安装
```bash
pip install -r requirements.txt
```
## 启动带有远程脚本的Substance Painter
```bat
"C:\Program Files\Adobe\Adobe Substance 3D Painter\Adobe Substance 3D Painter.exe" --enable-remote-scripting
```
包含一个便捷启动器：`launch_sp_remote.bat`。
远程API监听`localhost:60041`（HTTP，base64编码有效载荷）。
## 连接到您的MCP客户端
添加到您的`mcp.json`（或等效文件）：
```json
{
"mcpServers": {
"substance-painter": {
"command": "python",
"args": ["C:/path/to/substance-painter-mcp/sp-mcp.py"]
}
}
}
```
## 工具
| 工具 | 用途 |
|---|---|
| `check_connection` | 验证SP是否启动且启用了远程脚本。返回API版本和项目打开状态。 |
| `create_project` | 从网格文件新建项目。可配置法线贴图格式、默认分辨率、相机导入。 |
| `open_project` | 打开现有的`.spp`文件。 |
| `save_project` | 就地保存，或另存为新路径。 |
| `import_texture` | 导入纹理文件作为项目资源（TEXTURE / ENVIRONMENT / ALPHA）。 |
| `get_project_info` | 列出纹理集及其根层节点。 |
| `create_fill_layer` | 插入填充层，并通过JSON `{channel: search_term}`映射连接PBR通道。根据名称搜索解析资源；设置投影模式。 |
| `configure_and_bake` | 配置高多边形网格和烘焙参数，并通过JS API运行烘焙 **，因此烘焙对话框不会弹出**。轮询`alg.project.isBusy()`以检测完成。 |
| `export_textures` | 使用命名预设导出项目纹理（`PBR Metallic Roughness`，`Unreal Engine 4 Packed`，`Unity HD Render Pipeline Lit`，...）。 |
| `execute_script` | 出口 - 在Painter内部运行任意Python或JavaScript。Python具有完整的`substance_painter.*`访问权限；JS具有`alg.*`访问权限。 |
## 亮点
### 无对话框烘焙（无对话框）
`configure_and_bake`使用JavaScript烘焙API（`alg.baking.textureSetBakingParameters` + `alg.baking.bake`）完全绕过模态烘焙对话框。然后，它每3秒轮询`alg.project.isBusy()`，最多超时10分钟，以便工具在烘焙实际完成时返回。
```python
configure_and_bake(
hp_mesh_path=r"D:/meshes/hp_helmet.fbx",
output_size=2048,
max_frontal_distance=0.5,
bake_normal=True,
bake_ao=True,
bake_curvature=True,
)
```
### 通道映射填充层
`create_fill_layer`接受一个JSON字符串，将PBR通道映射到资源搜索项。工具按名称搜索资源，然后将每个匹配项连接到新填充层上的正确通道。
```python
create_fill_layer(
layer_name="Brushed Steel",
textures='{"BaseColor": "steel_albedo", "Roughness": "steel_rough", "Metallic": "steel_metal", "Normal": "steel_norm"}',
projection_mode="Triplanar",
)
```
有效通道：`BaseColor`，`Roughness`，`Metallic`，`Normal`，`Height`，`AmbientOcclusion`，`Emissive`。
投影模式：`UV`，`Planar`，`Triplanar`。
### 统一的Python / JS执行
`execute_script`接受两种语言 — 在Python API中未公开但可以通过`alg.*` JS访问时很有用（反之亦然）。
```python
execute_script(
script="alg.project.lastImportedMeshUrl()",
language="javascript",
)
```
## API说明
- 远程API对脚本有效载荷进行base64编码。`lib_remote.py`处理此操作 — 从MCP表面看不到它。
- 来自Painter内部的Python `print()`返回`null`给调用者。要返回数据，请引发一个包含JSON的异常：`raise Exception(json.dumps(result))`。工具解包它。
- 在Windows上，在网格/纹理路径中使用正斜杠或原始字符串。
- `set_source(ChannelType, ResourceID)` — 通道优先。容易翻转。
- `InsertPosition.from_textureset_stack(stack)`用于堆栈顶部。没有`InsertPosition.on_top()`。
## 文件
```
sp-mcp.py FastMCP服务器，10个工具
lib_remote.py 远程Painter HTTP客户端（Python + JS执行）
test_connection.py 独立连接测试
launch_sp_remote.bat 一键启动，启用--enable-remote-scripting
```
## 故障排除
| 症状 | 修复方法 |
|---|---|
| `无法连接到Substance Painter` | 使用`--enable-remote-scripting`启动SP。等待其完全加载。 |
| `来自Python脚本的null`响应 | 切换到异常返回技巧（参见API说明）。 |
| `层操作失败` | 确认项目已打开。调用`texture_set.get_stack()`，将堆栈（不是纹理集）传递给`get_root_layer_nodes()`。 |
| 烘焙触发对话框 | 您正在调用Painter的Python烘焙API。使用`configure_and_bake`（此工具使用JS API）。 |
## 许可证
MIT — 请参见`LICENSE`。
