td-atlas RU·EN Try it

Tool reference

Перевод английской документации от 15.09·English

Имена и описания в таблице стоят по-английски, как их видит агент.

Every td_ name here is an MCP tool the agent calls on the artist's behalf. A person at a terminal has a separate surface, td-atlas, with its own page.

41 MCP tools in three groups. tests/test_skill_reference.py compares every name, every parameter list and that count against the server.

Index — offline, no running TouchDesigner

ToolArgumentsUse it for
tool td_search_operators arguments query, family, limit use it for Find an operator by what it does. Plain language. family narrows to TOP/CHOP/SOP/DAT/MAT/COMP/POP.
tool td_operator_schema arguments op_type, page, include_hidden use it for Exact parameter names, defaults, menu options, ranges, connector counts, path to a shipped example. Menu options print as value — Label where the label says more than the value, which is where costs like "(GPU)" live.
tool td_search_parameters arguments query, limit use it for Which operator has a parameter doing X. How alwayscook gets found.
tool td_python_api arguments name, query use it for Members and methods of a class, with inherited ones resolved.
tool td_docs arguments query, page, limit use it for 2,060 wiki pages — concepts, techniques, tutorials, not just operators.
tool td_glossary arguments term, limit use it for 185 glossary entries: Cook, Time Slice, Clone, Perform Mode.
tool td_palette arguments query, category, limit use it for 277 ready-made components shipped with TouchDesigner.
tool td_expression_help arguments query, limit use it for Expression and command syntax.
tool td_example arguments op_type, depth use it for A real working network for an operator, from the shipped snippet library.

Live — acting on a running instance

ToolArgumentsUse it for
tool td_status arguments use it for Is the bridge up, what project is open.
tool td_log arguments limit, failures, summary, method use it for Your own trail: every bridge call this host made, how long it took and what it refused with. td_status reports no call history at all; this survives the session and answers "what did I break yesterday". failures=True for the refusals alone with the repair for the latest; summary=True for which methods refuse and which are slow. Offline tools never dial the bridge and leave no trace here.
tool td_instances arguments use it for Every running TouchDesigner that registered a bridge, and which one these tools reach. Check it before believing an edit landed in the project you meant.
tool td_doctor arguments use it for Every link — install, index, probe pass, bridge, this server — with the command that fixes each. Catches the index built from another TouchDesigner build, which raises nothing. The read cache is a CLI-only concern: td-atlas doctor on a terminal also says how many unpacked projects it holds and td-atlas doctor --clear-cache empties it, neither of which this tool reports or does — deleting a user's cache is not something a tool call should do on its own.
tool td_health arguments path, interval use it for The silent-failure detector. Run after building anything. interval is clamped, so a long wait comes back sooner than asked and says so. Read the reply for the two ways it can be partial — a truncated walk and script errors it could not read; see When a reply is cut short below.
tool td_network arguments path, depth use it for What is inside a component and how it is wired. A network too large for one reply comes back cut, and every cut is named; see When a reply is cut short below.
tool td_op_info arguments path use it for One operator: type, wiring, live parameter values, errors.
tool td_build arguments operations, undo_name, owner use it for Multi-step edits as one atomic, undoable block. Validated first. A created node with no position is given a free spot, and one wired inside its own op_create lands to the right of its source, so a batch reads left to right. op_create takes a text key for a DAT's contents, so shader and script source needs no separate td_exec.
tool td_set_params arguments path, pars, op_type, owner use it for Set parameters on an existing operator. Names are checked against the index only if you pass op_type; without it the name goes straight to TouchDesigner and comes back as an AttributeError.
tool td_palette_load arguments name, parent, rename, position, category, owner use it for Install a palette component by the name td_palette reports. Checks the .tox is on disk first, and reports the name TouchDesigner actually gave the node.
tool td_extension_add arguments class_name, code, path, parent, name, extension_name, promote, index, position, owner use it for Attach a Python class to a COMP as an extension — DAT, three Extensions parameters and the re-init in one call. Parses the code here first, and reads the result back: a class that fails to instantiate leaves the COMP reporting nothing at all.
tool td_annotate arguments text, parent, title, name, path, size, color, position, font_size, mode, owner use it for Leave a note in the network saying what you built and why — a coloured box beside the nodes it describes. Pass path to rewrite a note instead of adding another.
tool td_annotations arguments path, depth use it for Read the notes in a network, including a brief a person left for you, with the nodes each note's box sits over. Invisible to every other tool here.
tool td_flags arguments path use it for The flags that decide whether a node runs and what is visible: display, render, bypass, lock, expose, viewer, activeViewer, cloneImmune, allowCooking, selected, pickable, and which of them this operator does not have. Cooking is allowCooking; there is no flag named cooking. Check it when a correct-looking network produces nothing.
tool td_set_flags arguments path, flags, owner use it for Turn those flags on or off. Every write is read back, so a flag the family will not take comes back as a refusal.
tool td_render arguments path, width, height use it for A TOP's image, returned to you.
tool td_errors arguments path use it for Operators reporting an error or warning, at and under path — the project by default. Do not ask for /: the walk is breadth-first and bounded, and TouchDesigner's own /ui and /sys are thousands of operators wide near the top, so the budget runs out before anything of yours is reached (measured: 5000 nodes from / covered 3,979 of /ui and 954 of /sys, and missed a warning planted inside the project). The reply names the subtree it walked and says when the walk stopped early; see When a reply is cut short below.
tool td_exec arguments code use it for Arbitrary Python inside TouchDesigner. Last resort.
tool td_undo arguments redo use it for Undo or redo, including whole td_build batches. Cannot be a step inside td_build — that is refused, because two of them in a row reach past the batch into the artist's own history.
tool td_snapshot arguments label, path use it for Save a component for later diffing.
tool td_claim_scope arguments path, owner, ttl_seconds use it for Announce a subtree as yours before a run of edits, when another agent or session may be in the same project. Covers everything below path; lapses on its own. It guards against every unnamed caller including you, so carry the same owner into each write that follows.
tool td_release_scope arguments path, owner use it for Hand a claimed subtree back as soon as you are done. Until you do, the next agent waits out the claim.
tool td_scopes arguments use it for Which subtrees are claimed, by whom, until when. Check before editing a project someone else may be in.

