touchdesigner-mcp-server 1.3.1 → 1.4.1

package/dist/transport/transportRegistry.js

@@ -0,0 +1,272 @@
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createErrorResult, createSuccessResult } from "../core/result.js";
+/**
+ * Transport Registry
+ *
+ * Manages per-session transport and server instances for Streamable HTTP transport.
+ * Each session gets its own isolated transport and server to maintain independent MCP protocol state.
+ *
+ * Key Responsibilities:
+ * - Create new transport + server instances for new sessions
+ * - Reuse existing transport for requests with valid session IDs
+ * - Clean up sessions on close or expiration
+ * - Track active session count for health checks
+ *
+ * @example
+ * ```typescript
+ * const registry = new TransportRegistry(config, sessionManager, logger);
+ *
+ * // In HTTP request handler
+ * const transport = await registry.getOrCreate(
+ *   sessionId,
+ *   requestBody,
+ *   () => createTouchDesignerServer()
+ * );
+ *
+ * if (transport) {
+ *   await transport.handleRequest(req, res, requestBody);
+ * }
+ *
+ * // On shutdown
+ * await registry.cleanup();
+ * ```
+ */
+export class TransportRegistry {
+    sessions = new Map();
+    config;
+    sessionManager;
+    logger;
+    constructor(config, sessionManager, logger) {
+        this.config = config;
+        this.sessionManager = sessionManager;
+        this.logger = logger;
+        if (this.sessionManager) {
+            this.sessionManager.setExpirationHandler(async (sessionId) => {
+                const entry = this.sessions.get(sessionId);
+                if (!entry) {
+                    return;
+                }
+                this.logger.sendLog({
+                    data: `Expiring session via TTL: ${sessionId}`,
+                    level: "info",
+                    logger: "TransportRegistry",
+                });
+                try {
+                    await entry.transport.close();
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    this.logger.sendLog({
+                        data: `Error closing expired session ${sessionId}: ${err.message}`,
+                        level: "error",
+                        logger: "TransportRegistry",
+                    });
+                }
+                finally {
+                    this.remove(sessionId);
+                }
+            });
+        }
+    }
+    /**
+     * Get or create transport for a session
+     *
+     * Logic:
+     * 1. If sessionId exists and valid → return existing transport
+     * 2. If no sessionId and request is initialize → create new transport + server
+     * 3. Otherwise → return null (invalid session)
+     *
+     * @param sessionId - Session ID from mcp-session-id header (undefined for new sessions)
+     * @param requestBody - JSON-RPC request body
+     * @param serverFactory - Factory function to create new Server instances
+     * @returns Transport instance or null if session is invalid
+     */
+    async getOrCreate(sessionId, requestBody, serverFactory) {
+        // Case 1: Reuse existing session
+        if (sessionId && this.sessions.has(sessionId)) {
+            const entry = this.sessions.get(sessionId);
+            if (entry) {
+                if (this.sessionManager) {
+                    this.sessionManager.touch(sessionId);
+                }
+                this.logger.sendLog({
+                    data: `Reusing existing session: ${sessionId}`,
+                    level: "debug",
+                    logger: "TransportRegistry",
+                });
+                return entry.transport;
+            }
+        }
+        // Case 2: Create new session (only for initialize requests without session ID)
+        if (!sessionId && isInitializeRequest(requestBody)) {
+            return await this.createSession(serverFactory);
+        }
+        // Case 3: Invalid session (session ID provided but not found, or non-initialize without session)
+        this.logger.sendLog({
+            data: `Invalid session request: sessionId=${sessionId}, isInitialize=${isInitializeRequest(requestBody)}`,
+            level: "warning",
+            logger: "TransportRegistry",
+        });
+        return null;
+    }
+    /**
+     * Create a new session with transport and server instances
+     *
+     * @param serverFactory - Factory function to create new Server instances
+     * @returns Transport instance for the new session
+     */
+    async createSession(serverFactory) {
+        let transport = null;
+        let server = null;
+        // Create transport with session lifecycle callbacks
+        transport = new StreamableHTTPServerTransport({
+            // Disable JSON responses (use SSE for streaming)
+            enableJsonResponse: false,
+            // Session close callback
+            onsessionclosed: (sessionId) => {
+                this.logger.sendLog({
+                    data: `Session closed: ${sessionId}`,
+                    level: "info",
+                    logger: "TransportRegistry",
+                });
+                // Remove from registry
+                this.remove(sessionId);
+                // Cleanup from SessionManager
+                if (this.sessionManager) {
+                    this.sessionManager.cleanup(sessionId);
+                }
+            },
+            // Session initialization callback
+            onsessioninitialized: (sessionId) => {
+                this.logger.sendLog({
+                    data: `Session initialized: ${sessionId}`,
+                    level: "info",
+                    logger: "TransportRegistry",
+                });
+                // Store session in registry
+                if (transport && server) {
+                    this.sessions.set(sessionId, {
+                        createdAt: Date.now(),
+                        server,
+                        transport,
+                    });
+                    this.logger.sendLog({
+                        data: `Session stored in registry: ${sessionId} (total: ${this.sessions.size})`,
+                        level: "debug",
+                        logger: "TransportRegistry",
+                    });
+                }
+                // Register with SessionManager for TTL tracking
+                if (this.sessionManager) {
+                    this.sessionManager.register(sessionId);
+                }
+            },
+            // Retry interval for SSE
+            retryInterval: this.config.retryInterval,
+            // Session ID generator
+            sessionIdGenerator: this.config.sessionConfig?.enabled
+                ? () => randomUUID()
+                : undefined,
+        });
+        // Handle transport close event
+        transport.onclose = () => {
+            if (transport?.sessionId) {
+                this.logger.sendLog({
+                    data: `Transport closed for session: ${transport.sessionId}`,
+                    level: "debug",
+                    logger: "TransportRegistry",
+                });
+                this.remove(transport.sessionId);
+            }
+        };
+        // Create server instance
+        server = serverFactory();
+        // Connect server to transport
+        await server.connect(transport);
+        this.logger.sendLog({
+            data: "Created new session (session ID will be assigned after initialize)",
+            level: "info",
+            logger: "TransportRegistry",
+        });
+        return transport;
+    }
+    /**
+     * Remove session from registry
+     *
+     * @param sessionId - Session ID to remove
+     */
+    remove(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (entry) {
+            this.sessions.delete(sessionId);
+            this.logger.sendLog({
+                data: `Session removed from registry: ${sessionId} (remaining: ${this.sessions.size})`,
+                level: "info",
+                logger: "TransportRegistry",
+            });
+        }
+    }
+    /**
+     * Get number of active sessions
+     *
+     * @returns Active session count
+     */
+    getCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Get all session IDs
+     *
+     * @returns Array of session IDs
+     */
+    getSessionIds() {
+        return Array.from(this.sessions.keys());
+    }
+    /**
+     * Cleanup all sessions
+     *
+     * Called during graceful shutdown to close all active sessions
+     *
+     * @returns Result indicating success or failure
+     */
+    async cleanup() {
+        try {
+            this.logger.sendLog({
+                data: `Cleaning up ${this.sessions.size} active session(s)`,
+                level: "info",
+                logger: "TransportRegistry",
+            });
+            const closePromises = [];
+            for (const [sessionId, entry] of this.sessions.entries()) {
+                try {
+                    // Close transport (this will trigger onsessionclosed callback)
+                    closePromises.push(entry.transport.close());
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    this.logger.sendLog({
+                        data: `Error closing session ${sessionId}: ${err.message}`,
+                        level: "error",
+                        logger: "TransportRegistry",
+                    });
+                }
+            }
+            // Wait for all transports to close
+            await Promise.all(closePromises);
+            // Clear the map (should already be empty due to onsessionclosed callbacks)
+            this.sessions.clear();
+            this.logger.sendLog({
+                data: "All sessions cleaned up",
+                level: "info",
+                logger: "TransportRegistry",
+            });
+            return createSuccessResult(undefined);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            return createErrorResult(new Error(`Failed to cleanup sessions: ${err.message}`));
+        }
+    }
+}

