mcp-server-framework 1.0.0

package/build/logger/formatters/schema.js

@@ -0,0 +1,278 @@
+/**
+ * Structured Log Schema Module
+ *
+ * Defines the JSON log format compatible with ELK Stack, Datadog, Splunk,
+ * and other log aggregation platforms.
+ *
+ * Based on:
+ * - Elastic Common Schema (ECS) 8.x
+ * - OpenTelemetry Semantic Conventions
+ * - RFC 5424 Syslog
+ *
+ * @module logger/formatters/schema
+ */
+import { LOG_SEVERITY } from "../core/constants.js";
+/**
+ * Structured log entry for JSON output.
+ * Compatible with ECS (Elastic Common Schema) for log aggregation.
+ */
+/**
+ * ECS version this schema targets.
+ * @see https://www.elastic.co/guide/en/ecs/current
+ */
+export const ECS_VERSION = "8.11.0";
+/**
+ * Format error for structured log entry.
+ */
+function formatLogError(error) {
+    if ("toJSON" in error && typeof error.toJSON === "function") {
+        try {
+            // @ts-limitation — Duck-typed toJSON() returns unknown; runtime check validates AppError pattern
+            const serialized = error.toJSON();
+            return {
+                type: serialized.name,
+                message: serialized.message,
+                code: serialized.code,
+                stack_trace: serialized.stack,
+            };
+        }
+        catch {
+            // toJSON() threw — fall through to standard Error handling
+        }
+    }
+    if (error instanceof Error) {
+        return {
+            type: error.name,
+            message: error.message,
+            stack_trace: error.stack,
+        };
+    }
+    return {
+        type: error.name,
+        message: error.message,
+        code: error.code,
+        stack_trace: error.stack,
+    };
+}
+/**
+ * Build a structured log entry from options.
+ *
+ * Replaces the fluent LogEntryBuilder with a single-call factory function.
+ * All optional fields that are undefined are stripped from the output.
+ *
+ * @param options - Log entry parameters
+ * @returns Clean StructuredLogEntry with only defined fields
+ */
+export function buildLogEntry(options) {
+    const entry = {
+        "@timestamp": new Date().toISOString(),
+        "ecs.version": ECS_VERSION,
+        // @ts-limitation — String.toUpperCase() returns string; TS cannot infer Uppercase<T> template literal
+        level: options.level.toUpperCase(),
+        "log.level": LOG_SEVERITY[options.level],
+        message: options.message,
+        service: options.service ?? { name: "mcp-server" },
+        ...(options.component && { "log.logger": options.component }),
+        ...(options.host && { host: options.host }),
+        ...(options.process && { process: options.process }),
+        ...(options.trace && { trace: options.trace }),
+        ...(options.session && { session: options.session }),
+        ...(options.http && { http: options.http }),
+        ...(options.error && { error: formatLogError(options.error) }),
+        ...(options.event && { event: options.event }),
+        ...(options.labels && { labels: options.labels }),
+        ...(options.metadata &&
+            Object.keys(options.metadata).length > 0 && {
+            metadata: options.metadata,
+        }),
+    };
+    // Spread conditionals above already exclude undefined top-level fields.
+    // Any nested undefined values are naturally stripped by JSON.stringify()
+    // in downstream formatters, so no separate round-trip is needed.
+    return entry;
+}
+/**
+ * @deprecated Use {@link buildLogEntry} instead. Will be removed in a future major version.
+ *
+ * Builder class for creating structured log entries.
+ * Provides a fluent API for constructing log entries.
+ *
+ * @example
+ * ```typescript
+ * const entry = new LogEntryBuilder('info', 'User logged in')
+ *   .withService('mcp-server', '1.0.0')
+ *   .withSession('abc123')
+ *   .withEvent('auth', 'login', 'success')
+ *   .build();
+ * ```
+ */
+export class LogEntryBuilder {
+    entry;
+    constructor(level, message) {
+        this.entry = {
+            "@timestamp": new Date().toISOString(),
+            "ecs.version": ECS_VERSION,
+            // @ts-limitation — String.toUpperCase() returns string; TS cannot infer Uppercase<T> template literal
+            level: level.toUpperCase(),
+            "log.level": LOG_SEVERITY[level],
+            message,
+            service: {
+                name: "mcp-server",
+            },
+        };
+    }
+    /**
+     * Set service information.
+     */
+    withService(name, version, environment, component) {
+        this.entry.service = {
+            name,
+            version,
+            environment,
+            component,
+        };
+        // log.logger tracks the producing component
+        if (component) {
+            this.entry["log.logger"] = component;
+        }
+        return this;
+    }
+    /**
+     * Set host information.
+     */
+    withHost(name, architecture, osType) {
+        if (name || architecture || osType) {
+            this.entry.host = {
+                name,
+                architecture,
+                os: osType ? { type: osType } : undefined,
+            };
+        }
+        return this;
+    }
+    /**
+     * Set process information.
+     */
+    withProcess(pid, name) {
+        if (pid !== undefined || name) {
+            this.entry.process = { pid, name };
+        }
+        return this;
+    }
+    /**
+     * Set trace context for distributed tracing.
+     */
+    withTrace(traceId, spanId, parentId) {
+        if (traceId || spanId || parentId) {
+            this.entry.trace = {
+                id: traceId,
+                "span.id": spanId,
+                "parent.id": parentId,
+            };
+        }
+        return this;
+    }
+    /**
+     * Set session information.
+     */
+    withSession(sessionId) {
+        if (sessionId) {
+            this.entry.session = { id: sessionId };
+        }
+        return this;
+    }
+    /**
+     * Set HTTP request context.
+     */
+    withHttp(method, path, statusCode, durationMs) {
+        if (method || path || statusCode !== undefined || durationMs !== undefined) {
+            this.entry.http = {
+                method,
+                "url.path": path,
+                "response.status_code": statusCode,
+                "request.duration_ms": durationMs,
+            };
+        }
+        return this;
+    }
+    /**
+     * Set error information.
+     */
+    withError(error) {
+        if ("toJSON" in error && typeof error.toJSON === "function") {
+            // @ts-limitation — Duck-typed toJSON() returns unknown; runtime check validates AppError pattern
+            const serialized = error.toJSON();
+            this.entry.error = {
+                type: serialized.name,
+                message: serialized.message,
+                code: serialized.code,
+                stack_trace: serialized.stack,
+            };
+        }
+        else if (error instanceof Error) {
+            this.entry.error = {
+                type: error.name,
+                message: error.message,
+                stack_trace: error.stack,
+            };
+        }
+        else {
+            // LogSerializedError object
+            this.entry.error = {
+                type: error.name,
+                message: error.message,
+                code: error.code,
+                stack_trace: error.stack,
+            };
+        }
+        return this;
+    }
+    /**
+     * Set event metadata.
+     */
+    withEvent(category, action, outcome, durationNs) {
+        if (category || action || outcome || durationNs !== undefined) {
+            this.entry.event = {
+                category,
+                action,
+                outcome,
+                duration: durationNs,
+            };
+        }
+        return this;
+    }
+    /**
+     * Add custom labels for indexing.
+     */
+    withLabels(labels) {
+        this.entry.labels = { ...this.entry.labels, ...labels };
+        return this;
+    }
+    /**
+     * Add additional metadata.
+     */
+    withMetadata(metadata) {
+        this.entry.metadata = { ...this.entry.metadata, ...metadata };
+        return this;
+    }
+    /**
+     * Build the final log entry.
+     */
+    build() {
+        // JSON round-trip strips undefined values for cleaner output
+        return JSON.parse(JSON.stringify(this.entry));
+    }
+    /**
+     * Build and stringify the log entry.
+     */
+    toString() {
+        return JSON.stringify(this.build());
+    }
+}
+/**
+ * Helper function to create a structured log entry.
+ */
+export function createLogEntry(level, message) {
+    return new LogEntryBuilder(level, message);
+}
+//# sourceMappingURL=schema.js.map

