dcc-mcp-touchdesigner

Typed, main-thread-safe TouchDesigner control for the DCC Model Context Protocol.

The adapter embeds the DCC-MCP HTTP runtime in TouchDesigner, registers the instance with the local gateway, and executes TouchDesigner API work through the documented td.run() scheduler. Agents can inspect and edit operator networks, parameters, Unicode DAT content, and root timeline state, then save projects and export TOP images without sending TouchDesigner objects to background threads.

Illustrative workflow visualization generated with OpenAI ImageGen from the retained source in docs/images/sources. It is not a TouchDesigner screenshot or host-validation artifact. The header uses an approved operator-network reference motif rather than an official host mark.

Install

TouchDesigner 2025 uses Python 3.11. Install this package into the interpreter that TouchDesigner will import, inspect the machine-readable plan, and apply the receipt-owned integration:

python -m pip install --upgrade dcc-mcp-touchdesigner
dcc-mcp-touchdesigner install --dry-run --json
dcc-mcp-touchdesigner install --yes --json
dcc-mcp-touchdesigner verify --json

TouchDesigner physically stores startup callbacks in a project Execute DAT, so the installer returns one structured file_edit and exit code 50 until that edit and a restart are complete. See install.md for supported platforms, exact flags and exit codes, the TDPyEnvManager/Preferences manual route, upgrade, uninstall, verification, and recovery.

Start in TouchDesigner

Run this from the Textport or an Execute DAT onStart() callback:

import dcc_mcp_touchdesigner

server = dcc_mcp_touchdesigner.start_server()
print(server.mcp_url)

start_server() is idempotent inside one TouchDesigner process. It loads the bundled skill by default, selects an OS-assigned loopback port, starts the main-thread pump, and advertises the instance to a running DCC-MCP gateway. Stop it explicitly during project teardown when needed:

dcc_mcp_touchdesigner.stop_server()

Typed tools

All 19 tools have JSON input/output contracts and are dispatched on TouchDesigner's main thread. File-writing tools require an explicit absolute path and reject accidental overwrite unless overwrite=true is supplied. Root deletion and executable-DAT mutation are always rejected. The catalog exposes no arbitrary Python or expression-evaluation tool.

Security controls

The public contract is typed-only: it has no arbitrary Python escape hatch. Recursive graph, parameter, connector, JSON, and DAT operations are bounded; DAT writes use optional SHA-256 optimistic concurrency and only target Text/Table DATs. DAT text is treated as arbitrary Unicode data rather than a finite language list: RTL text, combining marks, ZWJ sequences, and non-BMP characters are preserved without language detection or normalization. Operator and parameter identifiers still follow TouchDesigner's own naming rules. The adapter binds to loopback by default. Do not expose the per-instance port directly to an untrusted network. Use the DCC-MCP gateway when multiple instances or attributable agent sessions are required.

Runtime configuration

Development

py -3.11 -m pip install -e ".[dev]"
pytest
ruff check .
ruff format --check .
dcc-mcp-cli lint src/dcc_mcp_touchdesigner/skills/touchdesigner-scripting --warnings-as-errors
python -m build
python -m twine check dist/*

Unit and contract tests use a deterministic TouchDesigner API double. A release additionally requires a real TouchDesigner process, six readiness checks, discovery of all 19 typed tools, and a create/connect/layout/set/pulse/DAT/timeline/capture/save/delete chain through dcc-mcp-cli; simulation alone is not release evidence.

License

MIT