@cyanheads/pubmed-mcp-server 1.0.12

package/dist/services/NCBI/ncbiCoreApiClient.js

@@ -0,0 +1,118 @@
+/**
+ * @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
+ */
+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
+        });
+        logger.debug("NcbiCoreApiClient initialized", requestContextService.createRequestContext({
+            service: "NcbiCoreApiClient",
+            ncbiBaseUrl: NCBI_EUTILS_BASE_URL,
+            maxRetries: config.ncbiMaxRetries,
+        }));
+    }
+    /**
+     * 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 = {}, retries = 0) {
+        const rawParams = {
+            tool: config.ncbiToolIdentifier,
+            email: config.ncbiAdminEmail,
+            api_key: config.ncbiApiKey,
+            ...params,
+        };
+        // Filter out undefined/null values and convert others to string for URLSearchParams/request body
+        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;
+        }
+        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: retries + 1,
+            }));
+            const response = await this.axiosInstance(requestConfig);
+            return response;
+        }
+        catch (error) {
+            if (retries < config.ncbiMaxRetries) {
+                const retryDelay = Math.pow(2, retries) * 200; // Increased base delay for retries
+                logger.warning(`NCBI request to ${endpoint} failed. Retrying (${retries + 1}/${config.ncbiMaxRetries}) in ${retryDelay}ms...`, requestContextService.createRequestContext({
+                    ...context,
+                    operation: "NCBI_HttpRequestRetry",
+                    endpoint,
+                    error: error.message,
+                    retryCount: retries + 1,
+                    maxRetries: config.ncbiMaxRetries,
+                    delay: retryDelay,
+                }));
+                await new Promise((r) => setTimeout(r, retryDelay));
+                return this.makeRequest(endpoint, params, context, options, retries + 1);
+            }
+            if (axios.isAxiosError(error)) {
+                logger.error(`Axios error during NCBI request to ${endpoint} after ${retries} 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 it's already an McpError, rethrow it (could be from a previous stage if this function is used more broadly)
+            if (error instanceof McpError)
+                throw error;
+            logger.error(`Unexpected error during NCBI request to ${endpoint} after ${retries} 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 });
+        }
+    }
+}

package/dist/services/NCBI/ncbiRequestQueueManager.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Manages a queue for NCBI E-utility requests to ensure compliance with rate limits.
+ * @module src/services/NCBI/ncbiRequestQueueManager
+ */
+import { RequestContext } from "../../utils/index.js";
+import { NcbiRequestParams } from "./ncbiConstants.js";
+/**
+ * Interface for a queued NCBI request.
+ */
+export interface QueuedRequest {
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+    task: () => Promise<any>;
+    context: RequestContext;
+    endpoint: string;
+    params: NcbiRequestParams;
+}
+export declare class NcbiRequestQueueManager {
+    private requestQueue;
+    private isProcessingQueue;
+    private lastRequestTime;
+    constructor();
+    /**
+     * Processes the request queue, ensuring delays between requests to respect NCBI rate limits.
+     */
+    private processQueue;
+    /**
+     * Enqueues a task (an NCBI API call) to be processed.
+     * @param task A function that returns a Promise resolving to the API call result.
+     * @param context The request context for logging and correlation.
+     * @param endpoint The NCBI endpoint being called (e.g., "esearch", "efetch").
+     * @param params The parameters for the NCBI request.
+     * @returns A Promise that resolves or rejects with the result of the task.
+     */
+    enqueueRequest<T>(task: () => Promise<T>, context: RequestContext, endpoint: string, params: NcbiRequestParams): Promise<T>;
+}

