@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/mcp-server/transports/http/sessionStore.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Simple in-memory session store for MCP HTTP transport.
+ * Implements session management as per MCP Spec 2025-06-18.
+ * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#session-management | MCP Session Management}
+ * @module src/mcp-server/transports/http/sessionStore
+ */
+/**
+ * Identity information for binding sessions to authenticated users.
+ * Used to prevent session hijacking across tenants/clients.
+ */
+export interface SessionIdentity {
+    /** Client ID from JWT 'cid'/'client_id' claim */
+    clientId?: string;
+    /** Subject from JWT 'sub' claim */
+    subject?: string;
+    /** Tenant ID from JWT 'tid' claim */
+    tenantId?: string;
+}
+/**
+ * Represents a stateful MCP session with identity binding.
+ * Sessions are bound to the authenticated identity to prevent hijacking.
+ */
+interface Session {
+    clientId?: string;
+    createdAt: Date;
+    id: string;
+    lastAccessedAt: Date;
+    subject?: string;
+    tenantId?: string;
+}
+/**
+ * Simple in-memory session store for stateful MCP sessions.
+ * In production, consider using Redis or another persistent store.
+ */
+export declare class SessionStore {
+    private sessions;
+    private staleTimeout;
+    private cleanupInterval;
+    constructor(staleTimeoutMs: number);
+    /**
+     * Stops the cleanup interval and clears all sessions.
+     * Call this during transport shutdown to prevent resource leaks.
+     */
+    destroy(): void;
+    /**
+     * Creates or retrieves a session with optional identity binding.
+     * If identity is provided, binds the session to prevent cross-tenant/client hijacking.
+     *
+     * @param sessionId - The session identifier
+     * @param identity - Optional identity info (tenantId, clientId, subject)
+     * @returns The session object
+     * @throws {McpError} If session ID format is invalid
+     */
+    getOrCreate(sessionId: string, identity?: SessionIdentity): Session;
+    /**
+     * Validates a session with identity binding checks.
+     * Prevents session hijacking by verifying the session belongs to the requesting identity.
+     *
+     * Security checks:
+     * 1. Session existence
+     * 2. Staleness timeout
+     * 3. Tenant ID match (if session has tenantId)
+     * 4. Client ID match (if session has clientId)
+     * 5. Subject match (if session has subject)
+     *
+     * @param sessionId - The session identifier
+     * @param identity - The identity to validate against (from auth)
+     * @returns True if session is valid and matches identity
+     */
+    isValidForIdentity(sessionId: string, identity?: SessionIdentity): boolean;
+    /**
+     * Terminates a session.
+     * @param sessionId - The session identifier
+     */
+    terminate(sessionId: string): void;
+    /**
+     * Cleans up stale sessions that haven't been accessed recently.
+     */
+    private cleanupStaleSessions;
+    /**
+     * Gets the current number of active sessions.
+     * @returns The number of sessions
+     */
+    getSessionCount(): number;
+}
+export {};
+//# sourceMappingURL=sessionStore.d.ts.map

package/dist/mcp-server/transports/http/sessionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionStore.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/http/sessionStore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,UAAU,OAAO;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,eAAe,CAAiC;gBAE5C,cAAc,EAAE,MAAM;IAOlC;;;OAGG;IACH,OAAO,IAAI,IAAI;IAKf;;;;;;;;OAQG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO;IA2DnE;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO;IA8D1E;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAWlC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;;OAGG;IACH,eAAe,IAAI,MAAM;CAG1B"}

