Tdmco

Read-only health check + TouchDesigner server info. Returns {connected, endpoint, touchdesigner version info, knowledge-base stats, bridge_stale?} and changes nothing. Use this first to confirm the bridge is reachable; it succeeds even when TD is offline, reporting connected:false with the reason. Also warns when the running Python bridge is older than this build (a common gotcha — editing td/ doesn't reload the running bridge), pointing you at reload_bridge.

Read-only: resolve compact TouchDesigner operator, Python API, or concept documentation from the installed OfflineHelp corpus first, then the embedded KB. Returns section ids for bounded drill-down plus installed/running build provenance. Web fallback is off by default and, when explicitly enabled, is restricted to docs.derivative.ca and labeled as latest-web rather than installed-build truth. Never accepts a filesystem path or returns raw HTML.

Read-only pre-show check: bridge reachability, node errors, topology, cook-time budget, GPU/display topology and perform-mode status in one PASS/UNVERIFIED/WARN/FAIL report. Use before rehearsals or venue handoff to see what is safe, unverified, suspicious, or failing without mutating the project.

Copy a RayTK ROP master (SDF / camera / light / combine / material / render) into a network and optionally wire an existing op into one of its typed inputs, using the same COMP.copy primitive RayTK's own palette uses. Resolves the install-dependent master path live (RayTK's pathsByOpType lookup, or a category-folder search) — never hardcoded — so it requires the RayTK toolkit staged + loaded first (see manage_packages / the tdmcp://raytk/operators catalog). Complementary to the GLSL create_raymarch_scene: this instances RayTK's own operators instead of authoring a shader.

Create a single bare operator (node) inside a parent COMP with optional deterministic auto placement or exact coordinates and viewer state. Omitted placement preserves legacy bridge behavior; idempotently reused nodes keep their existing coordinates. Validates the operator type against the knowledge base and warns (without blocking) on unknown types. Returns {node, warnings[]} for the created node. For a complete wired+arranged network prefer a Layer-1 create_* tool.

Safely remove or bypass one TouchDesigner node. mode:'delete' asks the artist in TouchDesigner to choose exactly Delete / Bypass / Keep; close, timeout, error or unavailable UI means Keep. mode:'bypass' is immediate and reversible. TDMCP_YOLO is an explicit audited skip policy, never inferred from missing UI. The bridge wraps the final mutation in a TouchDesigner undo block; whole-tool undo across multiple REST requests remains unverified. Returns the decision, action applied, final path, confirmation policy/request id and undo label when available.

Read compact project and editor state for references such as 'this node', 'the selected node', and 'place it here'. Returns only available project/build, perform mode, pane, active Network Editor, current/selected, rollover and viewport fields; unavailable UI fields are omitted with warnings instead of inferred. Does not dump project topology or mutate TouchDesigner.

Save the current TouchDesigner project or Save As to an explicit path. Existing Save As targets require bounded native overwrite consent and fail closed to Keep on timeout, close, error, or unavailable UI. Never opens a native file dialog, loads/quits a project, or falls back to raw Python. Returns the requested/final path, verified save state, decision and project/build metadata.

Validate that an existing operator parameter is Pulse style, invoke its structured .pulse() operation, and confirm the result. Missing operators, missing parameters and non-Pulse styles return typed bridge errors. Does not use raw Python fallback.

Atomically edit an operator's name, parent, exact Network Editor position, color, comment, or writable flags. The bridge prevalidates requested fields, reads values back, and rolls back partial failures; parent moves copy and validate the destination before destroying the source. Returns the final path and per-field results. Does not use raw Python fallback.

Modify an existing node by setting one or more of its parameters to constant values. The update is strict (not best-effort): an unknown parameter name fails the whole call atomically without changing anything, and a bad value (wrong type or out of range) returns an error naming which parameters applied and which failed. On success returns the updated {node}. To inspect valid parameter names/current values first use get_td_node_parameters; to make a parameter move over time use animate_parameter instead of a static value.

Read-only: list the DIRECT child nodes of one COMP. Defaults to a compact summary (count + type breakdown + sample paths); pass detail_level:"full" or path_only:true for the complete list, and `pattern` to filter by name. Returns {count, by_type/sample or paths/nodes}. Use this to browse one level; use find_td_nodes to search recursively and by operator type, or get_td_topology when you also need the connections between nodes. Token economy: keep the default compact summary and scope with `pattern`; only request the full list when you truly need every path, and avoid re-listing a path you already inspected.

Read-only: read the current parameters (and inputs/outputs) of one node. Returns {path, type, name, parameters, inputs, outputs}. Pass `keys` to project specific parameters or `omit_io:true` to drop the inputs/outputs lists. Use compare_td_nodes to diff two nodes' parameters at once. Token economy: pass `keys` to fetch only the parameters you care about and `omit_io:true` to drop inputs/outputs — a full parameter dump is large.

Read-only: for each parameter of a node, report its mode (CONSTANT / EXPRESSION / EXPORT / BIND), its evaluated value, and its raw expression / bind-expression / export-source strings. Use this to faithfully serialize a network for round-trip editing, diffing, or debugging — the evaluated value alone hides which parameters are driven by expressions or exports. Set `non_default_only` to surface only the parameters that would be lost in a plain value copy.

Read-only: check one node (or, with recursive:true, its whole sub-network) for cook/compile errors and warnings. Pass `summary:true` for grouped counts instead of the full list. Returns {total, errors[] or by_type}. For a large network prefer summarize_td_errors, which clusters errors by shared cause and points at the worst-offending nodes.

Escape hatch — run an arbitrary Python script inside the TouchDesigner process. Prefer the structured tools (find_td_nodes, get_td_node_parameters, update_td_node_parameters, summarize_td_errors, snapshot_td_graph, …); reach for this only when no structured tool can express the operation. Code runs in TD only, never on the local machine.

Escape hatch — invoke an arbitrary Python method on a node (operator). Prefer structured tools where one exists; use this for operations they don't cover (e.g. .cook(), .copy(), .destroy()).

Read-only: list TouchDesigner Python API class names from the embedded knowledge base (works offline, never touches TD). Returns {classes[]} of name/displayName entries. Optionally filter by name. Use get_td_class_details or get_module_help to expand one class into its members and methods.

Read-only: full STRUCTURED documentation for one TouchDesigner Python class (members + methods) from the embedded knowledge base (offline). Returns the class object, or {found:false, suggestions[]} of near-name matches if unknown. Use get_module_help instead when you want the same content as ready-to-read Markdown rather than structured JSON.

Read-only: human-readable Markdown help (description, members, method signatures) for a TouchDesigner Python class or module, from the embedded knowledge base (offline). Returns formatted text, or {found:false, suggestions[]} of near-name matches if unknown. Use get_td_class_details instead when you need the same information as structured JSON to process in code.

Read-only: report cook times under a network (recursively by default, slowest node first) and warn about nodes that exceed the frame budget. Returns {targetFps, frameBudgetMs, totalCookMs, nodes[], warnings[]} and changes nothing. Use this to just measure; use optimize_performance when you want suggestions and the option to auto-shrink the slow TOPs.

Read-only: return the nodes AND the connections (wiring) under a network root, flagging obvious structural issues. Returns {nodeCount, connectionCount, issues[], topology}. Use this when you need how nodes are wired together; use get_td_nodes/find_td_nodes when you only need the node list without connections, or snapshot_td_graph when you also want each node's parameters captured for diffing. Token economy: point it at a specific network root rather than the project root, and leave recursion off unless you need nested networks.

Read-only: compact bridge-side node search by name/path glob, exact or partial operator type, family and bounded depth. Returns {count, truncated, matches/paths, search_metadata} without transferring topology; older bridges fall back only to structured list/topology reads. Prefer this over get_td_nodes when looking through a sub-tree; use get_td_topology only when you need wiring.

Read-only: bounded bridge-side search for live TouchDesigner parameters by node, operator type/family, parameter name, evaluated value, expression, mode, or non-default state. Values are point-in-time snapshots; likely secrets are redacted and cannot satisfy value/expression filters. Inspect scan_truncated and count_complete before claiming project-wide completeness. Requires the current structured bridge route and never falls back to raw Python or a full parameter dump.

Read-only: bounded BM25-style lexical search across authored DAT text and parameter expressions in the live TouchDesigner project. Returns short redacted excerpts with exact operator, source field, line, column, ranking provenance, and truthful completeness metadata. Works with TDMCP_BRIDGE_ALLOW_EXEC=0; never falls back to raw Python, exports whole DATs, or requires an embedding service.

Read-only: collect errors and warnings across a network and cluster them by message, severity type, or parent container, with the nodes that have the most diagnostics and a suggested order to investigate. Returns {total, error_count, warning_count, groups[], suggestions[]}; each group sample retains its error/warning severity. Use this for network-wide triage instead of reading every node's diagnostics one by one; use get_td_node_errors when you want the raw list for one node or sub-tree.

Read-only: diff the parameters of two nodes, returning only the values that differ (by default). Returns {type_match, differing_count, differing[], same_count}. Useful for aligning settings across similar operators; compares two live nodes, whereas diff_snapshots compares two whole-network snapshots over time.

Read-only: capture a compact, serializable snapshot of a network — nodes, connections, structural issues, and optionally each node's parameters — for review, diffing, or documentation. Returns {nodeCount, connectionCount, issues[], nodes[], connections[]}. Set `compact` for a token-cheap whole-COMP read that hoists per-type default parameters and stores only each node's deltas. Feed two of these snapshots to diff_snapshots to see exactly what changed across an edit.

Hot-reload the bridge's Python inside the running TouchDesigner, so edits to the td/ modules take effect without reopening the project. Reimports every loaded mcp.*/utils.* module in place and returns the list reloaded. Use after editing bridge code.

Search the embedded operator knowledge base (629 operators) by keyword, exact name, tag/keyword, category, subcategory, parameter metadata, or TouchDesigner version compatibility — ranked by relevance, fully offline by default. Use it to discover the right operator before creating nodes instead of guessing a type (e.g. 'what sends DMX?', 'particle', 'corner pin'). Returns name, family, summary, facets and optional matching parameters. Pass semantic:true to re-rank fuzzy candidates by embedding similarity (needs an LLM endpoint; falls back to keyword). With parameter_search, matched Menu parameters include their menu options; results are stamped with a data_version (which TouchDesigner build the offline catalog reflects) and a stale_hint when the connected TD is on a different major. Token economy: use a specific query and a small `limit`; one focused search beats several broad ones.

Read-only: compare two TouchDesigner operator types from the embedded offline knowledge base, including overview metadata plus shared and unique documented parameters. This compares operator documentation, not live node settings; use compare_td_nodes for live node parameter diffs.

Read-only: return an embedded TouchDesigner operator workflow guide with common inputs, outputs, examples, next-operator suggestions, and snapshot provenance. When an operator is absent from the imported snapshot, returns candidate guide ids and an explicit snapshot caveat instead of claiming that the operator does not exist.

Read-only: suggest a small ordered TouchDesigner operator chain for a creative or technical goal from offline operator docs and workflow patterns. Returns connection hints and next tool hints; it does not create nodes.

Read-only: validate an ordered TouchDesigner operator chain against embedded operator docs, documented connections, family/category filters, and optional TouchDesigner version compatibility. It does not create or modify TD nodes.

Read-only: convert an ordered TouchDesigner operator chain into a RecipeSchema draft without writing files or touching the TD bridge.

Read-only: inspect embedded TouchDesigner technique packs and individual techniques, with optional code snippets and setup/workflow details.

Read-only: convert an embedded TouchDesigner technique with GLSL source into a RecipeSchema draft without writing files or touching the TD bridge.

Read-only: extract a conservative operator chain from an embedded TouchDesigner tutorial and draft a RecipeSchema JSON without writing files or touching the TD bridge.

Read-only: list embedded TouchDesigner tutorials, search tutorial metadata/content, or retrieve one by id/name. With include_content, the content is capped (~30K chars) and comes with a sections_available list; pass a `section` title to drill into just that part instead of pulling the whole document.

Read-only: search TouchDesigner Python API classes, methods and members from the embedded offline knowledge base. Supports class category filters and conservative stable-version compatibility filtering where compatibility metadata exists.

Read-only: plan a TouchDesigner stable-version migration from offline release highlights plus operator and Python API compatibility records. Returns upgrade boundaries, focused compatibility deltas, and an operator checklist without touching TouchDesigner.

Read-only: search the embedded TouchDesigner knowledge router across operators, operator workflows, examples, versions, compatibility notes, technique packs, TD classes, and experimental build notes. Returns normalized results with resource URIs and tool hints for deeper lookups.

Search, list, inspect, doctor, install, reconcile, and uninstall manifest-driven TouchDesigner community packages at explicit user or project scope. Reconciliation is dry-run-first, proves marker ownership, and uses Delete/Bypass/Keep consent before pruning a live package. A legacy uninstall with a live TD target now returns the safe reconciliation plan instead of deleting local state first. This tool never runs third-party scripts, pip installs, model downloads, or external app setup.

Document an EXISTING network: read its nodes and connections and return a readable map — counts by operator family and type, plus a Mermaid flowchart of the data flow you can paste into docs. Unlike plan_visual (which plans from a description), this describes what's actually in the project. Use it to explain or hand off a patch.

Compare two network snapshots (from snapshot_td_graph) and return a readable diff: which nodes were added or removed, which connections changed, and which parameters changed (with before/after values). Snapshot before an edit and after to see exactly what changed, or to version a patch over time. Pure analysis — touches nothing in TouchDesigner.

Scan a network for cook-time bottlenecks and report the slowest nodes with concrete suggestions. By default this is a read-only measurement; with apply=true it mutates flagged TOP resolutions by scale and returns the before/after sizes. Run get_td_performance when you only need metrics; use this tool when you want the bounded resolution change, and leave apply=false for a plan-only pass.

Save a TOP to an image file at its native, full resolution (PNG/JPG/EXR/TIFF by extension) — for exporting a finished frame, unlike get_preview which only transfers a small inline thumbnail. The file is written by TouchDesigner on the TD machine; pass an absolute path.

Record a TOP to a movie file (.mov/.mp4) via a Movie File Out TOP — for exporting a clip or a loop, where render_output only saves a single frame. start begins recording (pass file, fps); pass `seconds` to auto-stop after a fixed length, or call stop to finish (stop also cleans up the recorder node). The file is written by TouchDesigner on the TD machine. For individual numbered frames, use render_output per frame.

Start/stop a movie export with named VJ/editorial presets (HAP, HAP Alpha, ProRes 422/4444, NotchLC, MP4 review) while reusing record_movie's Movie File Out TOP recorder. This records a TOP to a file written by TouchDesigner and documents the expected codec/extension/fps for downstream playback tools.

Reconcile the operator knowledge base against the RUNNING TouchDesigner's ground-truth creatable-optype list (GET /api/optypes). Flags which documented operators are actually creatable in this build vs deprecated/unavailable, and (optionally) which live optypes the knowledge base doesn't yet document. Pass a single operator name to check just that one. Survives TDMCP_BRIDGE_ALLOW_EXEC=0.

Diagnose a network for cleanup: report likely-dead operators (zero wired outputs, unreferenced, not displayed), broken external-file dependencies (file parameters pointing at missing files), orphan COMPs, and a dependency map of which operators reference which. Read-only and conservative — every flagged item carries a human-readable reason. Complements plan_visual (which plans a build) and snapshot_td_graph (which dumps structure).

Produce a Markdown project document for any COMP or project: family/type counts, custom-parameter table, inputs/outputs, child inventory, external file dependencies, and an optional preview thumbnail of the output TOP. Use `include_mermaid` to add a Mermaid flowchart and `max_nodes` to cap large inventories. Returns the full Markdown on the structured channel under `markdown`.

Surgically replace a substring inside a Text or Table DAT's `.text`. Without `replace_all`, requires exactly one match — 0 or >1 occurrences is an error, forcing the caller to add context or set `replace_all`. Use `set_dat_content` to overwrite an entire DAT's text in place; use this to make a targeted edit. Because DAT text can become executable callbacks, this tool is hidden when TDMCP_RAW_PYTHON=off and the bridge also requires TDMCP_BRIDGE_ALLOW_EXEC=1 for writes.

Overwrite a Text or Table DAT's entire `.text` with new content. Unlike `edit_dat_content` (which makes a surgical find-and-replace), this replaces everything in one shot — use it to deploy a full script or template. Refuses to write empty/whitespace-only text unless `confirm_wipe:true` is passed, preventing silent data loss. Because DAT text can become executable callbacks, this tool is hidden when TDMCP_RAW_PYTHON=off and the bridge also requires TDMCP_BRIDGE_ALLOW_EXEC=1 for text writes.

Edit a GLSL/Text DAT and immediately run the practical shader feedback loop: write or surgically replace source text, inspect the shader/output node for errors, and optionally capture a compact inline preview. Uses set_dat_content/edit_dat_content under the hood so DAT write guardrails stay consistent, and requires TDMCP_RAW_PYTHON=on plus TDMCP_BRIDGE_ALLOW_EXEC=1.

Set one or more parameters on a node using five modes: 'expression' (par.expr = ...), 'bind' (par.bindExpr = ...), 'constant' (par.val = ...), 'reset' (restore the parameter default), and 'unbind' (freeze the current evaluated value as a constant). Caller-supplied expression/bind text requires TDMCP_RAW_PYTHON=on and TDMCP_BRIDGE_ALLOW_EXEC=1. In restricted mode, constant/reset/unbind use the structured endpoint and remain available on a current bridge. Multiple assignments are applied fail-forward — per-item failures accumulate as warnings so a partial batch still returns useful results.

Emit a project-local CLAUDE.md / AGENTS.md seeded with tdmcp operator conventions and TouchDesigner render-coordinate rules, so a future agent working on this project starts with the right mental model. A small dynamic header (project name, node count, top families) is prepended to a curated static body. Pass `output_dir` to also write the file to disk on the machine running TouchDesigner. The guide is always returned in the structured result.

Remove one or more input wires from a node in TouchDesigner. By default removes every incoming wire into to_path; narrow the scope with from_path (only wires from that upstream node) and/or to_input (only that input slot index). Returns the list of removed wires (input index + upstream node path), a probe of the Connector API attributes seen at runtime, and any per-wire warnings. Fatal only when to_path is not found — partial removals with per-wire warnings still succeed. The inverse of connect_nodes.

Read-only: report each node's operator flags (bypass / render / display / lock / allowCooking / clone) plus index-aware input wiring, network position, color and comment — the signals that explain a black/blank output that a parameter dump hides. Scan one node or a subtree (recursive); set only_problems to surface just the ops whose flags or cook errors would suppress output. Returns structuredContent for code to process.

Read-only: inspect a single operator's runtime telemetry — cook time, cook count, last-cook frame, resolution (TOPs), channel/sample counts (CHOPs), GPU memory usage, cook errors, and optional Info CHOP channels via include_info_chop. Complements get_td_performance (which aggregates cook times across a network) by providing deep per-op detail for the 'why is it black / why is it slow' diagnostic loop. Returns {path, type, family, cook_time_ms, cook_count, last_cook_frame, resolution, num_chans, num_samples, gpu_memory, info_chop?, errors[], warnings[], extra}. Attribute names are flagged UNVERIFIED and vary by TD build; the `extra` map records which attrs were actually present for live confirmation.

Read-only: sample one TouchDesigner operator over a short interval and return runtime state, readable parameter values, and CHOP channel values when available. Missing TD attributes/channels are reported as warnings instead of failing the watch. Returns {path, requested_samples, collected_samples, interval_ms, window_ms, warnings[], snapshots[]} where each snapshot has {sample_index, elapsed_ms, path, type, family, state, parameters, channels, warnings}.

Opt-in: subscribe to `param.changed` events for an operator's parameters. When a watched parameter's value changes in TouchDesigner (by a human or a script), the bridge broadcasts a {path, par, prev, value, frame} event on the TD event stream, forwarded to the MCP client as a logging notification. Use action='watch' to register (optionally scoped to named `parameters`), 'unwatch' to remove, and 'list' to see active watches. Events only arrive when the server's TD event stream is enabled (TDMCP_EVENTS); param.changed is treated as a high-frequency event (coalesced bridge-side so a slider drag can't flood). Survives TDMCP_BRIDGE_ALLOW_EXEC=0.

