touchdesigner-mcp-server 1.2.0 → 1.3.0

package/dist/tdClient/touchDesignerClient.js

@@ -1,27 +1,34 @@
-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";
+import { createErrorResult, createSuccessResult } from "../core/result.js";
+import { PACKAGE_VERSION } from "../core/version.js";
+import { createNode as apiCreateNode, deleteNode as apiDeleteNode, execNodeMethod as apiExecNodeMethod, execPythonScript as apiExecPythonScript, getModuleHelp as apiGetModuleHelp, getNodeDetail as apiGetNodeDetail, getNodeErrors as apiGetNodeErrors, getNodes as apiGetNodes, getTdInfo as apiGetTdInfo, getTdPythonClassDetails as apiGetTdPythonClassDetails, getTdPythonClasses as apiGetTdPythonClasses, updateNode as apiUpdateNode, } from "../gen/endpoints/TouchDesignerAPI.js";
+const updateGuide = `
+	1. Download the latest [touchdesigner-mcp-td.zip](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest/download/touchdesigner-mcp-td.zip) from the releases page.
+	2. Delete the existing \`touchdesigner-mcp-td\` folder and replace it with the newly extracted contents.
+	3. Remove the old \`mcp_webserver_base\` component from your TouchDesigner project and import the \`.tox\` from the new folder.
+	4. Restart TouchDesigner and the AI agent running the MCP server (e.g., Claude Desktop).
+`;
 /**
  * Default implementation of ITouchDesignerApi using generated API clients
  */
 const defaultApiClient = {
+    createNode: apiCreateNode,
+    deleteNode: apiDeleteNode,
     execNodeMethod: apiExecNodeMethod,
     execPythonScript: apiExecPythonScript,
-    getTdInfo: apiGetTdInfo,
-    getNodes: apiGetNodes,
+    getModuleHelp: apiGetModuleHelp,
     getNodeDetail: apiGetNodeDetail,
-    createNode: apiCreateNode,
-    updateNode: apiUpdateNode,
-    deleteNode: apiDeleteNode,
-    getTdPythonClasses: apiGetTdPythonClasses,
+    getNodeErrors: apiGetNodeErrors,
+    getNodes: apiGetNodes,
+    getTdInfo: apiGetTdInfo,
     getTdPythonClassDetails: apiGetTdPythonClassDetails,
+    getTdPythonClasses: apiGetTdPythonClasses,
+    updateNode: apiUpdateNode,
 };
 /**
  * Null logger implementation that discards all logs
  */
 const nullLogger = {
-    debug: () => { },
-    log: () => { },
-    warn: () => { },
-    error: () => { },
+    sendLog: () => { },
 };
 /**
  * Handle API error response
@@ -31,9 +38,9 @@ const nullLogger = {
 function handleError(response) {
     if (response.error) {
         const errorMessage = response.error;
-        return { success: false, error: new Error(errorMessage) };
+        return { error: new Error(errorMessage), success: false };
     }
-    return { success: false, error: new Error("Unknown error occurred") };
+    return { error: new Error("Unknown error occurred"), success: false };
 }
 /**
  * Handle API response and return a structured result
@@ -46,12 +53,12 @@ function handleApiResponse(response) {
         return handleError(response);
     }
     if (data === null) {
-        return { success: false, error: new Error("No data received") };
+        return { error: new Error("No data received"), success: false };
     }
     if (data === undefined) {
-        return { success: false, error: new Error("No data received") };
+        return { error: new Error("No data received"), success: false };
     }
-    return { success: true, data };
+    return { data, success: true };
 }
 /**
  * TouchDesigner client implementation with dependency injection
@@ -60,18 +67,47 @@ function handleApiResponse(response) {
 export class TouchDesignerClient {
     logger;
     api;
+    verifiedCompatibilityError;
+    logDebug(message, context) {
+        const data = context ? { message, ...context } : { message };
+        this.logger.sendLog({
+            data,
+            level: "debug",
+            logger: "TouchDesignerClient",
+        });
+    }
+    /**
+     * Verify compatibility with the TouchDesigner server
+     */
+    async verifyCompatibility() {
+        if (this.verifiedCompatibilityError) {
+            throw this.verifiedCompatibilityError;
+        }
+        const result = await this.verifyVersionCompatibility();
+        if (result.success) {
+            this.verifiedCompatibilityError = null;
+            return;
+        }
+        this.verifiedCompatibilityError = result.error;
+        throw result.error;
+    }
     /**
      * Initialize TouchDesigner client with optional dependencies
      */
     constructor(params = {}) {
         this.logger = params.logger || nullLogger;
         this.api = params.httpClient || defaultApiClient;
+        this.verifiedCompatibilityError = null;
     }
     /**
      * Execute a node method
      */
     async execNodeMethod(params) {
-        this.logger.debug(`Executing node method: ${params.method} on ${params.nodePath}`);
+        this.logDebug("Executing node method", {
+            method: params.method,
+            nodePath: params.nodePath,
+        });
+        await this.verifyCompatibility();
         const result = await this.api.execNodeMethod(params);
         return handleApiResponse(result);
     }
