magector 2.2.4 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "description": "Semantic code search for Magento 2 — index, search, MCP server",
   "type": "module",
   "main": "src/mcp-server.js",
@@ -23,13 +23,7 @@
     "test": "node tests/unit.test.js && node tests/mcp-server.test.js",
     "test:unit": "node tests/unit.test.js",
     "test:integration": "node tests/mcp-server.test.js",
-    "test:no-index": "node tests/mcp-server.test.js --no-index",
-    "test:accuracy": "node tests/mcp-accuracy.test.js",
-    "test:accuracy:verbose": "node tests/mcp-accuracy.test.js --verbose",
-    "test:sona-eval": "node tests/mcp-sona-eval.test.js",
-    "test:sona-eval:verbose": "node tests/mcp-sona-eval.test.js --verbose",
-    "test:describe-eval": "node tests/describe-benefit-eval.test.js",
-    "test:describe-eval:verbose": "node tests/describe-benefit-eval.test.js --verbose"
+    "test:no-index": "node tests/mcp-server.test.js --no-index"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -39,10 +33,10 @@
     "ruvector": "^0.1.96"
   },
   "optionalDependencies": {
-    "@magector/cli-darwin-arm64": "2.2.4",
-    "@magector/cli-linux-x64": "2.2.4",
-    "@magector/cli-linux-arm64": "2.2.4",
-    "@magector/cli-win32-x64": "2.2.4"
+    "@magector/cli-darwin-arm64": "2.3.0",
+    "@magector/cli-linux-x64": "2.3.0",
+    "@magector/cli-linux-arm64": "2.3.0",
+    "@magector/cli-win32-x64": "2.3.0"
   },
   "keywords": [
     "magento",

package/src/mcp-server.js

@@ -1773,6 +1773,11 @@ function expandQuery(query) {
 
 // ─── Module Filtering ───────────────────────────────────────────
 // Filter search results by vendor/module namespace pattern.
+// Module values in the index use composer format: "vendor_package"
+// (e.g. "some-vendor_module-name"). Users may write patterns with
+// "/" or "_" as separator, and may use a vendor prefix that matches
+// only the start of the full vendor name (e.g. "acme/*" matching
+// "acme-extensions_module-foo").
 
 function filterByModule(results, moduleFilter) {
   if (!moduleFilter) return results;
@@ -1782,11 +1787,43 @@ function filterByModule(results, moduleFilter) {
     const filePath = r.path || '';
     return patterns.some(pat => {
       if (pat.includes('*')) {
-        const regex = new RegExp('^' + pat.replace(/\*/g, '.*') + '$', 'i');
-        return regex.test(mod) || regex.test(filePath);
+        // 1. Exact regex match — treat / and _ as interchangeable separators
+        const normalized = pat.replace(/[/_]/g, '[/_]');
+        const regex = new RegExp('^' + normalized.replace(/\*/g, '.*') + '$', 'i');
+        if (regex.test(mod) || regex.test(filePath)) return true;
+
+        // 2. Vendor prefix match: "vendor/*" should also match "vendor-extended_*"
+        //    Extract the vendor part (everything before the first separator or wildcard)
+        const vendorPrefix = pat.split(/[/*_]/)[0];
+        if (vendorPrefix) {
+          const pfx = vendorPrefix.toLowerCase();
+          // Module field starts with the vendor prefix
+          if (mod.toLowerCase().startsWith(pfx)) return true;
+          // File path contains vendor/<prefix> (covers vendor/ directory)
+          if (filePath.toLowerCase().includes('vendor/' + pfx) ||
+              filePath.toLowerCase().includes('app/code/' + pfx)) return true;
+        }
+        return false;
+      }
+      // Non-wildcard: substring match on module and path, with separator normalization
+      const patLower = pat.toLowerCase();
+      if (mod.toLowerCase().includes(patLower) || filePath.toLowerCase().includes(patLower)) return true;
+      // Structured match: split "Vendor_Module" into parts and match against
+      // index format "vendor_module-name" (composer packages use "module-" prefix)
+      const patParts = patLower.split(/[/_]/);
+      if (patParts.length >= 2) {
+        const modLower = mod.toLowerCase();
+        const modParts = modLower.split(/[/_]/);
+        if (modParts.length >= 2) {
+          const vendorMatch = modParts[0].startsWith(patParts[0]) || patParts[0].startsWith(modParts[0]);
+          const modulePart = modParts.slice(1).join('-');
+          const patModule = patParts.slice(1).join('-');
+          // "module-catalog" contains "catalog", or "catalog" matches after stripping "module-"
+          const moduleMatch = modulePart.includes(patModule) || modulePart.replace(/^module-/, '').includes(patModule);
+          if (vendorMatch && moduleMatch) return true;
+        }
       }
-      return mod.toLowerCase().includes(pat.toLowerCase()) ||
-             filePath.toLowerCase().includes(pat.toLowerCase());
+      return false;
     });
   });
 }
@@ -2037,6 +2074,743 @@ async function findTests(className, methodName) {
   return result;
 }
 
+// ─── Find Implementors ──────────────────────────────────────────
+// Find all classes implementing a given interface: PHP `implements` + DI preferences
+
+async function findImplementors(interfaceName) {
+  const root = config.magentoRoot;
+  const shortName = interfaceName.split('\\').pop();
+
+  const result = {
+    interface: interfaceName,
+    implementors: [],
+    diPreferences: []
+  };
+
+  // 1. Search DI preferences for this interface
+  const diFiles = await glob('**/etc/**/di.xml', { cwd: root, absolute: true, nodir: true });
+  for (const diFile of diFiles) {
+    let content;
+    try { content = readFileSync(diFile, 'utf-8'); } catch { continue; }
+    const relativePath = diFile.replace(root + '/', '');
+
+    const prefRegex = /<preference\s+for="([^"]+)"\s+type="([^"]+)"\s*\/?>/g;
+    let m;
+    while ((m = prefRegex.exec(content)) !== null) {
+      const forClass = m[1];
+      if (forClass === interfaceName || forClass.endsWith('\\' + shortName) ||
+          forClass.toLowerCase() === interfaceName.toLowerCase()) {
+        result.diPreferences.push({ for: forClass, type: m[2], file: relativePath });
+      }
+    }
+  }
+
+  // 2. Grep PHP files for `implements ...InterfaceName`
+  const phpFiles = await glob('**/*.php', {
+    cwd: root, absolute: true, nodir: true,
+    ignore: ['**/test/**', '**/tests/**', '**/Test/**', '**/Tests/**']
+  });
+
+  const implementsRegex = new RegExp(
+    `implements\\s+[^{]*\\b${shortName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i'
+  );
+
+  for (const phpFile of phpFiles) {
+    let content;
+    try { content = readFileSync(phpFile, 'utf-8'); } catch { continue; }
+    if (!implementsRegex.test(content)) continue;
+
+    const relativePath = phpFile.replace(root + '/', '');
+    const classMatch = content.match(/(?:class|abstract\s+class)\s+(\w+)/);
+    const nsMatch = content.match(/namespace\s+([\w\\]+)/);
+    const className = classMatch ? classMatch[1] : path.basename(phpFile, '.php');
+    const fqcn = nsMatch ? `${nsMatch[1]}\\${className}` : className;
+
+    // Verify it references the right interface (not just a name collision)
+    const useStatements = content.match(/use\s+([\w\\]+);/g) || [];
+    const usesFullInterface = useStatements.some(u =>
+      u.includes(interfaceName) || u.endsWith(shortName + ';')
+    );
+
+    if (usesFullInterface || content.includes(interfaceName)) {
+      result.implementors.push({ class: fqcn, file: relativePath });
+    } else {
+      result.implementors.push({ class: fqcn, file: relativePath, matchType: 'shortName' });
+    }
+  }
+
+  return result;
+}
+
+// ─── Find Callers ───────────────────────────────────────────────
+// Find all call sites of a method across PHP and XML files
+
+async function findCallers(methodName, className) {
+  const root = config.magentoRoot;
+  const shortClass = className ? className.split('\\').pop() : null;
+
+  const result = {
+    method: methodName,
+    className: className || null,
+    phpCallers: [],
+    xmlReferences: [],
+    totalScanned: 0
+  };
+
+  // 1. PHP call sites: ->methodName( and ::methodName(
+  const phpFiles = await glob('**/*.php', { cwd: root, absolute: true, nodir: true });
+  result.totalScanned = phpFiles.length;
+
+  const methodRegex = new RegExp(
+    `(?:->|::)${methodName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\(`, 'g'
+  );
+
+  for (const phpFile of phpFiles) {
+    let content;
+    try { content = readFileSync(phpFile, 'utf-8'); } catch { continue; }
+    if (!methodRegex.test(content)) continue;
+    methodRegex.lastIndex = 0;
+
+    const relativePath = phpFile.replace(root + '/', '');
+    const lines = content.split('\n');
+    const callSites = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      if (methodRegex.test(lines[i])) {
+        if (shortClass) {
+          const usesClass = content.includes(shortClass);
+          if (!usesClass) continue;
+        }
+        callSites.push({ line: i + 1, snippet: lines[i].trim().slice(0, 150) });
+      }
+      methodRegex.lastIndex = 0;
+    }
+
+    if (callSites.length > 0) {
+      const nsMatch = content.match(/namespace\s+([\w\\]+)/);
+      const classMatch = content.match(/(?:class|trait)\s+(\w+)/);
+      const callerClass = nsMatch && classMatch ? `${nsMatch[1]}\\${classMatch[1]}` : null;
+
+      result.phpCallers.push({
+        file: relativePath, callerClass,
+        calls: callSites.slice(0, 5)
+      });
+    }
+  }
+
+  // 2. XML references
+  const xmlFiles = await glob('**/etc/**/*.xml', { cwd: root, absolute: true, nodir: true });
+  for (const xmlFile of xmlFiles) {
+    let content;
+    try { content = readFileSync(xmlFile, 'utf-8'); } catch { continue; }
+    if (!content.includes(methodName)) continue;
+
+    const relativePath = xmlFile.replace(root + '/', '');
+    const lines = content.split('\n');
+    const refs = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].includes(methodName)) {
+        refs.push({ line: i + 1, snippet: lines[i].trim().slice(0, 150) });
+      }
+    }
+    if (refs.length > 0) {
+      result.xmlReferences.push({ file: relativePath, refs: refs.slice(0, 5) });
+    }
+  }
+
+  // Sort: files referencing the class get priority
+  if (shortClass) {
+    result.phpCallers.sort((a, b) => {
+      const aHas = a.callerClass?.includes(shortClass) ? 0 : 1;
+      const bHas = b.callerClass?.includes(shortClass) ? 0 : 1;
+      return aHas - bHas;
+    });
+  }
+
+  return result;
+}
+
+// ─── Find DI Wiring ─────────────────────────────────────────────
+// Complete DI picture: preferences, plugins, constructor args, virtual types
+
+async function findDiWiring(className) {
+  const root = config.magentoRoot;
+  const shortName = className.split('\\').pop();
+  const shortLower = shortName.toLowerCase();
+
+  const result = {
+    className,
+    preferences: [],
+    plugins: [],
+    constructorArguments: [],
+    virtualTypes: [],
+    typeArguments: [],
+    totalDiFiles: 0
+  };
+
+  const diFiles = await glob('**/etc/**/di.xml', { cwd: root, absolute: true, nodir: true });
+  result.totalDiFiles = diFiles.length;
+
+  for (const diFile of diFiles) {
+    let content;
+    try { content = readFileSync(diFile, 'utf-8'); } catch { continue; }
+    const relativePath = diFile.replace(root + '/', '');
+    const contentLower = content.toLowerCase();
+
+    if (!contentLower.includes(shortLower)) continue;
+
+    // 1. Preferences where this class is the "for" or "type"
+    const prefRegex = /<preference\s+for="([^"]+)"\s+type="([^"]+)"\s*\/?>/g;
+    let m;
+    while ((m = prefRegex.exec(content)) !== null) {
+      const forLower = m[1].toLowerCase();
+      const typeLower = m[2].toLowerCase();
+      if (forLower.includes(shortLower) || typeLower.includes(shortLower)) {
+        result.preferences.push({ for: m[1], type: m[2], file: relativePath });
+      }
+    }
+
+    // 2. Plugins and type arguments
+    const typeBlockRegex = /<type\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/type>/g;
+    let typeMatch;
+    while ((typeMatch = typeBlockRegex.exec(content)) !== null) {
+      const typeName = typeMatch[1];
+      const typeNameLower = typeName.toLowerCase();
+      const typeBlock = typeMatch[2];
+
+      if (!typeNameLower.includes(shortLower)) continue;
+
+      // Plugins
+      const pluginRegex = /<plugin\s+name="([^"]+)"[^>]*type="([^"]+)"[^>]*/g;
+      let pMatch;
+      while ((pMatch = pluginRegex.exec(typeBlock)) !== null) {
+        result.plugins.push({
+          target: typeName, pluginName: pMatch[1],
+          pluginClass: pMatch[2], file: relativePath
+        });
+      }
+
+      // Simple arguments
+      const argSimpleRegex = /<argument\s+name="([^"]+)"[^>]*xsi:type="([^"]+)"[^>]*>([^<]*)<\/argument>/g;
+      let aMatch;
+      while ((aMatch = argSimpleRegex.exec(typeBlock)) !== null) {
+        result.typeArguments.push({
+          target: typeName, name: aMatch[1],
+          type: aMatch[2], value: aMatch[3].trim().slice(0, 200), file: relativePath
+        });
+      }
+
+      // Array arguments
+      const argArrayRegex = /<argument\s+name="([^"]+)"[^>]*xsi:type="array"[^>]*>([\s\S]*?)<\/argument>/g;
+      let arrMatch;
+      while ((arrMatch = argArrayRegex.exec(typeBlock)) !== null) {
+        const argName = arrMatch[1];
+        const argBlock = arrMatch[2];
+        const itemRegex = /<item\s+name="([^"]+)"[^>]*xsi:type="([^"]+)"[^>]*>([^<]*)<\/item>/g;
+        let iMatch;
+        const items = [];
+        while ((iMatch = itemRegex.exec(argBlock)) !== null) {
+          items.push({ name: iMatch[1], type: iMatch[2], value: iMatch[3].trim().slice(0, 200) });
+        }
+        if (items.length > 0) {
+          result.typeArguments.push({
+            target: typeName, name: argName,
+            type: 'array', items, file: relativePath
+          });
+        }
+      }
+    }
+
+    // 3. Virtual types extending this class
+    const vtRegex = /<virtualType\s+name="([^"]+)"[^>]*type="([^"]+)"[^>]*(?:\/>|>([\s\S]*?)<\/virtualType>)/g;
+    while ((m = vtRegex.exec(content)) !== null) {
+      const vtType = m[2];
+      if (!vtType.toLowerCase().includes(shortLower)) continue;
+      const vtEntry = { name: m[1], type: vtType, file: relativePath };
+      if (m[3]) {
+        const argRegex = /<argument\s+name="([^"]+)"[^>]*xsi:type="([^"]+)"[^>]*>([^<]*)<\/argument>/g;
+        const vtArgs = [];
+        let vam;
+        while ((vam = argRegex.exec(m[3])) !== null) {
+          vtArgs.push({ name: vam[1], type: vam[2], value: vam[3].trim().slice(0, 200) });
+        }
+        if (vtArgs.length > 0) vtEntry.arguments = vtArgs;
+      }
+      result.virtualTypes.push(vtEntry);
+    }
+  }
+
+  // 4. Constructor arguments from PHP class
+  const phpFiles = await glob(`**/${shortName}.php`, { cwd: root, absolute: true, nodir: true });
+  for (const phpFile of phpFiles) {
+    let content;
+    try { content = readFileSync(phpFile, 'utf-8'); } catch { continue; }
+    const classMatch = content.match(/(?:class|abstract\s+class)\s+(\w+)/);
+    if (!classMatch || classMatch[1] !== shortName) continue;
+
+    const ctorMatch = content.match(/function\s+__construct\s*\(([\s\S]*?)\)\s*[{:]/);
+    if (ctorMatch) {
+      const paramRegex = /(?:([\w\\]+)\s+)?(\$\w+)/g;
+      let pm;
+      while ((pm = paramRegex.exec(ctorMatch[1])) !== null) {
+        result.constructorArguments.push({ typeHint: pm[1] || null, variable: pm[2] });
+      }
+    }
+    break;
+  }
+
+  return result;
+}
+
+// ─── Trace Data Flow ───────────────────────────────────────────
+// Find all setters and getters for a data attribute across the codebase
+
+async function traceDataFlow(attributeKey, modelClass) {
+  const root = config.magentoRoot;
+
+  // Convert snake_case to PascalCase for magic method names
+  const pascal = attributeKey.split('_').map(p => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+  const setterMethod = `set${pascal}`;
+  const getterMethod = `get${pascal}`;
+
+  const result = {
+    attributeKey,
+    setterMethod,
+    getterMethod,
+    setters: [],
+    getters: [],
+    xmlReferences: []
+  };
+
+  // 1. Search PHP files for setters/getters
+  const phpFiles = await glob('**/*.php', {
+    cwd: root, absolute: true, nodir: true,
+    ignore: ['**/test/**', '**/tests/**', '**/Test/**', '**/Tests/**']
+  });
+
+  const setterRegex = new RegExp(
+    `(?:->|::)${setterMethod}\\s*\\(|` +
+    `setData\\s*\\(\\s*['"]${attributeKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`
+  );
+  const getterRegex = new RegExp(
+    `(?:->|::)${getterMethod}\\s*\\(|` +
+    `getData\\s*\\(\\s*['"]${attributeKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`
+  );
+  // Also match addData calls that could set this attribute
+  const addDataRegex = new RegExp(
+    `addData\\s*\\(.*${attributeKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`
+  );
+  // Match constant definitions for this key
+  const constRegex = new RegExp(
+    `(?:const\\s+\\w+\\s*=\\s*['"]${attributeKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"])`
+  );
+
+  const shortModel = modelClass ? modelClass.split('\\').pop() : null;
+
+  for (const phpFile of phpFiles) {
+    let content;
+    try { content = readFileSync(phpFile, 'utf-8'); } catch { continue; }
+
+    // Quick pre-check
+    if (!content.includes(setterMethod) && !content.includes(getterMethod) &&
+        !content.includes(attributeKey)) continue;
+
+    // If modelClass specified, prioritize files that reference it
+    const refsModel = !shortModel || content.includes(shortModel);
+
+    const relativePath = phpFile.replace(root + '/', '');
+    const classMatch = content.match(/(?:class|abstract\s+class|trait)\s+(\w+)/);
+    const nsMatch = content.match(/namespace\s+([\w\\]+)/);
+    const className = classMatch ? classMatch[1] : path.basename(phpFile, '.php');
+    const fqcn = nsMatch ? `${nsMatch[1]}\\${className}` : className;
+    const lines = content.split('\n');
+
+    // Determine area from path
+    const area = relativePath.includes('/frontend/') ? 'frontend'
+      : relativePath.includes('/adminhtml/') ? 'adminhtml'
+      : relativePath.includes('/graphql/') ? 'graphql' : 'global';
+
+    // Find setter lines
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (setterRegex.test(line) || (addDataRegex.test(line) && line.includes(attributeKey))) {
+        // Find enclosing method
+        let methodName = null;
+        for (let j = i; j >= Math.max(0, i - 30); j--) {
+          const mMatch = lines[j].match(/(?:public|protected|private|static)\s+function\s+(\w+)/);
+          if (mMatch) { methodName = mMatch[1]; break; }
+        }
+        result.setters.push({
+          path: relativePath,
+          class: fqcn,
+          method: methodName,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+          referencesModel: refsModel,
+          area
+        });
+        break; // one entry per file for setters
+      }
+    }
+
+    // Find getter lines
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (getterRegex.test(line)) {
+        let methodName = null;
+        for (let j = i; j >= Math.max(0, i - 30); j--) {
+          const mMatch = lines[j].match(/(?:public|protected|private|static)\s+function\s+(\w+)/);
+          if (mMatch) { methodName = mMatch[1]; break; }
+        }
+        result.getters.push({
+          path: relativePath,
+          class: fqcn,
+          method: methodName,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+          referencesModel: refsModel,
+          area
+        });
+        break; // one entry per file for getters
+      }
+    }
+
+    // Find constant definitions
+    if (constRegex.test(content)) {
+      const constLine = lines.findIndex(l => constRegex.test(l));
+      if (constLine >= 0) {
+        result.setters.push({
+          path: relativePath,
+          class: fqcn,
+          method: null,
+          line: constLine + 1,
+          snippet: lines[constLine].trim().slice(0, 200),
+          type: 'constant',
+          area
+        });
+      }
+    }
+  }
+
+  // 2. Search XML files (sales.xml, extension_attributes.xml) for attribute references
+  const xmlFiles = await glob('**/etc/**/*.xml', { cwd: root, absolute: true, nodir: true });
+  const escapedKey = attributeKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const xmlRegex = new RegExp(escapedKey);
+
+  for (const xmlFile of xmlFiles) {
+    let content;
+    try { content = readFileSync(xmlFile, 'utf-8'); } catch { continue; }
+    if (!xmlRegex.test(content)) continue;
+
+    const relativePath = xmlFile.replace(root + '/', '');
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (xmlRegex.test(lines[i])) {
+        result.xmlReferences.push({
+          path: relativePath,
+          line: i + 1,
+          snippet: lines[i].trim().slice(0, 200)
+        });
+        break;
+      }
+    }
+  }
+
+  // Sort: files referencing the model get priority
+  if (shortModel) {
+    result.setters.sort((a, b) => (b.referencesModel ? 1 : 0) - (a.referencesModel ? 1 : 0));
+    result.getters.sort((a, b) => (b.referencesModel ? 1 : 0) - (a.referencesModel ? 1 : 0));
+  }
+
+  return result;
+}
+
+// ─── Find Event Dispatchers ────────────────────────────────────
+// Find all PHP locations where a specific Magento event is dispatched
+
+async function findEventDispatchers(eventName) {
+  const root = config.magentoRoot;
+
+  const result = {
+    eventName,
+    dispatchers: [],
+    observerCount: 0
+  };
+
+  const escaped = eventName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Match eventManager->dispatch('event_name' and similar patterns
+  const dispatchRegex = new RegExp(
+    `dispatch\\s*\\(\\s*['"]${escaped}['"]`
+  );
+
+  // 1. Grep PHP files for exact dispatch calls
+  const phpFiles = await glob('**/*.php', {
+    cwd: root, absolute: true, nodir: true,
+    ignore: ['**/test/**', '**/tests/**', '**/Test/**', '**/Tests/**']
+  });
+
+  for (const phpFile of phpFiles) {
+    let content;
+    try { content = readFileSync(phpFile, 'utf-8'); } catch { continue; }
+    if (!content.includes(eventName)) continue;
+
+    const relativePath = phpFile.replace(root + '/', '');
+    const lines = content.split('\n');
+    const classMatch = content.match(/(?:class|abstract\s+class|trait)\s+(\w+)/);
+    const nsMatch = content.match(/namespace\s+([\w\\]+)/);
+    const className = classMatch ? classMatch[1] : path.basename(phpFile, '.php');
+    const fqcn = nsMatch ? `${nsMatch[1]}\\${className}` : className;
+
+    for (let i = 0; i < lines.length; i++) {
+      if (dispatchRegex.test(lines[i])) {
+        // Find enclosing method
+        let methodName = null;
+        for (let j = i; j >= Math.max(0, i - 30); j--) {
+          const mMatch = lines[j].match(/(?:public|protected|private|static)\s+function\s+(\w+)/);
+          if (mMatch) { methodName = mMatch[1]; break; }
+        }
+
+        // Get surrounding context (2 lines before and after)
+        const ctxStart = Math.max(0, i - 2);
+        const ctxEnd = Math.min(lines.length - 1, i + 2);
+        const context = lines.slice(ctxStart, ctxEnd + 1).map(l => l.trimEnd()).join('\n');
+
+        result.dispatchers.push({
+          path: relativePath,
+          class: fqcn,
+          method: methodName,
+          line: i + 1,
+          snippet: lines[i].trim().slice(0, 200),
+          context: context.slice(0, 500)
+        });
+      }
+    }
+  }
+
+  // 2. Count registered observers for context
+  const eventsFiles = await glob('**/etc/**/events.xml', { cwd: root, absolute: true, nodir: true });
+  for (const file of eventsFiles) {
+    let content;
+    try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+    if (!content.includes(eventName)) continue;
+    const obsMatches = content.match(/<observer\s+/g);
+    if (obsMatches) result.observerCount += obsMatches.length;
+  }
+
+  return result;
+}
+
+// ─── Trace Call Chain ───────────────────────────────────────────
+// Trace internal method execution: method calls, dispatched events, observers
+
+async function traceCallChain(startClass, startMethod, maxDepth = 3) {
+  const root = config.magentoRoot;
+
+  const result = {
+    entryPoint: `${startClass}::${startMethod}`,
+    chain: [],
+    events: [],
+    observers: [],
+    depth: 0
+  };
+
+  const classFileMap = new Map();
+
+  async function resolveClassFile(className) {
+    const shortName = className.split('\\').pop();
+    if (classFileMap.has(className)) return classFileMap.get(className);
+
+    // Try common Magento path patterns
+    const nsPath = className.replace(/\\/g, '/') + '.php';
+    const candidates = [
+      `app/code/${nsPath}`,
+      `vendor/${nsPath}`
+    ];
+
+    for (const c of candidates) {
+      const full = path.join(root, c);
+      if (existsSync(full)) {
+        classFileMap.set(className, full);
+        return full;
+      }
+    }
+
+    // Fallback: glob for the class file
+    const matches = await glob(`**/${shortName}.php`, {
+      cwd: root, absolute: true, nodir: true,
+      ignore: ['**/test/**', '**/tests/**', '**/Test/**', '**/Tests/**']
+    });
+
+    for (const match of matches) {
+      let content;
+      try { content = readFileSync(match, 'utf-8'); } catch { continue; }
+      const nsMatch = content.match(/namespace\s+([\w\\]+)/);
+      const classMatch = content.match(/(?:class|abstract\s+class|trait)\s+(\w+)/);
+      if (classMatch && classMatch[1] === shortName) {
+        const fqcn = nsMatch ? `${nsMatch[1]}\\${classMatch[1]}` : classMatch[1];
+        classFileMap.set(fqcn, match);
+        if (fqcn === className || classMatch[1] === shortName) {
+          classFileMap.set(className, match);
+          return match;
+        }
+      }
+    }
+
+    classFileMap.set(className, null);
+    return null;
+  }
+
+  // Load events.xml index
+  const eventObserverMap = new Map();
+  const eventFiles = await glob('**/etc/**/events.xml', { cwd: root, absolute: true, nodir: true });
+  for (const evFile of eventFiles) {
+    let content;
+    try { content = readFileSync(evFile, 'utf-8'); } catch { continue; }
+    const relativePath = evFile.replace(root + '/', '');
+
+    const eventRegex = /<event\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/event>/g;
+    let em;
+    while ((em = eventRegex.exec(content)) !== null) {
+      const eventName = em[1];
+      const eventBlock = em[2];
+      const obsRegex = /<observer\s+[^>]*name="([^"]+)"[^>]*instance="([^"]+)"[^>]*/g;
+      let om;
+      while ((om = obsRegex.exec(eventBlock)) !== null) {
+        if (!eventObserverMap.has(eventName)) eventObserverMap.set(eventName, []);
+        eventObserverMap.get(eventName).push({
+          name: om[1], class: om[2], file: relativePath
+        });
+      }
+    }
+  }
+
+  // Resolve DI preference for an interface
+  const prefCache = new Map();
+  async function resolvePreference(interfaceName) {
+    if (prefCache.has(interfaceName)) return prefCache.get(interfaceName);
+    const shortName = interfaceName.split('\\').pop();
+    const diXmlFiles = await glob('**/etc/di.xml', { cwd: root, absolute: true, nodir: true });
+    for (const diFile of diXmlFiles) {
+      let content;
+      try { content = readFileSync(diFile, 'utf-8'); } catch { continue; }
+      const prefRegex = /<preference\s+for="([^"]+)"\s+type="([^"]+)"\s*\/?>/g;
+      let m;
+      while ((m = prefRegex.exec(content)) !== null) {
+        if (m[1] === interfaceName || m[1].endsWith('\\' + shortName)) {
+          prefCache.set(interfaceName, m[2]);
+          return m[2];
+        }
+      }
+    }
+    prefCache.set(interfaceName, null);
+    return null;
+  }
+
+  async function traceMethod(className, methodName, depth) {
+    if (depth > maxDepth) return;
+
+    const filePath = await resolveClassFile(className);
+    if (!filePath) {
+      result.chain.push({ depth, class: className, method: methodName, status: 'unresolved' });
+      return;
+    }
+
+    let content;
+    try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
+    const relativePath = filePath.replace(root + '/', '');
+
+    // Extract method body (brace counting)
+    const methodRegex = new RegExp(
+      `function\\s+${methodName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\([^)]*\\)[^{]*\\{`
+    );
+    const methodStart = content.search(methodRegex);
+    if (methodStart === -1) {
+      result.chain.push({ depth, class: className, method: methodName, file: relativePath, status: 'method_not_found' });
+      return;
+    }
+
+    let braceCount = 0;
+    let bodyStart = content.indexOf('{', methodStart);
+    let bodyEnd = bodyStart;
+    for (let i = bodyStart; i < content.length; i++) {
+      if (content[i] === '{') braceCount++;
+      if (content[i] === '}') braceCount--;
+      if (braceCount === 0) { bodyEnd = i; break; }
+    }
+    const methodBody = content.slice(bodyStart, bodyEnd + 1);
+
+    const chainEntry = {
+      depth, class: className, method: methodName, file: relativePath,
+      calls: [], dispatches: []
+    };
+
+    // $this->method( calls
+    const selfCallRegex = /\$this->(\w+)\s*\(/g;
+    let sc;
+    while ((sc = selfCallRegex.exec(methodBody)) !== null) {
+      const calledMethod = sc[1];
+      if (calledMethod !== methodName && calledMethod !== '__construct') {
+        chainEntry.calls.push({ type: 'self', method: calledMethod });
+      }
+    }
+
+    // $this->dependency->method( calls
+    const depCallRegex = /\$this->(\w+)->(\w+)\s*\(/g;
+    let dc;
+    while ((dc = depCallRegex.exec(methodBody)) !== null) {
+      const property = dc[1];
+      const calledMethod = dc[2];
+      // Resolve property type from constructor
+      const ctorMatch = content.match(/function\s+__construct\s*\(([\s\S]*?)\)\s*[{:]/);
+      let resolvedType = null;
+      if (ctorMatch) {
+        const paramRegex = new RegExp(`([\\w\\\\]+)\\s+\\$${property}\\b`);
+        const pm = ctorMatch[1].match(paramRegex);
+        if (pm) resolvedType = pm[1];
+      }
+      chainEntry.calls.push({ type: 'dependency', property, method: calledMethod, typeHint: resolvedType || null });
+    }
+
+    // eventManager->dispatch calls
+    const dispatchRegex = /(?:eventManager|_eventManager)->dispatch\s*\(\s*['"]([^'"]+)['"]/g;
+    let dm;
+    while ((dm = dispatchRegex.exec(methodBody)) !== null) {
+      const eventName = dm[1];
+      chainEntry.dispatches.push(eventName);
+      const observers = eventObserverMap.get(eventName) || [];
+      result.events.push({ event: eventName, dispatchedIn: `${className}::${methodName}`, observers });
+      for (const obs of observers) {
+        result.observers.push({ event: eventName, ...obs });
+      }
+    }
+
+    result.chain.push(chainEntry);
+    result.depth = Math.max(result.depth, depth);
+
+    // Recurse into $this-> calls
+    for (const call of chainEntry.calls) {
+      if (call.type === 'self') {
+        await traceMethod(className, call.method, depth + 1);
+      }
+    }
+
+    // Recurse into dependency calls (within depth limit)
+    if (depth < maxDepth - 1) {
+      for (const call of chainEntry.calls) {
+        if (call.type === 'dependency' && call.typeHint) {
+          const impl = await resolvePreference(call.typeHint);
+          const targetClass = impl || call.typeHint;
+          await traceMethod(targetClass, call.method, depth + 1);
+        }
+      }
+    }
+  }
+
+  await traceMethod(startClass, startMethod, 0);
+
+  return result;
+}
+
 // ─── MCP Server ─────────────────────────────────────────────────
 
 const server = new Server(
@@ -2070,8 +2844,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             default: 10
           },
           moduleFilter: {
-            type: 'string',
-            description: 'Filter results by vendor/module pattern. Supports wildcards. Examples: "Vendor_*" to show only custom modules, "Magento_Catalog" for specific module. Omit to search all modules.'
+            oneOf: [
+              { type: 'string' },
+              { type: 'array', items: { type: 'string' } }
+            ],
+            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_*", ["drmax_paymentrestrictions", "drmax_module-free-shipping"], "Magento_Catalog".'
           },
           expand: {
             type: 'boolean',
@@ -2531,6 +3308,107 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['className']
       }
     },
+    {
+      name: 'magento_find_implementors',
+      description: 'Find all classes that implement a given PHP interface. Scans PHP files for `implements` keyword and di.xml for `<preference>` declarations. Use this to discover all concrete implementations of an interface across the codebase.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          interfaceName: {
+            type: 'string',
+            description: 'Full or short PHP interface name. Examples: "OrderRepositoryInterface", "Magento\\Sales\\Api\\OrderRepositoryInterface", "ChildOrderValidatorInterface"'
+          }
+        },
+        required: ['interfaceName']
+      }
+    },
+    {
+      name: 'magento_find_callers',
+      description: 'Find all call sites of a PHP method across the codebase. Searches for ->method() and ::method() patterns in PHP files and method references in XML config files. Use this to understand where a method is used and trace data flow.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          methodName: {
+            type: 'string',
+            description: 'Method name to find callers for. Examples: "execute", "save", "collectTotals", "copySalesRuleIdsFromParentToDrmaxQuote"'
+          },
+          className: {
+            type: 'string',
+            description: 'Optional: class that owns the method — narrows results to files that reference this class. Examples: "SalesRuleManagement", "CartRepository"'
+          }
+        },
+        required: ['methodName']
+      }
+    },
+    {
+      name: 'magento_find_di_wiring',
+      description: 'Get the complete DI wiring picture for a PHP class: preferences (interface→implementation), plugins (interceptors), constructor arguments from di.xml, virtual types, and argument overrides. Also extracts the PHP constructor signature. Use this to understand how a class is configured and extended across all modules.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          className: {
+            type: 'string',
+            description: 'Full or short PHP class/interface name. Examples: "ChildOrderValidatorChain", "Magento\\SalesRule\\Model\\Rule", "CartManagementInterface"'
+          }
+        },
+        required: ['className']
+      }
+    },
+    {
+      name: 'magento_trace_call_chain',
+      description: 'Trace the internal method call chain starting from a specific class::method. Follows $this->method() calls (same class), $this->dependency->method() calls (resolves DI types), and eventManager->dispatch() calls (maps to observers from events.xml). Returns a call tree showing the execution path through the code.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          className: {
+            type: 'string',
+            description: 'Full PHP class name (FQCN) to start tracing from. Examples: "DrmaxMarketplace\\OrderSplit\\Model\\CreateOrder\\CreateChildOrder", "Magento\\Quote\\Model\\QuoteManagement"'
+          },
+          methodName: {
+            type: 'string',
+            description: 'Method name to start tracing. Examples: "execute", "submit", "collectTotals"'
+          },
+          maxDepth: {
+            type: 'number',
+            description: 'Maximum recursion depth for tracing (default: 3). Higher values trace deeper but take longer.',
+            default: 3
+          }
+        },
+        required: ['className', 'methodName']
+      }
+    },
+    {
+      name: 'magento_trace_data_flow',
+      description: 'Trace how a data attribute flows through the Magento codebase: find all PHP files that set (via magic setter, setData, addData) and get (via magic getter, getData) a specific attribute key. Shows which classes write vs read the attribute, in which methods, and whether XML configs reference it. Use this to understand data dependencies — e.g., who sets drmax_discounted_price_incl_tax on Quote\\Address and who reads it.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          attributeKey: {
+            type: 'string',
+            description: 'The snake_case data attribute key to trace. Examples: "drmax_discounted_price_incl_tax", "base_grand_total", "drmax_free_shipping_price", "subtotal_with_discount"'
+          },
+          modelClass: {
+            type: 'string',
+            description: 'Optional: model class name to prioritize results that reference this class. Examples: "Quote\\Address", "Order", "Product"'
+          }
+        },
+        required: ['attributeKey']
+      }
+    },
+    {
+      name: 'magento_find_event_dispatchers',
+      description: 'Find all PHP locations where a specific Magento event is dispatched via eventManager->dispatch(). Unlike magento_find_event_flow (which shows the full chain: dispatchers+observers+handlers), this tool focuses exclusively on finding WHERE an event is triggered — with exact grep matching, method context, and surrounding code. Use this to answer "does class X dispatch event Y?" or "who triggers this event?".',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          eventName: {
+            type: 'string',
+            description: 'Magento event name to find dispatchers for. Examples: "sales_order_place_after", "drmax_discount_rule_validation_before", "checkout_cart_add_product_complete"'
+          }
+        },
+        required: ['eventName']
+      }
+    },
   ]
 }));
 
