touchdesigner-mcp-server 1.2.0 → 1.3.1

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

@@ -28,9 +28,9 @@ export function formatClassList(data, options) {
         : formatClassListSummary(classes, modules, opts.limit);
     const ctx = context;
     return finalizeFormattedText(text, opts, {
-        template: "classListSummary",
         context: ctx,
         structured: ctx,
+        template: "classListSummary",
     });
 }
 /**
@@ -49,9 +49,9 @@ export function formatClassDetails(data, options) {
         : formatClassDetailsSummary(data, opts.limit);
     const ctx = context;
     return finalizeFormattedText(text, opts, {
-        template: "classDetailsSummary",
         context: ctx,
         structured: ctx,
+        template: "classDetailsSummary",
     });
 }
 function formatClassListMinimal(classes, modules, limit) {
@@ -66,8 +66,8 @@ function formatClassListMinimal(classes, modules, limit) {
         text += `\nModules (${modules.length}): ${modules.join(", ")}`;
     }
     return {
-        text,
         context: buildClassListContext(classes, modules),
+        text,
     };
 }
 function formatClassListSummary(classes, modules, limit) {
@@ -78,37 +78,37 @@ function formatClassListSummary(classes, modules, limit) {
         .map((m) => `- ${m}`)
         .join("\n")}`;
     return {
-        text,
         context: buildClassListContext(classes, modules),
+        text,
     };
 }
 function buildClassListContext(classes, modules) {
     return {
         classCount: classes.length,
-        moduleCount: modules.length,
         classes: classes.map((cls) => ({
-            name: cls.name,
             description: cls.description,
+            name: cls.name,
         })),
+        moduleCount: modules.length,
         modules,
     };
 }
 function formatClassDetailsMinimal(data) {
     const text = `Class: ${data.name}\nType: ${data.type}`;
     return {
-        text,
         context: {
-            name: data.name,
-            type: data.type,
             description: data.description,
+            methods: [],
             methodsShown: 0,
             methodsTotal: data.methods?.length ?? 0,
-            methods: [],
+            name: data.name,
+            properties: [],
             propertiesShown: 0,
             propertiesTotal: data.properties?.length ?? 0,
-            properties: [],
             truncated: false,
+            type: data.type,
         },
+        text,
     };
 }
 function formatClassDetailsSummary(data, limit) {
@@ -148,25 +148,25 @@ function formatClassDetailsSummary(data, limit) {
         }
     }
     return {
-        text,
         context: {
-            name: data.name,
-            type: data.type,
             description: data.description,
-            methodsShown: limitedMethods.length,
-            methodsTotal: methods.length,
             methods: limitedMethods.map((method) => ({
                 signature: method.signature || `${method.name}()`,
                 summary: method.description?.split("\n")[0] ?? "",
             })),
-            propertiesShown: limitedProps.length,
-            propertiesTotal: properties.length,
+            methodsShown: limitedMethods.length,
+            methodsTotal: methods.length,
+            name: data.name,
             properties: limitedProps.map((prop) => ({
                 name: prop.name,
                 type: prop.type,
             })),
+            propertiesShown: limitedProps.length,
+            propertiesTotal: properties.length,
             truncated: methodsTruncated || propsTruncated,
+            type: data.type,
         },
+        text,
     };
 }
 function formatDetailed(data, format) {
@@ -175,13 +175,13 @@ function formatDetailed(data, format) {
         : "TouchDesigner Classes";
     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);
 }

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

@@ -4,7 +4,9 @@
  * Central export point for all response formatters
  */
 export { formatClassDetails, formatClassList } from "./classListFormatter.js";
+export { formatModuleHelp } from "./moduleHelpFormatter.js";
 export { formatNodeDetails } from "./nodeDetailsFormatter.js";
+export { formatNodeErrors } from "./nodeErrorsFormatter.js";
 export { formatNodeList } from "./nodeListFormatter.js";
 export { formatCreateNodeResult, formatDeleteNodeResult, formatExecNodeMethodResult, formatTdInfo, formatUpdateNodeResult, } from "./operationFormatter.js";
 export { formatScriptResult } from "./scriptResultFormatter.js";

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

