@maxgfr/codeindex 2.17.1 → 2.19.0

package/src/mcp.ts

@@ -1,20 +1,21 @@
 // MCP (Model Context Protocol) server over stdio — hand-rolled JSON-RPC 2.0 so
 // the engine stays zero-dependency. Newline-delimited JSON messages, protocol
 // 2024-11-05 (compatible with later revisions' initialize handshake). Exposes
-// the engine's read-only indexing capabilities as MCP tools; every tool takes a
-// `repo` path and returns JSON text content.
+// the engine's indexing capabilities as MCP tools; every tool takes a `repo`
+// path and returns text content — JSON, except repo_map, mermaid and
+// read_memory, which return their own formats.
 //
-// Register in an MCP client as:  node scripts/engine.mjs mcp
-import { readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+// Register in an MCP client as:  codeindex mcp
+// (NOT `node scripts/engine.mjs mcp`: engine.mjs is a side-effect-free library
+// with no main-module guard — see src/engine.ts — so that command does nothing.
+// The entrypoint is the `codeindex` bin, i.e. scripts/cli.mjs.)
+import { readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { createInterface } from "node:readline";
-import { ENGINE_VERSION, SCHEMA_VERSION, EXTRACTOR_VERSION, type FileRecord, type Graph, type SymbolIndex } from "./types.js";
-import { ensureGrammars, grammarKeysForExts } from "./ast/loader.js";
-import { buildArtifactsFromScan, type IndexArtifacts } from "./pipeline.js";
+import { ENGINE_VERSION } from "./types.js";
 import { renderGraphJson } from "./render/graph-json.js";
-import { scanRepo, type RepoScan, type ScanOptions } from "./scan.js";
-import { walk } from "./walk.js";
 import { buildCallerIndex } from "./callers.js";
+import { callerIndexFor } from "./derived.js";
 import { detectWorkspaces } from "./workspaces.js";
 import { gitChurn } from "./git.js";
 import { grepRepo } from "./grep.js";
@@ -28,11 +29,59 @@ import { replaceSymbolBody, insertAfterSymbol, insertBeforeSymbol } from "./edit
 import { writeMemory, readMemory, deleteMemory, listMemories } from "./memory.js";
 import { searchIndex } from "./bm25.js";
 import { checkRules, parseRules } from "./rules.js";
-import { EMBED_VERSION, resolveEmbedModelDir, loadEmbedModel, type StaticEmbedModel } from "./embed/model.js";
-import { buildEmbeddingIndex, type EmbeddingIndex } from "./embed/index.js";
+import { EMBED_VERSION, resolveEmbedModelDir } from "./embed/model.js";
+import { buildEmbeddingIndex } from "./embed/index.js";
 import { searchSemantic } from "./embed/search.js";
 import { resolveEmbedEndpoint, buildEndpointIndex, encodeQueryViaEndpoint, probeEndpoint } from "./embed/endpoint.js";
-import { sha1 } from "./hash.js";
+import { walk, type WalkResult } from "./walk.js";
+import { toolsFor, OUTPUT_SCHEMAS } from "./mcp/tools.js";
+import {
+  DEFAULT_MAX_RESPONSE_BYTES,
+  RICH_TOOLS_SINCE,
+  PROTOCOL_VERSIONS,
+  capResponse,
+  negotiateProtocol,
+  resourceLinkFor,
+  structuredContentFor,
+  validateArgs,
+} from "./mcp/protocol.js";
+import {
+  getArtifacts,
+  getScan,
+  getScanSummary,
+  memoizedEmbeddingIndex,
+  memoizedEmbedModel,
+  scanFingerprint,
+  sessionClear,
+  warmGrammarsForWalk,
+  type SessionScanOptions,
+} from "./mcp/session.js";
+
+// The public surface of this module is unchanged: everything that used to live
+// here is re-exported, so `src/engine.ts`, the tests and any consumer importing
+// from "./mcp.js" keep working exactly as before.
+export { toolsFor, TOOLS, TOOL_META, OUTPUT_SCHEMAS, annotationsFor } from "./mcp/tools.js";
+export {
+  DEFAULT_MAX_RESPONSE_BYTES,
+  PROTOCOL_VERSIONS,
+  capResponse,
+  negotiateProtocol,
+  resourceLinkFor,
+  structuredContentFor,
+  validateArgs,
+} from "./mcp/protocol.js";
+export {
+  getArtifacts,
+  getScan,
+  getScanSummary,
+  memoizedEmbeddingIndex,
+  memoizedEmbedModel,
+  scanFingerprint,
+  toCacheMap,
+  warmGrammarsForRepo,
+  warmGrammarsForWalk,
+} from "./mcp/session.js";
+export type { EmbeddingIndexCacheKey, SessionScanOptions } from "./mcp/session.js";
 
 interface RpcRequest {
   jsonrpc: "2.0";
@@ -41,622 +90,23 @@ interface RpcRequest {
   params?: Record<string, unknown>;
 }
 
-const repoProp = { repo: { type: "string", description: "Absolute path to the repository root" } };
-const scopeProps = {
-  scope: { type: "string", description: "Restrict to one directory (repo-relative)" },
-  include: { type: "array", items: { type: "string" }, description: "Include globs" },
-  exclude: { type: "array", items: { type: "string" }, description: "Exclude globs" },
-};
-
-const TOOLS = [
-  {
-    name: "scan_summary",
-    description:
-      "Deterministically scan a repository: file count, per-language file histogram, HEAD commit, and whether the walk was capped. Fast first look at any codebase.",
-    inputSchema: { type: "object", properties: { ...repoProp, ...scopeProps }, required: ["repo"] },
-  },
-  {
-    name: "graph",
-    description:
-      "Build the full typed cross-file link-graph (import/call/use/doc-link/mention edges, module grouping, PageRank centrality, Louvain communities, tests-map). Returns graph.json. Large on big repos — prefer scan_summary/symbols/callers for targeted questions.",
-    inputSchema: { type: "object", properties: { ...repoProp, ...scopeProps }, required: ["repo"] },
-  },
-  {
-    name: "symbols",
-    description:
-      "Where is a symbol defined and which files reference it? Returns the definition sites (file, line, kind, exported) and referencing files. Omit `name` for the full symbol index.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, name: { type: "string", description: "Symbol name to look up" } },
-      required: ["repo"],
-    },
-  },
-  {
-    name: "callers",
-    description:
-      "Who calls a function? Per-symbol caller index: each defined symbol with the exact (file, line) call sites that bind to it. Omit `name` for the full index.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, name: { type: "string", description: "Symbol name to look up" } },
-      required: ["repo"],
-    },
-  },
-  {
-    name: "workspaces",
-    description:
-      "Detect monorepo packages (npm/pnpm/yarn/lerna/nx/cargo/go.work/maven) with the workspace dependency graph, one cycle if present, and a topological build order.",
-    inputSchema: { type: "object", properties: { ...repoProp }, required: ["repo"] },
-  },
-  {
-    name: "churn",
-    description: "Per-file git commit counts (whole history, or since a ref) — the churn half of hotspot analysis.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, since: { type: "string", description: "Only count commits after this ref" } },
-      required: ["repo"],
-    },
-  },
-  {
-    name: "symbols_overview",
-    description:
-      "All symbols declared in ONE file (name, kind, line span, exported, parent), in declaration order — the fastest way to understand a file without reading it.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, file: { type: "string", description: "Repo-relative file path" } },
-      required: ["repo", "file"],
-    },
-  },
-  {
-    name: "find_symbol",
-    description:
-      "Find symbol declarations by name or name path ('Class/method' matches a method inside Class). Options: substring matching, includeBody to return the declaration's source. Exact-name matches rank first.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...repoProp,
-        namePath: { type: "string", description: "Symbol name or Parent/child path" },
-        substring: { type: "boolean" },
-        includeBody: { type: "boolean" },
-      },
-      required: ["repo", "namePath"],
-    },
-  },
-  {
-    name: "find_references",
-    description:
-      "Who references a symbol? Three labeled tiers: defs (declarations), callSites (line-precise, import-corroborated call bindings), referencingFiles (file-level identifier/doc mentions — may include homonyms). Confidence decreases across tiers; the labels let you decide what to trust.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, name: { type: "string", description: "Symbol name" } },
-      required: ["repo", "name"],
-    },
-  },
-  {
-    name: "repo_map",
-    description:
-      "Token-budgeted map of the repository: the highest-PageRank files with their key exported signatures, deterministically rendered to fit `budgetTokens` (default 1024). The densest single read to understand an unfamiliar codebase.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, budgetTokens: { type: "number", description: "Approximate token budget (default 1024)" } },
-      required: ["repo"],
-    },
-  },
-  {
-    name: "hotspots",
-    description:
-      "Where does work concentrate? Files ranked by git churn × size (commits × log2 lines). High-scoring files are where changes and defects cluster.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, since: { type: "string", description: "Only count commits after this ref" } },
-      required: ["repo"],
-    },
-  },
-  {
-    name: "coupling",
-    description:
-      "Change coupling: pairs of files that repeatedly change in the same commits — hidden dependencies no import shows. strength 1.0 = every change to one touched the other.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, since: { type: "string", description: "Only mine commits after this ref" } },
-      required: ["repo"],
-    },
-  },
-  {
-    name: "replace_symbol_body",
-    description:
-      "WRITE: replace a symbol's whole declaration with `body` (verbatim, supply full indentation). The symbol is resolved by name path ('Class/method'); ambiguity errors list the candidates — qualify with `file`. Line spans come from the AST index.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...repoProp,
-        namePath: { type: "string" },
-        body: { type: "string" },
-        file: { type: "string", description: "Disambiguate: repo-relative file containing the symbol" },
-      },
-      required: ["repo", "namePath", "body"],
-    },
-  },
-  {
-    name: "insert_after_symbol",
-    description:
-      "WRITE: insert `body` after a symbol's declaration (blank-line separation preserved for definition-like kinds). Resolved like replace_symbol_body.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, namePath: { type: "string" }, body: { type: "string" }, file: { type: "string" } },
-      required: ["repo", "namePath", "body"],
-    },
-  },
-  {
-    name: "insert_before_symbol",
-    description:
-      "WRITE: insert `body` before a symbol's declaration (blank-line separation preserved). Resolved like replace_symbol_body.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, namePath: { type: "string" }, body: { type: "string" }, file: { type: "string" } },
-      required: ["repo", "namePath", "body"],
-    },
-  },
-  {
-    name: "write_memory",
-    description:
-      "Persist a named markdown note under <repo>/.codeindex/memories/ (names may use topic/name form). Write small, focused notes: project map, build commands, conventions.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, name: { type: "string" }, content: { type: "string" } },
-      required: ["repo", "name", "content"],
-    },
-  },
-  {
-    name: "read_memory",
-    description: "Read one persisted memory by name.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, name: { type: "string" } },
-      required: ["repo", "name"],
-    },
-  },
-  {
-    name: "list_memories",
-    description: "List persisted memory names — load this first, then read individual memories on relevance.",
-    inputSchema: { type: "object", properties: { ...repoProp }, required: ["repo"] },
-  },
-  {
-    name: "delete_memory",
-    description: "Delete one persisted memory by name.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, name: { type: "string" } },
-      required: ["repo", "name"],
-    },
-  },
-  {
-    name: "dead_code",
-    description:
-      "Dead-code candidates in two labeled tiers: 'unreferenced' (no call site binds AND nothing references the name) and 'uncalled' (referenced somewhere — re-export, type position — but never called). Exported symbols only; test files and entrypoint-looking files excluded as roots.",
-    inputSchema: { type: "object", properties: { ...repoProp, ...scopeProps }, required: ["repo"] },
-  },
-  {
-    name: "complexity",
-    description:
-      "Cyclomatic-complexity estimates (branch-token counting over AST line spans), most-complex first. Pass `file` for one file's symbols, omit for the repo-wide top. Combine with hotspots: the `risk` field of this tool's sibling ranks complexity × churn.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, file: { type: "string" }, risk: { type: "boolean", description: "Return complexity × git-churn risk ranking instead" } },
-      required: ["repo"],
-    },
-  },
-  {
-    name: "mermaid",
-    description:
-      "Mermaid diagram of the module graph (renders inline in Claude/GitHub — no graph database). Optionally scoped to one module's neighborhood.",
-    inputSchema: {
-      type: "object",
-      properties: { ...repoProp, module: { type: "string", description: "Module slug to focus on" } },
-      required: ["repo"],
-    },
-  },
-  {
-    name: "grep",
-    description:
-      "Search file contents (ripgrep when available, deterministic JS fallback otherwise). Returns sorted (file, line, text) hits.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...repoProp,
-        pattern: { type: "string", description: "Regular expression to search for" },
-        globs: { type: "array", items: { type: "string" }, description: "Restrict to matching paths" },
-        ignoreCase: { type: "boolean" },
-        maxHits: { type: "number" },
-      },
-      required: ["repo", "pattern"],
-    },
-  },
-  {
-    name: "search",
-    description:
-      'Natural-language-ish lexical search: BM25 ranking (k1=1.2, b=0.75) over symbol names (camelCase/snake_case subtokens), file path segments, markdown headings and summary lines. NOT embeddings by default — deterministic, diacritic-folded, zero API keys. Answers "where is auth handled?"-style queries with ranked files, matched terms and top symbols. Query terms with zero document frequency get a deterministic trigram-fuzzy fallback (typo-tolerant) unless `fuzzy: false`. Set `semantic: true` to RRF-fuse an embedding tier (HTTP endpoint, else a local static model) with lexical — the response then wraps the ranked list as `{ results, tier, degradedReason? }`, `tier` being "endpoint"/"static" when fusion happened or "lexical" (with `degradedReason`) when it did not (see embed_status). Without `semantic`, the response is the bare ranked array, unchanged.',
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...repoProp,
-        ...scopeProps,
-        query: { type: "string", description: "Natural-language or identifier query" },
-        limit: { type: "number", description: "Max results (default 20)" },
-        fuzzy: {
-          type: "boolean",
-          description:
-            "Trigram fuzzy fallback for query terms with zero document frequency (default true)",
-        },
-        semantic: {
-          type: "boolean",
-          description:
-            'RRF-fuse an embedding tier with lexical (default false). Precedence: the HTTP endpoint (CODEINDEX_EMBED_ENDPOINT) if set, else a local static model. The response reports the effective tier as a top-level `tier` field ("endpoint"/"static" on success, "lexical" plus `degradedReason` when neither is available/reachable) instead of degrading silently — see embed_status.',
-        },
-      },
-      required: ["repo", "query"],
-    },
-  },
-  {
-    name: "embed_status",
-    description:
-      "Report the embedding tier: the effective mode (none/static/endpoint; endpoint > static model), the resolved model (opt-in, never shipped in the package) with its modelId/dim, EMBED_VERSION, and the configured HTTP endpoint with its reachability. Use to check whether `search` with semantic:true will fuse embeddings or degrade to lexical.",
-    inputSchema: { type: "object", properties: { ...repoProp }, required: ["repo"] },
-  },
-  {
-    name: "check_rules",
-    description:
-      'Validate dependency-cruiser-style architecture rules against the link-graph. Rules (inline JSON array): forbidden edges {name, from, to, kind?, severity?, comment?} with glob paths, plus builtins {name, builtin: "cycles"|"orphans"} (module-level import cycles; edge-less code files). Returns deterministic violations with severity error|warn — a CI gate.',
-    inputSchema: {
-      type: "object",
-      properties: {
-        ...repoProp,
-        ...scopeProps,
-        rules: { type: "array", description: "Rules array (inline JSON — see description)" },
-      },
-      required: ["repo", "rules"],
-    },
-  },
-] as const;
-
 function str(v: unknown): string | undefined {
   return typeof v === "string" && v ? v : undefined;
 }
 function strArray(v: unknown): string[] | undefined {
   return Array.isArray(v) && v.every((x) => typeof x === "string") && v.length ? (v as string[]) : undefined;
 }
