@opencodehub/mcp 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @opencodehub/mcp
+
+Model Context Protocol server for OpenCodeHub. Wraps the analysis +
+storage layer and exposes it to coding agents over stdio.
+
+## Surface
+
+```bash
+codehub mcp   # spawn the stdio server
+```
+
+- Transport is stdio only — no HTTP, no SSE, no daemon
+  (`packages/cli/src/commands/mcp.ts`).
+- `list_repos` is the discovery entry point. Per-repo tools accept an
+  optional `repo` (registry name) or `repo_uri` alias (Sourcegraph-style
+  URI like `github.com/org/repo`, `local:<hash>` for unpublished repos);
+  with one repo registered both are optional.
+- When ≥ 2 repos are registered and neither is supplied, the tool
+  returns an `AMBIGUOUS_REPO` error envelope with `choices[]` (capped at
+  10) so the caller can retry deterministically (see root `CLAUDE.md`).
+- Every response carries a `next_steps` array and a
+  `_meta.codehub/staleness` entry when the index may be behind HEAD
+  (`packages/mcp/src/staleness.ts`).
+
+## Tools
+
+29 tools registered in `packages/mcp/src/server.ts:151-179`. Implementation
+files live under `packages/mcp/src/tools/<id>.ts`.
+
+| Group       | Tools                                                                                                      |
+| ----------- | ---------------------------------------------------------------------------------------------------------- |
+| Discovery   | `list_repos`, `query`, `context`, `route_map`, `tool_map`                                                  |
+| Impact      | `impact`, `api_impact`, `detect_changes`, `shape_check`, `rename`                                          |
+| Snapshot    | `pack_codebase`, `project_profile`, `dependencies`, `owners`, `risk_trends`                                |
+| Findings    | `scan`, `verdict`, `list_findings`, `list_findings_delta`, `license_audit`                                 |
+| Dead code   | `list_dead_code`, `remove_dead_code`                                                                       |
+| Group       | `group_list`, `group_query`, `group_status`, `group_contracts`, `group_cross_repo_links`, `group_sync`     |
+| Raw query   | `sql`                                                                                                      |
+
+## Design
+
+- **Single source of truth** — registration order in `server.ts` IS the
+  surface. `tool_map` introspects the live server so agents can list
+  tools without out-of-band documentation
+  (`packages/mcp/src/tools/tool-map.ts`).
+- **Structured errors over prose** — every error returns
+  `structuredContent.error = { error_code, jsonrpc_code, ... }` so a
+  caller can branch on `error_code` instead of regex-matching
+  (`packages/mcp/src/error-envelope.ts`).
+- **Repo resolution is centralised** — `repoResolver` and the
+  AMBIGUOUS_REPO envelope are wired through every per-repo tool so
+  ambiguity is reported once, consistently
+  (`packages/mcp/src/repo-resolver.ts`).
+- **Connection pooling** — the graph store is held in a per-process
+  pool to amortise DuckDB cold starts across many tool calls
+  (`packages/mcp/src/connection-pool.ts`).
+- **Lazy analysis** — heavy work (scan, code-pack, verdict) shells out
+  via `analysis-bridge` rather than running in the MCP process so a
+  hung scanner cannot stall the server (`packages/mcp/src/analysis-bridge.ts`).
+
+See ADR 0012 for the `repo_uri`-as-typed-attribute rationale and the
+root `CLAUDE.md` for the AMBIGUOUS_REPO retry contract.

