@wundr.io/mcp-registry 1.0.12 → 1.0.14

package/dist/aggregator.d.ts

@@ -0,0 +1,394 @@
+/**
+ * @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
+ */
+import { EventEmitter } from 'eventemitter3';
+import type { MCPServerRegistry } from './registry';
+import type { ToolInvocationRequest, ToolInvocationResponse, ToolResult, AggregatorConfig, RoutingStrategy, CircuitBreakerState, CircuitBreakerStatus, MCPServerRegistration } from './types';
+/**
+ * Error thrown when no server can handle a tool invocation
+ */
+export declare class NoServerAvailableError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string, message?: string);
+}
+/**
+ * Error thrown when a tool invocation times out
+ */
+export declare class ToolInvocationTimeoutError extends Error {
+    readonly toolName: string;
+    readonly timeoutMs: number;
+    constructor(toolName: string, timeoutMs: number, message?: string);
+}
+/**
+ * Error thrown when circuit breaker is open for a server
+ */
+export declare class CircuitBreakerOpenError extends Error {
+    readonly serverId: string;
+    constructor(serverId: string, message?: string);
+}
+/**
+ * Error thrown when all retry attempts are exhausted
+ */
+export declare class RetryExhaustedError extends Error {
+    readonly toolName: string;
+    readonly attempts: number;
+    readonly lastError: Error;
+    constructor(toolName: string, attempts: number, lastError: Error, message?: string);
+}
+/**
+ * Error thrown when the target server has no registered transport and is not connected
+ */
+export declare class ServerNotConnectedError extends Error {
+    readonly serverId: string;
+    readonly serverName: string;
+    constructor(serverId: string, serverName: string, message?: string);
+}
+/**
+ * Event map for aggregator events
+ */
+export interface AggregatorEvents {
+    'request:started': (event: RequestEvent) => void;
+    'request:completed': (event: RequestEvent) => void;
+    'request:failed': (event: RequestEvent) => void;
+    'request:retried': (event: RequestEvent) => void;
+    'circuit:opened': (event: CircuitEvent) => void;
+    'circuit:closed': (event: CircuitEvent) => void;
+    'circuit:half-open': (event: CircuitEvent) => void;
+}
+/**
+ * Request event data
+ */
+export interface RequestEvent {
+    readonly requestId: string;
+    readonly toolName: string;
+    readonly serverId?: string;
+    readonly durationMs?: number;
+    readonly error?: Error;
+    readonly retryAttempt?: number;
+    readonly timestamp: Date;
+}
+/**
+ * Circuit breaker event data
+ */
+export interface CircuitEvent {
+    readonly serverId: string;
+    readonly previousState: CircuitBreakerState;
+    readonly newState: CircuitBreakerState;
+    readonly timestamp: Date;
+}
+/**
+ * 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',
+ * );
+ * ```
+ */
+export declare class MCPAggregator extends EventEmitter<AggregatorEvents> {
+    private readonly registry;
+    /** Configuration */
+    private readonly config;
+    /** Discovery service */
+    private readonly discovery;
+    /** Circuit breaker states by server ID */
+    private readonly circuitBreakers;
+    /** Round-robin index by tool name */
+    private readonly roundRobinIndex;
+    /** Request counter for generating IDs */
+    private requestCounter;
+    /** Tool handler registry for direct invocation */
+    private readonly toolHandlers;
+    /** Per-server transport registry for remote dispatch */
+    private readonly serverTransports;
+    /**
+     * Creates a new MCPAggregator
+     *
+     * @param registry - The server registry
+     * @param config - Aggregator configuration
+     */
+    constructor(registry: MCPServerRegistry, config?: AggregatorConfig);
+    /**
+     * 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
+     */
+    invoke(request: ToolInvocationRequest): Promise<ToolInvocationResponse>;
+    /**
+     * Invoke a tool with a specific routing strategy
+     *
+     * @param request - Tool invocation request
+     * @param strategy - Routing strategy to use
+     * @returns Tool invocation response
+     */
+    invokeWithStrategy(request: ToolInvocationRequest, strategy: RoutingStrategy): Promise<ToolInvocationResponse>;
+    /**
+     * Invoke multiple tools in parallel
+     *
+     * @param requests - Array of tool invocation requests
+     * @returns Array of tool invocation responses
+     */
+    invokeParallel(requests: readonly ToolInvocationRequest[]): Promise<readonly ToolInvocationResponse[]>;
+    /**
+     * Invoke tools in sequence
+     *
+     * @param requests - Array of tool invocation requests
+     * @returns Array of tool invocation responses
+     */
+    invokeSequential(requests: readonly ToolInvocationRequest[]): Promise<readonly ToolInvocationResponse[]>;
+    /**
+     * Register a direct tool handler (for local execution)
+     *
+     * @param toolName - Tool name
+     * @param handler - Tool handler function
+     */
+    registerToolHandler(toolName: string, handler: ToolHandler): void;
+    /**
+     * Unregister a tool handler
+     *
+     * @param toolName - Tool name
+     */
+    unregisterToolHandler(toolName: string): void;
+    /**
+     * Register a transport for a specific server to enable remote tool dispatch.
+     *
+     * The transport is responsible for forwarding the tool call to the actual
+     * MCP server process over whatever protocol the server uses (stdio, http, etc.).
+     *
+     * @example
+     * ```typescript
+     * aggregator.registerServerTransport(server.id, async (toolName, args) => {
+     *   return myMcpClient.callTool(toolName, args);
+     * });
+     * ```
+     *
+     * @param serverId - Server ID as returned by registry.register()
+     * @param transport - Transport implementation
+     */
+    registerServerTransport(serverId: string, transport: ServerTransport): void;
+    /**
+     * Unregister a server transport
+     *
+     * @param serverId - Server ID
+     */
+    unregisterServerTransport(serverId: string): void;
+    /**
+     * 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
+     */
+    selectServer(toolName: string, strategy: RoutingStrategy, preferredServer?: string): Promise<MCPServerRegistration | undefined>;
+    /**
+     * Select server by highest priority
+     */
+    private selectByPriority;
+    /**
+     * Select server using round-robin
+     */
+    private selectRoundRobin;
+    /**
+     * Select server with lowest latency
+     */
+    private selectByLeastLatency;
+    /**
+     * Select random server
+     */
+    private selectRandom;
+    /**
+     * Select server using health-aware strategy
+     */
+    private selectHealthAware;
+    /**
+     * Check if circuit is open for a server
+     *
+     * @param serverId - Server ID
+     * @returns True if circuit is open
+     */
+    isCircuitOpen(serverId: string): boolean;
+    /**
+     * Get circuit breaker status for a server
+     *
+     * @param serverId - Server ID
+     * @returns Circuit breaker status
+     */
+    getCircuitStatus(serverId: string): CircuitBreakerStatus;
+    /**
+     * Get all circuit breaker statuses
+     *
+     * @returns Array of circuit breaker statuses
+     */
+    getAllCircuitStatuses(): readonly CircuitBreakerStatus[];
+    /**
+     * Manually reset a circuit breaker
+     *
+     * @param serverId - Server ID
+     */
+    resetCircuit(serverId: string): void;
+    /**
+     * Manually open a circuit breaker
+     *
+     * @param serverId - Server ID
+     */
+    openCircuit(serverId: string): void;
+    /**
+     * Record a successful request
+     */
+    private recordSuccess;
+    /**
+     * Record a failed request
+     */
+    private recordFailure;
+    /**
+     * Transition circuit to a new state
+     */
+    private transitionCircuit;
+    /**
+     * Get or create circuit breaker state
+     */
+    private getOrCreateCircuitState;
+    /** Track last attempted server for failure recording */
+    private lastAttemptedServerId?;
+    /**
+     * Execute tool with timeout.
+     *
+     * Dispatch priority:
+     *   1. Local ToolHandler registered via registerToolHandler() - used for
+     *      in-process tools that do not require a remote server.
+     *   2. ServerTransport registered via registerServerTransport() - used to
+     *      forward the call to the actual MCP server over its native protocol.
+     *   3. Neither available - throw ServerNotConnectedError so the caller
+     *      can either register a transport or handle the error explicitly.
+     */
+    private executeWithTimeout;
+    /**
+     * Execute a function with timeout
+     */
+    private executeWithTimeoutInternal;
+    /**
+     * Get the last attempted server ID
+     */
+    private getLastAttemptedServerId;
+    /**
+     * Check if a server provides a tool
+     */
+    private serverProvidesTool;
+    /**
+     * Generate a unique request ID
+     */
+    private generateRequestId;
+    /**
+     * Delay for specified milliseconds
+     */
+    private delay;
+    /**
+     * Emit a request event
+     */
+    private emitRequestEvent;
+    /**
+     * Get aggregator statistics
+     *
+     * @returns Aggregator statistics
+     */
+    getStats(): AggregatorStats;
+    /**
+     * Get the current configuration
+     *
+     * @returns Current aggregator configuration
+     */
+    getConfig(): Readonly<Required<AggregatorConfig>>;
+}
+/**
+ * Tool handler function type for in-process (local) tool execution.
+ */
+export type ToolHandler = (args: Record<string, unknown>) => Promise<ToolResult>;
+/**
+ * Server transport function type for remote tool dispatch.
+ *
+ * Implementors are responsible for serialising the call over the appropriate
+ * protocol (stdio JSON-RPC, HTTP, WebSocket, etc.) and returning a ToolResult.
+ *
+ * @param toolName - The MCP tool name to invoke
+ * @param args - Tool arguments
+ * @param server - Full server registration (transport config, metadata, etc.)
+ * @returns Tool result from the remote server
+ *
+ * @example
+ * ```typescript
+ * // Example using the MCP SDK Client
+ * const transport: ServerTransport = async (toolName, args, server) => {
+ *   const result = await mcpClient.callTool({ name: toolName, arguments: args });
+ *   return {
+ *     content: result.content,
+ *     isError: result.isError ?? false,
+ *     serverId: server.id,
+ *     toolName,
+ *   };
+ * };
+ * aggregator.registerServerTransport(server.id, transport);
+ * ```
+ */
+export type ServerTransport = (toolName: string, args: Record<string, unknown>, server: MCPServerRegistration) => Promise<ToolResult>;
+/**
+ * Aggregator statistics
+ */
+export interface AggregatorStats {
+    /** Number of open circuit breakers */
+    readonly openCircuits: number;
+    /** Number of half-open circuit breakers */
+    readonly halfOpenCircuits: number;
+    /** Number of closed circuit breakers */
+    readonly closedCircuits: number;
+    /** Total requests processed */
+    readonly totalRequests: number;
+    /** Number of registered direct handlers */
+    readonly registeredHandlers: number;
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+export declare function createMCPAggregator(registry: MCPServerRegistry, config?: AggregatorConfig): MCPAggregator;
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/aggregator.d.ts.map

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