@wundr.io/mcp-registry 1.0.3

package/dist/aggregator.js

@@ -0,0 +1,708 @@
+"use strict";
+/**
+ * @wundr.io/mcp-registry - MCP Aggregator (Super MCP)
+ *
+ * Implements the Super MCP pattern for routing requests to appropriate
+ * servers based on capabilities, health, and configured routing strategies.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPAggregator = exports.RetryExhaustedError = exports.CircuitBreakerOpenError = exports.ToolInvocationTimeoutError = exports.NoServerAvailableError = void 0;
+exports.createMCPAggregator = createMCPAggregator;
+const eventemitter3_1 = require("eventemitter3");
+const discovery_1 = require("./discovery");
+const types_1 = require("./types");
+// =============================================================================
+// Aggregator Error Types
+// =============================================================================
+/**
+ * Error thrown when no server can handle a tool invocation
+ */
+class NoServerAvailableError extends Error {
+    toolName;
+    constructor(toolName, message) {
+        super(message ?? `No server available for tool: ${toolName}`);
+        this.toolName = toolName;
+        this.name = 'NoServerAvailableError';
+    }
+}
+exports.NoServerAvailableError = NoServerAvailableError;
+/**
+ * Error thrown when a tool invocation times out
+ */
+class ToolInvocationTimeoutError extends Error {
+    toolName;
+    timeoutMs;
+    constructor(toolName, timeoutMs, message) {
+        super(message ?? `Tool invocation timed out after ${timeoutMs}ms: ${toolName}`);
+        this.toolName = toolName;
+        this.timeoutMs = timeoutMs;
+        this.name = 'ToolInvocationTimeoutError';
+    }
+}
+exports.ToolInvocationTimeoutError = ToolInvocationTimeoutError;
+/**
+ * Error thrown when circuit breaker is open for a server
+ */
+class CircuitBreakerOpenError extends Error {
+    serverId;
+    constructor(serverId, message) {
+        super(message ?? `Circuit breaker open for server: ${serverId}`);
+        this.serverId = serverId;
+        this.name = 'CircuitBreakerOpenError';
+    }
+}
+exports.CircuitBreakerOpenError = CircuitBreakerOpenError;
+/**
+ * Error thrown when all retry attempts are exhausted
+ */
+class RetryExhaustedError extends Error {
+    toolName;
+    attempts;
+    lastError;
+    constructor(toolName, attempts, lastError, message) {
+        super(message ??
+            `All ${attempts} retry attempts exhausted for tool: ${toolName}`);
+        this.toolName = toolName;
+        this.attempts = attempts;
+        this.lastError = lastError;
+        this.name = 'RetryExhaustedError';
+    }
+}
+exports.RetryExhaustedError = RetryExhaustedError;
+// =============================================================================
+// MCPAggregator Class
+// =============================================================================
+/**
+ * MCP Aggregator (Super MCP Pattern)
+ *
+ * Routes tool invocation requests to appropriate servers based on
+ * capabilities, health status, and configured routing strategies.
+ * Implements circuit breaker pattern for fault tolerance.
+ *
+ * @example
+ * ```typescript
+ * const aggregator = new MCPAggregator(registry, {
+ *   defaultStrategy: 'health-aware',
+ *   enableRetries: true,
+ *   maxRetries: 3,
+ *   enableCircuitBreaker: true,
+ * });
+ *
+ * // Invoke a tool
+ * const response = await aggregator.invoke({
+ *   name: 'drift_detection',
+ *   arguments: { action: 'detect' },
+ * });
+ *
+ * // Use specific routing strategy
+ * const response = await aggregator.invokeWithStrategy(
+ *   { name: 'my-tool' },
+ *   'least-latency',
+ * );
+ * ```
+ */
+class MCPAggregator extends eventemitter3_1.EventEmitter {
+    registry;
+    /** Configuration */
+    config;
+    /** Discovery service */
+    discovery;
+    /** Circuit breaker states by server ID */
+    circuitBreakers;
+    /** Round-robin index by tool name */
+    roundRobinIndex;
+    /** Request counter for generating IDs */
+    requestCounter;
+    /** Tool handler registry for direct invocation */
+    toolHandlers;
+    /**
+     * Creates a new MCPAggregator
+     *
+     * @param registry - The server registry
+     * @param config - Aggregator configuration
+     */
+    constructor(registry, config = {}) {
+        super();
+        this.registry = registry;
+        // Validate and merge config with defaults
+        const validation = types_1.AggregatorConfigSchema.safeParse(config);
+        if (!validation.success) {
+            throw new Error(`Invalid aggregator config: ${validation.error.message}`);
+        }
+        this.config = {
+            defaultStrategy: config.defaultStrategy ?? 'health-aware',
+            requestTimeout: config.requestTimeout ?? 30000,
+            enableRetries: config.enableRetries ?? true,
+            maxRetries: config.maxRetries ?? 3,
+            retryDelay: config.retryDelay ?? 1000,
+            enableCircuitBreaker: config.enableCircuitBreaker ?? true,
+            circuitBreakerThreshold: config.circuitBreakerThreshold ?? 5,
+            circuitBreakerResetTimeout: config.circuitBreakerResetTimeout ?? 60000,
+            healthMonitor: config.healthMonitor ?? {},
+        };
+        this.discovery = (0, discovery_1.createServerDiscoveryService)(registry);
+        this.circuitBreakers = new Map();
+        this.roundRobinIndex = new Map();
+        this.requestCounter = 0;
+        this.toolHandlers = new Map();
+    }
+    // ===========================================================================
+    // Tool Invocation Methods
+    // ===========================================================================
+    /**
+     * Invoke a tool using the default routing strategy
+     *
+     * @param request - Tool invocation request
+     * @returns Tool invocation response
+     * @throws {NoServerAvailableError} If no server can handle the tool
+     * @throws {ToolInvocationTimeoutError} If the invocation times out
+     * @throws {RetryExhaustedError} If all retries are exhausted
+     */
+    async invoke(request) {
+        return this.invokeWithStrategy(request, this.config.defaultStrategy);
+    }
+    /**
+     * Invoke a tool with a specific routing strategy
+     *
+     * @param request - Tool invocation request
+     * @param strategy - Routing strategy to use
+     * @returns Tool invocation response
+     */
+    async invokeWithStrategy(request, strategy) {
+        const requestId = this.generateRequestId();
+        const startTime = Date.now();
+        let retryAttempts = 0;
+        let lastError;
+        // Emit request started event
+        this.emitRequestEvent('request:started', requestId, request.name);
+        while (retryAttempts <= (this.config.enableRetries ? this.config.maxRetries : 0)) {
+            try {
+                // Select server based on strategy
+                const server = await this.selectServer(request.name, strategy, request.preferredServer);
+                if (!server) {
+                    throw new NoServerAvailableError(request.name);
+                }
+                // Check circuit breaker
+                if (this.config.enableCircuitBreaker && this.isCircuitOpen(server.id)) {
+                    // Try next server
+                    throw new CircuitBreakerOpenError(server.id);
+                }
+                // Execute the tool
+                const result = await this.executeWithTimeout(request, server, request.timeout ?? this.config.requestTimeout);
+                const durationMs = Date.now() - startTime;
+                // Record success
+                this.recordSuccess(server.id);
+                // Emit completion event
+                this.emitRequestEvent('request:completed', requestId, request.name, server.id, durationMs);
+                return {
+                    result,
+                    serverId: server.id,
+                    latencyMs: durationMs,
+                    retried: retryAttempts > 0,
+                    retryAttempts,
+                };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Record failure for circuit breaker
+                const failedServerId = this.getLastAttemptedServerId();
+                if (failedServerId) {
+                    this.recordFailure(failedServerId);
+                }
+                // Check if we should retry
+                if (this.config.enableRetries &&
+                    retryAttempts < this.config.maxRetries) {
+                    retryAttempts++;
+                    // Emit retry event
+                    this.emitRequestEvent('request:retried', requestId, request.name, undefined, undefined, lastError, retryAttempts);
+                    // Wait before retry
+                    await this.delay(this.config.retryDelay * retryAttempts);
+                }
+                else {
+                    break;
+                }
+            }
+        }
+        // All retries exhausted
+        const durationMs = Date.now() - startTime;
+        this.emitRequestEvent('request:failed', requestId, request.name, undefined, durationMs, lastError);
+        if (retryAttempts > 0) {
+            throw new RetryExhaustedError(request.name, retryAttempts, lastError ?? new Error('Unknown error'));
+        }
+        throw lastError ?? new NoServerAvailableError(request.name);
+    }
+    /**
+     * Invoke multiple tools in parallel
+     *
+     * @param requests - Array of tool invocation requests
+     * @returns Array of tool invocation responses
+     */
+    async invokeParallel(requests) {
+        return Promise.all(requests.map(req => this.invoke(req)));
+    }
+    /**
+     * Invoke tools in sequence
+     *
+     * @param requests - Array of tool invocation requests
+     * @returns Array of tool invocation responses
+     */
+    async invokeSequential(requests) {
+        const results = [];
+        for (const request of requests) {
+            const response = await this.invoke(request);
+            results.push(response);
+        }
+        return results;
+    }
+    // ===========================================================================
+    // Tool Handler Registration
+    // ===========================================================================
+    /**
+     * Register a direct tool handler (for local execution)
+     *
+     * @param toolName - Tool name
+     * @param handler - Tool handler function
+     */
+    registerToolHandler(toolName, handler) {
+        this.toolHandlers.set(toolName, handler);
+    }
+    /**
+     * Unregister a tool handler
+     *
+     * @param toolName - Tool name
+     */
+    unregisterToolHandler(toolName) {
+        this.toolHandlers.delete(toolName);
+    }
+    // ===========================================================================
+    // Server Selection Methods
+    // ===========================================================================
+    /**
+     * Select a server for a tool using the specified strategy
+     *
+     * @param toolName - Tool name
+     * @param strategy - Routing strategy
+     * @param preferredServer - Optional preferred server ID
+     * @returns Selected server or undefined
+     */
+    async selectServer(toolName, strategy, preferredServer) {
+        // Check preferred server first
+        if (preferredServer) {
+            const server = this.registry.get(preferredServer);
+            if (server && this.serverProvidesTool(server, toolName)) {
+                const health = this.registry.getHealthStatus(server.id);
+                if (health?.status !== 'unhealthy' && !this.isCircuitOpen(server.id)) {
+                    return server;
+                }
+            }
+        }
+        // Get all servers that provide the tool
+        const candidates = this.registry.findByTool(toolName);
+        if (candidates.length === 0) {
+            return undefined;
+        }
+        // Filter out unhealthy servers and open circuits
+        const availableServers = candidates.filter(server => {
+            const health = this.registry.getHealthStatus(server.id);
+            const isHealthy = health?.status !== 'unhealthy';
+            const circuitClosed = !this.isCircuitOpen(server.id);
+            return isHealthy && circuitClosed;
+        });
+        if (availableServers.length === 0) {
+            // Fall back to any server if all are unhealthy
+            return candidates[0];
+        }
+        // Apply routing strategy
+        switch (strategy) {
+            case 'priority':
+                return this.selectByPriority(availableServers);
+            case 'round-robin':
+                return this.selectRoundRobin(toolName, availableServers);
+            case 'least-latency':
+                return this.selectByLeastLatency(availableServers);
+            case 'random':
+                return this.selectRandom(availableServers);
+            case 'health-aware':
+                return this.selectHealthAware(availableServers);
+            default:
+                return availableServers[0];
+        }
+    }
+    /**
+     * Select server by highest priority
+     */
+    selectByPriority(servers) {
+        return [...servers].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))[0];
+    }
+    /**
+     * Select server using round-robin
+     */
+    selectRoundRobin(toolName, servers) {
+        const currentIndex = this.roundRobinIndex.get(toolName) ?? 0;
+        const server = servers[currentIndex % servers.length];
+        this.roundRobinIndex.set(toolName, (currentIndex + 1) % servers.length);
+        return server;
+    }
+    /**
+     * Select server with lowest latency
+     */
+    selectByLeastLatency(servers) {
+        return [...servers].sort((a, b) => {
+            const aHealth = this.registry.getHealthStatus(a.id);
+            const bHealth = this.registry.getHealthStatus(b.id);
+            const aLatency = aHealth?.avgLatencyMs ?? Number.MAX_VALUE;
+            const bLatency = bHealth?.avgLatencyMs ?? Number.MAX_VALUE;
+            return aLatency - bLatency;
+        })[0];
+    }
+    /**
+     * Select random server
+     */
+    selectRandom(servers) {
+        const index = Math.floor(Math.random() * servers.length);
+        return servers[index];
+    }
+    /**
+     * Select server using health-aware strategy
+     */
+    selectHealthAware(servers) {
+        // Score each server based on health metrics
+        const scored = servers.map(server => {
+            const health = this.registry.getHealthStatus(server.id);
+            let score = 0;
+            // Health status score
+            switch (health?.status) {
+                case 'healthy':
+                    score += 100;
+                    break;
+                case 'degraded':
+                    score += 50;
+                    break;
+                case 'unhealthy':
+                    score += 0;
+                    break;
+                default:
+                    score += 25;
+            }
+            // Latency score (lower is better)
+            if (health?.avgLatencyMs !== undefined) {
+                score += Math.max(0, 50 - health.avgLatencyMs / 20);
+            }
+            // Error rate penalty
+            if (health?.errorRate !== undefined) {
+                score -= health.errorRate * 100;
+            }
+            // Priority bonus
+            score += (server.priority ?? 0) * 5;
+            return { server, score };
+        });
+        // Sort by score descending and return best
+        scored.sort((a, b) => b.score - a.score);
+        return scored[0].server;
+    }
+    // ===========================================================================
+    // Circuit Breaker Methods
+    // ===========================================================================
+    /**
+     * Check if circuit is open for a server
+     *
+     * @param serverId - Server ID
+     * @returns True if circuit is open
+     */
+    isCircuitOpen(serverId) {
+        const state = this.circuitBreakers.get(serverId);
+        if (!state) {
+            return false;
+        }
+        if (state.state === 'open') {
+            // Check if reset timeout has passed
+            if (state.openedAt) {
+                const elapsed = Date.now() - state.openedAt.getTime();
+                if (elapsed >= this.config.circuitBreakerResetTimeout) {
+                    // Transition to half-open
+                    this.transitionCircuit(serverId, 'half-open');
+                    return false;
+                }
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get circuit breaker status for a server
+     *
+     * @param serverId - Server ID
+     * @returns Circuit breaker status
+     */
+    getCircuitStatus(serverId) {
+        const state = this.circuitBreakers.get(serverId);
+        if (!state) {
+            return {
+                serverId,
+                state: 'closed',
+                failureCount: 0,
+            };
+        }
+        let timeUntilClose;
+        if (state.state === 'open' && state.openedAt) {
+            const elapsed = Date.now() - state.openedAt.getTime();
+            timeUntilClose = Math.max(0, this.config.circuitBreakerResetTimeout - elapsed);
+        }
+        return {
+            serverId,
+            state: state.state,
+            failureCount: state.failureCount,
+            lastFailure: state.lastFailure,
+            timeUntilClose,
+        };
+    }
+    /**
+     * Get all circuit breaker statuses
+     *
+     * @returns Array of circuit breaker statuses
+     */
+    getAllCircuitStatuses() {
+        const statuses = [];
+        for (const serverId of this.registry.getAll().map(s => s.id)) {
+            statuses.push(this.getCircuitStatus(serverId));
+        }
+        return statuses;
+    }
+    /**
+     * Manually reset a circuit breaker
+     *
+     * @param serverId - Server ID
+     */
+    resetCircuit(serverId) {
+        this.circuitBreakers.delete(serverId);
+    }
+    /**
+     * Manually open a circuit breaker
+     *
+     * @param serverId - Server ID
+     */
+    openCircuit(serverId) {
+        this.transitionCircuit(serverId, 'open');
+    }
+    /**
+     * Record a successful request
+     */
+    recordSuccess(serverId) {
+        const state = this.getOrCreateCircuitState(serverId);
+        state.successCount++;
+        state.lastSuccess = new Date();
+        if (state.state === 'half-open') {
+            // Success in half-open state closes the circuit
+            this.transitionCircuit(serverId, 'closed');
+        }
+    }
+    /**
+     * Record a failed request
+     */
+    recordFailure(serverId) {
+        const state = this.getOrCreateCircuitState(serverId);
+        state.failureCount++;
+        state.lastFailure = new Date();
+        if (state.state === 'half-open') {
+            // Failure in half-open state re-opens the circuit
+            this.transitionCircuit(serverId, 'open');
+        }
+        else if (state.failureCount >= this.config.circuitBreakerThreshold) {
+            // Threshold exceeded, open the circuit
+            this.transitionCircuit(serverId, 'open');
+        }
+    }
+    /**
+     * Transition circuit to a new state
+     */
+    transitionCircuit(serverId, newState) {
+        const state = this.getOrCreateCircuitState(serverId);
+        const previousState = state.state;
+        state.state = newState;
+        if (newState === 'open') {
+            state.openedAt = new Date();
+        }
+        else if (newState === 'closed') {
+            state.failureCount = 0;
+            state.openedAt = undefined;
+        }
+        // Emit circuit event
+        const event = {
+            serverId,
+            previousState,
+            newState,
+            timestamp: new Date(),
+        };
+        switch (newState) {
+            case 'open':
+                this.emit('circuit:opened', event);
+                break;
+            case 'closed':
+                this.emit('circuit:closed', event);
+                break;
+            case 'half-open':
+                this.emit('circuit:half-open', event);
+                break;
+        }
+    }
+    /**
+     * Get or create circuit breaker state
+     */
+    getOrCreateCircuitState(serverId) {
+        let state = this.circuitBreakers.get(serverId);
+        if (!state) {
+            state = {
+                state: 'closed',
+                failureCount: 0,
+                successCount: 0,
+            };
+            this.circuitBreakers.set(serverId, state);
+        }
+        return state;
+    }
+    // ===========================================================================
+    // Private Helper Methods
+    // ===========================================================================
+    /** Track last attempted server for failure recording */
+    lastAttemptedServerId;
+    /**
+     * Execute tool with timeout
+     */
+    async executeWithTimeout(request, server, timeoutMs) {
+        this.lastAttemptedServerId = server.id;
+        // Check for local handler first
+        const handler = this.toolHandlers.get(request.name);
+        if (handler) {
+            return this.executeWithTimeoutInternal(() => handler(request.arguments ?? {}), timeoutMs, request.name);
+        }
+        // Default implementation returns a placeholder result
+        // In real implementation, this would use transport to call the server
+        return this.executeWithTimeoutInternal(async () => this.createPlaceholderResult(request, server), timeoutMs, request.name);
+    }
+    /**
+     * Execute a function with timeout
+     */
+    async executeWithTimeoutInternal(fn, timeoutMs, toolName) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new ToolInvocationTimeoutError(toolName, timeoutMs));
+            }, timeoutMs);
+            fn()
+                .then(result => {
+                clearTimeout(timer);
+                resolve(result);
+            })
+                .catch(error => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Create a placeholder result for demonstration
+     */
+    createPlaceholderResult(request, server) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Tool "${request.name}" would be executed on server "${server.name}"`,
+                },
+            ],
+            isError: false,
+            serverId: server.id,
+            toolName: request.name,
+        };
+    }
+    /**
+     * Get the last attempted server ID
+     */
+    getLastAttemptedServerId() {
+        return this.lastAttemptedServerId;
+    }
+    /**
+     * Check if a server provides a tool
+     */
+    serverProvidesTool(server, toolName) {
+        return server.tools.some(tool => tool.name === toolName);
+    }
+    /**
+     * Generate a unique request ID
+     */
+    generateRequestId() {
+        return `req-${++this.requestCounter}-${Date.now()}`;
+    }
+    /**
+     * Delay for specified milliseconds
+     */
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Emit a request event
+     */
+    emitRequestEvent(type, requestId, toolName, serverId, durationMs, error, retryAttempt) {
+        const event = {
+            requestId,
+            toolName,
+            serverId,
+            durationMs,
+            error,
+            retryAttempt,
+            timestamp: new Date(),
+        };
+        this.emit(type, event);
+    }
+    // ===========================================================================
+    // Utility Methods
+    // ===========================================================================
+    /**
+     * Get aggregator statistics
+     *
+     * @returns Aggregator statistics
+     */
+    getStats() {
+        const circuitStatuses = this.getAllCircuitStatuses();
+        return {
+            openCircuits: circuitStatuses.filter(s => s.state === 'open').length,
+            halfOpenCircuits: circuitStatuses.filter(s => s.state === 'half-open')
+                .length,
+            closedCircuits: circuitStatuses.filter(s => s.state === 'closed').length,
+            totalRequests: this.requestCounter,
+            registeredHandlers: this.toolHandlers.size,
+        };
+    }
+    /**
+     * Get the current configuration
+     *
+     * @returns Current aggregator configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+exports.MCPAggregator = MCPAggregator;
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a new MCPAggregator
+ *
+ * @param registry - The server registry
+ * @param config - Optional aggregator configuration
+ * @returns New aggregator instance
+ *
+ * @example
+ * ```typescript
+ * const aggregator = createMCPAggregator(registry, {
+ *   defaultStrategy: 'health-aware',
+ *   enableRetries: true,
+ * });
+ * ```
+ */
+function createMCPAggregator(registry, config) {
+    return new MCPAggregator(registry, config);
+}
+//# sourceMappingURL=aggregator.js.map