touchdesigner-mcp-server 1.4.9 → 1.4.10

package/dist/api/customInstance.d.ts

@@ -0,0 +1,5 @@
+import { type AxiosError, type AxiosRequestConfig } from "axios";
+export declare const AXIOS_INSTANCE: import("axios").AxiosInstance;
+export declare const customInstance: <T>(config: AxiosRequestConfig, options?: AxiosRequestConfig) => Promise<T>;
+export type ErrorType<E> = AxiosError<E>;
+export type BodyType<BodyData> = BodyData;

package/dist/cli.d.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import type { TransportConfig } from "./transport/config.js";
+/**
+ * Parse command line arguments for TouchDesigner connection
+ */
+export declare function parseArgs(args?: string[]): {
+    host: string;
+    port: number;
+};
+/**
+ * Parse transport configuration from command line arguments
+ *
+ * Detects if HTTP mode is requested via --mcp-http-port flag.
+ * If not specified, defaults to stdio mode.
+ *
+ * @param args - Command line arguments (defaults to process.argv.slice(2))
+ * @returns Transport configuration (stdio or streamable-http)
+ *
+ * @example
+ * ```bash
+ * # Stdio mode (default)
+ * touchdesigner-mcp-server --host=http://localhost --port=9981
+ *
+ * # HTTP mode
+ * touchdesigner-mcp-server --mcp-http-port=6280 --mcp-http-host=127.0.0.1
+ * ```
+ */
+export declare function parseTransportConfig(args?: string[]): TransportConfig;
+/**
+ * Start TouchDesigner MCP server
+ *
+ * Supports both stdio and HTTP transport modes based on command line arguments.
+ *
+ * @param params - Server startup parameters
+ * @param params.argv - Command line arguments
+ * @param params.nodeEnv - Node environment
+ *
+ * @example
+ * ```bash
+ * # Stdio mode (default)
+ * touchdesigner-mcp-server --host=http://localhost --port=9981
+ *
+ * # HTTP mode
+ * touchdesigner-mcp-server --mcp-http-port=6280 --host=http://localhost --port=9981
+ * ```
+ */
+export declare function startServer(params?: {
+    nodeEnv?: string;
+    argv?: string[];
+}): Promise<void>;

package/dist/core/compatibility.d.ts

