touchdesigner-mcp-server 1.3.0 → 1.4.0

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();
+    }
+}

package/dist/transport/factory.js

@@ -0,0 +1,198 @@
+import { randomUUID } from "node:crypto";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createErrorResult, createSuccessResult } from "../core/result.js";
+import { isStreamableHttpTransportConfig } from "./config.js";
+import { TransportConfigValidator } from "./validator.js";
+/**
+ * Factory for creating MCP transport instances based on configuration
+ *
+ * This factory implements the Factory pattern to encapsulate transport creation logic.
+ * It validates configuration and creates the appropriate transport type (stdio or HTTP).
+ */
+export class TransportFactory {
+    /**
+     * Reset the internal state of a StreamableHTTPServerTransport instance
+     *
+     * WARNING: This method manipulates the private field '_initialized' using Reflect.set().
+     * This is fragile and may break if the MCP SDK implementation changes.
+     * There is currently no public API to reset the initialized state, so this is required
+     * to ensure the transport can be reused safely after a session is closed.
+     * If the SDK adds a public reset/init method, use that instead.
+     * If the SDK changes the field name or its semantics, update this code accordingly.
+     */
+    static resetStreamableHttpState(transport) {
+        transport.sessionId = undefined;
+        Reflect.set(transport, "_initialized", false);
+    }
+    /**
+     * Create a transport instance from configuration
+     *
+     * @param config - Transport configuration (stdio or streamable-http)
+     * @param logger - Optional logger for HTTP transport session events (ignored for stdio)
+     * @param sessionManager - Optional session manager for HTTP transport (ignored for stdio)
+     * @returns Result with Transport instance or Error
+     *
+     * @example
+     * ```typescript
+     * // Create stdio transport
+     * const stdioResult = TransportFactory.create({ type: 'stdio' });
+     *
+     * // Create HTTP transport with logger and session manager
+     * const httpResult = TransportFactory.create({
+     *   type: 'streamable-http',
+     *   port: 6280,
+     *   host: '127.0.0.1',
+     *   endpoint: '/mcp'
+     * }, logger, sessionManager);
+     * ```
+     */
+    static create(config, logger, sessionManager) {
+        // Validate configuration first
+        const validationResult = TransportConfigValidator.validate(config);
+        if (!validationResult.success) {
+            return validationResult;
+        }
+        const validatedConfig = validationResult.data;
+        // Dispatch to appropriate factory method based on type
+        if (isStreamableHttpTransportConfig(validatedConfig)) {
+            return TransportFactory.createStreamableHttp(validatedConfig, logger, sessionManager);
+        }
+        return TransportFactory.createStdio(validatedConfig);
+    }
+    /**
+     * Create a stdio transport instance
+     *
+     * @param _config - Stdio transport configuration (unused, kept for API consistency)
+     * @returns Result with StdioServerTransport instance
+     */
+    static createStdio(_config) {
+        try {
+            const transport = new StdioServerTransport();
+            return createSuccessResult(transport);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            return createErrorResult(new Error(`Failed to create stdio transport: ${err.message}`));
+        }
+    }
+    /**
+     * Create a streamable HTTP transport instance
+     *
+     * Creates a StreamableHTTPServerTransport with session management support.
+     * The transport instance is stateful and manages session lifecycle through callbacks.
+     *
+     * Note: DNS rebinding protection is handled by Express middleware (createMcpExpressApp)
+     * in the ExpressHttpManager, not by the transport itself.
+     *
+     * @param config - Streamable HTTP transport configuration
+     * @param logger - Optional logger for session lifecycle events
+     * @param sessionManager - Optional session manager for tracking sessions
+     * @returns Result with StreamableHTTPServerTransport instance or Error
+     *
+     * @example
+     * ```typescript
+     * const config: StreamableHttpTransportConfig = {
+     *   type: 'streamable-http',
+     *   port: 6280,
+     *   host: '127.0.0.1',
+     *   endpoint: '/mcp',
+     *   sessionConfig: { enabled: true }
+     * };
+     * const result = TransportFactory.createStreamableHttp(config, logger, sessionManager);
+     * ```
+     */
+    static createStreamableHttp(config, logger, sessionManager) {
+        try {
+            let transport = null;
+            let suppressCloseEvent = false;
+            const handleSessionClosed = config.sessionConfig?.enabled
+                ? (sessionId) => {
+                    if (logger) {
+                        logger.sendLog({
+                            data: `Session closed: ${sessionId}`,
+                            level: "info",
+                            logger: "TransportFactory",
+                        });
+                    }
+                    // Clean up session from SessionManager
+                    if (sessionManager) {
+                        sessionManager.cleanup(sessionId);
+                    }
+                    suppressCloseEvent = true;
+                    if (transport) {
+                        TransportFactory.resetStreamableHttpState(transport);
+                    }
+                }
+                : undefined;
+            // Create transport with session management only
+            // Security (DNS rebinding protection) is handled by Express middleware
+            transport = new StreamableHTTPServerTransport({
+                // Enable JSON responses for simple request/response scenarios
+                enableJsonResponse: false,
+                // Session close callback
+                // This is called when a session is terminated via DELETE request
+                onsessionclosed: handleSessionClosed,
+                // Session initialization callback
+                // This is called when a new session is created
+                onsessioninitialized: config.sessionConfig?.enabled
+                    ? (sessionId) => {
+                        if (logger) {
+                            logger.sendLog({
+                                data: `Session initialized: ${sessionId}`,
+                                level: "info",
+                                logger: "TransportFactory",
+                            });
+                        }
+                        // Register session with SessionManager
+                        if (sessionManager) {
+                            sessionManager.register(sessionId);
+                        }
+                    }
+                    : undefined,
+                // Retry interval for SSE polling behavior (optional)
+                retryInterval: config.retryInterval,
+                // Use randomUUID for session ID generation if sessions are enabled
+                sessionIdGenerator: config.sessionConfig?.enabled
+                    ? () => randomUUID()
+                    : undefined,
+            });
+            // Override the transport's close method to handle session cleanup scenarios.
+            //
+            // Why suppressCloseEvent is necessary:
+            // When a session is explicitly closed (via DELETE request), the SDK calls onsessionclosed
+            // which triggers our handleSessionClosed callback. We need to reset the transport state
+            // without triggering the onclose callback, which would signal a transport-level disconnection.
+            //
+            // Scenarios that trigger this code path:
+            // 1. Client sends DELETE request to close session → onsessionclosed fires → suppressCloseEvent = true
+            // 2. Session TTL expires → cleanup triggers close → suppressCloseEvent = true
+            //
+            // Relationship between suppressCloseEvent and handleSessionClosed:
+            // - handleSessionClosed sets suppressCloseEvent = true to indicate a session-level (not transport-level) close
+            // - When close() is called with suppressCloseEvent = true, we temporarily remove onclose callback
+            // - This prevents the MCP server from treating session cleanup as a transport disconnection
+            const originalClose = transport.close.bind(transport);
+            transport.close = (async () => {
+                if (suppressCloseEvent) {
+                    const previousOnClose = transport?.onclose;
+                    transport.onclose = undefined;
+                    try {
+                        await originalClose();
+                    }
+                    finally {
+                        transport.onclose = previousOnClose;
+                        suppressCloseEvent = false;
+                    }
+                    return;
+                }
+                await originalClose();
+            });
+            return createSuccessResult(transport);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            return createErrorResult(new Error(`Failed to create streamable HTTP transport: ${err.message}`));
+        }
+    }
+}

package/dist/transport/index.js

@@ -0,0 +1,12 @@
+/**
+ * Transport layer module exports
+ *
+ * This module provides type-safe configuration and validation for MCP transports:
+ * - stdio: Standard input/output transport
+ * - streamable-http: HTTP-based transport with SSE streaming
+ */
+export { DEFAULT_HTTP_CONFIG, DEFAULT_SESSION_CONFIG, isStdioTransportConfig, isStreamableHttpTransportConfig, TransportConfigSchema, } from "./config.js";
+export { ExpressHttpManager } from "./expressHttpManager.js";
+export { TransportFactory } from "./factory.js";
+export { SessionManager } from "./sessionManager.js";
+export { TransportConfigValidator } from "./validator.js";