package/dist/mcp-server/transports/http/sessionStore.js

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Simple in-memory session store for MCP HTTP transport.
+ * Implements session management as per MCP Spec 2025-06-18.
+ * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#session-management | MCP Session Management}
+ * @module src/mcp-server/transports/http/sessionStore
+ */
+import { validateSessionIdFormat } from '../../../mcp-server/transports/http/sessionIdUtils.js';
+import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+/**
+ * Simple in-memory session store for stateful MCP sessions.
+ * In production, consider using Redis or another persistent store.
+ */
+export class SessionStore {
+    sessions = new Map();
+    staleTimeout;
+    cleanupInterval;
+    constructor(staleTimeoutMs) {
+        this.staleTimeout = staleTimeoutMs;
+        // Clean up stale sessions every minute. unref() prevents blocking graceful shutdown.
+        this.cleanupInterval = setInterval(() => this.cleanupStaleSessions(), 60_000);
+        this.cleanupInterval.unref?.();
+    }
+    /**
+     * Stops the cleanup interval and clears all sessions.
+     * Call this during transport shutdown to prevent resource leaks.
+     */
+    destroy() {
+        clearInterval(this.cleanupInterval);
+        this.sessions.clear();
+    }
+    /**
+     * Creates or retrieves a session with optional identity binding.
+     * If identity is provided, binds the session to prevent cross-tenant/client hijacking.
+     *
+     * @param sessionId - The session identifier
+     * @param identity - Optional identity info (tenantId, clientId, subject)
+     * @returns The session object
+     * @throws {McpError} If session ID format is invalid
+     */
+    getOrCreate(sessionId, identity) {
+        // Validate session ID format to prevent injection attacks
+        if (!validateSessionIdFormat(sessionId)) {
+            const context = requestContextService.createRequestContext({
+                operation: 'SessionStore.getOrCreate',
+                sessionIdPrefix: sessionId.substring(0, 16),
+            });
+            logger.warning('Invalid session ID format rejected', context);
+            throw new McpError(JsonRpcErrorCode.InvalidParams, 'Invalid session ID format. Session IDs must be 64 hexadecimal characters.', context);
+        }
+        let session = this.sessions.get(sessionId);
+        if (!session) {
+            // Build session object conditionally to satisfy exactOptionalPropertyTypes
+            const newSession = {
+                id: sessionId,
+                createdAt: new Date(),
+                lastAccessedAt: new Date(),
+            };
+            // Only set identity fields if they have actual values (not undefined)
+            if (identity?.tenantId)
+                newSession.tenantId = identity.tenantId;
+            if (identity?.clientId)
+                newSession.clientId = identity.clientId;
+            if (identity?.subject)
+                newSession.subject = identity.subject;
+            session = newSession;
+            this.sessions.set(sessionId, session);
+            const context = requestContextService.createRequestContext({
+                operation: 'SessionStore.create',
+                sessionId,
+                tenantId: identity?.tenantId,
+            });
+            logger.debug('Session created with identity binding', context);
+        }
+        else {
+            session.lastAccessedAt = new Date();
+            // Bind identity on first authenticated request (lazy binding)
+            // This handles sessions created before authentication
+            if (identity && !session.tenantId) {
+                if (identity.tenantId)
+                    session.tenantId = identity.tenantId;
+                if (identity.clientId)
+                    session.clientId = identity.clientId;
+                if (identity.subject)
+                    session.subject = identity.subject;
+                const context = requestContextService.createRequestContext({
+                    operation: 'SessionStore.bindIdentity',
+                    sessionId,
+                    tenantId: identity.tenantId,
+                });
+                logger.debug('Session identity bound on authenticated request', context);
+            }
+        }
+        return session;
+    }
+    /**
+     * Validates a session with identity binding checks.
+     * Prevents session hijacking by verifying the session belongs to the requesting identity.
+     *
+     * Security checks:
+     * 1. Session existence
+     * 2. Staleness timeout
+     * 3. Tenant ID match (if session has tenantId)
+     * 4. Client ID match (if session has clientId)
+     * 5. Subject match (if session has subject)
+     *
+     * @param sessionId - The session identifier
+     * @param identity - The identity to validate against (from auth)
+     * @returns True if session is valid and matches identity
+     */
+    isValidForIdentity(sessionId, identity) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        // Check staleness
+        if (Date.now() - session.lastAccessedAt.getTime() > this.staleTimeout) {
+            this.terminate(sessionId);
+            return false;
+        }
+        // If session has no identity bound, allow (backwards compatibility / no-auth mode)
+        if (!session.tenantId && !session.clientId && !session.subject) {
+            return true;
+        }
+        // Lazy-create context only when a warning is likely
+        const warn = (message, extra) => {
+            const context = requestContextService.createRequestContext({
+                operation: 'SessionStore.isValidForIdentity',
+                sessionId,
+            });
+            logger.warning(message, extra ? { ...context, ...extra } : context);
+        };
+        // If request has no identity but session does, reject (security: session was authenticated)
+        if (!identity) {
+            warn('Session requires authentication but request has no identity');
+            return false;
+        }
+        // Verify tenant ID match — reject if session is bound but request lacks or mismatches
+        if (session.tenantId && session.tenantId !== identity.tenantId) {
+            warn('Session tenant mismatch - possible hijacking attempt', {
+                sessionTenant: session.tenantId,
+                requestTenant: identity.tenantId,
+            });
+            return false;
+        }
+        // Verify client ID match — reject if session is bound but request lacks or mismatches
+        if (session.clientId && session.clientId !== identity.clientId) {
+            warn('Session client mismatch - possible hijacking attempt', {
+                sessionClient: session.clientId,
+                requestClient: identity.clientId,
+            });
+            return false;
+        }
+        // Verify subject match — reject if session is bound but request lacks or mismatches
+        if (session.subject && session.subject !== identity.subject) {
+            warn('Session subject mismatch - possible hijacking attempt', {
+                sessionSubject: session.subject,
+                requestSubject: identity.subject,
+            });
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Terminates a session.
+     * @param sessionId - The session identifier
+     */
+    terminate(sessionId) {
+        const deleted = this.sessions.delete(sessionId);
+        if (deleted) {
+            const context = requestContextService.createRequestContext({
+                operation: 'SessionStore.terminate',
+                sessionId,
+            });
+            logger.info('Session terminated', context);
+        }
+    }
+    /**
+     * Cleans up stale sessions that haven't been accessed recently.
+     */
+    cleanupStaleSessions() {
+        const now = Date.now();
+        let cleanedCount = 0;
+        for (const [id, session] of this.sessions.entries()) {
+            if (now - session.lastAccessedAt.getTime() > this.staleTimeout) {
+                this.sessions.delete(id);
+                cleanedCount++;
+            }
+        }
+        if (cleanedCount > 0) {
+            const context = requestContextService.createRequestContext({
+                operation: 'SessionStore.cleanup',
+            });
+            logger.debug('Cleaned up stale sessions', {
+                ...context,
+                count: cleanedCount,
+            });
+        }
+    }
+    /**
+     * Gets the current number of active sessions.
+     * @returns The number of sessions
+     */
+    getSessionCount() {
+        return this.sessions.size;
+    }
+}
+//# sourceMappingURL=sessionStore.js.map

package/dist/mcp-server/transports/http/sessionStore.js.map

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

package/dist/mcp-server/transports/manager.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Manages the lifecycle of the configured MCP transport.
+ * @module src/mcp-server/transports/manager
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AppConfig as AppConfigType } from '../../config/index.js';
+import type { TaskManager } from '../../mcp-server/tasks/core/taskManager.js';
+import type { TransportServer } from '../../mcp-server/transports/ITransport.js';
+import type { logger as LoggerType } from '../../utils/internal/logger.js';
+export declare class TransportManager {
+    private config;
+    private logger;
+    private createMcpServer;
+    private taskManager;
+    private serverInstance;
+    private shutdown;
+    constructor(config: AppConfigType, logger: typeof LoggerType, createMcpServer: () => Promise<McpServer>, taskManager: TaskManager);
+    start(): Promise<void>;
+    stop(signal: string): Promise<void>;
+    getServer(): TransportServer | null;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/mcp-server/transports/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/transports/manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAE1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAK7E,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAIvE,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,WAAW;IAPrB,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAA6D;gBAGnE,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,OAAO,UAAU,EACzB,eAAe,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EACzC,WAAW,EAAE,WAAW;IAG5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BtB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzC,SAAS,IAAI,eAAe,GAAG,IAAI;CAGpC"}

package/dist/mcp-server/transports/manager.js

@@ -0,0 +1,62 @@
+import { startHttpTransport } from '../../mcp-server/transports/http/httpTransport.js';
+import { startStdioTransport, stopStdioTransport, } from '../../mcp-server/transports/stdio/stdioTransport.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+export class TransportManager {
+    config;
+    logger;
+    createMcpServer;
+    taskManager;
+    serverInstance = null;
+    shutdown = null;
+    constructor(config, logger, createMcpServer, taskManager) {
+        this.config = config;
+        this.logger = logger;
+        this.createMcpServer = createMcpServer;
+        this.taskManager = taskManager;
+    }
+    async start() {
+        const context = requestContextService.createRequestContext({
+            operation: 'TransportManager.start',
+            transport: this.config.mcpTransportType,
+        });
+        this.logger.info(`Starting transport: ${this.config.mcpTransportType}`, context);
+        if (this.config.mcpTransportType === 'http') {
+            // HTTP: pass factory so each request gets a fresh McpServer+transport pair
+            // (SDK 1.26.0 security fix — GHSA-345p-7cg4-v4c7)
+            const handle = await startHttpTransport(this.createMcpServer, context);
+            this.serverInstance = handle.server;
+            this.shutdown = (ctx) => handle.stop(ctx);
+        }
+        else if (this.config.mcpTransportType === 'stdio') {
+            // Stdio: single client, single connection — one server instance is correct
+            const mcpServer = await this.createMcpServer();
+            this.serverInstance = await startStdioTransport(mcpServer, context);
+            this.shutdown = (ctx) => stopStdioTransport(mcpServer, ctx);
+        }
+        else {
+            const transportType = String(this.config.mcpTransportType);
+            const error = new Error(`Unsupported transport type: ${transportType}`);
+            this.logger.crit(error.message, context);
+            throw error;
+        }
+    }
+    async stop(signal) {
+        const context = requestContextService.createRequestContext({
+            operation: 'TransportManager.stop',
+            signal,
+        });
+        if (!this.shutdown) {
+            this.logger.warning('Stop called but no active server instance found.', context);
+            return;
+        }
+        await this.shutdown(context);
+        // Clean up task manager timers to allow clean process exit
+        this.taskManager.cleanup();
+        this.serverInstance = null;
+        this.shutdown = null;
+    }
+    getServer() {
+        return this.serverInstance;
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/mcp-server/transports/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/mcp-server/transports/manager.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AAEnF,OAAO,EACL,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,iDAAiD,CAAC;AAGzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAE3E,MAAM,OAAO,gBAAgB;IAKjB;IACA;IACA;IACA;IAPF,cAAc,GAA2B,IAAI,CAAC;IAC9C,QAAQ,GAAwD,IAAI,CAAC;IAE7E,YACU,MAAqB,EACrB,MAAyB,EACzB,eAAyC,EACzC,WAAwB;QAHxB,WAAM,GAAN,MAAM,CAAe;QACrB,WAAM,GAAN,MAAM,CAAmB;QACzB,oBAAe,GAAf,eAAe,CAA0B;QACzC,gBAAW,GAAX,WAAW,CAAa;IAC/B,CAAC;IAEJ,KAAK,CAAC,KAAK;QACT,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,wBAAwB;YACnC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB;SACxC,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,uBAAuB,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,EAAE,OAAO,CAAC,CAAC;QAEjF,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,KAAK,MAAM,EAAE,CAAC;YAC5C,2EAA2E;YAC3E,kDAAkD;YAClD,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;YACvE,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;YACpC,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,KAAK,OAAO,EAAE,CAAC;YACpD,2EAA2E;YAC3E,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;YAC/C,IAAI,CAAC,cAAc,GAAG,MAAM,mBAAmB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACpE,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAC9D,CAAC;aAAM,CAAC;YACN,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAC3D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,+BAA+B,aAAa,EAAE,CAAC,CAAC;YACxE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,MAAM,OAAO,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACzD,SAAS,EAAE,uBAAuB;YAClC,MAAM;SACP,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,kDAAkD,EAAE,OAAO,CAAC,CAAC;YACjF,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAE7B,2DAA2D;QAC3D,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;QAE3B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/dist/mcp-server/transports/stdio/stdioTransport.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Handles the setup and connection for the Stdio MCP transport.
+ * Implements the MCP Specification 2025-06-18 for stdio transport.
+ * This transport communicates directly over standard input (stdin) and
+ * standard output (stdout), typically used when the MCP server is launched
+ * as a child process by a host application.
+ *
+ * Specification Reference:
+ * https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio
+ *
+ * --- Authentication Note ---
+ * As per the MCP Authorization Specification (2025-06-18, Section 1.2),
+ * STDIO transports SHOULD NOT implement HTTP-based authentication flows.
+ * Authorization is typically handled implicitly by the host application
+ * controlling the server process. This implementation follows that guideline.
+ *
+ * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization | MCP Authorization Specification}
+ * @module src/mcp-server/transports/stdioTransport
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RequestContext } from '../../../utils/internal/requestContext.js';
+/**
+ * Connects a given `McpServer` instance to the Stdio transport.
+ * This function initializes the SDK's `StdioServerTransport`, which manages
+ * communication over `process.stdin` and `process.stdout` according to the
+ * MCP stdio transport specification.
+ *
+ * MCP Spec Points Covered by SDK's `StdioServerTransport`:
+ * - Reads JSON-RPC messages (requests, notifications, responses, batches) from stdin.
+ * - Writes JSON-RPC messages to stdout.
+ * - Handles newline delimiters and ensures no embedded newlines in output messages.
+ * - Ensures only valid MCP messages are written to stdout.
+ *
+ * Logging via the `logger` utility MAY result in output to stderr, which is
+ * permitted by the spec for logging purposes.
+ *
+ * @param server - The `McpServer` instance.
+ * @param parentContext - The logging and tracing context from the calling function.
+ * @returns A promise that resolves when the Stdio transport is successfully connected.
+ * @throws {Error} If the connection fails during setup.
+ */
+export declare function startStdioTransport(server: McpServer, parentContext: RequestContext): Promise<McpServer>;
+export declare function stopStdioTransport(server: McpServer, parentContext: RequestContext): Promise<void>;
+//# sourceMappingURL=stdioTransport.d.ts.map