@@ -0,0 +1,102 @@
+export declare const COMPATIBILITY_POLICY_TYPES: {
+    readonly BELOW_MIN_VERSION: "belowMinVersion";
+    readonly COMPATIBLE: "compatible";
+    readonly MAJOR_MISMATCH: "majorMismatch";
+    readonly NEWER_MINOR: "newerMinor";
+    readonly NO_VERSION: "noVersion";
+    readonly OLDER_MINOR: "olderMinor";
+    readonly PATCH_DIFF: "patchDiff";
+};
+export declare const COMPATIBILITY_POLICY_ERROR_LEVELS: {
+    readonly ALLOW: "info";
+    readonly ERROR: "error";
+    readonly WARNING: "warning";
+};
+export type CompatibilityPolicyType = (typeof COMPATIBILITY_POLICY_TYPES)[keyof typeof COMPATIBILITY_POLICY_TYPES];
+export type CompatibilityPolicyErrorLevel = (typeof COMPATIBILITY_POLICY_ERROR_LEVELS)[keyof typeof COMPATIBILITY_POLICY_ERROR_LEVELS];
+export declare const getCompatibilityPolicyType: (params: {
+    mcpVersion: string;
+    apiVersion: string;
+}) => CompatibilityPolicyType;
+export declare const getCompatibilityPolicy: (type: CompatibilityPolicyType) => {
+    readonly compatible: false;
+    readonly level: "error";
+    readonly message: typeof generateNoVersionMessage;
+} | {
+    readonly compatible: false;
+    readonly level: "error";
+    readonly message: typeof generateMinVersionMessage;
+} | {
+    readonly compatible: false;
+    readonly level: "error";
+    readonly message: typeof generateMajorMismatchMessage;
+} | {
+    readonly compatible: true;
+    readonly level: "warning";
+    readonly message: typeof generateNewerMinorMessage;
+} | {
+    readonly compatible: true;
+    readonly level: "warning";
+    readonly message: typeof generateOlderMinorMessage;
+} | {
+    readonly compatible: true;
+    readonly level: "info";
+    readonly message: typeof generatePatchDiffMessage;
+} | {
+    readonly compatible: true;
+    readonly level: "info";
+    readonly message: typeof generateFullyCompatibleMessage;
+};
+/**
+ * Generate error message for unknown version information
+ */
+export declare function generateNoVersionMessage(args: {
+    apiVersion: string;
+    mcpVersion: string;
+}): string;
+/**
+ * Generate error message for MAJOR version mismatch
+ */
+export declare function generateMajorMismatchMessage(args: {
+    apiVersion: string;
+    mcpVersion: string;
+}): string;
+/**
+ * Generate error message when API version is below minimum compatible version
+ */
+export declare function generateMinVersionMessage(args: {
+    apiVersion: string;
+    minRequired: string;
+}): string;
+/**
+ * Generate warning message when MCP server has newer MINOR version
+ */
+export declare function generateNewerMinorMessage(args: {
+    apiVersion: string;
+    mcpVersion: string;
+}): string;
+/**
+ * Generate warning message when API server has newer MINOR version
+ */
+export declare function generateOlderMinorMessage(args: {
+    apiVersion: string;
+    mcpVersion: string;
+}): string;
+/**
+ * Generate warning message when PATCH versions differ
+ */
+export declare function generatePatchDiffMessage(args: {
+    apiVersion: string;
+    mcpVersion: string;
+}): string;
+/**
+ * Generate info message when versions are fully compatible
+ *
+ * @param mcpVersion MCP server version
+ * @param apiVersion TouchDesigner API server version
+ * @returns Info message
+ */
+export declare function generateFullyCompatibleMessage(args: {
+    apiVersion: string;
+    mcpVersion: string;
+}): string;

package/dist/core/constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Reference URLs for TouchDesigner Python documentation
+ */
+export declare const TD_PYTHON_CLASS_REFERENCE_BASE_URL = "https://docs.derivative.ca";
+export declare const TD_PYTHON_CLASS_REFERENCE_INDEX_URL = "https://docs.derivative.ca/Python_Classes_and_Modules";
+/**
+ * Reference Tool Names for TouchDesigner MCP
+ */
+export declare const TOOL_NAMES: {
+    readonly CREATE_TD_NODE: "create_td_node";
+    readonly DELETE_TD_NODE: "delete_td_node";
+    readonly DESCRIBE_TD_TOOLS: "describe_td_tools";
+    readonly EXECUTE_NODE_METHOD: "exec_node_method";
+    readonly EXECUTE_PYTHON_SCRIPT: "execute_python_script";
+    readonly GET_TD_CLASS_DETAILS: "get_td_class_details";
+    readonly GET_TD_CLASSES: "get_td_classes";
+    readonly GET_TD_INFO: "get_td_info";
+    readonly GET_TD_MODULE_HELP: "get_td_module_help";
+    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 UPDATE_TD_NODE_PARAMETERS: "update_td_node_parameters";
+};
+export declare const REFERENCE_COMMENT = "Check reference resources: https://docs.derivative.ca/Python_Classes_and_Modules";
+export declare const PROMPT_NAMES: {
+    readonly CHECK_NODE_ERRORS: "Check node errors";
+    readonly NODE_CONNECTION: "Node connection";
+    readonly SEARCH_NODE: "Search node";
+};

package/dist/core/errorHandling.d.ts