@@ -2542,7 +3420,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   // ── Warmup guard: index compatibility check or serve process still loading ──
   const indexFreeTools = ['magento_stats', 'magento_analyze_diff', 'magento_complexity',
     'magento_trace_dependency', 'magento_error_parser', 'magento_find_layout',
-    'magento_impact_analysis', 'magento_find_event_flow', 'magento_find_test'];
+    'magento_impact_analysis', 'magento_find_event_flow', 'magento_find_test',
+    'magento_trace_data_flow', 'magento_find_event_dispatchers'];
   if (warmupInProgress && !indexFreeTools.includes(name)) {
     logToFile('REQ', `${name} → blocked (warmup: loading index)`);
     return {
@@ -2725,12 +3604,65 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         );
         results = rerank(results, { isPlugin: true, pathContains: ['/Plugin/', 'di.xml'] });
 
-        return {
-          content: [{
-            type: 'text',
-            text: formatSearchResults(results.slice(0, 15))
-          }]
-        };
+        // Enrich results with di.xml registration area (frontend/adminhtml/global)
+        const enrichedResults = results.slice(0, 15).map(r => {
+          if (!r.path) return r;
+          let diArea = 'global';
+          if (r.path.includes('/etc/adminhtml/')) diArea = 'adminhtml';
+          else if (r.path.includes('/etc/frontend/')) diArea = 'frontend';
+          else if (r.path.includes('/etc/graphql/')) diArea = 'graphql';
+          else if (r.path.includes('/etc/webapi_rest/')) diArea = 'webapi_rest';
+          else if (r.path.includes('/etc/webapi_soap/')) diArea = 'webapi_soap';
+          else if (r.path.includes('/etc/crontab/')) diArea = 'crontab';
+          return { ...r, diArea };
+        });
+
+        // If targetClass provided, also scan di.xml for explicit registrations
+        let diRegistrations = [];
+        if (args.targetClass) {
+          const fpRoot = config.magentoRoot;
+          const diFiles = await glob('**/etc/**/di.xml', { cwd: fpRoot, absolute: true, nodir: true });
+          const shortTarget = args.targetClass.split('\\').pop();
+          for (const diFile of diFiles) {
+            let content;
+            try { content = readFileSync(diFile, 'utf-8'); } catch { continue; }
+            if (!content.includes(shortTarget)) continue;
+            const relPath = diFile.replace(fpRoot + '/', '');
+            // Find plugin registrations for this target
+            const typeBlockRegex = /<type\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/type>/g;
+            let tm;
+            while ((tm = typeBlockRegex.exec(content)) !== null) {
+              const typeName = tm[1];
+              if (!typeName.includes(shortTarget)) continue;
+              const block = tm[2];
+              const pluginRegex = /<plugin\s+name="([^"]+)"[^>]*type="([^"]+)"[^>]*/g;
+              let pm;
+              while ((pm = pluginRegex.exec(block)) !== null) {
+                let area = 'global';
+                if (relPath.includes('/etc/adminhtml/')) area = 'adminhtml';
+                else if (relPath.includes('/etc/frontend/')) area = 'frontend';
+                else if (relPath.includes('/etc/graphql/')) area = 'graphql';
+                diRegistrations.push({
+                  target: typeName,
+                  pluginName: pm[1],
+                  pluginClass: pm[2],
+                  area,
+                  file: relPath
+                });
+              }
+            }
+          }
+        }
+
+        let text = formatSearchResults(enrichedResults);
+        if (diRegistrations.length > 0) {
+          text += `\n\n### DI Plugin Registrations for ${args.targetClass} (${diRegistrations.length})\n`;
+          for (const reg of diRegistrations) {
+            text += `- **${reg.pluginName}** → \`${reg.pluginClass}\` [${reg.area}] (${reg.file})\n`;
+          }
+        }
+
+        return { content: [{ type: 'text', text }] };
       }
 
       case 'magento_find_observer': {
@@ -3376,6 +4308,257 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: 'text', text }] };
       }
 
