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 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 replacement showcase will be published only after a licensed multi-view capture has produced a validated GSplat, followed by GSplat-aware KineFX deformation, Houdini Groom fur, contact validation, and a full readable Houdini UI capture.

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.

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 (33 packages, 220 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.19.70
• Quickinstall bundles the latest non-prerelease dcc-mcp-core >= 0.19.70,<1.0.0 by default, or the validated core_version passed to a release backfill; no old-core pin is active.
• See pyproject.toml for full dependencies

License

MIT