touchdesigner-mcp-server 1.2.0 → 1.3.1

package/dist/tdClient/touchDesignerClient.js

@@ -1,27 +1,31 @@
-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 axios from "axios";
+import { getCompatibilityPolicy, getCompatibilityPolicyType, } from "../core/compatibility.js";
+import { createErrorResult, createSuccessResult } from "../core/result.js";
+import { MCP_SERVER_VERSION, MIN_COMPATIBLE_API_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";
 /**
  * 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,
 };
+export const ERROR_CACHE_TTL_MS = 5000; // 5 seconds
 /**
  * Null logger implementation that discards all logs
  */
 const nullLogger = {
-    debug: () => { },
-    log: () => { },
-    warn: () => { },
-    error: () => { },
+    sendLog: () => { },
 };
 /**
  * Handle API error response
@@ -31,9 +35,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 +50,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,91 +64,308 @@ function handleApiResponse(response) {
 export class TouchDesignerClient {
     logger;
     api;
+    verifiedCompatibilityError;
+    cachedCompatibilityCheck;
+    errorCacheTimestamp;
     /**
      * Initialize TouchDesigner client with optional dependencies
      */
     constructor(params = {}) {
         this.logger = params.logger || nullLogger;
         this.api = params.httpClient || defaultApiClient;
+        this.verifiedCompatibilityError = null;
+        this.cachedCompatibilityCheck = false;
+        this.errorCacheTimestamp = null;
+    }
+    /**
+     * Log debug message
+     */
+    logDebug(message, context) {
+        const data = context ? { message, ...context } : { message };
+        this.logger.sendLog({
+            data,
+            level: "debug",
+            logger: "TouchDesignerClient",
+        });
+    }
+    /**
+     * Check if the cached error should be cleared (TTL expired)
+     */
+    shouldClearErrorCache() {
+        if (!this.errorCacheTimestamp) {
+            return false;
+        }
+        const now = Date.now();
+        return now - this.errorCacheTimestamp >= ERROR_CACHE_TTL_MS;
+    }
+    /**
+     * Verify compatibility with the TouchDesigner server
+     */
+    async verifyCompatibility() {
+        // If we've already verified compatibility successfully, skip re-verification
+        if (this.cachedCompatibilityCheck && !this.verifiedCompatibilityError) {
+            return;
+        }
+        // Clear cached error if TTL has expired
+        if (this.verifiedCompatibilityError && this.shouldClearErrorCache()) {
+            this.logDebug("Clearing cached connection error (TTL expired), retrying...");
+            this.verifiedCompatibilityError = null;
+            this.errorCacheTimestamp = null;
+            this.cachedCompatibilityCheck = false;
+        }
+        if (this.verifiedCompatibilityError) {
+            // Re-log the cached error so users know it's still failing
+            const ttlRemaining = this.errorCacheTimestamp
+                ? Math.max(0, Math.ceil((ERROR_CACHE_TTL_MS - (Date.now() - this.errorCacheTimestamp)) /
+                    1000))
+                : 0;
+            this.logDebug(`Using cached connection error (retry in ${ttlRemaining} seconds)`, {
+                cacheAge: this.errorCacheTimestamp
+                    ? Date.now() - this.errorCacheTimestamp
+                    : 0,
+                cachedError: this.verifiedCompatibilityError.message,
+            });
+            throw this.verifiedCompatibilityError;
+        }
+        const result = await this.verifyVersionCompatibility();
+        if (result.success) {
+            this.verifiedCompatibilityError = null;
+            this.errorCacheTimestamp = null;
+            this.cachedCompatibilityCheck = true;
+            this.logDebug("Compatibility verified successfully");
+            return;
+        }
+        // Log when we're caching a NEW error
+        this.logDebug(`Caching connection error for ${ERROR_CACHE_TTL_MS / 1000} seconds`, {
+            error: result.error.message,
+        });
+        this.verifiedCompatibilityError = result.error;
+        this.errorCacheTimestamp = Date.now();
+        this.cachedCompatibilityCheck = false;
+        throw result.error;
+    }
+    /**
+     * Wrapper for API calls that require compatibility verification
+     * @private
+     */
+    async apiCall(message, call, context) {
+        this.logDebug(message, context);
+        await this.verifyCompatibility();
+        const result = await call();
+        return handleApiResponse(result);
     }
     /**
      * 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);
+        return this.apiCall("Executing node method", () => this.api.execNodeMethod(params), {
+            method: params.method,
+            nodePath: params.nodePath,
+        });
     }
     /**
      * 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);
+        return this.apiCall("Executing Python script", () => this.api.execPythonScript(params), { params });
     }
     /**
      * Get TouchDesigner server information
      */
     async getTdInfo() {
-        this.logger.debug("Getting server info");
-        const result = await this.api.getTdInfo();
-        return handleApiResponse(result);
+        return this.apiCall("Getting server info", () => this.api.getTdInfo());
     }
     /**
      * 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);
+        return this.apiCall("Getting nodes for parent", () => this.api.getNodes(params), { parentPath: params.parentPath });
     }
     /**
      * 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);
+        return this.apiCall("Getting properties for node", () => this.api.getNodeDetail(params), { nodePath: params.nodePath });
+    }
+    /**
+     * Get node error information
+     */
+    async getNodeErrors(params) {
+        return this.apiCall("Checking node errors", () => this.api.getNodeErrors(params), { nodePath: params.nodePath });
     }
     /**
      * 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);
+        return this.apiCall("Creating node", () => this.api.createNode(params), {
+            nodeName: params.nodeName,
+            nodeType: params.nodeType,
+            parentPath: params.parentPath,
+        });
     }
     /**
      * Update node properties
      */
     async updateNode(params) {
-        this.logger.debug(`Updating node: ${params.nodePath}`);
-        const result = await this.api.updateNode(params);
-        return handleApiResponse(result);
+        return this.apiCall("Updating node", () => this.api.updateNode(params), {
+            nodePath: params.nodePath,
+        });
     }
     /**
      * Delete a node
      */
     async deleteNode(params) {
-        this.logger.debug(`Deleting node: ${params.nodePath}`);
-        const result = await this.api.deleteNode(params);
-        return handleApiResponse(result);
+        return this.apiCall("Deleting node", () => this.api.deleteNode(params), {
+            nodePath: params.nodePath,
+        });
     }
     /**
      * 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);
+        return this.apiCall("Getting Python classes", () => this.api.getTdPythonClasses());
     }
     /**
      * 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);
+        return this.apiCall("Getting class details", () => this.api.getTdPythonClassDetails(className), { className });
+    }
+    /**
+     * Retrieve Python help() documentation for modules/classes
+     */
+    async getModuleHelp(params) {
+        return this.apiCall("Getting module help", () => this.api.getModuleHelp(params), { moduleName: params.moduleName });
+    }
+    async verifyVersionCompatibility() {
+        let tdInfoResult;
+        try {
+            tdInfoResult = await this.api.getTdInfo();
+        }
+        catch (error) {
+            // Use axios.isAxiosError() for robust network/HTTP error detection
+            // AxiosError includes connection refused, timeout, network errors, etc.
+            // All other errors (TypeError, etc.) are programming errors and should propagate
+            if (!axios.isAxiosError(error)) {
+                // This is a programming error (e.g., TypeError, ReferenceError), not a connection error
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const errorStack = error instanceof Error ? error.stack : undefined;
+                this.logger.sendLog({
+                    data: {
+                        error: errorMessage,
+                        errorType: "programming_error",
+                        stack: errorStack,
+                    },
+                    level: "error",
+                    logger: "TouchDesignerClient",
+                });
+                throw error;
+            }
+            // Handle AxiosError (network/HTTP errors)
+            const rawMessage = error.message || "Unknown network error";
+            const errorMessage = this.formatConnectionError(rawMessage);
+            this.logger.sendLog({
+                data: { error: rawMessage, errorType: "connection" },
+                level: "error",
+                logger: "TouchDesignerClient",
+            });
+            return createErrorResult(new Error(errorMessage));
+        }
+        if (!tdInfoResult.success) {
+            const errorMessage = this.formatConnectionError(tdInfoResult.error);
+            this.logger.sendLog({
+                data: { error: tdInfoResult.error, errorType: "api_response" },
+                level: "error",
+                logger: "TouchDesignerClient",
+            });
+            return createErrorResult(new Error(errorMessage));
+        }
+        const apiVersionRaw = tdInfoResult.data?.mcpApiVersion?.trim() || "";
+        const result = this.checkVersionCompatibility(MCP_SERVER_VERSION, apiVersionRaw);
+        this.logger.sendLog({
+            data: {
+                apiVersion: result.details.apiVersion,
+                mcpVersion: result.details.mcpVersion,
+                message: result.message,
+                minRequired: result.details.minRequired,
+            },
+            level: result.level,
+            logger: "TouchDesignerClient",
+        });
+        if (result.level === "error") {
+            return createErrorResult(new Error(result.message));
+        }
+        return createSuccessResult(undefined);
+    }
+    /**
+     * Format connection errors with helpful messages
+     */
+    formatConnectionError(error) {
+        if (!error) {
+            return "Failed to connect to TouchDesigner API server (unknown error)";
+        }
+        // Check for common connection errors
+        if (error.includes("ECONNREFUSED") ||
+            error.toLowerCase().includes("connect refused")) {
+            return `🔌 TouchDesigner Connection Failed
+
+Cannot connect to TouchDesigner API server at the configured address.
+
+Possible causes:
+  1. TouchDesigner is not running
+     → Please start TouchDesigner
+
+  2. WebServer DAT is not active
+     → Import 'mcp_webserver_base.tox' and ensure it's active
+
+  3. Wrong port configuration
+     → Default port is 9981, check your configuration
+
+For setup instructions, visit:
+https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest
+
+Original error: ${error}`;
+        }
+        if (error.includes("ETIMEDOUT") || error.includes("timeout")) {
+            return `⏱️  TouchDesigner Connection Timeout
+
+The connection to TouchDesigner timed out.
+
+Possible causes:
+  1. TouchDesigner is slow to respond
+  2. Network issues
+  3. WebServer DAT is overloaded
+
+Try restarting TouchDesigner or check the network connection.
+
+Original error: ${error}`;
+        }
+        if (error.includes("ENOTFOUND") || error.includes("getaddrinfo")) {
+            return `🌐 Invalid Host Configuration
+
+Cannot resolve the TouchDesigner API server hostname.
+
+Please check your host configuration (default: 127.0.0.1)
+
+Original error: ${error}`;
+        }
+        // Generic error message
+        return `Failed to connect to TouchDesigner API server: ${error}`;
+    }
+    checkVersionCompatibility(mcpVersion, apiVersion) {
+        const policyType = getCompatibilityPolicyType({ apiVersion, mcpVersion });
+        const policy = getCompatibilityPolicy(policyType);
+        const details = {
+            apiVersion,
+            mcpVersion,
+            minRequired: MIN_COMPATIBLE_API_VERSION,
+        };
+        const message = policy.message(details);
+        return {
+            compatible: policy.compatible,
+            details,
+            level: policy.level,
+            message,
+        };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "1.2.0",
+	"version": "1.3.1",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",
@@ -13,6 +13,9 @@
 	"author": "8beeeaaat",
 	"license": "MIT",
 	"mcpName": "io.github.8beeeaaat/touchdesigner-mcp-server",
+	"mcpCompatibility": {
+		"minApiVersion": "1.3.0"
+	},
 	"bugs": {
 		"url": "https://github.com/8beeeaaat/touchdesigner-mcp/issues"
 	},
@@ -23,30 +26,33 @@
 		"touchdesigner-mcp-server": "dist/cli.js"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.18.0",
+		"@modelcontextprotocol/sdk": "^1.24.3",
 		"@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"
+		"semver": "^7.7.3",
+		"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",
+		"@types/semver": "^7.7.1",
+		"@vitest/coverage-v8": "^4.0.15",
 		"archiver": "^7.0.1",
-		"msw": "^2.11.2",
+		"msw": "^2.12.4",
 		"npm-run-all": "^4.1.5",
-		"orval": "^7.11.2",
+		"orval": "^7.17.0",
+		"prettier": "^3.7.4",
 		"shx": "^0.4.0",
-		"typescript": "^5.9.2",
-		"vitest": "^3.2.4"
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.15"
 	},
 	"type": "module",
 	"exports": {
@@ -67,12 +73,20 @@
 		"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",
+		"version": "run-p version:*",
+		"version:api": "node ./scripts/syncApiServerVersions.ts",
+		"version:mcp": "node ./scripts/syncMcpServerVersions.ts",
 		"gen": "run-s gen:*",
 		"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",
@@ -87,6 +101,6 @@
 		]
 	},
 	"overrides": {
-		"axios": "^1.12.2"
+		"axios": "^1.13.2"
 	}
 }