+      case 'magento_find_implementors': {
+        const implResult = await findImplementors(args.interfaceName);
+
+        let text = `## Implementors of: ${implResult.interface}\n\n`;
+
+        if (implResult.diPreferences.length > 0) {
+          text += `### DI Preferences (${implResult.diPreferences.length})\n`;
+          for (const p of implResult.diPreferences) {
+            text += `- \`${p.for}\` → \`${p.type}\` (${p.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (implResult.implementors.length > 0) {
+          text += `### PHP Implementors (${implResult.implementors.length})\n`;
+          for (const impl of implResult.implementors) {
+            const suffix = impl.matchType === 'shortName' ? ' _(short name match)_' : '';
+            text += `- \`${impl.class}\` (${impl.file})${suffix}\n`;
+          }
+          text += '\n';
+        }
+
+        if (implResult.diPreferences.length === 0 && implResult.implementors.length === 0) {
+          text += '_No implementors found._\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_find_callers': {
+        const callResult = await findCallers(args.methodName, args.className);
+
+        let text = `## Callers of: ${args.methodName}${args.className ? ` (${args.className})` : ''}\n\n`;
+        text += `Scanned ${callResult.totalScanned} PHP files.\n\n`;
+
+        if (callResult.phpCallers.length > 0) {
+          text += `### PHP Call Sites (${callResult.phpCallers.length})\n`;
+          for (const caller of callResult.phpCallers.slice(0, 30)) {
+            text += `- **${caller.file}**${caller.callerClass ? ` (\`${caller.callerClass}\`)` : ''}\n`;
+            for (const c of caller.calls) {
+              text += `  - L${c.line}: \`${c.snippet}\`\n`;
+            }
+          }
+          text += '\n';
+        }
+
+        if (callResult.xmlReferences.length > 0) {
+          text += `### XML References (${callResult.xmlReferences.length})\n`;
+          for (const ref of callResult.xmlReferences.slice(0, 15)) {
+            text += `- **${ref.file}**\n`;
+            for (const r of ref.refs) {
+              text += `  - L${r.line}: \`${r.snippet}\`\n`;
+            }
+          }
+          text += '\n';
+        }
+
+        if (callResult.phpCallers.length === 0 && callResult.xmlReferences.length === 0) {
+          text += '_No callers found._\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_find_di_wiring': {
+        const diResult = await findDiWiring(args.className);
+
+        let text = `## DI Wiring: ${diResult.className}\n\n`;
+        text += `Scanned ${diResult.totalDiFiles} di.xml files.\n\n`;
+
+        if (diResult.constructorArguments.length > 0) {
+          text += `### Constructor Signature\n`;
+          for (const arg of diResult.constructorArguments) {
+            text += `- ${arg.typeHint || 'mixed'} ${arg.variable}\n`;
+          }
+          text += '\n';
+        }
+
+        if (diResult.preferences.length > 0) {
+          text += `### Preferences (${diResult.preferences.length})\n`;
+          for (const p of diResult.preferences) {
+            text += `- \`${p.for}\` → \`${p.type}\` (${p.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (diResult.plugins.length > 0) {
+          text += `### Plugins (${diResult.plugins.length})\n`;
+          for (const p of diResult.plugins) {
+            text += `- \`${p.pluginName}\`: \`${p.pluginClass}\` on \`${p.target}\` (${p.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (diResult.typeArguments.length > 0) {
+          text += `### DI Arguments (${diResult.typeArguments.length})\n`;
+          for (const a of diResult.typeArguments) {
+            if (a.type === 'array' && a.items) {
+              text += `- \`${a.target}\`.${a.name} (array, ${a.items.length} items) (${a.file})\n`;
+              for (const item of a.items.slice(0, 10)) {
+                text += `  - ${item.name}: \`${item.value}\`\n`;
+              }
+            } else {
+              text += `- \`${a.target}\`.${a.name} (${a.type}) = \`${a.value}\` (${a.file})\n`;
+            }
+          }
+          text += '\n';
+        }
+
+        if (diResult.virtualTypes.length > 0) {
+          text += `### Virtual Types (${diResult.virtualTypes.length})\n`;
+          for (const v of diResult.virtualTypes) {
+            text += `- \`${v.name}\` extends \`${v.type}\` (${v.file})\n`;
+            if (v.arguments) {
+              for (const a of v.arguments) {
+                text += `  - ${a.name}: \`${a.value}\`\n`;
+              }
+            }
+          }
+          text += '\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_trace_call_chain': {
+        const traceResult = await traceCallChain(args.className, args.methodName, args.maxDepth || 3);
+
+        let text = `## Call Chain: ${traceResult.entryPoint}\n\n`;
+        text += `Max depth reached: ${traceResult.depth}\n\n`;
+
+        if (traceResult.chain.length > 0) {
+          text += `### Execution Chain (${traceResult.chain.length} methods)\n`;
+          for (const entry of traceResult.chain) {
+            const indent = '  '.repeat(entry.depth);
+            const status = entry.status ? ` [${entry.status}]` : '';
+            text += `${indent}- **${entry.class}::${entry.method}**${status}`;
+            if (entry.file) text += ` (${entry.file})`;
+            text += '\n';
+
+            if (entry.calls) {
+              for (const call of entry.calls) {
+                if (call.type === 'self') {
+                  text += `${indent}  → \`$this->${call.method}()\`\n`;
+                } else {
+                  text += `${indent}  → \`$this->${call.property}->${call.method}()\``;
+                  if (call.typeHint) text += ` [${call.typeHint}]`;
+                  text += '\n';
+                }
+              }
+            }
+
+            if (entry.dispatches) {
+              for (const evt of entry.dispatches) {
+                text += `${indent}  ⚡ dispatch(\`${evt}\`)\n`;
+              }
+            }
+          }
+          text += '\n';
+        }
+
+        if (traceResult.events.length > 0) {
+          text += `### Events Dispatched (${traceResult.events.length})\n`;
+          for (const evt of traceResult.events) {
+            text += `- **${evt.event}** (from ${evt.dispatchedIn})\n`;
+            if (evt.observers.length > 0) {
+              for (const obs of evt.observers) {
+                text += `  - \`${obs.name}\`: \`${obs.class}\` (${obs.file})\n`;
+              }
+            } else {
+              text += '  - _no observers registered_\n';
+            }
+          }
+          text += '\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_trace_data_flow': {
+        const flowResult = await traceDataFlow(args.attributeKey, args.modelClass);
+
+        let text = `## Data Flow: \`${flowResult.attributeKey}\`\n`;
+        text += `Magic setter: \`${flowResult.setterMethod}()\` · Magic getter: \`${flowResult.getterMethod}()\`\n\n`;
+
+        if (flowResult.setters.length > 0) {
+          text += `### Setters (${flowResult.setters.length})\n`;
+          for (const s of flowResult.setters) {
+            const typeTag = s.type === 'constant' ? ' [const]' : '';
+            const methodTag = s.method ? `::${s.method}` : '';
+            text += `- \`${s.class}${methodTag}\`${typeTag} (${s.path}:${s.line})\n`;
+            if (s.snippet) text += `  \`${s.snippet}\`\n`;
+          }
+          text += '\n';
+        } else {
+          text += '### Setters\n_No setters found._\n\n';
+        }
+
+        if (flowResult.getters.length > 0) {
+          text += `### Getters (${flowResult.getters.length})\n`;
+          for (const g of flowResult.getters) {
+            const methodTag = g.method ? `::${g.method}` : '';
+            text += `- \`${g.class}${methodTag}\` (${g.path}:${g.line})\n`;
+            if (g.snippet) text += `  \`${g.snippet}\`\n`;
+          }
+          text += '\n';
+        } else {
+          text += '### Getters\n_No getters found._\n\n';
+        }
+
+        if (flowResult.xmlReferences.length > 0) {
+          text += `### XML References (${flowResult.xmlReferences.length})\n`;
+          for (const x of flowResult.xmlReferences) {
+            text += `- ${x.path}:${x.line}\n  \`${x.snippet}\`\n`;
+          }
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_find_event_dispatchers': {
+        const dispResult = await findEventDispatchers(args.eventName);
+
+        let text = `## Event Dispatchers: \`${dispResult.eventName}\`\n\n`;
+
+        if (dispResult.dispatchers.length > 0) {
+          text += `Found ${dispResult.dispatchers.length} dispatch location(s)`;
+          if (dispResult.observerCount > 0) {
+            text += ` (${dispResult.observerCount} observer(s) registered)`;
+          }
+          text += '.\n\n';
+
+          for (const d of dispResult.dispatchers) {
+            const methodTag = d.method ? `::${d.method}` : '';
+            text += `### \`${d.class}${methodTag}\`\n`;
+            text += `**File:** ${d.path}:${d.line}\n`;
+            if (d.context) {
+              text += '```php\n' + d.context + '\n```\n';
+            }
+            text += '\n';
+          }
+        } else {
+          text += '_No dispatch() calls found for this event._\n';
+          if (dispResult.observerCount > 0) {
+            text += `\nNote: ${dispResult.observerCount} observer(s) are registered for this event — it may be dispatched by Magento core or a module not in the scanned path.\n`;
+          }
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
       default:
         return {
           content: [{