TouchDesigner MCP

Esta es una implementación de un servidor MCP (Protocolo de Contexto de Modelo) para TouchDesigner. El objetivo es permitir que los agentes de IA controlen y operen proyectos de TouchDesigner.

Inglés /日本語

Descripción general

TouchDesigner MCP actúa como un puente entre los modelos de IA y TouchDesigner WebServer DAT, lo que permite a los agentes de IA:

• Crear, modificar y eliminar nodos

• Propiedades del nodo de consulta y estructura del proyecto

• Controlar TouchDesigner programáticamente mediante scripts de Python

Related MCP server: td-mcp

Uso

Requiere que Docker o Node.js estén instalados

1. Clonar el repositorio:

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

2. Configure el archivo de entorno y compile:

Copie el archivo de plantilla y ajuste TD_WEB_SERVER_HOST y TD_WEB_SERVER_PORT según sea necesario antes de crear la imagen de Docker.

cp dotenv .env
make build

3. Instale el servidor API en su proyecto TouchDesigner:

Inicie TouchDesigner e importe el componente td/mcp_webserver_base.tox directamente en el proyecto de TouchDesigner que desea controlar. Ejemplo: Colóquelo como /project1/mcp_webserver_base

Al importar el tox se activará el script td/import_modules.py , que carga módulos como los controladores del servidor API.

Puede comprobar los registros de arranque abriendo Textport desde el menú TouchDesigner.

4. Inicie el contenedor del servidor MCP

docker-compose up -d

5. Configure su agente de IA para usar el contenedor Docker:

Ejemplo para Claude Desktop

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

En sistemas Windows, incluya la letra de la unidad como C:, por ejemplo C:\\path\\to\\your\\touchdesigner-mcp\\docker-compose.yml

Para utilizar el JS prediseñado directamente desde Node.js:

1. Instalar el paquete

mkdir some && cd ./some  # If you need a new directory
npm install touchdesigner-mcp-server

2. Instale el servidor API en su proyecto TouchDesigner:

Inicie TouchDesigner e importe el componente some/node_modules/touchdesigner-mcp-server/td/mcp_webserver_base.tox directamente en el proyecto de TouchDesigner que desea controlar. Por ejemplo: colóquelo como /project1/mcp_webserver_base

Al importar el tox se activará el script some/node_modules/touchdesigner-mcp-server/td/import_modules.py , que carga módulos como controladores de servidor API.

Puede comprobar los registros de arranque abriendo Textport desde el menú TouchDesigner.

3. Configure su agente de IA:

Ejemplo para Claude Desktop

{
  "mcpServers": {
    "touchdesigner": {
      "args": [
        "/path/to/your/node_modules/touchdesigner-mcp-server/dist/index.js", // <-- Replace with the absolute path to node_modules/touchdesigner-mcp-server/dist/index.js
        "--stdio"
      ],
      "command": "node"
    }
  }
}

En sistemas Windows, incluya la letra de la unidad como C:, por ejemplo C:\\path\\to\\your\\node_modules\\touchdesigner-mcp-server\\dist\\index.js

3. Verificar la conexión

Si se reconoce el servidor MCP, la configuración está completa. Si no se reconoce, intente reiniciar el agente de IA. Si observa un error al iniciar, intente reiniciar el agente después de iniciar TouchDesigner. Cuando el servidor API funciona correctamente en TouchDesigner, el agente puede usar las herramientas proporcionadas para operarlo.

Características del servidor MCP

Este servidor permite operaciones en TouchDesigner a través del Protocolo de contexto de modelo (MCP) y proporciona referencias a varios documentos de implementación.

Herramientas

Las herramientas permiten que los agentes de IA realicen acciones en TouchDesigner.

Indicaciones

Las indicaciones proporcionan instrucciones para que los agentes de IA realicen acciones específicas en TouchDesigner.

Recursos

No implementado

Para desarrolladores

Creación de código de cliente y servidor API

1. cp dotenv .env

2. Ajuste TD_WEB_SERVER_HOST y TD_WEB_SERVER_PORT en el archivo .env para que coincidan con su entorno de desarrollo

3. Ejecute make build o npm run build para regenerar el código

Cuando necesite reflejar el código compilado, reinicie tanto el servidor MCP como TouchDesigner.

Verificación del servidor API

• npm run test Ejecuta pruebas unitarias para el código del servidor MCP y pruebas de integración con TouchDesigner. Puedes consultar los registros de comunicación abriendo Textport desde el menú de TouchDesigner.

• npm run dev Ejecute @modelcontextprotocol/inspector para depurar varias funciones.

Descripción general de la estructura del proyecto

├── src/                       # MCP server source code
│   ├── api/                  # OpenAPI spec for TD WebServer
│   ├── core/                 # Core utilities (logger, error handling)
│   ├── features/             # MCP feature implementations
│   │   ├── prompts/         # Prompt handlers
│   │   ├── resources/       # Resource handlers
│   │   └── tools/           # Tool handlers (e.g., tdTools.ts)
│   ├── gen/                  # Code generated from OpenAPI schema for MCP server
│   ├── server/               # MCP server logic (connections, main server class)
│   ├── tdClient/             # TD connection API client
│   ├── index.ts              # Main entry point for Node.js server
│   └── ...
├── td/                        # TouchDesigner related files
│   ├── modules/              # Python modules for TouchDesigner
│   │   ├── mcp/              # Core logic for handling MCP requests in TD
│   │   │   ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py)
│   │   │   └── services/    # Business logic (api_service.py)
│   │   ├── td_server/        # Python model code generated from OpenAPI schema
│   │   └── utils/            # Shared Python utilities
│   ├── templates/             # Mustache templates for Python code generation
│   ├── genHandlers.js         # Node.js script for generating generated_handlers.py
│   ├── import_modules.py      # Helper script to import API server modules into TD
│   └── mcp_webserver_base.tox # Main TouchDesigner component
├── tests/                      # Test code
│   ├── integration/
│   └── unit/
├── .env                        # Local environment variables (git ignored)
├── dotenv                      # Template for .env
└── orval.config.ts             # Orval config (TS client generation)

Flujo de trabajo de generación de código API

Este proyecto utiliza herramientas de generación de código basadas en OpenAPI (Orval / openapi-generator-cli):

Definición de API: El contrato de API entre el servidor MCP Node.js y el servidor Python que se ejecuta dentro de TouchDesigner se define en src/api/index.yml .

1. Generación del servidor Python ( npm run gen:webserver ):

   • Utiliza openapi-generator-cli a través de Docker.

   • Lee src/api/index.yml .

   • Genera un esqueleto de servidor Python ( td/modules/td_server/ ) basado en la definición de la API. Este código se ejecuta dentro de TouchDesigner mediante el DAT del servidor web.

   • Requiere que Docker esté instalado y en ejecución.

2. Generación de controladores de Python ( npm run gen:handlers ):

   • Utiliza un script Node.js personalizado ( td/genHandlers.js ) y plantillas Mustache ( td/templates/ ).

   • Lee el código del servidor Python generado o la especificación OpenAPI.

   • Genera implementaciones de controladores ( td/modules/mcp/controllers/generated_handlers.py ) que se conectan a la lógica empresarial en td/modules/mcp/services/api_service.py .

3. Generación de cliente TypeScript ( npm run gen:mcp ):

   • Utiliza Orval para generar código de cliente API y esquemas Zod para la validación de herramientas a partir del esquema YAML incluido en openapi-generator-cli .

   • Genera un cliente TypeScript tipificado ( src/tdClient/ ) utilizado por el servidor Node.js para realizar solicitudes al DAT del servidor web.

El proceso de compilación ( npm run build ) ejecuta todos los pasos de generación necesarios ( npm run gen ), seguido de la compilación de TypeScript ( tsc ).

Contribuyendo

¡Agradecemos sus contribuciones!

1. Bifurcar el repositorio

2. Crear una rama de características ( git checkout -b feature/amazing-feature )

3. Realiza tus cambios

4. Agregue pruebas y asegúrese de que todo funcione ( npm test )

5. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

6. Empujar a su rama ( git push origin feature/amazing-feature )

7. Abrir una solicitud de extracción

Incluya siempre pruebas adecuadas al realizar cambios de implementación.

Licencia

Instituto Tecnológico de Massachusetts (MIT)