package/build/logger/formatters/schema.js.map

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

package/build/logger/formatters/text-formatter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Text Formatter Module
+ *
+ * Provides human-readable log formatting for development and debugging.
+ * Format: [RFC3339-TIMESTAMP] [LEVEL] [Component] [Context] Message {metadata}
+ *
+ * @module logger/formatters/text-formatter
+ */
+import type { LogFormatter, LogEntryParams } from "../core/types.js";
+/**
+ * Configuration for the text formatter.
+ */
+export interface TextFormatterConfig {
+    /** Whether to include timestamps (default: true) */
+    includeTimestamp?: boolean | undefined;
+    /** Whether to include the component name (default: true) */
+    includeComponent?: boolean | undefined;
+    /** Whether to include session/request context (default: true) */
+    includeContext?: boolean | undefined;
+}
+/**
+ * Text Formatter class for human-readable log output.
+ *
+ * Produces logs in the format:
+ * `[2026-03-11T19:12:58.760Z] [INFO]  [server] [sess:req] Processing request {count: 42}`
+ */
+export declare class TextFormatter implements LogFormatter {
+    private config;
+    /**
+     * Create a new TextFormatter.
+     * @param config - Formatter configuration
+     */
+    constructor(config?: TextFormatterConfig);
+    /**
+     * Format a log entry as human-readable text.
+     *
+     * @param params - Log entry parameters
+     * @returns Formatted text string
+     */
+    format(params: LogEntryParams): string;
+    /**
+     * Format the context portion of the log entry.
+     */
+    private formatContext;
+}
+/**
+ * Default text formatter instance.
+ */
+export declare const textFormatter: TextFormatter;
+//# sourceMappingURL=text-formatter.d.ts.map

