Td Universal Toolkit

A unified MCP toolkit for TouchDesigner that lets an AI agent see your project, build networks, check its own visual output, and self-correct — without your involvement.

Tested on TouchDesigner 2023.11340 and 2025.30000. Works with any MCP-capable client (Claude Code, Claude Desktop, Gemini CLI, Cursor, VS Code).

---

Why this exists

Three community projects each solved a different piece of the AI ↔ TouchDesigner problem, but none closed the full loop:

• satoruhiga/claude-touchdesigner gave the agent hands — an HTTP bridge to run Python in TD — but no knowledge of operators or parameters.
• bottobot/touchdesigner-mcp-server gave the agent a brain — 630 operator docs, 69 Python classes, workflow patterns — but no live control.
• 8beeeaaat/touchdesigner-mcp had a clean control architecture but ran the MCP server as a standalone HTTP/SSE web service. Useful for remote / multi-client setups, but when the AI client and TouchDesigner are on the same machine, the simpler MCP stdio transport (client spawns server as a subprocess) covers the same job with much less code.

This toolkit merges all three under one MCP server, one bridge, one port (44444), unified td_ naming, and adds the missing piece none of them had:

A closed visual feedback loop: td_execute → td_get_preview → agent sees the result → td_execute (fix) → repeat.

---

What's in the box

Single bridge

• TouchDesignerAPI.tox — drop into any project, set Active=1, port 44444
• 7 of 8 internal files identical to satoruhiga's original; only the main extension class is rewritten
• Memory-resident: move the project folder anywhere, the bridge stays alive

Single MCP server (29 tools)

Layer	Tools	Source
Live control	td_execute, td_state, td_operators, td_describe, td_get_preview, td_check_errors, td_checkpoint	satoruhiga + new
Network builder (batch)	td_build_network, td_update_nodes, td_delete_nodes, td_annotate	new
Inspection	td_read_chop, td_read_dat, td_get_expressions, td_custom_params	new
Documentation (knowledge base)	get_operator, search_operators, get_python_api, search_python_api, get_operator_connections	bottobot (simplified)
Reference	td_versions, td_experimental, td_build_info, td_vulkan_quirks	bottobot (merged) + new
Shaders	td_generate_shader, td_create_glsl_top, td_write_sync_dat	new
Session / docs	td_session_start, td_toolkit_context	new

Of the 29 tools: 1 kept as-is, 6 rewritten, 4 merged from multiple upstreams, 5 reimplemented from upstream concepts, 13 net-new.

---

Engineering decisions

1. Super-Context for td_execute

satoruhiga's bridge injected only me. Every script needed import td. We pre-inject the entire td module plus all operator-type classes, cached after first call:

# Just works — no imports needed
noise = op('/project1/noise1')
geo = parent().create(geometryCOMP, 'geo1')

2. Visual feedback via /preview

New endpoint: td_get_preview(path) saves a 2x downscaled PNG to Backup/temp/preview_cache.png and returns the path. The agent reads the image, reasons about what it sees, fixes its own code.

3. Memory-resident bridge

Path resolution is relative to the extension's __file__. No hardcoded absolute paths. Move the project anywhere.

4. escapePythonString in network builder

Operator names and paths going into generated Python code are escaped. A single quote in a node name no longer crashes or exploits the script.

4b. Deeper error detection

td_check_errors pulls Vulkan/SPIR-V compiler output from auto-generated *_info DATs alongside every GLSL TOP. Python-side o.errors() / o.warnings() miss most GLSL compile issues — they only surface in the compiler log. The tool merges both sources and returns a compact "ok" when clean (saves tokens), full JSON only on issues.

5. Sterile workspace

• TD_Universal_Toolkit/ is read-only — agent never writes here
• Snapshots → Backup/ via td_checkpoint
• All temp files → Backup/temp/

6. Plumbing fixes invisible from the README of any upstream

• console.log = console.error at the top of index.js — MCP stdio uses stdout for JSON-RPC; any stray console.log from a tool breaks the protocol silently. Bottobot ships without this and is one rogue debug-print away from a broken handshake.
• Shared utils/ layer (td-client.js, response.js, esm-helpers.js, versions.js, config.js, experimental-loader.js). Bottobot has no utils/ folder — fetch logic, response shapes, and version arrays are duplicated across every tool. We DRY'd it.
• brief: true flag on get_operator returns only parameter names + types (no examples, tips, descriptions). Big token saving when the agent already knows the operator.
• Default limit: 3 on search_operators / search_python_api. Upstream defaults to 20 — wastes tokens on every call.
• Connection wiring data extracted from inline 400-line JS object into wiki/data/connections.json. Easier to maintain, agent-readable.
• TDOCS_PATH env var lets users override the hardcoded path to TouchDesigner's offline-help samples directory.
• Stronger schema descriptions ("ALWAYS call this before setting parameters", "input order is operator-specific") — agent gets enforcement at the schema level, not buried in docs.

6. Removed from upstream (deliberately)

• bottobot: compare_operators, get_network_template, get_operator_examples, get_tutorial, list_* duplicates, suggest_workflow, search_tutorials — agent reasons from primitives instead of pre-baked templates
• 8beeeaaat: entire HTTP/SSE transport stack, semantic version compatibility checks, token formatters — overkill for a single-user stdio MCP setup
• Lygia GLSL library — vendored 312 files but rarely used; removed in favour of presets in internal/shaders/

---

Quick Start

Requirements

• TouchDesigner 2023+
• Node.js 18+
• Git
• Any MCP-capable client (Claude Code, Claude Desktop, Gemini CLI, Cursor)

From a fresh clone (Windows, recommended)

Bootstraps a brand-new TD project directory with all the boilerplate (.mcp.json, .claude/settings.json, CLAUDE.md, Backup/temp/):

:: 1. Make an empty project folder
mkdir my_td_project
cd my_td_project

:: 2. Clone the toolkit as a subfolder named exactly "TD_Universal_Toolkit"
git clone https://github.com/kalektika/td-universal-toolkit.git TD_Universal_Toolkit

:: 3. Run the setup script (creates files in my_td_project/, runs npm install)
TD_Universal_Toolkit\SETUP.bat

Then in TouchDesigner: drop TD_Universal_Toolkit\TouchDesignerAPI.tox into your project, set Active = 1. Run TD_Universal_Toolkit\START_UNIVERSAL.bat (or let your MCP client auto-start the server via .mcp.json). Finally cd my_td_project && claude.

Manual install (Mac/Linux, or integrating into an existing project)

1. In TouchDesigner: drop TouchDesignerAPI.tox into your project. Set Active = 1. Bridge listens on port 44444.
2. Install MCP deps:

   cd TD_Universal_Toolkit/td-mcp
   npm install
   

3. Configure your AI client. For Claude Code / Claude Desktop, add to mcp_config.json:

   {
     "mcpServers": {
       "td-universal": {
         "command": "node",
         "args": ["<absolute-path-to>/TD_Universal_Toolkit/td-mcp/index.js"]
       }
     }
   }
   

First run

Tell your agent:

Read TD_Universal_Toolkit/AGENT_QUICKSTART.md, call td_session_start, then build a GLSL TOP showing an animated UV gradient. Show me the preview.

---

Repo structure

TD_Universal_Toolkit/
├── README.md                  ← this file
├── AGENT_QUICKSTART.md        ← agent manifest (rules, tools, conventions)
├── TouchDesignerAPI.tox       ← the bridge (drop into TD)
├── td-mcp/                    ← MCP server (29 tools)
│   ├── index.js
│   ├── tools/                 ← one file per tool
│   ├── wiki/                  ← bottobot's operator/Python KB
│   └── utils/
└── internal/
    ├── AGENT_QUICKSTART.md    ← agent self-instructions
    ├── ADVANCED_PATTERNS.md   ← advanced GLSL/network patterns
    ├── STYLE.md               ← default patching conventions (editable)
    ├── shaders/               ← preset GLSL shaders
    ├── universal_glsl_builder.py
    └── legacy_docs/           ← upstream LICENSE

---

Credits

Built on the work of:

• satoruhiga/claude-touchdesigner — TD HTTP bridge (.tox)
• bottobot/touchdesigner-mcp-server — operator + Python documentation database
• 8beeeaaat/touchdesigner-mcp — node control patterns

iflow-mcp/bottobot-touchdesigner-mcp-server is an identical fork of bottobot — not separately credited.

---

License

MIT. Includes code from satoruhiga, bottobot, and 8beeeaaat — all MIT-licensed. See NOTICE for full attribution and upstream license texts.