# Designer Stonewall MCP

通过 MCP 调用 Adobe Substance 3D Designer 原生 API，创建可编辑的石砖墙灰模、导出高度图与遮罩，并记录用户的灰度造型反馈。

外部适配器只使用 Python 标准库，以 stdio 接入 MCP 客户端；Designer 内部桥接通过带会话认证的本机 HTTP 通信。

```text
MCP 客户端 → server.py（stdio）→ 本机认证桥接 → Designer 原生 API
```

当前版本专注灰度排布：砖块大小、宽砖缝、留空、轻微旋转、凸轮廓与线性切角。提供 7 个工具，不提供任意 Python 执行或完整 PBR 细节生成。

![石砖墙灰度样例](examples/gray_review/Grayscale_Review.png)

## 环境要求

| 部分 | 要求 |
| --- | --- |
| 外部 MCP 适配器 | Python 3.10+，无需安装第三方包 |
| Designer 内部桥接 | Adobe Substance 3D Designer 及其内置 `sd`、`PySide6`；原包报告测试版本为 14.1.1 |
| 启动脚本 | Windows PowerShell |
| 可选图像 QA | 外部 Python 中的 Pillow、NumPy，见 `requirements-qa.txt` |

Adobe 软件与商业授权不随仓库提供。不要向 Designer 内置 Python 安装系统环境的 `sd`、PySide6、NumPy 或其他包。Linux CI 仅验证外部适配器与预设校验，不代表验证了 Designer 的 Linux 运行环境。

## 安装与启动

在 PowerShell 中克隆仓库并创建本机配置：

```powershell
git clone https://github.com/hillarybeasley8876-dot/Designer_Stonewall_MCP.git
cd Designer_Stonewall_MCP
Copy-Item config.example.json config.json
```

编辑 `config.json` 的 `designer_executable`，填写本机 Designer 可执行文件的绝对路径，例如：

```json
"designer_executable": "C:/Program Files/Adobe/Adobe Substance 3D Designer/Adobe Substance 3D Designer.exe"
```

默认工作目录是仓库下的 `workspace/`。配置支持 `${CONFIG_DIR}` 和 `${WORKSPACE_ROOT}` 占位符，一般无需更改其余路径。本机的 `config.json`、`mcp-config.local.json` 和运行目录均已加入 Git 忽略规则。

启动独立 Designer 实例：

```powershell
.\start_designer.ps1
```

脚本通过 `--startup-script` 加载桥接，只向新进程传入配置路径。若执行策略阻止脚本，可在已打开的 Designer Python 环境中手动加载（替换示例路径）：

```python
import os
import runpy
os.environ["DESIGNER_STONEWALL_CONFIG"] = r"C:\projects\Designer_Stonewall_MCP\config.json"
runpy.run_path(r"C:\projects\Designer_Stonewall_MCP\designer_bridge.py", run_name="__main__")
```

桥接必须在 Designer 的 Python 环境运行，外部 MCP 适配器使用系统 Python。

## 连接 MCP 客户端

参考 `mcp-config.example.json`，将 Python、`server.py`、`config.json` 替换为本机绝对路径：

```json
{
  "mcpServers": {
    "designer-stonewall": {
      "command": "C:/Python312/python.exe",
      "args": [
        "C:/projects/Designer_Stonewall_MCP/server.py",
        "--config",
        "C:/projects/Designer_Stonewall_MCP/config.json"
      ]
    }
  }
}
```

`mcpServers` 是通用 JSON 示例，具体配置格式取决于客户端。启动命令等价于：

```powershell
python server.py --config config.json
```

该进程等待客户端 JSON-RPC 输入，直接在终端启动时不会显示交互提示。适配器支持 MCP `2024-11-05` stdio 子集。仓库不会自动改写客户端的全局配置。

先启动 Designer 桥接，再让客户端调用 `designer_status` 和 `designer_capabilities` 检查连接。仅完成 stdio 初始化，不代表 Designer 已连接。

## 工具

