touchdesigner-mcp-server 1.2.0 → 1.3.1

package/dist/features/tools/metadata/touchDesignerToolMetadata.js

@@ -2,195 +2,201 @@ import { TOOL_NAMES } from "../../../core/constants.js";
 const MODULE_ROOT = "servers/touchdesigner";
 export const TOUCH_DESIGNER_TOOL_METADATA = [
     {
-        tool: TOOL_NAMES.GET_TD_INFO,
-        modulePath: `${MODULE_ROOT}/getTdInfo.ts`,
-        functionName: "getTdInfo",
-        description: "Get server information from TouchDesigner",
         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}\`);`,
+        functionName: "getTdInfo",
+        modulePath: `${MODULE_ROOT}/getTdInfo.ts`,
         parameters: [
             {
+                description: "Optional presenter granularity for formatted output.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "Optional presenter granularity for formatted output.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Overrides the formatter output format for automation.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Overrides the formatter output format for automation.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
         returns: "TouchDesigner build metadata (server, version, operating system).",
-        example: `import { getTdInfo } from './servers/touchdesigner/getTdInfo';
-
-const info = await getTdInfo();
-console.log(\`\${info.server} \${info.version}\`);`,
+        tool: TOOL_NAMES.GET_TD_INFO,
     },
     {
-        tool: TOOL_NAMES.EXECUTE_PYTHON_SCRIPT,
-        modulePath: `${MODULE_ROOT}/executePythonScript.ts`,
-        functionName: "executePythonScript",
-        description: "Execute arbitrary Python against the TouchDesigner session",
         category: "python",
+        description: "Execute arbitrary Python against the TouchDesigner session",
+        example: `import { executePythonScript } from './servers/touchdesigner/executePythonScript';
+
+await executePythonScript({
+  script: "op('/project1/text1').par.text = 'Hello MCP'",
+});`,
+        functionName: "executePythonScript",
+        modulePath: `${MODULE_ROOT}/executePythonScript.ts`,
+        notes: "Wrap long-running scripts with logging so the agent can stream intermediate checkpoints.",
         parameters: [
             {
+                description: "Python source that TouchDesigner will eval. Multiline scripts supported.",
                 name: "script",
-                type: "string",
                 required: true,
-                description: "Python source that TouchDesigner will eval. Multiline scripts supported.",
+                type: "string",
             },
             {
+                description: "Choose how much of the execution metadata to surface back to the agent.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "Choose how much of the execution metadata to surface back to the agent.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Structured response encoding for downstream tooling.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Structured response encoding for downstream tooling.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
         returns: "Result payload that mirrors `result` from the executed script (if set).",
-        example: `import { executePythonScript } from './servers/touchdesigner/executePythonScript';
-
-await executePythonScript({
-  script: "op('/project1/text1').par.text = 'Hello MCP'",
-});`,
-        notes: "Wrap long-running scripts with logging so the agent can stream intermediate checkpoints.",
+        tool: TOOL_NAMES.EXECUTE_PYTHON_SCRIPT,
     },
     {
-        tool: TOOL_NAMES.GET_TD_NODES,
-        modulePath: `${MODULE_ROOT}/getTdNodes.ts`,
-        functionName: "getTdNodes",
-        description: "List nodes below a parent path",
         category: "nodes",
+        description: "List nodes below a parent path",
+        example: `import { getTdNodes } from './servers/touchdesigner/getTdNodes';
+
+const nodes = await getTdNodes({
+  parentPath: '/project1',
+  pattern: 'geo*',
+});
+console.log(nodes.nodes?.map(node => node.path));`,
+        functionName: "getTdNodes",
+        modulePath: `${MODULE_ROOT}/getTdNodes.ts`,
         parameters: [
             {
+                description: "Root operator path (e.g. /project1).",
                 name: "parentPath",
-                type: "string",
                 required: true,
-                description: "Root operator path (e.g. /project1).",
+                type: "string",
             },
             {
+                description: "Glob pattern to filter node names (default '*').",
                 name: "pattern",
-                type: "string",
                 required: false,
-                description: "Glob pattern to filter node names (default '*').",
+                type: "string",
             },
             {
+                description: "Include expensive property blobs when you truly need them.",
                 name: "includeProperties",
-                type: "boolean",
                 required: false,
-                description: "Include expensive property blobs when you truly need them.",
+                type: "boolean",
             },
             {
+                description: "Formatter verbosity for the returned list.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "Formatter verbosity for the returned list.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Optional cap on how many nodes to return.",
                 name: "limit",
-                type: "number",
                 required: false,
-                description: "Optional cap on how many nodes to return.",
+                type: "number",
             },
             {
+                description: "Structured export for writing to disk.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Structured export for writing to disk.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
         returns: "Set of nodes (id, opType, name, path, optional properties) under parentPath.",
-        example: `import { getTdNodes } from './servers/touchdesigner/getTdNodes';
-
-const nodes = await getTdNodes({
-  parentPath: '/project1',
-  pattern: 'geo*',
-});
-console.log(nodes.nodes?.map(node => node.path));`,
+        tool: TOOL_NAMES.GET_TD_NODES,
     },
     {
-        tool: TOOL_NAMES.GET_TD_NODE_PARAMETERS,
-        modulePath: `${MODULE_ROOT}/getTdNodeParameters.ts`,
-        functionName: "getTdNodeParameters",
-        description: "Inspect an individual node with formatter-aware output",
         category: "nodes",
+        description: "Inspect an individual node with formatter-aware output",
+        example: `import { getTdNodeParameters } from './servers/touchdesigner/getTdNodeParameters';
+
+const node = await getTdNodeParameters({ nodePath: '/project1/text1' });
+console.log(node.properties?.Text);`,
+        functionName: "getTdNodeParameters",
+        modulePath: `${MODULE_ROOT}/getTdNodeParameters.ts`,
         parameters: [
             {
+                description: "Absolute path to the operator (e.g. /project1/text1).",
                 name: "nodePath",
-                type: "string",
                 required: true,
-                description: "Absolute path to the operator (e.g. /project1/text1).",
+                type: "string",
             },
             {
+                description: "Controls how many parameters and properties are shown.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "Controls how many parameters and properties are shown.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Trim parameter listings to the first N entries.",
                 name: "limit",
-                type: "number",
                 required: false,
-                description: "Trim parameter listings to the first N entries.",
+                type: "number",
             },
             {
+                description: "Switch between machine vs human friendly layouts.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Switch between machine vs human friendly layouts.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
         returns: "Full node record with parameters, paths, and metadata.",
-        example: `import { getTdNodeParameters } from './servers/touchdesigner/getTdNodeParameters';
-
-const node = await getTdNodeParameters({ nodePath: '/project1/text1' });
-console.log(node.properties?.Text);`,
+        tool: TOOL_NAMES.GET_TD_NODE_PARAMETERS,
     },
     {
-        tool: TOOL_NAMES.CREATE_TD_NODE,
-        modulePath: `${MODULE_ROOT}/createTdNode.ts`,
-        functionName: "createTdNode",
-        description: "Create an operator under a parent path",
         category: "nodes",
+        description: "Collect errors emitted by a node and its children",
+        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));
+}`,
+        functionName: "getTdNodeErrors",
+        modulePath: `${MODULE_ROOT}/getTdNodeErrors.ts`,
         parameters: [
             {
-                name: "parentPath",
-                type: "string",
+                description: "Absolute path to inspect (e.g. /project1/text1).",
+                name: "nodePath",
                 required: true,
-                description: "Where the new node should be created.",
-            },
-            {
-                name: "nodeType",
                 type: "string",
-                required: true,
-                description: "OP type (e.g. textTOP, constantCHOP).",
             },
             {
-                name: "nodeName",
-                type: "string",
+                description: "Formatter verbosity for the returned error list.",
+                name: "detailLevel",
                 required: false,
-                description: "Optional custom name. When omitted TouchDesigner assigns one.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
-                name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
+                description: "Optional limit on how many errors are displayed.",
+                name: "limit",
                 required: false,
-                description: "Formatter verbosity for the creation result.",
+                type: "number",
             },
             {
+                description: "Structured output encoding (json/yaml/markdown).",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Switch result serialization to JSON for scripts.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
-        returns: "Created node metadata including resolved path and properties.",
+        returns: "Error report outlining offending nodes, messages, and counts.",
+        tool: TOOL_NAMES.GET_TD_NODE_ERRORS,
+    },
+    {
+        category: "nodes",
+        description: "Create an operator under a parent path",
         example: `import { createTdNode } from './servers/touchdesigner/createTdNode';
 
 const created = await createTdNode({
@@ -199,202 +205,270 @@ const created = await createTdNode({
   nodeName: 'title',
 });
 console.log(created.result?.path);`,
-    },
-    {
-        tool: TOOL_NAMES.UPDATE_TD_NODE_PARAMETERS,
-        modulePath: `${MODULE_ROOT}/updateTdNodeParameters.ts`,
-        functionName: "updateTdNodeParameters",
-        description: "Patch node properties in bulk",
-        category: "nodes",
+        functionName: "createTdNode",
+        modulePath: `${MODULE_ROOT}/createTdNode.ts`,
         parameters: [
             {
-                name: "nodePath",
-                type: "string",
+                description: "Where the new node should be created.",
+                name: "parentPath",
                 required: true,
-                description: "Target operator path.",
+                type: "string",
             },
             {
-                name: "properties",
-                type: "Record<string, unknown>",
+                description: "OP type (e.g. textTOP, constantCHOP).",
+                name: "nodeType",
                 required: true,
-                description: "Key/value pairs to update on the node.",
+                type: "string",
+            },
+            {
+                description: "Optional custom name. When omitted TouchDesigner assigns one.",
+                name: "nodeName",
+                required: false,
+                type: "string",
             },
             {
+                description: "Formatter verbosity for the creation result.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "Controls how many updated keys are echoed back.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Switch result serialization to JSON for scripts.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Choose JSON when writing audit logs to disk.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
-        returns: "Lists of updated vs failed parameters so the agent can retry selectively.",
+        returns: "Created node metadata including resolved path and properties.",
+        tool: TOOL_NAMES.CREATE_TD_NODE,
+    },
+    {
+        category: "nodes",
+        description: "Patch node properties in bulk",
         example: `import { updateTdNodeParameters } from './servers/touchdesigner/updateTdNodeParameters';
 
 await updateTdNodeParameters({
   nodePath: '/project1/text1',
   properties: { text: 'Hello TouchDesigner' },
 });`,
-    },
-    {
-        tool: TOOL_NAMES.DELETE_TD_NODE,
-        modulePath: `${MODULE_ROOT}/deleteTdNode.ts`,
-        functionName: "deleteTdNode",
-        description: "Remove an operator safely",
-        category: "nodes",
+        functionName: "updateTdNodeParameters",
+        modulePath: `${MODULE_ROOT}/updateTdNodeParameters.ts`,
         parameters: [
             {
+                description: "Target operator path.",
                 name: "nodePath",
+                required: true,
                 type: "string",
+            },
+            {
+                description: "Key/value pairs to update on the node.",
+                name: "properties",
                 required: true,
-                description: "Absolute path of the operator to delete.",
+                type: "Record<string, unknown>",
             },
             {
+                description: "Controls how many updated keys are echoed back.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "Sends only boolean flags when set to minimal.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Choose JSON when writing audit logs to disk.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Structured payload when you need audit logs.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
-        returns: "Deletion status plus previous node metadata when available.",
+        returns: "Lists of updated vs failed parameters so the agent can retry selectively.",
+        tool: TOOL_NAMES.UPDATE_TD_NODE_PARAMETERS,
+    },
+    {
+        category: "nodes",
+        description: "Remove an operator safely",
         example: `import { deleteTdNode } from './servers/touchdesigner/deleteTdNode';
 
 const result = await deleteTdNode({ nodePath: '/project1/tmp1' });
 console.log(result.deleted);`,
+        functionName: "deleteTdNode",
+        modulePath: `${MODULE_ROOT}/deleteTdNode.ts`,
+        parameters: [
+            {
+                description: "Absolute path of the operator to delete.",
+                name: "nodePath",
+                required: true,
+                type: "string",
+            },
+            {
+                description: "Sends only boolean flags when set to minimal.",
+                name: "detailLevel",
+                required: false,
+                type: "'minimal' | 'summary' | 'detailed'",
+            },
+            {
+                description: "Structured payload when you need audit logs.",
+                name: "responseFormat",
+                required: false,
+                type: "'json' | 'yaml' | 'markdown'",
+            },
+        ],
+        returns: "Deletion status plus previous node metadata when available.",
+        tool: TOOL_NAMES.DELETE_TD_NODE,
     },
     {
-        tool: TOOL_NAMES.EXECUTE_NODE_METHOD,
-        modulePath: `${MODULE_ROOT}/execNodeMethod.ts`,
-        functionName: "execNodeMethod",
-        description: "Call TouchDesigner node methods directly",
         category: "nodes",
+        description: "Call TouchDesigner node methods directly",
+        example: `import { execNodeMethod } from './servers/touchdesigner/execNodeMethod';
+
+const renderStatus = await execNodeMethod({
+  nodePath: '/project1/render1',
+  method: 'par',
+  kwargs: { enable: true },
+});
+console.log(renderStatus.result);`,
+        functionName: "execNodeMethod",
+        modulePath: `${MODULE_ROOT}/execNodeMethod.ts`,
         parameters: [
             {
+                description: "OP to target.",
                 name: "nodePath",
-                type: "string",
                 required: true,
-                description: "OP to target.",
+                type: "string",
             },
             {
+                description: "Name of the method to call on that operator.",
                 name: "method",
-                type: "string",
                 required: true,
-                description: "Name of the method to call on that operator.",
+                type: "string",
             },
             {
+                description: "Positional arguments forwarded to the TouchDesigner API.",
                 name: "args",
-                type: "Array<string | number | boolean>",
                 required: false,
-                description: "Positional arguments forwarded to the TouchDesigner API.",
+                type: "Array<string | number | boolean>",
             },
             {
+                description: "Keyword arguments for the method call.",
                 name: "kwargs",
-                type: "Record<string, unknown>",
                 required: false,
-                description: "Keyword arguments for the method call.",
+                type: "Record<string, unknown>",
             },
             {
+                description: "How much of the result payload to echo back.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "How much of the result payload to echo back.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Switch to JSON when storing method responses.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Switch to JSON when storing method responses.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
         returns: "Raw method return payload including any serializable values.",
-        example: `import { execNodeMethod } from './servers/touchdesigner/execNodeMethod';
-
-const renderStatus = await execNodeMethod({
-  nodePath: '/project1/render1',
-  method: 'par',
-  kwargs: { enable: true },
-});
-console.log(renderStatus.result);`,
+        tool: TOOL_NAMES.EXECUTE_NODE_METHOD,
     },
     {
-        tool: TOOL_NAMES.GET_TD_CLASSES,
-        modulePath: `${MODULE_ROOT}/getTdClasses.ts`,
-        functionName: "getTdClasses",
-        description: "List TouchDesigner Python classes/modules",
         category: "classes",
+        description: "List TouchDesigner Python classes/modules",
+        example: `import { getTdClasses } from './servers/touchdesigner/getTdClasses';
+
+const classes = await getTdClasses({ limit: 20 });
+console.log(classes.classes?.map(cls => cls.name));`,
+        functionName: "getTdClasses",
+        modulePath: `${MODULE_ROOT}/getTdClasses.ts`,
         parameters: [
             {
+                description: "Minimal returns only names, summary adds short descriptions.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "Minimal returns only names, summary adds short descriptions.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Restrict the number of classes returned to save tokens.",
                 name: "limit",
-                type: "number",
                 required: false,
-                description: "Restrict the number of classes returned to save tokens.",
+                type: "number",
             },
             {
+                description: "Return the catalog as JSON when writing caches.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Return the catalog as JSON when writing caches.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
         returns: "Python class catalogue with names, types, and optional summaries.",
-        example: `import { getTdClasses } from './servers/touchdesigner/getTdClasses';
-
-const classes = await getTdClasses({ limit: 20 });
-console.log(classes.classes?.map(cls => cls.name));`,
+        tool: TOOL_NAMES.GET_TD_CLASSES,
     },
     {
-        tool: TOOL_NAMES.GET_TD_CLASS_DETAILS,
-        modulePath: `${MODULE_ROOT}/getTdClassDetails.ts`,
-        functionName: "getTdClassDetails",
-        description: "Fetch detailed docs for a TouchDesigner class or module",
         category: "classes",
+        description: "Fetch detailed docs for a TouchDesigner class or module",
+        example: `import { getTdClassDetails } from './servers/touchdesigner/getTdClassDetails';
+
+const textTop = await getTdClassDetails({ className: 'textTOP' });
+console.log(textTop.methods?.length);`,
+        functionName: "getTdClassDetails",
+        modulePath: `${MODULE_ROOT}/getTdClassDetails.ts`,
         parameters: [
             {
+                description: "Class/module name like textTOP or CHOP.",
                 name: "className",
-                type: "string",
                 required: true,
-                description: "Class/module name like textTOP or CHOP.",
+                type: "string",
             },
             {
+                description: "Switch to detailed when generating docs.",
                 name: "detailLevel",
-                type: "'minimal' | 'summary' | 'detailed'",
                 required: false,
-                description: "Switch to detailed when generating docs.",
+                type: "'minimal' | 'summary' | 'detailed'",
             },
             {
+                description: "Cap how many methods/properties are surfaced.",
                 name: "limit",
-                type: "number",
                 required: false,
-                description: "Cap how many methods/properties are surfaced.",
+                type: "number",
             },
             {
+                description: "Emit YAML or JSON for caching results to disk.",
                 name: "responseFormat",
-                type: "'json' | 'yaml' | 'markdown'",
                 required: false,
-                description: "Emit YAML or JSON for caching results to disk.",
+                type: "'json' | 'yaml' | 'markdown'",
             },
         ],
         returns: "Deep description of a Python class including methods and properties.",
-        example: `import { getTdClassDetails } from './servers/touchdesigner/getTdClassDetails';
+        tool: TOOL_NAMES.GET_TD_CLASS_DETAILS,
+    },
+    {
+        category: "classes",
+        description: "Run Python help() to inspect documentation for TouchDesigner modules or classes",
+        example: `import { getTdModuleHelp } from './servers/touchdesigner/getTdModuleHelp';
 
-const textTop = await getTdClassDetails({ className: 'textTOP' });
-console.log(textTop.methods?.length);`,
+const docs = await getTdModuleHelp({ moduleName: 'noiseCHOP' });
+console.log(docs.helpText?.slice(0, 200));`,
+        functionName: "getTdModuleHelp",
+        modulePath: `${MODULE_ROOT}/getTdModuleHelp.ts`,
+        parameters: [
+            {
+                description: "Module or class name (e.g., 'noiseCHOP', 'td.noiseCHOP', 'tdu').",
+                name: "moduleName",
+                required: true,
+                type: "string",
+            },
+            {
+                description: "Controls how much of the help text is shown.",
+                name: "detailLevel",
+                required: false,
+                type: "'minimal' | 'summary' | 'detailed'",
+            },
+            {
+                description: "Select markdown/json/yaml output for automation.",
+                name: "responseFormat",
+                required: false,
+                type: "'json' | 'yaml' | 'markdown'",
+            },
+        ],
+        returns: "Captured Python help() output with formatter context.",
+        tool: TOOL_NAMES.GET_TD_MODULE_HELP,
     },
 ];
 export function getTouchDesignerToolMetadata() {