mcp-server-framework 1.0.0

package/build/server/transport/streamable-http/transport.js

@@ -0,0 +1,118 @@
+/**
+ * Streamable HTTP Transport
+ *
+ * Facade that delegates HTTP requests to the appropriate strategy handler
+ * based on the configured mode (stateful or stateless).
+ *
+ * Architecture:
+ *   Express Route → StreamableHttpTransport → Strategy Handler → SDK Transport → McpServer
+ *
+ * The SDK transport handles all MCP protocol concerns:
+ * - JSON-RPC 2.0 parsing and validation
+ * - Content-Type and Accept header validation
+ * - Session ID management (header setting/checking)
+ * - SSE stream setup for server-to-client notifications
+ * - Session termination
+ *
+ * This transport manages:
+ * - Strategy selection (stateful vs stateless)
+ * - HTTP method routing (POST, GET, DELETE)
+ * - Error responses for unsupported methods
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+ * @module server/transport/streamable-http/transport
+ */
+import { HttpStatus, TransportErrorMessage, JsonRpcErrorCode, createJsonRpcError } from "../../../errors/index.js";
+import { logger as baseLogger } from "../../../logger/index.js";
+import { TRANSPORT_LOG_COMPONENTS, SESSION_ID_DISPLAY_LENGTH } from "../constants.js";
+import { StatefulHandler } from "./stateful-handler.js";
+import { StatelessHandler } from "./stateless-handler.js";
+const logger = baseLogger.child({
+    component: TRANSPORT_LOG_COMPONENTS.STREAMABLE_HTTP,
+});
+// ============================================================================
+// Shared Utilities
+// ============================================================================
+/**
+ * Sends a JSON-RPC error response if headers haven't been sent.
+ */
+export function sendError(res, status, code, message) {
+    if (!res.headersSent) {
+        res.status(status).json(createJsonRpcError(code, message));
+    }
+}
+/**
+ * Shortens a session ID for log display.
+ */
+export function shortId(sessionId) {
+    return sessionId.substring(0, SESSION_ID_DISPLAY_LENGTH);
+}
+/** @internal Log messages for transport router */
+const LogMessages = {
+    METHOD_NOT_ALLOWED: "%s /mcp rejected: method not allowed",
+    UNHANDLED_ERROR: "Unhandled error in request handler: %s",
+};
+// ============================================================================
+// Transport Facade
+// ============================================================================
+/**
+ * Routes HTTP requests to the appropriate strategy handler.
+ *
+ * In stateful mode (default): delegates to {@link StatefulHandler}
+ * In stateless mode: delegates to {@link StatelessHandler}
+ *
+ * All MCP protocol handling is delegated through the handler chain
+ * to the SDK's StreamableHTTPServerTransport.
+ */
+export class StreamableHttpTransport {
+    handler;
+    sessionManager;
+    constructor(sessionFactory, sessionManager, options = {}) {
+        this.sessionManager = sessionManager;
+        const enableJsonResponse = options.enableJsonResponse ?? true;
+        this.handler = options.stateless
+            ? new StatelessHandler(sessionFactory, enableJsonResponse)
+            : new StatefulHandler(sessionFactory, sessionManager, enableJsonResponse, options.eventStore);
+    }
+    // ==========================================================================
+    // Public API
+    // ==========================================================================
+    /**
+     * Handle an incoming HTTP request by delegating to the appropriate
+     * strategy handler.
+     *
+     * This is the single entry point called by Express route handlers.
+     * Security middleware (DNS rebinding, rate limiting, protocol version)
+     * runs BEFORE this method is called.
+     */
+    async handleRequest(req, res) {
+        try {
+            switch (req.method) {
+                case "POST":
+                    await this.handler.handlePost(req, res);
+                    break;
+                case "GET":
+                    await this.handler.handleGet(req, res);
+                    break;
+                case "DELETE":
+                    await this.handler.handleDelete(req, res);
+                    break;
+                default:
+                    logger.warn(LogMessages.METHOD_NOT_ALLOWED, req.method);
+                    sendError(res, HttpStatus.METHOD_NOT_ALLOWED, JsonRpcErrorCode.METHOD_NOT_FOUND, `Method ${req.method} not allowed`);
+            }
+        }
+        catch (error) {
+            logger.error(LogMessages.UNHANDLED_ERROR, error);
+            sendError(res, HttpStatus.INTERNAL_SERVER_ERROR, JsonRpcErrorCode.INTERNAL_ERROR, TransportErrorMessage.INTERNAL_ERROR);
+        }
+    }
+    /**
+     * Number of active stateful sessions.
+     * Returns 0 in stateless mode (no session tracking).
+     */
+    get activeSessionCount() {
+        return this.sessionManager.size;
+    }
+}
+//# sourceMappingURL=transport.js.map

