touchdesigner-mcp-server 1.3.0 → 1.4.0

package/dist/tdClient/touchDesignerClient.js

@@ -1,12 +1,8 @@
+import axios from "axios";
+import { getCompatibilityPolicy, getCompatibilityPolicyType, } from "../core/compatibility.js";
 import { createErrorResult, createSuccessResult } from "../core/result.js";
-import { PACKAGE_VERSION } from "../core/version.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";
-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
  */
@@ -24,6 +20,7 @@ const defaultApiClient = {
     getTdPythonClasses: apiGetTdPythonClasses,
     updateNode: apiUpdateNode,
 };
+export const ERROR_CACHE_TTL_MS = 5000; // 5 seconds
 /**
  * Null logger implementation that discards all logs
  */
@@ -68,6 +65,21 @@ 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({
@@ -76,176 +88,284 @@ export class TouchDesignerClient {
             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;
     }
     /**
-     * Initialize TouchDesigner client with optional dependencies
+     * Wrapper for API calls that require compatibility verification
+     * @private
      */
-    constructor(params = {}) {
-        this.logger = params.logger || nullLogger;
-        this.api = params.httpClient || defaultApiClient;
-        this.verifiedCompatibilityError = null;
+    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.logDebug("Executing node method", {
+        return this.apiCall("Executing node method", () => this.api.execNodeMethod(params), {
             method: params.method,
             nodePath: params.nodePath,
         });
-        await this.verifyCompatibility();
-        const result = await this.api.execNodeMethod(params);
-        return handleApiResponse(result);
     }
     /**
      * Execute a script in TouchDesigner
      */
     async execPythonScript(params) {
-        this.logDebug("Executing Python script", { params });
-        await this.verifyCompatibility();
-        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.logDebug("Getting server info");
-        await this.verifyCompatibility();
-        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.logDebug("Getting nodes for parent", {
-            parentPath: params.parentPath,
-        });
-        await this.verifyCompatibility();
-        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.logDebug("Getting properties for node", {
-            nodePath: params.nodePath,
-        });
-        await this.verifyCompatibility();
-        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) {
-        this.logDebug("Checking node errors", {
-            nodePath: params.nodePath,
-        });
-        await this.verifyCompatibility();
-        const result = await this.api.getNodeErrors(params);
-        return handleApiResponse(result);
+        return this.apiCall("Checking node errors", () => this.api.getNodeErrors(params), { nodePath: params.nodePath });
     }
     /**
      * Create a new node
      */
     async createNode(params) {
-        this.logDebug("Creating node", {
+        return this.apiCall("Creating node", () => this.api.createNode(params), {
             nodeName: params.nodeName,
             nodeType: params.nodeType,
             parentPath: params.parentPath,
         });
-        await this.verifyCompatibility();
-        const result = await this.api.createNode(params);
-        return handleApiResponse(result);
     }
     /**
      * Update node properties
      */
     async updateNode(params) {
-        this.logDebug("Updating node", { nodePath: params.nodePath });
-        await this.verifyCompatibility();
-        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.logDebug("Deleting node", { nodePath: params.nodePath });
-        await this.verifyCompatibility();
-        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.logDebug("Getting Python classes");
-        await this.verifyCompatibility();
-        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.logDebug("Getting class details", { className });
-        await this.verifyCompatibility();
-        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) {
-        this.logDebug("Getting module help", { moduleName: params.moduleName });
-        await this.verifyCompatibility();
-        const result = await this.api.getModuleHelp(params);
-        return handleApiResponse(result);
+        return this.apiCall("Getting module help", () => this.api.getModuleHelp(params), { moduleName: params.moduleName });
     }
     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}`));
+        let tdInfoResult;
+        try {
+            tdInfoResult = await this.api.getTdInfo();
         }
-        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}`));
+        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));
         }
-        const normalizedServerVersion = this.normalizeVersion(PACKAGE_VERSION);
-        const normalizedApiVersion = this.normalizeVersion(apiVersion);
-        if (normalizedServerVersion !== normalizedApiVersion) {
+        if (!tdInfoResult.success) {
+            const errorMessage = this.formatConnectionError(tdInfoResult.error);
             this.logger.sendLog({
-                data: {
-                    message: "MCP server and TouchDesigner API server versions are incompatible",
-                    touchDesignerApiVersion: normalizedApiVersion,
-                    touchDesignerServerVersion: normalizedServerVersion,
-                },
+                data: { error: tdInfoResult.error, errorType: "api_response" },
                 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 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);
     }
-    normalizeVersion(version) {
-        return version.trim().replace(/^v/i, "");
+    /**
+     * 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/dist/transport/config.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/**
+ * Zod schema for SessionConfig validation
+ */
+const SessionConfigSchema = z
+    .object({
+    cleanupInterval: z.number().int().positive().optional(),
+    enabled: z.boolean(),
+    ttl: z.number().int().positive().optional(),
+})
+    .strict();
+/**
+ * Zod schema for StdioTransportConfig validation
+ */
+const StdioTransportConfigSchema = z
+    .object({
+    type: z.literal("stdio"),
+})
+    .strict();
+/**
+ * Zod schema for StreamableHttpTransportConfig validation
+ */
+const StreamableHttpTransportConfigSchema = z
+    .object({
+    endpoint: z
+        .string()
+        .min(1, "Endpoint cannot be empty")
+        .regex(/^\//, "Endpoint must start with /"),
+    host: z.string().min(1, "Host cannot be empty"),
+    port: z
+        .number()
+        .int()
+        .positive()
+        .min(1)
+        .max(65535, "Port must be between 1 and 65535"),
+    retryInterval: z.number().int().positive().optional(),
+    sessionConfig: SessionConfigSchema.optional(),
+    type: z.literal("streamable-http"),
+})
+    .strict();
+/**
+ * Zod schema for TransportConfig validation (discriminated union)
+ */
+export const TransportConfigSchema = z.discriminatedUnion("type", [
+    StdioTransportConfigSchema,
+    StreamableHttpTransportConfigSchema,
+]);
+/**
+ * Type guard to check if config is StdioTransportConfig
+ */
+export function isStdioTransportConfig(config) {
+    return config.type === "stdio";
+}
+/**
+ * Type guard to check if config is StreamableHttpTransportConfig
+ */
+export function isStreamableHttpTransportConfig(config) {
+    return config.type === "streamable-http";
+}
+/**
+ * Default values for SessionConfig
+ */
+export const DEFAULT_SESSION_CONFIG = {
+    cleanupInterval: 5 * 60 * 1000, // 5 minutes
+    enabled: true,
+    ttl: 60 * 60 * 1000, // 1 hour
+};
+/**
+ * Default values for StreamableHttpTransportConfig (excluding required fields)
+ */
+export const DEFAULT_HTTP_CONFIG = {
+    endpoint: "/mcp",
+    host: "127.0.0.1",
+    sessionConfig: DEFAULT_SESSION_CONFIG,
+};