@@ -0,0 +1,315 @@
+/**
+ * Module Help Formatter
+ *
+ * Formats TouchDesigner module help information with token optimization.
+ * Used by GET_MODULE_HELP tool.
+ */
+import { DEFAULT_PRESENTER_FORMAT, presentStructuredData, } from "./presenter.js";
+import { finalizeFormattedText, mergeFormatterOptions, } from "./responseFormatter.js";
+/**
+ * Format module help result
+ */
+export function formatModuleHelp(data, options) {
+    const opts = mergeFormatterOptions(options);
+    if (!data?.helpText) {
+        return "No help information available.";
+    }
+    const moduleName = data.moduleName ?? "Unknown";
+    const helpText = data.helpText;
+    const members = extractModuleMembers(helpText);
+    const classInfo = extractClassSummary(helpText);
+    if (opts.detailLevel === "detailed") {
+        return formatDetailed(moduleName, helpText, opts.responseFormat);
+    }
+    let formattedText = "";
+    let context;
+    switch (opts.detailLevel) {
+        case "minimal":
+        case "summary": {
+            const summary = formatSummary(moduleName, helpText, members, classInfo);
+            formattedText = summary.text;
+            context = summary.context;
+            break;
+        }
+        default:
+            formattedText = helpText;
+            context = buildHelpContext(moduleName, helpText, members, classInfo);
+    }
+    const ctx = context;
+    return finalizeFormattedText(formattedText, opts, {
+        context: ctx,
+        structured: ctx,
+        template: "moduleHelp",
+    });
+}
+/**
+ * Summary mode: Module name with key sections
+ */
+function formatSummary(moduleName, helpText, members, classInfo) {
+    const sections = extractHelpSections(helpText);
+    const preview = extractHelpPreview(helpText, 500);
+    const memberSummary = formatMemberSummary(members);
+    const lines = [`✓ Help information for ${moduleName}`];
+    if (classInfo?.definition) {
+        lines.push(`Class: ${classInfo.definition}`);
+    }
+    if (classInfo?.description) {
+        lines.push(classInfo.description);
+    }
+    if (classInfo?.methodResolutionOrder?.length) {
+        lines.push(`MRO: ${classInfo.methodResolutionOrder.join(" → ")}`);
+    }
+    lines.push("");
+    if (sections.length > 0) {
+        lines.push(`Sections: ${sections.join(", ")}`, "");
+    }
+    lines.push(preview);
+    if (memberSummary) {
+        lines.push("", memberSummary);
+    }
+    if (helpText.length > 500) {
+        lines.push("", `💡 Use detailLevel='detailed' to see full documentation (${helpText.length} chars total).`);
+    }
+    return {
+        context: {
+            classInfo,
+            fullLength: helpText.length,
+            helpPreview: preview,
+            members,
+            moduleName,
+            sections,
+        },
+        text: lines.join("\n"),
+    };
+}
+/**
+ * Detailed mode: Full help text
+ */
+function formatDetailed(moduleName, helpText, format) {
+    const title = `Help for ${moduleName}`;
+    const payloadFormat = format ?? DEFAULT_PRESENTER_FORMAT;
+    // For detailed view, return formatted markdown
+    let formatted = `# ${title}\n\n`;
+    formatted += "```\n";
+    formatted += helpText;
+    formatted += "\n```";
+    return presentStructuredData({
+        context: {
+            payloadFormat,
+            title,
+        },
+        detailLevel: "detailed",
+        structured: {
+            helpText,
+            length: helpText.length,
+            moduleName,
+        },
+        template: "moduleHelpDetailed",
+        text: formatted,
+    }, payloadFormat);
+}
+/**
+ * Build help context
+ */
+function buildHelpContext(moduleName, helpText, members, classInfo) {
+    return {
+        classInfo,
+        fullLength: helpText.length,
+        helpPreview: extractHelpPreview(helpText, 200),
+        members,
+        moduleName,
+        sections: extractHelpSections(helpText),
+    };
+}
+/**
+ * Extract preview from help text
+ */
+function extractHelpPreview(helpText, maxChars) {
+    const trimmed = helpText.trim();
+    if (trimmed.length <= maxChars) {
+        return trimmed;
+    }
+    // Try to cut at a natural break point (newline)
+    const firstPart = trimmed.substring(0, maxChars);
+    const lastNewline = firstPart.lastIndexOf("\n");
+    if (lastNewline > maxChars * 0.7) {
+        return `${firstPart.substring(0, lastNewline)}...`;
+    }
+    return `${firstPart}...`;
+}
+/**
+ * Extract section headers from help text
+ */
+function extractHelpSections(helpText) {
+    const sections = [];
+    const lines = helpText.split("\n");
+    // Common help section patterns
+    const sectionPatterns = [
+        /^([A-Z][A-Za-z\s]+):$/,
+        /^\s*([A-Z][A-Z\s]+)$/,
+        /^-+\s*$/,
+    ];
+    let lastSection = "";
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Check for section headers
+        for (const pattern of sectionPatterns) {
+            const match = trimmed.match(pattern);
+            if (match?.[1]) {
+                const section = match[1].trim();
+                if (section && section !== lastSection && section.length < 50) {
+                    sections.push(section);
+                    lastSection = section;
+                }
+                break;
+            }
+        }
+        // Limit to first 10 sections
+        if (sections.length >= 10) {
+            break;
+        }
+    }
+    return sections;
+}
+function extractModuleMembers(helpText) {
+    const methods = [];
+    const properties = [];
+    const seenMethods = new Set();
+    const seenProperties = new Set();
+    const lines = helpText.split("\n");
+    let currentCategory;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const normalized = trimmed.replace(/^\|/, "").trim();
+        const headerMatch = normalized.match(/^(.*?):$/);
+        if (headerMatch) {
+            const newCategory = categorizeSection(headerMatch[1]);
+            if (newCategory) {
+                currentCategory = newCategory;
+            }
+            continue;
+        }
+        if (!currentCategory)
+            continue;
+        const entryMatch = trimmed.match(/^\|\s{2,4}([A-Za-z_][\w]*)/);
+        if (!entryMatch)
+            continue;
+        const name = entryMatch[1];
+        if (!name)
+            continue;
+        if (currentCategory === "method") {
+            if (!seenMethods.has(name)) {
+                seenMethods.add(name);
+                methods.push(name);
+            }
+        }
+        else if (currentCategory === "property") {
+            if (!seenProperties.has(name)) {
+                seenProperties.add(name);
+                properties.push(name);
+            }
+        }
+    }
+    return { methods, properties };
+}
+function extractClassSummary(helpText) {
+    const lines = helpText.split("\n");
+    let definition;
+    const descriptionLines = [];
+    const methodResolutionOrder = [];
+    let inDescription = false;
+    let inMro = false;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        if (!definition) {
+            const defMatch = trimmed.match(/^class\s+(.+)$/);
+            if (defMatch) {
+                definition = defMatch[1];
+                inDescription = true;
+                continue;
+            }
+        }
+        if (inDescription) {
+            if (!trimmed || trimmed.startsWith("|  Methods defined here:")) {
+                inDescription = false;
+                continue; // Skip further processing of this line
+            }
+            if (trimmed.startsWith("|")) {
+                const desc = trimmed.replace(/^\|\s*/, "");
+                if (desc) {
+                    descriptionLines.push(desc);
+                }
+            }
+        }
+        if (trimmed.startsWith("|  Method resolution order:")) {
+            inMro = true;
+            continue;
+        }
+        if (inMro) {
+            if (!trimmed.startsWith("|")) {
+                // MRO section ended - fall through to the exit check below
+                inMro = false;
+            }
+            else {
+                const entry = trimmed.replace(/^\|\s*/, "");
+                if (entry) {
+                    methodResolutionOrder.push(entry.trim());
+                }
+            }
+        }
+        // Exit early once we have collected the MRO and we're done with both sections
+        if (methodResolutionOrder.length > 0 && !inMro && !inDescription) {
+            break;
+        }
+    }
+    if (!definition &&
+        descriptionLines.length === 0 &&
+        methodResolutionOrder.length === 0) {
+        return undefined;
+    }
+    return {
+        definition,
+        description: descriptionLines.slice(0, 3).join(" "),
+        methodResolutionOrder: methodResolutionOrder.length
+            ? methodResolutionOrder
+            : undefined,
+    };
+}
+function categorizeSection(sectionName) {
+    const normalized = sectionName.toLowerCase();
+    if (normalized.includes("method")) {
+        return "method";
+    }
+    if (normalized.includes("descriptor") ||
+        normalized.includes("attribute") ||
+        normalized.includes("property")) {
+        return "property";
+    }
+    return undefined;
+}
+function formatMemberSummary(members, limitPerGroup) {
+    const segments = [];
+    const methodSummary = formatMemberGroup("Methods", members.methods, limitPerGroup);
+    if (methodSummary) {
+        segments.push(methodSummary);
+    }
+    const propertySummary = formatMemberGroup("Properties", members.properties, limitPerGroup);
+    if (propertySummary) {
+        segments.push(propertySummary);
+    }
+    return segments.join("\n\n");
+}
+function formatMemberGroup(label, items, limit) {
+    if (items.length === 0) {
+        return undefined;
+    }
+    const effectiveLimit = typeof limit === "number" && Number.isFinite(limit)
+        ? Math.max(limit, 0)
+        : items.length;
+    const displayed = items.slice(0, effectiveLimit);
+    const suffix = items.length > effectiveLimit ? ", …" : "";
+    return `${label} (${items.length}): ${displayed.join(", ")}${suffix}`;
+}

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