package/dist/analysis-bridge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bridge to `@opencodehub/analysis`.
+ *
+ * The analysis package exposes `runImpact`, `runRename`, `runDetectChanges`,
+ * and `computeStaleness`, which this bridge re-exports for the tool handlers.
+ * A slim inline-impact fallback remains as a safety net for repos where
+ * analysis cannot resolve the target — e.g. a bare node-id with no
+ * declaration row — so the `impact` tool always returns something actionable.
+ */
+import { type DetectChangesQuery, type DetectChangesResult, type FsAbstraction, type ImpactQuery, type ImpactResult, type RenameQuery, type RenameResult } from "@opencodehub/analysis";
+import type { IGraphStore } from "@opencodehub/storage";
+export type { DetectChangesQuery, DetectChangesResult, ImpactQuery, ImpactResult, RenameEdit, RenameQuery, RenameResult, } from "@opencodehub/analysis";
+export declare function callRunImpact(store: IGraphStore, q: ImpactQuery): Promise<ImpactResult>;
+export declare function callRunRename(store: IGraphStore, q: RenameQuery, repoRoot: string, fs?: FsAbstraction): Promise<RenameResult>;
+export declare function callRunDetectChanges(store: IGraphStore, q: DetectChangesQuery): Promise<DetectChangesResult>;
+/**
+ * Graph-only impact fallback. Produces the same `ImpactResult` shape as
+ * the analysis package but skips the name-to-id resolution step — useful
+ * when the target is already a node id and the caller does not need
+ * candidate disambiguation.
+ */
+export declare function inlineImpact(store: IGraphStore, q: ImpactQuery): Promise<ImpactResult>;
+//# sourceMappingURL=analysis-bridge.d.ts.map

package/dist/analysis-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-bridge.d.ts","sourceRoot":"","sources":["../src/analysis-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,UAAU,EACV,WAAW,EACX,YAAY,GACb,MAAM,uBAAuB,CAAC;AAE/B,wBAAsB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAE7F;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,WAAW,EACd,QAAQ,EAAE,MAAM,EAChB,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,WAAW,EAClB,CAAC,EAAE,kBAAkB,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAE9B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAgE5F"}

package/dist/analysis-bridge.js

@@ -0,0 +1,83 @@
+/**
+ * Bridge to `@opencodehub/analysis`.
+ *
+ * The analysis package exposes `runImpact`, `runRename`, `runDetectChanges`,
+ * and `computeStaleness`, which this bridge re-exports for the tool handlers.
+ * A slim inline-impact fallback remains as a safety net for repos where
+ * analysis cannot resolve the target — e.g. a bare node-id with no
+ * declaration row — so the `impact` tool always returns something actionable.
+ */
+import { runDetectChanges as analysisRunDetectChanges, runImpact as analysisRunImpact, runRename as analysisRunRename, createNodeFs, } from "@opencodehub/analysis";
+export async function callRunImpact(store, q) {
+    return analysisRunImpact(store, q);
+}
+export async function callRunRename(store, q, repoRoot, fs) {
+    return analysisRunRename(store, q, fs ?? createNodeFs(), repoRoot);
+}
+export async function callRunDetectChanges(store, q) {
+    return analysisRunDetectChanges(store, q);
+}
+/**
+ * Graph-only impact fallback. Produces the same `ImpactResult` shape as
+ * the analysis package but skips the name-to-id resolution step — useful
+ * when the target is already a node id and the caller does not need
+ * candidate disambiguation.
+ */
+export async function inlineImpact(store, q) {
+    const maxDepth = q.maxDepth ?? 3;
+    const minConfidence = q.minConfidence ?? 0.3;
+    const direction = q.direction === "upstream" ? "up" : q.direction === "downstream" ? "down" : "both";
+    const travArgs = {
+        startId: q.target,
+        direction,
+        maxDepth,
+        minConfidence,
+    };
+    if (q.relationTypes && q.relationTypes.length > 0) {
+        travArgs.relationTypes = q.relationTypes;
+    }
+    const results = await store.traverse(travArgs);
+    const byDepthMap = new Map();
+    for (const r of results) {
+        let bucket = byDepthMap.get(r.depth);
+        if (!bucket) {
+            bucket = new Map();
+            byDepthMap.set(r.depth, bucket);
+        }
+        bucket.set(r.nodeId, true);
+    }
+    const depths = Array.from(byDepthMap.keys()).sort((a, b) => a - b);
+    const byDepth = depths.map((depth) => {
+        const bucket = byDepthMap.get(depth);
+        const ids = bucket ? Array.from(bucket.keys()) : [];
+        return {
+            depth,
+            nodes: ids.map((nodeId) => ({
+                id: nodeId,
+                name: nodeId,
+                filePath: "",
+                kind: "",
+                viaRelation: "CALLS",
+            })),
+        };
+    });
+    const d1 = byDepthMap.get(1)?.size ?? 0;
+    let risk = "LOW";
+    if (d1 >= 20)
+        risk = "CRITICAL";
+    else if (d1 >= 8)
+        risk = "HIGH";
+    else if (d1 >= 3)
+        risk = "MEDIUM";
+    return {
+        targetCandidates: [],
+        byDepth,
+        risk,
+        totalAffected: results.length,
+        ambiguous: false,
+        affectedProcesses: [],
+        affectedModules: [],
+        traversedEdges: [],
+    };
+}
+//# sourceMappingURL=analysis-bridge.js.map

