mcp-server-framework 1.0.0

package/build/server/option-overrides.js

@@ -0,0 +1,85 @@
+/**
+ * Programmatic Option → Config Overrides
+ *
+ * Pure mapping function that bridges programmatic ServerOptions into
+ * FrameworkEnvConfig overrides. Extracted from McpServerInstance for
+ * testability and to reduce class complexity.
+ *
+ * @module server/option-overrides
+ * @internal
+ */
+import { isHttpTransport } from "./server-options.js";
+/**
+ * Maps programmatic server options to config override entries.
+ *
+ * This is a pure function — it reads `currentConfig` only to check
+ * whether OTEL_SERVICE_NAME is already set (avoiding accidental override).
+ *
+ * @param options - The server options from createServer() or McpServerBuilder
+ * @param currentConfig - The current resolved framework config
+ * @returns Partial config overrides to apply (empty object if none)
+ * @internal
+ */
+export function mapServerOptionsToOverrides(options, currentConfig) {
+    const overrides = {};
+    // Always bridge version — createServer({ version }) is the canonical source
+    overrides.VERSION = options.version;
+    // Bridge server name as OTEL service name default.
+    // The MCP server name is the natural default — env var or config file
+    // can override it for deployment-specific naming (e.g. 'my-app-prod').
+    if (options.name && !currentConfig.OTEL_SERVICE_NAME) {
+        overrides.OTEL_SERVICE_NAME = options.name;
+    }
+    // Bridge transport HTTP options (discriminated union — narrowed by isHttpTransport)
+    const transport = options.transport;
+    if (isHttpTransport(transport)) {
+        if (transport.legacySseEnabled !== undefined) {
+            overrides.MCP_LEGACY_SSE_ENABLED = transport.legacySseEnabled;
+        }
+        if (transport.port !== undefined) {
+            overrides.MCP_PORT = transport.port;
+        }
+        if (transport.host !== undefined) {
+            overrides.MCP_BIND_HOST = transport.host;
+        }
+        if (transport.rateLimitMax !== undefined) {
+            overrides.MCP_RATE_LIMIT_MAX = transport.rateLimitMax;
+        }
+        if (transport.rateLimitWindowMs !== undefined) {
+            overrides.MCP_RATE_LIMIT_WINDOW_MS = transport.rateLimitWindowMs;
+        }
+        if (transport.trustProxy !== undefined) {
+            overrides.MCP_TRUST_PROXY = transport.trustProxy;
+        }
+        if (transport.stateless !== undefined) {
+            overrides.MCP_STATELESS = transport.stateless;
+        }
+        if (transport.enableJsonResponse !== undefined) {
+            overrides.MCP_JSON_RESPONSE = transport.enableJsonResponse;
+        }
+        if (transport.corsOrigin !== undefined) {
+            overrides.MCP_CORS_ORIGIN = transport.corsOrigin;
+        }
+        if (transport.corsCredentials !== undefined) {
+            overrides.MCP_CORS_CREDENTIALS = transport.corsCredentials;
+        }
+        if (transport.helmetHsts !== undefined) {
+            overrides.MCP_HELMET_HSTS = transport.helmetHsts;
+        }
+        if (transport.helmetCsp !== undefined) {
+            overrides.MCP_HELMET_CSP = transport.helmetCsp;
+        }
+        if (transport.helmetFrameOptions !== undefined) {
+            overrides.MCP_HELMET_FRAME_OPTIONS = transport.helmetFrameOptions;
+        }
+    }
+    // Bridge programmatic session options → config cache (limits only)
+    const session = options.session;
+    if (session) {
+        if (session.maxSessions !== undefined) {
+            overrides.MCP_MAX_SESSIONS = session.maxSessions;
+        }
+    }
+    return overrides;
+}
+//# sourceMappingURL=option-overrides.js.map

package/build/server/option-overrides.js.map

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

