# TouchDesigner MCP

TouchDesigner MCP lets Codex inspect, build, wire, tune, sample, and visually verify a running TouchDesigner project. It is designed for generative visuals, audio-reactive systems, GLSL iteration, show-control networks, and fast agent-assisted prototyping.

The integration is local-first:

```text
Codex / ChatGPT desktop / Codex CLI
          │ MCP over stdio
          ▼
  touchdesigner-mcp (Node.js)
          │ authenticated HTTP on 127.0.0.1
          ▼
 TouchDesigner Web Server DAT
          │ main-thread Python callbacks
          ▼
     your .toe network
```

## What it can do

- Inspect networks, operators, parameters, wiring, cook times, warnings, and script errors.
- Create and connect COMP, TOP, CHOP, SOP, MAT, DAT, and POP operators.
- Set constant parameters, Python expressions, and bind expressions.
- Update GLSL/Text DAT source with optional compare-before-write protection.
- Build a reusable audio analysis rig with `low`, `mid`, `high`, `level`, and `beat` channels.
- Sample live CHOP values and return TOP captures as real MCP image content.
- Apply ordered edit batches with a best-effort TouchDesigner undo block.
- Run arbitrary TouchDesigner Python only when explicitly enabled on both sides.

The server uses the current split MCP TypeScript packages and serves both modern and legacy MCP clients through the SDK's stdio negotiation entry point.

## Requirements

- TouchDesigner 2025 Official or newer. POP tooling requires a POP-capable build.
- Node.js 20 or newer.
- A local Codex client: ChatGPT desktop, Codex CLI, or the Codex IDE extension.

## 1. Install the TouchDesigner bridge

1. Clone this repository.
2. Drag `touchdesigner/install_bridge.py` into `/project1` in TouchDesigner as a Text DAT.
3. Right-click the DAT and select **Run Script**.
4. Copy the printed URL and token. The default URL is `http://127.0.0.1:9980`.
5. Confirm `http://127.0.0.1:9980/health` returns JSON in a browser.

If TouchDesigner cannot find the sibling callback file, run this in the Textport with absolute paths:

```python
installer = r"C:\path\to\touchdesigner-mcp\touchdesigner\install_bridge.py"
callbacks = r"C:\path\to\touchdesigner-mcp\touchdesigner\bridge_callbacks.py"
scope = {'__name__': 'touchdesigner_mcp_installer'}
exec(compile(open(installer, encoding='utf-8').read(), installer, 'exec'), scope)
scope['install'](callback_file=callbacks)
```

The installer creates `/project1/touchdesigner_mcp_bridge`, a loopback-only Web Server DAT, its callback DAT, and a random bearer token. Save the `.toe` after installation.

## 2. Build the MCP server

```powershell
npm install
npm run build
```

From the repository root, confirm it starts:

```powershell
$env:TOUCHDESIGNER_URL = 'http://127.0.0.1:9980'
$env:TOUCHDESIGNER_TOKEN = 'paste-token-here'
node dist/index.js
```

The process waits for MCP messages on stdin. Its readiness message is written to stderr so it never corrupts the MCP protocol stream.

## 3. Connect Codex

The supported CLI form is:

```powershell
codex mcp add touchdesigner `
  --env TOUCHDESIGNER_URL=http://127.0.0.1:9980 `
  --env TOUCHDESIGNER_TOKEN=paste-token-here `
  -- node C:\absolute\path\to\touchdesigner-mcp\dist\index.js
```

Or add this to `~/.codex/config.toml` (also available as [`examples/codex.config.toml`](examples/codex.config.toml)):

```toml
[mcp_servers.touchdesigner]
command = "node"
args = ["C:/absolute/path/to/touchdesigner-mcp/dist/index.js"]
startup_timeout_sec = 15
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

[mcp_servers.touchdesigner.env]
TOUCHDESIGNER_URL = "http://127.0.0.1:9980"
TOUCHDESIGNER_TOKEN = "paste-token-here"
```

Restart the local Codex client after adding the server, then use `/mcp` or `codex mcp list` to confirm it is enabled. The ChatGPT desktop app and Codex IDE extension also expose MCP server settings in their UI.

## First session

Try this prompt:

> Check TouchDesigner status. Inspect `/project1`, build an audio-reactive analysis rig, then create a feedback-based visual whose displacement follows low frequencies and whose color follows high frequencies. Check the network for errors and capture the final TOP so we can iterate visually. Do not delete existing operators.

Codex can use this verification loop:

1. `td_status`
2. `td_list_operators` and `td_inspect_operator`
3. `td_build_audio_reactive_rig`
4. `td_batch` for coherent graph creation and wiring
5. `td_sample_chop` to calibrate live ranges
6. `td_get_errors`
7. `td_capture_top` to evaluate the result visually

## Tools

| Tool | Purpose | Mutation |
|---|---|---|
| `td_status` | Bridge, build, project, timeline, capabilities | Read |
| `td_list_operators` | Bounded recursive network discovery | Read |
| `td_inspect_operator` | Parameters, wiring, cook data, errors | Read |
| `td_create_operator` | Create any supported OP type | Write |
| `td_set_parameters` | Constants, expressions, bind expressions | Write |
| `td_pulse_parameter` | Reset/open/clear-style actions | Write |
| `td_connect` / `td_disconnect` | Network wiring | Write |
| `td_set_dat_text` | GLSL, scripts, and callback source | Write |
| `td_sample_chop` | Live control/audio values | Read |
| `td_capture_top` | PNG/JPEG visual feedback | Read |
| `td_get_errors` | Errors, warnings, and script errors | Read |
| `td_build_audio_reactive_rig` | Standardized audio features | Write |
| `td_batch` | Up to 100 ordered graph edits | Write/destructive |
| `td_delete_operator` | Delete exactly one non-protected OP | Destructive |
| `td_run_script` | Arbitrary Python, opt-in only | Destructive |

## Audio-reactive design notes

`td_build_audio_reactive_rig` creates a source, full spectrum view, filtered low/mid/high RMS branches, a full-level RMS branch, a configurable beat gate, smoothing, and `/OUT_AUDIO`. Use the stable output Null in expressions and exports so downstream visuals survive internal changes.

Good mappings are usually nonlinear and smoothed:

- `low`: feedback displacement, scale, particle emission, camera kick.
- `mid`: geometry deformation, noise amplitude, line width, scene transitions.
- `high`: bloom, chromatic separation, color temperature, strobe accents.
- `level`: master intensity or a subtle breathing envelope.
- `beat`: threshold gate for cuts, triggers, and event-style accents.

Sample the live channels before choosing ranges. A Math CHOP or Function CHOP can normalize, clamp, ease, and shape response curves more reliably than hard-coded multipliers.

## Safety model

- The bridge listens on `127.0.0.1` by default and uses a random bearer token.
- `/health` is the only unauthenticated route and exposes no project data.
- Request bodies, list sizes, batch sizes, and image sizes are bounded.
- `/`, `/project1`, the bridge itself, and its ancestors cannot be deleted.
- Arbitrary Python is absent from the MCP tool list unless `TOUCHDESIGNER_ALLOW_SCRIPT=true`; the TouchDesigner bridge must independently allow it.
- `td_set_dat_text` supports `expectedText` for optimistic concurrency.
- Batch rollback uses TouchDesigner's undo system and is best-effort; save/version important projects before large mutations.

Do not expose the Web Server DAT to another interface unless you add TLS, network controls, and an appropriate authentication design. Basic local bearer-token protection is not an internet-facing security boundary.

## Configuration

| Environment variable | Default | Meaning |
|---|---:|---|
| `TOUCHDESIGNER_URL` | `http://127.0.0.1:9980` | Bridge base URL |
| `TOUCHDESIGNER_TOKEN` | empty | Bearer token printed by installer |
| `TOUCHDESIGNER_TIMEOUT_MS` | `15000` | Per-call timeout |
| `TOUCHDESIGNER_ALLOW_SCRIPT` | `false` | Advertise arbitrary Python tool |
| `TOUCHDESIGNER_MAX_CAPTURE_BYTES` | `8000000` | Maximum decoded TOP capture size |

## Development

```powershell
npm run validate
npm run build
npm pack --dry-run
```

TouchDesigner-specific code is syntax-checked outside TouchDesigner, while its behavior must be integration-tested in a running licensed TouchDesigner process. The HTTP client and error handling have isolated unit tests.

See [`docs/architecture.md`](docs/architecture.md), [`docs/protocol.md`](docs/protocol.md), and [`CONTRIBUTING.md`](CONTRIBUTING.md) for extension guidance.

## Sources and compatibility

This project follows the official [Codex MCP configuration documentation](https://developers.openai.com/codex/mcp), the official [MCP TypeScript SDK server guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md), and Derivative's [Web Server DAT](https://docs.derivative.ca/Web_Server_DAT), [Webserver DAT class](https://derivative.ca/UserGuide/WebserverDAT_Class), [Connector class](https://derivative.ca/UserGuide/Connector_Class), and [TOP capture](https://derivative.ca/UserGuide/TOP_Class) APIs.

## License

MIT