mcp-server-framework 1.0.0

package/build/server/session/session-factory.js

@@ -0,0 +1,131 @@
+/**
+ * MCP Session Factory
+ *
+ * Responsible for creating fully-configured MCP sessions with pre-computed
+ * capabilities and all registered primitives. Capabilities are computed once
+ * at construction time since the input data (tools, resources, prompts) is
+ * immutable after server build.
+ *
+ * Extracted from McpServerInstance to satisfy the Single Responsibility
+ * Principle — the server orchestrates lifecycle, the factory creates sessions.
+ *
+ * @module server/session/session-factory
+ */
+import { InMemoryTaskStore, InMemoryTaskMessageQueue, } from "@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js";
+import { buildCapabilities } from "../../mcp/capabilities/index.js";
+import { McpSession } from "./mcp-session.js";
+import { logger as frameworkLogger, mcpLogger } from "../../logger/index.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const LOG_COMPONENT = "session-factory";
+const SessionFactoryLogMessages = {
+    FACTORY_CREATED: "Session factory created: %s v%s (%d tools, %d resources, %d prompts)",
+    SESSION_CREATED: "New MCP session created",
+    SESSION_ERROR: "MCP session error:",
+};
+const logger = frameworkLogger.child({ component: LOG_COMPONENT });
+// ============================================================================
+// Session Factory Implementation
+// ============================================================================
+/**
+ * Creates fully-configured MCP sessions.
+ *
+ * Capabilities are pre-computed once in the constructor since the input
+ * data is immutable after server build. Each `create()` call produces
+ * a new McpSession with all primitives registered — ready for transport
+ * connection.
+ *
+ * @internal Created by McpServerBuilder — do not instantiate directly.
+ *
+ * @example
+ * ```typescript
+ * const factory = new McpSessionFactory({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   tools: frozenToolArray,
+ *   resources: frozenResourceArray,
+ *   resourceTemplates: frozenTemplateArray,
+ *   prompts: frozenPromptArray,
+ * });
+ *
+ * const session = factory.create(); // Ready for transport.connect()
+ * ```
+ */
+export class McpSessionFactory {
+    config;
+    /** Pre-computed SDK capabilities (immutable after construction) */
+    computedCapabilities;
+    /** Task store instance (shared across all sessions) */
+    taskStore;
+    /** Task message queue instance (shared across all sessions) */
+    taskMessageQueue;
+    constructor(config) {
+        this.config = config;
+        // Compute capabilities ONCE — input data is immutable
+        this.computedCapabilities = buildCapabilities(config.capabilities, config.tools, config.resources, config.resourceTemplates, config.prompts, config.taskTools);
+        // Auto-create InMemoryTaskStore when task tools exist but no store provided
+        this.taskStore = config.taskStore ?? (config.taskTools.length > 0 ? new InMemoryTaskStore() : undefined);
+        // Auto-create InMemoryTaskMessageQueue when task tools exist but no queue provided
+        this.taskMessageQueue =
+            config.taskMessageQueue ?? (config.taskTools.length > 0 ? new InMemoryTaskMessageQueue() : undefined);
+        logger.trace(SessionFactoryLogMessages.FACTORY_CREATED, config.name, config.version, config.tools.length, config.resources.length + config.resourceTemplates.length, config.prompts.length);
+    }
+    /**
+     * Creates a new MCP session with all registered primitives.
+     *
+     * Called once for stdio mode, or per-client for HTTP mode.
+     * Each session wraps one SDK McpServer (1:1 per MCP spec).
+     *
+     * Session lifecycle is managed by the SessionManager —
+     * this factory only creates and configures sessions.
+     */
+    create() {
+        const session = new McpSession({
+            name: this.config.name,
+            version: this.config.version,
+            capabilities: this.computedCapabilities,
+            handlers: this.config.handlers,
+            stateless: this.config.stateless,
+            ...(this.taskStore && { taskStore: this.taskStore }),
+            ...(this.taskMessageQueue && { taskMessageQueue: this.taskMessageQueue }),
+        });
+        // Log session errors (lifecycle managed by SessionManager, not here)
+        session.onError((error) => {
+            logger.error(SessionFactoryLogMessages.SESSION_ERROR, error);
+        });
+        // Register all MCP primitives directly on the session
+        session.registerTools(this.config.tools);
+        session.registerResources(this.config.resources, this.config.resourceTemplates);
+        session.registerPrompts(this.config.prompts);
+        session.registerTaskTools(this.config.taskTools);
+        // Register subscription handlers when resources.subscribe capability is enabled
+        // and session is stateful (subscriptions require persistent sessions)
+        const resourceCaps = this.computedCapabilities.resources;
+        const hasSubscribe = typeof resourceCaps === "object" &&
+            resourceCaps !== null &&
+            "subscribe" in resourceCaps &&
+            // @type-narrowing — runtime checks above validate resourceCaps is a non-null object with 'subscribe'
+            resourceCaps.subscribe === true;
+        if (hasSubscribe && !this.config.stateless) {
+            session.registerSubscriptionHandlers();
+        }
+        // Register logging/setLevel handler when logging capability is enabled
+        const hasLogging = "logging" in this.computedCapabilities && this.computedCapabilities.logging != null;
+        if (hasLogging) {
+            session.registerSetLevelHandler((level) => mcpLogger.setMinLevel(level));
+        }
+        // Install scope-filtered list handlers (opt-in via auth.scopeFilterCapabilities)
+        if (this.config.scopeFilterCapabilities) {
+            session.registerScopeFilteredListHandlers({
+                tools: this.config.tools,
+                resources: this.config.resources,
+                templates: this.config.resourceTemplates,
+                prompts: this.config.prompts,
+            });
+        }
+        logger.debug(SessionFactoryLogMessages.SESSION_CREATED);
+        return session;
+    }
+}
+//# sourceMappingURL=session-factory.js.map