package/dist/services/NCBI/ncbiRequestQueueManager.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Manages a queue for NCBI E-utility requests to ensure compliance with rate limits.
+ * @module src/services/NCBI/ncbiRequestQueueManager
+ */
+import { config } from "../../config/index.js";
+import { logger, requestContextService, sanitizeInputForLogging, } from "../../utils/index.js";
+export class NcbiRequestQueueManager {
+    constructor() {
+        this.requestQueue = [];
+        this.isProcessingQueue = false;
+        this.lastRequestTime = 0;
+        logger.debug("NcbiRequestQueueManager initialized", requestContextService.createRequestContext({
+            service: "NcbiRequestQueueManager",
+            requestDelay: config.ncbiRequestDelayMs,
+        }));
+    }
+    /**
+     * Processes the request queue, ensuring delays between requests to respect NCBI rate limits.
+     */
+    async processQueue() {
+        if (this.isProcessingQueue || this.requestQueue.length === 0) {
+            return;
+        }
+        this.isProcessingQueue = true;
+        const requestItem = this.requestQueue.shift();
+        if (!requestItem) {
+            this.isProcessingQueue = false;
+            return;
+        }
+        const { resolve, reject, task, context, endpoint, params } = requestItem;
+        try {
+            const now = Date.now();
+            const timeSinceLastRequest = now - this.lastRequestTime;
+            const delayNeeded = config.ncbiRequestDelayMs - timeSinceLastRequest;
+            if (delayNeeded > 0) {
+                logger.debug(`Delaying NCBI request by ${delayNeeded}ms to respect rate limit.`, requestContextService.createRequestContext({
+                    ...context,
+                    operation: "NCBI_RateLimitDelay",
+                    delayNeeded,
+                    endpoint,
+                }));
+                await new Promise((r) => setTimeout(r, delayNeeded));
+            }
+            this.lastRequestTime = Date.now();
+            logger.info(`Executing NCBI request via queue: ${endpoint}`, requestContextService.createRequestContext({
+                ...context,
+                operation: "NCBI_ExecuteFromQueue",
+                endpoint,
+                params: sanitizeInputForLogging(params),
+            }));
+            const result = await task();
+            resolve(result);
+        }
+        catch (error) {
+            logger.error("Error processing NCBI request from queue", error instanceof Error ? error : new Error(String(error)), requestContextService.createRequestContext({
+                ...context,
+                operation: "NCBI_QueueError",
+                endpoint,
+                params: sanitizeInputForLogging(params),
+                errorMessage: error?.message,
+            }));
+            reject(error);
+        }
+        finally {
+            this.isProcessingQueue = false;
+            if (this.requestQueue.length > 0) {
+                // Ensure processQueue is called without awaiting it here to prevent deep stacks
+                Promise.resolve().then(() => this.processQueue());
+            }
+        }
+    }
+    /**
+     * Enqueues a task (an NCBI API call) to be processed.
+     * @param task A function that returns a Promise resolving to the API call result.
+     * @param context The request context for logging and correlation.
+     * @param endpoint The NCBI endpoint being called (e.g., "esearch", "efetch").
+     * @param params The parameters for the NCBI request.
+     * @returns A Promise that resolves or rejects with the result of the task.
+     */
+    enqueueRequest(task, context, endpoint, params) {
+        return new Promise((resolve, reject) => {
+            this.requestQueue.push({
+                resolve,
+                reject,
+                task,
+                context,
+                endpoint,
+                params,
+            });
+            if (!this.isProcessingQueue) {
+                // Ensure processQueue is called without awaiting it here
+                Promise.resolve().then(() => this.processQueue());
+            }
+        });
+    }
+}

package/dist/services/NCBI/ncbiResponseHandler.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Handles parsing of NCBI E-utility responses and NCBI-specific error extraction.
+ * @module src/services/NCBI/ncbiResponseHandler
+ */
+import { AxiosResponse } from "axios";
+import { RequestContext } from "../../utils/index.js";
+import { NcbiRequestOptions } from "./ncbiConstants.js";
+export declare class NcbiResponseHandler {
+    private xmlParser;
+    constructor();
+    private extractNcbiErrorMessages;
+    /**
+     * Parses the raw AxiosResponse data based on retmode and checks for NCBI-specific errors.
+     * @param response The raw AxiosResponse from an NCBI E-utility call.
+     * @param endpoint The E-utility endpoint for context.
+     * @param context The request context for logging.
+     * @param options The original request options, particularly `retmode`.
+     * @returns The parsed data (object for XML/JSON, string for text).
+     * @throws {McpError} If parsing fails or NCBI reports an error in the response body.
+     */
+    parseAndHandleResponse<T = any>(response: AxiosResponse, endpoint: string, context: RequestContext, options: NcbiRequestOptions): T;
+}

package/dist/services/NCBI/ncbiResponseHandler.js

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Handles parsing of NCBI E-utility responses and NCBI-specific error extraction.
+ * @module src/services/NCBI/ncbiResponseHandler
+ */
+import { XMLParser, XMLValidator } from "fast-xml-parser";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+import { logger, requestContextService, sanitizeInputForLogging, } from "../../utils/index.js";
+export class NcbiResponseHandler {
+    constructor() {
+        this.xmlParser = new XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: "@_",
+            parseTagValue: true, // auto-convert numbers, booleans if possible
+            isArray: (name, jpath, isLeafNode, isAttribute) => {
+                // Common NCBI list tags - expand as needed
+                const arrayTags = [
+                    "IdList.Id",
+                    "eSearchResult.IdList.Id",
+                    "PubmedArticleSet.PubmedArticle",
+                    "PubmedArticleSet.DeleteCitation.PMID",
+                    "AuthorList.Author",
+                    "MeshHeadingList.MeshHeading",
+                    "GrantList.Grant",
+                    "KeywordList.Keyword",
+                    "PublicationTypeList.PublicationType",
+                    "LinkSet.LinkSetDb.Link",
+                    "Link.Id",
+                    "DbInfo.FieldList.Field",
+                    "DbInfo.LinkList.Link",
+                    "DocSum.Item", // For ESummary v2.0 JSON-like XML
+                ];
+                return arrayTags.includes(jpath);
+            },
+        });
+        logger.debug("NcbiResponseHandler initialized", requestContextService.createRequestContext({
+            service: "NcbiResponseHandler",
+        }));
+    }
+    extractNcbiErrorMessages(parsedXml) {
+        const messages = [];
+        // Order matters for specificity if multiple error types could exist
+        const errorPaths = [
+            "eLinkResult.ERROR",
+            "eSummaryResult.ERROR",
+            "eSearchResult.ErrorList.PhraseNotFound",
+            "eSearchResult.ErrorList.FieldNotFound",
+            "PubmedArticleSet.ErrorList.CannotRetrievePMID", // More specific error
+            "ERROR", // Generic top-level error
+        ];
+        for (const path of errorPaths) {
+            let errorSource = parsedXml;
+            const parts = path.split(".");
+            for (const part of parts) {
+                if (errorSource &&
+                    typeof errorSource === "object" &&
+                    part in errorSource) {
+                    errorSource = errorSource[part];
+                }
+                else {
+                    errorSource = undefined;
+                    break;
+                }
+            }
+            if (errorSource) {
+                const items = Array.isArray(errorSource) ? errorSource : [errorSource];
+                for (const item of items) {
+                    if (typeof item === "string") {
+                        messages.push(item);
+                    }
+                    else if (item && typeof item["#text"] === "string") {
+                        messages.push(item["#text"]);
+                    }
+                }
+            }
+        }
+        // Handle warnings if no primary errors found
+        if (messages.length === 0 && parsedXml.eSearchResult?.WarningList) {
+            const warningPaths = [
+                "eSearchResult.WarningList.QuotedPhraseNotFound",
+                "eSearchResult.WarningList.OutputMessage",
+            ];
+            for (const path of warningPaths) {
+                let warningSource = parsedXml;
+                const parts = path.split(".");
+                for (const part of parts) {
+                    if (warningSource &&
+                        typeof warningSource === "object" &&
+                        part in warningSource) {
+                        warningSource = warningSource[part];
+                    }
+                    else {
+                        warningSource = undefined;
+                        break;
+                    }
+                }
+                if (warningSource) {
+                    const items = Array.isArray(warningSource)
+                        ? warningSource
+                        : [warningSource];
+                    for (const item of items) {
+                        if (typeof item === "string") {
+                            messages.push(`Warning: ${item}`);
+                        }
+                        else if (item && typeof item["#text"] === "string") {
+                            messages.push(`Warning: ${item["#text"]}`);
+                        }
+                    }
+                }
+            }
+        }
+        return messages.length > 0
+            ? messages
+            : ["Unknown NCBI API error structure."];
+    }
+    /**
+     * Parses the raw AxiosResponse data based on retmode and checks for NCBI-specific errors.
+     * @param response The raw AxiosResponse from an NCBI E-utility call.
+     * @param endpoint The E-utility endpoint for context.
+     * @param context The request context for logging.
+     * @param options The original request options, particularly `retmode`.
+     * @returns The parsed data (object for XML/JSON, string for text).
+     * @throws {McpError} If parsing fails or NCBI reports an error in the response body.
+     */
+    parseAndHandleResponse(response, endpoint, context, options) {
+        const responseData = response.data;
+        const operationContext = requestContextService.createRequestContext({
+            ...context,
+            operation: "NCBI_ParseResponse",
+            endpoint,
+            retmode: options.retmode,
+        });
+        if (options.retmode === "text") {
+            logger.debug("Received text response from NCBI.", operationContext);
+            return responseData;
+        }
+        if (options.retmode === "xml") {
+            logger.debug("Attempting to parse XML response from NCBI.", operationContext);
+            if (typeof responseData !== "string" ||
+                XMLValidator.validate(responseData) !== true) {
+                logger.error("Invalid or non-string XML response from NCBI", new Error("Invalid XML structure"), {
+                    ...operationContext,
+                    responseSnippet: String(responseData).substring(0, 500),
+                });
+                throw new McpError(BaseErrorCode.NCBI_PARSING_ERROR, "Received invalid XML from NCBI.", { endpoint, responseSnippet: String(responseData).substring(0, 200) });
+            }
+            // Always parse for error checking, even if returning raw XML
+            const parsedXml = this.xmlParser.parse(responseData);
+            // Check for error indicators within the parsed XML structure
+            if (parsedXml.eSearchResult?.ErrorList ||
+                parsedXml.eLinkResult?.ERROR ||
+                parsedXml.eSummaryResult?.ERROR ||
+                parsedXml.PubmedArticleSet?.ErrorList || // Check for ErrorList specifically
+                parsedXml.ERROR // Generic top-level error
+            ) {
+                const errorMessages = this.extractNcbiErrorMessages(parsedXml);
+                logger.error("NCBI API returned an error in XML response", new Error(errorMessages.join("; ")), {
+                    ...operationContext,
+                    errors: errorMessages,
+                    parsedXml: sanitizeInputForLogging(parsedXml), // Log the parsed structure for error diagnosis
+                });
+                throw new McpError(BaseErrorCode.NCBI_API_ERROR, `NCBI API Error: ${errorMessages.join("; ")}`, { endpoint, ncbiErrors: errorMessages });
+            }
+            // If raw XML is requested and no errors were found, return the original string
+            if (options.returnRawXml) {
+                logger.debug("Successfully validated XML response. Returning raw XML string as requested.", operationContext);
+                return responseData; // responseData is the raw XML string
+            }
+            logger.debug("Successfully parsed XML response. Returning parsed object.", operationContext);
+            return parsedXml; // Return the parsed object by default
+        }
+        if (options.retmode === "json") {
+            logger.debug("Handling JSON response from NCBI.", operationContext);
+            // Assuming responseData is already parsed by Axios if Content-Type was application/json
+            if (typeof responseData === "object" &&
+                responseData !== null &&
+                responseData.error) {
+                const errorMessage = String(responseData.error);
+                logger.error("NCBI API returned an error in JSON response", new Error(errorMessage), {
+                    ...operationContext,
+                    error: errorMessage,
+                    responseData: sanitizeInputForLogging(responseData),
+                });
+                throw new McpError(BaseErrorCode.NCBI_API_ERROR, `NCBI API Error: ${errorMessage}`, { endpoint, ncbiError: errorMessage });
+            }
+            logger.debug("Successfully processed JSON response.", operationContext);
+            return responseData;
+        }
+        // Fallback for unknown retmode or if retmode is undefined
+        logger.warning(`Response received with unspecified or unhandled retmode: ${options.retmode}. Returning raw data.`, operationContext);
+        return responseData;
+    }
+}