package/dist/mcp-server/transports/stdio/stdioTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdioTransport.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/transports/stdio/stdioTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,SAAS,EACjB,aAAa,EAAE,cAAc,GAC5B,OAAO,CAAC,SAAS,CAAC,CA8BpB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,aAAa,EAAE,cAAc,GAC5B,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/mcp-server/transports/stdio/stdioTransport.js

@@ -0,0 +1,63 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { logStartupBanner } from '../../../utils/internal/startupBanner.js';
+/**
+ * Connects a given `McpServer` instance to the Stdio transport.
+ * This function initializes the SDK's `StdioServerTransport`, which manages
+ * communication over `process.stdin` and `process.stdout` according to the
+ * MCP stdio transport specification.
+ *
+ * MCP Spec Points Covered by SDK's `StdioServerTransport`:
+ * - Reads JSON-RPC messages (requests, notifications, responses, batches) from stdin.
+ * - Writes JSON-RPC messages to stdout.
+ * - Handles newline delimiters and ensures no embedded newlines in output messages.
+ * - Ensures only valid MCP messages are written to stdout.
+ *
+ * Logging via the `logger` utility MAY result in output to stderr, which is
+ * permitted by the spec for logging purposes.
+ *
+ * @param server - The `McpServer` instance.
+ * @param parentContext - The logging and tracing context from the calling function.
+ * @returns A promise that resolves when the Stdio transport is successfully connected.
+ * @throws {Error} If the connection fails during setup.
+ */
+export async function startStdioTransport(server, parentContext) {
+    const operationContext = {
+        ...parentContext,
+        operation: 'connectStdioTransport',
+        transportType: 'Stdio',
+    };
+    logger.info('Attempting to connect stdio transport...', operationContext);
+    try {
+        logger.debug('Creating StdioServerTransport instance...', operationContext);
+        const transport = new StdioServerTransport();
+        logger.debug('Connecting McpServer instance to StdioServerTransport...', operationContext);
+        await server.connect(transport);
+        logger.info('MCP Server connected and listening via stdio transport.', operationContext);
+        logStartupBanner(`\n🚀 MCP Server running in STDIO mode.\n   (MCP Spec: 2025-06-18 Stdio Transport)\n`, 'stdio');
+        return server;
+    }
+    catch (err) {
+        // Let the ErrorHandler log the error with all context, then rethrow.
+        throw ErrorHandler.handleError(err, {
+            operation: 'connectStdioTransport',
+            context: operationContext,
+            critical: true,
+            rethrow: true,
+        });
+    }
+}
+export async function stopStdioTransport(server, parentContext) {
+    const operationContext = {
+        ...parentContext,
+        operation: 'stopStdioTransport',
+        transportType: 'Stdio',
+    };
+    logger.info('Attempting to stop stdio transport...', operationContext);
+    if (server) {
+        await server.close();
+        logger.info('Stdio transport stopped successfully.', operationContext);
+    }
+}
+//# sourceMappingURL=stdioTransport.js.map

