touchdesigner-mcp-server 1.4.12 → 1.5.0

package/dist/core/constants.d.ts

@@ -19,6 +19,7 @@ export declare const TOOL_NAMES: {
     readonly GET_TD_NODE_ERRORS: "get_td_node_errors";
     readonly GET_TD_NODE_PARAMETERS: "get_td_node_parameters";
     readonly GET_TD_NODES: "get_td_nodes";
+    readonly GET_TOP_IMAGE: "get_top_image";
     readonly UPDATE_TD_NODE_PARAMETERS: "update_td_node_parameters";
 };
 export declare const REFERENCE_COMMENT = "Check reference resources: https://docs.derivative.ca/Python_Classes_and_Modules";

package/dist/core/constants.js

@@ -19,6 +19,7 @@ export const TOOL_NAMES = {
     GET_TD_NODE_ERRORS: "get_td_node_errors",
     GET_TD_NODE_PARAMETERS: "get_td_node_parameters",
     GET_TD_NODES: "get_td_nodes",
+    GET_TOP_IMAGE: "get_top_image",
     UPDATE_TD_NODE_PARAMETERS: "update_td_node_parameters",
 };
 export const REFERENCE_COMMENT = `Check reference resources: ${TD_PYTHON_CLASS_REFERENCE_INDEX_URL}`;

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

