mcp-server-framework 1.0.0

package/build/logger/scrubbing/secret-scrubber.js

@@ -0,0 +1,177 @@
+/**
+ * Secret Scrubber Module
+ *
+ * Provides utilities for detecting and redacting sensitive information from logs.
+ * Handles JWTs, Bearer tokens, and key-value pairs with sensitive keys.
+ *
+ * @module logger/scrubbing/secret-scrubber
+ */
+import { SENSITIVE_KEYS as BASE_SENSITIVE_KEYS, isSensitiveKey as baseSensitiveKeyCheck, } from "../../utils/sensitive-keys.js";
+import { REDACTED_VALUE, JWT_PREFIX } from "../core/constants.js";
+/**
+ * Pre-compiled regex patterns for secret scrubbing.
+ * Performance optimization: compile once at module load instead of on every log call.
+ */
+/** Regex to match JWTs (eyJ...) - three base64 segments separated by dots */
+const JWT_REGEX = new RegExp(`\\b${JWT_PREFIX}[a-zA-Z0-9-_]+\\.[a-zA-Z0-9-_]+\\.[a-zA-Z0-9-_]+`, "g");
+/** Regex to match Bearer tokens */
+const BEARER_REGEX = /\bBearer\s+[a-zA-Z0-9._~+\-/=]+/gi;
+/** Regex to match Basic Auth credentials (Authorization: Basic <base64>) */
+const BASIC_AUTH_REGEX = /\bBasic\s+[A-Za-z0-9+/=]{8,}/gi;
+/** Regex to match key-value pairs with sensitive keys (excluding bearer/authorization) */
+const KV_KEYS = BASE_SENSITIVE_KEYS.filter((k) => !["bearer", "authorization"].includes(k.toLowerCase()));
+const KV_PATTERN = KV_KEYS.join("|");
+// Pre-computed lowercase keys for fast includes() pre-check before applying regex
+const KV_KEYS_LOWER = KV_KEYS.map((k) => k.toLowerCase());
+// Use custom boundary instead of \b — word boundaries treat _ as a word character,
+// so \bapi_key\b fails to match in "my_api_key=secret". Adding _ - . to the boundary
+// class ensures compound keys like my_api_key, app.secret, my-token are matched.
+const KV_REGEX = new RegExp(`(^|[\\s"'{(,;_\\-.])(${KV_PATTERN})(\\s*[:=]\\s*)(["']?)([^\\s"']+)\\4`, "gi");
+/** Regex to match sensitive URL query parameters (?key=value or &key=value) */
+const URL_PARAM_PATTERN = BASE_SENSITIVE_KEYS.filter((k) => !["bearer", "authorization", "key"].includes(k.toLowerCase())).join("|");
+const URL_PARAM_REGEX = new RegExp(`([?&](?:${URL_PARAM_PATTERN})=)([^&\\s]+)`, "gi");
+/** Regex to match credentials in connection strings (scheme://user:pass@host, including IPv6 [::1]) */
+const CONN_STRING_REGEX = /:\/\/([^/:@\s[\]]+|\[[^\]]+\]):([^@\s]+)@/g;
+/** Regex to match AWS access key IDs (AKIA followed by 16 uppercase alphanumeric characters) */
+const AWS_KEY_REGEX = /AKIA[0-9A-Z]{16}/g;
+/**
+ * Secret Scrubber class for detecting and redacting sensitive information.
+ *
+ * Usage:
+ * - Create a scrubber: `const scrubber = new SecretScrubber();`
+ * - Scrub a string: `scrubber.scrub('token=secret123')` returns `'token=**********'`
+ * - Scrub an object: `scrubber.scrubObject({ password: 'secret' })` returns `{ password: '**********' }`
+ */
+export class SecretScrubber {
+    /**
+     * Additional sensitive keys provided at construction time.
+     * These bypass the shared blocklist since they are explicitly
+     * provided by the consumer as known-sensitive patterns.
+     */
+    additionalKeys;
+    /**
+     * Create a new SecretScrubber.
+     * @param additionalKeys - Additional keys to consider sensitive
+     */
+    constructor(additionalKeys = []) {
+        this.additionalKeys = additionalKeys;
+    }
+    /**
+     * Scrub secrets from a text string.
+     *
+     * Handles:
+     * - JWTs (eyJ...)
+     * - Bearer tokens
+     * - Key-value pairs with sensitive keys
+     *
+     * @param text - The text to scrub
+     * @returns The scrubbed text
+     */
+    scrub(text) {
+        let scrubbed = text;
+        // 1. Known Secret Formats (High Confidence) - JWT
+        scrubbed = scrubbed.replace(JWT_REGEX, REDACTED_VALUE);
+        // 2. Common Auth Headers - Bearer token
+        // Run before generic KV scrubber to ensure "Bearer <token>" is handled as a unit
+        scrubbed = scrubbed.replace(BEARER_REGEX, `Bearer ${REDACTED_VALUE}`);
+        // 3. Basic Auth - "Basic <base64>"
+        scrubbed = scrubbed.replace(BASIC_AUTH_REGEX, `Basic ${REDACTED_VALUE}`);
+        // 4. AWS access key IDs - "AKIA..."
+        scrubbed = scrubbed.replace(AWS_KEY_REGEX, REDACTED_VALUE);
+        // 5. Connection strings - "scheme://user:pass@host"
+        scrubbed = scrubbed.replace(CONN_STRING_REGEX, `://$1:${REDACTED_VALUE}@`);
+        // 6. Sensitive URL query parameters - "?password=xxx&api_key=yyy"
+        scrubbed = scrubbed.replace(URL_PARAM_REGEX, `$1${REDACTED_VALUE}`);
+        // 7. Context-based Scrubbing (Key-Value pairs)
+        // Pre-check: skip expensive regex if no sensitive key substring is present
+        const lowerScrubbed = scrubbed.toLowerCase();
+        if (KV_KEYS_LOWER.some((k) => lowerScrubbed.includes(k))) {
+            scrubbed = scrubbed.replace(KV_REGEX, (match, prefix, key, sep, quote, value) => {
+                // Don't redact if already redacted
+                if (value.includes(REDACTED_VALUE))
+                    return match;
+                return `${prefix}${key}${sep}${quote}${REDACTED_VALUE}${quote}`;
+            });
+        }
+        return scrubbed;
+    }
+    /**
+     * Recursively scrub sensitive keys from an object.
+     *
+     * Also scrubs string values that may contain embedded secrets
+     * (e.g., "password=secret123" patterns).
+     *
+     * @param obj - The object to scrub
+     * @returns A new object with sensitive values redacted
+     */
+    scrubObject(obj) {
+        return this.scrubObjectRecursive(obj, new WeakSet());
+    }
+    /**
+     * Internal recursive scrub with circular reference protection.
+     */
+    scrubObjectRecursive(obj, visited) {
+        if (typeof obj !== "object" || obj === null) {
+            // Scrub string values for embedded secrets (e.g., "token=abc123")
+            if (typeof obj === "string") {
+                return this.scrub(obj);
+            }
+            return obj;
+        }
+        // Circular reference protection — prevent stack overflow
+        if (visited.has(obj)) {
+            return "[Circular]";
+        }
+        visited.add(obj);
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this.scrubObjectRecursive(item, visited));
+        }
+        const redacted = {};
+        // @type-narrowing — After null-check and Array.isArray, obj is a plain object; TS cannot narrow unknown to Record
+        const objRecord = obj;
+        for (const key in objRecord) {
+            if (Object.prototype.hasOwnProperty.call(objRecord, key)) {
+                if (this.isSensitiveKey(key)) {
+                    redacted[key] = REDACTED_VALUE;
+                }
+                else if (typeof objRecord[key] === "object") {
+                    redacted[key] = this.scrubObjectRecursive(objRecord[key], visited);
+                }
+                else if (typeof objRecord[key] === "string") {
+                    // @type-narrowing — typeof === 'string' branch; TS does not narrow Record<string, unknown> values via control flow
+                    redacted[key] = this.scrub(objRecord[key]);
+                }
+                else {
+                    redacted[key] = objRecord[key];
+                }
+            }
+        }
+        return redacted;
+    }
+    /**
+     * Check if a key is sensitive.
+     *
+     * Delegates to the shared utility for base sensitive keys (including
+     * blocklist logic). Additional keys provided at construction are checked
+     * separately — they bypass the blocklist since they are explicitly
+     * declared as sensitive by the consumer.
+     *
+     * @param key - The key to check
+     * @returns true if the key matches a sensitive pattern
+     */
+    isSensitiveKey(key) {
+        // Delegate to shared utility for base sensitive keys (includes blocklist)
+        if (baseSensitiveKeyCheck(key))
+            return true;
+        // Check additional keys — explicitly provided, no blocklist needed
+        if (this.additionalKeys.length === 0)
+            return false;
+        const lowerKey = key.toLowerCase();
+        return this.additionalKeys.some((ak) => lowerKey.includes(ak.toLowerCase()));
+    }
+}
+/**
+ * Default secret scrubber instance.
+ */
+export const secretScrubber = new SecretScrubber();
+//# sourceMappingURL=secret-scrubber.js.map

