dcc-mcp-substance3d-designer

Part of the DCC-MCP host matrix

dcc-mcp-substance3d-designer — Substance 3D Designer adapter for DCC-MCP.

It is one of 38 host adapters in the DCC-MCP catalog. Every adapter speaks the same MCP protocol and builds on the same core runtime contract; each one exposes the tools its own host needs on top of that.

• All host adapters and install metadata

• Host matrix on the core README

• Showcase

This block is generated from the catalog entry in dcc-mcp-catalog.yml. Re-run the generator after changing the catalog.

Related MCP server: blender-chatgpt-mcp

Showcase: reference image to Designer materials and Blender lookdev

A Codex-generated reference guided a 2.2 m wooden crate modeled in Blender with painted wood and rusted steel authored in Substance 3D Designer 16. Wood scratches, metal scratches and rust are independent procedural layers in the SD graphs. Their exported PBR maps drive the Blender materials. Layered broken battens combine attached wood fibers with native SD height displacement; fine wood grain uses a separate UV layer with consistent physical density.

Model UVs — coordinates and a rendered checker:

Wood detail uses one tile per 0.45 m. UVs intentionally tile and overlap; the UV review explains the two layers and the existing steel UVs.

Complete material graphs — unretouched Designer screenshots:

Blender scene with packed textures · Editable SBS, SBSAR, maps and workflow · UV checker · Broken wood detail · Blender showcase · Website gallery · Earlier color-correction study

The crate is a reference-guided modeling and lookdev study. Its proportions, board UVs and hardware were authored in Blender; it is not a scan of the generated image. The material screenshots use the project's DCC-CUA route.

Typed RGBA gradient edits

designer-session exposes get_gradient_keys and set_gradient_keys for native sbs::compositing::gradient nodes. Inspect the current node and graph IDs first; the setter requires the exact graph UID and 2..64 strictly increasing keys. Positions, RGBA channels and midpoints must be finite values in 0..1. It uses public SDK array/struct values, verifies native readback, and restores the previous gradient when verification fails. See the skill's call example for a three-stop color ramp. Other node types and connected/function-driven inputs are rejected; native readback may include float32 rounding.

Agent workflow

AI agents should use the shared gateway through dcc-mcp-cli; IDE users may continue to use the MCP endpoint. Prefer typed skills and tools over raw scripts.

Install or update the CLI

dcc-mcp-cli is the preferred control path for every shell-capable agent. If it is missing, ask the user before installing the latest official release:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.ps1 | iex"

Keep an official build current through the release manifest:

dcc-mcp-cli update check
dcc-mcp-cli update apply

update apply downloads and stages the latest CLI for the next launch. It does not update a running dcc-mcp-server; update that server in its own environment.

dcc-mcp-cli dcc-types
dcc-mcp-cli list
dcc-mcp-cli search --query "<task>" --dcc-type substance3d_designer
dcc-mcp-cli describe <tool-slug>
dcc-mcp-cli call <tool-slug> --json '{"key":"value"}'

dcc-types reports release-catalog support; list reports live sessions. If a tool belongs to an inactive progressive skill, call dcc-mcp-cli load-skill <skill-name> --dcc-type substance3d_designer before retrying. For post-task improvement, attach a stable session id with --meta-json, query dcc-mcp-cli stats --range 24h --session-id <task-id>, then pass the bounded evidence to the review_skill_improvement prompt from dcc-mcp-skills-creator.

Substance 3D Designer adapter for the DCC Model Context Protocol (MCP).

The package runs an embedded Streamable HTTP MCP server inside Designer, so tools execute through Designer's Qt main thread instead of a separate process.

Install and load

Follow the canonical Install SOP for automatic host discovery, a zero-write plan, staged installation, receipt-owned uninstall, and verify-to-usable diagnostics:

python3.11 -m pip install dcc-mcp-substance3d-designer
dcc-mcp-substance3d-designer install --dcc-path "/path/to/Designer" --python python3.11 --json --dry-run
dcc-mcp-substance3d-designer install --dcc-path "/path/to/Designer" --python python3.11 --json --yes

