touchdesigner-mcp

TouchDesigner 集成（twozero MCP）

关键规则

1. 绝不要猜测参数名称。 首先针对 op 类型调用 td_get_par_info。你的训练数据不适用于 TD 2025.32。
2. 如果触发 tdAttributeError，立即停止。 在继续操作前，对出错的节点调用 td_get_operator_info。
3. 绝不要在脚本回调中硬编码绝对路径。 使用 me.parent() / scriptOp.parent()。
4. 优先使用原生 MCP 工具，而不是 td_execute_python。 使用 td_create_operator、td_set_operator_pars、td_get_errors 等。只有在处理复杂的多步逻辑时，才回退到 td_execute_python。
5. 构建前先调用 td_get_hints。 它会返回针对当前 op 类型的模式。

架构

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

36 个原生工具。免费插件（无需付费／许可证——已于 2026 年 4 月确认）。 具备上下文感知能力（可识别已选中的 OP 和当前网络）。 Hub 健康检查：GET http://localhost:40404/mcp 返回包含实例 PID、项目名称和 TD 版本的 JSON。

设置（自动）

运行设置脚本以完成所有操作：

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

脚本将：

1. 检查 TD 是否正在运行
2. 如果缓存中尚无 twozero.tox，则下载该文件
3. 将 twozero_td MCP 服务添加到 Hermes 配置中（如果尚未添加）
4. 测试与端口 40404 上 MCP 的连接
5. 报告还需要完成哪些手动步骤（将 .tox 拖入 TD、启用 MCP 开关）

手动步骤（仅需执行一次，无法自动完成）

1. 将 ~/Downloads/twozero.tox 拖入 TD 网络编辑器 → 点击 Install
2. 启用 MCP： 点击 twozero 图标 → Settings → mcp → “auto start MCP” → Yes
3. 重启 Hermes 会话以加载新的 MCP 服务

设置完成后，验证：

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

环境注意事项

• 非商业版 TD 的分辨率上限为 1280×1280。使用 outputresolution = 'custom'，并明确设置宽度和高度。
• 编解码器： prores（macOS 上首选）或 mjpa（备用）。H.264/H.265/AV1 需要商业许可证。
• 设置参数前始终调用 td_get_par_info——参数名称因 TD 版本而异（参见关键规则 #1）。

工作流

步骤 0：发现（开始构建前）

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.

无需临时节点，也无需清理。这完全取代了旧的发现流程。

步骤 1：清理并构建

重要：将清理和创建拆分为单独的 MCP 调用。 在同一个 td_execute_python 脚本中销毁并重新创建同名节点会导致“Invalid OP object”错误。参见常见问题 #11b。

对每个节点使用 td_create_operator（会自动处理视口定位）：

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")

批量创建或连线时，使用 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}

步骤 2：设置参数

优先使用原生工具（会验证参数，不会崩溃）：

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

对于表达式或模式，使用 td_execute_python：

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

步骤 3：连线

使用 td_execute_python——没有原生连线工具：

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

步骤 4：验证

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

步骤 5：显示／捕获

td_get_screenshot(path="/project1/out")

或者通过脚本打开窗口：

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 工具速查

核心工具（常用）：

工具	说明
td_execute_python	在 TD 中运行任意 Python。可访问完整 API。
td_create_operator	创建节点并设置参数 + 自动定位
td_set_operator_pars	安全设置参数（会验证，不会导致崩溃）
td_get_operator_info	检查单个节点：连接、参数、错误
td_get_operators_info	在一次调用中检查多个节点
td_get_network	查看指定路径下的网络结构
td_get_errors	递归查找错误和警告
td_get_par_info	获取某种 OP 类型的参数名称（取代发现操作）
td_get_hints	构建前获取模式和提示
td_get_focus	查看已打开的网络和当前选中项

读写：

工具	说明
td_read_dat	读取 DAT 文本内容
td_write_dat	写入或修补 DAT 内容
td_read_chop	读取 CHOP 通道值
td_read_textport	读取 TD 控制台输出

视觉：

