@slbdn/mcp-tester 1.1.0 → 1.3.0

package/dist/utils/logger.js

@@ -1,8 +1,12 @@
 /**
  * Logging utilities for MCP client.
  *
- * Provides configurable logging with multiple output levels and formats.
+ * Provides configurable logging with multiple output levels, secret masking,
+ * request timing, and JSON pretty-printing for protocol debugging.
+ *
+ * All log output is automatically masked to prevent sensitive data leakage.
  */
+import { maskSecrets } from './masking.js';
 const LOG_LEVELS = {
     debug: 0,
     info: 1,
@@ -11,27 +15,117 @@ const LOG_LEVELS = {
     none: 99,
 };
 /**
- * Logger implementation that outputs to stderr.
+ * ANSI color codes for terminal output.
+ * Only used when output is a TTY.
+ */
+const COLORS = {
+    debug: '\x1b[36m', // cyan
+    info: '\x1b[32m', // green
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m', // red
+    dim: '\x1b[2m', // dim
+    reset: '\x1b[0m', // reset
+};
+/**
+ * Check if stderr is a TTY (terminal).
+ */
+function isTTY() {
+    return process.stderr?.isTTY ?? false;
+}
+/**
+ * Colorize a string for terminal output.
+ */
+function colorize(text, color, useColors) {
+    if (!useColors || !isTTY())
+        return text;
+    return `${color}${text}${COLORS.reset}`;
+}
+/**
+ * Format a timestamp for log messages.
+ */
+function formatTimestamp() {
+    const now = new Date();
+    const ms = String(now.getMilliseconds()).padStart(3, '0');
+    return `${now.toISOString().slice(11, 23)}.${ms}`;
+}
+/**
+ * Pretty-print a JSON-serializable value with indentation and masking.
+ */
+export function prettyPrint(value, shouldMask = true) {
+    if (value === null || value === undefined)
+        return String(value);
+    if (typeof value === 'string') {
+        return shouldMask ? maskSecrets(value) : value;
+    }
+    try {
+        const json = JSON.stringify(value, null, 2);
+        return shouldMask ? maskSecrets(json) : json;
+    }
+    catch {
+        const str = String(value);
+        return shouldMask ? maskSecrets(str) : str;
+    }
+}
+/**
+ * Start a timer and return a function that returns elapsed milliseconds.
  *
  * @example
  * ```typescript
- * const logger = new ConsoleLogger({ level: 'debug', prefix: 'MyApp' });
- * logger.info('Starting...'); // [MyApp] INFO: Starting...
+ * const elapsed = startTimer();
+ * await someOperation();
+ * logger.debug(`Operation completed in ${elapsed()}ms`);
+ * ```
+ */
+export function startTimer() {
+    const start = performance.now();
+    return () => Math.round(performance.now() - start);
+}
+/**
+ * Mask all arguments in an array by converting to strings and masking secrets.
+ */
+function maskArgs(args, shouldMask) {
+    if (!shouldMask)
+        return args;
+    return args.map((arg) => (typeof arg === 'string' ? maskSecrets(arg) : maskSecrets(String(arg))));
+}
+/**
+ * Logger implementation that outputs to stderr with automatic secret masking,
+ * timestamps, colors, and JSON pretty-printing.
+ *
+ * @example
+ * ```typescript
+ * const logger = new ConsoleLogger({ level: 'debug', prefix: 'MCPClient' });
+ * logger.info('Starting...'); // [MCPClient] INFO: Starting...
+ * logger.info('API key:', 'sk-abc123def456ghi789'); // [MCPClient] INFO: API key: sk-ab...789
  * ```
  */
 export class ConsoleLogger {
     level;
     prefix;
+    shouldMask;
+    useTimestamps;
+    useColors;
     constructor(options = {}) {
         this.level = LOG_LEVELS[options.level || 'info'];
         this.prefix = options.prefix || '';
+        this.shouldMask = options.maskSecrets !== false; // default true
+        this.useTimestamps = options.timestamps ?? false;
+        this.useColors = options.colors ?? true;
     }
     shouldLog(messageLevel) {
         return LOG_LEVELS[messageLevel] >= this.level;
     }
     format(level, args) {
         const prefix = this.prefix ? `[${this.prefix}] ` : '';
-        return [`${prefix}${level.toUpperCase()}:`, ...args];
+        const levelStr = level.toUpperCase();
+        const masked = maskArgs(args, this.shouldMask);
+        const parts = [];
+        if (this.useTimestamps) {
+            parts.push(colorize(`[${formatTimestamp()}]`, COLORS.dim, this.useColors));
+        }
+        parts.push(colorize(`${prefix}${levelStr}:`, COLORS[level] || COLORS.reset, this.useColors));
+        parts.push(...masked);
+        return parts.length > 1 ? parts : [`${prefix}${levelStr}:`, ...masked];
     }
     debug(...args) {
         if (this.shouldLog('debug')) {
@@ -70,9 +164,9 @@ export class ConsoleLogger {
  * ```
  */
 export class NoOpLogger {
-    debug() { }
-    info() { }
-    warn() { }
-    error() { }
+    debug(..._args) { }
+    info(..._args) { }
+    warn(..._args) { }
+    error(..._args) { }
 }
 //# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgDH,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,EAAE;CACT,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAChB,KAAK,CAAS;IACd,MAAM,CAAS;IAEvB,YAAY,UAAyB,EAAE;QACrC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IACrC,CAAC;IAEO,SAAS,CAAC,YAAsB;QACtC,OAAO,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC;IAChD,CAAC;IAEO,MAAM,CAAC,KAAe,EAAE,IAAe;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,GAAG,IAAe;QACtB,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,IAAe;QACrB,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,IAAe;QACrB,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,IAAe;QACtB,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,UAAU;IACrB,KAAK,KAAU,CAAC;IAChB,IAAI,KAAU,CAAC;IACf,IAAI,KAAU,CAAC;IACf,KAAK,KAAU,CAAC;CACjB"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAoD3C,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,EAAE;CACT,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,GAA2B;IACrC,KAAK,EAAE,UAAU,EAAE,OAAO;IAC1B,IAAI,EAAE,UAAU,EAAE,QAAQ;IAC1B,IAAI,EAAE,UAAU,EAAE,SAAS;IAC3B,KAAK,EAAE,UAAU,EAAE,MAAM;IACzB,GAAG,EAAE,SAAS,EAAE,MAAM;IACtB,KAAK,EAAE,SAAS,EAAE,QAAQ;CAC3B,CAAC;AAEF;;GAEG;AACH,SAAS,KAAK;IACZ,OAAO,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,KAAK,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,KAAa,EAAE,SAAkB;IAC/D,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,GAAG,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,SAAS,eAAe;IACtB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1D,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,aAAsB,IAAI;IACpE,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAChE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACjD,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5C,OAAO,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC7C,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAChC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,IAAe,EAAE,UAAmB;IACpD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACpG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,aAAa;IAChB,KAAK,CAAS;IACd,MAAM,CAAS;IACf,UAAU,CAAU;IACpB,aAAa,CAAU;IACvB,SAAS,CAAU;IAE3B,YAAY,UAAyB,EAAE;QACrC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC,eAAe;QAChE,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC;QACjD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IAC1C,CAAC;IAEO,SAAS,CAAC,YAAsB;QACtC,OAAO,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC;IAChD,CAAC;IAEO,MAAM,CAAC,KAAe,EAAE,IAAe;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QAE/C,MAAM,KAAK,GAAc,EAAE,CAAC;QAE5B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,eAAe,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAC7E,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,MAAM,GAAG,QAAQ,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAC7F,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QAEtB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,QAAQ,GAAG,EAAE,GAAG,MAAM,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,GAAG,IAAe;QACtB,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,IAAe;QACrB,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,IAAe;QACrB,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,IAAe;QACtB,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,UAAU;IACrB,KAAK,CAAC,GAAG,KAAgB,IAAS,CAAC;IACnC,IAAI,CAAC,GAAG,KAAgB,IAAS,CAAC;IAClC,IAAI,CAAC,GAAG,KAAgB,IAAS,CAAC;IAClC,KAAK,CAAC,GAAG,KAAgB,IAAS,CAAC;CACpC"}

package/dist/utils/masking.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Secret masking utility for preventing sensitive data from appearing in logs.
+ *
+ * Automatically detects and masks common secret patterns like API keys,
+ * tokens, passwords, and connection strings. Also masks values of known
+ * sensitive environment variable keys.
+ *
+ * @example
+ * ```typescript
+ * import { maskSecrets, addSecretPattern } from '@slbdn/mcp-tester';
+ *
+ * // Built-in patterns are applied automatically
+ * maskSecrets('API key: sk-abc123def456ghi789');
+ * // → 'API key: sk-ab...789'
+ *
+ * // Add custom patterns
+ * addSecretPattern(/my-secret-key-[a-zA-Z0-9]+/g, 'MyOrg API key');
+ * ```
+ */
+/**
+ * A secret masking pattern with a regex and human-readable name.
+ */
+export interface SecretPattern {
+    /** Regex pattern to match secrets. */
+    pattern: RegExp;
+    /** Human-readable name for the pattern (used in diagnostics). */
+    name: string;
+}
+/**
+ * Mask a string value, keeping the first few and last few characters visible
+ * and replacing the rest with `...`.
+ *
+ * @param value - The secret value to mask
+ * @param visibleChars - How many characters to keep visible at start and end
+ * @returns Masked string like "sk-ab...789"
+ */
+export declare function maskValue(value: string, visibleChars?: number): string;
+/**
+ * Mask secrets in a string by applying all active secret patterns
+ * and masking values of known sensitive environment variable keys.
+ *
+ * @param input - The value to mask (any type — converted to string)
+ * @returns String with secrets replaced by masked versions
+ */
+export declare function maskSecrets(input: unknown): string;
+/**
+ * Add a custom secret pattern to the masking rules.
+ *
+ * @param pattern - Regex pattern to match secrets
+ * @param name - Human-readable name for the pattern
+ */
+export declare function addSecretPattern(pattern: RegExp, name?: string): void;
+/**
+ * Reset all secret patterns to the built-in defaults.
+ * Removes any patterns added via `addSecretPattern()`.
+ */
+export declare function resetSecretPatterns(): void;
+/**
+ * Get the list of currently active secret patterns.
+ */
+export declare function getSecretPatterns(): SecretPattern[];
+/**
+ * Get the set of sensitive environment variable key names.
+ */
+export declare function getSensitiveEnvKeys(): ReadonlySet<string>;
+//# sourceMappingURL=masking.d.ts.map

package/dist/utils/masking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"masking.d.ts","sourceRoot":"","sources":["../../src/utils/masking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;CACd;AAuFD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,GAAE,MAAsB,GAAG,MAAM,CAOrF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA2BlD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAiB,GAAG,IAAI,CAE/E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CAEnD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,WAAW,CAAC,MAAM,CAAC,CAEzD"}

package/dist/utils/masking.js

@@ -0,0 +1,171 @@
+/**
+ * Secret masking utility for preventing sensitive data from appearing in logs.
+ *
+ * Automatically detects and masks common secret patterns like API keys,
+ * tokens, passwords, and connection strings. Also masks values of known
+ * sensitive environment variable keys.
+ *
+ * @example
+ * ```typescript
+ * import { maskSecrets, addSecretPattern } from '@slbdn/mcp-tester';
+ *
+ * // Built-in patterns are applied automatically
+ * maskSecrets('API key: sk-abc123def456ghi789');
+ * // → 'API key: sk-ab...789'
+ *
+ * // Add custom patterns
+ * addSecretPattern(/my-secret-key-[a-zA-Z0-9]+/g, 'MyOrg API key');
+ * ```
+ */
+/**
+ * Environment variable keys that commonly contain secrets.
+ * Values for these keys will be masked in log output.
+ */
+const SENSITIVE_ENV_KEYS = new Set([
+    'API_KEY',
+    'API_SECRET',
+    'SECRET_KEY',
+    'SECRET',
+    'PRIVATE_KEY',
+    'ACCESS_KEY',
+    'ACCESS_TOKEN',
+    'ACCESS_SECRET',
+    'AUTH_TOKEN',
+    'AUTHORIZATION',
+    'BEARER_TOKEN',
+    'TOKEN',
+    'REFRESH_TOKEN',
+    'SESSION_TOKEN',
+    'SESSION_ID',
+    'ID_TOKEN',
+    'PASSWORD',
+    'PASSWD',
+    'DB_PASSWORD',
+    'DATABASE_PASSWORD',
+    'REDIS_PASSWORD',
+    'MONGO_PASSWORD',
+    'DATABASE_URL',
+    'DB_URL',
+    'MONGODB_URI',
+    'POSTGRES_URL',
+    'MYSQL_URL',
+    'REDIS_URL',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'AZURE_CLIENT_SECRET',
+    'GCP_API_KEY',
+    'GOOGLE_API_KEY',
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'GITHUB_TOKEN',
+    'GITLAB_TOKEN',
+    'NPM_TOKEN',
+    'NPM_AUTH_TOKEN',
+    'SLACK_TOKEN',
+    'SLACK_WEBHOOK',
+    'SENTRY_DSN',
+    'ENCRYPTION_KEY',
+    'SIGNING_KEY',
+    'JWT_SECRET',
+    'CSRF_SECRET',
+    'APP_SECRET',
+]);
+const OPENAI_KEY_REGEX = /\bsk-(?:proj|ant)-[a-zA-Z0-9_-]{10,}/g;
+const SK_KEY_REGEX = /\bsk-[a-zA-Z0-9]{12,}/g;
+const AWS_KEY_REGEX = /\bAKIA[A-Z0-9]{16}\b/g;
+const BEARER_REGEX = /\bBearer\s+[a-zA-Z0-9._-]{8,}/gi;
+const JWT_REGEX = /\beyJ[a-zA-Z0-9_-]{10,}/g;
+const HEX_REGEX = /\b[a-f0-9]{40,}\b/g;
+const URL_CREDS_REGEX = /:[a-zA-Z0-9._-]{4,}@[a-zA-Z0-9.-]+/g;
+const KV_REGEX = /\b(?:password|passwd|secret|token|key|auth|credential)s?\s*[:=]\s*["']?[a-zA-Z0-9._/@+-]{8,}["']?/gi;
+/**
+ * Built-in secret patterns that are automatically masked.
+ */
+const DEFAULT_SECRET_PATTERNS = [
+    { pattern: OPENAI_KEY_REGEX, name: 'OpenAI/Anthropic API key' },
+    { pattern: SK_KEY_REGEX, name: 'API key (sk-)' },
+    { pattern: AWS_KEY_REGEX, name: 'AWS access key' },
+    { pattern: BEARER_REGEX, name: 'Bearer token' },
+    { pattern: JWT_REGEX, name: 'JWT token' },
+    { pattern: HEX_REGEX, name: 'Hex token' },
+    { pattern: URL_CREDS_REGEX, name: 'URL credentials' },
+    { pattern: KV_REGEX, name: 'Key-value secret' },
+];
+/** Active secret patterns (built-in + user-added). */
+let activePatterns = [...DEFAULT_SECRET_PATTERNS];
+/** Number of characters to keep visible at start/end when masking. */
+const VISIBLE_CHARS = 3;
+/**
+ * Mask a string value, keeping the first few and last few characters visible
+ * and replacing the rest with `...`.
+ *
+ * @param value - The secret value to mask
+ * @param visibleChars - How many characters to keep visible at start and end
+ * @returns Masked string like "sk-ab...789"
+ */
+export function maskValue(value, visibleChars = VISIBLE_CHARS) {
+    if (visibleChars <= 0 || value.length <= visibleChars * 2 + 3) {
+        return '***';
+    }
+    const start = value.slice(0, visibleChars);
+    const end = value.slice(-visibleChars);
+    return `${start}...${end}`;
+}
+/**
+ * Mask secrets in a string by applying all active secret patterns
+ * and masking values of known sensitive environment variable keys.
+ *
+ * @param input - The value to mask (any type — converted to string)
+ * @returns String with secrets replaced by masked versions
+ */
+export function maskSecrets(input) {
+    if (input === null || input === undefined) {
+        return String(input);
+    }
+    let result = String(input);
+    // 1. First mask values of known sensitive environment variable keys
+    //    Matches: KEY=value, KEY="value", KEY: value, KEY: "value"
+    result = result.replace(/\b([A-Z_][A-Z0-9_]{2,})(\s*[:=]\s*)(["']?)([^\s"']{4,})\3/g, (_match, key, separator, quote, _value) => {
+        if (SENSITIVE_ENV_KEYS.has(key.toUpperCase())) {
+            return `${key}${separator}${quote}***${quote}`;
+        }
+        return _match;
+    });
+    // 2. Then apply built-in and user-added secret patterns
+    for (const { pattern } of activePatterns) {
+        // Create fresh regex to avoid lastIndex issues from global flag
+        const regex = new RegExp(pattern.source, pattern.flags);
+        result = result.replace(regex, (match) => maskValue(match));
+    }
+    return result;
+}
+/**
+ * Add a custom secret pattern to the masking rules.
+ *
+ * @param pattern - Regex pattern to match secrets
+ * @param name - Human-readable name for the pattern
+ */
+export function addSecretPattern(pattern, name = 'custom') {
+    activePatterns.push({ pattern, name });
+}
+/**
+ * Reset all secret patterns to the built-in defaults.
+ * Removes any patterns added via `addSecretPattern()`.
+ */
+export function resetSecretPatterns() {
+    activePatterns = [...DEFAULT_SECRET_PATTERNS];
+}
+/**
+ * Get the list of currently active secret patterns.
+ */
+export function getSecretPatterns() {
+    return [...activePatterns];
+}
+/**
+ * Get the set of sensitive environment variable key names.
+ */
+export function getSensitiveEnvKeys() {
+    return SENSITIVE_ENV_KEYS;
+}
+//# sourceMappingURL=masking.js.map

package/dist/utils/masking.js.map

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

package/dist/utils/validation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Input validation utilities for MCPClient.
+ *
+ * Validates all user-facing inputs and throws descriptive `MCPClientError`
+ * with actionable messages when validation fails.
+ */
+/**
+ * Validate `start()` config — command is required and must be a non-empty string.
+ */
+export declare function validateServerConfig(config: unknown): asserts config is {
+    command: string;
+    args?: string[];
+    env?: Record<string, string | undefined>;
+    startupDelay?: number;
+};
+/**
+ * Validate `callTool()` options — tool name is required.
+ */
+export declare function validateToolCallOptions(options: unknown): asserts options is {
+    name: string;
+    arguments?: Record<string, unknown>;
+    timeout?: number;
+    retries?: number;
+};
+/**
+ * Validate a resource URI — must be a non-empty string.
+ */
+export declare function validateResourceUri(uri: unknown): asserts uri is string;
+/**
+ * Validate prompt name — must be a non-empty string.
+ */
+export declare function validatePromptName(name: unknown): asserts name is string;
+/**
+ * Validate prompt arguments — must be an object with string values if provided.
+ */
+export declare function validatePromptArgs(args: unknown): asserts args is Record<string, string>;
+/**
+ * Validate sampling request params.
+ */
+export declare function validateSamplingRequest(request: unknown): asserts request is {
+    messages: unknown[];
+    maxTokens: number;
+};
+/**
+ * Validate client constructor options.
+ */
+export declare function validateClientOptions(options: unknown): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAwGA;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAqFA;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,IAAI,MAAM,CAsBvE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAqBxE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsBxF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI;IAC5E,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CA+BA;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyG5D"}