touchdesigner-mcp-server 1.4.8 → 1.4.9

package/dist/features/tools/toolDefinitions.js

@@ -0,0 +1,317 @@
+import { REFERENCE_COMMENT, TOOL_NAMES } from "../../core/constants.js";
+import { CreateNodeBody, DeleteNodeQueryParams, ExecNodeMethodBody, ExecPythonScriptBody, GetModuleHelpQueryParams, GetNodeDetailQueryParams, GetNodeErrorsQueryParams, GetNodesQueryParams, GetTdPythonClassDetailsParams, UpdateNodeBody, } from "../../gen/mcp/touchDesignerAPI.zod.js";
+import { formatClassDetails, formatClassList, formatCreateNodeResult, formatDeleteNodeResult, formatExecNodeMethodResult, formatModuleHelp, formatNodeDetails, formatNodeErrors, formatNodeList, formatScriptResult, formatTdInfo, formatUpdateNodeResult, } from "./presenter/index.js";
+import { detailOnlyFormattingSchema, formattingOptionsSchema, } from "./types.js";
+/**
+ * Authoring helper that infers `params` from the tool's schema while erasing to
+ * the uniform {@link ToolDefinition} shape for storage in the table.
+ */
+function defineTool(def) {
+    // `run` has a narrower param type (z.infer<S>) than ToolDefinition exposes
+    // (Record<string, unknown>). Function parameters are contravariant, so a
+    // direct `as ToolDefinition` is rejected; the double cast is required. Safe
+    // because params are validated by the MCP SDK before reaching run().
+    return def;
+}
+export const TOOL_DEFINITIONS = [
+    defineTool({
+        category: "system",
+        description: "Get server information from TouchDesigner",
+        example: `import { getTdInfo } from './servers/touchdesigner/getTdInfo';
+
+const info = await getTdInfo();
+console.log(\`\${info.server} \${info.version}\`);`,
+        name: TOOL_NAMES.GET_TD_INFO,
+        returns: "TouchDesigner build metadata (server, version, operating system).",
+        run: async ({ params, tdClient }) => {
+            const result = await tdClient.getTdInfo();
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatTdInfo(result.data, {
+                detailLevel: params.detailLevel ?? "summary",
+                responseFormat: params.responseFormat,
+            });
+        },
+        schema: detailOnlyFormattingSchema,
+    }),
+    defineTool({
+        category: "python",
+        description: "Execute a Python script in TouchDesigner (detailLevel=minimal|summary|detailed, responseFormat=json|yaml|markdown)",
+        example: `import { executePythonScript } from './servers/touchdesigner/executePythonScript';
+
+await executePythonScript({
+  script: "op('/project1/text1').par.text = 'Hello MCP'",
+});`,
+        name: TOOL_NAMES.EXECUTE_PYTHON_SCRIPT,
+        notes: "Wrap long-running scripts with logging so the agent can stream intermediate checkpoints.",
+        returns: "Result payload that mirrors `result` from the executed script (if set).",
+        run: async ({ params, tdClient, logger }) => {
+            const { detailLevel, responseFormat, ...scriptParams } = params;
+            logger.sendLog({
+                data: `Executing script: ${scriptParams.script}`,
+                level: "debug",
+            });
+            const result = await tdClient.execPythonScript(scriptParams);
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatScriptResult(result, scriptParams.script, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
+        },
+        schema: ExecPythonScriptBody.extend(detailOnlyFormattingSchema.shape),
+    }),
+    defineTool({
+        category: "nodes",
+        description: "List nodes under a path with token-optimized output (detailLevel+limit supported)",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { getTdNodes } from './servers/touchdesigner/getTdNodes';
+
+const nodes = await getTdNodes({
+  parentPath: '/project1',
+  pattern: 'geo*',
+});
+console.log(nodes.nodes?.map(node => node.path));`,
+        name: TOOL_NAMES.GET_TD_NODES,
+        returns: "Set of nodes (id, opType, name, path, optional properties) under parentPath.",
+        run: async ({ params, tdClient }) => {
+            const { detailLevel, limit, responseFormat, ...queryParams } = params;
+            const result = await tdClient.getNodes(queryParams);
+            if (!result.success) {
+                throw result.error;
+            }
+            const fallbackMode = queryParams.includeProperties
+                ? "detailed"
+                : "summary";
+            return formatNodeList(result.data, {
+                detailLevel: detailLevel ?? fallbackMode,
+                limit,
+                responseFormat,
+            });
+        },
+        schema: GetNodesQueryParams.extend(formattingOptionsSchema.shape),
+    }),
+    defineTool({
+        category: "nodes",
+        description: "Get node parameters with concise/detailed formatting (detailLevel+limit supported)",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { getTdNodeParameters } from './servers/touchdesigner/getTdNodeParameters';
+
+const node = await getTdNodeParameters({ nodePath: '/project1/text1' });
+console.log(node.properties?.Text);`,
+        name: TOOL_NAMES.GET_TD_NODE_PARAMETERS,
+        returns: "Full node record with parameters, paths, and metadata.",
+        run: async ({ params, tdClient }) => {
+            const { detailLevel, limit, responseFormat, ...queryParams } = params;
+            const result = await tdClient.getNodeDetail(queryParams);
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatNodeDetails(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                limit,
+                responseFormat,
+            });
+        },
+        schema: GetNodeDetailQueryParams.extend(formattingOptionsSchema.shape),
+    }),
+    defineTool({
+        category: "nodes",
+        description: "Check node and descendant errors reported by TouchDesigner",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { getTdNodeErrors } from './servers/touchdesigner/getTdNodeErrors';
+
+const report = await getTdNodeErrors({
+  nodePath: '/project1/text1',
+});
+if (report.hasErrors) {
+  console.log(report.errors?.map(err => err.message));
+}`,
+        name: TOOL_NAMES.GET_TD_NODE_ERRORS,
+        returns: "Error report outlining offending nodes, messages, and counts.",
+        run: async ({ params, tdClient }) => {
+            const { detailLevel, limit, responseFormat, ...queryParams } = params;
+            const result = await tdClient.getNodeErrors(queryParams);
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatNodeErrors(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                limit,
+                responseFormat,
+            });
+        },
+        schema: GetNodeErrorsQueryParams.extend(formattingOptionsSchema.shape),
+    }),
+    defineTool({
+        category: "nodes",
+        description: "Create a new node in TouchDesigner",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { createTdNode } from './servers/touchdesigner/createTdNode';
+
+const created = await createTdNode({
+  parentPath: '/project1',
+  nodeType: 'textTOP',
+  nodeName: 'title',
+});
+console.log(created.result?.path);`,
+        name: TOOL_NAMES.CREATE_TD_NODE,
+        returns: "Created node metadata including resolved path and properties.",
+        run: async ({ params, tdClient }) => {
+            const { detailLevel, responseFormat, ...createParams } = params;
+            const result = await tdClient.createNode(createParams);
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatCreateNodeResult(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
+        },
+        schema: CreateNodeBody.extend(detailOnlyFormattingSchema.shape),
+    }),
+    defineTool({
+        category: "nodes",
+        description: "Update parameters of a specific node in TouchDesigner",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { updateTdNodeParameters } from './servers/touchdesigner/updateTdNodeParameters';
+
+await updateTdNodeParameters({
+  nodePath: '/project1/text1',
+  properties: { text: 'Hello TouchDesigner' },
+});`,
+        name: TOOL_NAMES.UPDATE_TD_NODE_PARAMETERS,
+        returns: "Lists of updated vs failed parameters so the agent can retry selectively.",
+        run: async ({ params, tdClient }) => {
+            const { detailLevel, responseFormat, ...updateParams } = params;
+            const result = await tdClient.updateNode(updateParams);
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatUpdateNodeResult(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
+        },
+        schema: UpdateNodeBody.extend(detailOnlyFormattingSchema.shape),
+    }),
+    defineTool({
+        category: "nodes",
+        description: "Delete an existing node in TouchDesigner",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { deleteTdNode } from './servers/touchdesigner/deleteTdNode';
+
+const result = await deleteTdNode({ nodePath: '/project1/tmp1' });
+console.log(result.deleted);`,
+        name: TOOL_NAMES.DELETE_TD_NODE,
+        returns: "Deletion status plus previous node metadata when available.",
+        run: async ({ params, tdClient }) => {
+            const { detailLevel, responseFormat, ...deleteParams } = params;
+            const result = await tdClient.deleteNode(deleteParams);
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatDeleteNodeResult(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
+        },
+        schema: DeleteNodeQueryParams.extend(detailOnlyFormattingSchema.shape),
+    }),
+    defineTool({
+        category: "nodes",
+        description: "Execute a method on a specific node in TouchDesigner",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { execNodeMethod } from './servers/touchdesigner/execNodeMethod';
+
+const renderStatus = await execNodeMethod({
+  nodePath: '/project1/render1',
+  method: 'par',
+  kwargs: { enable: true },
+});
+console.log(renderStatus.result);`,
+        name: TOOL_NAMES.EXECUTE_NODE_METHOD,
+        returns: "Raw method return payload including any serializable values.",
+        run: async ({ params, tdClient }) => {
+            const { detailLevel, responseFormat, ...execParams } = params;
+            const { nodePath, method, args, kwargs } = execParams;
+            const result = await tdClient.execNodeMethod(execParams);
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatExecNodeMethodResult(result.data, { args, kwargs, method, nodePath }, { detailLevel: detailLevel ?? "summary", responseFormat });
+        },
+        schema: ExecNodeMethodBody.extend(detailOnlyFormattingSchema.shape),
+    }),
+    defineTool({
+        category: "classes",
+        description: "List TouchDesigner Python classes/modules (detailLevel+limit supported)",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { getTdClasses } from './servers/touchdesigner/getTdClasses';
+
+const classes = await getTdClasses({ limit: 20 });
+console.log(classes.classes?.map(cls => cls.name));`,
+        name: TOOL_NAMES.GET_TD_CLASSES,
+        returns: "Python class catalogue with names, types, and optional summaries.",
+        run: async ({ params, tdClient }) => {
+            const result = await tdClient.getClasses();
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatClassList(result.data, {
+                detailLevel: params.detailLevel ?? "summary",
+                limit: params.limit ?? 50,
+                responseFormat: params.responseFormat,
+            });
+        },
+        schema: formattingOptionsSchema,
+    }),
+    defineTool({
+        category: "classes",
+        description: "Get information about a TouchDesigner class/module (detailLevel+limit supported)",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { getTdClassDetails } from './servers/touchdesigner/getTdClassDetails';
+
+const textTop = await getTdClassDetails({ className: 'textTOP' });
+console.log(textTop.methods?.length);`,
+        name: TOOL_NAMES.GET_TD_CLASS_DETAILS,
+        returns: "Deep description of a Python class including methods and properties.",
+        run: async ({ params, tdClient }) => {
+            const { className, detailLevel, limit, responseFormat } = params;
+            const result = await tdClient.getClassDetails(className);
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatClassDetails(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                limit: limit ?? 30,
+                responseFormat,
+            });
+        },
+        schema: GetTdPythonClassDetailsParams.extend(formattingOptionsSchema.shape),
+    }),
+    defineTool({
+        category: "classes",
+        description: "Retrieve Python help() text for a TouchDesigner module or class",
+        example: `import { getTdModuleHelp } from './servers/touchdesigner/getTdModuleHelp';
+
+const docs = await getTdModuleHelp({ moduleName: 'noiseCHOP' });
+console.log(docs.helpText?.slice(0, 200));`,
+        name: TOOL_NAMES.GET_TD_MODULE_HELP,
+        returns: "Captured Python help() output with formatter context.",
+        run: async ({ params, tdClient }) => {
+            const { detailLevel, moduleName, responseFormat } = params;
+            const result = await tdClient.getModuleHelp({ moduleName });
+            if (!result.success) {
+                throw result.error;
+            }
+            return formatModuleHelp(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
+        },
+        schema: GetModuleHelpQueryParams.extend(detailOnlyFormattingSchema.shape),
+    }),
+];

package/dist/gen/endpoints/TouchDesignerAPI.js

@@ -1,5 +1,5 @@
 /**
- * Generated by orval v8.16.0 🍺
+ * Generated by orval v8.17.0 🍺
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
@@ -28,16 +28,8 @@ export const TdPythonClassInfoType = {
     object: 'object',
 };
 /**
-* @summary Delete an existing node
+* @summary Get nodes in the path
 */
-export const deleteNode = (params, options) => {
-    return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes`, method: 'DELETE',
-        params
-    }, options);
-};
-/**
- * @summary Get nodes in the path
- */
 export const getNodes = (params, options) => {
     return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes`, method: 'GET',
         params
@@ -46,10 +38,18 @@ export const getNodes = (params, options) => {
 /**
  * @summary Create a new node
  */
-export const createNode = (createNodeRequest, options) => {
+export const createNode = (createNodeBody, options) => {
     return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes`, method: 'POST',
         headers: { 'Content-Type': 'application/json', },
-        data: createNodeRequest
+        data: createNodeBody
+    }, options);
+};
+/**
+ * @summary Delete an existing node
+ */
+export const deleteNode = (params, options) => {
+    return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes`, method: 'DELETE',
+        params
     }, options);
 };
 /**
@@ -64,10 +64,10 @@ export const getNodeDetail = (params, options) => {
 /**
  * @summary Update node properties
  */
-export const updateNode = (updateNodeRequest, options) => {
+export const updateNode = (updateNodeBody, options) => {
     return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/nodes/detail`, method: 'PATCH',
         headers: { 'Content-Type': 'application/json', },
-        data: updateNodeRequest
+        data: updateNodeBody
     }, options);
 };
 /**
@@ -110,10 +110,10 @@ export const getModuleHelp = (params, options) => {
  * `parent_comp = op('/project1')` and `parent_comp.create('textTOP', 'myText')`.
  * @summary Call a method of the specified node
  */
