Skip to main content
Glama

touchbridge

The TouchDesigner MCP you can leave connected during a show.

Most TouchDesigner MCP servers are built for working in the patch: a designer at the keyboard, TD mostly idle, an agent building networks. touchbridge is built for the moment the show is running: TD under full render load, a project file you can't lose, and an operator who needs to know the second something breaks.

touchbridge is the TouchDesigner control layer from ClipSense, a live-visuals system, pulled out into its own project. Every rule in it comes from a real failure on a real show.

What only touchbridge does

  • Show mode: a performance lock enforced inside TD. One call (or one command) locks the bridge: the agent can still read everything, and it can change only the parameters you allowlisted, e.g. /project1/master:Opacity. Creating, deleting, wiring, scripting and saving are all refused by TD itself, so the lock holds for every client, not just this server. Leaving show mode takes the operator typing END SHOW. The mode survives restarts.

  • A show watchdog. touchbridge-watch (or the bridge_health tool) reports TD crashed, TD frozen, FPS below the cook rate, frame time over budget, dropped frames, and output black, solid or frozen. The numbers come from TD's own Perform CHOP. --reopen brings the last saved .toe back up after a crash.

  • No server inside TD. Commands are files. TD picks them up on a 0.1 s tick at its own pace (an idle tick costs 0.1 ms), and a busy TD answers late instead of dropping connections. A heartbeat tells busy from dead. Measured round trip: about 86 ms median.

  • It can't overwrite your project. Saves go to a new numbered .toe. Snapshots copy files and never Save As. Exports refuse .toe/.tox targets. Safe mode is on by default: delete, raw Python and in-place save are removed from the tool list, and the batch and raw routes are gated too.

And everything you'd expect

70 tools covering nodes, parameters, wiring, CHOP/TOP/SOP/DAT data, timeline, render, project versions, batch, layout, and measurement (cook-time ranking, GPU, pixel statistics, a full-network error sweep). Results come back as compact YAML: about 30% fewer tokens than JSON with nothing lost, and about 80% fewer with detail="summary".

How it compares to the other TouchDesigner MCP servers, honestly: docs/COMPARISON.md.

Quickstart

1. Put the bridge in your project. Drag touchdesigner/TouchBridge.tox (or get it from the latest release) into any TouchDesigner project and save. Nothing needs to be installed on the TD side; the bridge code is embedded in the .tox. To try it right away, open touchdesigner/TouchBridge.toe, which already has the .tox in it.

2. Install the MCP server (Python 3.11+). pipx puts touchbridge-mcp on your PATH, where Claude Desktop and Cursor can find it:

pipx install "git+https://github.com/GaNotchVFX/touchbridge@v0.4.0"
# or: pip install "touchbridge @ git+https://github.com/GaNotchVFX/touchbridge@v0.4.0"

If your client can't find the command, put the full path to touchbridge-mcp (where touchbridge-mcp / which touchbridge-mcp) in "command".

3. Point your MCP client at it. For Claude Desktop, Cursor, and anything else that reads mcpServers:

{
  "mcpServers": {
    "touchbridge": { "command": "touchbridge-mcp" }
  }
}

That's it. Both sides default to the same bridge folder (~/.touchbridge/bridge), so there's nothing to configure. Ask your agent to run bridge_status; you should see alive: true.

Useful flags: --allow-destructive (turns off safe mode), --bridge-dir PATH (or $TOUCHBRIDGE_DIR, set for both TD and the server), --format json, --detail summary. See docs/MCP_REGISTRY.md for more client configs.

Related MCP server: TDPilot

How it works