The receipted launcher preserves existing SBS_DESIGNER_PYTHON_PATH and PYTHONPATH values while adding the dedicated plugin. A source checkout may still be loaded interactively through Tools > Plugin Manager as documented in the SOP. Each adapter instance uses an OS-assigned port and registers it for CLI discovery. Connect through the stable gateway at http://127.0.0.1:9765/mcp; set DCC_MCP_SUBSTANCE3D_DESIGNER_PORT only when a fixed direct endpoint is required. Standard DCC_MCP_GATEWAY_PORT and DCC_MCP_REGISTRY_DIR settings are also honoured.

For unattended launches, pass Designer a persistent configuration with --config-file <path-to-default_configuration.sbscfg>. This prevents a stale session-specific configuration reference from opening a blocking startup dialog.

Bundled skills

Offline SBS/SBSAR and mesh-position artifacts

With official sbscooker and sbsrender already installed, start the independent artifact service without opening Designer:

dcc-mcp-designer-offline --designer-bin "/path/to/installed/Designer/bin"
dcc-mcp-cli search --instance-id <returned-uuid> --query "offline cook render"
dcc-mcp-cli describe <returned-tool-slug> --instance-id <returned-uuid>
dcc-mcp-cli call <returned-tool-slug> --instance-id <returned-uuid> --json-file render.json --wait

The runtime is registered as standalone, with no GUI PID binding. Its bundled skill root contains only designer-offline; graph editing remains on the embedded Designer service. Existing GUI sessions can also load this skill when their operator configures DCC_MCP_SUBSTANCE3D_DESIGNER_BIN.

cook_package takes an SBS path, its expected SHA256 and a fresh output directory. It records actual source/archive/tool hashes. The cooker reads an owned snapshot beside the original SBS, so its directory must be writable. Relative dependencies retain that directory; their hashes are not separately collected.

inspect_renderer reads installed official render help and engine library identities. render_archive accepts only documented engine identifiers: sse2 (default), neon, d3d11, vk, ogl3 and mtl. The selected installed library is resolved and hash-pinned; missing or ambiguous engines fail without CPU fallback. Native warnings and the selected library hash remain in the manifest. GPU-only graphs, including native 3D Perlin noise, require an actual GPU render; inspecting a library does not establish hardware acceptance. See Adobe's renderer options.

bake_position_map uses installed substance3d_baker for a hash-pinned, self-contained triangulated OBJ with positive UV0 indices and one UV tile. It bakes bbox-normalized XYZ into Raw EXR twice, records native padding, warnings and argv, and verifies every RGB float sample through installed FFmpeg. Supply --ffmpeg "/path/to/installed/ffmpeg" on the standalone service or set DCC_MCP_SUBSTANCE3D_DESIGNER_FFMPEG. No decoder is downloaded or installed. Actual mesh/UV correspondence and complete coverage remain caller audits; native warnings are retained without being treated as proof of coverage.

inspect_mesh_baker reads bounded help from the installed official Color or Position baker. bake_color_map bakes caller-authored FBX vertex or material colours twice into UV0 PNG, with exact input/tool hashes, fixed same-mesh projection settings, complete PNG validation and retained warnings. Region assignment, packed UV coverage and geometry correspondence remain caller audits; the tool does not recognize anatomy or invent region colours from UV islands.

render_archive takes an SBSAR path and hash, a graph identifier, the complete output set, a fresh directory and expected resolution. For example:

{
  "archive_path": "/path/to/material.sbsar",
  "expected_archive_sha256": "replace-with-the-actual-64-character-lowercase-sha256",
  "graph_identifier": "Skin",
  "output_dir": "/path/to/fresh-material-run",
  "outputs": [
    {"name": "BaseColor", "bit_depth": 8, "color_space": "sRGB"},
    {"name": "Height", "bit_depth": 16, "color_space": "Raw"}
  ],
  "resolution": 2048
}

