touchdesigner-mcp-server 1.2.0 → 1.3.0

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

@@ -14,9 +14,9 @@ export function formatTdInfo(data, options) {
         ? `Server: ${data.server}, v${data.version}`
         : `${summary}${osLine}`;
     return finalizeFormattedText(text.trim(), opts, {
-        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
         context: { title: "TouchDesigner Info", ...data },
         structured: data,
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
     });
 }
 export function formatCreateNodeResult(data, options) {
@@ -37,9 +37,9 @@ export function formatCreateNodeResult(data, options) {
         ? base
         : `${base}\nProperties detected: ${propCount}`;
     return finalizeFormattedText(text, opts, {
-        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
-        context: { title: "Create Node", path, opType },
+        context: { opType, path, title: "Create Node" },
         structured: data,
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
     });
 }
 export function formatUpdateNodeResult(data, options) {
@@ -51,15 +51,15 @@ export function formatUpdateNodeResult(data, options) {
         ? base
         : `${base}${failedCount ? `, ${failedCount} failed` : ""}`;
     const context = {
-        title: "Update Node",
-        updated: data?.updated,
         failed: data?.failed,
         message: data?.message,
+        title: "Update Node",
+        updated: data?.updated,
     };
     return finalizeFormattedText(text, opts, {
-        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
         context,
         structured: data,
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
     });
 }
 export function formatDeleteNodeResult(data, options) {
@@ -71,9 +71,9 @@ export function formatDeleteNodeResult(data, options) {
         ? `🗑️ Deleted '${name}' at ${path}`
         : `Deletion status unknown for '${name}' at ${path}`;
     return finalizeFormattedText(text, opts, {
-        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
-        context: { title: "Delete Node", path, deleted },
+        context: { deleted, path, title: "Delete Node" },
         structured: data,
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
     });
 }
 export function formatExecNodeMethodResult(data, context, options) {
@@ -82,9 +82,9 @@ export function formatExecNodeMethodResult(data, context, options) {
     const resultPreview = summarizeValue(data?.result);
     const text = `${callSignature}\nResult: ${resultPreview}`;
     return finalizeFormattedText(text, opts, {
-        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
-        context: { title: "Execute Node Method", callSignature },
+        context: { callSignature, title: "Execute Node Method" },
         structured: { ...context, result: data?.result },
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
     });
 }
 function buildCallSignature(params) {

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

@@ -13,8 +13,8 @@ import { presentStructuredData } from "./presenter.js";
  */
 export const DEFAULT_FORMATTER_OPTIONS = {
     detailLevel: "summary",
-    limit: undefined,
     includeHints: true,
+    limit: undefined,
     responseFormat: undefined,
 };
 /**
@@ -27,8 +27,8 @@ export function mergeFormatterOptions(options) {
         DEFAULT_FORMATTER_OPTIONS.detailLevel;
     return {
         detailLevel,
-        limit: merged.limit,
         includeHints: merged.includeHints ?? true,
+        limit: merged.limit,
         responseFormat: merged.responseFormat,
     };
 }
@@ -36,11 +36,11 @@ export function finalizeFormattedText(text, opts, metadata) {
     const chosenFormat = opts.responseFormat ??
         (opts.detailLevel === "detailed" ? "yaml" : "markdown");
     return presentStructuredData({
-        text,
+        context: metadata?.context,
         detailLevel: opts.detailLevel,
         structured: metadata?.structured,
-        context: metadata?.context,
         template: metadata?.template,
+        text,
     }, chosenFormat);
 }
 /**

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

@@ -41,9 +41,9 @@ export function formatScriptResult(data, scriptSnippet, options) {
     }
     const ctx = context;
     return finalizeFormattedText(formattedText, opts, {
-        template: "scriptSummary",
         context: ctx,
         structured: ctx,
+        template: "scriptSummary",
     });
 }
 /**
@@ -98,25 +98,25 @@ function formatSummary(result, output, scriptSnippet) {
         formatted += `\nOutput:\n${outputPreview}`;
     }
     return {
-        text: formatted,
         context: {
-            snippet,
-            resultType: getValueType(result),
-            resultPreview,
             hasOutput: Boolean(outputPreview),
-            outputType: getValueType(output),
             outputPreview,
+            outputType: getValueType(output),
+            resultPreview,
+            resultType: getValueType(result),
+            snippet,
         },
+        text: formatted,
     };
 }
 function buildScriptContext(scriptSnippet, result, output) {
     return {
-        snippet: scriptSnippet ? truncateScript(scriptSnippet) : "",
-        resultType: getValueType(result),
-        resultPreview: formatResultValue(result ?? "", 200),
         hasOutput: Boolean(output?.trim()),
-        outputType: getValueType(output),
         outputPreview: output,
+        outputType: getValueType(output),
+        resultPreview: formatResultValue(result ?? "", 200),
+        resultType: getValueType(result),
+        snippet: scriptSnippet ? truncateScript(scriptSnippet) : "",
     };
 }
 /**
@@ -126,14 +126,14 @@ function formatDetailed(data, format) {
     const title = "Script Result";
     const payloadFormat = format ?? DEFAULT_PRESENTER_FORMAT;
     return presentStructuredData({
-        text: title,
-        detailLevel: "detailed",
-        structured: data,
         context: {
-            title,
             payloadFormat,
+            title,
         },
+        detailLevel: "detailed",
+        structured: data,
         template: "detailedPayload",
+        text: title,
     }, payloadFormat);
 }
 function getValueType(value) {

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

@@ -3,27 +3,27 @@ export function formatToolMetadata(entries, options) {
     const { detailLevel, responseFormat } = mergeFormatterOptions(options);
     if (entries.length === 0) {
         return finalizeFormattedText("No tools matched the requested criteria.", { detailLevel, responseFormat }, {
-            context: { totalTools: 0, filter: options?.filter },
+            context: { filter: options?.filter, totalTools: 0 },
         });
     }
     const sortedEntries = [...entries].sort((a, b) => a.modulePath.localeCompare(b.modulePath));
     const structured = sortedEntries.map((entry) => ({
-        tool: entry.tool,
-        modulePath: entry.modulePath,
-        functionName: entry.functionName,
-        description: entry.description,
         category: entry.category,
+        description: entry.description,
+        functionName: entry.functionName,
+        modulePath: entry.modulePath,
+        notes: entry.notes,
         parameters: entry.parameters,
         returns: entry.returns,
-        notes: entry.notes,
+        tool: entry.tool,
     }));
     const text = buildText(sortedEntries, detailLevel);
     return finalizeFormattedText(text, { detailLevel, responseFormat }, {
-        structured,
         context: {
-            totalTools: sortedEntries.length,
             filter: options?.filter,
+            totalTools: sortedEntries.length,
         },
+        structured,
         template: detailLevel === "detailed" ? "detailedPayload" : undefined,
     });
 }

package/dist/gen/endpoints/TouchDesignerAPI.js

@@ -1,9 +1,9 @@
 /**
- * Generated by orval v7.11.2 🍺
+ * Generated by orval v7.17.0 🍺
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 1.1.2
+ * OpenAPI spec version: 1.3.0
  */
 import { customInstance } from '../../api/customInstance.js';
 // eslint-disable-next-line @typescript-eslint/no-redeclare
@@ -17,14 +17,14 @@ export const TdNodeFamilyType = {
     CUSTOM: 'CUSTOM',
 };
 // eslint-disable-next-line @typescript-eslint/no-redeclare
-export const TdPythonClassInfoType = {
+export const TdPythonClassDetailsType = {
     class: 'class',
     module: 'module',
     function: 'function',
     object: 'object',
 };
 // eslint-disable-next-line @typescript-eslint/no-redeclare
-export const TdPythonClassDetailsType = {
+export const TdPythonClassInfoType = {
     class: 'class',
     module: 'module',
     function: 'function',
@@ -73,6 +73,15 @@ export const updateNode = (updateNodeRequest, options) => {
         data: updateNodeRequest
     }, options);
 };
+/**
+ * Collects TouchDesigner error messages for a node and its children
+ * @summary Get node errors
+ */
+export const getNodeErrors = (params, options) => {
+    return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes/errors`, method: 'GET',
+        params
+    }, options);
+};
 /**
  * Returns a list of Python classes, modules, and functions available in TouchDesigner
  * @summary Get a list of Python classes and modules
@@ -89,6 +98,15 @@ export const getTdPythonClassDetails = (className, options) => {
     return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/classes/${className}`, method: 'GET'
     }, options);
 };
+/**
+ * Retrieve Python help() documentation for TouchDesigner modules, classes, or utilities like tdu.
+ * @summary Get module/class Python help documentation
+ */
+export const getModuleHelp = (params, options) => {
+    return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/modules/help`, method: 'GET',
+        params
+    }, options);
+};
 /**
  * Call a method on the node at the specified path (e.g., /project1).
 This allows operations equivalent to TouchDesigner's Python API such as

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

@@ -1,11 +1,11 @@
 /**
- * Generated by orval v7.11.2 🍺
+ * Generated by orval v7.17.0 🍺
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 1.1.2
+ * OpenAPI spec version: 1.3.0
  */
-import { z as zod } from 'zod';
+import * as zod from 'zod';
 /**
  * @summary Delete an existing node
  */
@@ -21,7 +21,7 @@ export const deleteNodeResponse = zod.object({
             "opType": zod.string(),
             "name": zod.string(),
             "path": zod.string(),
-            "properties": zod.record(zod.string(), zod.any())
+            "properties": zod.record(zod.string(), zod.unknown())
         }).optional().describe('Information about a TouchDesigner node')
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
@@ -44,7 +44,7 @@ export const getNodesResponse = zod.object({
             "opType": zod.string(),
             "name": zod.string(),
             "path": zod.string(),
-            "properties": zod.record(zod.string(), zod.any())
+            "properties": zod.record(zod.string(), zod.unknown())
         }).describe('Information about a TouchDesigner node')).optional().describe('Result of the execution')
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
@@ -65,7 +65,7 @@ export const createNodeResponse = zod.object({
             "opType": zod.string(),
             "name": zod.string(),
             "path": zod.string(),
-            "properties": zod.record(zod.string(), zod.any())
+            "properties": zod.record(zod.string(), zod.unknown())
         }).optional().describe('Information about a TouchDesigner node')
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
@@ -84,7 +84,7 @@ export const getNodeDetailResponse = zod.object({
         "opType": zod.string(),
         "name": zod.string(),
         "path": zod.string(),
-        "properties": zod.record(zod.string(), zod.any())
+        "properties": zod.record(zod.string(), zod.unknown())
     }).describe('Information about a TouchDesigner node'),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });
@@ -93,7 +93,7 @@ export const getNodeDetailResponse = zod.object({
  */
 export const updateNodeBody = zod.object({
     "nodePath": zod.string().describe('Path to the node (e.g., /project1/null1)'),
-    "properties": zod.record(zod.string(), zod.any())
+    "properties": zod.record(zod.string(), zod.unknown())
 });
 export const updateNodeResponse = zod.object({
     "success": zod.boolean().describe('Whether the update operation was successful'),
@@ -108,6 +108,30 @@ export const updateNodeResponse = zod.object({
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });
+/**
+ * Collects TouchDesigner error messages for a node and its children
+ * @summary Get node errors
+ */
+export const getNodeErrorsQueryParams = zod.object({
+    "nodePath": zod.string().describe('Absolute path to the node to inspect. e.g., \"/project1/text1\"')
+});
+export const getNodeErrorsResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "nodePath": zod.string().describe('Path that was inspected for errors'),
+        "nodeName": zod.string().describe('Name of the inspected node'),
+        "opType": zod.string().describe('Operator type of the inspected node'),
+        "errorCount": zod.number().describe('Number of errors that were discovered'),
+        "hasErrors": zod.boolean().describe('Convenience flag indicating if any errors were found'),
+        "errors": zod.array(zod.object({
+            "nodePath": zod.string().describe('Absolute operator path that reported the error'),
+            "nodeName": zod.string().describe('Name of the operator'),
+            "opType": zod.string().describe('TouchDesigner operator type'),
+            "message": zod.string().describe('Error message reported by TouchDesigner')
+        }).describe('Single node error entry')).describe('Collection of raw node errors')
+    }).describe('Aggregated node error report'),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
 /**
  * Returns a list of Python classes, modules, and functions available in TouchDesigner
  * @summary Get a list of Python classes and modules
@@ -149,6 +173,21 @@ export const getTdPythonClassDetailsResponse = zod.object({
     }).describe('Detailed information about a Python class or module'),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });
+/**
+ * Retrieve Python help() documentation for TouchDesigner modules, classes, or utilities like tdu.
+ * @summary Get module/class Python help documentation
+ */
+export const getModuleHelpQueryParams = zod.object({
+    "moduleName": zod.string().describe('Module or class name (e.g., \"noiseCHOP\", \"td.noiseCHOP\", \"tdu\").')
+});
+export const getModuleHelpResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "moduleName": zod.string().describe('Normalized module/class name the help text was generated for'),
+        "helpText": zod.string().describe('Captured output from Python\'s help() function')
+    }).describe('Raw Python help() output for a TouchDesigner module or class'),
+    "error": zod.string().nullable().describe('Error message if the operation was not successful')
+});
 /**
  * Call a method on the node at the specified path (e.g., /project1).
 This allows operations equivalent to TouchDesigner's Python API such as
@@ -160,7 +199,7 @@ export const execNodeMethodBody = zod.object({
     "nodePath": zod.string().describe('Path to the node (e.g., /project1/null1)'),
     "method": zod.string().describe('Name of the method to call'),
     "args": zod.array(zod.union([zod.string(), zod.number(), zod.boolean()])).optional().describe('List of arguments for the method call'),
-    "kwargs": zod.record(zod.string(), zod.any()).optional().describe('Keyword arguments for the method call')
+    "kwargs": zod.record(zod.string(), zod.unknown()).optional().describe('Keyword arguments for the method call')
 });
 export const execNodeMethodResponse = zod.object({
     "success": zod.boolean().describe('Whether the operation was successful'),
@@ -196,10 +235,11 @@ export const execPythonScriptResponse = zod.object({
 export const getTdInfoResponse = zod.object({
     "success": zod.boolean().describe('Whether the operation was successful'),
     "data": zod.object({
-        "server": zod.string().describe('Server name (typically \"TouchDesigner\")'),
-        "version": zod.string().describe('TouchDesigner version number'),
+        "mcpApiVersion": zod.string().describe('Version of the TouchDesigner MCP API server'),
         "osName": zod.string().describe('Operating system name'),
-        "osVersion": zod.string().describe('Operating system version')
+        "osVersion": zod.string().describe('Operating system version'),
+        "server": zod.string().describe('Server name (typically \"TouchDesigner\")'),
+        "version": zod.string().describe('TouchDesigner version number')
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });

package/dist/server/connectionManager.js

@@ -5,31 +5,31 @@ import { createErrorResult, createSuccessResult } from "../core/result.js";
 export class ConnectionManager {
     server;
     logger;
-    tdClient;
     transport = null;
-    constructor(server, logger, tdClient) {
+    constructor(server, logger) {
         this.server = server;
         this.logger = logger;
-        this.tdClient = tdClient;
     }
     /**
      * Connect to MCP transport
      */
     async connect(transport) {
         if (this.isConnected()) {
-            this.logger.log("MCP server already connected");
+            this.logger.sendLog({
+                data: "MCP server already connected",
+                level: "info",
+                logger: "ConnectionManager",
+            });
             return createSuccessResult(undefined);
         }
         this.transport = transport;
         try {
             await this.server.connect(transport);
-            this.logger.log(`Server connected and ready to process requests: ${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}`);
-            // Connection will be checked when tools are actually used
-            const connectionResult = await this.checkTDConnection();
-            if (!connectionResult.success) {
-                throw new Error(`Failed to connect to TouchDesigner. The mcp_webserver_base on TouchDesigner not currently available: ${connectionResult.error.message}`);
-            }
-            this.logger.log("TouchDesigner connection verified");
+            this.logger.sendLog({
+                data: `Server connected and ready to process requests: ${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}`,
+                level: "info",
+                logger: "ConnectionManager",
+            });
             return createSuccessResult(undefined);
         }
         catch (error) {
@@ -65,21 +65,4 @@ export class ConnectionManager {
     isConnected() {
         return this.transport !== null;
     }
-    /**
-     * Check connection to TouchDesigner
-     */
-    async checkTDConnection() {
-        this.logger.log("Testing connection to TouchDesigner server...");
-        try {
-            const result = await this.tdClient.getTdInfo();
-            if (!result.success) {
-                throw result.error;
-            }
-            return createSuccessResult(result.data);
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            return createErrorResult(err);
-        }
-    }
 }

package/dist/server/touchDesignerServer.js

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { McpLogger } from "../core/logger.js";
+import { PACKAGE_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";
@@ -18,17 +19,17 @@ export class TouchDesignerServer {
     constructor() {
         this.server = new McpServer({
             name: "TouchDesigner",
-            version: "1.1.2",
+            version: PACKAGE_VERSION,
         }, {
             capabilities: {
-                prompts: {},
                 logging: {},
+                prompts: {},
                 tools: {},
             },
         });
         this.logger = new McpLogger(this.server);
         this.tdClient = createTouchDesignerClient({ logger: this.logger });
-        this.connectionManager = new ConnectionManager(this.server, this.logger, this.tdClient);
+        this.connectionManager = new ConnectionManager(this.server, this.logger);
         this.registerAllFeatures();
     }
     /**