package/dist/mcp-server/transports/stdio/stdioTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdioTransport.js","sourceRoot":"","sources":["../../../../src/mcp-server/transports/stdio/stdioTransport.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,gDAAgD,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAiB,EACjB,aAA6B;IAE7B,MAAM,gBAAgB,GAAG;QACvB,GAAG,aAAa;QAChB,SAAS,EAAE,uBAAuB;QAClC,aAAa,EAAE,OAAO;KACvB,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,0CAA0C,EAAE,gBAAgB,CAAC,CAAC;IAE1E,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,CAAC,2CAA2C,EAAE,gBAAgB,CAAC,CAAC;QAC5E,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAE7C,MAAM,CAAC,KAAK,CAAC,0DAA0D,EAAE,gBAAgB,CAAC,CAAC;QAC3F,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEhC,MAAM,CAAC,IAAI,CAAC,yDAAyD,EAAE,gBAAgB,CAAC,CAAC;QACzF,gBAAgB,CACd,qFAAqF,EACrF,OAAO,CACR,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,qEAAqE;QACrE,MAAM,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE;YAClC,SAAS,EAAE,uBAAuB;YAClC,OAAO,EAAE,gBAAgB;YACzB,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,IAAI;SACd,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAiB,EACjB,aAA6B;IAE7B,MAAM,gBAAgB,GAAG;QACvB,GAAG,aAAa;QAChB,SAAS,EAAE,oBAAoB;QAC/B,aAAa,EAAE,OAAO;KACvB,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,uCAAuC,EAAE,gBAAgB,CAAC,CAAC;IACvE,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,CAAC,uCAAuC,EAAE,gBAAgB,CAAC,CAAC;IACzE,CAAC;AACH,CAAC"}