touchdesigner-mcp-server 1.0.0 → 1.1.0

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

@@ -0,0 +1,140 @@
+/**
+ * Node Details Formatter
+ *
+ * Formats TouchDesigner node parameter details with token optimization.
+ * Used by GET_TD_NODE_PARAMETERS tool.
+ */
+import { DEFAULT_PRESENTER_FORMAT, presentStructuredData, } from "./presenter.js";
+import { finalizeFormattedText, limitArray, mergeFormatterOptions, } from "./responseFormatter.js";
+/**
+ * Format node parameter details
+ */
+export function formatNodeDetails(data, options) {
+    const opts = mergeFormatterOptions(options);
+    if (!data) {
+        return "No node details available.";
+    }
+    const nodePath = data.path;
+    const properties = data.properties;
+    const propertyKeys = properties ? Object.keys(properties) : [];
+    if (propertyKeys.length === 0) {
+        return `Node: ${nodePath}\nNo properties found.`;
+    }
+    if (opts.detailLevel === "detailed") {
+        return formatDetailed(data, opts.responseFormat);
+    }
+    let result;
+    if (opts.detailLevel === "minimal") {
+        result = formatMinimal(nodePath, propertyKeys, opts.limit);
+    }
+    else {
+        result = formatSummary(nodePath, data, opts.limit);
+    }
+    const context = result.context;
+    return finalizeFormattedText(result.text, opts, {
+        template: "nodeDetailsSummary",
+        context,
+        structured: context,
+    });
+}
+/**
+ * Minimal mode: Property names only
+ */
+function formatMinimal(nodePath, propertyKeys, limit) {
+    const { items, truncated } = limitArray(propertyKeys, limit);
+    let text = `Node: ${nodePath}\nProperties (${propertyKeys.length}):\n${items.join(", ")}`;
+    if (truncated) {
+        text += `\n💡 ${propertyKeys.length - items.length} more properties omitted.`;
+    }
+    return {
+        text,
+        context: {
+            nodePath,
+            type: "",
+            id: 0,
+            name: "",
+            total: propertyKeys.length,
+            displayed: items.length,
+            properties: items.map((name) => ({ name, value: "" })),
+            truncated,
+            omittedCount: Math.max(propertyKeys.length - items.length, 0),
+        },
+    };
+}
+/**
+ * Summary mode: Key properties with values
+ */
+function formatSummary(nodePath, data, limit) {
+    const properties = data.properties || {};
+    const propertyEntries = Object.entries(properties);
+    const { items, truncated } = limitArray(propertyEntries, limit);
+    let text = `Node: ${nodePath}\n`;
+    text += `Type: ${data.opType} (ID: ${data.id})\n`;
+    text += `Name: ${data.name}\n`;
+    text += `\nProperties (${propertyEntries.length}):\n\n`;
+    const propsForContext = [];
+    for (const [key, value] of items) {
+        const formattedValue = formatPropertyValue(value);
+        text += `  ${key}: ${formattedValue}\n`;
+        propsForContext.push({ name: key, value: formattedValue });
+    }
+    if (truncated) {
+        text += `\n💡 ${propertyEntries.length - items.length} more properties omitted.`;
+    }
+    return {
+        text,
+        context: {
+            nodePath,
+            type: data.opType,
+            id: data.id,
+            name: data.name,
+            total: propertyEntries.length,
+            displayed: items.length,
+            properties: propsForContext,
+            truncated,
+            omittedCount: Math.max(propertyEntries.length - items.length, 0),
+        },
+    };
+}
+/**
+ * Detailed mode: Full JSON
+ */
+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,
+        },
+        template: "detailedPayload",
+    }, payloadFormat);
+}
+/**
+ * Format property value for display
+ */
+function formatPropertyValue(value) {
+    if (value === undefined || value === null) {
+        return "(none)";
+    }
+    if (typeof value === "string") {
+        return value.length > 50 ? `"${value.substring(0, 50)}..."` : `"${value}"`;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        if (value.length <= 3)
+            return `[${value.join(", ")}]`;
+        return `[${value.slice(0, 3).join(", ")}, ... +${value.length - 3}]`;
+    }
+    if (typeof value === "object") {
+        return `{${Object.keys(value).length} keys}`;
+    }
+    return String(value);
+}

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