package/build/logger/scrubbing/secret-scrubber.js.map

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

package/build/logger/writers/base-writer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Base Log Writer Module
+ *
+ * Defines the abstract base class for all log writers.
+ * Writers are responsible for outputting log entries to specific destinations.
+ *
+ * @module logger/writers/base-writer
+ */
+import type { LogLevel, LogWriter } from "../core/types.js";
+/**
+ * Abstract base class for log writers.
+ * Provides common functionality for all writer implementations.
+ */
+export declare abstract class BaseLogWriter implements LogWriter {
+    protected enabled: boolean;
+    /**
+     * Write a log entry to the destination.
+     * Must be implemented by subclasses.
+     *
+     * @param level - The log level
+     * @param message - The formatted log message
+     * @param component - The component that generated the log
+     */
+    abstract write(level: LogLevel, message: string, component: string): void;
+    /**
+     * Close the writer and release any resources.
+     * Override in subclasses that need cleanup.
+     *
+     * @returns Promise that resolves when the writer is closed
+     */
+    close(): Promise<void>;
+    /**
+     * Check if the writer is available/ready.
+     *
+     * @returns true if the writer can accept log entries
+     */
+    isAvailable(): boolean;
+    /**
+     * Enable or disable the writer.
+     *
+     * @param enabled - Whether the writer should be enabled
+     */
+    setEnabled(enabled: boolean): void;
+}
+//# sourceMappingURL=base-writer.d.ts.map