@@ -0,0 +1,18 @@
+import type { ToolNames } from "../features/tools/index.js";
+import type { ILogger } from "./logger.js";
+/**
+ * Standard API error response structure compatible with MCP SDK
+ */
+interface ErrorResponse {
+    [key: string]: unknown;
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+/**
+ * Handles API errors consistently across the application
+ */
+export declare function handleToolError(error: unknown, logger: ILogger, toolName: ToolNames, referenceComment?: string): ErrorResponse;
+export {};

package/dist/core/logger.d.ts

@@ -0,0 +1,24 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LoggingMessageNotification } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Logger interface definition
+ */
+export interface ILogger {
+    sendLog(args: LoggingMessageNotification["params"]): void;
+}
+/**
+ * MCP compatible logger implementation
+ * Handles "Not connected" errors gracefully
+ */
+export declare class McpLogger implements ILogger {
+    private server;
+    constructor(server: McpServer);
+    sendLog(args: LoggingMessageNotification["params"]): void;
+}
+/**
+ * Console Logger implementation for standalone use (e.g., HTTP mode setup)
+ * Outputs to stderr to avoid interfering with stdio transport
+ */
+export declare class ConsoleLogger implements ILogger {
+    sendLog(args: LoggingMessageNotification["params"]): void;
+}

package/dist/core/result.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Result type pattern for handling operation results
+ * Success case contains data, failure case contains error
+ */
+export type Result<T, E = Error> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: E;
+};
+/**
+ * Creates a success result with the provided data
+ */
+export declare function createSuccessResult<T>(data: T): {
+    success: true;
+    data: T;
+};
+/**
+ * Creates an error result with the provided error
+ */
+export declare function createErrorResult<E = Error>(error: E): {
+    success: false;
+    error: E;
+};

package/dist/core/version.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Current MCP server version
+ */
+export declare const getMcpServerVersion: () => string;
+export declare const MCP_SERVER_VERSION: string;
+/**
+ * Minimum compatible TouchDesigner API Server version required by the MCP server
+ *
+ * Loaded from package.json's mcpCompatibility.minApiVersion field.
+ * Falls back to the current package version if undefined.
+ *
+ * API Server must be at or above this version.
+ * - MAJOR mismatch: Error
+ * - MINOR/PATCH differences: Warning or allow
+ *
+ * Update when:
+ * - Introducing breaking API changes
+ * - Making incompatible changes to OpenAPI schema
+ */
+export declare const getMinCompatibleApiVersion: () => string;
+export declare const MIN_COMPATIBLE_API_VERSION: string;

package/dist/features/prompts/handlers/td_prompts.d.ts

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

package/dist/features/prompts/index.d.ts

@@ -0,0 +1 @@
+export * from "./register.js";

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

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

package/dist/features/tools/handlers/tdTools.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ILogger } from "../../../core/logger.js";
+import type { TouchDesignerClient } from "../../../tdClient/touchDesignerClient.js";
+export declare function registerTdTools(server: McpServer, logger: ILogger, tdClient: TouchDesignerClient): void;

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

@@ -0,0 +1,3 @@
+import type { TOOL_NAMES } from "../../core/constants.js";
+export * from "./register.js";
+export type ToolNames = (typeof TOOL_NAMES)[keyof typeof TOOL_NAMES];

package/dist/features/tools/metadata/touchDesignerToolMetadata.d.ts

@@ -0,0 +1,29 @@
+import type { z } from "zod";
+import type { ToolNames } from "../index.js";
+import { type ToolCategory, type ToolDefinition } from "../toolDefinitions.js";
+export type { ToolCategory };
+export interface ToolParameterMetadata {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+}
+export interface ToolMetadata {
+    tool: ToolNames;
+    modulePath: string;
+    functionName: string;
+    description: string;
+    category: ToolCategory;
+    parameters: ToolParameterMetadata[];
+    returns: string;
+    example: string;
+    notes?: string;
+}
+/**
+ * Builds the `describe_td_tools` manifest from the tool table. Parameter
+ * metadata is introspected from each tool's Zod schema, so it always reflects
+ * the schema that is actually registered (sourced from the OpenAPI spec).
+ */
+export declare function buildToolMetadata(definitions?: readonly ToolDefinition[]): ToolMetadata[];
+/** Introspects a Zod object schema into flat parameter metadata. */
+export declare function deriveParameters(schema: z.ZodObject<z.ZodRawShape>): ToolParameterMetadata[];

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

