mcp-server-framework 1.0.0

package/build/server/routes/oauth-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-router.js","sourceRoot":"","sources":["../../../src/server/routes/oauth-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,aAAa,EAA0B,MAAM,iDAAiD,CAAC;AAExG,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE7D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,MAAM,aAAa,GAAG,cAAc,CAAC;AAErC,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE,mCAAmC;CACpC,CAAC;AAEX,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;AA0B9D,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IAEzD,MAAM,aAAa,GAAsB;QACvC,QAAQ;QACR,SAAS;QACT,GAAG,CAAC,eAAe,IAAI,EAAE,eAAe,EAAE,CAAC,GAAG,eAAe,CAAC,EAAE,CAAC;KAClE,CAAC;IAEF,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEvD,OAAO,aAAa,CAAC,aAAa,CAAC,CAAC;AACtC,CAAC"}

package/build/server/routes/readiness-status.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Readiness Status Constants
+ *
+ * Extracted from health.ts to avoid loading Express when only the
+ * ReadinessStatus constant is needed. This module has zero dependencies
+ * and can be safely imported from any barrel without triggering
+ * Express module evaluation.
+ *
+ * @module server/routes/readiness-status
+ */
+/**
+ * Readiness status codes returned by the /ready endpoint.
+ *
+ * Used by container orchestration (Kubernetes, Docker Swarm, Docker Compose)
+ * for readiness probes.
+ *
+ * @see {@link createHealthRouter} for the route implementation
+ */
+export declare const ReadinessStatus: {
+    readonly READY: 200;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly TOO_MANY_REQUESTS: 429;
+};
+export type ReadinessStatusValue = (typeof ReadinessStatus)[keyof typeof ReadinessStatus];
+//# sourceMappingURL=readiness-status.d.ts.map

package/build/server/routes/readiness-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness-status.d.ts","sourceRoot":"","sources":["../../../src/server/routes/readiness-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC"}

package/build/server/routes/readiness-status.js

@@ -0,0 +1,27 @@
+/**
+ * Readiness Status Constants
+ *
+ * Extracted from health.ts to avoid loading Express when only the
+ * ReadinessStatus constant is needed. This module has zero dependencies
+ * and can be safely imported from any barrel without triggering
+ * Express module evaluation.
+ *
+ * @module server/routes/readiness-status
+ */
+// ============================================================================
+// Readiness Status
+// ============================================================================
+/**
+ * Readiness status codes returned by the /ready endpoint.
+ *
+ * Used by container orchestration (Kubernetes, Docker Swarm, Docker Compose)
+ * for readiness probes.
+ *
+ * @see {@link createHealthRouter} for the route implementation
+ */
+export const ReadinessStatus = {
+    READY: 200,
+    SERVICE_UNAVAILABLE: 503,
+    TOO_MANY_REQUESTS: 429,
+};
+//# sourceMappingURL=readiness-status.js.map

package/build/server/routes/readiness-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness-status.js","sourceRoot":"","sources":["../../../src/server/routes/readiness-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,KAAK,EAAE,GAAG;IACV,mBAAmB,EAAE,GAAG;IACxB,iBAAiB,EAAE,GAAG;CACd,CAAC"}

