Designer Stonewall MCP

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

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

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

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

环境要求

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

Related MCP server: Houdini MCP

安装与启动

在 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 可执行文件的绝对路径，例如：

"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 实例：

.\start_designer.ps1

脚本通过 --startup-script 加载桥接，只向新进程传入配置路径。若执行策略阻止脚本，可在已打开的 Designer 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 替换为本机绝对路径：

{
  "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 示例，具体配置格式取决于客户端。启动命令等价于：

python server.py --config config.json

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

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

工具

制作参数示例：

{"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 环境安装可选依赖并检查新生成的目录：

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。

验证

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；其中历史工程反馈不构成新的自动执行任务。