┌──────────────┐  commands/{id}.json       ┌──────────────────────────────┐
│  MCP client  │ ────────────────────────► │ TouchDesigner + TouchBridge  │
│ (Claude, …)  │  mode.json (show / prep)  │  timer CHOP, every 0.1 s:    │
│ touchbridge- │                           │   show-mode gate, then run   │
│ mcp  (stdio) │  status.json  (heartbeat) │   ≤4 queued commands;        │
│              │ ◄──────────────────────── │   heartbeat + Perform stats  │
└──────────────┘  results/{id}.json        └──────────────────────────────┘
  • TD pulls work; nothing is pushed into it. There's no listening socket and no request handler waiting on TD's main thread. Each tick picks up at most 4 commands, in arrival order, so a flood of calls can't pile into one frame (a single heavy command, such as a big batch_execute or a full-project error sweep, still costs what it costs). If TD is slow, answers arrive later; nothing breaks.

  • The heartbeat is the source of truth. status.json is rewritten every tick. bridge_state reports ok, starting, down (TD running but not answering) or off.

  • One owner. With two TD instances open, exactly one services the queue (owner.json). The claim hands over automatically when the owner goes quiet. This fixed a real incident where two instances were fighting over commands.

  • Cost and speed, measured on TD 2025.32820 (Windows, NVIDIA) at 60 fps: an idle tick costs 0.1 ms of TD's frame, and FPS and frame time were unchanged with the bridge running. A round trip is 86 ms median (p90 125 ms). measure_verify reports yours as round_trip_ms. For 60 Hz streaming control, use OSC for that stream and touchbridge for everything else.

Show mode

touchbridge-mcp --set-mode show --allow "/project1/master:Opacity" --allow "/project1/fx*:Mix"
touchbridge-mcp --set-mode prep          # operator ends the show

Or from the agent: bridge_set_mode(mode="show", allow=[...]). Leaving from the agent needs confirm="END SHOW", and the server tells the model that phrase must come from the human.

In show mode

Always allowed

every read: nodes, params, CHOP/TOP/SOP/DAT data, errors, measure_*, read-only expressions

Allowed if allowlisted

par_set / par_pulse on "/path:ParName" globs you set when entering show mode

Refused inside TD

create, delete, copy, rename, wire, flags, expressions, DAT writes, scripts, exports, timeline changes, saves, snapshots taken inside TD

Refused by the server

bridge_save_increment (a .toe save stalls the frame for as long as the write takes)

The mode is <bridge>/mode.json, read by TD on every tick. It survives restarts, and an unreadable mode file counts as show, so the lock fails closed. The allowlist can't be widened mid-show.

Watchdog

touchbridge-watch --output /project1/out1            # alerts on change, logs to <bridge>/watchdog.log
touchbridge-watch --output /project1/out1 --reopen   # + reopen the last save if TD crashes
touchbridge-watch --once                             # one check; exit code 1 if anything is wrong
21:54:03  ok  fps 61.0/60.0  3.3 ms  all clear

(When something breaks, the line ends in ALERT: followed by the issues, e.g. fps_low: 38.0 of 60; frame_time_high: 26.1 ms (budget 16.7 ms).)

It checks TD running / heartbeating (td_not_running, bridge_down), real FPS vs cook rate, frame time vs budget, dropped frames, realtime off, and, with --output, an output that's black, solid, or showing identical stats twice. It never kills or restarts a TD that's still running; --reopen only acts once the process is gone. The same snapshot is available to agents as bridge_health.

Safety model

Guard

What it does

Safe mode (default on)

node_delete, script_exec, project_save are removed from the tool list, not just flagged with a warning. The same gate covers the indirect routes too: an op inside batch_execute (nested batches included), bridge_router_call, and bridge_send's raw python/eval. Unknown methods are refused, and measure_verify only accepts read-only expressions.

Never-overwrite saves

bridge_save_increment saves to the next unused Name.<N+1>.toe and never targets an existing path. TD's own version counter decides the final name, which is read back and reported.

Snapshots / restore

bridge_snapshot / project_snapshot copy the last saved .toe to a timestamped backup; they never Save As, so the live session stays on your file. bridge_restore lands as a new Name.restored.<N>.toe next to it. node_snapshot saves a node's full parameter state for diffing.

Export guards

render_export / render_screenshot / project_export_tox refuse to overwrite existing files unless you pass overwrite=true. Image exports always refuse .toe/.tox targets. project_import_tox only loads from the project folder (or $TOUCHBRIDGE_TOX_ROOTS).

Exec isolation

python/eval payloads run in their own namespace, never the bridge's globals. A payload once replaced a helper the poll loop depends on and silently killed the command channel for 5 hours while the heartbeat looked fine. This is isolation, not a security sandbox: when safe mode is off, code runs with TD's full powers.

Measure, don't assume

