@juspay/neurolink 1.2.4 → 1.5.0

package/dist/mcp/context-manager.d.ts

@@ -0,0 +1,164 @@
+/**
+ * NeuroLink MCP Context Management System
+ * Unified context creation and management for all tool executions
+ * Ensures rich context flows through tool chain with session tracking
+ */
+import type { NeuroLinkExecutionContext } from './factory.js';
+/**
+ * Context creation request interface
+ */
+export interface ContextRequest {
+    sessionId?: string;
+    userId?: string;
+    aiProvider?: string;
+    modelId?: string;
+    temperature?: number;
+    maxTokens?: number;
+    organizationId?: string;
+    projectId?: string;
+    environmentType?: 'development' | 'staging' | 'production';
+    frameworkType?: 'react' | 'vue' | 'svelte' | 'next' | 'nuxt' | 'sveltekit';
+    permissions?: string[];
+    securityLevel?: 'public' | 'private' | 'organization';
+    [key: string]: any;
+}
+/**
+ * Context manager for creating and managing execution contexts
+ * Provides rich context for all tool executions with session tracking
+ */
+export declare class ContextManager {
+    private sessionCounter;
+    private activeContexts;
+    /**
+     * Create a new execution context with rich information
+     *
+     * @param request Context creation request with optional fields
+     * @returns Complete execution context ready for tool chain
+     */
+    createContext(request?: ContextRequest): NeuroLinkExecutionContext;
+    /**
+     * Add a tool to the execution chain
+     *
+     * @param context Execution context to modify
+     * @param toolName Name of the tool being executed
+     */
+    addToToolChain(context: NeuroLinkExecutionContext, toolName: string): void;
+    /**
+     * Get the current tool chain for a context
+     *
+     * @param context Execution context
+     * @returns Array of tool names in execution order
+     */
+    getToolChain(context: NeuroLinkExecutionContext): string[];
+    /**
+     * Set parent tool for nested tool execution
+     *
+     * @param context Execution context to modify
+     * @param parentToolId ID of the parent tool
+     */
+    setParentTool(context: NeuroLinkExecutionContext, parentToolId: string): void;
+    /**
+     * Create child context for nested tool execution
+     *
+     * @param parentContext Parent execution context
+     * @param childToolName Name of the child tool
+     * @returns New child context with inherited properties
+     */
+    createChildContext(parentContext: NeuroLinkExecutionContext, childToolName: string): NeuroLinkExecutionContext;
+    /**
+     * Get context by session ID
+     *
+     * @param sessionId Session identifier
+     * @returns Execution context or undefined if not found
+     */
+    getContext(sessionId: string): NeuroLinkExecutionContext | undefined;
+    /**
+     * Update context with new information
+     *
+     * @param sessionId Session identifier
+     * @param updates Partial context updates
+     */
+    updateContext(sessionId: string, updates: Partial<NeuroLinkExecutionContext>): void;
+    /**
+     * Remove context from active tracking
+     *
+     * @param sessionId Session identifier
+     */
+    removeContext(sessionId: string): void;
+    /**
+     * Get all active contexts (for debugging/monitoring)
+     *
+     * @returns Array of all active contexts
+     */
+    getActiveContexts(): NeuroLinkExecutionContext[];
+    /**
+     * Clear all active contexts
+     */
+    clearAllContexts(): void;
+    /**
+     * Get context statistics
+     *
+     * @returns Context usage statistics
+     */
+    getStats(): {
+        activeContexts: number;
+        totalSessionsCreated: number;
+        averageToolChainLength: number;
+    };
+    /**
+     * Generate unique session ID
+     *
+     * @returns Unique session identifier
+     */
+    private generateSessionId;
+    /**
+     * Extract custom fields from request (excluding known fields)
+     *
+     * @param request Context creation request
+     * @returns Custom fields object
+     */
+    private extractCustomFields;
+}
+/**
+ * Default context manager instance
+ * Can be used across the application for consistent context management
+ */
+export declare const defaultContextManager: ContextManager;
+/**
+ * Utility function to create context with defaults
+ *
+ * @param request Optional context request
+ * @returns Execution context with sensible defaults
+ */
+export declare function createExecutionContext(request?: ContextRequest): NeuroLinkExecutionContext;
+/**
+ * Utility function to add tool to default context manager
+ *
+ * @param context Execution context
+ * @param toolName Tool name to add
+ */
+export declare function addToolToChain(context: NeuroLinkExecutionContext, toolName: string): void;
+/**
+ * Context validation utilities
+ */
+export declare class ContextValidator {
+    /**
+     * Validate context has required fields for tool execution
+     *
+     * @param context Execution context to validate
+     * @returns Validation result with details
+     */
+    static validateContext(context: NeuroLinkExecutionContext): {
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Validate context permissions for tool execution
+     *
+     * @param context Execution context
+     * @param requiredPermissions Permissions required by tool
+     * @returns Whether context has required permissions
+     */
+    static hasPermissions(context: NeuroLinkExecutionContext, requiredPermissions: string[]): boolean;
+}

package/dist/mcp/context-manager.js

@@ -0,0 +1,273 @@
+/**
+ * NeuroLink MCP Context Management System
+ * Unified context creation and management for all tool executions
+ * Ensures rich context flows through tool chain with session tracking
+ */
+/**
+ * Context manager for creating and managing execution contexts
+ * Provides rich context for all tool executions with session tracking
+ */
+export class ContextManager {
+    sessionCounter = 0;
+    activeContexts = new Map();
+    /**
+     * Create a new execution context with rich information
+     *
+     * @param request Context creation request with optional fields
+     * @returns Complete execution context ready for tool chain
+     */
+    createContext(request = {}) {
+        // Generate session ID if not provided
+        const sessionId = request.sessionId || this.generateSessionId();
+        // Create comprehensive context
+        const context = {
+            // Session Management
+            sessionId,
+            userId: request.userId,
+            // AI Provider Context (from existing NeuroLink)
+            aiProvider: request.aiProvider,
+            modelId: request.modelId,
+            temperature: request.temperature,
+            maxTokens: request.maxTokens,
+            // Business Context (new for MCP)
+            organizationId: request.organizationId,
+            projectId: request.projectId,
+            environmentType: request.environmentType || 'development',
+            // Framework Context (new for MCP)
+            frameworkType: request.frameworkType,
+            // Tool Execution Context (initialized empty)
+            toolChain: [],
+            parentToolId: undefined,
+            // Security & Permissions
+            permissions: request.permissions || [],
+            securityLevel: request.securityLevel || 'private',
+            // Copy any additional custom fields
+            ...this.extractCustomFields(request)
+        };
+        // Store context for session management
+        this.activeContexts.set(sessionId, context);
+        return context;
+    }
+    /**
+     * Add a tool to the execution chain
+     *
+     * @param context Execution context to modify
+     * @param toolName Name of the tool being executed
+     */
+    addToToolChain(context, toolName) {
+        if (!context.toolChain) {
+            context.toolChain = [];
+        }
+        context.toolChain.push(toolName);
+        // Update the active context
+        this.activeContexts.set(context.sessionId, context);
+    }
+    /**
+     * Get the current tool chain for a context
+     *
+     * @param context Execution context
+     * @returns Array of tool names in execution order
+     */
+    getToolChain(context) {
+        return context.toolChain || [];
+    }
+    /**
+     * Set parent tool for nested tool execution
+     *
+     * @param context Execution context to modify
+     * @param parentToolId ID of the parent tool
+     */
+    setParentTool(context, parentToolId) {
+        context.parentToolId = parentToolId;
+        this.activeContexts.set(context.sessionId, context);
+    }
+    /**
+     * Create child context for nested tool execution
+     *
+     * @param parentContext Parent execution context
+     * @param childToolName Name of the child tool
+     * @returns New child context with inherited properties
+     */
+    createChildContext(parentContext, childToolName) {
+        const childContext = {
+            // Inherit all parent context
+            ...parentContext,
+            // Create new session ID for child
+            sessionId: this.generateSessionId(),
+            // Set parent tool reference
+            parentToolId: parentContext.toolChain?.[parentContext.toolChain.length - 1],
+            // Reset tool chain for child (will be populated as child executes tools)
+            toolChain: []
+        };
+        // Store child context
+        this.activeContexts.set(childContext.sessionId, childContext);
+        return childContext;
+    }
+    /**
+     * Get context by session ID
+     *
+     * @param sessionId Session identifier
+     * @returns Execution context or undefined if not found
+     */
+    getContext(sessionId) {
+        return this.activeContexts.get(sessionId);
+    }
+    /**
+     * Update context with new information
+     *
+     * @param sessionId Session identifier
+     * @param updates Partial context updates
+     */
+    updateContext(sessionId, updates) {
+        const context = this.activeContexts.get(sessionId);
+        if (context) {
+            const updatedContext = { ...context, ...updates };
+            this.activeContexts.set(sessionId, updatedContext);
+        }
+    }
+    /**
+     * Remove context from active tracking
+     *
+     * @param sessionId Session identifier
+     */
+    removeContext(sessionId) {
+        this.activeContexts.delete(sessionId);
+    }
+    /**
+     * Get all active contexts (for debugging/monitoring)
+     *
+     * @returns Array of all active contexts
+     */
+    getActiveContexts() {
+        return Array.from(this.activeContexts.values());
+    }
+    /**
+     * Clear all active contexts
+     */
+    clearAllContexts() {
+        this.activeContexts.clear();
+        this.sessionCounter = 0;
+    }
+    /**
+     * Get context statistics
+     *
+     * @returns Context usage statistics
+     */
+    getStats() {
+        const contexts = Array.from(this.activeContexts.values());
+        const totalToolChainLength = contexts.reduce((sum, ctx) => sum + (ctx.toolChain?.length || 0), 0);
+        return {
+            activeContexts: contexts.length,
+            totalSessionsCreated: this.sessionCounter,
+            averageToolChainLength: contexts.length > 0
+                ? totalToolChainLength / contexts.length
+                : 0
+        };
+    }
+    /**
+     * Generate unique session ID
+     *
+     * @returns Unique session identifier
+     */
+    generateSessionId() {
+        this.sessionCounter++;
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 8);
+        return `nlmcp-${timestamp}-${this.sessionCounter}-${random}`;
+    }
+    /**
+     * Extract custom fields from request (excluding known fields)
+     *
+     * @param request Context creation request
+     * @returns Custom fields object
+     */
+    extractCustomFields(request) {
+        const knownFields = new Set([
+            'sessionId', 'userId', 'aiProvider', 'modelId', 'temperature', 'maxTokens',
+            'organizationId', 'projectId', 'environmentType', 'frameworkType',
+            'permissions', 'securityLevel'
+        ]);
+        const customFields = {};
+        for (const [key, value] of Object.entries(request)) {
+            if (!knownFields.has(key)) {
+                customFields[key] = value;
+            }
+        }
+        return customFields;
+    }
+}
+/**
+ * Default context manager instance
+ * Can be used across the application for consistent context management
+ */
+export const defaultContextManager = new ContextManager();
+/**
+ * Utility function to create context with defaults
+ *
+ * @param request Optional context request
+ * @returns Execution context with sensible defaults
+ */
+export function createExecutionContext(request = {}) {
+    return defaultContextManager.createContext(request);
+}
+/**
+ * Utility function to add tool to default context manager
+ *
+ * @param context Execution context
+ * @param toolName Tool name to add
+ */
+export function addToolToChain(context, toolName) {
+    defaultContextManager.addToToolChain(context, toolName);
+}
+/**
+ * Context validation utilities
+ */
+export class ContextValidator {
+    /**
+     * Validate context has required fields for tool execution
+     *
+     * @param context Execution context to validate
+     * @returns Validation result with details
+     */
+    static validateContext(context) {
+        const errors = [];
+        const warnings = [];
+        // Required field validation
+        if (!context.sessionId) {
+            errors.push('sessionId is required');
+        }
+        // Optional field validation with warnings
+        if (!context.environmentType) {
+            warnings.push('environmentType not specified, defaulting to development');
+        }
+        if (!context.securityLevel) {
+            warnings.push('securityLevel not specified, defaulting to private');
+        }
+        // Tool chain validation
+        if (context.toolChain && context.toolChain.length > 10) {
+            warnings.push('Tool chain is getting long (>10 tools), consider breaking into smaller workflows');
+        }
+        return {
+            isValid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Validate context permissions for tool execution
+     *
+     * @param context Execution context
+     * @param requiredPermissions Permissions required by tool
+     * @returns Whether context has required permissions
+     */
+    static hasPermissions(context, requiredPermissions) {
+        if (!requiredPermissions || requiredPermissions.length === 0) {
+            return true;
+        }
+        const contextPermissions = context.permissions || [];
+        // Check if context has all required permissions
+        return requiredPermissions.every(permission => contextPermissions.includes(permission) ||
+            contextPermissions.includes('*') // Wildcard permission
+        );
+    }
+}

package/dist/mcp/factory.d.ts

@@ -0,0 +1,144 @@
+/**
+ * NeuroLink MCP Server Factory
+ * Factory-First Architecture: MCP servers create tools for internal orchestration
+ * Compatible with Lighthouse MCP patterns for seamless migration
+ */
+import { z } from 'zod';
+/**
+ * MCP Server Categories for organization and discovery
+ */
+export type MCPServerCategory = 'ai-providers' | 'frameworks' | 'development' | 'business' | 'content' | 'data' | 'integrations' | 'automation' | 'analysis' | 'custom';
+/**
+ * Tool execution context - Rich context passed to every tool execution
+ * Based on Lighthouse patterns with NeuroLink enhancements
+ */
+export interface NeuroLinkExecutionContext {
+    sessionId: string;
+    userId?: string;
+    aiProvider?: string;
+    modelId?: string;
+    temperature?: number;
+    maxTokens?: number;
+    organizationId?: string;
+    projectId?: string;
+    environmentType?: 'development' | 'staging' | 'production';
+    frameworkType?: 'react' | 'vue' | 'svelte' | 'next' | 'nuxt' | 'sveltekit';
+    toolChain?: string[];
+    parentToolId?: string;
+    permissions?: string[];
+    securityLevel?: 'public' | 'private' | 'organization';
+    [key: string]: any;
+}
+/**
+ * Tool execution result - Standardized result format
+ */
+export interface ToolResult {
+    success: boolean;
+    data?: any;
+    error?: string;
+    usage?: {
+        tokens?: number;
+        cost?: number;
+        provider?: string;
+        model?: string;
+        executionTime?: number;
+    };
+    metadata?: {
+        toolName?: string;
+        serverId?: string;
+        serverTitle?: string;
+        sessionId?: string;
+        timestamp?: number;
+        executionTime?: number;
+    };
+}
+/**
+ * MCP Tool Interface - Lighthouse compatible with NeuroLink enhancements
+ */
+export interface NeuroLinkMCPTool {
+    name: string;
+    description: string;
+    execute: (params: unknown, context: NeuroLinkExecutionContext) => Promise<ToolResult>;
+    inputSchema?: z.ZodSchema;
+    outputSchema?: z.ZodSchema;
+    isImplemented?: boolean;
+    category?: string;
+    permissions?: string[];
+    version?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * MCP Server Interface - 99% Lighthouse compatible
+ * Minimal required fields for easy adoption
+ */
+export interface NeuroLinkMCPServer {
+    id: string;
+    title: string;
+    description?: string;
+    version?: string;
+    category?: MCPServerCategory;
+    visibility?: 'public' | 'private' | 'organization';
+    tools: Record<string, NeuroLinkMCPTool>;
+    registerTool: (tool: NeuroLinkMCPTool) => NeuroLinkMCPServer;
+    metadata?: Record<string, any>;
+    dependencies?: string[];
+    capabilities?: string[];
+}
+/**
+ * MCP Server Configuration for creation
+ */
+export interface MCPServerConfig {
+    id: string;
+    title: string;
+    description?: string;
+    version?: string;
+    category?: MCPServerCategory;
+    visibility?: 'public' | 'private' | 'organization';
+    metadata?: Record<string, any>;
+    dependencies?: string[];
+    capabilities?: string[];
+}
+/**
+ * Create MCP Server Factory Function
+ *
+ * Core factory function for creating Lighthouse-compatible MCP servers.
+ * Follows Factory-First architecture where tools are internal implementation.
+ *
+ * @param config Server configuration with minimal required fields
+ * @returns Fully configured MCP server ready for tool registration
+ *
+ * @example
+ * ```typescript
+ * const aiCoreServer = createMCPServer({
+ *   id: 'neurolink-ai-core',
+ *   title: 'NeuroLink AI Core',
+ *   description: 'Core AI provider tools',
+ *   category: 'ai-providers'
+ * });
+ *
+ * aiCoreServer.registerTool({
+ *   name: 'generate-text',
+ *   description: 'Generate text using AI providers',
+ *   execute: async (params, context) => {
+ *     // Tool implementation
+ *     return { success: true, data: result };
+ *   }
+ * });
+ * ```
+ */
+export declare function createMCPServer(config: MCPServerConfig): NeuroLinkMCPServer;
+/**
+ * Utility function to validate tool interface
+ */
+export declare function validateTool(tool: NeuroLinkMCPTool): boolean;
+/**
+ * Utility function to get server info
+ */
+export declare function getServerInfo(server: NeuroLinkMCPServer): {
+    id: string;
+    title: string;
+    description?: string;
+    category?: MCPServerCategory;
+    toolCount: number;
+    capabilities: string[];
+};