package/build/server/routes/sse-router.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SSE Transport Router
+ *
+ * Thin routing layer for the legacy HTTP+SSE transport (deprecated protocol 2024-11-05).
+ * All session management and message handling is delegated to the SseRequestHandler.
+ *
+ * Endpoints:
+ * - GET /sse → Opens SSE stream, sends endpoint event with message URL
+ * - POST /message?sessionId=xxx → Receives JSON-RPC messages
+ * - POST /mcp/message?sessionId=xxx → Alternative message endpoint (for /mcp SSE)
+ *
+ * @module server/routes/sse-router
+ */
+import { Router } from "express";
+import type { SessionFactory } from "../transport/types.js";
+import type { SessionManager } from "../session/index.js";
+/**
+ * Check if legacy SSE transport is enabled.
+ *
+ * Reads from the cached framework config (`MCP_LEGACY_SSE_ENABLED`).
+ *
+ * @returns true if SSE transport is enabled
+ */
+export declare function isSseEnabled(): boolean;
+/**
+ * Get the number of active SSE sessions from the session manager.
+ *
+ * @param sessionManager - Unified session manager
+ * @returns Number of active SSE sessions
+ */
+export declare function getSseSessionCount(sessionManager: SessionManager): number;
+/**
+ * Creates the SSE Router (deprecated HTTP+SSE transport from protocol 2024-11-05).
+ *
+ * The router is intentionally thin — all session management and
+ * message handling is delegated to the SseRequestHandler.
+ *
+ * @param sessionFactory - Factory to create McpSession instances
+ * @param sessionManager - Session manager for tracking active sessions
+ * @returns Express Router with SSE endpoints
+ */
+export declare function createSseRouter(sessionFactory: SessionFactory, sessionManager: SessionManager): Router;
+//# sourceMappingURL=sse-router.d.ts.map

package/build/server/routes/sse-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-router.d.ts","sourceRoot":"","sources":["../../../src/server/routes/sse-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAA+B,MAAM,SAAS,CAAC;AAK9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAc1D;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,cAAc,GAAG,MAAM,CAEzE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,GAAG,MAAM,CAqCtG"}

package/build/server/routes/sse-router.js

@@ -0,0 +1,92 @@
+/**
+ * SSE Transport Router
+ *
+ * Thin routing layer for the legacy HTTP+SSE transport (deprecated protocol 2024-11-05).
+ * All session management and message handling is delegated to the SseRequestHandler.
+ *
+ * Endpoints:
+ * - GET /sse → Opens SSE stream, sends endpoint event with message URL
+ * - POST /message?sessionId=xxx → Receives JSON-RPC messages
+ * - POST /mcp/message?sessionId=xxx → Alternative message endpoint (for /mcp SSE)
+ *
+ * @module server/routes/sse-router
+ */
+import { Router } from "express";
+import { SseRequestHandler } from "../transport/sse/handler.js";
+import { createJsonRpcError, JsonRpcErrorCode, HttpStatus, TransportErrorMessage } from "../../errors/index.js";
+import { getFrameworkConfig } from "../../config/index.js";
+import { logger as baseLogger } from "../../logger/index.js";
+import { TRANSPORT_LOG_COMPONENTS, TRANSPORT_ROUTES } from "../transport/constants.js";
+const logger = baseLogger.child({ component: TRANSPORT_LOG_COMPONENTS.SSE });
+/** @internal Log messages for SSE router */
+const LogMessages = {
+    TRANSPORT_ENABLED: "SSE transport enabled (deprecated protocol 2024-11-05)",
+    CLIENT_CONNECTING: "SSE client connecting via /sse from %s",
+};
+// ============================================================================
+// SSE Config Helpers
+// ============================================================================
+/**
+ * Check if legacy SSE transport is enabled.
+ *
+ * Reads from the cached framework config (`MCP_LEGACY_SSE_ENABLED`).
+ *
+ * @returns true if SSE transport is enabled
+ */
+export function isSseEnabled() {
+    return getFrameworkConfig().MCP_LEGACY_SSE_ENABLED;
+}
+/**
+ * Get the number of active SSE sessions from the session manager.
+ *
+ * @param sessionManager - Unified session manager
+ * @returns Number of active SSE sessions
+ */
+export function getSseSessionCount(sessionManager) {
+    return sessionManager.getByTransportType("sse").length;
+}
+// ============================================================================
+// SSE Router Factory
+// ============================================================================
+/**
+ * Creates the SSE Router (deprecated HTTP+SSE transport from protocol 2024-11-05).
+ *
+ * The router is intentionally thin — all session management and
+ * message handling is delegated to the SseRequestHandler.
+ *
+ * @param sessionFactory - Factory to create McpSession instances
+ * @param sessionManager - Session manager for tracking active sessions
+ * @returns Express Router with SSE endpoints
+ */
+export function createSseRouter(sessionFactory, sessionManager) {
+    const router = Router();
+    const config = getFrameworkConfig();
+    if (!config.MCP_LEGACY_SSE_ENABLED) {
+        // Return router with endpoints that indicate feature is disabled
+        const disabledHandler = (_req, res) => {
+            res
+                .status(HttpStatus.NOT_IMPLEMENTED)
+                .json(createJsonRpcError(JsonRpcErrorCode.SERVER_ERROR, TransportErrorMessage.SSE_DISABLED));
+        };
+        router.get(TRANSPORT_ROUTES.SSE, disabledHandler);
+        router.post(TRANSPORT_ROUTES.SSE_MESSAGE, disabledHandler);
+        router.post(TRANSPORT_ROUTES.MCP_MESSAGE, disabledHandler);
+        return router;
+    }
+    logger.info(LogMessages.TRANSPORT_ENABLED);
+    const handler = new SseRequestHandler(sessionFactory, sessionManager);
+    /* v8 ignore start - SSE routes require real SSE transport */
+    router.get(TRANSPORT_ROUTES.SSE, async (req, res) => {
+        logger.info(LogMessages.CLIENT_CONNECTING, req.ip || "unknown");
+        await handler.handleConnection(req, res, TRANSPORT_ROUTES.SSE_MESSAGE);
+    });
+    router.post(TRANSPORT_ROUTES.SSE_MESSAGE, async (req, res) => {
+        await handler.handleMessage(req, res, TRANSPORT_ROUTES.SSE_MESSAGE);
+    });
+    /* v8 ignore stop */
+    router.post(TRANSPORT_ROUTES.MCP_MESSAGE, async (req, res) => {
+        await handler.handleMessage(req, res, TRANSPORT_ROUTES.MCP_MESSAGE);
+    });
+    return router;
+}
+//# sourceMappingURL=sse-router.js.map

