@juspay/neurolink 3.0.1 → 4.1.0

package/dist/mcp/registry.d.ts

@@ -1,16 +1,25 @@
 /**
- * MCP Registry - Plugin Registration and Management
+ * MCP Registry - Industry Standard Interface with camelCase
  */
-import type { DiscoveredMCP } from "./contracts/mcp-contract.js";
+import type { DiscoveredMcp, ExecutionContext, ToolInfo } from "./contracts/mcpContract.js";
+/**
+ * MCP Registry interface with optional methods for maximum flexibility
+ */
+export interface McpRegistry {
+    registerServer?(serverId: string, serverConfig?: unknown, context?: ExecutionContext): Promise<void>;
+    executeTool?<T = unknown>(toolName: string, args?: unknown, context?: ExecutionContext): Promise<T>;
+    listTools?(context?: ExecutionContext): Promise<ToolInfo[]>;
+}
 /**
  * Simple MCP registry for plugin management
+ * Maintains backward compatibility with existing code
  */
-export declare class MCPRegistry {
+export declare class MCPRegistry implements McpRegistry {
     private plugins;
     /**
      * Register a plugin
      */
-    register(plugin: DiscoveredMCP): void;
+    register(plugin: DiscoveredMcp): void;
     /**
      * Unregister a plugin
      */
@@ -18,11 +27,11 @@ export declare class MCPRegistry {
     /**
      * Get a plugin
      */
-    get(name: string): DiscoveredMCP | undefined;
+    get(name: string): DiscoveredMcp | undefined;
     /**
      * List all plugins
      */
-    list(): DiscoveredMCP[];
+    list(): DiscoveredMcp[];
     /**
      * Check if plugin exists
      */
@@ -31,17 +40,63 @@ export declare class MCPRegistry {
      * Clear all plugins
      */
     clear(): void;
+    /**
+     * Register a server (compatible with new interface)
+     */
+    registerServer(serverId: string, serverConfig?: unknown, context?: ExecutionContext): Promise<void>;
+    /**
+     * Execute a tool (mock implementation for tests)
+     */
+    executeTool<T = unknown>(toolName: string, args?: unknown, context?: ExecutionContext): Promise<T>;
+    /**
+     * List all tools (compatible with new interface)
+     */
+    listTools(context?: ExecutionContext): Promise<ToolInfo[]>;
+    /**
+     * Register a server (legacy sync version)
+     */
+    registerServerSync(plugin: DiscoveredMcp): void;
+    /**
+     * Execute a tool (legacy sync version)
+     */
+    executeToolSync(toolName: string, args?: unknown): any;
+    /**
+     * List all tools (legacy sync version)
+     */
+    listToolsSync(): Array<{
+        name: string;
+        description?: string;
+    }>;
+    /**
+     * List all registered server IDs
+     *
+     * Returns an array of server IDs that are currently registered in the MCP registry.
+     * This complements listTools() by providing server-level information, while listTools()
+     * provides tool-level information across all servers.
+     *
+     * @returns Array of registered server identifier strings
+     * @see listTools() for getting detailed tool information from all servers
+     * @see list() for getting complete server metadata objects
+     *
+     * @example
+     * ```typescript
+     * const serverIds = registry.listServers();
+     * // ['ai-core', 'external-api', 'database-connector']
+     *
+     * // Compare with listTools() for comprehensive overview:
+     * const servers = registry.listServers(); // ['server1', 'server2']
+     * const tools = await registry.listTools(); // [{ name: 'tool1', serverId: 'server1' }, ...]
+     * ```
+     */
+    listServers(): string[];
 }
 /**
- * Default registry instance
+ * Enhanced MCP Registry implementation with config integration
+ * Will be implemented in Phase 3.2
  */
-export declare const mcpRegistry: MCPRegistry;
-export type MCPToolRegistry = MCPRegistry;
-export declare const defaultToolRegistry: MCPRegistry;
-export { mcpRegistry as defaultMCPRegistry };
-export interface ToolExecutionOptions {
-    preferredSource?: string;
-    fallbackEnabled?: boolean;
-    validateBeforeExecution?: boolean;
-    timeoutMs?: number;
+export declare class McpRegistryImpl implements McpRegistry {
+    private baseRegistry;
+    registerServer(serverId: string, serverConfig?: unknown, context?: ExecutionContext): Promise<void>;
+    executeTool<T = unknown>(toolName: string, args?: unknown, context?: ExecutionContext): Promise<T>;
+    listTools(context?: ExecutionContext): Promise<ToolInfo[]>;
 }

package/dist/mcp/registry.js

@@ -1,9 +1,10 @@
 /**
- * MCP Registry - Plugin Registration and Management
+ * MCP Registry - Industry Standard Interface with camelCase
  */
 import { registryLogger } from "./logging.js";
 /**
  * Simple MCP registry for plugin management
+ * Maintains backward compatibility with existing code
  */
 export class MCPRegistry {
     plugins = new Map();
@@ -49,11 +50,108 @@ export class MCPRegistry {
         this.plugins.clear();
         registryLogger.info("Registry cleared");
     }
+    /**
+     * Register a server (compatible with new interface)
+     */
+    async registerServer(serverId, serverConfig, context) {
+        const plugin = {
+            metadata: {
+                name: serverId,
+                description: typeof serverConfig === "object" && serverConfig
+                    ? serverConfig.description || "No description"
+                    : "No description",
+            },
+            tools: typeof serverConfig === "object" && serverConfig
+                ? serverConfig.tools
+                : {},
+            configuration: typeof serverConfig === "object" && serverConfig
+                ? serverConfig
+                : {},
+        };
+        this.register(plugin);
+    }
+    /**
+     * Execute a tool (mock implementation for tests)
+     */
+    async executeTool(toolName, args, context) {
+        registryLogger.info(`Executing tool: ${toolName}`);
+        return { result: `Mock execution of ${toolName}`, args };
+    }
+    /**
+     * List all tools (compatible with new interface)
+     */
+    async listTools(context) {
+        const tools = this.list().map((plugin) => ({
+            name: plugin.metadata.name,
+            description: plugin.metadata.description || "No description",
+            serverId: plugin.metadata.name,
+            category: "general",
+        }));
+        return tools;
+    }
+    // Legacy methods for backward compatibility
+    /**
+     * Register a server (legacy sync version)
+     */
+    registerServerSync(plugin) {
+        this.register(plugin);
+    }
+    /**
+     * Execute a tool (legacy sync version)
+     */
+    executeToolSync(toolName, args) {
+        registryLogger.info(`Executing tool (sync): ${toolName}`);
+        return { result: `Mock execution of ${toolName}`, args };
+    }
+    /**
+     * List all tools (legacy sync version)
+     */
+    listToolsSync() {
+        const tools = this.list().map((plugin) => ({
+            name: plugin.metadata.name,
+            description: plugin.metadata.description || "No description",
+        }));
+        return tools;
+    }
+    /**
+     * List all registered server IDs
+     *
+     * Returns an array of server IDs that are currently registered in the MCP registry.
+     * This complements listTools() by providing server-level information, while listTools()
+     * provides tool-level information across all servers.
+     *
+     * @returns Array of registered server identifier strings
+     * @see listTools() for getting detailed tool information from all servers
+     * @see list() for getting complete server metadata objects
+     *
+     * @example
+     * ```typescript
+     * const serverIds = registry.listServers();
+     * // ['ai-core', 'external-api', 'database-connector']
+     *
+     * // Compare with listTools() for comprehensive overview:
+     * const servers = registry.listServers(); // ['server1', 'server2']
+     * const tools = await registry.listTools(); // [{ name: 'tool1', serverId: 'server1' }, ...]
+     * ```
+     */
+    listServers() {
+        return Array.from(this.plugins.keys());
+    }
 }
 /**
- * Default registry instance
+ * Enhanced MCP Registry implementation with config integration
+ * Will be implemented in Phase 3.2
  */
-export const mcpRegistry = new MCPRegistry();
-export const defaultToolRegistry = mcpRegistry;
-// Additional exports for compatibility
-export { mcpRegistry as defaultMCPRegistry };
+export class McpRegistryImpl {
+    baseRegistry = new MCPRegistry();
+    // Additional implementation will be added in Phase 3.2
+    async registerServer(serverId, serverConfig, context) {
+        return this.baseRegistry.registerServer(serverId, serverConfig, context);
+    }
+    async executeTool(toolName, args, context) {
+        return this.baseRegistry.executeTool(toolName, args, context);
+    }
+    async listTools(context) {
+        return this.baseRegistry.listTools(context);
+    }
+}

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

@@ -0,0 +1,137 @@
+/**
+ * NeuroLink MCP Semaphore Manager
+ * Prevents race conditions in concurrent tool executions using a robust semaphore pattern
+ * Based on proven patterns from 1MCP reference implementation
+ */
+import type { NeuroLinkExecutionContext } from "./factory.js";
+/**
+ * Semaphore operation result
+ */
+export interface SemaphoreResult<T> {
+    success: boolean;
+    result?: T;
+    error?: Error;
+    waitTime: number;
+    executionTime: number;
+    queueDepth: number;
+}
+/**
+ * Semaphore statistics
+ */
+export interface SemaphoreStats {
+    activeOperations: number;
+    queuedOperations: number;
+    totalOperations: number;
+    totalWaitTime: number;
+    averageWaitTime: number;
+    peakQueueDepth: number;
+    lastActivity: number;
+}
+/**
+ * Semaphore Manager for concurrent operation control
+ * Implements the proven semaphore pattern from 1MCP to prevent race conditions
+ */
+export declare class SemaphoreManager {
+    private locks;
+    private queues;
+    private stats;
+    private globalStats;
+    /**
+     * Acquire a semaphore and execute an operation
+     * Ensures exclusive access to resources identified by the key
+     *
+     * @param key Unique identifier for the resource
+     * @param operation Async operation to execute with exclusive access
+     * @param context Optional execution context for enhanced tracking
+     * @returns Result of the operation with timing metrics
+     */
+    acquire<T>(key: string, operation: () => Promise<T>, context?: NeuroLinkExecutionContext): Promise<SemaphoreResult<T>>;
+    /**
+     * Try to acquire a semaphore without waiting
+     * Returns immediately if the resource is locked
+     *
+     * @param key Unique identifier for the resource
+     * @param operation Async operation to execute if lock is available
+     * @param context Optional execution context
+     * @returns Result of the operation or null if resource is locked
+     */
+    tryAcquire<T>(key: string, operation: () => Promise<T>, context?: NeuroLinkExecutionContext): Promise<SemaphoreResult<T> | null>;
+    /**
+     * Check if a resource is currently locked
+     *
+     * @param key Resource identifier
+     * @returns True if the resource is locked
+     */
+    isLocked(key: string): boolean;
+    /**
+     * Get the current queue depth for a resource
+     *
+     * @param key Resource identifier
+     * @returns Number of operations waiting for this resource
+     */
+    getQueueDepth(key: string): number;
+    /**
+     * Get statistics for a specific resource or global stats
+     *
+     * @param key Optional resource identifier
+     * @returns Semaphore statistics
+     */
+    getStats(key?: string): SemaphoreStats;
+    /**
+     * Clear all semaphores (use with caution)
+     * This will reject all pending operations
+     */
+    clearAll(): void;
+    /**
+     * Update queue depth statistics
+     *
+     * @private
+     */
+    private updateQueueDepth;
+    /**
+     * Increment active operations counter
+     *
+     * @private
+     */
+    private incrementActiveOperations;
+    /**
+     * Decrement active operations counter
+     *
+     * @private
+     */
+    private decrementActiveOperations;
+    /**
+     * Update timing statistics
+     *
+     * @private
+     */
+    private updateStats;
+    /**
+     * Create empty statistics object
+     *
+     * @private
+     */
+    private createEmptyStats;
+}
+/**
+ * Default semaphore manager instance
+ */
+export declare const defaultSemaphoreManager: SemaphoreManager;
+/**
+ * Utility function to acquire semaphore with default manager
+ *
+ * @param key Resource identifier
+ * @param operation Operation to execute
+ * @param context Optional execution context
+ * @returns Operation result with metrics
+ */
+export declare function acquireSemaphore<T>(key: string, operation: () => Promise<T>, context?: NeuroLinkExecutionContext): Promise<SemaphoreResult<T>>;
+/**
+ * Utility function to try acquiring semaphore without waiting
+ *
+ * @param key Resource identifier
+ * @param operation Operation to execute
+ * @param context Optional execution context
+ * @returns Operation result or null if locked
+ */
+export declare function tryAcquireSemaphore<T>(key: string, operation: () => Promise<T>, context?: NeuroLinkExecutionContext): Promise<SemaphoreResult<T> | null>;