An optional seed override requires an exposed $randomseed input in the compiled archive. Fixed graph defaults remain unchanged; a requested size must match actual native PNG dimensions even when $outputsize is not exposed. Optional image input identifiers must also appear in the compiled interface.

Each channel gets an explicit native bit depth and color space. The renderer validates complete PNG chunks, checksums, dimensions, precision and compressed scanlines, then compares two native renders byte for byte before publishing manifest.json. Up to eight optional PNG inputs are independently hash pinned. Constant channels are valid. Tangent normal conventions remain caller-declared; displacement units and downstream shader acceptance belong to the consumer. Offline artifact success does not prove a live Designer SDK session.

Host APIs are imported only while a tool runs, so metadata discovery remains safe outside Designer.

designer-effects and designer-lighting are experimental. Their catalog declares 13 recipes (7 effects, 6 lighting) over 31 candidate node type URLs (17 effects, 14 lighting). Every candidate is inferred from Designer's naming conventions and resolved at runtime against the live node-definition inventory, because node type URLs differ between Designer builds; none of them is pinned to a build verified on a real Designer session. Run the corresponding list_*_recipes tool first and treat its available flag as the source of truth: a recipe that resolves to nothing fails closed with RECIPE_UNAVAILABLE and reports the candidates it tried.

Designer has no particle system, dynamics solver, or timeline. The designer-particles, designer-dynamics, and designer-animation skills all drive one shared engine that re-evaluates a deterministic graph after a typed input changes, and each states that boundary in its SKILL.md.

Development

python -m pip install -e ".[dev]"
python -m pytest
ruff check src tests tools
python -m build

Releases use release-please. The release.yml workflow publishes through the pypi environment using PyPI Trusted Publishing.

Reference-material reconstruction

designer-session.create_imported_pbr_material accepts either packed RMA/ARM maps or separate roughness_path and metallic_path, alongside the required base-color and normal maps. Separate AO is optional. height_path works with either mode; packed and separate scalar maps cannot be mixed. Set embed_resources: true to embed the source bitmaps in the editable .sbs instead of linking them.

Example tool arguments (replace the paths with existing source maps):

{
  "package_path": "C:/materials/sample/material.sbs",
  "output_dir": "C:/materials/sample/maps",
  "base_color_path": "C:/sources/basecolor.png",
  "normal_path": "C:/sources/normal.png",
  "roughness_path": "C:/sources/roughness.png",
  "metallic_path": "C:/sources/metallic.png",
  "ambient_occlusion_path": "C:/sources/ao.png",
  "height_path": "C:/sources/height.png",
  "embed_resources": true,
  "open_in_editor": false
}

This creates an editable bitmap/output graph, not a recovered procedural material. Use the existing node creation, connection and parameter tools to construct and iterate procedural structure when needed. Source images must already be PBR maps; a lit reference photograph is not directly a base-color map. A single image does not uniquely determine roughness, metallic response, illumination or physical height. Record these as estimates until checked against additional evidence.

For a Designer-to-Painter handoff, pass the returned texture_files to Painter's create_textured_pbr_layer, mapping AmbientOcclusion to ambient_occlusion_path and optional Height to height_path. Keep the normal convention and color-management configuration consistent across both hosts. The import helper writes PNG previews without a configurable bit-depth contract; retain original high-precision height sources when precision matters.

Before accepting a result, reopen the saved .sbs and .spp, inspect graph connections and layer channels, verify the exported maps, and compare actual host renders under matched lighting, camera and scale. File existence and mocked SDK tests do not verify the visual result. Use a fresh output directory per iteration.

See the reference-material capability matrix for node inspection, connection guards, resource instancing, persistence/export contracts and remaining live-host validation. Parameter exposure uses public graph inputs and property function graphs; unsupported SDK variable readers return EXPOSE_API_UNAVAILABLE. Native PNG exports report actual channel count and bit depth, and graph input edits are verified by readback.