package/dist/analysis-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-bridge.js","sourceRoot":"","sources":["../src/analysis-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,IAAI,wBAAwB,EAC5C,SAAS,IAAI,iBAAiB,EAC9B,SAAS,IAAI,iBAAiB,EAC9B,YAAY,GAQb,MAAM,uBAAuB,CAAC;AAa/B,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAkB,EAAE,CAAc;IACpE,OAAO,iBAAiB,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAkB,EAClB,CAAc,EACd,QAAgB,EAChB,EAAkB;IAElB,OAAO,iBAAiB,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,YAAY,EAAE,EAAE,QAAQ,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAkB,EAClB,CAAqB;IAErB,OAAO,wBAAwB,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAkB,EAAE,CAAc;IACnE,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;IACjC,MAAM,aAAa,GAAG,CAAC,CAAC,aAAa,IAAI,GAAG,CAAC;IAC7C,MAAM,SAAS,GACb,CAAC,CAAC,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IACrF,MAAM,QAAQ,GAMV;QACF,OAAO,EAAE,CAAC,CAAC,MAAM;QACjB,SAAS;QACT,QAAQ;QACR,aAAa;KACd,CAAC;IACF,IAAI,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,QAAQ,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;IAC3C,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAE/C,MAAM,UAAU,GAAG,IAAI,GAAG,EAA6B,CAAC;IACxD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;YACnB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACnC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,OAAO;YACL,KAAK;YACL,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC1B,EAAE,EAAE,MAAM;gBACV,IAAI,EAAE,MAAM;gBACZ,QAAQ,EAAE,EAAE;gBACZ,IAAI,EAAE,EAAE;gBACR,WAAW,EAAE,OAAO;aACrB,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;IACxC,IAAI,IAAI,GAAyB,KAAK,CAAC;IACvC,IAAI,EAAE,IAAI,EAAE;QAAE,IAAI,GAAG,UAAU,CAAC;SAC3B,IAAI,EAAE,IAAI,CAAC;QAAE,IAAI,GAAG,MAAM,CAAC;SAC3B,IAAI,EAAE,IAAI,CAAC;QAAE,IAAI,GAAG,QAAQ,CAAC;IAElC,OAAO;QACL,gBAAgB,EAAE,EAAE;QACpB,OAAO;QACP,IAAI;QACJ,aAAa,EAAE,OAAO,CAAC,MAAM;QAC7B,SAAS,EAAE,KAAK;QAChB,iBAAiB,EAAE,EAAE;QACrB,eAAe,EAAE,EAAE;QACnB,cAAc,EAAE,EAAE;KACnB,CAAC;AACJ,CAAC"}

package/dist/connection-pool.d.ts

