触摸设计器MCP

这是TouchDesigner的MCP（模型上下文协议）服务器的实现。其目标是使AI代理能够控制和操作TouchDesigner项目。

英语 / 日本语

概述

TouchDesigner MCP充当AI模型和TouchDesigner WebServer DAT之间的桥梁，使AI代理能够：

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

安装

请参阅 安装指南.

如果您正在更新，请参阅 最新发布.

MCP服务器功能

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

工具

工具允许AI代理在TouchDesigner中执行操作。

工具名称	描述
create_td_node	创建新节点。
delete_td_node	删除现有节点。
exec_node_method	在节点上调用Python方法。
execute_python_script	在TouchDesigner中执行任意Python脚本。
get_module_help	获取TouchDesigner模块/类的Python help（）文档
get_td_class_details	获取TouchDesigner Python类或模块的详细信息。
get_td_classes	获取TouchDesigner Python类的列表。
get_td_info	获取有关TouchDesigner服务器环境的信息。
get_td_node_errors	检查指定节点及其子节点上的错误。
get_td_node_parameters	获取特定节点的参数。
get_td_nodes	获取父路径下的节点，具有可选筛选功能
update_td_node_parameters	更新特定节点的参数。

鼓励

提示为AI代理在TouchDesigner中执行特定操作提供说明。

提示名称	描述
Search node	模糊搜索节点，并根据名称、家族或类型检索信息。
Node connection	提供连接TouchDesigner中节点的说明。
Check node errors	检查指定节点上的错误，并递归检查其子节点。

资源

未执行。

开发者指南

正在寻找本地设置、客户端配置、项目结构或发布工作流说明？ 看 开发者指南 适用于所有面向开发人员的文档。

故障排除

版本兼容性故障排除

MCP服务器使用 语义化版本 用于灵活的兼容性检查

MCP服务器	API服务器	最低兼容API版本	行为	状态	注释
1.3.x	1.3.0	1.3.0	✅ 正常工作	兼容	推荐的基线配置
1.3.x	1.4.0	1.3.0	⚠️ 显示警告，继续	警告	较旧的MCP MINOR和较新的API可能缺少新功能
1.4.0	1.3.x	1.3.0	⚠️ 显示警告，继续	警告	较新的MCP MINOR可能具有其他功能
1.3.2	1.3.1	1.3.2	❌ 执行停止	错误	API低于最低兼容版本
2.0.0	1.x.x	不适用	❌ 执行停止	错误	不同的MAJOR=中断更改

兼容性规则:

• ✅ 兼容：相同的主要版本和API版本≥1.3.0（最低兼容版本）
• ⚠️ 警告：同一主版本中的不同MINOR或PATCH版本（显示警告但继续执行）
• ❌ 错误：不同的主要版本或API服务器＜1.3.0（执行立即停止，需要更新）
• 要解决兼容性错误，请执行以下操作：

1. 下载最新版 触摸设计器-mcp-td.zip 从发布页面。
2. 删除现有 touchdesigner-mcp-td 文件夹，并用新提取的内容替换它。
3. 删除旧 mcp_webserver_base 从TouchDesigner项目中导入组件，并导入 .tox 从新文件夹。
4. 重新启动TouchDesigner和运行MCP服务器的AI代理（例如Claude Desktop）。

• 对于开发者： 在本地开发时，运行 npm run version 编辑后 package.json （或简单地使用 npm version ...).这将保留Python API(pyproject.toml + td/modules/utils/version.py)、MCP包清单和注册表元数据同步，以便运行时兼容性检查成功。

要更深入地了解MCP服务器如何执行这些规则，请参阅 版本兼容性验证.

连接错误故障排除

• TouchDesignerClient 缓存连接检查失败 60秒。后续的工具调用会重用缓存的错误，以避免向TouchDesigner发送垃圾邮件，并在TTL到期后自动重试。

• 当MCP服务器无法访问TouchDesigner时，您现在会收到带有具体修复的引导错误消息：

• ECONNREFUSED /“连接被拒绝”：启动TouchDesigner，确保WebServer DAT从 mcp_webserver_base.tox 正在运行，并确认配置的端口（默认 9981).

• ETIMEDOUT /“超时”：TouchDesigner响应缓慢或网络被阻止。重新启动TouchDesigner/WebServer DAT或检查您的网络连接。

• ENOTFOUND / getaddrinfo：主机名无效。使用 127.0.0.1 除非你明确地更改了它。

• 结构化错误文本也会通过以下方式记录 ILogger，因此您可以检查MCP日志，以了解在点击TouchDesigner之前请求停止的原因。

• 一旦底层问题得到解决，只需再次运行该工具——客户端会清除缓存的错误并自动重新验证连接。

贡献

我们欢迎您的贡献！

1. 分叉存储库。
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请求。

在进行实现更改时，请始终包含适当的测试。

许可证

麻省理工学院