package/build/server/transport/streamable-http/transport.js.map

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

package/build/server/transport/transport-context.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Transport Context Types
+ *
+ * Transport-layer concerns for MCP sessions including connection details,
+ * transport type discrimination, and heartbeat tracking.
+ *
+ * @module server/transport/transport-context
+ */
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+/**
+ * Supported transport types in the framework.
+ */
+export type TransportType = "http" | "https" | "sse" | "stdio";
+/**
+ * Transport that optionally supports heartbeat (keep-alive).
+ *
+ * Some transports (like StreamableHTTPServerTransport) support sendHeartbeat
+ * but it's not in the public SDK types.
+ */
+export interface HeartbeatCapableTransport extends Transport {
+    /**
+     * Sends a heartbeat to check if the connection is still alive.
+     * @returns true if heartbeat was sent successfully
+     */
+    sendHeartbeat: () => boolean;
+}
+/**
+ * Heartbeat tracking state.
+ *
+ * Immutable — create new objects via spread to update.
+ */
+export interface HeartbeatState {
+    /** Number of consecutive missed heartbeats */
+    readonly missedCount: number;
+    /** Last successful heartbeat timestamp */
+    readonly lastSuccessAt?: Date;
+    /** Whether this transport supports heartbeats */
+    readonly supportsHeartbeat: boolean;
+}
+/**
+ * Transport-specific context containing connection details.
+ *
+ * Encapsulates all transport-layer concerns:
+ * - The actual MCP transport instance
+ * - Transport type for runtime discrimination
+ * - Heartbeat tracking for connection health
+ */
+export interface TransportContext {
+    /** Discriminator for transport type */
+    readonly type: TransportType;
+    /** MCP SDK transport instance */
+    readonly instance: Transport;
+    /** Heartbeat tracking (only for HTTP-based transports) */
+    heartbeat: HeartbeatState;
+}
+/**
+ * Type guard for heartbeat-capable transports.
+ *
+ * Checks if the transport has a `sendHeartbeat` method.
+ * Used to safely narrow `Transport` without unchecked casts.
+ */
+export declare function isHeartbeatCapable(transport: Transport): transport is HeartbeatCapableTransport;
+/**
+ * Factory to create transport context from transport instance.
+ */
+export declare function createTransportContext(type: TransportType, transport: Transport): TransportContext;
+//# sourceMappingURL=transport-context.d.ts.map

package/build/server/transport/transport-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-context.d.ts","sourceRoot":"","sources":["../../../src/server/transport/transport-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAM/E;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;AAM/D;;;;;GAKG;AACH,MAAM,WAAW,yBAA0B,SAAQ,SAAS;IAC1D;;;OAGG;IACH,aAAa,EAAE,MAAM,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,0CAA0C;IAC1C,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC;IAE9B,iDAAiD;IACjD,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAE7B,0DAA0D;IAC1D,SAAS,EAAE,cAAc,CAAC;CAC3B;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,IAAI,yBAAyB,CAG/F;AAMD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,GAAG,gBAAgB,CASlG"}

package/build/server/transport/transport-context.js

