mcp-server-framework 1.0.0

package/build/logger/logger.js

@@ -0,0 +1,459 @@
+/**
+ * Logger Facade Module
+ *
+ * Provides a unified logging interface that delegates to specialized components:
+ * - Context management via core/context.ts
+ * - Formatting via formatters/ (Text/JSON)
+ * - Output via writers/ (Console/File/MCP)
+ * - Security via scrubbing/ (SecretScrubber/InjectionGuard)
+ * - Resource management via factory.ts (DI-enabled)
+ *
+ * This facade follows the Single Responsibility Principle by coordinating
+ * the logging pipeline without implementing the details itself.
+ *
+ * @module logger
+ */
+import * as util from "util";
+import { LOG_LEVELS, MAX_MESSAGE_LENGTH, TRUNCATION_SUFFIX, DEFAULT_LOG_LEVEL, DEFAULT_SERVICE_NAME, } from "./core/constants.js";
+import { runWithContext, getContext, mergeContext, createChildContext, withExtendedContext, withChildContext, getContextDepth, } from "./core/context.js";
+import { extractTraceContext } from "./core/trace-context.js";
+// Factory for DI-enabled resource management
+import { LoggerResources, initializeLoggerResources, hasLoggerResources, getLoggerResources, resetLoggerResources, _setLoggerResources, } from "./factory.js";
+export { LoggerResources, initializeLoggerResources, resetLoggerResources };
+/**
+ * Default logger configuration.
+ * Used when no explicit config is provided.
+ */
+const DEFAULT_LOGGER_CONFIG = {
+    LOG_LEVEL: DEFAULT_LOG_LEVEL,
+    LOG_FORMAT: "text",
+    MCP_TRANSPORT: "http",
+    // @node-api — process.env.* returns string | undefined; config requires string literal union
+    NODE_ENV: process.env.NODE_ENV ?? "development",
+    SERVER_NAME: DEFAULT_SERVICE_NAME,
+    SERVER_VERSION: "0.0.0",
+};
+/** Global logger configuration storage */
+let globalLoggerConfig = { ...DEFAULT_LOGGER_CONFIG };
+/**
+ * Configure the global logger settings.
+ * Should be called once at application startup before creating loggers.
+ *
+ * @param config - Logger configuration options
+ *
+ * @example
+ * ```typescript
+ * // In app initialization
+ * configureLogger({
+ *   LOG_LEVEL: config.LOG_LEVEL,
+ *   LOG_FORMAT: config.LOG_FORMAT,
+ *   MCP_TRANSPORT: config.MCP_TRANSPORT,
+ *   NODE_ENV: config.NODE_ENV,
+ *   LOG_DIR: config.LOG_DIR,
+ *   SERVER_NAME: 'mcp-server',
+ *   SERVER_VERSION: '1.0.0',
+ * });
+ * ```
+ */
+export function configureLogger(config) {
+    globalLoggerConfig = { ...globalLoggerConfig, ...config };
+    // Close and reset resources so the next log call re-creates them with the new config.
+    // This is necessary because LoggerResources captures formatter settings
+    // (e.g., includeTimestamp, includeComponent) at construction time.
+    // Must use resetLoggerResources() (not _setLoggerResources(null)) to properly
+    // close existing FileWriter streams and clear rotation/retention timers.
+    if (hasLoggerResources()) {
+        void resetLoggerResources();
+    }
+}
+/**
+ * Get the current global logger configuration.
+ */
+export function getLoggerConfig() {
+    return globalLoggerConfig;
+}
+/**
+ * Reset the global logger configuration to defaults.
+ * Primarily for testing.
+ */
+export function resetLoggerConfig() {
+    globalLoggerConfig = { ...DEFAULT_LOGGER_CONFIG };
+}
+/**
+ * Centralized Logger Facade
+ *
+ * Coordinates the logging pipeline:
+ * 1. Level filtering
+ * 2. Message formatting (printf-style)
+ * 3. Metadata extraction
+ * 4. Secret scrubbing
+ * 5. Formatting (Text/JSON)
+ * 6. Injection prevention
+ * 7. Output to writers (Console/File/MCP)
+ *
+ * Now uses LoggerResources for DI-enabled resource management,
+ * eliminating the static state anti-pattern while maintaining
+ * backward compatibility through lazy global initialization.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage (global resources)
+ * const logger = new Logger('api');
+ * logger.info('Request received', { method: 'GET', path: '/health' });
+ *
+ * // DI usage (custom resources for testing)
+ * const resources = new LoggerResources(config, mockDeps);
+ * const testLogger = new Logger({ component: 'test', resources });
+ * ```
+ */
+export class Logger {
+    // ============================================================
+    // Instance properties
+    // ============================================================
+    /** Override log level (if set in options, otherwise uses global config) */
+    levelOverride;
+    /** Component name for this logger instance */
+    component;
+    /** Explicitly injected resources (DI/testing only) — `null` means use global */
+    _injectedResources;
+    /** Resolve the active resources: injected for DI, otherwise global (dynamic). */
+    get resources() {
+        return this._injectedResources ?? Logger.getOrInitializeResources();
+    }
+    /**
+     * Get the effective log level (numeric for fast comparison).
+     * Uses override if set, otherwise reads from global config dynamically.
+     */
+    get level() {
+        const effectiveLevel = this.levelOverride ?? getLoggerConfig().LOG_LEVEL;
+        return LOG_LEVELS[effectiveLevel];
+    }
+    // ============================================================
+    // Constructor and Initialization
+    // ============================================================
+    /**
+     * Create a new Logger instance.
+     *
+     * @param componentOrOptions - Component name string or options object
+     */
+    constructor(componentOrOptions = "server") {
+        if (typeof componentOrOptions === "string") {
+            this.component = componentOrOptions;
+            this.levelOverride = undefined; // Use global config dynamically
+            this._injectedResources = null; // Resolve from global on each log call
+        }
+        else {
+            this.component = componentOrOptions.component ?? "server";
+            this.levelOverride = componentOrOptions.level; // Override if explicitly set
+            this._injectedResources = componentOrOptions.resources ?? null;
+        }
+    }
+    /**
+     * Get or initialize global resources lazily.
+     * Provides backward compatibility with existing code.
+     */
+    static getOrInitializeResources() {
+        if (!hasLoggerResources()) {
+            const cfg = getLoggerConfig();
+            initializeLoggerResources({
+                level: cfg.LOG_LEVEL,
+                format: cfg.LOG_FORMAT,
+                transport: cfg.MCP_TRANSPORT,
+                serviceName: cfg.SERVER_NAME,
+                serviceVersion: cfg.SERVER_VERSION,
+                environment: cfg.NODE_ENV,
+                ...(cfg.LOG_DIR !== undefined && { logDir: cfg.LOG_DIR }),
+                ...(cfg.LOG_MAX_FILE_SIZE !== undefined && {
+                    maxFileSize: cfg.LOG_MAX_FILE_SIZE,
+                }),
+                ...(cfg.LOG_MAX_FILES !== undefined && { maxFiles: cfg.LOG_MAX_FILES }),
+                ...(cfg.LOG_RETENTION_DAYS !== undefined && {
+                    retentionDays: cfg.LOG_RETENTION_DAYS,
+                }),
+                ...(cfg.LOG_TIMESTAMP !== undefined && {
+                    includeTimestamp: cfg.LOG_TIMESTAMP,
+                }),
+                ...(cfg.LOG_COMPONENT !== undefined && {
+                    includeComponent: cfg.LOG_COMPONENT,
+                }),
+            });
+        }
+        return getLoggerResources();
+    }
+    // ============================================================
+    // Static Lifecycle Methods
+    // ============================================================
+    /**
+     * Close all writers gracefully.
+     * Should be called during application shutdown.
+     *
+     * @returns Promise that resolves when all writers are closed
+     */
+    static async closeStreams() {
+        if (hasLoggerResources()) {
+            await getLoggerResources().close();
+            await resetLoggerResources();
+        }
+    }
+    /**
+     * Clear the child logger cache.
+     * Useful for testing or when configuration changes.
+     */
+    static clearChildLoggerCache() {
+        if (hasLoggerResources()) {
+            getLoggerResources().clearChildLoggerCache();
+        }
+    }
+    /**
+     * Reset static state (for testing purposes).
+     * Fully resets all resources.
+     */
+    static async resetState() {
+        await resetLoggerResources();
+    }
+    // ============================================================
+    // Child Logger Factory
+    // ============================================================
+    /**
+     * Create a child logger with a specific component context.
+     * Uses LRU caching to avoid creating new instances while preventing memory leaks.
+     *
+     * @param context - The component context for the child logger
+     * @returns A cached or new Logger instance
+     */
+    child(context) {
+        return this.resources.getOrCreateChildLogger(context.component, () => this._injectedResources
+            ? new Logger({
+                component: context.component,
+                resources: this._injectedResources,
+            })
+            : new Logger({ component: context.component }));
+    }
+    // ============================================================
+    // Context Management (delegates to core/context.ts)
+    // ============================================================
+    /**
+     * Run a function within a logging context.
+     * All logs within the function will include the context.
+     *
+     * @param context - The context to use for logging
+     * @param fn - The function to execute
+     * @returns The result of the function
+     */
+    runWithContext(context, fn) {
+        return runWithContext(context, fn);
+    }
+    /**
+     * Get the current logging context.
+     *
+     * @returns The current context or undefined
+     */
+    getContext() {
+        return getContext();
+    }
+    /**
+     * Merge additional context with the current context.
+     *
+     * @param additionalContext - Context values to add/override
+     * @returns A new merged context
+     */
+    mergeContext(additionalContext) {
+        return mergeContext(additionalContext);
+    }
+    /**
+     * Create a child context that inherits from the current context.
+     * Component names are automatically concatenated.
+     *
+     * @param childContext - Context values for the child
+     * @returns A new child context
+     */
+    createChildContext(childContext) {
+        return createChildContext(childContext);
+    }
+    /**
+     * Execute a function with an extended context.
+     *
+     * @param additionalContext - Context values to add
+     * @param fn - The function to execute
+     * @returns The result of the function
+     */
+    withExtendedContext(additionalContext, fn) {
+        return withExtendedContext(additionalContext, fn);
+    }
+    /**
+     * Execute a function with a child context.
+     *
+     * @param childContext - Context values for the child scope
+     * @param fn - The function to execute
+     * @returns The result of the function
+     */
+    withChildContext(childContext, fn) {
+        return withChildContext(childContext, fn);
+    }
+    /**
+     * Get the current context nesting depth.
+     *
+     * @returns The current depth
+     */
+    getContextDepth() {
+        return getContextDepth();
+    }
+    // ============================================================
+    // Log Level Methods
+    // ============================================================
+    /**
+     * Log a message at TRACE level.
+     */
+    trace(message, ...args) {
+        this.log("trace", message, ...args);
+    }
+    /**
+     * Log a message at DEBUG level.
+     */
+    debug(message, ...args) {
+        this.log("debug", message, ...args);
+    }
+    /**
+     * Log a message at INFO level.
+     */
+    info(message, ...args) {
+        this.log("info", message, ...args);
+    }
+    /**
+     * Log a message at WARN level.
+     */
+    warn(message, ...args) {
+        this.log("warn", message, ...args);
+    }
+    /**
+     * Log a message at ERROR level.
+     */
+    error(message, ...args) {
+        this.log("error", message, ...args);
+    }
+    // ============================================================
+    // Core Logging Pipeline
+    // ============================================================
+    /**
+     * Internal log handler implementing the logging pipeline.
+     *
+     * Pipeline steps:
+     * 1. Level filtering
+     * 2. Metadata extraction
+     * 3. Printf-style formatting
+     * 4. Message truncation (if exceeds MAX_MESSAGE_LENGTH)
+     * 5. Context retrieval
+     * 6. Secret scrubbing
+     * 7. Format generation (Text/JSON)
+     * 8. Injection prevention
+     * 9. Output to writers
+     * 10. MCP notification (if context has sendMcpLog)
+     */
+    log(level, message, ...args) {
+        // Step 1: Level filtering (fast path for disabled levels)
+        if (LOG_LEVELS[level] < this.level) {
+            return;
+        }
+        // Step 2: Extract metadata and error from args
+        const { metadata, error, formatArgs } = this.extractMetadata(args);
+        // Step 3: Printf-style message formatting
+        let formattedMessage = util.format(message, ...formatArgs);
+        // Step 4: Truncate long messages to prevent memory issues
+        if (formattedMessage.length > MAX_MESSAGE_LENGTH) {
+            formattedMessage = formattedMessage.slice(0, MAX_MESSAGE_LENGTH - TRUNCATION_SUFFIX.length) + TRUNCATION_SUFFIX;
+        }
+        // Step 5: Get context (from AsyncLocalStorage)
+        const context = getContext();
+        const component = context?.component ?? this.component;
+        // Step 5b: Auto-enrich with OTEL trace context if not already set
+        let enrichedContext = context;
+        if (!context?.traceId) {
+            const otelCtx = extractTraceContext();
+            if (otelCtx) {
+                enrichedContext = { ...context, ...otelCtx };
+            }
+        }
+        // Step 6: Scrub secrets from metadata
+        // @ts-limitation — scrubObject() returns unknown; object input guarantees object output
+        const scrubbedMetadata = metadata
+            ? this.resources.secretScrubber.scrubObject(metadata)
+            : undefined;
+        // Step 7: Build log entry params
+        const params = {
+            level,
+            message: formattedMessage,
+            component,
+            ...(enrichedContext !== undefined && { context: enrichedContext }),
+            ...(scrubbedMetadata !== undefined && { metadata: scrubbedMetadata }),
+            ...(error !== undefined && { error }),
+            timestamp: new Date().toISOString(),
+        };
+        // Step 8: Format the log entry
+        const formatted = this.resources.getFormatter().format(params);
+        // Step 9: Apply injection guard and secret scrubbing to final output
+        const safeOutput = this.sanitizeOutput(formatted);
+        // Step 10: Write to outputs
+        this.writeToOutputs(level, safeOutput, component);
+        // Step 11: Send to MCP client if context has sendMcpLog (best-effort)
+        if (enrichedContext?.sendMcpLog) {
+            try {
+                const safeMessage = this.sanitizeOutput(formattedMessage);
+                enrichedContext.sendMcpLog(level, safeMessage);
+            }
+            catch {
+                // Silently ignore — MCP client notification is best-effort.
+                // A throwing callback must never crash the caller's logging call.
+            }
+        }
+    }
+    /**
+     * Extract metadata object from log arguments.
+     * The last argument is treated as metadata if it's a plain object (not an Error).
+     */
+    extractMetadata(args) {
+        if (args.length === 0) {
+            return { metadata: undefined, error: undefined, formatArgs: [] };
+        }
+        let metadata;
+        let error;
+        let formatArgs = args;
+        const lastArg = args[args.length - 1];
+        // Check if last arg is a plain object (not null, not Error)
+        if (lastArg !== null && typeof lastArg === "object" && !(lastArg instanceof Error) && !Array.isArray(lastArg)) {
+            // @type-narrowing — Runtime checks confirm object && !null && !Error && !Array; TS cannot narrow unknown
+            metadata = lastArg;
+            formatArgs = args.slice(0, -1);
+        }
+        // Check if last format arg (or the one before metadata) is an Error
+        const errorCandidate = formatArgs.length > 0 ? formatArgs[formatArgs.length - 1] : undefined;
+        if (errorCandidate instanceof Error) {
+            error = errorCandidate;
+        }
+        return { metadata, error, formatArgs };
+    }
+    /**
+     * Apply injection guard and secret scrubbing to formatted log output.
+     */
+    sanitizeOutput(formatted) {
+        const sanitized = this.resources.injectionGuard.sanitize(formatted);
+        return this.resources.secretScrubber.scrub(sanitized);
+    }
+    /**
+     * Write formatted output to all configured writers.
+     */
+    writeToOutputs(level, output, component) {
+        // Console writer
+        this.resources.consoleWriter?.write(level, output, component);
+        // File writer (if configured)
+        /* v8 ignore start - file logging requires LOG_DIR environment */
+        this.resources.fileWriter?.write(level, output, component);
+        /* v8 ignore stop */
+    }
+}
+/**
+ * Default logger instance for the application.
+ * Uses dynamic log level from global config, so configureLogger()
+ * can be called at any time to change the effective log level.
+ */
+export const logger = new Logger();
+//# sourceMappingURL=logger.js.map

