touchdesigner-mcp-server 1.4.9 → 1.4.10

package/dist/transport/expressHttpManager.d.ts

@@ -0,0 +1,86 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ILogger } from "../core/logger.js";
+import type { Result } from "../core/result.js";
+import type { StreamableHttpTransportConfig } from "./config.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 declare class ExpressHttpManager {
+    private readonly config;
+    private readonly serverFactory;
+    private readonly logger;
+    private readonly registry;
+    private server;
+    /**
+     * 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: StreamableHttpTransportConfig, serverFactory: () => McpServer, sessionManager: import("./sessionManager.js").ISessionManager | null, logger: ILogger);
+    /**
+     * Start HTTP server with Express app from SDK
+     *
+     * @returns Result indicating success or failure
+     */
+    start(): Promise<Result<void, Error>>;
+    /**
+     * Graceful shutdown
+     *
+     * Stops HTTP server and cleans up all active sessions.
+     *
+     * @returns Result indicating success or failure
+     */
+    stop(): Promise<Result<void, Error>>;
+    /**
+     * Check if server is running
+     *
+     * @returns True if server is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get active session count
+     *
+     * @returns Number of active sessions
+     */
+    getActiveSessionCount(): number;
+    /**
+     * Get all active session IDs
+     *
+     * @returns Array of session IDs
+     */
+    getActiveSessionIds(): string[];
+}

package/dist/transport/factory.d.ts

@@ -0,0 +1,81 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { ILogger } from "../core/logger.js";
+import type { Result } from "../core/result.js";
+import type { TransportConfig } from "./config.js";
+import type { ISessionManager } from "./sessionManager.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 declare 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.
+     */
+    private static resetStreamableHttpState;
+    /**
+     * 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: TransportConfig, logger?: ILogger, sessionManager?: ISessionManager | null): Result<Transport, Error>;
+    /**
+     * Create a stdio transport instance
+     *
+     * @param _config - Stdio transport configuration (unused, kept for API consistency)
+     * @returns Result with StdioServerTransport instance
+     */
+    private static createStdio;
+    /**
+     * 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);
+     * ```
+     */
+    private static createStreamableHttp;
+}

package/dist/transport/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 type { SessionConfig, StdioTransportConfig, StreamableHttpTransportConfig, TransportConfig, TransportType, } from "./config.js";
+export { DEFAULT_HTTP_CONFIG, DEFAULT_SESSION_CONFIG, isStdioTransportConfig, isStreamableHttpTransportConfig, TransportConfigSchema, } from "./config.js";
+export { ExpressHttpManager } from "./expressHttpManager.js";
+export { TransportFactory } from "./factory.js";
+export type { ISessionManager, Session } from "./sessionManager.js";
+export { SessionManager } from "./sessionManager.js";
+export type { ValidationError } from "./validator.js";
+export { TransportConfigValidator } from "./validator.js";

package/dist/transport/sessionManager.d.ts

