brainbank 0.1.3 → 0.1.5

package/src/mcp/mcp-server.ts

@@ -0,0 +1,192 @@
+/**
+ * BrainBank — MCP Server
+ *
+ * Exposes BrainBank as an MCP server via stdio transport.
+ * Works with Google Antigravity, Claude Code, and any MCP-compatible client.
+ *
+ * Tools:
+ *   brainbank_query — AI-pruned semantic context for a task
+ *   brainbank_index — Index/re-index a repository
+ */
+
+
+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.1.5',
+});
+
+// ── Tool: brainbank_query ───────────────────────────
+
+server.registerTool(
+    'brainbank_query',
+    {
+        title: 'BrainBank Context',
+        description:
+            'Get AI-pruned semantic context for a task. Returns search hits + full call tree ' +
+            'with `called by` annotations, topologically ordered. Pass `context` for general ' +
+            'background and `pruner` for specific filtering instructions.',
+        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'),
+            context: z.string().optional().describe('General task context for the pruner — e.g. GitHub issue body, requirements doc, conversation context. Helps the AI pruner understand the broader task'),
+            pruner: z.string().optional().describe('Specific pruning instructions — tells the pruner exactly what to focus on (e.g. "only keep files related to WebSocket JWT refresh")'),
+        }),
+    },
+    async ({ task, affectedFiles, codeResults, gitResults, docsResults, sources, path, ignore, repo, lines, symbols, compact, callTree, imports, context: ctx, pruner: prunerCtx }) => {
+        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;
+
+        const context = await brainbank.getContext(task, {
+            affectedFiles,
+            sources: resolvedSources,
+            pathPrefix: path,
+            ignorePaths: ignore,
+            source: 'mcp',
+            fields: Object.keys(fields).length > 0 ? fields : undefined,
+            context: ctx,
+            prunerContext: prunerCtx,
+        });
+
+        return { content: [{ type: 'text' as const, text: context }] };
+    },
+);
+
+
+
+// ── Tool: brainbank_index ───────────────────────────
+
+server.registerTool(
+    'brainbank_index',
+    {
+        title: 'BrainBank Index',
+        description:
+            'Index (or re-index) a repository. Scans code files, git history, and documents, ' +
+            'then builds vector embeddings and FTS5 indices. Run this after significant code changes ' +
+            'or when search results feel stale. Returns a summary of what changed.',
+        inputSchema: z.object({
+            repo: z.string().describe('Repository path to index'),
+            forceReindex: z.boolean().optional().default(false).describe('Force re-index all files (ignore cache). Use when embeddings changed or index is corrupted'),
+            modules: z.array(z.string()).optional().describe('Which plugins to index (e.g. ["code", "git", "docs"]). Omit to use config defaults'),
+        }),
+    },
+    async ({ repo, forceReindex, modules }) => {
+        const brainbank = await getBrainBank(repo);
+
+        const result = await brainbank.index({
+            forceReindex,
+            modules: modules && modules.length > 0 ? modules : undefined,
+        });
+
+        // Format results summary
+        const lines: string[] = ['# Index Results\n'];
+        let hasChanges = false;
+
+        for (const [name, value] of Object.entries(result)) {
+            if (!value) continue;
+            const v = value as Record<string, unknown>;
+            if (typeof v.indexed !== 'number') {
+                lines.push(`✓ ${name}: done`);
+                continue;
+            }
+
+            const indexed = v.indexed as number;
+            const skipped = (v.skipped ?? 0) as number;
+            const removed = (v.removed ?? 0) as number;
+            const chunks = (v.chunks ?? 0) as number;
+
+            if (indexed > 0 || removed > 0) hasChanges = true;
+
+            const parts: string[] = [];
+            if (indexed > 0) parts.push(`+${indexed} files (${chunks} chunks)`);
+            if (removed > 0) parts.push(`−${removed} files`);
+            if (skipped > 0) parts.push(`${skipped} unchanged`);
+
+            lines.push(`${name}: ${parts.join('  ')}`);
+        }
+
+        if (!hasChanges) {
+            lines.push('No changes — everything up to date');
+        }
+
+        // Stats
+        const stats = brainbank.stats();
+        lines.push('\n## Totals\n');
+        for (const [name, s] of Object.entries(stats)) {
+            if (!s || typeof s !== 'object') continue;
+            const entries = Object.entries(s as Record<string, unknown>)
+                .map(([k, v]) => `${k}: ${v}`)
+                .join(', ');
+            lines.push(`${name}: ${entries}`);
+        }
+
+        return { content: [{ type: 'text' as const, text: lines.join('\n') }] };
+    },
+);
+
+
+// ── 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);
+    }
+}