dcc-mcp-houdini

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

SideFX Houdini adapter for the DCC Model Context Protocol (MCP) ecosystem. It embeds a Streamable HTTP MCP server inside Houdini/hython and exposes skills-first Houdini automation tools to agents.

Houdini 22 captured GSplat engineering validation

This validation starts from the University of California, Santa Barbara specimen UCSB-IZC00037044, published under CC BY 4.0 in Honey Bee Heat Budget Images and Models. It is our own reconstruction and Houdini scene, not the SideFX sample. The source is a pinned specimen photographed from multiple views; it is not a live bee performance capture.

The COLMAP/Nerfstudio reconstruction contains 70,269 retained Gaussians after deterministic pin-region removal. Its held-out preview metrics pass the recorded engineering thresholds: PSNR 21.91, SSIM 0.849, and LPIPS 0.145. The complete machine-readable provenance, hashes, coordinate contract, thresholds, and limitations are in honeybee-gsplat-validation.json.

The Houdini 22 scene exercises GSplat-aware KineFX deformation, articulated wing/body/leg controls, a deformation-synchronized short-fur Groom, and a fixed camera flipbook under a neutral outdoor HDR environment. The five-frame contact sheet verifies that one splat instance remains in frame through the 96-frame takeoff/flight/landing cycle; the legacy camera object was hidden so its viewport frustum cannot be mistaken for model ghosting.

The UI capture is from the real Houdini process. DCC-MCP set each audited frame and DCC-CUA captured the same exact Houdini PID/window through Windows Graphics Capture. Only the title bar was cropped to remove a local path; the Scene View, parameter editor, timeline, and node graph were not recreated. This remains engineering evidence rather than final beauty approval: pin removal cannot synthesize occluded anatomy, residual capture-support Gaussians remain visible, and the pinned specimen cannot supply biological flight or foot-contact motion. A final living-bee showcase still requires a cleaner licensed capture and dedicated contact/occlusion review.

Source attribution and the separation between captured evidence and authored animation are documented in docs/showcase/honeybee-reference-license.md.

Photogrammetry high-poly quality gate

Increasing polygon count alone does not correct the captured specimen. A second licensed UCSB scan, UCSB-IZC00038675, contains 1,606,745 source faces. Keeping its largest connected component retains 1,281,475 faces; a UV-preserving 249,999-face proxy carries the source texture into a real Houdini 22 viewport for bounded interactive review.

This audit intentionally fails final-asset acceptance. The pin intersects the body, the fixture base remains connected, and occluded legs, claws, antennae, and wing regions are incomplete. Those errors cannot be repaired by subdivision, decimation, Groom density, relighting, or denoising. The machine-readable counts, hashes, and acceptance result are in honeybee-highpoly-validation.json.

The next visual-quality stage must therefore use a clean licensed living-bee multiview capture (or another source with complete anatomy), retrain the GSplat, and pass source-view plus novel-view silhouette checks before KineFX and Groom are treated as final presentation layers.

Archived procedural rig validation (pre-GSplat)

This archived validation uses an original DCC-MCP procedural insect prototype, not the SideFX sample. It is not a captured or trained Gaussian Splat, and its ant-like silhouette is not the visual-quality target for the honeybee showcase. The opening reference photograph makes that anatomical gap explicit.

The Houdini 22 scene remains useful as technical evidence for MaterialX/Solaris LookDev, KineFX-driven motion, wing beats, head and antenna controls, articulated legs, and phase-delayed body motion. Karma uses one CC0 Poly Haven Residential Garden HDRI, ACES display conversion, neutral calibration spheres, and no duplicate sun or stylized green rim light.

Watch the 1280×720, 24 fps MP4

The 96 rendered frames contain one animated insect: body motion blur is disabled, so takeoff silhouettes do not become a second model. The procedural leg controls were checked against a -0.003 floor tolerance. This numerical check does not replace collision/contact solving and the result is not accepted as final honeybee anatomy or grounded motion.

The older calibration turntable remains useful for inspecting the prototype's materials and topology, but should not be read as scan evidence or final art:

Reference provenance, license terms, technical evidence, and known limitations are recorded in docs/showcase/honeybee-reference-license.md. The archived procedural model remains useful for topology and control-rig comparison, but it is superseded as GSplat provenance evidence by the captured specimen validation above.

Features

• Embedded MCP Streamable HTTP server inside Houdini (OS-assigned instance port)
• Auto-gateway with first-wins election (gateway port 9765)
• Progressive skill loading (discover → load → unload)
• Houdini Python (hython) and interactive UI-thread dispatch
• Python 3.7+ package metadata for older Houdini runtimes
• Bundled skills for scripting, scene inspection, node authoring, HDA execution, and automation
• Wheel, sdist, and Houdini quickinstall ZIP release assets
• Prometheus metrics endpoint (/metrics), job persistence, and workflow engine support
• Optional licensed Houdini Docker E2E workflow

Agent install (recommended)

Let your AI agent do the setup. In an MCP-capable agent (Cursor, Claude, etc.), just say:

帮我参考 dcc-mcp/dcc-mcp-houdini/install.md 去安装

The agent reads install.md, runs the dcc-mcp-houdini-setup skill to install dependencies into Houdini's hython, generates an MCP host config, guides the Houdini package startup hooks step, and runs a smoke prompt to confirm the connection.

Installation

Release Wheel

pip install dcc-mcp-houdini

For an unreleased GitHub asset, install a release wheel directly:

