magector 2.15.1 → 2.16.1

package/README.md

@@ -5,7 +5,7 @@
 Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 46 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks *"how are checkout totals calculated?"* and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).
 
 [![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org)
-[![Node.js](https://img.shields.io/badge/node-22.5+-green.svg)](https://nodejs.org)
+[![Node.js](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org)
 [![Magento](https://img.shields.io/badge/magento-2.4.x-blue.svg)](https://magento.com)
 [![Adobe Commerce](https://img.shields.io/badge/adobe%20commerce-supported-blue.svg)](https://business.adobe.com/products/magento/magento-commerce.html)
 [![Accuracy](https://img.shields.io/badge/accuracy-99.2%25-brightgreen.svg)](#validation)
@@ -129,8 +129,7 @@ flowchart LR
 | JS parsing | `tree-sitter-javascript` | AMD/ES6 module detection |
 | Pattern detection | Custom Rust | 20+ Magento-specific patterns |
 | CLI | `clap` | Command-line interface (index, search, serve, validate) |
-| Descriptions | `rusqlite` (bundled SQLite) | LLM-generated di.xml descriptions stored in `.magector/sqlite.db`, prepended to embeddings |
-| Null-safety index | `node:sqlite` (Node.js 22.5+ built-in) | Method-chain enrichment index in `.magector/enrichment.db` — O(1) null-risk queries |
+| Unified metadata | rusqlite (bundled SQLite) | LLM descriptions, method-chain enrichment, process state, cache — all in .magector/data.db |
 | SONA | Custom Rust | Feedback learning with MicroLoRA + EWC++ |
 | MCP server | `@modelcontextprotocol/sdk` | AI tool integration with structured JSON output |
 
@@ -171,8 +170,7 @@ If you find a security issue, please open an issue on the GitHub repo and mark i
 
 ### Prerequisites
 
-- [Node.js 22.5+](https://nodejs.org) — required for built-in `node:sqlite` (used by `magento_enrich` / `magento_find_null_risks`)
-- [semgrep](https://semgrep.dev) (optional) — required for `magento_ast_search`: `pip install semgrep`
+- [Node.js 18+](https://nodejs.org)
 
 ### 1. Initialize in Your Project
 
@@ -246,7 +244,7 @@ Options:
   -v, --verbose                      Enable verbose output
 ```
 
-When `--descriptions-db` is provided (or auto-detected as `sqlite.db` next to the index), descriptions are prepended to the embedding text as `"Description: {text}\n\n"` before the raw file content. This places semantic terms within the 256-token ONNX window, significantly improving retrieval of di.xml files for natural-language queries.
+When `--descriptions-db` is provided (or auto-detected as `data.db` next to the index), descriptions are prepended to the embedding text as `"Description: {text}\n\n"` before the raw file content. This places semantic terms within the 256-token ONNX window, significantly improving retrieval of di.xml files for natural-language queries.
 
 #### `search`
 
@@ -266,7 +264,7 @@ magector-core describe [OPTIONS]
 
 Options:
   -m, --magento-root <PATH>   Path to Magento root directory
-  -o, --output <PATH>         Output SQLite database [default: ./.magector/sqlite.db]
+  -o, --output <PATH>         Output SQLite database [default: ./.magector/data.db]
       --force                 Re-describe all files (ignore cache)
 ```
 
@@ -504,7 +502,7 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 |------|-------------|
 | `magento_module_structure` | Show complete module structure -- controllers, models, blocks, plugins, observers, configs |
 | `magento_index` | Trigger re-indexing of the codebase (also kicks off background enrichment) |
-| `magento_describe` | Generate LLM descriptions for di.xml files (requires `ANTHROPIC_API_KEY`), stored in `.magector/sqlite.db`, auto-reindexes affected files |
+| `magento_describe` | Generate LLM descriptions for di.xml files (requires `ANTHROPIC_API_KEY`), stored in `.magector/data.db`, auto-reindexes affected files |
 | `magento_stats` | View index statistics |
 | `magento_batch` | Execute multiple tool queries in parallel in one MCP roundtrip. Supports all search, find, grep, read, and null-risk tools. Use to avoid N×3-5s roundtrip overhead. |
 | `magento_grep` | Exact text/regex search across PHP/XML/PHTML files (`grep -rn -E` internally). Supports `filesOnly` mode (like `grep -l`), `context` lines, `ignoreCase`, `include` patterns. **(v2.9)** |
@@ -517,10 +515,10 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 
 | Tool | Description |
 |------|-------------|
-| `magento_ast_search` | Structural PHP code search using [semgrep](https://semgrep.dev). Understands PHP AST — matches by structure regardless of variable names, ignores comments/strings. Pattern syntax: `$X` = any expression, `$Y` = any identifier, `...` = any args. Example: `$X->getPayment()->$Y(...)`. Requires `semgrep`. **(v2.12)** |
-| `magento_enrich` | Build the method-chain enrichment index. Scans all `vendor/` PHP files for `->firstMethod()->secondMethod()` chains and detects null guards in surrounding code. Stores results in `.magector/enrichment.db` (SQLite, `node:sqlite`). Runs automatically after `magento_index`. **(v2.13)** |
+| `magento_ast_search` | Structural PHP code search using tree-sitter. Named patterns: `dataobject-set-null` (detect setX(null) anti-pattern), `unchecked-method-chain` (detect $this->dep->method() chains). Pattern arg is an enum, not free-text. Executed in Rust serve process — no external dependency. **(v2.16)** |
+| `magento_enrich` | Build the method-chain enrichment index. Scans all `vendor/` PHP files for `->firstMethod()->secondMethod()` chains and detects null guards in surrounding code. Stores results in `.magector/data.db` (SQLite, via Rust serve). Runs automatically after `magento_index`. **(v2.13, moved to Rust v2.16)** |
 | `magento_find_null_risks` | Query the enrichment index for method chains without null guards. O(1) SQLite query instead of file scanning. Pass `firstMethod` to filter (e.g., `"getPayment"` → all `->getPayment()->anything()` without null guard). Requires `magento_enrich`. **(v2.13)** |
-| `magento_find_dataobject_issues` | Detect `setX(null)` anti-pattern on Magento `DataObject` subclasses. `setX(null)` stores `['x' => null]` in `_data` — `hasX()` (via `array_key_exists`) returns `true` even when the value is `null`, creating false-positive guard conditions. Use during field-lifecycle audits or when debugging "value persists but shouldn't" bugs. Requires `semgrep`. **(v2.15)** |
+| `magento_find_dataobject_issues` | Detect `setX(null)` anti-pattern on Magento `DataObject` subclasses. `setX(null)` stores `['x' => null]` in `_data` — `hasX()` (via `array_key_exists`) returns `true` even when the value is `null`, creating false-positive guard conditions. Use during field-lifecycle audits or when debugging "value persists but shouldn't" bugs. Uses tree-sitter. **(v2.15, tree-sitter v2.16)** |
 
 ### Search Enhancements (v2.1)
 
@@ -908,7 +906,7 @@ npx magector index /path/to/magento
 
 Or via the MCP tool: `magento_describe()` generates descriptions and auto-reindexes affected files in one step.
 
-**How it works:** Each di.xml file is sent to Claude Sonnet with a prompt optimized for semantic search retrieval. The resulting description (~70 words) is stored in a SQLite database (`.magector/sqlite.db`). During indexing, descriptions are prepended to the embedding text as `"Description: {text}\n\n"` before the raw file content, placing semantic terms (preferences, plugins, virtual types, subsystem names) within the ONNX model's 256-token window.
+**How it works:** Each di.xml file is sent to Claude Sonnet with a prompt optimized for semantic search retrieval. The resulting description (~70 words) is stored in a SQLite database (`.magector/data.db`). During indexing, descriptions are prepended to the embedding text as `"Description: {text}\n\n"` before the raw file content, placing semantic terms (preferences, plugins, virtual types, subsystem names) within the ONNX model's 256-token window.
 
 **Measured impact** (A/B experiment, 25 queries, Magento 2.4.7, 17,891 vectors, 371 described files):
 
@@ -1249,8 +1247,8 @@ All MCP server activity is logged to `.magector/magector.log` in the Magento pro
 | Level | Meaning |
 |-------|---------|
 | `INFO` | Normal operations: startup config, tool completion, search fallbacks, enrichment progress |
-| `WARN` | Recoverable issues: slow grep queries (>5s), missing enrichment.db, file read errors, serve process disconnects |
-| `ERR` | Failures: semgrep crashes, transaction rollbacks, serve process errors, tool execution errors |
+| `WARN` | Recoverable issues: slow grep queries (>5s), missing data.db, file read errors, serve process disconnects |
+| `ERR` | Failures: AST query errors, transaction rollbacks, serve process errors, tool execution errors |
 | `REQ` | Every tool call with full input parameters (JSON) |
 | `RES` | Tool completion with elapsed time in milliseconds |
 | `QUERY` | Rust serve process queries (search, feedback) |
@@ -1271,7 +1269,7 @@ grep '\[RES\]' .magector/magector.log | tail -20
 # Enrichment/null-risk analysis
 grep 'enrich:\|null_risks:' .magector/magector.log | tail -20
 
-# AST search (semgrep) issues
+# AST search (tree-sitter) issues
 grep 'ast_search:' .magector/magector.log | tail -20
 
 # Batch query breakdown (per-tool timing)
@@ -1288,7 +1286,7 @@ grep 'server starting\|Config:\|primary\|Serve process' .magector/magector.log |
 
 Every tool call logs `[REQ]` with input parameters and `[RES]` with elapsed time. Additionally:
 
-- **`magento_ast_search`** — semgrep pattern, target path, execution time, result count, semgrep errors
+- **`magento_ast_search`** — tree-sitter pattern, target path, execution time, result count, query errors
 - **`magento_enrich`** — file count, progress every 10k files, read errors, transaction failures, final summary
 - **`magento_find_null_risks`** — query parameters, result count, query timing, missing DB warnings
 - **`magento_batch`** — query list on entry, per-sub-tool timing and errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "2.15.1",
+  "version": "2.16.1",
   "description": "Semantic code search for Magento 2 — index, search, MCP server",
   "type": "module",
   "main": "src/mcp-server.js",
@@ -33,10 +33,10 @@
     "ruvector": "^0.1.96"
   },
   "optionalDependencies": {
-    "@magector/cli-darwin-arm64": "2.15.1",
-    "@magector/cli-linux-x64": "2.15.1",
-    "@magector/cli-linux-arm64": "2.15.1",
-    "@magector/cli-win32-x64": "2.15.1"
+    "@magector/cli-darwin-arm64": "2.16.1",
+    "@magector/cli-linux-x64": "2.16.1",
+    "@magector/cli-linux-arm64": "2.16.1",
+    "@magector/cli-win32-x64": "2.16.1"
   },
   "keywords": [
     "magento",

package/src/mcp-server.js

@@ -142,6 +142,9 @@ function extractJson(stdout) {
 
 // ─── PID File & Orphan Cleanup ──────────────────────────────────
 // Track the serve process PID to clean up orphans on restart.
+// Primary state lives in data.db (state_processes / state_cache tables).
+// File-based paths are kept as fallback for operations that run before
+// the serve process (and thus data.db) is available.
 
 const PID_PATH = path.join(config.magentoRoot, '.magector', 'serve.pid');
 const REINDEX_PID_PATH = path.join(config.magentoRoot, '.magector', 'reindex.pid');
@@ -222,12 +225,15 @@ function expandIncludePattern(include) {
 /**
  * Try to acquire the primary lock (O_EXCL = atomic create-or-fail).
  * Returns true if we are the primary instance, false if another instance holds the lock.
+ * Uses file-based O_EXCL for atomicity (runs before serve/DB is available).
+ * Also writes lock state to data.db when serve becomes available.
  */
 function tryAcquirePrimaryLock() {
   try {
     const fd = openSync(PRIMARY_LOCK_PATH, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL);
     writeFileSync(fd, String(process.pid));
     closeSync(fd);
+    // DB write deferred — serve is not available during lock acquisition
     return true;
   } catch {
     // Lock file exists — check if holder is alive
@@ -258,6 +264,19 @@ function tryAcquirePrimaryLock() {
   }
 }
 
+/**
+ * Write primary lock state to data.db (called after serve becomes available).
+ * This mirrors the file-based lock so other processes can query DB for lock owner.
+ */
+function persistPrimaryLockToDb() {
+  if (serveProcess && serveReady) {
+    serveQuery('cache_set', {
+      key: 'primary_lock',
+      value: JSON.stringify({ pid: process.pid, timestamp: Date.now() })
+    }, 5000).catch(() => {});
+  }
+}
+
 function releasePrimaryLock() {
   try {
     // Only remove if we own it
@@ -266,13 +285,27 @@ function releasePrimaryLock() {
       unlinkSync(PRIMARY_LOCK_PATH);
     }
   } catch {}
+  // Also clean DB state — fire-and-forget
+  if (serveProcess && serveReady) {
+    serveQuery('cache_set', {
+      key: 'primary_lock',
+      value: JSON.stringify({ pid: null, released: true })
+    }, 5000).catch(() => {});
+  }
 }
 
 /**
  * Write the serve process PID to disk so future instances can clean up orphans.
+ * Also writes to data.db via serve command when the serve process is available.
+ * Note: the Rust serve process writes its own PID to data.db on startup, so
+ * the file is primarily a fallback for the brief window before serve is ready.
  */
 function writePidFile(pid) {
   try { writeFileSync(PID_PATH, `${pid}\n${__pkg.version}`); } catch {}
+  // Async DB write — fire-and-forget, serve process also writes its own PID
+  if (serveProcess && serveReady) {
+    serveQuery('process_set', { name: 'serve', pid, version: __pkg.version }, 5000).catch(() => {});
+  }
 }
 
 function getServePidVersion() {
@@ -286,21 +319,35 @@ function getServePidVersion() {
 
 function removePidFile() {
   try { if (existsSync(PID_PATH)) unlinkSync(PID_PATH); } catch {}
+  // Also clean DB state — fire-and-forget
+  if (serveProcess && serveReady) {
+    serveQuery('process_remove', { name: 'serve' }, 5000).catch(() => {});
+  }
 }
 
 function writeReindexPidFile(pid) {
   try { writeFileSync(REINDEX_PID_PATH, String(pid)); } catch {}
+  // Also persist in data.db when serve is available
+  if (serveProcess && serveReady) {
+    serveQuery('process_set', { name: 'reindex', pid }, 5000).catch(() => {});
+  }
 }
 
 function removeReindexPidFile() {
   try { if (existsSync(REINDEX_PID_PATH)) unlinkSync(REINDEX_PID_PATH); } catch {}
+  // Also clean DB state
+  if (serveProcess && serveReady) {
+    serveQuery('process_remove', { name: 'reindex' }, 5000).catch(() => {});
+  }
 }
 
 /**
  * Check if another reindex process is already running (from another MCP instance).
+ * Checks data.db first (via serve query), falls back to PID file.
  * Returns the PID if alive, null otherwise.
  */
 function getRunningReindexPid() {
+  // Try file-based check (synchronous, always available)
   try {
     if (!existsSync(REINDEX_PID_PATH)) return null;
     const pid = parseInt(readFileSync(REINDEX_PID_PATH, 'utf-8').trim(), 10);
@@ -319,6 +366,7 @@ function getRunningReindexPid() {
  * Returns the PID if alive, null if stale/missing.
  * Does NOT kill it — multiple MCP instances can share one serve process
  * by sending queries to it via stdin (each instance starts its own).
+ * Tries file-based check (synchronous, always available).
  */
 function getExistingServePid() {
   try {
@@ -337,6 +385,7 @@ function getExistingServePid() {
  * Kill any stale serve process from a previous MCP server instance.
  * Only called during cleanup (exit/SIGTERM), not during startup —
  * multiple concurrent MCP instances each run their own serve process.
+ * Reads PID from file (DB may not be available if serve is dead).
  */
 function killStaleServeProcess() {
   try {
@@ -376,8 +425,13 @@ let warmupInProgress = true; // true until checkDbFormat + serve process ready
 
 /**
  * Check if the database file is compatible with the current binary.
- * Uses a cached result file to avoid running stats (30-60s) on every startup.
+ * Uses a cached result to avoid running stats (30-60s) on every startup.
  * Cache key: binary path mtime + db file mtime + db size.
+ *
+ * Cache lookup order:
+ *   1. data.db state_cache (via serve query, if serve is available)
+ *   2. format-ok.json file (fallback — runs before serve starts)
+ * Both locations are written on cache miss.
  */
 async function checkDbFormat() {
   if (!existsSync(config.dbPath)) return true;
@@ -389,10 +443,27 @@ async function checkDbFormat() {
     // Check cached result — avoids 40s stats command on every MCP startup
     const binaryStat = statSync(config.rustBinary);
     const cacheKey = `${binaryStat.mtimeMs}|${fstat.mtimeMs}|${fstat.size}`;
+
+    // Try DB cache first (if serve process is running)
+    const queryFn = globalServeQuery || ((serveProcess && serveReady) ? serveQuery : null);
+    if (queryFn) {
+      try {
+        const resp = await queryFn('cache_get', { key: 'format_ok' }, 5000);
+        if (resp.ok && resp.data) {
+          const cached = JSON.parse(resp.data.value);
+          if (cached.key === cacheKey) {
+            logToFile('INFO', `Format check cached (DB): ${cached.ok ? 'compatible' : 'incompatible'}`);
+            return cached.ok;
+          }
+        }
+      } catch { /* DB cache miss or unavailable */ }
+    }
+
+    // Fall back to file cache
     try {
       const cached = JSON.parse(readFileSync(FORMAT_CACHE_PATH, 'utf-8'));
       if (cached.key === cacheKey) {
-        logToFile('INFO', `Format check cached: ${cached.ok ? 'compatible' : 'incompatible'}`);
+        logToFile('INFO', `Format check cached (file): ${cached.ok ? 'compatible' : 'incompatible'}`);
         return cached.ok;
       }
     } catch { /* no cache or invalid */ }
@@ -412,8 +483,14 @@ async function checkDbFormat() {
     const vectors = parseInt(result.match(/Total vectors:\s*(\d+)/)?.[1] || '0');
     const ok = vectors > 0;
 
-    // Write cache
-    try { writeFileSync(FORMAT_CACHE_PATH, JSON.stringify({ key: cacheKey, ok })); } catch {}
+    // Write cache to both file and DB
+    const cacheValue = JSON.stringify({ key: cacheKey, ok });
+    try { writeFileSync(FORMAT_CACHE_PATH, cacheValue); } catch {}
+    // Async DB write — fire-and-forget (serve may not be up yet on first startup)
+    const queryFn2 = globalServeQuery || ((serveProcess && serveReady) ? serveQuery : null);
+    if (queryFn2) {
+      queryFn2('cache_set', { key: 'format_ok', value: cacheValue }, 5000).catch(() => {});
+    }
     return ok;
   } catch {
     return false;
@@ -717,6 +794,8 @@ function startServeProcess() {
         serveReady = true;
         logToFile('INFO', `Serve process ready (PID ${proc.pid})`);
         if (serveReadyResolve) { serveReadyResolve(true); serveReadyResolve = null; }
+        // Now that serve is up, persist primary lock state to data.db
+        persistPrimaryLockToDb();
         return;
       }
 
@@ -859,6 +938,10 @@ function tryConnectSocket() {
 let globalServeQuery = null;
 
 function serveQuery(command, params = {}, timeoutMs = 30000) {
+  if (!serveProcess || !serveReady) {
+    logToFile('WARN', `serveQuery(${command}): serve process not ready — returning error`);
+    return Promise.resolve({ ok: false, error: 'Serve process not ready' });
+  }
   return new Promise((resolve, reject) => {
     const id = serveNextId++;
     logToFile('QUERY', `[${id}] → ${command}(${JSON.stringify(params).slice(0, 200)})`);
@@ -3502,302 +3585,35 @@ async function traceCallChain(startClass, startMethod, maxDepth = 3) {
 }
 
 // ─── Method Chain Enrichment ────────────────────────────────────
-// Scans PHP files for two-step method chains (->first()->second()) and detects
-// null guards in surrounding code. Results stored in SQLite enrichment.db for
-// instant O(1) queries — eliminates 20+ grep calls for null-risk analyses.
-
-const ENRICHMENT_DB_PATH = (root) => path.join(root, '.magector', 'enrichment.db');
-
-/**
- * Detect null guard for a chained call in surrounding lines.
- * Checks ±guardRadius lines for: null checks, ?->, ??, isset()
- */
-function hasNullGuard(lines, matchLineIdx, receiverExpr, guardRadius = 6) {
-  const start = Math.max(0, matchLineIdx - guardRadius);
-  const end = Math.min(lines.length - 1, matchLineIdx + guardRadius);
-  const matchLine = lines[matchLineIdx] || '';
-  const window = lines.slice(start, end + 1).join('\n');
-
-  // ?-> only counts if it's on the same line as the chain (avoid false positives from unrelated variables)
-  if (matchLine.includes('?->')) return true;
-  if (/\?\?|\?:/.test(window)) return true;
-
-  if (receiverExpr) {
-    const esc = receiverExpr.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    if (new RegExp(`(?:is_null\\s*\\(\\s*${esc}|${esc}\\s*(?:===|!==)\\s*null|!\\s*${esc}\\s*[,)]|isset\\s*\\(\\s*${esc})`, 'i').test(window)) return true;
-  }
-  return false;
-}
-
-/**
- * Scan vendor/ PHP files for ->first()->second() chains and store null-safety
- * analysis in enrichment.db. Called by magento_enrich and after magento_index.
- */
-async function enrichMethodChains(root) {
-  const dbPath = ENRICHMENT_DB_PATH(root);
-  logToFile('INFO', `enrich: starting method-chain scan, db=${dbPath}`);
-  const enrichStart = Date.now();
-
-  // Use node:sqlite (built-in, no deps)
-  let DatabaseSync;
-  try {
-    ({ DatabaseSync } = await import('node:sqlite'));
-  } catch {
-    logToFile('ERR', 'enrich: node:sqlite not available — requires Node.js 22.5+');
-    throw new Error('node:sqlite not available — requires Node.js 22.5+');
-  }
-
-  const db = new DatabaseSync(dbPath);
-  db.exec('PRAGMA journal_mode = WAL');
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS method_chains (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      file TEXT NOT NULL,
-      line INTEGER NOT NULL,
-      chain TEXT NOT NULL,
-      first_method TEXT NOT NULL,
-      second_method TEXT NOT NULL,
-      has_null_guard INTEGER NOT NULL DEFAULT 0,
-      updated_at INTEGER NOT NULL
-    );
-    CREATE INDEX IF NOT EXISTS idx_first_method ON method_chains (first_method);
-    CREATE INDEX IF NOT EXISTS idx_null_guard ON method_chains (has_null_guard, first_method);
-  `);
-
-  // Two-step chain: $var->firstMethod(...)->secondMethod(
-  // Captures: receiver ($var), firstMethod, secondMethod
-  const chainRegex = /(\$\w+)\s*->\s*(\w+)\s*\([^)]{0,60}\)\s*->\s*(\w+)\s*\(/g;
-  const now = Date.now();
-
-  const phpFiles = await glob('vendor/**/*.php', { cwd: root, absolute: true, nodir: true });
-  logToFile('INFO', `enrich: found ${phpFiles.length} PHP files in vendor/`);
-  let scanned = 0;
-  let chains = 0;
-  let readErrors = 0;
-
-  const insertStmt = db.prepare(
-    'INSERT INTO method_chains (file, line, chain, first_method, second_method, has_null_guard, updated_at) VALUES (?,?,?,?,?,?,?)'
-  );
-  const deleteFile = db.prepare('DELETE FROM method_chains WHERE file = ?');
-
-  // Build line-offset index for O(1) line number lookups
-  function buildLineIndex(content) {
-    const offsets = [0];
-    let idx = 0;
-    while ((idx = content.indexOf('\n', idx)) !== -1) {
-      idx++;
-      offsets.push(idx);
-    }
-    return offsets;
-  }
-
-  function lineFromOffset(offsets, charIndex) {
-    let lo = 0, hi = offsets.length - 1;
-    while (lo < hi) {
-      const mid = (lo + hi + 1) >> 1;
-      if (offsets[mid] <= charIndex) lo = mid; else hi = mid - 1;
-    }
-    return lo + 1; // 1-based
-  }
+// Enrichment logic has been moved to the Rust serve process (enrich / enrich_query commands).
+// Use serveQuery('enrich', { magento_root }) and serveQuery('enrich_query', { first_method, limit }).
 
-  // Progress logging every 10k files
-  const progressInterval = 10000;
+// ─── AST Search (tree-sitter via Rust serve) ────────────────────
 
-  db.exec('BEGIN');
-  try {
-    for (const phpFile of phpFiles) {
-      let content;
-      try { content = readFileSync(phpFile, 'utf-8'); } catch (err) {
-        readErrors++;
-        if (readErrors <= 5) logToFile('WARN', `enrich: cannot read ${phpFile}: ${err.code || err.message}`);
-        continue;
-      }
-      if (!content.includes('->')) continue;
-
-      const relPath = phpFile.replace(root + '/', '');
-      const lines = content.split('\n');
-      const lineOffsets = buildLineIndex(content);
-      const rows = [];
-
-      chainRegex.lastIndex = 0;
-      let m;
-      while ((m = chainRegex.exec(content)) !== null) {
-        const lineNum = lineFromOffset(lineOffsets, m.index);
-        rows.push({
-          file: relPath, line: lineNum,
-          chain: `->${m[2]}()->${m[3]}()`,
-          firstMethod: m[2], secondMethod: m[3],
-          hasNullGuard: hasNullGuard(lines, lineNum - 1, m[1]) ? 1 : 0
-        });
-        chains++;
-      }
-
-      if (rows.length > 0) {
-        deleteFile.run(relPath);
-        for (const r of rows) {
-          insertStmt.run(r.file, r.line, r.chain, r.firstMethod, r.secondMethod, r.hasNullGuard, now);
-        }
-      }
-      scanned++;
-      if (scanned % progressInterval === 0) {
-        logToFile('INFO', `enrich: progress ${scanned}/${phpFiles.length} files, ${chains} chains so far (${Date.now() - enrichStart}ms)`);
-      }
-    }
-    db.exec('COMMIT');
-  } catch (err) {
-    logToFile('ERR', `enrich: transaction failed at file ${scanned}/${phpFiles.length}: ${err.message}`);
-    db.exec('ROLLBACK');
-    throw err;
-  }
-
-  db.close();
-  const enrichElapsed = Date.now() - enrichStart;
-  logToFile('INFO', `enrich: complete — ${scanned} files scanned, ${chains} chains indexed, ${readErrors} read errors, ${enrichElapsed}ms`);
-  return { scanned, chains };
-}
-
-/**
- * Query enrichment.db for unsafe method chains (no null guard).
- */
-async function queryNullRisks(root, firstMethod, limit = 100) {
-  const dbPath = ENRICHMENT_DB_PATH(root);
-  if (!existsSync(dbPath)) {
-    logToFile('WARN', `null_risks: enrichment.db not found at ${dbPath} — run magento_enrich first`);
-    return null;
-  }
-
-  let DatabaseSync;
-  try {
-    ({ DatabaseSync } = await import('node:sqlite'));
-  } catch (err) {
-    logToFile('ERR', `null_risks: node:sqlite not available: ${err.message}`);
-    return null;
-  }
-
-  const queryStart = Date.now();
-  logToFile('INFO', `null_risks: querying firstMethod=${firstMethod || '(all)'} limit=${limit}`);
-  const db = new DatabaseSync(dbPath, { open: true });
-  let rows;
-  try {
-    if (firstMethod) {
-      rows = db.prepare(
-        'SELECT file, line, chain, second_method FROM method_chains WHERE has_null_guard = 0 AND first_method = ? ORDER BY file, line LIMIT ?'
-      ).all(firstMethod, limit);
-    } else {
-      rows = db.prepare(
-        'SELECT file, line, chain, first_method, second_method FROM method_chains WHERE has_null_guard = 0 ORDER BY first_method, file, line LIMIT ?'
-      ).all(limit);
-    }
-  } finally {
-    db.close();
-  }
-  logToFile('INFO', `null_risks: ${rows.length} unsafe chain(s) found in ${Date.now() - queryStart}ms`);
-  return rows;
-}
-
-// ─── AST Search (semgrep) ───────────────────────────────────────
-
-async function astSearch(pattern, searchPath, lang, maxResults) {
+async function astSearch(patternName, searchPath, maxResults) {
   const root = config.magentoRoot;
   if (!root) throw new Error('MAGENTO_ROOT not set');
 
-  const targetPath = searchPath ? safePath(root, searchPath) : path.resolve(root);
-  if (!targetPath) {
-    logToFile('WARN', `ast_search: rejected path traversal attempt: "${searchPath}"`);
-    throw new Error(`Path escapes project root: ${searchPath}`);
-  }
-  const semgrepLang = lang || 'php';
-  const limit = Math.min(maxResults || 50, 200);
-
-  logToFile('INFO', `ast_search: pattern="${pattern}" path="${searchPath || '.'}" lang=${semgrepLang} limit=${limit}`);
-  const astStart = Date.now();
-
-  // Semgrep's default ignore list includes "vendor/" which is exactly what we need to scan.
-  // Semgrep resolves .semgrepignore from the git repo root, NOT the scan directory.
-  // An empty .semgrepignore at root overrides the defaults: https://semgrep.dev/docs/ignoring-files-folders-code/
-  const semgrepIgnorePath = path.join(root, '.semgrepignore');
-  let createdSemgrepIgnore = false;
-  if (!existsSync(semgrepIgnorePath)) {
-    try {
-      writeFileSync(semgrepIgnorePath, '# Magector: scan vendor/ and all project files\n');
-      createdSemgrepIgnore = true;
-      logToFile('INFO', `ast_search: created temporary .semgrepignore at ${root}`);
-    } catch (err) {
-      logToFile('WARN', `ast_search: failed to create .semgrepignore: ${err.message}`);
-    }
-  }
-
-  const semgrepArgs = [
-    '--pattern', pattern,
-    '--lang', semgrepLang,
-    '--json',
-    '--no-git-ignore',
-    targetPath
-  ];
+  const safeSp = searchPath ? safeRelPath(root, searchPath) : '.';
+  if (searchPath && !safeSp) throw new Error(`Path escapes project root: ${searchPath}`);
 
-  let rawOutput;
-  try {
-    rawOutput = execFileSync('semgrep', semgrepArgs, {
-      encoding: 'utf-8',
-      timeout: 60000,
-      maxBuffer: 20 * 1024 * 1024,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, PATH: process.env.PATH + ':/home/swed/.local/bin' }
-    });
-  } catch (err) {
-    // semgrep exits non-zero when it has findings — stdout still contains valid JSON
-    rawOutput = err.stdout || '';
-    if (!rawOutput) {
-      const errMsg = (err.stderr || err.message || '').slice(0, 500);
-      logToFile('ERR', `ast_search: semgrep failed after ${Date.now() - astStart}ms: ${errMsg}`);
-      throw new Error(`semgrep failed: ${errMsg}`);
-    }
-  } finally {
-    if (createdSemgrepIgnore) { try { unlinkSync(semgrepIgnorePath); } catch { /* best effort */ } }
-  }
+  const limit = Math.min(maxResults || 50, 200);
+  logToFile('INFO', `ast_search: pattern="${patternName}" path="${safeSp}" limit=${limit}`);
+  const start = Date.now();
 
-  let parsed;
-  try {
-    parsed = JSON.parse(rawOutput);
-  } catch {
-    logToFile('ERR', `ast_search: failed to parse semgrep JSON output (${rawOutput.length} bytes)`);
-    throw new Error(`Failed to parse semgrep output. First 300 chars: ${rawOutput.slice(0, 300)}`);
-  }
+  const resp = await serveQuery('ast_query', { pattern: patternName, path: safeSp, limit }, 60000);
+  if (!resp.ok) throw new Error(resp.error || 'ast_query failed');
 
-  const findings = (parsed.results || []).slice(0, limit);
-  const astElapsed = Date.now() - astStart;
-  logToFile('INFO', `ast_search: ${findings.length} match(es) in ${astElapsed}ms (semgrep returned ${(parsed.results || []).length} total)`);
-  if (parsed.errors && parsed.errors.length > 0) {
-    logToFile('WARN', `ast_search: semgrep reported ${parsed.errors.length} error(s): ${parsed.errors.slice(0, 3).map(e => e.message || e.type || JSON.stringify(e)).join('; ')}`);
-  }
-  return findings.map(r => {
-    // semgrep >=1.100 may return "requires login" in r.extra.lines for unlicensed installs.
-    // Fall back to r.extra.message which contains the matched expression (always available).
-    const rawLines = r.extra?.lines || '';
-    const snippet = (rawLines && rawLines !== 'requires login')
-      ? rawLines.trim()
-      : (r.extra?.message || '').trim();
-    return {
-      file: r.path.replace(root + '/', ''),
-      line: r.start.line,
-      endLine: r.end.line,
-      snippet
-    };
-  });
+  const elapsed = Date.now() - start;
+  const results = resp.data || [];
+  logToFile('INFO', `ast_search: ${results.length} match(es) in ${elapsed}ms`);
+  return results;
 }
 
 // ─── DataObject set-null Anti-pattern Detection ─────────────────
 
 async function findDataObjectIssues(searchPath, maxResults) {
-  // Detects DataObject::setX(null) anti-pattern:
-  //   setX(null) stores ['x' => null] in _data — key EXISTS with null value.
-  //   hasX() / hasData('x') calls array_key_exists() → returns true even for null.
-  //   This causes false-positive guard conditions: hasX() passes, getX() returns null.
-  //   Correct way to fully clear: unsetData('x') removes the key entirely.
-  const allResults = await astSearch('$X->$SETTER(null)', searchPath, 'php', 500);
-  const setterNullRegex = /->set[A-Z]\w+\s*\(\s*null\s*\)/;
-  const limit = Math.min(maxResults || 100, 500);
-  return allResults.filter(r => setterNullRegex.test(r.snippet)).slice(0, limit);
+  return astSearch('dataobject-set-null', searchPath, maxResults || 100);
 }
 
 // ─── MCP Server ─────────────────────────────────────────────────
@@ -3819,7 +3635,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: 'magento_search',
-      description: 'Search Magento codebase semantically — find any PHP class, method, XML config, PHTML template, JS file, or GraphQL schema by describing what you need in natural language. Use this as a general-purpose search when no specialized tool fits. See also: magento_find_class, magento_find_method, magento_find_config for targeted searches.',
+      description: 'Search Magento codebase semantically — find any PHP class, method, XML config, PHTML template, JS file, or GraphQL schema by describing what you need in natural language. Use this as a general-purpose search when no specialized tool fits. Works best for Magento core and popular vendor modules. For small/custom project-specific modules (e.g. proprietary modules not widely known to the embedding model), use magento_grep instead — semantic search may return 0 results for these. See also: magento_find_class, magento_find_method, magento_find_config for targeted searches.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -4466,7 +4282,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_batch',
-      description: 'Execute multiple Magector tool calls in a single request to reduce MCP round-trip overhead. Each query runs in parallel and returns combined results. Use this when you need 2+ independent lookups (e.g., find a class AND its plugins AND its observers in one call instead of three).',
+      description: 'Execute multiple Magector tool calls in a single request to reduce MCP round-trip overhead. Each query runs in parallel and returns combined results. Use this when you need 2+ independent lookups (e.g., find a class AND its plugins AND its observers in one call instead of three). Supported tools: magento_search, magento_find_class, magento_find_method, magento_find_plugin, magento_find_observer, magento_find_config, magento_find_event_flow, magento_find_di_wiring, magento_find_callers, magento_find_preference, magento_find_fieldset, magento_module_structure, magento_trace_dependency, magento_impact_analysis, magento_grep, magento_read, magento_ast_search, magento_find_dataobject_issues, magento_find_null_risks.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -4532,23 +4348,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_ast_search',
-      description: 'Structural PHP code search using semgrep patterns. Unlike magento_grep (text-based), this understands PHP AST — matches code structure regardless of variable names, ignores comments/strings, understands operator precedence. Use when grep gives false positives or you need structural awareness. Pattern syntax: $X = any expression/variable, $Y = any identifier, ... = any arguments. Examples: "$ORDER->getPayment()->$M(...)" finds all method calls on payment regardless of variable name; "$X->getPayment()->$Y(...)" finds all two-step chains involving getPayment. ⚡ For multi-query workflows use magento_batch.',
+      description: 'Structural PHP code search using tree-sitter AST queries. Unlike magento_grep (text-based), this understands PHP AST — matches code structure regardless of variable names, ignores comments/strings. Available named patterns: "dataobject-set-null" (finds ->setX(null) anti-pattern calls), "unchecked-method-chain" (finds ->a()->b() chains without null guards). Uses Rust tree-sitter for fast, accurate parsing. ⚡ For multi-query workflows use magento_batch.',
       inputSchema: {
         type: 'object',
         properties: {
           pattern: {
             type: 'string',
-            description: 'Semgrep PHP pattern. $X = any expr, $Y = any identifier, ... = any args. Examples: "$X->getPayment()->$Y(...)", "if ($X !== null) { ... $X->$Y(...) }", "$X = $Y->getPayment(); ... $X->$Z(...)"'
+            enum: ['dataobject-set-null', 'unchecked-method-chain'],
+            description: 'Named AST query pattern. "dataobject-set-null": finds ->setX(null) calls on DataObjects. "unchecked-method-chain": finds ->a()->b() chains without null guards.'
           },
           path: {
             type: 'string',
             description: 'Subdirectory to search (relative to MAGENTO_ROOT). Default: entire codebase. Example: "vendor/acme/"'
           },
-          lang: {
-            type: 'string',
-            description: 'Language to search (default: php). Options: php, xml, js.',
-            default: 'php'
-          },
           maxResults: {
             type: 'number',
             description: 'Maximum matches to return (default: 50, max: 200)',
@@ -4578,12 +4390,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_enrich',
-      description: 'Build the method-chain enrichment index. Scans all vendor/ PHP files for two-step method chains (->firstMethod()->secondMethod()) and analyses whether each call has a null guard in surrounding code. Results stored in .magector/enrichment.db. Run this once after magento_index, then use magento_find_null_risks for instant O(1) null-safety queries instead of 20+ grep calls. Also runs automatically after magento_index completes.',
+      description: 'Build the method-chain enrichment index. Scans all vendor/ PHP files for two-step method chains (->firstMethod()->secondMethod()) and analyses whether each call has a null guard in surrounding code. Results stored in .magector/data.db. Run this once after magento_index, then use magento_find_null_risks for instant O(1) null-safety queries instead of 20+ grep calls. Also runs automatically after magento_index completes.',
       inputSchema: { type: 'object', properties: {} }
     },
     {
       name: 'magento_find_null_risks',
-      description: 'Find method chains without null guards using the pre-built enrichment index. Returns all ->firstMethod()->secondMethod() calls where no null check (=== null, !== null, ?->, ??, isset, is_null) was detected in surrounding code. Requires magento_enrich to have been run first. 100× faster than grep — O(1) SQLite query vs O(n) file scan. Use firstMethod to filter (e.g., "getPayment" finds all ->getPayment()->anything() without null guard). ⚡ For multi-query workflows use magento_batch.',
+      description: 'Find method chains without null guards using the pre-built enrichment index. Returns all ->firstMethod()->secondMethod() calls where no null check (=== null, !== null, ?->, ??, isset, is_null) was detected in surrounding code. Requires magento_enrich to have been run first (magento_index triggers it automatically in the background). 100× faster than grep — O(1) SQLite query vs O(n) file scan. Use firstMethod to filter (e.g., "getPayment" finds all ->getPayment()->anything() without null guard). ⚡ For multi-query workflows use magento_batch.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -4928,10 +4740,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'magento_index': {
         const root = args.path || config.magentoRoot;
         const output = rustIndex(root);
-        // Auto-enrich after indexing: runs in background, doesn't block response
+        // Auto-enrich after indexing: runs in background via Rust serve, doesn't block response
         logToFile('INFO', 'Auto-enrich: starting in background after index');
-        enrichMethodChains(root).then(({ scanned, chains }) => {
-          logToFile('INFO', `Auto-enrich complete: ${scanned} files, ${chains} chains`);
+        serveQuery('enrich', { magento_root: root }, 120000).then(resp => {
+          if (resp.ok) {
+            logToFile('INFO', `Auto-enrich complete: ${resp.data.scanned} files, ${resp.data.chains} chains`);
+          } else {
+            logToFile('WARN', `Auto-enrich failed: ${resp.error}`);
+          }
         }).catch(err => {
           logToFile('WARN', `Auto-enrich failed: ${err.message}`);
         });
@@ -5388,43 +5204,63 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'magento_module_structure': {
-        const raw = await rustSearchAsync(args.moduleName, 200);
-        // Support both app/code (Magento/Catalog/) and vendor (module-catalog/) paths
-        const modulePath = args.moduleName.replace('_', '/') + '/';
         const parts = args.moduleName.split('_');
+        // Support both app/code (Magento/Catalog/) and vendor (magento/module-catalog/) paths
+        const modulePath = args.moduleName.replace('_', '/') + '/';
         // Hyphenate camelCase for vendor path: OrderSplit → order-split
+        const vendorDir = parts.length === 2 ? parts[0].toLowerCase() : '';
         const vendorPath = parts.length === 2
           ? `module-${parts[1].replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()}/`
           : '';
-        let results = raw.map(normalizeResult).filter(r => {
-          const p = r.path || '';
-          const mod = r.module || '';
-          // Exact module match or directory-level path match (trailing slash prevents Catalog matching CatalogRule)
-          return mod === args.moduleName ||
-            p.includes(modulePath) ||
-            (vendorPath && p.toLowerCase().includes(vendorPath));
-        });
-
-        // Filesystem fallback: if vector search found nothing, glob the module directory
-        if (results.length === 0 && config.magentoRoot && vendorPath) {
-          logToFile('INFO', `module_structure: vector search returned 0 results for "${args.moduleName}" — using filesystem fallback (glob ${vendorPath})`);
-          try {
-            const vendorGlob = `**/${vendorPath}**/*.{php,xml,phtml}`;
-            const files = await glob(vendorGlob, { cwd: config.magentoRoot, absolute: false, nodir: true });
-            for (const f of files.slice(0, 100)) {
-              const entry = { path: f, score: 0.5 };
-              if (f.includes('/Controller/')) entry.isController = true;
-              if (f.includes('/Model/')) entry.isModel = true;
-              if (f.includes('/Block/')) entry.isBlock = true;
-              if (f.includes('/Plugin/')) entry.isPlugin = true;
-              if (f.includes('/Observer/')) entry.isObserver = true;
-              if (f.endsWith('.xml')) entry.type = 'xml';
-              // Extract class name from path
-              const phpMatch = f.match(/\/([A-Z]\w+)\.php$/);
-              if (phpMatch) entry.className = phpMatch[1];
-              results.push(entry);
+        let results = [];
+
+        // Primary: filesystem-based (authoritative — avoids mixing cross-references from vector search)
+        if (config.magentoRoot) {
+          const fsGlobs = [];
+          if (parts.length === 2) {
+            // app/code/{Vendor}/{Module}/
+            fsGlobs.push(`app/code/${parts[0]}/${parts[1]}/**/*.{php,xml,phtml}`);
+            // vendor/{vendor-lower}/{module-lower}/ — vendor-specific to avoid false positives
+            if (vendorDir && vendorPath) {
+              fsGlobs.push(`vendor/${vendorDir}/${vendorPath}**/*.{php,xml,phtml}`);
             }
-          } catch {}
+          }
+          for (const globPattern of fsGlobs) {
+            try {
+              const files = await glob(globPattern, { cwd: config.magentoRoot, absolute: false, nodir: true });
+              if (files.length > 0) {
+                logToFile('INFO', `module_structure: filesystem found ${files.length} files for "${args.moduleName}" (${globPattern})`);
+                for (const f of files.slice(0, 100)) {
+                  const entry = { path: f, score: 1.0 };
+                  if (f.includes('/Controller/')) entry.isController = true;
+                  if (f.includes('/Model/')) entry.isModel = true;
+                  if (f.includes('/Block/')) entry.isBlock = true;
+                  if (f.includes('/Plugin/')) entry.isPlugin = true;
+                  if (f.includes('/Observer/')) entry.isObserver = true;
+                  if (f.endsWith('.xml')) entry.type = 'xml';
+                  const phpMatch = f.match(/\/([A-Z]\w+)\.php$/);
+                  if (phpMatch) entry.className = phpMatch[1];
+                  results.push(entry);
+                }
+                break; // Found in one location, stop
+              }
+            } catch {}
+          }
+        }
+
+        // Fallback: vector search with strict path/module filtering (only if filesystem found nothing)
+        if (results.length === 0) {
+          logToFile('INFO', `module_structure: filesystem found 0 files for "${args.moduleName}" — falling back to vector search`);
+          const raw = await rustSearchAsync(args.moduleName, 200);
+          results = raw.map(normalizeResult).filter(r => {
+            const p = r.path || '';
+            const mod = r.module || '';
+            // Exact module match or directory-level path match (trailing slash prevents Catalog matching CatalogRule)
+            return mod === args.moduleName ||
+              p.includes(modulePath) ||
+              // Vendor-specific path check to avoid matching other vendors' same-named modules
+              (vendorDir && vendorPath && p.toLowerCase().includes(`${vendorDir}/${vendorPath}`));
+          });
         }
 
         const structure = {
@@ -6370,6 +6206,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 break;
               }
+              case 'magento_find_config': {
+                let cfgQuery = a.query;
+                if (a.configType && a.configType !== 'other') cfgQuery = `${a.configType}.xml xml config ${a.query}`;
+                const cfgRaw = await rustSearchAsync(cfgQuery, 100);
+                let cfgRes = cfgRaw.map(normalizeResult).filter(r =>
+                  r.type === 'xml' || r.path?.endsWith('.xml') || r.path?.includes('.xml')
+                );
+                if (a.configType && a.configType !== 'other') {
+                  const cfgTypeFile = `${a.configType}.xml`;
+                  const cfgTyped = cfgRes.filter(r => r.path?.includes(cfgTypeFile));
+                  if (cfgTyped.length >= 3) cfgRes = cfgTyped;
+                }
+                text = formatSearchResults(cfgRes.slice(0, 10));
+                break;
+              }
               case 'magento_trace_dependency': {
                 const dep = await traceDependency(a.className, a.direction || 'both');
                 text = `Preferences: ${dep.preferences.length}, Plugins: ${dep.plugins.length}, VirtualTypes: ${dep.virtualTypes.length}, Args: ${dep.argumentOverrides.length}\n`;
@@ -6459,35 +6310,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 break;
               }
               case 'magento_module_structure': {
-                const raw = await rustSearchAsync(a.moduleName, 200);
-                const modulePath = a.moduleName.replace('_', '/') + '/';
                 const mParts = a.moduleName.split('_');
-                // Hyphenate camelCase for vendor path: OrderSplit → order-split
+                const modulePath = a.moduleName.replace('_', '/') + '/';
+                const mVendorDir = mParts.length === 2 ? mParts[0].toLowerCase() : '';
                 const vendorPath = mParts.length === 2
                   ? `module-${mParts[1].replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()}/`
                   : '';
-                let res = raw.map(normalizeResult).filter(r => {
-                  const p = r.path || '';
-                  const mod = r.module || '';
-                  return mod === a.moduleName || p.includes(modulePath) || (vendorPath && p.toLowerCase().includes(vendorPath));
-                });
-                // Filesystem fallback
-                if (res.length === 0 && config.magentoRoot && vendorPath) {
-                  try {
-                    const vendorGlob = `**/${vendorPath}**/*.{php,xml,phtml}`;
-                    const files = await glob(vendorGlob, { cwd: config.magentoRoot, absolute: false, nodir: true });
-                    for (const f of files.slice(0, 100)) {
-                      const entry = { path: f, score: 0.5 };
-                      if (f.includes('/Controller/')) entry.isController = true;
-                      if (f.includes('/Model/')) entry.isModel = true;
-                      if (f.includes('/Plugin/')) entry.isPlugin = true;
-                      if (f.includes('/Observer/')) entry.isObserver = true;
-                      if (f.endsWith('.xml')) entry.type = 'xml';
-                      const phpMatch = f.match(/\/([A-Z]\w+)\.php$/);
-                      if (phpMatch) entry.className = phpMatch[1];
-                      res.push(entry);
+                let res = [];
+                // Primary: filesystem-based (avoids mixing cross-references)
+                if (config.magentoRoot) {
+                  const msGlobs = [];
+                  if (mParts.length === 2) {
+                    msGlobs.push(`app/code/${mParts[0]}/${mParts[1]}/**/*.{php,xml,phtml}`);
+                    if (mVendorDir && vendorPath) {
+                      msGlobs.push(`vendor/${mVendorDir}/${vendorPath}**/*.{php,xml,phtml}`);
                     }
-                  } catch {}
+                  }
+                  for (const gp of msGlobs) {
+                    try {
+                      const files = await glob(gp, { cwd: config.magentoRoot, absolute: false, nodir: true });
+                      if (files.length > 0) {
+                        for (const f of files.slice(0, 100)) {
+                          const entry = { path: f, score: 1.0 };
+                          if (f.includes('/Controller/')) entry.isController = true;
+                          if (f.includes('/Model/')) entry.isModel = true;
+                          if (f.includes('/Plugin/')) entry.isPlugin = true;
+                          if (f.includes('/Observer/')) entry.isObserver = true;
+                          if (f.endsWith('.xml')) entry.type = 'xml';
+                          const phpMatch = f.match(/\/([A-Z]\w+)\.php$/);
+                          if (phpMatch) entry.className = phpMatch[1];
+                          res.push(entry);
+                        }
+                        break;
+                      }
+                    } catch {}
+                  }
+                }
+                // Fallback: vector search with vendor-specific path filtering
+                if (res.length === 0) {
+                  const raw = await rustSearchAsync(a.moduleName, 200);
+                  res = raw.map(normalizeResult).filter(r => {
+                    const p = r.path || '';
+                    const mod = r.module || '';
+                    return mod === a.moduleName ||
+                      p.includes(modulePath) ||
+                      (mVendorDir && vendorPath && p.toLowerCase().includes(`${mVendorDir}/${vendorPath}`));
+                  });
                 }
                 text = `Module: ${a.moduleName} (${res.length} files)\n`;
                 const cats = { controllers: '/Controller/', models: '/Model/', plugins: '/Plugin/', observers: '/Observer/', api: '/Api/' };
@@ -6548,27 +6416,69 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const maxRes = Math.min(a.maxResults || 30, 100);
                 const batchCtx = a.context !== undefined ? a.context : 4;
                 const batchFilesOnly = a.filesOnly || false;
-                const gArgs = batchFilesOnly ? ['-rl', '-E'] : ['-rn', '-E'];
-                if (a.ignoreCase) gArgs.push('-i');
-                if (!batchFilesOnly && batchCtx > 0) gArgs.push('-C', String(batchCtx));
-                for (const pat of expandIncludePattern(include)) gArgs.push('--include=' + pat);
-                gArgs.push('--', a.pattern, searchPath);
-                let out;
-                try {
-                  out = execFileSync('grep', gArgs, { cwd: config.magentoRoot, encoding: 'utf-8', timeout: 15000, maxBuffer: 5 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
-                } catch (err) { out = err.stdout || ''; }
-                const gLines = out.trim().split('\n').filter(Boolean);
-                if (batchFilesOnly) {
-                  text = `Files matching \`${a.pattern}\` (${gLines.length}):\n`;
-                  for (const gl of gLines.slice(0, maxRes)) text += gl + '\n';
-                } else {
-                  text = `Found ${gLines.length} matches${gLines.length > maxRes ? ` (showing ${maxRes})` : ''}:\n`;
-                  for (const gl of gLines.slice(0, maxRes)) text += gl + '\n';
+
+                // Try Rust serve grep first
+                const batchQueryFn = globalServeQuery || ((serveProcess && serveReady) ? serveQuery : null);
+                let batchGrepDone = false;
+                if (batchQueryFn) {
+                  try {
+                    const bResp = await batchQueryFn('grep', {
+                      pattern: a.pattern,
+                      magento_root: config.magentoRoot,
+                      path: searchPath,
+                      include,
+                      context: batchCtx,
+                      max_results: maxRes,
+                      files_only: batchFilesOnly,
+                      ignore_case: a.ignoreCase || false
+                    }, 15000);
+                    if (bResp.ok && bResp.data) {
+                      const bMatches = bResp.data.matches || [];
+                      const bTotal = bResp.data.total || bMatches.length;
+                      if (batchFilesOnly) {
+                        text = `Files matching \`${a.pattern}\` (${bTotal}):\n`;
+                        for (const m of bMatches) text += (m.file || m) + '\n';
+                      } else {
+                        text = `Found ${bTotal} matches${bTotal > maxRes ? ` (showing ${maxRes})` : ''}:\n`;
+                        for (const m of bMatches) {
+                          if (m.is_context) {
+                            text += `${m.file}-${m.line}-${m.text}\n`;
+                          } else {
+                            text += `${m.file}:${m.line}:${m.text}\n`;
+                          }
+                        }
+                      }
+                      batchGrepDone = true;
+                    }
+                  } catch (bErr) {
+                    logToFile('WARN', `batch grep: serve query failed, falling back to external grep: ${bErr.message}`);
+                  }
+                }
+
+                // Fallback: external GNU grep (cold-start path or serve error)
+                if (!batchGrepDone) {
+                  const gArgs = batchFilesOnly ? ['-rl', '-E'] : ['-rn', '-E'];
+                  if (a.ignoreCase) gArgs.push('-i');
+                  if (!batchFilesOnly && batchCtx > 0) gArgs.push('-C', String(batchCtx));
+                  for (const pat of expandIncludePattern(include)) gArgs.push('--include=' + pat);
+                  gArgs.push('--', a.pattern, searchPath);
+                  let out;
+                  try {
+                    out = execFileSync('grep', gArgs, { cwd: config.magentoRoot, encoding: 'utf-8', timeout: 15000, maxBuffer: 5 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
+                  } catch (err) { out = err.stdout || ''; }
+                  const gLines = out.trim().split('\n').filter(Boolean);
+                  if (batchFilesOnly) {
+                    text = `Files matching \`${a.pattern}\` (${gLines.length}):\n`;
+                    for (const gl of gLines.slice(0, maxRes)) text += gl + '\n';
+                  } else {
+                    text = `Found ${gLines.length} matches${gLines.length > maxRes ? ` (showing ${maxRes})` : ''}:\n`;
+                    for (const gl of gLines.slice(0, maxRes)) text += gl + '\n';
+                  }
                 }
                 break;
               }
               case 'magento_ast_search': {
-                const astResults = await astSearch(a.pattern, a.path, a.lang, a.maxResults);
+                const astResults = await astSearch(a.pattern, a.path, a.maxResults);
                 if (astResults.length === 0) {
                   text = `No matches for pattern: \`${a.pattern}\``;
                 } else {
@@ -6588,15 +6498,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 break;
               }
               case 'magento_find_null_risks': {
-                const bRoot = config.magentoRoot;
                 const bLimit = Math.min(a.limit || 100, 500);
-                const bRows = bRoot ? await queryNullRisks(bRoot, a.firstMethod || null, bLimit) : null;
-                if (!bRows) { text = '⚠️ Run magento_enrich first.'; break; }
-                if (bRows.length === 0) { text = 'No unsafe chains found.'; break; }
-                text = `Found ${bRows.length} unsafe chain(s):\n`;
-                for (const r of bRows.slice(0, 50)) {
-                  const chain = r.chain || `->${r.first_method}()->${r.second_method}()`;
-                  text += `${r.file}:${r.line}: ${chain}\n`;
+                try {
+                  const bResp = await serveQuery('enrich_query', { first_method: a.firstMethod || null, limit: bLimit }, 30000);
+                  if (!bResp.ok) { text = `⚠️ ${bResp.error || 'Query failed'}`; break; }
+                  const bRows = bResp.data || [];
+                  if (bRows.length === 0) { text = 'No unsafe chains found.'; break; }
+                  text = `Found ${bRows.length} unsafe chain(s):\n`;
+                  for (const r of bRows.slice(0, 50)) {
+                    const chain = r.chain || `->${r.first_method}()->${r.second_method}()`;
+                    text += `${r.file}:${r.line}: ${chain}\n`;
+                  }
+                } catch (bErr) {
+                  text = '⚠️ Run magento_enrich first.';
                 }
                 break;
               }
@@ -6630,6 +6544,51 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const maxResults = Math.min(args.maxResults || 50, 200);
         const ctxLines = args.context !== undefined ? args.context : 4;
         const filesOnly = args.filesOnly || false;
+        const grepStart = Date.now();
+
+        // Try Rust serve grep first
+        const queryFn = globalServeQuery || ((serveProcess && serveReady) ? serveQuery : null);
+        let output = null;
+        if (queryFn) {
+          try {
+            const resp = await queryFn('grep', {
+              pattern: args.pattern,
+              magento_root: root,
+              path: searchPath,
+              include,
+              context: ctxLines,
+              max_results: maxResults,
+              files_only: filesOnly,
+              ignore_case: args.ignoreCase || false
+            }, 30000);
+            if (resp.ok && resp.data) {
+              const matches = resp.data.matches || [];
+              const total = resp.data.total || matches.length;
+              const grepElapsed = Date.now() - grepStart;
+              if (grepElapsed > 5000) logToFile('WARN', `grep: slow query "${args.pattern}" — ${total} matches in ${grepElapsed}ms`);
+
+              if (filesOnly) {
+                let text = `## grep (files only): \`${args.pattern}\`\nFound **${total}** file(s)${total > maxResults ? ` (showing first ${maxResults})` : ''}. Use magento_read with methodName to read specific methods.\n\n`;
+                for (const m of matches) text += (m.file || m) + '\n';
+                return { content: [{ type: 'text', text }] };
+              } else {
+                let text = `## grep: \`${args.pattern}\`\nFound **${total}** matches${total > maxResults ? ` (showing first ${maxResults})` : ''}\n\n`;
+                for (const m of matches) {
+                  if (m.is_context) {
+                    text += `${m.file}-${m.line}-${m.text}\n`;
+                  } else {
+                    text += `${m.file}:${m.line}:${m.text}\n`;
+                  }
+                }
+                return { content: [{ type: 'text', text }] };
+              }
+            }
+          } catch (err) {
+            logToFile('WARN', `grep: serve query failed, falling back to external grep: ${err.message}`);
+          }
+        }
+
+        // Fallback: external GNU grep (cold-start path or serve error)
         const grepArgs = filesOnly ? ['-rl', '-E'] : ['-rn', '-E'];
         if (args.ignoreCase) grepArgs.push('-i');
         if (!filesOnly && ctxLines > 0) grepArgs.push('-C', String(ctxLines));
@@ -6637,8 +6596,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           grepArgs.push('--include=' + pat);
         }
         grepArgs.push('--', args.pattern, searchPath);
-        let output;
-        const grepStart = Date.now();
         try {
           output = execFileSync('grep', grepArgs, {
             cwd: root, encoding: 'utf-8', timeout: 30000,
@@ -6859,7 +6816,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'magento_ast_search': {
-        const astResults = await astSearch(args.pattern, args.path, args.lang, args.maxResults);
+        const astResults = await astSearch(args.pattern, args.path, args.maxResults);
         if (astResults.length === 0) {
           return { content: [{ type: 'text', text: `## magento_ast_search: \`${args.pattern}\`\n\nNo matches found.` }] };
         }
@@ -6894,8 +6851,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };
         let text = `## magento_enrich\n\nScanning vendor/ PHP files for method chains...\n`;
         try {
-          const { scanned, chains } = await enrichMethodChains(root);
-          text += `\n✅ **Done**\n- Files scanned: ${scanned}\n- Method chains indexed: ${chains}\n- Null-risk index saved to: \`.magector/enrichment.db\`\n\nUse \`magento_find_null_risks\` to query unsafe chains.`;
+          const resp = await serveQuery('enrich', { magento_root: root }, 120000);
+          if (resp.ok) {
+            text += `\n✅ **Done**\n- Files scanned: ${resp.data.scanned}\n- Method chains indexed: ${resp.data.chains}\n- Null-risk index saved to: \`.magector/data.db\``;
+          } else {
+            text += `\n❌ Error: ${resp.error}`;
+          }
         } catch (err) {
           text += `\n❌ Error: ${err.message}`;
         }
@@ -6906,32 +6867,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const root = config.magentoRoot;
         if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };
         const limit = Math.min(args.limit || 100, 500);
-        const rows = await queryNullRisks(root, args.firstMethod || null, limit);
-        if (rows === null) {
-          return { content: [{ type: 'text', text: `## magento_find_null_risks\n\n⚠️ Enrichment index not found. Run \`magento_enrich\` first to build the method-chain index.` }] };
-        }
-        if (rows.length === 0) {
+        try {
+          const resp = await serveQuery('enrich_query', { first_method: args.firstMethod || null, limit }, 30000);
+          if (!resp.ok) {
+            return { content: [{ type: 'text', text: `## magento_find_null_risks\n\n⚠️ ${resp.error || 'Query failed'}` }] };
+          }
+          const rows = resp.data || [];
+          if (rows.length === 0) {
+            const filter = args.firstMethod ? ` for \`->${args.firstMethod}()\`` : '';
+            return { content: [{ type: 'text', text: `## magento_find_null_risks${filter}\n\nNo unsafe chains found. All detected chains have null guards.` }] };
+          }
           const filter = args.firstMethod ? ` for \`->${args.firstMethod}()\`` : '';
-          return { content: [{ type: 'text', text: `## magento_find_null_risks${filter}\n\nNo unsafe chains found. All detected chains have null guards.` }] };
-        }
-        const filter = args.firstMethod ? ` for \`->${args.firstMethod}()\`` : '';
-        let text = `## magento_find_null_risks${filter}\n\nFound **${rows.length}** chain(s) without null guard:\n\n`;
-        // Group by chain type for readability
-        const byChain = {};
-        for (const r of rows) {
-          const key = r.chain || `->${r.first_method}()->${r.second_method}()`;
-          if (!byChain[key]) byChain[key] = [];
-          byChain[key].push(r);
-        }
-        for (const [chain, sites] of Object.entries(byChain)) {
-          text += `### \`${chain}\` (${sites.length} site${sites.length > 1 ? 's' : ''})\n`;
-          for (const s of sites.slice(0, 20)) {
-            text += `- \`${s.file}:${s.line}\`\n`;
-          }
-          if (sites.length > 20) text += `- ... and ${sites.length - 20} more\n`;
-          text += '\n';
+          let text = `## magento_find_null_risks${filter}\n\nFound **${rows.length}** chain(s) without null guard:\n\n`;
+          // Group by chain type for readability
+          const byChain = {};
+          for (const r of rows) {
+            const key = r.chain || `->${r.first_method}()->${r.second_method}()`;
+            if (!byChain[key]) byChain[key] = [];
+            byChain[key].push(r);
+          }
+          for (const [chain, sites] of Object.entries(byChain)) {
+            text += `### \`${chain}\` (${sites.length} site${sites.length > 1 ? 's' : ''})\n`;
+            for (const s of sites.slice(0, 20)) {
+              text += `- \`${s.file}:${s.line}\`\n`;
+            }
+            if (sites.length > 20) text += `- ... and ${sites.length - 20} more\n`;
+            text += '\n';
+          }
+          return { content: [{ type: 'text', text }] };
+        } catch (err) {
+          return { content: [{ type: 'text', text: `## magento_find_null_risks\n\n⚠️ Enrichment index not found. Run \`magento_enrich\` first.` }] };
         }
-        return { content: [{ type: 'text', text }] };
       }
 
       default: