touchdesigner-mcp-server 1.3.1 → 1.4.1

package/dist/cli.js

@@ -1,11 +1,16 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConsoleLogger } from "./core/logger.js";
 import { TouchDesignerServer } from "./server/touchDesignerServer.js";
+import { isStreamableHttpTransportConfig } from "./transport/config.js";
+import { ExpressHttpManager } from "./transport/expressHttpManager.js";
+import { TransportFactory } from "./transport/factory.js";
+import { SessionManager } from "./transport/sessionManager.js";
 // Note: Environment variables should be set by the MCP Bundle runtime or CLI arguments
 const DEFAULT_HOST = "http://127.0.0.1";
 const DEFAULT_PORT = 9981;
+const DEFAULT_MCP_ENDPOINT = "/mcp";
 /**
- * Parse command line arguments
+ * Parse command line arguments for TouchDesigner connection
  */
 export function parseArgs(args) {
     const argsToProcess = args || process.argv.slice(2);
@@ -25,38 +30,149 @@ export function parseArgs(args) {
     return parsed;
 }
 /**
- * Determine if the server should run in stdio mode
+ * 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 function isStdioMode(nodeEnv, argv) {
-    const env = nodeEnv ?? process.env.NODE_ENV;
-    const args = argv ?? process.argv;
-    return env === "cli" || args.includes("--stdio");
+export function parseTransportConfig(args) {
+    const argsToProcess = args || process.argv.slice(2);
+    // Check for HTTP mode
+    const httpPortArg = argsToProcess.find((arg) => arg.startsWith("--mcp-http-port="));
+    if (httpPortArg) {
+        const portStr = httpPortArg.split("=")[1];
+        const port = Number.parseInt(portStr, 10);
+        if (Number.isNaN(port) || port < 1 || port > 65535) {
+            console.error(`Invalid value for --mcp-http-port: "${portStr}". Please specify a valid port number (1-65535).`);
+            process.exit(1);
+        }
+        const hostArg = argsToProcess.find((arg) => arg.startsWith("--mcp-http-host="));
+        const host = hostArg ? hostArg.split("=")[1] : "127.0.0.1";
+        const config = {
+            endpoint: DEFAULT_MCP_ENDPOINT,
+            host,
+            port,
+            sessionConfig: { enabled: true },
+            type: "streamable-http",
+        };
+        return config;
+    }
+    // Default to stdio mode
+    return { type: "stdio" };
 }
 /**
  * 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 async function startServer(params) {
     try {
-        const isStdioModeFlag = isStdioMode(params?.nodeEnv, params?.argv);
-        if (!isStdioModeFlag) {
-            throw new Error("Sorry, this server is not yet available in the browser. Please use the CLI mode.");
-        }
-        // Parse command line arguments and set environment variables
+        // Parse transport configuration
+        const transportConfig = parseTransportConfig(params?.argv);
+        // Parse TouchDesigner connection arguments
         const args = parseArgs(params?.argv);
         process.env.TD_WEB_SERVER_HOST = args.host;
         process.env.TD_WEB_SERVER_PORT = args.port.toString();
+        // Create MCP server
         const server = new TouchDesignerServer();
-        const transport = new StdioServerTransport();
-        const result = await server.connect(transport);
-        if (!result.success) {
-            throw new Error(`Failed to connect: ${result.error.message}`);
+        // Handle stdio mode
+        if (transportConfig.type === "stdio") {
+            const transportResult = TransportFactory.create(transportConfig);
+            if (!transportResult.success) {
+                throw transportResult.error;
+            }
+            const result = await server.connect(transportResult.data);
+            if (!result.success) {
+                throw new Error(`Failed to connect: ${result.error.message}`);
+            }
+            console.error("MCP server started in stdio mode");
+            return;
         }
+        // Handle HTTP mode
+        if (isStreamableHttpTransportConfig(transportConfig)) {
+            // Use ConsoleLogger for HTTP manager and session manager
+            // This avoids "Not connected" errors since HTTP mode doesn't have a global MCP connection
+            const logger = new ConsoleLogger();
+            // Create session manager if enabled
+            const sessionManager = transportConfig.sessionConfig?.enabled
+                ? new SessionManager(transportConfig.sessionConfig, logger)
+                : null;
+            // Server factory for creating per-session instances
+            // Each session gets its own TouchDesignerServer with independent MCP protocol state
+            const serverFactory = () => TouchDesignerServer.create();
+            // Create Express HTTP manager with server factory
+            const httpManager = new ExpressHttpManager(transportConfig, serverFactory, sessionManager, logger);
+            // Start HTTP server
+            const startResult = await httpManager.start();
+            if (!startResult.success) {
+                throw startResult.error;
+            }
+            console.error(`MCP server started in HTTP mode on ${transportConfig.host}:${transportConfig.port}${transportConfig.endpoint}`);
+            // Start session cleanup if enabled
+            if (sessionManager) {
+                sessionManager.startTTLCleanup();
+            }
+            // Set up graceful shutdown
+            const shutdown = async () => {
+                console.error("\nShutting down server...");
+                // Stop session cleanup
+                if (sessionManager) {
+                    sessionManager.stopTTLCleanup();
+                }
+                // Stop HTTP server
+                const stopResult = await httpManager.stop();
+                if (!stopResult.success) {
+                    console.error(`Error during shutdown: ${stopResult.error.message}`);
+                }
+                console.error("Server shutdown complete");
+                process.exit(0);
+            };
+            process.on("SIGINT", shutdown);
+            process.on("SIGTERM", shutdown);
+            return;
+        }
+        // Type-safe exhaustive check using never type
+        // This ensures all cases of the TransportConfig discriminated union are handled
+        // If a new transport type is added, TypeScript will error at compile time
+        assertNever(transportConfig);
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         throw new Error(`Failed to initialize server: ${errorMessage}`);
     }
 }
+/**
+ * Helper function for exhaustive type checking
+ * TypeScript will error if called with a non-never type, ensuring all cases are handled
+ */
+function assertNever(value) {
+    throw new Error(`Unsupported transport type: ${value.type}`);
+}
 // Start server if this file is executed directly
 startServer({
     argv: process.argv,

package/dist/core/logger.js

@@ -28,3 +28,16 @@ export class McpLogger {
         }
     }
 }
+/**
+ * Console Logger implementation for standalone use (e.g., HTTP mode setup)
+ * Outputs to stderr to avoid interfering with stdio transport
+ */
+export class ConsoleLogger {
+    sendLog(args) {
+        const timestamp = new Date().toISOString();
+        const level = args.level?.toUpperCase() || "INFO";
+        const logger = args.logger || "unknown";
+        const data = args.data;
+        console.error(`[${timestamp}] [${level}] [${logger}] ${data}`);
+    }
+}

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.3.0
+ * OpenAPI spec version: 1.4.1
  */
 import { customInstance } from '../../api/customInstance.js';
 // eslint-disable-next-line @typescript-eslint/no-redeclare

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.3.0
+ * OpenAPI spec version: 1.4.1
  */
 import * as zod from 'zod';
 /**

package/dist/server/touchDesignerServer.js

@@ -32,6 +32,25 @@ export class TouchDesignerServer {
         this.connectionManager = new ConnectionManager(this.server, this.logger);
         this.registerAllFeatures();
     }
+    /**
+     * Create a new TouchDesignerServer instance
+     *
+     * Factory method for creating server instances in multi-session scenarios.
+     * Each session should have its own server instance to maintain independent MCP protocol state.
+     *
+     * @returns McpServer instance ready for connection to a transport
+     *
+     * @example
+     * ```typescript
+     * // In TransportRegistry
+     * const serverFactory = () => TouchDesignerServer.create();
+     * const transport = await registry.getOrCreate(sessionId, body, serverFactory);
+     * ```
+     */
+    static create() {
+        const instance = new TouchDesignerServer();
+        return instance.server;
+    }
     /**
      * Connect to MCP transport
      */

package/dist/transport/config.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/**
+ * Zod schema for SessionConfig validation
+ */
+const SessionConfigSchema = z
+    .object({
+    cleanupInterval: z.number().int().positive().optional(),
+    enabled: z.boolean(),
+    ttl: z.number().int().positive().optional(),
+})
+    .strict();
+/**
+ * Zod schema for StdioTransportConfig validation
+ */
+const StdioTransportConfigSchema = z
+    .object({
+    type: z.literal("stdio"),
+})
+    .strict();
+/**
+ * Zod schema for StreamableHttpTransportConfig validation
+ */
+const StreamableHttpTransportConfigSchema = z
+    .object({
+    endpoint: z
+        .string()
+        .min(1, "Endpoint cannot be empty")
+        .regex(/^\//, "Endpoint must start with /"),
+    host: z.string().min(1, "Host cannot be empty"),
+    port: z
+        .number()
+        .int()
+        .positive()
+        .min(1)
+        .max(65535, "Port must be between 1 and 65535"),
+    retryInterval: z.number().int().positive().optional(),
+    sessionConfig: SessionConfigSchema.optional(),
+    type: z.literal("streamable-http"),
+})
+    .strict();
+/**
+ * Zod schema for TransportConfig validation (discriminated union)
+ */
+export const TransportConfigSchema = z.discriminatedUnion("type", [
+    StdioTransportConfigSchema,
+    StreamableHttpTransportConfigSchema,
+]);
+/**
+ * Type guard to check if config is StdioTransportConfig
+ */
+export function isStdioTransportConfig(config) {
+    return config.type === "stdio";
+}
+/**
+ * Type guard to check if config is StreamableHttpTransportConfig
+ */
+export function isStreamableHttpTransportConfig(config) {
+    return config.type === "streamable-http";
+}
+/**
+ * Default values for SessionConfig
+ */
+export const DEFAULT_SESSION_CONFIG = {
+    cleanupInterval: 5 * 60 * 1000, // 5 minutes
+    enabled: true,
+    ttl: 60 * 60 * 1000, // 1 hour
+};
+/**
+ * Default values for StreamableHttpTransportConfig (excluding required fields)
+ */
+export const DEFAULT_HTTP_CONFIG = {
+    endpoint: "/mcp",
+    host: "127.0.0.1",
+    sessionConfig: DEFAULT_SESSION_CONFIG,
+};

package/dist/transport/expressHttpManager.js

@@ -0,0 +1,235 @@
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { createErrorResult, createSuccessResult } from "../core/result.js";
+import { TransportRegistry } from "./transportRegistry.js";
+/**
+ * Express HTTP Manager
+ *
+ * Manages HTTP server lifecycle for Streamable HTTP transport.
+ * Handles multiple concurrent sessions by creating per-session transport and server instances.
+ *
+ * Key Features:
+ * - /mcp endpoint → routes to appropriate transport via TransportRegistry
+ * - /health endpoint → reports active session count
+ * - Per-session isolation → each client gets independent MCP protocol state
+ * - Graceful shutdown → cleans up all active sessions
+ *
+ * Architecture:
+ * ```
+ * Client 1 → POST /mcp → TransportRegistry.getOrCreate() → Transport 1 + Server 1
+ * Client 2 → POST /mcp → TransportRegistry.getOrCreate() → Transport 2 + Server 2
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const manager = new ExpressHttpManager(
+ *   config,
+ *   () => TouchDesignerServer.create(), // Server factory
+ *   sessionManager,
+ *   logger
+ * );
+ *
+ * // Start server
+ * const result = await manager.start();
+ *
+ * // Graceful shutdown
+ * await manager.stop();
+ * ```
+ */
+export class ExpressHttpManager {
+    config;
+    serverFactory;
+    logger;
+    registry;
+    server = null;
+    /**
+     * Create ExpressHttpManager with server factory
+     *
+     * @param config - Streamable HTTP transport configuration
+     * @param serverFactory - Factory function to create new Server instances per session
+     * @param sessionManager - Session manager for TTL tracking (optional)
+     * @param logger - Logger instance
+     */
+    constructor(config, serverFactory, sessionManager, logger) {
+        this.config = config;
+        this.serverFactory = serverFactory;
+        this.logger = logger;
+        this.registry = new TransportRegistry(config, sessionManager, logger);
+    }
+    /**
+     * Start HTTP server with Express app from SDK
+     *
+     * @returns Result indicating success or failure
+     */
+    async start() {
+        try {
+            if (this.server?.listening) {
+                return createErrorResult(new Error("Express HTTP server is already running"));
+            }
+            // Create Express app using SDK's factory
+            // This automatically includes DNS rebinding protection for localhost
+            const app = createMcpExpressApp({
+                host: this.config.host,
+            });
+            // MCP endpoint handler - routes to appropriate transport via registry
+            const handleMcpRequest = async (req, res) => {
+                try {
+                    // Extract session ID from header
+                    const sessionId = req.headers["mcp-session-id"];
+                    // Get or create transport for this session
+                    const transport = await this.registry.getOrCreate(sessionId, req.body, this.serverFactory);
+                    if (!transport) {
+                        // Invalid session (session ID provided but not found, or non-initialize without session)
+                        res.status(400).json({
+                            error: {
+                                code: -32000,
+                                message: "Invalid session",
+                            },
+                            id: null,
+                            jsonrpc: "2.0",
+                        });
+                        return;
+                    }
+                    // Delegate request to transport
+                    await transport.handleRequest(req, res, req.body);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    this.logger.sendLog({
+                        data: `Error handling MCP request: ${errorMessage}`,
+                        level: "error",
+                        logger: "ExpressHttpManager",
+                    });
+                    if (!res.headersSent) {
+                        res.status(500).json({
+                            error: "Internal server error",
+                        });
+                    }
+                }
+            };
+            // Configure /mcp endpoints
+            // POST: JSON-RPC requests (initialize, tool calls, etc.)
+            // GET: SSE streaming for notifications
+            // DELETE: Session termination
+            app.post(this.config.endpoint, handleMcpRequest);
+            app.get(this.config.endpoint, handleMcpRequest);
+            app.delete(this.config.endpoint, handleMcpRequest);
+            // Configure /health endpoint
+            app.get("/health", (_req, res) => {
+                const sessionCount = this.registry.getCount();
+                res.json({
+                    sessions: sessionCount,
+                    status: "ok",
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            // Start HTTP server
+            await new Promise((resolve, reject) => {
+                try {
+                    this.server = app.listen(this.config.port, this.config.host, () => {
+                        this.logger.sendLog({
+                            data: `Express HTTP server listening on ${this.config.host}:${this.config.port}`,
+                            level: "info",
+                            logger: "ExpressHttpManager",
+                        });
+                        this.logger.sendLog({
+                            data: `MCP endpoint: ${this.config.endpoint}`,
+                            level: "info",
+                            logger: "ExpressHttpManager",
+                        });
+                        this.logger.sendLog({
+                            data: "Health check: GET /health",
+                            level: "info",
+                            logger: "ExpressHttpManager",
+                        });
+                        resolve();
+                    });
+                    this.server.on("error", (error) => {
+                        reject(error);
+                    });
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            return createSuccessResult(undefined);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            return createErrorResult(new Error(`Failed to start Express HTTP server: ${err.message}`));
+        }
+    }
+    /**
+     * Graceful shutdown
+     *
+     * Stops HTTP server and cleans up all active sessions.
+     *
+     * @returns Result indicating success or failure
+     */
+    async stop() {
+        try {
+            if (!this.server) {
+                return createSuccessResult(undefined);
+            }
+            this.logger.sendLog({
+                data: "Stopping Express HTTP server...",
+                level: "info",
+                logger: "ExpressHttpManager",
+            });
+            // Cleanup all active sessions first
+            const cleanupResult = await this.registry.cleanup();
+            if (!cleanupResult.success) {
+                this.logger.sendLog({
+                    data: `Warning: Session cleanup failed: ${cleanupResult.error.message}`,
+                    level: "warning",
+                    logger: "ExpressHttpManager",
+                });
+            }
+            // Close HTTP server
+            await new Promise((resolve, reject) => {
+                this.server?.close((error) => {
+                    if (error) {
+                        reject(error);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+            this.logger.sendLog({
+                data: "Express HTTP server stopped",
+                level: "info",
+                logger: "ExpressHttpManager",
+            });
+            this.server = null;
+            return createSuccessResult(undefined);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            return createErrorResult(new Error(`Failed to stop Express HTTP server: ${err.message}`));
+        }
+    }
+    /**
+     * Check if server is running
+     *
+     * @returns True if server is running
+     */
+    isRunning() {
+        return this.server?.listening ?? false;
+    }
+    /**
+     * Get active session count
+     *
+     * @returns Number of active sessions
+     */
+    getActiveSessionCount() {
+        return this.registry.getCount();
+    }
+    /**
+     * Get all active session IDs
+     *
+     * @returns Array of session IDs
+     */
+    getActiveSessionIds() {
+        return this.registry.getSessionIds();
+    }
+}