Touchdesigner MCP

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

Pitfalls

-

-

Verification

-

-

-

-

1. 2. 3.

IO_CONTRACT

• input: request: str, context: dict — 用户请求描述、上下文信息
• output: result: dict — 技能执行结果（结构因技能而异）

对应原则：P2（机械原子暴露输入输出规范）

TouchDesigner Integration (twozero MCP)

CRITICAL RULES

1. NEVER guess parameter names. Call td_get_par_info for the op type FIRST. Your training data is wrong for TD 2025.32.
2. If tdAttributeError fires, STOP. Call td_get_operator_info on the failing node before continuing.
3. NEVER hardcode absolute paths in script callbacks. Use me.parent() / scriptOp.parent().
4. Prefer native MCP tools over td_execute_python. Use td_create_operator, td_set_operator_pars, td_get_errors etc. Only fall back to td_execute_python for complex multi-step logic.
5. Call td_get_hints before building. It returns patterns specific to the op type you're working with.

Architecture

Hermes Agent -> MCP (Streamable HTTP) -> twozero.tox (port 40404) -> TD Python

36 native tools. Free plugin (no payment/license — confirmed April 2026). Context-aware (knows selected OP, current network). Hub health check: GET http://localhost:40404/mcp returns JSON with instance PID, project name, TD version.

Setup (Automated)

Run the setup script to handle everything:

bash "${HERMES_HOME:-$HOME/.hermes}/skills/creative/touchdesigner-mcp/scripts/setup.sh"

The script will:

1. Check if TD is running
2. Download twozero.tox if not already cached
3. Add twozero_td MCP server to Hermes config (if missing)
4. Test the MCP connection on port 40404
5. Report what manual steps remain (drag .tox into TD, enable MCP toggle)

Manual steps (one-time, cannot be automated)

1. Drag ~/Downloads/twozero.tox into the TD network editor → click Install
2. Enable MCP: click twozero icon → Settings → mcp → "auto start MCP" → Yes
3. Restart Hermes session to pick up the new MCP server

After setup, verify:

nc -z 127.0.0.1 40404 && echo "twozero MCP: READY"

Environment Notes

