@frontmcp/sdk 0.6.3 → 0.7.2

package/remote-mcp/mcp-client.service.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @file mcp-client.service.ts
+ * @description Service for managing connections to remote MCP servers
+ */
+import type { Tool, Resource, ResourceTemplate, Prompt, CallToolResult, ReadResourceResult, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+import type { FrontMcpLogger } from '../common';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import type { McpClientConnection, McpConnectionInfo, McpClientServiceOptions, McpConnectRequest, McpRemoteCapabilities, McpCapabilityChangeCallback, McpConnectionChangeCallback, McpUnsubscribeFn, McpRemoteAuthConfig, McpRemoteAuthContext } from './mcp-client.types';
+import { CircuitBreaker, HealthChecker } from './resilience';
+/**
+ * Service for managing connections to remote MCP servers.
+ *
+ * This service handles:
+ * - Connection lifecycle (connect, disconnect, reconnect)
+ * - Capability discovery (tools, resources, prompts)
+ * - Proxy execution (callTool, readResource, getPrompt)
+ * - Authentication context forwarding
+ * - Event subscriptions for capability and connection changes
+ */
+export declare class McpClientService {
+    private readonly connections;
+    private readonly capabilities;
+    private readonly configs;
+    private readonly options;
+    private readonly logger;
+    private readonly capabilityChangeCallbacks;
+    private readonly connectionChangeCallbacks;
+    private readonly refreshTimers;
+    private readonly refreshInProgress;
+    private readonly circuitBreakerManager;
+    private readonly healthCheckManager;
+    private readonly reconnectAttempts;
+    private readonly reconnectTimers;
+    constructor(logger: FrontMcpLogger, options?: McpClientServiceOptions);
+    /**
+     * Connect to a remote MCP server
+     */
+    connect(request: McpConnectRequest): Promise<McpClientConnection>;
+    /**
+     * Disconnect from a remote MCP server
+     */
+    disconnect(appId: string): Promise<void>;
+    /**
+     * Reconnect to a remote MCP server
+     */
+    reconnect(appId: string): Promise<McpClientConnection>;
+    /**
+     * Get connection status for an app
+     */
+    getConnectionStatus(appId: string): McpConnectionInfo | undefined;
+    /**
+     * Check if connected to an app
+     */
+    isConnected(appId: string): boolean;
+    /**
+     * Discover capabilities from a remote server
+     */
+    discoverCapabilities(appId: string): Promise<McpRemoteCapabilities>;
+    /**
+     * Get cached capabilities for an app
+     */
+    getCapabilities(appId: string): McpRemoteCapabilities | undefined;
+    /**
+     * List tools from a remote server
+     */
+    listTools(appId: string): Promise<Tool[]>;
+    /**
+     * List resources from a remote server
+     */
+    listResources(appId: string): Promise<Resource[]>;
+    /**
+     * List resource templates from a remote server
+     */
+    listResourceTemplates(appId: string): Promise<ResourceTemplate[]>;
+    /**
+     * List prompts from a remote server
+     */
+    listPrompts(appId: string): Promise<Prompt[]>;
+    /**
+     * Call a tool on a remote server with self-healing
+     */
+    callTool(appId: string, toolName: string, args: Record<string, unknown>, authContext?: McpRemoteAuthContext): Promise<CallToolResult>;
+    /**
+     * Read a resource from a remote server
+     */
+    readResource(appId: string, uri: string, authContext?: McpRemoteAuthContext): Promise<ReadResourceResult>;
+    /**
+     * Get a prompt from a remote server
+     */
+    getPrompt(appId: string, promptName: string, args: Record<string, string>, authContext?: McpRemoteAuthContext): Promise<GetPromptResult>;
+    /**
+     * Subscribe to capability change events
+     */
+    onCapabilityChange(callback: McpCapabilityChangeCallback): McpUnsubscribeFn;
+    /**
+     * Subscribe to connection status change events
+     */
+    onConnectionChange(callback: McpConnectionChangeCallback): McpUnsubscribeFn;
+    /**
+     * Resolve authentication headers for a remote request
+     */
+    resolveAuthHeaders(appId: string, authConfig: McpRemoteAuthConfig | undefined, gatewayAuthInfo?: AuthInfo): Promise<Record<string, string>>;
+    /**
+     * Disconnect from all remote servers and clean up
+     */
+    dispose(): Promise<void>;
+    private getConnection;
+    /**
+     * Create transport for a remote connection.
+     *
+     * Note: For HTTP transport with fallback, the initial transport is Streamable HTTP.
+     * If connection fails with Streamable HTTP, use createFallbackTransport() to get SSE.
+     */
+    private createTransport;
+    /**
+     * Create fallback SSE transport when Streamable HTTP fails
+     */
+    private createFallbackSSETransport;
+    /**
+     * Check if fallback to SSE is enabled for a request
+     */
+    private shouldFallbackToSSE;
+    private listToolsInternal;
+    private listResourcesInternal;
+    private listResourceTemplatesInternal;
+    private listPromptsInternal;
+    private updateConnectionStatus;
+    private emitCapabilityChangeIfNeeded;
+    private startCapabilityRefresh;
+    private stopCapabilityRefresh;
+    private buildAuthHeaders;
+    /**
+     * Schedule an auto-reconnect attempt for an app
+     */
+    private scheduleAutoReconnect;
+    /**
+     * Cancel scheduled auto-reconnect for an app
+     */
+    private cancelAutoReconnect;
+    /**
+     * Handle health status changes for proactive healing
+     */
+    private handleHealthStatusChange;
+    /**
+     * Start health checking for an app
+     */
+    private startHealthCheck;
+    /**
+     * Stop health checking for an app
+     */
+    private stopHealthCheck;
+    /**
+     * Get circuit breaker status for an app
+     */
+    getCircuitBreakerStatus(appId: string): ReturnType<CircuitBreaker['getStats']> | undefined;
+    /**
+     * Get health check status for an app
+     */
+    getHealthStatus(appId: string): ReturnType<HealthChecker['getLastResult']> | undefined;
+    /**
+     * Manually reset circuit breaker for an app
+     */
+    resetCircuitBreaker(appId: string): void;
+    /**
+     * Force a health check for an app
+     */
+    forceHealthCheck(appId: string): Promise<void>;
+}
+//# sourceMappingURL=mcp-client.service.d.ts.map

package/remote-mcp/mcp-client.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.service.d.ts","sourceRoot":"","sources":["../../src/remote-mcp/mcp-client.service.ts"],"names":[],"mappings":"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"}

package/remote-mcp/mcp-client.types.d.ts

@@ -0,0 +1,298 @@
+/**
+ * @file mcp-client.types.ts
+ * @description Types for MCP client connections to remote servers
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Tool, Resource, ResourceTemplate, Prompt, ServerCapabilities, CallToolResult, ReadResourceResult, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+/**
+ * Connection status for a remote MCP server
+ */
+export type McpConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
+/**
+ * Represents an active connection to a remote MCP server
+ */
+export interface McpClientConnection {
+    /** The MCP client instance */
+    client: Client;
+    /** The transport used for communication */
+    transport: Transport;
+    /** Session ID assigned by the remote server (if any) */
+    sessionId?: string;
+    /** Current connection status */
+    status: McpConnectionStatus;
+    /** Last error if status is 'error' */
+    lastError?: Error;
+    /** Server capabilities reported during initialization */
+    capabilities?: ServerCapabilities;
+    /** Timestamp of last successful communication */
+    lastHeartbeat?: Date;
+    /** Timestamp when connection was established */
+    connectedAt?: Date;
+}
+/**
+ * Summary of connection status for external consumers
+ */
+export interface McpConnectionInfo {
+    appId: string;
+    status: McpConnectionStatus;
+    sessionId?: string;
+    connectedAt?: Date;
+    lastHeartbeat?: Date;
+    capabilities?: ServerCapabilities;
+    error?: string;
+}
+/**
+ * Supported transport types for remote MCP connections
+ */
+export type McpTransportType = 'http' | 'sse' | 'worker' | 'npm' | 'esm';
+/**
+ * Options for HTTP-based transports (Streamable HTTP and SSE)
+ */
+export interface McpHttpTransportOptions {
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts for failed requests (default: 3) */
+    retryAttempts?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    retryDelayMs?: number;
+    /** Whether to fallback to SSE if Streamable HTTP fails (default: true) */
+    fallbackToSSE?: boolean;
+    /** Additional headers to include in all requests */
+    headers?: Record<string, string>;
+}
+/**
+ * Options for Worker subprocess transport
+ */
+export interface McpWorkerTransportOptions {
+    /** Path to the worker script */
+    workerPath: string;
+    /** Environment variables for the worker process */
+    env?: Record<string, string>;
+    /** Working directory for the worker process */
+    cwd?: string;
+    /** Timeout for worker startup in milliseconds (default: 10000) */
+    startupTimeout?: number;
+}
+/**
+ * Options for ESM/NPM dynamic import transport
+ */
+export interface McpEsmTransportOptions {
+    /** Package name or URL (e.g., '@frontmcp/slack-mcp@latest' or 'https://esm.sh/...') */
+    packageUrl: string;
+    /** Import map for module resolution */
+    importMap?: Record<string, string>;
+}
+/**
+ * Union of all transport options
+ */
+export type McpTransportOptions = McpHttpTransportOptions | McpWorkerTransportOptions | McpEsmTransportOptions;
+/**
+ * Static credentials for remote server authentication
+ */
+export interface McpStaticCredentials {
+    type: 'bearer' | 'basic' | 'apiKey';
+    value: string;
+    /** Header name for apiKey type (default: 'X-API-Key') */
+    headerName?: string;
+}
+/**
+ * Authentication configuration for remote MCP connections
+ */
+export type McpRemoteAuthConfig = {
+    /** Use static credentials */
+    mode: 'static';
+    credentials: McpStaticCredentials;
+} | {
+    /** Forward gateway user's token to remote server */
+    mode: 'forward';
+    /** Specific claim to extract from token (default: entire token) */
+    tokenClaim?: string;
+    /** Header name to use (default: 'Authorization') */
+    headerName?: string;
+} | {
+    /** Map gateway auth info to remote credentials */
+    mode: 'mapped';
+    mapper: (authInfo: AuthInfo | undefined) => McpStaticCredentials | Promise<McpStaticCredentials>;
+} | {
+    /** Let remote server handle its own OAuth flow */
+    mode: 'oauth';
+};
+/**
+ * Resolved authentication context for a remote call
+ */
+export interface McpRemoteAuthContext {
+    /** Gateway auth info (if available) - may be partial if not fully authenticated */
+    authInfo?: Partial<AuthInfo>;
+    /** Resolved headers to send to remote server */
+    headers?: Record<string, string>;
+}
+/**
+ * Cached capabilities from a remote server
+ */
+export interface McpRemoteCapabilities {
+    /** Tools available on the remote server */
+    tools: Tool[];
+    /** Resources available on the remote server */
+    resources: Resource[];
+    /** Resource templates available on the remote server */
+    resourceTemplates: ResourceTemplate[];
+    /** Prompts available on the remote server */
+    prompts: Prompt[];
+    /** Timestamp when capabilities were last fetched */
+    fetchedAt: Date;
+}
+/**
+ * Event emitted when remote capabilities change
+ */
+export interface McpCapabilityChangeEvent {
+    appId: string;
+    kind: 'tools' | 'resources' | 'prompts' | 'all';
+    previousCount: number;
+    newCount: number;
+    timestamp: Date;
+}
+/**
+ * Retry options for self-healing
+ */
+export interface McpRetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 10000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+    /** Jitter factor 0-1 to randomize delays (default: 0.1) */
+    jitterFactor?: number;
+}
+/**
+ * Circuit breaker options
+ */
+export interface McpCircuitBreakerOptions {
+    /** Number of failures before opening circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in ms before attempting to close circuit (default: 30000) */
+    resetTimeoutMs?: number;
+    /** Number of successful calls in half-open to close circuit (default: 2) */
+    successThreshold?: number;
+    /** Time window in ms for counting failures (default: 60000) */
+    failureWindowMs?: number;
+}
+/**
+ * Health check options
+ */
+export interface McpHealthCheckOptions {
+    /** Interval between health checks in ms (default: 30000) */
+    intervalMs?: number;
+    /** Timeout for health check in ms (default: 5000) */
+    timeoutMs?: number;
+    /** Number of failures before marking unhealthy (default: 3) */
+    unhealthyThreshold?: number;
+    /** Number of successes before marking healthy (default: 2) */
+    healthyThreshold?: number;
+}
+/**
+ * Configuration for the MCP client service
+ */
+export interface McpClientServiceOptions {
+    /** Interval for capability refresh in ms (0 = no refresh, default: 0) */
+    capabilityRefreshInterval?: number;
+    /** Client name reported to remote servers (default: 'frontmcp-gateway') */
+    clientName?: string;
+    /** Client version reported to remote servers (default: '1.0.0') */
+    clientVersion?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable retry with exponential backoff for transient failures (default: true) */
+    enableRetry?: boolean;
+    /** Retry configuration options */
+    retryOptions?: McpRetryOptions;
+    /** Enable circuit breaker to prevent cascading failures (default: true) */
+    enableCircuitBreaker?: boolean;
+    /** Circuit breaker configuration options */
+    circuitBreakerOptions?: McpCircuitBreakerOptions;
+    /** Enable health checking for proactive monitoring (default: true) */
+    enableHealthCheck?: boolean;
+    /** Health check configuration options */
+    healthCheckOptions?: McpHealthCheckOptions;
+    /** Enable automatic reconnection on connection failures (default: true) */
+    enableAutoReconnect?: boolean;
+    /** Base delay between auto-reconnect attempts in ms (default: 5000) */
+    autoReconnectDelayMs?: number;
+    /** Maximum number of auto-reconnect attempts (default: 3) */
+    maxAutoReconnectAttempts?: number;
+}
+/**
+ * Request to connect to a remote MCP server
+ */
+export interface McpConnectRequest {
+    /** Unique identifier for this remote app */
+    appId: string;
+    /** Display name for the remote app */
+    name: string;
+    /** Transport type to use */
+    transportType: McpTransportType;
+    /** URL or path for the remote server */
+    url: string;
+    /** Transport-specific options */
+    transportOptions?: McpTransportOptions;
+    /** Authentication configuration */
+    auth?: McpRemoteAuthConfig;
+    /** Namespace prefix for tool names (default: appId) */
+    namespace?: string;
+}
+/**
+ * Result of a tool call to a remote server
+ */
+export interface McpRemoteCallToolResult {
+    /** The raw result from the remote server */
+    result: CallToolResult;
+    /** Duration of the call in milliseconds */
+    durationMs: number;
+    /** Whether the call was successful */
+    success: boolean;
+    /** Error if the call failed */
+    error?: Error;
+}
+/**
+ * Result of a resource read from a remote server
+ */
+export interface McpRemoteReadResourceResult {
+    /** The raw result from the remote server */
+    result: ReadResourceResult;
+    /** Duration of the call in milliseconds */
+    durationMs: number;
+    /** Whether the call was successful */
+    success: boolean;
+    /** Error if the call failed */
+    error?: Error;
+}
+/**
+ * Result of a prompt get from a remote server
+ */
+export interface McpRemoteGetPromptResult {
+    /** The raw result from the remote server */
+    result: GetPromptResult;
+    /** Duration of the call in milliseconds */
+    durationMs: number;
+    /** Whether the call was successful */
+    success: boolean;
+    /** Error if the call failed */
+    error?: Error;
+}
+/**
+ * Callback for capability change notifications
+ */
+export type McpCapabilityChangeCallback = (event: McpCapabilityChangeEvent) => void;
+/**
+ * Callback for connection status changes
+ */
+export type McpConnectionChangeCallback = (appId: string, status: McpConnectionStatus, error?: Error) => void;
+/**
+ * Unsubscribe function returned by event subscriptions
+ */
+export type McpUnsubscribeFn = () => void;
+//# sourceMappingURL=mcp-client.types.d.ts.map

