Touchdesigner

🚀 触摸设计器 MCP 服务器开发指南

本指南详细介绍了触摸设计器 MCP 服务器的开发流程，包括安装、项目结构、API 代码生成、项目初始化、使用说明、贡献指南、开发流程以及版权信息等内容。

🚀 快速开始

安装依赖

使用 npm 进行安装：

npm install

启动项目

开发模式

npm run dev

此命令会启动 MCP 服务器和 Inspector 工具。

生产环境

npm start

✨ 主要特性

• 使用 OpenAPI 基于代码生成工具（Orval / openapi-generator-cli）生成 API 代码。
• 支持 Python 服务器代码、处理器代码和测试用例的自动生成。
• 提供 Inspector 工具用于调试和监控 MCP 服务器运行状态。

📦 安装指南

环境搭建

• 安装 Node.js 和 npm。
• 克隆本仓库并安装依赖：

git clone https://github.com/yourusername/touchdesigner-mcp.git
cd touchdesigner-mcp
npm install

配置环境

创建并编辑 .env 文件：

touch .env

添加以下内容到 .env 文件中：

NODE_ENV=development
MCP_PORT=8080
TOUCHDesigner_PATH=/path/to/TouchDesigner

💻 使用示例

基础用法

运行 MCP 服务器

npm start

启动 Inspector 工具

Inspector 是用于调试和监控 MCP 服务器运行状态的工具，可以通过以下命令启动：

npm run inspector

📚 详细文档

项目结构

├── src/                       # MCP 服务器源代码
│   ├── api/                  # OpenAPI 规范文件（定义了 TD WebServer 接口）
│   ├── core/                 # 核心工具（日志记录、错误处理）
│   ├── features/             # MCP 功能实现模块
│   │   ├── prompts/         # 提示处理器
│   │   ├── resources/       # 资源处理器
│   │   └── tools/           # 工具处理器（如 tdTools.ts）
│   ├── gen/                  # 根据 OpenAPI 方案生成的代码
│   ├── server/               # MCP 服务器逻辑（连接处理、主服务器类）
│   ├── tdClient/             # TouchDesigner 连接 API 客户端
│   ├── index.ts              # Node.js 服务器入口点
│   └── ...
├── td/                        # TouchDesigner 相关文件
│   ├── modules/              # TouchDesigner 插件模块
│   │   ├── mcp/              # 处理器核心逻辑
│   │   │   ├── controllers/ # API 请求控制器（api_controller.py、generated_handlers.py）
│   │   │   └── services/    # 业务逻辑实现（api_service.py）
│   │   ├── td_server/        # 根据 OpenAPI 方案生成的 Python 服务器代码
│   │   └── utils/            # 共享 Python 工具函数
│   ├── templates/             # Mustache 模板文件（用于生成处理器代码）
│   ├── genHandlers.js         # Node.js 脚本，用于生成 generated_handlers.py
│   ├── import_modules.py      # 辅助脚本，用于在 TouchDesigner 中导入 API 服务器模块
│   └── mcp_webserver_base.tox # 主 TouchDesigner 组件文件
├── tests/                      # 测试代码
│   ├── integration/
│   └── unit/
├── .env                        # 本地环境变量配置（被 Git 忽略）
├── dotenv                      # .env 文件模板
└── 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 文件内容。
   • 根据 OpenAPI 定义生成 Python 服务器代码框架（位于 td/modules/td_server/），此代码在 TouchDesigner 中通过 WebServer DAT 运行。
   • 需要 Docker 环境支持。

2. Python 处理器代码生成 (npm run gen:handlers)：

   • 使用 Node.js 脚本 genHandlers.js 生成处理器代码（位于 td/modules/mcp/）。

3. 测试用例生成 (npm run gen:test)：

   • 自动生成接口测试用例，便于后续验证 API 行为是否符合预期。

开发流程

1. 环境搭建

   • 安装 Node.js 和 npm。
   • 克隆本仓库并安装依赖：

     git clone https://github.com/yourusername/touchdesigner-mcp.git
     cd touchdesigner-mcp
     npm install
     

2. 开发与调试

   • 使用 npm run dev 启动开发环境。
   • 修改代码后，确保通过单元测试和集成测试验证功能。

3. 构建与部署

   • 生成生产环境构建文件：

     npm run build
     

   • 将构建后的文件部署到目标服务器或环境中。

🔧 技术细节

• 本项目使用 OpenAPI 规范定义 API 接口，通过代码生成工具自动生成服务器代码和测试用例，提高开发效率和代码质量。
• 使用 Docker 环境支持 Python 服务器代码的生成，确保生成过程的一致性和可重复性。
• 通过 Inspector 工具可以方便地调试和监控 MCP 服务器的运行状态，及时发现和解决问题。

📄 许可证

MIT License

Copyright (c) 年份 作者姓名

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

贡献指南

提交代码规范

遵循 CONTRIBUTING.md 文件中的规范进行代码提交。

问题报告

在遇到问题时，请通过 GitHub 提交 issue 或 fork 项目后提交 pull request 解决问题。