• Non-Commercial TD caps resolution at 1280×1280. Use outputresolution = 'custom' and set width/height explicitly.
• Codecs: prores (preferred on macOS) or mjpa as fallback. H.264/H.265/AV1 require a Commercial license.
• Always call td_get_par_info before setting params — names vary by TD version (see CRITICAL RULES #1).

Workflow

Step 0: Discover (before building anything)

Call td_get_par_info with op_type for each type you plan to use.
Call td_get_hints with the topic you're building (e.g. "glsl", "audio reactive", "feedback").
Call td_get_focus to see where the user is and what's selected.
Call td_get_network to see what already exists.

No temp nodes, no cleanup. This replaces the old discovery dance entirely.

Step 1: Clean + Build

IMPORTANT: Split cleanup and creation into SEPARATE MCP calls. Destroying and recreating same-named nodes in one td_execute_python script causes "Invalid OP object" errors. See pitfalls #11b.

Use td_create_operator for each node (handles viewport positioning automatically):

td_create_operator(type="noiseTOP", parent="/project1", name="bg", parameters={"resolutionw": 1280, "resolutionh": 720})
td_create_operator(type="levelTOP", parent="/project1", name="brightness")
td_create_operator(type="nullTOP", parent="/project1", name="out")

For bulk creation or wiring, use td_execute_python:

# td_execute_python script:
root = op('/project1')
nodes = []
for name, optype in [('bg', noiseTOP), ('fx', levelTOP), ('out', nullTOP)]:
    n = root.create(optype, name)
    nodes.append(n.path)
# Wire chain
for i in range(len(nodes)-1):
    op(nodes[i]).outputConnectors[0].connect(op(nodes[i+1]).inputConnectors[0])
result = {'created': nodes}

Step 2: Set Parameters

Prefer the native tool (validates params, won't crash):

td_set_operator_pars(path="/project1/bg", parameters={"roughness": 0.6, "monochrome": true})

For expressions or modes, use td_execute_python:

op('/project1/time_driver').par.colorr.expr = "absTime.seconds % 1000.0"

Step 3: Wire

Use td_execute_python — no native wire tool exists:

op('/project1/bg').outputConnectors[0].connect(op('/project1/fx').inputConnectors[0])

Step 4: Verify

td_get_errors(path="/project1", recursive=true)
td_get_perf()
td_get_operator_info(path="/project1/out", detail="full")

Step 5: Display / Capture

td_get_screenshot(path="/project1/out")

Or open a window via script:

win = op('/project1').create(windowCOMP, 'display')
win.par.winop = op('/project1/out').path
win.par.winw = 1280; win.par.winh = 720
win.par.winopen.pulse()

MCP Tool Quick Reference

Core (use these most):

Read/Write:

Visual:

Search:

System:

Input Automation:

The table above covers the 32 tools used in typical creative workflows. The remaining 4 tools (td_project_quit, td_test_session, td_dev_log, td_clear_dev_log) are admin/dev-mode utilities — see references/mcp-tools.md for the full 36-tool reference with complete parameter schemas.

Key Implementation Rules

GLSL time: No uTDCurrentTime in GLSL TOP. Use the Values page:

# Call td_get_par_info(op_type="glslTOP") first to confirm param names
td_set_operator_pars(path="/project1/shader", parameters={"value0name": "uTime"})
# Then set expression via script:
# op('/project1/shader').par.value0.expr = "absTime.seconds"
# In GLSL: uniform float uTime;

Fallback: Constant TOP in rgba32float format (8-bit clamps to 0-1, freezing the shader).

Feedback TOP: Use top parameter reference, not direct input wire. "Not enough sources" resolves after first cook. "Cook dependency loop" warning is expected.

Resolution: Non-Commercial caps at 1280×1280. Use outputresolution = 'custom'.

Large shaders: Write GLSL to /tmp/file.glsl, then use td_write_dat or td_execute_python to load.

Vertex/Point access (TD 2025.32): point.P[0], point.P[1], point.P[2] — NOT .x, .y, .z.

Extensions: ext0object format is "op('./datName').module.ClassName(me)" in CONSTANT mode. After editing extension code with td_write_dat, call td_reinit_extension.

Script callbacks: ALWAYS use relative paths via me.parent() / scriptOp.parent().

Cleaning nodes: Always list(root.children) before iterating + child.valid check.

Recording / Exporting Video

# via td_execute_python:
root = op('/project1')
rec = root.create(moviefileoutTOP, 'recorder')
op('/project1/out').outputConnectors[0].connect(rec.inputConnectors[0])
rec.par.type = 'movie'
rec.par.file = '/tmp/output.mov'
rec.par.videocodec = 'prores'  # Apple ProRes — NOT license-restricted on macOS
rec.par.record = True   # start
# rec.par.record = False  # stop (call separately later)

H.264/H.265/AV1 need Commercial license. Use prores on macOS or mjpa as fallback. Extract frames: ffmpeg -i /tmp/output.mov -vframes 120 /tmp/frames/frame_%06d.png

TOP.save() is useless for animation — captures same GPU texture every time. Always use MovieFileOut.

Before Recording: Checklist

1. Verify FPS > 0 via td_get_perf. If FPS=0 the recording will be empty. See pitfalls #38-39.
2. Verify shader output is not black via td_get_screenshot. Black output = shader error or missing input. See pitfalls #8, #40.
3. If recording with audio: cue audio to start first, then delay recording by 3 frames. See pitfalls #19.
4. Set output path before starting record — setting both in the same script can race.

Audio-Reactive GLSL (Proven Recipe)

Correct signal chain (tested April 2026)

AudioFileIn CHOP (playmode=sequential)
  → AudioSpectrum CHOP (FFT=512, outputmenu=setmanually, outlength=256, timeslice=ON)
  → Math CHOP (gain=10)
  → CHOP to TOP (dataformat=r, layout=rowscropped)
  → GLSL TOP input 1 (spectrum texture, 256x2)

Constant TOP (rgba32float, time) → GLSL TOP input 0
GLSL TOP → Null TOP → MovieFileOut

Critical audio-reactive rules (empirically verified)

1. TimeSlice must stay ON for AudioSpectrum. OFF = processes entire audio file → 24000+ samples → CHOP to TOP overflow.
2. Set Output Length manually to 256 via outputmenu='setmanually' and outlength=256. Default outputs 22050 samples.
3. DO NOT use Lag CHOP for spectrum smoothing. Lag CHOP operates in timeslice mode and expands 256 samples to 2400+, averaging all values to near-zero (~1e-06). The shader receives no usable data. This was the #1 audio sync failure in testing.
4. DO NOT use Filter CHOP either — same timeslice expansion problem with spectrum data.
5. Smoothing belongs in the GLSL shader if needed, via temporal lerp with a feedback texture: mix(prevValue, newValue, 0.3). This gives frame-perfect sync with zero pipeline latency.
6. CHOP to TOP dataformat = 'r', layout = 'rowscropped'. Spectrum output is 256x2 (stereo). Sample at y=0.25 for first channel.
7. Math gain = 10 (not 5). Raw spectrum values are ~0.19 in bass range. Gain of 10 gives usable ~5.0 for the shader.
8. No Resample CHOP needed. Control output size via AudioSpectrum's outlength param directly.

GLSL spectrum sampling

// Input 0 = time (1x1 rgba32float), Input 1 = spectrum (256x2)
float iTime = texture(sTD2DInputs[0], vec2(0.5)).r;

// Sample multiple points per band and average for stability:
// NOTE: y=0.25 for first channel (stereo texture is 256x2, first row center is 0.25)
float bass = (texture(sTD2DInputs[1], vec2(0.02, 0.25)).r +
              texture(sTD2DInputs[1], vec2(0.05, 0.25)).r) / 2.0;
float mid  = (texture(sTD2DInputs[1], vec2(0.2, 0.25)).r +
              texture(sTD2DInputs[1], vec2(0.35, 0.25)).r) / 2.0;
float hi   = (texture(sTD2DInputs[1], vec2(0.6, 0.25)).r +
              texture(sTD2DInputs[1], vec2(0.8, 0.25)).r) / 2.0;

See references/network-patterns.md for complete build scripts + shader code.

Operator Quick Reference

Security Notes

• MCP runs on localhost only (port 40404). No authentication — any local process can send commands.
• td_execute_python has unrestricted access to the TD Python environment and filesystem as the TD process user.
• setup.sh downloads twozero.tox from the official 404zero.com URL. Verify the download if concerned.
• The skill never sends data outside localhost. All MCP communication is local.

References

验证清单 · VERIFICATION

• nc -z 127.0.0.1 40404 通过，且 GET /mcp 返回含 TD 版本/PID 的 JSON，确认 twozero MCP 在线
• 构建前已对每个用到的 op type 调用 td_get_par_info + td_get_hints，未凭训练数据猜测参数名
• 同名节点的销毁与创建拆分为独立 MCP 调用，未在同一 td_execute_python 中混合（无 "Invalid OP object" 错误）
• 构建后 td_get_errors(path, recursive=true) 无 error/warning，td_get_operator_info 确认连线与参数正确
• 录制前 td_get_perf 确认 FPS > 0，td_get_screenshot 确认输出非全黑
• 非商业版已显式设置 outputresolution='custom' + 宽高，编码用 prores/mjpa（未用 H.264/H.265/AV1）

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

You're not writing code. You're conducting light.

Touchdesigner Mcp

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [TOUC-001] 构建节点前 → 必须调用 td_get_par_info 和 td_get_hints 获取当前版本的参数名与模式，严禁基于训练数据猜测参数
• [TOUC-002] 发生 tdAttributeError 时 → 立即停止操作，调用 td_get_operator_info 检查失败节点状态后再继续
• [TOUC-003] 编写脚本回调时 → 禁止硬编码绝对路径，必须使用 me.parent() 或 scriptOp.parent() 等相对路径引用
• [TOUC-004] 执行常规操作时 → 优先使用 td_create_operator、td_set_operator_pars 等原生 MCP 工具，仅在复杂多步逻辑时回退到 td_execute_python
• [TOUC-005] 清理与创建同名节点时 → 必须将销毁和创建拆分为独立的 MCP 调用，禁止在单个 td_execute_python 脚本中混合执行以避免 "Invalid OP object" 错误
• [TOUC-006] 设置非商业版 TD 分辨率时 → 显式设置 outputresolution = 'custom' 并指定宽高，以突破 1280×1280 的限制
• [TOUC-007] 处理视频编码时 → 在 macOS 上优先使用 prores 或 mjpa，避免使用 H.264/H.265/AV1 等需要商业授权的编码格式