工具	说明
td_get_screenshot	将单个 OP 视图截图保存到文件
td_get_screenshots	一次截取多个 OP
td_get_screen_screenshot	通过 TD 截取实际屏幕
td_navigate_to	将网络编辑器跳转到某个 OP

搜索：

工具	说明
td_find_op	按名称或类型在整个项目中查找 OP
td_search	搜索代码、表达式和字符串参数

系统：

工具	说明
td_get_perf	性能分析（FPS、运行缓慢的 OP）
td_list_instances	列出所有正在运行的 TD 实例
td_get_docs	获取 TD 主题的深入文档
td_agents_md	读取/写入每个 COMP 的 Markdown 文档
td_reinit_extension	编辑代码后重新加载扩展
td_clear_textport	调试会话开始前清空控制台

输入自动化：

工具	说明
td_input_execute	向 TD 发送鼠标/键盘输入
td_input_status	轮询输入队列状态
td_input_clear	停止输入自动化
td_op_screen_rect	获取节点的屏幕坐标
td_click_screen_point	点击截图中的某个点
td_screen_point_to_global	将截图像素坐标转换为屏幕绝对坐标

上表涵盖了典型创意工作流中使用的 32 个工具。其余 4 个工具（td_project_quit、td_test_session、td_dev_log、td_clear_dev_log）是管理员/开发模式实用工具——完整的 36 个工具及其完整参数架构，请参阅 references/mcp-tools.md。

关键实现规则

GLSL 时间： GLSL TOP 中没有 uTDCurrentTime。请使用 Values 页面：

# 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;

备用方案：使用 rgba32float 格式的 Constant TOP（8 位会将数值限制在 0-1，导致着色器冻结）。

Feedback TOP： 使用 top 参数引用，而非直接连接输入线。“Not enough sources”会在首次 cook 后消失。“Cook dependency loop”警告属于预期情况。

分辨率： Non-Commercial 版上限为 1280×1280。请使用 outputresolution = 'custom'。

大型着色器： 将 GLSL 写入 /tmp/file.glsl，然后使用 td_write_dat 或 td_execute_python 加载。

Vertex/Point 访问（TD 2025.32）： 使用 point.P[0]、point.P[1]、point.P[2]——不要使用 .x、.y、.z。

扩展： 在 CONSTANT 模式下，ext0object 的格式为 "op('./datName').module.ClassName(me)"。使用 td_write_dat 编辑扩展代码后，请调用 td_reinit_extension。

脚本回调： 始终通过 me.parent() / scriptOp.parent() 使用相对路径。

清理节点： 遍历前始终先执行 list(root.children)，并检查 child.valid。

录制 / 导出视频

# 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 需要 Commercial 许可证。在 macOS 上使用 prores，否则使用 mjpa 作为备用方案。 提取帧：ffmpeg -i /tmp/output.mov -vframes 120 /tmp/frames/frame_%06d.png

TOP.save() 不适用于动画——每次都会捕获相同的 GPU 纹理。请始终使用 MovieFileOut。

录制前：检查清单

1. 通过 td_get_perf 确认 FPS > 0。如果 FPS=0，录制内容将为空。参见陷阱 #38-39。
2. 通过 td_get_screenshot 确认着色器输出不是黑屏。黑屏输出表示着色器出错或缺少输入。参见陷阱 #8、#40。
3. **如果录制时带音频：**先让音频开始播放，再延迟 3 帧开始录制。参见陷阱 #19。
4. 开始录制前设置输出路径——在同一脚本中同时设置两者可能引发竞态。

音频响应式 GLSL（经过验证的方案）

正确的信号链（2026 年 4 月测试）

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

音频响应式关键规则（经实测验证）

