Touchdesigner

🚀 Touch Designer MCP Server Development Guide

This guide provides a detailed introduction to the installation, project structure, API code generation, and other aspects of the Touch Designer MCP server, helping developers quickly get started with development.

🚀 Quick Start

📦 Installation

Use npm to install dependencies:

npm install

▶️ Starting the Project

Development Mode

npm run dev

This command starts the MCP server and the Inspector tool.

Production Environment

npm start

📁 Project Structure

├── src/                       # MCP server source code
│   ├── api/                  # OpenAPI specification files (defining TD WebServer interfaces)
│   ├── core/                 # Core utilities (logging, error handling)
│   ├── features/             # MCP functionality implementation modules
│   │   ├── prompts/         # Prompt handlers
│   │   ├── resources/       # Resource handlers
│   │   └── tools/           # Tool handlers (e.g., tdTools.ts)
│   ├── gen/                  # Code generated based on the OpenAPI schema
│   ├── server/               # MCP server logic (connection handling, main server class)
│   ├── tdClient/             # TouchDesigner connection API client
│   ├── index.ts              # Node.js server entry point
│   └── ...
├── td/                        # TouchDesigner-related files
│   ├── modules/              # TouchDesigner plugin modules
│   │   ├── mcp/              # Processor core logic
│   │   │   ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py)
│   │   │   └── services/    # Business logic implementation (api_service.py)
│   │   ├── td_server/        # Python server code generated based on the OpenAPI schema
│   │   └── utils/            # Shared Python utility functions
│   ├── templates/             # Mustache template files (for generating processor code)
│   ├── genHandlers.js         # Node.js script for generating generated_handlers.py
│   ├── import_modules.py      # Helper script for importing API server modules in TouchDesigner
│   └── mcp_webserver_base.tox # Main TouchDesigner component file
├── tests/                      # Test code
│   ├── integration/
│   └── unit/
├── .env                        # Local environment variable configuration (ignored by Git)
├── dotenv                      # .env file template
└── orval.config.ts             # Orval configuration file (for generating TypeScript clients)

💻 API Code Generation Process

This project uses OpenAPI-based code generation tools (Orval / openapi-generator-cli):

API Definition: The API interface definition file between the Node.js MCP server and the Python server running in TouchDesigner is located at src/api/index.yml.

1. Python Server Code Generation (npm run gen:webserver):

   • Use the openapi-generator-cli tool in Docker.
   • Read the contents of the src/api/index.yml file.
   • Generate a Python server code framework based on the OpenAPI definition (located in td/modules/td_server/). This code runs in TouchDesigner through the WebServer DAT.
   • Requires Docker environment support.

2. Python Processor Code Generation (npm run gen:handlers):

   • Use the Node.js script genHandlers.js to generate processor code (located in td/modules/mcp/).

3. Test Case Generation (npm run gen:test):

   • Automatically generate interface test cases to facilitate subsequent verification of whether the API behavior meets expectations.

⚙️ Project Initialization

Configuring the Environment

Create and edit the .env file:

touch .env

Add the following content to the .env file:

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

📖 Usage Instructions

Running the MCP Server

npm start

Starting the Inspector Tool

The Inspector is a tool for debugging and monitoring the running status of the MCP server. It can be started with the following command:

npm run inspector

🤝 Contribution Guidelines

Code Submission Specifications

Follow the specifications in the CONTRIBUTING.md file for code submission.

Issue Reporting

When encountering issues, submit an issue on GitHub or fork the project and submit a pull request to resolve the issue.

🔨 Development Process

1. Environment Setup

   • Install Node.js and npm.
   • Clone this repository and install dependencies:

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

2. Development and Debugging

   • Use npm run dev to start the development environment.
   • After modifying the code, ensure that the functionality is verified through unit tests and integration tests.

3. Building and Deployment

   • Generate production environment build files:

     npm run build
     

   • Deploy the built files to the target server or environment.

📄 License

MIT License

Copyright (c) [Year] [Author's Name]

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.