@@ -0,0 +1,124 @@
+/**
+ * Node List Formatter
+ *
+ * Formats TouchDesigner node lists with token-optimized output.
+ * Used by GET_TD_NODES tool.
+ */
+import { DEFAULT_PRESENTER_FORMAT, presentStructuredData, } from "./presenter.js";
+import { finalizeFormattedText, formatOmissionHint, limitArray, mergeFormatterOptions, } from "./responseFormatter.js";
+/**
+ * Format node list based on detail level
+ */
+export function formatNodeList(data, options) {
+    const opts = mergeFormatterOptions(options);
+    if (!data?.nodes || data.nodes.length === 0) {
+        return "No nodes found.";
+    }
+    const nodes = data.nodes;
+    const totalCount = nodes.length;
+    const parentPath = data.parentPath ?? "project";
+    // Apply limit
+    const { items: limitedNodes, truncated } = limitArray(nodes, opts.limit);
+    if (opts.detailLevel === "detailed") {
+        return formatDetailed(nodes, data, opts.responseFormat, parentPath);
+    }
+    let result;
+    if (opts.detailLevel === "minimal") {
+        result = formatMinimal(limitedNodes, parentPath, totalCount, truncated);
+    }
+    else {
+        result = formatSummary(limitedNodes, parentPath, totalCount, truncated);
+    }
+    const hintEnabled = truncated && opts.includeHints;
+    let output = result.text;
+    if (hintEnabled) {
+        output += formatOmissionHint(totalCount, limitedNodes.length, "node");
+    }
+    const context = result.context;
+    context.truncated = hintEnabled;
+    if (!hintEnabled) {
+        context.omittedCount = 0;
+    }
+    return finalizeFormattedText(output, opts, {
+        template: "nodeListSummary",
+        context,
+        structured: context,
+    });
+}
+/**
+ * Minimal mode: Only node paths
+ */
+function formatMinimal(nodes, parentPath, totalCount, truncated) {
+    const paths = nodes.map((n) => n.path || n.name);
+    const text = `Found ${nodes.length} nodes in ${parentPath}:
+${paths.join("\n")}`;
+    return {
+        text,
+        context: buildNodeListContext(nodes, parentPath, totalCount, truncated),
+    };
+}
+/**
+ * Summary mode: Essential info with types
+ */
+function formatSummary(nodes, parentPath, totalCount, truncated) {
+    const header = `Found ${totalCount} nodes in ${parentPath}:
+
+`;
+    const groups = buildGroups(nodes);
+    const sections = groups.map((group) => {
+        const nodeLines = group.nodes.map((n) => `  • ${n.name} [${n.path}]`);
+        return `${group.type}:
+${nodeLines.join("\n")}`;
+    });
+    return {
+        text: header + sections.join("\n\n"),
+        context: {
+            parentPath,
+            totalCount,
+            groups,
+            truncated,
+            omittedCount: Math.max(totalCount - nodes.length, 0),
+        },
+    };
+}
+/**
+ * Detailed mode: Full information (original behavior)
+ */
+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,
+        },
+        template: "detailedPayload",
+    }, payloadFormat);
+}
+function buildNodeListContext(nodes, parentPath, totalCount, truncated) {
+    return {
+        parentPath,
+        totalCount,
+        groups: buildGroups(nodes),
+        truncated,
+        omittedCount: Math.max(totalCount - nodes.length, 0),
+    };
+}
+function buildGroups(nodes) {
+    const byType = new Map();
+    for (const node of nodes) {
+        const type = node.opType || "unknown";
+        if (!byType.has(type)) {
+            byType.set(type, []);
+        }
+        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 })),
+    }));
+}

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

