@juspay/neurolink 9.27.0 → 9.28.0

package/dist/lib/mcp/mcpServerBase.js

@@ -0,0 +1,374 @@
+/**
+ * MCP Server Base Class
+ *
+ * Abstract base class for creating custom MCP servers with consistent patterns
+ * for tool registration, execution, and lifecycle management.
+ *
+ * Implements Mastra-style MCPServerBase features including:
+ * - Tool annotation support (readOnlyHint, destructiveHint, idempotentHint)
+ * - Lifecycle hooks (onInit, onStart, onStop)
+ * - Event emission for tool operations
+ * - Conversion to MCPServerInfo format
+ *
+ * @module mcp/mcpServerBase
+ * @since 8.39.0
+ */
+import { EventEmitter } from "events";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { ErrorFactory } from "../utils/errorHandling.js";
+/**
+ * Abstract base class for MCP servers
+ *
+ * Provides a foundation for creating custom MCP servers with consistent
+ * patterns for tool registration, execution, and lifecycle management.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomServer extends MCPServerBase {
+ *   constructor() {
+ *     super({
+ *       id: "my-custom-server",
+ *       name: "My Custom Server",
+ *       description: "Provides custom functionality",
+ *       category: "custom",
+ *     });
+ *
+ *     // Register tools in constructor or init
+ *     this.registerTool({
+ *       name: "myTool",
+ *       description: "Does something useful",
+ *       annotations: {
+ *         readOnlyHint: true,
+ *         idempotentHint: true,
+ *       },
+ *       execute: async (params, context) => {
+ *         return { success: true, data: "result" };
+ *       },
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class MCPServerBase extends EventEmitter {
+    config;
+    tools = new Map();
+    isInitialized = false;
+    isRunning = false;
+    constructor(config) {
+        super();
+        // Apply defaults
+        this.config = {
+            id: config.id,
+            name: config.name,
+            description: config.description ?? "",
+            version: config.version ?? "1.0.0",
+            category: config.category ?? "custom",
+            transport: config.transport ?? "stdio",
+            metadata: config.metadata ?? {},
+            defaultTimeoutMs: config.defaultTimeoutMs ?? 30_000,
+            defaultAnnotations: config.defaultAnnotations ?? {},
+        };
+    }
+    /**
+     * Initialize the server
+     * Override in subclasses for async initialization
+     */
+    async init() {
+        if (this.isInitialized) {
+            return;
+        }
+        await this.onInit();
+        this.isInitialized = true;
+        this.emit("serverReady", {
+            tools: Array.from(this.tools.keys()),
+        });
+    }
+    /**
+     * Hook for subclass initialization
+     * Override to perform async setup
+     */
+    async onInit() {
+        // Override in subclasses
+    }
+    /**
+     * Start the server
+     */
+    async start() {
+        if (!this.isInitialized) {
+            await this.init();
+        }
+        if (this.isRunning) {
+            return;
+        }
+        await this.onStart();
+        this.isRunning = true;
+    }
+    /**
+     * Hook for subclass start logic
+     */
+    async onStart() {
+        // Override in subclasses
+    }
+    /**
+     * Stop the server
+     */
+    async stop(reason) {
+        if (!this.isRunning) {
+            return;
+        }
+        await this.onStop();
+        this.isRunning = false;
+        this.emit("serverStopped", { reason });
+    }
+    /**
+     * Hook for subclass stop logic
+     */
+    async onStop() {
+        // Override in subclasses
+    }
+    /**
+     * Register a tool with the server
+     */
+    registerTool(tool) {
+        // Validate tool
+        this.validateTool(tool);
+        // Merge with default annotations
+        const mergedTool = {
+            ...tool,
+            annotations: {
+                ...this.config.defaultAnnotations,
+                ...tool.annotations,
+            },
+        };
+        this.tools.set(tool.name, mergedTool);
+        this.emit("toolRegistered", {
+            toolName: tool.name,
+            tool: mergedTool,
+        });
+        return this;
+    }
+    /**
+     * Register multiple tools at once
+     */
+    registerTools(tools) {
+        for (const tool of tools) {
+            this.registerTool(tool);
+        }
+        return this;
+    }
+    /**
+     * Validate tool configuration
+     */
+    validateTool(tool) {
+        if (!tool.name || typeof tool.name !== "string") {
+            throw ErrorFactory.invalidConfiguration("tool.name", "Tool name is required and must be a string");
+        }
+        if (tool.name.length > 64) {
+            throw ErrorFactory.invalidConfiguration("tool.name", "Tool name must be 64 characters or less", { toolName: tool.name });
+        }
+        if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(tool.name)) {
+            throw ErrorFactory.invalidConfiguration("tool.name", "Tool name must start with a letter or underscore and contain only alphanumeric characters, underscores, and hyphens", { toolName: tool.name });
+        }
+        if (!tool.description || typeof tool.description !== "string") {
+            throw ErrorFactory.invalidConfiguration("tool.description", "Tool description is required and must be a string", { toolName: tool.name });
+        }
+        if (typeof tool.execute !== "function") {
+            throw ErrorFactory.invalidConfiguration("tool.execute", "Tool execute function is required", { toolName: tool.name });
+        }
+        if (this.tools.has(tool.name)) {
+            throw ErrorFactory.invalidConfiguration("tool.name", `Tool '${tool.name}' is already registered`, { toolName: tool.name });
+        }
+    }
+    /**
+     * Execute a tool by name
+     */
+    async executeTool(toolName, params, context) {
+        const tool = this.tools.get(toolName);
+        if (!tool) {
+            return {
+                success: false,
+                error: `Tool '${toolName}' not found on server '${this.config.id}'`,
+                metadata: {
+                    toolName,
+                    serverId: this.config.id,
+                },
+            };
+        }
+        const startTime = Date.now();
+        const toolTimeoutMs = this.config.defaultTimeoutMs ?? 30_000;
+        try {
+            const result = await withTimeout(tool.execute(params, context ?? {}), toolTimeoutMs, ErrorFactory.toolTimeout(toolName, toolTimeoutMs).message);
+            const duration = Date.now() - startTime;
+            this.emit("toolExecuted", {
+                toolName,
+                duration,
+                success: true,
+            });
+            // Ensure result conforms to ToolResult
+            if (this.isToolResult(result)) {
+                return {
+                    ...result,
+                    metadata: {
+                        ...result.metadata,
+                        toolName,
+                        serverId: this.config.id,
+                        executionTime: duration,
+                    },
+                };
+            }
+            return {
+                success: true,
+                data: result,
+                metadata: {
+                    toolName,
+                    serverId: this.config.id,
+                    executionTime: duration,
+                },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            this.emit("toolError", {
+                toolName,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+            this.emit("toolExecuted", {
+                toolName,
+                duration,
+                success: false,
+            });
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                metadata: {
+                    toolName,
+                    serverId: this.config.id,
+                    executionTime: duration,
+                },
+            };
+        }
+    }
+    /**
+     * Type guard to check if result is a ToolResult
+     */
+    isToolResult(result) {
+        return (result !== null &&
+            typeof result === "object" &&
+            "success" in result &&
+            typeof result.success === "boolean");
+    }
+    /**
+     * Get all registered tools
+     */
+    getTools() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Get a specific tool by name
+     */
+    getTool(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Check if a tool exists
+     */
+    hasTool(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Remove a tool
+     */
+    removeTool(name) {
+        return this.tools.delete(name);
+    }
+    /**
+     * Get server info in MCPServerInfo format
+     */
+    toServerInfo() {
+        return {
+            id: this.config.id,
+            name: this.config.name,
+            description: this.config.description,
+            transport: this.config.transport,
+            status: this.isRunning ? "connected" : "stopped",
+            tools: this.getTools().map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                execute: (params, context) => this.executeTool(tool.name, params, context),
+            })),
+            metadata: {
+                ...this.config.metadata,
+                category: this.config.category,
+                version: this.config.version,
+            },
+        };
+    }
+    /**
+     * Get tools filtered by annotations
+     */
+    getToolsByAnnotation(annotation, value) {
+        return this.getTools().filter((tool) => {
+            const annotationValue = tool.annotations?.[annotation];
+            if (Array.isArray(value) && Array.isArray(annotationValue)) {
+                return value.some((v) => annotationValue.includes(v));
+            }
+            return annotationValue === value;
+        });
+    }
+    /**
+     * Get read-only tools
+     */
+    getReadOnlyTools() {
+        return this.getToolsByAnnotation("readOnlyHint", true);
+    }
+    /**
+     * Get destructive tools
+     */
+    getDestructiveTools() {
+        return this.getToolsByAnnotation("destructiveHint", true);
+    }
+    /**
+     * Get idempotent tools
+     */
+    getIdempotentTools() {
+        return this.getToolsByAnnotation("idempotentHint", true);
+    }
+    /**
+     * Get tools that require confirmation
+     */
+    getToolsRequiringConfirmation() {
+        return this.getToolsByAnnotation("requiresConfirmation", true);
+    }
+    /**
+     * Server identification
+     */
+    get id() {
+        return this.config.id;
+    }
+    get name() {
+        return this.config.name;
+    }
+    get description() {
+        return this.config.description;
+    }
+    get version() {
+        return this.config.version;
+    }
+    get category() {
+        return this.config.category;
+    }
+    /**
+     * Check if server is initialized
+     */
+    get initialized() {
+        return this.isInitialized;
+    }
+    /**
+     * Check if server is running
+     */
+    get running() {
+        return this.isRunning;
+    }
+}
+//# sourceMappingURL=mcpServerBase.js.map

