touchdesigner-mcp-server 1.4.0 → 1.4.2

package/README.ja.md

@@ -18,6 +18,8 @@ TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッ
 
 **[インストールガイド](docs/installation.ja.md)** を参照してください。
 
+アップデートする場合は **[最新リリース](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest#for-updates-from-previous-versions)** の手順を参照してください。
+
 ## MCPサーバーの機能
 
 このサーバーは、Model Context Protocol (MCP) を通じてTouchDesigner への操作、および各種実装ドキュメントへの参照を可能にします。
@@ -87,9 +89,11 @@ TouchDesigner MCPは、AIモデルとTouchDesigner WebServer DAT 間のブリッ
 
 - **開発者向け：** ローカルで開発している場合は、`package.json` を編集した後に `npm run version` を実行してください（または単に `npm version ...` を使用してください）。これにより、Python API（`pyproject.toml` + `td/modules/utils/version.py`）、MCPバンドルマニフェスト、およびレジストリメタデータが同期され、ランタイム互換性チェックが成功するようになります。
 
+互換性チェックの内部動作については [Version Compatibility Verification](docs/architecture.md#version-compatibility-verification) も参照してください。
+
 ### 接続エラーのトラブルシューティング
 
-- `TouchDesignerClient` は接続に失敗した互換性チェック結果を **最大5秒間キャッシュ**し、その間のツール呼び出しでは同じエラーを再利用して TouchDesigner への無駄な負荷を避けます。TTL が切れると自動的に再試行します。
+- `TouchDesignerClient` は接続に失敗した互換性チェック結果を **最大60秒間キャッシュ**し、その間のツール呼び出しでは同じエラーを再利用して TouchDesigner への無駄な負荷を避けます。TTL が切れると自動的に再試行します。
 - MCP サーバーが TouchDesigner に接続できない場合は、次のようなガイド付きメッセージが表示されます：
   - `ECONNREFUSED` / "connect refused": TouchDesigner を起動し、`mcp_webserver_base.tox` からインポートした WebServer DAT がアクティブか、ポート設定（デフォルト `9981`）が正しいか確認してください。
   - `ETIMEDOUT` / "timeout": TouchDesigner の応答が遅い、またはネットワークが詰まっています。TouchDesigner/ WebServer DAT の再起動やネットワーク状況の確認を行ってください。

package/README.md

@@ -16,10 +16,9 @@ TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebSe
 
 ## Installation
 
-Read the **[Installation Guide](docs/installation.md)**.
+Please refer to the **[Installation Guide](docs/installation.md)**.
 
-The guide includes the required TouchDesigner preparation, per-agent setup, verification steps, and
-troubleshooting tips.
+If you are updating, please refer to the procedure in the **[Latest Release](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest#for-updates-from-previous-versions)**.
 
 ## MCP Server Features
 
@@ -91,9 +90,11 @@ The MCP server uses **semantic versioning** for flexible compatibility checks
 
 - **For developers:** When developing locally, run `npm run version` after editing `package.json` (or simply use `npm version ...`). This keeps the Python API (`pyproject.toml` + `td/modules/utils/version.py`), MCP bundle manifest, and registry metadata in sync so that the runtime compatibility check succeeds.
 
+For a deeper look at how the MCP server enforces these rules, see [Version Compatibility Verification](docs/architecture.md#version-compatibility-verification).
+
 ### Troubleshooting connection errors
 
-- `TouchDesignerClient` caches failed connection checks for **5 seconds**. Subsequent tool calls reuse the cached error to avoid spamming TouchDesigner and automatically retry after the TTL expires.
+- `TouchDesignerClient` caches failed connection checks for **60 seconds**. Subsequent tool calls reuse the cached error to avoid spamming TouchDesigner and automatically retry after the TTL expires.
 - When the MCP server cannot reach TouchDesigner, you now get guided error messages with concrete fixes:
   - `ECONNREFUSED` / "connect refused": start TouchDesigner, ensure the WebServer DAT from `mcp_webserver_base.tox` is running, and confirm the configured port (default `9981`).
   - `ETIMEDOUT` / "timeout": TouchDesigner is responding slowly or the network is blocked. Restart TouchDesigner/WebServer DAT or check your network connection.

package/dist/core/compatibility.js

@@ -65,11 +65,11 @@ const COMPATIBILITY_POLICY = {
     },
     /**
      * Behavior when PATCH versions differ
-     * - 'warning': Continue with warning
+     * - 'allow': Allow without logging
      */
     [COMPATIBILITY_POLICY_TYPES.PATCH_DIFF]: {
         compatible: true,
-        level: COMPATIBILITY_POLICY_ERROR_LEVELS.WARNING,
+        level: COMPATIBILITY_POLICY_ERROR_LEVELS.ALLOW,
         message: generatePatchDiffMessage,
     },
     /**
@@ -112,14 +112,15 @@ export const getCompatibilityPolicy = (type) => {
  * Update guide template
  */
 const updateGuide = `
-Update Guide:
-  1. Download the latest release: https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest
+Update Guide: https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest#for-updates-from-previous-versions
+  1. Download the latest release files from the releases page
   2. Replace TouchDesigner components:
-     - Delete the existing touchdesigner-mcp-td folder
-     - Extract and import the new mcp_webserver_base.tox
+     1. Delete the existing touchdesigner-mcp-td folder from your system
+     2. Delete old mcp_webserver_base node from your TouchDesigner project
+     3. Extract and import the new mcp_webserver_base.tox to your TouchDesigner project
   3. Restart TouchDesigner and the MCP client (e.g., Claude Desktop)
 
-For more details, see: https://github.com/8beeeaaat/touchdesigner-mcp#troubleshooting-version-compatibility
+For more details on compatibility, see: https://github.com/8beeeaaat/touchdesigner-mcp#troubleshooting-version-compatibility
 `.trim();
 /**
  * Generate error message for unknown version information
@@ -131,8 +132,11 @@ export function generateNoVersionMessage(args) {
 MCP Server:  ${args.mcpVersion || "Unknown"}
 API Server:  ${args.apiVersion || "Unknown"}
 
+${args.apiVersion ? "" : "You might be using an old tox file from before v1.3.0 released on December 1, 2025, or the TouchDesigner setup might not be done correctly."}
+${args.mcpVersion ? "" : "The MCP server version could not be determined. You might be using an outdated MCP server."}
+
 Version information is required to ensure compatibility between the MCP server and TouchDesigner components.
-Please ensure both components are updated to compatible versions.
+Please ensure both components are updated to latest versions.
 
 ${updateGuide}
 `.trim();
@@ -148,7 +152,7 @@ MCP Server:  ${args.mcpVersion}
 API Server:  ${args.apiVersion}
 
 MAJOR version mismatch indicates breaking changes.
-Both components must be updated to compatible versions.
+Please ensure both components are updated to compatible versions.
 
 ${updateGuide}
 `.trim();

package/dist/features/tools/handlers/tdTools.js

@@ -75,14 +75,7 @@ export function registerTdTools(server, logger, tdClient) {
                 detailLevel: detailLevel ?? "summary",
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_INFO);
@@ -104,14 +97,7 @@ export function registerTdTools(server, logger, tdClient) {
                 detailLevel: detailLevel ?? "summary",
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.EXECUTE_PYTHON_SCRIPT);
@@ -128,14 +114,7 @@ export function registerTdTools(server, logger, tdClient) {
                 detailLevel: detailLevel ?? "summary",
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.CREATE_TD_NODE, REFERENCE_COMMENT);
@@ -152,14 +131,7 @@ export function registerTdTools(server, logger, tdClient) {
                 detailLevel: detailLevel ?? "summary",
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.DELETE_TD_NODE, REFERENCE_COMMENT);
@@ -181,14 +153,7 @@ export function registerTdTools(server, logger, tdClient) {
                 limit,
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_NODES, REFERENCE_COMMENT);
@@ -207,14 +172,7 @@ export function registerTdTools(server, logger, tdClient) {
                 limit,
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_NODE_PARAMETERS, REFERENCE_COMMENT);
@@ -232,14 +190,7 @@ export function registerTdTools(server, logger, tdClient) {
                 limit,
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_NODE_ERRORS, REFERENCE_COMMENT);
@@ -256,14 +207,7 @@ export function registerTdTools(server, logger, tdClient) {
                 detailLevel: detailLevel ?? "summary",
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.UPDATE_TD_NODE_PARAMETERS, REFERENCE_COMMENT);
@@ -278,14 +222,7 @@ export function registerTdTools(server, logger, tdClient) {
                 throw result.error;
             }
             const formattedText = formatExecNodeMethodResult(result.data, { args, kwargs, method, nodePath }, { detailLevel: detailLevel ?? "summary", responseFormat });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             logger.sendLog({
@@ -307,14 +244,7 @@ export function registerTdTools(server, logger, tdClient) {
                 limit: params.limit ?? 50,
                 responseFormat: params.responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_CLASSES, REFERENCE_COMMENT);
@@ -333,14 +263,7 @@ export function registerTdTools(server, logger, tdClient) {
                 limit: limit ?? 30,
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_CLASS_DETAILS, REFERENCE_COMMENT);
@@ -357,20 +280,26 @@ export function registerTdTools(server, logger, tdClient) {
                 detailLevel: detailLevel ?? "summary",
                 responseFormat,
             });
-            return {
-                content: [
-                    {
-                        text: formattedText,
-                        type: "text",
-                    },
-                ],
-            };
+            return createToolResult(tdClient, formattedText);
         }
         catch (error) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_MODULE_HELP);
         }
     });
 }
+const createToolResult = (tdClient, text) => {
+    const content = [
+        {
+            text,
+            type: "text",
+        },
+    ];
+    const additionalContents = tdClient.getAdditionalToolResultContents();
+    if (additionalContents) {
+        content.push(...additionalContents);
+    }
+    return { content };
+};
 function matchesMetadataFilter(entry, keyword) {
     const normalizedKeyword = keyword.toLowerCase();
     const haystacks = [

package/dist/gen/endpoints/TouchDesignerAPI.js

@@ -3,7 +3,7 @@
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 1.3.0
+ * OpenAPI spec version: 1.4.1
  */
 import { customInstance } from '../../api/customInstance.js';
 // eslint-disable-next-line @typescript-eslint/no-redeclare

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

@@ -3,7 +3,7 @@
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 1.3.0
+ * OpenAPI spec version: 1.4.1
  */
 import * as zod from 'zod';
 /**

package/dist/tdClient/touchDesignerClient.js

@@ -20,7 +20,8 @@ const defaultApiClient = {
     getTdPythonClasses: apiGetTdPythonClasses,
     updateNode: apiUpdateNode,
 };
-export const ERROR_CACHE_TTL_MS = 5000; // 5 seconds
+export const ERROR_CACHE_TTL_MS = 60 * 1000; // 60 seconds
+export const SUCCESS_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 /**
  * Null logger implementation that discards all logs
  */
@@ -57,16 +58,14 @@ function handleApiResponse(response) {
     }
     return { data, success: true };
 }
-/**
- * TouchDesigner client implementation with dependency injection
- * for better testability and separation of concerns
- */
 export class TouchDesignerClient {
     logger;
     api;
     verifiedCompatibilityError;
     cachedCompatibilityCheck;
     errorCacheTimestamp;
+    successCacheTimestamp;
+    compatibilityNotice;
     /**
      * Initialize TouchDesigner client with optional dependencies
      */
@@ -76,6 +75,8 @@ export class TouchDesignerClient {
         this.verifiedCompatibilityError = null;
         this.cachedCompatibilityCheck = false;
         this.errorCacheTimestamp = null;
+        this.successCacheTimestamp = null;
+        this.compatibilityNotice = null;
     }
     /**
      * Log debug message
@@ -98,13 +99,56 @@ export class TouchDesignerClient {
         const now = Date.now();
         return now - this.errorCacheTimestamp >= ERROR_CACHE_TTL_MS;
     }
+    /**
+     * Check whether the cached successful compatibility check is still valid
+     */
+    hasValidSuccessCache() {
+        if (!this.cachedCompatibilityCheck || !this.successCacheTimestamp) {
+            return false;
+        }
+        const now = Date.now();
+        return now - this.successCacheTimestamp < SUCCESS_CACHE_TTL_MS;
+    }
+    /**
+     * Force the next API call to re-run compatibility verification.
+     * Useful when the user explicitly requests version information.
+     */
+    invalidateCompatibilityCache(reason) {
+        if (this.cachedCompatibilityCheck) {
+            this.logDebug("Invalidating cached compatibility check", { reason });
+        }
+        this.cachedCompatibilityCheck = false;
+        this.successCacheTimestamp = null;
+        this.verifiedCompatibilityError = null;
+        this.errorCacheTimestamp = null;
+        this.compatibilityNotice = null;
+    }
+    getAdditionalToolResultContents() {
+        if (!this.compatibilityNotice) {
+            return null;
+        }
+        return [
+            {
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: this.compatibilityNotice.level === "warning" ? 0.2 : 0.1,
+                },
+                text: this.compatibilityNotice.message,
+                type: "text",
+            },
+        ];
+    }
     /**
      * Verify compatibility with the TouchDesigner server
      */
     async verifyCompatibility() {
         // If we've already verified compatibility successfully, skip re-verification
         if (this.cachedCompatibilityCheck && !this.verifiedCompatibilityError) {
-            return;
+            if (this.hasValidSuccessCache()) {
+                return;
+            }
+            this.logDebug("Compatibility cache expired, re-verifying...");
+            this.invalidateCompatibilityCache("success cache expired");
         }
         // Clear cached error if TTL has expired
         if (this.verifiedCompatibilityError && this.shouldClearErrorCache()) {
@@ -129,9 +173,20 @@ export class TouchDesignerClient {
         }
         const result = await this.verifyVersionCompatibility();
         if (result.success) {
+            const compatibilityInfo = result.data;
             this.verifiedCompatibilityError = null;
             this.errorCacheTimestamp = null;
             this.cachedCompatibilityCheck = true;
+            this.successCacheTimestamp = Date.now();
+            if (compatibilityInfo.level === "warning" && compatibilityInfo.message) {
+                this.compatibilityNotice = {
+                    level: compatibilityInfo.level,
+                    message: compatibilityInfo.message,
+                };
+            }
+            else {
+                this.compatibilityNotice = null;
+            }
             this.logDebug("Compatibility verified successfully");
             return;
         }
@@ -142,6 +197,8 @@ export class TouchDesignerClient {
         this.verifiedCompatibilityError = result.error;
         this.errorCacheTimestamp = Date.now();
         this.cachedCompatibilityCheck = false;
+        this.successCacheTimestamp = null;
+        this.compatibilityNotice = null;
         throw result.error;
     }
     /**
@@ -173,6 +230,7 @@ export class TouchDesignerClient {
      * Get TouchDesigner server information
      */
     async getTdInfo() {
+        this.invalidateCompatibilityCache("tdInfo request");
         return this.apiCall("Getting server info", () => this.api.getTdInfo());
     }
     /**
@@ -295,7 +353,10 @@ export class TouchDesignerClient {
         if (result.level === "error") {
             return createErrorResult(new Error(result.message));
         }
-        return createSuccessResult(undefined);
+        return createSuccessResult({
+            level: result.level,
+            message: result.message,
+        });
     }
     /**
      * Format connection errors with helpful messages

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "1.4.0",
+	"version": "1.4.2",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",