@simonecoelhosfo/optimizely-mcp-server/dist/utils/ResponseWrapper.d.ts

Optimizely MCP Server for AI assistants with integrated CLI tools

/**
 * Universal Response Wrapper for Optimizely MCP Tools
 * @description Provides consistent response formatting with success indicators,
 * metadata, and performance tracking across all MCP tools while preserving
 * existing business logic response structures.
 *
 * DESIGN PRINCIPLES:
 * - Additive, not transformative: Wraps existing responses without breaking them
 * - Universal compatibility: Works with all 26 tool response patterns
 * - Neural-first: Places critical metadata in high-attention zones
 * - Backward compatible: Preserves existing response structures
 * - Progressive enhancement: Layers additional metadata as needed
 *
 * @pattern Decorator Pattern - Enhances responses without modifying core logic
 * @version 1.0.0
 */
export interface WrappedResponse<T = any> {
    status: 'success' | 'error' | 'warning' | 'hard_stop_required';
    tool: string;
    result_count?: number;
    query_mode?: 'all_projects' | 'single_project' | 'multi_entity' | 'single_entity';
    projects_queried?: number;
    operation_type?: 'list' | 'get' | 'search' | 'analyze' | 'manage' | 'system';
    timing?: {
        duration_ms: number;
        started_at: string;
        completed_at: string;
    };
    data: T;
    _wrapper_metadata?: {
        wrapper_version: '1.0.0';
        enhanced_response: true;
        original_structure_preserved: true;
        applied_patterns: string[];
    };
}
export interface SuccessHardStopResponse<T = any> {
    hard_stop: 'STOP_YOU_HAVE_ALL_DATA';
    required_action: 'PROCESS_DATA';
    forbidden_actions: string[];
    critical_rule: string;
    success: {
        code: 200 | 206;
        type: SuccessStopType;
        message: string;
        reason: string;
        comprehensive: true;
    };
    immediate_guidance: {
        critical_rule: string;
        detected_situation: string;
        next_step: string;
    };
}
export declare const SuccessStopType: {
    readonly COMPREHENSIVE_DATA_PROVIDED: "COMPREHENSIVE_DATA_PROVIDED";
    readonly MULTI_PROJECT_COMPLETE_DATASET: "MULTI_PROJECT_COMPLETE_DATASET";
    readonly TEMPLATE_GUIDANCE_PROVIDED: "TEMPLATE_GUIDANCE_PROVIDED";
    readonly PAGINATION_COMPLETE: "PAGINATION_COMPLETE";
    readonly THRESHOLD_EXCEEDED: "THRESHOLD_EXCEEDED";
};
export type SuccessStopType = typeof SuccessStopType[keyof typeof SuccessStopType];
export interface AIMeta {
    cursor_notice: "Ignore Cursor's conversation history panel";
    tool_status: "SUCCESS" | "WARNING" | "ERROR";
    source: "optimizely-mcp-server";
    timestamp?: string;
    recommended_next_tool?: {
        tool: string;
        reason: string;
        parameters?: Record<string, any>;
    };
    template_mode?: {
        required: boolean;
        reason: string;
        instruction: string;
        template_tool?: string;
    };
    operation_hints?: {
        complexity: "simple" | "moderate" | "complex";
        requires_orchestration?: boolean;
        child_entities_will_be_created?: string[];
        estimated_api_calls?: number;
        data_comprehensive?: boolean;
        no_further_calls_needed?: boolean;
    };
    result_interpretation?: {
        is_complete: boolean;
        has_more_data: boolean;
        data_summary: string;
        important_fields?: string[];
    };
    avoid_common_mistakes?: string[];
    success_indicators?: {
        operation_completed: boolean;
        no_further_action_needed?: boolean;
        data_comprehensive?: boolean;
    };
}
export interface ResponseWrapperOptions {
    tool_name: string;
    operation_type?: 'list' | 'get' | 'search' | 'analyze' | 'manage' | 'system';
    start_time?: number;
    project_context?: {
        project_id?: string | string[];
        is_multi_project?: boolean;
        projects_queried?: number;
        query_mode?: 'all_projects' | 'single_project';
    };
    enhance_for_mode_pattern?: boolean;
    preserve_hard_stops?: boolean;
    enable_success_stops?: boolean;
    preserve_root_structure?: boolean;
    aiMeta?: Partial<AIMeta>;
}
export declare class ResponseWrapper {
    /**
     * Detects if a success hard stop should be triggered
     * @param data - The response data
     * @param options - Wrapping configuration options
     * @returns Success stop configuration or null
     */
    private static detectSuccessStop;
    /**
     * Creates a success hard stop response with business data at root level
     * @param successStop - Success stop configuration
     * @param data - Original data
     * @param toolName - Tool name
     * @returns Success hard stop response with data spread at root level
     */
    private static createSuccessHardStop;
    /**
     * Wraps any tool response with consistent success indicators and metadata
     * @param data - The original business logic response
     * @param options - Wrapping configuration options
     * @returns Enhanced response with metadata at top, data preserved
     */
    static wrap<T>(data: T, options: ResponseWrapperOptions): WrappedResponse<T> | (SuccessHardStopResponse<T> & T);
    /**
     * Enhanced wrapper for tools using the MODE pattern
     * Provides neural-first metadata for all_projects vs single_project operations
     */
    static wrapWithModePattern<T>(data: T, toolName: string, projectContext: ResponseWrapperOptions['project_context'], startTime?: number): WrappedResponse<T> | (SuccessHardStopResponse<T> & T);
    /**
     * Enhanced wrapper with explicit success stop enablement
     * Use this when you specifically want to prevent repetitive tool calls
     */
    static wrapWithSuccessStops<T>(data: T, toolName: string, projectContext: ResponseWrapperOptions['project_context'], startTime?: number): WrappedResponse<T> | (SuccessHardStopResponse<T> & T);
    /**
     * Lightweight wrapper for simple success/failure indication
     * Minimal overhead for system tools that don't need full enhancement
     */
    static wrapSimple<T>(data: T, toolName: string, operationType?: string): WrappedResponse<T>;
    /**
     * Wraps response with AI metadata for guiding AI agents
     * Preserves root structure for backward compatibility
     * @param data - The original response
     * @param options - Wrapper options including AI metadata
     * @returns Response with _ai_meta added
     */
    static wrapWithAIMeta<T>(data: T, options: ResponseWrapperOptions): T & {
        _ai_meta: AIMeta;
    };
    /**
     * Determines tool status from response data
     */
    private static determineToolStatus;
    /**
     * Generates automatic AI guidance based on response patterns
     */
    private static generateAutoGuidance;
    private static extractResultCount;
    private static determineQueryMode;
    private static checkForHardStop;
    private static determineStatus;
    private static getAppliedPatterns;
}
/**
 * Decorator function for automatically wrapping tool methods
 * Usage: @withResponseWrapper('tool_name', options)
 */
export declare function withResponseWrapper(toolName: string, options?: Partial<ResponseWrapperOptions>): <T extends (...args: any[]) => Promise<any>>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
/**
 * Utility for gradually migrating existing tools to use response wrapper
 * Allows selective enhancement without breaking existing functionality
 */
export declare class ResponseWrapperMigration {
    private static enabledTools;
    static enableForTool(toolName: string): void;
    static isEnabledForTool(toolName: string): boolean;
    static wrapIfEnabled<T>(data: T, toolName: string, options: ResponseWrapperOptions): T | WrappedResponse<T> | SuccessHardStopResponse<T>;
}
//# sourceMappingURL=ResponseWrapper.d.ts.map