package/build/server/session/session-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-factory.js","sourceRoot":"","sources":["../../../src/server/session/session-factory.ts"],"names":[],"mappings":"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"}

package/build/server/session/session-housekeeper.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Session Housekeeper
+ *
+ * Background task manager for session maintenance.
+ * Handles periodic cleanup of expired sessions and heartbeat monitoring.
+ *
+ * Contains NO CRUD logic — session operations are delegated to SessionStore.
+ *
+ * @module server/session/session-housekeeper
+ */
+import type { SessionCloseReason } from "./session.js";
+import type { SessionStore } from "./session-store.js";
+/**
+ * Callback for the Housekeeper to request session closure.
+ * Implemented by SessionManager which owns the full teardown lifecycle.
+ * Returns void or Promise<void> to support async teardown.
+ */
+export type CloseSessionCallback = (sessionId: string, reason: SessionCloseReason) => void | Promise<void>;
+/**
+ * Configuration for the session housekeeper.
+ */
+export interface HousekeeperConfig {
+    /** Session timeout in milliseconds (default: 30 minutes) */
+    readonly timeoutMs: number;
+    /** Cleanup interval in milliseconds (0 = disabled) */
+    readonly cleanupIntervalMs: number;
+    /** Keep-alive interval in milliseconds (0 = disabled) */
+    readonly keepAliveIntervalMs: number;
+    /** Max missed heartbeats before disconnect (default: 3) */
+    readonly maxMissedHeartbeats: number;
+}
+/**
+ * Manages periodic background tasks for session maintenance.
+ *
+ * Responsibilities:
+ * - Cleanup expired (idle) sessions at regular intervals
+ * - Send heartbeats and remove dead connections
+ *
+ * Timers are configured at construction and use `.unref()` to
+ * not prevent Node.js process exit.
+ *
+ * For stdio mode, pass `cleanupIntervalMs: 0` and `keepAliveIntervalMs: 0`
+ * to disable all background tasks.
+ *
+ * @example
+ * ```typescript
+ * const housekeeper = new SessionHousekeeper(store, {
+ *   timeoutMs: 30 * 60_000,
+ *   cleanupIntervalMs: 60_000,
+ *   keepAliveIntervalMs: 30_000,
+ *   maxMissedHeartbeats: 3,
+ * });
+ *
+ * // Later during shutdown:
+ * housekeeper.dispose();
+ * ```
+ */
+export declare class SessionHousekeeper {
+    private readonly store;
+    private readonly config;
+    private readonly onCloseSession;
+    /** Cleanup interval timer */
+    private cleanupInterval;
+    /** Keep-alive interval timer */
+    private keepAliveInterval;
+    /** Whether the housekeeper is stopped */
+    private disposed;
+    constructor(store: SessionStore, config: HousekeeperConfig, onCloseSession: CloseSessionCallback);
+    /**
+     * Stops all background timers and marks as disposed.
+     */
+    dispose(): void;
+    /**
+     * Starts cleanup and heartbeat interval timers.
+     *
+     * Timers are only started when the corresponding interval is > 0.
+     * This allows stdio mode to skip background tasks entirely.
+     * Timers use .unref() to not prevent Node.js process exit.
+     */
+    private startTimers;
+    /**
+     * Runs a cleanup cycle to remove expired sessions.
+     *
+     * Iterates all sessions and closes those that have been idle
+     * longer than the configured timeout.
+     */
+    private runCleanupCycle;
+    /**
+     * Runs a heartbeat cycle to check connection health.
+     *
+     * Sends heartbeats to all sessions with heartbeat-capable transports.
+     * Sessions that exceed the maximum missed heartbeats are closed.
+     *
+     * NOTE: Heartbeat state mutations (missedCount, lastSuccessAt) are synchronous
+     * within the forEach callback — no async gap between read and write.
+     * This is safe in Node.js single-threaded event loop.
+     */
+    private runHeartbeatCycle;
+}
+//# sourceMappingURL=session-housekeeper.d.ts.map

