obsidian-mcp-server 1.5.8 → 2.0.2

package/dist/utils/parsing/jsonParser.js

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Provides a utility class for parsing potentially partial JSON strings,
+ * with support for handling and logging optional LLM <think> blocks.
+ * It wraps the 'partial-json' library.
+ * @module src/utils/parsing/jsonParser
+ */
+import { parse as parsePartialJson, Allow as PartialJsonAllow, } from "partial-json";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+import { logger, requestContextService, } from "../internal/index.js"; // Corrected import path for internal utils
+/**
+ * Enum mirroring `partial-json`'s `Allow` constants. These constants specify
+ * what types of partial JSON structures are permissible during parsing.
+ * They can be combined using bitwise OR (e.g., `Allow.STR | Allow.OBJ`).
+ *
+ * - `Allow.OBJ`: Allows partial objects (e.g., `{"key": "value",`)
+ * - `Allow.ARR`: Allows partial arrays (e.g., `[1, 2,`)
+ * - `Allow.STR`: Allows partial strings (e.g., `"abc`)
+ * - `Allow.NUM`: Allows partial numbers (e.g., `1.2e+`)
+ * - `Allow.BOOL`: Allows partial booleans (e.g., `tru`)
+ * - `Allow.NULL`: Allows partial nulls (e.g., `nul`)
+ * - `Allow.ALL`: Allows all types of partial JSON structures (default).
+ */
+export const Allow = PartialJsonAllow;
+// Regex to find a <think> block at the start of a string,
+// capturing its content and the rest of the string.
+const thinkBlockRegex = /^<think>([\s\S]*?)<\/think>\s*([\s\S]*)$/;
+/**
+ * Utility class for parsing JSON strings that may be partial or incomplete.
+ * It wraps the 'partial-json' library to provide a consistent parsing interface
+ * and includes logic to handle and log optional `<think>...</think>` blocks
+ * that might precede the JSON content (often found in LLM outputs).
+ */
+class JsonParser {
+    /**
+     * Parses a JSON string, which may be partial or prefixed with an LLM `<think>` block.
+     *
+     * @template T The expected type of the parsed JavaScript value. Defaults to `any`.
+     * @param {string} jsonString - The JSON string to parse.
+     * @param {number} [allowPartial=Allow.ALL] - A bitwise OR combination of `Allow` constants
+     *   specifying which types of partial JSON structures are permissible (e.g., `Allow.OBJ | Allow.ARR`).
+     *   Defaults to `Allow.ALL`, permitting any form of partial JSON.
+     * @param {RequestContext} [providedContext] - Optional `RequestContext` for logging,
+     *   especially for capturing `<think>` block content or parsing errors.
+     * @returns {T} The parsed JavaScript value.
+     * @throws {McpError} Throws an `McpError` with `BaseErrorCode.VALIDATION_ERROR` if:
+     *   - The string is empty after removing a `<think>` block.
+     *   - The remaining content does not appear to be a valid JSON structure (object, array, or permitted primitive).
+     *   - The `partial-json` library encounters a parsing error.
+     */
+    parse(jsonString, allowPartial = Allow.ALL, providedContext) {
+        const operation = "JsonParser.parse";
+        // Ensure opContext is always a valid RequestContext for internal logging
+        const opContext = providedContext ||
+            requestContextService.createRequestContext({ operation });
+        let stringToParse = jsonString;
+        let thinkContentExtracted;
+        const match = jsonString.match(thinkBlockRegex);
+        if (match) {
+            thinkContentExtracted = match[1].trim();
+            const restOfString = match[2];
+            if (thinkContentExtracted) {
+                logger.debug("LLM <think> block content extracted.", {
+                    ...opContext,
+                    operation,
+                    thinkContent: thinkContentExtracted,
+                });
+            }
+            else {
+                logger.debug("Empty LLM <think> block detected and removed.", {
+                    ...opContext,
+                    operation,
+                });
+            }
+            stringToParse = restOfString; // Continue parsing with the remainder of the string
+        }
+        stringToParse = stringToParse.trim(); // Trim whitespace from the string that will be parsed
+        if (!stringToParse) {
+            const errorMsg = "JSON string is empty after potential <think> block removal and trimming.";
+            logger.warning(errorMsg, {
+                ...opContext,
+                operation,
+                originalInput: jsonString,
+            });
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, errorMsg, {
+                ...opContext,
+                operation,
+            });
+        }
+        try {
+            // The pre-check for firstChar and specific primitive types has been removed.
+            // We now directly rely on parsePartialJson to validate the structure according
+            // to the 'allowPartial' flags. If parsePartialJson fails, it will throw an
+            // error which is caught below and wrapped in an McpError.
+            return parsePartialJson(stringToParse, allowPartial);
+        }
+        catch (error) {
+            const errorMessage = `Failed to parse JSON content: ${error.message}`;
+            logger.error(errorMessage, error, {
+                ...opContext, // Use the guaranteed valid opContext
+                operation,
+                contentAttempted: stringToParse,
+                thinkContentFound: thinkContentExtracted,
+            });
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, errorMessage, {
+                ...opContext, // Use the guaranteed valid opContext
+                operation,
+                originalContent: stringToParse,
+                thinkContentProcessed: !!thinkContentExtracted,
+                rawError: error instanceof Error
+                    ? { message: error.message, stack: error.stack }
+                    : String(error),
+            });
+        }
+    }
+}
+/**
+ * Singleton instance of the `JsonParser`.
+ * Use this instance for all partial JSON parsing needs.
+ *
+ * Example:
+ * ```typescript
+ * import { jsonParser, Allow, RequestContext } from './jsonParser';
+ * import { requestContextService } from '../internal'; // Assuming requestContextService is exported from internal utils
+ * const context: RequestContext = requestContextService.createRequestContext({ operation: 'MyOperation' });
+ * try {
+ *   const data = jsonParser.parse('<think>Thinking...</think>{"key": "value", "arr": [1,', Allow.ALL, context);
+ *   console.log(data); // Output: { key: "value", arr: [ 1 ] }
+ * } catch (e) {
+ *   console.error("Parsing failed:", e);
+ * }
+ * ```
+ */
+export const jsonParser = new JsonParser();

