mcp-ts-template 1.1.6

package/dist/utils/parsing/jsonParser.js

@@ -0,0 +1,79 @@
+import { parse as parsePartialJson, Allow as PartialJsonAllow } from 'partial-json';
+import { BaseErrorCode, McpError } from '../../types-global/errors.js';
+// Import utils from the main barrel file (logger, RequestContext from ../internal/*)
+import { logger } from '../index.js';
+/**
+ * Enum mirroring partial-json's Allow constants for specifying
+ * what types of partial JSON structures are permissible during parsing.
+ * Use bitwise OR to combine options (e.g., Allow.STR | Allow.OBJ).
+ */
+export const Allow = PartialJsonAllow;
+// Regex to find a <think> block at the start, capturing its content and the rest of the string
+const thinkBlockRegex = /^<think>([\s\S]*?)<\/think>\s*([\s\S]*)$/;
+/**
+ * Utility class for parsing potentially partial JSON strings.
+ * Wraps the 'partial-json' library to provide a consistent interface
+ * within the atlas-mcp-agent project.
+ * Handles optional <think>...</think> blocks at the beginning of the input.
+ */
+class JsonParser {
+    /**
+     * Parses a JSON string, potentially allowing for incomplete structures
+     * and handling optional <think> blocks at the start.
+     *
+     * @param jsonString The JSON string to parse.
+     * @param allowPartial A bitwise OR combination of 'Allow' constants specifying permissible partial types (defaults to Allow.ALL).
+     * @param context Optional RequestContext for error correlation and logging think blocks.
+     * @returns The parsed JavaScript value.
+     * @throws {McpError} Throws an McpError with BaseErrorCode.VALIDATION_ERROR if parsing fails due to malformed JSON.
+     */
+    parse(jsonString, allowPartial = Allow.ALL, context) {
+        let stringToParse = jsonString;
+        const match = jsonString.match(thinkBlockRegex);
+        if (match) {
+            const thinkContent = match[1].trim();
+            const restOfString = match[2];
+            if (thinkContent) {
+                logger.debug('LLM <think> block detected and logged.', { ...context, thinkContent });
+            }
+            else {
+                logger.debug('Empty LLM <think> block detected.', context);
+            }
+            stringToParse = restOfString; // Parse only the part after </think>
+        }
+        // Trim leading/trailing whitespace which might interfere with JSON parsing, especially if only JSON is left
+        stringToParse = stringToParse.trim();
+        if (!stringToParse) {
+            // If after removing think block and trimming, the string is empty, it's an error
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, 'JSON string is empty after removing <think> block.', context);
+        }
+        try {
+            // Ensure the string starts with '{' or '[' if we expect an object or array after stripping <think>
+            // This helps catch cases where only non-JSON text remains.
+            if (!stringToParse.startsWith('{') && !stringToParse.startsWith('[')) {
+                // Check if it might be a simple string value that partial-json could parse
+                // Allow simple strings only if specifically permitted or Allow.ALL is used
+                const allowsString = (allowPartial & Allow.STR) === Allow.STR;
+                if (!allowsString && !stringToParse.startsWith('"')) { // Allow quoted strings if Allow.STR is set
+                    throw new Error('Remaining content does not appear to be valid JSON object or array.');
+                }
+                // If it starts with a quote and strings are allowed, let parsePartialJson handle it
+            }
+            return parsePartialJson(stringToParse, allowPartial);
+        }
+        catch (error) {
+            // Wrap the original error in an McpError for consistent error handling
+            // Include the original error message for better debugging context.
+            logger.error('Failed to parse JSON content.', { ...context, error: error.message, contentAttempted: stringToParse });
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Failed to parse JSON: ${error.message}`, {
+                ...context,
+                originalContent: stringToParse,
+                rawError: error instanceof Error ? error.stack : String(error) // Include raw error info
+            });
+        }
+    }
+}
+/**
+ * Singleton instance of the JsonParser utility.
+ */
+export const jsonParser = new JsonParser();

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

@@ -0,0 +1,93 @@
+/**
+ * Interface for entity prefix configuration
+ */
+export interface EntityPrefixConfig {
+    [key: string]: string;
+}
+/**
+ * ID Generation Options
+ */
+export interface IdGenerationOptions {
+    length?: number;
+    separator?: string;
+    charset?: string;
+}
+/**
+ * Generic ID Generator class for creating and managing unique identifiers
+ */
+export declare class IdGenerator {
+    private static DEFAULT_CHARSET;
+    private static DEFAULT_SEPARATOR;
+    private static DEFAULT_LENGTH;
+    private entityPrefixes;
+    private prefixToEntityType;
+    /**
+     * Constructor that accepts entity prefix configuration
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    constructor(entityPrefixes?: EntityPrefixConfig);
+    /**
+     * Set or update entity prefixes and rebuild the reverse lookup
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    setEntityPrefixes(entityPrefixes: EntityPrefixConfig): void;
+    /**
+     * Get all registered entity prefixes
+     * @returns The entity prefix configuration
+     */
+    getEntityPrefixes(): EntityPrefixConfig;
+    /**
+     * Generates a cryptographically secure random alphanumeric string
+     * @param length The length of the random string to generate
+     * @param charset Optional custom character set
+     * @returns Random alphanumeric string
+     */
+    generateRandomString(length?: number, charset?: string): string;
+    /**
+     * Generates a unique ID with an optional prefix
+     * @param prefix Optional prefix to add to the ID
+     * @param options Optional generation options
+     * @returns A unique identifier string
+     */
+    generate(prefix?: string, options?: IdGenerationOptions): string;
+    /**
+     * Generates a custom ID for an entity with format PREFIX_XXXXXX
+     * @param entityType The type of entity to generate an ID for
+     * @param options Optional generation options
+     * @returns A unique identifier string (e.g., "PROJ_A6B3J0")
+     * @throws {McpError} If the entity type is not registered
+     */
+    generateForEntity(entityType: string, options?: IdGenerationOptions): string;
+    /**
+     * Validates if a given ID matches the expected format for an entity type
+     * @param id The ID to validate
+     * @param entityType The expected entity type
+     * @param options Optional validation options
+     * @returns boolean indicating if the ID is valid
+     */
+    isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
+    /**
+     * Strips the prefix from an ID
+     * @param id The ID to strip
+     * @param separator Optional custom separator
+     * @returns The ID without the prefix
+     */
+    stripPrefix(id: string, separator?: string): string;
+    /**
+     * Determines the entity type from an ID
+     * @param id The ID to get the entity type for
+     * @param separator Optional custom separator
+     * @returns The entity type
+     * @throws {McpError} If the ID format is invalid or entity type is unknown
+     */
+    getEntityType(id: string, separator?: string): string;
+    /**
+     * Normalizes an entity ID to ensure consistent uppercase format
+     * @param id The ID to normalize
+     * @param separator Optional custom separator
+     * @returns The normalized ID in uppercase format
+     */
+    normalize(id: string, separator?: string): string;
+}
+export declare const idGenerator: IdGenerator;
+export declare const generateUUID: () => string;

package/dist/utils/security/idGenerator.js

@@ -0,0 +1,147 @@
+import { randomBytes, randomUUID as cryptoRandomUUID } from 'crypto'; // Import cryptoRandomUUID
+import { BaseErrorCode, McpError } from '../../types-global/errors.js'; // Corrected path
+/**
+ * Generic ID Generator class for creating and managing unique identifiers
+ */
+export class IdGenerator {
+    /**
+     * Constructor that accepts entity prefix configuration
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    constructor(entityPrefixes = {}) {
+        // Entity prefixes
+        this.entityPrefixes = {};
+        // Reverse mapping for prefix to entity type lookup
+        this.prefixToEntityType = {};
+        this.setEntityPrefixes(entityPrefixes);
+    }
+    /**
+     * Set or update entity prefixes and rebuild the reverse lookup
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    setEntityPrefixes(entityPrefixes) {
+        this.entityPrefixes = { ...entityPrefixes };
+        // Rebuild reverse mapping
+        this.prefixToEntityType = Object.entries(this.entityPrefixes).reduce((acc, [type, prefix]) => {
+            acc[prefix] = type;
+            acc[prefix.toLowerCase()] = type;
+            return acc;
+        }, {});
+        // Removed logger call from setEntityPrefixes to prevent logging before initialization
+    }
+    /**
+     * Get all registered entity prefixes
+     * @returns The entity prefix configuration
+     */
+    getEntityPrefixes() {
+        return { ...this.entityPrefixes };
+    }
+    /**
+     * Generates a cryptographically secure random alphanumeric string
+     * @param length The length of the random string to generate
+     * @param charset Optional custom character set
+     * @returns Random alphanumeric string
+     */
+    generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
+        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 with an optional prefix
+     * @param prefix Optional prefix to add to the ID
+     * @param options Optional generation options
+     * @returns 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 custom ID for an entity with format PREFIX_XXXXXX
+     * @param entityType The type of entity to generate an ID for
+     * @param options Optional generation options
+     * @returns A unique identifier string (e.g., "PROJ_A6B3J0")
+     * @throws {McpError} If the entity type is not registered
+     */
+    generateForEntity(entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        if (!prefix) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type: ${entityType}`);
+        }
+        return this.generate(prefix, options);
+    }
+    /**
+     * Validates if a given ID matches the expected format for an entity type
+     * @param id The ID to validate
+     * @param entityType The expected entity type
+     * @param options Optional validation options
+     * @returns boolean indicating if the ID is valid
+     */
+    isValid(id, entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR } = options;
+        if (!prefix) {
+            return false;
+        }
+        const pattern = new RegExp(`^${prefix}${separator}[A-Z0-9]{${length}}$`);
+        return pattern.test(id);
+    }
+    /**
+     * Strips the prefix from an ID
+     * @param id The ID to strip
+     * @param separator Optional custom separator
+     * @returns The ID without the prefix
+     */
+    stripPrefix(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        return id.split(separator)[1] || id;
+    }
+    /**
+     * Determines the entity type from an ID
+     * @param id The ID to get the entity type for
+     * @param separator Optional custom separator
+     * @returns The entity type
+     * @throws {McpError} If the ID format is invalid or entity type is unknown
+     */
+    getEntityType(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        if (parts.length !== 2 || !parts[0]) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid ID format: ${id}. Expected format: PREFIX${separator}XXXXXX`);
+        }
+        const prefix = parts[0];
+        const entityType = this.prefixToEntityType[prefix];
+        if (!entityType) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type prefix: ${prefix}`);
+        }
+        return entityType;
+    }
+    /**
+     * Normalizes an entity ID to ensure consistent uppercase format
+     * @param id The ID to normalize
+     * @param separator Optional custom separator
+     * @returns The normalized ID in uppercase format
+     */
+    normalize(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const entityType = this.getEntityType(id, separator);
+        const idParts = id.split(separator);
+        return `${this.entityPrefixes[entityType]}${separator}${idParts[1].toUpperCase()}`;
+    }
+}
+// Default charset
+IdGenerator.DEFAULT_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+// Default separator
+IdGenerator.DEFAULT_SEPARATOR = '_';
+// Default random part length
+IdGenerator.DEFAULT_LENGTH = 6;
+// Create and export a default instance with an empty entity prefix configuration
+export const idGenerator = new IdGenerator();
+// For standalone use as a UUID generator
+export const generateUUID = () => {
+    return cryptoRandomUUID(); // Use imported 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,92 @@
+import { RequestContext } from '../index.js';
+/**
+ * Rate limiting configuration options
+ */
+export interface RateLimitConfig {
+    /** Time window in milliseconds */
+    windowMs: number;
+    /** Maximum number of requests allowed in the window */
+    maxRequests: number;
+    /** Custom error message template */
+    errorMessage?: string;
+    /** Whether to skip rate limiting in certain environments (e.g. development) */
+    skipInDevelopment?: boolean;
+    /** Custom key generator function */
+    keyGenerator?: (identifier: string, context?: RequestContext) => string;
+    /** How often to run cleanup of expired entries (in milliseconds) */
+    cleanupInterval?: number;
+}
+/**
+ * Individual rate limit entry
+ */
+export interface RateLimitEntry {
+    /** Current request count */
+    count: number;
+    /** When the window resets (timestamp) */
+    resetTime: number;
+}
+/**
+ * Generic rate limiter that can be used across the application
+ */
+export declare class RateLimiter {
+    private config;
+    /** Map storing rate limit data */
+    private limits;
+    /** Cleanup interval timer */
+    private cleanupTimer;
+    /** Default configuration */
+    private static DEFAULT_CONFIG;
+    /**
+     * Create a new rate limiter
+     * @param config Rate limiting configuration
+     */
+    constructor(config: RateLimitConfig);
+    /**
+     * Start the cleanup timer to periodically remove expired entries
+     */
+    private startCleanupTimer;
+    /**
+     * Clean up expired rate limit entries to prevent memory leaks
+     */
+    private cleanupExpiredEntries;
+    /**
+     * Update rate limiter configuration
+     * @param config New configuration options
+     */
+    configure(config: Partial<RateLimitConfig>): void;
+    /**
+     * Get current configuration
+     * @returns Current rate limit configuration
+     */
+    getConfig(): RateLimitConfig;
+    /**
+     * Reset all rate limits
+     */
+    reset(): void;
+    /**
+     * Check if a request exceeds the rate limit
+     * @param key Unique identifier for the request source
+     * @param context Optional request context
+     * @throws {McpError} If rate limit is exceeded
+     */
+    check(key: string, context?: RequestContext): void;
+    /**
+     * Get rate limit information for a key
+     * @param key The rate limit key
+     * @returns Current rate limit status or null if no record exists
+     */
+    getStatus(key: string): {
+        current: number;
+        limit: number;
+        remaining: number;
+        resetTime: number;
+    } | null;
+    /**
+     * Stop the cleanup timer when the limiter is no longer needed
+     */
+    dispose(): void;
+}
+/**
+ * Create and export a default rate limiter instance
+ */
+export declare const rateLimiter: RateLimiter;

package/dist/utils/security/rateLimiter.js

@@ -0,0 +1,171 @@
+import { BaseErrorCode, McpError } from '../../types-global/errors.js';
+// Import config and utils
+import { environment } from '../../config/index.js'; // Import environment from config
+import { logger } from '../index.js';
+/**
+ * Generic rate limiter that can be used across the application
+ */
+export class RateLimiter {
+    /**
+     * Create a new rate limiter
+     * @param config Rate limiting configuration
+     */
+    constructor(config) {
+        this.config = config;
+        /** Cleanup interval timer */
+        this.cleanupTimer = null;
+        this.config = { ...RateLimiter.DEFAULT_CONFIG, ...config };
+        this.limits = new Map();
+        this.startCleanupTimer();
+        // Removed logger call from constructor to prevent logging before initialization
+    }
+    /**
+     * Start the cleanup timer to periodically remove expired entries
+     */
+    startCleanupTimer() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+        const interval = this.config.cleanupInterval ?? RateLimiter.DEFAULT_CONFIG.cleanupInterval;
+        if (interval) {
+            this.cleanupTimer = setInterval(() => {
+                this.cleanupExpiredEntries();
+            }, interval);
+            // Ensure the timer doesn't prevent the process from exiting
+            if (this.cleanupTimer.unref) {
+                this.cleanupTimer.unref();
+            }
+        }
+    }
+    /**
+     * Clean up expired rate limit entries to prevent memory leaks
+     */
+    cleanupExpiredEntries() {
+        const now = Date.now();
+        let expiredCount = 0;
+        // Use a synchronized approach to avoid race conditions during cleanup
+        for (const [key, entry] of this.limits.entries()) {
+            if (now >= entry.resetTime) {
+                this.limits.delete(key);
+                expiredCount++;
+            }
+        }
+        if (expiredCount > 0) {
+            logger.debug(`Cleaned up ${expiredCount} expired rate limit entries`, {
+                totalRemaining: this.limits.size
+            });
+        }
+    }
+    /**
+     * Update rate limiter configuration
+     * @param config New configuration options
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+        // Restart cleanup timer if interval changed
+        if (config.cleanupInterval !== undefined) {
+            this.startCleanupTimer();
+        }
+    }
+    /**
+     * Get current configuration
+     * @returns Current rate limit configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Reset all rate limits
+     */
+    reset() {
+        this.limits.clear();
+        logger.debug('Rate limiter reset, all limits cleared');
+    }
+    /**
+     * Check if a request exceeds the rate limit
+     * @param key Unique identifier for the request source
+     * @param context Optional request context
+     * @throws {McpError} If rate limit is exceeded
+     */
+    check(key, context) {
+        // Skip in development if configured, using the validated environment from config
+        if (this.config.skipInDevelopment && environment === 'development') {
+            return;
+        }
+        // Generate key using custom generator if provided
+        const limitKey = this.config.keyGenerator
+            ? this.config.keyGenerator(key, context)
+            : key;
+        const now = Date.now();
+        // Accessing and updating the limit entry within a single function scope
+        // ensures atomicity in Node.js's single-threaded event loop for Map operations.
+        const limit = () => {
+            // Get current entry or create a new one if it doesn't exist or is expired
+            const entry = this.limits.get(limitKey);
+            // Create new entry or reset if expired
+            if (!entry || now >= entry.resetTime) {
+                const newEntry = {
+                    count: 1,
+                    resetTime: now + this.config.windowMs
+                };
+                this.limits.set(limitKey, newEntry);
+                return newEntry;
+            }
+            // Check if limit exceeded
+            if (entry.count >= this.config.maxRequests) {
+                const waitTime = Math.ceil((entry.resetTime - now) / 1000);
+                const errorMessage = this.config.errorMessage?.replace('{waitTime}', waitTime.toString()) ||
+                    `Rate limit exceeded. Please try again in ${waitTime} seconds.`;
+                throw new McpError(BaseErrorCode.RATE_LIMITED, errorMessage, { waitTime, key: limitKey });
+            }
+            // Increment counter and return updated entry
+            entry.count++;
+            return entry;
+        };
+        // Execute the rate limiting logic
+        limit();
+    }
+    /**
+     * Get rate limit information for a key
+     * @param key The rate limit key
+     * @returns Current rate limit status or null if no record exists
+     */
+    getStatus(key) {
+        const entry = this.limits.get(key);
+        if (!entry) {
+            return null;
+        }
+        return {
+            current: entry.count,
+            limit: this.config.maxRequests,
+            remaining: Math.max(0, this.config.maxRequests - entry.count),
+            resetTime: entry.resetTime
+        };
+    }
+    /**
+     * Stop the cleanup timer when the limiter is no longer needed
+     */
+    dispose() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        // Clear all entries
+        this.limits.clear();
+    }
+}
+/** Default configuration */
+RateLimiter.DEFAULT_CONFIG = {
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    maxRequests: 100, // 100 requests per window
+    errorMessage: 'Rate limit exceeded. Please try again in {waitTime} seconds.',
+    skipInDevelopment: false,
+    cleanupInterval: 5 * 60 * 1000 // 5 minutes
+};
+/**
+ * Create and export a default rate limiter instance
+ */
+export const rateLimiter = new RateLimiter({
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    maxRequests: 100 // 100 requests per window
+});