dcc-mcp-katana

Typed DCC-MCP control for Foundry Katana's node graph. Host work is marshalled through Katana's native event queue and runs on the event-processing thread. The adapter deliberately does not expose arbitrary Python, parameter expressions, render scripts, or shell commands.

Illustrative workflow generated with OpenAI ImageGen from the retained source in docs/images/sources; it is not a Katana screenshot or host-validation artifact.

Install in Katana's Python environment

python -m pip install dcc-mcp-katana
dcc-mcp-katana resource-path

Add the printed directory to KATANA_RESOURCES, preserving any existing entries. The separator is ; on Windows and : on Linux/macOS. Start Katana, then check the installation:

dcc-mcp-katana doctor
dcc-mcp-cli wait-ready --dcc-type katana
dcc-mcp-cli load-skill katana-nodegraph --dcc-type katana

Each instance uses an OS-assigned port and registers with DCC-MCP discovery. Agents should use the stable local gateway at http://127.0.0.1:9765/mcp; DCC_MCP_KATANA_PORT is only for a deliberately fixed direct endpoint.

Typed tools

Diagnostics and inspection:

• get_status
• inspect_nodegraph
• list_nodes
• get_node
• get_parameter

Node authoring:

• create_node
• rename_node
• delete_nodes
• set_node_position
• select_nodes
• set_parameter_value

Graph and project control:

• add_port
• remove_port
• connect_ports
• disconnect_ports
• set_timeline
• save_project

list_nodes is paginated and capped at 1,000 results. Selection and deletion are capped at 100 nodes. Parameter writes accept only JSON strings, booleans, or finite numbers. Deletion and port removal require confirm=true.

Safe project output

save_project accepts only absolute .katana paths inside DCC_MCP_KATANA_ALLOWED_ROOTS. The variable uses the platform path separator and defaults to the current user's home directory when unset. Existing files require overwrite=true; missing parent directories require create_parents=true. A successful result includes the file size and SHA-256.

Main-thread and timeout contract

At most 32 host calls may be pending. A timeout before Katana starts an operation cancels that operation. A timeout after execution starts reports an unknown final host outcome, so callers must inspect the graph before retrying a non-idempotent operation. Tool schemas carry main-thread affinity and bounded timeouts through the shared HostExecutionBridge.

Real-host smoke test

Open a disposable Katana project, configure an existing writable directory in both DCC_MCP_KATANA_ALLOWED_ROOTS and DCC_MCP_KATANA_SMOKE_ROOT, then run:

python tools/live_katana_smoke.py

The smoke test uses dcc-mcp-cli for discovery, readiness, skill loading, and typed calls. It creates a PrimitiveCreate/Merge graph, adds and connects ports, changes a typed parameter and timeline, saves a .katana file, and prints its byte count and SHA-256. Set DCC_MCP_KATANA_SMOKE_CLEANUP=1 only if the two generated nodes should be deleted after evidence is collected.

The repository's automated tests use a contract-compatible fake Katana API; they are not represented as real-host evidence. A production release should retain the real Katana version, typed CLI transcript, project hash, and visual node-graph evidence.

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check src tests tools
python -m ruff format --check src tests tools
python tools/lint_skills.py
python -m build
python -m twine check dist/*

Agent workflows should use dcc-mcp-cli search, describe, and call rather than bypassing typed tools. If a tool is not visible, load the progressive katana-nodegraph skill first.