@@ -0,0 +1,180 @@
+import type { ILogger } from "../core/logger.js";
+import type { Result } from "../core/result.js";
+import type { SessionConfig } from "./config.js";
+/**
+ * Session metadata
+ */
+export interface Session {
+    /**
+     * Unique session identifier (UUID v4)
+     */
+    id: string;
+    /**
+     * Timestamp when session was created (milliseconds since epoch)
+     */
+    createdAt: number;
+    /**
+     * Timestamp when session was last accessed (milliseconds since epoch)
+     */
+    lastAccessedAt: number;
+    /**
+     * Optional metadata associated with the session
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Session manager interface
+ */
+export interface ISessionManager {
+    /**
+     * Create a new session with auto-generated ID
+     */
+    create(metadata?: Record<string, unknown>): string;
+    /**
+     * Refresh last access time for a session
+     */
+    touch(sessionId: string): Result<void, Error>;
+    /**
+     * Register a callback invoked when a session expires via TTL cleanup.
+     */
+    setExpirationHandler(handler: (sessionId: string) => Promise<void> | void): void;
+    /**
+     * Register an existing session (created by SDK)
+     */
+    register(sessionId: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Clean up a session by ID
+     */
+    cleanup(sessionId: string): Result<void, Error>;
+    /**
+     * List all active sessions
+     */
+    list(): Session[];
+    /**
+     * Start automatic TTL-based cleanup
+     */
+    startTTLCleanup(): void;
+    /**
+     * Stop automatic TTL-based cleanup
+     */
+    stopTTLCleanup(): void;
+    /**
+     * Get number of active sessions
+     */
+    getActiveSessionCount(): number;
+    /**
+     * Clear all sessions (for testing or emergency cleanup)
+     */
+    clearAll(): void;
+}
+/**
+ * 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 declare class SessionManager implements ISessionManager {
+    private readonly sessions;
+    private readonly config;
+    private readonly logger;
+    private cleanupInterval;
+    private onSessionExpired;
+    constructor(config: SessionConfig, logger: ILogger);
+    /**
+     * Create a new session with optional metadata
+     *
+     * @param metadata - Optional metadata to associate with the session
+     * @returns Session ID (UUID v4)
+     */
+    create(metadata?: Record<string, unknown>): string;
+    /**
+     * Update lastAccessedAt when a session receives activity
+     *
+     * @param sessionId - Session ID to refresh
+     */
+    touch(sessionId: string): Result<void, Error>;
+    /**
+     * Register a callback to run when TTL cleanup expires a session.
+     *
+     * @param handler - Callback invoked with expired session ID
+     */
+    setExpirationHandler(handler: (sessionId: string) => Promise<void> | void): void;
+    /**
+     * 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: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Clean up (delete) a session by ID
+     *
+     * @param sessionId - Session ID to clean up
+     * @returns Result indicating success or failure
+     */
+    cleanup(sessionId: string): Result<void, Error>;
+    /**
+     * List all active sessions
+     *
+     * @returns Array of all active sessions
+     */
+    list(): Session[];
+    /**
+     * 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(): void;
+    /**
+     * Stop automatic TTL-based cleanup
+     */
+    stopTTLCleanup(): void;
+    /**
+     * Run a single cleanup task to remove expired sessions
+     *
+     * @private
+     */
+    private runCleanupTask;
+    /**
+     * Get number of active sessions
+     *
+     * @returns Number of active sessions
+     */
+    getActiveSessionCount(): number;
+    /**
+     * Clear all sessions
+     *
+     * Useful for testing or emergency cleanup.
+     */
+    clearAll(): void;
+}

package/dist/transport/transportRegistry.d.ts

@@ -0,0 +1,92 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import type { ILogger } from "../core/logger.js";
+import type { Result } from "../core/result.js";
+import type { StreamableHttpTransportConfig } from "./config.js";
+import type { ISessionManager } from "./sessionManager.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 declare class TransportRegistry {
+    private readonly sessions;
+    private readonly config;
+    private readonly sessionManager;
+    private readonly logger;
+    constructor(config: StreamableHttpTransportConfig, sessionManager: ISessionManager | null, logger: ILogger);
+    /**
+     * 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
+     */
+    getOrCreate(sessionId: string | undefined, requestBody: JSONRPCMessage, serverFactory: () => McpServer): Promise<StreamableHTTPServerTransport | 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
+     */
+    private createSession;
+    /**
+     * Remove session from registry
+     *
+     * @param sessionId - Session ID to remove
+     */
+    remove(sessionId: string): void;
+    /**
+     * Get number of active sessions
+     *
+     * @returns Active session count
+     */
+    getCount(): number;
+    /**
+     * Get all session IDs
+     *
+     * @returns Array of session IDs
+     */
+    getSessionIds(): string[];
+    /**
+     * Cleanup all sessions
+     *
+     * Called during graceful shutdown to close all active sessions
+     *
+     * @returns Result indicating success or failure
+     */
+    cleanup(): Promise<Result<void, Error>>;
+}

package/dist/transport/validator.d.ts

@@ -0,0 +1,43 @@
+import type { Result } from "../core/result.js";
+import type { TransportConfig } from "./config.js";
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * Transport configuration validator using Zod schemas
+ */
+export declare class TransportConfigValidator {
+    /**
+     * Validate a transport configuration
+     *
+     * @param config - The configuration to validate
+     * @returns Result with validated config or validation errors
+     */
+    static validate(config: unknown): Result<TransportConfig, Error>;
+    /**
+     * Format Zod validation errors into structured ValidationError objects
+     *
+     * @param zodError - The Zod validation error
+     * @returns Array of structured validation errors
+     */
+    private static formatZodErrors;
+    /**
+     * Build a comprehensive error message from validation errors
+     *
+     * @param errors - Array of validation errors
+     * @returns Formatted error message
+     */
+    private static buildErrorMessage;
+    /**
+     * 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: unknown): Result<TransportConfig, Error>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "touchdesigner-mcp-server",
-	"version": "1.4.9",
+	"version": "1.4.10",
 	"description": "MCP server for TouchDesigner",
 	"repository": {
 		"type": "git",