@optave/codegraph 3.9.5 → 3.10.0

package/src/domain/graph/builder/stages/insert-nodes.ts

@@ -12,10 +12,12 @@ import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { bulkNodeIdsByFile } from '../../../../db/index.js';
 import { debug } from '../../../../infrastructure/logger.js';
+import { normalizePath } from '../../../../shared/constants.js';
 import { toErrorMessage } from '../../../../shared/errors.js';
 import type {
   BetterSqlite3Database,
   ExtractorOutput,
+  FileToParse,
   MetadataUpdate,
   SqliteStatement,
 } from '../../../../types.js';
@@ -90,16 +92,30 @@ function marshalSymbolBatches(allSymbols: Map<string, ExtractorOutput>): InsertN
   return batches;
 }
 
-/** Build file hash entries from parsed symbols and precomputed/metadata sources. */
-function buildFileHashes(
-  allSymbols: Map<string, ExtractorOutput>,
+/**
+ * Build file hash entries for every collected file, including those that
+ * produced zero symbols (empty files, parsers that silently no-op'd, or
+ * optional-language extensions whose grammar wasn't installed). Iterating the
+ * symbol map instead would skip such files and leave them missing from
+ * `file_hashes`, which permanently breaks the JS-side fast-skip pre-flight on
+ * any subsequent no-op rebuild (#1068).
+ *
+ * Exported for unit testing.
+ */
+export function buildFileHashes(
+  filesToParse: FileToParse[],
   precomputedData: Map<string, PrecomputedFileData>,
   metadataUpdates: MetadataUpdate[],
   rootDir: string,
 ): Array<{ file: string; hash: string; mtime: number; size: number }> {
   const fileHashes: Array<{ file: string; hash: string; mtime: number; size: number }> = [];
+  const seen = new Set<string>();
+
+  for (const item of filesToParse) {
+    const relPath = item.relPath ?? normalizePath(path.relative(rootDir, item.file));
+    if (seen.has(relPath)) continue;
+    seen.add(relPath);
 
-  for (const [relPath] of allSymbols) {
     const precomputed = precomputedData.get(relPath);
     if (precomputed?._reverseDepOnly) {
       continue; // file unchanged, hash already correct
@@ -112,7 +128,7 @@ function buildFileHashes(
         size = precomputed.stat.size;
       } else {
         const rawStat = fileStat(path.join(rootDir, relPath));
-        mtime = rawStat ? Math.floor(rawStat.mtimeMs) : 0;
+        mtime = rawStat ? rawStat.mtime : 0;
         size = rawStat ? rawStat.size : 0;
       }
       fileHashes.push({ file: relPath, hash: precomputed.hash, mtime, size });
@@ -127,7 +143,7 @@ function buildFileHashes(
       }
       if (code !== null) {
         const stat = fileStat(absPath);
-        const mtime = stat ? Math.floor(stat.mtimeMs) : 0;
+        const mtime = stat ? stat.mtime : 0;
         const size = stat ? stat.size : 0;
         fileHashes.push({ file: relPath, hash: fileHash(code), mtime, size });
       }
@@ -136,7 +152,7 @@ function buildFileHashes(
 
   // Also include metadata-only updates (self-heal mtime/size without re-parse)
   for (const item of metadataUpdates) {
-    const mtime = item.stat ? Math.floor(item.stat.mtime) : 0;
+    const mtime = item.stat ? item.stat.mtime : 0;
     const size = item.stat ? item.stat.size : 0;
     fileHashes.push({ file: item.relPath, hash: item.hash, mtime, size });
   }
@@ -157,7 +173,7 @@ function tryNativeInsert(ctx: PipelineContext): boolean {
   for (const item of filesToParse) {
     if (item.relPath) precomputedData.set(item.relPath, item as PrecomputedFileData);
   }
-  const fileHashes = buildFileHashes(allSymbols, precomputedData, metadataUpdates, rootDir);
+  const fileHashes = buildFileHashes(filesToParse, precomputedData, metadataUpdates, rootDir);
 
   // In native-first mode (single rusqlite connection), no WAL dance is needed.
   // In dual-connection mode, checkpoint JS side before native write, then
@@ -321,7 +337,7 @@ function insertChildrenAndEdges(
 
 function updateFileHashes(
   _db: BetterSqlite3Database,
-  allSymbols: Map<string, ExtractorOutput>,
+  filesToParse: FileToParse[],
   precomputedData: Map<string, PrecomputedFileData>,
   metadataUpdates: MetadataUpdate[],
   rootDir: string,
@@ -329,7 +345,15 @@ function updateFileHashes(
 ): void {
   if (!upsertHash) return;
 
-  for (const [relPath] of allSymbols) {
+  // Iterate every collected file (#1068): files that produced zero symbols
+  // (empty, parser no-op, or grammar-missing optional language) still need a
+  // hash row, otherwise the next no-op rebuild's fast-skip pre-flight rejects.
+  const seen = new Set<string>();
+  for (const item of filesToParse) {
+    const relPath = item.relPath ?? normalizePath(path.relative(rootDir, item.file));
+    if (seen.has(relPath)) continue;
+    seen.add(relPath);
+
     const precomputed = precomputedData.get(relPath);
     if (precomputed?._reverseDepOnly) {
       // no-op: file unchanged, hash already correct
@@ -341,7 +365,7 @@ function updateFileHashes(
         size = precomputed.stat.size;
       } else {
         const rawStat = fileStat(path.join(rootDir, relPath));
-        mtime = rawStat ? Math.floor(rawStat.mtimeMs) : 0;
+        mtime = rawStat ? rawStat.mtime : 0;
         size = rawStat ? rawStat.size : 0;
       }
       upsertHash.run(relPath, precomputed.hash, mtime, size);
@@ -356,7 +380,7 @@ function updateFileHashes(
       }
       if (code !== null) {
         const stat = fileStat(absPath);
-        const mtime = stat ? Math.floor(stat.mtimeMs) : 0;
+        const mtime = stat ? stat.mtime : 0;
         const size = stat ? stat.size : 0;
         upsertHash.run(relPath, fileHash(code), mtime, size);
       }
@@ -365,7 +389,7 @@ function updateFileHashes(
 
   // Also update metadata-only entries (self-heal mtime/size without re-parse)
   for (const item of metadataUpdates) {
-    const mtime = item.stat ? Math.floor(item.stat.mtime) : 0;
+    const mtime = item.stat ? item.stat.mtime : 0;
     const size = item.stat ? item.stat.size : 0;
     upsertHash.run(item.relPath, item.hash, mtime, size);
   }
@@ -415,7 +439,7 @@ export async function insertNodes(ctx: PipelineContext): Promise<void> {
   const insertAll = ctx.db.transaction(() => {
     insertDefinitionsAndExports(ctx.db, allSymbols);
     insertChildrenAndEdges(ctx.db, allSymbols);
-    updateFileHashes(ctx.db, allSymbols, precomputedData, metadataUpdates, rootDir, upsertHash);
+    updateFileHashes(ctx.db, filesToParse, precomputedData, metadataUpdates, rootDir, upsertHash);
   });
 
   insertAll();

package/src/domain/parser.ts

@@ -316,16 +316,23 @@ export function getParser(parsers: Map<string, Parser | null>, filePath: string)
  *
  * Name is preserved for caller compatibility; the function now ensures
  * *analysis data* rather than *trees*.
+ *
+ * `needsFn` (optional): when provided, only files for which it returns true are
+ * re-parsed. Without it the function falls back to "any WASM-parseable file
+ * without _tree", which was the source of #1036 — a single file missing one
+ * analysis triggered a full-build re-parse of every WASM-parseable file.
  */
 export async function ensureWasmTrees(
   fileSymbols: Map<string, any>,
   rootDir: string,
+  needsFn?: (relPath: string, symbols: any) => boolean,
 ): Promise<void> {
   // Collect files that still need analysis data and are parseable by WASM.
   const pending: Array<{ relPath: string; absPath: string; symbols: any }> = [];
   for (const [relPath, symbols] of fileSymbols) {
     if (symbols._tree) continue; // legacy path — leave existing trees alone
     if (!_extToLang.has(path.extname(relPath).toLowerCase())) continue;
+    if (needsFn && !needsFn(relPath, symbols)) continue;
     pending.push({ relPath, absPath: path.join(rootDir, relPath), symbols });
   }
   if (pending.length === 0) return;
@@ -412,6 +419,128 @@ export function getInstalledWasmExtensions(): Set<string> {
   return exts;
 }
 
+/**
+ * Lowercase file extensions covered by the native Rust addon.
+ *
+ * Mirrors `LanguageKind::from_extension` in
+ * `crates/codegraph-core/src/parser_registry.rs`. Used to classify why the
+ * native orchestrator dropped a file: extensions outside this set are a
+ * legitimate parser limit (no Rust extractor exists), while extensions inside
+ * it indicate a real native bug (parse/read/extract failure).
+ *
+ * Keep this list in sync with the Rust enum — the native addon is a separate
+ * npm package, so JS has no runtime way to discover its language coverage.
+ */
+export const NATIVE_SUPPORTED_EXTENSIONS: ReadonlySet<string> = new Set([
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.tsx',
+  '.py',
+  '.pyi',
+  '.tf',
+  '.hcl',
+  '.go',
+  '.rs',
+  '.java',
+  '.cs',
+  '.rb',
+  '.rake',
+  '.gemspec',
+  '.php',
+  '.phtml',
+  '.c',
+  '.h',
+  '.cpp',
+  '.cc',
+  '.cxx',
+  '.hpp',
+  '.kt',
+  '.kts',
+  '.swift',
+  '.scala',
+  '.sh',
+  '.bash',
+  '.ex',
+  '.exs',
+  '.lua',
+  '.dart',
+  '.zig',
+  '.hs',
+  '.ml',
+  '.mli',
+]);
+
+/**
+ * Classification for a file the native orchestrator dropped.
+ * - `unsupported-by-native`: extension has no Rust extractor (legitimate parser limit).
+ * - `native-extractor-failure`: extension is supported by native but the file was
+ *   still dropped — points at a real bug (read error, parse failure, extractor crash).
+ */
+export type NativeDropReason = 'unsupported-by-native' | 'native-extractor-failure';
+
+export interface NativeDropClassification {
+  /** Per-reason → per-extension → list of relative paths that hit that bucket. */
+  byReason: Record<NativeDropReason, Map<string, string[]>>;
+  /** Total file count per reason. */
+  totals: Record<NativeDropReason, number>;
+}
+
+/**
+ * Group the missing files (relative paths) by drop reason and extension so the
+ * caller can log per-extension counts and a sample path. Pure function — no
+ * I/O, safe to unit-test independently of the build pipeline.
+ */
+export function classifyNativeDrops(relPaths: Iterable<string>): NativeDropClassification {
+  const byReason: Record<NativeDropReason, Map<string, string[]>> = {
+    'unsupported-by-native': new Map(),
+    'native-extractor-failure': new Map(),
+  };
+  const totals: Record<NativeDropReason, number> = {
+    'unsupported-by-native': 0,
+    'native-extractor-failure': 0,
+  };
+  for (const rel of relPaths) {
+    const ext = path.extname(rel).toLowerCase();
+    const reason: NativeDropReason = NATIVE_SUPPORTED_EXTENSIONS.has(ext)
+      ? 'native-extractor-failure'
+      : 'unsupported-by-native';
+    const bucket = byReason[reason];
+    let list = bucket.get(ext);
+    if (!list) {
+      list = [];
+      bucket.set(ext, list);
+    }
+    list.push(rel);
+    totals[reason]++;
+  }
+  return { byReason, totals };
+}
+
+/**
+ * Render `{ ext → paths[] }` as `ext (n: sample.ext, ...)` slices for log lines.
+ * Caps at 3 sample paths per extension and 6 extensions total to keep warnings
+ * readable when many languages are dropped at once. Extensions are sorted by
+ * descending file count so the loudest offender shows up first; ties keep
+ * insertion order. Pure function — safe to unit-test independently.
+ */
+export function formatDropExtensionSummary(buckets: Map<string, string[]>): string {
+  const MAX_EXTS = 6;
+  const MAX_SAMPLES = 3;
+  const entries = Array.from(buckets.entries()).sort((a, b) => b[1].length - a[1].length);
+  const shown = entries.slice(0, MAX_EXTS).map(([ext, paths]) => {
+    const sample = paths.slice(0, MAX_SAMPLES).join(', ');
+    const more = paths.length > MAX_SAMPLES ? `, +${paths.length - MAX_SAMPLES} more` : '';
+    return `${ext} (${paths.length}: ${sample}${more})`;
+  });
+  if (entries.length > MAX_EXTS) {
+    shown.push(`+${entries.length - MAX_EXTS} more extension(s)`);
+  }
+  return shown.join('; ');
+}
+
 // ── Unified API ──────────────────────────────────────────────────────────────
 
 function resolveEngine(opts: ParseEngineOpts = {}): ResolvedEngine {
@@ -938,6 +1067,71 @@ async function parseFilesWasm(
   return result;
 }
 
+/**
+ * Files at or below this count use the inline parse path (no worker spawn).
+ *
+ * Sized for typical engine-parity drops: a handful of fixture files in one
+ * or two languages (the recurring HCL case is 4 files). Above this, the
+ * worker-pool's IPC + crash-isolation cost (#965) is amortized over enough
+ * parse work to be worth paying; below it, the ~1–2s cold-start dominates.
+ */
+const INLINE_BACKFILL_THRESHOLD = 16;
+
+/**
+ * Inline WASM parse (no worker) for small file batches.
+ *
+ * Used by the engine-parity backfill path when the native engine drops a
+ * handful of files (typically test fixtures). The worker pool's per-call
+ * IPC + grammar-init overhead can cost 1–2s on slow CI runners — for a
+ * 4-file backfill, that dwarfs the ~10ms of actual parse work.
+ *
+ * Returns symbols with `_tree` set so `runAnalyses` can run AST/CFG/dataflow
+ * visitors via the unified walker (mirrors how WASM-engine results behaved
+ * before the worker pool was introduced).
+ */
+async function parseFilesWasmInline(
+  filePaths: string[],
+  rootDir: string,
+): Promise<Map<string, ExtractorOutput>> {
+  const result = new Map<string, ExtractorOutput>();
+  if (filePaths.length === 0) return result;
+  const parsers = await ensureParsersForFiles(filePaths);
+  for (const filePath of filePaths) {
+    if (!_extToLang.has(path.extname(filePath).toLowerCase())) continue;
+    let code: string;
+    try {
+      code = fs.readFileSync(filePath, 'utf-8');
+    } catch (err: unknown) {
+      warn(`Skipping ${path.relative(rootDir, filePath)}: ${(err as Error).message}`);
+      continue;
+    }
+    const extracted = wasmExtractSymbols(parsers, filePath, code);
+    if (!extracted) continue;
+    const relPath = path.relative(rootDir, filePath).split(path.sep).join('/');
+    const symbols = extracted.symbols as ExtractorOutput & { _tree?: unknown; _langId?: string };
+    symbols._tree = extracted.tree;
+    symbols._langId = extracted.langId;
+    result.set(relPath, symbols);
+  }
+  return result;
+}
+
+/**
+ * Backfill helper: small batches use the inline (main-thread) path; larger
+ * batches keep the worker-pool isolation against tree-sitter WASM crashes
+ * (#965). Threshold matches typical engine-parity drop sizes (a few fixture
+ * files in one or two languages).
+ */
+export async function parseFilesWasmForBackfill(
+  filePaths: string[],
+  rootDir: string,
+): Promise<Map<string, ExtractorOutput>> {
+  if (filePaths.length <= INLINE_BACKFILL_THRESHOLD) {
+    return parseFilesWasmInline(filePaths, rootDir);
+  }
+  return parseFilesWasm(filePaths, rootDir);
+}
+
 /**
  * Parse multiple files in bulk and return a Map<relPath, symbols>.
  */
@@ -988,7 +1182,7 @@ export async function parseFilesAuto(
   );
   if (dropped.length > 0) {
     warn(`Native engine dropped ${dropped.length} file(s); falling back to WASM for parity`);
-    const wasmResults = await parseFilesWasm(dropped, rootDir);
+    const wasmResults = await parseFilesWasmForBackfill(dropped, rootDir);
     for (const [relPath, symbols] of wasmResults) {
       result.set(relPath, symbols);
     }
@@ -1003,15 +1197,17 @@ export async function parseFilesAuto(
 export function getActiveEngine(opts: ParseEngineOpts = {}): {
   name: 'native' | 'wasm';
   version: string | null;
+  binaryVersion: string | null;
 } {
   const { name, native } = resolveEngine(opts);
-  let version: string | null = native
-    ? typeof native.engineVersion === 'function'
-      ? native.engineVersion()
-      : null
-    : null;
-  // Prefer platform package.json version over binary-embedded version
-  // to handle stale binaries that weren't recompiled during a release
+  const binaryVersion: string | null =
+    native && typeof native.engineVersion === 'function' ? native.engineVersion() : null;
+  // The display version prefers the platform package.json so the "Using native
+  // engine (vX)" log matches the npm release the user installed. The Rust
+  // orchestrator's check_version_mismatch compares against CARGO_PKG_VERSION
+  // (the binary's own value), so build_meta writes must use `binaryVersion`,
+  // not this display value — see pipeline.ts and finalize.ts (#1066).
+  let version: string | null = binaryVersion;
   if (native) {
     try {
       version = getNativePackageVersion() ?? version;
@@ -1019,7 +1215,7 @@ export function getActiveEngine(opts: ParseEngineOpts = {}): {
       debug(`getNativePackageVersion failed: ${(e as Error).message}`);
     }
   }
-  return { name, version };
+  return { name, version, binaryVersion };
 }
 
 /**

package/src/domain/search/models.ts

@@ -42,7 +42,7 @@ export const MODELS: Record<string, ModelConfig> = {
     quantized: false,
   },
   'jina-code': {
-    name: 'Xenova/jina-embeddings-v2-base-code',
+    name: 'jinaai/jina-embeddings-v2-base-code',
     dim: 768,
     contextWindow: 8192,
     desc: 'Code-aware (~137MB). Trained on code+text, best for code search.',
@@ -253,7 +253,7 @@ export async function embed(
     }
 
     if (texts.length > batchSize) {
-      process.stdout.write(`  Embedded ${Math.min(i + batchSize, texts.length)}/${texts.length}\r`);
+      process.stderr.write(`  Embedded ${Math.min(i + batchSize, texts.length)}/${texts.length}\r`);
     }
   }
 

package/src/domain/wasm-worker-entry.ts

@@ -28,7 +28,9 @@ import type { Tree } from 'web-tree-sitter';
 import { Language, Parser, Query } from 'web-tree-sitter';
 import { computeLOCMetrics, computeMaintainabilityIndex } from '../ast-analysis/metrics.js';
 import {
+  AST_STRING_CONFIGS,
   AST_TYPE_MAPS,
+  astStopRecurseKinds,
   CFG_RULES,
   COMPLEXITY_RULES,
   DATAFLOW_RULES,
@@ -584,7 +586,15 @@ function setupVisitorsLocal(
   if (opts.ast) {
     const astTypeMap = AST_TYPE_MAPS.get(langId);
     if (astTypeMap) {
-      astVisitor = createAstStoreVisitor(astTypeMap, defs, relPath, new Map<string, number>());
+      const stringConfig = AST_STRING_CONFIGS.get(langId);
+      astVisitor = createAstStoreVisitor(
+        astTypeMap,
+        defs,
+        relPath,
+        new Map<string, number>(),
+        stringConfig,
+        astStopRecurseKinds(langId),
+      );
       visitors.push(astVisitor);
     }
   }
@@ -698,18 +708,18 @@ async function handleParse(msg: WorkerParseRequest): Promise<SerializedExtractor
           file?: string;
           parentNodeId?: number | null;
         }>;
-        if (astRows.length > 0) {
-          // Strip `file` and `parentNodeId` — main thread re-resolves parent IDs
-          // against its DB in features/ast.ts::collectFileAstRows, and `file` is
-          // known from the map key.
-          serializedAstNodes = astRows.map((n) => ({
-            line: n.line,
-            kind: n.kind,
-            name: n.name ?? '',
-            text: n.text ?? undefined,
-            receiver: n.receiver ?? undefined,
-          }));
-        }
+        // Always set an array (even empty) — leaving astNodes undefined makes
+        // engine.ts::fileNeedsWasmTree treat the file as un-walked and trigger
+        // a full ensureWasmTrees re-parse of every WASM-parseable file (#1036).
+        // Strip `file` and `parentNodeId` — main thread re-resolves both in
+        // features/ast.ts::collectFileAstRows.
+        serializedAstNodes = astRows.map((n) => ({
+          line: n.line,
+          kind: n.kind,
+          name: n.name ?? '',
+          text: n.text ?? undefined,
+          receiver: n.receiver ?? undefined,
+        }));
       }
 
       if (complexityVisitor) storeComplexityResults(results, defs, entry.id);

package/src/features/ast.ts

@@ -1,5 +1,9 @@
 import path from 'node:path';
-import { AST_TYPE_MAPS } from '../ast-analysis/rules/index.js';
+import {
+  AST_STRING_CONFIGS,
+  AST_TYPE_MAPS,
+  astStopRecurseKinds,
+} from '../ast-analysis/rules/index.js';
 import { buildExtensionSet } from '../ast-analysis/shared.js';
 import { walkWithVisitors } from '../ast-analysis/visitor.js';
 import { createAstStoreVisitor } from '../ast-analysis/visitors/ast-store-visitor.js';
@@ -22,8 +26,6 @@ const KIND_ICONS: Record<string, string> = {
   await: '\u22B3', // ⊳
 };
 
-const JS_TS_AST_TYPES = AST_TYPE_MAPS.get('javascript');
-
 const WALK_EXTENSIONS = buildExtensionSet(AST_TYPE_MAPS);
 
 // ─── Helpers ──────────────────────────────────────────────────────────
@@ -171,9 +173,10 @@ function collectFileAstRows(
 
   // WASM fallback — walk tree if available
   const ext = path.extname(relPath).toLowerCase();
-  if (WALK_EXTENSIONS.has(ext) && symbols._tree) {
+  const langId = symbols._langId || '';
+  if ((WALK_EXTENSIONS.has(ext) || AST_TYPE_MAPS.has(langId)) && symbols._tree) {
     const rows: AstRow[] = [];
-    walkAst(symbols._tree.rootNode, defs, relPath, rows, nodeIdMap);
+    walkAst(symbols._tree.rootNode, defs, relPath, rows, nodeIdMap, langId);
     return rows;
   }
 
@@ -226,13 +229,23 @@ function walkAst(
   relPath: string,
   rows: AstRow[],
   nodeIdMap: Map<string, number>,
+  langId: string,
 ): void {
-  if (!JS_TS_AST_TYPES) {
-    debug('ast-store: JS_TS_AST_TYPES not available — skipping walk');
+  const astTypeMap = AST_TYPE_MAPS.get(langId);
+  if (!astTypeMap) {
+    debug(`ast-store: no astTypes for langId=${langId} — skipping walk`);
     return;
   }
-  const visitor = createAstStoreVisitor(JS_TS_AST_TYPES, defs, relPath, nodeIdMap);
-  const results = walkWithVisitors(rootNode, [visitor], 'javascript');
+  const stringConfig = AST_STRING_CONFIGS.get(langId);
+  const visitor = createAstStoreVisitor(
+    astTypeMap,
+    defs,
+    relPath,
+    nodeIdMap,
+    stringConfig,
+    astStopRecurseKinds(langId),
+  );
+  const results = walkWithVisitors(rootNode, [visitor], langId);
   const collected = (results['ast-store'] || []) as AstRow[];
   rows.push(...collected);
 }

package/src/infrastructure/config.ts

@@ -147,6 +147,7 @@ export const DEFAULTS = {
       implementations: 50,
       interfaces: 50,
     },
+    disabledTools: [] as string[],
   },
 } satisfies CodegraphConfig;
 

package/src/mcp/server.ts

@@ -98,17 +98,15 @@ async function resolveDbPath(
   return dbPath;
 }
 
-function validateMultiRepoAccess(multiRepo: boolean, name: string, args: { repo?: string }): void {
+function validateMultiRepoAccess(multiRepo: boolean, args: { repo?: string }): void {
   if (!multiRepo && args.repo) {
     throw new ConfigError(
       'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to access other repositories.',
     );
   }
-  if (!multiRepo && name === 'list_repos') {
-    throw new ConfigError(
-      'Multi-repo access is disabled. Restart with `codegraph mcp --multi-repo` to list repositories.',
-    );
-  }
+  // Note: the `list_repos` tool is excluded from `enabledToolNames` when
+  // `multiRepo` is false (see `buildToolList`), so any call to it is rejected
+  // earlier in `createCallToolHandler` with an "Unknown tool" error.
 }
 
 /**
@@ -163,11 +161,17 @@ function createCallToolHandler(
   customDbPath: string | undefined,
   allowedRepos: string[] | undefined,
   getQueries: () => Promise<unknown>,
+  enabledToolNames: Set<string>,
 ) {
   return async (request: any) => {
     const { name, arguments: args } = request.params;
     try {
-      validateMultiRepoAccess(multiRepo, name, args);
+      if (!enabledToolNames.has(name)) {
+        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+      }
+
+      validateMultiRepoAccess(multiRepo, args);
+
       const dbPath = await resolveDbPath(customDbPath, args, allowedRepos);
 
       const toolEntry = TOOL_HANDLERS.get(name);
@@ -209,6 +213,9 @@ export async function startMCPServer(
   // Apply config-based MCP page-size overrides
   const config = options.config || loadConfig();
   initMcpDefaults(config.mcp?.defaults ? { ...config.mcp.defaults } : undefined);
+  const disabledTools = [...(config.mcp?.disabledTools ?? [])];
+  const enabledTools = buildToolList(multiRepo, disabledTools);
+  const enabledToolNames = new Set(enabledTools.map((tool) => tool.name));
 
   const { Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema } =
     await loadMCPSdk();
@@ -225,12 +232,12 @@ export async function startMCPServer(
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: buildToolList(multiRepo),
+    tools: enabledTools,
   }));
 
   server.setRequestHandler(
     CallToolRequestSchema,
-    createCallToolHandler(multiRepo, customDbPath, allowedRepos, getQueries),
+    createCallToolHandler(multiRepo, customDbPath, allowedRepos, getQueries, enabledToolNames),
   );
 
   const transport = new (StdioServerTransport as any)();

package/src/mcp/tool-registry.ts

@@ -29,6 +29,17 @@ const PAGINATION_PROPS: Record<string, unknown> = {
   offset: { type: 'number', description: 'Skip this many results (pagination, default: 0)' },
 };
 
+function normalizeToolName(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/^codegraph\d+_/, '');
+}
+
+function buildDisabledToolSet(disabledTools?: string[]): Set<string> {
+  return new Set((disabledTools || []).map((name) => normalizeToolName(name)).filter(Boolean));
+}
+
 const BASE_TOOLS: ToolSchema[] = [
   {
     name: 'query',
@@ -849,18 +860,25 @@ const LIST_REPOS_TOOL: ToolSchema = {
 /**
  * Build the tool list based on multi-repo mode.
  */
-export function buildToolList(multiRepo: boolean): ToolSchema[] {
-  if (!multiRepo) return BASE_TOOLS;
-  return [
-    ...BASE_TOOLS.map((tool) => ({
+export function buildToolList(multiRepo: boolean, disabledTools?: string[]): ToolSchema[] {
+  const disabled = buildDisabledToolSet(disabledTools);
+  const includeTool = (tool: ToolSchema): boolean => !disabled.has(normalizeToolName(tool.name));
+  const baseTools = BASE_TOOLS.filter(includeTool);
+
+  if (!multiRepo) return baseTools;
+
+  const tools: ToolSchema[] = [
+    ...baseTools.map((tool) => ({
       ...tool,
       inputSchema: {
         ...tool.inputSchema,
         properties: { ...tool.inputSchema.properties, ...REPO_PROP },
       },
     })),
-    LIST_REPOS_TOOL,
   ];
+
+  if (includeTool(LIST_REPOS_TOOL)) tools.push(LIST_REPOS_TOOL);
+  return tools;
 }
 
 // Backward-compatible export: full multi-repo tool list

package/src/types.ts

@@ -1201,6 +1201,7 @@ export interface CodegraphConfig {
 
   mcp: {
     defaults: McpDefaults;
+    disabledTools?: string[];
   };
 }