touchdesigner-mcp-server 0.2.1

package/dist/gen/mcp/touchDesignerAPI.zod.js

@@ -0,0 +1,203 @@
+/**
+ * Generated by orval v7.9.0 🍺
+ * Do not edit manually.
+ * TouchDesigner API
+ * OpenAPI schema for generating TouchDesigner API client code
+ * OpenAPI spec version: 0.2.1
+ */
+import { z as zod } from 'zod';
+/**
+ * @summary Delete an existing node
+ */
+export const deleteNodeQueryParams = zod.object({
+    "nodePath": zod.string().describe('Path to the node to delete. e.g., \"/project1/geo1\"')
+});
+export const deleteNodeResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "deleted": zod.boolean().optional().describe('Whether the node was successfully deleted'),
+        "node": zod.object({
+            "id": zod.number(),
+            "opType": zod.string(),
+            "name": zod.string(),
+            "path": zod.string(),
+            "properties": zod.record(zod.string(), zod.any())
+        }).optional().describe('Information about a TouchDesigner node')
+    }).nullable(),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * @summary Get nodes in the path
+ */
+export const getNodesQueryPatternDefault = "*";
+export const getNodesQueryParams = zod.object({
+    "parentPath": zod.string().describe('Parent path  e.g., \"/project1\"'),
+    "pattern": zod.string().default(getNodesQueryPatternDefault).describe('Pattern to match against node names e.g., \"null*\"')
+});
+export const getNodesResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "nodes": zod.array(zod.object({
+            "id": zod.number(),
+            "opType": zod.string(),
+            "name": zod.string(),
+            "path": zod.string(),
+            "properties": zod.record(zod.string(), zod.any())
+        }).describe('Information about a TouchDesigner node')).optional().describe('Result of the execution')
+    }).nullable(),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * @summary Create a new node
+ */
+export const createNodeBody = zod.object({
+    "parentPath": zod.string().describe('Path to the parent node (e.g., /project1)'),
+    "nodeType": zod.string().describe('Type of the node to create (e.g., textTop)'),
+    "nodeName": zod.string().optional().describe('Name of the new node (optional)')
+});
+export const createNodeResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "result": zod.object({
+            "id": zod.number(),
+            "opType": zod.string(),
+            "name": zod.string(),
+            "path": zod.string(),
+            "properties": zod.record(zod.string(), zod.any())
+        }).optional().describe('Information about a TouchDesigner node')
+    }).nullable(),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * Retrieves detailed information about a specific node including its properties, parameters and connections
+ * @summary Get node detail
+ */
+export const getNodeDetailQueryParams = zod.object({
+    "nodePath": zod.string().describe('Node path. e.g., \"/project1/textTOP\"')
+});
+export const getNodeDetailResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "id": zod.number(),
+        "opType": zod.string(),
+        "name": zod.string(),
+        "path": zod.string(),
+        "properties": zod.record(zod.string(), zod.any())
+    }).describe('Information about a TouchDesigner node'),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * @summary Update node properties
+ */
+export const updateNodeBody = zod.object({
+    "nodePath": zod.string().describe('Path to the node (e.g., /project1/null1)'),
+    "properties": zod.record(zod.string(), zod.any())
+});
+export const updateNodeResponse = zod.object({
+    "success": zod.boolean().describe('Whether the update operation was successful'),
+    "data": zod.object({
+        "path": zod.string().optional().describe('Path of the node that was updated'),
+        "updated": zod.array(zod.string()).optional().describe('List of property names that were successfully updated'),
+        "failed": zod.array(zod.object({
+            "name": zod.string().optional().describe('Name of the property that failed to update'),
+            "reason": zod.string().optional().describe('Reason for the failure')
+        })).optional().describe('List of properties that failed to update'),
+        "message": zod.string().optional().describe('Summary message about the update operation')
+    }).nullable(),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * Returns a list of Python classes, modules, and functions available in TouchDesigner
+ * @summary Get a list of Python classes and modules
+ */
+export const getTdPythonClassesResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "classes": zod.array(zod.object({
+            "name": zod.string().describe('Name of the class or module'),
+            "type": zod.enum(['class', 'module', 'function', 'object']).describe('Type of the Python entity'),
+            "description": zod.string().optional().describe('Description of the class or module')
+        }).describe('Information about a Python class or module available in TouchDesigner')).optional()
+    }).nullable(),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * Returns detailed information about a specific Python class, module, or function including methods, properties, and documentation
+ * @summary Get details of a specific Python class or module
+ */
+export const getTdPythonClassDetailsParams = zod.object({
+    "className": zod.string().describe('Name of the class or module. e.g., \"textTOP\"')
+});
+export const getTdPythonClassDetailsResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "name": zod.string().describe('Name of the class or module'),
+        "type": zod.enum(['class', 'module', 'function', 'object']).describe('Type of the Python entity'),
+        "description": zod.string().optional().describe('Description of the class or module'),
+        "methods": zod.array(zod.object({
+            "name": zod.string().describe('Method name'),
+            "signature": zod.string().optional().describe('Method signature including parameters'),
+            "description": zod.string().optional().describe('Description of the method')
+        }).describe('Information about a Python method')).describe('List of methods available in the class or module'),
+        "properties": zod.array(zod.object({
+            "name": zod.string().describe('Property name'),
+            "type": zod.string().describe('Type of the property'),
+            "value": zod.object({}).nullish().describe('Current value of the property (if serializable)')
+        }).describe('Information about a Python property')).describe('List of properties available in the class or module')
+    }).describe('Detailed information about a Python class or module'),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * Call a method on the node at the specified path (e.g., /project1).
+This allows operations equivalent to TouchDesigner's Python API such as
+`parent_comp = op('/project1')` and `parent_comp.create('textTOP', 'myText')`.
+
+ * @summary Call a method of the specified node
+ */
+export const execNodeMethodBody = zod.object({
+    "nodePath": zod.string().describe('Path to the node (e.g., /project1/null1)'),
+    "method": zod.string().describe('Name of the method to call'),
+    "args": zod.array(zod.string().or(zod.number()).or(zod.boolean())).optional().describe('List of arguments for the method call'),
+    "kwargs": zod.record(zod.string(), zod.any()).optional().describe('Keyword arguments for the method call')
+});
+export const execNodeMethodResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "result": zod.object({}).describe('Result of the method call. Can be any type (equivalent to unknown in TypeScript).')
+    }).nullable(),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * Execute a Python script directly in TouchDesigner.
+Multiline scripts and scripts containing comments are supported.
+The script can optionally set a `result` variable to explicitly return a value.
+This endpoint allows you to interact with TouchDesigner nodes programmatically.
+
+ * @summary Execute python code on the server
+ */
+export const execPythonScriptBody = zod.object({
+    "script": zod.string().describe('e.g., \"op(\'/project1/text_over_image\').outputConnectors[0].connect(op(\'/project1/out1\'))\"')
+});
+export const execPythonScriptResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "result": zod.object({
+            "value": zod.object({}).optional().describe('Return value of the executed script, can be any serializable value')
+        }).describe('Result of the executed script')
+    }).nullable(),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
+/**
+ * Returns information about the TouchDesigner
+ * @summary Get TouchDesigner information
+ */
+export const getTdInfoResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "server": zod.string().describe('Server name (typically \"TouchDesigner\")'),
+        "version": zod.string().describe('TouchDesigner version number'),
+        "osName": zod.string().describe('Operating system name'),
+        "osVersion": zod.string().describe('Operating system version')
+    }).nullable(),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});

