Metadata-Version: 2.5
Name: dcc-mcp-openusd
Version: 0.10.0
Summary: OpenUSD MCP server with daemon runtime — uvx-launchable, defaults to Pixar USD bindings
Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-openusd
Project-URL: Repository, https://github.com/dcc-mcp/dcc-mcp-openusd
Project-URL: Issues, https://github.com/dcc-mcp/dcc-mcp-openusd/issues
Project-URL: Changelog, https://github.com/dcc-mcp/dcc-mcp-openusd/releases
Author-email: Long Hao <hal.long@outlook.com>
License: MIT
License-File: LICENSE
Keywords: ai,dcc,llm,mcp,model-context-protocol,openusd,usd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
Requires-Python: >=3.9
Requires-Dist: dcc-mcp-core<1.0.0,>=0.19.45
Provides-Extra: daemon
Requires-Dist: dcc-mcp-server<1.0.0,>=0.18.0; extra == 'daemon'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: dcc-mcp-server<1.0.0,>=0.18.0; extra == 'dev'
Requires-Dist: opentimelineio<1.0,>=0.15; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: openusd
Requires-Dist: usd-core<27,>=24.11; extra == 'openusd'
Provides-Extra: timeline
Requires-Dist: opentimelineio<1.0,>=0.15; extra == 'timeline'
Description-Content-Type: text/markdown

# dcc-mcp-openusd

<p align="center">
  <img src="docs/assets/dcc-mcp-openusd.svg" alt="DCC-MCP · OPENUSD" width="600">
</p>

## 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:

```bash
# 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:

```bash
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.

```bash
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](install.md). The
adapter requires `dcc-mcp-core>=0.19.45`. After installing a trusted wheel, run:

```bash
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:

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

Timeline interop (`openusd-timeline`) additionally needs OpenTimelineIO:

```bash
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

```python
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

| Feature | Text-fallback | pxr runtime |
| --- | --- | --- |
| `create_stage`, `create_project` | USDA text | Native `Usd.Stage` |
| `list_stage`, `define_xform`, `define_prim` | USDA parse + insert | Native API |
| `add_reference`, `set_xform_ops` | USDA text | Native API |
| `validate_stage` | Shared rule set (USDA parse) | Shared rule set (`Sdf` specs) |
| `fix_reference_path` (report + rewrite) | USDA text | Shared readback |
| `suggest_material_bind` (suggest) | USDA parse | Shared readback |
| `snapshot_stage` | File copy | File copy |
| `package_usdz` | `zipfile` | `UsdUtils.CreateNewUsdzPackage` |
| Material binding (`UsdShade`) | — | Requires pxr |
| Camera / Light (`UsdGeomCamera`, `UsdLux`) | — | Requires pxr |
| Time-sampled animation | — | Requires pxr |
| Sublayer / payload composition | — | Requires pxr |
| OTIO timeline import / export / parity | — | Requires pxr + `opentimelineio` |

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` is the exception: it runs the **same rule set** on both runtimes.
`pxr` is used only to parse the file (`Sdf.Layer`); both runtimes report facts for
the **root layer only** — prims composed in from references and sublayers are out
of scope — so the two collectors stay equivalent and reference asset paths are
always resolved against the root layer's directory. 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`](src/dcc_mcp_openusd/skills/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.

## Run

```bash
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](install.md). Doctor and
verify never start the service or daemon.

## Bundled Skills

The package ships eight bundled skills:

| Skill | Purpose |
| --- | --- |
| `openusd-project` | Create self-contained project folders and snapshots. |
| `openusd-stage` | Create stages, list prims, define xforms, set xform ops, modify stage metadata, add references, and repair broken reference paths. |
| `openusd-validate` | Validate stage invariants and package a USDZ-style archive. |
| `openusd-material` | Create UsdShadeMaterial prims, attach UsdPreviewSurface shaders, bind materials to geometry, and suggest missing bindings. |
| `openusd-light-camera` | Create cameras (UsdGeomCamera) and lights (DistantLight, SphereLight) with transforms. |
| `openusd-animation` | Set stage time codes and author translate/rotate/scale time samples. |
| `openusd-composition` | Add sublayers, payloads, variant sets, and variant selections for multi-layer scenes. |
| `openusd-timeline` | Import an OpenTimelineIO timeline into the stage time axis, export a stage back to OTIO, and assert round-trip parity. |

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

```bash
# 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.