package/dist/lib/mcp/multiServerManager.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Multi-Server Manager
+ *
+ * Coordinates multiple MCP servers with load balancing, failover,
+ * and unified tool discovery across all registered servers.
+ *
+ * Features:
+ * - Load balancing strategies (round-robin, least-loaded, random)
+ * - Health-aware routing
+ * - Automatic failover
+ * - Unified tool namespace management
+ * - Cross-server tool discovery
+ *
+ * @module mcp/multiServerManager
+ * @since 8.39.0
+ */
+import { EventEmitter } from "events";
+import type { MCPServerInfo } from "../types/mcpTypes.js";
+import type { JsonObject } from "../types/common.js";
+/**
+ * Load balancing strategies
+ */
+export type LoadBalancingStrategy = "round-robin" | "least-loaded" | "random" | "weighted" | "failover-only";
+/**
+ * Server weight for weighted load balancing
+ */
+export type ServerWeight = {
+    serverId: string;
+    weight: number;
+    priority: number;
+};
+/**
+ * Server group definition
+ */
+export type ServerGroup = {
+    /**
+     * Group identifier
+     */
+    id: string;
+    /**
+     * Human-readable name
+     */
+    name: string;
+    /**
+     * Description of the group
+     */
+    description?: string;
+    /**
+     * Server IDs in this group
+     */
+    servers: string[];
+    /**
+     * Load balancing strategy for this group
+     */
+    strategy: LoadBalancingStrategy;
+    /**
+     * Weights for weighted strategy
+     */
+    weights?: ServerWeight[];
+    /**
+     * Whether to enable health-aware routing
+     */
+    healthAware?: boolean;
+    /**
+     * Minimum healthy servers before alerting
+     */
+    minHealthyServers?: number;
+};
+/**
+ * Unified tool entry from multiple servers
+ */
+export type UnifiedTool = {
+    /**
+     * Tool name
+     */
+    name: string;
+    /**
+     * Tool description
+     */
+    description: string;
+    /**
+     * Servers that provide this tool
+     */
+    servers: Array<{
+        serverId: string;
+        serverName: string;
+        inputSchema?: JsonObject;
+        priority: number;
+    }>;
+    /**
+     * Whether this tool has naming conflicts
+     */
+    hasConflict: boolean;
+    /**
+     * Preferred server for this tool
+     */
+    preferredServerId?: string;
+};
+/**
+ * Multi-server manager configuration
+ */
+export type MultiServerManagerConfig = {
+    /**
+     * Default load balancing strategy
+     */
+    defaultStrategy?: LoadBalancingStrategy;
+    /**
+     * Enable health-aware routing by default
+     */
+    healthAwareRouting?: boolean;
+    /**
+     * Health check interval in milliseconds
+     */
+    healthCheckInterval?: number;
+    /**
+     * Maximum retries on failover
+     */
+    maxFailoverRetries?: number;
+    /**
+     * Tool namespace separator
+     */
+    namespaceSeparator?: string;
+    /**
+     * Enable automatic tool namespace prefixing
+     */
+    autoNamespace?: boolean;
+    /**
+     * Conflict resolution strategy.
+     * Reserved for future conflict resolution strategy — currently stored but not
+     * consumed by any routing or tool-merge logic.
+     */
+    conflictResolution?: "first-wins" | "last-wins" | "namespace" | "explicit";
+};
+/**
+ * Server metrics for load balancing
+ */
+type ServerMetrics = {
+    activeRequests: number;
+    totalRequests: number;
+    completedRequests: number;
+    averageResponseTime: number;
+    errorRate: number;
+    lastHealthCheck?: Date;
+    isHealthy: boolean;
+};
+/**
+ * Multi-Server Manager
+ *
+ * Coordinates multiple MCP servers for unified tool access
+ * with load balancing and failover capabilities.
+ *
+ * @example
+ * ```typescript
+ * const manager = new MultiServerManager({
+ *   defaultStrategy: "round-robin",
+ *   healthAwareRouting: true,
+ *   autoNamespace: true,
+ * });
+ *
+ * // Add servers
+ * manager.addServer(server1Info);
+ * manager.addServer(server2Info);
+ *
+ * // Create a group for redundant servers
+ * manager.createGroup({
+ *   id: "data-servers",
+ *   name: "Data Processing Servers",
+ *   servers: ["server1", "server2"],
+ *   strategy: "least-loaded",
+ * });
+ *
+ * // Get unified tool list
+ * const tools = manager.getUnifiedTools();
+ *
+ * // Execute with automatic routing
+ * const result = await manager.executeTool("readFile", { path: "/data" });
+ * ```
+ */
+export declare class MultiServerManager extends EventEmitter {
+    private config;
+    private servers;
+    private groups;
+    private metrics;
+    private roundRobinCounters;
+    private toolPreferences;
+    constructor(config?: MultiServerManagerConfig);
+    /**
+     * Add a server to the manager
+     */
+    addServer(server: MCPServerInfo): void;
+    /**
+     * Remove a server from the manager
+     */
+    removeServer(serverId: string): boolean;
+    /**
+     * Update server info
+     */
+    updateServer(serverId: string, updates: Partial<MCPServerInfo>): void;
+    /**
+     * Create a server group
+     */
+    createGroup(group: ServerGroup): void;
+    /**
+     * Remove a server group
+     */
+    removeGroup(groupId: string): boolean;
+    /**
+     * Add a server to a group
+     */
+    addServerToGroup(serverId: string, groupId: string): void;
+    /**
+     * Remove a server from a group
+     */
+    removeServerFromGroup(serverId: string, groupId: string): boolean;
+    /**
+     * Get unified tool list from all servers
+     */
+    getUnifiedTools(): UnifiedTool[];
+    /**
+     * Get namespaced tools (server.toolName format)
+     */
+    getNamespacedTools(): Array<{
+        fullName: string;
+        toolName: string;
+        serverId: string;
+        serverName: string;
+        description: string;
+        inputSchema?: JsonObject;
+    }>;
+    /**
+     * Set tool preference for routing
+     */
+    setToolPreference(toolName: string, serverId: string): void;
+    /**
+     * Clear tool preference
+     */
+    clearToolPreference(toolName: string): void;
+    /**
+     * Select a server for a tool using load balancing
+     */
+    selectServer(toolName: string, groupId?: string): {
+        serverId: string;
+        server: MCPServerInfo;
+    } | null;
+    /**
+     * Apply load balancing strategy
+     */
+    private applyStrategy;
+    /**
+     * Get server priority (lower = higher priority)
+     *
+     * @param serverId - The server to look up
+     * @param groupId - Optional group to scope the lookup to, avoiding
+     *   nondeterministic iteration across all groups.
+     */
+    private getServerPriority;
+    /**
+     * Update server metrics
+     */
+    updateMetrics(serverId: string, updates: Partial<ServerMetrics>): void;
+    /**
+     * Mark request started
+     */
+    requestStarted(serverId: string): void;
+    /**
+     * Mark request completed
+     */
+    requestCompleted(serverId: string, duration: number, success: boolean): void;
+    /**
+     * Get all servers
+     */
+    getServers(): MCPServerInfo[];
+    /**
+     * Get server by ID
+     */
+    getServer(serverId: string): MCPServerInfo | undefined;
+    /**
+     * Get all groups
+     */
+    getGroups(): ServerGroup[];
+    /**
+     * Get group by ID
+     */
+    getGroup(groupId: string): ServerGroup | undefined;
+    /**
+     * Get server metrics
+     */
+    getServerMetrics(serverId: string): ServerMetrics | undefined;
+    /**
+     * Get all metrics
+     */
+    getAllMetrics(): Map<string, ServerMetrics>;
+    /**
+     * Get statistics
+     */
+    getStatistics(): {
+        totalServers: number;
+        healthyServers: number;
+        totalGroups: number;
+        totalTools: number;
+        conflictingTools: number;
+        totalRequests: number;
+        activeRequests: number;
+    };
+}
+/**
+ * Global multi-server manager instance
+ */
+export declare const globalMultiServerManager: MultiServerManager;
+export {};