-export const execNodeMethod = (execNodeMethodRequest, options) => {
+export const execNodeMethod = (execNodeMethodBody, options) => {
     return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/nodes/exec`, method: 'POST',
         headers: { 'Content-Type': 'application/json', },
-        data: execNodeMethodRequest
+        data: execNodeMethodBody
     }, options);
 };
 /**
@@ -123,10 +123,10 @@ export const execNodeMethod = (execNodeMethodRequest, options) => {
  * This endpoint allows you to interact with TouchDesigner nodes programmatically.
  * @summary Execute python code on the server
  */
-export const execPythonScript = (execPythonScriptRequest, options) => {
+export const execPythonScript = (execPythonScriptBody, options) => {
     return customInstance({ url: `${process.env.TD_WEB_SERVER_HOST}:${process.env.TD_WEB_SERVER_PORT}/api/td/server/exec`, method: 'POST',
         headers: { 'Content-Type': 'application/json', },
-        data: execPythonScriptRequest
+        data: execPythonScriptBody
     }, options);
 };
 /**

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

@@ -1,31 +1,11 @@
 /**
- * Generated by orval v8.16.0 🍺
+ * Generated by orval v8.17.0 🍺
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
  * OpenAPI spec version: 1.4.3
  */
 import * as zod from 'zod';
-/**
- * @summary Delete an existing node
- */
-export const DeleteNodeQueryParams = zod.object({
-    "nodePath": zod.string().describe('Path to the node to delete. e.g., \"\/project1\/geo1\"')
-});
-export const DeleteNodeResponse = zod.object({
-    "success": zod.boolean().describe('Whether the operation was successful'),
-    "data": zod.object({
-        "deleted": zod.boolean().optional().describe('Whether the node was successfully deleted'),
-        "node": zod.object({
-            "id": zod.number(),
-            "opType": zod.string(),
-            "name": zod.string(),
-            "path": zod.string(),
-            "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')
-});
 /**
  * @summary Get nodes in the path
  */
@@ -66,7 +46,27 @@ export const CreateNodeResponse = zod.object({
             "name": zod.string(),
             "path": zod.string(),
             "properties": zod.record(zod.string(), zod.unknown())
-        }).optional().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')
+});
+/**
+ * @summary Delete an existing node
+ */
+export const DeleteNodeQueryParams = zod.object({
+    "nodePath": zod.string().describe('Path to the node to delete. e.g., \"\/project1\/geo1\"')
+});
+export const DeleteNodeResponse = zod.object({
+    "success": zod.boolean().describe('Whether the operation was successful'),
+    "data": zod.object({
+        "deleted": zod.boolean().optional().describe('Whether the node was successfully deleted'),
+        "node": zod.object({
+            "id": zod.number(),
+            "opType": zod.string(),
+            "name": zod.string(),
+            "path": zod.string(),
+            "properties": zod.record(zod.string(), zod.unknown())
+        }).optional().describe('Information about the deleted node')
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });
@@ -85,7 +85,7 @@ export const GetNodeDetailResponse = zod.object({
         "name": zod.string(),
         "path": zod.string(),
         "properties": zod.record(zod.string(), zod.unknown())
-    }).describe('Information about a TouchDesigner node'),
+    }).nullable().describe('Information about a TouchDesigner node'),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });
 /**
@@ -170,7 +170,7 @@ export const GetTdPythonClassDetailsResponse = zod.object({
             "type": zod.string().describe('Type of the property'),
             "value": zod.looseObject({}).nullish().describe('Current value of the property (if serializable)')
         }).describe('Information about a Python property')).describe('List of properties available in the class or module')
-    }).describe('Detailed information about a Python class or module'),
+    }).nullable().describe('Detailed information about a Python class or module'),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });
 /**
@@ -185,7 +185,7 @@ export const GetModuleHelpResponse = zod.object({
     "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'),
+    }).nullable().describe('Raw Python help() output for a TouchDesigner module or class'),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });
 /**
@@ -203,7 +203,7 @@ export const ExecNodeMethodBody = zod.object({
 export const ExecNodeMethodResponse = zod.object({
     "success": zod.boolean().describe('Whether the operation was successful'),
     "data": zod.object({
-        "result": zod.looseObject({}).describe('Result of the method call. Can be any type (equivalent to unknown in TypeScript).')
+        "result": zod.unknown().describe('Result of the method call. Can be any type (equivalent to unknown in TypeScript).')
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });
@@ -221,7 +221,7 @@ export const ExecPythonScriptResponse = zod.object({
     "success": zod.boolean().describe('Whether the operation was successful'),
     "data": zod.object({
         "result": zod.object({
-            "value": zod.looseObject({}).optional().describe('Return value of the executed script, can be any serializable value')
+            "value": zod.unknown().optional().describe('Return value of the executed script, can be any serializable value')
         }).describe('Result of the executed script')
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "1.4.8",
+	"version": "1.4.9",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",
@@ -27,9 +27,6 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "1.29.0",
-		"@mozilla/readability": "0.6.0",
-		"@types/ws": "8.18.1",
-		"@types/yargs": "17.0.35",
 		"axios": "1.17.0",
 		"express": "5.2.1",
 		"mustache": "4.2.0",
@@ -38,17 +35,15 @@
 		"zod": "4.4.3"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.4.16",
-		"@openapitools/openapi-generator-cli": "2.35.0",
+		"@biomejs/biome": "2.5.0",
+		"@redocly/cli": "2.32.2",
 		"@types/express": "5.0.6",
-		"@types/jsdom": "28.0.3",
 		"@types/mustache": "4.2.6",
 		"@types/node": "25.9.3",
 		"@types/semver": "7.7.1",
 		"@vitest/coverage-v8": "4.1.8",
-		"msw": "2.14.6",
 		"npm-run-all": "4.1.5",
-		"orval": "8.16.0",
+		"orval": "8.17.0",
 		"prettier": "3.8.4",
 		"shx": "0.4.0",
 		"typescript": "6.0.3",
@@ -89,21 +84,11 @@
 		"version:api": "node ./scripts/syncApiServerVersions.ts",
 		"version:mcp": "node ./scripts/syncMcpServerVersions.ts",
 		"gen": "run-s gen:*",
-		"gen:webserver": "openapi-generator-cli generate -i ./src/api/index.yml -g python-flask -o ./td/modules/td_server -t ./src/templates/python-flask",
+		"gen:openapi": "redocly bundle ./src/api/index.yml -o ./td/modules/td_server/openapi_server/openapi/openapi.yaml",
 		"gen:handlers": "node td/genHandlers.js",
 		"gen:mcp": "orval --config ./orval.config.ts"
 	},
 	"files": [
 		"dist/**/*"
-	],
-	"overrides": {
-		"concurrently": {
-			"shell-quote": "1.8.4"
-		}
-	},
-	"msw": {
-		"workerDirectory": [
-			"public"
-		]
-	}
+	]
 }