@simonecoelhosfo/optimizely-mcp-server/dist/errors/MCPErrorMapping.d.ts

Optimizely MCP Server for AI assistants with integrated CLI tools

/**
 * MCP Error Mapping Utilities
 * @description Provides standardized error mapping from business logic errors
 * to MCP-compliant error types with appropriate error codes and messaging
 *
 * This module ensures consistent error handling across the entire codebase
 * while maintaining MCP protocol compliance and providing clear error context
 * for debugging and client error handling.
 *
 * @author Optimizely MCP Server
 * @version 1.0.0
 */
import { McpError } from '@modelcontextprotocol/sdk/types.js';
import { type ErrorEnhancementContext, type PrescriptiveErrorResponse } from './AutomatedPrescriptiveErrorEnhancer.js';
import { HardStopError } from './HardStopError.js';
/**
 * Error context interface for providing additional error information
 */
export interface ErrorContext {
    /** Operation or method that failed */
    operation?: string;
    /** Tool name if error occurred during tool execution */
    toolName?: string;
    /** Resource URI if error occurred during resource access */
    resourceUri?: string;
    /** Additional context data */
    metadata?: Record<string, any>;
    /** Hard stop response if this is a hard stop error */
    hardStop?: any;
}
/**
 * MCP Error Categories for internal classification
 */
export declare enum MCPErrorCategory {
    /** Invalid input parameters or validation failures */
    VALIDATION = "validation",
    /** Authentication or authorization failures */
    AUTHENTICATION = "authentication",
    /** Resource not found or access denied */
    NOT_FOUND = "not_found",
    /** Rate limiting or quota exceeded */
    RATE_LIMIT = "rate_limit",
    /** External service or network failures */
    EXTERNAL_SERVICE = "external_service",
    /** Database or storage failures */
    STORAGE = "storage",
    /** Configuration or setup issues */
    CONFIGURATION = "configuration",
    /** Unexpected internal errors */
    INTERNAL = "internal"
}
/**
 * MCP Error Mapper class for converting various error types to MCP errors
 * @description Provides centralized error handling and mapping logic
 */
export declare class MCPErrorMapper {
    /**
     * Creates a hard stop error for unrecoverable scenarios
     * @param code - Error type code
     * @param reason - Specific reason for the error
     * @param message - User-friendly error message
     * @param httpStatus - HTTP status code (default 409)
     * @returns HardStopError instance
     */
    static createHardStopError(code: string, reason: string, message: string, httpStatus?: number): HardStopError;
    /**
     * Detects if an error should trigger a hard stop
     * @param error - The error to analyze
     * @param context - Error context
     * @returns True if error requires hard stop
     */
    static shouldHardStop(error: any, context?: ErrorContext): boolean;
    /**
     * Converts any error to appropriate MCP error type with context
     * @param error - The original error to convert
     * @param context - Additional context information
     * @returns MCP-compliant error with appropriate error code
     */
    static toMCPError(error: any, context?: string | ErrorContext): McpError;
    /**
     * Maps Optimizely API errors to appropriate MCP error codes
     * @param error - OptimizelyAPIError instance
     * @param context - Error context
     * @returns Mapped MCP error
     * @private
     */
    private static mapOptimizelyAPIError;
    /**
     * Maps configuration validation errors to MCP errors
     * @param error - ConfigValidationError instance
     * @param context - Error context
     * @returns Mapped MCP error
     * @private
     */
    private static mapConfigValidationError;
    /**
     * Check if an error message indicates a validation error
     * @param message - Error message to check
     * @returns True if this appears to be a validation error
     * @private
     */
    private static isValidationError;
    /**
     * Creates a standardized MCP error with enhanced context
     * @param code - MCP error code
     * @param message - Error message
     * @param context - Error context
     * @param category - Error category for internal classification
     * @returns Created MCP error
     * @private
     */
    private static createMCPError;
    /**
     * Enhances an existing MCP error with additional context
     * @param error - Existing MCP error
     * @param context - Additional context to add
     * @returns Enhanced MCP error
     * @private
     */
    private static enhanceMCPError;
    private static isAuthenticationError;
    private static isNotFoundError;
    private static isRateLimitError;
    private static isStorageError;
}
/**
 * Convenience functions for common error creation patterns
 */