Read-only: collect recent cook errors and warnings from the running TouchDesigner project for debugging. Walks the operator tree under `scope` and gathers each operator's current cook errors and warnings (guaranteed). Also attempts a best-effort probe of textport/log DATs if they exist in the project. Use this when a script or cook fails and you need more context than the immediate error string — it surfaces the real Python traceback or operator cook errors without requiring a new REST endpoint. Returns {lines[], count, probe} where probe reports which log sources were reachable in this TD build.

Read-only: inspect what a COMP exposes — its Python storage dict (keys + values), its extension class descriptors (name, promoted flag, public members), and its custom-parameter definitions (page/name/style/default). Closes the inspect side of the reusable-component loop: use after `scaffold_extension` + `add_custom_parameters` to verify what was built, or call standalone to examine any COMP without resorting to raw Python. Returns structured data for agent code-path consumption. API names vary by TD build; the `probe` field records which attributes were reachable.

Read-only: serialize a COMP's immediate children into a git-diffable JSON spec — each node's name, op type, parameters (with mode + expression, not just the evaluated value), input wires by source node name, and position — plus best-effort custom-parameter definitions. This is the serialize half of a round-trip pair: feed the output spec to rebuild_network to reconstruct the subtree. Use it to snapshot a network as text you can diff across edits or commit to version control. Returns {root, nodes[], truncated?, warnings[]}.

