mcp-server-framework 1.0.0

package/build/utils/string-helpers.d.ts

@@ -0,0 +1,126 @@
+/**
+ * String Helpers
+ *
+ * Generic string manipulation utilities used across the framework.
+ *
+ * @module utils/string-helpers
+ */
+/**
+ * Split a comma-separated string into trimmed, non-empty segments.
+ *
+ * Used by Zod schema helpers and config file mappers to provide
+ * a single source of truth for CSV-style string parsing.
+ *
+ * @param value - Raw comma-separated string (e.g., `"a, b, c"`)
+ * @param options - Parsing options
+ * @param options.lowercase - Lowercase all segments (default: false)
+ * @returns Array of trimmed, non-empty strings
+ *
+ * @example
+ * ```typescript
+ * splitCommaSeparated('a, b, c');              // ['a', 'b', 'c']
+ * splitCommaSeparated('A, B', { lowercase: true }); // ['a', 'b']
+ * splitCommaSeparated('');                     // []
+ * splitCommaSeparated(' , , ');                // []
+ * ```
+ */
+export declare function splitCommaSeparated(value: string, options?: {
+    lowercase?: boolean;
+}): string[];
+/**
+ * Interpolation parameters type.
+ * Maps template variable names to their values.
+ */
+export type MessageParams = Record<string, string | number | boolean | undefined>;
+/**
+ * Interpolate a template string with parameters.
+ *
+ * Replaces `{variableName}` placeholders with values from the params object.
+ * Unmatched placeholders are preserved as-is.
+ *
+ * @param template - The template string with `{variable}` placeholders
+ * @param params - The parameters to interpolate
+ * @returns The interpolated string
+ *
+ * @example
+ * ```typescript
+ * interpolate("Hello {name}!", { name: "World" })
+ * // "Hello World!"
+ * ```
+ */
+export declare function interpolate(template: string, params: MessageParams): string;
+/**
+ * Truncate an ID string (session, request, trace) for display purposes.
+ *
+ * Keeps logs readable while providing enough uniqueness for debugging.
+ * Also avoids exposing full tokens in log output.
+ *
+ * @param id - The full ID string
+ * @param length - Number of characters to keep (default: 8)
+ * @returns Truncated ID
+ *
+ * @example
+ * ```typescript
+ * truncateId('a1b2c3d4-e5f6-7890-abcd-ef1234567890')
+ * // Returns: 'a1b2c3d4'
+ * ```
+ */
+export declare function truncateId(id: string, length?: number): string;
+/**
+ * Regex pattern for human-readable byte sizes.
+ *
+ * Matches formats like `"10mb"`, `"1.5gb"`, `"500kb"`, or plain byte
+ * counts like `"1048576"`. Case-insensitive, optional whitespace
+ * between number and unit.
+ *
+ * Shared with Zod schemas (`MCP_BODY_SIZE_LIMIT`, `LOG_MAX_FILE_SIZE`)
+ * to ensure consistent validation across env vars and config files.
+ *
+ * @example
+ * ```typescript
+ * BYTE_SIZE_REGEX.test('10mb');      // true
+ * BYTE_SIZE_REGEX.test('1.5 gb');    // true
+ * BYTE_SIZE_REGEX.test('1048576');   // true (plain bytes)
+ * BYTE_SIZE_REGEX.test('abc');       // false
+ * ```
+ */
+export declare const BYTE_SIZE_REGEX: RegExp;
+/**
+ * Parse a human-readable byte size string into a number of bytes.
+ *
+ * Accepts formats like `"10mb"`, `"1.5gb"`, `"500kb"`, or plain numeric
+ * strings like `"1048576"` (interpreted as bytes). Uses binary units
+ * (1 KB = 1024 bytes, 1 MB = 1048576 bytes, etc.).
+ *
+ * The supported units match the `MCP_BODY_SIZE_LIMIT` regex pattern
+ * used throughout the framework: `kb`, `mb`, `gb`, `tb`, `pb`.
+ *
+ * @param value - Human-readable size string (e.g. `"10mb"`, `"1048576"`)
+ * @returns Number of bytes (floored to integer)
+ * @throws {Error} If the format is invalid
+ *
+ * @example
+ * ```typescript
+ * parseByteSize('10mb');      // 10485760
+ * parseByteSize('500kb');     // 512000
+ * parseByteSize('1.5gb');     // 1610612736
+ * parseByteSize('1048576');   // 1048576 (plain bytes)
+ * ```
+ */
+export declare function parseByteSize(value: string): number;
+/**
+ * Check if a host string is a localhost/loopback address.
+ *
+ * @param host - The host string to check (e.g., 'localhost:3000', '192.168.1.1')
+ * @returns true if the host is a local loopback address
+ *
+ * @example
+ * ```typescript
+ * isLocalHost('localhost:3000');  // true
+ * isLocalHost('127.0.0.1');       // true
+ * isLocalHost('[::1]:8080');      // true
+ * isLocalHost('192.168.1.1');     // false
+ * ```
+ */
+export declare function isLocalHost(host: string): boolean;
+//# sourceMappingURL=string-helpers.d.ts.map