package/build/logger/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"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"}

package/build/logger/mcp-logger.d.ts

@@ -0,0 +1,177 @@
+/**
+ * MCP Notification Logger Module
+ *
+ * Provides structured logging via MCP notifications/message protocol.
+ * This allows MCP clients to receive and display server-side logs.
+ *
+ * Per MCP Spec, logging levels follow RFC 5424 (syslog):
+ * - emergency: System is unusable
+ * - alert: Action must be taken immediately
+ * - critical: Critical conditions
+ * - error: Error conditions
+ * - warning: Warning conditions
+ * - notice: Normal but significant condition
+ * - info: Informational messages
+ * - debug: Debug-level messages
+ *
+ * @module logger/mcp-logger
+ */
+import type { LogLevel, McpLogLevel, LogNotificationHandler } from "./core/types.js";
+/**
+ * Configuration options for MCP Notification Logger.
+ */
+export interface McpLoggerConfig {
+    /** Minimum log level to send (default: 'debug') */
+    minLevel?: McpLogLevel;
+    /** Whether logging is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * MCP Notification Logger
+ *
+ * Sends structured log messages to MCP clients via the notifications/message protocol.
+ * Clients that support the logging capability will receive and display these messages.
+ *
+ * Features:
+ * - Multi-server support for multi-session scenarios
+ * - Level filtering with configurable minimum level
+ * - Secret scrubbing for security
+ * - Context-aware logger creation for tool handlers
+ *
+ * @example
+ * ```typescript
+ * // Set up with MCP server
+ * mcpLogger.addServer(mcpServer);
+ *
+ * // Log messages (sent to all connected clients)
+ * await mcpLogger.info('Processing request...');
+ * await mcpLogger.warn('Resource limit approaching', { current: 80, max: 100 });
+ * await mcpLogger.error('Failed to connect', { error: 'Connection refused' });
+ * ```
+ */
+export declare class McpNotificationLogger {
+    /** Set of registered notification handlers */
+    private readonly handlers;
+    /** Whether logging is enabled */
+    private enabled;
+    /** Minimum log level to send */
+    private minLevel;
+    /** Use shared secret scrubber instance for consistency */
+    private readonly secretScrubber;
+    /** Injection guard for CWE-117 protection (consistent with main logger pipeline) */
+    private readonly injectionGuard;
+    /**
+     * Create a new McpNotificationLogger.
+     *
+     * @param config - Optional configuration
+     */
+    constructor(config?: McpLoggerConfig);
+    /**
+     * Register a notification handler for receiving log notifications.
+     * Multiple handlers can be registered for multi-session scenarios.
+     *
+     * @param handler - The notification handler to register
+     */
+    addHandler(handler: LogNotificationHandler): void;
+    /**
+     * Unregister a notification handler.
+     *
+     * @param handler - The notification handler to remove
+     */
+    removeHandler(handler: LogNotificationHandler): void;
+    /**
+     * Clear all registered handlers.
+     */
+    clearHandlers(): void;
+    /**
+     * Get the number of registered handlers.
+     */
+    getHandlerCount(): number;
+    /**
+     * Enable or disable MCP logging.
+     * When disabled, log methods become no-ops but still return resolved promises.
+     *
+     * @param enabled - Whether to enable logging
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if logging is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Set the minimum log level.
+     * Messages below this level will not be sent.
+     *
+     * @param level - The minimum log level
+     */
+    setMinLevel(level: McpLogLevel): void;
+    /**
+     * Get the current minimum log level.
+     */
+    getMinLevel(): McpLogLevel;
+    /**
+     * Check if logging is currently available (enabled and has servers).
+     */
+    isAvailable(): boolean;
+    /**
+     * Send a log message to all connected MCP clients.
+     *
+     * @param level - The MCP log level
+     * @param message - The log message
+     * @param data - Optional structured data to include
+     * @returns Promise that resolves when all sends complete
+     */
+    log(level: McpLogLevel, message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log a debug message */
+    debug(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log an info message */
+    info(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log a notice message */
+    notice(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log a warning message */
+    warn(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log a warning message (alias for warn) */
+    warning(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log an error message */
+    error(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log a critical message */
+    critical(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log an alert message */
+    alert(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Log an emergency message */
+    emergency(message: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Create a context-aware logger function for use in tool handlers.
+     * Returns a function that can be passed to LogContext.sendMcpLog.
+     *
+     * @param handler - The notification handler for this context
+     * @returns A function compatible with LogContext.sendMcpLog
+     *
+     * @example
+     * ```typescript
+     * const sendMcpLog = mcpLogger.createContextLogger(handler);
+     * logger.runWithContext({ sendMcpLog }, () => {
+     *   logger.info('This will also be sent to MCP client');
+     * });
+     * ```
+     */
+    createContextLogger(handler: LogNotificationHandler): (level: LogLevel, message: string) => void;
+    /**
+     * Check if a log level should be logged based on minimum level.
+     */
+    private shouldLog;
+    /**
+     * Format message with optional data.
+     */
+    private formatMessage;
+    /**
+     * Send a log message to a specific handler.
+     */
+    private sendToHandler;
+}
+/**
+ * Singleton instance of the MCP Notification Logger.
+ * Use this for sending log messages to MCP clients.
+ */
+export declare const mcpLogger: McpNotificationLogger;
+//# sourceMappingURL=mcp-logger.d.ts.map

package/build/logger/mcp-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-logger.d.ts","sourceRoot":"","sources":["../../src/logger/mcp-logger.ts"],"names":[],"mappings":"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"}