Make a COMP self-contained: recursively scan its subtree for external file references (movie/image files, fonts, LUTs, externaltox links — reusing the collect_project_assets scan), COPY each existing asset into <out_dir>/assets/, rewrite each referencing parameter in the LIVE network to the copied relative path (assets/<file>), then save the COMP as a .tox beside its assets with a tdmcp-component manifest. The result is a folder you can move to another machine and open without broken links. Delta vs make_portable_tox (which saves the .tox only, leaving external assets behind) and collect_project_assets (which only reports refs). Rewriting mutates the live network — set rewrite_refs=false to copy-and-report without touching parameters.

Scan a COMP subtree for every external file dependency (movie/image file pars, fonts, LUTs, externaltox links) and report each referenced file, the node+parameter that references it, and whether the file currently exists on disk. The TouchDesigner scan is read-only and copies/rewrites nothing in the network; when out_manifest is set, this tool writes that local JSON path and may overwrite an existing manifest. File-par detection uses par.style ('File'/'Folder') when readable, falling back to a suffix/exact name heuristic (*file*, *fontfile*, *lut*, *externaltox*, *moviefile*, *imagefile*) — both UNVERIFIED across TD builds; `style_supported` records whether par.style was available.

Compose a one-folder handoff/portfolio documentation PACKAGE for a network: a README.md (title, node count, per-family summary, how-to-load note), a topology.md with a Mermaid graph of the connections, and - when include_thumbnails is set - preview PNGs of output TOPs under thumbs/ linked from gallery.md, all written into out_dir. Unlike generate_readme (a single file), this assembles a small multi-file site folder for sharing or archiving a project.

