@cyanheads/pubmed-mcp-server 1.2.4 → 1.3.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/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;

package/dist/utils/scheduling/scheduler.js

@@ -0,0 +1,150 @@
+/**
+ * @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 cron, { createTask } from "node-cron";
+import { logger } from "../internal/index.js";
+import { requestContextService } from "../internal/requestContext.js";
+/**
+ * A singleton service for scheduling and managing cron jobs.
+ */
+export class SchedulerService {
+    /** @private */
+    constructor() {
+        this.jobs = new Map();
+        logger.info("SchedulerService initialized.", {
+            requestId: "scheduler-init",
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Gets the singleton instance of the SchedulerService.
+     * @returns The singleton SchedulerService instance.
+     */
+    static getInstance() {
+        if (!SchedulerService.instance) {
+            SchedulerService.instance = new SchedulerService();
+        }
+        return SchedulerService.instance;
+    }
+    /**
+     * 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, schedule, taskFunction, description) {
+        if (this.jobs.has(id)) {
+            throw new Error(`Job with ID '${id}' already exists.`);
+        }
+        if (!cron.validate(schedule)) {
+            throw new Error(`Invalid cron schedule: ${schedule}`);
+        }
+        const task = createTask(schedule, async () => {
+            const job = this.jobs.get(id);
+            if (job && job.isRunning) {
+                logger.warning(`Job '${id}' is already running. Skipping this execution.`, {
+                    requestId: `job-skip-${id}`,
+                    timestamp: new Date().toISOString(),
+                });
+                return;
+            }
+            if (job) {
+                job.isRunning = true;
+            }
+            const context = requestContextService.createRequestContext({
+                jobId: id,
+                schedule,
+            });
+            logger.info(`Starting job '${id}'...`, context);
+            try {
+                await Promise.resolve(taskFunction(context));
+                logger.info(`Job '${id}' completed successfully.`, context);
+            }
+            catch (error) {
+                logger.error(`Job '${id}' failed.`, error, context);
+            }
+            finally {
+                if (job) {
+                    job.isRunning = false;
+                }
+            }
+        });
+        const newJob = {
+            id,
+            schedule,
+            description,
+            task,
+            isRunning: false,
+        };
+        this.jobs.set(id, newJob);
+        logger.info(`Job '${id}' scheduled: ${description}`, {
+            requestId: `job-schedule-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+        return newJob;
+    }
+    /**
+     * Starts a scheduled job.
+     * @param id - The ID of the job to start.
+     */
+    start(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.start();
+        logger.info(`Job '${id}' started.`, {
+            requestId: `job-start-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Stops a scheduled job.
+     * @param id - The ID of the job to stop.
+     */
+    stop(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.stop();
+        logger.info(`Job '${id}' stopped.`, {
+            requestId: `job-stop-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Removes a job from the scheduler. The job is stopped before being removed.
+     * @param id - The ID of the job to remove.
+     */
+    remove(id) {
+        const job = this.jobs.get(id);
+        if (!job) {
+            throw new Error(`Job with ID '${id}' not found.`);
+        }
+        job.task.stop();
+        this.jobs.delete(id);
+        logger.info(`Job '${id}' removed.`, {
+            requestId: `job-remove-${id}`,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Gets a list of all scheduled jobs.
+     * @returns An array of all Job objects.
+     */
+    listJobs() {
+        return Array.from(this.jobs.values());
+    }
+}
+/**
+ * The singleton instance of the SchedulerService.
+ * Use this instance for all job scheduling operations.
+ */
+export const schedulerService = SchedulerService.getInstance();

package/dist/utils/security/sanitization.js

@@ -121,14 +121,25 @@ export class Sanitization {
     sanitizeHtml(input, config) {
         if (!input)
             return "";
-        const effectiveConfig = { ...this.defaultHtmlSanitizeConfig, ...config };
+        const effectiveConfig = {
+            allowedTags: config?.allowedTags ?? this.defaultHtmlSanitizeConfig.allowedTags,
+            allowedAttributes: config?.allowedAttributes ??
+                this.defaultHtmlSanitizeConfig.allowedAttributes,
+            transformTags: config?.transformTags, // Can be undefined
+            preserveComments: config?.preserveComments ??
+                this.defaultHtmlSanitizeConfig.preserveComments,
+        };
         const options = {
             allowedTags: effectiveConfig.allowedTags,
             allowedAttributes: effectiveConfig.allowedAttributes,
             transformTags: effectiveConfig.transformTags,
         };
         if (effectiveConfig.preserveComments) {
-            options.allowedTags = [...(options.allowedTags || []), "!--"];
+            // Ensure allowedTags is an array before spreading
+            const baseTags = Array.isArray(options.allowedTags)
+                ? options.allowedTags
+                : [];
+            options.allowedTags = [...baseTags, "!--"];
         }
         return sanitizeHtml(input, options);
     }
@@ -144,14 +155,18 @@ export class Sanitization {
     sanitizeString(input, options = {}) {
         if (!input)
             return "";
-        switch (options.context) {
-            case "html":
-                return this.sanitizeHtml(input, {
-                    allowedTags: options.allowedTags,
-                    allowedAttributes: options.allowedAttributes
-                        ? this.convertAttributesFormat(options.allowedAttributes)
-                        : undefined,
-                });
+        const context = options.context ?? "text";
+        switch (context) {
+            case "html": {
+                const config = {};
+                if (options.allowedTags) {
+                    config.allowedTags = options.allowedTags;
+                }
+                if (options.allowedAttributes) {
+                    config.allowedAttributes = this.convertAttributesFormat(options.allowedAttributes);
+                }
+                return this.sanitizeHtml(input, config);
+            }
             case "attribute":
                 return sanitizeHtml(input, { allowedTags: [], allowedAttributes: {} });
             case "url":
@@ -233,7 +248,6 @@ export class Sanitization {
             rootDir: options.rootDir ? path.resolve(options.rootDir) : undefined,
         };
         let wasAbsoluteInitially = false;
-        let convertedToRelative = false;
         try {
             if (!input || typeof input !== "string")
                 throw new Error("Invalid path input: must be a non-empty string.");
@@ -262,8 +276,7 @@ export class Sanitization {
             else {
                 if (path.isAbsolute(normalized)) {
                     if (!effectiveOptions.allowAbsolute) {
-                        finalSanitizedPath = normalized.replace(/^(?:[A-Za-z]:)?[/\\]+/, "");
-                        convertedToRelative = true;
+                        throw new Error("Absolute paths are disallowed by current options.");
                     }
                     else {
                         finalSanitizedPath = normalized;
@@ -355,7 +368,7 @@ export class Sanitization {
             throw new McpError(BaseErrorCode.VALIDATION_ERROR, "Invalid number value (NaN or Infinity).", { input });
         }
         let clamped = false;
-        let originalValueForLog = value;
+        const originalValueForLog = value;
         if (min !== undefined && value < min) {
             value = min;
             clamped = true;
@@ -399,8 +412,8 @@ export class Sanitization {
         try {
             if (!input || typeof input !== "object")
                 return input;
-            const clonedInput = typeof structuredClone === "function"
-                ? structuredClone(input)
+            const clonedInput = typeof globalThis.structuredClone === "function"
+                ? globalThis.structuredClone(input)
                 : JSON.parse(JSON.stringify(input));
             this.redactSensitiveFields(clonedInput);
             return clonedInput;
@@ -428,8 +441,12 @@ export class Sanitization {
         for (const key in obj) {
             if (Object.prototype.hasOwnProperty.call(obj, key)) {
                 const value = obj[key];
-                const lowerKey = key.toLowerCase();
-                const isSensitive = this.sensitiveFields.some((field) => lowerKey.includes(field));
+                // Split camelCase and snake_case/kebab-case keys into words
+                const keyWords = key
+                    .replace(/([A-Z])/g, " $1") // Add space before uppercase letters
+                    .toLowerCase()
+                    .split(/[\s_-]+/); // Split by space, underscore, or hyphen
+                const isSensitive = keyWords.some((word) => this.sensitiveFields.includes(word));
                 if (isSensitive) {
                     obj[key] = "[REDACTED]";
                 }