package/build/logger/writers/base-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-writer.d.ts","sourceRoot":"","sources":["../../../src/logger/writers/base-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;;GAGG;AACH,8BAAsB,aAAc,YAAW,SAAS;IACtD,SAAS,CAAC,OAAO,EAAE,OAAO,CAAQ;IAElC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAEzE;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAItB;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CAGnC"}

package/build/logger/writers/base-writer.js

@@ -0,0 +1,41 @@
+/**
+ * Base Log Writer Module
+ *
+ * Defines the abstract base class for all log writers.
+ * Writers are responsible for outputting log entries to specific destinations.
+ *
+ * @module logger/writers/base-writer
+ */
+/**
+ * Abstract base class for log writers.
+ * Provides common functionality for all writer implementations.
+ */
+export class BaseLogWriter {
+    enabled = true;
+    /**
+     * Close the writer and release any resources.
+     * Override in subclasses that need cleanup.
+     *
+     * @returns Promise that resolves when the writer is closed
+     */
+    async close() {
+        this.enabled = false;
+    }
+    /**
+     * Check if the writer is available/ready.
+     *
+     * @returns true if the writer can accept log entries
+     */
+    isAvailable() {
+        return this.enabled;
+    }
+    /**
+     * Enable or disable the writer.
+     *
+     * @param enabled - Whether the writer should be enabled
+     */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+}
+//# sourceMappingURL=base-writer.js.map