package/build/logger/formatters/text-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-formatter.d.ts","sourceRoot":"","sources":["../../../src/logger/formatters/text-formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAc,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGjF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC;AAED;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,CAAC,MAAM,CAAgC;IAE9C;;;OAGG;gBACS,MAAM,GAAE,mBAAwB;IAQ5C;;;;;OAKG;IACI,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM;IAwC7C;;OAEG;IACH,OAAO,CAAC,aAAa;CAqBtB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/build/logger/formatters/text-formatter.js

@@ -0,0 +1,93 @@
+/**
+ * Text Formatter Module
+ *
+ * Provides human-readable log formatting for development and debugging.
+ * Format: [RFC3339-TIMESTAMP] [LEVEL] [Component] [Context] Message {metadata}
+ *
+ * @module logger/formatters/text-formatter
+ */
+import * as util from "util";
+import { ID_DISPLAY_LENGTH, LEVEL_PAD_LENGTH } from "../core/constants.js";
+/**
+ * Text Formatter class for human-readable log output.
+ *
+ * Produces logs in the format:
+ * `[2026-03-11T19:12:58.760Z] [INFO]  [server] [sess:req] Processing request {count: 42}`
+ */
+export class TextFormatter {
+    config;
+    /**
+     * Create a new TextFormatter.
+     * @param config - Formatter configuration
+     */
+    constructor(config = {}) {
+        this.config = {
+            includeTimestamp: config.includeTimestamp ?? true,
+            includeComponent: config.includeComponent ?? true,
+            includeContext: config.includeContext ?? true,
+        };
+    }
+    /**
+     * Format a log entry as human-readable text.
+     *
+     * @param params - Log entry parameters
+     * @returns Formatted text string
+     */
+    format(params) {
+        const { level, message, formatArgs = [], component, context, metadata } = params;
+        const parts = [];
+        // Timestamp (RFC 3339 / ISO 8601 — preserves 'T' separator and 'Z' suffix)
+        if (this.config.includeTimestamp) {
+            const timestamp = params.timestamp ?? new Date().toISOString();
+            parts.push(`[${timestamp}]`);
+        }
+        // Level (padded after bracket for column alignment)
+        const levelStr = level.toUpperCase();
+        parts.push(`[${levelStr}]`.padEnd(LEVEL_PAD_LENGTH + 2));
+        // Component
+        if (this.config.includeComponent) {
+            parts.push(`[${component}]`);
+        }
+        // Context (session/request IDs)
+        if (this.config.includeContext && context) {
+            const contextStr = this.formatContext(context);
+            if (contextStr) {
+                parts.push(`[${contextStr}]`);
+            }
+        }
+        // Message with printf-style formatting
+        const formattedMessage = util.format(message, ...formatArgs);
+        parts.push(formattedMessage);
+        // Metadata
+        if (metadata && Object.keys(metadata).length > 0) {
+            parts.push(JSON.stringify(metadata));
+        }
+        return parts.join(" ");
+    }
+    /**
+     * Format the context portion of the log entry.
+     */
+    formatContext(context) {
+        const parts = [];
+        if (context.sessionId) {
+            parts.push(context.sessionId.slice(0, ID_DISPLAY_LENGTH));
+        }
+        if (context.requestId) {
+            if (parts.length > 0) {
+                parts.push(context.requestId.slice(0, ID_DISPLAY_LENGTH));
+            }
+            else {
+                parts.push(`Req:${context.requestId.slice(0, ID_DISPLAY_LENGTH)}`);
+            }
+        }
+        if (context.traceId) {
+            parts.push(`T:${context.traceId.slice(0, ID_DISPLAY_LENGTH)}`);
+        }
+        return parts.join(":");
+    }
+}
+/**
+ * Default text formatter instance.
+ */
+export const textFormatter = new TextFormatter();
+//# sourceMappingURL=text-formatter.js.map