package/dist/utils/security/idGenerator.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Provides a generic ID generator class for creating unique,
+ * prefixed identifiers and standard UUIDs. It supports custom character sets,
+ * lengths, and separators for generated IDs.
+ * @module src/utils/security/idGenerator
+ */
+/**
+ * Defines the structure for configuring entity prefixes, mapping entity types (strings)
+ * to their corresponding ID prefixes (strings).
+ */
+export interface EntityPrefixConfig {
+    [key: string]: string;
+}
+/**
+ * Options for customizing ID generation.
+ */
+export interface IdGenerationOptions {
+    /** The length of the random part of the ID. Defaults to `IdGenerator.DEFAULT_LENGTH`. */
+    length?: number;
+    /** The separator string used between a prefix and the random part. Defaults to `IdGenerator.DEFAULT_SEPARATOR`. */
+    separator?: string;
+    /** The character set from which the random part of the ID is generated. Defaults to `IdGenerator.DEFAULT_CHARSET`. */
+    charset?: string;
+}
+/**
+ * A generic ID Generator class for creating and managing unique identifiers.
+ * It can generate IDs with entity-specific prefixes or standard UUIDs.
+ */
+export declare class IdGenerator {
+    /** Default character set for the random part of generated IDs (uppercase alphanumeric). */
+    private static DEFAULT_CHARSET;
+    /** Default separator used between a prefix and the random part of an ID. */
+    private static DEFAULT_SEPARATOR;
+    /** Default length for the random part of generated IDs. */
+    private static DEFAULT_LENGTH;
+    private entityPrefixes;
+    private prefixToEntityType;
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param {EntityPrefixConfig} [entityPrefixes={}] - An optional map of entity types
+     *   to their desired ID prefixes (e.g., `{ project: 'PROJ', task: 'TASK' }`).
+     */
+    constructor(entityPrefixes?: EntityPrefixConfig);
+    /**
+     * Sets or updates the entity prefix configuration and rebuilds the internal
+     * reverse lookup table (prefix to entity type).
+     * @param {EntityPrefixConfig} entityPrefixes - A map of entity types to their prefixes.
+     */
+    setEntityPrefixes(entityPrefixes: EntityPrefixConfig): void;
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns {EntityPrefixConfig} The current entity prefix configuration.
+     */
+    getEntityPrefixes(): EntityPrefixConfig;
+    /**
+     * Generates a cryptographically secure random string of a specified length
+     * from a given character set.
+     * @param {number} [length=IdGenerator.DEFAULT_LENGTH] - The desired length of the random string.
+     * @param {string} [charset=IdGenerator.DEFAULT_CHARSET] - The character set to use for generation.
+     * @returns {string} A random string.
+     */
+    generateRandomString(length?: number, charset?: string): string;
+    /**
+     * Generates a unique ID, optionally with a specified prefix.
+     * @param {string} [prefix] - An optional prefix for the ID.
+     * @param {IdGenerationOptions} [options={}] - Optional parameters for customizing
+     *   the length, separator, and charset of the random part of the ID.
+     * @returns {string} A unique identifier string.
+     */
+    generate(prefix?: string, options?: IdGenerationOptions): string;
+    /**
+     * Generates a unique ID for a specified entity type, using its configured prefix.
+     * The format is typically `PREFIX_RANDOMPART`.
+     * @param {string} entityType - The type of entity for which to generate an ID (must be registered
+     *   via `setEntityPrefixes` or constructor).
+     * @param {IdGenerationOptions} [options={}] - Optional parameters for customizing the ID generation.
+     * @returns {string} A unique identifier string for the entity (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the `entityType` is not registered (i.e., no prefix is configured for it).
+     */
+    generateForEntity(entityType: string, options?: IdGenerationOptions): string;
+    /**
+     * Validates if a given ID string matches the expected format for a specified entity type,
+     * including its prefix, separator, and random part characteristics.
+     * @param {string} id - The ID string to validate.
+     * @param {string} entityType - The expected entity type of the ID.
+     * @param {IdGenerationOptions} [options={}] - Optional parameters to specify the expected
+     *   length and separator if they differ from defaults for this validation.
+     * @returns {boolean} `true` if the ID is valid for the entity type, `false` otherwise.
+     */
+    isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
+    /**
+     * Strips the prefix from a prefixed ID string.
+     * @param {string} id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param {string} [separator=IdGenerator.DEFAULT_SEPARATOR] - The separator used in the ID.
+     * @returns {string} The part of the ID after the first separator, or the original ID if no separator is found.
+     */
+    stripPrefix(id: string, separator?: string): string;
+    /**
+     * Determines the entity type from a prefixed ID string.
+     * @param {string} id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param {string} [separator=IdGenerator.DEFAULT_SEPARATOR] - The separator used in the ID.
+     * @returns {string} The determined entity type.
+     * @throws {McpError} If the ID format is invalid or the prefix does not map to a known entity type.
+     */
+    getEntityType(id: string, separator?: string): string;
+    /**
+     * Normalizes an entity ID to ensure the prefix matches the configured case
+     * (if specific casing is important for the system) and the random part is uppercase.
+     * This implementation assumes prefixes are stored/used consistently and focuses on random part casing.
+     * @param {string} id - The ID to normalize.
+     * @param {string} [separator=IdGenerator.DEFAULT_SEPARATOR] - The separator used in the ID.
+     * @returns {string} The normalized ID string.
+     * @throws {McpError} If the entity type cannot be determined from the ID.
+     */
+    normalize(id: string, separator?: string): string;
+}
+/**
+ * A default, shared instance of the `IdGenerator`.
+ * This instance can be configured with entity prefixes at application startup
+ * or used directly for generating unprefixed random IDs or UUIDs.
+ *
+ * Example:
+ * ```typescript
+ * import { idGenerator, generateUUID } from './idGenerator';
+ *
+ * // Configure prefixes (optional, typically at app start)
+ * idGenerator.setEntityPrefixes({ user: 'USR', order: 'ORD' });
+ *
+ * const userId = idGenerator.generateForEntity('user'); // e.g., USR_X7V2L9
+ * const simpleId = idGenerator.generate(); // e.g., K3P8A1
+ * const standardUuid = generateUUID(); // e.g., '123e4567-e89b-12d3-a456-426614174000'
+ * ```
+ */
+export declare const idGenerator: IdGenerator;
+/**
+ * Generates a standard Version 4 UUID (Universally Unique Identifier).
+ * Uses the `crypto.randomUUID()` method for cryptographically strong randomness.
+ * @returns {string} A UUID string (e.g., "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx").
+ */
+export declare const generateUUID: () => string;

