dcc-mcp-openusd

Scene gallery · 场景展示

Real renders of USD-authored scenes, from a stylized assembly study to an architectural greenhouse. OpenUSD stores and composes the scene; Blender imports it and produces the Cycles render.

Garden Light · architectural study / 写实温室	Seedlight · stylized assembly / 风格化装配
An approved still with typed UV/texture authoring and CC0 surface/environment assets.	The original modular study: native instances, relative references, a payload and foliage variants.

Authoring combines typed DCC-MCP calls with explicit native pxr steps; Blender supplies rendering and final look development. These stills do not claim that every Blender shader node round-trips through USD. What was tested, runtime boundaries and image credits.

两图均为真实 USD 场景的 Blender/Cycles 渲染：左为已认可的写实温室单帧，右为 早期 Seedlight 三联温室技术样例。OpenUSD 负责存储、组合与互换，Blender 负责 渲染及最终材质调整；原生 pxr 补足步骤不冒称 typed 接口能力。毛发、粒子、体积和 动力学已有小型数据验证，尚未作为动态渲染作品展示。图片来源与独立于代码许可的 媒体权利说明见详情。

Part of the DCC-MCP host matrix

dcc-mcp-openusd — OpenUSD adapter and skills for DCC-MCP.

It is one of 47 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.

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 openusd
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 openusd 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.

OpenUSD adapter and skills for the DCC Model Context Protocol ecosystem.

dcc-mcp-openusd runs a headless OpenUSD-oriented MCP server that can create portable USD project folders, author simple stages, add references, validate stages, and package USDZ-like archives. It is designed to plug into the dcc-mcp-core gateway and skills-first workflow.

Install

Follow the wheel-first installation and lifecycle guide. The adapter requires dcc-mcp-core>=0.19.45. After installing a trusted wheel, run:

dcc-mcp-openusd doctor --json
dcc-mcp-openusd verify --json

The base install operates in text-fallback mode: it reads and writes USDA text without requiring the Pixar USD runtime. This mode is suitable for lightweight agents, CI gates, and environments where native USD libraries are unavailable.

For full OpenUSD runtime behavior, install the optional Pixar USD bindings:

python -m pip install --only-binary=:all: "dcc-mcp-openusd[openusd]"

Timeline interop (openusd-timeline) additionally needs OpenTimelineIO:

python -m pip install "dcc-mcp-openusd[timeline]"

The [openusd] extra pulls in usd-core>=24.11 (the Pixar open-source USD Python bindings, importable as pxr). With pxr installed, all stage authoring, material binding, camera/light definition, time-sampled animation, and composition-arc operations go through the native USD runtime.

Runtime mode detection

from dcc_mcp_openusd.runtime import detect_runtime

runtime = detect_runtime()
print(runtime.has_pxr)  # True when pxr is installed
print(runtime.version)  # API tuple label, for example "0.26.5"

Every public function returns a "runtime" field in its result dict — "pxr" when the native runtime was used, "text-fallback" otherwise.

Feature boundary

Advanced features that cannot be expressed through text-fallback raise OpenUsdError("... requires the Pixar USD (pxr) package. Install it with: pip install usd-core") when pxr is absent.

validate_stage shares its root-layer metadata, composition and material rules across both runtimes. With pxr, it additionally validates connected OpenVDB field dependencies and PointInstancer parallel arrays/prototype targets on the composed stage, without loading payloads. Optional unrelated asset attributes are not treated as required volume dependencies. The native_checks result field reports performed, unavailable, or failed.

Native package_usdz requires all package dependencies to resolve and never silently downgrades a failed native package to a root-only ZIP. Its result includes dependency_check, complete, and unresolved_assets; text-fallback reports complete: null and dependency_check: "unavailable". See the validation and packaging boundaries (English / 中文). The registry is dcc_mcp_openusd.runtime.VALIDATION_RULES.

The result is a ValidationResult ({success, message, stage_file, issues, summary, next_steps}): summary counts issues per severity, and next_steps aggregates every issue's steps so an agent can act without walking issues. Each issue is a ValidationIssue ({code, severity, message, location, strict_promoted, suggested_fix, next_steps}) whose location is a discriminated object — {"kind": "prim"|"layer"|"line", "path": …, "line": …, "label": …} — so callers tell a prim path from a layer or a line number by reading kind instead of re-parsing brackets. strict_promoted marks issues that only became errors because the run was strict. See dcc_mcp_openusd.validation for the schema and openusd-validate/SKILL.md for the agent-facing contract.

Issues point at the skill that can fix them: UNRESOLVED_REFERENCE suggests openusd_stage__fix_reference_path, and UNBOUND_MATERIAL / DANGLING_MATERIAL_BINDING suggest openusd_material__suggest_material_bind. Both fix skills run on the shared facts, so they agree with the validator on every runtime, and both read back what they write instead of claiming a fix that did not happen. Reporting needs no pxr; applying a material binding does.

Portable textured materials / 可移植纹理材质

set_mesh_uvs authors static indexed or non-indexed mesh texture coordinates. connect_preview_surface_texture connects standard UV textures for color, roughness, metalness, opacity, clearcoat, occlusion, and tangent-space normals. Both require pxr and preserve relative texture asset paths. See the English / 中文 guide for typed arguments, layer behavior, packaging, and renderer boundaries.

两个新 typed 工具支持网格 UV 和标准 Preview Surface 纹理连接；相对资源路径、 索引 UV 与保存重开均有原生测试。详细用法及限制见上述双语说明。

Run

dcc-mcp-openusd

The instance uses an OS-assigned direct port. Connect through the stable local gateway, or discover the exact direct URL with dcc-mcp-cli list.

Daemon startup, explicit pidfiles, identity-verified platform-specific stop, upgrade, and uninstall are documented in install.md. Doctor and verify never start the service or daemon.

Bundled Skills

The package ships eight bundled skills:

Agents should follow the normal DCC-MCP flow:

1. search_skills(query="openusd stage")
2. load_skill("openusd-stage")
3. Call a typed tool such as openusd_stage__create_stage
4. Validate with openusd_validate__validate_stage
5. Follow each issue's suggested_fix to repair the stage

Scope

This repository is intentionally an adapter/domain-skill package, not a new core USD engine. dcc-mcp-core remains the shared transport, gateway, validation, telemetry, and skill-loading foundation. This package owns OpenUSD-specific project semantics, stage authoring tools, validation policy, and packaging workflows.

Development

# Minimal setup (text-fallback, fast CI gate)
pip install -e ".[dev]"
pytest tests/ --ignore=tests/e2e

# Full setup (pxr runtime, material/light/animation/composition/timeline tests)
pip install -e ".[dev,openusd]"
pytest tests/e2e/ -v
ruff check src tests tools
python -m build

The CI matrix enforces both modes:

• test-minimal — no pxr, runs unit tests + contract test (text-fallback baseline)
• test-openusd — with pxr, runs the e2e golden-path suite

Release

The repository uses release-please; PyPI publishing is wired through the pypi GitHub environment.