@juspay/neurolink 7.13.0 → 7.14.1

package/dist/lib/types/externalMcp.d.ts

@@ -0,0 +1,288 @@
+/**
+ * External MCP Server Types
+ * Comprehensive type system for external MCP server integration
+ * Following MCP 2024-11-05 specification
+ */
+import type { JsonValue, JsonObject } from "./common.js";
+import type { ChildProcess } from "child_process";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+/**
+ * Supported MCP transport protocols
+ */
+export type MCPTransportType = "stdio" | "sse" | "websocket";
+/**
+ * External MCP server configuration for process spawning
+ */
+export interface ExternalMCPServerConfig {
+    /** Unique identifier for the server */
+    id: string;
+    /** Command to execute (e.g., 'npx', 'node', 'python') */
+    command: string;
+    /** Arguments to pass to the command */
+    args: string[];
+    /** Environment variables for the process */
+    env?: Record<string, string>;
+    /** Transport protocol to use */
+    transport: MCPTransportType;
+    /** Connection timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Maximum retry attempts for connection (default: 3) */
+    retries?: number;
+    /** Health check interval in milliseconds (default: 30000) */
+    healthCheckInterval?: number;
+    /** Whether to automatically restart on failure (default: true) */
+    autoRestart?: boolean;
+    /** Working directory for the process */
+    cwd?: string;
+    /** URL for SSE/WebSocket transports */
+    url?: string;
+    /** Additional metadata */
+    metadata?: Record<string, JsonValue>;
+}
+/**
+ * Runtime state of an external MCP server instance
+ */
+export interface ExternalMCPServerInstance {
+    /** Server configuration */
+    config: ExternalMCPServerConfig;
+    /** Child process (for stdio transport) */
+    process: ChildProcess | null;
+    /** MCP client instance */
+    client: Client | null;
+    /** Transport instance */
+    transport: Transport | null;
+    /** Current server status */
+    status: ExternalMCPServerStatus;
+    /** Last error message if any */
+    lastError?: string;
+    /** When the server was started */
+    startTime?: Date;
+    /** When the server was last seen healthy */
+    lastHealthCheck?: Date;
+    /** Number of reconnection attempts */
+    reconnectAttempts: number;
+    /** Maximum reconnection attempts before giving up */
+    maxReconnectAttempts: number;
+    /** Available tools from this server */
+    tools: Map<string, ExternalMCPToolInfo>;
+    /** Cached tools array for ZERO conversion - MCP format */
+    toolsArray?: Array<{
+        name: string;
+        description: string;
+        inputSchema?: object;
+    }>;
+    /** Server capabilities reported by MCP */
+    capabilities?: Record<string, JsonValue>;
+    /** Health monitoring timer */
+    healthTimer?: NodeJS.Timeout;
+    /** Restart backoff timer */
+    restartTimer?: NodeJS.Timeout;
+    /** Performance metrics */
+    metrics: {
+        totalConnections: number;
+        totalDisconnections: number;
+        totalErrors: number;
+        totalToolCalls: number;
+        averageResponseTime: number;
+        lastResponseTime: number;
+    };
+}
+/**
+ * External MCP server status states
+ */
+export type ExternalMCPServerStatus = "initializing" | "connecting" | "connected" | "disconnected" | "failed" | "restarting" | "stopping" | "stopped";
+/**
+ * Tool information from external MCP server
+ */
+export interface ExternalMCPToolInfo {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description: string;
+    /** Server ID that provides this tool */
+    serverId: string;
+    /** Input schema (JSON Schema) */
+    inputSchema?: JsonObject;
+    /** Whether the tool is currently available */
+    isAvailable: boolean;
+    /** Tool metadata */
+    metadata?: Record<string, JsonValue>;
+    /** When the tool was last successfully called */
+    lastCalled?: Date;
+    /** Tool execution statistics */
+    stats: {
+        totalCalls: number;
+        successfulCalls: number;
+        failedCalls: number;
+        averageExecutionTime: number;
+        lastExecutionTime: number;
+    };
+}
+/**
+ * External MCP server health status
+ */
+export interface ExternalMCPServerHealth {
+    /** Server ID */
+    serverId: string;
+    /** Whether the server is healthy */
+    isHealthy: boolean;
+    /** Current status */
+    status: ExternalMCPServerStatus;
+    /** When the health check was performed */
+    checkedAt: Date;
+    /** Response time for health check */
+    responseTime?: number;
+    /** Number of available tools */
+    toolCount: number;
+    /** Any health issues detected */
+    issues: string[];
+    /** Performance metrics */
+    performance: {
+        uptime: number;
+        memoryUsage?: number;
+        cpuUsage?: number;
+        averageResponseTime: number;
+    };
+}
+/**
+ * External MCP server configuration validation result
+ */
+export interface ExternalMCPConfigValidation {
+    /** Whether the configuration is valid */
+    isValid: boolean;
+    /** Validation errors */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
+    /** Suggestions for improvement */
+    suggestions: string[];
+}
+/**
+ * External MCP server operation result
+ */
+export interface ExternalMCPOperationResult<T = unknown> {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Result data if successful */
+    data?: T;
+    /** Error message if failed */
+    error?: string;
+    /** Server ID */
+    serverId?: string;
+    /** Operation duration in milliseconds */
+    duration?: number;
+    /** Additional metadata */
+    metadata?: {
+        timestamp: number;
+        operation: string;
+        [key: string]: JsonValue;
+    };
+}
+/**
+ * External MCP tool execution context
+ */
+export interface ExternalMCPToolContext {
+    /** Execution session ID */
+    sessionId: string;
+    /** User ID if available */
+    userId?: string;
+    /** Server ID executing the tool */
+    serverId: string;
+    /** Tool name being executed */
+    toolName: string;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
+    /** Additional context data */
+    metadata?: Record<string, JsonValue>;
+}
+/**
+ * External MCP tool execution result
+ */
+export interface ExternalMCPToolResult {
+    /** Whether the execution was successful */
+    success: boolean;
+    /** Result data if successful */
+    data?: unknown;
+    /** Error message if failed */
+    error?: string;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Tool execution metadata */
+    metadata?: {
+        toolName: string;
+        serverId: string;
+        timestamp: number;
+        [key: string]: JsonValue;
+    };
+}
+/**
+ * External MCP server events
+ */
+export interface ExternalMCPServerEvents {
+    /** Server status changed */
+    statusChanged: {
+        serverId: string;
+        oldStatus: ExternalMCPServerStatus;
+        newStatus: ExternalMCPServerStatus;
+        timestamp: Date;
+    };
+    /** Server connected successfully */
+    connected: {
+        serverId: string;
+        toolCount: number;
+        timestamp: Date;
+    };
+    /** Server disconnected */
+    disconnected: {
+        serverId: string;
+        reason?: string;
+        timestamp: Date;
+    };
+    /** Server failed */
+    failed: {
+        serverId: string;
+        error: string;
+        timestamp: Date;
+    };
+    /** Tool discovered */
+    toolDiscovered: {
+        serverId: string;
+        toolName: string;
+        toolInfo: ExternalMCPToolInfo;
+        timestamp: Date;
+    };
+    /** Tool removed */
+    toolRemoved: {
+        serverId: string;
+        toolName: string;
+        timestamp: Date;
+    };
+    /** Health check completed */
+    healthCheck: {
+        serverId: string;
+        health: ExternalMCPServerHealth;
+        timestamp: Date;
+    };
+}
+/**
+ * External MCP manager configuration
+ */
+export interface ExternalMCPManagerConfig {
+    /** Maximum number of concurrent servers */
+    maxServers?: number;
+    /** Default timeout for operations */
+    defaultTimeout?: number;
+    /** Default health check interval */
+    defaultHealthCheckInterval?: number;
+    /** Whether to enable automatic restart */
+    enableAutoRestart?: boolean;
+    /** Maximum restart attempts per server */
+    maxRestartAttempts?: number;
+    /** Restart backoff multiplier */
+    restartBackoffMultiplier?: number;
+    /** Whether to enable performance monitoring */
+    enablePerformanceMonitoring?: boolean;
+    /** Log level for external MCP operations */
+    logLevel?: "debug" | "info" | "warn" | "error";
+}

