@cyanheads/git-mcp-server 2.2.2 → 2.2.4

package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Implements the OAuth 2.1 authentication strategy.
+ * This module provides a concrete implementation of the AuthStrategy for validating
+ * JWTs against a remote JSON Web Key Set (JWKS), as is common in OAuth 2.1 flows.
+ * @module src/mcp-server/transports/auth/strategies/OauthStrategy
+ */
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { config } from "../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../../utils/index.js";
+export class OauthStrategy {
+    jwks;
+    constructor() {
+        const context = requestContextService.createRequestContext({
+            operation: "OauthStrategy.constructor",
+        });
+        logger.debug("Initializing OauthStrategy...", context);
+        if (config.mcpAuthMode !== "oauth") {
+            // This check is for internal consistency, so a standard Error is acceptable here.
+            throw new Error("OauthStrategy instantiated for non-oauth auth mode.");
+        }
+        if (!config.oauthIssuerUrl || !config.oauthAudience) {
+            logger.fatal("CRITICAL: OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.", context);
+            // This is a user-facing configuration error, so McpError is appropriate.
+            throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OAUTH_ISSUER_URL and OAUTH_AUDIENCE must be set for OAuth mode.", context);
+        }
+        try {
+            const jwksUrl = new URL(config.oauthJwksUri ||
+                `${config.oauthIssuerUrl.replace(/\/$/, "")}/.well-known/jwks.json`);
+            this.jwks = createRemoteJWKSet(jwksUrl, {
+                cooldownDuration: 300000, // 5 minutes
+                timeoutDuration: 5000, // 5 seconds
+            });
+            logger.info(`JWKS client initialized for URL: ${jwksUrl.href}`, context);
+        }
+        catch (error) {
+            logger.fatal("Failed to initialize JWKS client.", {
+                ...context,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // This is a critical startup failure, so a specific McpError is warranted.
+            throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, "Could not initialize JWKS client for OAuth strategy.", {
+                ...context,
+                originalError: error instanceof Error ? error.message : "Unknown",
+            });
+        }
+    }
+    async verify(token) {
+        const context = requestContextService.createRequestContext({
+            operation: "OauthStrategy.verify",
+        });
+        logger.debug("Attempting to verify OAuth token via JWKS.", context);
+        try {
+            const { payload } = await jwtVerify(token, this.jwks, {
+                issuer: config.oauthIssuerUrl,
+                audience: config.oauthAudience,
+            });
+            logger.debug("OAuth token signature verified successfully.", {
+                ...context,
+                claims: payload,
+            });
+            const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+            if (scopes.length === 0) {
+                logger.warning("Invalid token: missing or empty 'scope' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.", context);
+            }
+            const clientId = typeof payload.client_id === "string" ? payload.client_id : undefined;
+            if (!clientId) {
+                logger.warning("Invalid token: missing 'client_id' claim.", context);
+                throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain a 'client_id' claim.", context);
+            }
+            const authInfo = {
+                token,
+                clientId,
+                scopes,
+                subject: typeof payload.sub === "string" ? payload.sub : undefined,
+            };
+            logger.info("OAuth token verification successful.", {
+                ...context,
+                clientId,
+                scopes,
+            });
+            return authInfo;
+        }
+        catch (error) {
+            const message = error instanceof Error && error.name === "JWTExpired"
+                ? "Token has expired."
+                : "OAuth token verification failed.";
+            logger.warning(`OAuth token verification failed: ${message}`, {
+                ...context,
+                errorName: error instanceof Error ? error.name : "Unknown",
+            });
+            throw ErrorHandler.handleError(error, {
+                operation: "OauthStrategy.verify",
+                context,
+                rethrow: true,
+                errorCode: BaseErrorCode.UNAUTHORIZED,
+                errorMapper: () => new McpError(BaseErrorCode.UNAUTHORIZED, message, context),
+            });
+        }
+    }
+}

package/dist/mcp-server/transports/core/baseTransportManager.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Abstract base class for transport managers.
+ * @module src/mcp-server/transports/core/baseTransportManager
+ */
+import { logger, requestContextService, } from "../../../utils/index.js";
+/**
+ * Abstract base class for transport managers, providing common functionality.
+ */
+export class BaseTransportManager {
+    createServerInstanceFn;
+    constructor(createServerInstanceFn) {
+        const context = requestContextService.createRequestContext({
+            operation: "BaseTransportManager.constructor",
+            managerType: this.constructor.name,
+        });
+        logger.debug("Initializing transport manager.", context);
+        this.createServerInstanceFn = createServerInstanceFn;
+    }
+}

package/dist/mcp-server/transports/core/honoNodeBridge.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Provides a bridge between the MCP SDK's Node.js-style
+ * streamable HTTP transport and Hono's Web Standards-based streaming response.
+ * @module src/mcp-server/transports/core/honoNodeBridge
+ */
+import { PassThrough } from "stream";
+/**
+ * A mock ServerResponse that pipes writes to a PassThrough stream.
+ * This is the bridge between Model Context Protocol's SDK's Node.js-style response handling
+ * and Hono's stream-based body. It captures status and headers.
+ */
+export class HonoStreamResponse extends PassThrough {
+    statusCode = 200;
+    headers = {};
+    constructor() {
+        super();
+    }
+    writeHead(statusCode, headers) {
+        this.statusCode = statusCode;
+        if (headers) {
+            this.headers = { ...this.headers, ...headers };
+        }
+        return this;
+    }
+    setHeader(name, value) {
+        this.headers[name.toLowerCase()] = value;
+        return this;
+    }
+    getHeader(name) {
+        return this.headers[name.toLowerCase()];
+    }
+    getHeaders() {
+        return this.headers;
+    }
+    removeHeader(name) {
+        delete this.headers[name.toLowerCase()];
+    }
+    write(chunk, encodingOrCallback, callback) {
+        const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
+        const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return super.write(chunk, encoding, cb);
+    }
+    end(chunk, encodingOrCallback, callback) {
+        const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
+        const cb = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        super.end(chunk, encoding, cb);
+        return this;
+    }
+}

package/dist/mcp-server/transports/core/statefulTransportManager.js

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Stateful Transport Manager implementation for MCP SDK.
+ * This manager handles multiple, persistent sessions, creating a dedicated
+ * McpServer and StreamableHTTPServerTransport instance for each one.
+ * This version is adapted for Hono by bridging the SDK's Node.js-style
+ * request handling with Hono's stream-based response model.
+ * @module src/mcp-server/transports/core/statefulTransportManager
+ */
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { randomUUID } from "node:crypto";
+import { Readable } from "stream";
+import { config } from "../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { BaseTransportManager } from "./baseTransportManager.js";
+import { HonoStreamResponse } from "./honoNodeBridge.js";
+/**
+ * Stateful Transport Manager that handles MCP SDK integration and session management
+ * for a Hono-based HTTP server.
+ */
+export class StatefulTransportManager extends BaseTransportManager {
+    transports = new Map();
+    servers = new Map();
+    sessions = new Map();
+    garbageCollector;
+    constructor(createServerInstanceFn) {
+        super(createServerInstanceFn);
+        const context = requestContextService.createRequestContext({
+            operation: "StatefulTransportManager.constructor",
+        });
+        logger.info("Starting session garbage collector.", context);
+        this.garbageCollector = setInterval(() => this.cleanupStaleSessions(), config.mcpStatefulSessionStaleTimeoutMs);
+    }
+    async initializeAndHandle(headers, body, context) {
+        const operationName = "StatefulTransportManager.initializeAndHandle";
+        const opContext = { ...context, operation: operationName };
+        logger.debug("Initializing new stateful session.", opContext);
+        const server = await this.createServerInstanceFn();
+        const mockRes = new HonoStreamResponse();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sessionId) => {
+                const sessionContext = { ...opContext, sessionId };
+                this.transports.set(sessionId, transport);
+                this.servers.set(sessionId, server);
+                this.sessions.set(sessionId, {
+                    id: sessionId,
+                    createdAt: new Date(),
+                    lastAccessedAt: new Date(),
+                });
+                logger.info(`MCP Session created: ${sessionId}`, sessionContext);
+            },
+        });
+        transport.onclose = () => {
+            const sessionId = transport.sessionId;
+            if (sessionId) {
+                const closeContext = requestContextService.createRequestContext({
+                    operation: "StatefulTransportManager.transport.onclose",
+                    sessionId,
+                });
+                this.closeSession(sessionId, closeContext).catch((err) => logger.error(`Error during transport.onclose cleanup for session ${sessionId}`, err, closeContext));
+            }
+        };
+        await server.connect(transport);
+        logger.debug("Server connected to transport, handling initial request.", opContext);
+        const mockReq = {
+            headers,
+            method: "POST",
+            url: config.mcpHttpEndpointPath,
+        };
+        await transport.handleRequest(mockReq, mockRes, body);
+        const responseHeaders = new Headers();
+        for (const [key, value] of Object.entries(mockRes.getHeaders())) {
+            responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+        }
+        if (transport.sessionId) {
+            responseHeaders.set("Mcp-Session-Id", transport.sessionId);
+        }
+        const webStream = Readable.toWeb(mockRes);
+        return {
+            headers: responseHeaders,
+            statusCode: mockRes.statusCode,
+            stream: webStream,
+            sessionId: transport.sessionId,
+        };
+    }
+    async handleRequest(headers, body, context, sessionId) {
+        if (!sessionId) {
+            throw new McpError(BaseErrorCode.INVALID_INPUT, "Session ID is required for stateful requests.", context);
+        }
+        const sessionContext = {
+            ...context,
+            sessionId,
+            operation: "StatefulTransportManager.handleRequest",
+        };
+        logger.debug(`Handling request for session: ${sessionId}`, {
+            ...sessionContext,
+            method: headers["x-forwarded-proto"] || "http",
+        });
+        const transport = this.transports.get(sessionId);
+        if (!transport) {
+            logger.warning(`Request for non-existent session: ${sessionId}`, sessionContext);
+            return {
+                headers: new Headers({ "Content-Type": "application/json" }),
+                statusCode: 404,
+                body: {
+                    jsonrpc: "2.0",
+                    error: { code: -32601, message: "Session not found" },
+                },
+            };
+        }
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.lastAccessedAt = new Date();
+            logger.debug(`Updated lastAccessedAt for session ${sessionId}.`, sessionContext);
+        }
+        const mockReq = {
+            headers,
+            method: "POST",
+        };
+        const mockRes = new HonoStreamResponse();
+        await transport.handleRequest(mockReq, mockRes, body);
+        const responseHeaders = new Headers();
+        for (const [key, value] of Object.entries(mockRes.getHeaders())) {
+            responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+        }
+        const webStream = Readable.toWeb(mockRes);
+        return {
+            headers: responseHeaders,
+            statusCode: mockRes.statusCode,
+            stream: webStream,
+            sessionId: transport.sessionId,
+        };
+    }
+    async handleDeleteRequest(sessionId, context) {
+        const sessionContext = {
+            ...context,
+            sessionId,
+            operation: "StatefulTransportManager.handleDeleteRequest",
+        };
+        logger.info(`Attempting to delete session: ${sessionId}`, sessionContext);
+        const transport = this.transports.get(sessionId);
+        if (!transport) {
+            logger.warning(`Attempted to delete non-existent session: ${sessionId}`, sessionContext);
+            throw new McpError(BaseErrorCode.NOT_FOUND, "Session not found or expired.", sessionContext);
+        }
+        await this.closeSession(sessionId, sessionContext);
+        const headers = new Headers();
+        headers.set("Content-Type", "application/json");
+        return {
+            headers,
+            statusCode: 200,
+            body: { status: "session_closed", sessionId },
+        };
+    }
+    getSession(sessionId) {
+        const context = requestContextService.createRequestContext({
+            operation: "StatefulTransportManager.getSession",
+            sessionId,
+        });
+        logger.debug(`Retrieving session: ${sessionId}`, context);
+        return this.sessions.get(sessionId);
+    }
+    async shutdown() {
+        const context = requestContextService.createRequestContext({
+            operation: "StatefulTransportManager.shutdown",
+        });
+        logger.info("Shutting down stateful transport manager...", context);
+        clearInterval(this.garbageCollector);
+        logger.debug("Garbage collector stopped.", context);
+        const sessionIds = Array.from(this.transports.keys());
+        logger.info(`Closing ${sessionIds.length} active sessions.`, context);
+        const closePromises = sessionIds.map((sessionId) => this.closeSession(sessionId, context));
+        await Promise.all(closePromises);
+        this.transports.clear();
+        this.sessions.clear();
+        this.servers.clear();
+        logger.info("All active sessions closed and manager shut down.", context);
+    }
+    async closeSession(sessionId, context) {
+        const sessionContext = {
+            ...context,
+            sessionId,
+            operation: "StatefulTransportManager.closeSession",
+        };
+        logger.debug(`Closing session: ${sessionId}`, sessionContext);
+        const transport = this.transports.get(sessionId);
+        const server = this.servers.get(sessionId);
+        await ErrorHandler.tryCatch(async () => {
+            if (transport) {
+                await transport.close();
+                logger.debug(`Transport closed for session ${sessionId}.`, sessionContext);
+            }
+            if (server) {
+                await server.close();
+                logger.debug(`Server instance closed for session ${sessionId}.`, sessionContext);
+            }
+        }, {
+            operation: "closeSession.cleanup",
+            context: sessionContext,
+        });
+        this.transports.delete(sessionId);
+        this.servers.delete(sessionId);
+        this.sessions.delete(sessionId);
+        logger.info(`MCP Session closed and resources released: ${sessionId}`, sessionContext);
+    }
+    async cleanupStaleSessions() {
+        const context = requestContextService.createRequestContext({
+            operation: "StatefulTransportManager.cleanupStaleSessions",
+        });
+        logger.debug("Running stale session cleanup...", context);
+        const now = Date.now();
+        const STALE_TIMEOUT_MS = config.mcpStatefulSessionStaleTimeoutMs;
+        let staleCount = 0;
+        for (const [sessionId, session] of this.sessions.entries()) {
+            if (now - session.lastAccessedAt.getTime() > STALE_TIMEOUT_MS) {
+                staleCount++;
+                const sessionContext = {
+                    ...context,
+                    sessionId,
+                    lastAccessed: session.lastAccessedAt.toISOString(),
+                };
+                logger.info(`Found stale session, closing: ${sessionId}`, sessionContext);
+                await this.closeSession(sessionId, sessionContext);
+            }
+        }
+        if (staleCount > 0) {
+            logger.info(`Stale session cleanup complete. Closed ${staleCount} sessions.`, context);
+        }
+        else {
+            logger.debug("No stale sessions found.", context);
+        }
+    }
+}