Project files — on disk

ToolArgumentsUse it for
tool td_project_read arguments file, path, depth, params use it for Operator tree of a .toe/.tox without TouchDesigner.
tool td_project_text arguments file, path, max_bytes use it for The whole network as JSON — every parameter, wire, flag and DAT line. Reach for it when the tree is not enough; narrow with path, since a big network is refused.
tool td_project_write arguments file, text, output use it for The return leg of td_project_text: write an edited dump into a new .toe/.tox, no instance running. file must still be the original — the dump covers five of the forty-odd kinds of file a .toe holds and the rest are copied from it — and output must not exist. Read the gaps in the reply: anything that could not be written is listed, not approximated.
tool td_project_grep arguments file, pattern, limit use it for Search the Python and GLSL inside DATs.
tool td_project_diff arguments before, after, show_moves, include_text use it for Semantic comparison of two files.
tool td_variant_save arguments file, label, note, path use it for Keep the current state of a .toe/.tox before trying a direction. A variant is the network text plus a byte copy of the file, under ~/.td-atlas/variants — the text alone cannot rebuild a .toe, and the copy costs a median 19% on top of the text. A label already in use is refused, never overwritten.
tool td_variant_list arguments file use it for What has been saved — of one project, or of every project that has any. Says whether the original has changed since each save; that is information, not a warning, because a restore reads the variant's own copy.
tool td_variant_restore arguments file, label, output use it for Write a saved state back out. A copy, not a repack: toecollapse never runs, so nothing of the user's is moved aside to a .bkp1 file. output must not exist; a directory keeps the saved file name.
tool td_variant_diff arguments file, before, after, show_moves, include_text use it for Compare two saved states with the same semantic diff td_project_diff runs.

When a reply is cut short

Every call below is bounded in the work it may do. It runs on TouchDesigner's main thread during a cook, and a reply that reached a bound names the bound it reached.

td_network marks four separate cuts. childrenHidden is printed under the component whose listing was shortened, gives the number left out, and is printed even where nothing was listed at all. Over the whole reply, truncated with hidden says how many operators were dropped against the overall budget. limit and maxChildren say which two bounds applied. depthLimited carries the depth you asked for, when it was reduced to the deepest this tool walks. A component sitting at the depth you asked for is listed with the number of direct children it has that were not walked. That count is a floor, since what hangs below those children was never looked at. The repair is the same for all four cuts, and it is to ask again with a narrower path or a larger depth.

td_errors and td_health bound their walk by node count, and both take the subtree to walk as path. scanned is how many operators were actually looked at, the named subtree's own root included, so it never exceeds limit. notScanned is how many were not, truncated marks that it happened, and limit is the bound. notScanned is a floor, counting operators the walk had already found and not visited, and never what hangs below them. Read "nothing is wrong" as covering scanned operators at and under the subtree the reply names, and no others.

td_health also reports scriptErrorsUnread. It names the places where reading TouchDesigner's own script errors raised, and gives the reason. Read those places as unknown, and note that they arrive as a finding in the report.

Frame capture, used by the contact sheet below, has a byte budget as well as a frame count. A capture call answers captured: true while it is collecting. It answers full: true once the buffer is at its limit, and limit and maxFrames name the bounds. The sheet stops sampling on that flag.

When a tool refuses

Every refusal comes back with the state it observed and then three lines. A dead bridge, a path that does not exist, a parameter name the index rejects and an index that was never built all arrive in this shape:

shell
cause: no operator exists at that path in the running project
fix: list what is actually there before retrying — paths are case-sensitive ...
continue with: td_network, td_op_info

continue with: names tools and td-atlas subcommands that exist, and acting on that line beats repeating the call. Where the connector has no mapped recovery for the exception, it says fix: none known and names nothing. The message above it is then the whole answer, and something has to change before the retry.

Not exposed over MCP

A contact sheet needs repeated sampling over wall-clock time, which one tool call cannot do. Use the Python helper:

python
from td_atlas.bridge.client import BridgeClient
from td_atlas.bridge.filmstrip import contact_sheet
contact_sheet(BridgeClient.discover(), "/project1/out", "sheet.png",
              frames=12, interval=0.11, columns=4, width=280)

Setup

bash
td-atlas build     # offline index, 13-16 s
td-atlas install   # stage the bridge, print the bootstrap line
# paste that line into TouchDesigner's textport, once per project
td-atlas probe     # runtime facts: defaults, ranges, menus, type aliases