@juspay/neurolink 1.10.0 → 1.11.0

package/dist/mcp/plugin-manager.js

@@ -0,0 +1,295 @@
+/**
+ * PluginManager - Central Orchestrator for MCP Lifecycle
+ * Implements generic factory pattern with manifest-based discovery
+ * Based on research blueprint for extensible plugin architecture
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+// ES Module compatibility
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+import { MCP } from "./contracts/mcp-contract.js";
+import { SecurityManager } from "./security-manager.js";
+import { mcpLogger } from "./logging.js";
+/**
+ * Central Plugin Manager implementing the research blueprint
+ */
+export class PluginManager {
+    static instance;
+    mcpConstructors = new Map();
+    mcpInstances = new Map();
+    discoveredMCPs = new Map();
+    securityManager;
+    initialized = false;
+    config;
+    constructor(config = {}) {
+        this.config = {
+            enableDiscovery: true,
+            pluginDirectories: [],
+            securityLevel: "moderate",
+            maxPlugins: 50,
+            ...config,
+        };
+        this.securityManager = new SecurityManager(this.config.securityLevel);
+    }
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(config) {
+        if (!PluginManager.instance) {
+            PluginManager.instance = new PluginManager(config);
+        }
+        return PluginManager.instance;
+    }
+    /**
+     * Initialize the plugin manager with discovery
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        mcpLogger.info("[PluginManager] Initializing plugin discovery...");
+        if (this.config.enableDiscovery) {
+            await this.discoverPlugins();
+        }
+        this.initialized = true;
+        mcpLogger.info(`[PluginManager] Initialized with ${this.discoveredMCPs.size} discovered plugins`);
+    }
+    /**
+     * Discover plugins following research blueprint priority:
+     * 1. Core plugins (bundled)
+     * 2. Project plugins (./neurolink-mcp/)
+     * 3. Installed plugins (node_modules)
+     */
+    async discoverPlugins() {
+        const functionTag = "PluginManager.discoverPlugins";
+        try {
+            // 1. Discover core plugins
+            await this.discoverCorePlugins();
+            // 2. Discover project plugins
+            await this.discoverProjectPlugins();
+            // 3. Discover installed plugins
+            await this.discoverInstalledPlugins();
+            mcpLogger.debug(`[${functionTag}] Discovery completed`, {
+                total: this.discoveredMCPs.size,
+                bySource: this.getDiscoveryStats(),
+            });
+        }
+        catch (error) {
+            mcpLogger.error(`[${functionTag}] Discovery failed:`, error);
+        }
+    }
+    /**
+     * Discover core plugins bundled with NeuroLink
+     */
+    async discoverCorePlugins() {
+        // Correctly resolve path from 'dist' to 'src'
+        const corePluginsPath = path.resolve(__dirname, "../../src/lib/mcp/plugins/core");
+        await this.discoverPluginsInDirectory(corePluginsPath, "core");
+    }
+    /**
+     * Discover project-local plugins
+     */
+    async discoverProjectPlugins() {
+        const projectPluginsPath = path.join(process.cwd(), "neurolink-mcp");
+        await this.discoverPluginsInDirectory(projectPluginsPath, "project");
+    }
+    /**
+     * Discover installed plugins from node_modules
+     */
+    async discoverInstalledPlugins() {
+        const nodeModulesPath = path.join(process.cwd(), "node_modules");
+        try {
+            const packages = await fs.readdir(nodeModulesPath);
+            for (const pkg of packages) {
+                if (pkg.startsWith(".")) {
+                    continue;
+                }
+                const packagePath = path.join(nodeModulesPath, pkg);
+                const packageJsonPath = path.join(packagePath, "package.json");
+                try {
+                    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf-8"));
+                    // Check for neurolink-mcp keyword
+                    if (packageJson.keywords?.includes("neurolink-mcp")) {
+                        await this.discoverPluginsInDirectory(packagePath, "installed");
+                    }
+                }
+                catch {
+                    // Skip invalid packages
+                }
+            }
+        }
+        catch {
+            // node_modules doesn't exist or not accessible
+        }
+    }
+    /**
+     * Discover plugins in a specific directory
+     */
+    async discoverPluginsInDirectory(dirPath, source) {
+        try {
+            const manifestPath = path.join(dirPath, "neurolink-mcp.json");
+            const manifestExists = await fs
+                .access(manifestPath)
+                .then(() => true)
+                .catch(() => false);
+            if (!manifestExists) {
+                return;
+            }
+            const manifest = JSON.parse(await fs.readFile(manifestPath, "utf-8"));
+            // Validate manifest
+            if (!this.validateManifest(manifest)) {
+                mcpLogger.warn(`[PluginManager] Invalid manifest in ${dirPath}`);
+                return;
+            }
+            // Now we know manifest is MCPMetadata due to type guard
+            const validatedManifest = manifest;
+            const entryPath = path
+                .resolve(dirPath, validatedManifest.main)
+                .replace(`${process.cwd()}/src/lib`, `${process.cwd()}/dist`);
+            this.discoveredMCPs.set(validatedManifest.name, {
+                metadata: validatedManifest,
+                entryPath,
+                source,
+                constructor: undefined, // Will be loaded on demand
+            });
+            mcpLogger.debug(`[PluginManager] Discovered ${validatedManifest.name} from ${source}`);
+        }
+        catch (error) {
+            mcpLogger.debug(`[PluginManager] Failed to discover plugin in ${dirPath}:`, error);
+        }
+    }
+    /**
+     * Validate manifest structure
+     */
+    validateManifest(manifest) {
+        if (!manifest || typeof manifest !== "object") {
+            return false;
+        }
+        const obj = manifest;
+        return (typeof obj.name === "string" &&
+            typeof obj.version === "string" &&
+            typeof obj.main === "string" &&
+            obj.engine?.neurolink &&
+            typeof obj.description === "string" &&
+            Array.isArray(obj.permissions));
+    }
+    /**
+     * Generic Factory Method - Creates type-safe MCP instances
+     * Core implementation of the research blueprint
+     */
+    async createInstance(name, config) {
+        const functionTag = "PluginManager.createInstance";
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        // Check if already instantiated
+        const existingInstance = this.mcpInstances.get(name);
+        if (existingInstance) {
+            mcpLogger.debug(`[${functionTag}] Returning existing instance of ${name}`);
+            return existingInstance;
+        }
+        // Get constructor (load if necessary)
+        const Constructor = await this.getConstructor(name);
+        if (!Constructor) {
+            throw new Error(`MCP with name "${name}" is not registered or failed validation.`);
+        }
+        // Security check
+        const discovered = this.discoveredMCPs.get(name);
+        if (discovered &&
+            !this.securityManager.validatePermissions(discovered.metadata.permissions)) {
+            throw new Error(`Security validation failed for MCP "${name}"`);
+        }
+        try {
+            // Instantiate the class
+            const instance = new Constructor();
+            // Initialize with config
+            await instance.initialize(config);
+            // Store instance
+            this.mcpInstances.set(name, instance);
+            mcpLogger.info(`[${functionTag}] Created and initialized ${name}`);
+            return instance;
+        }
+        catch (error) {
+            mcpLogger.error(`[${functionTag}] Failed to create instance of ${name}:`, error);
+            throw error;
+        }
+    }
+    /**
+     * Get or load constructor for an MCP
+     */
+    async getConstructor(name) {
+        // Check if already loaded
+        const existingConstructor = this.mcpConstructors.get(name);
+        if (existingConstructor) {
+            return existingConstructor;
+        }
+        // Load from discovered plugins
+        const discovered = this.discoveredMCPs.get(name);
+        if (!discovered) {
+            return null;
+        }
+        try {
+            // Dynamic import of the plugin
+            const module = await import(discovered.entryPath);
+            const Constructor = module.default || module[discovered.metadata.name];
+            if (typeof Constructor !== "function") {
+                throw new Error(`Invalid export from ${discovered.entryPath}`);
+            }
+            // Store constructor
+            this.mcpConstructors.set(name, Constructor);
+            return Constructor;
+        }
+        catch (error) {
+            mcpLogger.error(`[PluginManager] Failed to load ${name} from ${discovered.entryPath}:`, error);
+            return null;
+        }
+    }
+    /**
+     * List all discovered MCPs
+     */
+    listDiscovered() {
+        return Array.from(this.discoveredMCPs.values()).map((d) => d.metadata);
+    }
+    /**
+     * Get metadata for a specific MCP
+     */
+    getMetadata(name) {
+        const discovered = this.discoveredMCPs.get(name);
+        return discovered ? discovered.metadata : null;
+    }
+    /**
+     * Get discovery statistics
+     */
+    getDiscoveryStats() {
+        const stats = { core: 0, project: 0, installed: 0 };
+        for (const discovered of this.discoveredMCPs.values()) {
+            stats[discovered.source]++;
+        }
+        return stats;
+    }
+    /**
+     * Dispose of all instances and cleanup
+     */
+    async dispose() {
+        mcpLogger.info("[PluginManager] Disposing all MCP instances...");
+        for (const [name, instance] of this.mcpInstances) {
+            try {
+                await instance.dispose();
+                mcpLogger.debug(`[PluginManager] Disposed ${name}`);
+            }
+            catch (error) {
+                mcpLogger.error(`[PluginManager] Failed to dispose ${name}:`, error);
+            }
+        }
+        this.mcpInstances.clear();
+        this.mcpConstructors.clear();
+        this.initialized = false;
+    }
+}
+/**
+ * Export singleton instance getter
+ */
+export const pluginManager = PluginManager.getInstance();

package/dist/mcp/plugins/core/filesystem-mcp.d.ts

@@ -0,0 +1,35 @@
+/**
+ * FileSystemMCP - Proof of Concept Plugin
+ * Demonstrates the research blueprint implementation
+ */
+import { MCP } from "../../contracts/mcp-contract.js";
+import type { MCPMetadata, ExecutionContext } from "../../contracts/mcp-contract.js";
+interface FileSystemConfig {
+    basePath: string;
+    allowedExtensions?: string[];
+}
+interface FileSystemArgs {
+    operation: "readFile" | "writeFile" | "listFiles" | "createDir";
+    path: string;
+    content?: string;
+    options?: any;
+}
+interface FileSystemResult {
+    success: boolean;
+    data?: any;
+    error?: string;
+}
+/**
+ * FileSystem MCP implementing the abstract contract
+ */
+export declare class FileSystemMCP extends MCP<FileSystemConfig, FileSystemArgs, FileSystemResult> {
+    readonly metadata: MCPMetadata;
+    initialize(config: FileSystemConfig): Promise<void>;
+    execute(context: ExecutionContext, args: FileSystemArgs): Promise<FileSystemResult>;
+    private readFile;
+    private writeFile;
+    private listFiles;
+    private createDirectory;
+    dispose(): Promise<void>;
+}
+export default FileSystemMCP;

package/dist/mcp/plugins/core/filesystem-mcp.js

@@ -0,0 +1,139 @@
+/**
+ * FileSystemMCP - Proof of Concept Plugin
+ * Demonstrates the research blueprint implementation
+ */
+import { MCP } from "../../contracts/mcp-contract.js";
+import * as path from "path";
+/**
+ * FileSystem MCP implementing the abstract contract
+ */
+export class FileSystemMCP extends MCP {
+    metadata = {
+        name: "@neurolink-mcp/filesystem",
+        version: "1.0.0",
+        main: "./filesystem-mcp.js",
+        engine: {
+            neurolink: ">=1.9.0 <2.0.0",
+        },
+        description: "Provides secure file system operations for NeuroLink agents",
+        permissions: [
+            "fs:read:./**/*",
+            "fs:write:./output/**/*",
+            "fs:write:./temp/**/*",
+        ],
+    };
+    async initialize(config) {
+        if (!config.basePath) {
+            throw new Error("basePath is required in FileSystemMCP configuration");
+        }
+        this.config = {
+            allowedExtensions: [".txt", ".json", ".md", ".js", ".ts"],
+            ...config,
+        };
+        this.initialized = true;
+    }
+    async execute(context, args) {
+        this.log(context, "info", "Executing FileSystemMCP", { args });
+        this.log(context, "info", "Executing FileSystemMCP", { args });
+        this.log(context, "info", "Executing FileSystemMCP", { args });
+        this.ensureInitialized();
+        try {
+            if (!args.path) {
+                // This is a configuration call, not an operation
+                return { success: true, data: { configured: true } };
+            }
+            const fullPath = path.isAbsolute(args.path)
+                ? args.path
+                : context.path.join(this.config.basePath, args.path);
+            switch (args.operation) {
+                case "readFile":
+                    return await this.readFile(context, fullPath);
+                case "writeFile":
+                    return await this.writeFile(context, fullPath, args.content);
+                case "listFiles":
+                    return await this.listFiles(context, fullPath);
+                case "createDir":
+                    return await this.createDirectory(context, fullPath);
+                default:
+                    throw new Error(`Unsupported operation: ${args.operation}`);
+            }
+        }
+        catch (error) {
+            this.log(context, "error", "Operation failed", {
+                operation: args.operation,
+                error,
+            });
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async readFile(context, filePath) {
+        const content = await context.secureFS.readFile(filePath, "utf-8");
+        const stats = await context.secureFS.stat(filePath);
+        return {
+            success: true,
+            data: {
+                content,
+                size: stats.size,
+                lastModified: stats.mtime,
+                path: filePath,
+            },
+        };
+    }
+    async writeFile(context, filePath, content) {
+        await context.secureFS.writeFile(filePath, content);
+        return {
+            success: true,
+            data: {
+                path: filePath,
+                size: content.length,
+                written: true,
+            },
+        };
+    }
+    async listFiles(context, dirPath) {
+        const items = await context.secureFS.readdir(dirPath);
+        const itemDetails = [];
+        for (const item of items) {
+            const itemPath = context.path.join(dirPath, item);
+            try {
+                const stats = await context.secureFS.stat(itemPath);
+                itemDetails.push({
+                    name: item,
+                    type: stats.isDirectory() ? "directory" : "file",
+                    size: stats.isFile() ? stats.size : undefined,
+                    lastModified: stats.mtime,
+                });
+            }
+            catch {
+                // Skip inaccessible items
+            }
+        }
+        return {
+            success: true,
+            data: {
+                path: dirPath,
+                items: itemDetails,
+                count: itemDetails.length,
+            },
+        };
+    }
+    async createDirectory(context, dirPath) {
+        await context.secureFS.mkdir(dirPath, { recursive: true });
+        return {
+            success: true,
+            data: {
+                path: dirPath,
+                created: true,
+            },
+        };
+    }
+    async dispose() {
+        this.initialized = false;
+        this.config = undefined;
+    }
+}
+// Export as default for dynamic import
+export default FileSystemMCP;

package/dist/mcp/plugins/core/neurolink-mcp.json

@@ -0,0 +1,17 @@
+{
+  "name": "@neurolink-mcp/filesystem",
+  "version": "1.0.0",
+  "main": "./filesystem-mcp.js",
+  "description": "Provides secure file system operations for NeuroLink agents",
+  "author": "NeuroLink Team",
+  "license": "MIT",
+  "engine": {
+    "neurolink": ">=1.9.0 <2.0.0"
+  },
+  "permissions": [
+    "fs:read:./**/*",
+    "fs:write:./output/**/*",
+    "fs:write:./temp/**/*"
+  ],
+  "keywords": ["filesystem", "file", "mcp", "plugin"]
+}

package/dist/mcp/plugins/filesystem-mcp.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Enhanced FileSystem MCP Plugin
+ * Implements the new MCP contract with security sandbox
+ * Based on research document recommendations
+ */
+import { MCP, MCPMetadata, ExecutionContext } from "../contracts/mcp-contract.js";
+/**
+ * FileSystem MCP Configuration
+ */
+export interface FileSystemConfig {
+    basePath: string;
+    allowedExtensions?: string[];
+    maxFileSize?: number;
+    readOnly?: boolean;
+}
+/**
+ * FileSystem Operation Arguments
+ */
+export interface FileSystemArgs {
+    operation: "readFile" | "writeFile" | "listFiles" | "getFileInfo";
+    path: string;
+    content?: string;
+    encoding?: string;
+}
+/**
+ * Enhanced FileSystem MCP Plugin
+ */
+export declare class FileSystemMCP extends MCP<FileSystemConfig> {
+    config: FileSystemConfig;
+    readonly metadata: MCPMetadata;
+    initialize(config: FileSystemConfig): Promise<void>;
+    execute(context: ExecutionContext, args: FileSystemArgs): Promise<any>;
+    private resolvePath;
+    dispose(): Promise<void>;
+}
+export declare function createFileSystemMCP(): FileSystemMCP;

package/dist/mcp/plugins/filesystem-mcp.js

@@ -0,0 +1,54 @@
+/**
+ * Enhanced FileSystem MCP Plugin
+ * Implements the new MCP contract with security sandbox
+ * Based on research document recommendations
+ */
+import path from "path";
+import { MCP, MCPMetadata, ExecutionContext, MCPCategory, } from "../contracts/mcp-contract.js";
+/**
+ * Enhanced FileSystem MCP Plugin
+ */
+export class FileSystemMCP extends MCP {
+    metadata = {
+        name: "@neurolink-mcp/filesystem",
+        version: "1.0.0",
+        main: "./dist/filesystem-mcp.js",
+        engine: { neurolink: ">=1.9.0 <2.0.0" },
+        description: "Secure file system operations with permission-based access control",
+        permissions: ["fs:read:./**/*", "fs:write:./output/**/*"],
+    };
+    async initialize(config) {
+        this.config = {
+            allowedExtensions: [".txt", ".md", ".json", ".js", ".ts"],
+            maxFileSize: 10 * 1024 * 1024,
+            readOnly: false,
+            ...config,
+        };
+    }
+    async execute(context, args) {
+        const resolvedPath = this.resolvePath(args.path);
+        switch (args.operation) {
+            case "readFile":
+                return await context.secureFS.readFile(resolvedPath, args.encoding || "utf-8");
+            case "listFiles":
+                return await context.secureFS.readdir(resolvedPath);
+            case "getFileInfo":
+                return await context.secureFS.stat(resolvedPath);
+            default:
+                throw new Error(`Unsupported operation: ${args.operation}`);
+        }
+    }
+    resolvePath(inputPath) {
+        const resolved = path.resolve(this.config.basePath, inputPath);
+        if (!resolved.startsWith(this.config.basePath)) {
+            throw new Error(`Path outside allowed directory: ${inputPath}`);
+        }
+        return resolved;
+    }
+    async dispose() {
+        // Cleanup resources
+    }
+}
+export function createFileSystemMCP() {
+    return new FileSystemMCP();
+}