@tryhamster/gerbil 1.1.2 → 1.2.0

package/docs/mcp-client.md

@@ -1,224 +0,0 @@
-# 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

@@ -1,109 +0,0 @@
-# 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-rag.md

@@ -1,91 +0,0 @@
-# Memory / RAG (on-device agent memory)
-
-> Note: this is the **RAG / persistent-memory** module (`@tryhamster/gerbil/memory`).
-> For GPU/KV-cache memory management see [memory.md](memory.md).
-
-Gerbil's memory module is an on-device, persistent memory layer that turns
-Gerbil into an agent harness: store text + embeddings, retrieve semantically,
-and rebuild a token-budgeted context block every turn.
-
-It is engine-agnostic — bring any embedder and any storage backend — but wires
-straight into Gerbil's native embeddings by default.
-
-## Quick start
-
-```ts
-import { Gerbil } from "@tryhamster/gerbil";
-import { createMemory, createGerbilEmbedder } from "@tryhamster/gerbil/memory";
-
-const g = new Gerbil();
-await g.loadModel("embeddinggemma-300m");
-
-const mem = createMemory({ embed: createGerbilEmbedder(g) });
-
-await mem.add("Paris is the capital of France", { metadata: { topic: "geo" } });
-const hits = await mem.search("French capital", { k: 3 });
-const { context } = await mem.recall("French capital", { tokenBudget: 512 });
-```
-
-## Public API
-
-`createMemory({ embed, store?, redact?, chunk? }) → Memory`
-
-| Method | Description |
-| --- | --- |
-| `add(text, { metadata?, id?, chunk? })` | Redact → (optional) chunk → embed → normalize → store. Returns created ids. |
-| `search(query, { k?, filter?, minScore? })` | Cosine top-k. Returns `{ record, score }[]`. |
-| `recall(query, { tokenBudget?, k?, filter?, minScore?, separator? })` | Retrieve + greedily pack into a token-budgeted context block. |
-| `get(id)` / `delete(id)` / `list(filter?)` / `clear()` / `size()` | CRUD over records. |
-| `export()` / `import(snapshot)` | JSON snapshot round-trip. |
-| `backend` | The underlying `MemoryStore` (for advanced use). |
-
-## Backends (pluggable `MemoryStore`)
-
-| Factory | Runtime | Durability |
-| --- | --- | --- |
-| `createInMemoryStore()` (default) | Node + browser | none (process lifetime) |
-| `createIndexedDBStore({ dbName?, storeName?, indexedDB? })` | browser | durable across sessions |
-| `createFileStore(path)` | Node | durable JSON on disk |
-
-All backends store **pre-normalized** embeddings and perform a brute-force
-cosine top-k scan, which is fine to the thousands-of-records scale. Inject an
-`indexedDB` factory (e.g. `fake-indexeddb`) to exercise the IndexedDB backend
-under Node.
-
-## Embedder injection
-
-The module only needs `(texts: string[]) => Promise<Float32Array[]>`.
-`createGerbilEmbedder(engine)` adapts any object with a compatible
-`embedBatch` (a `Gerbil` instance, the one-liner `embedBatch`, or the browser
-`useEmbedding().embedBatch`). Any other embedder works by passing the function
-directly.
-
-## Chunking
-
-`add(text, { chunk: true })` or `add(text, { chunk: { chunkSize, overlap } })`
-splits long documents into overlapping character windows (defaults: 1000 chars,
-200 overlap), one record per chunk, so retrieval targets relevant passages.
-
-## Context packing (`recall`)
-
-`recall` retrieves a candidate pool (default `k: 20`), then greedily fills a
-context block highest-score-first, stopping before `tokenBudget` is exceeded
-(it skips a too-large candidate and tries smaller ones rather than stopping
-outright). Token counts are **approximate**: the heuristic is ~4 characters per
-token (the common English-ish rule), deliberately avoiding a tokenizer
-dependency. The goal is to stay under a model's context window, not exact
-accounting.
-
-## Privacy
-
-- `redact` is applied on **write**: a `RegExp` (matches → `[REDACTED]`) or a
-  `(text) => string` predicate.
-- `export()` / `import()` move the full corpus as JSON.
-
-## Follow-ups
-
-- **HNSW/ANN index** for >10k records (current scan is O(n) per query).
-- **Node OPFS / SQLite backend** for larger durable corpora than the JSON
-  file store comfortably holds.
-- **Real tokenizer** option for exact budgeting (currently a char heuristic).
-- **TTL / decay & dedup** policies for long-running agents.