package/dist/mcp-server/transports/core/statelessTransportManager.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Stateless Transport Manager implementation for MCP SDK.
+ * This manager handles single-request operations without maintaining sessions.
+ * Each request creates a temporary server instance that is cleaned up immediately.
+ * This version is adapted for Hono by bridging the SDK's Node.js-style
+ * request handling with Hono's stream-based response model.
+ * @module src/mcp-server/transports/core/statelessTransportManager
+ */
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { Readable } from "stream";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
+import { BaseTransportManager } from "./baseTransportManager.js";
+import { HonoStreamResponse } from "./honoNodeBridge.js";
+/**
+ * Stateless Transport Manager that handles ephemeral MCP operations.
+ */
+export class StatelessTransportManager extends BaseTransportManager {
+    async handleRequest(headers, body, context) {
+        const opContext = {
+            ...context,
+            operation: "StatelessTransportManager.handleRequest",
+        };
+        logger.debug("Creating ephemeral server instance for stateless request.", opContext);
+        let server;
+        let transport;
+        try {
+            server = await this.createServerInstanceFn();
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                onsessioninitialized: undefined,
+            });
+            await server.connect(transport);
+            logger.debug("Ephemeral server connected to transport.", opContext);
+            const mockReq = {
+                headers,
+                method: "POST",
+            };
+            const mockRes = new HonoStreamResponse();
+            await transport.handleRequest(mockReq, mockRes, body);
+            logger.info("Stateless request handled successfully.", opContext);
+            const responseHeaders = new Headers();
+            for (const [key, value] of Object.entries(mockRes.getHeaders())) {
+                responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+            }
+            // Bridge the Node.js stream (PassThrough) to a Web Stream (ReadableStream)
+            const webStream = Readable.toWeb(mockRes);
+            return {
+                headers: responseHeaders,
+                statusCode: mockRes.statusCode,
+                stream: webStream,
+            };
+        }
+        catch (error) {
+            throw ErrorHandler.handleError(error, {
+                operation: "StatelessTransportManager.handleRequest",
+                context: opContext,
+                rethrow: true,
+            });
+        }
+        finally {
+            if (server || transport) {
+                this.cleanup(server, transport, opContext);
+            }
+        }
+    }
+    async shutdown() {
+        const context = requestContextService.createRequestContext({
+            operation: "StatelessTransportManager.shutdown",
+        });
+        logger.info("Stateless transport manager shutdown - no persistent resources to clean up.", context);
+        return Promise.resolve();
+    }
+    cleanup(server, transport, context) {
+        const opContext = {
+            ...context,
+            operation: "StatelessTransportManager.cleanup",
+        };
+        logger.debug("Scheduling cleanup for ephemeral resources.", opContext);
+        Promise.all([transport?.close(), server?.close()])
+            .then(() => {
+            logger.debug("Ephemeral resources cleaned up successfully.", opContext);
+        })
+            .catch((cleanupError) => {
+            logger.warning("Error during stateless resource cleanup.", {
+                ...opContext,
+                error: cleanupError instanceof Error
+                    ? cleanupError.message
+                    : String(cleanupError),
+            });
+        });
+    }
+}

