touchdesigner-mcp: Skill for Claude Code

TouchDesigner Startup + Functional Self-Debugging

A general technique for verifying any TD-side Python change (e.g. anything in td/modules/**) inside real TouchDesigner. Calling functions directly from the Textport, without standing up the HTTP WebServer, is the shortest path.

This skill is feature-agnostic. The worked example in Steps 4–5 happens to verify node auto-alignment (the PR that produced this skill), but that is illustration only. The reusable shape is: create/modify via the real code path → read back the TD runtime value you actually care about → reconcile against an invariant. Swap the alignment-specific bits (grid, overlap area, node_layout.py) for whatever your change touches. Do not assume alignment, grids, or overlap have anything to do with your task.

When to Execute

• You modified TD-side logic (e.g. td/modules/mcp/services/*.py) and want to check behavior on the real machine.
• Unit/offline verification is insufficient and you need to reconcile against TD runtime data (any node attribute, cook result, error state, etc.).
• You are in a fresh worktree that cannot rely on CI or the 9981-dependent integration suite.

Prerequisites and Pitfalls (read first — these are general)

1. The .tox reads td/modules/ from disk at runtime. Re-authoring the .tox is not required for .py changes; reload modules or restart TD.
2. loadTox() leaves externaltox empty → import_modules.setup() fails with No module named 'mcp'. Replicate setup manually (Step 3).
3. A fresh worktree lacks generated artifacts → empty OpenAPI schema / missing node_modules breaks HTTP routing. Bypass it by calling the Textport directly (Step 4). Only run npm install && npm run gen if you specifically need the HTTP path (e.g. running the vitest integration suite).
4. Computer-use screenshots go black when TD loses frontmost focus → recover with open_application("TouchDesigner") + switch_display.
5. Multi-line pastes into the REPL break on line boundaries → always wrap in exec("""...""") to submit as one statement.
6. To pick up a later .py edit in an already-running TD, drop the module from sys.modules so the next import reloads from disk (Step 3c). If the WebServer is already up you can do this via execute_python_script — no computer-use needed.