package/dist/lib/types/externalMcp.js

@@ -0,0 +1,7 @@
+/**
+ * External MCP Server Types
+ * Comprehensive type system for external MCP server integration
+ * Following MCP 2024-11-05 specification
+ */
+export {};
+// Note: In Phase 2, these interfaces will be consolidated into MCPServerInfo

package/dist/lib/types/generateTypes.d.ts

@@ -73,7 +73,6 @@ export interface GenerateResult {
         name: string;
         input: Record<string, unknown>;
         output: unknown;
-        duration: number;
     }>;
     enhancedWithTools?: boolean;
     availableTools?: Array<{

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

@@ -1,6 +1,5 @@
 /**
  * Centralized type exports for NeuroLink
- * Provides type-safe alternatives to 'any' usage throughout the codebase
  */
 export * from "./common.js";
 export * from "./tools.js";
@@ -10,7 +9,8 @@ export type { Unknown, UnknownRecord, UnknownArray, JsonValue, JsonObject, JsonA
 export type { ToolArgs, ToolContext, ToolResult, ToolDefinition, SimpleTool, AvailableTool, ToolExecution, } from "./tools.js";
 export type { AISDKModel, ProviderError, TokenUsage, AnalyticsData, EvaluationData, ProviderConfig, } from "./providers.js";
 export type { BaseCommandArgs, GenerateCommandArgs, MCPCommandArgs, ModelsCommandArgs, CommandResult, GenerateResult, StreamChunk, } from "./cli.js";
-export type { MCPTransportType, MCPServerStatus, MCPDiscoveredServer, MCPConnectedServer, MCPServerConfig, MCPToolInfo, MCPServerMetadata, MCPToolMetadata, MCPServerRegistryEntry, } from "./mcpTypes.js";
+export type { MCPTransportType, MCPServerConnectionStatus, MCPServerCategory, MCPServerStatus, MCPDiscoveredServer, MCPConnectedServer, MCPToolInfo, MCPExecutableTool, MCPServerMetadata, MCPToolMetadata, MCPServerRegistryEntry, } from "./mcpTypes.js";
+export type { ExternalMCPServerInstance, ExternalMCPServerStatus, ExternalMCPToolInfo, ExternalMCPServerHealth, ExternalMCPConfigValidation, ExternalMCPOperationResult, ExternalMCPToolContext, ExternalMCPToolResult, ExternalMCPServerEvents, ExternalMCPManagerConfig, } from "./externalMcp.js";
 export type { ModelCapability, ModelUseCase, ModelFilter, ModelResolutionContext, ModelStats, ModelPricing, } from "./providers.js";
 export type { ToolCallResults, ToolCalls, StreamAnalyticsData, } from "./streamTypes.js";
 export type { DomainType, DomainConfig, DomainTemplate, DomainConfigOptions, DomainEvaluationCriteria, DomainValidationRule, } from "./domainTypes.js";

package/dist/lib/types/index.js

@@ -1,6 +1,5 @@
 /**
  * Centralized type exports for NeuroLink
- * Provides type-safe alternatives to 'any' usage throughout the codebase
  */
 // Common utility types
 export * from "./common.js";

package/dist/lib/types/mcpTypes.d.ts

@@ -6,93 +6,57 @@ import type { JsonValue, JsonObject } from "./common.js";
 /**
  * In-memory MCP server configuration
  */
-export interface InMemoryMCPServerConfig {
-    /**
-     * The actual server instance with tools
-     */
-    server: {
-        /**
-         * Server title for display
-         */
-        title?: string;
-        /**
-         * Map of tool name to tool implementation
-         */
-        tools: Map<string, InMemoryToolInfo> | Record<string, InMemoryToolInfo>;
-        /**
-         * Optional server description
-         */
-        description?: string;
-    };
-    /**
-     * Category for grouping tools
-     */
-    category?: string;
-    /**
-     * Metadata about the server
-     */
-    metadata?: {
-        provider?: string;
-        version?: string;
-        author?: string;
-        [key: string]: unknown;
-    };
-}
 /**
- * In-memory tool information
+ * MCP Transport Types - Maximally Reusable
  */
-export interface InMemoryToolInfo {
-    /**
-     * Tool description
-     */
-    description: string;
-    /**
-     * Tool execution function
-     */
-    execute: (params: unknown) => Promise<InMemoryToolResult> | InMemoryToolResult;
-    /**
-     * Input parameter schema (Zod or JSON Schema)
-     */
-    inputSchema?: unknown;
-    /**
-     * Whether the tool is implemented (default: true)
-     */
-    isImplemented?: boolean;
-    /**
-     * Optional metadata
-     */
-    metadata?: Record<string, unknown>;
-}
+export type MCPTransportType = "stdio" | "sse" | "websocket" | "ws" | "tcp" | "unix";
 /**
- * Result from in-memory tool execution
+ * MCP Server Connection Status - Individual server status
  */
-export interface InMemoryToolResult {
-    /**
-     * Whether execution was successful
-     */
-    success: boolean;
-    /**
-     * Result data if successful
-     */
-    data?: unknown;
-    /**
-     * Error message if failed
-     */
+export type MCPServerConnectionStatus = "initializing" | "connecting" | "connected" | "disconnected" | "failed" | "restarting" | "stopping" | "stopped";
+/**
+ * MCP Server Category Types - Organizational classification
+ */
+export type MCPServerCategory = "external" | "in-memory" | "built-in" | "user-defined" | "custom" | "uncategorized";
+/**
+ * Universal MCP Server - Unified configuration and runtime state
+ * MCP 2024-11-05 specification compliant
+ * Replaces both MCPServerInfo and MCPServerConfig
+ */
+export interface MCPServerInfo {
+    id: string;
+    name: string;
+    description: string;
+    transport: MCPTransportType;
+    status: MCPServerConnectionStatus;
+    tools: Array<{
+        name: string;
+        description: string;
+        inputSchema?: object;
+        execute?: (params: unknown, context?: unknown) => Promise<unknown> | unknown;
+    }>;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    timeout?: number;
+    retries?: number;
     error?: string;
-    /**
-     * Optional metadata about execution
-     */
+    installed?: boolean;
+    cwd?: string;
+    autoRestart?: boolean;
+    healthCheckInterval?: number;
     metadata?: {
-        executionTime?: number;
-        toolName?: string;
-        serverId?: string;
+        uptime?: number;
+        toolCount?: number;
+        category?: MCPServerCategory;
+        provider?: string;
+        version?: string;
+        author?: string;
+        tags?: string[];
         [key: string]: unknown;
     };
 }
-/**
- * MCP Transport Types - Maximally Reusable
- */
-export type MCPTransportType = "stdio" | "websocket" | "tcp" | "unix";
 /**
  * MCP Server Status for CLI Operations - High Reusability
  */
@@ -111,7 +75,7 @@ export interface MCPServerStatus {
     customToolsCount: number;
     /** Number of in-memory servers */
     inMemoryServersCount: number;
-    /** Error message if any */
+    /** Error message */
     error?: string;
     /** Auto-discovered servers from various sources */
     autoDiscoveredServers?: MCPDiscoveredServer[];
@@ -120,14 +84,14 @@ export interface MCPServerStatus {
     /** Available tools across all servers */
     availableTools: MCPToolInfo[];
     /** Server registry entries */
-    serverRegistry?: Record<string, MCPServerConfig>;
+    serverRegistry?: Record<string, MCPServerInfo>;
 }
 /**
  * Auto-discovered MCP Server - High Reusability
  */
 export interface MCPDiscoveredServer {
     name: string;
-    status: "connected" | "disconnected" | "error" | "pending" | "failed";
+    status: MCPServerConnectionStatus;
     source: string;
     transport: MCPTransportType;
     description?: string;
@@ -149,21 +113,6 @@ export interface MCPConnectedServer {
     connectionTime?: Date;
     metadata?: MCPServerMetadata;
 }
-/**
- * MCP Server Configuration - Maximally Reusable
- */
-export interface MCPServerConfig {
-    name: string;
-    transport: MCPTransportType;
-    description?: string;
-    command?: string;
-    args?: string[];
-    env?: Record<string, string>;
-    url?: string;
-    timeout?: number;
-    retries?: number;
-    metadata?: MCPServerMetadata;
-}
 /**
  * MCP Tool Information - High Reusability
  */
@@ -177,6 +126,11 @@ export interface MCPToolInfo {
     outputSchema?: JsonObject;
     metadata?: MCPToolMetadata;
 }
+/**
+ * MCP Executable Tool - Tool with execution capability
+ * Extracted from MCPServerInfo.tools array for better readability
+ */
+export type MCPExecutableTool = MCPServerInfo["tools"][0];
 /**
  * MCP Server Metadata - Extensible
  */
@@ -203,7 +157,7 @@ export type MCPToolMetadata = {
 /**
  * MCP Server Registry Entry - For Object.entries() usage
  */
-export type MCPServerRegistryEntry = [string, MCPServerConfig];
+export type MCPServerRegistryEntry = [string, MCPServerInfo];
 /**
  * Unified MCP Registry interface
  */
@@ -211,7 +165,7 @@ export interface UnifiedMCPRegistry {
     /**
      * Register an in-memory server
      */
-    registerInMemoryServer(serverId: string, config: InMemoryMCPServerConfig): Promise<void>;
+    registerInMemoryServer(serverId: string, serverInfo: MCPServerInfo): Promise<void>;
     /**
      * Get all available tools
      */
@@ -219,7 +173,7 @@ export interface UnifiedMCPRegistry {
     /**
      * Execute a tool
      */
-    executeTool(toolName: string, params: JsonObject, context: JsonObject): Promise<InMemoryToolResult>;
+    executeTool(toolName: string, params: JsonObject, context: JsonObject): Promise<unknown>;
     /**
      * Check if connected to a server
      */

package/dist/lib/types/providers.d.ts

@@ -1,6 +1,5 @@
 /**
  * Provider-specific type definitions for NeuroLink
- * Replaces 'any' types in provider implementations
  */
 import type { UnknownRecord, JsonValue } from "./common.js";
 /**

package/dist/lib/types/providers.js

@@ -1,6 +1,5 @@
 /**
  * Provider-specific type definitions for NeuroLink
- * Replaces 'any' types in provider implementations
  */
 /**
  * Type guard for provider error

package/dist/lib/types/tools.d.ts

@@ -1,6 +1,6 @@
 /**
- * Tool system type definitions for NeuroLink
- * Replaces 'any' types in tool registration and execution
+ * Type definitions for NeuroLink tool system, including parameter schemas,
+ * argument patterns, execution metadata, context, and result types.
  */
 import { z } from "zod";
 import type { Result, JsonValue, ErrorInfo } from "./common.js";

package/dist/lib/types/tools.js

@@ -1,6 +1,6 @@
 /**
- * Tool system type definitions for NeuroLink
- * Replaces 'any' types in tool registration and execution
+ * Type definitions for NeuroLink tool system, including parameter schemas,
+ * argument patterns, execution metadata, context, and result types.
  */
 /**
  * Type guard for tool result

package/dist/lib/utils/factoryProcessing.js

@@ -204,7 +204,7 @@ class FactoryProcessingCache {
         return hash >>> 0;
     }
     /**
-     * Hash any value to a numeric hash
+     * Hash random value to a numeric hash
      * Optimized for different value types
      */
     hashValue(value) {

package/dist/lib/utils/mcpDefaults.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Smart Defaults for MCPServerInfo Creation
+ * Eliminates boilerplate manual object creation
+ */
+import type { MCPServerInfo, MCPExecutableTool, MCPServerCategory } from "../types/mcpTypes.js";
+/**
+ * Smart category detection based on context
+ */
+export declare function detectCategory(context: {
+    isCustomTool?: boolean;
+    isExternal?: boolean;
+    isBuiltIn?: boolean;
+    serverId?: string;
+    existingCategory?: string;
+}): MCPServerCategory;
+/**
+ * Create MCPServerInfo with smart defaults
+ * Eliminates manual boilerplate object creation
+ */
+export declare function createMCPServerInfo(options: {
+    id?: string;
+    name: string;
+    tool?: MCPExecutableTool;
+    tools?: MCPServerInfo["tools"];
+    transport?: MCPServerInfo["transport"];
+    status?: MCPServerInfo["status"];
+    description?: string;
+    category?: string;
+    isCustomTool?: boolean;
+    isExternal?: boolean;
+    isBuiltIn?: boolean;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+}): MCPServerInfo;
+/**
+ * Create MCPServerInfo for custom tool registration
+ * Specialized version with smart defaults for registerTool usage
+ */
+export declare function createCustomToolServerInfo(toolName: string, tool: MCPExecutableTool): MCPServerInfo;
+/**
+ * Create MCPServerInfo for external servers
+ * Specialized version with smart defaults for external server usage
+ */
+export declare function createExternalServerInfo(options: {
+    id: string;
+    name?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    transport?: MCPServerInfo["transport"];
+    description?: string;
+    tools?: MCPServerInfo["tools"];
+}): MCPServerInfo;