@ibm/ibmi-mcp-server 0.1.0

package/dist/utils/internal/asyncContext.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Manages asynchronous context propagation using AsyncLocalStorage.
+ * This module provides a mechanism to store and retrieve a `RequestContext` across
+ * asynchronous operations, ensuring that critical metadata like `requestId` and trace
+ * information is available throughout the entire call stack without prop drilling.
+ * @module src/utils/internal/asyncContext
+ * @see {@link src/utils/internal/requestContext.ts} for the definition of RequestContext.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * The singleton `AsyncLocalStorage` instance for storing the `RequestContext`.
+ * This holds the context for the duration of a single asynchronous operation,
+ * such as an incoming tool call or a scheduled job.
+ */
+export const requestContextStore = new AsyncLocalStorage();
+/**
+ * Retrieves the current `RequestContext` from the async local storage.
+ * It is a synchronous call that depends on the execution context.
+ *
+ * @returns {RequestContext | undefined} The current `RequestContext` if it exists
+ * in the current async context, otherwise `undefined`.
+ */
+export function getRequestContext() {
+    return requestContextStore.getStore();
+}
+/**
+ * A higher-order function that runs a given function within a specified `RequestContext`.
+ * This is the primary mechanism for establishing an async context for an operation.
+ *
+ * @template T The return type of the function to be executed.
+ * @param {RequestContext} context - The `RequestContext` to set for the duration of the function's execution.
+ * @param {() => T} fn - The function to execute within the context.
+ * @returns {T} The result returned by the function `fn`.
+ */
+export function withRequestContext(context, fn) {
+    return requestContextStore.run(context, fn);
+}
+//# sourceMappingURL=asyncContext.js.map

package/dist/utils/internal/asyncContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncContext.js","sourceRoot":"","sources":["../../../src/utils/internal/asyncContext.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,mBAAmB,CAAC,QAAQ,EAAE,CAAC;AACxC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAI,OAAuB,EAAE,EAAW;IACxE,OAAO,mBAAmB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC"}

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

@@ -0,0 +1,95 @@
+import { JsonRpcErrorCode } from "../../types-global/errors.js";
+import { RequestContext } from "./requestContext.js";
+/**
+ * Defines a generic structure for providing context with errors.
+ * This context can include identifiers like `requestId` or any other relevant
+ * key-value pairs that aid in debugging or understanding the error's circumstances.
+ */
+export type ErrorContext = RequestContext;
+/**
+ * Configuration options for the `ErrorHandler.handleError` method.
+ * These options control how an error is processed, logged, and whether it's rethrown.
+ */
+export interface ErrorHandlerOptions {
+    /**
+     * The context of the operation that caused the error.
+     * This can include `requestId` and other relevant debugging information.
+     */
+    context?: ErrorContext;
+    /**
+     * A descriptive name of the operation being performed when the error occurred.
+     * This helps in identifying the source or nature of the error in logs.
+     * Example: "UserLogin", "ProcessPayment", "FetchUserProfile".
+     */
+    operation: string;
+    /**
+     * The input data or parameters that were being processed when the error occurred.
+     * This input will be sanitized before logging to prevent sensitive data exposure.
+     */
+    input?: unknown;
+    /**
+     * If true, the (potentially transformed) error will be rethrown after handling.
+     * Defaults to `false`.
+     */
+    rethrow?: boolean;
+    /**
+     * A specific `JsonRpcErrorCode` to assign to the error, overriding any
+     * automatically determined error code.
+     */
+    errorCode?: JsonRpcErrorCode;
+    /**
+     * A custom function to map or transform the original error into a new `Error` instance.
+     * If provided, this function is used instead of the default `McpError` creation.
+     * @param error - The original error that occurred.
+     * @returns The transformed error.
+     */
+    errorMapper?: (error: unknown) => Error;
+    /**
+     * If true, indicates that the error is critical and might require immediate attention
+     * or could lead to system instability. This is primarily for logging and alerting.
+     * Defaults to `false`.
+     */
+    critical?: boolean;
+}
+/**
+ * Defines a rule for mapping error patterns to a specific JSON-RPC error code.
+ */
+export interface ErrorMappingRule {
+    /**
+     * A string or regular expression to match against the error message.
+     */
+    pattern: string | RegExp;
+    /**
+     * The `JsonRpcErrorCode` to assign if the pattern matches.
+     */
+    errorCode: JsonRpcErrorCode;
+}
+/**
+ * A utility class providing static methods for comprehensive error handling.
+ */
+export declare class ErrorHandler {
+    /**
+     * Determines an appropriate `JsonRpcErrorCode` for a given error.
+     * @param error - The error instance or value to classify.
+     * @returns The determined error code.
+     */
+    static determineErrorCode(error: unknown): JsonRpcErrorCode;
+    static handleError(error: unknown, options: ErrorHandlerOptions): Error;
+    private static _recordOtelError;
+    private static _createFinalError;
+    private static _buildLogPayload;
+    /**
+     * Formats an error into a consistent object structure for API responses.
+     * @param error - The error instance or value to format.
+     * @returns A structured representation of the error.
+     */
+    static formatError(error: unknown): Record<string, unknown>;
+    /**
+     * Safely executes a function and handles errors using `ErrorHandler.handleError`.
+     * @param fn - The function to execute.
+     * @param options - Error handling options.
+     * @returns A promise resolving with the result of `fn`.
+     */
+    static tryCatch<T>(fn: () => Promise<T> | T, options: Omit<ErrorHandlerOptions, "rethrow">): Promise<T>;
+}
+//# sourceMappingURL=errorHandler.d.ts.map

package/dist/utils/internal/errorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/errorHandler.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,gBAAgB,EAAY,MAAM,8BAA8B,CAAC;AAG1E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;IAExC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB;;OAEG;IACH,SAAS,EAAE,gBAAgB,CAAC;CAC7B;AAkFD;;GAEG;AACH,qBAAa,YAAY;IACvB;;;;OAIG;WACW,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;WAsBpD,WAAW,CACvB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,mBAAmB,GAC3B,KAAK;IA2BR,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAa/B,OAAO,CAAC,MAAM,CAAC,iBAAiB;IA2BhC,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwB/B;;;;OAIG;WACW,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAgBlE;;;;;OAKG;WACiB,QAAQ,CAAC,CAAC,EAC5B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,GAC5C,OAAO,CAAC,CAAC,CAAC;CAOd"}

package/dist/utils/internal/errorHandler.js

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview This module provides utilities for robust error handling.
+ * It defines structures for error context, options for handling errors,
+ * and mappings for classifying errors. The main `ErrorHandler` class
+ * offers static methods for consistent error processing, logging, and transformation.
+ * @module src/utils/internal/errorHandler
+ */
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { JsonRpcErrorCode, McpError } from "../../types-global/errors.js";
+import { requestContextService, sanitizeInputForLogging } from "../index.js";
+import { logOperationError } from "./logging-helpers.js";
+/**
+ * Maps standard JavaScript error constructor names to `JsonRpcErrorCode` values.
+ * @private
+ */
+const ERROR_TYPE_MAPPINGS = {
+    SyntaxError: JsonRpcErrorCode.InvalidParams,
+    TypeError: JsonRpcErrorCode.InvalidParams,
+    ReferenceError: JsonRpcErrorCode.InternalError,
+    RangeError: JsonRpcErrorCode.InvalidParams,
+    URIError: JsonRpcErrorCode.InvalidParams,
+    EvalError: JsonRpcErrorCode.InternalError,
+};
+/**
+ * Array of `ErrorMappingRule` to classify errors by message/name patterns.
+ * Order matters: more specific patterns should precede generic ones.
+ * @private
+ */
+const COMMON_ERROR_PATTERNS = [
+    {
+        pattern: /auth|unauthorized|unauthenticated|invalid.*token/i,
+        errorCode: JsonRpcErrorCode.Unauthorized,
+    },
+    {
+        pattern: /permission|forbidden|access.*denied/i,
+        errorCode: JsonRpcErrorCode.Forbidden,
+    },
+    {
+        pattern: /not found|missing|no such/i,
+        errorCode: JsonRpcErrorCode.NotFound,
+    },
+    {
+        pattern: /invalid|validation|malformed|bad request|wrong format|missing required/i,
+        errorCode: JsonRpcErrorCode.InvalidParams, // Use the standard code for invalid parameters
+    },
+    {
+        pattern: /conflict|already exists|duplicate/i,
+        errorCode: JsonRpcErrorCode.Conflict,
+    },
+    {
+        pattern: /rate limit|too many requests/i,
+        errorCode: JsonRpcErrorCode.RateLimited,
+    },
+    {
+        pattern: /timeout|timed out/i,
+        errorCode: JsonRpcErrorCode.Timeout,
+    },
+    {
+        pattern: /service unavailable|bad gateway/i,
+        errorCode: JsonRpcErrorCode.ServiceUnavailable,
+    },
+];
+/**
+ * Creates a "safe" RegExp for testing error messages.
+ * @param pattern - The string or RegExp pattern.
+ * @returns A new RegExp instance.
+ * @private
+ */
+function createSafeRegex(pattern) {
+    if (pattern instanceof RegExp) {
+        let flags = pattern.flags.replace("g", "");
+        if (!flags.includes("i"))
+            flags += "i";
+        return new RegExp(pattern.source, flags);
+    }
+    return new RegExp(pattern, "i");
+}
+function getErrorName(error) {
+    if (error instanceof Error)
+        return error.name || "Error";
+    return "NonError";
+}
+function getErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    return "An unknown error occurred.";
+}
+/**
+ * A utility class providing static methods for comprehensive error handling.
+ */
+export class ErrorHandler {
+    /**
+     * Determines an appropriate `JsonRpcErrorCode` for a given error.
+     * @param error - The error instance or value to classify.
+     * @returns The determined error code.
+     */
+    static determineErrorCode(error) {
+        if (error instanceof McpError) {
+            return error.code;
+        }
+        const errorName = getErrorName(error);
+        const errorMessage = getErrorMessage(error);
+        const mappedFromType = ERROR_TYPE_MAPPINGS[errorName];
+        if (mappedFromType) {
+            return mappedFromType;
+        }
+        for (const mapping of COMMON_ERROR_PATTERNS) {
+            const regex = createSafeRegex(mapping.pattern);
+            if (regex.test(errorMessage) || regex.test(errorName)) {
+                return mapping.errorCode;
+            }
+        }
+        return JsonRpcErrorCode.InternalError;
+    }
+    static handleError(error, options) {
+        this._recordOtelError(error);
+        const finalError = this._createFinalError(error, options);
+        const logPayload = this._buildLogPayload(finalError, error, options);
+        // Ensure a valid context exists for logging.
+        const contextForLogging = options.context ??
+            requestContextService.createRequestContext({
+                operation: options.operation,
+            });
+        // Use the centralized logging helper for consistent error logging.
+        logOperationError(contextForLogging, finalError.message, finalError, logPayload);
+        if (options.rethrow ?? false) {
+            throw finalError;
+        }
+        return finalError;
+    }
+    static _recordOtelError(error) {
+        const activeSpan = trace.getActiveSpan();
+        if (!activeSpan)
+            return;
+        if (error instanceof Error) {
+            activeSpan.recordException(error);
+        }
+        activeSpan.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: getErrorMessage(error),
+        });
+    }
+    static _createFinalError(error, options) {
+        if (options.errorMapper) {
+            return options.errorMapper(error);
+        }
+        const determinedCode = options.errorCode || this.determineErrorCode(error);
+        const originalMessage = getErrorMessage(error);
+        if (error instanceof McpError) {
+            error.code = determinedCode; // Allow override
+            return error;
+        }
+        return new McpError(determinedCode, `Error in ${options.operation}: ${originalMessage}`, {
+            originalErrorName: getErrorName(error),
+            originalMessage,
+        }, { cause: error instanceof Error ? error : undefined });
+    }
+    static _buildLogPayload(finalError, originalError, options) {
+        const { context = {}, operation, input, critical = false } = options;
+        const payload = {
+            ...context,
+            operation,
+            input: input !== undefined ? sanitizeInputForLogging(input) : undefined,
+            critical,
+            errorCode: finalError instanceof McpError
+                ? finalError.code
+                : this.determineErrorCode(finalError),
+            originalErrorType: getErrorName(originalError),
+            finalErrorType: getErrorName(finalError),
+        };
+        // The Pino error serializer will handle the stack trace automatically.
+        return payload;
+    }
+    /**
+     * Formats an error into a consistent object structure for API responses.
+     * @param error - The error instance or value to format.
+     * @returns A structured representation of the error.
+     */
+    static formatError(error) {
+        if (error instanceof McpError) {
+            return {
+                code: error.code,
+                message: error.message,
+                details: error.details ?? {},
+            };
+        }
+        return {
+            code: this.determineErrorCode(error),
+            message: getErrorMessage(error),
+            details: { errorType: getErrorName(error) },
+        };
+    }
+    /**
+     * Safely executes a function and handles errors using `ErrorHandler.handleError`.
+     * @param fn - The function to execute.
+     * @param options - Error handling options.
+     * @returns A promise resolving with the result of `fn`.
+     */
+    static async tryCatch(fn, options) {
+        try {
+            return await Promise.resolve(fn());
+        }
+        catch (error) {
+            throw this.handleError(error, { ...options, rethrow: true });
+        }
+    }
+}
+//# sourceMappingURL=errorHandler.js.map

