@cyanheads/pubmed-mcp-server 1.2.3 → 1.3.0

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

@@ -5,9 +5,10 @@
  * 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
+ * @module src/services/NCBI/core/ncbiService
  */
-import { RequestContext } from "../../utils/index.js";
+import { ESearchResult, EFetchArticleSet } from "../../../types-global/pubmedXml.js";
+import { RequestContext } from "../../../utils/index.js";
 import { NcbiRequestParams, NcbiRequestOptions } from "./ncbiConstants.js";
 export declare class NcbiService {
     private queueManager;
@@ -15,9 +16,9 @@ export declare class NcbiService {
     private responseHandler;
     constructor();
     private performNcbiRequest;
-    eSearch(params: NcbiRequestParams, context: RequestContext): Promise<any>;
+    eSearch(params: NcbiRequestParams, context: RequestContext): Promise<ESearchResult>;
     eSummary(params: NcbiRequestParams, context: RequestContext): Promise<any>;
-    eFetch(params: NcbiRequestParams, context: RequestContext, options?: NcbiRequestOptions): Promise<any>;
+    eFetch(params: NcbiRequestParams, context: RequestContext, options?: NcbiRequestOptions): Promise<EFetchArticleSet>;
     eLink(params: NcbiRequestParams, context: RequestContext): Promise<any>;
     eInfo(params: NcbiRequestParams, context: RequestContext): Promise<any>;
 }

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

@@ -5,9 +5,9 @@
  * 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
+ * @module src/services/NCBI/core/ncbiService
  */
-import { logger, requestContextService, } from "../../utils/index.js";
+import { logger, requestContextService, } from "../../../utils/index.js";
 import { NcbiCoreApiClient } from "./ncbiCoreApiClient.js";
 import { NcbiRequestQueueManager } from "./ncbiRequestQueueManager.js";
 import { NcbiResponseHandler } from "./ncbiResponseHandler.js";
@@ -25,9 +25,21 @@ export class NcbiService {
         return this.queueManager.enqueueRequest(task, context, endpoint, params);
     }
     async eSearch(params, context) {
-        return this.performNcbiRequest("esearch", params, context, {
+        const response = await this.performNcbiRequest("esearch", params, context, {
             retmode: "xml",
         });
+        const esResult = response.eSearchResult;
+        return {
+            count: parseInt(esResult.Count, 10) || 0,
+            retmax: parseInt(esResult.RetMax, 10) || 0,
+            retstart: parseInt(esResult.RetStart, 10) || 0,
+            queryKey: esResult.QueryKey,
+            webEnv: esResult.WebEnv,
+            idList: esResult.IdList?.Id || [],
+            queryTranslation: esResult.QueryTranslation,
+            errorList: esResult.ErrorList,
+            warningList: esResult.WarningList,
+        };
     }
     async eSummary(params, context) {
         // Determine retmode based on params, default to xml

package/dist/{utils/parsing/ncbi-parsing → services/NCBI/parsing}/eSummaryResultParser.d.ts

@@ -2,7 +2,7 @@
  * @fileoverview Helper functions for parsing ESummary results from NCBI.
  * Handles different ESummary XML structures and formats the data into
  * consistent ParsedBriefSummary objects.
- * @module src/utils/parsing/ncbi-parsing/eSummaryResultParser
+ * @module src/services/NCBI/parsing/eSummaryResultParser
  */
 import { ESummaryResult, ParsedBriefSummary, ESummaryAuthor as XmlESummaryAuthor } from "../../../types-global/pubmedXml.js";
 import { RequestContext } from "../../../utils/index.js";

package/dist/{utils/parsing/ncbi-parsing → services/NCBI/parsing}/eSummaryResultParser.js

@@ -2,7 +2,7 @@
  * @fileoverview Helper functions for parsing ESummary results from NCBI.
  * Handles different ESummary XML structures and formats the data into
  * consistent ParsedBriefSummary objects.
- * @module src/utils/parsing/ncbi-parsing/eSummaryResultParser
+ * @module src/services/NCBI/parsing/eSummaryResultParser
  */
 import { dateParser, logger, requestContextService, } from "../../../utils/index.js"; // Note: utils/index.js is the barrel file
 import { ensureArray, getAttribute, getText } from "./xmlGenericHelpers.js";

package/dist/{utils/parsing/ncbi-parsing → services/NCBI/parsing}/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Barrel file for NCBI XML parsing helper utilities.
  * Re-exports functions from more specific parser modules.
- * @module src/utils/parsing/ncbi-parsing/index
+ * @module src/services/NCBI/parsing/index
  */
 export * from "./xmlGenericHelpers.js";
 export * from "./pubmedArticleStructureParser.js";

package/dist/{utils/parsing/ncbi-parsing → services/NCBI/parsing}/index.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Barrel file for NCBI XML parsing helper utilities.
  * Re-exports functions from more specific parser modules.
- * @module src/utils/parsing/ncbi-parsing/index
+ * @module src/services/NCBI/parsing/index
  */
 export * from "./xmlGenericHelpers.js";
 export * from "./pubmedArticleStructureParser.js";

package/dist/{utils/parsing/ncbi-parsing → services/NCBI/parsing}/pubmedArticleStructureParser.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Helper functions for parsing detailed PubMed Article XML structures,
  * typically from EFetch results.
- * @module src/utils/parsing/ncbi-parsing/pubmedArticleStructureParser
+ * @module src/services/NCBI/parsing/pubmedArticleStructureParser
  */
 import { XmlArticle, XmlAuthorList, XmlGrantList, XmlJournal, XmlKeywordList, XmlMedlineCitation, XmlMeshHeadingList, XmlPublicationTypeList, ParsedArticleAuthor, ParsedJournalInfo, ParsedMeshTerm, ParsedGrant, ParsedArticleDate } from "../../../types-global/pubmedXml.js";
 /**

package/dist/{utils/parsing/ncbi-parsing → services/NCBI/parsing}/pubmedArticleStructureParser.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Helper functions for parsing detailed PubMed Article XML structures,
  * typically from EFetch results.
- * @module src/utils/parsing/ncbi-parsing/pubmedArticleStructureParser
+ * @module src/services/NCBI/parsing/pubmedArticleStructureParser
  */
 import { ensureArray, getText, getAttribute } from "./xmlGenericHelpers.js";
 /**
@@ -14,6 +14,10 @@ export function extractAuthors(authorListXml) {
         return [];
     const authors = ensureArray(authorListXml.Author);
     return authors.map((auth) => {
+        const collectiveName = getText(auth.CollectiveName);
+        if (collectiveName) {
+            return { collectiveName };
+        }
         let affiliation = "";
         const affiliations = ensureArray(auth.AffiliationInfo);
         if (affiliations.length > 0) {

package/dist/{utils/parsing/ncbi-parsing → services/NCBI/parsing}/xmlGenericHelpers.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Generic helper functions for parsing XML data, particularly
  * structures from fast-xml-parser.
- * @module src/utils/parsing/ncbi-parsing/xmlGenericHelpers
+ * @module src/services/NCBI/parsing/xmlGenericHelpers
  */
 /**
  * Ensures that the input is an array. If it's not an array, it wraps it in one.

package/dist/{utils/parsing/ncbi-parsing → services/NCBI/parsing}/xmlGenericHelpers.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Generic helper functions for parsing XML data, particularly
  * structures from fast-xml-parser.
- * @module src/utils/parsing/ncbi-parsing/xmlGenericHelpers
+ * @module src/services/NCBI/parsing/xmlGenericHelpers
  */
 /**
  * Ensures that the input is an array. If it's not an array, it wraps it in one.

package/dist/types-global/errors.d.ts

@@ -23,6 +23,8 @@ export declare enum BaseErrorCode {
     CONFLICT = "CONFLICT",
     /** The request failed due to invalid input parameters or data. */
     VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** The provided input is invalid, but not necessarily a schema validation failure. */
+    INVALID_INPUT = "INVALID_INPUT",
     /** An error occurred while parsing input data (e.g., date string, JSON). */
     PARSING_ERROR = "PARSING_ERROR",
     /** The request was rejected because the client has exceeded rate limits. */

package/dist/types-global/errors.js

@@ -24,6 +24,8 @@ export var BaseErrorCode;
     BaseErrorCode["CONFLICT"] = "CONFLICT";
     /** The request failed due to invalid input parameters or data. */
     BaseErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    /** The provided input is invalid, but not necessarily a schema validation failure. */
+    BaseErrorCode["INVALID_INPUT"] = "INVALID_INPUT";
     /** An error occurred while parsing input data (e.g., date string, JSON). */
     BaseErrorCode["PARSING_ERROR"] = "PARSING_ERROR";
     /** The request was rejected because the client has exceeded rate limits. */

package/dist/types-global/pubmedXml.d.ts

@@ -166,6 +166,7 @@ export interface ParsedArticleAuthor {
     firstName?: string;
     initials?: string;
     affiliation?: string;
+    collectiveName?: string;
 }
 export interface ParsedArticleDate {
     dateType?: string;
@@ -348,3 +349,17 @@ export interface ESearchResultContent {
 export interface ESearchResponseContainer {
     eSearchResult: ESearchResultContent;
 }
+export interface ESearchResult {
+    count: number;
+    retmax: number;
+    retstart: number;
+    queryKey?: string;
+    webEnv?: string;
+    idList: string[];
+    queryTranslation: string;
+    errorList?: ESearchErrorList;
+    warningList?: ESearchWarningList;
+}
+export interface EFetchArticleSet {
+    articles: ParsedArticle[];
+}

package/dist/utils/internal/errorHandler.js

@@ -126,7 +126,7 @@ function getErrorMessage(error) {
             try {
                 return `Non-Error object encountered: ${JSON.stringify(error)}`;
             }
-            catch (stringifyError) {
+            catch {
                 return `Unstringifyable non-Error object encountered (constructor: ${error.constructor?.name || "Unknown"})`;
             }
         }

package/dist/utils/internal/logger.d.ts

@@ -17,7 +17,7 @@ export interface McpLogPayload {
         message: string;
         stack?: string;
     };
-    [key: string]: any;
+    [key: string]: unknown;
 }
 /**
  * Type for the `data` parameter of the `McpNotificationSender` function.
@@ -38,6 +38,7 @@ export type McpNotificationSender = (level: McpLogLevel, data: McpNotificationDa
 export declare class Logger {
     private static instance;
     private winstonLogger?;
+    private interactionLogger?;
     private initialized;
     private mcpNotificationSender?;
     private currentMcpLevel;
@@ -75,6 +76,11 @@ export declare class Logger {
      * @returns The singleton Logger instance.
      */
     static getInstance(): Logger;
+    /**
+     * Resets the singleton instance.
+     * This is intended for use in testing environments only.
+     */
+    static resetForTesting(): void;
     /**
      * Ensures the logger has been initialized.
      * @returns True if initialized, false otherwise.
@@ -133,6 +139,12 @@ export declare class Logger {
      * @param context - Optional. RequestContext if `err` is an Error.
      */
     fatal(msg: string, err?: Error | RequestContext, context?: RequestContext): void;
+    /**
+     * Logs a structured interaction object to a dedicated file.
+     * @param interactionName - A name for the interaction type (e.g., 'OpenRouterIO').
+     * @param data - The structured data to log.
+     */
+    logInteraction(interactionName: string, data: Record<string, unknown>): void;
 }
 /**
  * The singleton instance of the Logger.

package/dist/utils/internal/logger.js

@@ -35,9 +35,8 @@ const mcpToWinstonLevel = {
     alert: "error",
     emerg: "error",
 };
-// The logsPath from config is already resolved and validated by src/config/index.ts
-const resolvedLogsDir = config.logsPath;
-const isLogsDirSafe = !!resolvedLogsDir; // If logsPath is set, it's considered safe by config logic.
+// The logsPath from config is resolved and validated by src/config/index.ts.
+// It can be null if the directory is invalid or inaccessible, in which case file logging will be disabled.
 /**
  * Creates the Winston console log format.
  * @returns The Winston log format for console output.
@@ -107,10 +106,7 @@ export class Logger {
         this.initialized = true;
         this.currentMcpLevel = level;
         this.currentWinstonLevel = mcpToWinstonLevel[level];
-        // The logs directory (config.logsPath / resolvedLogsDir) is expected to be created and validated
-        // by the configuration module (src/config/index.ts) before logger initialization.
-        // If isLogsDirSafe is true, we assume resolvedLogsDir exists and is usable.
-        // No redundant directory creation logic here.
+        const resolvedLogsDir = config.logsPath;
         const fileFormat = winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json());
         const transports = [];
         const fileTransportOptions = {
@@ -119,7 +115,7 @@ export class Logger {
             maxFiles: this.LOG_MAX_FILES,
             tailable: true,
         };
-        if (isLogsDirSafe) {
+        if (resolvedLogsDir) {
             transports.push(new winston.transports.File({
                 filename: path.join(resolvedLogsDir, "error.log"),
                 level: "error",
@@ -151,6 +147,18 @@ export class Logger {
             transports,
             exitOnError: false,
         });
+        // Initialize a separate logger for structured interactions
+        if (resolvedLogsDir) {
+            this.interactionLogger = winston.createLogger({
+                format: winston.format.combine(winston.format.timestamp(), winston.format.json({ space: 2 })),
+                transports: [
+                    new winston.transports.File({
+                        filename: path.join(resolvedLogsDir, "interactions.log"),
+                        ...fileTransportOptions,
+                    }),
+                ],
+            });
+        }
         // Configure console transport after Winston logger is created
         const consoleStatus = this._configureConsoleTransport();
         const initialContext = {
@@ -167,7 +175,7 @@ export class Logger {
             loggerSetup: true,
             requestId: "logger-post-init",
             timestamp: new Date().toISOString(),
-            logsPathUsed: resolvedLogsDir,
+            logsPathUsed: resolvedLogsDir ?? "none",
         });
     }
     /**
@@ -262,6 +270,20 @@ export class Logger {
         }
         return Logger.instance;
     }
+    /**
+     * Resets the singleton instance.
+     * This is intended for use in testing environments only.
+     */
+    static resetForTesting() {
+        // This is a clear indication that this method is for testing purposes.
+        if (process.env.NODE_ENV !== "test") {
+            console.warn("Warning: `resetForTesting` should only be called in a test environment.");
+            return;
+        }
+        // De-reference the instance to allow garbage collection
+        // and force re-creation on next getInstance() call.
+        Logger.instance = undefined;
+    }
     /**
      * Ensures the logger has been initialized.
      * @returns True if initialized, false otherwise.
@@ -398,6 +420,18 @@ export class Logger {
         const actualContext = err instanceof Error ? context : err;
         this.log("emerg", msg, actualContext, errorObj);
     }
+    /**
+     * Logs a structured interaction object to a dedicated file.
+     * @param interactionName - A name for the interaction type (e.g., 'OpenRouterIO').
+     * @param data - The structured data to log.
+     */
+    logInteraction(interactionName, data) {
+        if (!this.interactionLogger) {
+            this.warning("Interaction logger not available. File logging may be disabled.", data.context);
+            return;
+        }
+        this.interactionLogger.info({ interactionName, ...data });
+    }
 }
 /**
  * The singleton instance of the Logger.

package/dist/utils/network/fetchWithTimeout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Provides a utility function to make fetch requests with a specified timeout.
+ * @module src/utils/network/fetchWithTimeout
+ */
+import type { RequestContext } from "../internal/requestContext.js";
+/**
+ * Options for the fetchWithTimeout utility.
+ * Extends standard RequestInit but omits 'signal' as it's handled internally.
+ */
+export type FetchWithTimeoutOptions = Omit<RequestInit, "signal">;
+/**
+ * Fetches a resource with a specified timeout.
+ *
+ * @param url - The URL to fetch.
+ * @param timeoutMs - The timeout duration in milliseconds.
+ * @param context - The request context for logging.
+ * @param options - Optional fetch options (RequestInit), excluding 'signal'.
+ * @returns A promise that resolves to the Response object.
+ * @throws {McpError} If the request times out or another fetch-related error occurs.
+ */
+export declare function fetchWithTimeout(url: string | URL, timeoutMs: number, context: RequestContext, options?: FetchWithTimeoutOptions): Promise<Response>;

package/dist/utils/network/fetchWithTimeout.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Provides a utility function to make fetch requests with a specified timeout.
+ * @module src/utils/network/fetchWithTimeout
+ */
+import { logger } from "../internal/logger.js"; // Adjusted import path
+import { McpError, BaseErrorCode } from "../../types-global/errors.js";
+/**
+ * Fetches a resource with a specified timeout.
+ *
+ * @param url - The URL to fetch.
+ * @param timeoutMs - The timeout duration in milliseconds.
+ * @param context - The request context for logging.
+ * @param options - Optional fetch options (RequestInit), excluding 'signal'.
+ * @returns A promise that resolves to the Response object.
+ * @throws {McpError} If the request times out or another fetch-related error occurs.
+ */
+export async function fetchWithTimeout(url, timeoutMs, context, options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const urlString = url.toString();
+    const operationDescription = `fetch ${options?.method || "GET"} ${urlString}`;
+    logger.debug(`Attempting ${operationDescription} with ${timeoutMs}ms timeout.`, context);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        logger.debug(`Successfully fetched ${urlString}. Status: ${response.status}`, context);
+        return response;
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof Error && error.name === "AbortError") {
+            logger.error(`${operationDescription} timed out after ${timeoutMs}ms.`, {
+                ...context,
+                errorSource: "FetchTimeout",
+            });
+            throw new McpError(BaseErrorCode.TIMEOUT, `${operationDescription} timed out.`, { ...context, errorSource: "FetchTimeout" });
+        }
+        // Log and re-throw other errors as McpError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Network error during ${operationDescription}: ${errorMessage}`, {
+            ...context,
+            originalErrorName: error instanceof Error ? error.name : "UnknownError",
+            errorSource: "FetchNetworkError",
+        });
+        if (error instanceof McpError) {
+            // If it's already an McpError, re-throw it
+            throw error;
+        }
+        throw new McpError(BaseErrorCode.SERVICE_UNAVAILABLE, // Generic error for network/service issues
+        `Network error during ${operationDescription}: ${errorMessage}`, {
+            ...context,
+            originalErrorName: error instanceof Error ? error.name : "UnknownError",
+            errorSource: "FetchNetworkErrorWrapper",
+        });
+    }
+}