package/dist/index.js

@@ -0,0 +1,3 @@
+export { startServer } from "./cli.js";
+export { TouchDesignerServer } from "./server/touchDesignerServer.js";
+export { createTouchDesignerClient, TouchDesignerClient, } from "./tdClient/index.js";

package/dist/mock/index.js

@@ -0,0 +1,5 @@
+async function initMocks() {
+    const { node } = await import("./node.js");
+    node.listen();
+}
+export { initMocks };

package/dist/mock/node.js

@@ -0,0 +1,3 @@
+import { setupServer } from "msw/node";
+import { getTouchDesignerAPIMock } from "../gen/endpoints/TouchDesignerAPI.js";
+export const node = setupServer(...getTouchDesignerAPIMock());

package/dist/server/connectionManager.js

@@ -0,0 +1,83 @@
+import { createErrorResult, createSuccessResult } from "../core/result.js";
+/**
+ * Manages the connection between TouchDesignerServer and MCP transport
+ */
+export class ConnectionManager {
+    server;
+    logger;
+    tdClient;
+    transport = null;
+    constructor(server, logger, tdClient) {
+        this.server = server;
+        this.logger = logger;
+        this.tdClient = tdClient;
+    }
+    /**
+     * Connect to MCP transport
+     */
+    async connect(transport) {
+        if (this.isConnected()) {
+            this.logger.log("MCP server already connected");
+            return createSuccessResult(undefined);
+        }
+        this.transport = transport;
+        try {
+            await this.server.connect(transport);
+            this.logger.log("Server connected and ready to process requests");
+            const connectionResult = await this.checkTDConnection();
+            if (!connectionResult.success) {
+                throw new Error(`Failed to connect to TouchDesigner: ${connectionResult.error.message}`);
+            }
+            return createSuccessResult(undefined);
+        }
+        catch (error) {
+            this.transport = null;
+            const err = error instanceof Error ? error : new Error(String(error));
+            console.error("Fatal error starting server! Check TouchDesigner setup and starting webserver.", err);
+            return createErrorResult(err);
+        }
+    }
+    /**
+     * Disconnect from MCP transport
+     */
+    async disconnect() {
+        if (!this.isConnected()) {
+            console.log("MCP server not connected");
+            return createSuccessResult(undefined);
+        }
+        try {
+            await this.server.close();
+            console.log("MCP server disconnected from MCP");
+            this.transport = null;
+            return createSuccessResult(undefined);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            console.error("Error disconnecting from server", err);
+            return createErrorResult(err);
+        }
+    }
+    /**
+     * Check if connected to MCP transport
+     */
+    isConnected() {
+        return this.transport !== null;
+    }
+    /**
+     * Check connection to TouchDesigner
+     */
+    async checkTDConnection() {
+        this.logger.log("Testing connection to TouchDesigner server...");
+        try {
+            const result = await this.tdClient.getTdInfo();
+            if (!result.success) {
+                throw result.error;
+            }
+            return createSuccessResult(result.data);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            return createErrorResult(err);
+        }
+    }
+}