@@ -0,0 +1,29 @@
+/**
+ * Class List Formatter
+ *
+ * Formats TouchDesigner Python class/module lists with token optimization.
+ * Used by GET_TD_CLASSES and GET_TD_CLASS_DETAILS tools.
+ */
+import type { TdPythonClassDetails, TdPythonClassInfo } from "../../../gen/endpoints/TouchDesignerAPI.js";
+import type { FormatterOptions } from "./responseFormatter.js";
+/**
+ * Class list data structure (matches API response)
+ */
+export interface ClassListData {
+    classes?: TdPythonClassInfo[];
+    modules?: string[];
+    totalCount?: number;
+    [key: string]: unknown;
+}
+/**
+ * Class details data structure (matches API response)
+ */
+export type ClassDetailsData = TdPythonClassDetails;
+/**
+ * Format class/module list
+ */
+export declare function formatClassList(data: ClassListData | undefined, options?: FormatterOptions): string;
+/**
+ * Format class details
+ */
+export declare function formatClassDetails(data: ClassDetailsData | undefined, options?: FormatterOptions): string;

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

@@ -0,0 +1,18 @@
+/**
+ * Response Formatters Index
+ *
+ * Central export point for all response formatters
+ */
+export type { ClassDetailsData, ClassListData } from "./classListFormatter.js";
+export { formatClassDetails, formatClassList } from "./classListFormatter.js";
+export { formatModuleHelp } from "./moduleHelpFormatter.js";
+export type { NodeDetailsData } from "./nodeDetailsFormatter.js";
+export { formatNodeDetails } from "./nodeDetailsFormatter.js";
+export type { NodeErrorReportData } from "./nodeErrorsFormatter.js";
+export { formatNodeErrors } from "./nodeErrorsFormatter.js";
+export type { NodeListData } from "./nodeListFormatter.js";
+export { formatNodeList } from "./nodeListFormatter.js";
+export { formatCreateNodeResult, formatDeleteNodeResult, formatExecNodeMethodResult, formatTdInfo, formatUpdateNodeResult, } from "./operationFormatter.js";
+export type { ScriptResultData } from "./scriptResultFormatter.js";
+export { formatScriptResult } from "./scriptResultFormatter.js";
+export { formatToolMetadata } from "./toolMetadataFormatter.js";

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

@@ -0,0 +1,3 @@
+type Context = Record<string, unknown>;
+export declare function renderMarkdownTemplate(templateName: string, context?: Context): string;
+export {};

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

@@ -0,0 +1,12 @@
+/**
+ * Module Help Formatter
+ *
+ * Formats TouchDesigner module help information with token optimization.
+ * Used by GET_MODULE_HELP tool.
+ */
+import type { ModuleHelp } from "../../../gen/endpoints/TouchDesignerAPI.js";
+import type { FormatterOptions } from "./responseFormatter.js";
+/**
+ * Format module help result
+ */
+export declare function formatModuleHelp(data: ModuleHelp | undefined, options?: FormatterOptions): string;

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

@@ -0,0 +1,16 @@
+/**
+ * Node Details Formatter
+ *
+ * Formats TouchDesigner node parameter details with token optimization.
+ * Used by GET_TD_NODE_PARAMETERS tool.
+ */
+import type { TdNode } from "../../../gen/endpoints/TouchDesignerAPI.js";
+import type { FormatterOptions } from "./responseFormatter.js";
+/**
+ * Node details data structure (matches API response)
+ */
+export type NodeDetailsData = TdNode;
+/**
+ * Format node parameter details
+ */
+export declare function formatNodeDetails(data: NodeDetailsData | undefined, options?: FormatterOptions): string;

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

@@ -0,0 +1,4 @@
+import type { TdNodeErrorReport } from "../../../gen/endpoints/TouchDesignerAPI.js";
+import type { FormatterOptions } from "./responseFormatter.js";
+export type NodeErrorReportData = TdNodeErrorReport;
+export declare function formatNodeErrors(data: NodeErrorReportData | undefined, options?: FormatterOptions): string;

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[];