@defai.digital/ax-cli 4.4.7 → 4.4.11

package/dist/mcp/client-v2.d.ts

@@ -1,500 +0,0 @@
-/**
- * Type-Safe MCP Client (Phase 1 Improvements)
- *
- * Improvements applied:
- * 1. SafeMutex with lock tokens (prevents race conditions)
- * 2. Result types for all public APIs (explicit error handling)
- * 3. State machine for connection tracking (type-safe states)
- * 4. Branded types for ServerName/ToolName (prevent confusion)
- * 5. Invariant checks (runtime validation)
- *
- * Coverage: 70% → 85%+ (Phase 1)
- */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { EventEmitter } from "events";
-import { MCPTransport, TransportType } from "./transports.js";
-import type { MCPServerConfig, MCPTransportConfig } from "../schemas/settings-schemas.js";
-import { Result } from "./type-safety.js";
-import { ServerName, ToolName, createServerName, createToolName } from "./type-safety.js";
-import { type ProgressUpdate, type ProgressCallback } from "./progress.js";
-import { type CancellableRequest, type CancellationResult } from "./cancellation.js";
-import { type ResourceSubscription } from "./subscriptions.js";
-import { type SchemaValidationResult } from "./schema-validator.js";
-export type { ProgressUpdate, ProgressCallback };
-export type { CancellableRequest, CancellationResult };
-export type { ResourceSubscription };
-export type { SchemaValidationResult };
-/**
- * Extended tool result with schema validation
- */
-export interface ValidatedToolResult extends CallToolResult {
-    /** Schema validation result (if tool has outputSchema) */
-    schemaValidation?: SchemaValidationResult;
-}
-export type { MCPServerConfig, MCPTransportConfig, ServerName, ToolName };
-/**
- * Connection State Machine
- *
- * Valid transitions:
- * - idle → connecting (addServer called)
- * - connecting → connected (connection succeeds)
- * - connecting → failed (connection fails)
- * - connected → disconnecting (removeServer called)
- * - disconnecting → idle (cleanup complete)
- * - failed → idle (reset)
- */
-export type ConnectionState = {
-    status: 'idle';
-    serverName: ServerName;
-} | {
-    status: 'connecting';
-    serverName: ServerName;
-    startedAt: number;
-    promise: Promise<Result<void, Error>>;
-} | {
-    status: 'connected';
-    serverName: ServerName;
-    client: Client;
-    transport: MCPTransport;
-    connectedAt: number;
-} | {
-    status: 'disconnecting';
-    serverName: ServerName;
-    client: Client;
-    transport: MCPTransport;
-} | {
-    status: 'failed';
-    serverName: ServerName;
-    error: Error;
-    failedAt: number;
-};
-/**
- * Reconnection Configuration
- *
- * Controls automatic reconnection behavior when MCP servers fail or disconnect.
- * Uses exponential backoff to avoid overwhelming failed servers.
- *
- * @example
- * ```typescript
- * const config: ReconnectionConfig = {
- *   enabled: true,
- *   maxRetries: 5,
- *   initialDelayMs: 1000,
- *   maxDelayMs: 30000,
- *   backoffMultiplier: 2
- * };
- * ```
- */
-export interface ReconnectionConfig {
-    /** Enable automatic reconnection on failure */
-    enabled: boolean;
-    /** Maximum number of reconnection attempts before giving up (default: 5) */
-    maxRetries: number;
-    /** Initial delay before first reconnection attempt in ms (default: 1000) */
-    initialDelayMs: number;
-    /** Maximum delay between reconnection attempts in ms (default: 30000) */
-    maxDelayMs: number;
-    /** Multiplier for exponential backoff (default: 2) */
-    backoffMultiplier: number;
-}
-/**
- * Default reconnection configuration
- */
-export declare const DEFAULT_RECONNECTION_CONFIG: ReconnectionConfig;
-/**
- * Health Check Configuration
- */
-export interface HealthCheckConfig {
-    /** Enable periodic health checks */
-    enabled: boolean;
-    /** Interval between health checks in ms */
-    intervalMs: number;
-}
-/**
- * Default health check configuration
- */
-export declare const DEFAULT_HEALTH_CHECK_CONFIG: HealthCheckConfig;
-/**
- * MCP Tool with branded types
- */
-export interface MCPTool {
-    name: ToolName;
-    description: string;
-    inputSchema: Record<string, unknown>;
-    outputSchema?: Record<string, unknown>;
-    serverName: ServerName;
-}
-/**
- * MCP Prompt from a server
- */
-export interface MCPPrompt {
-    serverName: ServerName;
-    name: string;
-    description?: string;
-    arguments?: Array<{
-        name: string;
-        description?: string;
-        required?: boolean;
-    }>;
-}
-/**
- * MCP Server Capabilities Summary
- *
- * Provides a structured view of what an MCP server supports.
- * This enables agents to tailor their behavior based on server capabilities.
- *
- * For example, Figma MCP servers may support:
- * - Resource subscriptions for real-time design updates
- * - Progress notifications for long-running exports
- * - Tools with output schemas for structured responses
- */
-export interface MCPServerCapabilities {
-    /** Whether the server supports resources/list and resources/read */
-    supportsResources: boolean;
-    /** Whether the server supports resources/subscribe for real-time updates */
-    supportsResourceSubscriptions: boolean;
-    /** Whether the server emits notifications/resources/list_changed */
-    supportsResourceListChanged: boolean;
-    /** Whether the server supports tools/list and tools/call */
-    supportsTools: boolean;
-    /** Whether the server emits notifications/tools/list_changed */
-    supportsToolListChanged: boolean;
-    /** Whether the server supports prompts/list and prompts/get */
-    supportsPrompts: boolean;
-    /** Whether the server emits notifications/prompts/list_changed */
-    supportsPromptListChanged: boolean;
-    /** Whether the server supports logging/setLevel */
-    supportsLogging: boolean;
-    experimental: Record<string, unknown>;
-    raw: Record<string, unknown>;
-}
-/**
- * Type-safe MCP Manager with improved safety
- */
-export declare class MCPManagerV2 extends EventEmitter {
-    private connections;
-    private tools;
-    private prompts;
-    private connectionMutex;
-    private initializationPromise;
-    private tokenCounter;
-    private disposed;
-    private disposing;
-    private disposePromise;
-    private reconnectionConfig;
-    private healthCheckConfig;
-    private reconnectionAttempts;
-    private reconnectionTimers;
-    private serverConfigs;
-    private healthCheckTimer;
-    private healthCheckInFlight;
-    private clientName;
-    private clientVersion;
-    constructor(reconnectionConfig?: Partial<ReconnectionConfig>, healthCheckConfig?: Partial<HealthCheckConfig>, clientConfig?: {
-        name?: string;
-        version?: string;
-    });
-    /**
-     * Transition server to failed state (reduces duplication)
-     */
-    private _setFailedState;
-    /**
-     * Add MCP server with type-safe connection management
-     *
-     * Phase 1 improvements:
-     * - Returns Result instead of throwing
-     * - Uses SafeMutex for concurrency control
-     * - Tracks state machine transitions
-     * - Validates inputs with invariants
-     */
-    addServer(config: MCPServerConfig): Promise<Result<void, Error>>;
-    /**
-     * Internal connection logic with state transitions
-     */
-    private _addServerInternal;
-    /**
-     * Remove MCP server with proper state transitions
-     */
-    removeServer(serverName: ServerName): Promise<Result<void, Error>>;
-    /**
-     * Internal disconnection logic with state transitions
-     */
-    private _removeServerInternal;
-    /**
-     * Close client with error handling
-     */
-    private closeClient;
-    /**
-     * Disconnect transport with error handling
-     */
-    private disconnectTransport;
-    /**
-     * Call MCP tool with type safety and optional schema validation
-     *
-     * @param toolName - The tool to call
-     * @param arguments_ - Tool arguments
-     * @param options - Optional settings for validation and MCP _meta
-     * @returns Result containing the tool result with optional schema validation
-     */
-    callTool(toolName: ToolName, arguments_: Record<string, unknown> | null | undefined, options?: {
-        validateOutput?: boolean;
-        /** MCP _meta for progress tracking and cancellation */
-        _meta?: {
-            progressToken?: string | number;
-            /** Request ID for cancellation (custom extension) */
-            requestId?: string | number;
-        };
-        /** AbortSignal for cancellation */
-        signal?: AbortSignal;
-    }): Promise<Result<ValidatedToolResult, Error>>;
-    /**
-     * Call MCP tool with progress tracking
-     *
-     * MCP Specification: Supports notifications/progress for long-running operations.
-     *
-     * FIX: Now properly forwards _meta.progressToken to the MCP server so it can
-     * attach progress notifications to this specific request.
-     *
-     * @param toolName - The tool to call
-     * @param arguments_ - Tool arguments
-     * @param options - Progress tracking options
-     * @returns Result containing the tool result or error
-     */
-    callToolWithProgress(toolName: ToolName, arguments_: Record<string, unknown> | null | undefined, options?: {
-        onProgress?: ProgressCallback;
-    }): Promise<Result<CallToolResult, Error>>;
-    /**
-     * Call MCP tool with cancellation support
-     *
-     * MCP Specification: Supports notifications/cancelled for aborting operations.
-     *
-     * FIX: Now properly propagates AbortSignal to the MCP SDK so cancellation
-     * actually stops the server work instead of just racing locally. Also sends
-     * notifications/cancelled to the server so it can clean up.
-     *
-     * @param toolName - The tool to call
-     * @param arguments_ - Tool arguments
-     * @returns Result containing the tool result, cancellation status, or error
-     */
-    callToolCancellable(toolName: ToolName, arguments_: Record<string, unknown> | null | undefined): Promise<Result<CallToolResult & {
-        isCancelled?: boolean;
-        cancelReason?: string;
-    }, Error>>;
-    /**
-     * Cancel the most recent active request
-     *
-     * @param reason - Optional reason for cancellation
-     * @returns Cancellation result
-     */
-    cancelCurrentRequest(reason?: string): Promise<CancellationResult | undefined>;
-    /**
-     * Cancel all active requests
-     *
-     * @param reason - Optional reason for cancellation
-     * @returns Array of cancellation results
-     */
-    cancelAllRequests(reason?: string): Promise<CancellationResult[]>;
-    /**
-     * Check if there are any active cancellable requests
-     */
-    hasActiveRequests(): boolean;
-    /**
-     * Get the count of active cancellable requests
-     */
-    getActiveRequestCount(): number;
-    /**
-     * Subscribe to a resource
-     *
-     * @param serverName - Server providing the resource
-     * @param uri - Resource URI to subscribe to
-     * @returns Result indicating success or error
-     */
-    subscribeResource(serverName: ServerName, uri: string): Promise<Result<void, Error>>;
-    /**
-     * Unsubscribe from a resource
-     *
-     * @param serverName - Server providing the resource
-     * @param uri - Resource URI to unsubscribe from
-     * @returns Result indicating success or error
-     */
-    unsubscribeResource(serverName: ServerName, uri: string): Promise<Result<void, Error>>;
-    /**
-     * Get all active resource subscriptions
-     */
-    getResourceSubscriptions(): ResourceSubscription[];
-    /**
-     * Check if subscribed to a resource
-     */
-    isSubscribedToResource(serverName: ServerName, uri: string): boolean;
-    /**
-     * Set up notification handlers for MCP server
-     *
-     * Handles:
-     * - notifications/progress - Progress updates for long-running operations
-     * - notifications/resources/updated - Resource change notifications
-     * - notifications/resources/list_changed - Resource list changes
-     */
-    private setupNotificationHandlers;
-    /**
-     * Truncate text to fit within token limit
-     * UNICODE FIX: Uses grapheme clusters
-     */
-    private truncateToTokenLimit;
-    /**
-     * Get all tools
-     */
-    getTools(): MCPTool[];
-    /**
-     * Get all connected servers
-     */
-    getServers(): ServerName[];
-    /**
-     * Get MCP connection status summary
-     * Returns counts of connected, failed, connecting, and total servers
-     */
-    getConnectionStatus(): {
-        connected: number;
-        failed: number;
-        connecting: number;
-        total: number;
-    };
-    /**
-     * Get connection state for a server
-     */
-    getConnectionState(serverName: ServerName): ConnectionState | undefined;
-    /**
-     * Get all prompts from connected servers
-     */
-    getPrompts(): MCPPrompt[];
-    /**
-     * List prompts from a specific server
-     */
-    listServerPrompts(serverName: ServerName): Promise<Result<MCPPrompt[], Error>>;
-    /**
-     * Get a specific prompt from a server
-     */
-    getPrompt(serverName: ServerName, promptName: string, args?: Record<string, string>): Promise<Result<{
-        description?: string;
-        messages: unknown[];
-    }, Error>>;
-    /**
-     * Discover prompts from all connected servers
-     * PERF: Parallelized - servers are independent, no need to wait sequentially
-     */
-    discoverPrompts(): Promise<void>;
-    /**
-     * Get transport type for a server
-     */
-    getTransportType(serverName: ServerName): Result<TransportType, Error>;
-    /**
-     * Get capabilities for a specific MCP server
-     *
-     * This allows agents to tailor their behavior based on server capabilities.
-     * For example, Figma MCP servers may support long-running exports with progress.
-     *
-     * @param serverName - The server to query capabilities for
-     * @returns Result containing capability summary or error
-     *
-     * @example
-     * ```typescript
-     * const caps = manager.getServerCapabilities(serverName);
-     * if (caps.success && caps.value.supportsProgress) {
-     *   // Use callToolWithProgress for better UX
-     *   await manager.callToolWithProgress(toolName, args, { onProgress });
-     * }
-     * ```
-     */
-    getServerCapabilities(serverName: ServerName): Result<MCPServerCapabilities, Error>;
-    /**
-     * Get capabilities for all connected servers
-     *
-     * @returns Map of server names to their capabilities
-     */
-    getAllServerCapabilities(): Map<ServerName, MCPServerCapabilities>;
-    /**
-     * Check if a server supports a specific capability
-     *
-     * @param serverName - Server to check
-     * @param capability - Capability to check for
-     * @returns true if the server supports the capability
-     */
-    serverSupports(serverName: ServerName, capability: keyof Omit<MCPServerCapabilities, 'experimental' | 'raw'>): boolean;
-    /**
-     * Get the MCP client for a specific server
-     *
-     * This is used by resources.ts to access listResources/readResource
-     *
-     * @param serverName - The server name
-     * @returns Result containing the client or error
-     */
-    getClient(serverName: ServerName): Result<Client, Error>;
-    /**
-     * List resources from a specific server
-     *
-     * @param serverName - The server name
-     * @returns Result containing resources or error
-     */
-    listResources(serverName: ServerName): Promise<Result<Array<{
-        uri: string;
-        name: string;
-        description?: string;
-        mimeType?: string;
-    }>, Error>>;
-    /**
-     * Read a resource from a specific server
-     *
-     * @param serverName - The server name
-     * @param uri - Resource URI
-     * @returns Result containing resource content or error
-     */
-    readResource(serverName: ServerName, uri: string): Promise<Result<string, Error>>;
-    /**
-     * Schedule reconnection for a failed server with exponential backoff
-     *
-     * Phase 2: Automatic reconnection logic
-     *
-     * @param serverName - Server to reconnect
-     * @param config - Server configuration
-     */
-    private scheduleReconnection;
-    /**
-     * Cancel reconnection for a server
-     */
-    private cancelReconnection;
-    /**
-     * Perform health check on a single server
-     *
-     * @param serverName - Server to check
-     * @returns Result indicating health status
-     */
-    healthCheck(serverName: ServerName): Promise<Result<boolean, Error>>;
-    /**
-     * Start periodic health checks for all connected servers
-     * PERF: Parallelized - health checks are independent per server
-     */
-    private startHealthChecks;
-    /**
-     * Stop periodic health checks
-     */
-    private stopHealthChecks;
-    /**
-     * Shutdown all servers
-     */
-    shutdown(): Promise<Result<void, Error>>;
-    /**
-     * Ensure servers initialized
-     */
-    ensureServersInitialized(): Promise<Result<void, Error>>;
-    /**
-     * Dispose all resources
-     */
-    dispose(): Promise<Result<void, Error>>;
-    /**
-     * Clean up resources and remove all event listeners.
-     * @deprecated Use dispose() instead for complete cleanup.
-     * This method now delegates to dispose() for backwards compatibility.
-     */
-    destroy(): void;
-}
-export { createServerName, createToolName };