package/dist/server/touchDesignerServer.js

@@ -0,0 +1,60 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpLogger } from "../core/logger.js";
+import { registerPrompts } from "../features/prompts/index.js";
+import { registerTools } from "../features/tools/index.js";
+import { createTouchDesignerClient } from "../tdClient/index.js";
+import { ConnectionManager } from "./connectionManager.js";
+/**
+ * TouchDesigner MCP Server implementation
+ */
+export class TouchDesignerServer {
+    server;
+    logger;
+    tdClient;
+    connectionManager;
+    /**
+     * Initialize TouchDesignerServer with proper dependency injection
+     */
+    constructor() {
+        this.server = new McpServer({
+            name: "TouchDesigner",
+            version: "0.2.1",
+        }, {
+            capabilities: {
+                prompts: {},
+                logging: {},
+                tools: {},
+            },
+        });
+        this.logger = new McpLogger(this.server);
+        this.tdClient = createTouchDesignerClient({ logger: this.logger });
+        this.connectionManager = new ConnectionManager(this.server, this.logger, this.tdClient);
+        this.registerAllFeatures();
+    }
+    /**
+     * Connect to MCP transport
+     */
+    async connect(transport) {
+        return this.connectionManager.connect(transport);
+    }
+    /**
+     * Disconnect from MCP transport
+     */
+    async disconnect() {
+        return this.connectionManager.disconnect();
+    }
+    /**
+     * Check if connected to MCP transport
+     */
+    isConnectedToMCP() {
+        return this.connectionManager.isConnected();
+    }
+    /**
+     * Register all features with the server
+     * Only called after all dependencies are initialized
+     */
+    registerAllFeatures() {
+        registerPrompts(this.server, this.logger);
+        registerTools(this.server, this.logger, this.tdClient);
+    }
+}

package/dist/tdClient/index.js

@@ -0,0 +1,6 @@
+import { TouchDesignerClient } from "./touchDesignerClient.js";
+export function createTouchDesignerClient(params) {
+    const { logger } = params;
+    return new TouchDesignerClient({ logger });
+}
+export { TouchDesignerClient } from "./touchDesignerClient.js";

package/dist/tdClient/touchDesignerClient.js

