touchdesigner-mcp-server 1.3.0 → 1.4.0

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

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.0",
+	"version": "1.4.0",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",
@@ -13,6 +13,9 @@
 	"author": "8beeeaaat",
 	"license": "MIT",
 	"mcpName": "io.github.8beeeaaat/touchdesigner-mcp-server",
+	"mcpCompatibility": {
+		"minApiVersion": "1.3.0"
+	},
 	"bugs": {
 		"url": "https://github.com/8beeeaaat/touchdesigner-mcp/issues"
 	},
@@ -23,31 +26,35 @@
 		"touchdesigner-mcp-server": "dist/cli.js"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.23.0",
+		"@modelcontextprotocol/sdk": "^1.24.3",
 		"@mozilla/readability": "^0.6.0",
 		"@types/axios": "^0.14.4",
 		"@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",
 		"zod": "4.1.13"
 	},
 	"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",
-		"@vitest/coverage-v8": "^4.0.14",
+		"@types/semver": "^7.7.1",
+		"@vitest/coverage-v8": "^4.0.15",
 		"archiver": "^7.0.1",
-		"msw": "^2.12.3",
+		"msw": "^2.12.4",
 		"npm-run-all": "^4.1.5",
 		"orval": "^7.17.0",
-		"prettier": "^3.7.3",
+		"prettier": "^3.7.4",
 		"shx": "^0.4.0",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.14"
+		"vitest": "^4.0.15"
 	},
 	"type": "module",
 	"exports": {
@@ -75,12 +82,15 @@
 		"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",
 		"coverage": "vitest run --coverage",
+		"version": "run-p version:*",
+		"version:api": "node ./scripts/syncApiServerVersions.ts",
+		"version:mcp": "node ./scripts/syncMcpServerVersions.ts",
 		"gen": "run-s gen:*",
-		"gen:version": "node ./scripts/syncVersions.ts",
 		"gen:webserver": "openapi-generator-cli generate -i ./src/api/index.yml -g python-flask -o ./td/modules/td_server",
 		"gen:handlers": "node td/genHandlers.js",
 		"gen:mcp": "orval --config ./orval.config.ts"