package/build/server/routes/sse-router.js.map

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

package/build/server/routes/streamable-http-router.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Streamable HTTP Express Router
+ *
+ * Thin routing layer that delegates all MCP protocol handling to the SDK
+ * via the StreamableHttpTransport.
+ *
+ * Responsibilities:
+ * - Express routing (POST/GET/DELETE /mcp)
+ * - Method rejection (405 for unsupported methods)
+ *
+ * Protocol handling (JSON-RPC, sessions, SSE) is fully delegated
+ * to the StreamableHttpTransport → SDK StreamableHTTPServerTransport chain.
+ *
+ * Security middleware (DNS rebinding, rate limiting, protocol version)
+ * is applied at the Express app level BEFORE this router.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+ * @module server/routes/streamable-http-router
+ */
+import { Router } from "express";
+import { type StreamableHttpTransportOptions } from "../transport/streamable-http/transport.js";
+import type { SessionManager } from "../session/index.js";
+import type { SessionFactory } from "../transport/types.js";
+/**
+ * Creates the MCP Streamable HTTP router.
+ *
+ * The router is intentionally thin — all protocol logic lives in
+ * the SDK transport, managed by the StreamableHttpTransport.
+ *
+ * @param sessionFactory - Factory to create McpSession instances
+ * @param sessionManager - Session manager for tracking active sessions
+ * @param options - Transport options (stateless mode, etc.)
+ * @returns Express Router to be mounted at /mcp
+ */
+export declare function createStreamableHttpRouter(sessionFactory: SessionFactory, sessionManager: SessionManager, options?: StreamableHttpTransportOptions): Router;
+//# sourceMappingURL=streamable-http-router.d.ts.map

package/build/server/routes/streamable-http-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamable-http-router.d.ts","sourceRoot":"","sources":["../../../src/server/routes/streamable-http-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAA+B,MAAM,SAAS,CAAC;AAC9D,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,2CAA2C,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAO5D;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,cAAc,EAC9B,OAAO,CAAC,EAAE,8BAA8B,GACvC,MAAM,CA0BR"}

package/build/server/routes/streamable-http-router.js

@@ -0,0 +1,59 @@
+/**
+ * Streamable HTTP Express Router
+ *
+ * Thin routing layer that delegates all MCP protocol handling to the SDK
+ * via the StreamableHttpTransport.
+ *
+ * Responsibilities:
+ * - Express routing (POST/GET/DELETE /mcp)
+ * - Method rejection (405 for unsupported methods)
+ *
+ * Protocol handling (JSON-RPC, sessions, SSE) is fully delegated
+ * to the StreamableHttpTransport → SDK StreamableHTTPServerTransport chain.
+ *
+ * Security middleware (DNS rebinding, rate limiting, protocol version)
+ * is applied at the Express app level BEFORE this router.
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+ * @module server/routes/streamable-http-router
+ */
+import { Router } from "express";
+import { StreamableHttpTransport, } from "../transport/streamable-http/transport.js";
+import { createJsonRpcError, JsonRpcErrorCode, HttpStatus } from "../../errors/index.js";
+// ============================================================================
+// Router Factory
+// ============================================================================
+/**
+ * Creates the MCP Streamable HTTP router.
+ *
+ * The router is intentionally thin — all protocol logic lives in
+ * the SDK transport, managed by the StreamableHttpTransport.
+ *
+ * @param sessionFactory - Factory to create McpSession instances
+ * @param sessionManager - Session manager for tracking active sessions
+ * @param options - Transport options (stateless mode, etc.)
+ * @returns Express Router to be mounted at /mcp
+ */
+export function createStreamableHttpRouter(sessionFactory, sessionManager, options) {
+    const handler = new StreamableHttpTransport(sessionFactory, sessionManager, options);
+    const router = Router();
+    // All MCP protocol traffic is delegated to the SDK via the handler.
+    // Express 5 catches rejected promises from async route handlers automatically.
+    router.post("/", async (req, res) => {
+        await handler.handleRequest(req, res);
+    });
+    router.get("/", async (req, res) => {
+        await handler.handleRequest(req, res);
+    });
+    router.delete("/", async (req, res) => {
+        await handler.handleRequest(req, res);
+    });
+    // Reject unsupported methods
+    router.all("/", (_req, res) => {
+        res
+            .status(HttpStatus.METHOD_NOT_ALLOWED)
+            .json(createJsonRpcError(JsonRpcErrorCode.METHOD_NOT_FOUND, "Method not allowed"));
+    });
+    return router;
+}
+//# sourceMappingURL=streamable-http-router.js.map

package/build/server/routes/streamable-http-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamable-http-router.js","sourceRoot":"","sources":["../../../src/server/routes/streamable-http-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAA+B,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,uBAAuB,GAExB,MAAM,2CAA2C,CAAC;AAGnD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEzF,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CACxC,cAA8B,EAC9B,cAA8B,EAC9B,OAAwC;IAExC,MAAM,OAAO,GAAG,IAAI,uBAAuB,CAAC,cAAc,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;IACrF,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IAExB,oEAAoE;IACpE,+EAA+E;IAC/E,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QACrD,MAAM,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QACpD,MAAM,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QACvD,MAAM,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,6BAA6B;IAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAa,EAAE,GAAa,EAAE,EAAE;QAC/C,GAAG;aACA,MAAM,CAAC,UAAU,CAAC,kBAAkB,CAAC;aACrC,IAAI,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,CAAC,CAAC;IACvF,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/build/server/server-instance.d.ts

