触摸设计器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 从发布页面。 1. 删除现有 touchdesigner-mcp-td 文件夹，并用新提取的内容替换它。 1. 删除旧 mcp_webserver_base 从TouchDesigner项目中导入组件，并导入 .tox 从新文件夹。 1. 重新启动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之前请求停止的原因。 - 一旦底层问题得到解决，只需再次运行该工具——客户端会清除缓存的错误并自动重新验证连接。
贡献
我们欢迎您的贡献！
- 分叉存储库。
- 创建要素分支(
git checkout -b feature/amazing-feature). - 进行更改。
- 添加测试并确保一切正常(
npm test). - 提交您的更改(
git commit -m 'Add some amazing feature'). - 推到您的分支(
git push origin feature/amazing-feature). - 打开一个pull请求。
在进行实现更改时，请始终包含适当的测试。
许可证
麻省理工学院