package/dist/utils/internal/errorHandler.js.map

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

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

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Barrel file for internal utility modules.
+ * This file re-exports core internal utilities related to error handling,
+ * logging, and request context management.
+ * @module src/utils/internal
+ */
+export * from "./asyncContext.js";
+export * from "./errorHandler.js";
+export * from "./logger.js";
+export * from "./performance.js";
+export * from "./requestContext.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/internal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC"}

package/dist/utils/internal/index.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Barrel file for internal utility modules.
+ * This file re-exports core internal utilities related to error handling,
+ * logging, and request context management.
+ * @module src/utils/internal
+ */
+export * from "./asyncContext.js";
+export * from "./errorHandler.js";
+export * from "./logger.js";
+export * from "./performance.js";
+export * from "./requestContext.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/internal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/internal/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC"}

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

@@ -0,0 +1,30 @@
+import pino from "pino";
+import { RequestContext } from "./requestContext.js";
+export type McpLogLevel = "debug" | "info" | "notice" | "warning" | "error" | "crit" | "alert" | "emerg";
+export interface McpLogPayload {
+    message: string;
+    context?: RequestContext;
+    error?: {
+        message: string;
+        stack?: string;
+    };
+    [key: string]: unknown;
+}
+export type McpNotificationData = McpLogPayload | Record<string, unknown>;
+export type McpNotificationSender = (level: McpLogLevel, data: McpNotificationData, loggerName?: string) => void;
+export declare const logger: {
+    debug: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    info: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    notice: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    warning: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    error: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    crit: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    alert: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    emerg: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    fatal: (obj: Error | Record<string, unknown> | string, msg?: string) => void;
+    logInteraction: (interactionName: string, data: Record<string, unknown>) => void;
+    setMcpNotificationSender: (sender: McpNotificationSender | undefined) => void;
+    setLevel: (newLevel: McpLogLevel) => void;
+    pino: pino.Logger;
+};
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/logger.ts"],"names":[],"mappings":"AASA,OAAO,IAGN,MAAM,MAAM,CAAC;AAGd,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAeZ,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1E,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,mBAAmB,EACzB,UAAU,CAAC,EAAE,MAAM,KAChB,IAAI,CAAC;AA4MV,eAAO,MAAM,MAAM;iBA3BX,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;gBAAtD,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;kBAAtD,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;mBAAtD,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;iBAAtD,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;gBAAtD,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;iBAAtD,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;iBAAtD,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;iBAAtD,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,QAAQ,MAAM;sCAsC1B,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;uCAIpC,qBAAqB,GAAG,SAAS;yBAI/C,WAAW;;CAYjC,CAAC"}