@@ -0,0 +1,185 @@
+/**
+ * MCP Server Instance
+ *
+ * The central framework object. Runtime implementation of the ServerInstance
+ * interface. Manages the MCP server lifecycle including transport selection,
+ * session management, signal handling, and graceful shutdown.
+ *
+ * Each connected client gets its own McpSession (1:1 per MCP SDK spec).
+ * Session creation is delegated to McpSessionFactory (SRP).
+ * Cancellation and progress are handled natively by the SDK.
+ *
+ * This class is created by McpServerBuilder and should not be
+ * instantiated directly by application code.
+ *
+ * @module server/server-instance
+ */
+import type { ServerOptions, ServerInstance } from "./server-options.js";
+import type { McpSessionFactory } from "./session/session-factory.js";
+/**
+ * The central MCP server framework object.
+ *
+ * Manages the MCP server lifecycle including:
+ * - Multi-session support (one McpSession per client in HTTP mode)
+ * - Transport selection (stdio/http/https)
+ * - Signal handling with graceful shutdown
+ *
+ * Session creation is delegated to {@link McpSessionFactory}.
+ *
+ * @internal Created by McpServerBuilder — do not instantiate directly.
+ */
+export declare class McpServerInstance implements ServerInstance {
+    private readonly options;
+    private readonly sessionFactory;
+    private serverState;
+    /** Whether telemetry has been initialized */
+    private telemetryInitialized;
+    /** Resolved transport mode, cached at construction time */
+    private readonly transportMode;
+    /** Unified session manager — single source of truth for all sessions */
+    private sessionManager?;
+    /** Transport handle for shutdown and info queries */
+    private transportHandle?;
+    /** Stored signal handler references for cleanup on stop/restart */
+    private signalHandlers;
+    /** Stored process error handler references for cleanup on stop/restart */
+    private processErrorHandlers;
+    /** Guard against concurrent shutdown from multiple error sources */
+    private shutdownInProgress;
+    constructor(options: ServerOptions, sessionFactory: McpSessionFactory);
+    get name(): string;
+    get version(): string;
+    get isRunning(): boolean;
+    /**
+     * Notify all connected MCP clients that the tool list has changed.
+     *
+     * Call this when external connection state changes affect tool availability.
+     * Delegates to the unified SessionManager which handles all transport types.
+     */
+    notifyToolListChanged(): void;
+    /**
+     * Notify all connected MCP clients that the resource list has changed.
+     */
+    notifyResourceListChanged(): void;
+    /**
+     * Notify all connected MCP clients that the prompt list has changed.
+     */
+    notifyPromptListChanged(): void;
+    /**
+     * Notify subscribed MCP clients that a specific resource has been updated.
+     * Only sessions that subscribed to the given URI receive the notification.
+     */
+    notifyResourceUpdated(uri: string): void;
+    /**
+     * Initialize OpenTelemetry before starting the server.
+     *
+     * OTEL auto-instrumentation must be initialized before any HTTP/Express
+     * modules are loaded to properly instrument them. Call this as early
+     * as possible. No-op if telemetry is disabled or already initialized.
+     */
+    initTelemetry(): Promise<void>;
+    start(): Promise<void>;
+    /**
+     * Gracefully stop the server.
+     *
+     * Performs cleanup in order: sessions → transport → auth → logger → telemetry.
+     * Each step is individually guarded (error isolation) so that a failure
+     * in one step does not prevent the remaining steps from running.
+     * Idempotent — calling `stop()` on an already stopped server is a no-op.
+     */
+    stop(): Promise<void>;
+    /**
+     * Create the unified SessionManager.
+     *
+     * For stdio mode: single session, no cleanup/keepalive cycles.
+     * For HTTP modes: default config from environment/constants.
+     */
+    private createSessionManager;
+    /**
+     * Bridges config file / env values into the logger configuration.
+     *
+     * The logger has its own `globalLoggerConfig` (default: info) which is
+     * intentionally decoupled from the framework config (DD-006). This method
+     * acts as the explicit bridge — reading resolved config values and
+     * forwarding them to `configureLogger()`.
+     */
+    private applyLoggerConfig;
+    /**
+     * Bridges programmatic `createServer()` options into the framework
+     * config cache so that all downstream modules (telemetry, SSE router,
+     * rate limiter, health endpoint, etc.) see consistent configuration.
+     *
+     * Bridges:
+     * - `options.version` → `config.VERSION` (fixes `service_version="unknown"`)
+     * - `options.name` → `config.OTEL_SERVICE_NAME` (default, unless env/config file overrides)
+     * - Transport HTTP options → corresponding config keys
+     *
+     * Environment variables remain the default — programmatic options override them.
+     */
+    private applyProgrammaticOverrides;
+    /**
+     * Start the appropriate transport for the configured mode.
+     *
+     * For HTTP/HTTPS: dynamically loads Express modules (after OTEL init),
+     * creates Express app with full middleware stack, then starts the HTTP server.
+     * For stdio: creates a single session connected to stdin/stdout.
+     *
+     * @lazy-transport Express/HTTP modules are loaded via dynamic `import()` so
+     * that OTEL instrumentation initializes before Express is imported.
+     * See DD-006 for the established lazy-import pattern and DD-018 for
+     * the Express lazy-loading rationale.
+     */
+    private startTransport;
+    /**
+     * Register process signal handlers for graceful shutdown.
+     *
+     * Uses `process.once()` for each signal. Handler references are stored
+     * so they can be removed in `stop()` to prevent accumulation when the
+     * server is restarted within the same process.
+     */
+    private setupSignalHandlers;
+    /**
+     * Register handlers for unhandled promise rejections and uncaught exceptions.
+     *
+     * Both trigger a graceful shutdown followed by `process.exit(1)`. A guard
+     * prevents concurrent shutdown attempts when multiple errors arrive or
+     * a signal arrives simultaneously.
+     */
+    private setupProcessErrorHandlers;
+    /**
+     * Remove previously registered signal handlers.
+     *
+     * Prevents handler accumulation when `start()` is called multiple times
+     * (e.g., after `stop()` → `start()` restart).
+     */
+    private removeSignalHandlers;
+    /**
+     * Perform graceful shutdown with optional timeout enforcement.
+     *
+     * If `forceExitOnTimeout` is enabled, forces `process.exit(1)` when
+     * the shutdown exceeds the configured timeout. The timeout is unref'd
+     * to avoid keeping the event loop alive if shutdown completes in time.
+     */
+    private gracefulStop;
+    /**
+     * Transitions the server state and logs the change.
+     */
+    private transitionState;
+    /**
+     * Invokes a lifecycle hook with error logging.
+     * Hook errors are logged as warnings but do not abort the lifecycle.
+     */
+    private invokeLifecycleHook;
+    /**
+     * Log the auth configuration at startup.
+     *
+     * Warns when auth is configured with stdio (unsupported)
+     * or when auth is used without trust proxy behind a reverse proxy.
+     */
+    private logAuthConfiguration;
+    /**
+     * Dispose the auth provider if it has a `dispose()` method.
+     */
+    private disposeAuthProvider;
+}
+//# sourceMappingURL=server-instance.d.ts.map