The server tells the model to confirm results by effect (read params back, data_pixel_sample, measure_verify) before reporting success.

What safe mode is and isn't. It's a guardrail against accidents: a confused agent can't delete a network, run a script, or save over your file with a single call. It is not a security boundary against an agent that's trying to get around it. Write-tier tools can still set Python parameter expressions or build an Execute DAT. If you don't trust the model or the prompt, don't connect it to a show machine.

The bridge folder is local: any process running as your user can drop commands in it, the same trust level as a localhost port. Don't share it over a network drive with people you don't trust.

Tools (70; 67 in safe mode)

Tool name = router method with . → _ (node.list → node_list). ◊ = destructive, hidden in safe mode.

  • system: ping, info

  • node: create, delete◊, list, get, copy, rename, find, set_flags, errors, errors_deep (subtree sweep: cook, warning, expression and script errors), clear_script_errors (tells a live problem from a stale one), snapshot (full param state to diff)

  • par: get, set, get_all, info, set_expression, pulse

  • conn: create, delete, get (plus connection.* aliases)

  • data: chop, top (optional base64 PNG), sop, dat, dat_write, pixel_sample (luma mean/min/max/std with dark/solid/clipped flags)

  • script: exec◊, class_list, class_detail, module_help

  • timeline: get, set, play, pause

  • render: screenshot, export

  • project: info, save◊, snapshot, versions, import_tox, export_tox

  • measure: cooktimes (per-op cost, most expensive first), fps (FPS, realtime, throttle queue), gpu (NVIDIA util/VRAM measured host-side + "is TD really rendering"), verify (real round trip plus a live TD value), chain (Src/Srcpath topology and orphan detection for COMP chains that use those custom pars)

  • batch: execute (N ops in one round trip; not a rollback transaction)

  • layout: set_position, align

  • show / health (host side): bridge_mode, bridge_set_mode, bridge_health

  • bridge (host side): bridge_status, bridge_state, bridge_save_increment, bridge_snapshot, bridge_snapshots, bridge_restore, bridge_ensure_alive, bridge_open_show, bridge_router_call, bridge_router_version, bridge_send

  • resources: bridge://project, bridge://versions, bridge://snapshots

  • prompts: diagnose_dark_output, wire_feedback_safely, save_before_editing

Compact results

Every tool accepts two optional arguments:

  • response_format: yaml (default) or json. The YAML is lossless: it parses back to exactly the same data.

  • detail: full (default), summary (lists cut to 25 items plus a ... N more line) or minimal (top-level values only; containers become <N items>). Long strings such as base64 images are never cut.

On sample payloads (80-parameter par_get_all, 120-child node_list), YAML is about 30% smaller than the JSON the MCP SDK sends, and summary is 78–86% smaller. Set server-wide defaults with --format / --detail or $TOUCHBRIDGE_FORMAT / $TOUCHBRIDGE_DETAIL.

Development

pip install -e ".[dev]"
python -m pytest            # 195 tests, no TouchDesigner needed

The router runs against a mock op graph, the file-bridge transport runs the real poll loop in a thread, and the .tox bodies run against a mock COMP.

Rebuild TouchBridge.tox after changing bridge_logic.py or command_router.py. In TD's Textport (Alt+T):

TB_REPO = r"C:\path\to\touchbridge"
exec(open(TB_REPO + "/tools/build_touchbridge_tox.py").read())

Then run python tools/verify_touchbridge.py against real TD. It checks the heartbeat, a node_get round trip, round-trip timing and the router version. For a live-edit loop without rebuilding, set TOUCHBRIDGE_PKG=<repo>/touchbridge on the process that launches TD; the .tox then loads the .py files from disk.

touchbridge/
  command_router.py   in-TD router: 56 handlers (node/par/data/measure/…)
  bridge_logic.py     in-TD poll loop, show-mode gate, heartbeat, owner claim
  client.py           host-side client (send, save_increment, snapshots)
  mcp_server.py       MCP server: tool catalog, safe-mode gating, resources
  watch.py            touchbridge-watch: the show watchdog
  formatting.py       compact YAML / detail shaping