@@ -0,0 +1,76 @@
+/**
+ * LRU-backed connection pool for graph stores.
+ *
+ * A single MCP session routinely fields back-to-back tool calls that all
+ * target the same repo; opening the underlying database for every call
+ * would be wasteful. We cache open `Store` (= `OpenStoreResult`) handles
+ * keyed by absolute repo path, with three safety guards on top of a plain
+ * LRU:
+ *
+ *   1. Per-key promise dedupe. Concurrent acquires for the same repo share
+ *      a single in-flight open() — otherwise DuckDB will raise on the
+ *      second connection opening the same file in read-write mode.
+ *   2. Reference counting. Release must decrement a per-entry counter; an
+ *      eviction that lands on a still-in-use entry MUST NOT close it. We
+ *      mark it `closed` deferred and the last release actually closes.
+ *   3. Idle TTL. lru-cache@11 bumps recency on every acquire, so a repo
+ *      that is actively queried never evicts; an idle repo closes after
+ *      15 minutes.
+ *
+ * `shutdown()` drains the pool on stdio close so the server exits cleanly.
+ *
+ * The pool caches the composed `OpenStoreResult` so MCP tools can route
+ * graph-tier calls through `store.graph` and temporal-tier calls
+ * (cochanges, summaries, `--sql` escape hatch) through `store.temporal`.
+ * Backend selection follows the standard `openStore` resolution (env-
+ * driven `CODEHUB_STORE`, with auto-detect when unset).
+ * `OpenStoreResult.close()` is the deterministic composite close — for
+ * the DuckDB-only deployment that's a single underlying close.
+ */
+import { type Store } from "@opencodehub/storage";
+export interface PoolEntry {
+    readonly store: Store;
+    refCount: number;
+    closed: boolean;
+    /** Set when an eviction fires while refCount > 0; close on last release. */
+    closePending: boolean;
+}
+export interface ConnectionPoolOptions {
+    readonly max?: number;
+    readonly ttlMs?: number;
+}
+/**
+ * Factory indirection keeps tests mockable without standing up the
+ * underlying database. Production always calls `openStore` so backend
+ * selection (DuckDB or the graph-db pairing) follows the env-driven
+ * resolution.
+ */
+export type StoreFactory = (dbPath: string) => Promise<Store>;
+export declare class ConnectionPool {
+    private readonly cache;
+    private readonly inflight;
+    private readonly factory;
+    private disposed;
+    constructor(opts?: ConnectionPoolOptions, factory?: StoreFactory);
+    /**
+     * Acquire a store handle for the given repo. The caller MUST pair every
+     * acquire with a release. The `dbPath` argument is the absolute path to
+     * the on-disk DuckDB file; `repoKey` is a stable identifier used for
+     * caching (usually the absolute repo path).
+     */
+    acquire(repoKey: string, dbPath: string): Promise<Store>;
+    /**
+     * Release a previously-acquired handle. If the entry was evicted while
+     * in use (`closePending`), the last release closes the store.
+     */
+    release(repoKey: string): Promise<void>;
+    /**
+     * Drain the pool: wait on any inflight opens, then close every cached
+     * entry. Safe to call multiple times.
+     */
+    shutdown(): Promise<void>;
+    /** Test-only view of cached keys; stable iteration order is not guaranteed. */
+    size(): number;
+    private findEvicted;
+}
+//# sourceMappingURL=connection-pool.d.ts.map

package/dist/connection-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-pool.d.ts","sourceRoot":"","sources":["../src/connection-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAG7D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAKD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;AAiB9D,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,GAAE,qBAA0B,EAAE,OAAO,GAAE,YAA6B;IA0BpF;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAsC9D;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7C;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB/B,+EAA+E;IAC/E,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,WAAW;CAYpB"}

package/dist/connection-pool.js

@@ -0,0 +1,179 @@
+/**
+ * LRU-backed connection pool for graph stores.
+ *
+ * A single MCP session routinely fields back-to-back tool calls that all
+ * target the same repo; opening the underlying database for every call
+ * would be wasteful. We cache open `Store` (= `OpenStoreResult`) handles
+ * keyed by absolute repo path, with three safety guards on top of a plain
+ * LRU:
+ *
+ *   1. Per-key promise dedupe. Concurrent acquires for the same repo share
+ *      a single in-flight open() — otherwise DuckDB will raise on the
+ *      second connection opening the same file in read-write mode.
+ *   2. Reference counting. Release must decrement a per-entry counter; an
+ *      eviction that lands on a still-in-use entry MUST NOT close it. We
+ *      mark it `closed` deferred and the last release actually closes.
+ *   3. Idle TTL. lru-cache@11 bumps recency on every acquire, so a repo
+ *      that is actively queried never evicts; an idle repo closes after
+ *      15 minutes.
+ *
+ * `shutdown()` drains the pool on stdio close so the server exits cleanly.
+ *
+ * The pool caches the composed `OpenStoreResult` so MCP tools can route
+ * graph-tier calls through `store.graph` and temporal-tier calls
+ * (cochanges, summaries, `--sql` escape hatch) through `store.temporal`.
+ * Backend selection follows the standard `openStore` resolution (env-
+ * driven `CODEHUB_STORE`, with auto-detect when unset).
+ * `OpenStoreResult.close()` is the deterministic composite close — for
+ * the DuckDB-only deployment that's a single underlying close.
+ */
+import { openStore } from "@opencodehub/storage";
+import { LRUCache } from "lru-cache";
+const DEFAULT_MAX = 8;
+const DEFAULT_TTL_MS = 15 * 60 * 1000;
+const defaultFactory = async (dbPath) => {
+    // openStore picks backend via CODEHUB_STORE (defaults to "duck"). We
+    // open read-only because every MCP tool is a reader; the ingestion
+    // pipeline owns writes and runs out-of-process.
+    const store = await openStore({ path: dbPath, readOnly: true });
+    await store.graph.open();
+    if (store.graphFile !== store.temporalFile) {
+        // Two distinct underlying files — open each side. For the default
+        // DuckDB backend graph and temporal alias the same instance and the
+        // second open() is a no-op.
+        await store.temporal.open();
+    }
+    return store;
+};
+export class ConnectionPool {
+    cache;
+    inflight = new Map();
+    factory;
+    disposed = false;
+    constructor(opts = {}, factory = defaultFactory) {
+        this.factory = factory;
+        this.cache = new LRUCache({
+            max: opts.max ?? DEFAULT_MAX,
+            ttl: opts.ttlMs ?? DEFAULT_TTL_MS,
+            updateAgeOnGet: true,
+            // The dispose callback fires on eviction (size or ttl) and on
+            // cache.clear(). We treat eviction as "this entry is no longer
+            // reachable from the cache"; if nobody is using it we close now,
+            // otherwise we let the last `release()` close it.
+            dispose: (entry, key) => {
+                if (entry.closed)
+                    return;
+                if (entry.refCount === 0) {
+                    entry.closed = true;
+                    void entry.store.close().catch(() => {
+                        /* swallow — best effort during eviction */
+                    });
+                }
+                else {
+                    entry.closePending = true;
+                }
+                // Ensure we don't leak a stale inflight promise for an evicted key.
+                this.inflight.delete(key);
+            },
+        });
+    }
+    /**
+     * Acquire a store handle for the given repo. The caller MUST pair every
+     * acquire with a release. The `dbPath` argument is the absolute path to
+     * the on-disk DuckDB file; `repoKey` is a stable identifier used for
+     * caching (usually the absolute repo path).
+     */
+    async acquire(repoKey, dbPath) {
+        if (this.disposed) {
+            throw new Error("ConnectionPool is shut down");
+        }
+        const existing = this.cache.get(repoKey);
+        if (existing && !existing.closed) {
+            existing.refCount += 1;
+            return existing.store;
+        }
+        const pending = this.inflight.get(repoKey);
+        if (pending) {
+            const entry = await pending;
+            entry.refCount += 1;
+            return entry.store;
+        }
+        const promise = (async () => {
+            const store = await this.factory(dbPath);
+            const entry = {
+                store,
+                refCount: 0,
+                closed: false,
+                closePending: false,
+            };
+            this.cache.set(repoKey, entry);
+            return entry;
+        })();
+        this.inflight.set(repoKey, promise);
+        try {
+            const entry = await promise;
+            entry.refCount += 1;
+            return entry.store;
+        }
+        finally {
+            this.inflight.delete(repoKey);
+        }
+    }
+    /**
+     * Release a previously-acquired handle. If the entry was evicted while
+     * in use (`closePending`), the last release closes the store.
+     */
+    async release(repoKey) {
+        const entry = this.cache.peek(repoKey) ?? this.findEvicted(repoKey);
+        if (!entry)
+            return;
+        if (entry.refCount > 0)
+            entry.refCount -= 1;
+        if (entry.refCount === 0 && entry.closePending && !entry.closed) {
+            entry.closed = true;
+            await entry.store.close().catch(() => {
+                /* swallow */
+            });
+        }
+    }
+    /**
+     * Drain the pool: wait on any inflight opens, then close every cached
+     * entry. Safe to call multiple times.
+     */
+    async shutdown() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Wait for inflight opens so we don't leak half-opened DBs.
+        const pending = Array.from(this.inflight.values());
+        await Promise.allSettled(pending);
+        this.inflight.clear();
+        const entries = [];
+        for (const entry of this.cache.values())
+            entries.push(entry);
+        this.cache.clear(); // triggers dispose on remaining entries
+        await Promise.allSettled(entries.map(async (entry) => {
+            if (!entry.closed) {
+                entry.closed = true;
+                await entry.store.close();
+            }
+        }));
+    }
+    /** Test-only view of cached keys; stable iteration order is not guaranteed. */
+    size() {
+        return this.cache.size;
+    }
+    findEvicted(_repoKey) {
+        // After dispose runs, the entry is gone from the cache; the caller
+        // holds no direct reference to it here. We intentionally don't store
+        // a secondary map — reference counting for evicted entries is tracked
+        // inside the entry object itself, which remains reachable via the
+        // store reference that the tool handler still holds. For the current
+        // MVP usage (single-threaded tool handlers that acquire + release in
+        // the same function) this branch is unreachable, so we return
+        // undefined and rely on the dispose path to have already closed the
+        // store if refCount was 0.
+        return undefined;
+    }
+}
+//# sourceMappingURL=connection-pool.js.map

package/dist/connection-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-pool.js","sourceRoot":"","sources":["../src/connection-pool.ts"],"names":[],"mappings":"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"}

package/dist/error-envelope.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Uniform error envelope for MCP tool responses.
+ *
+ * The OpenCodeHub PRD (§9.1) defines a single error code enumeration used
+ * across the MCP surface. Every tool that fails gracefully (i.e. the tool
+ * ran but the operation could not complete) returns this shape so agents
+ * can key on `error.code` to decide whether to retry, disambiguate, or
+ * abort.
+ *
+ * For protocol-level failures (unknown tool name, malformed JSON-RPC) the
+ * SDK's `McpError` class is thrown instead — those do not go through this
+ * helper.
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/** The fixed set of tool-level error codes exposed to MCP clients. */
+export type ErrorCode = "STALENESS" | "INVALID_INPUT" | "NOT_FOUND" | "DB_ERROR" | "SCHEMA_MISMATCH" | "RATE_LIMITED" | "INTERNAL" | "NO_INDEX" | "AMBIGUOUS_REPO" | "EMBEDDER_MISMATCH";
+/** Structured shape carried under `structuredContent.error`. */
+export interface ErrorDetail {
+    readonly code: ErrorCode;
+    readonly message: string;
+    readonly hint?: string;
+}
+/**
+ * One registered repo exposed to the caller in an `AMBIGUOUS_REPO` envelope
+ * so the LLM can retry with an explicit `repo_uri`. Snake-case wire fields
+ * are intentional — this shape crosses the MCP boundary to an agent, and
+ * the research spec (§6.2 of research-m5m6.yaml) names them that way.
+ *
+ * `repo_uri` is derived from the registry at error-construction time.
+ * Once the registry surfaces the persisted RepoNode, this field will
+ * be pulled from there instead of being computed from
+ * `RegistryEntry.name`.
+ */
+export interface RepoChoice {
+    readonly repo_uri: string;
+    readonly default_branch: string | null;
+    readonly group: string | null;
+}
+/**
+ * Extended detail shape for `AMBIGUOUS_REPO`. Retains the legacy
+ * `{ code, message, hint }` surface so existing callers (and tests at
+ * error-envelope.test.ts:39-47) keep working; adds structured fields for
+ * LLM disambiguation.
+ */
+export interface AmbiguousRepoDetail extends ErrorDetail {
+    readonly code: "AMBIGUOUS_REPO";
+    /** Alias of `code` — matches the `error_code` field in the research spec. */
+    readonly error_code: "AMBIGUOUS_REPO";
+    /** JSON-RPC code for "invalid params" — per MCP spec. */
+    readonly jsonrpc_code: -32602;
+    /** Capped at 10. */
+    readonly choices: readonly RepoChoice[];
+    /** Full count of matching registry entries (may exceed `choices.length`). */
+    readonly total_matches: number;
+}
+/**
+ * Input to {@link toolAmbiguousRepoError}. Caller (typically the repo
+ * resolver at `repo-resolver.ts`) provides the full choice set; this
+ * builder caps it to 10 and reports the untruncated total.
+ */
+export interface AmbiguousRepoPayload {
+    readonly message: string;
+    readonly hint: string;
+    readonly choices: readonly RepoChoice[];
+    readonly totalMatches: number;
+}
+/**
+ * Build a tool-level error result. Both `content` (for clients that only
+ * read text) and `structuredContent` (for clients that honour the output
+ * schema) are populated, and `isError` is set so output-schema validation
+ * is skipped by the SDK per the 2025-06-18 spec revision.
+ */
+export declare function toolError(code: ErrorCode, message: string, hint?: string): CallToolResult;
+/**
+ * Map an arbitrary thrown value to an `INTERNAL` error envelope. Used as a
+ * catch-all at the boundary of each tool handler so unexpected exceptions
+ * reach the agent as a structured error instead of tearing down the stdio
+ * transport.
+ */
+export declare function toolErrorFromUnknown(err: unknown, hint?: string): CallToolResult;
+/**
+ * Max number of `choices[]` entries carried in an AMBIGUOUS_REPO envelope.
+ * More than 10 gets truncated; `total_matches` still reports the full count
+ * so the caller knows there is more.
+ */
+export declare const AMBIGUOUS_REPO_CHOICES_CAP = 10;
+/**
+ * Build a structured AMBIGUOUS_REPO envelope. Wraps {@link toolError} so
+ * the legacy `{ code, message, hint }` fields stay intact (back-compat with
+ * `error-envelope.test.ts:39-47`) and layers on `error_code`, `choices[]`,
+ * `total_matches` for disambiguation by an agent.
+ *
+ * Choices are capped at {@link AMBIGUOUS_REPO_CHOICES_CAP}; `total_matches`
+ * always reports the pre-truncation count.
+ */
+export declare function toolAmbiguousRepoError(payload: AmbiguousRepoPayload): CallToolResult;
+//# sourceMappingURL=error-envelope.d.ts.map

package/dist/error-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-envelope.d.ts","sourceRoot":"","sources":["../src/error-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,sEAAsE;AACtE,MAAM,MAAM,SAAS,GACjB,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,iBAAiB,GACjB,cAAc,GACd,UAAU,GACV,UAAU,GACV,gBAAgB,GAChB,mBAAmB,CAAC;AAExB,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC;IAC9B,oBAAoB;IACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,CASzF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,CAGhF;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAkBpF"}

package/dist/error-envelope.js

@@ -0,0 +1,75 @@
+/**
+ * Uniform error envelope for MCP tool responses.
+ *
+ * The OpenCodeHub PRD (§9.1) defines a single error code enumeration used
+ * across the MCP surface. Every tool that fails gracefully (i.e. the tool
+ * ran but the operation could not complete) returns this shape so agents
+ * can key on `error.code` to decide whether to retry, disambiguate, or
+ * abort.
+ *
+ * For protocol-level failures (unknown tool name, malformed JSON-RPC) the
+ * SDK's `McpError` class is thrown instead — those do not go through this
+ * helper.
+ */
+/**
+ * Build a tool-level error result. Both `content` (for clients that only
+ * read text) and `structuredContent` (for clients that honour the output
+ * schema) are populated, and `isError` is set so output-schema validation
+ * is skipped by the SDK per the 2025-06-18 spec revision.
+ */
+export function toolError(code, message, hint) {
+    const lines = [`Error (${code}): ${message}`];
+    if (hint)
+        lines.push(`Hint: ${hint}`);
+    const detail = hint ? { code, message, hint } : { code, message };
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: { error: detail },
+        isError: true,
+    };
+}
+/**
+ * Map an arbitrary thrown value to an `INTERNAL` error envelope. Used as a
+ * catch-all at the boundary of each tool handler so unexpected exceptions
+ * reach the agent as a structured error instead of tearing down the stdio
+ * transport.
+ */
+export function toolErrorFromUnknown(err, hint) {
+    const message = err instanceof Error ? err.message : String(err);
+    return toolError("INTERNAL", message, hint);
+}
+/**
+ * Max number of `choices[]` entries carried in an AMBIGUOUS_REPO envelope.
+ * More than 10 gets truncated; `total_matches` still reports the full count
+ * so the caller knows there is more.
+ */
+export const AMBIGUOUS_REPO_CHOICES_CAP = 10;
+/**
+ * Build a structured AMBIGUOUS_REPO envelope. Wraps {@link toolError} so
+ * the legacy `{ code, message, hint }` fields stay intact (back-compat with
+ * `error-envelope.test.ts:39-47`) and layers on `error_code`, `choices[]`,
+ * `total_matches` for disambiguation by an agent.
+ *
+ * Choices are capped at {@link AMBIGUOUS_REPO_CHOICES_CAP}; `total_matches`
+ * always reports the pre-truncation count.
+ */
+export function toolAmbiguousRepoError(payload) {
+    const capped = payload.choices.slice(0, AMBIGUOUS_REPO_CHOICES_CAP);
+    const base = toolError("AMBIGUOUS_REPO", payload.message, payload.hint);
+    const baseDetail = base.structuredContent.error;
+    const detail = {
+        code: "AMBIGUOUS_REPO",
+        message: baseDetail.message,
+        ...(baseDetail.hint !== undefined ? { hint: baseDetail.hint } : {}),
+        error_code: "AMBIGUOUS_REPO",
+        jsonrpc_code: -32602,
+        choices: capped,
+        total_matches: payload.totalMatches,
+    };
+    return {
+        content: base.content,
+        structuredContent: { error: detail },
+        isError: true,
+    };
+}
+//# sourceMappingURL=error-envelope.js.map

package/dist/error-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-envelope.js","sourceRoot":"","sources":["../src/error-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAuEH;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,OAAe,EAAE,IAAa;IACvE,MAAM,KAAK,GAAG,CAAC,UAAU,IAAI,MAAM,OAAO,EAAE,CAAC,CAAC;IAC9C,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,MAAM,GAAgB,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC/E,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5D,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;QACpC,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY,EAAE,IAAa;IAC9D,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,SAAS,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA6B;IAClE,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,0BAA0B,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,MAAM,UAAU,GAAI,IAAI,CAAC,iBAA4C,CAAC,KAAK,CAAC;IAC5E,MAAM,MAAM,GAAwB;QAClC,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,GAAG,CAAC,UAAU,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,UAAU,EAAE,gBAAgB;QAC5B,YAAY,EAAE,CAAC,KAAK;QACpB,OAAO,EAAE,MAAM;QACf,aAAa,EAAE,OAAO,CAAC,YAAY;KACpC,CAAC;IACF,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;QACpC,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}