package/dist/services/NCBI/ncbiService.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Service for interacting with NCBI E-utilities.
+ * This module centralizes all communication with NCBI's E-utility APIs,
+ * handling request construction, API key management, rate limiting,
+ * retries, and parsing of XML/JSON responses. It aims to provide a robust
+ * and compliant interface for other parts of the pubmed-mcp-server to
+ * access PubMed data.
+ * @module src/services/NCBI/ncbiService
+ */
+import { RequestContext } from "../../utils/index.js";
+import { NcbiRequestParams, NcbiRequestOptions } from "./ncbiConstants.js";
+export declare class NcbiService {
+    private queueManager;
+    private apiClient;
+    private responseHandler;
+    constructor();
+    private performNcbiRequest;
+    eSearch(params: NcbiRequestParams, context: RequestContext): Promise<any>;
+    eSummary(params: NcbiRequestParams, context: RequestContext): Promise<any>;
+    eFetch(params: NcbiRequestParams, context: RequestContext, options?: NcbiRequestOptions): Promise<any>;
+    eLink(params: NcbiRequestParams, context: RequestContext): Promise<any>;
+    eInfo(params: NcbiRequestParams, context: RequestContext): Promise<any>;
+}
+export declare const ncbiService: NcbiService;

package/dist/services/NCBI/ncbiService.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Service for interacting with NCBI E-utilities.
+ * This module centralizes all communication with NCBI's E-utility APIs,
+ * handling request construction, API key management, rate limiting,
+ * retries, and parsing of XML/JSON responses. It aims to provide a robust
+ * and compliant interface for other parts of the pubmed-mcp-server to
+ * access PubMed data.
+ * @module src/services/NCBI/ncbiService
+ */
+import { logger, requestContextService, } from "../../utils/index.js";
+import { NcbiCoreApiClient } from "./ncbiCoreApiClient.js";
+import { NcbiRequestQueueManager } from "./ncbiRequestQueueManager.js";
+import { NcbiResponseHandler } from "./ncbiResponseHandler.js";
+export class NcbiService {
+    constructor() {
+        this.queueManager = new NcbiRequestQueueManager();
+        this.apiClient = new NcbiCoreApiClient();
+        this.responseHandler = new NcbiResponseHandler();
+        logger.debug("NcbiService initialized with new modular architecture", requestContextService.createRequestContext({
+            service: "NcbiService",
+        }));
+    }
+    async performNcbiRequest(endpoint, params, context, options = {}) {
+        const task = async () => {
+            const rawResponse = await this.apiClient.makeRequest(endpoint, params, context, options);
+            return this.responseHandler.parseAndHandleResponse(rawResponse, endpoint, context, options);
+        };
+        return this.queueManager.enqueueRequest(task, context, endpoint, params);
+    }
+    async eSearch(params, context) {
+        return this.performNcbiRequest("esearch", params, context, {
+            retmode: "xml",
+        });
+    }
+    async eSummary(params, context) {
+        // Determine retmode based on params, default to xml
+        const retmode = params.version === "2.0" && params.retmode === "json" ? "json" : "xml";
+        return this.performNcbiRequest("esummary", params, context, { retmode });
+    }
+    async eFetch(params, context, options = { retmode: "xml" }) {
+        // Determine if POST should be used based on number of IDs
+        const usePost = typeof params.id === "string" && params.id.split(",").length > 200;
+        const fetchOptions = { ...options, usePost };
+        return this.performNcbiRequest("efetch", params, context, fetchOptions);
+    }
+    async eLink(params, context) {
+        return this.performNcbiRequest("elink", params, context, {
+            retmode: "xml",
+        });
+    }
+    async eInfo(params, context) {
+        return this.performNcbiRequest("einfo", params, context, {
+            retmode: "xml",
+        });
+    }
+}
+export const ncbiService = new NcbiService();