tools/build_touchbridge_tox.py   builds the self-contained TouchBridge.tox
touchdesigner/                   TouchBridge.tox, example TouchBridge.toe, usage notes
tools/verify_touchbridge.py      live post-install check

Status and limits

  • Developed and used on Windows with current TouchDesigner builds. Nothing in the code is Windows-only, but macOS hasn't been tested yet; reports are welcome.

  • GPU stats need an NVIDIA GPU (nvidia-smi). Everything else is vendor-neutral.

  • The live-TD integration check is manual (tools/verify_touchbridge.py): TouchDesigner has no headless mode for CI.

  • Roadmap: PLAN.md. Changes: CHANGELOG.md.

License

MIT; see LICENSE.

Available Tools

67 tools
batch_executeA

Run a list of router requests in ONE bridge round trip (transport batching, not a rollback transaction: failures are reported per item).

ops (list[typing.Any]): [{method, params}, ...] — the ops to run.

abort_on_error (bool | None): Stop at the first failure (default false).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: ops (required), detail, abort_on_error, response_format.

bridge_ensure_aliveA

Open the show in TD (if needed) and wait for the bridge heartbeat. Returns alive status.

timeout (float | None): Max seconds to wait (default 45).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, timeout, response_format.

bridge_healthA

Show health in one call: bridge alive / TD frozen / TD gone, REAL fps vs cook rate, frame time vs budget, dropped frames, GPU memory/temp (TD's Perform CHOP), mode, and optionally whether an output TOP is black or solid.

output (str | None): TOP path of the show output to check for black/solid.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, output, response_format.

bridge_modeA

Current bridge mode: prep (normal editing) or show (live performance lock: reads + allowlisted params only), with the allowlist and since-when.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

bridge_open_showA

Launch the resolved show .toe in TouchDesigner (refuses if TD is already running unless force).

force (bool | None): Launch even if TD is running.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: force, detail, response_format.

bridge_restoreA

Restore a backup into the show folder as a NEW restored..toe sibling (never overwrites the live file).

backup (<class 'str'>): Absolute path to a backup .toe.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: backup (required), detail, response_format.

bridge_router_callA

Raw router call for ANY router method (escape hatch; prefer the typed tools). Destructive methods stay gated by safe mode.

method (<class 'str'>): Router method name (e.g. 'node.get').

params (dict[str, typing.Any]): Method parameters as a dict.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: method (required), detail, params, response_format.

bridge_router_versionA

Router surface version + method count (capability negotiation; soft-warn on mismatch, never hard-lock).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

bridge_save_incrementA

SAFE save: write the next numbered Show.<N+1>.toe and structurally refuse to overwrite an existing file. The preferred way to persist bridge edits.

timeout (float | None): Seconds to wait (default 45).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, timeout, response_format.

bridge_sendA

Raw bridge send: op + payload. In safe mode only catalogued non-destructive router methods pass; the raw python/eval opcodes need --allow-destructive.

op (<class 'str'>): Bridge opcode (eval, python, ...).

payload (dict[str, typing.Any]): Payload dict.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: op (required), detail, payload, response_format.

bridge_set_modeA

Enter SHOW mode (lock the bridge for a live performance: reads and the allowlisted parameters only; enforced inside TD for every client) or return to PREP. Leaving show mode needs confirm='END SHOW' TYPED BY THE HUMAN OPERATOR: never supply it on your own initiative.

mode (<class 'str'>): 'show' or 'prep'.

allow (list[str]): Entering show: params that may still change, as '/path:ParName' globs (e.g. '/project1/master:Opacity', '/project1/fx*:Mix').

confirm (str | None): Leaving show: the exact phrase END SHOW, from the operator.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: mode (required), allow, detail, confirm, +1 more.

bridge_snapshotA

Copy the current show .toe to a timestamped backup (never overwrites anything).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

bridge_snapshotsA

List existing backups, newest-first.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

bridge_stateB

TD three-state probe: ok | starting | down | off.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

bridge_statusA

Bridge heartbeat state: alive, age (s), project, build.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

conn_createA

Wire two ops together (output -> input).

fromPath (<class 'str'>): Source operator path.

toPath (<class 'str'>): Destination operator path.

fromOutput (int | None): Source output index (default 0).

toInput (int | None): Destination input index (default 0).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: toPath (required), fromPath (required), detail, toInput, +2 more.

conn_deleteB

Disconnect an input and/or output of a node.

path (<class 'str'>): Operator path.

inputIndex (int | None): Disconnect this input.

outputIndex (int | None): Disconnect this output.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, inputIndex, outputIndex, +1 more.

connection_createB

Alias of conn.create (kept for MCP-side compat).

fromPath (<class 'str'>): Source operator path.

toPath (<class 'str'>): Destination operator path.

fromOutput (int | None): Source output index (default 0).

toInput (int | None): Destination input index (default 0).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: toPath (required), fromPath (required), detail, toInput, +2 more.

connection_deleteB

Alias of conn.delete.

path (<class 'str'>): Operator path.

inputIndex (int | None): Disconnect this input.

outputIndex (int | None): Disconnect this output.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, inputIndex, outputIndex, +1 more.

connection_getD

Alias of conn.get.

path (<class 'str'>): Operator path.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, response_format.

conn_getA

Read all input/output connections of a node.

path (<class 'str'>): Operator path.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, response_format.

data_chopA

Read CHOP channel values (uniformly downsampled).

path (<class 'str'>): CHOP operator path.

max_samples (int | None): Max samples per channel (default 1024).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, max_samples, response_format.

data_datA

Read text or table DAT content.

path (<class 'str'>): DAT operator path.

row_start (int | None): First table row (default 0).

row_end (int | None): Last table row, exclusive.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, row_end, row_start, +1 more.

data_dat_writeA

Write text / append a row / clear a DAT.

path (<class 'str'>): DAT operator path.

text (str | None): Replace full text content.

appendRow (list[typing.Any]): Append a row to a table DAT.

clear (bool | None): Clear before writing.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), text, clear, detail, +2 more.

