Analyze pixel data of a TOP node without transferring full image data.

Runs server-side numpy analysis inside TouchDesigner and returns statistical results per requested mode. Supported modes:

• histogram: per-channel (RGB) pixel value histograms

• luminance: mean, min, max, std, p5, p95 of perceived luminance

• alpha_coverage: alpha channel statistics (requires RGBA TOP)

• color_dominant: most frequent quantized color in the frame

• roi_diff: pixel-level diff between a region and a reference TOP

For roi_diff, also pass roi=[x, y, w, h] and reference_path.

Read-only project audit. Pair with td_brain_plan for new build/debug requests that need plan-aware changes afterward.

DEFAULT apply path for a BrainPlan: use this when you already have a BrainPlan from td_brain_plan (or a draft from td_brain_propose) and need TDPilot to apply it transactionally with validation, rollback, and optional local learning. Prefer the lower-level td_transaction_apply only when you hold a ready PatchPlan/BrainPlan and want to drive raw transaction controls yourself (no grounding, no learning). Do not use the legacy td_plan_patch / td_patch_* pipeline for new builds.

Use this when the request is artistic, multi-domain, spatial, or implicit-architecture requests, and whenever td_brain_plan returns blocked: it returns a read-only grounding pack (task features, corpus evidence, candidate operators, parameter contracts, operator availability, live state, exemplars, and the draft authoring contract) so you can write a draft for td_brain_propose. Do not use it for trivial single-node edits.

Use this when a request is pattern-shaped with an exact validated topology or technique composition. It returns a non-mutating concept graph, typed patch plan, and server-derived intent coverage; execute only when coverage is complete. For artistic, multi-domain, spatial, camera/depth/fog, or implicit-architecture requests, start directly with td_brain_ground → td_brain_propose.

Use this when you have authored a draft candidate graph from a td_brain_ground grounding pack and need TDPilot to validate it into an executable BrainPlan. It is read-only and never mutates TouchDesigner: accepted drafts are compiled, gated by parameter semantics, and cached server-side so td_brain_execute(plan_id=...) can run them immediately; rejected drafts return machine-readable rejections to fix and retry.

Capture a TOP frame together with cooking + error state, plus optional AI analysis.

Use this when you want one call that folds the screenshot together with cooking info and node errors (and, if sampling is supported, an AI read of the frame). Prefer td_screenshot for a bare inline frame; prefer td_capture_frame for a metadata-first capture without the extra cooking/error probes.

Capture a single frame from a TOP node, metadata-first.

Returns resolution, format, and byte size; the base64 image comes back only when confirm=True or save_path is set (behind that gate, so token cost stays near-zero by default). If save_path is set the frame is written to disk TD-side and only metadata + the saved path come back — the cheap visual-verify loop. Ask the user before setting confirm=True because image payloads consume significant model context tokens. Prefer td_screenshot for a quick inline thumbnail; prefer td_capture_and_analyze when you also want cooking state and errors folded into the same call.

Read CHOP channel data (values/samples).

Clear parameter bounds for specific paths, or all bounds if paths is None.

Use this when you already have BrainPlan or transaction data and want to render the optional local cockpit UI. This is read-only presentation; call td_brain_plan or td_brain_execute first for authoritative data.

Inspect the color management pipeline in TouchDesigner: color space, gamma, display settings.

Per-COMP markdown notes — what this subnet does, why it's wired this way, gotchas, TODOs. External JSON storage by default; embed=True also writes a hidden Text DAT inside the COMP for portability.

Audit or fix COMP standardization: required custom parameters (Version, Help, Creator), extension, naming.

Connect two nodes (source output → target input).

Get cooking/performance info for a subtree.

Copy/duplicate an existing node (with its parameters) to a new node.

Instantiate a legacy scaffold; feedback/audio macros are not complete visuals.

Create a new TouchDesigner operator of a given type under a parent path.

Create or update a custom parameter page on a COMP.

Delete a node by its absolute path.

v1.4.6 Bug A PoC: explicit-args signature instead of the old params: DeleteNodeInput wrapper. MCPServer wraps params: Model signatures under a params: {"$ref": ...} property that MCP clients collapse to an opaque {}. Explicit args produce a flat schema the client can render directly — callers see path as a required string with description and min_length instead of having to guess. The Annotated[str, Field(...)] pattern carries the same validation the old Pydantic model had.

Asynchronous temporal dynamics observation (frame, cooking, events).

Describe the MCP server surface: tool count, resource count, capabilities, version.

Detect instability signals: FPS, heavy cookers, critical errors.

Diff two snapshots, or a snapshot against live state.

Disconnect a node's input or output connector.

Emergency stabilization: pause timeline, clamp safety, capture baseline snapshot.

Execute Python code inside TouchDesigner.

Suggest better official alternatives for a given intent, with gotcha warnings.

Search for official examples and snippets matching a query.

Read SOP/POP geometry data (points/prims).

Recent tool-call activity from this MCP server's ring buffer.

Returns a JSON array of entries newest-first, each with ts, tool, args_summary, result_summary, duration_ms, ok. The buffer holds the most recent 200 calls; older entries are evicted.

Pairs with the in-TD activity_log Table DAT mirror so the same data is also wireable into a live visual patch.

Check if an operator type is compatible with a specific build.

Detect MCP client capabilities plus server/component versions and runtime config. Returns a JSON envelope.

Get upstream/downstream connections for a node.

Read the text or table content of a DAT node.

Get errors + warnings for a node (optionally recursive).

Read recent runtime event history from the server-side event buffer.

Return where the user currently is in TouchDesigner: active network pane, selection, project metadata, timeline state. Reduces the cold-start tax of needing to ask the user 'what path are you working in?' before every patch.

Return concise, source-cited hints for a topic, op_type, or intent.

Sources include hint packs shipped under src/td_mcp/hints/packs/ (skill pitfalls, canonical recipes), with future expansion to live knowledge-store essays. Every hint cites its source.

The response shape:

{
  "topic": ...,
  "op_type": ...,
  "confidence": 0.87,
  "hints": [
    {"id": ..., "priority": "critical|useful|context", "rule": ...,
     "source": "tdpilot-core §11", "source_kind": "skill_pitfall"},
    ...
  ],
  "next_tools": ["td_get_param_help", "td_screenshot"],
  "hint_pack_version": "v1.6.0-1",
  "available_topics": [...],
  "available_op_types": [...]
}

Get TouchDesigner project info: version, build, project name, OS. Returns a JSON envelope.

Inspect parameters plus truthful capability, I/O, limitations, and completion status.

Get detailed info about a node (type, errors, warnings, parameters).

The parameters dict is capped at param_limit entries (default 50, hard ceiling 200) — full COMP serialization can blow past 80 KB. Use td_get_params with name/page filters when you need the rest.

When include_notes=True, any markdown note saved via td_component_notes for this path is attached as a note field.

List the child operators (nodes) directly under a network path.

Get full documentation card for an operator type or a specific node.

Get help for a specific parameter: live metadata + knowledge card entry + current value.

Get parameter values and metadata for a node.

Get full documentation for a POPx operator (e.g. 'Particle SIM', 'Shape Falloff').

Get release notes for a specific build (default: current).

Get MCP server runtime metrics: telemetry, events, streams, safety, snapshots, jobs. Returns a JSON envelope.

Aggregated scene state vector (cached for _tr.TD_STATE_VECTOR_TTL seconds).

Read beat/phrase-derived timeline state (bars, beats, phrase position).

Fetch the full markdown body + metadata for one entry.

List free-form markdown knowledge-entry summaries, newest first.

Prefer td_memory_list for the structured, replayable technique library.

Search the free-form markdown knowledge store. Returns summaries (no bodies).

Use this for prose reference content — notes, essays, prose-with-math saved via td_knowledge_save. Use td_knowledge_get afterward to fetch a specific entry's body. Prefer td_memory_recall when you want the structured, replayable technique-recipe library (learned via td_memory_learn, rebuilt with td_memory_replay) rather than free-form notes.

Persist a free-form markdown knowledge entry (prose/notes/essays).

Returns the entry id. The body is stored at ~/.tdpilot/knowledge//entries/.md and the metadata in index.json. Local-only, never pushed anywhere. Prefer td_memory_save (with td_memory_learn) when you want to capture a structured, replayable technique recipe rather than free-form prose.

List available operator families (TOP, CHOP, SOP, DAT, COMP, MAT, POP). Returns a JSON envelope.

List all available macro templates (built-in plus user templates). Returns a JSON envelope.

List saved scene snapshots (newest first).

Save, list, jump-to, rename, or delete named network locations per project. Storage is host-side JSON in ~/.tdpilot/locations/<hash>.json and survives session restarts. Pairs with td_get_focus to give the agent

• user a shared spatial vocabulary for big projects.

Inspect the Python logging configuration inside TouchDesigner: log level, handlers, registered loggers.

Note: This inspects Python's logging module, not TD's native logging. Requires 'full' exec mode.

Look up a palette component by name or search by query.

Search for OP Snippets by keyword and optional family.

Export the technique library as a portable JSON object for sharing or backup.

Mark a technique as favorite and/or rate it (0-5).

Import techniques from an exported library (from td_memory_export).

Analyze a network subtree and extract a reusable technique recipe.

Auto-detects complexity:

• small (<10 nodes): full recipe with all params and expressions

• medium (10-20): full recipe

• large (>20): structure summary + key params only

Returns the technique dict — pass it to td_memory_save to persist.

List saved (structured, replayable) techniques, filterable by scope, tags, and favorites.

Prefer td_knowledge_list for the free-form markdown notes/essays store.

Get, set, list, or delete user preferences.

Preferences store things like: preferred color palettes, default resolutions, favorite operator types, naming conventions, etc.

Copy a project technique to the global library so it's available across all projects.

Search the structured, replayable technique library by text query and/or tags.

Returns summaries (not full recipes). Use td_memory_replay to rebuild a found technique as live nodes. Prefer td_knowledge_recall when you want free-form markdown notes/essays (prose reference content) rather than replayable recipes.

Rebuild a saved technique in a new location in the TD project.

Creates nodes, sets parameters and expressions, wires connections. Only works for techniques with a full recipe (small/medium complexity).

Save a structured, replayable technique to the project or global library.

Use the output of td_memory_learn as the technique input, or construct a technique dict manually. Prefer td_knowledge_save when you want to capture free-form markdown prose/notes rather than a replayable network recipe.

Start periodic monitor for a TOP.

Default mode omits base64 frames to keep token usage low.

Autonomous visual goal optimization via bounded parameter search.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Destructive compatibility/expert PatchPlan executor. Prefer td_brain_execute for BrainPlans because it is the default validated transaction path for TDPilot-authored builds.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Compatibility/expert surface for typed PatchPlan construction. For new concept-to-network TouchDesigner builds, prefer td_brain_plan followed by td_brain_execute.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Read-only PatchPlan preview for compatibility/expert workflows. For new visual builds, prefer td_brain_plan because it carries concept, corpus, and validation context.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Read-only validation for patch compatibility workflows. BrainPlan workflows should use td_brain_plan and td_brain_execute so validation is tied to the authored plan.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Generate PatchPlan variants for compatibility/expert workflows. For new creative builds, start with td_brain_plan so variants remain grounded in a BrainPlan.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Legacy compatibility planner returning the pre-v1.5 patch dict shape. For new concept-to-network TouchDesigner work, prefer td_brain_plan followed by td_brain_execute.

Read structured POP metadata and attribute samples.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Read-only validation for legacy td_plan_patch dicts. For new TDPilot-authored builds, use the BrainPlan path: td_brain_plan then td_brain_execute.

Save/load/undo/redo project lifecycle operations.

Pulse a pulse-type parameter (e.g. a button par).

List available Python classes in the TD runtime. Returns a JSON envelope.

Inspect the Python environment inside TouchDesigner: version, installed packages, env manager status.

Requires 'full' exec mode — uses sys and pkg_resources which are not in the standard allowlist.

Get Python help documentation for a TD class/module.

Recommend official palette or built-in operator components for a given goal.

Rename a node to a new name within its parent network.

Restore parameter values from a previously saved snapshot.

This tool replays the parameter values captured in the snapshot back onto the live TouchDesigner network. It restores parameter values only — it does not add, remove, or rewire nodes. For structural rollback (topology changes such as added/deleted nodes or connection changes) use TouchDesigner's native Ctrl+Z undo stack instead.

Use dry_run=True to preview what would be changed without applying anything. Supply partial with a list of node paths to limit the restore to a subset of the snapshot.

Capture a TOP frame as base64 inline, or to disk via save_path.

Use this for a quick single-frame visual: with save_path set the image is written to disk TD-side and only metadata + the path come back — use this for repeated visual verification. Without it the response embeds base64 image data; ask the user before repeated base64 screenshots because each image can consume significant tokens in model context. Prefer td_capture_frame when you want metadata-first (resolution/format/bytes) with the image behind a confirm/save_path gate; prefer td_capture_and_analyze when you also need cooking state and errors folded into the same call.

Search nodes across a subtree.

Legacy scopes ('name'/'type'/'family'/'all') hit the existing TD-side /api/search endpoint. New v1.6.0 scopes ('dat_text', 'param_exprs') iterate via the /api/exec endpoint — no .tox rebuild required.

Search the knowledge corpus for operators, palette, releases, snippets, or articles.

Search POPx operator documentation — GPU particles, falloffs, simulations.

Check for and optionally install a newer TDPilot release from GitHub.

Default behavior (check_only=True) hits the GitHub releases API and returns {installed, latest, newer_available, release_url, asset_urls}. Set check_only=False to actually download and install — this writes to ~/.tdpilot/td_component/tdpilot.tox, the Claude Code plugin cache, and the repo working-tree (when running from a clone). On success returns md5 fingerprints for each install path so the caller can verify sync.

Releases v1.6.9 through v2.0.3 shipped without the tdpilot.tox asset; against those, check_only=False returns error_code="release_asset_missing" with remediation hints instead of installing. Releases after v2.0.3 attach the asset automatically (.github/workflows/release-assets.yml).

Network-only — does not touch TouchDesigner. Safe to run when TD is closed.

Write text or table content into a DAT node (overwrites existing).

Set parameter safety bounds with enforcement mode.

Set node parameters (static values or live expressions).

Parameter-semantics checks are advisory here by default (param_semantics_policy= 'warn'): findings are attached but the write proceeds, since some out-of-range values are legitimate in TD (e.g. extending a soft UI range). Use param_semantics_policy='block', or the brain/transaction path which gates automatically, when you want invalid bindings to stop the write.

Capture a scene snapshot (structure + params; optionally visual).

Stop a running visual-monitor job by its monitor id.

Stop a running continuous TOP stream by its stream id.

Start continuous TOP stream.

Default mode omits base64 frames to keep token usage low.

Subscribe to runtime TD events for a node.

Strict version/auth sync diagnostic without exposing secret material.

Report whether the local server, TD component, packages, and public surfaces are in sync.

Inspect TDResources available in the TouchDesigner installation: fonts, icons, defaults.

Inspect the threading status inside TouchDesigner: active threads, cook rate.

Requires 'full' exec mode — uses threading module which is not in the standard allowlist.

Read current timeline state: frame, seconds, FPS, playing. Returns a JSON envelope.

Control timeline playback: play/pause, jump to frame, set FPS.

Dispatch up to 8 tool calls in one model roundtrip.

Each sub-call's result is returned in a structured array — per-call failures don't abort siblings. Use this for read-only sweeps ("inspect 5 things at once") to save model-to-server-to-model latency.

Hard constraints:

• Maximum 8 sub-calls per invocation.

• Nested td_tool_batch calls are rejected per-sub-call (fork-bomb guard).

• Sub-calls execute sequentially (TD's Python API is not thread-safe).

Returns: {"ok": True, "count": int, "results": [ {"tool": str, "ok": bool, "result": dict|None, "error": str|None, "elapsed_ms": int}, ... ]}

``error`` is always ``str | None`` — dict errors from
``format_tool_error`` are normalised to their ``message`` field.

Low-level executor: use this when you already hold a ready PatchPlan or BrainPlan and want to drive raw preflight, snapshot, validation, dry-run, max-op, and rollback controls yourself. For the normal BrainPlan build flow prefer td_brain_execute, which wraps this layer and adds grounding-aware concept profiles and optional local learning. Do not use the legacy td_plan_patch / td_patch_* pipeline for new builds.

Remove a runtime-event subscription for a node path.

(Legacy — prefer td_brain_plan → td_brain_execute; slated for removal in v3.0.) Read-only recipe compatibility check. Use td_brain_plan for new grounded visual-programming requests that should become a BrainPlan.