# Td Universal Toolkit

> Unified MCP toolkit for TouchDesigner - gives any AI agent live network control, 630-operator knowledge base, and a closed visual feedback loop

- **Type:** MCP server
- **Install:** `agentstack add mcp-kalektika-td-universal-toolkit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kalektika](https://agentstack.voostack.com/s/kalektika)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kalektika](https://github.com/kalektika)
- **Source:** https://github.com/kalektika/td-universal-toolkit

## Install

```sh
agentstack add mcp-kalektika-td-universal-toolkit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```python
# 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/`):

```cmd
:: 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:**
   ```bash
   cd TD_Universal_Toolkit/td-mcp
   npm install
   ```
3. **Configure your AI client.** For Claude Code / Claude Desktop, add to `mcp_config.json`:
   ```json
   {
     "mcpServers": {
       "td-universal": {
         "command": "node",
         "args": ["/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](https://github.com/satoruhiga/claude-touchdesigner)** — TD HTTP bridge (.tox)
- **[bottobot/touchdesigner-mcp-server](https://github.com/bottobot/touchdesigner-mcp-server)** — operator + Python documentation database
- **[8beeeaaat/touchdesigner-mcp](https://github.com/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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kalektika](https://github.com/kalektika)
- **Source:** [kalektika/td-universal-toolkit](https://github.com/kalektika/td-universal-toolkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kalektika-td-universal-toolkit
- Seller: https://agentstack.voostack.com/s/kalektika
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.