touchdesigner-mcp-server 1.2.0 → 1.3.1

package/README.ja.md

@@ -250,9 +250,11 @@ td/
 | `delete_td_node`            | 既存のノードを削除します。                     |
 | `exec_node_method`          | ノードに対してPythonメソッドを呼び出します。   |
 | `execute_python_script`     | TD内で任意のPythonスクリプトを実行します。     |
+| `get_module_help`           | TouchDesignerモジュール/クラスのPython help()ドキュメントを取得します。 |
 | `get_td_class_details`      | TD Pythonクラス/モジュールの詳細情報を取得します。 |
 | `get_td_classes`            | TouchDesigner Pythonクラスのリストを取得します。 |
 | `get_td_info`           | TDサーバー環境に関する情報を取得します。       |
+| `get_td_node_errors`        | 指定されたノードとその子ノードのエラーをチェックします。 |
 | `get_td_node_parameters`    | 特定ノードのパラメータを取得します。           |
 | `get_td_nodes`              | 親パス内のノードを取得します（オプションでフィルタリング）。 |
 | `update_td_node_parameters` | 特定ノードのパラメータを更新します。           |
@@ -354,6 +356,50 @@ td/
 
 ビルドプロセス (`npm run build`) は、必要なすべての生成ステップ (`npm run gen`) を実行し、その後にTypeScriptコンパイル (`tsc`) を行います。
 
+### バージョン管理
+
+- `package.json` はすべてのコンポーネントバージョンの唯一の信頼できる情報源です（Node.js MCPサーバー、TouchDesigner Python API、MCPバンドル、および `server.json` メタデータ）。
+- バージョンを更新する際は `npm version <patch|minor|major>`（または内部で使用される `npm run gen:version`）を実行してください。このスクリプトは `pyproject.toml`、`td/modules/utils/version.py`、`mcpb/manifest.json`、および `server.json` を書き換え、リリースワークフローがタグ値を信頼できるようにします。
+- GitHubリリースワークフロー（`.github/workflows/release.yml`）はコミットを `v${version}` としてタグ付けし、同じバージョン番号から `touchdesigner-mcp-td.zip` / `touchdesigner-mcp.mcpb` を公開します。リリースをトリガーする前に必ず同期ステップを実行し、すべてのアーティファクトが整合するようにしてください。
+
+## トラブルシューティング
+
+### バージョン互換性のトラブルシューティング
+
+柔軟な互換性チェックのために**セマンティックバージョニング**を使用しています
+
+| 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 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

@@ -250,9 +250,11 @@ Tools allow AI agents to perform actions in TouchDesigner.
 | `delete_td_node`        | Deletes an existing node.                                          |
 | `exec_node_method`      | Calls a Python method on a node.                                   |
 | `execute_python_script` | Executes an arbitrary Python script in TouchDesigner.              |
+| `get_module_help`       | Gets Python help() documentation for TouchDesigner modules/classes.|
 | `get_td_class_details`  | Gets details of a TouchDesigner Python class or module.            |
 | `get_td_classes`        | Gets a list of TouchDesigner Python classes.                       |
 | `get_td_info`           | Gets information about the TouchDesigner server environment.       |
+| `get_td_node_errors`    | Checks for errors on a specified node and its children. |
 | `get_td_node_parameters`| Gets the parameters of a specific node.                            |
 | `get_td_nodes`          | Gets nodes under a parent path, with optional filtering.           |
 | `update_td_node_parameters` | Updates the parameters of a specific node.                     |