data_pixel_sampleA

Luma statistics of a TOP (mean/min/max/std) with dark / solid / clipped flags. The 'is the output actually black?' verifier.

path (<class 'str'>): TOP operator path.

grid (int | None): Samples per axis (default 16).

numpy (bool | None): Full-frame read via numpyArray().

dark_below (float | None): Mean luma below this = dark (0.02).

solid_std (float | None): Std below this = solid (0.005).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), grid, numpy, detail, +3 more.

data_sopA

SOP point count/positions and bounds.

path (<class 'str'>): SOP operator path.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, response_format.

data_topA

TOP resolution, optionally base64 PNG pixel capture.

path (<class 'str'>): TOP operator path.

pixels (bool | None): Capture pixels as base64 PNG.

max_width (int | None): Downscale if wider (default 512).

max_height (int | None): Downscale if taller (default 512).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, pixels, max_width, +2 more.

layout_alignA

Distribute nodes along a horizontal or vertical axis.

paths (list[str]): Ordered operator paths.

axis (str | None): 'horizontal' (default) or 'vertical'.

start_x (float | None): X of the first node.

start_y (float | None): Y of the first node.

spacing (float | None): Gap between centres (default 200).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: paths (required), axis, detail, spacing, +3 more.

layout_set_positionA

Set network-editor position of one or more nodes.

nodes (list[typing.Any]): [{path, x, y}, ...].

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: nodes (required), detail, response_format.

measure_chainA

Per-device topology: Bypass/Src/Srcpath truth + chain orphan detection for chained COMPs.

path (str | None): Root container to scan (default '/').

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path, detail, response_format.

measure_cooktimesA

Per-operator cook cost (ms) sorted most-expensive first: which device is eating the frame.

paths (list[str]): Operator paths to measure.

path (str | None): Parent whose children are measured.

top (int | None): Return only the N most expensive.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: top, path, paths, detail, +1 more.

measure_fpsC

FPS, realtime flag, cook rate, throttle queue.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

measure_gpuA

GPU util/VRAM (NVIDIA, measured host-side so TD never blocks) + whether TD is really rendering. The 'looks healthy but isn't' detector.

require_render (bool | None): Error instead of returning empty stats when TD is not rendering and no GPU numbers are available (default false).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, require_render, response_format.

measure_verifyA

Round-trip canary over the file bridge: rtt_ms + a live TD value (absTime.seconds by default).

