obsidian-mcp-server 2.0.4 → 2.0.6

package/dist/mcp-server/tools/{obsidianUpdateFileTool → obsidianUpdateNoteTool}/registration.js

@@ -1,9 +1,9 @@
 import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
 import { ErrorHandler, logger, requestContextService, } from "../../../utils/index.js";
 // Import the Zod schema for validation and the core processing logic
-import { ObsidianUpdateFileInputSchema, ObsidianUpdateFileInputSchemaShape, processObsidianUpdateFile, } from "./logic.js";
+import { ObsidianUpdateNoteInputSchema, ObsidianUpdateNoteInputSchemaShape, processObsidianUpdateNote, } from "./logic.js";
 /**
- * Registers the 'obsidian_update_file' tool with the MCP server.
+ * Registers the 'obsidian_update_note' tool with the MCP server.
  *
  * This tool allows modification of Obsidian notes (specified by file path,
  * the active file, or a periodic note) using whole-file operations:
@@ -20,26 +20,26 @@ import { ObsidianUpdateFileInputSchema, ObsidianUpdateFileInputSchemaShape, proc
  * @returns {Promise<void>} A promise that resolves when the tool registration is complete or rejects on error.
  * @throws {McpError} Throws an McpError if registration fails critically.
  */
-export const registerObsidianUpdateFileTool = async (server, obsidianService, vaultCacheService) => {
-    const toolName = "obsidian_update_file";
+export const registerObsidianUpdateNoteTool = async (server, obsidianService, vaultCacheService) => {
+    const toolName = "obsidian_update_note";
     const toolDescription = "Tool to modify Obsidian notes (specified by file path, the active file, or a periodic note) using whole-file operations: 'append', 'prepend', or 'overwrite'. Options allow creating missing files/targets and controlling overwrite behavior. Returns success status, message, a formatted timestamp string, file stats (stats), and optionally the final file content.";
     // Create a context for the registration process itself for better traceability.
     const registrationContext = requestContextService.createRequestContext({
-        operation: "RegisterObsidianUpdateFileTool",
+        operation: "RegisterObsidianUpdateNoteTool",
         toolName: toolName,
-        module: "ObsidianUpdateFileRegistration", // Identify the module performing registration
+        module: "ObsidianUpdateNoteRegistration", // Identify the module performing registration
     });
     logger.info(`Attempting to register tool: ${toolName}`, registrationContext);
     // Wrap the registration in a tryCatch block for robust error handling during setup.
     await ErrorHandler.tryCatch(async () => {
         // Use the high-level SDK method for tool registration.
         // This handles schema generation, validation, and routing automatically.
-        server.tool(toolName, toolDescription, ObsidianUpdateFileInputSchemaShape, // Provide the Zod schema shape for input validation.
+        server.tool(toolName, toolDescription, ObsidianUpdateNoteInputSchemaShape, // Provide the Zod schema shape for input validation.
         /**
-         * The handler function executed when the 'obsidian_update_file' tool is called.
+         * The handler function executed when the 'obsidian_update_note' tool is called.
          *
-         * @param {ObsidianUpdateFileRegistrationInput} params - The raw input parameters received from the client,
-         *   matching the structure defined by ObsidianUpdateFileInputSchemaShape.
+         * @param {ObsidianUpdateNoteRegistrationInput} params - The raw input parameters received from the client,
+         *   matching the structure defined by ObsidianUpdateNoteInputSchemaShape.
          * @returns {Promise<CallToolResult>} A promise resolving to the structured result for the MCP client,
          *   containing either the successful response data or an error indication.
          */
@@ -47,7 +47,7 @@ export const registerObsidianUpdateFileTool = async (server, obsidianService, va
             // Create a specific context for this handler invocation.
             const handlerContext = requestContextService.createRequestContext({
                 parentContext: registrationContext, // Link to the registration context
-                operation: "HandleObsidianUpdateFileRequest",
+                operation: "HandleObsidianUpdateNoteRequest",
                 toolName: toolName,
                 params: {
                     // Log key parameters for easier debugging, content is omitted for brevity/security
@@ -67,10 +67,10 @@ export const registerObsidianUpdateFileTool = async (server, obsidianService, va
                 // This ensures type safety and adherence to constraints defined in logic.ts.
                 // While server.tool performs initial validation based on the shape,
                 // this step applies any stricter rules or refinements from the full schema.
-                const validatedParams = ObsidianUpdateFileInputSchema.parse(params);
+                const validatedParams = ObsidianUpdateNoteInputSchema.parse(params);
                 // Delegate the actual file update logic to the dedicated processing function.
                 // Pass the validated parameters, the handler context, and the Obsidian service instance.
-                const response = await processObsidianUpdateFile(validatedParams, handlerContext, obsidianService, vaultCacheService);
+                const response = await processObsidianUpdateNote(validatedParams, handlerContext, obsidianService, vaultCacheService);
                 logger.debug(`'${toolName}' (wholeFile mode) processed successfully`, handlerContext);
                 // Format the successful response from the logic function into the MCP CallToolResult structure.
                 // The response object (containing status, message, timestamp, stat, etc.) is serialized to JSON.

package/dist/mcp-server/transports/{authentication → auth/core}/authContext.d.ts

@@ -5,10 +5,10 @@
  * from the middleware layer down to the tool and resource handlers without
  * drilling props.
  *
- * @module src/mcp-server/transports/authentication/authContext
+ * @module src/mcp-server/transports/auth/core/authContext
  */
 import { AsyncLocalStorage } from "async_hooks";
-import type { AuthInfo } from "./types.js";
+import type { AuthInfo } from "./authTypes.js";
 /**
  * Defines the structure of the store used within the AsyncLocalStorage.
  * It holds the authentication information for the current request context.

package/dist/mcp-server/transports/{authentication → auth/core}/authContext.js

@@ -5,7 +5,7 @@
  * from the middleware layer down to the tool and resource handlers without
  * drilling props.
  *
- * @module src/mcp-server/transports/authentication/authContext
+ * @module src/mcp-server/transports/auth/core/authContext
  */
 import { AsyncLocalStorage } from "async_hooks";
 /**

package/dist/mcp-server/transports/{authentication/types.d.ts → auth/core/authTypes.d.ts}

@@ -1,6 +1,6 @@
 /**
  * @fileoverview Shared types for authentication middleware.
- * @module src/mcp-server/transports/authentication/types
+ * @module src/mcp-server/transports/auth/core/auth.types
  */
 import type { AuthInfo as SdkAuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
 /**

package/dist/mcp-server/transports/{authentication/types.js → auth/core/authTypes.js}

@@ -1,5 +1,5 @@
 /**
  * @fileoverview Shared types for authentication middleware.
- * @module src/mcp-server/transports/authentication/types
+ * @module src/mcp-server/transports/auth/core/auth.types
  */
 export {};

package/dist/mcp-server/transports/{authentication → auth/core}/authUtils.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Provides utility functions for authorization, specifically for
  * checking token scopes against required permissions for a given operation.
- * @module src/mcp-server/transports/authentication/authUtils
+ * @module src/mcp-server/transports/auth/core/authUtils
  */
 /**
  * Checks if the current authentication context contains all the specified scopes.

package/dist/mcp-server/transports/{authentication → auth/core}/authUtils.js

@@ -1,10 +1,10 @@
 /**
  * @fileoverview Provides utility functions for authorization, specifically for
  * checking token scopes against required permissions for a given operation.
- * @module src/mcp-server/transports/authentication/authUtils
+ * @module src/mcp-server/transports/auth/core/authUtils
  */
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
-import { logger, requestContextService } from "../../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../../types-global/errors.js";
+import { logger, requestContextService } from "../../../../utils/index.js";
 import { authContext } from "./authContext.js";
 /**
  * Checks if the current authentication context contains all the specified scopes.

package/dist/mcp-server/transports/auth/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Barrel file for the auth module.
+ * Exports core utilities and middleware strategies for easier imports.
+ * @module src/mcp-server/transports/auth/index
+ */
+export { authContext } from "./core/authContext.js";
+export { withRequiredScopes } from "./core/authUtils.js";
+export type { AuthInfo } from "./core/authTypes.js";
+export { mcpAuthMiddleware as jwtAuthMiddleware } from "./strategies/jwt/jwtMiddleware.js";
+export { oauthMiddleware } from "./strategies/oauth/oauthMiddleware.js";

package/dist/mcp-server/transports/auth/index.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Barrel file for the auth module.
+ * Exports core utilities and middleware strategies for easier imports.
+ * @module src/mcp-server/transports/auth/index
+ */
+export { authContext } from "./core/authContext.js";
+export { withRequiredScopes } from "./core/authUtils.js";
+export { mcpAuthMiddleware as jwtAuthMiddleware } from "./strategies/jwt/jwtMiddleware.js";
+export { oauthMiddleware } from "./strategies/oauth/oauthMiddleware.js";

package/dist/mcp-server/transports/{authentication/authMiddleware.d.ts → auth/strategies/jwt/jwtMiddleware.d.ts}

@@ -10,10 +10,11 @@
  * is attached to `c.env.incoming.auth`. This direct attachment to the raw Node.js
  * request object is for compatibility with the underlying SDK transport, which is
  * not Hono-context-aware.
- * If the token is missing, invalid, or expired, it returns an HTTP 401 Unauthorized response.
+ * If the token is missing, invalid, or expired, it throws an `McpError`, which is
+ * then handled by the centralized `httpErrorHandler`.
  *
  * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
- * @module src/mcp-server/transports/authentication/authMiddleware
+ * @module src/mcp-server/transports/auth/strategies/jwt/jwtMiddleware
  */
 import { HttpBindings } from "@hono/node-server";
 import { Context, Next } from "hono";
@@ -23,8 +24,4 @@ import { Context, Next } from "hono";
  */
 export declare function mcpAuthMiddleware(c: Context<{
     Bindings: HttpBindings;
-}>, next: Next): Promise<void | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 500, "json">) | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 401, "json">)>;
+}>, next: Next): Promise<void>;

package/dist/mcp-server/transports/{authentication/authMiddleware.js → auth/strategies/jwt/jwtMiddleware.js}

@@ -10,22 +10,26 @@
  * is attached to `c.env.incoming.auth`. This direct attachment to the raw Node.js
  * request object is for compatibility with the underlying SDK transport, which is
  * not Hono-context-aware.
- * If the token is missing, invalid, or expired, it returns an HTTP 401 Unauthorized response.
+ * If the token is missing, invalid, or expired, it throws an `McpError`, which is
+ * then handled by the centralized `httpErrorHandler`.
  *
  * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/authorization.mdx | MCP Authorization Specification}
- * @module src/mcp-server/transports/authentication/authMiddleware
+ * @module src/mcp-server/transports/auth/strategies/jwt/jwtMiddleware
  */
-import jwt from "jsonwebtoken";
-import { config, environment } from "../../../config/index.js";
-import { logger, requestContextService } from "../../../utils/index.js";
-import { authContext } from "./authContext.js";
+import { jwtVerify } from "jose";
+import { config, environment } from "../../../../../config/index.js";
+import { logger, requestContextService } from "../../../../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../../../types-global/errors.js";
+import { authContext } from "../../core/authContext.js";
 // Startup Validation: Validate secret key presence on module load.
-if (environment === "production" && !config.mcpAuthSecretKey) {
-    logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment. Authentication cannot proceed securely.");
-    throw new Error("MCP_AUTH_SECRET_KEY must be set in production environment for JWT authentication.");
-}
-else if (!config.mcpAuthSecretKey) {
-    logger.warning("MCP_AUTH_SECRET_KEY is not set. Authentication middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.");
+if (config.mcpAuthMode === "jwt") {
+    if (environment === "production" && !config.mcpAuthSecretKey) {
+        logger.fatal("CRITICAL: MCP_AUTH_SECRET_KEY is not set in production environment for JWT auth. Authentication cannot proceed securely.");
+        throw new Error("MCP_AUTH_SECRET_KEY must be set in production environment for JWT authentication.");
+    }
+    else if (!config.mcpAuthSecretKey) {
+        logger.warning("MCP_AUTH_SECRET_KEY is not set. JWT auth middleware will bypass checks (DEVELOPMENT ONLY). This is insecure for production.");
+    }
 }
 /**
  * Hono middleware for verifying JWT Bearer token authentication.
@@ -39,6 +43,10 @@ export async function mcpAuthMiddleware(c, next) {
     });
     logger.debug("Running MCP Authentication Middleware (Bearer Token Validation)...", context);
     const reqWithAuth = c.env.incoming;
+    // If JWT auth is not enabled, skip the middleware.
+    if (config.mcpAuthMode !== "jwt") {
+        return await next();
+    }
     // Development Mode Bypass
     if (!config.mcpAuthSecretKey) {
         if (environment !== "production") {
@@ -57,28 +65,23 @@ export async function mcpAuthMiddleware(c, next) {
         }
         else {
             logger.error("FATAL: MCP_AUTH_SECRET_KEY is missing in production. Cannot bypass auth.", context);
-            return c.json({ error: "Server configuration error: Authentication key missing." }, 500);
+            throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Server configuration error: Authentication key missing.");
         }
     }
+    const secretKey = new TextEncoder().encode(config.mcpAuthSecretKey);
     const authHeader = c.req.header("Authorization");
     if (!authHeader || !authHeader.startsWith("Bearer ")) {
         logger.warning("Authentication failed: Missing or malformed Authorization header (Bearer scheme required).", context);
-        return c.json({
-            error: "Unauthorized: Missing or invalid authentication token format.",
-        }, 401);
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid authentication token format.");
     }
     const tokenParts = authHeader.split(" ");
     if (tokenParts.length !== 2 || tokenParts[0] !== "Bearer" || !tokenParts[1]) {
         logger.warning("Authentication failed: Malformed Bearer token.", context);
-        return c.json({ error: "Unauthorized: Malformed authentication token." }, 401);
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Malformed authentication token.");
     }
     const rawToken = tokenParts[1];
     try {
-        const decoded = jwt.verify(rawToken, config.mcpAuthSecretKey);
-        if (typeof decoded === "string") {
-            logger.warning("Authentication failed: JWT decoded to a string, expected an object payload.", context);
-            return c.json({ error: "Unauthorized: Invalid token payload format." }, 401);
-        }
+        const { payload: decoded } = await jwtVerify(rawToken, secretKey);
         const clientIdFromToken = typeof decoded.cid === "string"
             ? decoded.cid
             : typeof decoded.client_id === "string"
@@ -86,7 +89,7 @@ export async function mcpAuthMiddleware(c, next) {
                 : undefined;
         if (!clientIdFromToken) {
             logger.warning("Authentication failed: JWT 'cid' or 'client_id' claim is missing or not a string.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
-            return c.json({ error: "Unauthorized: Invalid token, missing client identifier." }, 401);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token, missing client identifier.");
         }
         let scopesFromToken = [];
         if (Array.isArray(decoded.scp) &&
@@ -102,7 +105,7 @@ export async function mcpAuthMiddleware(c, next) {
         }
         if (scopesFromToken.length === 0) {
             logger.warning("Authentication failed: Token resulted in an empty scope array, and scopes are required.", { ...context, jwtPayloadKeys: Object.keys(decoded) });
-            return c.json({ error: "Unauthorized: Token must contain valid, non-empty scopes." }, 401);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.");
         }
         reqWithAuth.auth = {
             token: rawToken,
@@ -120,26 +123,27 @@ export async function mcpAuthMiddleware(c, next) {
         await authContext.run({ authInfo }, next);
     }
     catch (error) {
-        let errorMessage = "Invalid token";
-        if (error instanceof jwt.TokenExpiredError) {
-            errorMessage = "Token expired";
+        let errorMessage = "Invalid token.";
+        let errorCode = BaseErrorCode.UNAUTHORIZED;
+        if (error instanceof Error && error.name === "JWTExpired") {
+            errorMessage = "Token expired.";
             logger.warning("Authentication failed: Token expired.", {
                 ...context,
-                expiredAt: error.expiredAt,
+                errorName: error.name,
             });
         }
-        else if (error instanceof jwt.JsonWebTokenError) {
-            errorMessage = `Invalid token: ${error.message}`;
-            logger.warning(`Authentication failed: ${errorMessage}`, { ...context });
-        }
         else if (error instanceof Error) {
-            errorMessage = `Verification error: ${error.message}`;
-            logger.error("Authentication failed: Unexpected error during token verification.", { ...context, error: error.message });
+            errorMessage = `Invalid token: ${error.message}`;
+            logger.warning(`Authentication failed: ${errorMessage}`, {
+                ...context,
+                errorName: error.name,
+            });
         }
         else {
-            errorMessage = "Unknown verification error";
+            errorMessage = "Unknown verification error.";
+            errorCode = BaseErrorCode.INTERNAL_ERROR;
             logger.error("Authentication failed: Unexpected non-error exception during token verification.", { ...context, error });
         }
-        return c.json({ error: `Unauthorized: ${errorMessage}.` }, 401);
+        throw new McpError(errorCode, errorMessage);
     }
 }

package/dist/mcp-server/transports/{authentication → auth/strategies/oauth}/oauthMiddleware.d.ts

@@ -5,7 +5,7 @@
  * On success, it populates an AuthInfo object and stores it in an AsyncLocalStorage
  * context for use in downstream handlers.
  *
- * @module src/mcp-server/transports/authentication/oauthMiddleware
+ * @module src/mcp-server/transports/auth/strategies/oauth/oauthMiddleware
  */
 import { HttpBindings } from "@hono/node-server";
 import { Context, Next } from "hono";
@@ -17,8 +17,4 @@ import { Context, Next } from "hono";
  */
 export declare function oauthMiddleware(c: Context<{
     Bindings: HttpBindings;
-}>, next: Next): Promise<(Response & import("hono").TypedResponse<{
-    error: string;
-}, 500, "json">) | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 401, "json">) | undefined>;
+}>, next: Next): Promise<void>;

package/dist/mcp-server/transports/{authentication → auth/strategies/oauth}/oauthMiddleware.js

@@ -5,14 +5,14 @@
  * On success, it populates an AuthInfo object and stores it in an AsyncLocalStorage
  * context for use in downstream handlers.
  *
- * @module src/mcp-server/transports/authentication/oauthMiddleware
+ * @module src/mcp-server/transports/auth/strategies/oauth/oauthMiddleware
  */
 import { createRemoteJWKSet, jwtVerify } from "jose";
-import { config } from "../../../config/index.js";
-import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
-import { ErrorHandler } from "../../../utils/internal/errorHandler.js";
-import { logger, requestContextService } from "../../../utils/index.js";
-import { authContext } from "./authContext.js";
+import { config } from "../../../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../../../types-global/errors.js";
+import { logger, requestContextService } from "../../../../../utils/index.js";
+import { ErrorHandler } from "../../../../../utils/internal/errorHandler.js";
+import { authContext } from "../../core/authContext.js";
 // --- Startup Validation ---
 // Ensures that necessary OAuth configuration is present when the mode is 'oauth'.
 if (config.mcpAuthMode === "oauth") {
@@ -57,6 +57,10 @@ if (config.mcpAuthMode === "oauth" && config.oauthIssuerUrl) {
  * @param next - The function to call to proceed to the next middleware.
  */
 export async function oauthMiddleware(c, next) {
+    // If OAuth is not the configured auth mode, skip this middleware.
+    if (config.mcpAuthMode !== "oauth") {
+        return await next();
+    }
     const context = requestContextService.createRequestContext({
         operation: "oauthMiddleware",
         httpMethod: c.req.method,
@@ -64,13 +68,12 @@ export async function oauthMiddleware(c, next) {
     });
     if (!jwks) {
         // This should not happen if startup validation is correct, but it's a safeguard.
-        const error = new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OAuth middleware is active, but JWKS client is not initialized.", context);
-        ErrorHandler.handleError(error, { operation: "oauthMiddleware", context });
-        return c.json({ error: "Server configuration error." }, 500);
+        // This should not happen if startup validation is correct, but it's a safeguard.
+        throw new McpError(BaseErrorCode.CONFIGURATION_ERROR, "OAuth middleware is active, but JWKS client is not initialized.", context);
     }
     const authHeader = c.req.header("Authorization");
     if (!authHeader || !authHeader.startsWith("Bearer ")) {
-        return c.json({ error: "Unauthorized: Missing or invalid token format." }, 401);
+        throw new McpError(BaseErrorCode.UNAUTHORIZED, "Missing or invalid token format.");
     }
     const token = authHeader.substring(7);
     try {
@@ -80,10 +83,14 @@ export async function oauthMiddleware(c, next) {
         });
         // The 'scope' claim is typically a space-delimited string in OAuth 2.1.
         const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+        if (scopes.length === 0) {
+            logger.warning("Authentication failed: Token contains no scopes, but scopes are required.", { ...context, jwtPayloadKeys: Object.keys(payload) });
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token must contain valid, non-empty scopes.");
+        }
         const clientId = typeof payload.client_id === "string" ? payload.client_id : undefined;
         if (!clientId) {
             logger.warning("Authentication failed: OAuth token 'client_id' claim is missing or not a string.", { ...context, jwtPayloadKeys: Object.keys(payload) });
-            return c.json({ error: "Unauthorized: Invalid token, missing client identifier." }, 401);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Invalid token, missing client identifier.");
         }
         const authInfo = {
             token,
@@ -97,13 +104,21 @@ export async function oauthMiddleware(c, next) {
         await authContext.run({ authInfo }, next);
     }
     catch (error) {
-        logger.warning("OAuth token validation failed", {
-            ...context,
-            errorName: error.name,
-            errorMessage: error.message,
+        if (error instanceof Error && error.name === "JWTExpired") {
+            logger.warning("Authentication failed: OAuth token expired.", context);
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, "Token expired.");
+        }
+        const handledError = ErrorHandler.handleError(error, {
+            operation: "oauthMiddleware",
+            context,
+            rethrow: false, // We will throw a new McpError below
         });
-        // The `jose` library provides specific error codes like 'ERR_JWT_EXPIRED' or 'ERR_JWS_INVALID'
-        const message = `Unauthorized: ${error.message || "Invalid token"}`;
-        return c.json({ error: message }, 401);
+        // Ensure we always throw an McpError for consistency
+        if (handledError instanceof McpError) {
+            throw handledError;
+        }
+        else {
+            throw new McpError(BaseErrorCode.UNAUTHORIZED, `Unauthorized: ${handledError.message || "Invalid token"}`, { originalError: handledError.name });
+        }
     }
 }

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

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Centralized error handler for the Hono HTTP transport.
+ * This middleware intercepts errors that occur during request processing,
+ * standardizes them using the application's ErrorHandler utility, and
+ * formats them into a consistent JSON-RPC error response.
+ * @module src/mcp-server/transports/httpErrorHandler
+ */
+import { Context } from "hono";
+import { BaseErrorCode } from "../../types-global/errors.js";
+/**
+ * A centralized error handling middleware for Hono.
+ * This function is registered with `app.onError()` and will catch any errors
+ * thrown from preceding middleware or route handlers.
+ *
+ * @param err - The error that was thrown.
+ * @param c - The Hono context object for the request.
+ * @returns A Response object containing the formatted JSON-RPC error.
+ */
+export declare const httpErrorHandler: (err: Error, c: Context) => Promise<Response & import("hono").TypedResponse<{
+    jsonrpc: string;
+    error: {
+        code: number | BaseErrorCode;
+        message: string;
+    };
+    id: string | number | null;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;

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

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Centralized error handler for the Hono HTTP transport.
+ * This middleware intercepts errors that occur during request processing,
+ * standardizes them using the application's ErrorHandler utility, and
+ * 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";
+/**
+ * A centralized error handling middleware for Hono.
+ * This function is registered with `app.onError()` and will catch any errors
+ * thrown from preceding middleware or route handlers.
+ *
+ * @param err - The error that was thrown.
+ * @param c - The Hono context object for the request.
+ * @returns A Response object containing the formatted JSON-RPC error.
+ */
+export const httpErrorHandler = async (err, c) => {
+    const context = requestContextService.createRequestContext({
+        operation: "httpErrorHandler",
+        path: c.req.path,
+        method: c.req.method,
+    });
+    const handledError = ErrorHandler.handleError(err, {
+        operation: "httpTransport",
+        context,
+    });
+    let status = 500;
+    if (handledError instanceof McpError) {
+        switch (handledError.code) {
+            case BaseErrorCode.NOT_FOUND:
+                status = 404;
+                break;
+            case BaseErrorCode.UNAUTHORIZED:
+                status = 401;
+                break;
+            case BaseErrorCode.FORBIDDEN:
+                status = 403;
+                break;
+            case BaseErrorCode.VALIDATION_ERROR:
+                status = 400;
+                break;
+            case BaseErrorCode.CONFLICT:
+                status = 409;
+                break;
+            case BaseErrorCode.RATE_LIMITED:
+                status = 429;
+                break;
+            default:
+                status = 500;
+        }
+    }
+    // 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;
+    }
+    catch {
+        // Ignore parsing errors, requestId will remain null
+    }
+    const errorCode = handledError instanceof McpError ? handledError.code : -32603;
+    c.status(status);
+    return c.json({
+        jsonrpc: "2.0",
+        error: {
+            code: errorCode,
+            message: handledError.message,
+        },
+        id: requestId,
+    });
+};

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

@@ -1,10 +1,15 @@
 /**
- * @fileoverview Handles the setup and management of the Streamable HTTP MCP transport using Hono.
- * Implements the MCP Specification 2025-03-26 for Streamable HTTP.
- * This includes creating a Hono server, configuring middleware (CORS, Authentication),
- * defining request routing for the single MCP endpoint (POST/GET/DELETE),
- * managing server-side sessions, handling Server-Sent Events (SSE) for streaming,
- * and binding to a network port with retry logic for port conflicts.
+ * @fileoverview Configures and starts the Streamable HTTP MCP transport using Hono.
+ * This module integrates the `@modelcontextprotocol/sdk`'s `StreamableHTTPServerTransport`
+ * into a Hono web server. Its responsibilities include:
+ * - Creating a Hono server instance.
+ * - Applying and configuring middleware for CORS, rate limiting, and authentication (JWT/OAuth).
+ * - Defining the routes (`/mcp` endpoint for POST, GET, DELETE) to handle the MCP lifecycle.
+ * - Orchestrating session management by mapping session IDs to SDK transport instances.
+ * - Implementing port-binding logic with automatic retry on conflicts.
+ *
+ * The underlying implementation of the MCP Streamable HTTP specification, including
+ * Server-Sent Events (SSE) for streaming, is handled by the SDK's transport class.
  *
  * Specification Reference:
  * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/basic/transports.mdx#streamable-http
@@ -13,12 +18,4 @@
 import { ServerType } from "@hono/node-server";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { RequestContext } from "../../utils/index.js";
-/**
- * Sets up and starts the Streamable HTTP transport layer for the MCP server.
- *
- * @param createServerInstanceFn - An asynchronous factory function that returns a new `McpServer` instance.
- * @param parentContext - Logging context from the main server startup process.
- * @returns A promise that resolves with the Node.js `http.Server` instance when the HTTP server is successfully listening.
- * @throws {Error} If the server fails to start after all port retries.
- */
 export declare function startHttpTransport(createServerInstanceFn: () => Promise<McpServer>, parentContext: RequestContext): Promise<ServerType>;