| 工具 | 用途 |
| --- | --- |
| `designer_status` | 读取活动图名称与节点数量 |
| `designer_capabilities` | 查询支持的能力与尚未支持的视口设置 |
| `build_gray_blockout` | 按允许的预设在新目录创建灰模、保存 `.sbs` 并导出 Height／Mask |
| `get_review_state` | 读取当前灰模反馈状态 |
| `record_user_review` | 记录用户明确反馈原文及确认／修改意见 |
| `get_job_status` | 查询任务状态，供超时后检查 |
| `capture_designer` | 抓取 Designer Qt 窗口；OpenGL 区域可能不完整 |

制作参数示例：

```json
{"preset": "blockout_v6", "resolution": 1024}
```

每次生成到 `workspace/results/gray_时间_随机后缀/`，状态设为 `awaiting_user`。确认顺序为大小层级 → 砖缝与空位 → 旋转 → 轮廓 → 线性切角。技术测试通过不代表美术确认；记录批准也不会自动生成颜色、青苔、裂纹或凹陷等后续细节。

预设含 112 个槽位、105 块启用石砖和 7 处留空。`desired_corners` 已包含缩放与旋转，顺序为左上、右上、右下、左下，不应再次变换。代码校验凸性、唯一 ID、有限数值与 ±3° 旋转上限；碰撞及砖缝观感需结合导出 QA 和图像判断。

## 示例与图像 QA

`examples/gray_review/` 包含原包随附的 1024×1024 灰模图、可编辑 `.sbs`、已编译 `.sbsar` 和 QA 报告。打开 `.sbs` 后选择主图 `Stonewall_Blockout_Review`。

随附报告记载 105 个跨边界独立区域、无粘连，灰缝与留空占比约 33.07%。这是随包示例的历史结果，不是每次生成都会达到的保证。

在外部 Python 环境安装可选依赖并检查新生成的目录：

```powershell
python -m pip install -r requirements-qa.txt
python qa_gray.py "workspace/results/本次生成目录"
```

QA 输出 `Grayscale_Review.png`、`Tiling_Check_2x2.png` 和 `qa_report.json`。配方接受 2048 分辨率，但随附示例的验收分辨率为 1024。

## 验证

```powershell
python -m unittest discover -s tests -v
```

测试覆盖配置解析、本机地址限制、认证与令牌脱敏、重定向拒绝、超时不重试、工具过滤、JSON-RPC、预设校验，以及真实 stdio 子进程的初始化、ping 与缺失桥接错误。无需启动 Designer 或安装 QA 依赖。

仓库提供 `ci/tests.github-actions.yml` 模板，配置 Windows／Linux、Python 3.10／3.12 测试矩阵。将它复制为 `.github/workflows/tests.yml` 并使用具备工作流写入权限的 GitHub 凭据提交，即可启用 GitHub Actions。当前尚未启用云端 CI，以下验证结果来自本机运行。`VALIDATION.json` 区分本次仓库验证与原压缩包的历史实连记录。本次发布未执行 Designer 原生建图；Designer 内部 Qt 派发与任务状态流程不在本次自动测试覆盖范围内。

`MANIFEST.sha256` 对应仓库发布文件，不含本机配置与运行目录。

## 运行边界

- 桥接仅监听 `127.0.0.1`，每次启动生成随机端口和会话令牌；请求禁止代理、重定向和浏览器 Origin。
- `workspace/.runtime/designer_connection.json` 含会话令牌，必须保留在本机，不要上传或加入分发包。
- Designer API 在 Qt 主线程串行运行，忙时拒绝再次排队。写操作超时后先查询任务状态，不自动重试。
- 输出使用新目录；失败输出与进度文件可保留排查。关闭专用 Designer 进程将停止桥接。
- 当前不支持通过原生 API 设置 3D 视口的高度 5×／法线 10×；修改像素或 Normal 节点强度不等于设置视口倍率。
- 用户反馈记录是工作流约定，不提供真人身份认证。代码在本机执行，不是操作系统沙箱。

## 来源

本仓库整理自用户提供的 `Designer_Stonewall_MCP_v1.0.zip`。发布时保留核心源码、预设与灰模示例，移除对原机器配置的依赖，补充自动测试和通用安装说明。原始压缩包 SHA-256 与历史验证声明保存在 `VALIDATION.json`；其中历史工程反馈不构成新的自动执行任务。