expr (str | None): Expression to eval (default absTime.seconds).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: expr, detail, response_format.

node_clear_script_errorsA

Clear a node's accumulated script-error log, force a cook, re-read. recurring: true is proof of a LIVE problem; a one-off hit was stale.

path (<class 'str'>): Operator path.

force_cook (bool | None): cook(force=True) after clearing (default true).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, force_cook, response_format.

node_copyA

Copy a node into a destination parent.

sourcePath (<class 'str'>): Path of the operator to copy.

destParentPath (<class 'str'>): Destination parent COMP path.

name (str | None): Name for the copy; TD assigns if omitted.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: sourcePath (required), destParentPath (required), name, detail, +1 more.

node_createB

Create an operator in a parent COMP (e.g. 'noiseCHOP'). Auto-placed to the right of siblings.

parentPath (<class 'str'>): Full path of the parent COMP.

type (<class 'str'>): Operator type string (e.g. 'noiseCHOP').

name (str | None): Desired name; TD assigns one if omitted.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: type (required), parentPath (required), name, detail, +1 more.

node_errorsA

Errors/warnings for a node, optionally including children.

path (<class 'str'>): Full path of the operator.

includeChildren (bool | None): Also collect child errors.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, includeChildren, response_format.

node_errors_deepA

Walk a whole subtree; report every node with cook errors, warnings, parameter-expression errors or script errors. Only nodes with a problem are returned.

path (str | None): Root of the walk (default '/project1').

max_depth (int | None): Recursion limit (default 32).

max_nodes (int | None): Visit cap (default 5000).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path, detail, max_depth, max_nodes, +1 more.

node_findA

Search for nodes matching name/type/family, recursively.

path (str | None): Root container to search (default '/').

name (str | None): Case-insensitive substring on node name.

type (str | None): Exact operator type (case-insensitive).

family (str | None): 'CHOP'/'TOP'/'DAT'/'SOP'/...

depth (int | None): Max recursion depth (default 5).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: name, path, type, depth, +3 more.

node_getA

Full metadata for one operator (params, connections, position).

path (<class 'str'>): Full path of the operator.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, response_format.

node_listA

List children of a container, optionally filtered by family.

path (str | None): Parent container path (default '/').

family (str | None): Filter by operator family (CHOP/TOP/...).

depth (int | None): Recursion depth; 1 = direct children.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path, depth, detail, family, +1 more.

node_renameA

Rename a node.

path (<class 'str'>): Full path of the operator.

name (<class 'str'>): New name for the operator.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: name (required), path (required), detail, response_format.

node_set_flagsB

Set display / render / bypass flags on a node.

path (<class 'str'>): Full path of the operator.

display (bool | None): Set display flag.

render (bool | None): Set render flag.

bypass (bool | None): Set bypass flag.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), bypass, detail, render, +2 more.

node_snapshotA

Complete parameter state (value/mode/expr/evalError) + flags, optionally written to a JSON file (never overwrites). Diff two snapshots around a risky edit.

path (<class 'str'>): Operator path.

out (str | None): JSON file under the project folder.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), out, detail, response_format.

par_getA

Read parameter values, optionally filtered by glob.

path (<class 'str'>): Operator path.

pattern (str | None): Glob like 't[xyz]'; None = all.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, pattern, response_format.

par_get_allA

Full metadata (mode, bounds, menu names) for every par.

path (<class 'str'>): Operator path.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, response_format.

par_infoA

Metadata for named parameters (or all if names omitted).

path (<class 'str'>): Operator path.

names (list[str]): Parameter names; None = all.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), names, detail, response_format.

par_pulseA

Pulse a momentary parameter.

path (<class 'str'>): Operator path.

name (<class 'str'>): Parameter name.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: name (required), path (required), detail, response_format.

par_setA

Set one or more parameter values on an operator.

path (<class 'str'>): Operator path.

values (dict[str, typing.Any]): Mapping of parameter name -> value.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), values (required), detail, response_format.

par_set_expressionC

Put a parameter into expression mode.

path (<class 'str'>): Operator path.

name (<class 'str'>): Parameter name.

expression (<class 'str'>): Python expression string.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: name (required), path (required), expression (required), detail, +1 more.

project_export_toxA

