@cyanheads/git-mcp-server 2.0.1 → 2.0.3

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

@@ -0,0 +1,432 @@
+/**
+ * Handles the setup and management of the Streamable HTTP MCP transport.
+ * Implements the MCP Specification 2025-03-26 for Streamable HTTP.
+ * Includes Express server creation, middleware (CORS, Auth), request routing
+ * (POST/GET/DELETE on a single endpoint), session handling, SSE streaming,
+ * and port binding with retry logic.
+ *
+ * Specification Reference:
+ * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#streamable-http
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'; // SDK type guard for InitializeRequest
+import express from 'express';
+import http from 'http';
+import { randomUUID } from 'node:crypto';
+// Import config and utils
+import { config } from '../../config/index.js'; // Import the validated config object
+import { logger } from '../../utils/index.js';
+import { mcpAuthMiddleware } from './authentication/authMiddleware.js'; // Import the auth middleware
+// --- Configuration Constants (Derived from imported config) ---
+/**
+ * The port number for the HTTP transport, configured via MCP_HTTP_PORT.
+ * Defaults to 3010 (defined in config/index.ts).
+ * @constant {number} HTTP_PORT
+ */
+const HTTP_PORT = config.mcpHttpPort;
+/**
+ * The host address for the HTTP transport, configured via MCP_HTTP_HOST.
+ * Defaults to '127.0.0.1' (defined in config/index.ts).
+ * MCP Spec Security: Recommends binding to localhost for local servers.
+ * @constant {string} HTTP_HOST
+ */
+const HTTP_HOST = config.mcpHttpHost;
+/**
+ * The single HTTP endpoint path for all MCP communication, as required by the spec.
+ * Supports POST, GET, DELETE, OPTIONS methods.
+ * @constant {string} MCP_ENDPOINT_PATH
+ */
+const MCP_ENDPOINT_PATH = '/mcp';
+/**
+ * Maximum number of attempts to find an available port if the initial HTTP_PORT is in use.
+ * Tries ports sequentially: HTTP_PORT, HTTP_PORT + 1, ...
+ * @constant {number} MAX_PORT_RETRIES
+ */
+const MAX_PORT_RETRIES = 15;
+/**
+ * Stores active StreamableHTTPServerTransport instances, keyed by their session ID.
+ * Essential for routing subsequent requests to the correct stateful session.
+ * @type {Record<string, StreamableHTTPServerTransport>}
+ */
+const httpTransports = {};
+/** Stores the working directory for each active HTTP session. */
+const sessionWorkingDirectories = new Map();
+/**
+ * Gets the current working directory set for a specific HTTP session.
+ * @param {string} sessionId - The ID of the session.
+ * @returns {string | undefined} The current working directory path or undefined if not set.
+ */
+export function getHttpSessionWorkingDirectory(sessionId) {
+    return sessionWorkingDirectories.get(sessionId);
+}
+/**
+ * Sets the working directory for a specific HTTP session.
+ * @param {string} sessionId - The ID of the session.
+ * @param {string} dir - The new working directory path.
+ */
+export function setHttpSessionWorkingDirectory(sessionId, dir) {
+    sessionWorkingDirectories.set(sessionId, dir);
+    logger.info(`HTTP session ${sessionId} working directory set to: ${dir}`, { operation: 'setHttpSessionWorkingDirectory', sessionId });
+}
+/**
+ * Checks if an incoming HTTP request's origin header is permissible.
+ * MCP Spec Security: Servers MUST validate the `Origin` header.
+ * This function checks against `MCP_ALLOWED_ORIGINS` and allows requests
+ * from localhost if the server is bound locally. Sets CORS headers if allowed.
+ *
+ * @param {Request} req - Express request object.
+ * @param {Response} res - Express response object.
+ * @returns {boolean} True if the origin is allowed, false otherwise.
+ */
+function isOriginAllowed(req, res) {
+    const origin = req.headers.origin;
+    const host = req.hostname; // Considers Host header
+    const isLocalhostBinding = ['127.0.0.1', '::1', 'localhost'].includes(host);
+    const allowedOrigins = config.mcpAllowedOrigins || []; // Use parsed array from config
+    const context = { operation: 'isOriginAllowed', origin, host, isLocalhostBinding, allowedOrigins };
+    logger.debug('Checking origin allowance', context);
+    // Determine if allowed based on config or localhost binding
+    const allowed = (origin && allowedOrigins.includes(origin)) || (isLocalhostBinding && (!origin || origin === 'null'));
+    if (allowed && origin) {
+        // Origin is allowed and present, set specific CORS headers.
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        // MCP Spec: Streamable HTTP uses POST, GET, DELETE. OPTIONS is for preflight.
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        // MCP Spec: Requires Mcp-Session-Id. Last-Event-ID for SSE resumption. Content-Type is standard. Authorization for security.
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id, Last-Event-ID, Authorization');
+        res.setHeader('Access-Control-Allow-Credentials', 'true'); // Set based on whether auth/cookies are used
+    }
+    else if (allowed && !origin) {
+        // Allowed (e.g., localhost binding, file:// origin), but no origin header to echo back. No specific CORS needed.
+    }
+    else if (!allowed && origin) {
+        // Origin provided but not in allowed list. Log warning.
+        logger.warning(`Origin denied: ${origin}`, context);
+    }
+    logger.debug(`Origin check result: ${allowed}`, { ...context, allowed });
+    return allowed;
+}
+/**
+ * Proactively checks if a specific port is already in use. (Asynchronous)
+ * @param {number} port - Port to check.
+ * @param {string} host - Host address to check.
+ * @param {Record<string, any>} context - Logging context.
+ * @returns {Promise<boolean>} True if port is in use (EADDRINUSE), false otherwise.
+ */
+async function isPortInUse(port, host, context) {
+    const checkContext = { ...context, operation: 'isPortInUse', port, host };
+    logger.debug(`Proactively checking port usability...`, checkContext);
+    return new Promise((resolve) => {
+        const tempServer = http.createServer();
+        tempServer
+            .once('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                logger.debug(`Proactive check: Port confirmed in use (EADDRINUSE).`, checkContext);
+                resolve(true); // Port is definitely in use
+            }
+            else {
+                logger.debug(`Proactive check: Non-EADDRINUSE error encountered: ${err.message}`, { ...checkContext, errorCode: err.code });
+                resolve(false); // Other error, let main listen attempt handle it
+            }
+        })
+            .once('listening', () => {
+            logger.debug(`Proactive check: Port is available.`, checkContext);
+            tempServer.close(() => resolve(false)); // Port is free
+        })
+            .listen(port, host);
+    });
+}
+/**
+ * Attempts to start the HTTP server, retrying on incrementing ports if EADDRINUSE occurs. (Asynchronous)
+ * Uses proactive checks before attempting to bind the main server instance.
+ *
+ * @param {http.Server} serverInstance - The Node.js HTTP server instance.
+ * @param {number} initialPort - The starting port number.
+ * @param {string} host - The host address to bind to.
+ * @param {number} maxRetries - Maximum number of additional ports to try.
+ * @param {Record<string, any>} context - Logging context.
+ * @returns {Promise<number>} Resolves with the port number successfully bound to.
+ * @throws {Error} Rejects if binding fails after all retries or for non-EADDRINUSE errors.
+ */
+function startHttpServerWithRetry(serverInstance, initialPort, host, maxRetries, context) {
+    const startContext = { ...context, operation: 'startHttpServerWithRetry', initialPort, host, maxRetries };
+    logger.debug(`Attempting to start HTTP server...`, startContext);
+    return new Promise(async (resolve, reject) => {
+        let lastError = null;
+        for (let i = 0; i <= maxRetries; i++) {
+            const currentPort = initialPort + i;
+            const attemptContext = { ...startContext, port: currentPort, attempt: i + 1, maxAttempts: maxRetries + 1 };
+            logger.debug(`Attempting port ${currentPort} (${attemptContext.attempt}/${attemptContext.maxAttempts})`, attemptContext);
+            // 1. Proactive Check
+            if (await isPortInUse(currentPort, host, attemptContext)) {
+                logger.warning(`Proactive check detected port ${currentPort} is in use, retrying...`, attemptContext);
+                lastError = new Error(`EADDRINUSE: Port ${currentPort} detected as in use by proactive check.`);
+                await new Promise(res => setTimeout(res, 100)); // Short delay
+                continue; // Try next port
+            }
+            // 2. Attempt Main Server Bind
+            try {
+                await new Promise((listenResolve, listenReject) => {
+                    serverInstance.listen(currentPort, host, () => {
+                        const serverAddress = `http://${host}:${currentPort}${MCP_ENDPOINT_PATH}`;
+                        logger.info(`HTTP transport successfully listening on host ${host} at ${serverAddress}`, { ...attemptContext, address: serverAddress });
+                        listenResolve(); // Success
+                    }).on('error', (err) => {
+                        listenReject(err); // Forward error
+                    });
+                });
+                resolve(currentPort); // Listen succeeded
+                return; // Exit function
+            }
+            catch (err) {
+                lastError = err;
+                logger.debug(`Listen error on port ${currentPort}: Code=${err.code}, Message=${err.message}`, { ...attemptContext, errorCode: err.code, errorMessage: err.message });
+                if (err.code === 'EADDRINUSE') {
+                    logger.warning(`Port ${currentPort} already in use (EADDRINUSE), retrying...`, attemptContext);
+                    await new Promise(res => setTimeout(res, 100)); // Short delay before retry
+                }
+                else {
+                    logger.error(`Failed to bind to port ${currentPort} due to non-EADDRINUSE error: ${err.message}`, { ...attemptContext, error: err.message });
+                    reject(err); // Non-recoverable error for this port
+                    return; // Exit function
+                }
+            }
+        }
+        // Loop finished without success
+        logger.error(`Failed to bind to any port after ${maxRetries + 1} attempts. Last error: ${lastError?.message}`, { ...startContext, error: lastError?.message });
+        reject(lastError || new Error('Failed to bind to any port after multiple retries.'));
+    });
+}
+/**
+ * Sets up and starts the Streamable HTTP transport layer for MCP. (Asynchronous)
+ * Creates Express app, configures middleware (CORS, Auth, Security Headers),
+ * defines the single MCP endpoint handler for POST/GET/DELETE, manages sessions,
+ * and starts the HTTP server with retry logic.
+ *
+ * @param {() => Promise<McpServer>} createServerInstanceFn - Async factory function to create a new McpServer instance per session.
+ * @param {Record<string, any>} context - Logging context.
+ * @returns {Promise<void>} Resolves when the server is listening, or rejects on failure.
+ * @throws {Error} If the server fails to start after retries.
+ */
+export async function startHttpTransport(createServerInstanceFn, context) {
+    const app = express();
+    const transportContext = { ...context, transportType: 'HTTP' };
+    logger.debug('Setting up Express app for HTTP transport...', transportContext);
+    // Middleware to parse JSON request bodies. Required for MCP messages.
+    app.use(express.json());
+    // --- Security Middleware Pipeline ---
+    // 1. CORS Preflight (OPTIONS) Handler
+    // Handles OPTIONS requests sent by browsers before actual GET/POST/DELETE.
+    app.options(MCP_ENDPOINT_PATH, (req, res) => {
+        const optionsContext = { ...transportContext, operation: 'handleOptions', origin: req.headers.origin };
+        logger.debug(`Received OPTIONS request for ${MCP_ENDPOINT_PATH}`, optionsContext);
+        if (isOriginAllowed(req, res)) {
+            // isOriginAllowed sets necessary Access-Control-* headers.
+            logger.debug('OPTIONS request origin allowed, sending 204.', optionsContext);
+            res.sendStatus(204); // OK, No Content
+        }
+        else {
+            // isOriginAllowed logs the warning.
+            logger.debug('OPTIONS request origin denied, sending 403.', optionsContext);
+            res.status(403).send('Forbidden: Invalid Origin');
+        }
+    });
+    // 2. General Security Headers & Origin Check Middleware (for non-OPTIONS)
+    app.use((req, res, next) => {
+        const securityContext = { ...transportContext, operation: 'securityMiddleware', path: req.path, method: req.method, origin: req.headers.origin };
+        logger.debug(`Applying security middleware...`, securityContext);
+        // Check origin again for non-OPTIONS requests and set CORS headers if allowed.
+        if (!isOriginAllowed(req, res)) {
+            // isOriginAllowed logs the warning.
+            logger.debug('Origin check failed, sending 403.', securityContext);
+            res.status(403).send('Forbidden: Invalid Origin');
+            return; // Block request
+        }
+        // Apply standard security headers to all allowed responses.
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+        // Basic Content Security Policy (CSP). Adjust if server needs external connections.
+        // 'connect-src 'self'' allows connections back to the server's own origin (needed for SSE).
+        res.setHeader("Content-Security-Policy", "default-src 'self'; script-src 'self'; object-src 'none'; style-src 'self'; img-src 'self'; media-src 'self'; frame-src 'none'; font-src 'self'; connect-src 'self'");
+        // Strict-Transport-Security (HSTS) - IMPORTANT: Enable only if server is *always* served over HTTPS.
+        // if (config.environment === 'production') {
+        //   res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains'); // 1 year
+        // }
+        logger.debug('Security middleware passed.', securityContext);
+        next(); // Proceed to next middleware/handler
+    });
+    // 3. MCP Authentication Middleware (Optional, based on config)
+    // Verifies Authorization header (e.g., Bearer token) if enabled.
+    app.use(mcpAuthMiddleware);
+    // --- MCP Route Handlers ---
+    // Handle POST requests: Used for Initialize and all subsequent client->server messages.
+    // MCP Spec: Client MUST use POST. Body is single message or batch.
+    // MCP Spec: Server responds 202 for notification/response-only, or JSON/SSE for requests.
+    app.post(MCP_ENDPOINT_PATH, async (req, res) => {
+        // Define base context for this request
+        const basePostContext = { ...transportContext, operation: 'handlePost', method: 'POST' };
+        logger.debug(`Received POST request on ${MCP_ENDPOINT_PATH}`, { ...basePostContext, headers: req.headers, bodyPreview: JSON.stringify(req.body).substring(0, 100) });
+        // MCP Spec: Session ID MUST be included by client after initialization.
+        const sessionId = req.headers['mcp-session-id'];
+        // Log extracted session ID, adding it to the context for this specific log message
+        logger.debug(`Extracted session ID: ${sessionId}`, { ...basePostContext, sessionId });
+        let transport = sessionId ? httpTransports[sessionId] : undefined;
+        // Log transport lookup result, adding sessionId to context
+        logger.debug(`Found existing transport for session ID: ${!!transport}`, { ...basePostContext, sessionId });
+        // Check if it's an InitializeRequest using SDK helper.
+        const isInitReq = isInitializeRequest(req.body);
+        logger.debug(`Is InitializeRequest: ${isInitReq}`, { ...basePostContext, sessionId });
+        const requestId = req.body?.id || null; // For potential error responses
+        try {
+            // --- Handle Initialization Request ---
+            if (isInitReq) {
+                if (transport) {
+                    // Client sent Initialize on an existing session - likely an error or recovery attempt.
+                    // Close the old session cleanly before creating a new one.
+                    logger.warning('Received InitializeRequest on an existing session ID. Closing old session and creating new.', { ...basePostContext, sessionId });
+                    await transport.close(); // Ensure cleanup
+                    delete httpTransports[sessionId];
+                }
+                logger.info('Handling Initialize Request: Creating new session...', { ...basePostContext, sessionId });
+                // Create new SDK transport instance for this session.
+                transport = new StreamableHTTPServerTransport({
+                    // MCP Spec: Server MAY assign session ID on InitializeResponse via Mcp-Session-Id header.
+                    sessionIdGenerator: () => {
+                        const newId = randomUUID(); // Secure UUID generation
+                        logger.debug(`Generated new session ID: ${newId}`, basePostContext); // Use base context here
+                        return newId;
+                    },
+                    onsessioninitialized: (newId) => {
+                        // Store the transport instance once the session ID is confirmed and sent to client.
+                        logger.debug(`Session initialized callback triggered for ID: ${newId}`, { ...basePostContext, newSessionId: newId });
+                        httpTransports[newId] = transport; // Store by the generated ID
+                        logger.info(`HTTP Session created: ${newId}`, { ...basePostContext, newSessionId: newId });
+                    },
+                });
+                // Define cleanup logic when the transport closes (client disconnect, DELETE, error).
+                transport.onclose = () => {
+                    const closedSessionId = transport.sessionId; // Get ID before potential deletion
+                    // Removed duplicate declaration below
+                    if (closedSessionId) {
+                        logger.debug(`onclose handler triggered for session ID: ${closedSessionId}`, { ...basePostContext, closedSessionId });
+                        delete httpTransports[closedSessionId]; // Remove from active transports
+                        sessionWorkingDirectories.delete(closedSessionId); // Clean up working directory state
+                        logger.info(`HTTP Session closed and state cleaned: ${closedSessionId}`, { ...basePostContext, closedSessionId });
+                    }
+                    else {
+                        logger.debug('onclose handler triggered for transport without session ID (likely init failure).', basePostContext);
+                    }
+                };
+                // Create a dedicated McpServer instance for this new session.
+                logger.debug('Creating McpServer instance for new session...', basePostContext);
+                const server = await createServerInstanceFn();
+                // Connect the server logic to the transport layer.
+                logger.debug('Connecting McpServer to new transport...', basePostContext);
+                await server.connect(transport);
+                logger.debug('McpServer connected to transport.', basePostContext);
+                // NOTE: SDK's connect/handleRequest handles sending the InitializeResult.
+            }
+            else if (!transport) {
+                // --- Handle Non-Initialize Request without Valid Session ---
+                // MCP Spec: Server SHOULD respond 400/404 if session ID is missing/invalid for non-init requests.
+                logger.warning('Invalid or missing session ID for non-initialize POST request.', { ...basePostContext, sessionId });
+                res.status(404).json({ jsonrpc: '2.0', error: { code: -32004, message: 'Invalid or expired session ID' }, id: requestId });
+                return; // Stop processing
+            }
+            // --- Handle Request Content (Initialize or Subsequent Message) ---
+            // Use the extracted sessionId in the context for these logs
+            const currentSessionId = transport.sessionId; // Should be defined here
+            logger.debug(`Processing POST request content for session ${currentSessionId}...`, { ...basePostContext, sessionId: currentSessionId, isInitReq });
+            // Delegate the actual handling (parsing, routing, response/SSE generation) to the SDK transport instance.
+            // The SDK transport handles returning 202 for notification/response-only POSTs internally.
+            await transport.handleRequest(req, res, req.body);
+            logger.debug(`Finished processing POST request content for session ${currentSessionId}.`, { ...basePostContext, sessionId: currentSessionId });
+        }
+        catch (err) {
+            // Catch-all for errors during POST handling.
+            // Include sessionId if available in the transport object at this point
+            const errorSessionId = transport?.sessionId || sessionId; // Use extracted or from transport if available
+            logger.error('Error handling POST request', {
+                ...basePostContext,
+                sessionId: errorSessionId, // Add sessionId to error context
+                isInitReq, // Include isInitReq flag
+                error: err instanceof Error ? err.message : String(err),
+                stack: err instanceof Error ? err.stack : undefined
+            });
+            if (!res.headersSent) {
+                // Send generic JSON-RPC error if possible.
+                res.status(500).json({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal server error during POST handling' }, id: requestId });
+            }
+            // Ensure transport is cleaned up if an error occurred during initialization before session ID assigned.
+            if (isInitReq && transport && !transport.sessionId) {
+                logger.debug('Cleaning up transport after initialization failure.', { ...basePostContext, sessionId: errorSessionId });
+                await transport.close().catch(closeErr => logger.error('Error closing transport after init failure', { ...basePostContext, sessionId: errorSessionId, closeError: closeErr }));
+            }
+        }
+    });
+    // Unified handler for GET (SSE connection) and DELETE (session termination).
+    const handleSessionReq = async (req, res) => {
+        const method = req.method; // GET or DELETE
+        // Define base context for this request
+        const baseSessionReqContext = { ...transportContext, operation: `handle${method}`, method };
+        logger.debug(`Received ${method} request on ${MCP_ENDPOINT_PATH}`, { ...baseSessionReqContext, headers: req.headers });
+        // MCP Spec: Client MUST include Mcp-Session-Id header (after init).
+        const sessionId = req.headers['mcp-session-id'];
+        // Log extracted session ID, adding it to the context for this specific log message
+        logger.debug(`Extracted session ID: ${sessionId}`, { ...baseSessionReqContext, sessionId });
+        const transport = sessionId ? httpTransports[sessionId] : undefined;
+        // Log transport lookup result, adding sessionId to context
+        logger.debug(`Found existing transport for session ID: ${!!transport}`, { ...baseSessionReqContext, sessionId });
+        if (!transport) {
+            // MCP Spec: Server MUST respond 404 if session ID invalid/expired.
+            logger.warning(`Session not found for ${method} request`, { ...baseSessionReqContext, sessionId });
+            res.status(404).send('Session not found or expired');
+            return;
+        }
+        try {
+            // Use the extracted sessionId in the context for these logs
+            logger.debug(`Delegating ${method} request to transport for session ${sessionId}...`, { ...baseSessionReqContext, sessionId });
+            // MCP Spec (GET): Client MAY issue GET to open SSE stream. Server MUST respond text/event-stream or 405.
+            // MCP Spec (GET): Client SHOULD include Last-Event-ID for resumption. Resumption handling depends on SDK transport.
+            // MCP Spec (DELETE): Client SHOULD send DELETE to terminate. Server MAY respond 405 if not supported.
+            // This implementation supports DELETE via the SDK transport's handleRequest.
+            await transport.handleRequest(req, res);
+            logger.info(`Successfully handled ${method} request for session ${sessionId}`, { ...baseSessionReqContext, sessionId });
+            // Note: For DELETE, the transport's handleRequest should trigger the 'onclose' handler for cleanup.
+        }
+        catch (err) {
+            // Include sessionId in error context
+            logger.error(`Error handling ${method} request for session ${sessionId}`, {
+                ...baseSessionReqContext,
+                sessionId, // Add sessionId here
+                error: err instanceof Error ? err.message : String(err),
+                stack: err instanceof Error ? err.stack : undefined
+            });
+            if (!res.headersSent) {
+                // Generic error if response hasn't started (e.g., error before SSE connection).
+                res.status(500).send('Internal Server Error');
+            }
+            // The SDK transport's handleRequest should manage errors occurring *during* an SSE stream.
+        }
+    };
+    // Route GET and DELETE requests to the unified handler.
+    app.get(MCP_ENDPOINT_PATH, handleSessionReq);
+    app.delete(MCP_ENDPOINT_PATH, handleSessionReq);
+    // --- Start HTTP Server ---
+    logger.debug('Creating HTTP server instance...', transportContext);
+    const serverInstance = http.createServer(app);
+    try {
+        logger.debug('Attempting to start HTTP server with retry logic...', transportContext);
+        // Use configured host and port, with retry logic.
+        const actualPort = await startHttpServerWithRetry(serverInstance, config.mcpHttpPort, config.mcpHttpHost, MAX_PORT_RETRIES, transportContext);
+        // Determine protocol for logging (basic assumption based on HSTS possibility)
+        const protocol = config.environment === 'production' ? 'https' : 'http';
+        const serverAddress = `${protocol}://${config.mcpHttpHost}:${actualPort}${MCP_ENDPOINT_PATH}`;
+        // Use console.log for prominent startup message.
+        console.log(`\n🚀 MCP Server running in HTTP mode at: ${serverAddress}\n   (MCP Spec: 2025-03-26 Streamable HTTP Transport)\n`);
+    }
+    catch (err) {
+        logger.fatal('HTTP server failed to start after multiple port retries.', { ...transportContext, error: err instanceof Error ? err.message : String(err) });
+        throw err; // Propagate error to stop the application
+    }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Handles the setup and connection for the Stdio MCP transport.
+ * Implements the MCP Specification 2025-03-26 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://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#stdio
+ *
+ * --- Authentication Note ---
+ * As per the MCP Authorization Specification (2025-03-26, 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://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// Import core utilities: ErrorHandler for centralized error management and logger for logging.
+import { ErrorHandler, logger } from '../../utils/index.js';
+// --- Stdio Session State ---
+// Since stdio typically involves a single, persistent connection managed by a parent,
+// we manage a single working directory state for the entire process.
+let currentWorkingDirectory = undefined; // Initialize as undefined
+/**
+ * Gets the current working directory set for the stdio session.
+ * @returns {string | undefined} The current working directory path or undefined if not set.
+ */
+export function getStdioWorkingDirectory() {
+    return currentWorkingDirectory;
+}
+/**
+ * Sets the working directory for the stdio session.
+ * @param {string} dir - The new working directory path.
+ */
+export function setStdioWorkingDirectory(dir) {
+    currentWorkingDirectory = dir;
+    logger.info(`Stdio working directory set to: ${dir}`, { operation: 'setStdioWorkingDirectory' });
+}
+/**
+ * Connects a given McpServer instance to the Stdio transport. (Asynchronous)
+ * Initializes the SDK's StdioServerTransport, which handles reading newline-delimited
+ * JSON-RPC messages from process.stdin and writing corresponding messages to process.stdout,
+ * adhering 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.
+ *
+ * Note: Logging via the `logger` utility MAY result in output to stderr, which is
+ * permitted by the spec for logging purposes.
+ *
+ * @param {McpServer} server - The McpServer instance containing the core logic (tools, resources).
+ * @param {Record<string, any>} context - Logging context for correlation.
+ * @returns {Promise<void>} A promise that resolves when the connection is successfully established.
+ * @throws {Error} Throws an error if the connection fails during setup (e.g., issues connecting server to transport).
+ */
+export async function connectStdioTransport(server, context) {
+    // Add a specific operation name to the context for better log filtering.
+    const operationContext = { ...context, operation: 'connectStdioTransport', transportType: 'Stdio' };
+    logger.debug('Attempting to connect stdio transport...', operationContext);
+    try {
+        logger.debug('Creating StdioServerTransport instance...', operationContext);
+        // Instantiate the transport provided by the SDK for standard I/O communication.
+        // This class encapsulates the logic for reading from stdin and writing to stdout
+        // according to the MCP stdio spec.
+        const transport = new StdioServerTransport();
+        logger.debug('Connecting McpServer instance to StdioServerTransport...', operationContext);
+        // Establish the link between the server's core logic and the transport layer.
+        // This internally starts the necessary listeners on process.stdin.
+        await server.connect(transport);
+        // Log successful connection. The server is now ready to process messages via stdio.
+        logger.info('MCP Server connected and listening via stdio transport.', operationContext);
+        // Use console.log for prominent startup message visibility when run directly.
+        console.log(`\n🚀 MCP Server running in STDIO mode.\n   (MCP Spec: 2025-03-26 Stdio Transport)\n`);
+    }
+    catch (err) {
+        // Catch and handle any critical errors during the transport connection setup.
+        // Mark as critical because the server cannot function without a connected transport.
+        ErrorHandler.handleError(err, { ...operationContext, critical: true });
+        // Rethrow the error to signal the failure to the calling code (e.g., the main server startup).
+        throw err;
+    }
+}

package/{build → dist}/types-global/errors.js

@@ -15,6 +15,8 @@ export var BaseErrorCode;
     BaseErrorCode["CONFLICT"] = "CONFLICT";
     /** The request failed due to invalid input parameters or data. */
     BaseErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    /** An error occurred while parsing input data (e.g., date string, JSON). */
+    BaseErrorCode["PARSING_ERROR"] = "PARSING_ERROR";
     /** The request was rejected because the client has exceeded rate limits. */
     BaseErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
     /** The request timed out before a response could be generated. */
@@ -27,8 +29,6 @@ export var BaseErrorCode;
     BaseErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
     /** An error occurred during the loading or validation of configuration data. */
     BaseErrorCode["CONFIGURATION_ERROR"] = "CONFIGURATION_ERROR";
-    /** An error occurred related to network connectivity (e.g., DNS resolution, connection refused). */
-    BaseErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
 })(BaseErrorCode || (BaseErrorCode = {}));
 /**
  * Custom error class for MCP-specific errors.

package/dist/utils/index.js

@@ -0,0 +1,12 @@
+// Re-export all utilities from their categorized subdirectories
+export * from './internal/index.js';
+export * from './parsing/index.js';
+export * from './security/index.js';
+export * from './metrics/index.js';
+// It's good practice to have index.ts files in each subdirectory
+// that export the contents of that directory.
+// Assuming those will be created or already exist.
+// If not, this might need adjustment to export specific files, e.g.:
+// export * from './internal/errorHandler.js';
+// export * from './internal/logger.js';
+// ... etc.

package/{build/utils → dist/utils/internal}/errorHandler.js

@@ -1,6 +1,6 @@
-import { BaseErrorCode, McpError } from '../types-global/errors.js';
+import { BaseErrorCode, McpError } from '../../types-global/errors.js'; // Corrected path
 import { logger } from './logger.js';
-import { sanitizeInputForLogging } from './sanitization.js'; // Updated import
+import { sanitizeInputForLogging } from '../index.js'; // Import from main barrel file
 /**
  * Simple mapper that maps error types to error codes
  */
@@ -115,7 +115,9 @@ export class ErrorHandler {
         if (error instanceof McpError) {
             // Add any additional context
             if (context && Object.keys(context).length > 0) {
-                error.details = { ...error.details, ...context };
+                // Ensure details is an object before spreading
+                const existingDetails = typeof error.details === 'object' && error.details !== null ? error.details : {};
+                error.details = { ...existingDetails, ...context };
             }
             // Log the error with sanitized input
             logger.error(`Error ${operation}: ${error.message}`, {
@@ -129,13 +131,14 @@ export class ErrorHandler {
             if (rethrow) {
                 throw error;
             }
+            // Ensure the function returns an Error type
             return error;
         }
         // Sanitize input for logging
         const sanitizedInput = input ? sanitizeInputForLogging(input) : undefined;
         // Log the error with consistent format
         logger.error(`Error ${operation}`, {
-            error: error instanceof Error ? error.message : String(error),
+            error: getErrorMessage(error), // Use helper function
             errorType: getErrorName(error),
             input: sanitizedInput,
             requestId: context?.requestId,
@@ -148,16 +151,22 @@ export class ErrorHandler {
             ErrorHandler.determineErrorCode(error) ||
             BaseErrorCode.INTERNAL_ERROR;
         // Transform to appropriate error type
-        const transformedError = options.errorMapper
-            ? options.errorMapper(error)
-            : new McpError(errorCode, `Error ${operation}: ${error instanceof Error ? error.message : 'Unknown error'}`, {
+        let transformedError;
+        if (options.errorMapper) {
+            transformedError = options.errorMapper(error);
+        }
+        else {
+            transformedError = new McpError(errorCode, `Error ${operation}: ${getErrorMessage(error)}`, // Use helper function
+            {
                 originalError: getErrorName(error),
                 ...context
             });
+        }
         // Rethrow if requested
         if (rethrow) {
             throw transformedError;
         }
+        // Ensure the function returns an Error type
         return transformedError;
     }
     /**
@@ -204,7 +213,8 @@ export class ErrorHandler {
             return {
                 code: error.code,
                 message: error.message,
-                details: error.details || {}
+                // Ensure details is an object
+                details: typeof error.details === 'object' && error.details !== null ? error.details : {}
             };
         }
         if (error instanceof Error) {

package/dist/utils/internal/index.js

@@ -0,0 +1,3 @@
+export * from './errorHandler.js';
+export * from './logger.js';
+export * from './requestContext.js';