touchdesigner-mcp-server 1.4.8 → 1.4.10

package/dist/features/tools/presenter/nodeListFormatter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Node List Formatter
+ *
+ * Formats TouchDesigner node lists with token-optimized output.
+ * Used by GET_TD_NODES tool.
+ */
+import type { TdNode } from "../../../gen/endpoints/TouchDesignerAPI.js";
+import type { FormatterOptions } from "./responseFormatter.js";
+/**
+ * Node list data structure (matches API response)
+ */
+export interface NodeListData {
+    nodes?: TdNode[];
+    parentPath?: string;
+    pattern?: string;
+    includeProperties?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Format node list based on detail level
+ */
+export declare function formatNodeList(data: NodeListData | undefined, options?: FormatterOptions): string;

package/dist/features/tools/presenter/operationFormatter.d.ts

@@ -0,0 +1,16 @@
+import type { CreateNode200Data, DeleteNode200Data, ExecNodeMethod200Data, GetTdInfo200Data, UpdateNode200Data } from "../../../gen/endpoints/TouchDesignerAPI.js";
+import type { FormatterOptions } from "./responseFormatter.js";
+type FormatterOpts = Pick<FormatterOptions, "detailLevel" | "responseFormat">;
+export declare function formatTdInfo(data: GetTdInfo200Data, options?: FormatterOpts): string;
+export declare function formatCreateNodeResult(data: CreateNode200Data, options?: FormatterOpts): string;
+export declare function formatUpdateNodeResult(data: UpdateNode200Data, options?: FormatterOpts): string;
+export declare function formatDeleteNodeResult(data: DeleteNode200Data, options?: FormatterOpts): string;
+export declare function formatExecNodeMethodResult(data: ExecNodeMethod200Data | {
+    result?: unknown;
+} | null | undefined, context: {
+    nodePath: string;
+    method: string;
+    args?: unknown[];
+    kwargs?: Record<string, unknown>;
+}, options?: FormatterOpts): string;
+export {};

package/dist/features/tools/presenter/presenter.d.ts

@@ -0,0 +1,10 @@
+export type PresenterFormat = "json" | "yaml" | "markdown";
+export declare const DEFAULT_PRESENTER_FORMAT: PresenterFormat;
+export interface PresenterPayload {
+    text: string;
+    detailLevel?: string;
+    structured?: unknown;
+    context?: Record<string, unknown>;
+    template?: string;
+}
+export declare function presentStructuredData(payload: PresenterPayload, format?: PresenterFormat): string;

package/dist/features/tools/presenter/responseFormatter.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Response Formatter Utilities
+ *
+ * Provides token-optimized formatting for MCP tool responses.
+ * Based on the design document: docs/context-optimization-design.md
+ */
+/**
+ * Detail level for response formatting
+ * - minimal: Only essential information (lowest tokens)
+ * - summary: Key information with counts and hints (balanced)
+ * - detailed: Full information (original behavior)
+ */
+export type DetailLevel = "minimal" | "summary" | "detailed";
+/**
+ * Common formatting options
+ */
+import { type PresenterFormat } from "./presenter.js";
+export interface FormatterOptions {
+    /**
+     * Backwards-compatible alias for detailLevel
+     * @deprecated Use detailLevel instead
+     */
+    mode?: DetailLevel;
+    /**
+     * Level of detail in the response
+     * @default "summary"
+     */
+    detailLevel?: DetailLevel;
+    /**
+     * Maximum number of items to include in lists
+     * @default undefined (no limit)
+     */
+    limit?: number;
+    /**
+     * Include hints about omitted content
+     * @default true
+     */
+    includeHints?: boolean;
+    /**
+     * Structured output format for detailed mode
+     * @default "yaml"
+     */
+    responseFormat?: PresenterFormat;
+}
+/**
+ * Default formatter options
+ */
+export declare const DEFAULT_FORMATTER_OPTIONS: {
+    detailLevel: "summary";
+    includeHints: true;
+    limit: number | undefined;
+    responseFormat: PresenterFormat | undefined;
+};
+/**
+ * Merge user options with defaults
+ */
+export declare function mergeFormatterOptions(options?: FormatterOptions): {
+    detailLevel: DetailLevel;
+    limit: number | undefined;
+    includeHints: boolean;
+    responseFormat?: PresenterFormat;
+};
+interface FormatterMetadata {
+    template?: string;
+    context?: Record<string, unknown>;
+    structured?: unknown;
+}
+export declare function finalizeFormattedText(text: string, opts: {
+    responseFormat?: PresenterFormat;
+    detailLevel: DetailLevel;
+}, metadata?: FormatterMetadata): string;
+/**
+ * Format a hint message for omitted content
+ */
+export declare function formatOmissionHint(totalCount: number, shownCount: number, itemType: string): string;
+/**
+ * Truncate array based on limit option
+ */
+export declare function limitArray<T>(items: T[], limit: number | undefined): {
+    items: T[];
+    truncated: boolean;
+};
+export {};

package/dist/features/tools/presenter/scriptResultFormatter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Script Result Formatter
+ *
+ * Formats Python script execution results with token optimization.
+ * Used by EXECUTE_PYTHON_SCRIPT tool.
+ */
+import type { FormatterOptions } from "./responseFormatter.js";
+/**
+ * Script execution result structure
+ */
+export interface ScriptResultData {
+    success?: boolean;
+    data?: {
+        result?: unknown;
+        output?: string;
+        error?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Format script execution result
+ */
+export declare function formatScriptResult(data: ScriptResultData | undefined, scriptSnippet?: string, options?: FormatterOptions): string;

package/dist/features/tools/presenter/toolMetadataFormatter.d.ts

@@ -0,0 +1,7 @@
+import type { ToolMetadata } from "../metadata/touchDesignerToolMetadata.js";
+import { type FormatterOptions } from "./responseFormatter.js";
+interface ToolMetadataFormatterOptions extends Partial<FormatterOptions> {
+    filter?: string;
+}
+export declare function formatToolMetadata(entries: ToolMetadata[], options?: ToolMetadataFormatterOptions): string;
+export {};

package/dist/features/tools/register.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ILogger } from "../../core/logger.js";
+import type { TouchDesignerClient } from "../../tdClient/index.js";
+/**
+ * Register resource handlers with MCP server
+ */
+export declare function registerTools(server: McpServer, logger: ILogger, tdClient: TouchDesignerClient): void;

package/dist/features/tools/toolDefinitions.d.ts

@@ -0,0 +1,38 @@
+import type { z } from "zod";
+import type { ILogger } from "../../core/logger.js";
+import type { TouchDesignerClient } from "../../tdClient/touchDesignerClient.js";
+import type { ToolNames } from "./index.js";
+export type ToolCategory = "system" | "python" | "nodes" | "classes" | "state";
+/**
+ * Single source of truth for a TouchDesigner MCP tool.
+ *
+ * Both the MCP registration loop (`registerTdTools`) and the
+ * `describe_td_tools` manifest (`buildToolMetadata`) are derived from this
+ * table, so a tool's description and input parameters can never drift between
+ * what is registered and what is documented. Parameter metadata is introspected
+ * directly from `schema`, which itself originates from the OpenAPI spec.
+ */
+export interface ToolDefinition {
+    /** Registered MCP tool name (also the source for functionName/modulePath). */
+    name: ToolNames;
+    /** Agent-facing description, used for both registration and the manifest. */
+    description: string;
+    category: ToolCategory;
+    /** Composed Zod schema: OpenAPI-derived params extended with formatting flags. */
+    schema: z.ZodObject<z.ZodRawShape>;
+    /** Human summary of the return payload (manifest only). */
+    returns: string;
+    /** Usage example shown in the detailed manifest view (manifest only). */
+    example: string;
+    notes?: string;
+    /** Optional reference comment appended to error output. */
+    errorComment?: string;
+    /** Executes the tool and returns formatter-ready text. */
+    run: (ctx: ToolRunContext) => Promise<string>;
+}
+export interface ToolRunContext {
+    params: Record<string, unknown>;
+    tdClient: TouchDesignerClient;
+    logger: ILogger;
+}
+export declare const TOOL_DEFINITIONS: ToolDefinition[];

package/dist/features/tools/toolDefinitions.js

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

package/dist/features/tools/types.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+/**
+ * Shared Zod schemas for MCP tool formatting parameters.
+ * These stay on the TypeScript side only and are not sent to TouchDesigner.
+ */
+export declare const detailLevelSchema: z.ZodEnum<{
+    detailed: "detailed";
+    minimal: "minimal";
+    summary: "summary";
+}>;
+export declare const limitSchema: z.ZodNumber;
+export declare const presenterFormatSchema: z.ZodEnum<{
+    json: "json";
+    yaml: "yaml";
+    markdown: "markdown";
+}>;
+export declare const detailOnlyFormattingSchema: z.ZodObject<{
+    detailLevel: z.ZodOptional<z.ZodEnum<{
+        detailed: "detailed";
+        minimal: "minimal";
+        summary: "summary";
+    }>>;
+    responseFormat: z.ZodOptional<z.ZodEnum<{
+        json: "json";
+        yaml: "yaml";
+        markdown: "markdown";
+    }>>;
+}, z.core.$strip>;
+export declare const formattingOptionsSchema: z.ZodObject<{
+    detailLevel: z.ZodOptional<z.ZodEnum<{
+        detailed: "detailed";
+        minimal: "minimal";
+        summary: "summary";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    responseFormat: z.ZodOptional<z.ZodEnum<{
+        json: "json";
+        yaml: "yaml";
+        markdown: "markdown";
+    }>>;
+}, z.core.$strip>;
+export type DetailOnlyFormattingParams = z.input<typeof detailOnlyFormattingSchema>;
+export type FormattingOptionsParams = z.input<typeof formattingOptionsSchema>;