package/build/server/server-instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instance.d.ts","sourceRoot":"","sources":["../../src/server/server-instance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AAYxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AA6DtE;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IA+BpD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,cAAc;IA/BjC,OAAO,CAAC,WAAW,CAA0B;IAE7C,6CAA6C;IAC7C,OAAO,CAAC,oBAAoB,CAAS;IAErC,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAE9C,wEAAwE;IACxE,OAAO,CAAC,cAAc,CAAC,CAA6B;IAEpD,qDAAqD;IACrD,OAAO,CAAC,eAAe,CAAC,CAA8B;IAEtD,mEAAmE;IACnE,OAAO,CAAC,cAAc,CAGd;IAER,0EAA0E;IAC1E,OAAO,CAAC,oBAAoB,CAGpB;IAER,oEAAoE;IACpE,OAAO,CAAC,kBAAkB,CAAS;gBAGhB,OAAO,EAAE,aAAa,EACtB,cAAc,EAAE,iBAAiB;IAUpD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;;OAKG;IACH,qBAAqB,IAAI,IAAI;IAI7B;;OAEG;IACH,yBAAyB,IAAI,IAAI;IAIjC;;OAEG;IACH,uBAAuB,IAAI,IAAI;IAI/B;;;OAGG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxC;;;;;;OAMG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAa9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4F5B;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqF3B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,0BAA0B;IAOlC;;;;;;;;;;;OAWG;YACW,cAAc;IA4C5B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;;;;;OAMG;IACH,OAAO,CAAC,yBAAyB;IA8BjC;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;;;;;OAMG;YACW,YAAY;IAgD1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;;OAGG;YACW,mBAAmB;IASjC;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;OAEG;YACW,mBAAmB;CAQlC"}