package/dist/services/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Main barrel file for all services.
+ * This file re-exports all service modules, providing a single entry point
+ * for accessing various services within the application.
+ * @module src/services/index
+ */
+export * from "./llm-providers";

package/dist/services/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Main barrel file for all services.
+ * This file re-exports all service modules, providing a single entry point
+ * for accessing various services within the application.
+ * @module src/services/index
+ */
+export * from "./llm-providers";

package/dist/services/llm-providers/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for LLM provider services.
+ * This file re-exports all services related to different Large Language Model providers,
+ * making them easily accessible from a single import path.
+ * @module src/services/llm-providers/index
+ */
+export * from "./openRouter";

package/dist/services/llm-providers/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for LLM provider services.
+ * This file re-exports all services related to different Large Language Model providers,
+ * making them easily accessible from a single import path.
+ * @module src/services/llm-providers/index
+ */
+export * from "./openRouter"; // Changed to export from the new barrel file

package/dist/services/llm-providers/llmFactory.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Factory for creating LLM client instances.
+ * Provides a centralized way to instantiate clients for different LLM providers
+ * like OpenRouter and Google Gemini, handling API key configuration and
+ * basic client setup.
+ * @module src/services/llm-providers/llmFactory
+ */
+import { GoogleGenAI } from "@google/genai";
+import OpenAI from "openai";
+import { RequestContext } from "../../utils/index.js";
+/**
+ * Defines the supported LLM providers.
+ */
+export type LlmProviderType = "openrouter" | "gemini";
+/**
+ * Options for configuring the OpenRouter client.
+ */
+export interface OpenRouterClientOptions {
+    apiKey?: string;
+    baseURL?: string;
+    siteUrl?: string;
+    siteName?: string;
+}
+/**
+ * Options for configuring the Gemini client using @google/genai.
+ * The factory will return a GoogleGenAI instance.
+ * Vertex AI specific options are included here.
+ */
+export interface GeminiClientOptions {
+    apiKey?: string;
+    useVertexAi?: boolean;
+    project?: string;
+    location?: string;
+}
+/**
+ * Union type for all LLM client options.
+ */
+export type LlmClientOptions = OpenRouterClientOptions | GeminiClientOptions;
+/**
+ * LLM Factory class to create and configure LLM clients.
+ */
+declare class LlmFactory {
+    /**
+     * Creates and returns an LLM client instance for the specified provider.
+     *
+     * @param provider - The LLM provider to create a client for.
+     * @param context - The request context for logging.
+     * @param options - Optional provider-specific configuration options.
+     * @returns A Promise resolving to an instance of OpenAI (for OpenRouter)
+     *          or GoogleGenAI (for Gemini).
+     * @throws {McpError} If the provider is unsupported or API key/config is missing.
+     */
+    getLlmClient(provider: LlmProviderType, context: RequestContext, options?: LlmClientOptions): Promise<OpenAI | GoogleGenAI>;
+    /**
+     * Creates an OpenAI client configured for OpenRouter.
+     * @private
+     */
+    private createOpenRouterClient;
+    /**
+     * Creates a GoogleGenAI client for Gemini, supporting standard API key or Vertex AI.
+     * @private
+     */
+    private createGeminiClient;
+}
+/**
+ * Singleton instance of the LlmFactory.
+ */
+export declare const llmFactory: LlmFactory;
+export {};