@cyanheads/pubmed-mcp-server 1.2.3 → 1.3.0

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

@@ -0,0 +1,251 @@
+/**
+ * @fileoverview Configures and starts the HTTP MCP transport using Hono.
+ * This file has been refactored to correctly integrate Hono's streaming
+ * capabilities with the Model Context Protocol SDK's transport layer.
+ * @module src/mcp-server/transports/http/httpTransport
+ */
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { stream } from "hono/streaming";
+import http from "http";
+import { config } from "../../../config/index.js";
+import { logger, rateLimiter, requestContextService, } from "../../../utils/index.js";
+import { createAuthMiddleware, createAuthStrategy } from "../auth/index.js";
+import { StatefulTransportManager } from "../core/statefulTransportManager.js";
+import { StatelessTransportManager } from "../core/statelessTransportManager.js";
+import { httpErrorHandler } from "./httpErrorHandler.js";
+import { mcpTransportMiddleware } from "./mcpTransportMiddleware.js";
+const HTTP_PORT = config.mcpHttpPort;
+const HTTP_HOST = config.mcpHttpHost;
+const MCP_ENDPOINT_PATH = config.mcpHttpEndpointPath;
+/**
+ * Converts a Fetch API Headers object to Node.js IncomingHttpHeaders.
+ * Hono uses Fetch API Headers, but the underlying transport managers expect
+ * Node's native IncomingHttpHeaders.
+ * @param headers - The Headers object to convert.
+ * @returns An object compatible with IncomingHttpHeaders.
+ */
+async function isPortInUse(port, host, parentContext) {
+    const context = { ...parentContext, operation: "isPortInUse", port, host };
+    logger.debug(`Checking if port ${port} is in use...`, context);
+    return new Promise((resolve) => {
+        const tempServer = http.createServer();
+        tempServer
+            .once("error", (err) => {
+            const inUse = err.code === "EADDRINUSE";
+            logger.debug(`Port check resulted in error: ${err.code}. Port in use: ${inUse}`, context);
+            resolve(inUse);
+        })
+            .once("listening", () => {
+            logger.debug(`Successfully bound to port ${port} temporarily. Port is not in use.`, context);
+            tempServer.close(() => resolve(false));
+        })
+            .listen(port, host);
+    });
+}
+function startHttpServerWithRetry(app, initialPort, host, maxRetries, parentContext) {
+    const startContext = {
+        ...parentContext,
+        operation: "startHttpServerWithRetry",
+    };
+    logger.info(`Attempting to start HTTP server on port ${initialPort} with ${maxRetries} retries.`, startContext);
+    return new Promise((resolve, reject) => {
+        const tryBind = (port, attempt) => {
+            const attemptContext = { ...startContext, port, attempt };
+            if (attempt > maxRetries + 1) {
+                const error = new Error(`Failed to bind to any port after ${maxRetries} retries.`);
+                logger.fatal(error.message, attemptContext);
+                return reject(error);
+            }
+            isPortInUse(port, host, attemptContext)
+                .then((inUse) => {
+                if (inUse) {
+                    logger.warning(`Port ${port} is in use, retrying on port ${port + 1}...`, attemptContext);
+                    setTimeout(() => tryBind(port + 1, attempt + 1), config.mcpHttpPortRetryDelayMs);
+                    return;
+                }
+                try {
+                    const serverInstance = serve({ fetch: app.fetch, port, hostname: host }, (info) => {
+                        const serverAddress = `http://${info.address}:${info.port}${MCP_ENDPOINT_PATH}`;
+                        logger.info(`HTTP transport listening at ${serverAddress}`, {
+                            ...attemptContext,
+                            address: serverAddress,
+                            sessionMode: config.mcpSessionMode,
+                        });
+                        if (process.stdout.isTTY) {
+                            console.log(`\n🚀 MCP Server running at: ${serverAddress}`);
+                            console.log(`   Session Mode: ${config.mcpSessionMode}\n`);
+                        }
+                    });
+                    resolve(serverInstance);
+                }
+                catch (err) {
+                    if (err &&
+                        typeof err === "object" &&
+                        "code" in err &&
+                        err.code !== "EADDRINUSE") {
+                        const errorToLog = err instanceof Error ? err : new Error(String(err));
+                        logger.error("An unexpected error occurred while starting the server.", errorToLog, attemptContext);
+                        return reject(err);
+                    }
+                    logger.warning(`Encountered EADDRINUSE race condition on port ${port}, retrying...`, attemptContext);
+                    setTimeout(() => tryBind(port + 1, attempt + 1), config.mcpHttpPortRetryDelayMs);
+                }
+            })
+                .catch((err) => {
+                logger.fatal("Failed to check if port is in use.", err, attemptContext);
+                reject(err);
+            });
+        };
+        tryBind(initialPort, 1);
+    });
+}
+function createTransportManager(createServerInstanceFn, sessionMode, context) {
+    const opContext = {
+        ...context,
+        operation: "createTransportManager",
+        sessionMode,
+    };
+    logger.info(`Creating transport manager for session mode: ${sessionMode}`, opContext);
+    switch (sessionMode) {
+        case "stateless":
+            return new StatelessTransportManager(createServerInstanceFn);
+        case "stateful":
+            return new StatefulTransportManager(createServerInstanceFn);
+        case "auto":
+        default:
+            logger.info("Defaulting to 'auto' mode (stateful with stateless fallback).", opContext);
+            return new StatefulTransportManager(createServerInstanceFn);
+    }
+}
+export function createHttpApp(transportManager, createServerInstanceFn, parentContext) {
+    const app = new Hono();
+    const transportContext = {
+        ...parentContext,
+        component: "HttpTransportSetup",
+    };
+    logger.info("Creating Hono HTTP application.", transportContext);
+    app.use("*", cors({
+        origin: config.mcpAllowedOrigins || [],
+        allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
+        allowHeaders: [
+            "Content-Type",
+            "Mcp-Session-Id",
+            "Last-Event-ID",
+            "Authorization",
+        ],
+        credentials: true,
+    }));
+    app.use("*", async (c, next) => {
+        c.env.outgoing.setHeader("X-Content-Type-Options", "nosniff");
+        await next();
+    });
+    app.use(MCP_ENDPOINT_PATH, async (c, next) => {
+        const clientIp = c.req.header("x-forwarded-for")?.split(",")[0].trim() || "unknown_ip";
+        const context = requestContextService.createRequestContext({
+            operation: "httpRateLimitCheck",
+            ipAddress: clientIp,
+        });
+        try {
+            rateLimiter.check(clientIp, context);
+            logger.debug("Rate limit check passed.", context);
+        }
+        catch (error) {
+            logger.warning("Rate limit check failed.", {
+                ...context,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        await next();
+    });
+    const authStrategy = createAuthStrategy();
+    if (authStrategy) {
+        logger.info("Authentication strategy found, enabling auth middleware.", transportContext);
+        app.use(MCP_ENDPOINT_PATH, createAuthMiddleware(authStrategy));
+    }
+    else {
+        logger.info("No authentication strategy found, auth middleware disabled.", transportContext);
+    }
+    app.onError(httpErrorHandler);
+    app.get("/healthz", (c) => {
+        return c.json({
+            status: "ok",
+            timestamp: new Date().toISOString(),
+        });
+    });
+    app.get(MCP_ENDPOINT_PATH, (c) => {
+        const sessionId = c.req.header("mcp-session-id");
+        if (sessionId) {
+            return c.text("GET requests to existing sessions are not supported.", 405);
+        }
+        return c.json({
+            status: "ok",
+            mode: "stateless",
+            message: "Server is running. Provide a Mcp-Session-Id header to stream from a session.",
+        });
+    });
+    app.post(MCP_ENDPOINT_PATH, mcpTransportMiddleware(transportManager, createServerInstanceFn), (c) => {
+        const response = c.get("mcpResponse");
+        if (response.sessionId) {
+            c.header("Mcp-Session-Id", response.sessionId);
+        }
+        response.headers.forEach((value, key) => {
+            c.header(key, value);
+        });
+        c.status(response.statusCode);
+        if (response.stream) {
+            return stream(c, async (s) => {
+                if (response.stream) {
+                    await s.pipe(response.stream);
+                }
+            });
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return c.json(response.body);
+        }
+    });
+    app.delete(MCP_ENDPOINT_PATH, async (c) => {
+        const sessionId = c.req.header("mcp-session-id");
+        const context = requestContextService.createRequestContext({
+            ...transportContext,
+            operation: "handleDeleteRequest",
+            sessionId,
+        });
+        if (sessionId) {
+            if (transportManager instanceof StatefulTransportManager) {
+                const response = await transportManager.handleDeleteRequest(sessionId, context);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return c.json(response.body, response.statusCode);
+            }
+            else {
+                return c.json({
+                    error: "Method Not Allowed",
+                    message: "DELETE operations are not supported in this mode.",
+                }, 405);
+            }
+        }
+        else {
+            return c.json({
+                status: "stateless_mode",
+                message: "No sessions to delete in stateless mode",
+            });
+        }
+    });
+    logger.info("Hono application setup complete.", transportContext);
+    return app;
+}
+export async function startHttpTransport(createServerInstanceFn, parentContext) {
+    const transportContext = {
+        ...parentContext,
+        component: "HttpTransportStart",
+    };
+    logger.info("Starting HTTP transport.", transportContext);
+    const transportManager = createTransportManager(createServerInstanceFn, config.mcpSessionMode, transportContext);
+    const app = createHttpApp(transportManager, createServerInstanceFn, transportContext);
+    const server = await startHttpServerWithRetry(app, HTTP_PORT, HTTP_HOST, config.mcpHttpMaxPortRetries, transportContext);
+    logger.info("HTTP transport started successfully.", transportContext);
+    return { app, server, transportManager };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Defines custom types for the Hono HTTP transport layer.
+ * @module src/mcp-server/transports/http/httpTypes
+ */
+import type { IncomingMessage, ServerResponse } from "http";
+/**
+ * Extends Hono's Bindings to include the raw Node.js request and response objects.
+ * This is necessary for integrating with libraries like the MCP SDK that
+ * need to write directly to the response stream.
+ *
+ * As per `@hono/node-server`, the response object is available on `c.env.outgoing`.
+ */
+export type HonoNodeBindings = {
+    incoming: IncomingMessage;
+    outgoing: ServerResponse;
+};

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

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Defines custom types for the Hono HTTP transport layer.
+ * @module src/mcp-server/transports/http/httpTypes
+ */
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the HTTP transport module.
+ * @module src/mcp-server/transports/http/index
+ */
+export { createHttpApp, startHttpTransport } from "./httpTransport.js";
+export { httpErrorHandler } from "./httpErrorHandler.js";
+export type { HonoNodeBindings } from "./httpTypes.js";

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

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the HTTP transport module.
+ * @module src/mcp-server/transports/http/index
+ */
+export { createHttpApp, startHttpTransport } from "./httpTransport.js";
+export { httpErrorHandler } from "./httpErrorHandler.js";

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

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Hono middleware for handling MCP transport logic.
+ * This middleware encapsulates the logic for processing MCP requests,
+ * delegating to the appropriate transport manager, and preparing the
+ * response for Hono to send.
+ * @module src/mcp-server/transports/http/mcpTransportMiddleware
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TransportManager, TransportResponse } from "../core/transportTypes.js";
+import { HonoNodeBindings } from "./httpTypes.js";
+/**
+ * Creates a Hono middleware for handling MCP POST requests.
+ * @param transportManager - The main transport manager (usually stateful).
+ * @param createServerInstanceFn - Function to create an McpServer instance.
+ * @returns A Hono middleware function.
+ */
+type McpMiddlewareEnv = {
+    Variables: {
+        mcpResponse: TransportResponse;
+    };
+};
+export declare const mcpTransportMiddleware: (transportManager: TransportManager, createServerInstanceFn: () => Promise<McpServer>) => import("hono").MiddlewareHandler<McpMiddlewareEnv & {
+    Bindings: HonoNodeBindings;
+}, string, {}>;
+export {};

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

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Hono middleware for handling MCP transport logic.
+ * This middleware encapsulates the logic for processing MCP requests,
+ * delegating to the appropriate transport manager, and preparing the
+ * response for Hono to send.
+ * @module src/mcp-server/transports/http/mcpTransportMiddleware
+ */
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createMiddleware } from "hono/factory";
+import { config } from "../../../config/index.js";
+import { requestContextService } from "../../../utils/index.js";
+import { StatelessTransportManager } from "../core/statelessTransportManager.js";
+/**
+ * Converts a Fetch API Headers object to Node.js IncomingHttpHeaders.
+ * @param headers - The Headers object to convert.
+ * @returns An object compatible with IncomingHttpHeaders.
+ */
+function toIncomingHttpHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+/**
+ * Handles a stateless request by creating an ephemeral transport manager.
+ * @param createServerInstanceFn - Function to create an McpServer instance.
+ * @param headers - The request headers.
+ * @param body - The request body.
+ * @param context - The request context.
+ * @returns A promise resolving with the transport response.
+ */
+async function handleStatelessRequest(createServerInstanceFn, headers, body, context) {
+    const statelessManager = new StatelessTransportManager(createServerInstanceFn);
+    return statelessManager.handleRequest(toIncomingHttpHeaders(headers), body, context);
+}
+export const mcpTransportMiddleware = (transportManager, createServerInstanceFn) => createMiddleware(async (c, next) => {
+    const sessionId = c.req.header("mcp-session-id");
+    const context = requestContextService.createRequestContext({
+        operation: "mcpTransportMiddleware",
+        sessionId,
+    });
+    const body = await c.req.json();
+    let response;
+    if (isInitializeRequest(body)) {
+        if (config.mcpSessionMode === "stateless") {
+            response = await handleStatelessRequest(createServerInstanceFn, c.req.raw.headers, body, context);
+        }
+        else {
+            response = await transportManager.initializeAndHandle(toIncomingHttpHeaders(c.req.raw.headers), body, context);
+        }
+    }
+    else {
+        if (sessionId) {
+            response = await transportManager.handleRequest(toIncomingHttpHeaders(c.req.raw.headers), body, context, sessionId);
+        }
+        else {
+            response = await handleStatelessRequest(createServerInstanceFn, c.req.raw.headers, body, context);
+        }
+    }
+    c.set("mcpResponse", response);
+    await next();
+});

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

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Barrel file for the Stdio transport module.
+ * @module src/mcp-server/transports/stdio/index
+ */
+export { startStdioTransport } from "./stdioTransport.js";

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

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Barrel file for the Stdio transport module.
+ * @module src/mcp-server/transports/stdio/index
+ */
+export { startStdioTransport } from "./stdioTransport.js";

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

@@ -18,7 +18,7 @@
  * @module src/mcp-server/transports/stdioTransport
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { RequestContext } from "../../utils/index.js";
+import { RequestContext } from "../../../utils/index.js";
 /**
  * Connects a given `McpServer` instance to the Stdio transport.
  * This function initializes the SDK's `StdioServerTransport`, which manages
@@ -39,4 +39,4 @@ import { RequestContext } from "../../utils/index.js";
  * @returns A promise that resolves when the Stdio transport is successfully connected.
  * @throws {Error} If the connection fails during setup.
  */
-export declare function connectStdioTransport(server: McpServer, parentContext: RequestContext): Promise<void>;
+export declare function startStdioTransport(server: McpServer, parentContext: RequestContext): Promise<void>;

package/dist/mcp-server/transports/{stdioTransport.js → stdio/stdioTransport.js}

@@ -18,7 +18,7 @@
  * @module src/mcp-server/transports/stdioTransport
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { ErrorHandler, logger } from "../../utils/index.js";
+import { ErrorHandler, logger } from "../../../utils/index.js";
 /**
  * Connects a given `McpServer` instance to the Stdio transport.
  * This function initializes the SDK's `StdioServerTransport`, which manages
@@ -39,13 +39,13 @@ import { ErrorHandler, logger } from "../../utils/index.js";
  * @returns A promise that resolves when the Stdio transport is successfully connected.
  * @throws {Error} If the connection fails during setup.
  */
-export async function connectStdioTransport(server, parentContext) {
+export async function startStdioTransport(server, parentContext) {
     const operationContext = {
         ...parentContext,
         operation: "connectStdioTransport",
         transportType: "Stdio",
     };
-    logger.debug("Attempting to connect stdio transport...", operationContext);
+    logger.info("Attempting to connect stdio transport...", operationContext);
     try {
         logger.debug("Creating StdioServerTransport instance...", operationContext);
         const transport = new StdioServerTransport();
@@ -57,7 +57,12 @@ export async function connectStdioTransport(server, parentContext) {
         }
     }
     catch (err) {
-        ErrorHandler.handleError(err, { ...operationContext, critical: true });
-        throw err; // Re-throw after handling to allow caller to react if necessary
+        // Let the ErrorHandler log the error with all context, then rethrow.
+        throw ErrorHandler.handleError(err, {
+            operation: "connectStdioTransport",
+            context: operationContext,
+            critical: true,
+            rethrow: true,
+        });
     }
 }

package/dist/services/NCBI/{ncbiConstants.d.ts → core/ncbiConstants.d.ts}

@@ -1,6 +1,6 @@
 /**
  * @fileoverview Constants and shared type definitions for NCBI E-utility interactions.
- * @module src/services/NCBI/ncbiConstants
+ * @module src/services/NCBI/core/ncbiConstants
  */
 export declare const NCBI_EUTILS_BASE_URL = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
 /**

package/dist/services/NCBI/{ncbiConstants.js → core/ncbiConstants.js}

@@ -1,5 +1,5 @@
 /**
  * @fileoverview Constants and shared type definitions for NCBI E-utility interactions.
- * @module src/services/NCBI/ncbiConstants
+ * @module src/services/NCBI/core/ncbiConstants
  */
 export const NCBI_EUTILS_BASE_URL = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";

package/dist/services/NCBI/{ncbiCoreApiClient.d.ts → core/ncbiCoreApiClient.d.ts}

@@ -1,10 +1,10 @@
 /**
  * @fileoverview Core client for making HTTP requests to NCBI E-utilities.
  * Handles request construction, API key injection, retries, and basic error handling.
- * @module src/services/NCBI/ncbiCoreApiClient
+ * @module src/services/NCBI/core/ncbiCoreApiClient
  */
 import { AxiosResponse } from "axios";
-import { RequestContext } from "../../utils/index.js";
+import { RequestContext } from "../../../utils/index.js";
 import { NcbiRequestParams, NcbiRequestOptions } from "./ncbiConstants.js";
 export declare class NcbiCoreApiClient {
     private axiosInstance;
@@ -20,5 +20,5 @@ export declare class NcbiCoreApiClient {
      * @returns A Promise resolving to the raw AxiosResponse.
      * @throws {McpError} If the request fails after all retries or an unexpected error occurs.
      */
-    makeRequest(endpoint: string, params: NcbiRequestParams, context: RequestContext, options?: NcbiRequestOptions, retries?: number): Promise<AxiosResponse>;
+    makeRequest(endpoint: string, params: NcbiRequestParams, context: RequestContext, options?: NcbiRequestOptions): Promise<AxiosResponse>;
 }

package/dist/services/NCBI/core/ncbiCoreApiClient.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Core client for making HTTP requests to NCBI E-utilities.
+ * Handles request construction, API key injection, retries, and basic error handling.
+ * @module src/services/NCBI/core/ncbiCoreApiClient
+ */
+import axios from "axios";
+import { config } from "../../../config/index.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
+import { NCBI_EUTILS_BASE_URL, } from "./ncbiConstants.js";
+export class NcbiCoreApiClient {
+    constructor() {
+        this.axiosInstance = axios.create({
+            timeout: 30000, // 30 seconds timeout for NCBI requests
+        });
+    }
+    /**
+     * Makes an HTTP request to the specified NCBI E-utility endpoint.
+     * Handles parameter assembly, API key injection, GET/POST selection, and retries.
+     * @param endpoint The E-utility endpoint (e.g., "esearch", "efetch").
+     * @param params The parameters for the E-utility.
+     * @param context The request context for logging.
+     * @param options Options for the request, like retmode and whether to use POST.
+     * @param retries The current retry attempt number.
+     * @returns A Promise resolving to the raw AxiosResponse.
+     * @throws {McpError} If the request fails after all retries or an unexpected error occurs.
+     */
+    async makeRequest(endpoint, params, context, options = {}) {
+        const rawParams = {
+            tool: config.ncbiToolIdentifier,
+            email: config.ncbiAdminEmail,
+            api_key: config.ncbiApiKey,
+            ...params,
+        };
+        const finalParams = {};
+        for (const key in rawParams) {
+            if (Object.prototype.hasOwnProperty.call(rawParams, key)) {
+                const value = rawParams[key];
+                if (value !== undefined && value !== null) {
+                    finalParams[key] = String(value);
+                }
+            }
+        }
+        const requestConfig = {
+            method: options.usePost ? "POST" : "GET",
+            url: `${NCBI_EUTILS_BASE_URL}/${endpoint}.fcgi`,
+        };
+        if (options.usePost) {
+            requestConfig.data = new URLSearchParams(finalParams).toString();
+            requestConfig.headers = {
+                "Content-Type": "application/x-www-form-urlencoded",
+            };
+        }
+        else {
+            requestConfig.params = finalParams;
+        }
+        for (let attempt = 0; attempt <= config.ncbiMaxRetries; attempt++) {
+            try {
+                logger.debug(`Making NCBI HTTP request: ${requestConfig.method} ${requestConfig.url}`, requestContextService.createRequestContext({
+                    ...context,
+                    operation: "NCBI_HttpRequest",
+                    endpoint,
+                    method: requestConfig.method,
+                    requestParams: sanitizeInputForLogging(finalParams),
+                    attempt: attempt + 1,
+                }));
+                const response = await this.axiosInstance(requestConfig);
+                return response;
+            }
+            catch (error) {
+                if (attempt < config.ncbiMaxRetries) {
+                    const retryDelay = Math.pow(2, attempt) * 200;
+                    logger.warning(`NCBI request to ${endpoint} failed. Retrying (${attempt + 1}/${config.ncbiMaxRetries}) in ${retryDelay}ms...`, requestContextService.createRequestContext({
+                        ...context,
+                        operation: "NCBI_HttpRequestRetry",
+                        endpoint,
+                        error: error.message,
+                        retryCount: attempt + 1,
+                        maxRetries: config.ncbiMaxRetries,
+                        delay: retryDelay,
+                    }));
+                    await new Promise((r) => setTimeout(r, retryDelay));
+                    continue; // Continue to the next iteration of the loop
+                }
+                // If all retries are exhausted, handle the final error
+                if (axios.isAxiosError(error)) {
+                    logger.error(`Axios error during NCBI request to ${endpoint} after ${attempt} retries`, error, requestContextService.createRequestContext({
+                        ...context,
+                        operation: "NCBI_AxiosError",
+                        endpoint,
+                        status: error.response?.status,
+                        responseData: sanitizeInputForLogging(error.response?.data),
+                    }));
+                    throw new McpError(BaseErrorCode.NCBI_SERVICE_UNAVAILABLE, `NCBI request failed: ${error.message}`, {
+                        endpoint,
+                        status: error.response?.status,
+                        details: error.response?.data
+                            ? String(error.response.data).substring(0, 500)
+                            : undefined,
+                    });
+                }
+                if (error instanceof McpError)
+                    throw error;
+                logger.error(`Unexpected error during NCBI request to ${endpoint} after ${attempt} retries`, error, requestContextService.createRequestContext({
+                    ...context,
+                    operation: "NCBI_UnexpectedError",
+                    endpoint,
+                    errorMessage: error.message,
+                }));
+                throw new McpError(BaseErrorCode.INTERNAL_ERROR, `Unexpected error communicating with NCBI: ${error.message}`, { endpoint });
+            }
+        }
+        // This line should theoretically be unreachable, but it satisfies TypeScript's need
+        // for a return path if the loop completes without returning or throwing.
+        throw new McpError(BaseErrorCode.INTERNAL_ERROR, "Request failed after all retries.", { endpoint });
+    }
+}

package/dist/services/NCBI/{ncbiRequestQueueManager.d.ts → core/ncbiRequestQueueManager.d.ts}

@@ -1,8 +1,8 @@
 /**
  * @fileoverview Manages a queue for NCBI E-utility requests to ensure compliance with rate limits.
- * @module src/services/NCBI/ncbiRequestQueueManager
+ * @module src/services/NCBI/core/ncbiRequestQueueManager
  */
-import { RequestContext } from "../../utils/index.js";
+import { RequestContext } from "../../../utils/index.js";
 import { NcbiRequestParams } from "./ncbiConstants.js";
 /**
  * Interface for a queued NCBI request.

package/dist/services/NCBI/{ncbiRequestQueueManager.js → core/ncbiRequestQueueManager.js}

@@ -1,9 +1,9 @@
 /**
  * @fileoverview Manages a queue for NCBI E-utility requests to ensure compliance with rate limits.
- * @module src/services/NCBI/ncbiRequestQueueManager
+ * @module src/services/NCBI/core/ncbiRequestQueueManager
  */
-import { config } from "../../config/index.js";
-import { logger, requestContextService, sanitizeInputForLogging, } from "../../utils/index.js";
+import { config } from "../../../config/index.js";
+import { logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
 export class NcbiRequestQueueManager {
     constructor() {
         this.requestQueue = [];

package/dist/services/NCBI/{ncbiResponseHandler.d.ts → core/ncbiResponseHandler.d.ts}

@@ -1,9 +1,9 @@
 /**
  * @fileoverview Handles parsing of NCBI E-utility responses and NCBI-specific error extraction.
- * @module src/services/NCBI/ncbiResponseHandler
+ * @module src/services/NCBI/core/ncbiResponseHandler
  */
 import { AxiosResponse } from "axios";
-import { RequestContext } from "../../utils/index.js";
+import { RequestContext } from "../../../utils/index.js";
 import { NcbiRequestOptions } from "./ncbiConstants.js";
 export declare class NcbiResponseHandler {
     private xmlParser;

package/dist/services/NCBI/{ncbiResponseHandler.js → core/ncbiResponseHandler.js}

@@ -1,10 +1,10 @@
 /**
  * @fileoverview Handles parsing of NCBI E-utility responses and NCBI-specific error extraction.
- * @module src/services/NCBI/ncbiResponseHandler
+ * @module src/services/NCBI/core/ncbiResponseHandler
  */
 import { XMLParser, XMLValidator } from "fast-xml-parser";
-import { BaseErrorCode, McpError } from "../../types-global/errors.js";
-import { logger, requestContextService, sanitizeInputForLogging, } from "../../utils/index.js";
+import { BaseErrorCode, McpError } from "../../../types-global/errors.js";
+import { logger, requestContextService, sanitizeInputForLogging, } from "../../../utils/index.js";
 export class NcbiResponseHandler {
     constructor() {
         this.xmlParser = new XMLParser({