TouchDesigner MCP

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

English / 日本語

概述

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

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

架构

flowchart LR
    A["🤖<br/>MCP 客户端<br/>(Claude / Codex / ...)"]

    subgraph S [Node.js MCP 服务器]
      B1["🧰<br/>工具及提示<br/>(src/features/tools)"]
      B2["🖌️<br/>展示器及格式化器<br/>(markdown 输出)"]
      B3["🌐<br/>OpenAPI HTTP 客户端<br/>(src/tdClient)"]
    end

    subgraph T [TouchDesigner 项目]
      C1["🧩<br/>WebServer DAT<br/>(mcp_webserver_base.tox)"]
      C2["🐍<br/>Python 控制器 / 服务<br/>(td/modules/mcp)"]
      C3["🎛️<br/>项目节点及参数<br/>(/project1/...)"]
    end

    A --> B1
    B1 --> B2
    B1 --> B3
    B2 --> A
    B3 <--> C1
    C1 <--> C2
    C2 <--> C3

    %% 更高对比度的颜色以提高可读性
    classDef client fill:#d8e8ff,stroke:#1f6feb,stroke-width:2px,color:#111,font-weight:bold
    classDef server fill:#efe1ff,stroke:#8250df,stroke-width:2px,color:#111,font-weight:bold
    classDef td fill:#d7f5e3,stroke:#2f9e44,stroke-width:2px,color:#111,font-weight:bold
    class A client;
    class B1,B2,B3 server;
    class C1,C2,C3 td;

使用方法

<details> <summary>方法 1：使用 Claude Desktop 和 MCP Bundle（推荐）</summary>

1. 下载文件

从发布页面下载以下内容：

• TouchDesigner 组件：touchdesigner-mcp-td.zip
• MCP Bundle (.mcpb)：touchdesigner-mcp.mcpb

2. 设置 TouchDesigner 组件

1. 从 touchdesigner-mcp-td.zip 中解压 TouchDesigner 组件。
2. 将 mcp_webserver_base.tox 导入到你的 TouchDesigner 项目中。
3. 将其放置在 /project1/mcp_webserver_base。

https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4

你可以通过打开 TouchDesigner 菜单中的 Textport 查看启动日志。

3. 安装 MCP Bundle

双击 touchdesigner-mcp.mcpb 文件以在 Claude Desktop 中安装该捆绑包。

https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854

4. 连接到服务器

MCP 捆绑包会自动处理与 TouchDesigner 服务器的连接。

⚠️ 重要提示：必须精确保留提取时的目录结构。mcp_webserver_base.tox 组件引用了相对于 modules/ 目录和其他文件的相对路径。

</details> <details> <summary>方法 2：使用 npx</summary>

需要安装 Node.js。

1. 设置 TouchDesigner 组件

1. 从 touchdesigner-mcp-td.zip 下载并解压 TouchDesigner 组件（发布页面）。
2. 将 mcp_webserver_base.tox 导入到你的 TouchDesigner 项目中。
3. 将其放置在 /project1/mcp_webserver_base。

https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4

你可以通过打开 TouchDesigner 菜单中的 Textport 查看启动日志。

2. 设置 MCP 服务器配置

针对 Claude Desktop 的示例：

{
  "mcpServers": {
    "touchdesigner": {
      "command": "npx",
      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
    }
  }
}

自定义：你可以通过添加 --host 和 --port 参数来自定义 TouchDesigner 服务器连接：

"args": [
  "-y",
  "touchdesigner-mcp-server@latest",
  "--stdio",
  "--host=http://custom_host",
  "--port=9982"
]

</details> <details> <summary>方法 3：使用 Docker 镜像</summary>

1. 克隆仓库

git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
cd touchdesigner-mcp

2. 构建 Docker 镜像

make build

3. 在你的 TouchDesigner 项目中安装 API 服务器

启动 TouchDesigner 并将 td/mcp_webserver_base.tox 组件导入到你想要控制的项目中。 示例：将其放置在 /project1/mcp_webserver_base。

导入 .tox 文件将触发 td/import_modules.py 脚本，该脚本加载 API 服务器所需的模块。

https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4

你可以通过打开 TouchDesigner 菜单中的 Textport 查看启动日志。

4. 启动 MCP 服务器容器

docker-compose up -d

5. 配置你的 AI 代理以使用 Docker 容器

针对 Claude Desktop 的示例：

{
  "mcpServers": {
    "touchdesigner": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/path/to/your/touchdesigner-mcp/docker-compose.yml",
        "exec",
        "-i",
        "touchdesigner-mcp-server",
        "node",
        "dist/cli.js",
        "--stdio",
        "--host=http://host.docker.internal"
      ]
    }
  }
}

在 Windows 系统上，请包含驱动器字母，例如 C:\path\to\your\touchdesigner-mcp\docker-compose.yml。

注意：你可以通过添加 --host 和 --port 参数来自定义 TouchDesigner 服务器连接：

"args": [
...,
"--stdio",
"--host=http://host.docker.internal",
"--port=9982"
]

</details>

验证连接

如果 MCP 服务器被识别，则设置完成。 如果没有被识别，请尝试重启你的 AI 代理。 如果在启动时看到错误，请在启动 TouchDesigner 后再次启动代理。 当 API 服务器在 TouchDesigner 中正常运行时，代理可以使用提供的工具来操作它。

目录结构要求

关键：无论使用哪种方法，都必须保持原始目录结构：