@@ -354,6 +356,50 @@ This project uses OpenAPI-based code generation tools (Orval and openapi-generat
 
 The build process (`npm run build`) runs all necessary generation steps (`npm run gen`), followed by TypeScript compilation (`tsc`).
 
+### Version management
+
+- `package.json` is the single source of truth for every component version (Node.js MCP server, TouchDesigner Python API, MCP bundle, and `server.json` metadata).
+- Run `npm version <patch|minor|major>` (or the underlying `npm run gen:version`) whenever you bump the version. The script rewrites `pyproject.toml`, `td/modules/utils/version.py`, `mcpb/manifest.json`, and `server.json` so that the release workflow can trust the tag value.
+- The GitHub release workflow (`.github/workflows/release.yml`) tags the commit as `v${version}` and publishes `touchdesigner-mcp-td.zip` / `touchdesigner-mcp.mcpb` from the exact same version number. Always run the sync step before triggering a release so that every artifact stays aligned.
+
+## Troubleshooting
+
+### Troubleshooting version compatibility
+
+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.
+  4. Restart TouchDesigner and the AI agent running the MCP server (e.g., Claude Desktop).
+
+- **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
 
 We welcome your contributions!

package/dist/cli.js

@@ -59,8 +59,8 @@ export async function startServer(params) {
 }
 // Start server if this file is executed directly
 startServer({
-    nodeEnv: process.env.NODE_ENV,
     argv: process.argv,
+    nodeEnv: process.env.NODE_ENV,
 }).catch((error) => {
     console.error("Failed to start server:", error);
     if (process.env.NODE_ENV === "test")

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/constants.js

@@ -10,18 +10,20 @@ export const TOOL_NAMES = {
     CREATE_TD_NODE: "create_td_node",
     DELETE_TD_NODE: "delete_td_node",
     DESCRIBE_TD_TOOLS: "describe_td_tools",
-    EXECUTE_PYTHON_SCRIPT: "execute_python_script",
     EXECUTE_NODE_METHOD: "exec_node_method",
-    GET_TD_INFO: "get_td_info",
+    EXECUTE_PYTHON_SCRIPT: "execute_python_script",
     GET_TD_CLASS_DETAILS: "get_td_class_details",
     GET_TD_CLASSES: "get_td_classes",
+    GET_TD_INFO: "get_td_info",
+    GET_TD_MODULE_HELP: "get_td_module_help",
+    GET_TD_NODE_ERRORS: "get_td_node_errors",
     GET_TD_NODE_PARAMETERS: "get_td_node_parameters",
     GET_TD_NODES: "get_td_nodes",
     UPDATE_TD_NODE_PARAMETERS: "update_td_node_parameters",
 };
 export const REFERENCE_COMMENT = `Check reference resources: ${TD_PYTHON_CLASS_REFERENCE_INDEX_URL}`;
 export const PROMPT_NAMES = {
-    SEARCH_NODE: "Search node",
     CHECK_NODE_ERRORS: "Check node errors",
     NODE_CONNECTION: "Node connection",
+    SEARCH_NODE: "Search node",
 };

package/dist/core/errorHandling.js

@@ -5,15 +5,30 @@ export function handleToolError(error, logger, toolName, referenceComment) {
     const formattedError = error instanceof Error
         ? error
         : new Error(error === null ? "Null error received" : String(error));
-    logger.error(toolName, formattedError);
+    const logData = {
+        error: formattedError.message,
+        message: "Tool execution failed",
+        toolName,
+    };
+    if (referenceComment) {
+        logData.referenceComment = referenceComment;
+    }
+    if (formattedError.stack) {
+        logData.stack = formattedError.stack;
+    }
+    logger.sendLog({
+        data: logData,
+        level: "error",
+        logger: "ErrorHandling",
+    });
     const errorMessage = `${toolName}: ${formattedError}${referenceComment ? `. ${referenceComment}` : ""}`;
     return {
-        isError: true,
         content: [
             {
-                type: "text",
                 text: errorMessage,
+                type: "text",
             },
         ],
+        isError: true,
     };
 }

package/dist/core/logger.js

@@ -7,39 +7,24 @@ export class McpLogger {
     constructor(server) {
         this.server = server;
     }
-    // biome-ignore lint/suspicious/noExplicitAny: logging accepts any type
-    log(...args) {
-        this.sendLog("info", args);
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: logging accepts any type
-    debug(...args) {
-        this.sendLog("debug", args);
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: logging accepts any type
-    warn(...args) {
-        this.sendLog("warning", args);
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: logging accepts any type
-    error(...args) {
-        this.sendLog("error", args);
-    }
-    sendLog(level, 
-    // biome-ignore lint/suspicious/noExplicitAny: logging accepts any type
-    args) {
-        for (const arg of args) {
-            try {
-                this.server.server.sendLoggingMessage({
-                    level,
-                    data: arg,
-                });
-            }
-            catch (error) {
-                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)}`);
-                console[level === "warning" ? "warn" : level]?.(arg);
+    sendLog(args) {
+        try {
+            this.server.server.sendLoggingMessage({
+                ...args,
+            });
+        }
+        catch (error) {
+            // Only swallow the expected "Not connected" error during startup/shutdown
+            if (error instanceof Error && error.message === "Not connected") {
+                return;
             }
+            // 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/result.js

@@ -2,11 +2,11 @@
  * Creates a success result with the provided data
  */
 export function createSuccessResult(data) {
-    return { success: true, data };
+    return { data, success: true };
 }
 /**
  * Creates an error result with the provided error
  */
 export function createErrorResult(error) {
-    return { success: false, error };
+    return { error, success: false };
 }

package/dist/core/version.js

@@ -0,0 +1,24 @@
+import { createRequire } from "node:module";
+const requirePackage = createRequire(import.meta.url);
+const packageJson = requirePackage("../../package.json");
+/**
+ * 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/prompts/handlers/td_prompts.js

@@ -2,40 +2,40 @@ import { GetPromptRequestSchema, ListPromptsRequestSchema, } from "@modelcontext
 import { PROMPT_NAMES, TOOL_NAMES } from "../../../core/constants.js";
 const PROMPTS = [
     {
-        name: PROMPT_NAMES.SEARCH_NODE,
-        description: "Fuzzy search for node",
         arguments: [
             {
-                name: "nodeName",
                 description: "Name of the node to check",
+                name: "nodeName",
                 required: true,
             },
             {
-                name: "nodeFamily",
                 description: "Family of the node to check",
+                name: "nodeFamily",
                 required: false,
             },
             {
-                name: "nodeType",
                 description: "Type of the node to check",
+                name: "nodeType",
                 required: false,
             },
         ],
+        description: "Fuzzy search for node",
+        name: PROMPT_NAMES.SEARCH_NODE,
     },
     {
-        name: PROMPT_NAMES.CHECK_NODE_ERRORS,
-        description: "Fuzzy search for node and return errors in TouchDesigner.",
         arguments: [
             {
-                name: "nodePath",
                 description: "Path to the node to check",
+                name: "nodePath",
                 required: true,
             },
         ],
+        description: "Fuzzy search for node and return errors in TouchDesigner.",
+        name: PROMPT_NAMES.CHECK_NODE_ERRORS,
     },
     {
-        name: PROMPT_NAMES.NODE_CONNECTION,
         description: "Connect nodes between each other in TouchDesigner.",
+        name: PROMPT_NAMES.NODE_CONNECTION,
     },
 ];
 /**
@@ -49,7 +49,10 @@ export function registerTdPrompts(server, logger) {
     });
     server.server.setRequestHandler(GetPromptRequestSchema, (request) => {
         try {
-            logger.debug(`Handling GetPromptRequest: ${request.params.name}`);
+            logger.sendLog({
+                data: `Handling GetPromptRequest: ${request.params.name}`,
+                level: "debug",
+            });
             const prompt = getPrompt(request.params.name);
             if (!prompt) {
                 throw new Error("Prompt name is required");
@@ -60,8 +63,8 @@ export function registerTdPrompts(server, logger) {
                 }
                 const { nodeName, nodeFamily, nodeType } = request.params.arguments;
                 const messages = handleSearchNodePrompt({
-                    nodeName,
                     nodeFamily,
+                    nodeName,
                     nodeType,
                 });
                 return { messages };
@@ -84,7 +87,10 @@ export function registerTdPrompts(server, logger) {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.error(`Error handling prompt request: ${errorMessage}`);
+            logger.sendLog({
+                data: `Error handling prompt request: ${errorMessage}`,
+                level: "error",
+            });
             throw new Error(errorMessage);
         }
     });
@@ -92,33 +98,33 @@ export function registerTdPrompts(server, logger) {
 function handleSearchNodePrompt(params) {
     return [
         {
-            role: "user",
             content: {
-                type: "text",
                 text: `Use the "${TOOL_NAMES.GET_TD_NODES}", "${TOOL_NAMES.GET_TD_NODE_PARAMETERS}" tools to search nodes what named "${params.nodeName}" in the TouchDesigner project.${params.nodeType ? ` Node Type: ${params.nodeType}.` : ""}${params.nodeFamily ? ` Node Family: ${params.nodeFamily}.` : ""}`,
+                type: "text",
             },
+            role: "user",
         },
     ];
 }
 function handleCheckNodeErrorsPrompt(params) {
     return [
         {
-            role: "user",
             content: {
+                text: `Use the "${TOOL_NAMES.GET_TD_NODE_ERRORS}" tool to inspect "${params.nodePath}" (and optionally its children) for error messages. If errors are returned, examine the affected nodes' parameters and connections to resolve them.`,
                 type: "text",
-                text: `Use the "${TOOL_NAMES.EXECUTE_NODE_METHOD}" like "op('${params.nodePath}').errors()" tool to check node errors. If there are any errors, please check the node parameters and connections. If the node has children, please check the child nodes as well. Please check the node connections and parameters. If the node has children, please check the child nodes as well.`,
             },
+            role: "user",
         },
     ];
 }
 function handleNodeConnectionPrompt() {
     return [
         {
-            role: "user",
             content: {
-                type: "text",
                 text: `Use the "${TOOL_NAMES.EXECUTE_PYTHON_SCRIPT}" tool e.g. op('/project1/text_over_image').outputConnectors[0].connect(op('/project1/out1'))`,
+                type: "text",
             },
+            role: "user",
         },
     ];
 }