Touchdesigner

🚀 觸摸設計器 MCP 服務器開發指南

本開發指南詳細介紹了觸摸設計器 MCP 服務器的安裝、運行、項目結構、API 代碼生成、項目初始化、使用說明、貢獻方式、開發流程以及版權信息等內容，幫助開發者快速上手和開發。

🚀 快速開始

安裝依賴

使用 npm 進行安裝：

npm install

啟動項目

開發模式

npm run dev

此命令會啟動 MCP 服務器和 Inspector 工具。

生產環境

npm start

📦 安裝指南

環境搭建

• 安裝 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

📁 項目結構

├── 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。

Python 服務器代碼生成 (npm run gen:webserver)

• 使用 Docker 中的 openapi-generator-cli 工具。
• 讀取 src/api/index.yml 文件內容。
• 根據 OpenAPI 定義生成 Python 服務器代碼框架（位於 td/modules/td_server/），此代碼在 TouchDesigner 中通過 WebServer DAT 運行。
• 需要 Docker 環境支持。

Python 處理器代碼生成 (npm run gen:handlers)

使用 Node.js 腳本 genHandlers.js 生成處理器代碼（位於 td/modules/mcp/）。

測試用例生成 (npm run gen:test)

自動生成接口測試用例，便於後續驗證 API 行為是否符合預期。

💻 使用示例

運行 MCP 服務器

npm start

啟動 Inspector 工具

Inspector 是用於調試和監控 MCP 服務器運行狀態的工具，可以通過以下命令啟動：

npm run inspector

🤝 貢獻指南

提交代碼規範

遵循 CONTRIBUTING.md 文件中的規範進行代碼提交。

問題報告

在遇到問題時，請通過 GitHub 提交 issue 或 fork 項目後提交 pull request 解決問題。

🔨 開發流程

環境搭建

• 安裝 Node.js 和 npm。
• 克隆本倉庫並安裝依賴：

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

開發與調試

• 使用 npm run dev 啟動開發環境。
• 修改代碼後，確保通過單元測試和集成測試驗證功能。

構建與部署

• 生成生產環境構建文件：

npm run build

• 將構建後的文件部署到目標服務器或環境中。

📄 許可證

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.