@@ -0,0 +1,150 @@
+import { createNode as apiCreateNode, deleteNode as apiDeleteNode, execNodeMethod as apiExecNodeMethod, execPythonScript as apiExecPythonScript, getNodeDetail as apiGetNodeDetail, getNodes as apiGetNodes, getTdInfo as apiGetTdInfo, getTdPythonClassDetails as apiGetTdPythonClassDetails, getTdPythonClasses as apiGetTdPythonClasses, updateNode as apiUpdateNode, } from "../gen/endpoints/TouchDesignerAPI.js";
+/**
+ * Default implementation of ITouchDesignerApi using generated API clients
+ */
+const defaultApiClient = {
+    execNodeMethod: apiExecNodeMethod,
+    execPythonScript: apiExecPythonScript,
+    getTdInfo: apiGetTdInfo,
+    getNodes: apiGetNodes,
+    getNodeDetail: apiGetNodeDetail,
+    createNode: apiCreateNode,
+    updateNode: apiUpdateNode,
+    deleteNode: apiDeleteNode,
+    getTdPythonClasses: apiGetTdPythonClasses,
+    getTdPythonClassDetails: apiGetTdPythonClassDetails,
+};
+/**
+ * Null logger implementation that discards all logs
+ */
+const nullLogger = {
+    debug: () => { },
+    log: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * Handle API error response
+ * @param response - API response object
+ * @returns ErrorResult object indicating failure
+ */
+function handleError(response) {
+    if (response.error) {
+        const errorMessage = response.error;
+        return { success: false, error: new Error(errorMessage) };
+    }
+    return { success: false, error: new Error("Unknown error occurred") };
+}
+/**
+ * Handle API response and return a structured result
+ * @param response - API response object
+ * @returns Result object indicating success or failure
+ */
+function handleApiResponse(response) {
+    const { success, data } = response;
+    if (!success) {
+        return handleError(response);
+    }
+    if (data === null) {
+        return { success: false, error: new Error("No data received") };
+    }
+    if (data === undefined) {
+        return { success: false, error: new Error("No data received") };
+    }
+    return { success: true, data };
+}
+/**
+ * TouchDesigner client implementation with dependency injection
+ * for better testability and separation of concerns
+ */
+export class TouchDesignerClient {
+    logger;
+    api;
+    /**
+     * Initialize TouchDesigner client with optional dependencies
+     */
+    constructor(params = {}) {
+        this.logger = params.logger || nullLogger;
+        this.api = params.httpClient || defaultApiClient;
+    }
+    /**
+     * Execute a node method
+     */
+    async execNodeMethod(params) {
+        this.logger.debug(`Executing node method: ${params.method} on ${params.nodePath}`);
+        const result = await this.api.execNodeMethod(params);
+        return handleApiResponse(result);
+    }
+    /**
+     * Execute a script in TouchDesigner
+     */
+    async execPythonScript(params) {
+        this.logger.debug(`Executing Python script: ${params}`);
+        const result = await this.api.execPythonScript(params);
+        return handleApiResponse(result);
+    }
+    /**
+     * Get TouchDesigner server information
+     */
+    async getTdInfo() {
+        this.logger.debug("Getting server info");
+        const result = await this.api.getTdInfo();
+        return handleApiResponse(result);
+    }
+    /**
+     * Get list of nodes
+     */
+    async getNodes(params) {
+        this.logger.debug(`Getting nodes for parent: ${params.parentPath}`);
+        const result = await this.api.getNodes(params);
+        return handleApiResponse(result);
+    }
+    /**
+     * Get node properties
+     */
+    async getNodeDetail(params) {
+        this.logger.debug(`Getting properties for node: ${params.nodePath}`);
+        const result = await this.api.getNodeDetail(params);
+        return handleApiResponse(result);
+    }
+    /**
+     * Create a new node
+     */
+    async createNode(params) {
+        this.logger.debug(`Creating node: ${params.nodeName} of type ${params.nodeType} under ${params.parentPath}`);
+        const result = await this.api.createNode(params);
+        return handleApiResponse(result);
+    }
+    /**
+     * Update node properties
+     */
+    async updateNode(params) {
+        this.logger.debug(`Updating node: ${params.nodePath}`);
+        const result = await this.api.updateNode(params);
+        return handleApiResponse(result);
+    }
+    /**
+     * Delete a node
+     */
+    async deleteNode(params) {
+        this.logger.debug(`Deleting node: ${params.nodePath}`);
+        const result = await this.api.deleteNode(params);
+        return handleApiResponse(result);
+    }
+    /**
+     * Get list of available Python classes/modules in TouchDesigner
+     */
+    async getClasses() {
+        this.logger.debug("Getting Python classes");
+        const result = await this.api.getTdPythonClasses();
+        return handleApiResponse(result);
+    }
+    /**
+     * Get details of a specific class/module
+     */
+    async getClassDetails(className) {
+        this.logger.debug(`Getting class details for: ${className}`);
+        const result = await this.api.getTdPythonClassDetails(className);
+        return handleApiResponse(result);
+    }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+	"name": "touchdesigner-mcp-server",
+	"version": "0.2.1",
+	"description": "MCP server for TouchDesigner",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/8beeeaaat/touchdesigner-mcp.git"
+	},
+	"keywords": [
+		"MCP",
+		"TouchDesigner"
+	],
+	"author": "8beeeaaat",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/8beeeaaat/touchdesigner-mcp/issues"
+	},
+	"homepage": "https://github.com/8beeeaaat/touchdesigner-mcp#readme",
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.10.2",
+		"@mozilla/readability": "^0.6.0",
+		"@types/axios": "^0.14.4",
+		"@types/ws": "^8.18.1",
+		"@types/yargs": "^17.0.33",
+		"axios": "^1.9.0",
+		"dotenv": "^16.5.0",
+		"zod": "^3.24.3"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "1.9.4",
+		"@faker-js/faker": "^9.7.0",
+		"@types/jsdom": "^21.1.7",
+		"@types/node": "^22.15.2",
+		"@vitest/coverage-v8": "^3.1.2",
+		"msw": "^2.7.5",
+		"mustache": "^4.2.0",
+		"npm-run-all": "^4.1.5",
+		"orval": "^7.9.0",
+		"typescript": "^5.8.3",
+		"vitest": "^3.1.2",
+		"yaml": "^2.7.1"
+	},
+	"type": "module",
+	"main": "src/index.ts",
+	"bin": {
+		"mcp-server": "dist/index.js"
+	},
+	"scripts": {
+		"build": "run-s build:*",
+		"build:gen": "npm run gen",
+		"build:dist": "tsc",
+		"lint": "run-p lint:*",
+		"lint:biome": "biome check",
+		"lint:tsc": "tsc --noEmit",
+		"format": "biome check --fix",
+		"dev": "npx @modelcontextprotocol/inspector node dist/index.js --stdio",
+		"test": "run-p test:*",
+		"test:integration": "vitest run ./tests/integration",
+		"test:unit": "vitest run ./tests/unit",
+		"coverage": "vitest run --coverage",
+		"gen": "run-s gen:*",
+		"gen:webserver": "docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate -i /local/src/api/index.yml -g python-flask -o /local/td/modules/td_server",
+		"gen:handlers": "node td/genHandlers.js",
+		"gen:mcp": "orval --config ./orval.config.ts"
+	},
+	"files": [
+		"dist/**/*",
+		"td/**/*",
+		"README*"
+	],
+	"msw": {
+		"workerDirectory": [
+			"public"
+		]
+	}
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { startServer } from "./cli.js";
+export { TouchDesignerServer } from "./server/touchDesignerServer.js";
+export {
+	createTouchDesignerClient,
+	TouchDesignerClient,
+} from "./tdClient/index.js";

