@juspay/neurolink 7.12.0 → 7.14.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [7.14.0](https://github.com/juspay/neurolink/compare/v7.13.0...v7.14.0) (2025-08-14)
+
+### Features
+
+- **(external-mcp):** add external MCP server integration support ([c03dee8](https://github.com/juspay/neurolink/commit/c03dee8dd7a2e06e78bc743d7b3a5cff858395de))
+
+## [7.13.0](https://github.com/juspay/neurolink/compare/v7.12.0...v7.13.0) (2025-08-14)
+
+### Features
+
+- **(SDK):** Add context summarizer for conversation BZ-43204 ([38231c4](https://github.com/juspay/neurolink/commit/38231c475b7546c16db741010173794251a7dbaa))
+
 ## [7.12.0](https://github.com/juspay/neurolink/compare/v7.11.1...v7.12.0) (2025-08-14)
 
 ### Features

package/README.md

@@ -69,7 +69,7 @@ npx @juspay/neurolink sagemaker benchmark my-endpoint  # Performance testing
 - **🛡️ Error Recovery** - Graceful failures with provider fallback and retry logic
 - **📊 Analytics & Evaluation** - Built-in usage tracking and AI-powered quality assessment
 - **🎯 Real-time Event Monitoring** - EventEmitter integration for progress tracking and debugging
-- **🔧 MCP Integration** - Model Context Protocol with 6 built-in tools and 58+ discoverable servers
+- **🔧 External MCP Integration** - Model Context Protocol with 6 built-in tools + full external MCP server support
 - **🚀 Lighthouse Integration** - Unified tool registration API supporting both object and array formats for seamless Lighthouse tool import
 
 ---
@@ -118,6 +118,28 @@ npx @juspay/neurolink status                # Check all providers
 ```bash
 # SDK Installation for using in your typescript projects
 npm install @juspay/neurolink
+
+# 🆕 NEW: External MCP Server Integration Quick Test
+node -e "
+const { NeuroLink } = require('@juspay/neurolink');
+(async () => {
+  const neurolink = new NeuroLink();
+
+  // Add external filesystem MCP server
+  await neurolink.addExternalMCPServer('filesystem', {
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+    transport: 'stdio'
+  });
+
+  // External tools automatically available in generate()
+  const result = await neurolink.generate({
+    input: { text: 'List files in the current directory' }
+  });
+  console.log('🎉 External MCP integration working!');
+  console.log(result.content);
+})();
+"
 ```
 
 ### Basic Usage
@@ -327,40 +349,56 @@ console.log(productData.name, productData.price, productData.features);
 - ⚡ **Automatic Fallback** - Never fail when providers are down, intelligent provider switching
 - 🖥️ **CLI + SDK** - Use from command line or integrate programmatically with TypeScript support
 - 🛡️ **Production Ready** - Enterprise-grade error handling, performance optimization, extracted from production
-- ✅ **MCP Integration** - Model Context Protocol with working built-in tools and 58+ discoverable external servers
+- ✅ **External MCP Integration** - Model Context Protocol with built-in tools + full external MCP server support
 - 🔍 **Smart Model Resolution** - Fuzzy matching, aliases, and capability-based search across all providers
 - 🏠 **Local AI Support** - Run completely offline with Ollama or through LiteLLM proxy
 - 🌍 **Universal Model Access** - Direct providers + 100,000+ models via Hugging Face + 100+ models via LiteLLM
+- 🧠 **Automatic Context Summarization** - Stateful, long-running conversations with automatic history summarization.
 - 📊 **Analytics & Evaluation** - Built-in usage tracking and AI-powered quality assessment
 
-## 🛠️ MCP Integration Status ✅ **BUILT-IN TOOLS WORKING**
+## 🛠️ External MCP Integration Status ✅ **PRODUCTION READY**
 
-| Component           | Status             | Description                                              |
-| ------------------- | ------------------ | -------------------------------------------------------- |
-| Built-in Tools      | ✅ **Working**     | 6 core tools fully functional across all providers       |
-| SDK Custom Tools    | ✅ **Working**     | Register custom tools programmatically                   |
-| External Discovery  | 🔍 **Discovery**   | 58+ MCP servers discovered from AI tools ecosystem       |
-| Tool Execution      | ✅ **Working**     | Real-time AI tool calling with built-in tools            |
-| **External Tools**  | 🚧 **Development** | Manual config needs one-line fix, activation in progress |
-| **CLI Integration** | ✅ **READY**       | **Production-ready with built-in tools**                 |
-| External Activation | 🔧 **Development** | Discovery complete, activation protocol in progress      |
+| Component              | Status         | Description                                                      |
+| ---------------------- | -------------- | ---------------------------------------------------------------- |
+| Built-in Tools         | ✅ **Working** | 6 core tools fully functional across all providers               |
+| SDK Custom Tools       | ✅ **Working** | Register custom tools programmatically                           |
+| **External MCP Tools** | ✅ **Working** | **Full external MCP server support with dynamic tool discovery** |
+| Tool Execution         | ✅ **Working** | Real-time AI tool calling with all tool types                    |
+| **Streaming Support**  | ✅ **Working** | **External MCP tools work with streaming generation**            |
+| **Multi-Provider**     | ✅ **Working** | **External tools work across all AI providers**                  |
+| **CLI Integration**    | ✅ **READY**   | **Production-ready with external MCP support**                   |
 
-### ✅ Quick MCP Test (v1.7.1)
+### ✅ External MCP Integration Demo
 
 ```bash
 # Test built-in tools (works immediately)
 npx @juspay/neurolink generate "What time is it?" --debug
 
-# Disable tools for pure text generation
-npx @juspay/neurolink generate "Write a poem" --disable-tools
+# 🆕 NEW: External MCP server integration (SDK)
+import { NeuroLink } from '@juspay/neurolink';
+
+const neurolink = new NeuroLink();
+
+// Add external MCP server (e.g., Bitbucket)
+await neurolink.addExternalMCPServer('bitbucket', {
+  command: 'npx',
+  args: ['-y', '@nexus2520/bitbucket-mcp-server'],
+  transport: 'stdio',
+  env: {
+    BITBUCKET_USERNAME: process.env.BITBUCKET_USERNAME,
+    BITBUCKET_TOKEN: process.env.BITBUCKET_TOKEN,
+    BITBUCKET_BASE_URL: 'https://bitbucket.example.com'
+  }
+});
+
+// Use external MCP tools in generation
+const result = await neurolink.generate({
+  input: { text: 'Get pull request #123 details from the main repository' },
+  disableTools: false // External MCP tools automatically available
+});
 
 # Discover available MCP servers
 npx @juspay/neurolink mcp discover --format table
-
-# Install popular MCP servers (NEW: Bitbucket support added!)
-npx @juspay/neurolink mcp install filesystem
-npx @juspay/neurolink mcp install github
-npx @juspay/neurolink mcp install bitbucket  # 🆕 NEW
 ```
 
 ### 🔧 SDK Custom Tool Registration (NEW!)
@@ -662,16 +700,43 @@ npx @juspay/neurolink generate "Hello!" --provider openai-compatible
 - **Extensibility**: Connect external tools and services via MCP protocol
 - **🆕 Dynamic Server Management**: Programmatically add MCP servers at runtime
 
-### 🔧 Programmatic MCP Server Management [Coming Soon]
+### 🔧 External MCP Server Management ✅ **AVAILABLE NOW**
 
-**Note**: External MCP server activation is in development. Currently available:
+**External MCP integration is now production-ready:**
 
 - ✅ 6 built-in tools working across all providers
 - ✅ SDK custom tool registration
-- 🔍 MCP server discovery (58+ servers found)
-- 🚧 External server activation (one-line fix pending)
+- ✅ **External MCP server management** (add, remove, list, test servers)
+- ✅ **Dynamic tool discovery** (automatic tool registration from external servers)
+- ✅ **Multi-provider support** (external tools work with all AI providers)
+- ✅ **Streaming integration** (external tools work with real-time streaming)
+- ✅ **Enhanced tool tracking** (proper parameter extraction and execution logging)
 
-Manual MCP configuration (`.mcp-config.json`) support coming soon.
+```typescript
+// Complete external MCP server API
+const neurolink = new NeuroLink();
+
+// Server management
+await neurolink.addExternalMCPServer(serverId, config);
+await neurolink.removeExternalMCPServer(serverId);
+const servers = neurolink.listExternalMCPServers();
+const server = neurolink.getExternalMCPServer(serverId);
+
+// Tool management
+const tools = neurolink.getExternalMCPTools();
+const serverTools = neurolink.getExternalMCPServerTools(serverId);
+
+// Direct tool execution
+const result = await neurolink.executeExternalMCPTool(
+  serverId,
+  toolName,
+  params,
+);
+
+// Statistics and monitoring
+const stats = neurolink.getExternalMCPStatistics();
+await neurolink.shutdownExternalMCPServers();
+```
 
 ## 🤝 Contributing
 

package/dist/config/conversationMemoryConfig.js

@@ -34,6 +34,7 @@ export function getConversationMemoryDefaults() {
     return {
         enabled: process.env.NEUROLINK_MEMORY_ENABLED === "true",
         maxSessions: Number(process.env.NEUROLINK_MEMORY_MAX_SESSIONS) || DEFAULT_MAX_SESSIONS,
-        maxTurnsPerSession: Number(process.env.NEUROLINK_MEMORY_MAX_TURNS_PER_SESSION) || DEFAULT_MAX_TURNS_PER_SESSION,
+        maxTurnsPerSession: Number(process.env.NEUROLINK_MEMORY_MAX_TURNS_PER_SESSION) ||
+            DEFAULT_MAX_TURNS_PER_SESSION,
     };
 }

package/dist/context/ContextManager.d.ts

@@ -0,0 +1,28 @@
+import type { TextGenerationOptions, TextGenerationResult } from "../core/types.js";
+import type { ContextManagerConfig } from "./types.js";
+type InternalGenerator = (options: TextGenerationOptions) => Promise<TextGenerationResult>;
+/**
+ * Manages conversation context, automatically summarizing it when it
+ * exceeds a specified word count limit.
+ */
+export declare class ContextManager {
+    private static readonly SUMMARIZATION_FAILED_WARNING;
+    private static readonly SUMMARIZATION_EMPTY_WARNING;
+    private history;
+    private wordCount;
+    private readonly internalGenerator;
+    private readonly config;
+    constructor(generatorFunction: InternalGenerator, config: ContextManagerConfig, initialContext?: string);
+    addTurn(role: "user" | "assistant", message: string): Promise<void>;
+    /**
+     * Formats the history including the latest user turn for the prompt, without modifying the permanent history.
+     */
+    getContextForPrompt(role: "user", message: string): string;
+    getCurrentContext(): string;
+    private _summarize;
+    /**
+     * Truncates the history to a specific word count, preserving the most recent messages.
+     */
+    private _truncateHistory;
+}
+export {};

package/dist/context/ContextManager.js

@@ -0,0 +1,113 @@
+import { logger } from "../utils/logger.js";
+import { formatHistoryToString } from "./utils.js";
+/**
+ * Manages conversation context, automatically summarizing it when it
+ * exceeds a specified word count limit.
+ */
+export class ContextManager {
+    static SUMMARIZATION_FAILED_WARNING = "[System Warning: Context summarization failed. Conversation history has been truncated.]";
+    static SUMMARIZATION_EMPTY_WARNING = "[System Warning: Context summarization failed to return valid content. Conversation history has been truncated.]";
+    history;
+    wordCount;
+    internalGenerator;
+    config;
+    constructor(generatorFunction, config, initialContext = "This is the start of the conversation.") {
+        this.internalGenerator = generatorFunction;
+        this.config = config;
+        const initialMessage = {
+            role: "system",
+            content: initialContext,
+        };
+        initialMessage.wordCount = this.config.estimateWordCount([initialMessage]);
+        this.history = [initialMessage];
+        this.wordCount = initialMessage.wordCount;
+    }
+    async addTurn(role, message) {
+        const newMessage = { role, content: message };
+        newMessage.wordCount = this.config.estimateWordCount([newMessage]);
+        this.history.push(newMessage);
+        this.wordCount += newMessage.wordCount;
+        logger.info(`[ContextManager] Current word count: ${this.wordCount} / ${this.config.highWaterMarkWords}`);
+        if (this.wordCount > this.config.highWaterMarkWords) {
+            await this._summarize();
+        }
+    }
+    /**
+     * Formats the history including the latest user turn for the prompt, without modifying the permanent history.
+     */
+    getContextForPrompt(role, message) {
+        const tempHistory = [...this.history, { role, content: message }];
+        return formatHistoryToString(tempHistory);
+    }
+    getCurrentContext() {
+        // Format the history into a single string for the provider prompt
+        return formatHistoryToString(this.history);
+    }
+    async _summarize() {
+        try {
+            const prompt = this.config.getSummarizationPrompt(this.history, this.config.lowWaterMarkWords);
+            // Construct options for the internal method, bypassing the main 'generate' entry point
+            const textOptions = {
+                prompt,
+                provider: this.config.summarizationProvider,
+                model: this.config.summarizationModel,
+                // Ensure summarization does not trigger more context management or tools
+                disableTools: true,
+            };
+            // Call the internal generation function directly to avoid recursion
+            const result = await this.internalGenerator(textOptions);
+            if (typeof result.content === "string" && result.content.length > 0) {
+                // Replace the history with a single system message containing the summary
+                const newHistory = [
+                    { role: "system", content: result.content },
+                ];
+                this.history = newHistory;
+                this.wordCount = this.config.estimateWordCount(this.history);
+                logger.info(`[ContextManager] Summarization complete. New history length: ${this.wordCount} words.`);
+            }
+            else {
+                logger.warn("[ContextManager] Summarization returned empty or non-string content; truncating history as a fallback.");
+                this._truncateHistory(this.config.lowWaterMarkWords);
+                this.history.unshift({
+                    role: "system",
+                    content: ContextManager.SUMMARIZATION_EMPTY_WARNING,
+                });
+                this.wordCount = this.config.estimateWordCount(this.history);
+            }
+            logger.debug(`[ContextManager] New history: ${JSON.stringify(this.history)}`);
+        }
+        catch (error) {
+            logger.error("Context summarization failed:", { error });
+            // Fallback strategy: truncate the history to the target word count.
+            this._truncateHistory(this.config.lowWaterMarkWords);
+            this.history.unshift({
+                role: "system",
+                content: ContextManager.SUMMARIZATION_FAILED_WARNING,
+            });
+            this.wordCount = this.config.estimateWordCount(this.history);
+        }
+    }
+    /**
+     * Truncates the history to a specific word count, preserving the most recent messages.
+     */
+    _truncateHistory(wordLimit) {
+        if (this.wordCount <= wordLimit) {
+            return;
+        }
+        let runningCount = 0;
+        let sliceIndex = this.history.length;
+        for (let i = this.history.length - 1; i >= 0; i--) {
+            let wordCount = this.history[i].wordCount;
+            if (wordCount === undefined) {
+                logger.warn(`[ContextManager] Word count cache missing for message at index ${i}. Recalculating.`);
+                wordCount = this.config.estimateWordCount([this.history[i]]);
+            }
+            runningCount += wordCount;
+            if (runningCount > wordLimit) {
+                sliceIndex = i + 1;
+                break;
+            }
+        }
+        this.history = this.history.slice(sliceIndex);
+    }
+}

package/dist/context/config.d.ts

@@ -0,0 +1,5 @@
+import type { ContextManagerConfig } from "./types.js";
+/**
+ * Default configuration for the ContextManager.
+ */
+export declare const defaultContextConfig: ContextManagerConfig;

package/dist/context/config.js

@@ -0,0 +1,42 @@
+import { formatHistoryToString } from "./utils.js";
+/**
+ * Estimates the word count of a conversation history.
+ */
+function estimateWordCount(history) {
+    if (!history || history.length === 0) {
+        return 0;
+    }
+    return history.reduce((acc, msg) => acc +
+        (msg.content
+            .trim()
+            .split(/\s+/)
+            .filter((word) => word.length > 0).length || 0), 0);
+}
+/**
+ * Generates the default prompt for summarization.
+ */
+function getDefaultSummarizationPrompt(history, wordLimit) {
+    const formattedHistory = formatHistoryToString(history);
+    return `
+You are a context summarization AI. Your task is to condense the following conversation history for another AI assistant.
+The summary must be a concise, third-person narrative that retains all critical information. Pay special attention to retaining key entities, technical details, decisions made, and any specific dates or times mentioned.
+Ensure the summary flows logically and is ready to be used as context for the next turn in the conversation.
+Please keep the summary under ${wordLimit} words.
+
+Conversation History to Summarize:
+---
+${formattedHistory}
+---
+`.trim();
+}
+/**
+ * Default configuration for the ContextManager.
+ */
+export const defaultContextConfig = {
+    highWaterMarkWords: 3000,
+    lowWaterMarkWords: 800,
+    summarizationModel: "gemini-2.5-flash",
+    summarizationProvider: "googlevertex",
+    getSummarizationPrompt: getDefaultSummarizationPrompt,
+    estimateWordCount: estimateWordCount,
+};

package/dist/context/types.d.ts

@@ -0,0 +1,20 @@
+export interface ChatMessage {
+    /** Role of the message sender */
+    role: "user" | "assistant" | "system";
+    /** Content of the message */
+    content: string;
+    /** Cached word count for performance */
+    wordCount?: number;
+}
+/**
+ * Defines the configuration for the ContextManager.
+ * This allows for easy customization of the summarization behavior.
+ */
+export interface ContextManagerConfig {
+    highWaterMarkWords: number;
+    lowWaterMarkWords: number;
+    summarizationModel: string;
+    summarizationProvider: string;
+    getSummarizationPrompt: (history: ChatMessage[], wordLimit: number) => string;
+    estimateWordCount: (history: ChatMessage[]) => number;
+}

package/dist/context/types.js

@@ -0,0 +1 @@
+export {};

package/dist/context/utils.d.ts

@@ -0,0 +1,7 @@
+import type { ChatMessage } from "./types.js";
+/**
+ * Formats a chat history array into a single string for use in a prompt.
+ * @param history The array of ChatMessage objects.
+ * @returns A formatted string representing the conversation.
+ */
+export declare function formatHistoryToString(history: ChatMessage[]): string;

package/dist/context/utils.js

@@ -0,0 +1,8 @@
+/**
+ * Formats a chat history array into a single string for use in a prompt.
+ * @param history The array of ChatMessage objects.
+ * @returns A formatted string representing the conversation.
+ */
+export function formatHistoryToString(history) {
+    return history.map((msg) => `${msg.role}: ${msg.content}`).join("\n\n");
+}

package/dist/core/baseProvider.d.ts

@@ -6,7 +6,7 @@ import type { StreamOptions, StreamResult } from "../types/streamTypes.js";
 import type { JsonValue, UnknownRecord } from "../types/common.js";
 import type { ToolResult } from "../types/tools.js";
 /**
- * Interface for SDK with in-memory MCP servers
+ * Interface for SDK with in-memory MCP servers and external MCP support
  */
 export interface NeuroLinkSDK {
     getInMemoryServers?: () => Map<string, {
@@ -18,6 +18,16 @@ export interface NeuroLinkSDK {
         category?: string;
         metadata?: UnknownRecord;
     }>;
+    externalServerManager?: {
+        getAllTools: () => Array<{
+            name: string;
+            description: string;
+            serverId: string;
+            isAvailable: boolean;
+            inputSchema?: Record<string, unknown>;
+        }>;
+        executeTool: (serverId: string, toolName: string, params: any) => Promise<any>;
+    };
 }
 /**
  * Interface for tool information in MCP servers
@@ -86,6 +96,11 @@ export declare abstract class BaseProvider implements AIProvider {
      * MCP tools are added when available (without blocking)
      */
     protected getAllTools(): Promise<Record<string, Tool>>;
+    /**
+     * Convert MCP JSON Schema to Zod schema for AI SDK tools
+     * Handles common MCP schema patterns safely
+     */
+    private convertMCPSchemaToZod;
     /**
      * Set session context for MCP tools
      */