touchdesigner-mcp-server 1.3.1 → 1.4.0

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";

package/dist/transport/sessionManager.js

@@ -0,0 +1,276 @@
+import { randomUUID } from "node:crypto";
+import { createErrorResult, createSuccessResult } from "../core/result.js";
+import { DEFAULT_SESSION_CONFIG } from "./config.js";
+/**
+ * Session Manager
+ *
+ * Manages client sessions for Streamable HTTP transport.
+ * Provides session creation, validation, TTL-based expiration, and automatic cleanup.
+ *
+ * Note: Session validation (checking if session ID exists) is now handled by
+ * StreamableHTTPServerTransport.handleRequest(). This SessionManager focuses on:
+ * - Session creation via SDK callbacks (onsessioninitialized)
+ * - Session cleanup via SDK callbacks (onsessionclosed) and TTL-based cleanup
+ * - Session tracking for health checks and monitoring
+ *
+ * @example
+ * ```typescript
+ * const sessionManager = new SessionManager(
+ *   { enabled: true, ttl: 60 * 60 * 1000 }, // 1 hour TTL
+ *   logger
+ * );
+ *
+ * // Create session (typically called from SDK callback)
+ * const sessionId = sessionManager.create({ clientVersion: '1.0' });
+ *
+ * // Start automatic TTL-based cleanup
+ * sessionManager.startTTLCleanup();
+ *
+ * // Stop cleanup when done
+ * sessionManager.stopTTLCleanup();
+ * ```
+ */
+export class SessionManager {
+    sessions = new Map();
+    config;
+    logger;
+    cleanupInterval = null;
+    onSessionExpired = null;
+    constructor(config, logger) {
+        // Apply defaults for optional values to ensure TTL cleanup is active by default
+        this.config = {
+            cleanupInterval: config.cleanupInterval ?? DEFAULT_SESSION_CONFIG.cleanupInterval,
+            enabled: config.enabled ?? DEFAULT_SESSION_CONFIG.enabled,
+            ttl: config.ttl ?? DEFAULT_SESSION_CONFIG.ttl,
+        };
+        this.logger = logger;
+    }
+    /**
+     * Create a new session with optional metadata
+     *
+     * @param metadata - Optional metadata to associate with the session
+     * @returns Session ID (UUID v4)
+     */
+    create(metadata) {
+        const sessionId = randomUUID();
+        const now = Date.now();
+        const session = {
+            createdAt: now,
+            id: sessionId,
+            lastAccessedAt: now,
+            metadata,
+        };
+        this.sessions.set(sessionId, session);
+        this.logger.sendLog({
+            data: `Session created: ${sessionId}${metadata ? ` (metadata: ${JSON.stringify(metadata)})` : ""}`,
+            level: "info",
+            logger: "SessionManager",
+        });
+        return sessionId;
+    }
+    /**
+     * Update lastAccessedAt when a session receives activity
+     *
+     * @param sessionId - Session ID to refresh
+     */
+    touch(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return createErrorResult(new Error(`Session not found: ${sessionId}`));
+        }
+        session.lastAccessedAt = Date.now();
+        return createSuccessResult(undefined);
+    }
+    /**
+     * Register a callback to run when TTL cleanup expires a session.
+     *
+     * @param handler - Callback invoked with expired session ID
+     */
+    setExpirationHandler(handler) {
+        this.onSessionExpired = handler;
+    }
+    /**
+     * Register an SDK-created session for tracking
+     *
+     * This method registers sessions that were created by the MCP SDK's
+     * StreamableHTTPServerTransport. The SDK generates session IDs via the
+     * sessionIdGenerator callback, and then calls onsessioninitialized.
+     * This method creates a new tracking entry with current timestamps
+     * so the session can be managed for TTL cleanup and monitoring.
+     *
+     * @param sessionId - Session ID generated by SDK
+     * @param metadata - Optional metadata to associate with the session
+     */
+    register(sessionId, metadata) {
+        const now = Date.now();
+        const session = {
+            createdAt: now,
+            id: sessionId,
+            lastAccessedAt: now,
+            metadata,
+        };
+        this.sessions.set(sessionId, session);
+        this.logger.sendLog({
+            data: `Session registered: ${sessionId}${metadata ? ` (metadata: ${JSON.stringify(metadata)})` : ""}`,
+            level: "info",
+            logger: "SessionManager",
+        });
+    }
+    /**
+     * Clean up (delete) a session by ID
+     *
+     * @param sessionId - Session ID to clean up
+     * @returns Result indicating success or failure
+     */
+    cleanup(sessionId) {
+        const existed = this.sessions.delete(sessionId);
+        if (existed) {
+            this.logger.sendLog({
+                data: `Session cleaned up: ${sessionId}`,
+                level: "info",
+                logger: "SessionManager",
+            });
+            return createSuccessResult(undefined);
+        }
+        return createErrorResult(new Error(`Session not found for cleanup: ${sessionId}`));
+    }
+    /**
+     * List all active sessions
+     *
+     * @returns Array of all active sessions
+     */
+    list() {
+        return Array.from(this.sessions.values());
+    }
+    /**
+     * Start automatic TTL-based cleanup
+     *
+     * Runs cleanup task at an interval of TTL/2 to remove expired sessions.
+     * Does nothing if TTL is not configured or cleanup is already running.
+     */
+    startTTLCleanup() {
+        // Don't start if TTL not configured or already running
+        if (!this.config.ttl || this.cleanupInterval) {
+            return;
+        }
+        const intervalMs = this.config.cleanupInterval || this.config.ttl / 2;
+        this.logger.sendLog({
+            data: `Starting TTL cleanup (interval: ${intervalMs}ms, TTL: ${this.config.ttl}ms)`,
+            level: "info",
+            logger: "SessionManager",
+        });
+        this.cleanupInterval = setInterval(() => {
+            try {
+                this.runCleanupTask();
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.logger.sendLog({
+                    data: `CRITICAL: TTL cleanup task failed: ${err.message}. Stack: ${err.stack}`,
+                    level: "error",
+                    logger: "SessionManager",
+                });
+            }
+        }, intervalMs);
+        // Don't keep the process alive just for cleanup
+        this.cleanupInterval.unref();
+    }
+    /**
+     * Stop automatic TTL-based cleanup
+     */
+    stopTTLCleanup() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+            this.logger.sendLog({
+                data: "Stopped TTL cleanup",
+                level: "info",
+                logger: "SessionManager",
+            });
+        }
+    }
+    /**
+     * Run a single cleanup task to remove expired sessions
+     *
+     * @private
+     */
+    runCleanupTask() {
+        const ttl = this.config.ttl;
+        if (!ttl) {
+            return;
+        }
+        const now = Date.now();
+        const expiredIds = [];
+        for (const [id, session] of this.sessions.entries()) {
+            try {
+                const elapsed = now - session.lastAccessedAt;
+                if (elapsed > ttl) {
+                    expiredIds.push(id);
+                }
+            }
+            catch (error) {
+                // Log individual session cleanup errors but continue processing others
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.logger.sendLog({
+                    data: `Error cleaning session ${id}: ${err.message}`,
+                    level: "error",
+                    logger: "SessionManager",
+                });
+            }
+        }
+        for (const sessionId of expiredIds) {
+            try {
+                const result = this.onSessionExpired?.(sessionId);
+                if (result && typeof result.catch === "function") {
+                    result.catch((error) => {
+                        const err = error instanceof Error ? error : new Error(String(error));
+                        this.logger.sendLog({
+                            data: `Error running expiration handler for ${sessionId}: ${err.message}`,
+                            level: "error",
+                            logger: "SessionManager",
+                        });
+                    });
+                }
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.logger.sendLog({
+                    data: `Error running expiration handler for ${sessionId}: ${err.message}`,
+                    level: "error",
+                    logger: "SessionManager",
+                });
+            }
+            // Ensure the session is removed from tracking even if handler fails
+            this.sessions.delete(sessionId);
+        }
+        if (expiredIds.length > 0) {
+            this.logger.sendLog({
+                data: `Cleanup completed: removed ${expiredIds.length} expired session(s): ${expiredIds.join(", ")}`,
+                level: "info",
+                logger: "SessionManager",
+            });
+        }
+    }
+    /**
+     * Get number of active sessions
+     *
+     * @returns Number of active sessions
+     */
+    getActiveSessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Clear all sessions
+     *
+     * Useful for testing or emergency cleanup.
+     */
+    clearAll() {
+        const count = this.sessions.size;
+        this.sessions.clear();
+        this.logger.sendLog({
+            data: `All sessions cleared: ${count} session(s) removed`,
+            level: "info",
+            logger: "SessionManager",
+        });
+    }
+}