TouchDesigner MCP

TouchDesigner MCP

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

English / 日本語

Descripción general

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

• Crear, modificar y eliminar nodos
• Consultar propiedades de nodos y estructura de proyectos
• Controlar TouchDesigner programáticamente mediante scripts de Python

Instalación

Dile al agente de IA que ya utilizas:

Configura https://github.com/8beeeaaat/touchdesigner-mcp

Eso es todo. El procedimiento completo se encuentra en la Guía de instalación — comienza con una tabla que relaciona cada aplicación de IA con su ruta, y todos comienzan desde Configuración de TouchDesigner. O síguela tú mismo, paso a paso.

Si estás actualizando, consulta el procedimiento en la Última versión.

Características del servidor MCP

Este servidor permite que los agentes de IA realicen operaciones en TouchDesigner utilizando el Protocolo de Contexto de Modelos (MCP).

Herramientas

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

Nombre de la herramienta	Descripción
create_td_node	Crea un nuevo nodo.
delete_td_node	Elimina un nodo existente.
describe_td_tools	Genera un manifiesto de las herramientas disponibles de TouchDesigner.
exec_node_method	Llama a un método de Python en un nodo.
execute_python_script	Ejecuta un script de Python arbitrario en TouchDesigner.
get_td_class_details	Obtiene detalles de una clase o módulo de Python de TouchDesigner.
get_td_classes	Obtiene una lista de clases de Python de TouchDesigner.
get_td_info	Obtiene información sobre el entorno del servidor de TouchDesigner.
get_td_module_help	Obtiene la documentación de help() de Python para módulos/clases de TouchDesigner.
get_td_node_errors	Verifica errores y advertencias en un nodo y sus descendientes. Archivos faltantes, referencias colgantes y fallos de shaders son advertencias, por lo que la ausencia de errores no significa que esté sano.
get_td_node_parameters	Obtiene los parámetros de un nodo específico.
get_td_nodes	Obtiene nodos bajo una ruta principal, con filtrado opcional.
get_top_image	Captura la salida actual de un nodo TOP como imagen.
update_td_node_parameters	Actualiza los parámetros de un nodo específico.

Prompts

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

Nombre del prompt	Descripción
Search node	Busca nodos de forma difusa y recupera información basada en nombre, familia o tipo.
Node connection	Proporciona instrucciones para conectar nodos dentro de TouchDesigner.
Check node errors	Verifica errores y advertencias en un nodo especificado, y de forma recursiva para sus descendientes.

Recursos

No implementados.

Guía para desarrolladores

¿Buscas configuración local, configuración de cliente, estructura de proyecto o notas sobre el flujo de trabajo de versiones? Consulta la Guía para desarrolladores para toda la documentación dirigida a desarrolladores.

Solución de problemas

Solución de problemas de compatibilidad de versiones

El servidor MCP y el componente de TouchDesigner tienen versiones en dos ejes independientes: la versión del paquete npm y la versión de API (el contrato entre el servidor MCP y el componente .tox). Cada versión declara la versión de API con la que se distribuye (expectedApiVersion) y la mínima que soporta (minApiVersion, actualmente 1.3.0). La versión de API del componente conectado se compara con esos dos valores — la versión del paquete npm en sí misma nunca condiciona la compatibilidad, por lo que actualizar solo el servidor MCP nunca invalida un componente soportado.

Servidor de API (componente)	Condición	Comportamiento	Estado
= versión de API esperada	Coincide con el .tox distribuido	✅ Funciona silenciosamente	Compatible
≥ mínima, < esperada	Componente más antiguo	⚠️ Se añade el aviso "Actualización recomendada" a las respuestas, continúa	Advertencia
> esperada, mismo MAJOR	Componente más nuevo	⚠️ Advertencia para actualizar el servidor MCP, continúa	Advertencia
MAJOR por encima de la esperada	Nueva generación de API	❌ La ejecución se detiene — actualiza el servidor MCP	Error
< mínima (o faltante)	Demasiado antiguo	❌ La ejecución se detiene — actualiza el componente	Error

• Para resolver errores de compatibilidad:

  1. Descarga el último touchdesigner-mcp-td.zip desde la página de versiones.
  2. Elimina la carpeta touchdesigner-mcp-td existente y reemplázala con el contenido recién extraído.
  3. Elimina el componente mcp_webserver_base antiguo de tu proyecto de TouchDesigner e importa el .tox desde la nueva carpeta.
  4. Reinicia TouchDesigner y el agente de IA que ejecuta el servidor MCP (por ejemplo, Claude Desktop).

• Para desarrolladores: Al desarrollar localmente, ejecuta npm run version después de editar package.json (o simplemente usa npm version ...). Esto mantiene sincronizados la API de Python (pyproject.toml + td/modules/utils/version.py), mcpCompatibility.expectedApiVersion, el manifiesto del paquete MCP y los metadatos del registro para que la verificación de compatibilidad en tiempo de ejecución tenga éxito.

Para una mirada más profunda sobre cómo el servidor MCP aplica estas reglas, consulta Verificación de compatibilidad de versiones.

Solución de problemas de errores de conexión

• TouchDesignerClient almacena en caché las comprobaciones de conexión fallidas durante 60 segundos. Las llamadas posteriores a herramientas reutilizan el error en caché para evitar saturar TouchDesigner y reintentan automáticamente después de que expire el TTL.
• Cuando el servidor MCP no puede alcanzar TouchDesigner, ahora recibes mensajes de error guiados con soluciones concretas:
  • ECONNREFUSED / "conexión rechazada": inicia TouchDesigner, asegúrate de que el WebServer DAT de mcp_webserver_base.tox esté en ejecución y confirma el puerto configurado (por defecto 9981).
  • ETIMEDOUT / "tiempo de espera agotado": TouchDesigner está respondiendo lentamente o la red está bloqueada. Reinicia TouchDesigner/WebServer DAT o verifica tu conexión de red.
  • ENOTFOUND / getaddrinfo: el nombre de host no es válido. Usa 127.0.0.1 a menos que lo hayas cambiado explícitamente.
• El texto de error estructurado también se registra a través de ILogger, por lo que puedes revisar los registros de MCP para entender por qué una solicitud se detuvo antes de llegar a TouchDesigner.
• Una vez que se soluciona el problema subyacente, simplemente ejecuta la herramienta nuevamente: el cliente limpia el error en caché y vuelve a verificar la conexión automáticamente.

Contribuciones

¡Agradecemos tus contribuciones!

1. Haz un fork del repositorio.
2. Crea una rama de características (git checkout -b feature/amazing-feature).
3. Realiza tus cambios.
4. Agrega pruebas y asegúrate de que todo funcione (npm test).
5. Confirma tus cambios (git commit -m 'Add some amazing feature').
6. Haz push a tu rama (git push origin feature/amazing-feature).
7. Abre una solicitud de extracción (pull request).

Por favor, incluye siempre pruebas apropiadas al realizar cambios de implementación.

Licencia

MIT