package/remote-mcp/mcp-client.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.types.d.ts","sourceRoot":"","sources":["../../src/remote-mcp/mcp-client.types.ts"],"names":[],"mappings":"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"}

package/remote-mcp/resilience/circuit-breaker.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @file circuit-breaker.ts
+ * @description Circuit breaker pattern for preventing cascading failures in remote MCP operations
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerOptions {
+    /** Number of failures before opening circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in ms before attempting to close circuit (default: 30000) */
+    resetTimeoutMs?: number;
+    /** Number of successful calls in half-open to close circuit (default: 2) */
+    successThreshold?: number;
+    /** Time window in ms for counting failures (default: 60000) */
+    failureWindowMs?: number;
+    /** Callback when state changes */
+    onStateChange?: (state: CircuitState, previousState: CircuitState) => void;
+}
+/**
+ * Circuit breaker for a specific remote app connection.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Failures exceeded threshold, requests fail immediately
+ * - HALF-OPEN: Testing if service recovered, limited requests allowed
+ */
+export declare class CircuitBreaker {
+    private readonly appId;
+    private readonly options;
+    private state;
+    private failures;
+    private successCount;
+    private lastFailureTime?;
+    private nextAttemptTime?;
+    constructor(appId: string, options?: CircuitBreakerOptions);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Check if the circuit allows requests
+     */
+    canExecute(): boolean;
+    /**
+     * Record a successful operation
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed operation
+     */
+    recordFailure(error: Error): void;
+    /**
+     * Force reset the circuit to closed state
+     */
+    reset(): void;
+    /**
+     * Get circuit breaker stats
+     */
+    getStats(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        lastFailureTime?: number;
+        nextAttemptTime?: number;
+    };
+    private transitionTo;
+    private cleanOldFailures;
+}
+/**
+ * Error thrown when circuit is open
+ */
+export declare class CircuitOpenError extends Error {
+    readonly appId: string;
+    readonly nextAttemptTime?: number;
+    constructor(appId: string, nextAttemptTime?: number);
+}
+/**
+ * Manager for multiple circuit breakers (one per remote app)
+ */
+export declare class CircuitBreakerManager {
+    private readonly breakers;
+    private readonly defaultOptions;
+    constructor(defaultOptions?: CircuitBreakerOptions);
+    /**
+     * Get or create a circuit breaker for an app
+     */
+    getBreaker(appId: string, options?: CircuitBreakerOptions): CircuitBreaker;
+    /**
+     * Remove a circuit breaker
+     */
+    removeBreaker(appId: string): void;
+    /**
+     * Reset all circuit breakers
+     */
+    resetAll(): void;
+    /**
+     * Get stats for all circuit breakers
+     */
+    getAllStats(): Map<string, ReturnType<CircuitBreaker['getStats']>>;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/remote-mcp/resilience/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/remote-mcp/resilience/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,KAAK,IAAI,CAAC;CAC5E;AAeD;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,eAAe,CAAC,CAAS;gBAErB,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B;IAK9D;;OAEG;IACH,QAAQ,IAAI,YAAY;IAIxB;;OAEG;IACH,UAAU,IAAI,OAAO;IAwBrB;;OAEG;IACH,aAAa,IAAI,IAAI;IAmBrB;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAoBjC;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,QAAQ,IAAI;QACV,KAAK,EAAE,YAAY,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B;IAeD,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,gBAAgB;CAIzB;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;gBAEtB,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM;CAOpD;AAED;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;gBAE3C,cAAc,GAAE,qBAA0B;IAItD;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,cAAc;IAS1E;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC;;OAEG;IACH,QAAQ,IAAI,IAAI;IAMhB;;OAEG;IACH,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;CAOnE"}