package/dist/transport/validator.js

@@ -0,0 +1,78 @@
+import { ZodError } from "zod";
+import { createErrorResult, createSuccessResult } from "../core/result.js";
+import { TransportConfigSchema } from "./config.js";
+/**
+ * Transport configuration validator using Zod schemas
+ */
+export class TransportConfigValidator {
+    /**
+     * Validate a transport configuration
+     *
+     * @param config - The configuration to validate
+     * @returns Result with validated config or validation errors
+     */
+    static validate(config) {
+        try {
+            const validatedConfig = TransportConfigSchema.parse(config);
+            return createSuccessResult(validatedConfig);
+        }
+        catch (error) {
+            if (error instanceof ZodError) {
+                const validationErrors = TransportConfigValidator.formatZodErrors(error);
+                const errorMessage = TransportConfigValidator.buildErrorMessage(validationErrors);
+                return createErrorResult(new Error(errorMessage));
+            }
+            // Unexpected error
+            const err = error instanceof Error ? error : new Error(String(error));
+            return createErrorResult(new Error(`Transport configuration validation failed: ${err.message}`));
+        }
+    }
+    /**
+     * Format Zod validation errors into structured ValidationError objects
+     *
+     * @param zodError - The Zod validation error
+     * @returns Array of structured validation errors
+     */
+    static formatZodErrors(zodError) {
+        return zodError.issues.map((err) => ({
+            field: err.path.join("."),
+            message: err.message,
+        }));
+    }
+    /**
+     * Build a comprehensive error message from validation errors
+     *
+     * @param errors - Array of validation errors
+     * @returns Formatted error message
+     */
+    static buildErrorMessage(errors) {
+        const errorLines = errors.map((err) => {
+            if (err.field) {
+                return `  - ${err.field}: ${err.message}`;
+            }
+            return `  - ${err.message}`;
+        });
+        return `Transport configuration validation failed:\n${errorLines.join("\n")}`;
+    }
+    /**
+     * Validate and merge with defaults for HTTP transport
+     * This is a convenience method for applying default values after validation
+     *
+     * @param config - The configuration to validate
+     * @returns Result with validated and merged config
+     */
+    static validateAndMergeDefaults(config) {
+        const validationResult = TransportConfigValidator.validate(config);
+        if (!validationResult.success) {
+            return validationResult;
+        }
+        // No merging needed for stdio
+        if (validationResult.data.type === "stdio") {
+            return validationResult;
+        }
+        // Merge defaults for HTTP transport
+        // Note: Defaults are already defined in config.ts
+        // This method is here for future extensibility if runtime merging is needed
+        return validationResult;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "1.3.1",
+	"version": "1.4.1",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",
@@ -32,6 +32,7 @@
 		"@types/ws": "^8.18.1",
 		"@types/yargs": "^17.0.35",
 		"axios": "^1.13.2",
+		"express": "^5.2.1",
 		"mustache": "^4.2.0",
 		"semver": "^7.7.3",
 		"yaml": "^2.8.2",
@@ -40,6 +41,7 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.3.8",
 		"@openapitools/openapi-generator-cli": "^2.25.2",
+		"@types/express": "^5.0.6",
 		"@types/jsdom": "^27.0.0",
 		"@types/mustache": "^4.2.6",
 		"@types/node": "^24.10.1",
@@ -80,6 +82,7 @@
 		"format:python": "ruff format td/ && ruff check --fix td/",
 		"format:yaml": "prettier --write \"**/*.{yml,yaml}\"",
 		"dev": "npx @modelcontextprotocol/inspector node dist/cli.js --stdio",
+		"http": "npm run build && node dist/cli.js --mcp-http-port=6280 --mcp-http-host=127.0.0.1 --host=http://127.0.0.1 --port=9981",
 		"test": "run-p test:*",
 		"test:integration": "vitest run ./tests/integration",
 		"test:unit": "vitest run ./tests/unit",