@cyanheads/pubmed-mcp-server 1.0.12

package/dist/utils/internal/logger.js

@@ -0,0 +1,426 @@
+/**
+ * @fileoverview Provides a singleton Logger class that wraps Winston for file logging
+ * and supports sending MCP (Model Context Protocol) `notifications/message`.
+ * It handles different log levels compliant with RFC 5424 and MCP specifications.
+ * @module src/utils/internal/logger
+ */
+import fs from "fs";
+import path from "path";
+import winston from "winston";
+import { config } from "../../config/index.js";
+/**
+ * Numeric severity mapping for MCP log levels (lower is more severe).
+ * @private
+ */
+const mcpLevelSeverity = {
+    emerg: 0,
+    alert: 1,
+    crit: 2,
+    error: 3,
+    warning: 4,
+    notice: 5,
+    info: 6,
+    debug: 7,
+};
+/**
+ * Maps MCP log levels to Winston's core levels for file logging.
+ * @private
+ */
+const mcpToWinstonLevel = {
+    debug: "debug",
+    info: "info",
+    notice: "info",
+    warning: "warn",
+    error: "error",
+    crit: "error",
+    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.
+/**
+ * Creates the Winston console log format.
+ * @returns The Winston log format for console output.
+ * @private
+ */
+function createWinstonConsoleFormat() {
+    return winston.format.combine(winston.format.colorize(), winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }), winston.format.printf(({ timestamp, level, message, ...meta }) => {
+        let metaString = "";
+        const metaCopy = { ...meta };
+        if (metaCopy.error && typeof metaCopy.error === "object") {
+            const errorObj = metaCopy.error;
+            if (errorObj.message)
+                metaString += `\n  Error: ${errorObj.message}`;
+            if (errorObj.stack)
+                metaString += `\n  Stack: ${String(errorObj.stack)
+                    .split("\n")
+                    .map((l) => `    ${l}`)
+                    .join("\n")}`;
+            delete metaCopy.error;
+        }
+        if (Object.keys(metaCopy).length > 0) {
+            try {
+                const remainingMetaJson = JSON.stringify(metaCopy, null, 2);
+                if (remainingMetaJson !== "{}")
+                    metaString += `\n  Meta: ${remainingMetaJson}`;
+            }
+            catch (stringifyError) {
+                const errorMessage = stringifyError instanceof Error
+                    ? stringifyError.message
+                    : String(stringifyError);
+                metaString += `\n  Meta: [Error stringifying metadata: ${errorMessage}]`;
+            }
+        }
+        return `${timestamp} ${level}: ${message}${metaString}`;
+    }));
+}
+/**
+ * Singleton Logger class that wraps Winston for robust logging.
+ * Supports file logging, conditional console logging, and MCP notifications.
+ */
+export class Logger {
+    /** @private */
+    constructor() {
+        this.initialized = false;
+        this.currentMcpLevel = "info";
+        this.currentWinstonLevel = "info";
+        this.MCP_NOTIFICATION_STACK_TRACE_MAX_LENGTH = 1024;
+        this.LOG_FILE_MAX_SIZE = 5 * 1024 * 1024; // 5MB
+        this.LOG_MAX_FILES = 5;
+    }
+    /**
+     * Initializes the Winston logger instance.
+     * Should be called once at application startup.
+     * @param level - The initial minimum MCP log level.
+     */
+    async initialize(level = "info") {
+        if (this.initialized) {
+            this.warning("Logger already initialized.", {
+                loggerSetup: true,
+                requestId: "logger-init",
+                timestamp: new Date().toISOString(),
+            });
+            return;
+        }
+        this.currentMcpLevel = level;
+        this.currentWinstonLevel = mcpToWinstonLevel[level];
+        let logsDirCreatedMessage = null; // This message is now informational as creation is handled by config
+        if (isLogsDirSafe) {
+            // Directory creation is handled by config/index.ts ensureDirectory.
+            // We can log if it was newly created by checking if it existed before config ran,
+            // but that's complex. For now, we assume config handled it.
+            // If resolvedLogsDir is set, config ensures it exists.
+            if (!fs.existsSync(resolvedLogsDir)) {
+                // This case should ideally not be hit if config.logsPath is correctly set up and validated.
+                // However, if it somehow occurs (e.g. dir deleted after config init but before logger init),
+                // we attempt to create it.
+                try {
+                    await fs.promises.mkdir(resolvedLogsDir, { recursive: true });
+                    logsDirCreatedMessage = `Re-created logs directory (should have been created by config): ${resolvedLogsDir}`;
+                }
+                catch (err) {
+                    if (process.stdout.isTTY) {
+                        const errorMessage = err instanceof Error ? err.message : String(err);
+                        console.error(`Error creating logs directory at ${resolvedLogsDir}: ${errorMessage}. File logging disabled.`);
+                    }
+                    throw err; // Critical if logs dir cannot be ensured
+                }
+            }
+        }
+        const fileFormat = winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json());
+        const transports = [];
+        const fileTransportOptions = {
+            format: fileFormat,
+            maxsize: this.LOG_FILE_MAX_SIZE,
+            maxFiles: this.LOG_MAX_FILES,
+            tailable: true,
+        };
+        if (isLogsDirSafe) {
+            transports.push(new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "error.log"),
+                level: "error",
+                ...fileTransportOptions,
+            }), new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "warn.log"),
+                level: "warn",
+                ...fileTransportOptions,
+            }), new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "info.log"),
+                level: "info",
+                ...fileTransportOptions,
+            }), new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "debug.log"),
+                level: "debug",
+                ...fileTransportOptions,
+            }), new winston.transports.File({
+                filename: path.join(resolvedLogsDir, "combined.log"),
+                ...fileTransportOptions,
+            }));
+        }
+        else {
+            if (process.stdout.isTTY) {
+                console.warn("File logging disabled as logsPath is not configured or invalid.");
+            }
+        }
+        this.winstonLogger = winston.createLogger({
+            level: this.currentWinstonLevel,
+            transports,
+            exitOnError: false,
+        });
+        // Configure console transport after Winston logger is created
+        const consoleStatus = this._configureConsoleTransport();
+        const initialContext = {
+            loggerSetup: true,
+            requestId: "logger-init-deferred",
+            timestamp: new Date().toISOString(),
+        };
+        if (logsDirCreatedMessage) {
+            // Log if we had to re-create it
+            this.info(logsDirCreatedMessage, initialContext);
+        }
+        if (consoleStatus.message) {
+            this.info(consoleStatus.message, initialContext);
+        }
+        this.initialized = true;
+        this.info(`Logger initialized. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${consoleStatus.enabled ? "enabled" : "disabled"}`, {
+            loggerSetup: true,
+            requestId: "logger-post-init",
+            timestamp: new Date().toISOString(),
+            logsPathUsed: resolvedLogsDir,
+        });
+    }
+    /**
+     * Sets the function used to send MCP 'notifications/message'.
+     * @param sender - The function to call for sending notifications, or undefined to disable.
+     */
+    setMcpNotificationSender(sender) {
+        this.mcpNotificationSender = sender;
+        const status = sender ? "enabled" : "disabled";
+        this.info(`MCP notification sending ${status}.`, {
+            loggerSetup: true,
+            requestId: "logger-set-sender",
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Dynamically sets the minimum logging level.
+     * @param newLevel - The new minimum MCP log level to set.
+     */
+    setLevel(newLevel) {
+        const setLevelContext = {
+            loggerSetup: true,
+            requestId: "logger-set-level",
+            timestamp: new Date().toISOString(),
+        };
+        if (!this.ensureInitialized()) {
+            if (process.stdout.isTTY) {
+                console.error("Cannot set level: Logger not initialized.");
+            }
+            return;
+        }
+        if (!(newLevel in mcpLevelSeverity)) {
+            this.warning(`Invalid MCP log level provided: ${newLevel}. Level not changed.`, setLevelContext);
+            return;
+        }
+        const oldLevel = this.currentMcpLevel;
+        this.currentMcpLevel = newLevel;
+        this.currentWinstonLevel = mcpToWinstonLevel[newLevel];
+        if (this.winstonLogger) {
+            // Ensure winstonLogger is defined
+            this.winstonLogger.level = this.currentWinstonLevel;
+        }
+        const consoleStatus = this._configureConsoleTransport();
+        if (oldLevel !== newLevel) {
+            this.info(`Log level changed. File logging level: ${this.currentWinstonLevel}. MCP logging level: ${this.currentMcpLevel}. Console logging: ${consoleStatus.enabled ? "enabled" : "disabled"}`, setLevelContext);
+            if (consoleStatus.message &&
+                consoleStatus.message !== "Console logging status unchanged.") {
+                this.info(consoleStatus.message, setLevelContext);
+            }
+        }
+    }
+    /**
+     * Configures the console transport based on the current log level and TTY status.
+     * Adds or removes the console transport as needed.
+     * @returns {{ enabled: boolean, message: string | null }} Status of console logging.
+     * @private
+     */
+    _configureConsoleTransport() {
+        if (!this.winstonLogger) {
+            return {
+                enabled: false,
+                message: "Cannot configure console: Winston logger not initialized.",
+            };
+        }
+        const consoleTransport = this.winstonLogger.transports.find((t) => t instanceof winston.transports.Console);
+        const shouldHaveConsole = this.currentMcpLevel === "debug" && process.stdout.isTTY;
+        let message = null;
+        if (shouldHaveConsole && !consoleTransport) {
+            const consoleFormat = createWinstonConsoleFormat();
+            this.winstonLogger.add(new winston.transports.Console({
+                level: "debug", // Console always logs debug if enabled
+                format: consoleFormat,
+            }));
+            message = "Console logging enabled (level: debug, stdout is TTY).";
+        }
+        else if (!shouldHaveConsole && consoleTransport) {
+            this.winstonLogger.remove(consoleTransport);
+            message = "Console logging disabled (level not debug or stdout not TTY).";
+        }
+        else {
+            message = "Console logging status unchanged.";
+        }
+        return { enabled: shouldHaveConsole, message };
+    }
+    /**
+     * Gets the singleton instance of the Logger.
+     * @returns The singleton Logger instance.
+     */
+    static getInstance() {
+        if (!Logger.instance) {
+            Logger.instance = new Logger();
+        }
+        return Logger.instance;
+    }
+    /**
+     * Ensures the logger has been initialized.
+     * @returns True if initialized, false otherwise.
+     * @private
+     */
+    ensureInitialized() {
+        if (!this.initialized || !this.winstonLogger) {
+            if (process.stdout.isTTY) {
+                console.warn("Logger not initialized; message dropped.");
+            }
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Centralized log processing method.
+     * @param level - The MCP severity level of the message.
+     * @param msg - The main log message.
+     * @param context - Optional request context for the log.
+     * @param error - Optional error object associated with the log.
+     * @private
+     */
+    log(level, msg, context, error) {
+        if (!this.ensureInitialized())
+            return;
+        if (mcpLevelSeverity[level] > mcpLevelSeverity[this.currentMcpLevel]) {
+            return; // Do not log if message level is less severe than currentMcpLevel
+        }
+        const logData = { ...context };
+        const winstonLevel = mcpToWinstonLevel[level];
+        if (error) {
+            this.winstonLogger.log(winstonLevel, msg, { ...logData, error });
+        }
+        else {
+            this.winstonLogger.log(winstonLevel, msg, logData);
+        }
+        if (this.mcpNotificationSender) {
+            const mcpDataPayload = { message: msg };
+            if (context && Object.keys(context).length > 0)
+                mcpDataPayload.context = context;
+            if (error) {
+                mcpDataPayload.error = { message: error.message };
+                // Include stack trace in debug mode for MCP notifications, truncated for brevity
+                if (this.currentMcpLevel === "debug" && error.stack) {
+                    mcpDataPayload.error.stack = error.stack.substring(0, this.MCP_NOTIFICATION_STACK_TRACE_MAX_LENGTH);
+                }
+            }
+            try {
+                const serverName = config?.mcpServerName ?? "MCP_SERVER_NAME_NOT_CONFIGURED";
+                this.mcpNotificationSender(level, mcpDataPayload, serverName);
+            }
+            catch (sendError) {
+                const errorMessage = sendError instanceof Error ? sendError.message : String(sendError);
+                const internalErrorContext = {
+                    requestId: context?.requestId || "logger-internal-error",
+                    timestamp: new Date().toISOString(),
+                    originalLevel: level,
+                    originalMessage: msg,
+                    sendError: errorMessage,
+                    mcpPayload: JSON.stringify(mcpDataPayload).substring(0, 500), // Log a preview
+                };
+                this.winstonLogger.error("Failed to send MCP log notification", internalErrorContext);
+            }
+        }
+    }
+    /** Logs a message at the 'debug' level. */
+    debug(msg, context) {
+        this.log("debug", msg, context);
+    }
+    /** Logs a message at the 'info' level. */
+    info(msg, context) {
+        this.log("info", msg, context);
+    }
+    /** Logs a message at the 'notice' level. */
+    notice(msg, context) {
+        this.log("notice", msg, context);
+    }
+    /** Logs a message at the 'warning' level. */
+    warning(msg, context) {
+        this.log("warning", msg, context);
+    }
+    /**
+     * Logs a message at the 'error' level.
+     * @param msg - The main log message.
+     * @param err - Optional. Error object or RequestContext.
+     * @param context - Optional. RequestContext if `err` is an Error.
+     */
+    error(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const actualContext = err instanceof Error ? context : err;
+        this.log("error", msg, actualContext, errorObj);
+    }
+    /**
+     * Logs a message at the 'crit' (critical) level.
+     * @param msg - The main log message.
+     * @param err - Optional. Error object or RequestContext.
+     * @param context - Optional. RequestContext if `err` is an Error.
+     */
+    crit(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const actualContext = err instanceof Error ? context : err;
+        this.log("crit", msg, actualContext, errorObj);
+    }
+    /**
+     * Logs a message at the 'alert' level.
+     * @param msg - The main log message.
+     * @param err - Optional. Error object or RequestContext.
+     * @param context - Optional. RequestContext if `err` is an Error.
+     */
+    alert(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const actualContext = err instanceof Error ? context : err;
+        this.log("alert", msg, actualContext, errorObj);
+    }
+    /**
+     * Logs a message at the 'emerg' (emergency) level.
+     * @param msg - The main log message.
+     * @param err - Optional. Error object or RequestContext.
+     * @param context - Optional. RequestContext if `err` is an Error.
+     */
+    emerg(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const actualContext = err instanceof Error ? context : err;
+        this.log("emerg", msg, actualContext, errorObj);
+    }
+    /**
+     * Logs a message at the 'emerg' (emergency) level, typically for fatal errors.
+     * @param msg - The main log message.
+     * @param err - Optional. Error object or RequestContext.
+     * @param context - Optional. RequestContext if `err` is an Error.
+     */
+    fatal(msg, err, context) {
+        const errorObj = err instanceof Error ? err : undefined;
+        const actualContext = err instanceof Error ? context : err;
+        this.log("emerg", msg, actualContext, errorObj);
+    }
+}
+/**
+ * The singleton instance of the Logger.
+ * Use this instance for all logging operations.
+ */
+export const logger = Logger.getInstance();

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

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Utilities for creating and managing request contexts.
+ * A request context is an object carrying a unique ID, timestamp, and other
+ * relevant data for logging, tracing, and processing. It also defines
+ * configuration and operational context structures.
+ * @module src/utils/internal/requestContext
+ */
+/**
+ * Defines the core structure for context information associated with a request or operation.
+ * This is fundamental for logging, tracing, and passing operational data.
+ */
+export interface RequestContext {
+    /**
+     * Unique ID for the context instance.
+     * Used for log correlation and request tracing.
+     */
+    requestId: string;
+    /**
+     * ISO 8601 timestamp indicating when the context was created.
+     */
+    timestamp: string;
+    /**
+     * Allows arbitrary key-value pairs for specific context needs.
+     * Using `unknown` promotes type-safe access.
+     * Consumers must type-check/assert when accessing extended properties.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Configuration for the {@link requestContextService}.
+ * Allows for future extensibility of service-wide settings.
+ */
+export interface ContextConfig {
+    /** Custom configuration properties. Allows for arbitrary key-value pairs. */
+    [key: string]: unknown;
+}
+/**
+ * Represents a broader context for a specific operation or task.
+ * It can optionally include a base {@link RequestContext} and other custom properties
+ * relevant to the operation.
+ */
+export interface OperationContext {
+    /** Optional base request context data, adhering to the `RequestContext` structure. */
+    requestContext?: RequestContext;
+    /** Allows for additional, custom properties specific to the operation. */
+    [key: string]: unknown;
+}
+/**
+ * Primary export for request context functionalities.
+ * This service provides methods to create and manage {@link RequestContext} instances,
+ * which are essential for logging, tracing, and correlating operations.
+ */
+export declare const requestContextService: {
+    /**
+     * Internal configuration store for the service.
+     */
+    config: ContextConfig;
+    /**
+     * Configures the request context service with new settings.
+     * Merges the provided partial configuration with existing settings.
+     *
+     * @param config - A partial `ContextConfig` object containing settings to update or add.
+     * @returns A shallow copy of the newly updated configuration.
+     */
+    configure(config: Partial<ContextConfig>): ContextConfig;
+    /**
+     * Retrieves a shallow copy of the current service configuration.
+     * This prevents direct mutation of the internal configuration state.
+     *
+     * @returns A shallow copy of the current `ContextConfig`.
+     */
+    getConfig(): ContextConfig;
+    /**
+     * Creates a new {@link RequestContext} instance.
+     * Each context is assigned a unique `requestId` (UUID) and a current `timestamp` (ISO 8601).
+     * Additional custom properties can be merged into the context.
+     *
+     * @param additionalContext - An optional record of key-value pairs to be
+     *   included in the created request context.
+     * @returns A new `RequestContext` object.
+     */
+    createRequestContext(additionalContext?: Record<string, unknown>): RequestContext;
+};

package/dist/utils/internal/requestContext.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Utilities for creating and managing request contexts.
+ * A request context is an object carrying a unique ID, timestamp, and other
+ * relevant data for logging, tracing, and processing. It also defines
+ * configuration and operational context structures.
+ * @module src/utils/internal/requestContext
+ */
+import { generateUUID } from "../index.js";
+import { logger } from "./logger.js";
+/**
+ * Singleton-like service object for managing request context operations.
+ * @private
+ */
+const requestContextServiceInstance = {
+    /**
+     * Internal configuration store for the service.
+     */
+    config: {},
+    /**
+     * Configures the request context service with new settings.
+     * Merges the provided partial configuration with existing settings.
+     *
+     * @param config - A partial `ContextConfig` object containing settings to update or add.
+     * @returns A shallow copy of the newly updated configuration.
+     */
+    configure(config) {
+        this.config = {
+            ...this.config,
+            ...config,
+        };
+        const logContext = this.createRequestContext({
+            operation: "RequestContextService.configure",
+            newConfigState: { ...this.config },
+        });
+        logger.debug("RequestContextService configuration updated", logContext);
+        return { ...this.config };
+    },
+    /**
+     * Retrieves a shallow copy of the current service configuration.
+     * This prevents direct mutation of the internal configuration state.
+     *
+     * @returns A shallow copy of the current `ContextConfig`.
+     */
+    getConfig() {
+        return { ...this.config };
+    },
+    /**
+     * Creates a new {@link RequestContext} instance.
+     * Each context is assigned a unique `requestId` (UUID) and a current `timestamp` (ISO 8601).
+     * Additional custom properties can be merged into the context.
+     *
+     * @param additionalContext - An optional record of key-value pairs to be
+     *   included in the created request context.
+     * @returns A new `RequestContext` object.
+     */
+    createRequestContext(additionalContext = {}) {
+        const requestId = generateUUID();
+        const timestamp = new Date().toISOString();
+        const context = {
+            requestId,
+            timestamp,
+            ...additionalContext,
+        };
+        return context;
+    },
+};
+/**
+ * Primary export for request context functionalities.
+ * This service provides methods to create and manage {@link RequestContext} instances,
+ * which are essential for logging, tracing, and correlating operations.
+ */
+export const requestContextService = requestContextServiceInstance;

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

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for metrics-related utility modules.
+ * This file re-exports utilities for collecting and processing metrics,
+ * such as token counting.
+ * @module src/utils/metrics
+ */
+export * from "./tokenCounter.js";

package/dist/utils/metrics/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for metrics-related utility modules.
+ * This file re-exports utilities for collecting and processing metrics,
+ * such as token counting.
+ * @module src/utils/metrics
+ */
+export * from "./tokenCounter.js";

package/dist/utils/metrics/tokenCounter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Provides utility functions for counting tokens in text and chat messages
+ * using the `tiktoken` library, specifically configured for 'gpt-4o' tokenization.
+ * These functions are essential for managing token limits and estimating costs
+ * when interacting with language models.
+ * @module src/utils/metrics/tokenCounter
+ */
+import { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import { RequestContext } from "../index.js";
+/**
+ * Calculates the number of tokens for a given text string using the
+ * tokenizer specified by `TOKENIZATION_MODEL`.
+ * Wraps tokenization in `ErrorHandler.tryCatch` for robust error management.
+ *
+ * @param text - The input text to tokenize.
+ * @param context - Optional request context for logging and error handling.
+ * @returns A promise that resolves with the number of tokens in the text.
+ * @throws {McpError} If tokenization fails.
+ */
+export declare function countTokens(text: string, context?: RequestContext): Promise<number>;
+/**
+ * Calculates the estimated number of tokens for an array of chat messages.
+ * Uses the tokenizer specified by `TOKENIZATION_MODEL` and accounts for
+ * special tokens and message overhead according to OpenAI's guidelines.
+ *
+ * For multi-part content, only text parts are currently tokenized.
+ *
+ * Reference: {@link https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb}
+ *
+ * @param messages - An array of chat messages.
+ * @param context - Optional request context for logging and error handling.
+ * @returns A promise that resolves with the estimated total number of tokens.
+ * @throws {McpError} If tokenization fails.
+ */
+export declare function countChatTokens(messages: ReadonlyArray<ChatCompletionMessageParam>, context?: RequestContext): Promise<number>;