@@ -32,9 +32,9 @@ export function formatNodeDetails(data, options) {
     }
     const context = result.context;
     return finalizeFormattedText(result.text, opts, {
-        template: "nodeDetailsSummary",
         context,
         structured: context,
+        template: "nodeDetailsSummary",
     });
 }
 /**
@@ -47,18 +47,18 @@ function formatMinimal(nodePath, propertyKeys, limit) {
         text += `\n💡 ${propertyKeys.length - items.length} more properties omitted.`;
     }
     return {
-        text,
         context: {
-            nodePath,
-            type: "",
+            displayed: items.length,
             id: 0,
             name: "",
-            total: propertyKeys.length,
-            displayed: items.length,
+            nodePath,
+            omittedCount: Math.max(propertyKeys.length - items.length, 0),
             properties: items.map((name) => ({ name, value: "" })),
+            total: propertyKeys.length,
             truncated,
-            omittedCount: Math.max(propertyKeys.length - items.length, 0),
+            type: "",
         },
+        text,
     };
 }
 /**
@@ -82,18 +82,18 @@ function formatSummary(nodePath, data, limit) {
         text += `\n💡 ${propertyEntries.length - items.length} more properties omitted.`;
     }
     return {
-        text,
         context: {
-            nodePath,
-            type: data.opType,
+            displayed: items.length,
             id: data.id,
             name: data.name,
-            total: propertyEntries.length,
-            displayed: items.length,
+            nodePath,
+            omittedCount: Math.max(propertyEntries.length - items.length, 0),
             properties: propsForContext,
+            total: propertyEntries.length,
             truncated,
-            omittedCount: Math.max(propertyEntries.length - items.length, 0),
+            type: data.opType,
         },
+        text,
     };
 }
 /**
@@ -103,14 +103,14 @@ function formatDetailed(data, format) {
     const title = `Node ${data.path ?? data.name ?? "details"}`;
     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);
 }
 /**

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

@@ -0,0 +1,68 @@
+import { DEFAULT_PRESENTER_FORMAT, presentStructuredData, } from "./presenter.js";
+import { finalizeFormattedText, limitArray, mergeFormatterOptions, } from "./responseFormatter.js";
+export function formatNodeErrors(data, options) {
+    const opts = mergeFormatterOptions(options);
+    if (!data) {
+        return "No node error information is available.";
+    }
+    if (opts.detailLevel === "detailed") {
+        return formatDetailed(data, opts.responseFormat);
+    }
+    const errors = data.errors ?? [];
+    if (errors.length === 0 || !data.hasErrors || data.errorCount === 0) {
+        const noErrorText = `Node ${data.nodePath} has no reported errors.`;
+        return finalizeFormattedText(noErrorText, opts, {
+            context: {
+                errorCount: 0,
+                nodeName: data.nodeName,
+                nodePath: data.nodePath,
+            },
+            structured: data,
+            template: "nodeErrorSummary",
+        });
+    }
+    const { items, truncated } = limitArray(errors, opts.limit);
+    const header = `Node: ${data.nodePath}\nOperator: ${data.opType} (${data.nodeName})\n${data.errorCount} error(s) found\n`;
+    const body = opts.detailLevel === "minimal"
+        ? formatMinimal(items)
+        : formatSummary(items);
+    let text = `${header}\n${body}`;
+    if (truncated) {
+        text += `\n💡 ${data.errorCount - items.length} more errors omitted.`;
+    }
+    return finalizeFormattedText(text, opts, {
+        context: {
+            displayed: items.length,
+            errorCount: data.errorCount,
+            nodeName: data.nodeName,
+            nodePath: data.nodePath,
+            opType: data.opType,
+        },
+        structured: data,
+        template: "nodeErrorSummary",
+    });
+}
+function formatMinimal(errors) {
+    return errors
+        .map((entry) => `- ${entry.nodePath}: ${entry.message}`)
+        .join("\n");
+}
+function formatSummary(errors) {
+    return errors
+        .map((entry) => `- ${entry.nodePath} (${entry.opType}): ${entry.message}`)
+        .join("\n");
+}
+function formatDetailed(data, format) {
+    const title = `Node error report for ${data.nodePath}`;
+    const payloadFormat = format ?? DEFAULT_PRESENTER_FORMAT;
+    return presentStructuredData({
+        context: {
+            payloadFormat,
+            title,
+        },
+        detailLevel: "detailed",
+        structured: data,
+        template: "detailedPayload",
+        text: title,
+    }, payloadFormat);
+}

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

@@ -40,9 +40,9 @@ export function formatNodeList(data, options) {
         context.omittedCount = 0;
     }
     return finalizeFormattedText(output, opts, {
-        template: "nodeListSummary",
         context,
         structured: context,
+        template: "nodeListSummary",
     });
 }
 /**
@@ -53,8 +53,8 @@ function formatMinimal(nodes, parentPath, totalCount, truncated) {
     const text = `Found ${nodes.length} nodes in ${parentPath}:
 ${paths.join("\n")}`;
     return {
-        text,
         context: buildNodeListContext(nodes, parentPath, totalCount, truncated),
+        text,
     };
 }
 /**
@@ -71,14 +71,14 @@ function formatSummary(nodes, parentPath, totalCount, truncated) {
 ${nodeLines.join("\n")}`;
     });
     return {
-        text: header + sections.join("\n\n"),
         context: {
+            groups,
+            omittedCount: Math.max(totalCount - nodes.length, 0),
             parentPath,
             totalCount,
-            groups,
             truncated,
-            omittedCount: Math.max(totalCount - nodes.length, 0),
         },
+        text: header + sections.join("\n\n"),
     };
 }
 /**
@@ -88,23 +88,23 @@ function formatDetailed(nodes, data, format, parentPath) {
     const title = `Nodes in ${parentPath}`;
     const payloadFormat = format ?? DEFAULT_PRESENTER_FORMAT;
     return presentStructuredData({
-        text: title,
-        detailLevel: "detailed",
-        structured: { ...data, nodes },
         context: {
-            title,
             payloadFormat,
+            title,
         },
+        detailLevel: "detailed",
+        structured: { ...data, nodes },
         template: "detailedPayload",
+        text: title,
     }, payloadFormat);
 }
 function buildNodeListContext(nodes, parentPath, totalCount, truncated) {
     return {
+        groups: buildGroups(nodes),
+        omittedCount: Math.max(totalCount - nodes.length, 0),
         parentPath,
         totalCount,
-        groups: buildGroups(nodes),
         truncated,
-        omittedCount: Math.max(totalCount - nodes.length, 0),
     };
 }
 function buildGroups(nodes) {
@@ -117,8 +117,8 @@ function buildGroups(nodes) {
         byType.get(type)?.push(node);
     }
     return Array.from(byType.entries()).map(([type, typeNodes]) => ({
-        type,
         count: typeNodes.length,
         nodes: typeNodes.map((n) => ({ name: n.name, path: n.path })),
+        type,
     }));
 }