@optave/codegraph 3.2.0 → 3.3.0

package/src/extractors/rust.js

@@ -10,9 +10,11 @@ export function extractRustSymbols(tree, _filePath) {
     imports: [],
     classes: [],
     exports: [],
+    typeMap: new Map(),
   };
 
   walkRustNode(tree.rootNode, ctx);
+  extractRustTypeMap(tree.rootNode, ctx);
   return ctx;
 }
 
@@ -257,6 +259,64 @@ function extractEnumVariants(enumNode) {
   return variants;
 }
 
+function extractRustTypeMap(node, ctx) {
+  extractRustTypeMapDepth(node, ctx, 0);
+}
+
+function extractRustTypeMapDepth(node, ctx, depth) {
+  if (depth >= 200) return;
+
+  // let x: MyType = ...
+  if (node.type === 'let_declaration') {
+    const pattern = node.childForFieldName('pattern');
+    const typeNode = node.childForFieldName('type');
+    if (pattern && pattern.type === 'identifier' && typeNode) {
+      const typeName = extractRustTypeName(typeNode);
+      if (typeName) ctx.typeMap.set(pattern.text, { type: typeName, confidence: 0.9 });
+    }
+  }
+
+  // fn foo(x: MyType) — parameter node has pattern + type fields
+  if (node.type === 'parameter') {
+    const pattern = node.childForFieldName('pattern');
+    const typeNode = node.childForFieldName('type');
+    if (pattern && typeNode) {
+      const name = pattern.type === 'identifier' ? pattern.text : null;
+      if (name && name !== 'self' && name !== '&self' && name !== '&mut self') {
+        const typeName = extractRustTypeName(typeNode);
+        if (typeName) ctx.typeMap.set(name, { type: typeName, confidence: 0.9 });
+      }
+    }
+  }
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) extractRustTypeMapDepth(child, ctx, depth + 1);
+  }
+}
+
+function extractRustTypeName(typeNode) {
+  if (!typeNode) return null;
+  const t = typeNode.type;
+  if (t === 'type_identifier' || t === 'identifier') return typeNode.text;
+  if (t === 'scoped_type_identifier') return typeNode.text;
+  // Reference: &MyType or &mut MyType → MyType
+  if (t === 'reference_type') {
+    for (let i = 0; i < typeNode.childCount; i++) {
+      const child = typeNode.child(i);
+      if (child && (child.type === 'type_identifier' || child.type === 'scoped_type_identifier')) {
+        return child.text;
+      }
+    }
+  }
+  // Generic: Vec<T> → Vec
+  if (t === 'generic_type') {
+    const first = typeNode.child(0);
+    return first ? first.text : null;
+  }
+  return null;
+}
+
 function extractRustUsePath(node) {
   if (!node) return [];
 

package/src/features/audit.js

@@ -100,7 +100,8 @@ function readPhase44(db, nodeId) {
 
 export function auditData(target, customDbPath, opts = {}) {
   const noTests = opts.noTests || false;
-  const maxDepth = opts.depth || 3;
+  const config = opts.config || loadConfig();
+  const maxDepth = opts.depth || config.analysis?.auditDepth || 3;
   const fileFilters = normalizeFileFilter(opts.file);
   const kind = opts.kind;
 

package/src/features/communities.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { openRepo } from '../db/index.js';
 import { louvainCommunities } from '../graph/algorithms/louvain.js';
 import { buildDependencyGraph } from '../graph/builders/dependency.js';
+import { loadConfig } from '../infrastructure/config.js';
 import { paginateResult } from '../shared/paginate.js';
 
 // ─── Directory Helpers ────────────────────────────────────────────────
@@ -144,7 +145,8 @@ export function communitiesData(customDbPath, opts = {}) {
     };
   }
 
-  const resolution = opts.resolution ?? 1.0;
+  const config = opts.config || loadConfig();
+  const resolution = opts.resolution ?? config.community?.resolution ?? 1.0;
   const { assignments, modularity } = louvainCommunities(graph, { resolution });
 
   const { communities, communityDirs } = buildCommunityObjects(graph, assignments, opts);

package/src/features/graph-enrichment.js

@@ -162,7 +162,7 @@ function prepareFunctionLevelData(db, noTests, minConf, cfg) {
     const community = communityMap.get(n.id) ?? null;
     const directory = path.dirname(n.file);
     const risk = [];
-    if (n.role === 'dead') risk.push('dead-code');
+    if (n.role?.startsWith('dead')) risk.push('dead-code');
     if (fanIn >= (cfg.riskThresholds?.highBlastRadius ?? 10)) risk.push('high-blast-radius');
     if (cx && cx.maintainabilityIndex < (cfg.riskThresholds?.lowMI ?? 40)) risk.push('low-mi');
 

package/src/features/sequence.js

@@ -9,6 +9,7 @@
 import { openRepo } from '../db/index.js';
 import { SqliteRepository } from '../db/repository/sqlite-repository.js';
 import { findMatchingNodes } from '../domain/queries.js';
+import { loadConfig } from '../infrastructure/config.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
 import { paginateResult } from '../shared/paginate.js';
 import { FRAMEWORK_ENTRY_PREFIXES } from './structure.js';
@@ -230,7 +231,8 @@ function buildParticipants(fileSet, entryFile) {
 export function sequenceData(name, dbPath, opts = {}) {
   const { repo, close } = openRepo(dbPath, opts);
   try {
-    const maxDepth = opts.depth || 10;
+    const config = opts.config || loadConfig();
+    const maxDepth = opts.depth || config.analysis?.sequenceDepth || 10;
     const noTests = opts.noTests || false;
 
     const matchNode = findEntryNode(repo, name, opts);

package/src/features/structure.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { getNodeId, openReadonlyOrFail, testFilterSQL } from '../db/index.js';
+import { loadConfig } from '../infrastructure/config.js';
 import { debug } from '../infrastructure/logger.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
 import { normalizePath } from '../shared/constants.js';
@@ -349,7 +350,19 @@ export function classifyNodeRoles(db) {
     .all();
 
   if (rows.length === 0) {
-    return { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, 'test-only': 0, leaf: 0 };
+    return {
+      entry: 0,
+      core: 0,
+      utility: 0,
+      adapter: 0,
+      dead: 0,
+      'dead-leaf': 0,
+      'dead-entry': 0,
+      'dead-ffi': 0,
+      'dead-unresolved': 0,
+      'test-only': 0,
+      leaf: 0,
+    };
   }
 
   const exportedIds = new Set(
@@ -385,6 +398,8 @@ export function classifyNodeRoles(db) {
   const classifierInput = rows.map((r) => ({
     id: String(r.id),
     name: r.name,
+    kind: r.kind,
+    file: r.file,
     fanIn: r.fan_in,
     fanOut: r.fan_out,
     isExported: exportedIds.has(r.id),
@@ -394,12 +409,25 @@ export function classifyNodeRoles(db) {
   const roleMap = classifyRoles(classifierInput);
 
   // Build summary and updates
-  const summary = { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, 'test-only': 0, leaf: 0 };
+  const summary = {
+    entry: 0,
+    core: 0,
+    utility: 0,
+    adapter: 0,
+    dead: 0,
+    'dead-leaf': 0,
+    'dead-entry': 0,
+    'dead-ffi': 0,
+    'dead-unresolved': 0,
+    'test-only': 0,
+    leaf: 0,
+  };
   const updates = [];
   for (const row of rows) {
     const role = roleMap.get(String(row.id)) || 'leaf';
     updates.push({ id: row.id, role });
-    summary[role]++;
+    if (role.startsWith('dead')) summary.dead++;
+    summary[role] = (summary[role] || 0) + 1;
   }
 
   const clearRoles = db.prepare('UPDATE nodes SET role = NULL');
@@ -609,7 +637,8 @@ export function hotspotsData(customDbPath, opts = {}) {
 export function moduleBoundariesData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
   try {
-    const threshold = opts.threshold || 0.3;
+    const config = opts.config || loadConfig();
+    const threshold = opts.threshold ?? config.structure?.cohesionThreshold ?? 0.3;
 
     const dirs = db
       .prepare(`

package/src/features/triage.js

@@ -1,5 +1,6 @@
 import { openRepo } from '../db/index.js';
 import { DEFAULT_WEIGHTS, scoreRisk } from '../graph/classifiers/risk.js';
+import { loadConfig } from '../infrastructure/config.js';
 import { warn } from '../infrastructure/logger.js';
 import { isTestFile } from '../infrastructure/test-filter.js';
 import { paginateResult } from '../shared/paginate.js';
@@ -94,7 +95,13 @@ export function triageData(customDbPath, opts = {}) {
     const noTests = opts.noTests || false;
     const minScore = opts.minScore != null ? Number(opts.minScore) : null;
     const sort = opts.sort || 'risk';
-    const weights = { ...DEFAULT_WEIGHTS, ...(opts.weights || {}) };
+    const config = opts.config || loadConfig();
+    const riskConfig = config.risk || {};
+    const weights = { ...DEFAULT_WEIGHTS, ...(riskConfig.weights || {}), ...(opts.weights || {}) };
+    const riskOpts = {
+      roleWeights: riskConfig.roleWeights,
+      defaultRoleWeight: riskConfig.defaultRoleWeight,
+    };
 
     let rows;
     try {
@@ -114,7 +121,7 @@ export function triageData(customDbPath, opts = {}) {
       return { items: [], summary: EMPTY_SUMMARY(weights) };
     }
 
-    const riskMetrics = scoreRisk(filtered, weights);
+    const riskMetrics = scoreRisk(filtered, weights, riskOpts);
     const items = buildTriageItems(filtered, riskMetrics);
 
     const scored = minScore != null ? items.filter((it) => it.riskScore >= minScore) : items;

package/src/graph/classifiers/risk.js

@@ -26,6 +26,10 @@ export const ROLE_WEIGHTS = {
   leaf: 0.2,
   'test-only': 0.1,
   dead: 0.1,
+  'dead-leaf': 0.0,
+  'dead-entry': 0.3,
+  'dead-ffi': 0.05,
+  'dead-unresolved': 0.15,
 };
 
 const DEFAULT_ROLE_WEIGHT = 0.5;
@@ -48,11 +52,14 @@ function round4(n) {
  *
  * @param {{ fan_in: number, cognitive: number, churn: number, mi: number, role: string|null }[]} items
  * @param {object} [weights] - Override DEFAULT_WEIGHTS
+ * @param {{ roleWeights?: object, defaultRoleWeight?: number }} [opts] - Optional role weight overrides
  * @returns {{ normFanIn: number, normComplexity: number, normChurn: number, normMI: number, roleWeight: number, riskScore: number }[]}
  *   Parallel array with risk metrics for each input item.
  */
-export function scoreRisk(items, weights = {}) {
+export function scoreRisk(items, weights = {}, opts = {}) {
   const w = { ...DEFAULT_WEIGHTS, ...weights };
+  const rw = opts.roleWeights || ROLE_WEIGHTS;
+  const drw = opts.defaultRoleWeight ?? DEFAULT_ROLE_WEIGHT;
 
   const fanIns = items.map((r) => r.fan_in);
   const cognitives = items.map((r) => r.cognitive);
@@ -66,7 +73,7 @@ export function scoreRisk(items, weights = {}) {
   const normMIs = normMIsRaw.map((v) => round4(1 - v));
 
   return items.map((r, i) => {
-    const roleWeight = ROLE_WEIGHTS[r.role] ?? DEFAULT_ROLE_WEIGHT;
+    const roleWeight = rw[r.role] ?? drw;
     const riskScore =
       w.fanIn * normFanIns[i] +
       w.complexity * normCognitives[i] +

package/src/graph/classifiers/roles.js

@@ -1,11 +1,59 @@
 /**
  * Node role classification — pure logic, no DB.
  *
- * Roles: entry, core, utility, adapter, leaf, dead, test-only
+ * Roles: entry, core, utility, adapter, leaf, dead-*, test-only
+ *
+ * Dead sub-categories refine the coarse "dead" bucket:
+ *   dead-leaf       — parameters, properties, constants (leaf nodes by definition)
+ *   dead-entry      — framework dispatch: CLI commands, MCP tools, event handlers
+ *   dead-ffi        — cross-language FFI boundaries (e.g. Rust napi-rs bindings)
+ *   dead-unresolved — genuinely unreferenced callables (the real dead code)
  */
 
 export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
 
+// ── Dead sub-classification helpers ────────────────────────────────
+
+const LEAF_KINDS = new Set(['parameter', 'property', 'constant']);
+
+const FFI_EXTENSIONS = new Set(['.rs', '.c', '.cpp', '.h', '.go', '.java', '.cs']);
+
+/** Path patterns indicating framework-dispatched entry points. */
+const ENTRY_PATH_PATTERNS = [
+  /cli[/\\]commands[/\\]/,
+  /mcp[/\\]/,
+  /routes?[/\\]/,
+  /handlers?[/\\]/,
+  /middleware[/\\]/,
+];
+
+/**
+ * Refine a "dead" classification into a sub-category.
+ *
+ * @param {{ kind?: string, file?: string }} node
+ * @returns {'dead-leaf'|'dead-entry'|'dead-ffi'|'dead-unresolved'}
+ */
+function classifyDeadSubRole(node) {
+  // Leaf kinds are dead by definition — they can't have callers
+  if (node.kind && LEAF_KINDS.has(node.kind)) return 'dead-leaf';
+
+  if (node.file) {
+    // Cross-language FFI: compiled-language files in a JS/TS project
+    // Priority: dead-ffi is checked before dead-entry deliberately — an FFI
+    // boundary is a more fundamental classification than a path-based hint.
+    // A .so/.dll in a routes/ directory is still FFI, not an entry point.
+    const dotIdx = node.file.lastIndexOf('.');
+    if (dotIdx !== -1 && FFI_EXTENSIONS.has(node.file.slice(dotIdx))) return 'dead-ffi';
+
+    // Framework-dispatched entry points (CLI commands, MCP tools, routes)
+    if (ENTRY_PATH_PATTERNS.some((p) => p.test(node.file))) return 'dead-entry';
+  }
+
+  return 'dead-unresolved';
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
 function median(sorted) {
   if (sorted.length === 0) return 0;
   const mid = Math.floor(sorted.length / 2);
@@ -15,7 +63,7 @@ function median(sorted) {
 /**
  * Classify nodes into architectural roles based on fan-in/fan-out metrics.
  *
- * @param {{ id: string, name: string, fanIn: number, fanOut: number, isExported: boolean, testOnlyFanIn?: number }[]} nodes
+ * @param {{ id: string, name: string, kind?: string, file?: string, fanIn: number, fanOut: number, isExported: boolean, testOnlyFanIn?: number }[]} nodes
  * @returns {Map<string, string>} nodeId → role
  */
 export function classifyRoles(nodes) {
@@ -45,7 +93,7 @@ export function classifyRoles(nodes) {
     if (isFrameworkEntry) {
       role = 'entry';
     } else if (node.fanIn === 0 && !node.isExported) {
-      role = node.testOnlyFanIn > 0 ? 'test-only' : 'dead';
+      role = node.testOnlyFanIn > 0 ? 'test-only' : classifyDeadSubRole(node);
     } else if (node.fanIn === 0 && node.isExported) {
       role = 'entry';
     } else if (hasProdFanIn && node.fanIn > 0 && node.productionFanIn === 0) {

package/src/infrastructure/config.js

@@ -23,7 +23,7 @@ export const DEFAULTS = {
   },
   embeddings: { model: 'nomic-v1.5', llmProvider: null },
   llm: { provider: null, model: null, baseUrl: null, apiKey: null, apiKeyCommand: null },
-  search: { defaultMinScore: 0.2, rrfK: 60, topK: 15 },
+  search: { defaultMinScore: 0.2, rrfK: 60, topK: 15, similarityWarnThreshold: 0.85 },
   ci: { failOnCycles: false, impactThreshold: null },
   manifesto: {
     rules: {
@@ -54,6 +54,80 @@ export const DEFAULTS = {
     minJaccard: 0.3,
     maxFilesPerCommit: 50,
   },
+  analysis: {
+    impactDepth: 3,
+    fnImpactDepth: 5,
+    auditDepth: 3,
+    sequenceDepth: 10,
+    falsePositiveCallers: 20,
+    briefCallerDepth: 5,
+    briefImporterDepth: 5,
+    briefHighRiskCallers: 10,
+    briefMediumRiskCallers: 3,
+  },
+  community: {
+    resolution: 1.0,
+  },
+  structure: {
+    cohesionThreshold: 0.3,
+  },
+  risk: {
+    weights: {
+      fanIn: 0.25,
+      complexity: 0.3,
+      churn: 0.2,
+      role: 0.15,
+      mi: 0.1,
+    },
+    roleWeights: {
+      core: 1.0,
+      utility: 0.9,
+      entry: 0.8,
+      adapter: 0.5,
+      leaf: 0.2,
+      'test-only': 0.1,
+      dead: 0.1,
+      'dead-leaf': 0.0,
+      'dead-entry': 0.3,
+      'dead-ffi': 0.05,
+      'dead-unresolved': 0.15,
+    },
+    defaultRoleWeight: 0.5,
+  },
+  display: {
+    maxColWidth: 40,
+    excerptLines: 50,
+    summaryMaxChars: 100,
+    jsdocEndScanLines: 10,
+    jsdocOpenScanLines: 20,
+    signatureGatherLines: 5,
+  },
+  mcp: {
+    defaults: {
+      list_functions: 100,
+      query: 10,
+      where: 50,
+      node_roles: 100,
+      export_graph: 500,
+      fn_impact: 5,
+      context: 5,
+      explain: 10,
+      file_deps: 20,
+      file_exports: 20,
+      diff_impact: 30,
+      impact_analysis: 20,
+      semantic_search: 20,
+      execution_flow: 50,
+      hotspots: 20,
+      co_changes: 20,
+      complexity: 30,
+      manifesto: 50,
+      communities: 20,
+      structure: 30,
+      triage: 20,
+      ast_query: 50,
+    },
+  },
 };
 
 /**
@@ -120,7 +194,183 @@ export function resolveSecrets(config) {
   return config;
 }
 
-function mergeConfig(defaults, overrides) {
+// ── Monorepo workspace detection ─────────────────────────────────────
+
+/**
+ * Expand a workspace glob pattern into matching directories.
+ * Supports trailing `/*` or `/**` patterns (e.g. "packages/*").
+ * Does not depend on an external glob library — uses fs.readdirSync.
+ */
+function expandWorkspaceGlob(pattern, rootDir) {
+  // Strip trailing /*, /**, or just *
+  const clean = pattern.replace(/\/?\*\*?$/, '');
+  const baseDir = path.resolve(rootDir, clean);
+  if (!fs.existsSync(baseDir)) return [];
+  try {
+    const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isDirectory())
+      .map((e) => path.join(baseDir, e.name))
+      .filter((d) => fs.existsSync(path.join(d, 'package.json')));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read a package.json and return its name field, or null.
+ */
+function readPackageName(pkgDir) {
+  try {
+    const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    return pkg.name || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the entry-point source file for a workspace package.
+ * Checks exports → main → index file fallback.
+ */
+function resolveWorkspaceEntry(pkgDir) {
+  try {
+    const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+
+    // Try "source" field first (common in monorepos for pre-built packages)
+    if (pkg.source) {
+      const s = path.resolve(pkgDir, pkg.source);
+      if (fs.existsSync(s)) return s;
+    }
+
+    // Try "main" field
+    if (pkg.main) {
+      const m = path.resolve(pkgDir, pkg.main);
+      if (fs.existsSync(m)) return m;
+    }
+
+    // Index file fallback
+    for (const idx of [
+      'index.ts',
+      'index.tsx',
+      'index.js',
+      'index.mjs',
+      'src/index.ts',
+      'src/index.tsx',
+      'src/index.js',
+    ]) {
+      const candidate = path.resolve(pkgDir, idx);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+/**
+ * Detect monorepo workspace packages from workspace configuration files.
+ *
+ * Checks (in order):
+ *   1. pnpm-workspace.yaml — `packages:` array
+ *   2. package.json — `workspaces` field (npm/yarn)
+ *   3. lerna.json — `packages` array
+ *
+ * @param {string} rootDir - Project root directory
+ * @returns {Map<string, { dir: string, entry: string|null }>}
+ *   Map of package name → { absolute dir, resolved entry file }
+ */
+export function detectWorkspaces(rootDir) {
+  const workspaces = new Map();
+  const patterns = [];
+
+  // 1. pnpm-workspace.yaml
+  const pnpmPath = path.join(rootDir, 'pnpm-workspace.yaml');
+  if (fs.existsSync(pnpmPath)) {
+    try {
+      const raw = fs.readFileSync(pnpmPath, 'utf-8');
+      // Simple YAML parse for `packages:` array — no dependency needed
+      const packagesMatch = raw.match(/^packages:\s*\n((?:\s+-\s+.+\n?)*)/m);
+      if (packagesMatch) {
+        const lines = packagesMatch[1].match(/^\s+-\s+['"]?([^'"#\n]+)['"]?\s*$/gm);
+        if (lines) {
+          for (const line of lines) {
+            const m = line.match(/^\s+-\s+['"]?([^'"#\n]+?)['"]?\s*$/);
+            if (m) patterns.push(m[1].trim());
+          }
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  // 2. package.json workspaces (npm/yarn)
+  if (patterns.length === 0) {
+    const rootPkgPath = path.join(rootDir, 'package.json');
+    if (fs.existsSync(rootPkgPath)) {
+      try {
+        const raw = fs.readFileSync(rootPkgPath, 'utf-8');
+        const pkg = JSON.parse(raw);
+        const ws = pkg.workspaces;
+        if (Array.isArray(ws)) {
+          patterns.push(...ws);
+        } else if (ws && Array.isArray(ws.packages)) {
+          // Yarn classic format: { packages: [...], nohoist: [...] }
+          patterns.push(...ws.packages);
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  // 3. lerna.json
+  if (patterns.length === 0) {
+    const lernaPath = path.join(rootDir, 'lerna.json');
+    if (fs.existsSync(lernaPath)) {
+      try {
+        const raw = fs.readFileSync(lernaPath, 'utf-8');
+        const lerna = JSON.parse(raw);
+        if (Array.isArray(lerna.packages)) {
+          patterns.push(...lerna.packages);
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  if (patterns.length === 0) return workspaces;
+
+  // Expand glob patterns and collect packages
+  for (const pattern of patterns) {
+    // Check if pattern is a direct path (no glob) or a glob
+    if (pattern.includes('*')) {
+      for (const dir of expandWorkspaceGlob(pattern, rootDir)) {
+        const name = readPackageName(dir);
+        if (name) workspaces.set(name, { dir, entry: resolveWorkspaceEntry(dir) });
+      }
+    } else {
+      // Direct path like "packages/core"
+      const dir = path.resolve(rootDir, pattern);
+      if (fs.existsSync(path.join(dir, 'package.json'))) {
+        const name = readPackageName(dir);
+        if (name) workspaces.set(name, { dir, entry: resolveWorkspaceEntry(dir) });
+      }
+    }
+  }
+
+  if (workspaces.size > 0) {
+    debug(`Detected ${workspaces.size} workspace packages: ${[...workspaces.keys()].join(', ')}`);
+  }
+
+  return workspaces;
+}
+
+export function mergeConfig(defaults, overrides) {
   const result = { ...defaults };
   for (const [key, value] of Object.entries(overrides)) {
     if (
@@ -128,9 +378,10 @@ function mergeConfig(defaults, overrides) {
       typeof value === 'object' &&
       !Array.isArray(value) &&
       defaults[key] &&
-      typeof defaults[key] === 'object'
+      typeof defaults[key] === 'object' &&
+      !Array.isArray(defaults[key])
     ) {
-      result[key] = { ...defaults[key], ...value };
+      result[key] = mergeConfig(defaults[key], value);
     } else {
       result[key] = value;
     }

package/src/mcp/middleware.js

@@ -2,10 +2,28 @@
  * MCP middleware helpers — pagination defaults and limits.
  */
 
-import { MCP_DEFAULTS, MCP_MAX_LIMIT } from '../shared/paginate.js';
+import { getMcpDefaults, MCP_DEFAULTS, MCP_MAX_LIMIT } from '../shared/paginate.js';
 
 export { MCP_DEFAULTS, MCP_MAX_LIMIT };
 
+/** Resolved MCP defaults (may include config overrides). Set via initMcpDefaults(). */
+let resolvedDefaults = MCP_DEFAULTS;
+
+/**
+ * Initialize MCP defaults from config. Call once at server startup.
+ * @param {object} [configMcpDefaults] - config.mcp.defaults overrides
+ */
+export function initMcpDefaults(configMcpDefaults) {
+  resolvedDefaults = getMcpDefaults(configMcpDefaults);
+}
+
+/**
+ * Reset MCP defaults back to the base defaults. Useful for test isolation.
+ */
+export function resetMcpDefaults() {
+  resolvedDefaults = MCP_DEFAULTS;
+}
+
 /**
  * Resolve effective limit for a tool call.
  * @param {object} args - Tool arguments
@@ -13,7 +31,7 @@ export { MCP_DEFAULTS, MCP_MAX_LIMIT };
  * @returns {number}
  */
 export function effectiveLimit(args, toolName) {
-  return Math.min(args.limit ?? MCP_DEFAULTS[toolName] ?? 100, MCP_MAX_LIMIT);
+  return Math.min(args.limit ?? resolvedDefaults[toolName] ?? 100, MCP_MAX_LIMIT);
 }
 
 /**