package/build/server/session/session-housekeeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-housekeeper.d.ts","sourceRoot":"","sources":["../../../src/server/session/session-housekeeper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAM3G;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,sDAAsD;IACtD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAEnC,yDAAyD;IACzD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAErC,2DAA2D;IAC3D,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,kBAAkB;IAW3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAZjC,6BAA6B;IAC7B,OAAO,CAAC,eAAe,CAA+B;IAEtD,gCAAgC;IAChC,OAAO,CAAC,iBAAiB,CAA+B;IAExD,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAS;gBAGN,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,iBAAiB,EACzB,cAAc,EAAE,oBAAoB;IAYvD;;OAEG;IACH,OAAO,IAAI,IAAI;IAuBf;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAoBnB;;;;;OAKG;YACW,eAAe;IAyC7B;;;;;;;;;OASG;YACW,iBAAiB;CA+DhC"}

package/build/server/session/session-housekeeper.js

@@ -0,0 +1,217 @@
+/**
+ * Session Housekeeper
+ *
+ * Background task manager for session maintenance.
+ * Handles periodic cleanup of expired sessions and heartbeat monitoring.
+ *
+ * Contains NO CRUD logic — session operations are delegated to SessionStore.
+ *
+ * @module server/session/session-housekeeper
+ */
+import { logger as baseLogger } from "../../logger/index.js";
+import { isHeartbeatCapable } from "../transport/transport-context.js";
+import { SESSION_STATES, SESSION_CLOSE_REASONS } from "./session.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const LOG_COMPONENT = "session-housekeeper";
+const LogMessages = {
+    STARTED: "Housekeeper started (timeout=%dmin, cleanup=%ds, heartbeat=%ds)",
+    SESSION_EXPIRED: "Session expired: %s (idle=%dms)",
+    SESSION_HEARTBEAT_FAILED: "Session heartbeat failed: %s (missed=%d)",
+    SESSION_CLOSE_ERROR: "Error closing session %s during %s: %s",
+    CLEANUP_CYCLE: "Cleanup cycle: expired=%d remaining=%d",
+    HEARTBEAT_CYCLE: "Heartbeat cycle: success=%d failed=%d removed=%d",
+    DISPOSED: "Housekeeper disposed",
+};
+const logger = baseLogger.child({ component: LOG_COMPONENT });
+// ============================================================================
+// Session Housekeeper
+// ============================================================================
+/**
+ * Manages periodic background tasks for session maintenance.
+ *
+ * Responsibilities:
+ * - Cleanup expired (idle) sessions at regular intervals
+ * - Send heartbeats and remove dead connections
+ *
+ * Timers are configured at construction and use `.unref()` to
+ * not prevent Node.js process exit.
+ *
+ * For stdio mode, pass `cleanupIntervalMs: 0` and `keepAliveIntervalMs: 0`
+ * to disable all background tasks.
+ *
+ * @example
+ * ```typescript
+ * const housekeeper = new SessionHousekeeper(store, {
+ *   timeoutMs: 30 * 60_000,
+ *   cleanupIntervalMs: 60_000,
+ *   keepAliveIntervalMs: 30_000,
+ *   maxMissedHeartbeats: 3,
+ * });
+ *
+ * // Later during shutdown:
+ * housekeeper.dispose();
+ * ```
+ */
+export class SessionHousekeeper {
+    store;
+    config;
+    onCloseSession;
+    /** Cleanup interval timer */
+    cleanupInterval = null;
+    /** Keep-alive interval timer */
+    keepAliveInterval = null;
+    /** Whether the housekeeper is stopped */
+    disposed = false;
+    constructor(store, config, onCloseSession) {
+        this.store = store;
+        this.config = config;
+        this.onCloseSession = onCloseSession;
+        this.startTimers();
+        logger.trace(LogMessages.STARTED, Math.round(this.config.timeoutMs / 60000), Math.round(this.config.cleanupIntervalMs / 1000), Math.round(this.config.keepAliveIntervalMs / 1000));
+    }
+    /**
+     * Stops all background timers and marks as disposed.
+     */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        if (this.keepAliveInterval) {
+            clearInterval(this.keepAliveInterval);
+            this.keepAliveInterval = null;
+        }
+        logger.trace(LogMessages.DISPOSED);
+    }
+    // ==========================================================================
+    // Timer Management
+    // ==========================================================================
+    /**
+     * Starts cleanup and heartbeat interval timers.
+     *
+     * Timers are only started when the corresponding interval is > 0.
+     * This allows stdio mode to skip background tasks entirely.
+     * Timers use .unref() to not prevent Node.js process exit.
+     */
+    startTimers() {
+        if (this.config.cleanupIntervalMs > 0) {
+            this.cleanupInterval = setInterval(() => {
+                void this.runCleanupCycle();
+            }, this.config.cleanupIntervalMs);
+            this.cleanupInterval.unref();
+        }
+        if (this.config.keepAliveIntervalMs > 0) {
+            this.keepAliveInterval = setInterval(() => {
+                void this.runHeartbeatCycle();
+            }, this.config.keepAliveIntervalMs);
+            this.keepAliveInterval.unref();
+        }
+    }
+    // ==========================================================================
+    // Cleanup Cycle
+    // ==========================================================================
+    /**
+     * Runs a cleanup cycle to remove expired sessions.
+     *
+     * Iterates all sessions and closes those that have been idle
+     * longer than the configured timeout.
+     */
+    async runCleanupCycle() {
+        if (this.disposed) {
+            return;
+        }
+        const now = Date.now();
+        const expiredIds = [];
+        this.store.forEach((session) => {
+            if (session.state !== SESSION_STATES.ACTIVE) {
+                return;
+            }
+            const idleTime = now - session.metadata.lastActivityAt.getTime();
+            if (idleTime > this.config.timeoutMs) {
+                expiredIds.push(session.id);
+                logger.debug(LogMessages.SESSION_EXPIRED, session.id, idleTime);
+            }
+        });
+        const results = await Promise.allSettled(expiredIds.map((sessionId) => Promise.resolve(this.onCloseSession(sessionId, SESSION_CLOSE_REASONS.TIMEOUT))));
+        for (let i = 0; i < results.length; i++) {
+            if (results[i]?.status === "rejected") {
+                // @ts-limitation — TS narrows status to 'rejected' but not the union discriminant on results[i]
+                const reason = results[i].reason;
+                logger.warn(LogMessages.SESSION_CLOSE_ERROR, expiredIds[i], "cleanup", String(reason));
+            }
+        }
+        if (expiredIds.length > 0) {
+            logger.trace(LogMessages.CLEANUP_CYCLE, expiredIds.length, this.store.size);
+        }
+    }
+    // ==========================================================================
+    // Heartbeat Cycle
+    // ==========================================================================
+    /**
+     * Runs a heartbeat cycle to check connection health.
+     *
+     * Sends heartbeats to all sessions with heartbeat-capable transports.
+     * Sessions that exceed the maximum missed heartbeats are closed.
+     *
+     * NOTE: Heartbeat state mutations (missedCount, lastSuccessAt) are synchronous
+     * within the forEach callback — no async gap between read and write.
+     * This is safe in Node.js single-threaded event loop.
+     */
+    async runHeartbeatCycle() {
+        if (this.disposed) {
+            return;
+        }
+        let successCount = 0;
+        let failedCount = 0;
+        const toRemove = [];
+        this.store.forEach((session) => {
+            if (session.state !== SESSION_STATES.ACTIVE) {
+                return;
+            }
+            const transport = session.transport.instance;
+            if (!isHeartbeatCapable(transport)) {
+                return;
+            }
+            const success = transport.sendHeartbeat();
+            if (success) {
+                successCount++;
+                session.metadata.lastActivityAt = new Date();
+                session.transport.heartbeat = {
+                    ...session.transport.heartbeat,
+                    missedCount: 0,
+                    lastSuccessAt: new Date(),
+                };
+            }
+            else {
+                failedCount++;
+                const newMissedCount = session.transport.heartbeat.missedCount + 1;
+                session.transport.heartbeat = {
+                    ...session.transport.heartbeat,
+                    missedCount: newMissedCount,
+                };
+                if (newMissedCount >= this.config.maxMissedHeartbeats) {
+                    toRemove.push(session.id);
+                    logger.debug(LogMessages.SESSION_HEARTBEAT_FAILED, session.id, newMissedCount);
+                }
+            }
+        });
+        const results = await Promise.allSettled(toRemove.map((sessionId) => Promise.resolve(this.onCloseSession(sessionId, SESSION_CLOSE_REASONS.HEARTBEAT_FAILURE))));
+        for (let i = 0; i < results.length; i++) {
+            if (results[i]?.status === "rejected") {
+                // @ts-limitation — TS narrows status to 'rejected' but not the union discriminant on results[i]
+                const reason = results[i].reason;
+                logger.warn(LogMessages.SESSION_CLOSE_ERROR, toRemove[i], "heartbeat", String(reason));
+            }
+        }
+        if (successCount > 0 || failedCount > 0) {
+            logger.trace(LogMessages.HEARTBEAT_CYCLE, successCount, failedCount, toRemove.length);
+        }
+    }
+}
+//# sourceMappingURL=session-housekeeper.js.map

package/build/server/session/session-housekeeper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-housekeeper.js","sourceRoot":"","sources":["../../../src/server/session/session-housekeeper.ts"],"names":[],"mappings":"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"}