brainbank 0.1.0-beta.1

package/src/mcp/mcp-server.ts

@@ -0,0 +1,195 @@
+/**
+ * BrainBank — MCP Server
+ *
+ * Exposes BrainBank as an MCP server via stdio transport.
+ * Works with Google Antigravity, Claude Desktop, and any MCP-compatible client.
+ *
+ * Usage in mcp_config.json:
+ * {
+ *   "mcpServers": {
+ *     "brainbank": {
+ *       "command": "brainbank-mcp"
+ *     }
+ *   }
+ * }
+ *
+ * Tools:
+ *   brainbank_context — Workflow Trace: search + call tree + called-by annotations
+ *   brainbank_search  — Hybrid search (vector + BM25 → RRF), returns structured results
+ *
+ * Indexing is handled by the CLI (`brainbank index`) — not exposed as an MCP tool.
+ */
+
+import type { SearchResult } from '@/types.ts';
+import type { SearchOptions } from '@/search/types.ts';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod/v3';
+
+import { WorkspacePool } from './workspace-pool.ts';
+import { createWorkspaceBrain, resolveRepoPath } from './workspace-factory.ts';
+
+
+
+// ── Multi-Workspace BrainBank Pool ─────────────────────
+
+const pool = new WorkspacePool({
+    factory: createWorkspaceBrain,
+    maxMemoryMB: parseInt(process.env.BRAINBANK_MAX_MEMORY_MB ?? '2048', 10),
+    ttlMinutes: parseInt(process.env.BRAINBANK_TTL_MINUTES ?? '30', 10),
+    onError: (repo, err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`BrainBank pool error [${repo}]: ${msg}`);
+    },
+});
+
+/** Resolve repo and get a BrainBank from the pool. */
+async function getBrainBank(targetRepo?: string) {
+    return pool.get(resolveRepoPath(targetRepo));
+}
+
+// ── MCP Server Setup ────────────────────────────────
+
+const server = new McpServer({
+    name: 'brainbank',
+    version: '0.9.7',
+});
+
+// ── Tool: brainbank_context ─────────────────────────
+
+server.registerTool(
+    'brainbank_context',
+    {
+        title: 'BrainBank Context',
+        description:
+            'Get a formatted knowledge context block for a task. Returns a Workflow Trace: ' +
+            'search hits + full call tree with `called by` annotations, topologically ordered. ' +
+            'All source code included — no trimming, no truncation.',
+        inputSchema: z.object({
+            task: z.string().describe('Description of the task you need context for'),
+            affectedFiles: z.array(z.string()).optional().default([]).describe('Files you plan to modify (improves co-edit suggestions)'),
+            codeResults: z.number().optional().default(20).describe('Max code results'),
+            gitResults: z.number().optional().default(5).describe('Max git commit results'),
+            docsResults: z.number().optional().describe('Max document results (omit to skip docs)'),
+            sources: z.record(z.number()).optional().describe('Per-source result limits, overrides codeResults/gitResults/docsResults (e.g. { code: 10, git: 0, docs: 5 })'),
+            path: z.union([z.string(), z.array(z.string())]).optional().describe('Filter results to files under these path prefixes. Pass a single string or array (e.g. ["src/services/", "lib/"])'),
+            ignore: z.array(z.string()).optional().describe('Exclude results whose filePath starts with any of these prefixes (e.g. ["src/tests/", "src/mocks/"])'),
+            repo: z.string().describe('Repository path (default: BRAINBANK_REPO)'),
+            // BrainBankQL context fields
+            lines: z.boolean().optional().describe('Prefix each code line with its source line number (e.g. 127| code)'),
+            symbols: z.boolean().optional().describe('Append symbol index (all functions, classes, interfaces) for matched files'),
+            compact: z.boolean().optional().describe('Show only function/class signatures, skip bodies'),
+            callTree: z.union([z.boolean(), z.object({ depth: z.number() })]).optional().describe('Include call tree expansion. Pass { depth: N } to control depth'),
+            imports: z.boolean().optional().describe('Include dependency/import summary section'),
+            expander: z.boolean().optional().describe('Enable LLM-powered context expansion to discover related chunks not found by search'),
+        }),
+    },
+    async ({ task, affectedFiles, codeResults, gitResults, docsResults, sources, path, ignore, repo, lines, symbols, compact, callTree, imports, expander }) => {
+        const repoPath = resolveRepoPath(repo);
+        const brainbank = await getBrainBank(repo);
+
+        // Build sources from explicit params, then let `sources` override
+        const base: Record<string, number> = { code: codeResults, git: gitResults };
+        if (docsResults !== undefined) base.docs = docsResults;
+        const resolvedSources = sources ? { ...base, ...sources } : base;
+
+        // Build fields from explicit params (only include defined values)
+        const fields: Record<string, unknown> = {};
+        if (lines !== undefined) fields.lines = lines;
+        if (symbols !== undefined) fields.symbols = symbols;
+        if (compact !== undefined) fields.compact = compact;
+        if (callTree !== undefined) fields.callTree = callTree;
+        if (imports !== undefined) fields.imports = imports;
+        if (expander !== undefined) fields.expander = expander;
+
+        const context = await brainbank.getContext(task, {
+            affectedFiles,
+            sources: resolvedSources,
+            pathPrefix: path,
+            ignorePaths: ignore,
+            source: 'mcp',
+            fields: Object.keys(fields).length > 0 ? fields : undefined,
+        });
+
+        return { content: [{ type: 'text' as const, text: context }] };
+    },
+);
+
+// ── Tool: brainbank_search ──────────────────────────
+
+/** Format SearchResult[] into readable text blocks for the agent. */
+function formatSearchResults(results: SearchResult[]): string {
+    if (results.length === 0) return 'No results found.';
+
+    const lines: string[] = [];
+    for (const r of results) {
+        const score = Math.round(r.score * 100);
+        if (r.type === 'code') {
+            const m = r.metadata;
+            lines.push(`[CODE ${score}%] ${r.filePath} — ${m.name || m.chunkType} L${m.startLine}-${m.endLine}`);
+            lines.push(r.content);
+            lines.push('');
+        } else if (r.type === 'commit') {
+            const m = r.metadata;
+            lines.push(`[COMMIT ${score}%] ${m.shortHash} ${r.content} (${m.author})`);
+            if (m.files?.length) lines.push(`  Files: ${m.files.slice(0, 6).join(', ')}`);
+            lines.push('');
+        } else if (r.type === 'document') {
+            const ctx = r.context ? ` — ${r.context}` : '';
+            lines.push(`[DOC ${score}%] ${r.filePath} [${r.metadata.collection}]${ctx}`);
+            lines.push(r.content);
+            lines.push('');
+        } else if (r.type === 'collection') {
+            lines.push(`[COLLECTION ${score}%] ${r.metadata.collection ?? 'kv'}`);
+            lines.push(r.content);
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+
+server.registerTool(
+    'brainbank_search',
+    {
+        title: 'BrainBank Search',
+        description:
+            'Hybrid search across the codebase: combines vector similarity + BM25 keyword matching ' +
+            'via Reciprocal Rank Fusion. Returns code chunks, git commits, and documents ranked by relevance. ' +
+            'Use for finding code, understanding systems, and locating files by meaning.',
+        inputSchema: z.object({
+            query: z.string().describe('Natural language search query (e.g. "authentication middleware", "WebSocket reconnection")'),
+            repo: z.string().describe('Repository path (default: BRAINBANK_REPO)'),
+            sources: z.record(z.number()).optional().describe('Per-source result limits (e.g. { code: 10, git: 0, docs: 5 }). Set source to 0 to skip it'),
+            path: z.union([z.string(), z.array(z.string())]).optional().describe('Filter results to files under these path prefixes (e.g. "src/services" or ["src/", "lib/"])'),
+            maxResults: z.number().optional().default(20).describe('Maximum total results to return'),
+        }),
+    },
+    async ({ query, repo, sources, path, maxResults }) => {
+        const brainbank = await getBrainBank(repo);
+
+        const opts: Record<string, unknown> = { source: 'mcp' as const };
+        if (sources) opts.sources = sources;
+        if (path) opts.pathPrefix = path;
+
+        const results = await brainbank.hybridSearch(query, opts as SearchOptions);
+        const limited = results.slice(0, maxResults);
+        const text = formatSearchResults(limited);
+
+        return { content: [{ type: 'text' as const, text }] };
+    },
+);
+
+
+// ── Start Server ────────────────────────────────────
+
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+
+main().catch(err => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`BrainBank MCP Server Error: ${message}`);
+    process.exit(1);
+});

package/src/mcp/workspace-factory.ts

@@ -0,0 +1,68 @@
+/**
+ * WorkspaceFactory — creates BrainBank instances via the core factory.
+ *
+ * Delegates to `createBrain()` from the core factory, passing
+ * a portable `BrainContext`. No plugin hardcoding — the factory handles
+ * plugin discovery from config and installed packages.
+ */
+
+import type { BrainBank } from '@/brainbank.ts';
+import type { BrainContext } from '@/cli/factory/brain-context.ts';
+
+import { createBrain, resetFactoryCache } from '@/cli/factory/index.ts';
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Detect repo root by walking up from startDir until we find `.git/`.
+ * Returns startDir itself if no `.git/` is found.
+ */
+export function findRepoRoot(startDir: string): string {
+    let dir = path.resolve(startDir);
+    while (true) {
+        if (fs.existsSync(path.join(dir, '.git'))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return path.resolve(startDir);
+}
+
+/** Resolve the effective repo path from an optional target, env, or cwd. */
+export function resolveRepoPath(targetRepo?: string): string {
+    const rp = targetRepo
+        ?? process.env.BRAINBANK_REPO
+        ?? findRepoRoot(process.cwd());
+    return rp.replace(/\/+$/, '');
+}
+
+/**
+ * Create a BrainBank instance for a workspace.
+ * Uses the core factory which handles:
+ * - Config loading from .brainbank/config.json
+ * - Dynamic plugin discovery and registration
+ * - Embedding/pruner/expander provider setup
+ * - Folder plugin auto-discovery
+ */
+export async function createWorkspaceBrain(repoPath: string): Promise<BrainBank> {
+    resetFactoryCache();
+
+    const context: BrainContext = {
+        repoPath,
+        env: process.env as Record<string, string | undefined>,
+    };
+
+    // Silence stdout during initialization — the core factory emits ANSI-colored
+    // console.log messages (plugin loading) that corrupt
+    // the MCP JSON-RPC stdio transport. Redirect console.log → stderr temporarily.
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => console.error(...args);
+    try {
+        const brain = await createBrain(context);
+        await brain.initialize();
+        return brain;
+    } finally {
+        console.log = origLog;
+    }
+}

package/src/mcp/workspace-pool.ts

@@ -0,0 +1,224 @@
+/**
+ * WorkspacePool — BrainBank instance lifecycle manager.
+ *
+ * Manages cached BrainBank instances per workspace with:
+ * - Memory-pressure eviction (oldest idle first)
+ * - TTL eviction for inactive workspaces
+ * - Active-operation tracking (prevents mid-query eviction)
+ * - Hot-reload of stale HNSW indices
+ */
+
+import type { BrainBank } from '@/brainbank.ts';
+
+/** Pool configuration. */
+export interface PoolOptions {
+    /** Max total estimated memory in MB. Default: 2048. */
+    maxMemoryMB?: number;
+    /** Minutes of inactivity before eviction. Default: 30. */
+    ttlMinutes?: number;
+    /** Factory function to create a BrainBank for a repo path. */
+    factory: (repoPath: string) => Promise<BrainBank>;
+    /** Called when a workspace is evicted. */
+    onEvict?: (repoPath: string) => void;
+    /** Called when an error occurs during pool operations. */
+    onError?: (repoPath: string, err: unknown) => void;
+}
+
+/** Internal pool entry. */
+interface PoolEntry {
+    brain: BrainBank;
+    repoPath: string;
+    lastAccess: number;
+    createdAt: number;
+    activeOps: number;
+}
+
+/** Public pool statistics. */
+export interface PoolStats {
+    size: number;
+    totalMemoryMB: number;
+    entries: PoolEntryStats[];
+}
+
+/** Per-entry statistics. */
+export interface PoolEntryStats {
+    repoPath: string;
+    lastAccessAgo: string;
+    memoryMB: number;
+    activeOps: number;
+}
+
+const DEFAULT_MAX_MEMORY_MB = 2048;
+const DEFAULT_TTL_MINUTES = 30;
+const EVICTION_INTERVAL_MS = 60_000;
+
+/** Format milliseconds as a human-readable "ago" string. */
+function formatAgo(ms: number): string {
+    if (ms < 60_000) return `${Math.round(ms / 1000)}s ago`;
+    if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m ago`;
+    return `${Math.round(ms / 3_600_000)}h ago`;
+}
+
+export class WorkspacePool {
+    private _pool = new Map<string, PoolEntry>();
+    private _timer: ReturnType<typeof setInterval> | null = null;
+    private _maxMemoryBytes: number;
+    private _ttlMs: number;
+    private _factory: (repoPath: string) => Promise<BrainBank>;
+    private _onEvict?: (repoPath: string) => void;
+    private _onError?: (repoPath: string, err: unknown) => void;
+
+    constructor(options: PoolOptions) {
+        this._maxMemoryBytes = (options.maxMemoryMB ?? DEFAULT_MAX_MEMORY_MB) * 1024 * 1024;
+        this._ttlMs = (options.ttlMinutes ?? DEFAULT_TTL_MINUTES) * 60 * 1000;
+        this._factory = options.factory;
+        this._onEvict = options.onEvict;
+        this._onError = options.onError;
+
+        this._timer = setInterval(() => this._evictStale(), EVICTION_INTERVAL_MS);
+        // Don't hold the process open for the timer
+        if (this._timer.unref) this._timer.unref();
+    }
+
+    /** Number of cached workspaces. */
+    get size(): number {
+        return this._pool.size;
+    }
+
+    /**
+     * Get a BrainBank for the given repo path.
+     * Returns a cached instance (with hot-reload) or creates a new one.
+     */
+    async get(repoPath: string): Promise<BrainBank> {
+        const key = repoPath.replace(/\/+$/, '');
+
+        const existing = this._pool.get(key);
+        if (existing) {
+            existing.lastAccess = Date.now();
+            try { await existing.brain.ensureFresh(); } catch { /* stale is better than nothing */ }
+            return existing.brain;
+        }
+
+        this._evictByMemoryPressure();
+
+        const brain = await this._factory(key);
+        this._pool.set(key, {
+            brain,
+            repoPath: key,
+            lastAccess: Date.now(),
+            createdAt: Date.now(),
+            activeOps: 0,
+        });
+
+        return brain;
+    }
+
+    /**
+     * Execute an operation with active-op tracking.
+     * Prevents the workspace from being evicted while the operation runs.
+     */
+    async withBrain<T>(repoPath: string, fn: (brain: BrainBank) => Promise<T>): Promise<T> {
+        const brain = await this.get(repoPath);
+        const key = repoPath.replace(/\/+$/, '');
+        const entry = this._pool.get(key);
+        if (entry) entry.activeOps++;
+
+        try {
+            return await fn(brain);
+        } finally {
+            if (entry) {
+                entry.activeOps--;
+                entry.lastAccess = Date.now();
+            }
+        }
+    }
+
+    /** Manually evict a specific workspace. */
+    evict(repoPath: string): void {
+        const key = repoPath.replace(/\/+$/, '');
+        this._evictEntry(key);
+    }
+
+    /** Get pool statistics. */
+    stats(): PoolStats {
+        const now = Date.now();
+        let totalMemory = 0;
+        const entries: PoolEntryStats[] = [];
+
+        for (const entry of this._pool.values()) {
+            const memBytes = entry.brain.memoryHint();
+            const memMB = Math.round(memBytes / 1024 / 1024 * 100) / 100;
+            totalMemory += memBytes;
+
+            entries.push({
+                repoPath: entry.repoPath,
+                lastAccessAgo: formatAgo(now - entry.lastAccess),
+                memoryMB: memMB,
+                activeOps: entry.activeOps,
+            });
+        }
+
+        return {
+            size: this._pool.size,
+            totalMemoryMB: Math.round(totalMemory / 1024 / 1024 * 100) / 100,
+            entries,
+        };
+    }
+
+    /** Close all entries and stop the eviction timer. */
+    close(): void {
+        if (this._timer) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+        for (const key of [...this._pool.keys()]) {
+            this._evictEntry(key);
+        }
+    }
+
+    /** Evict workspaces that haven't been accessed within the TTL. */
+    private _evictStale(): void {
+        const cutoff = Date.now() - this._ttlMs;
+        for (const [key, entry] of this._pool) {
+            if (entry.lastAccess < cutoff && entry.activeOps === 0) {
+                this._evictEntry(key);
+            }
+        }
+    }
+
+    /** Evict oldest idle entries until total memory is under the limit. */
+    private _evictByMemoryPressure(): void {
+        let totalMemory = 0;
+        for (const entry of this._pool.values()) {
+            totalMemory += entry.brain.memoryHint();
+        }
+
+        if (totalMemory < this._maxMemoryBytes) return;
+
+        // Sort by lastAccess ascending (oldest first), filter idle
+        const candidates = [...this._pool.entries()]
+            .filter(([, e]) => e.activeOps === 0)
+            .sort(([, a], [, b]) => a.lastAccess - b.lastAccess);
+
+        for (const [key, entry] of candidates) {
+            if (totalMemory < this._maxMemoryBytes) break;
+            totalMemory -= entry.brain.memoryHint();
+            this._evictEntry(key);
+        }
+    }
+
+    /** Evict a single entry by key. */
+    private _evictEntry(key: string): void {
+        const entry = this._pool.get(key);
+        if (!entry) return;
+
+        try {
+            entry.brain.close();
+        } catch (err: unknown) {
+            this._onError?.(key, err);
+        }
+
+        this._pool.delete(key);
+        this._onEvict?.(key);
+    }
+}