@juspay/neurolink 1.10.0 → 1.11.0

package/dist/lib/mcp/client.js

@@ -147,15 +147,15 @@ export class NeuroLinkMCPClient extends EventEmitter {
                 error: `Tool not found: ${toolName}`,
             };
         }
-        // Create full context
-        const fullContext = {
+        // Create full context using createExecutionContext for proper structure
+        const { createExecutionContext } = await import("./context-manager.js");
+        const fullContext = createExecutionContext({
             sessionId: this.config.sessionId,
             userId: this.config.userId,
             aiProvider: this.config.aiProvider,
             modelId: this.config.modelId,
-            timestamp: Date.now(),
             ...context,
-        };
+        });
         // Track execution
         this.executionCount++;
         const executionId = `exec-${this.executionCount}`;

package/dist/lib/mcp/context-manager.js

@@ -23,7 +23,78 @@ export class ContextManager {
         const context = {
             // Session Management
             sessionId,
-            userId: request.userId,
+            userId: request.userId || "unknown-user",
+            // Required ExecutionContext properties
+            secureFS: {
+                readFile: async (path, encoding) => {
+                    const fs = await import("fs/promises");
+                    if (encoding) {
+                        return fs.readFile(path, { encoding: encoding });
+                    }
+                    else {
+                        return fs.readFile(path);
+                    }
+                },
+                writeFile: async (path, content) => {
+                    const fs = await import("fs/promises");
+                    return fs.writeFile(path, content);
+                },
+                readdir: async (path) => {
+                    const fs = await import("fs/promises");
+                    return fs.readdir(path);
+                },
+                stat: async (path) => {
+                    const fs = await import("fs/promises");
+                    return fs.stat(path);
+                },
+                mkdir: async (path, options) => {
+                    const fs = await import("fs/promises");
+                    await fs.mkdir(path, options);
+                },
+                exists: async (path) => {
+                    const fs = await import("fs/promises");
+                    try {
+                        await fs.access(path);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+            },
+            path: {
+                join: (...paths) => {
+                    const path = require("path");
+                    return path.join(...paths);
+                },
+                resolve: (...paths) => {
+                    const path = require("path");
+                    return path.resolve(...paths);
+                },
+                relative: (from, to) => {
+                    const path = require("path");
+                    return path.relative(from, to);
+                },
+                dirname: (path) => {
+                    const pathModule = require("path");
+                    return pathModule.dirname(path);
+                },
+                basename: (path, ext) => {
+                    const pathModule = require("path");
+                    return pathModule.basename(path, ext);
+                },
+            },
+            grantedPermissions: request.permissions || [],
+            log: (level, message, data) => {
+                // Use logger if available, otherwise console
+                try {
+                    const { logger } = require("../utils/logger.js");
+                    logger[level](message, data);
+                }
+                catch {
+                    console[level === "debug" ? "log" : level](message, data);
+                }
+            },
             // AI Provider Context (from existing NeuroLink)
             aiProvider: request.aiProvider,
             modelId: request.modelId,

package/dist/lib/mcp/contracts/mcp-contract.d.ts

@@ -0,0 +1,162 @@
+/**
+ * MCP Abstract Contract - The Foundation of NeuroLink's Plugin Ecosystem
+ * Based on research blueprint for extensible MCP architecture
+ */
+import type { ZodSchema } from "zod";
+/**
+ * Metadata structure for MCP plugins following manifest-based discovery
+ */
+export interface MCPMetadata {
+    /** Unique NPM-style package name */
+    name: string;
+    /** Semantic version */
+    version: string;
+    /** Entry point path */
+    main: string;
+    /** Compatible NeuroLink version range */
+    engine: {
+        neurolink: string;
+    };
+    /** Human-readable description */
+    description: string;
+    /** Declarative permissions array for security */
+    permissions: string[];
+    /** JSON Schema for configuration validation */
+    configSchema?: ZodSchema | object;
+}
+/**
+ * Execution Context - Security Sandbox for MCP Operations
+ * Provides sandboxed access to system resources with permission checking
+ */
+export interface ExecutionContext {
+    /** Session identifier for tracking */
+    sessionId: string;
+    /** User identifier for permissions */
+    userId: string;
+    /** Sandboxed filesystem operations */
+    secureFS: {
+        readFile: (path: string, encoding?: string) => Promise<string | Buffer>;
+        writeFile: (path: string, content: string | Buffer) => Promise<void>;
+        readdir: (path: string) => Promise<string[]>;
+        stat: (path: string) => Promise<any>;
+        mkdir: (path: string, options?: any) => Promise<void>;
+        exists: (path: string) => Promise<boolean>;
+    };
+    /** Sandboxed path operations */
+    path: {
+        join: (...paths: string[]) => string;
+        resolve: (...paths: string[]) => string;
+        relative: (from: string, to: string) => string;
+        dirname: (path: string) => string;
+        basename: (path: string, ext?: string) => string;
+    };
+    /** Sandboxed network operations (future) */
+    secureNet?: {
+        fetch: (url: string, options?: any) => Promise<Response>;
+    };
+    /** Plugin-specific permissions granted */
+    grantedPermissions: string[];
+    /** Log function for debugging */
+    log: (level: "debug" | "info" | "warn" | "error", message: string, data?: any) => void;
+    /** Plugin instance reference (for plugin bridge compatibility) */
+    plugin?: any;
+}
+/**
+ * MCP Abstract Class - The Core Contract for All Plugins
+ * Uses TypeScript generics for type-safe configuration
+ */
+export declare abstract class MCP<TConfig = any, TArgs = any, TResult = any> {
+    /** Static metadata loaded from manifest */
+    abstract readonly metadata: MCPMetadata;
+    /** Configuration state - accessible to child classes */
+    config?: TConfig;
+    /** Initialization flag */
+    protected initialized: boolean;
+    /**
+     * Initialize the MCP with user-provided configuration
+     * @param config - Plugin-specific configuration object
+     */
+    abstract initialize(config: TConfig): Promise<void>;
+    /**
+     * Execute the MCP's primary functionality
+     * @param context - Sandboxed execution context
+     * @param args - Operation-specific arguments
+     * @returns Plugin-specific result
+     */
+    abstract execute(context: ExecutionContext, args: TArgs): Promise<TResult>;
+    /**
+     * Graceful shutdown and resource cleanup
+     */
+    abstract dispose(): Promise<void>;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): TConfig | undefined;
+    /**
+     * Check if the MCP is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get plugin metadata
+     */
+    getMetadata(): MCPMetadata;
+    /**
+     * Validate that the MCP is ready for execution
+     */
+    protected ensureInitialized(): void;
+    /**
+     * Helper method for logging with context
+     */
+    protected log(context: ExecutionContext, level: "debug" | "info" | "warn" | "error", message: string, data?: any): void;
+}
+/**
+ * Type definitions for plugin registry
+ */
+export type MCPConstructor<T extends MCP = MCP> = new () => T;
+export type MCPInstance<T extends MCP = MCP> = T;
+/**
+ * Plugin discovery result
+ */
+export interface DiscoveredMCP {
+    metadata: MCPMetadata;
+    entryPath: string;
+    source: "core" | "project" | "installed";
+    constructor?: MCPConstructor;
+}
+/**
+ * Plugin load result
+ */
+export interface PluginLoadResult {
+    success: boolean;
+    plugin?: MCP;
+    error?: string;
+}
+/**
+ * Plugin discovery result
+ */
+export interface PluginDiscoveryResult {
+    total: number;
+    loaded: number;
+    failed: number;
+    plugins: DiscoveredMCP[];
+}
+/**
+ * Plugin execution result
+ */
+export interface PluginExecutionResult<T = any> {
+    success: boolean;
+    result?: T;
+    error?: string;
+    executionTime?: number;
+}
+/**
+ * MCP Category for organization
+ */
+export declare enum MCPCategory {
+    FILESYSTEM = "filesystem",
+    NETWORK = "network",
+    DATABASE = "database",
+    AI = "ai",
+    UTILITY = "utility",
+    INTEGRATION = "integration"
+}

package/dist/lib/mcp/contracts/mcp-contract.js

@@ -0,0 +1,58 @@
+/**
+ * MCP Abstract Contract - The Foundation of NeuroLink's Plugin Ecosystem
+ * Based on research blueprint for extensible MCP architecture
+ */
+/**
+ * MCP Abstract Class - The Core Contract for All Plugins
+ * Uses TypeScript generics for type-safe configuration
+ */
+export class MCP {
+    /** Configuration state - accessible to child classes */
+    config;
+    /** Initialization flag */
+    initialized = false;
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Check if the MCP is initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get plugin metadata
+     */
+    getMetadata() {
+        return this.metadata;
+    }
+    /**
+     * Validate that the MCP is ready for execution
+     */
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error(`MCP ${this.metadata.name} is not initialized. Call initialize() first.`);
+        }
+    }
+    /**
+     * Helper method for logging with context
+     */
+    log(context, level, message, data) {
+        context.log(level, `[${this.metadata.name}] ${message}`, data);
+    }
+}
+/**
+ * MCP Category for organization
+ */
+export var MCPCategory;
+(function (MCPCategory) {
+    MCPCategory["FILESYSTEM"] = "filesystem";
+    MCPCategory["NETWORK"] = "network";
+    MCPCategory["DATABASE"] = "database";
+    MCPCategory["AI"] = "ai";
+    MCPCategory["UTILITY"] = "utility";
+    MCPCategory["INTEGRATION"] = "integration";
+})(MCPCategory || (MCPCategory = {}));

package/dist/lib/mcp/core/plugin-manager.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Core Plugin Manager
+ * Enhanced plugin management with advanced lifecycle control
+ */
+import type { MCP, MCPMetadata, MCPConstructor, PluginLoadResult, PluginExecutionResult, ExecutionContext } from "../contracts/mcp-contract.js";
+/**
+ * Enhanced plugin manager with core functionality
+ */
+export declare class CorePluginManager {
+    private plugins;
+    private constructors;
+    private metadata;
+    /**
+     * Load a plugin from constructor
+     */
+    loadPlugin(name: string, Constructor: MCPConstructor, config: any): Promise<PluginLoadResult>;
+    /**
+     * Execute a plugin operation
+     */
+    executePlugin<T = any>(name: string, context: ExecutionContext, args: any): Promise<PluginExecutionResult<T>>;
+    /**
+     * Get plugin instance
+     */
+    getPlugin(name: string): MCP | undefined;
+    /**
+     * Get plugin metadata
+     */
+    getPluginMetadata(name: string): MCPMetadata | undefined;
+    /**
+     * List all loaded plugins
+     */
+    listPlugins(): string[];
+    /**
+     * Unload a plugin
+     */
+    unloadPlugin(name: string): Promise<void>;
+    /**
+     * Dispose all plugins
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Default core plugin manager instance
+ */
+export declare const corePluginManager: CorePluginManager;

package/dist/lib/mcp/core/plugin-manager.js

@@ -0,0 +1,110 @@
+/**
+ * Core Plugin Manager
+ * Enhanced plugin management with advanced lifecycle control
+ */
+import { mcpLogger } from "../logging.js";
+/**
+ * Enhanced plugin manager with core functionality
+ */
+export class CorePluginManager {
+    plugins = new Map();
+    constructors = new Map();
+    metadata = new Map();
+    /**
+     * Load a plugin from constructor
+     */
+    async loadPlugin(name, Constructor, config) {
+        try {
+            const instance = new Constructor();
+            await instance.initialize(config);
+            this.plugins.set(name, instance);
+            this.constructors.set(name, Constructor);
+            this.metadata.set(name, instance.getMetadata());
+            mcpLogger.info(`[CorePluginManager] Loaded plugin: ${name}`);
+            return {
+                success: true,
+                plugin: instance,
+            };
+        }
+        catch (error) {
+            mcpLogger.error(`[CorePluginManager] Failed to load plugin ${name}:`, error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Execute a plugin operation
+     */
+    async executePlugin(name, context, args) {
+        const startTime = Date.now();
+        try {
+            const plugin = this.plugins.get(name);
+            if (!plugin) {
+                throw new Error(`Plugin ${name} not loaded`);
+            }
+            const result = await plugin.execute(context, args);
+            const executionTime = Date.now() - startTime;
+            return {
+                success: true,
+                result,
+                executionTime,
+            };
+        }
+        catch (error) {
+            const executionTime = Date.now() - startTime;
+            mcpLogger.error(`[CorePluginManager] Plugin execution failed for ${name}:`, error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                executionTime,
+            };
+        }
+    }
+    /**
+     * Get plugin instance
+     */
+    getPlugin(name) {
+        return this.plugins.get(name);
+    }
+    /**
+     * Get plugin metadata
+     */
+    getPluginMetadata(name) {
+        return this.metadata.get(name);
+    }
+    /**
+     * List all loaded plugins
+     */
+    listPlugins() {
+        return Array.from(this.plugins.keys());
+    }
+    /**
+     * Unload a plugin
+     */
+    async unloadPlugin(name) {
+        const plugin = this.plugins.get(name);
+        if (plugin) {
+            await plugin.dispose();
+            this.plugins.delete(name);
+            this.constructors.delete(name);
+            this.metadata.delete(name);
+            mcpLogger.info(`[CorePluginManager] Unloaded plugin: ${name}`);
+        }
+    }
+    /**
+     * Dispose all plugins
+     */
+    async dispose() {
+        const pluginNames = Array.from(this.plugins.keys());
+        for (const name of pluginNames) {
+            await this.unloadPlugin(name);
+        }
+        mcpLogger.info("[CorePluginManager] All plugins disposed");
+    }
+}
+/**
+ * Default core plugin manager instance
+ */
+export const corePluginManager = new CorePluginManager();

package/dist/lib/mcp/demo/plugin-demo.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Plugin Demo - Example MCP Plugin Usage
+ */
+/**
+ * Demo plugin functionality
+ */
+export declare class PluginDemo {
+    /**
+     * Demonstrate filesystem plugin
+     */
+    static demonstrateFileSystem(): Promise<void>;
+    /**
+     * Demonstrate plugin execution via ecosystem
+     */
+    static demonstrateEcosystem(): Promise<void>;
+    /**
+     * Demonstrate quick plugin factory
+     */
+    static demonstrateQuickFactory(): Promise<void>;
+}

package/dist/lib/mcp/demo/plugin-demo.js

@@ -0,0 +1,116 @@
+/**
+ * Plugin Demo - Example MCP Plugin Usage
+ */
+import { mcpEcosystem } from "../ecosystem.js";
+import { FileSystemMCP } from "../plugins/core/filesystem-mcp.js";
+import { QuickPluginFactory, executePlugin, } from "../adapters/plugin-bridge.js";
+import { mcpLogger } from "../logging.js";
+/**
+ * Demo plugin functionality
+ */
+export class PluginDemo {
+    /**
+     * Demonstrate filesystem plugin
+     */
+    static async demonstrateFileSystem() {
+        try {
+            // Create filesystem plugin instance
+            const fsPlugin = new FileSystemMCP();
+            await fsPlugin.initialize({ basePath: process.cwd() });
+            mcpLogger.info("FileSystem plugin demonstration started");
+            // This would normally be done through the ecosystem
+            // but we're demonstrating direct usage
+            const result = await mcpEcosystem.filesystem({
+                action: "listFiles",
+                path: ".",
+                basePath: process.cwd(),
+            });
+            mcpLogger.info("File listing result:", result);
+        }
+        catch (error) {
+            mcpLogger.error("Demo failed:", error);
+        }
+    }
+    /**
+     * Demonstrate plugin execution via ecosystem
+     */
+    static async demonstrateEcosystem() {
+        try {
+            await mcpEcosystem.initialize();
+            const stats = await mcpEcosystem.getStats();
+            mcpLogger.info("MCP Ecosystem stats:", stats);
+            // Try to read a file
+            const fsPlugin = new FileSystemMCP();
+            await fsPlugin.initialize({ basePath: process.cwd() });
+            const result = await executePlugin(fsPlugin, createMockContext(), "listFiles", ".");
+            mcpLogger.info("Plugin execution result:", result);
+        }
+        catch (error) {
+            mcpLogger.error("Ecosystem demo failed:", error);
+        }
+    }
+    /**
+     * Demonstrate quick plugin factory
+     */
+    static async demonstrateQuickFactory() {
+        try {
+            const fsPlugin = new FileSystemMCP();
+            await fsPlugin.initialize({ basePath: process.cwd() });
+            const quickPlugin = await QuickPluginFactory.create("demo-plugin", {
+                basePath: process.cwd(),
+            });
+            mcpLogger.info("Quick plugin created:", quickPlugin);
+        }
+        catch (error) {
+            mcpLogger.error("Quick factory demo failed:", error);
+        }
+    }
+}
+/**
+ * Create a mock execution context for testing
+ */
+function createMockContext() {
+    return {
+        sessionId: "demo-session",
+        userId: "demo-user",
+        grantedPermissions: ["fs:read:./**/*", "fs:write:./temp/**/*"],
+        secureFS: {
+            async readFile(path, encoding) {
+                return `Mock content from ${path}`;
+            },
+            async writeFile(path, content) {
+                mcpLogger.info(`Mock write to ${path}`);
+            },
+            async readdir(path) {
+                return ["file1.txt", "file2.json", "subdir"];
+            },
+            async stat(path) {
+                return {
+                    size: 1024,
+                    mtime: new Date(),
+                    isDirectory: () => false,
+                    isFile: () => true,
+                };
+            },
+            async mkdir(path, options) {
+                mcpLogger.info(`Mock mkdir: ${path}`);
+            },
+            async exists(path) {
+                return true;
+            },
+        },
+        path: {
+            join: (...paths) => paths.join("/"),
+            resolve: (...paths) => "/" + paths.join("/"),
+            relative: (from, to) => to,
+            dirname: (path) => path.split("/").slice(0, -1).join("/"),
+            basename: (path, ext) => {
+                const name = path.split("/").pop() || "";
+                return ext ? name.replace(ext, "") : name;
+            },
+        },
+        log: (level, message, data) => {
+            mcpLogger[level](`[MockContext] ${message}`, data);
+        },
+    };
+}

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

@@ -0,0 +1,75 @@
+/**
+ * MCP Ecosystem Integration - Bridge Between Research Blueprint and NeuroLink
+ * Provides unified interface for plugin management and execution
+ */
+import { MCP } from "./contracts/mcp-contract.js";
+import type { MCPMetadata, ExecutionContext } from "./contracts/mcp-contract.js";
+/**
+ * MCP Ecosystem - Main Interface for Plugin Operations
+ */
+export declare class MCPEcosystem {
+    private static instance;
+    private securityManager;
+    private initialized;
+    private constructor();
+    static getInstance(): MCPEcosystem;
+    /**
+     * Initialize the MCP ecosystem
+     */
+    initialize(): Promise<void>;
+    /**
+     * List all available MCPs
+     */
+    list(): Promise<MCPMetadata[]>;
+    /**
+     * Get metadata for a specific MCP
+     */
+    getMetadata(name: string): Promise<MCPMetadata | null>;
+    /**
+     * Create and execute an MCP instance
+     */
+    execute<T = any>(name: string, config: any, args: any, context?: {
+        sessionId?: string;
+        userId?: string;
+    }): Promise<T>;
+    /**
+     * Execute filesystem operations using FileSystemMCP
+     */
+    filesystem(operation: {
+        action: "readFile" | "writeFile" | "listFiles" | "createDir";
+        path: string;
+        content?: string;
+        basePath?: string;
+    }): Promise<any>;
+    /**
+     * Get ecosystem statistics
+     */
+    getStats(): Promise<{
+        initialized: boolean;
+        pluginsDiscovered: number;
+        pluginsBySource: Record<string, number>;
+        availablePlugins: string[];
+    }>;
+    /**
+     * Create an MCP instance for direct use
+     */
+    createInstance<T extends MCP>(name: string, config: any): Promise<T>;
+    /**
+     * Create execution context for manual MCP usage
+     */
+    createExecutionContext(sessionId: string, userId: string, permissions: string[], basePath?: string): ExecutionContext;
+    /**
+     * Ensure ecosystem is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Get all tools formatted for AI providers
+     */
+    getToolsForAI(): Promise<any>;
+    /**
+     * Dispose of all resources
+     */
+    dispose(): Promise<void>;
+}
+export declare const mcpEcosystem: MCPEcosystem;
+export type { MCPMetadata, ExecutionContext, } from "./contracts/mcp-contract.js";