touchdesigner-mcp-server 0.4.7 → 1.1.0

package/dist/features/tools/handlers/tdTools.js

@@ -1,18 +1,83 @@
+import { z } from "zod";
 import { REFERENCE_COMMENT, TOOL_NAMES } from "../../../core/constants.js";
 import { handleToolError } from "../../../core/errorHandling.js";
 import { createNodeBody, deleteNodeQueryParams, execNodeMethodBody, execPythonScriptBody, getNodeDetailQueryParams, getNodesQueryParams, getTdPythonClassDetailsParams, updateNodeBody, } from "../../../gen/mcp/touchDesignerAPI.zod.js";
+import { getTouchDesignerToolMetadata } from "../metadata/touchDesignerToolMetadata.js";
+import { formatClassDetails, formatClassList, formatCreateNodeResult, formatDeleteNodeResult, formatExecNodeMethodResult, formatNodeDetails, formatNodeList, formatScriptResult, formatTdInfo, formatToolMetadata, formatUpdateNodeResult, } from "../presenter/index.js";
+import { detailOnlyFormattingSchema, formattingOptionsSchema, } from "../types.js";
+const execPythonScriptToolSchema = execPythonScriptBody.extend(detailOnlyFormattingSchema.shape);
+const tdInfoToolSchema = detailOnlyFormattingSchema;
+const getNodesToolSchema = getNodesQueryParams.extend(formattingOptionsSchema.shape);
+const getNodeDetailToolSchema = getNodeDetailQueryParams.extend(formattingOptionsSchema.shape);
+const createNodeToolSchema = createNodeBody.extend(detailOnlyFormattingSchema.shape);
+const updateNodeToolSchema = updateNodeBody.extend(detailOnlyFormattingSchema.shape);
+const deleteNodeToolSchema = deleteNodeQueryParams.extend(detailOnlyFormattingSchema.shape);
+const classListToolSchema = formattingOptionsSchema;
+const classDetailToolSchema = getTdPythonClassDetailsParams.extend(formattingOptionsSchema.shape);
+const execNodeMethodToolSchema = execNodeMethodBody.extend(detailOnlyFormattingSchema.shape);
+const describeToolsSchema = detailOnlyFormattingSchema.extend({
+    filter: z
+        .string()
+        .min(1)
+        .describe("Optional keyword to filter by tool name, module path, or parameter description")
+        .optional(),
+});
 export function registerTdTools(server, logger, tdClient) {
-    server.tool(TOOL_NAMES.GET_TD_INFO, "Get server information from TouchDesigner", async () => {
+    const toolMetadataEntries = getTouchDesignerToolMetadata();
+    server.tool(TOOL_NAMES.DESCRIBE_TD_TOOLS, "Generate a filesystem-oriented manifest of available TouchDesigner tools", describeToolsSchema.strict().shape, async (params = {}) => {
         try {
+            const { detailLevel, responseFormat, filter } = params;
+            const normalizedFilter = filter?.trim().toLowerCase();
+            const filteredEntries = normalizedFilter
+                ? toolMetadataEntries.filter((entry) => matchesMetadataFilter(entry, normalizedFilter))
+                : toolMetadataEntries;
+            if (filteredEntries.length === 0) {
+                const message = filter
+                    ? `No TouchDesigner tools matched filter "${filter}".`
+                    : "No TouchDesigner tools are registered.";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: message,
+                        },
+                    ],
+                };
+            }
+            const formattedText = formatToolMetadata(filteredEntries, {
+                detailLevel: detailLevel ?? (filter ? "summary" : "minimal"),
+                responseFormat,
+                filter: normalizedFilter,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formattedText,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return handleToolError(error, logger, TOOL_NAMES.DESCRIBE_TD_TOOLS);
+        }
+    });
+    server.tool(TOOL_NAMES.GET_TD_INFO, "Get server information from TouchDesigner", tdInfoToolSchema.strict().shape, async (params = {}) => {
+        try {
+            const { detailLevel, responseFormat } = params;
             const result = await tdClient.getTdInfo();
             if (!result.success) {
                 throw result.error;
             }
+            const formattedText = formatTdInfo(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Server information: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -21,19 +86,24 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_INFO);
         }
     });
-    server.tool(TOOL_NAMES.EXECUTE_PYTHON_SCRIPT, "Execute Python script directly in TouchDesigner", execPythonScriptBody.strict().shape, async (params) => {
+    server.tool(TOOL_NAMES.EXECUTE_PYTHON_SCRIPT, "Execute a Python script in TouchDesigner (detailLevel=minimal|summary|detailed, responseFormat=json|yaml|markdown)", execPythonScriptToolSchema.strict().shape, async (params) => {
         try {
-            const { script } = params;
-            logger.debug(`Executing script: ${script}`);
-            const result = await tdClient.execPythonScript(params);
+            const { detailLevel, responseFormat, ...scriptParams } = params;
+            logger.debug(`Executing script: ${scriptParams.script}`);
+            const result = await tdClient.execPythonScript(scriptParams);
             if (!result.success) {
                 throw result.error;
             }
+            // Use formatter for token-optimized response
+            const formattedText = formatScriptResult(result, scriptParams.script, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Script executed successfully. Result: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -42,22 +112,22 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.EXECUTE_PYTHON_SCRIPT);
         }
     });
-    server.tool(TOOL_NAMES.CREATE_TD_NODE, "Create a new node in TouchDesigner", createNodeBody.strict().shape, async (params) => {
+    server.tool(TOOL_NAMES.CREATE_TD_NODE, "Create a new node in TouchDesigner", createNodeToolSchema.strict().shape, async (params) => {
         try {
-            const { parentPath, nodeType, nodeName } = params;
-            const result = await tdClient.createNode({
-                parentPath,
-                nodeType,
-                nodeName,
-            });
+            const { detailLevel, responseFormat, ...createParams } = params;
+            const result = await tdClient.createNode(createParams);
             if (!result.success) {
                 throw result.error;
             }
+            const formattedText = formatCreateNodeResult(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Node created successfully: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -66,17 +136,22 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.CREATE_TD_NODE, REFERENCE_COMMENT);
         }
     });
-    server.tool(TOOL_NAMES.DELETE_TD_NODE, "Delete an existing node in TouchDesigner", deleteNodeQueryParams.strict().shape, async (params) => {
+    server.tool(TOOL_NAMES.DELETE_TD_NODE, "Delete an existing node in TouchDesigner", deleteNodeToolSchema.strict().shape, async (params) => {
         try {
-            const result = await tdClient.deleteNode(params);
+            const { detailLevel, responseFormat, ...deleteParams } = params;
+            const result = await tdClient.deleteNode(deleteParams);
             if (!result.success) {
                 throw result.error;
             }
+            const formattedText = formatDeleteNodeResult(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Node deleted successfully: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -85,22 +160,27 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.DELETE_TD_NODE, REFERENCE_COMMENT);
         }
     });
-    server.tool(TOOL_NAMES.GET_TD_NODES, "Get all nodes in the parent path (lightweight by default for better performance)", getNodesQueryParams.strict().shape, async (params) => {
+    server.tool(TOOL_NAMES.GET_TD_NODES, "List nodes under a path with token-optimized output (detailLevel+limit supported)", getNodesToolSchema.strict().shape, async (params) => {
         try {
-            const result = await tdClient.getNodes(params);
+            const { detailLevel, limit, responseFormat, ...queryParams } = params;
+            const result = await tdClient.getNodes(queryParams);
             if (!result.success) {
                 throw result.error;
             }
-            const nodeCount = result.data?.nodes?.length || 0;
-            const isLightweight = !params.includeProperties;
-            const performanceNote = isLightweight
-                ? " (lightweight mode - set includeProperties=true for full node details)"
-                : " (full mode with properties)";
+            // Use formatter for token-optimized response
+            const fallbackMode = queryParams.includeProperties
+                ? "detailed"
+                : "summary";
+            const formattedText = formatNodeList(result.data, {
+                detailLevel: detailLevel ?? fallbackMode,
+                limit,
+                responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Project nodes retrieved (${nodeCount} nodes)${performanceNote}: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -109,18 +189,24 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_NODES, REFERENCE_COMMENT);
         }
     });
-    server.tool(TOOL_NAMES.GET_TD_NODE_PARAMETERS, "Get parameters of a specific node in TouchDesigner", getNodeDetailQueryParams.strict().shape, async (params) => {
+    server.tool(TOOL_NAMES.GET_TD_NODE_PARAMETERS, "Get node parameters with concise/detailed formatting (detailLevel+limit supported)", getNodeDetailToolSchema.strict().shape, async (params) => {
         try {
-            const { nodePath } = params;
-            const result = await tdClient.getNodeDetail(params);
+            const { detailLevel, limit, responseFormat, ...queryParams } = params;
+            const result = await tdClient.getNodeDetail(queryParams);
             if (!result.success) {
                 throw result.error;
             }
+            // Use formatter for token-optimized response
+            const formattedText = formatNodeDetails(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                limit,
+                responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Node parameters for node at path ${nodePath}: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -129,17 +215,22 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_NODE_PARAMETERS, REFERENCE_COMMENT);
         }
     });
-    server.tool(TOOL_NAMES.UPDATE_TD_NODE_PARAMETERS, "Update parameters of a specific node in TouchDesigner", updateNodeBody.strict().shape, async (params) => {
+    server.tool(TOOL_NAMES.UPDATE_TD_NODE_PARAMETERS, "Update parameters of a specific node in TouchDesigner", updateNodeToolSchema.strict().shape, async (params) => {
         try {
-            const result = await tdClient.updateNode(params);
+            const { detailLevel, responseFormat, ...updateParams } = params;
+            const result = await tdClient.updateNode(updateParams);
             if (!result.success) {
                 throw result.error;
             }
+            const formattedText = formatUpdateNodeResult(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Node parameters updated successfully: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -148,26 +239,20 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.UPDATE_TD_NODE_PARAMETERS, REFERENCE_COMMENT);
         }
     });
-    server.tool(TOOL_NAMES.EXECUTE_NODE_METHOD, "Execute a method on a specific node in TouchDesigner", execNodeMethodBody.strict().shape, async (params) => {
+    server.tool(TOOL_NAMES.EXECUTE_NODE_METHOD, "Execute a method on a specific node in TouchDesigner", execNodeMethodToolSchema.strict().shape, async (params) => {
         try {
-            const { nodePath, method, args } = params;
-            const result = await tdClient.execNodeMethod(params);
+            const { detailLevel, responseFormat, ...execParams } = params;
+            const { nodePath, method, args, kwargs } = execParams;
+            const result = await tdClient.execNodeMethod(execParams);
             if (!result.success) {
                 throw result.error;
             }
+            const formattedText = formatExecNodeMethodResult(result.data, { nodePath, method, args, kwargs }, { detailLevel: detailLevel ?? "summary", responseFormat });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `op('${nodePath}').${method}(${args?.map((v) => `"${v}"`).join(",")}${params.kwargs
-                            ? Object.entries(params.kwargs)
-                                .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
-                                .join(", ")
-                            : ""})`,
-                    },
-                    {
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
+                        text: formattedText,
                     },
                 ],
             };
@@ -177,17 +262,23 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.EXECUTE_NODE_METHOD, REFERENCE_COMMENT);
         }
     });
-    server.tool(TOOL_NAMES.GET_TD_CLASSES, "Get list of classes and modules in TouchDesigner", async () => {
+    server.tool(TOOL_NAMES.GET_TD_CLASSES, "List TouchDesigner Python classes/modules (detailLevel+limit supported)", classListToolSchema.strict().shape, async (params = {}) => {
         try {
             const result = await tdClient.getClasses();
             if (!result.success) {
                 throw result.error;
             }
+            // Use formatter for token-optimized response
+            const formattedText = formatClassList(result.data, {
+                detailLevel: params.detailLevel ?? "summary",
+                limit: params.limit ?? 50,
+                responseFormat: params.responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `TouchDesigner classes list: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -196,18 +287,24 @@ export function registerTdTools(server, logger, tdClient) {
             return handleToolError(error, logger, TOOL_NAMES.GET_TD_CLASSES, REFERENCE_COMMENT);
         }
     });
-    server.tool(TOOL_NAMES.GET_TD_CLASS_DETAILS, "Get detailed information about a specific TouchDesigner class or module", getTdPythonClassDetailsParams.strict().shape, async (params) => {
+    server.tool(TOOL_NAMES.GET_TD_CLASS_DETAILS, "Get information about a TouchDesigner class/module (detailLevel+limit supported)", classDetailToolSchema.strict().shape, async (params) => {
         try {
-            const { className } = params;
+            const { className, detailLevel, limit, responseFormat } = params;
             const result = await tdClient.getClassDetails(className);
             if (!result.success) {
                 throw result.error;
             }
+            // Use formatter for token-optimized response
+            const formattedText = formatClassDetails(result.data, {
+                detailLevel: detailLevel ?? "summary",
+                limit: limit ?? 30,
+                responseFormat,
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Details for ${className}: ${JSON.stringify(result, null, 2)}`,
+                        text: formattedText,
                     },
                 ],
             };
@@ -217,3 +314,18 @@ export function registerTdTools(server, logger, tdClient) {
         }
     });
 }
+function matchesMetadataFilter(entry, keyword) {
+    const normalizedKeyword = keyword.toLowerCase();
+    const haystacks = [
+        entry.functionName,
+        entry.modulePath,
+        entry.description,
+        entry.category,
+        entry.tool,
+        entry.notes ?? "",
+    ];
+    if (haystacks.some((value) => value.toLowerCase().includes(normalizedKeyword))) {
+        return true;
+    }
+    return entry.parameters.some((param) => [param.name, param.type, param.description ?? ""].some((value) => value.toLowerCase().includes(normalizedKeyword)));
+}