package/build/server/routes/health.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Health and Readiness check routes
+ *
+ * Provides endpoints for container orchestration (Kubernetes, Docker Swarm, Docker Compose):
+ *
+ * /health - Liveness probe (is the process alive?)
+ *   - Always returns 200 if server is running
+ *   - Use: Kubernetes livenessProbe, basic uptime monitoring
+ *
+ * /ready - Readiness probe (can the server handle requests?)
+ *   - 200 OK: Server is ready for traffic
+ *   - 503 Service Unavailable: API configured but not connected
+ *   - 429 Too Many Requests: Session limit reached
+ *   - Use: Kubernetes readinessProbe, Docker HEALTHCHECK, load balancer health checks
+ *
+ * For Docker containers, use /ready as the HEALTHCHECK endpoint to ensure
+ * the container only receives traffic when fully operational.
+ *
+ * @module server/routes/health
+ */
+import { Router } from "express";
+import type { SessionManager } from "../session/index.js";
+import type { ConnectionStateManager } from "../../connection/index.js";
+import type { ServiceClient } from "../../connection/types.js";
+export { ReadinessStatus, type ReadinessStatusValue } from "./readiness-status.js";
+/**
+ * SSE transport information provider.
+ *
+ * Injected by the transport layer to decouple health checks
+ * from SSE implementation details.
+ */
+export interface SseInfoProvider {
+    /** Whether SSE transport is enabled */
+    readonly enabled: boolean;
+    /** Get the current count of active SSE sessions */
+    getSessionCount(sessionManager: SessionManager): number;
+}
+/**
+ * Options for creating the health router.
+ */
+export interface HealthRouterOptions<TService extends ServiceClient = ServiceClient> {
+    /** Session manager for tracking active sessions */
+    sessionManager: SessionManager;
+    /**
+     * Optional connection manager for API health checks.
+     * If not provided, API connectivity checks are skipped.
+     */
+    connectionManager?: ConnectionStateManager<TService> | undefined;
+    /**
+     * Function to check if API is configured.
+     * Reads from runtime environment to support Docker env_file.
+     * If not provided, defaults to checking for API_URL env var.
+     */
+    isApiConfigured?: (() => boolean) | undefined;
+    /**
+     * Label for the API in health responses (e.g., 'my-api', 'docker', 'kubernetes')
+     * Defaults to 'api'
+     */
+    apiLabel?: string | undefined;
+    /**
+     * Optional SSE transport information.
+     * If not provided, SSE-related information is omitted from health responses.
+     */
+    sseInfo?: SseInfoProvider | undefined;
+}
+/**
+ * Creates health check router with configurable API connection monitoring.
+ *
+ * @param options - Configuration options for the health router
+ * @returns Express router with /health and /ready endpoints
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (no API monitoring)
+ * const router = createHealthRouter({ sessionManager });
+ *
+ * // With API connection monitoring
+ * const router = createHealthRouter({
+ *   sessionManager,
+ *   connectionManager: myConnectionManager,
+ *   isApiConfigured: () => !!process.env.API_URL,
+ *   apiLabel: 'api',
+ * });
+ * ```
+ */
+export declare function createHealthRouter<TService extends ServiceClient = ServiceClient>(options: HealthRouterOptions<TService>): Router;
+//# sourceMappingURL=health.d.ts.map

package/build/server/routes/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/server/routes/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AA2B/D,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEnF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mDAAmD;IACnD,eAAe,CAAC,cAAc,EAAE,cAAc,GAAG,MAAM,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa;IACjF,mDAAmD;IACnD,cAAc,EAAE,cAAc,CAAC;IAE/B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;IAEjE;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,SAAS,CAAC;IAE9C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9B;;;OAGG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CACvC;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC/E,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACrC,MAAM,CAuIR"}

package/build/server/routes/health.js