package/build/logger/writers/base-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-writer.js","sourceRoot":"","sources":["../../../src/logger/writers/base-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;GAGG;AACH,MAAM,OAAgB,aAAa;IACvB,OAAO,GAAY,IAAI,CAAC;IAYlC;;;;;OAKG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,OAAgB;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/build/logger/writers/composite-writer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Composite Log Writer Module
+ *
+ * Combines multiple log writers into a single writer interface.
+ * Delegates write operations to all registered writers.
+ *
+ * @module logger/writers/composite-writer
+ */
+import type { LogLevel, LogWriter } from "../core/types.js";
+import { BaseLogWriter } from "./base-writer.js";
+/**
+ * Composite Writer class that combines multiple writers.
+ *
+ * This is the primary writer used by the Logger class.
+ * It manages multiple output destinations (console, file, MCP)
+ * and ensures all enabled writers receive log entries.
+ *
+ * @example
+ * ```typescript
+ * const composite = new CompositeWriter();
+ * composite.addWriter('console', consoleWriter);
+ * composite.addWriter('file', fileWriter);
+ * composite.write('info', 'Hello world', 'server'); // Goes to both writers
+ * ```
+ */
+export declare class CompositeWriter extends BaseLogWriter {
+    private writers;
+    /**
+     * Add a named writer to the composite.
+     *
+     * @param name - Unique name for the writer
+     * @param writer - The writer instance
+     */
+    addWriter(name: string, writer: LogWriter): void;
+    /**
+     * Remove a writer by name.
+     *
+     * @param name - The writer name to remove
+     * @returns true if a writer was removed
+     */
+    removeWriter(name: string): boolean;
+    /**
+     * Get a writer by name.
+     *
+     * @param name - The writer name
+     * @returns The writer or undefined
+     */
+    getWriter(name: string): LogWriter | undefined;
+    /**
+     * Check if a writer exists.
+     *
+     * @param name - The writer name
+     * @returns true if the writer exists
+     */
+    hasWriter(name: string): boolean;
+    /**
+     * Write to all enabled writers.
+     *
+     * @param level - The log level
+     * @param message - The formatted log message
+     * @param component - The component that generated the log
+     */
+    write(level: LogLevel, message: string, component: string): void;
+    /**
+     * Close all writers.
+     *
+     * @returns Promise that resolves when all writers are closed
+     */
+    close(): Promise<void>;
+    /**
+     * Check if any writer is available.
+     */
+    isAvailable(): boolean;
+    /**
+     * Get the number of registered writers.
+     */
+    getWriterCount(): number;
+    /**
+     * Get all writer names.
+     */
+    getWriterNames(): string[];
+}
+//# sourceMappingURL=composite-writer.d.ts.map

package/build/logger/writers/composite-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-writer.d.ts","sourceRoot":"","sources":["../../../src/logger/writers/composite-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAChD,OAAO,CAAC,OAAO,CAAqC;IAEpD;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAIhD;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAInC;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI9C;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAehE;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;OAEG;IACH,WAAW,IAAI,OAAO;IAStB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,cAAc,IAAI,MAAM,EAAE;CAG3B"}

package/build/logger/writers/composite-writer.js