package/dist/utils/internal/logger.js

@@ -0,0 +1,228 @@
+/**
+ * @fileoverview Provides a globally accessible, pre-configured Pino logger instance.
+ * This module handles environment-aware logging, structured JSON output for production,
+ * pretty-printing for development, and safe file-based logging for STDIO transports.
+ * It integrates with the async context to automatically enrich logs with request details.
+ * @module src/utils/internal/logger
+ */
+import os from "os";
+import path from "path";
+import pino from "pino";
+import { config } from "../../config/index.js";
+import { getRequestContext } from "./asyncContext.js";
+// Pino levels are 'trace', 'debug', 'info', 'warn', 'error', 'fatal'.
+// We map our custom MCP levels to these.
+const mcpToPinoLevel = {
+    debug: "debug",
+    info: "info",
+    notice: "info",
+    warning: "warn",
+    error: "error",
+    crit: "fatal",
+    alert: "fatal",
+    emerg: "fatal",
+};
+let mcpNotificationSender;
+function createPinoLogger() {
+    const isProd = config.environment === "production";
+    const isStdioTransport = config.mcpTransportType === "stdio";
+    const resolvedLogsDir = config.logsPath;
+    const logLevel = mcpToPinoLevel[config.logLevel] || "info";
+    // Build a transport target list so we can combine console + file outputs.
+    const targets = [];
+    // Console pretty printing for local dev (non-stdio, non-prod) if TTY.
+    if (!isProd && !isStdioTransport && process.stdout.isTTY) {
+        targets.push({
+            target: "pino-pretty",
+            options: {
+                colorize: true,
+                destination: process.stderr.fd,
+                ignore: "pid,hostname,env,name",
+                translateTime: "SYS:yyyy-mm-dd HH:MM:ss.l",
+            },
+            level: "debug",
+        });
+    }
+    // File logging: required for stdio/prod; optional for others when logs dir is available.
+    if (isStdioTransport || isProd) {
+        if (!resolvedLogsDir) {
+            throw new Error("Configuration Error: LOGS_PATH must be defined for STDIO transport or production environments.");
+        }
+    }
+    if (resolvedLogsDir) {
+        // Combined rotating log file (JSON) similar to previous combined.log
+        targets.push({
+            target: "pino-roll",
+            options: {
+                file: path.join(resolvedLogsDir, "combined.log"),
+                frequency: "daily",
+                mkdir: true,
+                size: "10m",
+                files: 5,
+            },
+            level: "info",
+        });
+        // Level-specific rolling files to mirror prior Winston setup
+        targets.push({
+            target: "pino-roll",
+            options: {
+                file: path.join(resolvedLogsDir, "error.log"),
+                frequency: "daily",
+                mkdir: true,
+                size: "10m",
+                files: 5,
+            },
+            level: "error",
+        }, {
+            target: "pino-roll",
+            options: {
+                file: path.join(resolvedLogsDir, "warn.log"),
+                frequency: "daily",
+                mkdir: true,
+                size: "10m",
+                files: 5,
+            },
+            level: "warn",
+        }, {
+            target: "pino-roll",
+            options: {
+                file: path.join(resolvedLogsDir, "info.log"),
+                frequency: "daily",
+                mkdir: true,
+                size: "10m",
+                files: 5,
+            },
+            level: "info",
+        }, {
+            target: "pino-roll",
+            options: {
+                file: path.join(resolvedLogsDir, "debug.log"),
+                frequency: "daily",
+                mkdir: true,
+                size: "10m",
+                files: 5,
+            },
+            level: "debug",
+        });
+    }
+    const pinoInstance = pino({
+        name: config.mcpServerName || "mcp-server",
+        level: logLevel,
+        timestamp: pino.stdTimeFunctions.isoTime,
+        redact: {
+            paths: [
+                "password",
+                "token",
+                "apiKey",
+                "secret",
+                "authorization",
+                "cookie",
+            ],
+            censor: "[REDACTED]",
+        },
+        base: {
+            pid: process.pid,
+            hostname: os.hostname(),
+            env: config.environment,
+        },
+        // Automatically add request context to every log message via async local storage.
+        // mixin() {
+        //   return getRequestContext() ?? {};
+        // },
+        // Use Pino's standard error serializer for robust error logging.
+        serializers: {
+            err: pino.stdSerializers.err,
+        },
+        transport: targets.length > 0 ? { targets } : undefined,
+    });
+    // Set up a global uncaught exception handler to ensure fatal errors are logged before exit.
+    process.on("uncaughtException", (err) => {
+        pinoInstance.fatal(err, "Uncaught exception detected. The application will now exit.");
+        process.exit(1);
+    });
+    return pinoInstance;
+}
+const mainLogger = createPinoLogger();
+// Create a dedicated logger for interaction-specific logs.
+// Create a dedicated interaction logger that writes to interactions.log if logsPath is available.
+let interactionLogger;
+if (config.logsPath) {
+    const interactionLogLevel = mcpToPinoLevel[config.logLevel] || "info";
+    interactionLogger = pino({
+        name: `${config.mcpServerName || "mcp-server"}-interactions`,
+        level: interactionLogLevel,
+        timestamp: pino.stdTimeFunctions.isoTime,
+        transport: {
+            targets: [
+                {
+                    target: "pino-roll",
+                    options: {
+                        file: path.join(config.logsPath, "interactions.log"),
+                        frequency: "daily",
+                        mkdir: true,
+                        size: "10m",
+                        files: 5,
+                    },
+                    level: "info",
+                },
+            ],
+        },
+    });
+}
+else {
+    interactionLogger = mainLogger.child({ name: "interaction-logger" });
+}
+// Wrapper function to preserve the original MCP log levels and handle notifications.
+const logWrapper = (level) => (obj, msg) => {
+    const pinoLevel = mcpToPinoLevel[level];
+    if (typeof obj === "string") {
+        mainLogger[pinoLevel](obj);
+    }
+    else if (obj instanceof Error) {
+        // Pino convention: pass error as 'err' property for the serializer to pick it up.
+        mainLogger[pinoLevel]({ err: obj }, msg);
+    }
+    else {
+        mainLogger[pinoLevel](obj, msg);
+    }
+    if (mcpNotificationSender) {
+        const payload = {
+            message: typeof obj === "string"
+                ? obj
+                : msg || obj.message || "No message provided.",
+            context: getRequestContext(),
+        };
+        if (typeof obj === "object" && obj !== null) {
+            Object.assign(payload, obj);
+        }
+        mcpNotificationSender(level, payload, config.mcpServerName);
+    }
+};
+export const logger = {
+    debug: logWrapper("debug"),
+    info: logWrapper("info"),
+    notice: logWrapper("notice"),
+    warning: logWrapper("warning"),
+    error: logWrapper("error"),
+    crit: logWrapper("crit"),
+    alert: logWrapper("alert"),
+    emerg: logWrapper("emerg"),
+    fatal: logWrapper("emerg"), // Alias fatal to emerg for convenience
+    logInteraction: (interactionName, data) => {
+        interactionLogger.info({ interactionName, ...data });
+    },
+    setMcpNotificationSender: (sender) => {
+        mcpNotificationSender = sender;
+    },
+    setLevel: (newLevel) => {
+        if (mcpToPinoLevel[newLevel]) {
+            mainLogger.level = mcpToPinoLevel[newLevel];
+        }
+        else {
+            mainLogger.warn(`Invalid MCP log level provided: ${newLevel}. Log level remains unchanged.`);
+        }
+    },
+    // Expose the raw pino instance for advanced use cases, like passing to other libraries.
+    pino: mainLogger,
+};
+//# sourceMappingURL=logger.js.map