@@ -79,7 +115,8 @@ export class TouchDesignerClient {
      * Execute a script in TouchDesigner
      */
     async execPythonScript(params) {
-        this.logger.debug(`Executing Python script: ${params}`);
+        this.logDebug("Executing Python script", { params });
+        await this.verifyCompatibility();
         const result = await this.api.execPythonScript(params);
         return handleApiResponse(result);
     }
@@ -87,7 +124,8 @@ export class TouchDesignerClient {
      * Get TouchDesigner server information
      */
     async getTdInfo() {
-        this.logger.debug("Getting server info");
+        this.logDebug("Getting server info");
+        await this.verifyCompatibility();
         const result = await this.api.getTdInfo();
         return handleApiResponse(result);
     }
@@ -95,7 +133,10 @@ export class TouchDesignerClient {
      * Get list of nodes
      */
     async getNodes(params) {
-        this.logger.debug(`Getting nodes for parent: ${params.parentPath}`);
+        this.logDebug("Getting nodes for parent", {
+            parentPath: params.parentPath,
+        });
+        await this.verifyCompatibility();
         const result = await this.api.getNodes(params);
         return handleApiResponse(result);
     }
@@ -103,15 +144,34 @@ export class TouchDesignerClient {
      * Get node properties
      */
     async getNodeDetail(params) {
-        this.logger.debug(`Getting properties for node: ${params.nodePath}`);
+        this.logDebug("Getting properties for node", {
+            nodePath: params.nodePath,
+        });
+        await this.verifyCompatibility();
         const result = await this.api.getNodeDetail(params);
         return handleApiResponse(result);
     }
+    /**
+     * Get node error information
+     */
+    async getNodeErrors(params) {
+        this.logDebug("Checking node errors", {
+            nodePath: params.nodePath,
+        });
+        await this.verifyCompatibility();
+        const result = await this.api.getNodeErrors(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}`);
+        this.logDebug("Creating node", {
+            nodeName: params.nodeName,
+            nodeType: params.nodeType,
+            parentPath: params.parentPath,
+        });
+        await this.verifyCompatibility();
         const result = await this.api.createNode(params);
         return handleApiResponse(result);
     }
@@ -119,7 +179,8 @@ export class TouchDesignerClient {
      * Update node properties
      */
     async updateNode(params) {
-        this.logger.debug(`Updating node: ${params.nodePath}`);
+        this.logDebug("Updating node", { nodePath: params.nodePath });
+        await this.verifyCompatibility();
         const result = await this.api.updateNode(params);
         return handleApiResponse(result);
     }
@@ -127,7 +188,8 @@ export class TouchDesignerClient {
      * Delete a node
      */
     async deleteNode(params) {
-        this.logger.debug(`Deleting node: ${params.nodePath}`);
+        this.logDebug("Deleting node", { nodePath: params.nodePath });
+        await this.verifyCompatibility();
         const result = await this.api.deleteNode(params);
         return handleApiResponse(result);
     }
@@ -135,7 +197,8 @@ export class TouchDesignerClient {
      * Get list of available Python classes/modules in TouchDesigner
      */
     async getClasses() {
-        this.logger.debug("Getting Python classes");
+        this.logDebug("Getting Python classes");
+        await this.verifyCompatibility();
         const result = await this.api.getTdPythonClasses();
         return handleApiResponse(result);
     }
@@ -143,8 +206,46 @@ export class TouchDesignerClient {
      * Get details of a specific class/module
      */
     async getClassDetails(className) {
-        this.logger.debug(`Getting class details for: ${className}`);
+        this.logDebug("Getting class details", { className });
+        await this.verifyCompatibility();
         const result = await this.api.getTdPythonClassDetails(className);
         return handleApiResponse(result);
     }
+    /**
+     * Retrieve Python help() documentation for modules/classes
+     */
+    async getModuleHelp(params) {
+        this.logDebug("Getting module help", { moduleName: params.moduleName });
+        await this.verifyCompatibility();
+        const result = await this.api.getModuleHelp(params);
+        return handleApiResponse(result);
+    }
+    async verifyVersionCompatibility() {
+        const tdInfoResult = await this.api.getTdInfo();
+        if (!tdInfoResult.success) {
+            return createErrorResult(new Error(`Failed to retrieve TouchDesigner info for version check: ${tdInfoResult.error}`));
+        }
+        const apiVersion = tdInfoResult.data?.mcpApiVersion?.trim();
+        if (!apiVersion) {
+            return createErrorResult(new Error(`TouchDesigner API server did not report its version. Please reinstall the TouchDesigner components from the latest release.\n${updateGuide}`));
+        }
+        const normalizedServerVersion = this.normalizeVersion(PACKAGE_VERSION);
+        const normalizedApiVersion = this.normalizeVersion(apiVersion);
+        if (normalizedServerVersion !== normalizedApiVersion) {
+            this.logger.sendLog({
+                data: {
+                    message: "MCP server and TouchDesigner API server versions are incompatible",
+                    touchDesignerApiVersion: normalizedApiVersion,
+                    touchDesignerServerVersion: normalizedServerVersion,
+                },
+                level: "error",
+                logger: "TouchDesignerClient",
+            });
+            return createErrorResult(new Error(`Version mismatch detected between MCP server (${normalizedServerVersion}) and TouchDesigner API server (${normalizedApiVersion}). Update both components to the same release.\n${updateGuide}`));
+        }
+        return createSuccessResult(undefined);
+    }
+    normalizeVersion(version) {
+        return version.trim().replace(/^v/i, "");
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",
@@ -23,30 +23,31 @@
 		"touchdesigner-mcp-server": "dist/cli.js"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.18.0",
+		"@modelcontextprotocol/sdk": "^1.23.0",
 		"@mozilla/readability": "^0.6.0",
 		"@types/axios": "^0.14.4",
 		"@types/ws": "^8.18.1",
-		"@types/yargs": "^17.0.33",
-		"axios": "^1.12.2",
+		"@types/yargs": "^17.0.35",
+		"axios": "^1.13.2",
 		"mustache": "^4.2.0",
-		"yaml": "^2.8.1",
-		"zod": "3.25.76"
+		"yaml": "^2.8.2",
+		"zod": "4.1.13"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.2.4",
-		"@openapitools/openapi-generator-cli": "^2.23.1",
-		"@types/jsdom": "^21.1.7",
+		"@biomejs/biome": "2.3.8",
+		"@openapitools/openapi-generator-cli": "^2.25.2",
+		"@types/jsdom": "^27.0.0",
 		"@types/mustache": "^4.2.6",
-		"@types/node": "^24.4.0",
-		"@vitest/coverage-v8": "^3.2.4",
+		"@types/node": "^24.10.1",
+		"@vitest/coverage-v8": "^4.0.14",
 		"archiver": "^7.0.1",
-		"msw": "^2.11.2",
+		"msw": "^2.12.3",
 		"npm-run-all": "^4.1.5",
-		"orval": "^7.11.2",
+		"orval": "^7.17.0",
+		"prettier": "^3.7.3",
 		"shx": "^0.4.0",
-		"typescript": "^5.9.2",
-		"vitest": "^3.2.4"
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.14"
 	},
 	"type": "module",
 	"exports": {
@@ -67,13 +68,19 @@
 		"lint": "run-p lint:*",
 		"lint:biome": "biome check",
 		"lint:tsc": "tsc --noEmit",
-		"format": "biome check --fix",
+		"lint:python": "ruff check td/",
+		"lint:yaml": "prettier --check \"**/*.{yml,yaml}\"",
+		"format": "run-p format:*",
+		"format:biome": "biome check --fix",
+		"format:python": "ruff format td/ && ruff check --fix td/",
+		"format:yaml": "prettier --write \"**/*.{yml,yaml}\"",
 		"dev": "npx @modelcontextprotocol/inspector node dist/cli.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:version": "node ./scripts/syncVersions.ts",
 		"gen:webserver": "openapi-generator-cli generate -i ./src/api/index.yml -g python-flask -o ./td/modules/td_server",
 		"gen:handlers": "node td/genHandlers.js",
 		"gen:mcp": "orval --config ./orval.config.ts"
@@ -87,6 +94,6 @@
 		]
 	},
 	"overrides": {
-		"axios": "^1.12.2"
+		"axios": "^1.13.2"
 	}
 }