@@ -0,0 +1,117 @@
+import { finalizeFormattedText, mergeFormatterOptions, } from "./responseFormatter.js";
+export function formatTdInfo(data, options) {
+    const opts = mergeFormatterOptions(options);
+    if (!data) {
+        return finalizeFormattedText("TouchDesigner info not available.", opts, {
+            context: { title: "TouchDesigner Info" },
+        });
+    }
+    const summary = `Server: ${data.server}\nVersion: ${data.version}`;
+    const osLine = data.osName
+        ? `\nOS: ${data.osName} ${data.osVersion ?? ""}`
+        : "";
+    const text = opts.detailLevel === "minimal"
+        ? `Server: ${data.server}, v${data.version}`
+        : `${summary}${osLine}`;
+    return finalizeFormattedText(text.trim(), opts, {
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
+        context: { title: "TouchDesigner Info", ...data },
+        structured: data,
+    });
+}
+export function formatCreateNodeResult(data, options) {
+    const opts = mergeFormatterOptions(options);
+    const node = data?.result;
+    if (!node) {
+        return finalizeFormattedText("Node created but no metadata returned.", opts, {
+            context: { title: "Create Node" },
+            structured: data,
+        });
+    }
+    const name = node.name ?? "(unknown)";
+    const path = node.path ?? "(path unknown)";
+    const opType = node.opType ?? "unknown";
+    const base = `✓ Created node '${name}' (${opType}) at ${path}`;
+    const propCount = Object.keys(node.properties ?? {}).length;
+    const text = opts.detailLevel === "minimal"
+        ? base
+        : `${base}\nProperties detected: ${propCount}`;
+    return finalizeFormattedText(text, opts, {
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
+        context: { title: "Create Node", path, opType },
+        structured: data,
+    });
+}
+export function formatUpdateNodeResult(data, options) {
+    const opts = mergeFormatterOptions(options);
+    const updatedCount = data?.updated?.length ?? 0;
+    const failedCount = data?.failed?.length ?? 0;
+    const base = `✓ Updated ${updatedCount} parameter(s)`;
+    const text = opts.detailLevel === "minimal"
+        ? base
+        : `${base}${failedCount ? `, ${failedCount} failed` : ""}`;
+    const context = {
+        title: "Update Node",
+        updated: data?.updated,
+        failed: data?.failed,
+        message: data?.message,
+    };
+    return finalizeFormattedText(text, opts, {
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
+        context,
+        structured: data,
+    });
+}
+export function formatDeleteNodeResult(data, options) {
+    const opts = mergeFormatterOptions(options);
+    const deleted = data?.deleted ?? false;
+    const name = data?.node?.name ?? "node";
+    const path = data?.node?.path ?? "(path unknown)";
+    const text = deleted
+        ? `🗑️ Deleted '${name}' at ${path}`
+        : `Deletion status unknown for '${name}' at ${path}`;
+    return finalizeFormattedText(text, opts, {
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
+        context: { title: "Delete Node", path, deleted },
+        structured: data,
+    });
+}
+export function formatExecNodeMethodResult(data, context, options) {
+    const opts = mergeFormatterOptions(options);
+    const callSignature = buildCallSignature(context);
+    const resultPreview = summarizeValue(data?.result);
+    const text = `${callSignature}\nResult: ${resultPreview}`;
+    return finalizeFormattedText(text, opts, {
+        template: opts.detailLevel === "detailed" ? "detailedPayload" : "default",
+        context: { title: "Execute Node Method", callSignature },
+        structured: { ...context, result: data?.result },
+    });
+}
+function buildCallSignature(params) {
+    const argPart = params.args ?? [];
+    const kwPart = params.kwargs
+        ? Object.entries(params.kwargs).map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+        : [];
+    const joinedArgs = [...argPart.map(stringifyValue), ...kwPart].join(", ");
+    return `op('${params.nodePath}').${params.method}(${joinedArgs})`;
+}
+function summarizeValue(value) {
+    if (value === undefined)
+        return "(no result)";
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return value.length > 120 ? `${value.slice(0, 117)}...` : value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value))
+        return `Array[${value.length}]`;
+    if (typeof value === "object")
+        return `Object{${Object.keys(value).length} keys}`;
+    return String(value);
+}
+function stringifyValue(value) {
+    if (typeof value === "string")
+        return `'${value}'`;
+    return JSON.stringify(value);
+}

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