package/build/logger/formatters/text-formatter.js.map

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

package/build/logger/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Logger Module — Public API
+ *
+ * Centralized logging for the MCP server framework.
+ * Only exports what consumers need. Internal components (writers, formatters,
+ * scrubbing, context, constants) are accessed via direct imports within
+ * the logger module.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { logger, configureLogger } from './logger/index.js';
+ *
+ * configureLogger({
+ *   LOG_LEVEL: 'info',
+ *   LOG_FORMAT: 'text',
+ *   MCP_TRANSPORT: 'http',
+ *   NODE_ENV: 'production',
+ *   SERVER_NAME: 'my-mcp-server',
+ *   SERVER_VERSION: '1.0.0',
+ * });
+ *
+ * logger.info('Server started on port %d', 8000);
+ *
+ * const apiLogger = logger.child({ component: 'api' });
+ * apiLogger.debug('Processing request');
+ * ```
+ *
+ * @module logger
+ */
+export type { LogLevel, McpLogLevel, TransportMode, HttpContext, EventContext, LogContext, LoggerInterface, LogWriter, LogFormatter, LogEntryParams, LoggerConfig, LogNotificationHandler, } from "./core/index.js";
+export type { LoggerOptions } from "./logger.js";
+export { LoggerResources, type LoggerSystemConfig, type LoggerDependencies } from "./factory.js";
+export { SecretScrubber } from "./scrubbing/index.js";
+export { InjectionGuard } from "./scrubbing/index.js";
+export { logger, Logger } from "./logger.js";
+export { configureLogger, getLoggerConfig, resetLoggerConfig, type GlobalLoggerConfig } from "./logger.js";
+export { mcpLogger, McpNotificationLogger, type McpLoggerConfig } from "./mcp-logger.js";
+//# sourceMappingURL=index.d.ts.map

package/build/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,YAAY,EACV,QAAQ,EACR,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEjG,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAMtD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAM3G,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/build/logger/index.js

@@ -0,0 +1,43 @@
+/**
+ * Logger Module — Public API
+ *
+ * Centralized logging for the MCP server framework.
+ * Only exports what consumers need. Internal components (writers, formatters,
+ * scrubbing, context, constants) are accessed via direct imports within
+ * the logger module.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { logger, configureLogger } from './logger/index.js';
+ *
+ * configureLogger({
+ *   LOG_LEVEL: 'info',
+ *   LOG_FORMAT: 'text',
+ *   MCP_TRANSPORT: 'http',
+ *   NODE_ENV: 'production',
+ *   SERVER_NAME: 'my-mcp-server',
+ *   SERVER_VERSION: '1.0.0',
+ * });
+ *
+ * logger.info('Server started on port %d', 8000);
+ *
+ * const apiLogger = logger.child({ component: 'api' });
+ * apiLogger.debug('Processing request');
+ * ```
+ *
+ * @module logger
+ */
+export { LoggerResources } from "./factory.js";
+export { SecretScrubber } from "./scrubbing/index.js";
+export { InjectionGuard } from "./scrubbing/index.js";
+// =============================================================================
+// Main Logger
+// =============================================================================
+export { logger, Logger } from "./logger.js";
+export { configureLogger, getLoggerConfig, resetLoggerConfig } from "./logger.js";
+// =============================================================================
+// MCP Logger (notifications to connected clients)
+// =============================================================================
+export { mcpLogger, McpNotificationLogger } from "./mcp-logger.js";
+//# sourceMappingURL=index.js.map

package/build/logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAuBH,OAAO,EAAE,eAAe,EAAoD,MAAM,cAAc,CAAC;AAEjG,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAA2B,MAAM,aAAa,CAAC;AAE3G,gFAAgF;AAChF,kDAAkD;AAClD,gFAAgF;AAEhF,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAwB,MAAM,iBAAiB,CAAC"}