@@ -0,0 +1,183 @@
+/**
+ * Health and Readiness check routes
+ *
+ * Provides endpoints for container orchestration (Kubernetes, Docker Swarm, Docker Compose):
+ *
+ * /health - Liveness probe (is the process alive?)
+ *   - Always returns 200 if server is running
+ *   - Use: Kubernetes livenessProbe, basic uptime monitoring
+ *
+ * /ready - Readiness probe (can the server handle requests?)
+ *   - 200 OK: Server is ready for traffic
+ *   - 503 Service Unavailable: API configured but not connected
+ *   - 429 Too Many Requests: Session limit reached
+ *   - Use: Kubernetes readinessProbe, Docker HEALTHCHECK, load balancer health checks
+ *
+ * For Docker containers, use /ready as the HEALTHCHECK endpoint to ensure
+ * the container only receives traffic when fully operational.
+ *
+ * @module server/routes/health
+ */
+import { Router } from "express";
+import { getFrameworkConfig } from "../../config/index.js";
+import { logger as baseLogger } from "../../logger/index.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const ROUTES = {
+    HEALTH: "/health",
+    READY: "/ready",
+};
+const LOG_COMPONENT = "health";
+const LogMessages = {
+    NOT_READY: "Server not ready: %s",
+    READINESS_CHECK: "Readiness check: status=%d, reason=%s",
+};
+const logger = baseLogger.child({ component: LOG_COMPONENT });
+// ============================================================================
+// Types
+// ============================================================================
+import { ReadinessStatus } from "./readiness-status.js";
+export { ReadinessStatus } from "./readiness-status.js";
+// ============================================================================
+// Health Router Factory
+// ============================================================================
+/**
+ * Creates health check router with configurable API connection monitoring.
+ *
+ * @param options - Configuration options for the health router
+ * @returns Express router with /health and /ready endpoints
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (no API monitoring)
+ * const router = createHealthRouter({ sessionManager });
+ *
+ * // With API connection monitoring
+ * const router = createHealthRouter({
+ *   sessionManager,
+ *   connectionManager: myConnectionManager,
+ *   isApiConfigured: () => !!process.env.API_URL,
+ *   apiLabel: 'api',
+ * });
+ * ```
+ */
+export function createHealthRouter(options) {
+    const { sessionManager, connectionManager, isApiConfigured = () => !!process.env.API_URL?.trim(), apiLabel = "api", sseInfo, } = options;
+    const router = Router();
+    /**
+     * Liveness probe endpoint
+     * Returns 200 if the server process is running.
+     */
+    router.get(ROUTES.HEALTH, (_req, res) => {
+        const config = getFrameworkConfig();
+        const { byTransportType } = sessionManager.stats;
+        const streamableHttpCount = byTransportType.http + byTransportType.https;
+        const response = {
+            status: "healthy",
+            version: config.VERSION,
+            uptime: process.uptime(),
+            sessions: {
+                active: sessionManager.size,
+                streamableHttp: streamableHttpCount,
+            },
+        };
+        // Include SSE session count if enabled
+        if (sseInfo?.enabled) {
+            // @type-narrowing — response.sessions is narrower typed; SSE field added conditionally
+            response.sessions.sse = byTransportType.sse;
+        }
+        res.status(200).json(response);
+    });
+    /**
+     * Readiness probe endpoint
+     * Returns appropriate status code based on server readiness.
+     */
+    router.get(ROUTES.READY, (_req, res) => {
+        const config = getFrameworkConfig();
+        // Get API connection state (if connection manager is provided)
+        const connectionState = connectionManager?.getState() ?? "unknown";
+        const isApiConnected = connectionState === "connected";
+        // Read session limits from dynamic config
+        const maxSessions = config.MCP_MAX_SESSIONS;
+        const maxStreamableHttpSessions = config.MCP_MAX_STREAMABLE_HTTP_SESSIONS;
+        const maxSseSessions = config.MCP_MAX_SSE_SESSIONS;
+        // Check session limits using accurate per-transport-type counters
+        const { byTransportType } = sessionManager.stats;
+        const totalSessionCount = sessionManager.size;
+        const sseEnabled = sseInfo?.enabled ?? false;
+        const sseSessionCount = byTransportType.sse;
+        const streamableHttpSessionCount = byTransportType.http + byTransportType.https;
+        const totalAtLimit = totalSessionCount >= maxSessions;
+        const streamableHttpAtLimit = streamableHttpSessionCount >= maxStreamableHttpSessions;
+        const sseAtLimit = sseEnabled && sseSessionCount >= maxSseSessions;
+        const sessionsAtLimit = totalAtLimit || streamableHttpAtLimit || sseAtLimit;
+        // Determine readiness
+        const hasApiConfig = isApiConfigured();
+        const apiReady = !hasApiConfig || isApiConnected;
+        // Determine status code
+        let status;
+        let reason;
+        if (sessionsAtLimit) {
+            status = ReadinessStatus.TOO_MANY_REQUESTS;
+            if (totalAtLimit) {
+                reason = `Total session limit reached (${totalSessionCount}/${maxSessions})`;
+            }
+            else if (streamableHttpAtLimit) {
+                reason = `Streamable HTTP session limit reached (${streamableHttpSessionCount}/${maxStreamableHttpSessions})`;
+            }
+            else {
+                reason = `SSE session limit reached (${sseSessionCount}/${maxSseSessions})`;
+            }
+        }
+        else if (!apiReady) {
+            status = ReadinessStatus.SERVICE_UNAVAILABLE;
+            reason = `${apiLabel} not connected (state: ${connectionState})`;
+        }
+        else {
+            status = ReadinessStatus.READY;
+            reason = "Server is ready";
+        }
+        const isReady = status === ReadinessStatus.READY;
+        // Log readiness state — warn on not-ready, debug on ready
+        if (!isReady) {
+            logger.warn(LogMessages.NOT_READY, reason);
+        }
+        else {
+            logger.debug(LogMessages.READINESS_CHECK, status, reason);
+        }
+        const response = {
+            ready: isReady,
+            status: reason,
+            version: config.VERSION,
+            uptime: process.uptime(),
+            [apiLabel]: {
+                configured: hasApiConfig,
+                state: connectionState,
+                connected: isApiConnected,
+            },
+            sessions: {
+                total: {
+                    current: totalSessionCount,
+                    max: maxSessions,
+                    atLimit: totalAtLimit,
+                },
+                streamableHttp: {
+                    current: streamableHttpSessionCount,
+                    max: maxStreamableHttpSessions,
+                    atLimit: streamableHttpAtLimit,
+                },
+                ...(sseEnabled && {
+                    sse: {
+                        current: sseSessionCount,
+                        max: maxSseSessions,
+                        atLimit: sseAtLimit,
+                    },
+                }),
+            },
+        };
+        res.status(status).json(response);
+    });
+    return router;
+}
+//# sourceMappingURL=health.js.map