pip install https://github.com/dcc-mcp/dcc-mcp-houdini/releases/download/v0.9.1/dcc_mcp_houdini-0.9.1-py3-none-any.whl

Houdini Quickinstall ZIP

Download dcc_mcp_houdini_quickinstall_<platform>_v<version>.zip from GitHub Releases, extract it to a stable folder, then run:

powershell -ExecutionPolicy Bypass -File install.ps1 -HoudiniVersion 20.5

For an isolated or custom package location, pass -PackagesDir explicitly:

powershell -ExecutionPolicy Bypass -File install.ps1 -HoudiniVersion 20.5 -PackagesDir C:\temp\houdini-packages

DCC_MCP_HOUDINI_PACKAGES_DIR provides the same override on every platform; on Windows, the explicit -PackagesDir argument takes precedence. Changing the HOME environment variable inside PowerShell does not redirect its automatic $HOME variable, so use this override for deterministic isolated installs.

On Linux/macOS:

chmod +x install.sh
./install.sh 20.5

The package writes a Houdini package JSON into the user preferences folder. scripts/123.py handles an empty startup and scripts/456.py handles a loaded scene; both reuse one bootstrap that extracts bundled wheels into vendor/ and starts the MCP server unless DCC_MCP_HOUDINI_AUTOSTART=0.

For Core 0.20.14, quickinstall supports Python 3.7+ on Windows/Linux and Python 3.8+ on macOS. The macOS archive fails closed before extraction on Python 3.7 because that Core release has no native cp37 macOS wheel. Default macOS registration is ~/Library/Preferences/houdini/<version>/packages; the environment override remains authoritative.

Isolated background ROP workers receive DCC_MCP_BACKGROUND_RENDER=1 in their child environment. Package and custom 123.py/456.py startup hooks must skip MCP adapter autostart when that marker is present; the parent Houdini environment is not modified. Background render cancellation uses only live child-process handles owned by the current adapter process; status-file PIDs are never used as process ownership evidence.

Usage

import dcc_mcp_houdini

server = dcc_mcp_houdini.start_server()
print(server.mcp_url)  # Exact direct endpoint selected by the OS

start_server() is the interactive Houdini API and uses Houdini's budgeted event-loop pump. Headless Hython must keep its owning thread available for HOM work; launch the foreground pump instead:

hython -m dcc_mcp_houdini

or call dcc_mcp_houdini.serve_headless(...) from a dedicated Hython entrypoint. A plain headless start_server() fails before tools are registered instead of silently executing HOM on an HTTP worker.

Hython cannot report a reliable HIP dirty state: context snapshots omit scene_saved, while validate_scene returns dirty: null; GUI sessions report the real boolean state. Destructive open_scene and new_scene calls fail closed when that state is unknown unless the caller explicitly passes force=true.

Default minimal mode (DCC_MCP_MINIMAL=1) loads only:

• houdini-scripting
• houdini-scene

Use progressive discovery for heavier tools:

search_skills(query="hda")
load_skill("houdini-hda")
call houdini_hda__execute_hda

Local MCP debug (Cursor / Claude)

See docs/guide/local-mcp-debug.md and copy examples/mcp/cursor-houdini-streamable-http.json into your MCP host config.

Development

# Install dependencies
just dev

# Run tests
just test

# Lint
just lint-all

# Windows: build dcc-mcp-core with Houdini's Python and symlink
just houdini-version=20.5 houdini-dev-build-link-core-win

# Windows: start Houdini with debugpy
just houdini-version=20.5 houdini-dev-debug-win

# Build wheel + platform quickinstall package
just build-houdini-package platform=win64

Release Publishing

The Release workflow publishes to PyPI when release-please creates a new release. To backfill an existing GitHub release tag, run the Release workflow manually with tag_name=vX.Y.Z and publish_to_pypi=true. Publishing uses PyPI trusted publishing when configured, or PYPI_API_TOKEN when that secret is available.

Bundled Skills (34 packages, 223 tools)

Full authoritative index with ready-made task chains: src/dcc_mcp_houdini/skills/SKILLS_INDEX.md

bootstrap (default loaded)

scene (partial default — houdini-scene only)

authoring (load on demand)

interchange (load on demand)

pipeline (load on demand)

CI and Houdini Docker

Normal CI runs without Houdini installed: unit tests, skill validation, Python 3.7 syntax checks, wheel/sdist build, and quickinstall ZIP assembly.

Live Houdini E2E is in .github/workflows/e2e.yml. It defaults to sabjorn/hbuild-worker:21.0.559-base and runs only when SideFX licensing secrets are configured. See docs/ci/houdini-docker.md.

Project Structure

dcc-mcp-houdini/
├── src/dcc_mcp_houdini/        # Python package and bundled skills
├── packaging/                  # Quickinstall ZIP assembly
├── tests/                      # Unit and packaging tests
├── tools/                      # Dev, lint, and syntax scripts
├── examples/                   # Usage examples
├── docs/                       # Guides and CI notes
├── justfile                    # Task runner
└── pyproject.toml              # Build config

Requirements

• Houdini with Python 3.7+ (hython or interactive Houdini)
• dcc-mcp-core >= 0.20.14
• Quickinstall bundles the latest non-prerelease dcc-mcp-core >= 0.20.14,<1.0.0 by default, or the validated core_version passed to a release backfill; no old-core pin is active.
• Bundled Core wheel matrix: Python 3.7+ on Windows/Linux and Python 3.8+ on macOS; unsupported runtime/tag pairs fail before extraction.
• See pyproject.toml for full dependencies

License

MIT