@@ -0,0 +1,121 @@
+/**
+ * Composite Log Writer Module
+ *
+ * Combines multiple log writers into a single writer interface.
+ * Delegates write operations to all registered writers.
+ *
+ * @module logger/writers/composite-writer
+ */
+import { BaseLogWriter } from "./base-writer.js";
+/**
+ * Composite Writer class that combines multiple writers.
+ *
+ * This is the primary writer used by the Logger class.
+ * It manages multiple output destinations (console, file, MCP)
+ * and ensures all enabled writers receive log entries.
+ *
+ * @example
+ * ```typescript
+ * const composite = new CompositeWriter();
+ * composite.addWriter('console', consoleWriter);
+ * composite.addWriter('file', fileWriter);
+ * composite.write('info', 'Hello world', 'server'); // Goes to both writers
+ * ```
+ */
+export class CompositeWriter extends BaseLogWriter {
+    writers = new Map();
+    /**
+     * Add a named writer to the composite.
+     *
+     * @param name - Unique name for the writer
+     * @param writer - The writer instance
+     */
+    addWriter(name, writer) {
+        this.writers.set(name, writer);
+    }
+    /**
+     * Remove a writer by name.
+     *
+     * @param name - The writer name to remove
+     * @returns true if a writer was removed
+     */
+    removeWriter(name) {
+        return this.writers.delete(name);
+    }
+    /**
+     * Get a writer by name.
+     *
+     * @param name - The writer name
+     * @returns The writer or undefined
+     */
+    getWriter(name) {
+        return this.writers.get(name);
+    }
+    /**
+     * Check if a writer exists.
+     *
+     * @param name - The writer name
+     * @returns true if the writer exists
+     */
+    hasWriter(name) {
+        return this.writers.has(name);
+    }
+    /**
+     * Write to all enabled writers.
+     *
+     * @param level - The log level
+     * @param message - The formatted log message
+     * @param component - The component that generated the log
+     */
+    write(level, message, component) {
+        if (!this.enabled)
+            return;
+        for (const writer of this.writers.values()) {
+            if (writer.isAvailable()) {
+                try {
+                    writer.write(level, message, component);
+                }
+                catch {
+                    // Individual writer failure must not break the pipeline.
+                    // Remaining writers continue to receive log output.
+                }
+            }
+        }
+    }
+    /**
+     * Close all writers.
+     *
+     * @returns Promise that resolves when all writers are closed
+     */
+    async close() {
+        const closePromises = Array.from(this.writers.values()).map((writer) => writer.close());
+        await Promise.allSettled(closePromises);
+        this.writers.clear();
+        await super.close();
+    }
+    /**
+     * Check if any writer is available.
+     */
+    isAvailable() {
+        if (!this.enabled)
+            return false;
+        for (const writer of this.writers.values()) {
+            if (writer.isAvailable())
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Get the number of registered writers.
+     */
+    getWriterCount() {
+        return this.writers.size;
+    }
+    /**
+     * Get all writer names.
+     */
+    getWriterNames() {
+        return Array.from(this.writers.keys());
+    }
+}
+//# sourceMappingURL=composite-writer.js.map

package/build/logger/writers/composite-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-writer.js","sourceRoot":"","sources":["../../../src/logger/writers/composite-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,eAAgB,SAAQ,aAAa;IACxC,OAAO,GAA2B,IAAI,GAAG,EAAE,CAAC;IAEpD;;;;;OAKG;IACH,SAAS,CAAC,IAAY,EAAE,MAAiB;QACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAe,EAAE,OAAe,EAAE,SAAiB;QACvD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAE1B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,IAAI,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;gBACzB,IAAI,CAAC;oBACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;gBAC1C,CAAC;gBAAC,MAAM,CAAC;oBACP,yDAAyD;oBACzD,oDAAoD;gBACtD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACxF,MAAM,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,WAAW;QACT,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAEhC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,IAAI,MAAM,CAAC,WAAW,EAAE;gBAAE,OAAO,IAAI,CAAC;QACxC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;CACF"}

package/build/logger/writers/console-writer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Console Log Writer Module
+ *
+ * Writes log entries to stdout/stderr based on transport mode and log level.
+ * In stdio mode, ALL logs go to stderr to avoid corrupting JSON-RPC on stdout.
+ * In HTTP mode, info/debug go to stdout, warn/error go to stderr.
+ *
+ * @module logger/writers/console-writer
+ */
+import type { LogLevel, TransportMode } from "../core/types.js";
+import { BaseLogWriter } from "./base-writer.js";
+/**
+ * Configuration for the console writer.
+ */
+export interface ConsoleWriterConfig {
+    /** Transport mode determines output stream routing */
+    transport: TransportMode;
+}
+/**
+ * Console Writer class for terminal output.
+ *
+ * Handles the complexity of MCP transport modes:
+ * - **stdio mode**: ALL output goes to stderr (stdout is reserved for JSON-RPC)
+ * - **http/https mode**: Standard behavior (info/debug → stdout, warn/error → stderr)
+ *
+ * @example
+ * ```typescript
+ * const writer = new ConsoleWriter({ transport: 'stdio' });
+ * writer.write('info', 'Hello world', 'server'); // Goes to stderr
+ * ```
+ */
+export declare class ConsoleWriter extends BaseLogWriter {
+    private transport;
+    /**
+     * Create a new ConsoleWriter.
+     * @param config - Writer configuration
+     */
+    constructor(config: ConsoleWriterConfig);
+    /**
+     * Write a log message to the appropriate console stream.
+     *
+     * @param level - The log level
+     * @param message - The formatted log message
+     * @param _component - The component (unused, but part of interface)
+     */
+    write(level: LogLevel, message: string, _component: string): void;
+    /**
+     * Update the transport mode.
+     * Useful when transport changes at runtime.
+     *
+     * @param transport - The new transport mode
+     */
+    setTransport(transport: TransportMode): void;
+    /**
+     * Get the current transport mode.
+     */
+    getTransport(): TransportMode;
+}
+//# sourceMappingURL=console-writer.d.ts.map

package/build/logger/writers/console-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-writer.d.ts","sourceRoot":"","sources":["../../../src/logger/writers/console-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAC9C,OAAO,CAAC,SAAS,CAAgB;IAEjC;;;OAGG;gBACS,MAAM,EAAE,mBAAmB;IAKvC;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAiBjE;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI;IAI5C;;OAEG;IACH,YAAY,IAAI,aAAa;CAG9B"}

package/build/logger/writers/console-writer.js

@@ -0,0 +1,73 @@
+/**
+ * Console Log Writer Module
+ *
+ * Writes log entries to stdout/stderr based on transport mode and log level.
+ * In stdio mode, ALL logs go to stderr to avoid corrupting JSON-RPC on stdout.
+ * In HTTP mode, info/debug go to stdout, warn/error go to stderr.
+ *
+ * @module logger/writers/console-writer
+ */
+import { BaseLogWriter } from "./base-writer.js";
+/**
+ * Console Writer class for terminal output.
+ *
+ * Handles the complexity of MCP transport modes:
+ * - **stdio mode**: ALL output goes to stderr (stdout is reserved for JSON-RPC)
+ * - **http/https mode**: Standard behavior (info/debug → stdout, warn/error → stderr)
+ *
+ * @example
+ * ```typescript
+ * const writer = new ConsoleWriter({ transport: 'stdio' });
+ * writer.write('info', 'Hello world', 'server'); // Goes to stderr
+ * ```
+ */
+export class ConsoleWriter extends BaseLogWriter {
+    transport;
+    /**
+     * Create a new ConsoleWriter.
+     * @param config - Writer configuration
+     */
+    constructor(config) {
+        super();
+        this.transport = config.transport;
+    }
+    /**
+     * Write a log message to the appropriate console stream.
+     *
+     * @param level - The log level
+     * @param message - The formatted log message
+     * @param _component - The component (unused, but part of interface)
+     */
+    write(level, message, _component) {
+        if (!this.enabled)
+            return;
+        // In stdio mode, MUST write to stderr to avoid corrupting JSON-RPC on stdout
+        if (this.transport === "stdio") {
+            process.stderr.write(message + "\n");
+            return;
+        }
+        // In HTTP/HTTPS mode, use standard console behavior
+        if (level === "error" || level === "warn") {
+            process.stderr.write(message + "\n");
+        }
+        else {
+            process.stdout.write(message + "\n");
+        }
+    }
+    /**
+     * Update the transport mode.
+     * Useful when transport changes at runtime.
+     *
+     * @param transport - The new transport mode
+     */
+    setTransport(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Get the current transport mode.
+     */
+    getTransport() {
+        return this.transport;
+    }
+}
+//# sourceMappingURL=console-writer.js.map

package/build/logger/writers/console-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-writer.js","sourceRoot":"","sources":["../../../src/logger/writers/console-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAUjD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,aAAc,SAAQ,aAAa;IACtC,SAAS,CAAgB;IAEjC;;;OAGG;IACH,YAAY,MAA2B;QACrC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACpC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAe,EAAE,OAAe,EAAE,UAAkB;QACxD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAE1B,6EAA6E;QAC7E,IAAI,IAAI,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;YAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;YACrC,OAAO;QACT,CAAC;QAED,oDAAoD;QACpD,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACvC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,SAAwB;QACnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}