+// A positive numeric argument. Also accepts the numeric STRING a JSON-Schema-less
+// client may send: `"50"` used to fall through to the default in silence, which
+// reads to the caller as the option being ignored.
+function num(v: unknown): number | undefined {
+  const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
 function errMessage(e: unknown): string {
   return e instanceof Error ? e.message : String(e);
 }
 
-// --- embedding index memoization --------------------------------------------
-// The MCP server process is long-lived, but every `search` call used to redo
-// the FULL corpus embedding build — N `buildEndpointIndex` HTTP round-trips,
-// or a full `buildEmbeddingIndex` re-encode pass — even when nothing in the
-// repo changed between requests. Memoize the last build behind a fingerprint
-// of the scan contents plus the tier's identity, so an unchanged repo reuses
-// the cached index and any file add/edit/remove (or a switch of endpoint/model)
-// still rebuilds. RepoScan carries no fingerprint of its own (checked
-// scan.ts/types.ts) — every FileRecord already carries a content hash, so
-// hashing the (rel, hash) pairs is the staleness oracle scan.ts itself uses.
-export function scanFingerprint(scan: RepoScan): string {
-  return sha1(scan.files.map((f) => `${f.rel}:${f.hash}`).join("\n"));
-}
-
-export interface EmbeddingIndexCacheKey {
-  mode: "endpoint" | "static";
-  // Distinguishes cache entries across configs sharing the same scan: the
-  // endpoint URL, or the model dir + modelId for the static tier.
-  identity: string;
-  scan: RepoScan;
-}
-
-// A SINGLE entry — never an unbounded map — holding the most recent build.
-let embeddingIndexCache: { key: string; index: EmbeddingIndex } | undefined;
-
-// Reuse the cached index when (mode, identity, scanFingerprint) matches the
-// last build; otherwise call `build` and cache its result. A failed build is
-// NEVER cached (matches today's per-call error behavior: the next request
-// retries from scratch, and a still-valid previous entry — under a different
-// key — is left untouched).
-export async function memoizedEmbeddingIndex(
-  key: EmbeddingIndexCacheKey,
-  build: () => Promise<EmbeddingIndex> | EmbeddingIndex,
-): Promise<EmbeddingIndex> {
-  const cacheKey = `${key.mode}:${key.identity}:${scanFingerprint(key.scan)}`;
-  if (embeddingIndexCache && embeddingIndexCache.key === cacheKey) return embeddingIndexCache.index;
-  const index = await build();
-  embeddingIndexCache = { key: cacheKey, index };
-  return index;
-}
-
-// A SINGLE entry — never an unbounded map — holding the most recent parse.
-let embedModelCache: { key: string; model: StaticEmbedModel } | undefined;
-
-// model.json is 10-30 MB with the real asset; reading + JSON.parsing it on
-// EVERY request dominates static-tier latency, so the parsed model is memoized
-// across requests. One statSync per request keys the cache on
-// (dir, mtimeMs, size) so an in-place re-pull invalidates on the next call.
-// Same discipline as memoizedEmbeddingIndex: a failed load is NEVER cached —
-// the throw propagates and the cache is left as it was, so the next request
-// retries from scratch. A missing model.json returns undefined (the
-// not-present case, exactly like loadEmbedModel).
-export function memoizedEmbedModel(modelDir: string): StaticEmbedModel | undefined {
-  let stat;
-  try {
-    stat = statSync(join(modelDir, "model.json"));
-  } catch {
-    return undefined;
-  }
-  const key = `${modelDir}:${stat.mtimeMs}:${stat.size}`;
-  if (embedModelCache && embedModelCache.key === key) return embedModelCache.model;
-  const model = loadEmbedModel(modelDir);
-  if (model) embedModelCache = { key, model };
-  return model;
-}
-
-// --- session-level scan + artifacts memoization ------------------------------
-// Same single-entry discipline as the embedding caches above: the MCP server
-// process is long-lived, but every tool call used to redo a FULL scanRepo walk
-// + read + hash + extraction pass (and, for graph-shaped tools, the whole
-// pipeline) even when nothing in the repo changed between requests. Cache the
-// last (repo, scan-opts) scan and feed its records back to scanRepo as `cache`
-// on the next call — scan.ts's EXISTING stat-fastpath + exact-hash machinery
-// is the freshness oracle, so a cache hit costs one walk + per-file stats, not
-// reads. When the oracle proves the content unchanged the SAME RepoScan object
-// is returned, which keeps the per-scan WeakMap of derived structures
-// (src/derived.ts) warm across requests. Artifacts are memoized on scan object
-// identity. Rendered strings are NEVER memoized — a big repo's graph.json runs
-// tens of MB, so renders stay per-call while the expensive structures behind
-// them are reused.
-//
-// Determinism: reused records come from scan.ts's own reuse paths (stat
-// fastpath / exact content-hash match), which produce records value-identical
-// to a from-scratch scan — artifacts stay byte-identical; only repeated work
-// disappears.
-
-// The scan options a session entry is keyed on. `cache`/`precomputedWalk` are
-// excluded from the contract: the session cache OWNS the cache it feeds back,
-// and a caller-supplied stale walk would desynchronize the freshness oracle.
-export type SessionScanOptions = Omit<ScanOptions, "cache" | "precomputedWalk">;
-
-type SessionCacheEntry = { hash: string; record: FileRecord; size?: number; mtimeMs?: number };
-type SessionCacheMap = Map<string, SessionCacheEntry>;
-
-// A SINGLE entry — never an unbounded map — holding the most recent scan.
-let sessionCache:
-  | { key: string; scan: RepoScan; cacheMap: SessionCacheMap; arts?: IndexArtifacts }
-  | undefined;
-
-// Fixed property order (and JSON.stringify dropping undefined) keeps the key
-// deterministic regardless of how the caller assembled the options object.
-function sessionKey(repo: string, opts: SessionScanOptions): string {
-  return (
-    repo +
-    "\0" +
-    JSON.stringify({
-      scope: opts.scope,
-      include: opts.include,
-      exclude: opts.exclude,
-      gitignore: opts.gitignore,
-      ignoreDirs: opts.ignoreDirs,
-      maxBytes: opts.maxBytes,
-      maxFiles: opts.maxFiles,
-      maxCallsPerFile: opts.maxCallsPerFile,
-      out: opts.out,
-      fullHash: opts.fullHash,
-    })
-  );
-}
-
-// A scan re-expressed as the `ScanOptions.cache` shape (the exact map the CLI
-// persists as cache.json): rel → (hash, record, size, mtimeMs), so the next
-// scanRepo can take the stat fastpath / hash-match reuse paths against it.
-// Exported for tests.
-export function toCacheMap(scan: RepoScan): SessionCacheMap {
-  const m: SessionCacheMap = new Map();
-  for (const f of scan.files) m.set(f.rel, { hash: f.hash, record: f, size: f.size, mtimeMs: scan.mtimes.get(f.rel) });
-  return m;
-}
-
-// --- persisted-index preload -------------------------------------------------
-// On the FIRST tool call for a repo, a committed .codeindex/ index (written by
-// `codeindex index`) lets the session skip work TWO ways. cache.json seeds the
-// session scan, so every unchanged file takes scan.ts's stat fastpath instead
-// of a read + hash + extraction; and — only when the T4 freshness guard holds —
-// the persisted graph.json/symbols.json are deserialized straight into the
-// session, so the first graph/symbols/mermaid/repo_map/check_rules call skips
-// the whole downstream pipeline (buildArtifactsFromScan). Both are pure
-// optimizations: the seeded scan's reused records are value-identical to a cold
-// scan's (T3/T4 determinism), and the guard is the SAME oracle the CLI's index
-// fastpath uses to prove the on-disk artifacts equal a fresh build here. Absent,
-// stale, corrupt, or any version/commit/sha mismatch → every step falls back to
-// today's cold path EXACTLY (a fresh scanRepo / buildArtifactsFromScan), never a
-// throw.
-
-// ADDITIVE cache.json meta describing the artifacts a prior `index` run wrote
-// (see engine-cli.ts's CacheMeta). Old caches lacking these keys simply never
-// pass the guard below — their per-file records are still reused to seed the
-// scan. Only the graph/symbols shas matter here; the embed sidecar has its own
-// memoization path.
-interface PersistedMeta {
-  engineVersion?: string;
-  commit?: string;
-  graphSha1?: string;
-  symbolsSha1?: string;
-}
-
-// Read <repo>/.codeindex/cache.json into the (cacheMap, meta) the preload needs.
-// Per-file records are reusable ONLY when (schemaVersion, extractorVersion)
-// match this engine — the exact gate the CLI applies before trusting a cache —
-// otherwise the whole cache is discarded (cold scan). Any read/parse failure (no
-// index yet, unreadable, malformed) returns undefined: the cold path.
-function readPersistedIndex(repo: string): { cacheMap: SessionCacheMap; meta: PersistedMeta } | undefined {
-  let parsed:
-    | ({ schemaVersion?: number; extractorVersion?: number; files?: Record<string, SessionCacheEntry> } & PersistedMeta)
-    | undefined;
-  try {
-    parsed = JSON.parse(readFileSync(join(repo, ".codeindex", "cache.json"), "utf8")) as typeof parsed;
-  } catch {
-    return undefined;
-  }
-  if (!parsed || parsed.schemaVersion !== SCHEMA_VERSION || parsed.extractorVersion !== EXTRACTOR_VERSION || !parsed.files) {
-    return undefined;
-  }
-  const cacheMap: SessionCacheMap = new Map(Object.entries(parsed.files));
-  const meta: PersistedMeta = {
-    engineVersion: parsed.engineVersion,
-    commit: parsed.commit,
-    graphSha1: parsed.graphSha1,
-    symbolsSha1: parsed.symbolsSha1,
-  };
-  return { cacheMap, meta };
-}
-
-// The T4 freshness guard, applied to a session scan seeded from cache.json:
-// contentUnchanged proves this scan's records are the ones that built the
-// on-disk artifacts; engineVersion pins the version stamp graph.json embeds and
-// commit the HEAD it embeds; the sha checks prove the on-disk bytes ARE that
-// build's output. All true ⇒ graph.json/symbols.json are byte-equal to
-// buildArtifactsFromScan(scan) run here, so deserialize them instead of
-// rebuilding. Graph/SymbolIndex are pure JSON POJOs (no Map/Set/typed fields),
-// so JSON.parse is a lossless round-trip — a schemaVersion assert is the only
-// reconstruction needed (see the round-trip test). ANY failure — a stale scan,
-// a version/commit/sha mismatch, a missing/corrupt/partial artifact, an
-// unexpected schemaVersion — returns undefined so the caller rebuilds. NEVER
-// throws (a corrupt artifact must degrade, not crash the session).
-function preloadArtifacts(repo: string, scan: RepoScan, meta: PersistedMeta): IndexArtifacts | undefined {
-  if (
-    !scan.contentUnchanged ||
-    meta.engineVersion !== ENGINE_VERSION ||
-    meta.commit !== scan.commit ||
-    meta.graphSha1 === undefined ||
-    meta.symbolsSha1 === undefined
-  ) {
-    return undefined;
-  }
-  const dir = join(repo, ".codeindex");
-  let graphBytes: Buffer;
-  let symbolsBytes: Buffer;
-  try {
-    graphBytes = readFileSync(join(dir, "graph.json"));
-    symbolsBytes = readFileSync(join(dir, "symbols.json"));
-  } catch {
-    return undefined; // a sha'd artifact went missing since cache.json — rebuild
-  }
-  // sha over the raw bytes; sha1(string) hashes the same UTF-8 bytes writeFileSync
-  // put on disk, so this equals the meta sha the CLI computed over the render.
-  if (sha1(graphBytes) !== meta.graphSha1 || sha1(symbolsBytes) !== meta.symbolsSha1) {
-    return undefined; // tampered / partial / corrupt on-disk bytes — rebuild
-  }
-  try {
-    const graph = JSON.parse(graphBytes.toString("utf8")) as Graph;
-    const symbols = JSON.parse(symbolsBytes.toString("utf8")) as SymbolIndex;
-    if (graph.schemaVersion !== SCHEMA_VERSION || symbols.schemaVersion !== SCHEMA_VERSION) return undefined;
-    return { scan, graph, symbols };
-  } catch {
-    // Unreachable once the shas matched (the bytes are valid JSON this engine
-    // wrote), but the contract is "never throw" — degrade to a rebuild.
-    return undefined;
-  }
-}
-
-// First-touch preload: seed the session scan from cache.json and, when the guard
-// holds, the artifacts from graph.json/symbols.json. undefined ⇒ no persisted
-// index ⇒ the caller takes the cold scanRepo path unchanged.
-function preloadSession(
-  repo: string,
-  opts: SessionScanOptions,
-): { scan: RepoScan; cacheMap: SessionCacheMap; arts?: IndexArtifacts } | undefined {
-  const persisted = readPersistedIndex(repo);
-  if (!persisted) return undefined;
-  // Seed the scan from the persisted records — scan.ts's stat fastpath + exact
-  // content-hash reuse make this value-identical to a cold scan (T3/T4), only
-  // cheaper, and it computes the contentUnchanged the artifact guard reads. When
-  // the on-disk content drifted from cache.json, changed files are re-read/
-  // extracted here exactly as a cold scan would, so the scan stays correct and
-  // the guard simply fails (arts undefined → rebuild on demand).
-  const scan = scanRepo(repo, { ...opts, cache: persisted.cacheMap });
-  const arts = preloadArtifacts(repo, scan, persisted.meta);
-  return { scan, cacheMap: toCacheMap(scan), arts };
-}
-
-// The memoizing replacement for scanRepo inside callTool. Exported for tests.
-export function getScan(repo: string, opts: SessionScanOptions = {}): RepoScan {
-  const key = sessionKey(repo, opts);
-  if (sessionCache && sessionCache.key === key) {
-    const fresh = scanRepo(repo, { ...opts, cache: sessionCache.cacheMap });
-    if (fresh.contentUnchanged) {
-      // Content proven identical → return the SAME object (object identity is
-      // what keeps derived.ts's WeakMap and the memoized artifacts warm). A
-      // stat-only drift (e.g. a bare touch) still refreshes the cache map so
-      // the next call's stat fastpath keys on the new (size, mtimeMs).
-      if (fresh.cacheDirty) sessionCache.cacheMap = toCacheMap(fresh);
-      // `commit` (headCommit(root)) is NOT part of the stat/hash freshness
-      // oracle: a git HEAD move that leaves the worktree untouched — commit /
-      // commit --amend / reset --soft / checkout to an identical-tree branch —
-      // changes headCommit without altering any file's size or mtime, so
-      // contentUnchanged stays true while the cached scan's commit went stale.
-      // `fresh` recomputed it just now (exactly what a cold process reports), so
-      // sync it onto the returned object; otherwise scan_summary would emit the
-      // OLD commit a from-scratch scanRepo never would. Mutate the SAME object
-      // rather than clone — cloning would forfeit the identity the artifacts and
-      // derived.ts WeakMap key on. Safe: no artifact carries commit (graph /
-      // symbols render byte-identically regardless), so nothing memoized here
-      // depends on this field.
-      if (sessionCache.scan.commit !== fresh.commit) sessionCache.scan.commit = fresh.commit;
-      return sessionCache.scan;
-    }
-    sessionCache = { key, scan: fresh, cacheMap: toCacheMap(fresh) };
-    return fresh;
-  }
-  // First touch of this (repo, opts): try the persisted-index preload before a
-  // cold scan. A present, version-compatible .codeindex/cache.json seeds the
-  // scan (and, when the guard holds, the artifacts); absent it, fall through to
-  // the cold path EXACTLY as before.
-  const preloaded = preloadSession(repo, opts);
-  if (preloaded) {
-    sessionCache = { key, scan: preloaded.scan, cacheMap: preloaded.cacheMap, arts: preloaded.arts };
-    return preloaded.scan;
-  }
-  const scan = scanRepo(repo, opts);
-  sessionCache = { key, scan, cacheMap: toCacheMap(scan) };
-  return scan;
-}
-
-// Lazy pipeline memoized on scan OBJECT IDENTITY: graph-shaped tools reuse the
-// artifacts exactly as long as getScan keeps returning the same scan object.
-// Exported for tests.
-export function getArtifacts(repo: string, opts: SessionScanOptions = {}): IndexArtifacts {
-  const scan = getScan(repo, opts);
-  if (sessionCache && sessionCache.scan === scan) {
-    return (sessionCache.arts ??= buildArtifactsFromScan(scan, opts));
-  }
-  // Defensive fallback (getScan always leaves sessionCache holding `scan`).
-  return buildArtifactsFromScan(scan, opts);
-}
-
-// Warm the grammars for the languages CURRENTLY present in `repo`, re-derived on
-// EVERY scan-needing call — never frozen on first touch. The server no longer
-// warms every committed grammar at startup; most sessions touch one repo and a
-// handful of languages, so each scan-needing tool warms the walk-derived set
-// itself. It MUST re-derive per call because the session cache (getScan) is built
-// to pick up mid-session file adds/edits/removes: a language whose first file
-// appears only AFTER the initial scan-needing call must still get its grammar
-// warmed, or that file falls to the regex tier and its symbols diverge from a
-// cold build on the identical on-disk state — a byte-identity break. (A per-
-// repo-path memo froze the grammar set at first touch and silently missed
-// exactly this case.) ensureGrammars is idempotent and near-free once a grammar
-// is loaded — it warms only newly-seen keys — so the sole repeated cost is the
-// walk; the wasm for a given language loads at most once. Determinism: the walk's
-// extension set is a superset of what scanRepo keeps (scope/include/exclude only
-// filter further), so every extracted file has its grammar loaded; Language.load
-// calls are independent, so warming fewer grammars cannot alter the parse of a
-// loaded one.
-export async function warmGrammarsForRepo(repo: string): Promise<void> {
-  const { files } = walk(repo, {});
-  await ensureGrammars(grammarKeysForExts(files.map((f) => f.ext)));
-}
-
 // Tools that never scan the file tree (git/grep/memory/embed-status only) — they
 // must not trigger a grammar warm. Every other tool is scan-needing and warms
 // the repo's grammars first; defaulting to "warm" keeps a newly added scan tool
@@ -665,6 +115,10 @@ const SCANLESS_TOOLS = new Set([
   "workspaces", "churn", "coupling", "grep",
   "write_memory", "read_memory", "list_memories", "delete_memory",
   "embed_status",
+  // scan_summary counts and classifies by path only — it never parses, so the
+  // grammar warm (a whole extra walk) would be pure overhead. When a scan is
+  // already cached getScanSummary reuses it, warm grammars included.
+  "scan_summary",
 ]);
 
 async function callTool(name: string, args: Record<string, unknown>, defaultRepo?: string): Promise<string> {
@@ -676,21 +130,26 @@ async function callTool(name: string, args: Record<string, unknown>, defaultRepo
   const scanOpts = { scope: str(args.scope), include: strArray(args.include), exclude: strArray(args.exclude) };
   // Scan-needing tools warm the present-language grammars (re-derived per call)
   // before any scan so extraction takes the AST tier; scan-less tools skip it.
-  if (!SCANLESS_TOOLS.has(name)) await warmGrammarsForRepo(repo);
+  // ONE walk feeds both the warm and the scan below — see warmGrammarsForWalk.
+  let walked: WalkResult | undefined;
+  if (!SCANLESS_TOOLS.has(name)) {
+    walked = walk(repo, {});
+    await warmGrammarsForWalk(walked);
+  }
 
   if (name === "scan_summary") {
-    const scan = getScan(repo, scanOpts);
+    const s = getScanSummary(repo, scanOpts, walked);
     return JSON.stringify(
-      { engineVersion: ENGINE_VERSION, commit: scan.commit, fileCount: scan.files.length, languages: scan.languages, capped: scan.capped },
+      { engineVersion: ENGINE_VERSION, commit: s.commit, fileCount: s.fileCount, languages: s.languages, capped: s.capped },
       null,
       2,
     );
   }
   if (name === "graph") {
-    return renderGraphJson(getArtifacts(repo, scanOpts).graph);
+    return renderGraphJson(getArtifacts(repo, scanOpts, walked).graph);
   }
   if (name === "symbols") {
-    const { symbols } = getArtifacts(repo, scanOpts);
+    const { symbols } = getArtifacts(repo, scanOpts, walked);
     const lookup = str(args.name);
     if (lookup) {
       return JSON.stringify({ name: lookup, defs: symbols.defs[lookup] ?? [], refs: symbols.refs[lookup] ?? [] }, null, 2);
@@ -698,7 +157,13 @@ async function callTool(name: string, args: Record<string, unknown>, defaultRepo
     return JSON.stringify(symbols, null, 2);
   }
   if (name === "callers") {
-    const index = buildCallerIndex(getScan(repo, scanOpts));
+    // callerIndexFor, not buildCallerIndex: the public builder is unmemoized, so
+    // this rebuilt the whole index on EVERY request (318ms per call on a 20k-file
+    // repo in the project's own benchmark). The memoized one is keyed on scan
+    // object identity, which the session cache preserves across calls.
+    // Recall mode is option-dependent, so it cannot use the memoized index.
+    const scan = getScan(repo, scanOpts, walked);
+    const index = args.recall === true ? buildCallerIndex(scan, undefined, { recall: true }) : callerIndexFor(scan);
     const lookup = str(args.name);
     if (lookup) {
       const entry = index.get(lookup);
@@ -721,27 +186,28 @@ async function callTool(name: string, args: Record<string, unknown>, defaultRepo
   if (name === "symbols_overview") {
     const file = str(args.file);
     if (!file) throw new Error("`file` is required");
-    return JSON.stringify(symbolsOverview(getScan(repo, scanOpts), file), null, 2);
+    return JSON.stringify(symbolsOverview(getScan(repo, scanOpts, walked), file), null, 2);
   }
   if (name === "find_symbol") {
     const namePath = str(args.namePath);
     if (!namePath) throw new Error("`namePath` is required");
-    const matches = findSymbol(getScan(repo, scanOpts), namePath, {
+    const matches = findSymbol(getScan(repo, scanOpts, walked), namePath, {
       substring: args.substring === true,
       includeBody: args.includeBody === true,
+      maxResults: num(args.maxResults),
     });
     return JSON.stringify(matches, null, 2);
   }
   if (name === "find_references") {
     const symName = str(args.name);
     if (!symName) throw new Error("`name` is required");
-    return JSON.stringify(findReferences(getScan(repo, scanOpts), symName), null, 2);
+    return JSON.stringify(findReferences(getScan(repo, scanOpts, walked), symName), null, 2);
   }
   if (name === "replace_symbol_body" || name === "insert_after_symbol" || name === "insert_before_symbol") {
     const namePath = str(args.namePath);
     const body = typeof args.body === "string" ? args.body : undefined;
     if (!namePath || body === undefined) throw new Error("`namePath` and `body` are required");
-    const scan = getScan(repo, scanOpts);
+    const scan = getScan(repo, scanOpts, walked);
     const fn = name === "replace_symbol_body" ? replaceSymbolBody : name === "insert_after_symbol" ? insertAfterSymbol : insertBeforeSymbol;
     const result = fn(scan, namePath, body, str(args.file));
     // A write WE just performed must not be trusted to the stat oracle: an
@@ -750,7 +216,7 @@ async function callTool(name: string, args: Record<string, unknown>, defaultRepo
     // session entry unconditionally — the next call rescans from scratch.
     // (write_memory needs no invalidation: .codeindex/ is excluded from the
     // walk, so memories never enter a scan.)
-    sessionCache = undefined;
+    sessionClear();
     return JSON.stringify(result, null, 2);
   }
   if (name === "write_memory") {
@@ -775,26 +241,31 @@ async function callTool(name: string, args: Record<string, unknown>, defaultRepo
     return JSON.stringify({ deleted: deleteMemory(repo, memName) }, null, 2);
   }
   if (name === "dead_code") {
-    return JSON.stringify(findDeadCode(getScan(repo, scanOpts)), null, 2);
+    const all = findDeadCode(getScan(repo, scanOpts, walked));
+    const limit = num(args.limit);
+    // Additive: without `limit` the payload is exactly what it always was.
+    if (limit === undefined || all.length <= limit) return JSON.stringify(all, null, 2);
+    return JSON.stringify({ total: all.length, shown: limit, truncated: true, candidates: all.slice(0, limit) }, null, 2);
   }
   if (name === "complexity") {
-    const scan = getScan(repo, scanOpts);
+    const scan = getScan(repo, scanOpts, walked);
     if (args.risk === true) {
-      const { churn, ok } = gitChurn(repo);
-      return JSON.stringify({ churnOk: ok, risks: riskHotspots(scan, churn) }, null, 2);
+      // `since` was accepted by the CLI's `risk` but silently dropped here.
+      const { churn, ok } = gitChurn(repo, { since: str(args.since) });
+      return JSON.stringify({ churnOk: ok, risks: riskHotspots(scan, churn, num(args.top)) }, null, 2);
     }
-    return JSON.stringify(symbolComplexity(scan, str(args.file)), null, 2);
+    return JSON.stringify(symbolComplexity(scan, str(args.file), num(args.top)), null, 2);
   }
   if (name === "mermaid") {
-    const { graph } = getArtifacts(repo, scanOpts);
-    return renderMermaid(graph, { module: str(args.module) });
+    const { graph } = getArtifacts(repo, scanOpts, walked);
+    return renderMermaid(graph, { module: str(args.module), maxEdges: num(args.maxEdges) });
   }
   if (name === "repo_map") {
-    const { scan, graph } = getArtifacts(repo, scanOpts);
+    const { scan, graph } = getArtifacts(repo, scanOpts, walked);
     return renderRepoMap(scan, graph, { budgetTokens: typeof args.budgetTokens === "number" ? args.budgetTokens : undefined });
   }
   if (name === "hotspots") {
-    const scan = getScan(repo, scanOpts);
+    const scan = getScan(repo, scanOpts, walked);
     const { churn, ok } = gitChurn(repo, { since: str(args.since) });
     return JSON.stringify({ churnOk: ok, hotspots: rankHotspots(scan, churn) }, null, 2);
   }
@@ -805,8 +276,12 @@ async function callTool(name: string, args: Record<string, unknown>, defaultRepo
   if (name === "grep") {
     const pattern = str(args.pattern);
     if (!pattern) throw new Error("`pattern` is required");
+    // `scope` was CLI-only: the a205c34 fix folded it into the CLI's glob list
+    // but this handler ignored scanOpts entirely.
+    const scope = str(args.scope);
+    const globs = strArray(args.globs);
     const hits = grepRepo(repo, pattern, {
-      globs: strArray(args.globs),
+      globs: scope ? [...(globs ?? []), `${scope.replace(/\/+$/, "")}/**`] : globs,
       ignoreCase: args.ignoreCase === true,
       maxHits: typeof args.maxHits === "number" ? args.maxHits : undefined,
     });
@@ -815,7 +290,7 @@ async function callTool(name: string, args: Record<string, unknown>, defaultRepo
   if (name === "search") {
     const query = str(args.query);
     if (!query) throw new Error("`query` is required");
-    const scan = getScan(repo, scanOpts);
+    const scan = getScan(repo, scanOpts, walked);
     const limit = typeof args.limit === "number" ? args.limit : undefined;
     const fuzzy = typeof args.fuzzy === "boolean" ? args.fuzzy : undefined;
     if (args.semantic === true) {
@@ -882,33 +357,27 @@ async function callTool(name: string, args: Record<string, unknown>, defaultRepo
     return JSON.stringify(status, null, 2);
   }
   if (name === "check_rules") {
-    const rules = parseRules(args.rules); // throws a descriptive error on a malformed payload
-    const { graph } = getArtifacts(repo, scanOpts);
+    // Inline `rules` stays the primary form; `configPath` is the CLI's --config,
+    // which had no MCP equivalent, so a repo with a committed rules file had to
+    // have it re-pasted into every call.
+    const configPath = str(args.configPath);
+    let payload: unknown = args.rules;
+    if (payload === undefined && configPath) {
+      const abs = isAbsolute(configPath) ? configPath : join(repo, configPath);
+      try {
+        payload = JSON.parse(readFileSync(abs, "utf8"));
+      } catch (e) {
+        throw new Error(`cannot read rules from ${abs}: ${errMessage(e)}`);
+      }
+    }
+    if (payload === undefined) throw new Error("`rules` (or `configPath`) is required");
+    const rules = parseRules(payload); // throws a descriptive error on a malformed payload
+    const { graph } = getArtifacts(repo, scanOpts, walked);
     return JSON.stringify(checkRules(graph, rules), null, 2);
   }
   throw new Error(`unknown tool: ${name}`);
 }
 
-// The advertised tool list. Without a server-level repo pin this is TOOLS
-// verbatim (byte-compat for existing consumers). With one, every tool drops
-// `repo` from its `required` set and documents the default — so a client that
-// omits it is spec-correct rather than relying on the server being lenient.
-// The pin is reflected in the schema, not just honoured at call time.
-function toolsFor(defaultRepo?: string): readonly unknown[] {
-  if (!defaultRepo) return TOOLS;
-  return TOOLS.map((t) => ({
-    ...t,
-    inputSchema: {
-      ...t.inputSchema,
-      properties: {
-        ...t.inputSchema.properties,
-        repo: { type: "string", description: `Absolute path to the repository root (optional — defaults to ${defaultRepo})` },
-      },
-      required: (t.inputSchema.required as readonly string[]).filter((r) => r !== "repo"),
-    },
-  }));
-}
-
 export interface McpServerOptions {
   // Override the serverInfo announced in the initialize response — for
   // downstream consumers embedding this server under their own identity.
@@ -919,6 +388,9 @@ export interface McpServerOptions {
   // spawn one server per workspace — `codeindex mcp --repo <dir>` — instead of
   // requiring the agent to thread an absolute path through every single call.
   defaultRepo?: string;
+  // Cap on a single tool response, in bytes (default DEFAULT_MAX_RESPONSE_BYTES).
+  // Responses under it are untouched; see capResponse for what happens above it.
+  maxResponseBytes?: number;
 }
 
 export async function runMcpServer(opts: McpServerOptions = {}): Promise<void> {
@@ -926,8 +398,13 @@ export async function runMcpServer(opts: McpServerOptions = {}): Promise<void> {
     name: opts.serverInfo?.name ?? "codeindex",
     version: opts.serverInfo?.version ?? ENGINE_VERSION,
   };
-  // Derived ONCE: the pin cannot change mid-session, so neither can the list.
-  const tools = toolsFor(opts.defaultRepo);
+  // The negotiated protocol version, settled by `initialize` and fixed for the
+  // session. Until a client says otherwise we assume the oldest revision, so a
+  // client that skips the handshake sees exactly the pre-negotiation server.
+  let protocolVersion: string = PROTOCOL_VERSIONS[0];
+  // Rebuilt when negotiation lands: the pin cannot change mid-session, but the
+  // fields we are allowed to advertise depend on the version.
+  let tools = toolsFor(opts.defaultRepo, protocolVersion);
   // No startup warm: each scan-needing tool warms the present-language grammars
   // for its repo before it runs (warmGrammarsForRepo re-derives them per call),
   // so a session that never scans — or only touches one language — loads no
@@ -959,10 +436,12 @@ export async function runMcpServer(opts: McpServerOptions = {}): Promise<void> {
 
     try {
       if (req.method === "initialize") {
+        protocolVersion = negotiateProtocol(req.params?.protocolVersion);
+        tools = toolsFor(opts.defaultRepo, protocolVersion);
         send({
           id: req.id,
           result: {
-            protocolVersion: "2024-11-05",
+            protocolVersion,
             capabilities: { tools: {} },
             serverInfo,
           },
@@ -976,8 +455,37 @@ export async function runMcpServer(opts: McpServerOptions = {}): Promise<void> {
         const name = str(params.name) ?? "";
         const args = (params.arguments ?? {}) as Record<string, unknown>;
         try {
-          const text = await callTool(name, args, opts.defaultRepo);
-          send({ id: req.id, result: { content: [{ type: "text", text }] } });
+          const decl = (tools as { name: string; inputSchema: { properties?: Record<string, unknown> } }[]).find(
+            (t) => t.name === name,
+          );
+          const invalid = decl ? validateArgs(decl.inputSchema, args) : undefined;
+          if (invalid) throw new Error(invalid);
+          const raw = await callTool(name, args, opts.defaultRepo);
+          const repo = str(args.repo) ?? opts.defaultRepo ?? "";
+          const text = capResponse(raw, name, repo, opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES);
+          // A capped whole-repo response points at an artifact already on disk.
+          // From 2025-06-18 the protocol has a content type that says exactly
+          // that, so the client can fetch the bytes instead of re-asking.
+          //
+          // Gated on `text !== raw` — i.e. capResponse actually replaced the
+          // payload. Otherwise a normal 900 KB graph would be JSON.parsed on
+          // every single call just to discover it was not truncated.
+          const capped = text !== raw;
+          const link = capped && protocolVersion >= RICH_TOOLS_SINCE ? resourceLinkFor(text, name) : undefined;
+          // Typed, validatable result alongside the text block — for the tools
+          // that declare an outputSchema, and never when the guard replaced the
+          // payload (see structuredContentFor).
+          const structured =
+            protocolVersion >= RICH_TOOLS_SINCE
+              ? structuredContentFor(text, capped, OUTPUT_SCHEMAS[name] !== undefined)
+              : undefined;
+          send({
+            id: req.id,
+            result: {
+              content: link ? [{ type: "text", text }, link] : [{ type: "text", text }],
+              ...(structured ? { structuredContent: structured } : {}),
+            },
+          });
         } catch (e) {
           send({
             id: req.id,