@juspay/neurolink 1.6.0 → 1.9.0

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

@@ -0,0 +1,190 @@
+/**
+ * NeuroLink MCP (Model Context Protocol) Module
+ *
+ * This module exports the MCP configuration and initialization utilities
+ * for use throughout the application, following Lighthouse's patterns.
+ */
+import { getMCPManager, removeMCPManager } from "./manager.js";
+import { createMCPServer } from "./factory.js";
+import type { NeuroLinkMCPServer } from "./factory.js";
+export { createMCPServer } from "./factory.js";
+export { mcpConfig } from "./config.js";
+export { getMCPManager, removeMCPManager, MCPManager } from "./manager.js";
+export { createMCPClient } from "./client.js";
+export { initializeMCPTools, getAllAvailableTools, initializeServerTools, } from "./initialize-tools.js";
+export type { NeuroLinkMCPServer, NeuroLinkMCPTool, NeuroLinkExecutionContext, ToolResult, MCPServerCategory, MCPServerConfig, } from "./factory.js";
+export type { MCPClientConfig } from "./client.js";
+/**
+ * MCP utilities for system-wide operations
+ */
+export declare const MCPUtils: {
+    /**
+     * Get a formatted list of all available tools across all registered MCP servers
+     * Useful for documentation or configuration UI
+     */
+    getAvailableTools: () => Promise<{
+        serverId: string;
+        serverTitle: string;
+        serverDescription: string | undefined;
+        category: import("./factory.js").MCPServerCategory | undefined;
+        toolCount: number;
+        tools: {
+            name: string;
+            description: string;
+            isImplemented: boolean;
+        }[];
+    }[]>;
+    /**
+     * Function to test connectivity with MCP servers
+     * Returns diagnostics about the MCP server initialization status
+     */
+    testConnectivity: () => Promise<{
+        status: string;
+        message: string;
+        servers: {
+            serverId: string;
+            serverTitle: string;
+            status: string;
+            toolCount: number;
+            implementedTools: number;
+        }[];
+        timestamp: string;
+    } | {
+        status: string;
+        message: string;
+        timestamp: string;
+        servers?: undefined;
+    }>;
+    /**
+     * Get statistics about MCP usage
+     */
+    getStatistics: () => Promise<{
+        servers: {
+            total: number;
+            byCategory: Record<string, number>;
+        };
+        tools: {
+            totalTools: number;
+            implementedTools: number;
+            byCategory: Record<string, number>;
+        };
+        sessions: {
+            instanceCount: number;
+            maxInstances: number;
+            instances: Record<string, any>;
+        };
+    }>;
+    /**
+     * Initialize MCP for a session
+     * Convenience method that sets up everything needed for a session
+     */
+    initializeSession: (sessionId: string, config?: {
+        userId?: string;
+        aiProvider?: string;
+        modelId?: string;
+    }) => Promise<{
+        sessionId: string;
+        client: import("./client.js").NeuroLinkMCPClient;
+        context: import("./factory.js").NeuroLinkExecutionContext;
+        toolCount: number;
+    }>;
+    /**
+     * Clean up a session
+     */
+    cleanupSession: (sessionId: string) => Promise<boolean>;
+};
+/**
+ * Default export for convenience
+ */
+declare const _default: {
+    config: {
+        getServers: () => Promise<NeuroLinkMCPServer[]>;
+        getAllTools: () => Promise<{
+            name: string;
+            description: string;
+            serverId: string;
+            serverTitle: string;
+            category?: string;
+        }[]>;
+    };
+    utils: {
+        /**
+         * Get a formatted list of all available tools across all registered MCP servers
+         * Useful for documentation or configuration UI
+         */
+        getAvailableTools: () => Promise<{
+            serverId: string;
+            serverTitle: string;
+            serverDescription: string | undefined;
+            category: import("./factory.js").MCPServerCategory | undefined;
+            toolCount: number;
+            tools: {
+                name: string;
+                description: string;
+                isImplemented: boolean;
+            }[];
+        }[]>;
+        /**
+         * Function to test connectivity with MCP servers
+         * Returns diagnostics about the MCP server initialization status
+         */
+        testConnectivity: () => Promise<{
+            status: string;
+            message: string;
+            servers: {
+                serverId: string;
+                serverTitle: string;
+                status: string;
+                toolCount: number;
+                implementedTools: number;
+            }[];
+            timestamp: string;
+        } | {
+            status: string;
+            message: string;
+            timestamp: string;
+            servers?: undefined;
+        }>;
+        /**
+         * Get statistics about MCP usage
+         */
+        getStatistics: () => Promise<{
+            servers: {
+                total: number;
+                byCategory: Record<string, number>;
+            };
+            tools: {
+                totalTools: number;
+                implementedTools: number;
+                byCategory: Record<string, number>;
+            };
+            sessions: {
+                instanceCount: number;
+                maxInstances: number;
+                instances: Record<string, any>;
+            };
+        }>;
+        /**
+         * Initialize MCP for a session
+         * Convenience method that sets up everything needed for a session
+         */
+        initializeSession: (sessionId: string, config?: {
+            userId?: string;
+            aiProvider?: string;
+            modelId?: string;
+        }) => Promise<{
+            sessionId: string;
+            client: import("./client.js").NeuroLinkMCPClient;
+            context: import("./factory.js").NeuroLinkExecutionContext;
+            toolCount: number;
+        }>;
+        /**
+         * Clean up a session
+         */
+        cleanupSession: (sessionId: string) => Promise<boolean>;
+    };
+    createServer: typeof createMCPServer;
+    getManager: typeof getMCPManager;
+    removeManager: typeof removeMCPManager;
+};
+export default _default;