package/build/server/routes/health.js.map

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

package/build/server/routes/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Server Routes
+ *
+ * Express route handlers for server-level endpoints (health, readiness, metrics)
+ * and MCP transport routers (Streamable HTTP, legacy SSE).
+ *
+ * @module server/routes
+ */
+export { createHealthRouter, ReadinessStatus } from "./health.js";
+export type { HealthRouterOptions, SseInfoProvider } from "./health.js";
+export { createMetricsRouter } from "./metrics.js";
+export { createStreamableHttpRouter } from "./streamable-http-router.js";
+export { createSseRouter, isSseEnabled, getSseSessionCount } from "./sse-router.js";
+export { createOAuthRouter } from "./oauth-router.js";
+export type { OAuthRouterOptions } from "./oauth-router.js";
+//# sourceMappingURL=index.d.ts.map

package/build/server/routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/routes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAIxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAInD,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAIpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/build/server/routes/index.js

@@ -0,0 +1,18 @@
+/**
+ * Server Routes
+ *
+ * Express route handlers for server-level endpoints (health, readiness, metrics)
+ * and MCP transport routers (Streamable HTTP, legacy SSE).
+ *
+ * @module server/routes
+ */
+// ===== Health & Readiness =====
+export { createHealthRouter, ReadinessStatus } from "./health.js";
+// ===== Prometheus Metrics =====
+export { createMetricsRouter } from "./metrics.js";
+// ===== MCP Transport Routers =====
+export { createStreamableHttpRouter } from "./streamable-http-router.js";
+export { createSseRouter, isSseEnabled, getSseSessionCount } from "./sse-router.js";
+// ===== OAuth Router =====
+export { createOAuthRouter } from "./oauth-router.js";
+//# sourceMappingURL=index.js.map

package/build/server/routes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/routes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,iCAAiC;AAEjC,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGlE,iCAAiC;AAEjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,oCAAoC;AAEpC,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEpF,2BAA2B;AAE3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/build/server/routes/metrics.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Prometheus Metrics Route
+ *
+ * Exposes OpenTelemetry metrics in Prometheus text format at `/metrics`.
+ *
+ * The route delegates to the embedded PrometheusExporter registered as a
+ * MetricReader in the SDK. When telemetry is disabled or 'prometheus' is
+ * not in OTEL_METRICS_EXPORTER, the endpoint returns 503.
+ *
+ * All metrics are collected centrally by OpenTelemetry — no custom metric
+ * implementations. The Prometheus exporter serializes the same data that
+ * is also exported to OTLP backends.
+ *
+ * Exposed metrics include:
+ * - `mcp_server_*` — MCP server metrics (requests, sessions, errors, uptime, memory)
+ * - `http_server_*` — HTTP server metrics from auto-instrumentation
+ * - `target_info` — Service resource attributes
+ *
+ * @module server/routes/metrics
+ */
+import { Router } from "express";
+/**
+ * Creates an Express router that serves Prometheus-formatted metrics.
+ *
+ * Delegates to the `PrometheusExporter` request handler registered as a
+ * MetricReader in the SDK ({@link initializeTelemetry}). Returns 503 when
+ * telemetry is disabled or 'prometheus' is not in OTEL_METRICS_EXPORTER.
+ *
+ * @returns Express Router with GET /metrics handler
+ *
+ * @example
+ * ```typescript
+ * import { createMetricsRouter } from './routes/metrics.js';
+ *
+ * const app = express();
+ * app.use(createMetricsRouter());
+ * ```
+ */
+export declare function createMetricsRouter(): Router;
+//# sourceMappingURL=metrics.d.ts.map