Read-only: render a TOP's preview and return a plain-text description of it — the headless 'is the output alive?' primitive. Two paths: (a) a configured vision LLM endpoint when available, (b) a DETERMINISTIC luma/colour-histogram fallback decoded from the preview PNG pixels (always works, no model needed). Reports dominant colours, mean luma, near-black fraction, a coarse classification ('black'/'very dark'/'dark'/'bright'/'colorful'/'mid'), and a friendly caption. Returns {node_path, width, height, source:'vision'|'histogram', caption, stats{...}, warnings}. Use it after a build to confirm the network is actually rendering instead of a black frame. The vision path is currently inert (no vision field on the tool context) and falls back to the histogram.

Bounded, autonomous repair: scan cook errors under a subtree, classify each, and plan a safe fix, capped at max_steps so it can never run away. Defaults to dry_run (PLAN only, no changes). Set dry_run:false to apply the known-safe fixes — resetting a broken parameter expression to constant mode, and re-enabling a bypassed/display-off op — within the same bound; risky cases (DAT syntax errors, missing inputs, unclassified errors) are always PLAN-only. Re-checks errors after applying and stops at the bound or when errors clear. Returns {parent_path, dry_run, max_steps, errors_before, errors_after, steps[], remaining[], warnings, rolled_back}. Use it as the diagnostic 'try the obvious safe fixes' loop after a build; for raw triage use summarize_td_errors / get_td_node_errors instead.