package/dist/lib/mcp/index.js

@@ -0,0 +1,156 @@
+/**
+ * NeuroLink MCP (Model Context Protocol) Module
+ *
+ * This module exports the MCP configuration and initialization utilities
+ * for use throughout the application, following Lighthouse's patterns.
+ */
+import { mcpConfig } from "./config.js";
+import { getMCPManager, removeMCPManager, MCPManager } from "./manager.js";
+import { initializeMCPTools, } from "./initialize-tools.js";
+import { createMCPServer } from "./factory.js";
+import { logger } from "../utils/logger.js";
+// Re-export core components
+export { createMCPServer } from "./factory.js";
+export { mcpConfig } from "./config.js";
+export { getMCPManager, removeMCPManager, MCPManager } from "./manager.js";
+export { createMCPClient } from "./client.js";
+export { initializeMCPTools, getAllAvailableTools, initializeServerTools, } from "./initialize-tools.js";
+/**
+ * MCP utilities for system-wide operations
+ */
+export const MCPUtils = {
+    /**
+     * Get a formatted list of all available tools across all registered MCP servers
+     * Useful for documentation or configuration UI
+     */
+    getAvailableTools: async () => {
+        const servers = await mcpConfig.getServers();
+        return servers.map((server) => ({
+            serverId: server.id,
+            serverTitle: server.title,
+            serverDescription: server.description,
+            category: server.category,
+            toolCount: Object.keys(server.tools).length,
+            tools: Object.entries(server.tools).map(([name, tool]) => ({
+                name,
+                description: tool.description,
+                isImplemented: tool.isImplemented !== false,
+            })),
+        }));
+    },
+    /**
+     * Function to test connectivity with MCP servers
+     * Returns diagnostics about the MCP server initialization status
+     */
+    testConnectivity: async () => {
+        try {
+            const servers = await mcpConfig.getServers();
+            const results = servers.map((server) => ({
+                serverId: server.id,
+                serverTitle: server.title,
+                status: "connected",
+                toolCount: Object.keys(server.tools).length,
+                implementedTools: Object.values(server.tools).filter((tool) => tool.isImplemented !== false).length,
+            }));
+            const totalToolCount = results.reduce((acc, server) => acc + server.toolCount, 0);
+            const totalImplemented = results.reduce((acc, server) => acc + server.implementedTools, 0);
+            logger.info("[MCP Utils] Connectivity test successful", {
+                serverCount: results.length,
+                totalToolCount,
+                totalImplemented,
+            });
+            return {
+                status: "ok",
+                message: `Connected to ${results.length} MCP servers with ${totalToolCount} total tools (${totalImplemented} implemented)`,
+                servers: results,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error";
+            logger.error("[MCP Utils] Connectivity test failed", {
+                error: errorMessage,
+            });
+            return {
+                status: "error",
+                message: `Failed to connect to MCP servers: ${errorMessage}`,
+                timestamp: new Date().toISOString(),
+            };
+        }
+    },
+    /**
+     * Get statistics about MCP usage
+     */
+    getStatistics: async () => {
+        const servers = await mcpConfig.getServers();
+        const managerStats = MCPManager.getAllStats();
+        const toolStats = servers.reduce((acc, server) => {
+            const tools = Object.values(server.tools);
+            acc.totalTools += tools.length;
+            acc.implementedTools += tools.filter((t) => t.isImplemented !== false).length;
+            // Count by category
+            if (server.category) {
+                acc.byCategory[server.category] =
+                    (acc.byCategory[server.category] || 0) + tools.length;
+            }
+            return acc;
+        }, {
+            totalTools: 0,
+            implementedTools: 0,
+            byCategory: {},
+        });
+        return {
+            servers: {
+                total: servers.length,
+                byCategory: servers.reduce((acc, server) => {
+                    const category = server.category || "custom";
+                    acc[category] = (acc[category] || 0) + 1;
+                    return acc;
+                }, {}),
+            },
+            tools: toolStats,
+            sessions: managerStats,
+        };
+    },
+    /**
+     * Initialize MCP for a session
+     * Convenience method that sets up everything needed for a session
+     */
+    initializeSession: async (sessionId, config) => {
+        // Get or create MCP client for session
+        const client = getMCPManager(sessionId, config);
+        // Create context for tool execution
+        const context = {
+            sessionId,
+            userId: config?.userId,
+            aiProvider: config?.aiProvider,
+            modelId: config?.modelId,
+            timestamp: Date.now(),
+        };
+        // Initialize all tools
+        initializeMCPTools(sessionId, client, context);
+        // Return session info
+        return {
+            sessionId,
+            client,
+            context,
+            toolCount: Object.keys(client.getTools()).length,
+        };
+    },
+    /**
+     * Clean up a session
+     */
+    cleanupSession: async (sessionId) => {
+        return removeMCPManager(sessionId);
+    },
+};
+/**
+ * Default export for convenience
+ */
+export default {
+    config: mcpConfig,
+    utils: MCPUtils,
+    createServer: createMCPServer,
+    getManager: getMCPManager,
+    removeManager: removeMCPManager,
+};

package/dist/lib/mcp/initialize-tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * NeuroLink MCP Tool Initialization
+ * Following Lighthouse's pattern for registering MCP server tools with the client
+ */
+import type { NeuroLinkMCPClient } from "./client.js";
+import type { NeuroLinkExecutionContext } from "./factory.js";
+/**
+ * Initialize and register tools from MCP Servers with the MCP client
+ * Following Lighthouse's pattern for tool registration
+ */
+export declare const initializeMCPTools: (sessionId: string, client: NeuroLinkMCPClient, context: NeuroLinkExecutionContext) => Promise<void>;
+/**
+ * Get all available tools across all servers
+ * Useful for documentation and discovery
+ */
+export declare function getAllAvailableTools(): Promise<Array<{
+    serverId: string;
+    serverTitle: string;
+    toolName: string;
+    namespacedName: string;
+    description: string;
+    isImplemented: boolean;
+}>>;
+/**
+ * Initialize tools for a specific server only
+ * Useful for selective tool registration
+ */
+export declare function initializeServerTools(serverId: string, client: NeuroLinkMCPClient, context: NeuroLinkExecutionContext): Promise<number>;

package/dist/lib/mcp/initialize-tools.js

@@ -0,0 +1,209 @@
+/**
+ * NeuroLink MCP Tool Initialization
+ * Following Lighthouse's pattern for registering MCP server tools with the client
+ */
+import { mcpConfig } from "./config.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { logger } from "../utils/logger.js";
+/**
+ * Sanitize tool name for compatibility
+ * Following Lighthouse's pattern of ensuring valid tool names
+ */
+const sanitizeToolName = (name) => {
+    return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+};
+/**
+ * Check if a schema is a Zod schema
+ */
+const isZodSchema = (schema) => {
+    if (typeof schema !== "object" || schema === null) {
+        return false;
+    }
+    return "_def" in schema || "parse" in schema;
+};
+/**
+ * Initialize and register tools from MCP Servers with the MCP client
+ * Following Lighthouse's pattern for tool registration
+ */
+export const initializeMCPTools = async (sessionId, client, context) => {
+    try {
+        logger.info(`[MCP Tools] Initializing tools for session: ${sessionId}`);
+        // Get all registered servers
+        const servers = await mcpConfig.getServers();
+        if (!servers || servers.length === 0) {
+            logger.warn("[MCP Tools] No MCP servers found to register tools from");
+            return;
+        }
+        let totalToolsRegistered = 0;
+        // Process each server
+        servers.forEach((server) => {
+            if (!server || !server.id || !server.tools) {
+                logger.warn(`[MCP Tools] Skipping invalid server configuration: ${JSON.stringify(server)}`);
+                return;
+            }
+            const serverId = server.id;
+            logger.info(`[MCP Tools] Registering tools from server: ${serverId}`);
+            // Process each tool in the server
+            Object.entries(server.tools).forEach(([originalToolName, tool]) => {
+                if (!tool || typeof tool.execute !== "function") {
+                    logger.warn(`[MCP Tools] Skipping invalid tool definition for ${originalToolName} in server ${serverId}`);
+                    return;
+                }
+                // Create namespaced tool name (serverId_toolName)
+                let finalToolName = originalToolName;
+                const prefix = `${serverId}_`;
+                const maxToolNameLength = 64 - prefix.length;
+                // Truncate if necessary
+                if (finalToolName.length > maxToolNameLength) {
+                    finalToolName = finalToolName.substring(0, maxToolNameLength);
+                    logger.info(`[MCP Tools] Truncated tool name: ${originalToolName} -> ${finalToolName}`);
+                }
+                // Sanitize and combine
+                const namespacedToolName = sanitizeToolName(`${prefix}${finalToolName}`);
+                // Validate final length
+                if (namespacedToolName.length > 64) {
+                    logger.warn(`[MCP Tools] Tool name too long after sanitization: ${namespacedToolName}. Skipping.`);
+                    return;
+                }
+                // Prepare description
+                const description = tool.description ||
+                    `Tool ${originalToolName} from server ${serverId}`;
+                // Convert schema if needed
+                let schemaForClient = undefined;
+                if (tool.inputSchema) {
+                    if (isZodSchema(tool.inputSchema)) {
+                        try {
+                            const jsonSchemaOutput = zodToJsonSchema(tool.inputSchema);
+                            if (typeof jsonSchemaOutput === "object" &&
+                                jsonSchemaOutput !== null &&
+                                "type" in jsonSchemaOutput &&
+                                jsonSchemaOutput.type === "object") {
+                                schemaForClient = jsonSchemaOutput;
+                            }
+                            else {
+                                logger.warn(`[MCP Tools] Converted schema for ${originalToolName} is not a root object type`);
+                            }
+                        }
+                        catch (schemaError) {
+                            logger.error(`[MCP Tools] Error converting Zod schema for tool ${originalToolName}: ${schemaError}`);
+                        }
+                    }
+                    else if (typeof tool.inputSchema === "object" &&
+                        tool.inputSchema !== null) {
+                        if (tool.inputSchema.type === "object") {
+                            schemaForClient = tool.inputSchema;
+                        }
+                        else {
+                            logger.warn(`[MCP Tools] Input schema for ${originalToolName} is not type 'object'`);
+                        }
+                    }
+                }
+                try {
+                    // Register tool with client
+                    client.registerTool(namespacedToolName, async (_name, input) => {
+                        // Execute the tool with full context
+                        const result = await tool.execute(input, context);
+                        // Convert to Lighthouse-style response
+                        if (result.success) {
+                            return {
+                                content: [{ text: JSON.stringify(result.data ?? {}) }],
+                            };
+                        }
+                        else {
+                            return {
+                                content: [
+                                    { text: `Error: ${result.error || "Unknown error"}` },
+                                ],
+                                isError: true,
+                            };
+                        }
+                    }, description, schemaForClient);
+                    logger.debug(`[MCP Tools] Registered tool: ${namespacedToolName}`, {
+                        serverId,
+                        originalToolName,
+                    });
+                    totalToolsRegistered++;
+                }
+                catch (registrationError) {
+                    logger.error(`[MCP Tools] Failed to register tool ${originalToolName} from server ${serverId}: ${registrationError}`);
+                }
+            });
+        });
+        logger.info(`[MCP Tools] Successfully registered ${totalToolsRegistered} tools for session: ${sessionId}`);
+    }
+    catch (error) {
+        logger.error(`[MCP Tools] Error during tool initialization for session ${sessionId}: ${error}`);
+    }
+};
+/**
+ * Get all available tools across all servers
+ * Useful for documentation and discovery
+ */
+export async function getAllAvailableTools() {
+    const tools = [];
+    const servers = await mcpConfig.getServers();
+    servers.forEach((server) => {
+        Object.entries(server.tools).forEach(([toolName, tool]) => {
+            const prefix = `${server.id}_`;
+            const finalToolName = toolName.length > 64 - prefix.length
+                ? toolName.substring(0, 64 - prefix.length)
+                : toolName;
+            const namespacedName = sanitizeToolName(`${prefix}${finalToolName}`);
+            tools.push({
+                serverId: server.id,
+                serverTitle: server.title,
+                toolName,
+                namespacedName,
+                description: tool.description || "",
+                isImplemented: tool.isImplemented !== false,
+            });
+        });
+    });
+    return tools;
+}
+/**
+ * Initialize tools for a specific server only
+ * Useful for selective tool registration
+ */
+export async function initializeServerTools(serverId, client, context) {
+    const servers = await mcpConfig.getServers();
+    const server = servers.find((s) => s.id === serverId);
+    if (!server) {
+        logger.warn(`[MCP Tools] Server not found: ${serverId}`);
+        return 0;
+    }
+    let toolsRegistered = 0;
+    Object.entries(server.tools).forEach(([toolName, tool]) => {
+        if (!tool || typeof tool.execute !== "function") {
+            return;
+        }
+        const prefix = `${serverId}_`;
+        const finalToolName = toolName.length > 64 - prefix.length
+            ? toolName.substring(0, 64 - prefix.length)
+            : toolName;
+        const namespacedToolName = sanitizeToolName(`${prefix}${finalToolName}`);
+        if (namespacedToolName.length > 64) {
+            return;
+        }
+        try {
+            client.registerTool(namespacedToolName, async (_name, input) => {
+                const result = await tool.execute(input, context);
+                if (result.success) {
+                    return { content: [{ text: JSON.stringify(result.data ?? {}) }] };
+                }
+                else {
+                    return {
+                        content: [{ text: `Error: ${result.error || "Unknown error"}` }],
+                        isError: true,
+                    };
+                }
+            }, tool.description || `Tool ${toolName} from server ${serverId}`, tool.inputSchema);
+            toolsRegistered++;
+        }
+        catch (error) {
+            logger.error(`[MCP Tools] Failed to register tool ${toolName}: ${error}`);
+        }
+    });
+    logger.info(`[MCP Tools] Registered ${toolsRegistered} tools from server ${serverId}`);
+    return toolsRegistered;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * NeuroLink MCP Initialization System
+ * Automatically registers built-in NeuroLink servers with the default registry
+ * Ensures built-in tools are always available without manual configuration
+ */
+/**
+ * Initialize NeuroLink MCP system by registering built-in servers
+ */
+export declare function initializeNeuroLinkMCP(): Promise<void>;
+/**
+ * Get initialization status
+ */
+export declare function isNeuroLinkMCPInitialized(): boolean;
+/**
+ * Reset initialization status (for testing)
+ */
+export declare function resetInitialization(): void;

package/dist/lib/mcp/initialize.js

@@ -0,0 +1,51 @@
+/**
+ * NeuroLink MCP Initialization System
+ * Automatically registers built-in NeuroLink servers with the default registry
+ * Ensures built-in tools are always available without manual configuration
+ */
+import { defaultToolRegistry } from "./registry.js";
+import { mcpLogger } from "./logging.js";
+let isInitialized = false;
+/**
+ * Initialize NeuroLink MCP system by registering built-in servers
+ */
+export async function initializeNeuroLinkMCP() {
+    if (isInitialized) {
+        return;
+    }
+    mcpLogger.debug("Initializing built-in MCP servers...");
+    try {
+        // Import utility server dynamically to avoid circular dependencies
+        // Note: AI core server temporarily disabled due to circular dependency issues
+        const { utilityServer } = await import("./servers/utilities/utility-server.js");
+        // Register built-in NeuroLink servers with default registry
+        await defaultToolRegistry.registerServer(utilityServer);
+        mcpLogger.debug("Registered neurolink-utility server with built-in tools");
+        // TODO: Re-enable AI core server once circular dependencies are resolved
+        // const { aiCoreServer } = await import('./servers/ai-providers/ai-core-server.js');
+        // await defaultToolRegistry.registerServer(aiCoreServer);
+        // mcpLogger.debug('Registered neurolink-ai-core server with AI tools');
+        const stats = defaultToolRegistry.getStats();
+        mcpLogger.info(`Initialization complete: ${stats.totalServers} servers, ${stats.totalTools} tools available`);
+        isInitialized = true;
+    }
+    catch (error) {
+        mcpLogger.error("Failed to initialize built-in servers:", error instanceof Error ? error.message : String(error));
+        throw error;
+    }
+}
+/**
+ * Get initialization status
+ */
+export function isNeuroLinkMCPInitialized() {
+    return isInitialized;
+}
+/**
+ * Reset initialization status (for testing)
+ */
+export function resetInitialization() {
+    isInitialized = false;
+    defaultToolRegistry.clear();
+}
+// Note: Auto-initialization removed to prevent circular dependencies
+// Call initializeNeuroLinkMCP() explicitly where needed