@@ -0,0 +1,62 @@
+import { stringify as toYaml } from "yaml";
+import { renderMarkdownTemplate } from "./markdownRenderer.js";
+export const DEFAULT_PRESENTER_FORMAT = "yaml";
+export function presentStructuredData(payload, format = DEFAULT_PRESENTER_FORMAT) {
+    switch (format) {
+        case "json":
+            return JSON.stringify(resolveStructured(payload), null, 2);
+        case "yaml":
+            return toYaml(resolveStructured(payload));
+        case "markdown":
+            return formatMarkdown(payload, format);
+        default:
+            return toYaml(resolveStructured(payload));
+    }
+}
+function resolveStructured(payload) {
+    if (payload.structured !== undefined) {
+        return payload.structured;
+    }
+    return {
+        mode: payload.detailLevel,
+        text: payload.text,
+        ...(payload.context ?? {}),
+    };
+}
+function formatMarkdown(payload, requestedFormat) {
+    const context = { ...(payload.context ?? {}) };
+    const inferredTitle = payload.detailLevel
+        ? `${payload.detailLevel.charAt(0).toUpperCase()}${payload.detailLevel.slice(1)}`
+        : "Response";
+    const effectiveTemplate = payload.template ??
+        (payload.detailLevel === "detailed" ? "detailedPayload" : "default");
+    const payloadFormat = context.payloadFormat ??
+        (requestedFormat === "markdown"
+            ? DEFAULT_PRESENTER_FORMAT
+            : requestedFormat);
+    const resolveStructuredText = () => {
+        if (typeof payload.structured === "string")
+            return payload.structured;
+        if (payload.structured === undefined)
+            return payload.text ?? "";
+        return payloadFormat === "json"
+            ? JSON.stringify(payload.structured, null, 2)
+            : toYaml(payload.structured);
+    };
+    let bodyText = payload.text?.trim() ?? "";
+    if (!bodyText) {
+        bodyText = resolveStructuredText();
+    }
+    if (effectiveTemplate === "detailedPayload") {
+        context.title ??= inferredTitle;
+        context.payload ??= resolveStructuredText();
+        context.payloadFormat ??= payloadFormat;
+    }
+    if (effectiveTemplate === "default" && !("title" in context)) {
+        context.title = inferredTitle;
+    }
+    return renderMarkdownTemplate(effectiveTemplate, {
+        ...context,
+        text: bodyText,
+    });
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Response Formatter Utilities
+ *
+ * Provides token-optimized formatting for MCP tool responses.
+ * Based on the design document: docs/context-optimization-design.md
+ */
+/**
+ * Common formatting options
+ */
+import { presentStructuredData } from "./presenter.js";
+/**
+ * Default formatter options
+ */
+export const DEFAULT_FORMATTER_OPTIONS = {
+    detailLevel: "summary",
+    limit: undefined,
+    includeHints: true,
+    responseFormat: undefined,
+};
+/**
+ * Merge user options with defaults
+ */
+export function mergeFormatterOptions(options) {
+    const merged = { ...DEFAULT_FORMATTER_OPTIONS, ...options };
+    const detailLevel = options?.detailLevel ??
+        options?.mode ??
+        DEFAULT_FORMATTER_OPTIONS.detailLevel;
+    return {
+        detailLevel,
+        limit: merged.limit,
+        includeHints: merged.includeHints ?? true,
+        responseFormat: merged.responseFormat,
+    };
+}
+export function finalizeFormattedText(text, opts, metadata) {
+    const chosenFormat = opts.responseFormat ??
+        (opts.detailLevel === "detailed" ? "yaml" : "markdown");
+    return presentStructuredData({
+        text,
+        detailLevel: opts.detailLevel,
+        structured: metadata?.structured,
+        context: metadata?.context,
+        template: metadata?.template,
+    }, chosenFormat);
+}
+/**
+ * Format a hint message for omitted content
+ */
+export function formatOmissionHint(totalCount, shownCount, itemType) {
+    const omitted = totalCount - shownCount;
+    if (omitted <= 0)
+        return "";
+    return `\n💡 ${omitted} more ${itemType}(s) omitted. Use detailLevel='detailed' or increase limit to see all.`;
+}
+/**
+ * Truncate array based on limit option
+ */
+export function limitArray(items, limit) {
+    if (limit === undefined || limit >= items.length) {
+        return { items, truncated: false };
+    }
+    return {
+        items: items.slice(0, limit),
+        truncated: true,
+    };
+}

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

@@ -0,0 +1,171 @@
+/**
+ * Script Result Formatter
+ *
+ * Formats Python script execution results with token optimization.
+ * Used by EXECUTE_PYTHON_SCRIPT tool.
+ */
+import { DEFAULT_PRESENTER_FORMAT, presentStructuredData, } from "./presenter.js";
+import { finalizeFormattedText, mergeFormatterOptions, } from "./responseFormatter.js";
+/**
+ * Format script execution result
+ */
+export function formatScriptResult(data, scriptSnippet, options) {
+    const opts = mergeFormatterOptions(options);
+    if (!data) {
+        return "No result returned.";
+    }
+    const success = data.success ?? true;
+    const result = data.data?.result;
+    const output = data.data?.output;
+    const error = data.data?.error;
+    // Error case - always show full details
+    if (!success || error) {
+        return formatError(error, scriptSnippet);
+    }
+    if (opts.detailLevel === "detailed") {
+        return formatDetailed(data, opts.responseFormat);
+    }
+    let formattedText = "";
+    let context;
+    switch (opts.detailLevel) {
+        case "minimal":
+            formattedText = formatMinimal(result);
+            context = buildScriptContext(scriptSnippet, result, output);
+            break;
+        case "summary": {
+            const summary = formatSummary(result, output, scriptSnippet);
+            formattedText = summary.text;
+            context = summary.context;
+            break;
+        }
+    }
+    const ctx = context;
+    return finalizeFormattedText(formattedText, opts, {
+        template: "scriptSummary",
+        context: ctx,
+        structured: ctx,
+    });
+}
+/**
+ * Format error result
+ */
+function formatError(error, scriptSnippet) {
+    const errorMsg = typeof error === "string" ? error : JSON.stringify(error);
+    const snippet = scriptSnippet
+        ? `\nScript: ${truncateScript(scriptSnippet)}`
+        : "";
+    return `❌ Script execution failed:${snippet}\n\nError: ${errorMsg}`;
+}
+/**
+ * Minimal mode: Just the result value
+ */
+function formatMinimal(result) {
+    if (result === undefined || result === null) {
+        return "✓ Script executed successfully (no return value)";
+    }
+    if (typeof result === "string" ||
+        typeof result === "number" ||
+        typeof result === "boolean") {
+        return `✓ Result: ${result}`;
+    }
+    if (Array.isArray(result)) {
+        return `✓ Result: Array[${result.length}]`;
+    }
+    if (typeof result === "object") {
+        const keys = Object.keys(result);
+        return `✓ Result: Object{${keys.length} keys}`;
+    }
+    return `✓ Result: ${String(result)}`;
+}
+/**
+ * Summary mode: Result with context
+ */
+function formatSummary(result, output, scriptSnippet) {
+    let formatted = "✓ Script executed successfully\n\n";
+    const snippet = scriptSnippet ? truncateScript(scriptSnippet) : "";
+    if (snippet) {
+        formatted += `Script: ${snippet}\n\n`;
+    }
+    let resultPreview = "(none)";
+    if (result !== undefined && result !== null) {
+        resultPreview = formatResultValue(result, 500);
+        formatted += `Result: ${resultPreview}\n`;
+    }
+    let outputPreview;
+    if (output?.trim()) {
+        outputPreview =
+            output.length > 200 ? `${output.substring(0, 200)}...` : output;
+        formatted += `\nOutput:\n${outputPreview}`;
+    }
+    return {
+        text: formatted,
+        context: {
+            snippet,
+            resultType: getValueType(result),
+            resultPreview,
+            hasOutput: Boolean(outputPreview),
+            outputType: getValueType(output),
+            outputPreview,
+        },
+    };
+}
+function buildScriptContext(scriptSnippet, result, output) {
+    return {
+        snippet: scriptSnippet ? truncateScript(scriptSnippet) : "",
+        resultType: getValueType(result),
+        resultPreview: formatResultValue(result ?? "", 200),
+        hasOutput: Boolean(output?.trim()),
+        outputType: getValueType(output),
+        outputPreview: output,
+    };
+}
+/**
+ * Detailed mode: Full JSON
+ */
+function formatDetailed(data, format) {
+    const title = "Script Result";
+    const payloadFormat = format ?? DEFAULT_PRESENTER_FORMAT;
+    return presentStructuredData({
+        text: title,
+        detailLevel: "detailed",
+        structured: data,
+        context: {
+            title,
+            payloadFormat,
+        },
+        template: "detailedPayload",
+    }, payloadFormat);
+}
+function getValueType(value) {
+    if (value === undefined || value === null) {
+        return "none";
+    }
+    if (Array.isArray(value)) {
+        return `array(${value.length})`;
+    }
+    return typeof value;
+}
+/**
+ * Format result value with size limit
+ */
+function formatResultValue(value, maxChars) {
+    const str = typeof value === "object" ? JSON.stringify(value, null, 2) : String(value);
+    if (str.length <= maxChars) {
+        return str;
+    }
+    return `${str.substring(0, maxChars)}...\n💡 Result truncated. Use detailLevel='detailed' for full output.`;
+}
+/**
+ * Truncate script for display
+ */
+function truncateScript(script, maxLength = 100) {
+    const trimmed = script.trim();
+    if (trimmed.length <= maxLength) {
+        return trimmed;
+    }
+    const firstLine = trimmed.split("\n")[0];
+    if (firstLine.length <= maxLength) {
+        return `${firstLine}...`;
+    }
+    return `${trimmed.substring(0, maxLength)}...`;
+}

package/dist/features/tools/presenter/templates/markdown/classDetailsSummary.md

@@ -0,0 +1,13 @@
+## Class `{{name}}`
+- Type: {{type}}
+- Description: {{{description}}}
+
+### Methods ({{methodsShown}} / {{methodsTotal}})
+{{#methods}}1. `{{signature}}` — {{summary}}
+{{/methods}}
+
+### Properties ({{propertiesShown}} / {{propertiesTotal}})
+{{#properties}}- `{{name}}`: {{type}}
+{{/properties}}
+
+{{#truncated}}_💡 Additional members omitted._{{/truncated}}