Offline semantic linter for recipes/*.json. Checks schema, id/filename match, duplicate node names, unknown operator types, dangling connections, bad parents, render-outside-geometryCOMP, missing parameter nodes, unresolved control bind_to, GLSL uniforms on non-GLSL hosts, and hygiene (tags/description/preview_description). Returns a structured report; never calls TouchDesigner.

Read-only: score a built network 0–100 on a fixed rubric (palette/motion/complexity/errors/perf) and return per-criterion sub-scores plus deterministic improvement suggestions. Optional LLM critique when llmCritique=true and ctx.llm is configured. Composes existing bridge endpoints — creates nothing.

Read-only: sample cook times over a window (N samples × intervalMs) and rank hotspot nodes by p95 cook time. Use this to diagnose intermittent stalls that a single get_td_performance snapshot misses. Returns {path, samples, intervalMs, targetFps, frameBudgetMs, windowMs, hotspots[], warnings[]}.

Drive the TouchDesigner project timeline: play, pause, seek to a frame, jump to a named cue, or set playback rate. Returns the timeline state after the action so a copilot can verify the change took effect. NOTE: pausing will freeze any downstream motion/feedback/frame-diff chain — expected behaviour, not a bug.

Read-only: returns the host GPU info (name, driver, VRAM), attached monitor topology (resolution, refresh rate, primary flag, position), and whether the project is in Perform Mode. Use to plan output mapping, dome rigs, and multi-display shows without leaving the chat. Offline-safe — returns { connected: false, reason } when TD is unreachable.

Read-only: check whether TouchDesigner is reachable, whether display/projector topology matches expectations, and whether generated sensor/helper status DATs such as source_status or bridge_status are healthy. This is a room/hardware preflight for physical installations; it returns PASS/WARNING/FAIL/UNVERIFIED checks without mutating the TD project.

CRUD operations on a COMP operator's .storage dictionary. Actions: list (all keys+values), get (one key), set (write a key), delete (remove a key). No operators are created; the target COMP must already exist.

Safely inspect, install, update, or uninstall the small bundled tdmcp skill catalog for Codex or Claude. Mutations default to dry-run, use exact manifest ownership, reject unowned conflicts and symlinks, and roll back partial filesystem changes. Only package-bundled skills are accepted; this is not a remote or arbitrary skill installer.

Use the schema + LLM to propose values for a tool call's missing required args.

Sample dominant colors from a TOP by capturing its preview PNG and running deterministic k-means on the decoded RGB pixels. Returns `{source_top, k, width, height, pixels_sampled, hex_colors[], swatches[{hex,rgb,weight}], warnings[]}` sorted by dominance (most-frequent cluster first). Feeds AI grading prompts, `create_palette`, and design hand-offs. Read-only; no nodes are created or modified.

Walk a SOP's primitives via the bridge and emit an SVG document of polylines (each primitive becomes one `<polyline>`). Projects to x/y (drops z), auto-fits viewBox, supports stroke/fill/scale/flip_y. Writes to disk when `output_path` is supplied and always returns the SVG string in the report. Pen-plotter / laser / print deliverable.

Change an operator's TYPE while preserving its name, position, incoming + outgoing wires, and any parameters that exist on the new type. Snapshots wires + params, deletes the old node, creates a new node of `new_type` at the same parent/name/x/y, re-applies matching params (others go into `dropped_parameters`), and rewires connectors. Fail-forward: per-wire / per-param failures are reported as `failed_inputs[]` / `failed_outputs[]` / `dropped_parameters[]` rather than aborting. Returns `{old_type, new_path, preserved_parameters, dropped_parameters, reconnected_inputs, reconnected_outputs, failed_inputs, failed_outputs, warnings}`.

Capture a TOP as a preview image and ask the configured multimodal LLM a question about it. Numeric-loopback endpoints need no extra opt-in; remote, client-managed, or unknown backends require `allow_remote_image_egress=true` for that frame. Returns redacted egress locality/transport and `calibration: not_checked`; this read-only tool is NOT the calibrated visual-mutation authority. Uses ctx.llm.complete() with an image part. Different from `caption_top`, which is deterministic-by-default.

Read-only one-shot inspection of a TOP: small base64 thumbnail (default 256² JPEG) + parent error sweep (BFS up `parent_depth` hops) + top-N changed-from-default parameters + cook stats. One call instead of chaining get_preview / get_td_node_errors / get_td_node_parameters when you just want to know 'is this op alive and healthy?'. Use get_preview/render_output for delivery-grade frames; this thumbnail is intentionally tiny + lossy.

Read-only: compress a TD subtree into a structured digest under max_tokens (default 500). Returns {header, nodeCount, connectionCount, primaryOutput, families{count,topTypes}, outputChain, errors{total,topGroups}, warnings, approxTokens}. Uses getNetworkTopology + getNetworkErrors — no new bridge work. Cheaper than get_td_topology / snapshot_td_graph for planning turns.

Read a Text or Table DAT with pagination so a large table cannot flood context. Returns total row/col counts, a header (table DATs), a sliced page (offset/limit), an optional stable head preview (preview_rows), and a `row_range` only on a partial read. Table DATs are split on tabs/newlines client-side — that split is lossy if a cell embeds a literal tab or newline (probe live before relying on it). Use edit_dat_content/set_dat_content to write.

Read-only: for each menu parameter of a node, live-fetch the menu option values (`menuNames` — the machine values you set with `par.val`), their human-readable UI labels (`menuLabels`), and the currently selected value (`current`). Use this before setting a Menu / StrMenu parameter so you pick a valid option instead of guessing. Values come straight from the running TouchDesigner build, so they are authoritative and even include dynamically-populated menus (device lists, file menus) — an empty `menuNames` on a known-menu parameter means the menu has not populated yet (the node has not cooked / the device is not enumerated), not that there is no menu. Requires TDMCP_BRIDGE_ALLOW_EXEC=1; when raw exec is unavailable it falls back to the bundled catalog and attaches a stale-catalog warning.

Safely follow one same-parent operator group in an existing TouchDesigner Network Editor. Reuses the active/already-owning pane, replaces stale selection, sets an explicit current operator, and returns applied or fail-closed suppression readback. UI-only: it never creates panes or changes project topology, and Perform/headless/disabled states do not steal focus. Smooth colour highlights remain held pending live compare-and-swap proof.

Atomically insert one same-family operator on one deterministic downstream edge of the exactly selected/current TouchDesigner operator. Requires an exact editor-context compare-and-swap and an idempotency key; returns bounded before/after connector receipts, explicit non-overlapping placement and rollback state. Fan-out siblings and sibling inputs are preserved. Uses the authenticated structured bridge with ALLOW_EXEC=0; it never invokes raw Python, mouse-interactive placeOPs, or implicit pane selection.

Create multiple nodes and (optionally) connect them in sequence. Returns all created paths; on failure it stops and reports partial progress without deleting anything.

Wire one node's output connector into another node's input connector inside TouchDesigner, creating a single link between two existing nodes. Uses the bridge's batch endpoint when available and falls back to a Python connect otherwise. Use create_node_chain instead when you are creating several new nodes and want them auto-wired in sequence. Returns the source and target paths, the connector indices used, and which method made the connection.

Create a GLSL TOP under parent_path that renders a custom fragment shader (and optional vertex shader). Caller shader source requires TDMCP_RAW_PYTHON=on and TDMCP_BRIDGE_ALLOW_EXEC=1. The shader source is placed in companion Text DATs (`<name>_frag` and, if given, `<name>_vert`) and wired to the GLSL TOP's pixel/vertex parameters; numeric uniforms are best-effort bound on the Vectors page and the output resolution is set. Returns the GLSL TOP path, the fragment/vertex DAT paths, and any warnings (e.g. sampler2D uniforms or uniform binds that need manual wiring).

Create one DAT under parent_path preloaded with your Python `code`. `dat_type` chooses a Text DAT (plain code), an Execute DAT (event hooks like onFrameStart), or a Script DAT (table builder); for a Script DAT the code is written to its auto-created companion callbacks DAT, since the Script DAT's own text is read-only. Returns the created DAT's path. This only stores code as a node; use execute_python_script instead to run Python immediately against the live project.

Update parameters on multiple nodes in a single batch request. Each update reports its own success; a failure does not roll back the others.

Create one empty COMP under parent_path to hold a visual system, then tile it into the parent's network grid clear of existing siblings. `comp_type` picks a Container COMP (a 2D panel) or a generic Base COMP. Returns the created node's path, type, and name. Use a higher-level Layer 1 tool instead when you want a fully built, wired network rather than an empty shell.

Expose live controls on a COMP: append custom parameters (sliders, toggles, menus, RGB, pulse) and bind them to node parameters so the artist can drive a generated system in real time. Point `comp_path` at a system container and list the controls; use each control's `bind_to` to wire it to one or more 'nodePath.parName' targets.

Generate a performable control panel from an existing node/COMP's primitive parameters. It reads source_path, infers sliders/toggles/text fields, appends them as custom parameters on comp_path (default source_path), and optionally binds each control back to the source parameter. Use when a generated component has useful parameters but no playable UI yet.

Build a companion performance surface for an existing node/COMP: infer useful primitive parameters, add bound custom parameters, create a playable fader/cue panel, and optionally append a read-only preflight report. Use after generating a component that needs a human-facing control surface without hand-wiring every parameter.

Build a playable performance panel (a Container COMP of visual widgets) for live use, beyond the parameter dialog: vertical faders that drive parameters, and buttons that recall or morph to named cues (from manage_cue). Open the container in Perform/Panel mode for a touchable surface — faders move their parameters, cue buttons fire scenes (instantly or with a crossfade).

Drive one or more node parameters over time with an LFO (sine/triangle/ramp/square/pulse/random). Creates an LFO CHOP and binds each target so it oscillates between min and max with the given period — movement without manual keyframing.

Drive one or more node parameters from a CHOP channel by expression — the link that makes a visual react. Point it at an audio_features channel (bass/mid/treble/level) or a tempo_sync channel (ramp/pulse/beat) with a scale and offset, and each target parameter tracks that signal live. This is how you wire extract_audio_features / create_tempo_sync into a visual system. Optionally add attack/release smoothing (in seconds) — or a single `smooth` time — to insert a Lag CHOP between the channel and the parameter so reactivity follows a clean envelope instead of flickering on raw audio (e.g. a fast attack + slow release for a punchy hit that decays smoothly).

Store, recall, list, or delete named snapshots of a COMP's parameter values — the live-performance preset system. Pair with create_control_panel: snapshot the knob positions and jump between looks. Snapshots are saved in the COMP's storage so they persist with the project.

Store / restore / list / delete a full snapshot of a sub-network — an 'undo point' to take before risky live edits. A checkpoint captures every node's constant parameters, the wiring, and node positions. Restoring reapplies parameters, recreates nodes that were deleted since (with their wiring), and prunes nodes that were created since. Unlike manage_presets (custom-parameter looks for performance), this captures the whole network for safe experimentation.

Live-performance scene system: store / recall / morph / list / delete named cues (snapshots of a COMP's custom-parameter values). Unlike manage_presets, a cue can be reached with a timed `morph` that crossfades every numeric control from the current look to the cue over N seconds (eased), via a small Execute DAT — so you can glide between looks on stage instead of hard-cutting. Recall and morph also take an optional `quantize` ('beat'/'bar') that defers the change to the next musical boundary (from the project tempo) so scene changes land on the downbeat. Build cues with create_control_panel, then jump or morph between them.

Build a reusable component library by moving COMPs to/from .tox files on disk. 'save' uses a deferred, verified same-directory temporary export and refuses overwrite by default; set overwrite_policy='ask' for native Overwrite/Keep consent. 'load' keeps its legacy behavior and reads file_path into parent_path. Paths are on the machine running TouchDesigner.

Transactionally add, edit, delete, sort, and organize a COMP's custom parameters through an authenticated structured TouchDesigner route. Legacy page+params calls remain valid. Supports Float, Int, Toggle, Str, Menu, Pulse, Header, OP, TOP, File, Folder, XYZW, RGBA, RGB, and XYZ; EXPRESSION and BIND are reversible and require TDMCP_RAW_PYTHON=on plus TDMCP_BRIDGE_ALLOW_EXEC=1 because their source is caller-supplied code. Constant and page-lifecycle operations remain available in restricted mode. EXPORT is explicitly HELD and returns an error without mutation. Built-ins are protected and failures roll back to the exact prior custom-page snapshot.

Give a COMP a Python extension class: create a Text DAT holding the class (with optional method stubs), wire it into an extension slot, optionally promote it (so members are callable directly on the COMP), and reinitialize. The other half of making a generated network reusable — pair with `add_custom_parameters` (knobs) and `manage_component` (save as .tox).

Add one macro knob (a 0–1 custom parameter) to a COMP that drives many parameters at once, each remapped into its own [min,max] range with an optional response curve — a one-to-many control for sweeping a whole look from a single fader. Targets are bound by expression so they track the macro live.

Randomize a COMP's numeric custom parameters within their slider ranges — an instant new variation for live improvisation. `amount` blends toward random (1 = fully random, low values nudge the current look). Non-numeric controls (toggles, menus) are left untouched, so it is always safe to fire. Pair with manage_presets/manage_cue to snapshot a happy accident.

Serve a mobile-friendly web panel from a Web Server DAT so you can control a COMP's numeric custom parameters from a phone — just open the URL, no app to install. Each parameter becomes a touch slider that writes back live. SECURITY: like the bridge, this listens on all interfaces and accepts writes with no auth, so use it only on a trusted network. Pair with create_control_panel (the params to expose) and manage_cue (snapshot looks you dial in from the phone).

Bridge TouchDesigner to the outside world: OSC/MIDI input (a control surface — bind incoming channels straight to parameters), OSC/MIDI output (send a CHOP's channels back out for bidirectional feedback to lighting desks, other apps or hardware — pass source_path), DMX/Art-Net output for lighting (dmx_out for any DMX desk; artnet_out for network Art-Net/sACN pixel-mapping of LED strips & stage fixtures), RTMP output to live-stream a TOP to Twitch/YouTube/OBS (rtmp_out — NVIDIA GPU on Windows only), or NDI / Syphon-Spout video input. To discover which channel a control sends (a 'MIDI learn'), wiggle it and read the input CHOP with get_td_nodes, then bind_to that channel. Validate live where possible, but real signal needs the hardware/sender present.

Build an OSC Companion-style button surface inside TouchDesigner: an OSC In CHOP listens for button addresses, each button gets a Select CHOP and Null CHOP row, optional target parameters are expression-bound, and an OSC Out CHOP is configured for feedback. A mapping table records label/address/target/mode/feedback for later editing.

Create a TouchDesigner-side OBS control scaffold with obs-websocket v5 request templates, status/setup DATs, and optional NDI or Syphon/Spout TOP publishing for OBS capture. The optional OBS password is passed only to the bridge payload and is redacted from all returned reports.

Create a TouchOSC-oriented OSC mapping surface and JSON manifest DAT. This intentionally does not claim to generate TouchOSC .tosc documents.

Create a dry-run/approval-gated voice-to-prompt TouchDesigner scaffold for AI Party-style workflows. It never dispatches raw hardware effects; policy and operator approval remain authoritative.

Create a TouchEngine/Notch bridge scaffold with stable output TOP, control channels, NDI/Syphon fallback modes, and explicit licensing/runtime warnings.

Create a Resolume Arena/Avenue OSC control scaffold with command maps, status DATs, and preview handoff notes. Runtime validation against Resolume remains explicit.

Create a MadMapper OSC surface/media control scaffold with source handoff notes for Syphon/Spout or NDI.

Create a generic OptiTrack/Rokoko/Axis Studio/VRPN-style mocap bus scaffold with joint and rigid-body mapping surfaces.

Create a Blender-to-TouchDesigner scene handoff scaffold for file-watch, OSC, or WebSocket metadata workflows.

Create an Unreal Engine Live Link/OSC/NDI handoff scaffold with subject maps, event queue, and runtime setup warnings.

Create a VCV Rack OSC/MIDI/CV modulation bridge scaffold with channel mapping and setup notes.

Create a QLab OSC cue-stack scaffold with cue command maps, status, and rehearsal-focused setup notes.

Create a safety-gated OSC command scaffold for grandMA3, ETC Eos, ChamSys, Avolites, or generic lighting consoles without sending direct DMX.

Create a Max/MSP OSC bridge scaffold with parameter and audio-feature channel maps.

Create an OpenXR/SteamVR controller input scaffold for pose, trigger, grip, thumbstick, and button streams supplied by an external adapter.

Create a vMix HTTP/API production-control scaffold for input switching, overlays, recording, and streaming command templates.

Create a CasparCG AMCP/playout scaffold with channel/layer command templates and media manifest notes.

Create a Millumin OSC layer, column, and dashboard control scaffold with command maps and setup notes.

Create an Isadora OSC actor, watcher, and scene exchange scaffold with stable namespace mapping.

Create a Unity OSC and preview handoff scaffold for object transforms, events, and NDI/Syphon notes.

Create a REAPER OSC transport, track, and marker bridge scaffold with operator-approved recording templates.

Create a stable NDI source/output routing matrix scaffold without claiming live NDI discovery.

Create a browser/WebRTC input scaffold for webcam, screen, pointer, and sensor data supplied by an external signaling app.

Create a platform-gated Syphon/Spout texture-sharing router scaffold with route maps and explicit setup notes.

Create a Blackmagic ATEM command-map scaffold with UDP transport placeholders, input maps, macro maps, and operator approval notes.

Create an OSCQuery HTTP namespace and OSC send/receive scaffold with action maps for live-control apps.

Create an MQTT Client DAT bus scaffold for IoT sensors, installation telemetry, and policy-gated operator commands.

Create a DepthAI/OAK camera scaffold with OAK Device, OAK Select TOP/CHOP placeholders, stream maps, and hardware-gated setup notes.

Create an ARKit Face Capture OSC scaffold with blendshape and head-transform maps for iPhone-driven facial performance.

Create a safety-gated Pangolin Beyond laser-control scaffold with zone maps, cue maps, blackout notes, and no live-output claim.

Create a Hokuyo LiDAR scanner scaffold with hardware-gated CHOP setup, scan-zone maps, and calibration notes.

Create a SuperCollider OSC synth/bus bridge scaffold with explicit port maps and no code-evaluation behavior.

Create an Ableton Link timing scaffold with beat/bar maps for tempo-locked visual systems.

Create a Blackmagic DeckLink video-device input/output router scaffold with route maps and hardware-gated safety notes.

Create an expressive MIDI MPE input/output scaffold with zone and expression maps for pressure, timbre, pitch bend, and note channels.

Create a TidalCycles/SuperDirt OSC scaffold with pattern and orbit maps for live-coded audiovisual sets.

Create a VDMX OSC/Syphon workspace scaffold with layer, clip, preview, and setup maps.

Create a disguise/d3 HTTP and OSC show-control scaffold with timeline, layer, and approval maps.

Create an Azure Kinect body/depth scaffold with Kinect Azure TOP/CHOP placeholders, stream maps, and calibration notes.

Create a ZED camera depth/body/point-cloud scaffold with ZED TOP/CHOP/SOP placeholders and runtime-gated warnings.

Create a Leap Motion hand/gesture scaffold with CHOP/TOP placeholders, hand maps, gesture maps, and setup notes.

Create a BlackTrax tracking scaffold with receiver, trackable maps, zone maps, and calibration notes.

Create an NCAM camera-tracking scaffold with pose, lens, video-preview, and calibration maps.

Create an Ouster LiDAR scaffold with Ouster TOP, range selection, zone maps, and calibration notes.

Create a TUIO touch-surface scaffold with TUIO DAT, optional raw OSC, cursor maps, and surface maps.

Create a Windows Multi Touch In DAT scaffold with panel maps, touch-slot maps, and platform notes.

Create an LTC receive/generate scaffold with LTC In/Out CHOP placeholders, cue maps, and routing notes.

Create an OptiTrack/NatNet tracking scaffold with receiver, rigid-body maps, marker maps, and calibration notes.

Create a Video Stream In TOP scaffold for RTSP, HLS, SRT, or WebRTC ingest with stream maps and setup notes.

Create a WebSocket DAT scaffold with command maps, message schema hints, status, and safety notes.

Create a Serial DAT/CHOP scaffold for microcontrollers, sensors, and show-control devices with parse maps.

Create a UDP In/Out DAT scaffold for telemetry packets, replies, status maps, and diagnostics.

Create an Art-Net DAT discovery scaffold with optional DMX In monitor, device maps, and universe maps.

Create an MPCDI projection-calibration scaffold with MPCDI TOP/DAT, projector maps, region maps, and setup notes.

Create a VIOSO projection-warp scaffold with VIOSO TOP, blend-zone maps, projector metadata, and setup notes.

Create a Direct Display Out TOP scaffold with monitor inventory, display maps, and inactive-by-default safety notes.

Create a Scalable Display TOP scaffold with display tile maps, status, and calibration setup notes.

Create a Window COMP output matrix scaffold with window maps, source maps, status, and setup notes.

Create a Monitors DAT inventory scaffold with monitor maps, GPU maps, preflight checks, and setup notes.

Create an Intel RealSense depth-camera scaffold with RealSense TOP, NDI, WebSocket adapter, or sample-source modes plus depth/color/point-cloud routing notes.

Create a Livox LiDAR adapter scaffold with UDP/WebSocket/file-replay ingest, point-stream schema, zone maps, and calibration notes.

Create an Xsens MVN mocap scaffold with OSC/UDP/TCP ingest, actor/segment mapping, normalized skeleton tables, and coordinate-space notes.

Create a Houdini Engine/HDA/cache handoff scaffold with HDA manifests, parameter maps, cook-status ingest, and geometry cache notes.

Create an NVIDIA Omniverse/USD stage sync scaffold with Nucleus/stage metadata, layer maps, variant maps, and live-session notes.

Create an OPC UA industrial telemetry scaffold with node maps, adapter ingest options, status tables, and read-only safety-policy notes.

Create a Replicate-style prediction handoff scaffold with request templates, polling/webhook maps, output contracts, and credential-safety notes.

Create an AUTOMATIC1111/Forge Stable Diffusion WebUI handoff scaffold with prompt slots, result maps, ControlNet hints, and adapter notes.

Create a Hugging Face Inference Endpoint scaffold with task input maps, output contracts, token-env hints, and adapter notes.

Create a Whisper-compatible transcription scaffold with audio/file/chunk ingest, segment maps, status tables, and privacy notes.

Create an RVC-style voice conversion scaffold with source audio, model maps, output contracts, latency notes, and consent warnings.

Create a Runway-style video generation handoff scaffold with prompt maps, input/result contracts, polling status, and adapter notes.

Create a Kafka/Redpanda event-bus scaffold with adapter ingest, topic maps, schema hints, consumer group metadata, and policy-gated producer notes.

Create a Redis Pub/Sub/Streams scaffold with adapter ingest, channel maps, keyspace safety notes, and read-first operations policy.

Create an InfluxDB telemetry scaffold with measurement maps, field maps, query/write adapter notes, and token-safety warnings.

Create a Prometheus metrics scaffold with PromQL/client adapter notes, metric maps, alert routes, and operator-dashboard safety guidance.

Create a Grafana annotation/event-marker scaffold with dashboard, panel, tag, and annotation maps plus token-safety notes.

Create a Home Assistant state/service scaffold with REST/WebSocket adapter nodes, entity maps, service maps, and physical-action safety notes.

Create a Google Sheets cue-table scaffold with source adapter, cue rows, column validation, sync policy, and OAuth/writeback safety notes.

Create an Airtable content scaffold with record maps, field maps, sync policy, adapter source, and token/rate-limit safety notes.

Create a Notion show-rundown scaffold with scene maps, property maps, approval policy, adapter source, and token-safety notes.

Create a Figma design-token scaffold with token rows, component-review rows, style preview metadata, adapter source, and access-token safety notes.

Create a Slack operator-alert scaffold with webhook/socket adapter, alert rows, approval-gated command rows, and token/signing safety notes.

Create an S3-compatible media-bucket scaffold with manifest rows, cache policy, ingest status, adapter source, and credential/signing safety notes.

Create a venue calendar scaffold with event rows, reminder maps, blackout windows, adapter source, and credential/privacy safety notes.

Create a ticketing/check-in scaffold with aggregate gate counts, ticket-tier maps, gate status, adapter source, and PII/token safety notes.

Create a POS aggregate-telemetry scaffold with sales metrics, revenue buckets, privacy policy, adapter source, and PCI/PII safety notes.

Create a weather forecast/station scaffold with forecast rows, sensor maps, alert maps, adapter source, and safety-policy notes.

Create a GTFS static/realtime transit scaffold with route maps, stop maps, arrival predictions, adapter source, and public-data notes.

Create a parking/queue occupancy scaffold with zone occupancy, sensor maps, signage policy, adapter source, and privacy safety notes.