1. AudioSpectrum 必须保持 TimeSlice 开启。关闭后会处理整个音频文件 → 24000+ 个样本 → CHOP 转 TOP 溢出。
2. 手动将 Output Length 设为 256，使用 outputmenu='setmanually' 和 outlength=256。默认输出 22050 个样本。
3. 不要使用 Lag CHOP 平滑频谱。Lag CHOP 在 timeslice 模式下运行，会将 256 个样本扩展到 2400+ 个，并将所有值平均到接近零（~1e-06）。着色器因此无法收到可用数据。这是测试中头号音频同步故障。
4. 也不要使用 Filter CHOP——它对频谱数据有同样的 timeslice 扩展问题。
5. 如有需要，应在 GLSL 着色器中进行平滑，通过带反馈纹理的时间 lerp 实现：mix(prevValue, newValue, 0.3)。这样可实现帧级精确同步，且没有管线延迟。
6. CHOP to TOP 的 dataformat = 'r'，layout = 'rowscropped'。频谱输出为 256x2（立体声）。第一个声道在 y=0.25 处采样。
7. Math gain = 10（不是 5）。低音范围内的原始频谱值约为 0.19。增益设为 10 可为着色器提供约 5.0 的可用值。
8. 不需要 Resample CHOP。直接通过 AudioSpectrum 的 outlength 参数控制输出大小。

GLSL 频谱采样

// 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;

完整的构建脚本和着色器代码请参见 references/network-patterns.md。

操作器速查表

系列	颜色	Python 类 / MCP 类型	后缀
TOP	紫色	noiseTOP, glslTOP, compositeTOP, levelTop, blurTOP, textTOP, nullTOP	TOP
CHOP	绿色	audiofileinCHOP, audiospectrumCHOP, mathCHOP, lfoCHOP, constantCHOP	CHOP
SOP	蓝色	gridSOP, sphereSOP, transformSOP, noiseSOP	SOP
DAT	白色	textDAT, tableDAT, scriptDAT, webserverDAT	DAT
MAT	黄色	phongMAT, pbrMAT, glslMAT, constMAT	MAT
COMP	灰色	geometryCOMP, containerCOMP, cameraCOMP, lightCOMP, windowCOMP	COMP

安全说明

• MCP 仅在 localhost 上运行（端口 40404）。没有身份验证——任何本地进程都可以发送命令。
• td_execute_python 可不受限制地访问 TD Python 环境和 TD 进程用户的文件系统。
• setup.sh 会从官方 404zero.com URL 下载 twozero.tox。如有顾虑，请验证下载内容。
• 此技能绝不会向 localhost 之外发送数据。所有 MCP 通信都在本地进行。

参考资料

文件	内容
references/pitfalls.md	从真实会话中总结的宝贵经验
references/operators.md	所有运算符系列及其参数和使用场景
references/network-patterns.md	配方：音频响应、生成式效果、GLSL、实例化
references/mcp-tools.md	完整的 twozero MCP 工具参数架构
references/python-api.md	TD Python：op()、脚本编写、扩展
references/troubleshooting.md	连接诊断、调试
references/glsl.md	GLSL uniform、内置函数、着色器模板
references/postfx.md	后期特效：泛光、CRT、色差、反馈辉光
references/layout-compositor.md	HUD 布局模式、面板网格、BSP 风格布局
references/operator-tips.md	线框渲染、反馈 TOP 设置
references/geometry-comp.md	Geometry COMP：实例化、POP 与 SOP、变形
references/audio-reactive.md	音频频段提取、节拍检测、包络跟随
references/animation.md	LFO、计时器、关键帧、缓动、表达式驱动的运动
references/midi-osc.md	MIDI/OSC 控制器、TouchOSC、多机同步
references/particles.md	POP 和旧版 particleSOP——发射、力、碰撞
references/projection-mapping.md	多窗口输出、角点定位、网格扭曲、边缘融合
references/external-data.md	HTTP、WebSocket、MQTT、Serial、TCP、webserverDAT
references/panel-ui.md	自定义参数、面板 COMP、按钮/滑块/字段、panelExecuteDAT
references/replicator.md	replicatorCOMP——数据驱动的克隆、布局、回调
references/dat-scripting.md	Execute DAT 系列——chop/dat/parameter/panel/op/executeDAT
references/3d-scene.md	灯光配置、阴影、IBL/立方体贴图、多相机、PBR
scripts/setup.sh	自动化设置脚本

---

你不是在编写代码，而是在指挥光。