touchdesigner-mcp-server

Implements the Model Context Protocol (MCP) as a server that translates MCP client requests into TouchDesigner network commands, enabling LLM agents and tools to communicate with TouchDesigner instances over the network. Uses MCP's standardized resource and tool schemas to expose TouchDesigner capabilities as callable functions, with request/response serialization handling the protocol translation layer between MCP clients and TouchDesigner's native network API.

Exposes TouchDesigner parameters, operators, and available commands as MCP resources with JSON schema definitions, allowing MCP clients to discover what can be controlled and what data types are expected. Implements MCP's resource listing and schema introspection endpoints so clients can query available operations before making calls, enabling intelligent prompt generation and parameter validation.

Handles reading and writing TouchDesigner parameters through the network protocol with automatic type conversion between MCP's JSON types and TouchDesigner's native types (float, int, string, bool, vector). Implements validation logic to ensure values conform to parameter constraints (min/max ranges, enum values) before sending to TouchDesigner, with error handling for type mismatches and out-of-range values.

Enables calling TouchDesigner operators (CHOP, SOP, TOP, DAT) as MCP tools, with support for passing inputs and retrieving outputs. Implements operator invocation through TouchDesigner's network protocol, handling asynchronous execution and state polling to retrieve results. Supports querying operator state (enabled/disabled, current output values) to enable agents to understand the current scene state.

Groups multiple parameter changes or operator calls into a single network transaction, reducing round-trip latency and ensuring atomic updates. Implements command buffering and batch sending through TouchDesigner's network protocol, with rollback support if any command in the batch fails. Enables agents to perform coordinated multi-step updates (e.g., change position, rotation, and scale simultaneously) with guaranteed consistency.

Implements retry logic, connection pooling, and graceful degradation for network failures between MCP server and TouchDesigner. Detects connection loss, automatically attempts reconnection with exponential backoff, and queues commands during disconnection for replay when connection restores. Provides detailed error messages distinguishing between network errors, TouchDesigner errors, and validation errors to enable intelligent error recovery in agents.

Records all MCP tool calls, parameter changes, and operator executions with timestamps and execution results, enabling audit trails and debugging. Implements structured logging with configurable verbosity levels and optional integration with external logging systems (e.g., JSON logging to files or services). Provides execution traces showing command sequence, timing, and results to help agents understand what happened and diagnose failures.