Metadata-Version: 2.5
Name: dcc-mcp-nuke
Version: 0.16.0
Summary: Nuke adapter for the DCC Model Context Protocol ecosystem
Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-nuke
Project-URL: Repository, https://github.com/dcc-mcp/dcc-mcp-nuke
Project-URL: Issues, https://github.com/dcc-mcp/dcc-mcp-nuke/issues
Author-email: Long Hao <hal.long@outlook.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Requires-Dist: dcc-mcp-core<1.0.0,>=0.20.14
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: jsonschema>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# dcc-mcp-nuke

<p align="center">
  <img src="docs/assets/dcc-mcp-nuke.svg" alt="DCC-MCP · NUKE" 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 nuke
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 nuke` 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`.


Nuke adapter for the DCC Model Context Protocol. It embeds a Streamable HTTP
MCP server in Nuke and uses Nuke's main-thread execution API for scene tools.

See [install.md](install.md) for the agent-first install, verify, upgrade, and
receipt-driven uninstall workflow on Windows, macOS, and Linux.

## Host flavors: Nuke, NukeX, and Nuke Studio

One package covers all three Foundry entry points. Nuke, NukeX, and Nuke Studio
ship from one installation, share one embedded Python interpreter and one
`~/.nuke` plug-in profile, and install once. Core registers all three as
executable stems of a single `dcc-type` (`nuke`), so there is no second
package, entry point, or release channel to install.

What differs between them is the feature surface available at runtime. The
adapter classifies the running entry point as one of three host flavors and
reports it as server capability metadata:

```bash
dcc-mcp-cli call nuke_diagnostics__host_flavor --dcc-type nuke --json '{}'
```

| Host flavor | Provides |
|---|---|
| `nuke` | Shared baseline: `compositing`, `node_graph`, `scripting` |
| `nukex` | The same shared baseline |
| `nukestudio` | Baseline plus `studio.timeline`, `studio.sequence`, `studio.project_bin`, `studio.conform`, `studio.track` |

Detection prefers `nuke.env`, then the executable name, and treats an
importable `hiero` module as a supporting signal rather than a decisive one.
Set `DCC_MCP_NUKE_HOST_FLAVOR` only to override detection for a host that
really runs that flavor; unrecognized values are ignored.

### Studio-only skills are gated, not silently unavailable

A bundled skill that needs the Studio surface declares it in its manifest:

```yaml
metadata:
  dcc-mcp:
    host-flavors: [nukestudio]
```

On a `nuke` or `nukex` session that skill stays discoverable, so an agent can
still see the capability exists, but it will not load.
`dcc-mcp-cli load-skill nuke-studio-timeline --dcc-type nuke` fails with an
explicit veto naming both the required flavor and the current one, and calling
the tool directly returns the same `capability_unavailable` error. A Studio
skill never fails silently.

`nuke-studio-timeline` is the first Studio skill. It inspects open projects,
sequences, track counts, and frame range through the Hiero surface, read-only,
and reports an explicit `studio_surface_unavailable` error when a Studio build
does not expose the expected API instead of skipping it.

Probe the host with `nuke_diagnostics__host_flavor` first when the entry point
is unknown.

## Automated Houdini AOV compositing

![Automated Nuke AOV rebuild from a Houdini solar-system render](docs/images/nuke-houdini-aov-compositing.gif)

This real Nuke session progressively isolates Albedo, Sun, Diffuse, Glossy, and
Emission passes, then merges them into the approved composite. The 35-layer,
114-channel EXR source was rendered from a solar-system scene built in Houdini with
[`dcc-mcp-houdini`](https://github.com/dcc-mcp/dcc-mcp-houdini); Nuke reads the
Houdini AOVs rather than bundled sample footage.

Nuke loads the lifecycle-managed plug-in path and asks the operating system for
an available instance port. Use `dcc-mcp-cli list` or the stable gateway at
`http://127.0.0.1:9765/mcp` to discover and connect to the running instance.
Set `DCC_MCP_NUKE_PORT` only when a fixed direct port is required.

The bundled `nuke-script` skill can open an existing absolute `.nk` path,
inspect bounded node topology and knob values, sample per-channel AOV
statistics, and explicitly save the current script. The `nuke-node-graph`
skill adds non-clearing node CRUD, exact input connections, and readback-
verified static knob edits while rejecting executable knobs. The
`nuke-text-layout` skill creates or updates one bounded
`Text2` label, maps requested pixel size through Nuke's effective
`global_font_scale`, and returns verified node position, text box, and
alignment readback with rollback on mismatch. It rejects arbitrary node
classes, Python, Tcl, scripts, expressions, callbacks, bracket/backslash/control
text, animated/keyed/expression-bearing required knobs, and UI input while
preserving ordinary Unicode labels. Dynamic-state probes must return their
documented boolean, curve-list, and non-negative key-count shapes; unsupported
or unobservable probe results fail closed before mutation. Scale, box, and
position readback must use finite non-boolean numeric values with exact bounded
shapes; malformed readback fails closed and rolls back. Releases
use a canonical tag and exact-main identity check, one digest-bound wheel/sdist
bundle, and a minimal-OIDC publisher in `release.yaml` and the GitHub `pypi`
environment. Immediately before publishing, the workflow force-refreshes
authoritative main and tag refs into an isolated namespace and repeats the
identity checks. CI obtains the Install SOP schema from the isolated minimum-
Core environment used for the installed-wheel smoke rather than its ambient
interpreter.

The `nuke-node-assets` skill packages reusable, versioned Gizmos with an
explicit public knob interface, instantiates saved assets, and validates live
instances. Its registered tools use `DCC_MCP_NUKE_PLUGIN_ROOT`, stable ids and
versions, bounded typed knobs, and reject executable callbacks.

The `nuke-layered-compositing` skill supports ordered global and
Cryptomatte-scoped gain, saturation, edge-feather, and bounded albedo-fill
adjustments without changing pixels outside the selected material.