package/dist/utils/security/idGenerator.js

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview Provides a generic ID generator class for creating unique,
+ * prefixed identifiers and standard UUIDs. It supports custom character sets,
+ * lengths, and separators for generated IDs.
+ * @module src/utils/security/idGenerator
+ */
+import { randomBytes, randomUUID as cryptoRandomUUID } from "crypto";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+/**
+ * A generic ID Generator class for creating and managing unique identifiers.
+ * It can generate IDs with entity-specific prefixes or standard UUIDs.
+ */
+export class IdGenerator {
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param {EntityPrefixConfig} [entityPrefixes={}] - An optional map of entity types
+     *   to their desired ID prefixes (e.g., `{ project: 'PROJ', task: 'TASK' }`).
+     */
+    constructor(entityPrefixes = {}) {
+        this.entityPrefixes = {};
+        this.prefixToEntityType = {};
+        this.setEntityPrefixes(entityPrefixes);
+    }
+    /**
+     * Sets or updates the entity prefix configuration and rebuilds the internal
+     * reverse lookup table (prefix to entity type).
+     * @param {EntityPrefixConfig} entityPrefixes - A map of entity types to their prefixes.
+     */
+    setEntityPrefixes(entityPrefixes) {
+        this.entityPrefixes = { ...entityPrefixes }; // Create a copy
+        // Rebuild reverse mapping for efficient lookup (case-insensitive for prefix matching)
+        this.prefixToEntityType = Object.entries(this.entityPrefixes).reduce((acc, [type, prefix]) => {
+            acc[prefix.toUpperCase()] = type; // Store prefix in uppercase for consistent lookup
+            // Consider if lowercase or original case mapping is also needed based on expected input.
+            // For now, assuming prefixes are matched case-insensitively by uppercasing input prefix.
+            return acc;
+        }, {});
+    }
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns {EntityPrefixConfig} The current entity prefix configuration.
+     */
+    getEntityPrefixes() {
+        return { ...this.entityPrefixes };
+    }
+    /**
+     * Generates a cryptographically secure random string of a specified length
+     * from a given character set.
+     * @param {number} [length=IdGenerator.DEFAULT_LENGTH] - The desired length of the random string.
+     * @param {string} [charset=IdGenerator.DEFAULT_CHARSET] - The character set to use for generation.
+     * @returns {string} A random string.
+     */
+    generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
+        if (length <= 0) {
+            return "";
+        }
+        const bytes = randomBytes(length);
+        let result = "";
+        for (let i = 0; i < length; i++) {
+            result += charset[bytes[i] % charset.length];
+        }
+        return result;
+    }
+    /**
+     * Generates a unique ID, optionally with a specified prefix.
+     * @param {string} [prefix] - An optional prefix for the ID.
+     * @param {IdGenerationOptions} [options={}] - Optional parameters for customizing
+     *   the length, separator, and charset of the random part of the ID.
+     * @returns {string} A unique identifier string.
+     */
+    generate(prefix, options = {}) {
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, } = options;
+        const randomPart = this.generateRandomString(length, charset);
+        return prefix ? `${prefix}${separator}${randomPart}` : randomPart;
+    }
+    /**
+     * Generates a unique ID for a specified entity type, using its configured prefix.
+     * The format is typically `PREFIX_RANDOMPART`.
+     * @param {string} entityType - The type of entity for which to generate an ID (must be registered
+     *   via `setEntityPrefixes` or constructor).
+     * @param {IdGenerationOptions} [options={}] - Optional parameters for customizing the ID generation.
+     * @returns {string} A unique identifier string for the entity (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the `entityType` is not registered (i.e., no prefix is configured for it).
+     */
+    generateForEntity(entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        if (!prefix) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type: "${entityType}". No prefix configured.`);
+        }
+        return this.generate(prefix, options);
+    }
+    /**
+     * Validates if a given ID string matches the expected format for a specified entity type,
+     * including its prefix, separator, and random part characteristics.
+     * @param {string} id - The ID string to validate.
+     * @param {string} entityType - The expected entity type of the ID.
+     * @param {IdGenerationOptions} [options={}] - Optional parameters to specify the expected
+     *   length and separator if they differ from defaults for this validation.
+     * @returns {boolean} `true` if the ID is valid for the entity type, `false` otherwise.
+     */
+    isValid(id, entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        if (!prefix) {
+            return false; // Cannot validate if entity type or prefix is unknown
+        }
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR,
+        // charset is not used for regex validation but for generation
+         } = options;
+        // Regex assumes default charset (A-Z, 0-9). If charset is customizable for validation,
+        // the regex would need to be dynamically built or options.charset used.
+        // For now, it matches the default generation charset.
+        const pattern = new RegExp(`^${prefix}${separator}[A-Z0-9]{${length}}$`);
+        return pattern.test(id);
+    }
+    /**
+     * Strips the prefix from a prefixed ID string.
+     * @param {string} id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param {string} [separator=IdGenerator.DEFAULT_SEPARATOR] - The separator used in the ID.
+     * @returns {string} The part of the ID after the first separator, or the original ID if no separator is found.
+     */
+    stripPrefix(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        return parts.length > 1 ? parts.slice(1).join(separator) : id; // Handle cases with multiple separators in random part
+    }
+    /**
+     * Determines the entity type from a prefixed ID string.
+     * @param {string} id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param {string} [separator=IdGenerator.DEFAULT_SEPARATOR] - The separator used in the ID.
+     * @returns {string} The determined entity type.
+     * @throws {McpError} If the ID format is invalid or the prefix does not map to a known entity type.
+     */
+    getEntityType(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        if (parts.length < 2 || !parts[0]) {
+            // Need at least a prefix and a random part
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid ID format: "${id}". Expected format like "PREFIX${separator}RANDOMPART".`);
+        }
+        const inputPrefix = parts[0].toUpperCase(); // Match prefix case-insensitively
+        const entityType = this.prefixToEntityType[inputPrefix];
+        if (!entityType) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type for prefix: "${parts[0]}" in ID "${id}".`);
+        }
+        return entityType;
+    }
+    /**
+     * Normalizes an entity ID to ensure the prefix matches the configured case
+     * (if specific casing is important for the system) and the random part is uppercase.
+     * This implementation assumes prefixes are stored/used consistently and focuses on random part casing.
+     * @param {string} id - The ID to normalize.
+     * @param {string} [separator=IdGenerator.DEFAULT_SEPARATOR] - The separator used in the ID.
+     * @returns {string} The normalized ID string.
+     * @throws {McpError} If the entity type cannot be determined from the ID.
+     */
+    normalize(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        // This will throw if entity type is not found or ID format is wrong
+        const entityType = this.getEntityType(id, separator);
+        const configuredPrefix = this.entityPrefixes[entityType]; // Get the canonical prefix
+        const parts = id.split(separator);
+        const randomPart = parts.slice(1).join(separator); // Re-join if separator was in random part
+        return `${configuredPrefix}${separator}${randomPart.toUpperCase()}`;
+    }
+}
+/** Default character set for the random part of generated IDs (uppercase alphanumeric). */
+IdGenerator.DEFAULT_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+/** Default separator used between a prefix and the random part of an ID. */
+IdGenerator.DEFAULT_SEPARATOR = "_";
+/** Default length for the random part of generated IDs. */
+IdGenerator.DEFAULT_LENGTH = 6;
+/**
+ * A default, shared instance of the `IdGenerator`.
+ * This instance can be configured with entity prefixes at application startup
+ * or used directly for generating unprefixed random IDs or UUIDs.
+ *
+ * Example:
+ * ```typescript
+ * import { idGenerator, generateUUID } from './idGenerator';
+ *
+ * // Configure prefixes (optional, typically at app start)
+ * idGenerator.setEntityPrefixes({ user: 'USR', order: 'ORD' });
+ *
+ * const userId = idGenerator.generateForEntity('user'); // e.g., USR_X7V2L9
+ * const simpleId = idGenerator.generate(); // e.g., K3P8A1
+ * const standardUuid = generateUUID(); // e.g., '123e4567-e89b-12d3-a456-426614174000'
+ * ```
+ */
+export const idGenerator = new IdGenerator();
+/**
+ * Generates a standard Version 4 UUID (Universally Unique Identifier).
+ * Uses the `crypto.randomUUID()` method for cryptographically strong randomness.
+ * @returns {string} A UUID string (e.g., "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx").
+ */
+export const generateUUID = () => {
+    return cryptoRandomUUID();
+};

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

@@ -0,0 +1,3 @@
+export * from "./sanitization.js";
+export * from "./rateLimiter.js";
+export * from "./idGenerator.js";

package/dist/utils/security/index.js

@@ -0,0 +1,3 @@
+export * from "./sanitization.js";
+export * from "./rateLimiter.js";
+export * from "./idGenerator.js";

package/dist/utils/security/rateLimiter.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Provides a generic rate limiter class to manage request rates
+ * based on configurable time windows and request counts. It supports custom
+ * key generation, periodic cleanup of expired entries, and skipping rate
+ * limiting in development environments.
+ * @module src/utils/security/rateLimiter
+ */
+import { RequestContext } from "../internal/index.js";
+/**
+ * Configuration options for the {@link RateLimiter}.
+ */
+export interface RateLimitConfig {
+    /** Time window in milliseconds during which requests are counted. */
+    windowMs: number;
+    /** Maximum number of requests allowed from a single key within the `windowMs`. */
+    maxRequests: number;
+    /**
+     * Custom error message template when rate limit is exceeded.
+     * Use `{waitTime}` as a placeholder for the remaining seconds until reset.
+     * Defaults to "Rate limit exceeded. Please try again in {waitTime} seconds."
+     */
+    errorMessage?: string;
+    /**
+     * If `true`, rate limiting checks will be skipped if `process.env.NODE_ENV` is 'development'.
+     * Defaults to `false`.
+     */
+    skipInDevelopment?: boolean;
+    /**
+     * An optional function to generate a unique key for rate limiting based on an identifier
+     * and optional request context. If not provided, the raw identifier is used as the key.
+     * @param identifier - The base identifier (e.g., IP address, user ID).
+     * @param context - Optional request context.
+     * @returns A string to be used as the rate limiting key.
+     */
+    keyGenerator?: (identifier: string, context?: RequestContext) => string;
+    /**
+     * Interval in milliseconds for cleaning up expired rate limit entries from memory.
+     * Defaults to 5 minutes. Set to `0` or `null` to disable automatic cleanup.
+     */
+    cleanupInterval?: number | null;
+}
+/**
+ * Represents an individual entry in the rate limiter's tracking store.
+ * @internal
+ */
+export interface RateLimitEntry {
+    /** The current count of requests within the window. */
+    count: number;
+    /** The timestamp (milliseconds since epoch) when the current window resets. */
+    resetTime: number;
+}
+/**
+ * A generic rate limiter class that can be used to control the frequency of
+ * operations or requests from various sources. It stores request counts in memory.
+ */
+export declare class RateLimiter {
+    private limits;
+    private cleanupTimer;
+    private currentConfig;
+    /**
+     * Default configuration values for the rate limiter.
+     */
+    private static DEFAULT_CONFIG;
+    /**
+     * Creates a new `RateLimiter` instance.
+     * @param {Partial<RateLimitConfig>} [initialConfig={}] - Optional initial configuration
+     *   to override default settings.
+     */
+    constructor(initialConfig?: Partial<RateLimitConfig>);
+    /**
+     * Starts the periodic cleanup timer for expired rate limit entries.
+     * If a timer already exists, it's cleared and restarted.
+     * @private
+     */
+    private startCleanupTimer;
+    /**
+     * Removes expired entries from the rate limit store to free up memory.
+     * This method is called periodically by the cleanup timer.
+     * @private
+     */
+    private cleanupExpiredEntries;
+    /**
+     * Updates the rate limiter's configuration.
+     * @param {Partial<RateLimitConfig>} newConfig - Partial configuration object
+     *   with new settings to apply.
+     */
+    configure(newConfig: Partial<RateLimitConfig>): void;
+    /**
+     * Retrieves a copy of the current rate limiter configuration.
+     * @returns {RateLimitConfig} The current configuration.
+     */
+    getConfig(): RateLimitConfig;
+    /**
+     * Resets all rate limits, clearing all tracked keys and their counts.
+     * @param {RequestContext} [context] - Optional context for logging the reset operation.
+     */
+    reset(context?: RequestContext): void;
+    /**
+     * Checks if a request identified by a key exceeds the configured rate limit.
+     * If the limit is exceeded, an `McpError` is thrown.
+     *
+     * @param {string} identifier - A unique string identifying the source of the request
+     *   (e.g., IP address, user ID, session ID).
+     * @param {RequestContext} [context] - Optional request context for logging and potentially
+     *   for use by a custom `keyGenerator`.
+     * @throws {McpError} If the rate limit is exceeded for the given key.
+     *   The error will have `BaseErrorCode.RATE_LIMITED`.
+     */
+    check(identifier: string, context?: RequestContext): void;
+    /**
+     * Retrieves the current rate limit status for a given key.
+     * @param {string} key - The rate limit key (as generated by `keyGenerator` or the raw identifier).
+     * @returns {{ current: number; limit: number; remaining: number; resetTime: number } | null}
+     *   An object with current status, or `null` if the key is not currently tracked (or has expired).
+     *   `resetTime` is a Unix timestamp (milliseconds).
+     */
+    getStatus(key: string): {
+        current: number;
+        limit: number;
+        remaining: number;
+        resetTime: number;
+    } | null;
+    /**
+     * Stops the cleanup timer and clears all rate limit entries.
+     * This should be called if the rate limiter instance is no longer needed,
+     * to prevent resource leaks (though `unref` on the timer helps).
+     * @param {RequestContext} [context] - Optional context for logging the disposal.
+     */
+    dispose(context?: RequestContext): void;
+}
+/**
+ * A default, shared instance of the `RateLimiter`.
+ * This instance is configured with default settings (e.g., 100 requests per 15 minutes).
+ * It can be reconfigured using `rateLimiter.configure()`.
+ *
+ * Example:
+ * ```typescript
+ * import { rateLimiter, RequestContext } from './rateLimiter';
+ * import { requestContextService } from '../internal';
+ *
+ * const context: RequestContext = requestContextService.createRequestContext({ operation: 'MyApiCall' });
+ * const userIp = '123.45.67.89';
+ *
+ * try {
+ *   rateLimiter.check(userIp, context);
+ *   // Proceed with operation
+ * } catch (e) {
+ *   if (e instanceof McpError && e.code === BaseErrorCode.RATE_LIMITED) {
+ *     console.error("Rate limit hit:", e.message);
+ *   } else {
+ *     // Handle other errors
+ *   }
+ * }
+ * ```
+ */
+export declare const rateLimiter: RateLimiter;