package/dist/utils/network/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for network utilities.
+ * @module src/utils/network/index
+ */
+export * from "./fetchWithTimeout.js";
+export type { FetchWithTimeoutOptions } from "./fetchWithTimeout.js";

package/dist/utils/network/index.js

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Barrel file for network utilities.
+ * @module src/utils/network/index
+ */
+export * from "./fetchWithTimeout.js";

package/dist/utils/scheduling/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the scheduling module.
+ * Exports the singleton schedulerService for application-wide use.
+ * @module src/utils/scheduling
+ */
+export * from "./scheduler.js";

package/dist/utils/scheduling/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for the scheduling module.
+ * Exports the singleton schedulerService for application-wide use.
+ * @module src/utils/scheduling
+ */
+export * from "./scheduler.js";

package/dist/utils/scheduling/scheduler.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Provides a singleton service for scheduling and managing cron jobs.
+ * This service wraps the 'node-cron' library to offer a unified interface for
+ * defining, starting, stopping, and listing recurring tasks within the application.
+ * @module src/utils/scheduling/scheduler
+ */
+import { ScheduledTask } from "node-cron";
+import { RequestContext } from "../internal/index.js";
+/**
+ * Represents a scheduled job managed by the SchedulerService.
+ */
+export interface Job {
+    /** A unique identifier for the job. */
+    id: string;
+    /** The cron pattern defining the job's schedule. */
+    schedule: string;
+    /** A description of what the job does. */
+    description: string;
+    /** The underlying 'node-cron' task instance. */
+    task: ScheduledTask;
+    /** Indicates whether the job is currently running. */
+    isRunning: boolean;
+}
+/**
+ * A singleton service for scheduling and managing cron jobs.
+ */
+export declare class SchedulerService {
+    private static instance;
+    private jobs;
+    /** @private */
+    private constructor();
+    /**
+     * Gets the singleton instance of the SchedulerService.
+     * @returns The singleton SchedulerService instance.
+     */
+    static getInstance(): SchedulerService;
+    /**
+     * Schedules a new job.
+     *
+     * @param id - A unique identifier for the job.
+     * @param schedule - The cron pattern for the schedule (e.g., '* * * * *').
+     * @param taskFunction - The function to execute on schedule. It receives a RequestContext.
+     * @param description - A description of the job.
+     * @returns The newly created Job object.
+     */
+    schedule(id: string, schedule: string, taskFunction: (context: RequestContext) => void | Promise<void>, description: string): Job;
+    /**
+     * Starts a scheduled job.
+     * @param id - The ID of the job to start.
+     */
+    start(id: string): void;
+    /**
+     * Stops a scheduled job.
+     * @param id - The ID of the job to stop.
+     */
+    stop(id: string): void;
+    /**
+     * Removes a job from the scheduler. The job is stopped before being removed.
+     * @param id - The ID of the job to remove.
+     */
+    remove(id: string): void;
+    /**
+     * Gets a list of all scheduled jobs.
+     * @returns An array of all Job objects.
+     */
+    listJobs(): Job[];
+}
+/**
+ * The singleton instance of the SchedulerService.
+ * Use this instance for all job scheduling operations.
+ */
+export declare const schedulerService: SchedulerService;