package/build/server/routes/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/server/routes/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AA0BjC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CA4B5C"}

package/build/server/routes/metrics.js

@@ -0,0 +1,81 @@
+/**
+ * Prometheus Metrics Route
+ *
+ * Exposes OpenTelemetry metrics in Prometheus text format at `/metrics`.
+ *
+ * The route delegates to the embedded PrometheusExporter registered as a
+ * MetricReader in the SDK. When telemetry is disabled or 'prometheus' is
+ * not in OTEL_METRICS_EXPORTER, the endpoint returns 503.
+ *
+ * All metrics are collected centrally by OpenTelemetry — no custom metric
+ * implementations. The Prometheus exporter serializes the same data that
+ * is also exported to OTLP backends.
+ *
+ * Exposed metrics include:
+ * - `mcp_server_*` — MCP server metrics (requests, sessions, errors, uptime, memory)
+ * - `http_server_*` — HTTP server metrics from auto-instrumentation
+ * - `target_info` — Service resource attributes
+ *
+ * @module server/routes/metrics
+ */
+import { Router } from "express";
+import { getPrometheusExporter } from "../../telemetry/index.js";
+import { logger as baseLogger } from "../../logger/index.js";
+const COMPONENT = "MetricsRoute";
+const logger = baseLogger.child({ component: COMPONENT });
+/** @internal Log messages for the metrics route */
+const LogMessages = {
+    TELEMETRY_DISABLED: "Metrics endpoint requested but Prometheus exporter is not available",
+};
+// ============================================================================
+// Content Types
+// ============================================================================
+/**
+ * Prometheus text exposition format content type.
+ * @see https://prometheus.io/docs/instrumenting/exposition_formats/
+ */
+const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+// ============================================================================
+// Metrics Router Factory
+// ============================================================================
+/**
+ * Creates an Express router that serves Prometheus-formatted metrics.
+ *
+ * Delegates to the `PrometheusExporter` request handler registered as a
+ * MetricReader in the SDK ({@link initializeTelemetry}). Returns 503 when
+ * telemetry is disabled or 'prometheus' is not in OTEL_METRICS_EXPORTER.
+ *
+ * @returns Express Router with GET /metrics handler
+ *
+ * @example
+ * ```typescript
+ * import { createMetricsRouter } from './routes/metrics.js';
+ *
+ * const app = express();
+ * app.use(createMetricsRouter());
+ * ```
+ */
+export function createMetricsRouter() {
+    const router = Router();
+    router.get("/metrics", (req, res) => {
+        const exporter = getPrometheusExporter();
+        if (!exporter) {
+            logger.debug(LogMessages.TELEMETRY_DISABLED);
+            res.status(503).json({
+                error: "Prometheus metrics not available",
+                hint: 'Set OTEL_ENABLED=true and include "prometheus" in OTEL_METRICS_EXPORTER',
+            });
+            return;
+        }
+        // @express-api — PrometheusExporter.getMetricsRequestHandler expects
+        // Node.js IncomingMessage/ServerResponse, which Express req/res extend.
+        // @type-narrowing — getPrometheusExporter() returns `unknown` because the
+        // PrometheusExporter class is lazy-loaded (DD-020). The null check above
+        // guarantees the exporter exists, and its API is known.
+        res.setHeader("Content-Type", PROMETHEUS_CONTENT_TYPE);
+        const handler = exporter;
+        handler.getMetricsRequestHandler(req, res);
+    });
+    return router;
+}
+//# sourceMappingURL=metrics.js.map

