groq-rag 0.1.4 → 0.2.0

package/README.md

@@ -7,6 +7,9 @@
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
 [![Demo](https://img.shields.io/badge/Demo-Live-brightgreen.svg)](https://groq-rag.onrender.com)
 [![Groq SDK](https://img.shields.io/badge/Built%20on-Groq%20SDK-orange.svg)](https://github.com/groq/groq-typescript)
+[![Context7](https://img.shields.io/badge/Context7-AI%20Docs-purple.svg)](https://context7.com/mithun50/groq-rag)
+[![Benchmark](https://img.shields.io/badge/Benchmark-1.7M%20ops%2Fs-brightgreen.svg)](#benchmarks)
+[![Groq API](https://img.shields.io/badge/Groq%20API-190ms-blue.svg)](#benchmarks)
 
 Extended [Groq TypeScript SDK](https://github.com/groq/groq-typescript) with RAG (Retrieval-Augmented Generation), web browsing, and autonomous agent capabilities. Build intelligent AI applications that can search the web, fetch URLs, query knowledge bases, and reason through complex tasks.
 
@@ -49,6 +52,7 @@ groq-rag is built on top of the official [Groq TypeScript SDK](https://github.co
   - [Chat Module](#chat-module)
   - [Agent System](#agent-system)
   - [Tool System](#tool-system)
+  - [MCP Integration](#mcp-integration)
 - [Configuration](#configuration)
   - [Vector Stores](#vector-stores)
   - [Embedding Providers](#embedding-providers)
@@ -71,6 +75,7 @@ groq-rag is built on top of the official [Groq TypeScript SDK](https://github.co
 | **Web Search** | DuckDuckGo (free), Brave Search, and Serper (Google) integration |
 | **Agent System** | ReAct-style autonomous agents with tool use, memory, and streaming |
 | **Tool Framework** | Extensible tool system with built-in and custom tools |
+| **MCP Integration** | Connect to Model Context Protocol servers for external tool access |
 | **Content Limiting** | Optional token/character limits to control API costs |
 | **TypeScript** | Full type safety with comprehensive IntelliSense support |
 | **Zero Config** | Works out of the box with sensible defaults |
@@ -633,6 +638,111 @@ executor.register(anotherTool);
 const result = await executor.execute('my_tool', { input: 'hello' });
 ```
 
+---
+
+### MCP Integration
+
+Connect to [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers to use external tools from the MCP ecosystem.
+
+#### Adding MCP Servers
+
+```typescript
+const client = new GroqRAG();
+
+// Add an MCP server (stdio transport)
+await client.mcp.addServer({
+  name: 'filesystem',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-filesystem', './data'],
+});
+
+// Add another MCP server (e.g., GitHub)
+await client.mcp.addServer({
+  name: 'github',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-github'],
+  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
+});
+```
+
+#### Using MCP Tools with Agents
+
+```typescript
+// Create agent with built-in + MCP tools
+const agent = await client.createAgentWithBuiltins(
+  { model: 'llama-3.3-70b-versatile', verbose: true },
+  { includeMCP: true }
+);
+
+// Agent can now use tools from all connected MCP servers
+const result = await agent.run('List files in the data directory');
+
+// Cleanup when done
+await client.mcp.disconnectAll();
+```
+
+#### MCP Server Configuration
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | string | Unique name for the server |
+| `transport` | 'stdio' \| 'http' | Transport protocol |
+| `command` | string | Command to run (stdio) |
+| `args` | string[] | Command arguments (stdio) |
+| `env` | object | Environment variables (stdio) |
+| `url` | string | Server URL (http) |
+| `timeout` | number | Connection timeout (ms) |
+
+#### Standalone MCP Client
+
+```typescript
+import { createMCPClient } from 'groq-rag';
+
+// Create and connect to an MCP server
+const mcpClient = createMCPClient({
+  name: 'filesystem',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
+});
+
+await mcpClient.connect();
+
+// Get tools as ToolDefinitions for use with any agent
+const tools = mcpClient.getToolsAsDefinitions();
+console.log('Available tools:', tools.map(t => t.name));
+
+// Call a tool directly
+const result = await mcpClient.callTool('read_file', { path: './README.md' });
+
+await mcpClient.disconnect();
+```
+
+#### MCP Module Methods
+
+| Method | Description |
+|--------|-------------|
+| `client.mcp.addServer(config)` | Connect to an MCP server |
+| `client.mcp.removeServer(name)` | Disconnect from a server |
+| `client.mcp.getServer(name)` | Get a specific MCP client |
+| `client.mcp.getServers()` | List all connected clients |
+| `client.mcp.getAllTools()` | Get all tools from all servers |
+| `client.mcp.disconnectAll()` | Disconnect from all servers |
+
+#### Popular MCP Servers
+
+| Server | Package | Description |
+|--------|---------|-------------|
+| Filesystem | `@modelcontextprotocol/server-filesystem` | Read/write local files |
+| GitHub | `@modelcontextprotocol/server-github` | GitHub API access |
+| Brave Search | `@modelcontextprotocol/server-brave-search` | Web search |
+| SQLite | `@modelcontextprotocol/server-sqlite` | SQLite database |
+| Memory | `@modelcontextprotocol/server-memory` | Persistent memory |
+
+> See [MCP Servers](https://github.com/modelcontextprotocol/servers) for more available servers.
+
 ## Configuration
 
 ### Vector Stores
@@ -888,6 +998,7 @@ Complete examples in the [examples/](./examples) directory:
 | `url-fetch.ts` | URL fetching and summarization |
 | `agent.ts` | Agent with tools |
 | `streaming-agent.ts` | Streaming agent execution |
+| `mcp-tools.ts` | **MCP server integration** |
 | `full-chatbot.ts` | **Full-featured interactive CLI chatbot** |
 
 ### Running the Full Chatbot
@@ -937,6 +1048,10 @@ groq-rag/
 │   ├── tools/
 │   │   ├── executor.ts   # Tool execution engine
 │   │   └── builtins.ts   # Built-in tools
+│   ├── mcp/
+│   │   ├── client.ts     # MCP client implementation
+│   │   ├── adapter.ts    # MCP to ToolDefinition conversion
+│   │   └── transports/   # Stdio and HTTP transports
 │   ├── agents/
 │   │   └── agent.ts      # ReAct agent implementation
 │   └── utils/
@@ -988,8 +1103,50 @@ npm run lint
 npm run typecheck
 ```
 
+## Benchmarks
+
+Performance benchmarks for groq-rag SDK operations.
+
+### Local Processing (CPU-bound)
+
+| Operation | Ops/sec | Avg Time |
+|-----------|---------|----------|
+| Content Truncation | **1,743,317** | 0.0006ms |
+| Context Formatting | **330,914** | 0.003ms |
+| Text Chunking | **84,861** | 0.01ms |
+
+### Network Operations (I/O-bound)
+
+| Operation | Ops/sec | Avg Time |
+|-----------|---------|----------|
+| Groq Chat Completion | 5.27 | 190ms |
+| URL Fetch | 5.05 | 198ms |
+| Content Limiting (Total) | 4.87 | 205ms |
+| Content Limiting (Snippet) | 3.09 | 323ms |
+| Chat with URL | 2.61 | 383ms |
+| Web Search (DuckDuckGo) | 1.83 | 546ms |
+| Chat with Web Search | 0.98 | 1024ms |
+
+> **Note**: Network operations are limited by external API latency (Groq, DuckDuckGo), not SDK performance. Local processing shows the SDK's actual code efficiency.
+
+Run benchmarks:
+```bash
+npm run benchmark
+```
+
 ## Changelog
 
+### v0.1.6
+
+- **New Feature: MCP Integration** - Connect to Model Context Protocol servers
+  - `client.mcp.addServer()` - Connect to MCP servers (stdio/http)
+  - `client.mcp.getAllTools()` - Get tools from connected servers
+  - `createAgentWithBuiltins({ includeMCP: true })` - Include MCP tools in agents
+  - Support for `@modelcontextprotocol/server-*` packages
+  - Standalone `createMCPClient()` for direct MCP usage
+- **ToolExecutor Enhancement** - Added `registerMCPTools()` and `unregisterMCPTools()`
+- **Tests** - Added MCP client and adapter tests
+
 ### v0.1.4
 
 - **New Feature: Content Limiting** - Control token usage with optional limits