touchdesigner-mcp-server 1.3.0 → 1.3.1

package/README.ja.md

@@ -366,13 +366,39 @@ td/
 
 ### バージョン互換性のトラブルシューティング
 
-- `ConnectionManager.connect` の実行中、MCPサーバーは自身のバージョンと `getTdInfo` が報告するTouchDesigner APIサーバーのバージョンを比較します。APIサーバーがバージョンを公開していない場合、またはバージョンが異なる場合（例：片方のみが更新された場合）、MCPサーバーはClaude/Codexコンソールおよび TouchDesigner ログ DAT に説明的なエラーメッセージを表示して接続を中止します。
-- 不一致を解決するには、TouchDesignerコンポーネントを再インストールしてください：
+柔軟な互換性チェックのために**セマンティックバージョニング**を使用しています
+
+| MCP Server | API Server | 最小互換APIバージョン | 動作 | ステータス | 備考 |
+|------------|------------|----------------|----------|--------|-------|
+| 1.3.x | 1.3.0 | 1.3.0 | ✅ 正常動作 | 互換 | 推奨ベースライン構成 |
+| 1.3.x | 1.4.0 | 1.3.0 | ⚠️ 警告表示、実行継続 | 警告 | 旧MCP MINORと新API、新機能未対応の可能性 |
+| 1.4.0 | 1.3.x | 1.3.0 | ⚠️ 警告表示、実行継続 | 警告 | 新MCP MINORに追加機能がある可能性 |
+| 1.3.2 | 1.3.1 | 1.3.2 | ❌ 実行停止 | エラー | APIが最小互換バージョン未満 |
+| 2.0.0 | 1.x.x | N/A | ❌ 実行停止 | エラー | MAJORバージョン相違 = 破壊的変更 |
+
+**互換性ルール**:
+
+- ✅ **互換**: 同じMAJORバージョン、かつAPIバージョン ≥ 最小互換バージョン
+- ⚠️ **警告**: 同じMAJOR内でMINORまたはPATCHバージョンが異なる（警告表示、実行継続）
+- ❌ **エラー**: MAJORバージョンが異なる、またはAPIサーバー < 最小互換バージョン（即座に実行停止、更新が必要）
+
+- **互換性エラーを解決するには：**
   1. リリースページから最新の [touchdesigner-mcp-td.zip](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest/download/touchdesigner-mcp-td.zip) をダウンロードします。
   2. 既存の `touchdesigner-mcp-td` フォルダを削除し、新しく展開した内容に置き換えます。
   3. TouchDesignerプロジェクトから古い `mcp_webserver_base` コンポーネントを削除し、新しいフォルダから `.tox` をインポートします。
   4. TouchDesignerとMCPサーバーを実行しているAIエージェント（例：Claude Desktop）を再起動します。
-- ローカルで開発している場合は、`package.json` を編集した後に `npm run gen:version` を実行してください（または単に `npm version ...` を使用してください）。これにより、Python API（`pyproject.toml` + `td/modules/utils/version.py`）、MCPバンドルマニフェスト、およびレジストリメタデータが同期され、ランタイム互換性チェックが成功するようになります。
+
+- **開発者向け：** ローカルで開発している場合は、`package.json` を編集した後に `npm run version` を実行してください（または単に `npm version ...` を使用してください）。これにより、Python API（`pyproject.toml` + `td/modules/utils/version.py`）、MCPバンドルマニフェスト、およびレジストリメタデータが同期され、ランタイム互換性チェックが成功するようになります。
+
+### 接続エラーのトラブルシューティング
+
+- `TouchDesignerClient` は接続に失敗した互換性チェック結果を **最大5秒間キャッシュ**し、その間のツール呼び出しでは同じエラーを再利用して TouchDesigner への無駄な負荷を避けます。TTL が切れると自動的に再試行します。
+- MCP サーバーが TouchDesigner に接続できない場合は、次のようなガイド付きメッセージが表示されます：
+  - `ECONNREFUSED` / "connect refused": TouchDesigner を起動し、`mcp_webserver_base.tox` からインポートした WebServer DAT がアクティブか、ポート設定（デフォルト `9981`）が正しいか確認してください。
+  - `ETIMEDOUT` / "timeout": TouchDesigner の応答が遅い、またはネットワークが詰まっています。TouchDesigner/ WebServer DAT の再起動やネットワーク状況の確認を行ってください。
+  - `ENOTFOUND` / `getaddrinfo`: ホスト名が解決できません。特別な理由がなければ `127.0.0.1` を使用してください。
+- これらの詳細なエラーテキストは `ILogger` にも出力されるため、MCP 側のログを確認すれば TouchDesigner に到達する前に止まった理由を把握できます。
+- 問題を解決したら再度ツールを実行するだけで、キャッシュされたエラーがクリアされて接続チェックがやり直されます。
 
 ## 開発で貢献
 