package/build/server/routes/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/server/routes/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,SAAS,GAAG,cAAc,CAAC;AACjC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;AAE1D,mDAAmD;AACnD,MAAM,WAAW,GAAG;IAClB,kBAAkB,EAAE,qEAAqE;CACjF,CAAC;AAEX,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,uBAAuB,GAAG,0CAA0C,CAAC;AAE3E,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IAExB,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAClC,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;QAEzC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC;YAC7C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;gBACnB,KAAK,EAAE,kCAAkC;gBACzC,IAAI,EAAE,yEAAyE;aAChF,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,qEAAqE;QACrE,wEAAwE;QACxE,0EAA0E;QAC1E,yEAAyE;QACzE,wDAAwD;QACxD,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,uBAAuB,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,QAEf,CAAC;QACF,OAAO,CAAC,wBAAwB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,50 @@
+/**
+ * OAuth Router Middleware
+ *
+ * Wraps the SDK's `mcpAuthRouter()` to mount OAuth 2.1 endpoints
+ * when a full OAuth provider is configured.
+ *
+ * Routes mounted:
+ * - `GET /authorize` — Authorization endpoint
+ * - `POST /token` — Token endpoint
+ * - `POST /register` — Dynamic client registration
+ * - `POST /revoke` — Token revocation
+ * - `GET /.well-known/oauth-authorization-server` — Authorization Server Metadata (RFC 8414)
+ * - `GET /.well-known/oauth-protected-resource` — Protected Resource Metadata (RFC 9728)
+ *
+ * Only created when the provider is a full `OAuthServerProvider`
+ * (detected via {@link isFullOAuthProvider}).
+ *
+ * @module server/routes/oauth-router
+ */
+import type { RequestHandler } from "express";
+import type { OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+/**
+ * Options for creating the OAuth router.
+ */
+export interface OAuthRouterOptions {
+    /** Full OAuth server provider (must have `clientsStore`) */
+    readonly provider: OAuthServerProvider;
+    /**
+     * OAuth issuer URL (Authorization Server identifier).
+     * Required by the MCP SDK for Authorization Server Metadata (RFC 8414).
+     */
+    readonly issuerUrl: URL;
+    /**
+     * Scopes supported by this authorization server.
+     * Advertised in the Authorization Server Metadata document.
+     */
+    readonly scopesSupported?: readonly string[] | undefined;
+}
+/**
+ * Creates an Express router with OAuth 2.1 endpoints.
+ *
+ * Delegates to the SDK's `mcpAuthRouter()` for the actual endpoint
+ * implementation. The router handles authorization, token exchange,
+ * client registration, and discovery metadata.
+ *
+ * @param options - OAuth router configuration
+ * @returns Express request handler (router) with OAuth endpoints
+ */
+export declare function createOAuthRouter(options: OAuthRouterOptions): RequestHandler;
+//# sourceMappingURL=oauth-router.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-router.d.ts","sourceRoot":"","sources":["../../../src/server/routes/oauth-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mDAAmD,CAAC;AAqB7F;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC1D;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CAY7E"}

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

@@ -0,0 +1,53 @@
+/**
+ * OAuth Router Middleware
+ *
+ * Wraps the SDK's `mcpAuthRouter()` to mount OAuth 2.1 endpoints
+ * when a full OAuth provider is configured.
+ *
+ * Routes mounted:
+ * - `GET /authorize` — Authorization endpoint
+ * - `POST /token` — Token endpoint
+ * - `POST /register` — Dynamic client registration
+ * - `POST /revoke` — Token revocation
+ * - `GET /.well-known/oauth-authorization-server` — Authorization Server Metadata (RFC 8414)
+ * - `GET /.well-known/oauth-protected-resource` — Protected Resource Metadata (RFC 9728)
+ *
+ * Only created when the provider is a full `OAuthServerProvider`
+ * (detected via {@link isFullOAuthProvider}).
+ *
+ * @module server/routes/oauth-router
+ */
+import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { logger as baseLogger } from "../../logger/index.js";
+// ============================================================================
+// Logger
+// ============================================================================
+const LOG_COMPONENT = "oauth-router";
+const LogMessages = {
+    MOUNTED: "OAuth router mounted (issuer: %s)",
+};
+const logger = baseLogger.child({ component: LOG_COMPONENT });
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Creates an Express router with OAuth 2.1 endpoints.
+ *
+ * Delegates to the SDK's `mcpAuthRouter()` for the actual endpoint
+ * implementation. The router handles authorization, token exchange,
+ * client registration, and discovery metadata.
+ *
+ * @param options - OAuth router configuration
+ * @returns Express request handler (router) with OAuth endpoints
+ */
+export function createOAuthRouter(options) {
+    const { provider, issuerUrl, scopesSupported } = options;
+    const routerOptions = {
+        provider,
+        issuerUrl,
+        ...(scopesSupported && { scopesSupported: [...scopesSupported] }),
+    };
+    logger.info(LogMessages.MOUNTED, issuerUrl.toString());
+    return mcpAuthRouter(routerOptions);
+}
+//# sourceMappingURL=oauth-router.js.map