client-mcp/src/types/index.ts

/**
 * Configuration for the MCP client
 */
export interface ClientMCPConfig {
    /** OpenAI API key */
    apiKey: string;
    /** AI model to use (default: "gemini-2.0-flash") */
    model?: string;
    /** Custom base URL for API requests */
    baseUrl?: string;
    /** Request timeout in milliseconds (default: 30000) */
    timeout?: number;
    /** Enable debug logging (default: false) */
    debug?: boolean;
    /** System messages to initialize the conversation */
    systemMessages?: string;
}

/**
 * Generic API response wrapper
 */
export interface ApiResponse<T> {
    data: T;
    error?: string;
    metadata?: Record<string, unknown>;
}

/**
 * Custom chat chunk for tool execution results
 */
export interface ChatChunk {
    choices: Array<{
        delta: {
            content?: string;
            tool_calls?: Array<{
                function: {
                    name: string;
                    arguments: string;
                };
            }>;
        };
    }>;
}

/**
 * Result of tool execution
 */
export interface ToolExecutionResult {
    success: boolean;
    result?: unknown;
    error?: string;
    toolName: string;
    arguments: Record<string, unknown>;
    timestamp: Date;
}

/**
 * Current state of the conversation
 */
export interface ConversationState {
    messageCount: number;
    toolsAvailable: number;
    isConnected: boolean;
    lastActivity: Date;
}

/**
 * Options for chat operations
 */
export interface ChatOptions {
    /** Maximum recursion depth for tool calls */
    maxDepth?: number;
    /** Whether to automatically summarize long conversations */
    autoSummarize?: boolean;
    /** Reasoning effort level for AI responses */
    reasoningEffort?: "low" | "medium" | "high";
}

/**
 * Tool definition for MCP
 */
export interface MCPTool {
    name: string;
    description: string;
    input_schema: Record<string, unknown>;
}

/**
 * Connection status information
 */
export interface ConnectionStatus {
    connected: boolean;
    serverType: 'stdio' | 'sse' | null;
    connectedAt?: Date;
    lastError?: string;
}

/**
 * Enhanced error information
 */
export interface MCPError extends Error {
    code?: string;
    details?: Record<string, unknown>;
    retryable?: boolean;
}

/**
 * Session information for SSE connections
 */
export interface SessionInfo {
    id: string;
    createdAt: Date;
    lastActivity: Date;
    metadata?: Record<string, unknown>;
}

/**
 * Conversation continuation decision
 */
export interface ContinuationDecision {
    continue: boolean;
    nextMessage?: string;
    reason?: string;
    confidence?: number;
}

/**
 * Tool call tracking information
 */
export interface ToolCallTracker {
    callId: string;
    toolName: string;
    startTime: Date;
    endTime?: Date;
    status: 'pending' | 'success' | 'error';
    result?: unknown;
    error?: string;
}

/**
 * Performance metrics
 */
export interface PerformanceMetrics {
    totalRequests: number;
    successfulRequests: number;
    failedRequests: number;
    averageResponseTime: number;
    toolCallsExecuted: number;
    conversationDepth: number;
    lastRequestTime?: Date;
}

/**
 * Enhanced logging context
 */
export interface LogContext {
    sessionId?: string;
    conversationId?: string;
    userId?: string;
    toolName?: string;
    metadata?: Record<string, unknown>;
}

/**
 * Configuration validation result
 */
export interface ConfigValidationResult {
    valid: boolean;
    errors: string[];
    warnings: string[];
}

/**
 * Connection parameters for different transport types
 */
export type ConnectionParams = {
    type: 'stdio';
    scriptPath: string;
} | {
    type: 'sse';
    serverUrl: URL;
    sessionId?: string;
    headers?: Record<string, string>;
};

/**
 * Event types for the MCP client
 */
export type MCPClientEvent = 
    | { type: 'connected'; data: ConnectionStatus }
    | { type: 'disconnected'; data: { reason?: string } }
    | { type: 'tool_call_started'; data: ToolCallTracker }
    | { type: 'tool_call_completed'; data: ToolCallTracker }
    | { type: 'conversation_depth_warning'; data: { currentDepth: number; maxDepth: number } }
    | { type: 'error'; data: MCPError };

/**
 * Callback for handling MCP client events
 */
export type MCPEventHandler = (event: MCPClientEvent) => void;

/**
 * Advanced configuration options
 */
export interface AdvancedClientConfig extends ClientMCPConfig {
    /** Maximum number of concurrent tool calls */
    maxConcurrentToolCalls?: number;
    /** Enable automatic conversation summarization */
    autoSummarizeThreshold?: number;
    /** Custom headers for HTTP requests */
    customHeaders?: Record<string, string>;
    /** Retry configuration */
    retryConfig?: {
        maxRetries: number;
        initialDelay: number;
        maxDelay: number;
        backoffMultiplier: number;
    };
    /** Performance monitoring */
    enableMetrics?: boolean;
    /** Event handler for client events */
    eventHandler?: MCPEventHandler;
}