@simonecoelhosfo/optimizely-mcp-server

/** * Configuration management system for Optimizely MCP Server * @description Handles loading and validation of configuration from environment variables, * config files, and default values with proper error handling and validation */ /** * Main configuration interface for the MCP server */ export interface MCPServerConfig { /** Optimizely API configuration */ optimizely: { /** Optimizely API token for authentication */ apiToken: string; /** * Project filtering configuration - CRITICAL for controlling data scope * If not specified, will fail to prevent accidental full sync */ projects: { /** * Specific project IDs to sync (recommended approach) * Example: ["12345", "67890"] */ allowedIds?: string[]; /** * Project name patterns to include (alternative to IDs) * Supports glob patterns like "staging-*", "prod-*" */ allowedNames?: string[]; /** * Maximum number of projects to sync (safety limit) * Default: 5, Max recommended: 20 */ maxProjects?: number; /** * Auto-discover mode: sync all accessible projects * WARNING: Only enable this for accounts with limited projects */ autoDiscoverAll?: boolean; }; /** Base URL for Optimizely API v2 endpoints */ baseUrl?: string; /** URL for feature flag configuration datafiles */ flagsUrl?: string; /** Rate limiting configuration */ rateLimits?: { /** Maximum requests per minute */ requestsPerMinute?: number; /** Maximum requests per second */ requestsPerSecond?: number; }; /** Retry configuration for failed requests */ retries?: { /** Maximum number of retry attempts */ maxAttempts?: number; /** Base delay between retries in milliseconds */ baseDelay?: number; }; }; /** Database and storage configuration */ storage: { /** SQLite database file path */ databasePath?: string; /** Directory for database backups */ backupDir?: string; /** Enable verbose SQL logging */ verbose?: boolean; }; /** Cache and synchronization settings */ cache: { /** Default sync interval in minutes */ syncIntervalMinutes?: number; /** Enable automatic background sync */ autoSync?: boolean; /** Maximum age of cached data in hours before refresh */ maxCacheAgeHours?: number; /** Change history sync configuration */ changeHistory?: { /** Number of days of change history to sync (default: 1) */ days?: number; /** Maximum number of change records to sync */ maxRecords?: number; /** Disable change history sync entirely */ disable?: boolean; }; }; /** MCP-safe logging configuration - CRITICAL for StdioServerTransport */ logging: { /** Log level (fatal, error, warn, info, debug, trace) */ level?: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'; /** * Enable console logging to stderr (safe for MCP debugging) * NEVER enables stdout logging which breaks StdioServerTransport */ consoleLogging?: boolean; /** * Log file path for Pino file-based logging * Defaults to ./logs/optimizely-mcp.log * Falls back to system temp directory if path fails */ logFile?: string; /** * Enable pretty printing for development * Only applies to console logging (stderr) */ prettyPrint?: boolean; /** Maximum log file size in bytes before rotation */ maxFileSize?: number; /** Number of rotated log files to keep */ maxFiles?: number; }; /** MCP server specific settings */ server: { /** Server name identifier */ name?: string; /** Server version */ version?: string; /** Maximum concurrent operations */ maxConcurrency?: number; }; /** MCP protocol specific configuration */ mcp: { /** * Transport type for MCP communication * 'stdio' is the standard for Claude Desktop integration */ transport?: 'stdio' | 'sse' | 'websocket'; /** * Maximum request timeout in milliseconds * Prevents hanging requests that could block the MCP protocol */ requestTimeoutMs?: number; /** * Enable MCP protocol debugging and detailed logging * Only affects MCP-specific operations, not business logic */ debugMode?: boolean; /** * Tool execution configuration */ tools?: { /** Maximum execution time for any single tool in milliseconds */ maxExecutionTimeMs?: number; /** Enable detailed input/output logging for tools */ logInputOutput?: boolean; /** Validate all tool responses against schemas */ validateResponses?: boolean; }; /** * Resource access configuration */ resources?: { /** Maximum size of resource content in bytes */ maxContentSize?: number; /** Enable caching of resource content */ enableCaching?: boolean; /** Resource cache TTL in seconds */ cacheTtlSeconds?: number; }; /** * Error handling configuration */ errors?: { /** Include stack traces in error responses (for debugging) */ includeStackTraces?: boolean; /** Include detailed error context in responses */ includeErrorContext?: boolean; /** Log all errors to the logging system */ logAllErrors?: boolean; }; }; } /** * Configuration validation error with detailed context */ export declare class ConfigValidationError extends Error { /** Field that failed validation */ field: string; /** Expected value format or type */ expected: string; /** Actual value that was provided */ actual: any; /** * Creates a new configuration validation error * @param field - The configuration field that failed validation * @param expected - Description of what was expected * @param actual - The actual value that was provided */ constructor(field: string, expected: string, actual: any); } /** * Configuration manager for loading and validating MCP server settings * @description Provides centralized configuration management with support for * environment variables, JSON config files, and runtime validation */ export declare class ConfigManager { private config; private configFilePath?; /** * Creates a new ConfigManager instance * @param configFilePath - Optional path to JSON configuration file */ constructor(configFilePath?: string); /** * Gets the default configuration with sensible defaults * @returns Default configuration object * @private */ private getDefaultConfig; /** * Loads configuration from all available sources in priority order * @returns Promise that resolves when configuration is loaded and validated * @throws {ConfigValidationError} When required configuration is missing or invalid * @description Sources (in priority order): Environment variables, config file, defaults */ loadConfig(): Promise<void>; /** * Loads configuration from a JSON file * @private * @throws {Error} When file cannot be read or contains invalid JSON */ private loadFromFile; /** * Loads configuration from environment variables * @private * @description Supports nested configuration via underscore-separated variable names */ private loadFromEnvironment; /** * Validates the loaded configuration for required fields and value constraints * @private * @throws {ConfigValidationError} When validation fails */ private validateConfig; /** * Validates if a string is a proper URL * @param urlString - The string to validate * @returns True if the string is a valid URL * @private */ private isValidUrl; /** * Deep merges two configuration objects * @param target - The target object to merge into * @param source - The source object to merge from * @returns The merged configuration object * @private */ private deepMerge; /** * Gets the current configuration * @returns The loaded and validated configuration */ getConfig(): MCPServerConfig; /** * Gets the Optimizely API configuration specifically * @returns Optimizely-specific configuration */ getOptimizelyConfig(): { /** Optimizely API token for authentication */ apiToken: string; /** * Project filtering configuration - CRITICAL for controlling data scope * If not specified, will fail to prevent accidental full sync */ projects: { /** * Specific project IDs to sync (recommended approach) * Example: ["12345", "67890"] */ allowedIds?: string[]; /** * Project name patterns to include (alternative to IDs) * Supports glob patterns like "staging-*", "prod-*" */ allowedNames?: string[]; /** * Maximum number of projects to sync (safety limit) * Default: 5, Max recommended: 20 */ maxProjects?: number; /** * Auto-discover mode: sync all accessible projects * WARNING: Only enable this for accounts with limited projects */ autoDiscoverAll?: boolean; }; /** Base URL for Optimizely API v2 endpoints */ baseUrl?: string; /** URL for feature flag configuration datafiles */ flagsUrl?: string; /** Rate limiting configuration */ rateLimits?: { /** Maximum requests per minute */ requestsPerMinute?: number; /** Maximum requests per second */ requestsPerSecond?: number; }; /** Retry configuration for failed requests */ retries?: { /** Maximum number of retry attempts */ maxAttempts?: number; /** Base delay between retries in milliseconds */ baseDelay?: number; }; }; /** * Gets the storage configuration specifically * @returns Storage-specific configuration */ getStorageConfig(): { /** SQLite database file path */ databasePath?: string; /** Directory for database backups */ backupDir?: string; /** Enable verbose SQL logging */ verbose?: boolean; }; /** * Gets the cache configuration specifically * @returns Cache-specific configuration */ getCacheConfig(): { /** Default sync interval in minutes */ syncIntervalMinutes?: number; /** Enable automatic background sync */ autoSync?: boolean; /** Maximum age of cached data in hours before refresh */ maxCacheAgeHours?: number; /** Change history sync configuration */ changeHistory?: { /** Number of days of change history to sync (default: 1) */ days?: number; /** Maximum number of change records to sync */ maxRecords?: number; /** Disable change history sync entirely */ disable?: boolean; }; }; /** * Gets the logging configuration specifically * @returns Logging-specific configuration */ getLoggingConfig(): { /** Log level (fatal, error, warn, info, debug, trace) */ level?: "fatal" | "error" | "warn" | "info" | "debug" | "trace"; /** * Enable console logging to stderr (safe for MCP debugging) * NEVER enables stdout logging which breaks StdioServerTransport */ consoleLogging?: boolean; /** * Log file path for Pino file-based logging * Defaults to ./logs/optimizely-mcp.log * Falls back to system temp directory if path fails */ logFile?: string; /** * Enable pretty printing for development * Only applies to console logging (stderr) */ prettyPrint?: boolean; /** Maximum log file size in bytes before rotation */ maxFileSize?: number; /** Number of rotated log files to keep */ maxFiles?: number; }; /** * Gets the server configuration specifically * @returns Server-specific configuration */ getServerConfig(): { /** Server name identifier */ name?: string; /** Server version */ version?: string; /** Maximum concurrent operations */ maxConcurrency?: number; }; /** * Gets the MCP protocol configuration specifically * @returns MCP-specific configuration */ getMcpConfig(): { /** * Transport type for MCP communication * 'stdio' is the standard for Claude Desktop integration */ transport?: "stdio" | "sse" | "websocket"; /** * Maximum request timeout in milliseconds * Prevents hanging requests that could block the MCP protocol */ requestTimeoutMs?: number; /** * Enable MCP protocol debugging and detailed logging * Only affects MCP-specific operations, not business logic */ debugMode?: boolean; /** * Tool execution configuration */ tools?: { /** Maximum execution time for any single tool in milliseconds */ maxExecutionTimeMs?: number; /** Enable detailed input/output logging for tools */ logInputOutput?: boolean; /** Validate all tool responses against schemas */ validateResponses?: boolean; }; /** * Resource access configuration */ resources?: { /** Maximum size of resource content in bytes */ maxContentSize?: number; /** Enable caching of resource content */ enableCaching?: boolean; /** Resource cache TTL in seconds */ cacheTtlSeconds?: number; }; /** * Error handling configuration */ errors?: { /** Include stack traces in error responses (for debugging) */ includeStackTraces?: boolean; /** Include detailed error context in responses */ includeErrorContext?: boolean; /** Log all errors to the logging system */ logAllErrors?: boolean; }; }; /** * Saves the current configuration to a JSON file * @param filePath - Path where to save the configuration * @param includeSecrets - Whether to include sensitive data like API tokens * @returns Promise that resolves when file is written */ saveConfigToFile(filePath: string, includeSecrets?: boolean): Promise<void>; /** * Creates a sample configuration file with documentation * @param filePath - Path where to create the sample file * @returns Promise that resolves when sample file is created */ createSampleConfig(filePath: string): Promise<void>; } /** * Gets the global configuration manager instance * @param configFilePath - Optional path to configuration file (used only on first call) * @returns The global ConfigManager instance * @description Implements singleton pattern for consistent configuration access */ export declare function getConfigManager(configFilePath?: string): ConfigManager; /** * Initializes the global configuration manager with environment-based config file detection * @returns Promise that resolves when configuration is loaded * @description Automatically detects config file from MCP_CONFIG_FILE environment variable */ export declare function initializeConfig(): Promise<ConfigManager>; //# sourceMappingURL=ConfigManager.d.ts.map