@juspay/neurolink 9.26.2 → 9.28.0

package/dist/lib/mcp/agentExposure.js

@@ -0,0 +1,357 @@
+/**
+ * Agent and Workflow Exposure as MCP Tools
+ *
+ * Enables exposing NeuroLink agents and workflows as MCP tools,
+ * allowing external MCP clients to invoke complex AI operations
+ * through the standardized MCP protocol.
+ *
+ * @module mcp/agentExposure
+ * @since 8.39.0
+ */
+import { logger } from "../utils/logger.js";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { ErrorFactory } from "../utils/errorHandling.js";
+/**
+ * Expose an agent as an MCP tool
+ */
+export function exposeAgentAsTool(agent, options = {}) {
+    const { prefix = "agent", defaultAnnotations = {}, includeMetadataInDescription = true, nameTransformer = (name) => name.toLowerCase().replace(/\s+/g, "_"), wrapWithContext = true, executionTimeout = 300000, // 5 minutes default
+    enableLogging = true, } = options;
+    // Generate tool name
+    const baseName = nameTransformer(agent.name);
+    const toolName = prefix ? `${prefix}_${baseName}` : baseName;
+    // Build description
+    let description = agent.description;
+    if (includeMetadataInDescription && agent.metadata) {
+        const metaParts = [];
+        if (agent.metadata.version) {
+            metaParts.push(`v${agent.metadata.version}`);
+        }
+        if (agent.metadata.category) {
+            metaParts.push(`category: ${agent.metadata.category}`);
+        }
+        if (agent.metadata.estimatedDuration) {
+            metaParts.push(`~${agent.metadata.estimatedDuration}ms`);
+        }
+        if (metaParts.length > 0) {
+            description += ` [${metaParts.join(", ")}]`;
+        }
+    }
+    // Build annotations
+    const annotations = {
+        ...defaultAnnotations,
+        complexity: defaultAnnotations.complexity ?? "complex",
+        estimatedDuration: agent.metadata?.estimatedDuration ?? defaultAnnotations.estimatedDuration,
+        costHint: agent.metadata?.costHint ?? defaultAnnotations.costHint,
+        tags: [
+            ...(defaultAnnotations.tags ?? []),
+            "agent",
+            ...(agent.metadata?.tags ?? []),
+        ],
+    };
+    // Build input schema with agent context
+    const inputSchema = agent.inputSchema ?? {
+        type: "object",
+        properties: {},
+    };
+    // Create execution wrapper
+    const execute = async (params, context) => {
+        const startTime = Date.now();
+        if (enableLogging) {
+            logger.debug(`[AgentExposure] Executing agent '${agent.id}' as tool '${toolName}'`);
+        }
+        try {
+            // Execute agent with context wrapper if enabled
+            const existingConfig = context?.config && typeof context.config === "object"
+                ? context.config
+                : {};
+            const executionContext = wrapWithContext
+                ? {
+                    ...context,
+                    config: {
+                        ...existingConfig,
+                        sourceType: "mcp-exposed-agent",
+                        agentId: agent.id,
+                        toolName,
+                    },
+                }
+                : (context ?? {});
+            const result = await withTimeout(agent.execute(params, executionContext), executionTimeout);
+            const duration = Date.now() - startTime;
+            if (enableLogging) {
+                logger.debug(`[AgentExposure] Agent '${agent.id}' completed in ${duration}ms`);
+            }
+            return {
+                success: true,
+                data: result,
+                metadata: {
+                    agentId: agent.id,
+                    toolName,
+                    executionTime: duration,
+                    sourceType: "agent",
+                },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const agentError = error instanceof Error
+                ? error
+                : ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
+            if (enableLogging) {
+                logger.error(`[AgentExposure] Agent '${agent.id}' failed after ${duration}ms: ${agentError.message}`);
+            }
+            return {
+                success: false,
+                error: agentError.message,
+                metadata: {
+                    agentId: agent.id,
+                    toolName,
+                    executionTime: duration,
+                    sourceType: "agent",
+                },
+            };
+        }
+    };
+    const tool = {
+        name: toolName,
+        description,
+        inputSchema,
+        outputSchema: agent.outputSchema,
+        annotations,
+        execute,
+        metadata: {
+            sourceType: "agent",
+            sourceId: agent.id,
+            originalName: agent.name,
+            ...agent.metadata,
+        },
+    };
+    return {
+        tool,
+        sourceType: "agent",
+        sourceId: agent.id,
+        toolName,
+    };
+}
+/**
+ * Expose a workflow as an MCP tool
+ */
+export function exposeWorkflowAsTool(workflow, options = {}) {
+    const { prefix = "workflow", defaultAnnotations = {}, includeMetadataInDescription = true, nameTransformer = (name) => name.toLowerCase().replace(/\s+/g, "_"), wrapWithContext = true, executionTimeout = 600000, // 10 minutes default for workflows
+    enableLogging = true, } = options;
+    // Generate tool name
+    const baseName = nameTransformer(workflow.name);
+    const toolName = prefix ? `${prefix}_${baseName}` : baseName;
+    // Build description
+    let description = workflow.description;
+    if (includeMetadataInDescription) {
+        const metaParts = [];
+        if (workflow.metadata?.version) {
+            metaParts.push(`v${workflow.metadata.version}`);
+        }
+        if (workflow.steps?.length) {
+            metaParts.push(`${workflow.steps.length} steps`);
+        }
+        if (workflow.metadata?.estimatedDuration) {
+            metaParts.push(`~${workflow.metadata.estimatedDuration}ms`);
+        }
+        if (metaParts.length > 0) {
+            description += ` [${metaParts.join(", ")}]`;
+        }
+    }
+    // Build annotations
+    const annotations = {
+        ...defaultAnnotations,
+        complexity: defaultAnnotations.complexity ?? "complex",
+        estimatedDuration: workflow.metadata?.estimatedDuration ??
+            defaultAnnotations.estimatedDuration,
+        idempotentHint: workflow.metadata?.idempotent ?? defaultAnnotations.idempotentHint,
+        tags: [
+            ...(defaultAnnotations.tags ?? []),
+            "workflow",
+            ...(workflow.metadata?.tags ?? []),
+        ],
+    };
+    // Build input schema
+    const inputSchema = workflow.inputSchema ?? {
+        type: "object",
+        properties: {},
+    };
+    // Create execution wrapper
+    const execute = async (params, context) => {
+        const startTime = Date.now();
+        if (enableLogging) {
+            logger.debug(`[WorkflowExposure] Executing workflow '${workflow.id}' as tool '${toolName}'`);
+        }
+        try {
+            // Execute workflow with context wrapper if enabled
+            const existingConfig = context?.config && typeof context.config === "object"
+                ? context.config
+                : {};
+            const executionContext = wrapWithContext
+                ? {
+                    ...context,
+                    config: {
+                        ...existingConfig,
+                        sourceType: "mcp-exposed-workflow",
+                        workflowId: workflow.id,
+                        toolName,
+                    },
+                }
+                : (context ?? {});
+            const result = await withTimeout(workflow.execute(params, executionContext), executionTimeout);
+            const duration = Date.now() - startTime;
+            if (enableLogging) {
+                logger.debug(`[WorkflowExposure] Workflow '${workflow.id}' completed in ${duration}ms`);
+            }
+            return {
+                success: true,
+                data: result,
+                metadata: {
+                    workflowId: workflow.id,
+                    toolName,
+                    executionTime: duration,
+                    sourceType: "workflow",
+                    stepsCount: workflow.steps?.length,
+                },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const workflowError = error instanceof Error
+                ? error
+                : ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
+            if (enableLogging) {
+                logger.error(`[WorkflowExposure] Workflow '${workflow.id}' failed after ${duration}ms: ${workflowError.message}`);
+            }
+            return {
+                success: false,
+                error: workflowError.message,
+                metadata: {
+                    workflowId: workflow.id,
+                    toolName,
+                    executionTime: duration,
+                    sourceType: "workflow",
+                },
+            };
+        }
+    };
+    const tool = {
+        name: toolName,
+        description,
+        inputSchema,
+        outputSchema: workflow.outputSchema,
+        annotations,
+        execute,
+        metadata: {
+            sourceType: "workflow",
+            sourceId: workflow.id,
+            originalName: workflow.name,
+            steps: workflow.steps,
+            ...workflow.metadata,
+        },
+    };
+    return {
+        tool,
+        sourceType: "workflow",
+        sourceId: workflow.id,
+        toolName,
+    };
+}
+/**
+ * Batch expose agents as MCP tools
+ */
+export function exposeAgentsAsTools(agents, options = {}) {
+    return agents.map((agent) => exposeAgentAsTool(agent, options));
+}
+/**
+ * Batch expose workflows as MCP tools
+ */
+export function exposeWorkflowsAsTools(workflows, options = {}) {
+    return workflows.map((workflow) => exposeWorkflowAsTool(workflow, options));
+}
+/**
+ * Agent Exposure Manager
+ *
+ * Manages the lifecycle of exposed agents and workflows,
+ * providing registration, lookup, and invocation capabilities.
+ */
+export class AgentExposureManager {
+    exposedTools = new Map();
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Expose an agent and register it
+     */
+    exposeAgent(agent) {
+        const result = exposeAgentAsTool(agent, this.options);
+        this.exposedTools.set(result.toolName, result);
+        return result.tool;
+    }
+    /**
+     * Expose a workflow and register it
+     */
+    exposeWorkflow(workflow) {
+        const result = exposeWorkflowAsTool(workflow, this.options);
+        this.exposedTools.set(result.toolName, result);
+        return result.tool;
+    }
+    /**
+     * Get all exposed tools
+     */
+    getExposedTools() {
+        return Array.from(this.exposedTools.values()).map((r) => r.tool);
+    }
+    /**
+     * Get exposed tool by name
+     */
+    getExposedTool(toolName) {
+        return this.exposedTools.get(toolName)?.tool;
+    }
+    /**
+     * Get exposure result by tool name
+     */
+    getExposureResult(toolName) {
+        return this.exposedTools.get(toolName);
+    }
+    /**
+     * Get tools by source type
+     */
+    getToolsBySourceType(sourceType) {
+        return Array.from(this.exposedTools.values())
+            .filter((r) => r.sourceType === sourceType)
+            .map((r) => r.tool);
+    }
+    /**
+     * Remove exposed tool
+     */
+    unexpose(toolName) {
+        return this.exposedTools.delete(toolName);
+    }
+    /**
+     * Clear all exposed tools
+     */
+    clear() {
+        this.exposedTools.clear();
+    }
+    /**
+     * Get statistics
+     */
+    getStatistics() {
+        const results = Array.from(this.exposedTools.values());
+        return {
+            totalExposed: results.length,
+            exposedAgents: results.filter((r) => r.sourceType === "agent").length,
+            exposedWorkflows: results.filter((r) => r.sourceType === "workflow")
+                .length,
+            toolNames: results.map((r) => r.toolName),
+        };
+    }
+}
+/**
+ * Global agent exposure manager instance
+ */
+export const globalAgentExposureManager = new AgentExposureManager();
+//# sourceMappingURL=agentExposure.js.map

package/dist/lib/mcp/batching/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Batching Module - Request batching for efficiency
+ *
+ * Provides intelligent batching of MCP tool calls:
+ * - Automatic batch size management
+ * - Configurable wait times
+ * - Server-grouped batching
+ * - Parallel batch execution
+ */
+export type { BatchConfig, BatchExecutor, BatcherEvents, BatchResult, } from "./requestBatcher.js";
+export { createRequestBatcher, createToolCallBatcher, DEFAULT_BATCH_CONFIG, RequestBatcher, ToolCallBatcher, } from "./requestBatcher.js";

package/dist/lib/mcp/batching/index.js

@@ -0,0 +1,11 @@
+/**
+ * MCP Batching Module - Request batching for efficiency
+ *
+ * Provides intelligent batching of MCP tool calls:
+ * - Automatic batch size management
+ * - Configurable wait times
+ * - Server-grouped batching
+ * - Parallel batch execution
+ */
+export { createRequestBatcher, createToolCallBatcher, DEFAULT_BATCH_CONFIG, RequestBatcher, ToolCallBatcher, } from "./requestBatcher.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/mcp/batching/requestBatcher.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Request Batcher - Batches multiple tool calls for efficiency
+ *
+ * Provides intelligent batching of MCP tool calls to reduce overhead
+ * and improve throughput. Supports automatic flushing based on:
+ * - Maximum batch size
+ * - Maximum wait time
+ * - Manual flush triggers
+ */
+import { EventEmitter } from "events";
+/**
+ * Batch configuration options
+ */
+export type BatchConfig = {
+    /**
+     * Maximum number of requests to batch together (default: 10)
+     */
+    maxBatchSize: number;
+    /**
+     * Maximum time to wait for a full batch in milliseconds (default: 100ms)
+     */
+    maxWaitMs: number;
+    /**
+     * Enable parallel execution of batched requests (default: true).
+     * Reserved for future parallel batch execution; currently stored but not read.
+     */
+    enableParallel?: boolean;
+    /**
+     * Maximum concurrent batches in flight (default: 5)
+     */
+    maxConcurrentBatches?: number;
+    /**
+     * Group requests by server ID (default: true)
+     */
+    groupByServer?: boolean;
+};
+/**
+ * Batch execution result
+ */
+export type BatchResult<T> = {
+    id: string;
+    success: boolean;
+    result?: T;
+    error?: Error;
+    executionTime: number;
+};
+/**
+ * Batch executor function type
+ */
+export type BatchExecutor<T> = (requests: Array<{
+    tool: string;
+    args: unknown;
+    serverId?: string;
+}>) => Promise<Array<{
+    success: boolean;
+    result?: T;
+    error?: Error;
+}>>;
+/**
+ * Batcher events
+ */
+export type BatcherEvents<T> = {
+    batchStarted: {
+        batchId: string;
+        size: number;
+    };
+    batchCompleted: {
+        batchId: string;
+        results: BatchResult<T>[];
+    };
+    batchFailed: {
+        batchId: string;
+        error: Error;
+    };
+    requestQueued: {
+        requestId: string;
+        queueSize: number;
+    };
+    flushTriggered: {
+        reason: "size" | "timeout" | "manual";
+        queueSize: number;
+    };
+};
+/**
+ * Request Batcher - Efficient batch processing for MCP tool calls
+ *
+ * @example
+ * ```typescript
+ * const batcher = new RequestBatcher<ToolResult>({
+ *   maxBatchSize: 10,
+ *   maxWaitMs: 100,
+ * });
+ *
+ * // Set the batch executor
+ * batcher.setExecutor(async (requests) => {
+ *   // Execute all requests in a batch
+ *   return await Promise.all(requests.map(r => executeTool(r.tool, r.args)));
+ * });
+ *
+ * // Add requests - they'll be batched automatically
+ * const result1 = await batcher.add('getUserById', { id: 1 });
+ * const result2 = await batcher.add('getUserById', { id: 2 });
+ * ```
+ */
+export declare class RequestBatcher<T = unknown> extends EventEmitter {
+    private config;
+    private pending;
+    private serverQueues;
+    private flushTimer?;
+    private executor?;
+    private activeBatches;
+    private batchCounter;
+    private requestCounter;
+    private isDestroyed;
+    constructor(config: BatchConfig);
+    /**
+     * Set the batch executor function
+     */
+    setExecutor(executor: BatchExecutor<T>): void;
+    /**
+     * Add a request to the batch queue
+     */
+    add(tool: string, args: unknown, serverId?: string): Promise<T>;
+    /**
+     * Manually flush the current batch
+     */
+    flush(): Promise<void>;
+    /**
+     * Get current queue size
+     */
+    get queueSize(): number;
+    /**
+     * Get number of active batches
+     */
+    get activeBatchCount(): number;
+    /**
+     * Check if the batcher is idle (no pending requests)
+     */
+    get isIdle(): boolean;
+    /**
+     * Wait for all pending requests to complete
+     */
+    drain(): Promise<void>;
+    /**
+     * Destroy the batcher and reject all pending requests
+     */
+    destroy(): void;
+    private generateRequestId;
+    private generateBatchId;
+    private scheduleFlush;
+    private clearFlushTimer;
+    private executeBatch;
+    private selectBatchRequests;
+}
+/**
+ * Factory function to create a RequestBatcher instance
+ */
+export declare const createRequestBatcher: <T = unknown>(config: BatchConfig) => RequestBatcher<T>;
+/**
+ * Default batcher configuration
+ */
+export declare const DEFAULT_BATCH_CONFIG: BatchConfig;
+/**
+ * Tool Call Batcher - Specialized batcher for MCP tool calls
+ */
+export declare class ToolCallBatcher {
+    private batcher;
+    private toolExecutor?;
+    constructor(config?: Partial<BatchConfig>);
+    /**
+     * Set the tool executor function
+     */
+    setToolExecutor(executor: (tool: string, args: unknown, serverId?: string) => Promise<unknown>): void;
+    /**
+     * Execute a tool call (will be batched automatically)
+     */
+    execute(tool: string, args: unknown, serverId?: string): Promise<unknown>;
+    /**
+     * Flush pending tool calls
+     */
+    flush(): Promise<void>;
+    /**
+     * Wait for all pending tool calls to complete
+     */
+    drain(): Promise<void>;
+    /**
+     * Get current queue size
+     */
+    get queueSize(): number;
+    /**
+     * Check if idle
+     */
+    get isIdle(): boolean;
+    /**
+     * Destroy the batcher
+     */
+    destroy(): void;
+}
+/**
+ * Create a tool call batcher instance
+ */
+export declare const createToolCallBatcher: (config?: Partial<BatchConfig>) => ToolCallBatcher;