package/build/utils/string-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/string-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,EAAE,CAMlG;AAYD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;AAElF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAS3E;AASD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,SAA4B,GAAG,MAAM,CAEjF;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,QAAuC,CAAC;AAcpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBnD;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUjD"}

package/build/utils/string-helpers.js

@@ -0,0 +1,189 @@
+/**
+ * String Helpers
+ *
+ * Generic string manipulation utilities used across the framework.
+ *
+ * @module utils/string-helpers
+ */
+// ============================================================================
+// Comma-Separated Parsing
+// ============================================================================
+/**
+ * Split a comma-separated string into trimmed, non-empty segments.
+ *
+ * Used by Zod schema helpers and config file mappers to provide
+ * a single source of truth for CSV-style string parsing.
+ *
+ * @param value - Raw comma-separated string (e.g., `"a, b, c"`)
+ * @param options - Parsing options
+ * @param options.lowercase - Lowercase all segments (default: false)
+ * @returns Array of trimmed, non-empty strings
+ *
+ * @example
+ * ```typescript
+ * splitCommaSeparated('a, b, c');              // ['a', 'b', 'c']
+ * splitCommaSeparated('A, B', { lowercase: true }); // ['a', 'b']
+ * splitCommaSeparated('');                     // []
+ * splitCommaSeparated(' , , ');                // []
+ * ```
+ */
+export function splitCommaSeparated(value, options = {}) {
+    const items = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return options.lowercase ? items.map((s) => s.toLowerCase()) : items;
+}
+// ============================================================================
+// Template Interpolation
+// ============================================================================
+/**
+ * Cached regex for template interpolation.
+ * Pattern matches `{variableName}` placeholders.
+ */
+const INTERPOLATION_REGEX = /\{(\w+)\}/g;
+/**
+ * Interpolate a template string with parameters.
+ *
+ * Replaces `{variableName}` placeholders with values from the params object.
+ * Unmatched placeholders are preserved as-is.
+ *
+ * @param template - The template string with `{variable}` placeholders
+ * @param params - The parameters to interpolate
+ * @returns The interpolated string
+ *
+ * @example
+ * ```typescript
+ * interpolate("Hello {name}!", { name: "World" })
+ * // "Hello World!"
+ * ```
+ */
+export function interpolate(template, params) {
+    INTERPOLATION_REGEX.lastIndex = 0;
+    return template.replace(INTERPOLATION_REGEX, (match, key) => {
+        const value = params[key];
+        if (value === undefined) {
+            return match;
+        }
+        return String(value);
+    });
+}
+// ============================================================================
+// ID Truncation
+// ============================================================================
+/** Default display length for truncated IDs. */
+const DEFAULT_ID_DISPLAY_LENGTH = 8;
+/**
+ * Truncate an ID string (session, request, trace) for display purposes.
+ *
+ * Keeps logs readable while providing enough uniqueness for debugging.
+ * Also avoids exposing full tokens in log output.
+ *
+ * @param id - The full ID string
+ * @param length - Number of characters to keep (default: 8)
+ * @returns Truncated ID
+ *
+ * @example
+ * ```typescript
+ * truncateId('a1b2c3d4-e5f6-7890-abcd-ef1234567890')
+ * // Returns: 'a1b2c3d4'
+ * ```
+ */
+export function truncateId(id, length = DEFAULT_ID_DISPLAY_LENGTH) {
+    return id.substring(0, length);
+}
+// ============================================================================
+// Byte Size Parsing
+// ============================================================================
+/**
+ * Regex pattern for human-readable byte sizes.
+ *
+ * Matches formats like `"10mb"`, `"1.5gb"`, `"500kb"`, or plain byte
+ * counts like `"1048576"`. Case-insensitive, optional whitespace
+ * between number and unit.
+ *
+ * Shared with Zod schemas (`MCP_BODY_SIZE_LIMIT`, `LOG_MAX_FILE_SIZE`)
+ * to ensure consistent validation across env vars and config files.
+ *
+ * @example
+ * ```typescript
+ * BYTE_SIZE_REGEX.test('10mb');      // true
+ * BYTE_SIZE_REGEX.test('1.5 gb');    // true
+ * BYTE_SIZE_REGEX.test('1048576');   // true (plain bytes)
+ * BYTE_SIZE_REGEX.test('abc');       // false
+ * ```
+ */
+export const BYTE_SIZE_REGEX = /^\d+(\.\d+)?\s*(kb|mb|gb|tb|pb)?$/i;
+/**
+ * Binary unit multipliers (1 KB = 1024 bytes).
+ * @internal
+ */
+const BYTE_MULTIPLIERS = {
+    kb: 1024,
+    mb: 1024 ** 2,
+    gb: 1024 ** 3,
+    tb: 1024 ** 4,
+    pb: 1024 ** 5,
+};
+/**
+ * Parse a human-readable byte size string into a number of bytes.
+ *
+ * Accepts formats like `"10mb"`, `"1.5gb"`, `"500kb"`, or plain numeric
+ * strings like `"1048576"` (interpreted as bytes). Uses binary units
+ * (1 KB = 1024 bytes, 1 MB = 1048576 bytes, etc.).
+ *
+ * The supported units match the `MCP_BODY_SIZE_LIMIT` regex pattern
+ * used throughout the framework: `kb`, `mb`, `gb`, `tb`, `pb`.
+ *
+ * @param value - Human-readable size string (e.g. `"10mb"`, `"1048576"`)
+ * @returns Number of bytes (floored to integer)
+ * @throws {Error} If the format is invalid
+ *
+ * @example
+ * ```typescript
+ * parseByteSize('10mb');      // 10485760
+ * parseByteSize('500kb');     // 512000
+ * parseByteSize('1.5gb');     // 1610612736
+ * parseByteSize('1048576');   // 1048576 (plain bytes)
+ * ```
+ */
+export function parseByteSize(value) {
+    const trimmed = value.trim();
+    const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*(kb|mb|gb|tb|pb)?$/i);
+    if (!match) {
+        throw new Error(`Invalid byte size format: "${value}". Use formats like "10mb", "500kb", "2gb", or a plain byte count like "1048576".`);
+    }
+    const num = parseFloat(match[1]);
+    const unit = match[2]?.toLowerCase();
+    if (!unit) {
+        return Math.floor(num);
+    }
+    return Math.floor(num * (BYTE_MULTIPLIERS[unit] ?? 1));
+}
+// ============================================================================
+// Network Helpers
+// ============================================================================
+/**
+ * Check if a host string is a localhost/loopback address.
+ *
+ * @param host - The host string to check (e.g., 'localhost:3000', '192.168.1.1')
+ * @returns true if the host is a local loopback address
+ *
+ * @example
+ * ```typescript
+ * isLocalHost('localhost:3000');  // true
+ * isLocalHost('127.0.0.1');       // true
+ * isLocalHost('[::1]:8080');      // true
+ * isLocalHost('192.168.1.1');     // false
+ * ```
+ */
+export function isLocalHost(host) {
+    const cleanHost = host.trim().toLowerCase();
+    return (cleanHost.startsWith("localhost:") ||
+        cleanHost === "localhost" ||
+        cleanHost.startsWith("127.0.0.1:") ||
+        cleanHost === "127.0.0.1" ||
+        cleanHost.startsWith("[::1]:") ||
+        cleanHost === "[::1]");
+}
+//# sourceMappingURL=string-helpers.js.map

package/build/utils/string-helpers.js.map

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

package/build/utils/validation.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Definition Validation
+ *
+ * Runtime validation helpers for define*() factory functions.
+ * Catches misconfigurations early with clear, actionable error messages.
+ *
+ * These validations complement TypeScript's compile-time checks by catching:
+ * - Empty strings (valid `string` but invalid as identifiers)
+ * - Wrong types from JavaScript consumers or dynamic definitions
+ * - Missing required fields in loose object literals
+ *
+ * @internal Not exported from the public API.
+ * @module utils/validation
+ */
+/**
+ * Validate that a definition name is a non-empty string.
+ *
+ * @param name - The name value to validate
+ * @param type - Definition type for error context (e.g., 'Tool', 'Resource')
+ * @throws TypeError if name is not a non-empty string
+ */
+export declare function validateName(name: unknown, type: string): asserts name is string;
+/**
+ * Validate that a string field is non-empty.
+ *
+ * @param value - The value to validate
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value is not a non-empty string
+ */
+export declare function validateNonEmptyString(value: unknown, type: string, field: string): asserts value is string;
+/**
+ * Validate that a value is a function.
+ *
+ * @param value - The value to validate
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value is not a function
+ */
+export declare function validateFunction(value: unknown, type: string, field: string): asserts value is (...args: unknown[]) => unknown;
+/**
+ * Validate that a value is a Zod schema (duck-type check).
+ *
+ * Performs a minimal structural check for Zod-like objects by verifying
+ * the presence of `.parse()`. This is intentionally loose to support
+ * different Zod versions and custom schema wrappers.
+ *
+ * @param schema - The value to validate
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value doesn't look like a Zod schema
+ */
+export declare function validateZodSchema(schema: unknown, type: string, field: string): void;
+/**
+ * Validate that a value is a non-null object (not an array).
+ *
+ * @param value - The value to validate
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value is not a plain object
+ */
+export declare function validateObject(value: unknown, type: string, field: string): asserts value is Record<string, unknown>;
+/**
+ * Validate that a value is one of the allowed enum values.
+ *
+ * @param value - The value to validate
+ * @param allowed - Array of allowed string values
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value is not one of the allowed values
+ */
+export declare function validateEnum(value: unknown, allowed: readonly string[], type: string, field: string): asserts value is string;
+/**
+ * Validate common definition fields: name (non-empty string) and description (non-empty string).
+ * Shared across all define*() factory functions.
+ *
+ * @param definition - Object with name and description fields
+ * @param type - Definition type for error context (e.g., 'Tool', 'Resource')
+ */
+export declare function validateDefinitionBase(definition: {
+    name: unknown;
+    description: unknown;
+}, type: string): void;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAIhF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAI3G;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAIlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIpH;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,KAAK,IAAI,MAAM,CAMzB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAG9G"}

