magector 2.16.6 → 2.16.9

package/README.md

@@ -2,7 +2,7 @@
 
 **Technology-aware MCP server for Magento 2 and Adobe Commerce with intelligent indexing and search.**
 
-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).
+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 47 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-18+-green.svg)](https://nodejs.org)
@@ -58,7 +58,7 @@ The result: your AI assistant calls one MCP tool and gets ranked, pattern-enrich
 - **Complexity analysis** -- cyclomatic complexity, function count, and hotspot detection across modules
 - **Fast** -- 10-45ms queries via persistent serve process, batched ONNX embedding with adaptive thread scaling
 - **LLM description enrichment** -- generate natural-language descriptions of di.xml files using Claude, stored in SQLite, and prepend them to embedding text so descriptions influence vector search ranking (not just post-retrieval display)
-- **MCP server** -- 46 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
+- **MCP server** -- 47 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
 - **Clean architecture** -- Rust core handles all indexing/search, Node.js MCP server delegates to it
 
 ---
@@ -70,7 +70,7 @@ flowchart LR
   subgraph node ["Node.js Layer"]
     direction TB
     G["CLI<br/>init · index · search · describe"]
-    E["MCP Server<br/>46 tools · LRU cache"]
+    E["MCP Server<br/>47 tools · LRU cache"]
     F["Persistent Serve Process"]
     G --> F
     E --> F
@@ -132,6 +132,7 @@ flowchart LR
 | 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 |
+| Config data | JSON exports in `.magector/config-data/` | One-time `core_config_data` exports per environment for config tracing |
 
 ---
 
@@ -400,7 +401,7 @@ npx magector index --force
 
 ## MCP Server Tools
 
-The MCP server exposes 46 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
+The MCP server exposes 47 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
 
 ### Output Format
 
@@ -508,6 +509,7 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 | `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)** |
 | `magento_read` | Read a specific file with optional `methodName` extraction (~10× fewer tokens than reading the whole file) and `startLine`/`endLine` range. **(v2.10)** |
 | `magento_trace_api` | Trace REST/GraphQL API endpoint from URL to implementation: webapi.xml → service interface → DI preference → method body. One call replaces 4-5 grep+read steps. **(v2.11)** |
+| `magento_trace_config` | Trace a config path end-to-end: system.xml admin definition → PHP classes that consume the value → actual DB values from config-data exports. Accepts exact path or keyword search. **(v2.17)** |
 | `magento_find_trigger` | Find database triggers across the codebase |
 | `magento_find_table_usage` | Find all PHP code referencing a specific database table |
 
@@ -702,7 +704,7 @@ cd rust-core && cargo run --release -- validate -m ./magento2 --skip-index
 magector/
 ├── src/                          # Node.js source
 │   ├── cli.js                    # CLI entry point (npx magector <command>)
-│   ├── mcp-server.js             # MCP server (46 tools, structured JSON output)
+│   ├── mcp-server.js             # MCP server (47 tools, structured JSON output)
 │   ├── binary.js                 # Platform binary resolver
 │   ├── model.js                  # ONNX model resolver/downloader
 │   ├── init.js                   # Full init command (index + IDE config)
@@ -1022,6 +1024,25 @@ lib/internal
 - Patterns without `/` match directory names anywhere in the tree
 - Patterns with `/` match relative paths from the project root
 
+### Config Data (core_config_data exports)
+
+The `magento_trace_config` tool can show actual database config values alongside code analysis. Export your `core_config_data` table as JSON and place files in `.magector/config-data/`:
+
+```bash
+# Export from MySQL (one-time per environment)
+mysql -u user -p magento_db -e "SELECT scope, scope_id, path, value FROM core_config_data" --json > .magector/config-data/CZ-production.json
+
+# Or from n8n/API/any tool that produces:
+# [{scope, scope_id, path, value}, ...]
+```
+
+**File naming:** Use `{country}-{environment}.json`, e.g.:
+- `CZ-production.json`
+- `SK-staging.json`
+- `IT-production.json`
+
+When `magento_trace_config` traces a config path, it automatically looks up values from all available exports and shows them per environment.
+
 ### Model Configuration
 
 The ONNX model (`all-MiniLM-L6-v2`) is automatically downloaded on first run to `~/.magector/models/`. To use a different location:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "2.16.6",
+  "version": "2.16.9",
   "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.16.6",
-    "@magector/cli-linux-x64": "2.16.6",
-    "@magector/cli-linux-arm64": "2.16.6",
-    "@magector/cli-win32-x64": "2.16.6"
+    "@magector/cli-darwin-arm64": "2.16.9",
+    "@magector/cli-linux-x64": "2.16.9",
+    "@magector/cli-linux-arm64": "2.16.9",
+    "@magector/cli-win32-x64": "2.16.9"
   },
   "keywords": [
     "magento",

package/src/mcp-server.js

@@ -17,7 +17,7 @@ import {
 import { execFileSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
 import { createServer as createNetServer, createConnection } from 'net';
-import { existsSync, statSync, unlinkSync, copyFileSync, renameSync, appendFileSync, writeFileSync, readFileSync, mkdirSync, openSync, closeSync, chmodSync, constants as fsConstants } from 'fs';
+import { existsSync, statSync, unlinkSync, copyFileSync, renameSync, appendFileSync, writeFileSync, readFileSync, readdirSync, mkdirSync, openSync, closeSync, chmodSync, constants as fsConstants } from 'fs';
 import { stat } from 'fs/promises';
 import { glob } from 'glob';
 import path from 'path';
@@ -67,6 +67,68 @@ async function loadDescriptions() {
 
 }
 
+// ─── Config Data (core_config_data exports) ─────────────────────
+// One-time JSON exports from core_config_data, stored per environment.
+// Directory: .magector/config-data/
+// Files: {label}.json, e.g. "CZ-production.json", "SK-staging.json"
+// Format: [{scope, scope_id, path, value}, ...]
+
+let configDataCache = null;
+
+function getConfigDataDir() {
+  return path.join(config.magentoRoot, '.magector', 'config-data');
+}
+
+function loadAllConfigData() {
+  if (configDataCache) return configDataCache;
+  const dir = getConfigDataDir();
+  configDataCache = {};
+  try {
+    if (!existsSync(dir)) return configDataCache;
+    const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+    for (const file of files) {
+      const label = file.replace(/\.json$/, '');
+      try {
+        const data = JSON.parse(readFileSync(path.join(dir, file), 'utf-8'));
+        configDataCache[label] = Array.isArray(data) ? data : [];
+      } catch {
+        // Skip malformed files
+      }
+    }
+  } catch {
+    // Directory doesn't exist yet — that's fine
+  }
+  return configDataCache;
+}
+
+function lookupConfigValues(configPath) {
+  const allData = loadAllConfigData();
+  const results = [];
+  for (const [env, rows] of Object.entries(allData)) {
+    const matches = rows.filter(r => r.path === configPath);
+    if (matches.length > 0) {
+      results.push({ environment: env, values: matches });
+    }
+  }
+  return results;
+}
+
+function searchConfigData(keyword) {
+  const allData = loadAllConfigData();
+  const kw = keyword.toLowerCase();
+  const results = [];
+  for (const [env, rows] of Object.entries(allData)) {
+    const matches = rows.filter(r =>
+      (r.path && r.path.toLowerCase().includes(kw)) ||
+      (r.value && String(r.value).toLowerCase().includes(kw))
+    );
+    if (matches.length > 0) {
+      results.push({ environment: env, values: matches });
+    }
+  }
+  return results;
+}
+
 // ─── Logging ─────────────────────────────────────────────────────
 // All activity is logged to .magector/magector.log.
 
@@ -933,7 +995,7 @@ function tryConnectSocket() {
         if (socketBusy || socketQueryQueue.length === 0) return;
         socketBusy = true;
         const { command, params, timeoutMs, resolve: qResolve, reject: qReject } = socketQueryQueue.shift();
-        const timer = setTimeout(() => { pendingResolve = null; qReject(new Error('Socket query timeout')); socketBusy = false; processSocketQueue(); }, timeoutMs);
+        const timer = setTimeout(() => { pendingResolve = null; qReject(new Error('Socket query timeout')); socketBusy = false; processSocketQueue(); }, timeoutMs || 30000);
         pendingResolve = (resp) => { clearTimeout(timer); qResolve(resp); socketBusy = false; processSocketQueue(); };
         try {
           conn.write(JSON.stringify({ command, params, timeout: timeoutMs }) + '\n');
@@ -947,8 +1009,8 @@ function tryConnectSocket() {
       }
 
       // Replace the global serveQuery with socket-based version
-      globalServeQuery = (command, params, timeoutMs) => new Promise((res, rej) => {
-        socketQueryQueue.push({ command, params, timeoutMs, resolve: res, reject: rej });
+      globalServeQuery = (command, params, timeoutMs = 30000) => new Promise((res, rej) => {
+        socketQueryQueue.push({ command, params, timeoutMs: timeoutMs || 30000, resolve: res, reject: rej });
         processSocketQueue();
       });
 
@@ -2486,6 +2548,13 @@ function filterByModule(results, moduleFilter) {
   });
 }
 
+function excludeByModule(results, excludeFilter) {
+  if (!excludeFilter) return results;
+  // Use filterByModule to find what TO exclude, then remove those
+  const toExclude = new Set(filterByModule(results, excludeFilter).map(r => r.path));
+  return results.filter(r => !toExclude.has(r.path));
+}
+
 // ─── Layout XML Search ──────────────────────────────────────────
 
 async function findLayout(query, handle) {
@@ -3653,6 +3722,247 @@ async function findDataObjectIssues(searchPath, maxResults) {
   return astSearch('dataobject-set-null', searchPath, maxResults || 100);
 }
 
+// ─── Config Tracing ─────────────────────────────────────────────
+// Trace a config path end-to-end: system.xml definition → PHP consumers → actual DB values
+
+async function traceConfig(configPath, keyword) {
+  const root = config.magentoRoot;
+  if (!root) return { error: 'MAGENTO_ROOT not set' };
+
+  const result = {
+    configPath: configPath || null,
+    keyword: keyword || null,
+    systemXml: [],
+    phpConsumers: [],
+    configValues: [],
+    configPhpValues: []
+  };
+
+  // If only keyword given, try to find matching config paths first
+  let pathsToTrace = [];
+  if (configPath) {
+    pathsToTrace = [configPath];
+  } else if (keyword) {
+    // Search system.xml for the keyword
+    const kw = keyword.toLowerCase();
+    try {
+      const sysXmlFiles = await glob('**/etc/adminhtml/system.xml', { cwd: root, absolute: true, nodir: true });
+      for (const f of sysXmlFiles) {
+        try {
+          const content = readFileSync(f, 'utf-8');
+          if (content.toLowerCase().includes(kw)) {
+            // Extract config paths (section/group/field ids) using nested regex
+            const sectionRegex = /<section\s+id="([^"]+)"[^>]*>([\s\S]*?)<\/section>/g;
+            let secMatch;
+            while ((secMatch = sectionRegex.exec(content)) !== null) {
+              const secId = secMatch[1];
+              const secBlock = secMatch[2];
+              const groupRegex = /<group\s+id="([^"]+)"[^>]*>([\s\S]*?)<\/group>/g;
+              let grpMatch;
+              while ((grpMatch = groupRegex.exec(secBlock)) !== null) {
+                const grpId = grpMatch[1];
+                const grpBlock = grpMatch[2];
+                const fieldRegex = /<field\s+id="([^"]+)"/g;
+                let fldMatch;
+                while ((fldMatch = fieldRegex.exec(grpBlock)) !== null) {
+                  const fullPath = `${secId}/${grpId}/${fldMatch[1]}`;
+                  if (fullPath.toLowerCase().includes(kw) || fldMatch[1].toLowerCase().includes(kw)) {
+                    if (!pathsToTrace.includes(fullPath)) pathsToTrace.push(fullPath);
+                  }
+                }
+              }
+            }
+          }
+        } catch { /* skip unreadable */ }
+      }
+    } catch { /* glob error */ }
+  }
+
+  // For each config path, find system.xml definition
+  for (const cp of pathsToTrace) {
+    const parts = cp.split('/');
+    const fieldId = parts[parts.length - 1];
+
+    // 1. Find system.xml definition
+    try {
+      const sysXmlFiles = await glob('**/etc/adminhtml/system.xml', { cwd: root, absolute: true, nodir: true });
+      for (const f of sysXmlFiles) {
+        try {
+          const content = readFileSync(f, 'utf-8');
+          if (!content.includes(`id="${fieldId}"`)) continue;
+          // Check if this is the right section/group
+          const hasSection = parts.length < 2 || content.includes(`id="${parts[0]}"`);
+          const hasGroup = parts.length < 3 || content.includes(`id="${parts[1]}"`);
+          if (!hasSection || !hasGroup) continue;
+
+          const relPath = path.relative(root, f);
+          const entry = { file: relPath, configPath: cp };
+
+          // Extract field details
+          const fieldRegex = new RegExp(`<field\\s+id="${fieldId}"[^>]*>([\\s\\S]*?)</field>`, 'g');
+          const fieldMatch = fieldRegex.exec(content);
+          if (fieldMatch) {
+            const block = fieldMatch[1];
+            const labelMatch = block.match(/<label>(.*?)<\/label>/);
+            const typeMatch = content.match(new RegExp(`<field\\s+id="${fieldId}"[^>]*type="([^"]+)"`));
+            const sourceMatch = block.match(/<source_model>(.*?)<\/source_model>/);
+            const commentMatch = block.match(/<comment>(?:<!\[CDATA\[)?(.*?)(?:\]\]>)?<\/comment>/s);
+            if (labelMatch) entry.label = labelMatch[1];
+            if (typeMatch) entry.type = typeMatch[1];
+            if (sourceMatch) entry.sourceModel = sourceMatch[1];
+            if (commentMatch) entry.comment = commentMatch[1].trim();
+          }
+          result.systemXml.push(entry);
+        } catch { /* skip */ }
+      }
+    } catch { /* glob error */ }
+
+    // 2. Find PHP consumers — classes that read this config path
+    const escapedPath = cp.replace(/[/]/g, '\\/');
+    try {
+      // Search for the config path string in PHP files (argv-array, no shell)
+      const grepArgs = ['-rn', '-l', '--include=*.php', '--', cp, root];
+      let grepOut;
+      try {
+        grepOut = execFileSync('grep', grepArgs, { encoding: 'utf-8', timeout: 15000, maxBuffer: 5 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
+      } catch (err) { grepOut = err.stdout || ''; }
+
+      const phpFiles = grepOut.trim().split('\n').filter(Boolean);
+      for (const f of phpFiles.slice(0, 20)) {
+        try {
+          const content = readFileSync(f, 'utf-8');
+          const relPath = path.relative(root, f);
+          const entry = { file: relPath };
+
+          // Extract class name
+          const nsMatch = content.match(/namespace\s+([\w\\]+)/);
+          const classMatch = content.match(/class\s+(\w+)/);
+          if (nsMatch && classMatch) entry.className = nsMatch[1] + '\\' + classMatch[1];
+
+          // Find the constant or property that holds this path
+          const constMatch = content.match(new RegExp(`(\\w+)\\s*=\\s*'${escapedPath}'`));
+          if (constMatch) entry.constant = constMatch[1];
+
+          // Find methods that use this config value
+          const methods = [];
+          const methodRegex = /(?:public|protected|private)\s+(?:static\s+)?function\s+(\w+)/g;
+          let mm;
+          while ((mm = methodRegex.exec(content)) !== null) {
+            const methodName = mm[1];
+            const body = readFullMethodBody(f, methodName);
+            if (body && (body.includes(cp) || (constMatch && body.includes(constMatch[1])))) {
+              methods.push(methodName);
+            }
+          }
+          if (methods.length > 0) entry.methods = methods;
+
+          result.phpConsumers.push(entry);
+        } catch { /* skip */ }
+      }
+    } catch { /* grep error */ }
+
+    // 3. Look up actual config values from imported data
+    const dbValues = lookupConfigValues(cp);
+    if (dbValues.length > 0) {
+      result.configValues.push({ configPath: cp, environments: dbValues });
+    }
+  }
+
+  // 4. Also check config.php for statically set values
+  if (pathsToTrace.length > 0) {
+    const configPhpPath = path.join(root, 'app/etc/config.php');
+    if (existsSync(configPhpPath)) {
+      try {
+        const configPhpContent = readFileSync(configPhpPath, 'utf-8');
+        for (const cp of pathsToTrace) {
+          const parts = cp.split('/');
+          // Check if any part of the path appears in config.php
+          if (parts.some(p => configPhpContent.includes(`'${p}'`))) {
+            result.configPhpValues.push({ configPath: cp, note: 'Path segments found in app/etc/config.php — may contain static overrides' });
+          }
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  return result;
+}
+
+function formatTraceConfigResult(result) {
+  let text = '## Config Trace';
+  if (result.configPath) text += `: \`${result.configPath}\``;
+  if (result.keyword) text += ` (keyword: "${result.keyword}")`;
+  text += '\n\n';
+
+  if (result.error) return text + `Error: ${result.error}\n`;
+
+  // System.xml definitions
+  if (result.systemXml.length > 0) {
+    text += '### Admin Configuration (system.xml)\n\n';
+    for (const s of result.systemXml) {
+      text += `**${s.label || s.configPath}**`;
+      if (s.type) text += ` (type: ${s.type})`;
+      text += `\n- File: \`${s.file}\`\n- Config path: \`${s.configPath}\`\n`;
+      if (s.sourceModel) text += `- Source model: \`${s.sourceModel}\`\n`;
+      if (s.comment) text += `- Comment: ${s.comment}\n`;
+      text += '\n';
+    }
+  } else {
+    text += '### Admin Configuration (system.xml)\nNo system.xml definition found.\n\n';
+  }
+
+  // PHP consumers
+  if (result.phpConsumers.length > 0) {
+    text += '### PHP Consumers\n\n';
+    for (const c of result.phpConsumers) {
+      text += `- \`${c.className || c.file}\``;
+      if (c.constant) text += ` (const \`${c.constant}\`)`;
+      if (c.methods?.length > 0) text += ` — methods: ${c.methods.map(m => '`' + m + '()`').join(', ')}`;
+      text += `\n  File: \`${c.file}\`\n`;
+    }
+    text += '\n';
+  } else {
+    text += '### PHP Consumers\nNo PHP files reference this config path.\n\n';
+  }
+
+  // Actual DB values
+  if (result.configValues.length > 0) {
+    text += '### Actual Values (from config-data exports)\n\n';
+    for (const cv of result.configValues) {
+      text += `**\`${cv.configPath}\`**\n`;
+      for (const env of cv.environments) {
+        text += `\n**${env.environment}:**\n`;
+        for (const v of env.values) {
+          const scope = v.scope === 'default' ? 'default' : `${v.scope} (id: ${v.scope_id})`;
+          const val = v.value === null ? '*(null)*' : (String(v.value).length > 200 ? String(v.value).slice(0, 200) + '...' : String(v.value));
+          text += `- [${scope}] = \`${val}\`\n`;
+        }
+      }
+      text += '\n';
+    }
+  } else {
+    const dataDir = getConfigDataDir();
+    let hasData = false;
+    try { hasData = existsSync(dataDir) && readdirSync(dataDir).some(f => f.endsWith('.json')); } catch {}
+    if (!hasData) {
+      text += '### Actual Values\nNo config-data exports found. Export `core_config_data` to `.magector/config-data/{env}.json` (format: `[{scope, scope_id, path, value}, ...]`).\n\n';
+    } else {
+      text += '### Actual Values\nNo matching values found in config-data exports.\n\n';
+    }
+  }
+
+  // config.php static values
+  if (result.configPhpValues.length > 0) {
+    text += '### Static Config (app/etc/config.php)\n';
+    for (const c of result.configPhpValues) {
+      text += `- \`${c.configPath}\`: ${c.note}\n`;
+    }
+    text += '\n';
+  }
+
+  return text;
+}
+
 // ─── MCP Server ─────────────────────────────────────────────────
 
 const server = new Server(
@@ -3692,6 +4002,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             ],
             description: 'Filter results by vendor/module pattern(s). Accepts a single string or array of strings. Supports wildcards and vendor prefix matching. Uses "/" or "_" interchangeably as separator. Examples: "Vendor_*", ["Acme_PaymentGateway", "Acme_FreeShipping"], "Magento_Catalog".'
           },
+          excludeModuleFilter: {
+            oneOf: [
+              { type: 'string' },
+              { type: 'array', items: { type: 'string' } }
+            ],
+            description: 'Exclude results from vendor/module pattern(s). Inverse of moduleFilter — removes matching modules from results. Same pattern syntax as moduleFilter. Useful when you know which modules are irrelevant. Examples: "Vendor_MarketplaceBase", ["Vendor_ModuleA", "Vendor_ModuleB"].'
+          },
           expand: {
             type: 'boolean',
             description: 'Enable query expansion with Magento domain synonyms for better recall (default: true)',
@@ -4470,6 +4787,23 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         }
       }
     },
+    {
+      name: 'magento_trace_config',
+      description: 'Trace a Magento config path end-to-end: finds system.xml admin definition (label, type, source_model), PHP classes that read the value, and actual DB values from config-data exports. Use when investigating config-driven behavior ("why is this feature enabled/disabled?", "what controls marketplace payment methods?"). Accepts either an exact config path or a keyword to search for.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          configPath: {
+            type: 'string',
+            description: 'Exact config path to trace. Example: "acme_marketplace/payments/marketplace_payment_methods", "payment/cashondelivery/active"'
+          },
+          keyword: {
+            type: 'string',
+            description: 'Keyword to search for in system.xml fields when exact path is unknown. Example: "marketplace_payment", "cashondelivery". Returns all matching config paths.'
+          }
+        }
+      }
+    },
     {
       name: 'magento_read',
       description: 'Read a file from the Magento codebase. Use in magento_batch to read multiple files in a single MCP call (e.g., grep finds 5 files → read all 5 in one batch). Supports line ranges and method extraction.',
@@ -4605,7 +4939,11 @@ const _callToolHandler = async (request) => {
       case 'magento_search': {
         const precise = args.precise === true;
         const searchQuery = (args.expand !== false && !precise) ? expandQuery(args.query) : args.query;
-        const raw = await rustSearchAsync(searchQuery, Math.max(args.limit || 10, precise ? 60 : 30));
+        // When moduleFilter is present, fetch more results so post-filtering has enough candidates
+        const fetchLimit = args.moduleFilter
+          ? Math.max(args.limit || 10, 200)
+          : Math.max(args.limit || 10, precise ? 60 : 30);
+        const raw = await rustSearchAsync(searchQuery, fetchLimit);
         const arr = Array.isArray(raw) ? raw : [];
         let results = arr.map(normalizeResult);
         // Hybrid BM25 rerank for better exact-match handling
@@ -4623,6 +4961,9 @@ const _callToolHandler = async (request) => {
         if (args.moduleFilter) {
           results = filterByModule(results, args.moduleFilter);
         }
+        if (args.excludeModuleFilter) {
+          results = excludeByModule(results, args.excludeModuleFilter);
+        }
         // SONA: record search with results for follow-up tracking
         sessionTracker.recordToolCall(name, args || {}, arr);
         return {
@@ -6631,6 +6972,11 @@ const _callToolHandler = async (request) => {
                 }
                 break;
               }
+              case 'magento_trace_config': {
+                const trResult = await traceConfig(a.configPath, a.keyword);
+                text = formatTraceConfigResult(trResult);
+                break;
+              }
               default:
                 text = `Unsupported batch tool: ${q.tool}`;
             }
@@ -6883,6 +7229,17 @@ const _callToolHandler = async (request) => {
         return { content: [{ type: 'text', text }] };
       }
 
+      case 'magento_trace_config': {
+        const traceResult = await traceConfig(args.configPath, args.keyword);
+        logToFile('RES', `trace_config: path=${args.configPath || 'none'} keyword=${args.keyword || 'none'} sysxml=${traceResult.systemXml?.length || 0} php=${traceResult.phpConsumers?.length || 0} values=${traceResult.configValues?.length || 0}`);
+        return {
+          content: [{
+            type: 'text',
+            text: formatTraceConfigResult(traceResult)
+          }]
+        };
+      }
+
       case 'magento_read': {
         const root = config.magentoRoot;
         if (!root) return { content: [{ type: 'text', text: 'MAGENTO_ROOT not set.' }], isError: true };

package/src/templates/claude-md.js

@@ -38,6 +38,14 @@ This project is indexed with Magector. Use the MCP tools below to search the cod
 - Include Magento terms: "plugin for save", "observer for order place"
 - Be specific: "customer address validation before checkout" not just "validation"
 
+## Analysis Patterns
+
+### Negative match audit
+When \`magento_grep\` finds a bug pattern in only SOME files of a known group (e.g. \`orderRepository->save()\` in 5 of 8 transition handlers), always read the files that DON'T match to understand why they differ. This narrows the fix scope — files with a different code path may not need fixing.
+
+### Follow up DI listings with code reads
+When \`magento_trace_dependency\` or \`magento_find_plugin\` returns a list of plugins/preferences, don't stop at the names. Use \`magento_read\` or \`Read\` to inspect the actual implementation of each — the root cause is often in a specific condition inside the plugin code, not in the DI wiring itself.
+
 ## Re-indexing
 
 After significant code changes, re-index:

package/src/templates/cursor-rules-mdc.js

@@ -40,6 +40,11 @@ Before reading files manually, ALWAYS use Magector MCP tools to find relevant co
 - Include Magento terms: "plugin for save", "observer for order place", "checkout totals collector"
 - Be specific: "customer address validation before checkout" not just "validation"
 
+## Analysis Patterns
+
+- **Negative match audit:** When \`magento_grep\` finds a bug pattern in only SOME files of a group, always read the non-matching files to understand why they differ. This narrows the fix scope.
+- **Follow up DI listings with code reads:** When \`magento_trace_dependency\` or \`magento_find_plugin\` returns plugin/preference names, always read the actual implementation. The root cause is often in a condition inside the code, not in the DI wiring.
+
 ## Magento Development Patterns
 
 - Always check for existing plugins before modifying core behavior