td/
├── import_modules.py          # 模块加载脚本
├── mcp_webserver_base.tox     # 主要的 TouchDesigner 组件
└── modules/                   # Python 模块目录
    ├── mcp/                   # MCP 核心逻辑
    ├── utils/                 # 共享实用工具
    └── td_server/             # 生成的 API 服务器代码

mcp_webserver_base.tox 组件使用相对路径来定位 Python 模块。移动或重新组织这些文件会导致 TouchDesigner 中的导入错误。

MCP 服务器特性

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

工具

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

工具名称	描述
create_td_node	创建一个新的节点。
delete_td_node	删除一个现有的节点。
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_node_parameters	获取特定节点的参数。
get_td_nodes	获取父路径下的节点，可选过滤。
update_td_node_parameters	更新特定节点的参数。

提示

提示提供指令，使 AI 代理能够在 TouchDesigner 中执行特定操作。

提示名称	描述
搜索节点	模糊搜索节点，并根据名称、家族或类型检索信息。
节点连接	提供在 TouchDesigner 内部连接节点的指令。
检查节点错误	检查指定节点及其子节点的错误。

资源

未实现。

开发者指南

快速开始开发

1. 设置你的环境：

   # 克隆并安装依赖项
   git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
   cd touchdesigner-mcp
   npm install
   

2. 构建项目：

   make build        # 基于 Docker 的构建（推荐）
   # 或
   npm run build     # 基于 Node.js 的构建
   

3. 可用命令：

   npm run test      # 运行单元和集成测试
   npm run dev       # 启动 MCP 检查器进行调试
   

注意：当你更新代码时，必须重启 MCP 服务器和 TouchDesigner 以应用更改。

项目结构概述

├── src/                       # MCP 服务器源代码
│   ├── api/                  # TouchDesigner WebServer 的 OpenAPI 规范
│   ├── core/                 # 核心实用工具（日志记录器、错误处理）
│   ├── features/             # MCP 特性实现
│   │   ├── prompts/         # 提示处理器
│   │   ├── resources/       # 资源处理器
│   │   └── tools/           # 工具处理器（例如，tdTools.ts）
│   ├── gen/                  # 根据 OpenAPI 模式为 MCP 服务器生成的代码
│   ├── server/               # MCP 服务器逻辑（连接、主服务器类）
│   ├── tdClient/             # TouchDesigner 连接 API 客户端
│   ├── index.ts              # Node.js 服务器的主要入口点
│   └── ...
├── td/                        # 与 TouchDesigner 相关的文件
│   ├── modules/              # TouchDesigner 的 Python 模块
│   │   ├── mcp/              # 处理 TouchDesigner 中 MCP 请求的核心逻辑
│   │   │   ├── controllers/ # API 请求控制器（api_controller.py，generated_handlers.py）
│   │   │   └── services/    # 业务逻辑（api_service.py）
│   │   ├── td_server/        # 根据 OpenAPI 模式生成的 Python 模型代码
│   │   └── utils/            # 共享的 Python 实用工具
│   ├── templates/             # 用于 Python 代码生成的 Mustache 模板
│   ├── genHandlers.js         # 生成 generated_handlers.py 的 Node.js 脚本
│   ├── import_modules.py      # 辅助脚本，将 API 服务器模块导入到 TouchDesigner 中
│   └── mcp_webserver_base.tox # 主要的 TouchDesigner 组件
├── tests/                      # 测试代码
│   ├── integration/
│   └── unit/
└── orval.config.ts             # Orval 配置（TypeScript 客户端生成）

API 代码生成工作流程

该项目使用基于 OpenAPI 的代码生成工具（Orval 和 openapi-generator-cli）。

API 定义：Node.js MCP 服务器与运行在 TouchDesigner 内部的 Python 服务器之间的 API 合同定义在 src/api/index.yml。

1. Python 服务器生成（npm run gen:webserver）：
   • 通过 Docker 使用 openapi-generator-cli。
   • 读取 src/api/index.yml。
   • 根据 API 定义生成 Python 服务器骨架（td/modules/td_server/）。此代码在 TouchDesigner 的 WebServer DAT 中运行。
   • 需要安装并运行 Docker。
2. Python 处理器生成（npm run gen:handlers）：
   • 使用自定义的 Node.js 脚本（td/genHandlers.js）和 Mustache 模板（td/templates/）。
   • 读取生成的 Python 服务器代码或 OpenAPI 规范。
   • 生成处理器实现（td/modules/mcp/controllers/generated_handlers.py），这些处理器连接到 td/modules/mcp/services/api_service.py 中的业务逻辑。
3. TypeScript 客户端生成（npm run gen:mcp）：
   • 使用 Orval 从模式 YAML 生成 API 客户端和 Zod 模式，这些模式由 openapi-generator-cli 打包。
   • 生成一个类型的 TypeScript 客户端（src/tdClient/），该客户端由 Node.js 服务器用来向 WebServer DAT 发送请求。

构建过程（npm run build）运行所有必要的生成步骤（npm run gen），然后进行 TypeScript 编译（tsc）。

贡献

我们欢迎您的贡献！

1. 分叉仓库。
2. 创建一个功能分支（git checkout -b feature/amazing-feature）。
3. 进行更改。
4. 添加测试并确保一切正常（npm test）。
5. 提交更改（git commit -m '添加一些惊人的功能'）。
6. 推送到你的分支（git push origin feature/amazing-feature）。
7. 打开拉取请求。

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

许可证

MIT