export declare class MCPErrorUtils {
    /**
     * Creates a validation error for invalid tool parameters
     * @param toolName - Name of the tool
     * @param message - Validation error message
     * @param field - Field that failed validation
     * @returns MCP error for invalid parameters
     */
    static invalidToolParameter(toolName: string, message: string, field?: string): McpError;
    /**
     * Creates an error for unknown tools
     * @param toolName - Name of the unknown tool
     * @returns MCP error for unknown method
     */
    static unknownTool(toolName: string): McpError;
    /**
     * Creates an error for unknown resources
     * @param resourceUri - URI of the unknown resource
     * @returns MCP error for unknown resource
     */
    static unknownResource(resourceUri: string): McpError;
    /**
     * Creates an error for tool execution timeouts
     * @param toolName - Name of the tool that timed out
     * @param timeoutMs - Timeout value in milliseconds
     * @returns MCP error for execution timeout
     */
    static toolTimeout(toolName: string, timeoutMs: number): McpError;
    /**
     * Creates a prescriptive validation error with intelligent guidance
     * @param originalError - The validation error message
     * @param context - Context for error enhancement
     * @returns Enhanced MCP error with prescriptive guidance
     */
    static validationError(originalError: string, context: ErrorEnhancementContext): McpError;
    /**
     * Creates an error for resource content size limits
     * @param resourceUri - URI of the oversized resource
     * @param size - Actual size in bytes
     * @param limit - Size limit in bytes
     * @returns MCP error for oversized content
     */
    static resourceTooLarge(resourceUri: string, size: number, limit: number): McpError;
    /**
     * Creates a clear "entity not found" error for AI agents
     * @param entityType - Type of entity (project, flag, experiment, etc.)
     * @param entityId - ID or key of the entity that wasn't found
     * @param projectId - Optional project ID for context
     * @returns MCP error with clear not found message
     */
    static entityNotFound(entityType: string, entityId: string, projectId?: string): McpError;
    /**
     * Creates a clear "project not found" error for AI agents
     * @param projectId - Project ID that wasn't found
     * @returns MCP error with clear project not found message
     */
    static projectNotFound(projectId: string): McpError;
    /**
     * Creates a clear "invalid parameters" error for AI agents
     * @param toolName - Name of the tool
     * @param missingParams - Array of missing parameter names
     * @param providedParams - Array of provided parameter names
     * @returns MCP error with clear parameter validation message
     */
    static invalidParameters(toolName: string, missingParams: string[], providedParams: string[]): McpError;
    /**
     * Creates a prescriptive entity validation error
     * @param entityType - Type of entity being validated
     * @param originalError - The validation error message
     * @param context - Additional context for enhancement
     * @returns Enhanced MCP error with prescriptive guidance
     */
    static entityValidationError(entityType: string, originalError: string, context?: Partial<ErrorEnhancementContext>): McpError;
}
/**
 * Enhanced error creation with prescriptive guidance
 * @param error - Original error to enhance
 * @param context - Additional context for enhancement
 * @returns Enhanced MCP error with prescriptive guidance
 */
export declare function createPrescriptiveError(error: any, context?: ErrorEnhancementContext): McpError;
/**
 * Type guard to check if an error is an MCP error
 * @param error - Error to check
 * @returns True if error is an MCP error
 */
export declare function isMCPError(error: any): error is McpError;
/**
 * Extract error category from MCP error (if available)
 * @param error - MCP error to analyze
 * @returns Error category or undefined
 */
export declare function getMCPErrorCategory(error: McpError): MCPErrorCategory | undefined;
/**
 * Extract error context from MCP error (if available)
 * @param error - MCP error to analyze
 * @returns Error context or undefined
 */
export declare function getMCPErrorContext(error: McpError): ErrorContext | undefined;
/**
 * Extract prescriptive guidance from enhanced MCP error (if available)
 * @param error - Enhanced MCP error to analyze
 * @returns Prescriptive guidance or undefined
 */
export declare function getPrescriptiveGuidance(error: McpError): PrescriptiveErrorResponse | undefined;
/**
 * Extract original error message from enhanced MCP error (if available)
 * @param error - Enhanced MCP error to analyze
 * @returns Original error message or undefined
 */
export declare function getOriginalErrorMessage(error: McpError): string | undefined;
//# sourceMappingURL=MCPErrorMapping.d.ts.map