@@ -0,0 +1,38 @@
+/**
+ * Transport Context Types
+ *
+ * Transport-layer concerns for MCP sessions including connection details,
+ * transport type discrimination, and heartbeat tracking.
+ *
+ * @module server/transport/transport-context
+ */
+// ============================================================================
+// Type Guard
+// ============================================================================
+/**
+ * Type guard for heartbeat-capable transports.
+ *
+ * Checks if the transport has a `sendHeartbeat` method.
+ * Used to safely narrow `Transport` without unchecked casts.
+ */
+export function isHeartbeatCapable(transport) {
+    // @type-guard — Standard TS pattern: cast to target type for property access within type predicate
+    return typeof transport.sendHeartbeat === "function";
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Factory to create transport context from transport instance.
+ */
+export function createTransportContext(type, transport) {
+    return {
+        type,
+        instance: transport,
+        heartbeat: {
+            missedCount: 0,
+            supportsHeartbeat: isHeartbeatCapable(transport),
+        },
+    };
+}
+//# sourceMappingURL=transport-context.js.map

package/build/server/transport/transport-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-context.js","sourceRoot":"","sources":["../../../src/server/transport/transport-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAsEH,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAoB;IACrD,mGAAmG;IACnG,OAAO,OAAQ,SAAuC,CAAC,aAAa,KAAK,UAAU,CAAC;AACtF,CAAC;AAED,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAmB,EAAE,SAAoB;IAC9E,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,SAAS;QACnB,SAAS,EAAE;YACT,WAAW,EAAE,CAAC;YACd,iBAAiB,EAAE,kBAAkB,CAAC,SAAS,CAAC;SACjD;KACF,CAAC;AACJ,CAAC"}

package/build/server/transport/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Transport Types
+ *
+ * Cross-module type definitions for the transport layer.
+ * Only types used by multiple transport sub-modules are defined here.
+ * Internal types are co-located with their consuming modules.
+ *
+ * @module server/transport/types
+ */
+import type { McpSession } from "../session/index.js";
+export type { TransportType, HeartbeatCapableTransport, HeartbeatState, TransportContext, } from "./transport-context.js";
+export { createTransportContext, isHeartbeatCapable } from "./transport-context.js";
+/**
+ * Transport state values for lifecycle tracking.
+ */
+export type TransportState = "created" | "starting" | "running" | "stopping" | "stopped" | "error";
+/**
+ * Factory function type for creating McpSession instances.
+ *
+ * Used by the transport layer where each connected client
+ * gets an McpSession with protocol handlers and SDK-native
+ * cancellation/progress support.
+ *
+ * @returns A new McpSession instance for the client
+ */
+export type SessionFactory = () => McpSession;
+/**
+ * Lightweight handle returned by transport start functions.
+ *
+ * Replaces the former TransportManager class hierarchy with a simple
+ * functional interface: start returns a handle, call shutdown to stop.
+ */
+export interface TransportHandle {
+    /** Graceful shutdown of the transport */
+    shutdown(): Promise<void>;
+    /** Get runtime transport information */
+    info(): TransportInfo;
+}
+/**
+ * Runtime information about the active transport.
+ */
+export interface TransportInfo {
+    /** Current transport state */
+    readonly state: TransportState;
+    /** When the transport was started */
+    readonly startedAt?: Date | undefined;
+    /** Transport mode identifier (e.g., 'stdio', 'http', 'https') */
+    readonly mode?: string | undefined;
+    /** Host address (HTTP/HTTPS only) */
+    readonly host?: string | undefined;
+    /** Port number (HTTP/HTTPS only) */
+    readonly port?: number | undefined;
+    /** Full URL (HTTP/HTTPS only) */
+    readonly url?: string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/server/transport/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/transport/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,YAAY,EACV,aAAa,EACb,yBAAyB,EACzB,cAAc,EACd,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAMpF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;AAMnG;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,UAAU,CAAC;AAM9C;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,wCAAwC;IACxC,IAAI,IAAI,aAAa,CAAC;CACvB;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,qCAAqC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,iCAAiC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC"}

package/build/server/transport/types.js

@@ -0,0 +1,11 @@
+/**
+ * Transport Types
+ *
+ * Cross-module type definitions for the transport layer.
+ * Only types used by multiple transport sub-modules are defined here.
+ * Internal types are co-located with their consuming modules.
+ *
+ * @module server/transport/types
+ */
+export { createTransportContext, isHeartbeatCapable } from "./transport-context.js";
+//# sourceMappingURL=types.js.map

package/build/server/transport/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/transport/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/build/server/transport-options.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Transport Configuration Types
+ *
+ * User-facing transport configuration types for the MCP server.
+ * These types define how consumers configure transport mode, TLS, HTTP options, etc.
+ *
+ * @module server/transport-options
+ */
+import type { EventStore } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+/**
+ * Transport modes supported by the MCP framework.
+ *
+ * - `stdio` — Single-client CLI mode
+ * - `http` — Multi-client HTTP mode
+ * - `https` — Multi-client HTTPS mode with TLS
+ */
+export type TransportMode = "stdio" | "http" | "https";
+/**
+ * TLS configuration for HTTPS transport.
+ *
+ * Certificate files are read from the filesystem at server startup.
+ * Required when transport mode is 'https'.
+ */
+export interface TlsConfig {
+    /** Path to the TLS certificate file (PEM format) */
+    readonly certPath: string;
+    /** Path to the TLS private key file (PEM format) */
+    readonly keyPath: string;
+    /** Optional path to the CA certificate file (PEM format) */
+    readonly caPath?: string;
+}
+/**
+ * Shared HTTP/HTTPS transport options.
+ *
+ * Contains all configuration common to both `http` and `https` modes.
+ * Used as the base for the discriminated union members.
+ */
+export interface BaseHttpTransportOptions {
+    /** Port to listen on (default: 8000 or MCP_PORT env) */
+    port?: number;
+    /** Host to bind to (default: '127.0.0.1' or MCP_BIND_HOST env) */
+    host?: string;
+    /** Enable legacy SSE transport for backwards compatibility */
+    legacySseEnabled?: boolean;
+    /** Rate limiting: max requests per window */
+    rateLimitMax?: number;
+    /** Rate limiting: window duration in ms */
+    rateLimitWindowMs?: number;
+    /**
+     * Trust proxy setting for Express.
+     *
+     * Required when running behind a reverse proxy (nginx, Traefik, cloud LB)
+     * to correctly resolve client IPs, protocol, and host from proxy headers
+     * (`X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`).
+     *
+     * Values:
+     * - Hop count (`'1'`, `'2'`) — Trust N hops from the front-facing proxy
+     * - Express keyword (`'loopback'`, `'linklocal'`, `'uniquelocal'`)
+     * - IP/CIDR (`'10.0.0.1'`, `'10.0.0.0/8'`)
+     * - DNS hostname (`'proxy.example.com'`) — resolved at startup
+     * - Comma-separated list (`'loopback, 10.0.0.1'`)
+     *
+     * Can also be configured via `MCP_TRUST_PROXY` env var or config file.
+     * Omit to disable trust proxy.
+     *
+     * @see https://expressjs.com/en/guide/behind-proxies.html
+     */
+    trustProxy?: string;
+    /**
+     * Operate in stateless mode (no session IDs).
+     *
+     * When enabled, each request gets a fresh McpSession and SDK transport.
+     * No Mcp-Session-Id headers are set. Per MCP specification, stateless
+     * servers do not track individual client sessions.
+     *
+     * In stateless mode, GET and DELETE return 405 Method Not Allowed.
+     *
+     * Use cases:
+     * - Simple tool servers that don't need per-client state
+     * - Serverless/edge deployments where session persistence is impractical
+     * - Horizontal scaling behind round-robin load balancers
+     *
+     * @default false
+     */
+    stateless?: boolean;
+    /**
+     * Prefer JSON responses over SSE streams for simple request-response.
+     *
+     * When enabled, the SDK returns `application/json` for non-streaming
+     * responses (e.g. tools/list, resources/list) instead of wrapping them
+     * in a `text/event-stream` SSE envelope.
+     *
+     * The MCP specification recommends: "If the server is only sending one
+     * response with no notifications, it SHOULD prefer application/json."
+     *
+     * Streaming responses (progress, notifications) always use SSE regardless.
+     *
+     * Can also be configured via `MCP_JSON_RESPONSE` env var or config file.
+     *
+     * @default true (spec-compliant JSON responses)
+     */
+    enableJsonResponse?: boolean;
+    /**
+     * Event store for stream resumability.
+     *
+     * When provided, the SDK transport stores events and supports
+     * client reconnection via the `Last-Event-ID` header. Only meaningful
+     * in stateful mode — stateless requests have no persistent streams.
+     *
+     * The SDK provides `InMemoryEventStore` as a reference implementation.
+     * For production horizontal scaling, implement the `EventStore` interface
+     * with Redis, PostgreSQL, or another shared backend.
+     *
+     * @example
+     * ```typescript
+     * import { InMemoryEventStore } from '@modelcontextprotocol/sdk/examples/shared/inMemoryEventStore.js';
+     *
+     * createServer({
+     *   name: 'my-server',
+     *   version: '1.0.0',
+     *   transport: { mode: 'http', eventStore: new InMemoryEventStore() },
+     * });
+     * ```
+     */
+    eventStore?: EventStore;
+    /**
+     * CORS allowed origins.
+     *
+     * When set, CORS middleware is mounted globally and allows requests
+     * from the listed origins. When omitted, CORS is disabled.
+     *
+     * Use `['*']` to allow all origins (not recommended for production).
+     *
+     * Can also be configured via `MCP_CORS_ORIGIN` env var (comma-separated)
+     * or `[security] cors_origin` in the config file.
+     *
+     * @example ['https://app.example.com', 'https://admin.example.com']
+     */
+    corsOrigin?: string[];
+    /**
+     * Allow credentials in CORS requests (cookies, auth headers).
+     *
+     * Only effective when `corsOrigin` is set.
+     * Cannot be used with `corsOrigin: ['*']`.
+     *
+     * Can also be configured via `MCP_CORS_CREDENTIALS` env var.
+     *
+     * @default false
+     */
+    corsCredentials?: boolean;
+    /**
+     * Enable HTTP Strict Transport Security (HSTS) header.
+     *
+     * When true, Helmet sets `Strict-Transport-Security` with `max-age=15552000`
+     * (180 days) and `includeSubDomains`. Only enable when serving over HTTPS.
+     *
+     * Can also be configured via `MCP_HELMET_HSTS` env var.
+     *
+     * @default false
+     */
+    helmetHsts?: boolean;
+    /**
+     * Content Security Policy configuration.
+     *
+     * - Omit: Helmet default CSP applies
+     * - `'false'`: Disable CSP entirely
+     * - Custom string: CSP directives (e.g. `"default-src 'self'; script-src 'none'"`)
+     *
+     * Can also be configured via `MCP_HELMET_CSP` env var.
+     */
+    helmetCsp?: string;
+    /**
+     * X-Frame-Options header value.
+     *
+     * - `'DENY'` — Never allow framing (most secure)
+     * - `'SAMEORIGIN'` — Allow from same origin
+     * - `'false'` — Disable X-Frame-Options header
+     *
+     * Can also be configured via `MCP_HELMET_FRAME_OPTIONS` env var.
+     *
+     * @default 'DENY'
+     */
+    helmetFrameOptions?: "DENY" | "SAMEORIGIN" | "false";
+}
+/**
+ * Stdio transport — single-client CLI mode.
+ *
+ * No HTTP options are available. Uses stdin/stdout for MCP protocol data.
+ */
+export interface StdioTransportOptions {
+    mode: "stdio";
+}
+/**
+ * HTTP transport — multi-client mode without TLS.
+ *
+ * Use behind a reverse proxy that handles TLS termination,
+ * or for local development.
+ */
+export interface HttpTransportOptions extends BaseHttpTransportOptions {
+    mode: "http";
+}
+/**
+ * HTTPS transport — multi-client mode with TLS.
+ *
+ * Requires TLS certificate configuration. Use for direct TLS termination
+ * without a reverse proxy.
+ */
+export interface HttpsTransportOptions extends BaseHttpTransportOptions {
+    mode: "https";
+    /**
+     * TLS configuration (required for HTTPS mode).
+     *
+     * Can also be configured via environment variables:
+     * - MCP_TLS_CERT_PATH
+     * - MCP_TLS_KEY_PATH
+     * - MCP_TLS_CA_PATH (optional)
+     */
+    tls: TlsConfig;
+}
+/**
+ * Transport configuration — discriminated union by `mode`.
+ *
+ * TypeScript narrows the available options based on the selected mode:
+ * - `{ mode: 'stdio' }` — no additional options
+ * - `{ mode: 'http', port: 8000, ... }` — flat HTTP options
+ * - `{ mode: 'https', port: 8443, tls: { ... }, ... }` — flat HTTPS options with required TLS
+ *
+ * @example
+ * ```typescript
+ * // Stdio
+ * transport: { mode: 'stdio' }
+ *
+ * // HTTP
+ * transport: { mode: 'http', port: 8000, host: '0.0.0.0' }
+ *
+ * // HTTPS
+ * transport: { mode: 'https', port: 8443, tls: { certPath: '/certs/cert.pem', keyPath: '/certs/key.pem' } }
+ * ```
+ */
+export type TransportOptions = StdioTransportOptions | HttpTransportOptions | HttpsTransportOptions;
+/**
+ * Type guard: checks whether the transport is an HTTP-based mode (http or https).
+ *
+ * After this guard, TypeScript narrows to `HttpTransportOptions | HttpsTransportOptions`,
+ * allowing direct access to `port`, `host`, `stateless`, etc.
+ */
+export declare function isHttpTransport(transport: TransportOptions): transport is HttpTransportOptions | HttpsTransportOptions;
+//# sourceMappingURL=transport-options.d.ts.map

package/build/server/transport-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-options.d.ts","sourceRoot":"","sources":["../../src/server/transport-options.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oDAAoD,CAAC;AAMrF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,2CAA2C;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;;;;;;OAeG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAIxB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC;CACtD;AAID;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAqB,SAAQ,wBAAwB;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAsB,SAAQ,wBAAwB;IACrE,IAAI,EAAE,OAAO,CAAC;IAEd;;;;;;;OAOG;IACH,GAAG,EAAE,SAAS,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,GAAG,oBAAoB,GAAG,qBAAqB,CAAC;AAEpG;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,gBAAgB,GAC1B,SAAS,IAAI,oBAAoB,GAAG,qBAAqB,CAE3D"}

package/build/server/transport-options.js

@@ -0,0 +1,18 @@
+/**
+ * Transport Configuration Types
+ *
+ * User-facing transport configuration types for the MCP server.
+ * These types define how consumers configure transport mode, TLS, HTTP options, etc.
+ *
+ * @module server/transport-options
+ */
+/**
+ * Type guard: checks whether the transport is an HTTP-based mode (http or https).
+ *
+ * After this guard, TypeScript narrows to `HttpTransportOptions | HttpsTransportOptions`,
+ * allowing direct access to `port`, `host`, `stateless`, etc.
+ */
+export function isHttpTransport(transport) {
+    return transport.mode === "http" || transport.mode === "https";
+}
+//# sourceMappingURL=transport-options.js.map

package/build/server/transport-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-options.js","sourceRoot":"","sources":["../../src/server/transport-options.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0QH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,SAA2B;IAE3B,OAAO,SAAS,CAAC,IAAI,KAAK,MAAM,IAAI,SAAS,CAAC,IAAI,KAAK,OAAO,CAAC;AACjE,CAAC"}