TouchDesigner MCP

TouchDesigner MCP

这是为 TouchDesigner 实现的 MCP（模型上下文协议）服务，旨在让 AI Agent 能够控制和操作 TouchDesigner 项目。

English / 日本語

概述

TouchDesigner MCP 充当 AI 模型与 TouchDesigner WebServer DAT 之间的桥梁，使 AI Agent 能够：

• 创建、修改和删除节点
• 查询节点属性和项目结构
• 通过 Python 脚本以编程方式控制 TouchDesigner

安装

告诉你正在使用的 AI Agent：

设置 https://github.com/8beeeaaat/touchdesigner-mcp

就这么简单。完整流程请参阅 安装指南——其中首先会提供一张表格，将每款 AI 应用与对应的配置方式相匹配，并且所有人都从 TouchDesigner 设置 开始。你也可以自行逐步操作。

如果要更新，请参阅 **最新版本**中的流程。

MCP 服务功能

此服务使用模型上下文协议（MCP），让 AI Agent 能够在 TouchDesigner 中执行操作。

工具

工具可让 AI Agent 在 TouchDesigner 中执行操作。

工具名称	描述
create_td_node	创建新节点。
delete_td_node	删除现有节点。
describe_td_tools	生成可用 TouchDesigner 工具的清单。
exec_node_method	调用节点上的 Python 方法。
execute_python_script	在 TouchDesigner 中执行任意 Python 脚本。
get_td_class_details	获取 TouchDesigner Python 类或模块的详细信息。
get_td_classes	获取 TouchDesigner Python 类列表。
get_td_info	获取 TouchDesigner 服务环境的信息。
get_td_module_help	获取 TouchDesigner 模块／类的 Python help() 文档。
get_td_node_errors	检查节点及其后代节点上的错误和警告。缺失文件、悬空引用和着色器故障都属于警告，因此没有错误并不代表状态正常。
get_td_node_parameters	获取指定节点的参数。
get_td_nodes	获取父路径下的节点，并可选择进行筛选。
get_top_image	将 TOP 节点的当前输出捕获为图像。
update_td_node_parameters	更新指定节点的参数。

提示词

提示词为 AI Agent 提供指令，使其在 TouchDesigner 中执行特定操作。

提示词名称	描述
Search node	模糊搜索节点，并根据名称、系列或类型获取信息。
Node connection	提供在 TouchDesigner 中连接节点的说明。
Check node errors	检查指定节点及其所有后代节点的错误和警告。

资源

尚未实现。

开发者指南

想了解本地设置、客户端配置、项目结构或发布工作流说明？ 请参阅**开发者指南**，获取面向开发者的所有文档。

故障排除

排查版本兼容性问题

MCP 服务和 TouchDesigner 组件的版本分别沿两个独立的维度管理：npm 包版本和 API 版本（MCP 服务与 .tox 组件之间的契约）。每个版本都会声明其包含的 API 版本（expectedApiVersion）以及支持的最低版本（minApiVersion，目前为 1.3.0）。系统会将已连接组件的 API 版本与这两个值进行比较——npm 包版本本身不会限制兼容性，因此仅更新 MCP 服务不会使受支持的组件失效。

API 服务（组件）	条件	行为	状态
= 预期 API 版本	与随附的 .tox 匹配	✅ 静默运行	兼容
≥ 最低版本，< 预期版本	较旧的组件	⚠️ 在响应中附加“建议更新”通知，并继续运行	警告
> 预期版本，且 MAJOR 相同	较新的组件	⚠️ 警告需要更新 MCP 服务，并继续运行	警告
MAJOR 高于预期版本	更新一代的 API	❌ 停止执行——请更新 MCP 服务	错误
< 最低版本（或缺失）	版本过旧	❌ 停止执行——请更新组件	错误

• 解决兼容性错误：

  1. 从发布页面下载最新的 touchdesigner-mcp-td.zip。
  2. 删除现有的 touchdesigner-mcp-td 文件夹，并用新解压的内容替换。
  3. 从 TouchDesigner 项目中移除旧的 mcp_webserver_base 组件，并从新文件夹导入 .tox。
  4. 重启 TouchDesigner 和运行 MCP 服务的 AI Agent（例如 Claude Desktop）。

• 面向开发者： 本地开发时，编辑 package.json 后运行 npm run version（或直接使用 npm version ...）。这样可确保 Python API（pyproject.toml + td/modules/utils/version.py）、mcpCompatibility.expectedApiVersion、MCP bundle 清单和注册表元数据保持同步，从而使运行时兼容性检查通过。

如需深入了解 MCP 服务如何实施这些规则，请参阅版本兼容性验证。

连接错误故障排除

• TouchDesignerClient 会缓存失败的连接检查 60 seconds。后续工具调用会复用缓存的错误，以避免频繁请求 TouchDesigner；TTL 过期后会自动重试。
• 当 MCP 服务无法连接到 TouchDesigner 时，现在会显示提供具体解决方法的引导式错误消息：
  • ECONNREFUSED / "connect refused"：启动 TouchDesigner，确保 mcp_webserver_base.tox 中的 WebServer DAT 正在运行，并确认已配置的端口（默认值为 9981）。
  • ETIMEDOUT / "timeout"：TouchDesigner 响应缓慢或网络受阻。重启 TouchDesigner/WebServer DAT，或检查网络连接。
  • ENOTFOUND / getaddrinfo：主机名无效。除非你明确更改过，否则请使用 127.0.0.1。
• 结构化错误文本也会通过 ILogger 记录，因此你可以查看 MCP 日志，了解请求为何在触达 TouchDesigner 之前停止。
• 修复根本问题后，只需再次运行工具——客户端会清除缓存的错误并自动重新验证连接。

参与贡献

欢迎贡献！

1. Fork 此仓库。
2. 创建功能分支（git checkout -b feature/amazing-feature）。
3. 进行更改。
4. 添加测试并确保一切正常（npm test）。
5. 提交更改（git commit -m 'Add some amazing feature'）。
6. 将更改推送到你的分支（git push origin feature/amazing-feature）。
7. 发起 Pull Request。

进行实现更改时，请务必添加适当的测试。

许可证

MIT