package/README.md

@@ -366,13 +366,39 @@ The build process (`npm run build`) runs all necessary generation steps (`npm ru
 
 ### Troubleshooting version compatibility
 
-- During `ConnectionManager.connect` the MCP server compares its own version with the TouchDesigner API server version reported by `getTdInfo`. If the API server does not expose a version or the versions differ (for example because only one side was updated), the MCP server aborts the connection with a descriptive error message in the Claude/Codex console and in the TouchDesigner log DAT.
-- To resolve the mismatch, reinstall both the TouchDesigner components
+The MCP server uses **semantic versioning** for flexible compatibility checks
+
+| MCP Server | API Server | Minimum compatible API version | Behavior | Status | Notes |
+|------------|------------|----------------|----------|--------|-------|
+| 1.3.x | 1.3.0 | 1.3.0 | ✅ Works normally | Compatible | Recommended baseline configuration |
+| 1.3.x | 1.4.0 | 1.3.0 | ⚠️ Warning shown, continues | Warning | Older MCP MINOR with newer API may lack new features |
+| 1.4.0 | 1.3.x | 1.3.0 | ⚠️ Warning shown, continues | Warning | Newer MCP MINOR may have additional features |
+| 1.3.2 | 1.3.1 | 1.3.2 | ❌ Execution stops | Error | API below minimum compatible version |
+| 2.0.0 | 1.x.x | N/A | ❌ Execution stops | Error | Different MAJOR = breaking changes |
+
+**Compatibility Rules**:
+
+- ✅ **Compatible**: Same MAJOR version AND API version ≥ 1.3.0 (minimum compatible version)
+- ⚠️ **Warning**: Different MINOR or PATCH versions within the same MAJOR version (shows warning but continues execution)
+- ❌ **Error**: Different MAJOR versions OR API server < 1.3.0 (execution stops immediately, update required)
+
+- **To resolve compatibility errors:**
   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.
+  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).
-- When developing locally, run `npm run gen: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 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.
+
+### 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.
+- 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.
+  - `ENOTFOUND` / `getaddrinfo`: the host name is invalid. Use `127.0.0.1` unless you explicitly changed it.
+- The structured error text is also logged through `ILogger`, so you can check the MCP logs to understand why a request stopped before hitting TouchDesigner.
+- Once the underlying issue is fixed, simply run the tool again—the client clears the cached error and re-verifies the connection automatically.
 
 ## Contributing
 

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,17 @@ 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,
+            });
         }
     }
 }

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: {},

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "1.3.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,13 +26,14 @@
 		"touchdesigner-mcp-server": "dist/cli.js"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.23.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.35",
 		"axios": "^1.13.2",
 		"mustache": "^4.2.0",
+		"semver": "^7.7.3",
 		"yaml": "^2.8.2",
 		"zod": "4.1.13"
 	},
@@ -39,15 +43,16 @@
 		"@types/jsdom": "^27.0.0",
 		"@types/mustache": "^4.2.6",
 		"@types/node": "^24.10.1",
-		"@vitest/coverage-v8": "^4.0.14",
+		"@types/semver": "^7.7.1",
+		"@vitest/coverage-v8": "^4.0.15",
 		"archiver": "^7.0.1",
-		"msw": "^2.12.3",
+		"msw": "^2.12.4",
 		"npm-run-all": "^4.1.5",
 		"orval": "^7.17.0",
-		"prettier": "^3.7.3",
+		"prettier": "^3.7.4",
 		"shx": "^0.4.0",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.14"
+		"vitest": "^4.0.15"
 	},
 	"type": "module",
 	"exports": {
@@ -79,8 +84,10 @@
 		"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: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"