package/td/genHandlers.js

@@ -0,0 +1,47 @@
+import path from "node:path";
+import fs from "fs-extra";
+import mustache from "mustache";
+import yaml from "yaml";
+
+const openapiPath = path.resolve(
+	"td/modules/td_server/openapi_server/openapi/openapi.yaml",
+);
+const templatePath = path.resolve(
+	"td/templates/mcp/api_controller_handlers.mustache",
+);
+const outputPath = path.resolve(
+	"td/modules/mcp/controllers/generated_handlers.py",
+);
+
+async function generateHandlers() {
+	try {
+		const yamlContent = await fs.readFile(openapiPath, "utf-8");
+		const openapiDoc = yaml.parse(yamlContent);
+		const operations = [];
+
+		if (openapiDoc.paths) {
+			for (const pathKey of Object.keys(openapiDoc.paths)) {
+				const methods = openapiDoc.paths[pathKey];
+				for (const methodKey of Object.keys(methods)) {
+					const operation = methods[methodKey];
+					if (operation.operationId) {
+						operations.push({ operationId: operation.operationId });
+					}
+				}
+			}
+		}
+		const template = await fs.readFile(templatePath, "utf-8");
+		const rendered = mustache.render(template, {
+			operations,
+		});
+
+		await fs.outputFile(outputPath, rendered);
+
+		console.log("✅ generated_handlers.py created successfully!");
+	} catch (error) {
+		console.error("❌ Error generating handlers:", error);
+		process.exit(1);
+	}
+}
+
+generateHandlers();