package/build/utils/validation.js

@@ -0,0 +1,111 @@
+/**
+ * Definition Validation
+ *
+ * Runtime validation helpers for define*() factory functions.
+ * Catches misconfigurations early with clear, actionable error messages.
+ *
+ * These validations complement TypeScript's compile-time checks by catching:
+ * - Empty strings (valid `string` but invalid as identifiers)
+ * - Wrong types from JavaScript consumers or dynamic definitions
+ * - Missing required fields in loose object literals
+ *
+ * @internal Not exported from the public API.
+ * @module utils/validation
+ */
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validate that a definition name is a non-empty string.
+ *
+ * @param name - The name value to validate
+ * @param type - Definition type for error context (e.g., 'Tool', 'Resource')
+ * @throws TypeError if name is not a non-empty string
+ */
+export function validateName(name, type) {
+    if (typeof name !== "string" || name.trim().length === 0) {
+        throw new TypeError(`${type} definition requires a non-empty 'name', received: ${String(name)}`);
+    }
+}
+/**
+ * Validate that a string field is non-empty.
+ *
+ * @param value - The value to validate
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value is not a non-empty string
+ */
+export function validateNonEmptyString(value, type, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${type} definition requires a non-empty '${field}', received: ${String(value)}`);
+    }
+}
+/**
+ * Validate that a value is a function.
+ *
+ * @param value - The value to validate
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value is not a function
+ */
+export function validateFunction(value, type, field) {
+    if (typeof value !== "function") {
+        throw new TypeError(`${type} definition requires '${field}' to be a function, received: ${typeof value}`);
+    }
+}
+/**
+ * Validate that a value is a Zod schema (duck-type check).
+ *
+ * Performs a minimal structural check for Zod-like objects by verifying
+ * the presence of `.parse()`. This is intentionally loose to support
+ * different Zod versions and custom schema wrappers.
+ *
+ * @param schema - The value to validate
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value doesn't look like a Zod schema
+ */
+export function validateZodSchema(schema, type, field) {
+    if (schema == null || typeof schema !== "object" || !("parse" in schema)) {
+        throw new TypeError(`${type} definition requires '${field}' to be a Zod schema (object with .parse()), received: ${typeof schema}`);
+    }
+}
+/**
+ * Validate that a value is a non-null object (not an array).
+ *
+ * @param value - The value to validate
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value is not a plain object
+ */
+export function validateObject(value, type, field) {
+    if (value == null || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`${type} definition requires '${field}' to be an object, received: ${typeof value}`);
+    }
+}
+/**
+ * Validate that a value is one of the allowed enum values.
+ *
+ * @param value - The value to validate
+ * @param allowed - Array of allowed string values
+ * @param type - Definition type for error context
+ * @param field - Field name for error context
+ * @throws TypeError if value is not one of the allowed values
+ */
+export function validateEnum(value, allowed, type, field) {
+    if (!allowed.includes(value)) {
+        throw new TypeError(`${type} definition requires '${field}' to be one of [${allowed.join(", ")}], received: '${String(value)}'`);
+    }
+}
+/**
+ * Validate common definition fields: name (non-empty string) and description (non-empty string).
+ * Shared across all define*() factory functions.
+ *
+ * @param definition - Object with name and description fields
+ * @param type - Definition type for error context (e.g., 'Tool', 'Resource')
+ */
+export function validateDefinitionBase(definition, type) {
+    validateName(definition.name, type);
+    validateNonEmptyString(definition.description, type, "description");
+}
+//# sourceMappingURL=validation.js.map

package/build/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,IAAY;IACtD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,sDAAsD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnG,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,IAAY,EAAE,KAAa;IAChF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,qCAAqC,KAAK,gBAAgB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxG,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAc,EACd,IAAY,EACZ,KAAa;IAEb,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,yBAAyB,KAAK,iCAAiC,OAAO,KAAK,EAAE,CAAC,CAAC;IAC5G,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe,EAAE,IAAY,EAAE,KAAa;IAC5E,IAAI,MAAM,IAAI,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,SAAS,CACjB,GAAG,IAAI,yBAAyB,KAAK,0DAA0D,OAAO,MAAM,EAAE,CAC/G,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,IAAY,EAAE,KAAa;IACxE,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,yBAAyB,KAAK,gCAAgC,OAAO,KAAK,EAAE,CAAC,CAAC;IAC3G,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,OAA0B,EAC1B,IAAY,EACZ,KAAa;IAEb,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAe,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,SAAS,CACjB,GAAG,IAAI,yBAAyB,KAAK,mBAAmB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,KAAK,CAAC,GAAG,CAC5G,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAmD,EAAE,IAAY;IACtG,YAAY,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACpC,sBAAsB,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;AACtE,CAAC"}

package/build/utils/zod-helpers.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Zod Schema Helpers
+ *
+ * Reusable Zod schema primitives for environment variable parsing.
+ * These helpers eliminate repetition in `env.ts` and ensure consistent
+ * coercion behavior for common patterns:
+ *
+ * - Boolean env vars (`"true"` / `"false"` strings)
+ * - Comma-separated lists (`"a,b,c"` → `string[]`)
+ *
+ * @module utils/zod-helpers
+ */
+import { z } from "zod";
+/**
+ * Zod schema for boolean environment variables.
+ *
+ * Accepts both native booleans (from config files) and string values
+ * from process.env. Only `"true"` (case-insensitive) maps to `true`,
+ * everything else maps to `false`.
+ *
+ * @param defaultValue - Default value when the env var is not set
+ * @returns Zod schema that outputs a `boolean`
+ *
+ * @example
+ * ```typescript
+ * // In env schema:
+ * OTEL_ENABLED: booleanFromEnv(false),
+ * MCP_LEGACY_SSE_ENABLED: booleanFromEnv(false),
+ * ```
+ */
+export declare function booleanFromEnv(defaultValue: boolean): z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodEffects<z.ZodString, boolean, string>]>>;
+/**
+ * Zod schema for comma-separated string list env vars.
+ *
+ * Splits on `,`, trims whitespace, removes empty segments.
+ * Optionally lowercases all values.
+ *
+ * Use for **required** list fields that always produce a `string[]`.
+ * For optional fields that should return `undefined` when empty,
+ * use {@link optionalCommaSeparatedList}.
+ *
+ * @param options - Configuration for list parsing
+ * @param options.lowercase - Lowercase all values (default: false)
+ * @returns Zod schema that outputs `string[]`
+ *
+ * @example
+ * ```typescript
+ * // In env schema:
+ * OTEL_METRICS_EXPORTER: commaSeparatedList({ lowercase: true }).default('otlp,prometheus'),
+ * ```
+ */
+export declare function commaSeparatedList(options?: {
+    lowercase?: boolean;
+}): z.ZodEffects<z.ZodString, string[], string>;
+/**
+ * Zod schema for optional comma-separated string list env vars.
+ *
+ * Like {@link commaSeparatedList}, but returns `undefined` when the
+ * input is empty or produces no items after trimming. The resulting
+ * field type is `string[] | undefined`.
+ *
+ * Use for optional list fields where absence has semantic meaning
+ * (e.g., "use defaults" for allowed origins/hosts).
+ *
+ * @returns Zod schema that outputs `string[] | undefined`
+ *
+ * @example
+ * ```typescript
+ * // In env schema:
+ * MCP_ALLOWED_ORIGINS: optionalCommaSeparatedList(),
+ * MCP_ALLOWED_HOSTS: optionalCommaSeparatedList(),
+ * ```
+ */
+export declare function optionalCommaSeparatedList(): z.ZodOptional<z.ZodEffects<z.ZodString, string[] | undefined, string>>;
+/**
+ * Zod schema for human-readable byte size environment variables.
+ *
+ * Accepts strings like `"10mb"`, `"500kb"`, `"1.5gb"`, or plain byte
+ * counts like `"1048576"`. Transforms the input to a `number` (bytes)
+ * via {@link parseByteSize}.
+ *
+ * @param defaultValue - Default value as human-readable string (e.g. `'10mb'`)
+ * @returns Zod schema that accepts `string` and outputs `number` (bytes)
+ *
+ * @example
+ * ```typescript
+ * // In env schema:
+ * LOG_MAX_FILE_SIZE: byteSizeSchema('10mb').pipe(z.number().int().min(1024)),
+ * ```
+ */
+export declare function byteSizeSchema(defaultValue: string): z.ZodDefault<z.ZodEffects<z.ZodString, number, string>>;
+//# sourceMappingURL=zod-helpers.d.ts.map

package/build/utils/zod-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/zod-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,OAAO,wFAKnD;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,+CAEvE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,2EAQzC;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,2DAKlD"}