@tryhamster/gerbil 1.0.0-rc.0

package/docs/mcp-client.md

@@ -0,0 +1,224 @@
+# MCP Client
+
+Connect Gerbil to external MCP (Model Context Protocol) servers and use their tools in chat or skills.
+
+## Quick Start
+
+```typescript
+import { connectMCP, callMCPTool, getMCPHub } from "@tryhamster/gerbil/mcp-client";
+
+// Connect to an MCP server
+await connectMCP("filesystem", {
+  command: "uvx",
+  args: ["mcp-server-filesystem", "/home/user"],
+});
+
+// Call a tool
+const files = await callMCPTool("filesystem:list_directory", { path: "/" });
+```
+
+## MCPClient
+
+Direct client for a single MCP server:
+
+```typescript
+import { MCPClient } from "@tryhamster/gerbil/mcp-client";
+
+const client = new MCPClient("browser", {
+  command: "npx",
+  args: ["-y", "@anthropic/mcp-server-puppeteer"],
+});
+
+// Connect
+await client.connect();
+
+// List available tools
+const tools = client.getTools();
+console.log(tools);
+// [{ name: "navigate", description: "Navigate to URL", parameters: {...} }, ...]
+
+// Call a tool
+const result = await client.callTool("navigate", { url: "https://example.com" });
+
+// Check connection status
+console.log(client.isConnected()); // true
+
+// Disconnect when done
+await client.disconnect();
+```
+
+## MCPHub
+
+Manage multiple MCP servers:
+
+```typescript
+import { MCPHub } from "@tryhamster/gerbil/mcp-client";
+
+const hub = new MCPHub();
+
+// Add multiple servers
+await hub.addServer("filesystem", {
+  command: "uvx",
+  args: ["mcp-server-filesystem", "/tmp"],
+});
+
+await hub.addServer("browser", {
+  command: "npx",
+  args: ["-y", "@anthropic/mcp-server-puppeteer"],
+});
+
+// List all connected servers
+console.log(hub.listServers()); // ["filesystem", "browser"]
+
+// Get all tools from all servers
+const allTools = hub.getAllTools();
+// Tools are prefixed: "filesystem:list_directory", "browser:navigate"
+
+// Call tool using server:tool format
+await hub.callTool("filesystem:list_directory", { path: "/" });
+
+// Remove a server
+await hub.removeServer("browser");
+```
+
+## Singleton Hub
+
+Use the global hub for app-wide MCP connections:
+
+```typescript
+import { getMCPHub, connectMCP, disconnectMCP, callMCPTool } from "@tryhamster/gerbil/mcp-client";
+
+// These all use the same global hub
+await connectMCP("myserver", { command: "...", args: [...] });
+const result = await callMCPTool("myserver:sometool", { arg: "value" });
+await disconnectMCP("myserver");
+
+// Or access the hub directly
+const hub = getMCPHub();
+```
+
+## Using MCP Tools in Chat
+
+When connected, MCP tools are automatically registered in Gerbil's tool registry. In **Agent mode**, the AI can use them:
+
+```
+User: Read the file /tmp/notes.txt
+
+Gerbil: {"tool": "mcp_call", "params": {"tool_name": "filesystem:read_file", "params": {"path": "/tmp/notes.txt"}}}
+
+[Tool Result: Contents of notes.txt...]
+
+Gerbil: The file contains your meeting notes from yesterday...
+```
+
+### Built-in MCP Tools
+
+When MCP servers are connected, these tools become available to the AI:
+
+| Tool | Description |
+|------|-------------|
+| `mcp_call` | Call any tool from a connected MCP server |
+| `mcp_list` | List all available tools from connected servers |
+
+## Using MCP Tools in Skills
+
+Create skills that leverage MCP tools:
+
+```typescript
+import { defineSkill } from "@tryhamster/gerbil/skills";
+import { getMCPHub } from "@tryhamster/gerbil/mcp-client";
+import { z } from "zod";
+
+export const webScraper = defineSkill({
+  name: "web-scraper",
+  description: "Scrape and summarize a webpage",
+  input: z.object({
+    url: z.string().url(),
+  }),
+  async run(input, gerbil) {
+    const hub = getMCPHub();
+    
+    // Navigate to page
+    await hub.callTool("browser:navigate", { url: input.url });
+    
+    // Get page content
+    const content = await hub.callTool("browser:get_content", {});
+    
+    // Summarize with Gerbil
+    const summary = await gerbil.generate(
+      `Summarize this webpage:\n\n${content}`,
+      { maxTokens: 300 }
+    );
+    
+    return summary.text;
+  },
+});
+```
+
+## Popular MCP Servers
+
+| Server | Install | Description |
+|--------|---------|-------------|
+| Filesystem | `uvx mcp-server-filesystem /path` | Read/write files |
+| Puppeteer | `npx -y @anthropic/mcp-server-puppeteer` | Browser automation |
+| SQLite | `uvx mcp-server-sqlite --db-path db.sqlite` | Database access |
+| GitHub | `npx -y @anthropic/mcp-server-github` | GitHub API |
+| Slack | `npx -y @anthropic/mcp-server-slack` | Slack integration |
+
+See [modelcontextprotocol.io](https://modelcontextprotocol.io) for more servers.
+
+## Server Configuration
+
+```typescript
+interface MCPServerConfig {
+  /** Command to run (e.g., "npx", "uvx", "node") */
+  command: string;
+  
+  /** Arguments for the command */
+  args?: string[];
+  
+  /** Environment variables */
+  env?: Record<string, string>;
+  
+  /** Working directory */
+  cwd?: string;
+}
+```
+
+## Error Handling
+
+```typescript
+import { connectMCP, callMCPTool } from "@tryhamster/gerbil/mcp-client";
+
+try {
+  await connectMCP("myserver", { command: "bad-command" });
+} catch (e) {
+  console.error("Failed to connect:", e.message);
+}
+
+try {
+  const result = await callMCPTool("myserver:unknown_tool", {});
+} catch (e) {
+  console.error("Tool call failed:", e.message);
+}
+```
+
+## REPL Integration
+
+In the Gerbil REPL, you can use MCP tools in **Chat** with Agent mode enabled.
+
+```
+[gerbil / Chat]
+Mode: [@] Agent
+
+You: Connect to the filesystem server at /tmp and list the files
+
+Gerbil: I'll use the mcp_list tool to see available tools, then list files.
+{"tool": "mcp_list", "params": {}}
+
+[Available MCP tools: filesystem:list_directory, filesystem:read_file...]
+
+{"tool": "mcp_call", "params": {"tool_name": "filesystem:list_directory", "params": {"path": "/tmp"}}}
+
+[files listed...]
+```

package/docs/mcp.md

@@ -0,0 +1,109 @@
+# MCP Server
+
+Gerbil can run as a Model Context Protocol (MCP) server for Claude Desktop, Cursor, and other MCP clients.
+
+## Start Server
+
+```bash
+gerbil serve --mcp
+```
+
+## Claude Desktop Config
+
+Add to your Claude Desktop config:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux**: `~/.config/claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "gerbil": {
+      "command": "npx",
+      "args": ["-y", "@tryhamster/gerbil", "serve", "--mcp"]
+    }
+  }
+}
+```
+
+## Cursor Config
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "gerbil": {
+      "command": "npx",
+      "args": ["-y", "@tryhamster/gerbil", "serve", "--mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+Built-in skills are exposed as MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `gerbil_generate` | Generate text with local LLM |
+| `gerbil_summarize` | Summarize content |
+| `gerbil_explain` | Explain code or concepts |
+| `gerbil_review` | Code review |
+| `gerbil_commit` | Generate commit message |
+| `gerbil_translate` | Translate text |
+| `gerbil_embed` | Generate embeddings |
+
+## Custom Skills as Tools
+
+Custom skills loaded via `loadSkills()` are automatically exposed:
+
+```typescript
+// In your MCP server setup
+import { loadSkills } from "@tryhamster/gerbil/skills";
+
+await loadSkills("./skills");
+// Now your custom skills are available as MCP tools
+```
+
+## Programmatic Usage
+
+```typescript
+import { createMCPServer, startMCPServer } from "@tryhamster/gerbil/mcp";
+
+// Create server instance
+const server = await createMCPServer({ model: "qwen3-0.6b" });
+
+// List tools
+const tools = server.listTools();
+console.log(tools.map(t => t.name));
+
+// Call a tool
+const result = await server.callTool("gerbil_summarize", {
+  content: "Long text here...",
+  length: "short",
+});
+
+// Or start stdio server for MCP clients
+await startMCPServer({ model: "qwen3-0.6b" });
+```
+
+## Options
+
+```typescript
+interface MCPServerOptions {
+  /** Model to load (default: "qwen3-0.6b") */
+  model?: string;
+  
+  /** Device to use */
+  device?: "auto" | "gpu" | "cpu";
+  
+  /** Quantization */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+  
+  /** Specific tools to expose (default: all) */
+  tools?: string[];
+}
+```

package/docs/memory.md

@@ -0,0 +1,229 @@
+# Memory Management
+
+Gerbil automatically manages memory to prevent leaks while maintaining performance. For WebGPU inference (Node.js), memory is bounded and monitored.
+
+## Automatic Management
+
+### Context-Aware Auto-Reset
+
+The KV cache automatically resets when it exceeds the model's context length (2048 tokens for Qwen3). This prevents unbounded memory growth:
+
+```typescript
+// Memory automatically resets after ~2048 tokens
+// No action needed - happens transparently
+const gerbil = new Gerbil();
+await gerbil.loadModel("qwen3-0.6b");
+
+// Long conversations work fine - auto-reset preserves context window
+for (let i = 0; i < 100; i++) {
+  await gerbil.generate("Tell me something interesting");
+}
+```
+
+### Memory Bounds
+
+- **Per-page maximum**: ~4GB (context length × token size)
+- **Concurrent page limit**: 5 pages maximum
+- **Total worst-case**: ~20GB (5 pages × 4GB each)
+- **Typical usage**: < 2GB (most conversations are < 500 tokens)
+
+## Manual Control
+
+### Check Memory Usage
+
+```typescript
+const mem = await gerbil.getMemoryUsage();
+if (mem) {
+  console.log(`Using ${mem.usedGB.toFixed(1)}GB / ${mem.totalGB.toFixed(1)}GB`);
+}
+```
+
+### Clear Cache Manually
+
+```typescript
+// Clear KV cache to free memory (resets conversation context)
+await gerbil.clearCache();
+```
+
+### Auto-Cleanup with Threshold
+
+```typescript
+// Check and cleanup if memory exceeds threshold
+const didCleanup = await gerbil.checkMemoryAndCleanup(8); // 8GB threshold
+if (didCleanup) {
+  console.log("Memory cleaned up");
+}
+```
+
+## REPL Commands
+
+### `/memory` - Show Memory Usage
+
+```
+> /memory
+💾 Memory: 2.3GB / 8.5GB (27.1%)
+```
+
+### `/reset-cache` - Clear Cache
+
+```
+> /reset-cache
+🧹 Cache cleared (was 2.3GB). Conversation context reset.
+```
+
+## Long-Running Sessions
+
+For background services or long-running processes:
+
+```typescript
+import { Gerbil } from '@tryhamster/gerbil';
+
+const gerbil = new Gerbil();
+await gerbil.loadModel("qwen3-0.6b");
+
+// Periodic memory monitoring
+setInterval(async () => {
+  const mem = await gerbil.getMemoryUsage();
+  
+  if (mem && mem.usedGB > 10) {
+    console.warn(`High memory: ${mem.usedGB.toFixed(1)}GB`);
+    await gerbil.clearCache(); // Clear if threshold exceeded
+  }
+}, 60000); // Check every minute
+```
+
+## Development Best Practices
+
+### Multiple Instances
+
+When creating multiple Gerbil instances during development:
+
+```typescript
+// ✅ Good: Dispose when done
+const gerbil = new Gerbil();
+await gerbil.loadModel("qwen3-0.6b");
+// ... use gerbil ...
+await gerbil.dispose(); // Frees resources
+
+// ❌ Bad: Creating many instances without cleanup
+for (let i = 0; i < 10; i++) {
+  const g = new Gerbil();
+  await g.loadModel("qwen3-0.6b");
+  // Forgot to dispose - pages accumulate!
+}
+```
+
+### Page Limit
+
+Gerbil limits concurrent Chrome pages to 5. If you hit this limit:
+
+```typescript
+// Error: Maximum concurrent pages (5) reached. 
+// Call dispose() on old Gerbil instances to free resources.
+
+// Solution: Dispose unused instances
+await oldGerbil.dispose();
+```
+
+## Architecture
+
+### WebGPU (Node.js)
+- Uses headless Chrome for GPU acceleration
+- Shared browser process, separate pages per instance
+- KV cache stored in-memory per page
+- Auto-reset prevents unbounded growth
+
+### WebGPU (Browser)
+- Native WebGPU API
+- KV cache in browser memory
+- Auto-reset applies same as Node.js
+
+### CPU/WASM
+- Memory monitoring not available
+- Smaller models, less memory pressure
+- Manual cleanup still works
+
+## Console Events
+
+When using WebGPU via Chrome, the backend emits events:
+
+```javascript
+// Auto-reset event (cache exceeded context)
+{ 
+  type: "cache_reset", 
+  reason: "context_exceeded",
+  tokensInCache: 2100,
+  contextLength: 2048 
+}
+
+// Manual reset event
+{ type: "cache_reset", reason: "manual" }
+
+// Generation complete (includes cache info)
+{ 
+  type: "complete",
+  text: "...",
+  numTokens: 50,
+  tokensInCache: 520
+}
+```
+
+## Performance Impact
+
+- ✅ **Zero impact on short conversations** (< 2048 tokens)
+- ✅ **Graceful degradation on long conversations** (auto-reset maintains context window)
+- ✅ **Minimal overhead** (memory check is async, doesn't block generation)
+
+## API Reference
+
+### `getMemoryUsage()`
+
+Returns memory statistics in GB (WebGPU only):
+
+```typescript
+const mem = await gerbil.getMemoryUsage();
+// Returns: { usedGB: number; totalGB: number; usedPercent: number } | null
+```
+
+### `clearCache()`
+
+Manually clear KV cache:
+
+```typescript
+await gerbil.clearCache();
+// Resets conversation context, frees memory
+```
+
+### `checkMemoryAndCleanup(thresholdGB?)`
+
+Check memory and auto-cleanup if threshold exceeded:
+
+```typescript
+const didCleanup = await gerbil.checkMemoryAndCleanup(8); // 8GB threshold
+// Returns: boolean (true if cleanup was performed)
+```
+
+### `dispose()`
+
+Clean up all resources:
+
+```typescript
+await gerbil.dispose();
+// Closes Chrome page, releases memory
+```
+
+## Testing
+
+Run the memory management test suite:
+
+```bash
+node test-memory-management.js
+```
+
+This verifies:
+- Memory monitoring works
+- Cache clearing reduces memory
+- Auto-reset triggers correctly
+- Threshold-based cleanup works
+- Proper cleanup on dispose
+