Save a COMP to a .tox. Never a .toe; never overwrites unless overwrite=true.

path (<class 'str'>): COMP operator path.

out (<class 'str'>): Destination .tox under the project folder.

overwrite (bool | None): Allow replacing an existing file.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: out (required), path (required), detail, overwrite, +1 more.

project_import_toxA

Load a .tox into a parent COMP. Path must be under the project folder or $TOUCHBRIDGE_TOX_ROOTS; .toe refused.

path (<class 'str'>): The .tox file.

parentPath (str | None): COMP to load into (default '/project1').

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, parentPath, response_format.

project_infoA

Project + app metadata (name, folder, version, cook rate).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

project_snapshotA

Save a timestamped, collision-free backup .toe.

dest (str | None): Backup folder; 'snapshots/' next to the project.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: dest, detail, response_format.

project_versionsA

List saved .toe versions in the project folder, newest-first.

folder (str | None): Folder to scan (default project folder).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, folder, response_format.

render_exportB

Export a TOP frame to a file (extension picks format).

path (<class 'str'>): TOP operator path.

save_path (<class 'str'>): Output path (.png/.jpg/.exr...).

quality (int | None): JPEG quality 0-100 (default 90).

overwrite (bool | None): Replace an existing file (default false; .toe/.tox never).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), save_path (required), detail, quality, +2 more.

render_screenshotA

Save a TOP's current frame to a PNG file.

path (<class 'str'>): TOP operator path.

save_path (str | None): Output PNG path; tempfile if omitted.

overwrite (bool | None): Replace an existing save_path (default false; .toe/.tox never).

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: path (required), detail, overwrite, save_path, +1 more.

script_class_detailA

Methods/properties/docstring for a td class.

name (<class 'str'>): Class or attribute name.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: name (required), detail, response_format.

script_class_listA

List names in the td module (optional substring filter).

pattern (str | None): Case-insensitive substring.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, pattern, response_format.

script_module_helpA

help() output for a td name.

name (<class 'str'>): Name to look up.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: name (required), detail, response_format.

system_infoA

TD version, cook rate, realtime flag and the full registered method list.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

system_pingA

Liveness canary. Returns pong + TD frame.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

timeline_getB

Current timeline / playback state.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

timeline_pauseB

Pause timeline playback.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

timeline_playA

Start timeline playback.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: detail, response_format.

timeline_setA

Set cookRate, realTime and/or jump to a frame.

cookRate (float | None): Desired cook rate (fps).

realTime (bool | None): Enable/disable real-time playback.

frame (int | None): Jump to this absolute frame.

detail (str | None): full (default) | summary (long lists cut to 25 + count) | minimal (top-level scalars only).

response_format (str | None): yaml (default, token-cheap) | json.

Inputs: frame, detail, cookRate, realTime, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 67 tools

    Disambiguation3/5

    There are several pairs of tools with overlapping purposes: node_get vs node_snapshot (both read node state), par_get vs par_info vs par_get_all (all read parameter info), and the connection_* aliases duplicate conn_* tools. However, many tools have distinct purposes (node_create vs node_copy vs node_rename). The presence of aliases and similar read endpoints creates some ambiguity.

    Naming Consistency3/5

    The naming is mostly consistent with verb_noun pattern (e.g., node_get, par_set, data_chop), but there are deviations: some tools use 'get' (node_get) while others use 'list' (node_list), and the use of 'connection_*' aliases alongside 'conn_*' breaks consistency. Also, 'par_get_all' versus 'par_info' are not clearly differentiated by name.

    Tool Count2/5

    With 57 tools, this is far beyond the typical 3-15 range and even exceeds the 25+ threshold. The server covers a broad domain (TouchDesigner automation), but many tools are highly specialized (e.g., measure_chain, data_pixel_sample) and could be consolidated. The count feels overwhelming and undermines usability.

    Completeness4/5

    The tool surface is quite comprehensive: it covers node CRUD (create, copy, rename, delete? no delete but set_flags), parameter operations (get, set, expression, pulse), connections, data reading for all families, timeline control, rendering, project save/restore, and performance measurement. Minor gaps include no explicit node delete or connection listing beyond conn_get, but the breadth is strong.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers