touchdesigner-mcp-server 1.3.0 → 1.4.0

package/dist/core/compatibility.js

@@ -0,0 +1,236 @@
+import semver from "semver";
+import { MIN_COMPATIBLE_API_VERSION } from "./version.js";
+export const COMPATIBILITY_POLICY_TYPES = {
+    BELOW_MIN_VERSION: "belowMinVersion",
+    COMPATIBLE: "compatible",
+    MAJOR_MISMATCH: "majorMismatch",
+    NEWER_MINOR: "newerMinor",
+    NO_VERSION: "noVersion",
+    OLDER_MINOR: "olderMinor",
+    PATCH_DIFF: "patchDiff",
+};
+export const COMPATIBILITY_POLICY_ERROR_LEVELS = {
+    ALLOW: "info",
+    ERROR: "error",
+    WARNING: "warning",
+};
+/**
+ * Compatibility policy configuration
+ */
+const COMPATIBILITY_POLICY = {
+    /**
+     * Behavior when no version information is available
+     * - 'error': Stop processing with error
+     */
+    [COMPATIBILITY_POLICY_TYPES.NO_VERSION]: {
+        compatible: false,
+        level: COMPATIBILITY_POLICY_ERROR_LEVELS.ERROR,
+        message: generateNoVersionMessage,
+    },
+    /**
+     * Behavior when API server version is below minimum required version
+     * - 'error': Stop processing with error
+     */
+    [COMPATIBILITY_POLICY_TYPES.BELOW_MIN_VERSION]: {
+        compatible: false,
+        level: COMPATIBILITY_POLICY_ERROR_LEVELS.ERROR,
+        message: generateMinVersionMessage,
+    },
+    /**
+     * Behavior when MAJOR versions differ
+     * - 'error': Stop processing with error
+     */
+    [COMPATIBILITY_POLICY_TYPES.MAJOR_MISMATCH]: {
+        compatible: false,
+        level: COMPATIBILITY_POLICY_ERROR_LEVELS.ERROR,
+        message: generateMajorMismatchMessage,
+    },
+    /**
+     * Behavior when MCP server has newer MINOR version than API server
+     * - 'warning': Continue with warning only
+     */
+    [COMPATIBILITY_POLICY_TYPES.NEWER_MINOR]: {
+        compatible: true,
+        level: COMPATIBILITY_POLICY_ERROR_LEVELS.WARNING,
+        message: generateNewerMinorMessage,
+    },
+    /**
+     * Behavior when API server has newer MINOR version than MCP server
+     * - 'warning': Continue with warning
+     */
+    [COMPATIBILITY_POLICY_TYPES.OLDER_MINOR]: {
+        compatible: true,
+        level: COMPATIBILITY_POLICY_ERROR_LEVELS.WARNING,
+        message: generateOlderMinorMessage,
+    },
+    /**
+     * Behavior when PATCH versions differ
+     * - 'warning': Continue with warning
+     */
+    [COMPATIBILITY_POLICY_TYPES.PATCH_DIFF]: {
+        compatible: true,
+        level: COMPATIBILITY_POLICY_ERROR_LEVELS.WARNING,
+        message: generatePatchDiffMessage,
+    },
+    /**
+     * Behavior when versions are fully compatible
+     * - 'allow': Allow without logging
+     */
+    [COMPATIBILITY_POLICY_TYPES.COMPATIBLE]: {
+        compatible: true,
+        level: COMPATIBILITY_POLICY_ERROR_LEVELS.ALLOW,
+        message: generateFullyCompatibleMessage,
+    },
+};
+export const getCompatibilityPolicyType = (params) => {
+    const mcpSemVer = semver.coerce(params.mcpVersion);
+    const apiSemVer = semver.coerce(params.apiVersion);
+    if (!mcpSemVer || !apiSemVer) {
+        return COMPATIBILITY_POLICY_TYPES.NO_VERSION;
+    }
+    if (semver.lt(apiSemVer, MIN_COMPATIBLE_API_VERSION)) {
+        return COMPATIBILITY_POLICY_TYPES.BELOW_MIN_VERSION;
+    }
+    if (mcpSemVer.major !== apiSemVer.major) {
+        return COMPATIBILITY_POLICY_TYPES.MAJOR_MISMATCH;
+    }
+    if (mcpSemVer.minor > apiSemVer.minor) {
+        return COMPATIBILITY_POLICY_TYPES.NEWER_MINOR;
+    }
+    if (mcpSemVer.minor < apiSemVer.minor) {
+        return COMPATIBILITY_POLICY_TYPES.OLDER_MINOR;
+    }
+    if (mcpSemVer.patch !== apiSemVer.patch) {
+        return COMPATIBILITY_POLICY_TYPES.PATCH_DIFF;
+    }
+    return COMPATIBILITY_POLICY_TYPES.COMPATIBLE;
+};
+export const getCompatibilityPolicy = (type) => {
+    return COMPATIBILITY_POLICY[type];
+};
+/**
+ * Update guide template
+ */
+const updateGuide = `
+Update Guide:
+  1. Download the latest release: https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest
+  2. Replace TouchDesigner components:
+     - Delete the existing touchdesigner-mcp-td folder
+     - Extract and import the new mcp_webserver_base.tox
+  3. Restart TouchDesigner and the MCP client (e.g., Claude Desktop)
+
+For more details, see: https://github.com/8beeeaaat/touchdesigner-mcp#troubleshooting-version-compatibility
+`.trim();
+/**
+ * Generate error message for unknown version information
+ */
+export function generateNoVersionMessage(args) {
+    return `
+🚨 Version Information Missing
+
+MCP Server:  ${args.mcpVersion || "Unknown"}
+API Server:  ${args.apiVersion || "Unknown"}
+
+Version information is required to ensure compatibility between the MCP server and TouchDesigner components.
+Please ensure both components are updated to compatible versions.
+
+${updateGuide}
+`.trim();
+}
+/**
+ * Generate error message for MAJOR version mismatch
+ */
+export function generateMajorMismatchMessage(args) {
+    return `
+🚨 Version Incompatibility Detected
+
+MCP Server:  ${args.mcpVersion}
+API Server:  ${args.apiVersion}
+
+MAJOR version mismatch indicates breaking changes.
+Both components must be updated to compatible versions.
+
+${updateGuide}
+`.trim();
+}
+/**
+ * Generate error message when API version is below minimum compatible version
+ */
+export function generateMinVersionMessage(args) {
+    return `
+⚠️  TouchDesigner API Server Update Required
+
+Current:  ${args.apiVersion}
+Required: ${args.minRequired}+
+
+Your TouchDesigner components are outdated and may not support all features.
+
+${updateGuide}
+`.trim();
+}
+/**
+ * Generate warning message when MCP server has newer MINOR version
+ */
+export function generateNewerMinorMessage(args) {
+    return `
+💡 Update Recommended
+
+MCP Server:  ${args.mcpVersion}
+API Server:  ${args.apiVersion}
+
+The MCP server has newer features that may not work with your TouchDesigner components.
+Consider updating for the best experience.
+
+${updateGuide}
+`.trim();
+}
+/**
+ * Generate warning message when API server has newer MINOR version
+ */
+export function generateOlderMinorMessage(args) {
+    return `
+💡 Update Recommended
+
+MCP Server:  ${args.mcpVersion}
+API Server:  ${args.apiVersion}
+
+Your TouchDesigner components have features that may not be supported by the MCP server.
+Consider updating the MCP server for the best experience.
+
+${updateGuide}
+`.trim();
+}
+/**
+ * Generate warning message when PATCH versions differ
+ */
+export function generatePatchDiffMessage(args) {
+    return `
+💡 Patch Version Mismatch
+
+MCP Server:  ${args.mcpVersion}
+API Server:  ${args.apiVersion}
+
+The MCP server and TouchDesigner components have different PATCH versions.
+While generally compatible, updating both to the latest versions is recommended.
+
+${updateGuide}
+`.trim();
+}
+/**
+ * Generate info message when versions are fully compatible
+ *
+ * @param mcpVersion MCP server version
+ * @param apiVersion TouchDesigner API server version
+ * @returns Info message
+ */
+export function generateFullyCompatibleMessage(args) {
+    return `
+✅ Versions Fully Compatible
+
+MCP Server:  ${args.mcpVersion}
+API Server:  ${args.apiVersion}
+
+Your MCP server and TouchDesigner components are fully compatible.
+No action is needed.
+`.trim();
+}

package/dist/core/logger.js

@@ -14,10 +14,30 @@ export class McpLogger {
             });
         }
         catch (error) {
+            // Only swallow the expected "Not connected" error during startup/shutdown
             if (error instanceof Error && error.message === "Not connected") {
                 return;
             }
-            console.error(`Failed to send log to MCP server: ${error instanceof Error ? error.message : String(error)}`);
+            // For all other errors, log detailed information to help diagnose logging system failures
+            console.error("CRITICAL: Failed to send log to MCP server. Logging system may be compromised.", {
+                error: error instanceof Error ? error.message : String(error),
+                originalLogger: args.logger,
+                originalLogLevel: args.level,
+                stack: error instanceof Error ? error.stack : undefined,
+            });
         }
     }
 }
+/**
+ * Console Logger implementation for standalone use (e.g., HTTP mode setup)
+ * Outputs to stderr to avoid interfering with stdio transport
+ */
+export class ConsoleLogger {
+    sendLog(args) {
+        const timestamp = new Date().toISOString();
+        const level = args.level?.toUpperCase() || "INFO";
+        const logger = args.logger || "unknown";
+        const data = args.data;
+        console.error(`[${timestamp}] [${level}] [${logger}] ${data}`);
+    }
+}

package/dist/core/version.js

@@ -1,4 +1,24 @@
 import { createRequire } from "node:module";
 const requirePackage = createRequire(import.meta.url);
 const packageJson = requirePackage("../../package.json");
-export const PACKAGE_VERSION = packageJson.version ?? "0.0.0";
+/**
+ * Current MCP server version
+ */
+export const getMcpServerVersion = () => packageJson.version ?? "0.0.0";
+export const MCP_SERVER_VERSION = getMcpServerVersion();
+/**
+ * Minimum compatible TouchDesigner API Server version required by the MCP server
+ *
+ * Loaded from package.json's mcpCompatibility.minApiVersion field.
+ * Falls back to the current package version if undefined.
+ *
+ * API Server must be at or above this version.
+ * - MAJOR mismatch: Error
+ * - MINOR/PATCH differences: Warning or allow
+ *
+ * Update when:
+ * - Introducing breaking API changes
+ * - Making incompatible changes to OpenAPI schema
+ */
+export const getMinCompatibleApiVersion = () => packageJson.mcpCompatibility?.minApiVersion ?? MCP_SERVER_VERSION;
+export const MIN_COMPATIBLE_API_VERSION = getMinCompatibleApiVersion();

package/dist/features/tools/presenter/operationFormatter.js

@@ -1,3 +1,4 @@
+import { MCP_SERVER_VERSION } from "../../../core/version.js";
 import { finalizeFormattedText, mergeFormatterOptions, } from "./responseFormatter.js";
 export function formatTdInfo(data, options) {
     const opts = mergeFormatterOptions(options);
@@ -6,17 +7,23 @@ export function formatTdInfo(data, options) {
             context: { title: "TouchDesigner Info" },
         });
     }
-    const summary = `Server: ${data.server}\nVersion: ${data.version}`;
-    const osLine = data.osName
-        ? `\nOS: ${data.osName} ${data.osVersion ?? ""}`
-        : "";
-    const text = opts.detailLevel === "minimal"
-        ? `Server: ${data.server}, v${data.version}`
-        : `${summary}${osLine}`;
+    const structured = {
+        "API Server Version": data.mcpApiVersion,
+        "MCP Server Version": MCP_SERVER_VERSION,
+        "Operating System": data.osName
+            ? `${data.osName} ${data.osVersion ?? ""}`.trim()
+            : "Unknown",
+        "TouchDesigner Version": data.version,
+    };
+    const text = Object.entries(structured)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n");
     return finalizeFormattedText(text.trim(), opts, {
-        context: { title: "TouchDesigner Info", ...data },
-        structured: data,
-        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
+        context: {
+            title: "TouchDesigner Info",
+        },
+        structured,
+        template: "detailedPayload",
     });
 }
 export function formatCreateNodeResult(data, options) {

package/dist/server/touchDesignerServer.js

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { McpLogger } from "../core/logger.js";
-import { PACKAGE_VERSION } from "../core/version.js";
+import { MCP_SERVER_VERSION } from "../core/version.js";
 import { registerPrompts } from "../features/prompts/index.js";
 import { registerTools } from "../features/tools/index.js";
 import { createTouchDesignerClient } from "../tdClient/index.js";
@@ -19,7 +19,7 @@ export class TouchDesignerServer {
     constructor() {
         this.server = new McpServer({
             name: "TouchDesigner",
-            version: PACKAGE_VERSION,
+            version: MCP_SERVER_VERSION,
         }, {
             capabilities: {
                 logging: {},
@@ -32,6 +32,25 @@ export class TouchDesignerServer {
         this.connectionManager = new ConnectionManager(this.server, this.logger);
         this.registerAllFeatures();
     }
+    /**
+     * Create a new TouchDesignerServer instance
+     *
+     * Factory method for creating server instances in multi-session scenarios.
+     * Each session should have its own server instance to maintain independent MCP protocol state.
+     *
+     * @returns McpServer instance ready for connection to a transport
+     *
+     * @example
+     * ```typescript
+     * // In TransportRegistry
+     * const serverFactory = () => TouchDesignerServer.create();
+     * const transport = await registry.getOrCreate(sessionId, body, serverFactory);
+     * ```
+     */
+    static create() {
+        const instance = new TouchDesignerServer();
+        return instance.server;
+    }
     /**
      * Connect to MCP transport
      */