package/dist/mcp-server/transports/core/transportTypes.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Core types and interfaces for the transport layer abstraction.
+ * @module src/mcp-server/transports/core/transportTypes
+ */
+export {};

package/dist/mcp-server/transports/{httpErrorHandler.js → http/httpErrorHandler.js}

@@ -5,8 +5,8 @@
  * formats them into a consistent JSON-RPC error response.
  * @module src/mcp-server/transports/httpErrorHandler
  */
-import { BaseErrorCode, McpError } from "../../types-global/errors.js";
-import { ErrorHandler, requestContextService } from "../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 /**
  * A centralized error handling middleware for Hono.
  * This function is registered with `app.onError()` and will catch any errors
@@ -22,6 +22,7 @@ export const httpErrorHandler = async (err, c) => {
         path: c.req.path,
         method: c.req.method,
     });
+    logger.debug("HTTP error handler invoked.", context);
     const handledError = ErrorHandler.handleError(err, {
         operation: "httpTransport",
         context,
@@ -39,6 +40,7 @@ export const httpErrorHandler = async (err, c) => {
                 status = 403;
                 break;
             case BaseErrorCode.VALIDATION_ERROR:
+            case BaseErrorCode.INVALID_INPUT:
                 status = 400;
                 break;
             case BaseErrorCode.CONFLICT:
@@ -51,23 +53,46 @@ export const httpErrorHandler = async (err, c) => {
                 status = 500;
         }
     }
+    logger.debug(`Mapping error to HTTP status ${status}.`, {
+        ...context,
+        status,
+        errorCode: handledError.code,
+    });
     // Attempt to get the request ID from the body, but don't fail if it's not there or unreadable.
     let requestId = null;
-    try {
-        const body = await c.req.json();
-        requestId = body?.id || null;
+    // Only attempt to read the body if it hasn't been consumed already.
+    if (c.req.raw.bodyUsed === false) {
+        try {
+            const body = await c.req.json();
+            requestId = body?.id || null;
+            logger.debug("Extracted JSON-RPC request ID from body.", {
+                ...context,
+                jsonRpcId: requestId,
+            });
+        }
+        catch {
+            logger.warning("Could not parse request body to extract JSON-RPC ID.", context);
+            // Ignore parsing errors, requestId will remain null
+        }
     }
-    catch {
-        // Ignore parsing errors, requestId will remain null
+    else {
+        logger.debug("Request body already consumed, cannot extract JSON-RPC ID.", context);
     }
     const errorCode = handledError instanceof McpError ? handledError.code : -32603;
     c.status(status);
-    return c.json({
+    const errorResponse = {
         jsonrpc: "2.0",
         error: {
             code: errorCode,
             message: handledError.message,
         },
         id: requestId,
+    };
+    logger.info(`Sending formatted error response for request.`, {
+        ...context,
+        status,
+        errorCode,
+        jsonRpcId: requestId,
     });
+    return c.json(errorResponse);
 };