@@ -17,8 +17,8 @@ export function registerTdTools(server, logger, tdClient) {
     for (const definition of TOOL_DEFINITIONS) {
         server.tool(definition.name, definition.description, definition.schema.strict().shape, async (params = {}) => {
             try {
-                const text = await definition.run({ logger, params, tdClient });
-                return createToolResult(tdClient, text);
+                const output = await definition.run({ logger, params, tdClient });
+                return createToolResult(tdClient, output);
             }
             catch (error) {
                 return handleToolError(error, logger, definition.name, definition.errorComment);
@@ -57,10 +57,16 @@ export function registerTdTools(server, logger, tdClient) {
         }
     });
 }
-const createToolResult = (tdClient, text) => {
-    const content = [
-        { text, type: "text" },
-    ];
+const createToolResult = (tdClient, output) => {
+    const content = typeof output === "string"
+        ? [{ text: output, type: "text" }]
+        : output.content.map((block) => block.type === "image"
+            ? {
+                data: block.data,
+                mimeType: block.mimeType,
+                type: "image",
+            }
+            : { text: block.text, type: "text" });
     const additionalContents = tdClient.getAdditionalToolResultContents();
     if (additionalContents) {
         content.push(...additionalContents);

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

@@ -12,7 +12,8 @@ export interface ScriptResultData {
     success?: boolean;
     data?: {
         result?: unknown;
-        output?: string;
+        stdout?: string;
+        stderr?: string;
         error?: string;
     };
     [key: string]: unknown;

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

@@ -16,7 +16,8 @@ export function formatScriptResult(data, scriptSnippet, options) {
     }
     const success = data.success ?? true;
     const result = data.data?.result;
-    const output = data.data?.output;
+    const stdout = data.data?.stdout;
+    const stderr = data.data?.stderr;
     const error = data.data?.error;
     // Error case - always show full details
     if (!success || error) {
@@ -30,10 +31,10 @@ export function formatScriptResult(data, scriptSnippet, options) {
     switch (opts.detailLevel) {
         case "minimal":
             formattedText = formatMinimal(result);
-            context = buildScriptContext(scriptSnippet, result, output);
+            context = buildScriptContext(scriptSnippet, result, stdout, stderr);
             break;
         case "summary": {
-            const summary = formatSummary(result, output, scriptSnippet);
+            const summary = formatSummary(result, stdout, stderr, scriptSnippet);
             formattedText = summary.text;
             context = summary.context;
             break;
@@ -80,7 +81,7 @@ function formatMinimal(result) {
 /**
  * Summary mode: Result with context
  */
-function formatSummary(result, output, scriptSnippet) {
+function formatSummary(result, stdout, stderr, scriptSnippet) {
     let formatted = "✓ Script executed successfully\n\n";
     const snippet = scriptSnippet ? truncateScript(scriptSnippet) : "";
     if (snippet) {
@@ -91,34 +92,49 @@ function formatSummary(result, output, scriptSnippet) {
         resultPreview = formatResultValue(result, 500);
         formatted += `Result: ${resultPreview}\n`;
     }
-    let outputPreview;
-    if (output?.trim()) {
-        outputPreview =
-            output.length > 200 ? `${output.substring(0, 200)}...` : output;
+    const outputPreview = truncateOutput(stdout);
+    if (outputPreview) {
         formatted += `\nOutput:\n${outputPreview}`;
     }
+    const stderrPreview = truncateOutput(stderr);
+    if (stderrPreview) {
+        formatted += `\nStderr:\n${stderrPreview}`;
+    }
     return {
         context: {
             hasOutput: Boolean(outputPreview),
+            hasStderr: Boolean(stderrPreview),
             outputPreview,
-            outputType: getValueType(output),
+            outputType: getValueType(stdout),
             resultPreview,
             resultType: getValueType(result),
             snippet,
+            stderrPreview,
         },
         text: formatted,
     };
 }
-function buildScriptContext(scriptSnippet, result, output) {
+function buildScriptContext(scriptSnippet, result, stdout, stderr) {
     return {
-        hasOutput: Boolean(output?.trim()),
-        outputPreview: output,
-        outputType: getValueType(output),
+        hasOutput: Boolean(stdout?.trim()),
+        hasStderr: Boolean(stderr?.trim()),
+        outputPreview: stdout,
+        outputType: getValueType(stdout),
         resultPreview: formatResultValue(result ?? "", 200),
         resultType: getValueType(result),
         snippet: scriptSnippet ? truncateScript(scriptSnippet) : "",
+        stderrPreview: stderr,
     };
 }
+/**
+ * Truncate captured stdout/stderr for display
+ */
+function truncateOutput(output) {
+    if (!output?.trim()) {
+        return undefined;
+    }
+    return output.length > 200 ? `${output.substring(0, 200)}...` : output;
+}
 /**
  * Detailed mode: Full JSON
  */

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

@@ -9,7 +9,16 @@
 ```
 
 {{#outputPreview}}
+Output:
+
 ```text
 {{{outputPreview}}}
 ```
 {{/outputPreview}}
+{{#stderrPreview}}
+Stderr:
+
+```text
+{{{stderrPreview}}}
+```
+{{/stderrPreview}}

package/dist/features/tools/pythonScripts/getTopImageScript.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Python script builder for GET_TOP_IMAGE.
+ *
+ * `get_top_image` has no dedicated API endpoint: it reuses the same
+ * `execute_python_script` channel as EXECUTE_PYTHON_SCRIPT. This module only
+ * builds the script text that gets sent over that channel.
+ */
+export interface GetTopImageScriptParams {
+    nodePath: string;
+    maxSize?: number;
+}
+/**
+ * Builds a Python script that captures the current output of a TOP node as a
+ * base64-encoded JPEG and assigns it to `result` (the variable the TD-side
+ * script executor extracts as the return value).
+ *
+ * When `maxSize` is set and the TOP's longer dimension exceeds it, a
+ * temporary `td.resolutionTOP` is chained onto the node to downscale (aspect
+ * preserved) before capture, then destroyed in a `finally` block so the
+ * project is left unmodified.
+ *
+ * OP type constants are referenced via `td.resolutionTOP` (not the bare
+ * `resolutionTOP` global) because the bare global is only injected into the
+ * exec namespace by TD-side packages that include #185's global injection
+ * fix; `import td` + `td.resolutionTOP` works against both older and newer
+ * deployed `mcp_webserver_base.tox` packages.
+ */
+export declare function buildGetTopImageScript({ nodePath, maxSize, }: GetTopImageScriptParams): string;

package/dist/features/tools/pythonScripts/getTopImageScript.js

@@ -0,0 +1,77 @@
+/**
+ * Python script builder for GET_TOP_IMAGE.
+ *
+ * `get_top_image` has no dedicated API endpoint: it reuses the same
+ * `execute_python_script` channel as EXECUTE_PYTHON_SCRIPT. This module only
+ * builds the script text that gets sent over that channel.
+ */
+/**
+ * Builds a Python script that captures the current output of a TOP node as a
+ * base64-encoded JPEG and assigns it to `result` (the variable the TD-side
+ * script executor extracts as the return value).
+ *
+ * When `maxSize` is set and the TOP's longer dimension exceeds it, a
+ * temporary `td.resolutionTOP` is chained onto the node to downscale (aspect
+ * preserved) before capture, then destroyed in a `finally` block so the
+ * project is left unmodified.
+ *
+ * OP type constants are referenced via `td.resolutionTOP` (not the bare
+ * `resolutionTOP` global) because the bare global is only injected into the
+ * exec namespace by TD-side packages that include #185's global injection
+ * fix; `import td` + `td.resolutionTOP` works against both older and newer
+ * deployed `mcp_webserver_base.tox` packages.
+ */
+export function buildGetTopImageScript({ nodePath, maxSize, }) {
+    // JSON string literals are valid Python string literals for the characters
+    // that can appear in a node path, so this is a safe way to embed user input.
+    const nodePathLiteral = JSON.stringify(nodePath);
+    const maxSizeLiteral = maxSize === undefined ? "None" : JSON.stringify(maxSize);
+    return `import base64
+import td
+
+node_path = ${nodePathLiteral}
+max_size = ${maxSizeLiteral}
+
+node = op(node_path)
+if node is None:
+    raise Exception(f"Node not found at path: {node_path}")
+if node.family != 'TOP':
+    raise Exception(f"Node at {node_path} is not a TOP (family={node.family})")
+
+tmp_top = None
+source_top = node
+try:
+    if max_size is not None:
+        width = node.width
+        height = node.height
+        longest = max(width, height)
+        if longest > max_size:
+            if width >= height:
+                new_w = max_size
+                new_h = max(1, round(height * max_size / width))
+            else:
+                new_h = max_size
+                new_w = max(1, round(width * max_size / height))
+
+            parent = node.parent()
+            tmp_name = '__mcp_tmp_res__' + node.name
+            existing = parent.op(tmp_name)
+            if existing is not None:
+                existing.destroy()
+            tmp_top = parent.create(td.resolutionTOP, tmp_name)
+            tmp_top.inputConnectors[0].connect(node)
+            tmp_top.par.outputresolution = 'custom'
+            tmp_top.par.resolutionw = new_w
+            tmp_top.par.resolutionh = new_h
+            source_top = tmp_top
+
+    byte_array = source_top.saveByteArray('.jpg')
+    if not byte_array:
+        raise Exception(f"Failed to capture image from {node_path}: saveByteArray returned no data")
+
+    result = base64.b64encode(bytes(byte_array)).decode('ascii')
+finally:
+    if tmp_top is not None:
+        tmp_top.destroy()
+`;
+}

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

@@ -1,8 +1,29 @@
-import type { z } from "zod";
+import { 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";
+/** MCP text content block. */
+export interface ToolTextContent {
+    type: "text";
+    text: string;
+}
+/** MCP image content block (base64-encoded). */
+export interface ToolImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export type ToolContent = ToolTextContent | ToolImageContent;
+/**
+ * A tool's `run` normally returns formatter-ready text, which is wrapped in a
+ * single text content block. Tools that need to return non-text content
+ * (e.g. an image) return `{ content }` with the full content block list
+ * instead.
+ */
+export type ToolRunResult = string | {
+    content: ToolContent[];
+};
 /**
  * Single source of truth for a TouchDesigner MCP tool.
  *
@@ -27,8 +48,8 @@ export interface ToolDefinition {
     notes?: string;
     /** Optional reference comment appended to error output. */
     errorComment?: string;
-    /** Executes the tool and returns formatter-ready text. */
-    run: (ctx: ToolRunContext) => Promise<string>;
+    /** Executes the tool and returns formatter-ready text (or explicit content blocks). */
+    run: (ctx: ToolRunContext) => Promise<ToolRunResult>;
 }
 export interface ToolRunContext {
     params: Record<string, unknown>;

package/dist/features/tools/toolDefinitions.js

@@ -1,6 +1,8 @@
+import { z } from "zod";
 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 { buildGetTopImageScript } from "./pythonScripts/getTopImageScript.js";
 import { detailOnlyFormattingSchema, formattingOptionsSchema, } from "./types.js";
 /**
  * Authoring helper that infers `params` from the tool's schema while erasing to
@@ -13,6 +15,24 @@ function defineTool(def) {
     // because params are validated by the MCP SDK before reaching run().
     return def;
 }
+/**
+ * `get_top_image` has no OpenAPI-backed endpoint (see architecture note on
+ * the tool definition below), so its params schema is defined locally
+ * instead of being derived from the generated Zod schemas.
+ */
+const GetTopImageParams = z.object({
+    maxSize: z
+        .number()
+        .int()
+        .positive()
+        .max(4096)
+        .optional()
+        .describe("Maximum length of the image's longer side in pixels. The TOP is downscaled (aspect ratio preserved) only if it exceeds this value; omit to capture at native resolution."),
+    nodePath: z
+        .string()
+        .min(1)
+        .describe("Path to the TOP node to capture, e.g. '/project1/moviefilein1'"),
+});
 export const TOOL_DEFINITIONS = [
     defineTool({
         category: "system",
@@ -314,4 +334,37 @@ console.log(docs.helpText?.slice(0, 200));`,
         },
         schema: GetModuleHelpQueryParams.extend(detailOnlyFormattingSchema.shape),
     }),
+    defineTool({
+        category: "nodes",
+        description: "Capture the current output of a TOP node as an image so it can be viewed directly (maxSize optionally downscales the longer side)",
+        errorComment: REFERENCE_COMMENT,
+        example: `import { getTopImage } from './servers/touchdesigner/getTopImage';
+
+const image = await getTopImage({ nodePath: '/project1/moviefilein1', maxSize: 512 });`,
+        name: TOOL_NAMES.GET_TOP_IMAGE,
+        notes: "Routed through the same Python execution channel as execute_python_script; no dedicated API endpoint exists. When maxSize forces a downscale, a temporary resolutionTOP is created next to the node and always destroyed afterward, so the project is left unmodified.",
+        returns: "An image content block (base64-encoded JPEG) with the captured TOP output.",
+        run: async ({ params, tdClient }) => {
+            const { nodePath, maxSize } = params;
+            const script = buildGetTopImageScript({ maxSize, nodePath });
+            const result = await tdClient.execPythonScript({ script });
+            if (!result.success) {
+                throw result.error;
+            }
+            const base64Data = result.data.result;
+            if (typeof base64Data !== "string" || base64Data.length === 0) {
+                throw new Error(`get_top_image: expected a base64 string result for ${nodePath}, got ${typeof base64Data}`);
+            }
+            return {
+                content: [
+                    { data: base64Data, mimeType: "image/jpeg", type: "image" },
+                    {
+                        text: `Captured TOP image from ${nodePath}${maxSize ? ` (maxSize=${maxSize}px)` : ""}.`,
+                        type: "text",
+                    },
+                ],
+            };
+        },
+        schema: GetTopImageParams,
+    }),
 ];

package/dist/gen/endpoints/TouchDesignerAPI.d.ts

@@ -3,7 +3,7 @@
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 1.4.3
+ * OpenAPI spec version: 1.5.0
  */
 import { customInstance } from '../../api/customInstance.js';
 import type { BodyType } from '../../api/customInstance.js';
@@ -395,6 +395,10 @@ export type ExecPythonScript200DataResult = {
 export type ExecPythonScript200Data = {
     /** Result of the executed script */
     result: ExecPythonScript200DataResult;
+    /** Captured standard output (e.g. print statements) emitted while the script ran */
+    stdout?: string;
+    /** Captured standard error output emitted while the script ran */
+    stderr?: string;
 } | null;
 export type ExecPythonScript200 = {
     /** Whether the operation was successful */

package/dist/gen/endpoints/TouchDesignerAPI.js

@@ -3,7 +3,7 @@
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 1.4.3
+ * OpenAPI spec version: 1.5.0
  */
 import { customInstance } from '../../api/customInstance.js';
 export const TdNodeFamilyType = {

package/dist/gen/mcp/touchDesignerAPI.zod.d.ts

@@ -3,7 +3,7 @@
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 1.4.3
+ * OpenAPI spec version: 1.5.0
  */
 import * as zod from 'zod';
 /**
@@ -233,6 +233,8 @@ export declare const ExecPythonScriptResponse: zod.ZodObject<{
         result: zod.ZodObject<{
             value: zod.ZodOptional<zod.ZodUnknown>;
         }, zod.z.core.$strip>;
+        stdout: zod.ZodOptional<zod.ZodString>;
+        stderr: zod.ZodOptional<zod.ZodString>;
     }, zod.z.core.$strip>>;
     error: zod.ZodNullable<zod.ZodString>;
 }, zod.z.core.$strip>;

package/dist/gen/mcp/touchDesignerAPI.zod.js

@@ -3,7 +3,7 @@
  * Do not edit manually.
  * TouchDesigner API
  * OpenAPI schema for generating TouchDesigner API client code
- * OpenAPI spec version: 1.4.3
+ * OpenAPI spec version: 1.5.0
  */
 import * as zod from 'zod';
 /**
@@ -222,7 +222,9 @@ export const ExecPythonScriptResponse = zod.object({
     "data": zod.object({
         "result": zod.object({
             "value": zod.unknown().optional().describe('Return value of the executed script, can be any serializable value')
-        }).describe('Result of the executed script')
+        }).describe('Result of the executed script'),
+        "stdout": zod.string().optional().describe('Captured standard output (e.g. print statements) emitted while the script ran'),
+        "stderr": zod.string().optional().describe('Captured standard error output emitted while the script ran')
     }).nullable(),
     "error": zod.string().nullable().describe('Error message if the operation was not successful')
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "1.4.12",
+	"version": "1.5.0",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",