magector 2.4.1 → 2.5.1

package/README.md

@@ -415,7 +415,8 @@ All search tools return structured JSON:
 |------|-------------|
 | `magento_find_config` | Find XML configuration (di.xml, events.xml, routes.xml, system.xml, webapi.xml, module.xml, layout) |
 | `magento_find_template` | Find PHTML template files for frontend or admin rendering |
-| `magento_find_plugin` | Find interceptor plugins (before/after/around methods) and di.xml declarations |
+| `magento_find_plugin` | Find interceptor plugins (before/after/around methods) and di.xml declarations. Resolves plugin PHP files and extracts interceptor method signatures **(v2.5)** |
+| `magento_find_fieldset` | Find fieldset.xml definitions controlling data copy between entities (order→quote, quote→order). Shows fields per aspect (to_order, to_edit) **(v2.5)** |
 | `magento_find_observer` | Find event observers and events.xml declarations |
 | `magento_find_preference` | Find DI preference overrides -- which class implements an interface |
 | `magento_find_controller` | Find MVC controllers by frontend or admin route path |
@@ -429,7 +430,8 @@ All search tools return structured JSON:
 
 | Tool | Description |
 |------|-------------|
-| `magento_trace_flow` | Trace execution flow from an entry point (route, API, GraphQL, event, cron) -- maps controller → plugins → observers → templates in one call |
+| `magento_trace_flow` | Trace execution flow from an entry point (route, API, GraphQL, event, cron) -- maps controller → plugins → observers → templates with code snippets **(v2.5)** |
+| `magento_trace_shipping_chain` | Trace the complete shipping rate chain: carriers → collectRates plugins → rate modifiers → totals collectors → fieldset mappings **(v2.5)** |
 | `magento_trace_dependency` | Trace DI graph for a class/interface -- preferences, plugins, virtualTypes, argument overrides (parses all di.xml, no index needed) |
 | `magento_find_event_flow` | Trace complete event chain: dispatchers → observers → handler PHP classes (parses events.xml + vector search) |
 | `magento_find_event_dispatchers` | Find all PHP locations where a specific event is dispatched -- exact grep matching with method context and surrounding code **(v2.3)** |

package/package.json

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

package/src/mcp-server.js

@@ -965,6 +965,228 @@ function normalizeResult(r) {
  * @param {Object} boosts - e.g. { fileType: 'xml', pathContains: 'di.xml', isPlugin: true }
  * @param {number} weight - boost multiplier (default 0.3 = 30% score bump per match)
  */
+/**
+ * Extract before/after/around plugin method signatures from a PHP file.
+ * Returns array of { name, type, targetMethod, signature } objects.
+ */
+function extractPluginMethods(filePath) {
+  const absPath = filePath.startsWith('/') ? filePath : path.join(config.magentoRoot, filePath);
+  let content;
+  try { content = readFileSync(absPath, 'utf-8'); } catch { return []; }
+  const methods = [];
+  const methodRegex = /^\s*public\s+function\s+((?:before|after|around)([A-Z]\w*))\s*\(([^)]*)\)/gm;
+  let match;
+  while ((match = methodRegex.exec(content)) !== null) {
+    const name = match[1];
+    const targetMethod = match[2].charAt(0).toLowerCase() + match[2].slice(1);
+    let type = 'around';
+    if (name.startsWith('before')) type = 'before';
+    else if (name.startsWith('after')) type = 'after';
+    methods.push({ name, type, targetMethod, signature: match[0].trim() });
+  }
+  return methods;
+}
+
+/**
+ * Read a short code snippet around a method definition from a PHP file.
+ * Returns up to `maxLines` lines starting from the method signature.
+ */
+function readMethodSnippet(filePath, methodName, maxLines = 15) {
+  const absPath = filePath.startsWith('/') ? filePath : path.join(config.magentoRoot, filePath);
+  let content;
+  try { content = readFileSync(absPath, 'utf-8'); } catch { return null; }
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(`function ${methodName}(`)) {
+      return lines.slice(i, i + maxLines).join('\n');
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse all fieldset.xml files in the Magento root.
+ * Returns array of { file, scope, fieldset, fields: [{ field, aspect }] }.
+ */
+async function parseFieldsetXml(filterFieldset, filterAspect) {
+  const root = config.magentoRoot;
+  const fieldsetFiles = await glob('**/etc/fieldset.xml', { cwd: root, absolute: true, nodir: true });
+  const results = [];
+  for (const fsFile of fieldsetFiles) {
+    let content;
+    try { content = readFileSync(fsFile, 'utf-8'); } catch { continue; }
+    const relPath = fsFile.replace(root + '/', '');
+    // Parse <scope id="..."> blocks
+    const scopeRegex = /<scope\s+id="([^"]+)">([\s\S]*?)<\/scope>/g;
+    let scopeMatch;
+    while ((scopeMatch = scopeRegex.exec(content)) !== null) {
+      const scopeName = scopeMatch[1];
+      const scopeBlock = scopeMatch[2];
+      const innerFsRegex = /<fieldset\s+id="([^"]+)">([\s\S]*?)<\/fieldset>/g;
+      let innerMatch;
+      while ((innerMatch = innerFsRegex.exec(scopeBlock)) !== null) {
+        const innerFieldsetId = innerMatch[1];
+        if (filterFieldset && !innerFieldsetId.toLowerCase().includes(filterFieldset.toLowerCase()) && !scopeName.toLowerCase().includes(filterFieldset.toLowerCase())) continue;
+        const innerBlock = innerMatch[2];
+        const fieldRegex = /<field\s+name="([^"]+)">([\s\S]*?)<\/field>/g;
+        let fieldMatch;
+        const fields = [];
+        while ((fieldMatch = fieldRegex.exec(innerBlock)) !== null) {
+          const fieldName = fieldMatch[1];
+          const fieldBlock = fieldMatch[2];
+          const aspectRegex = /<aspect\s+name="([^"]+)"\s*(?:\/>|>[^<]*<\/aspect>)/g;
+          let aspectMatch;
+          while ((aspectMatch = aspectRegex.exec(fieldBlock)) !== null) {
+            if (filterAspect && !aspectMatch[1].toLowerCase().includes(filterAspect.toLowerCase())) continue;
+            fields.push({ field: fieldName, aspect: aspectMatch[1] });
+          }
+        }
+        if (fields.length > 0) {
+          results.push({ file: relPath, scope: scopeName, fieldset: innerFieldsetId, fields });
+        }
+      }
+    }
+    // Also handle flat fieldset format: <fieldset id="..."> without scope wrapper
+    const flatFsRegex = /<fieldset\s+id="([^"]+)">([\s\S]*?)<\/fieldset>/g;
+    let flatMatch;
+    while ((flatMatch = flatFsRegex.exec(content)) !== null) {
+      const fieldsetId = flatMatch[1];
+      if (filterFieldset && !fieldsetId.toLowerCase().includes(filterFieldset.toLowerCase())) continue;
+      const block = flatMatch[2];
+      if (block.includes('<fieldset')) continue; // skip nested (handled above)
+      const fieldRegex = /<field\s+name="([^"]+)">([\s\S]*?)<\/field>/g;
+      let fieldMatch;
+      const fields = [];
+      while ((fieldMatch = fieldRegex.exec(block)) !== null) {
+        const fieldName = fieldMatch[1];
+        const fieldBlock = fieldMatch[2];
+        const aspectRegex = /<aspect\s+name="([^"]+)"\s*(?:\/>|>[^<]*<\/aspect>)/g;
+        let aspectMatch;
+        while ((aspectMatch = aspectRegex.exec(fieldBlock)) !== null) {
+          if (filterAspect && !aspectMatch[1].toLowerCase().includes(filterAspect.toLowerCase())) continue;
+          fields.push({ field: fieldName, aspect: aspectMatch[1] });
+        }
+      }
+      if (fields.length > 0) {
+        results.push({ file: relPath, scope: null, fieldset: fieldsetId, fields });
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * Resolve a PHP class name to a file path by converting namespace to path.
+ */
+function findClassFile(root, className) {
+  if (!className) return '';
+  const parts = className.replace(/\\\\/g, '\\').split('\\');
+  if (parts.length < 3) return '';
+  const vendor = parts[0].toLowerCase();
+  const moduleParts = parts[1].replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '').split('-');
+  const candidates = [
+    path.join(root, 'vendor', vendor, parts.slice(1).join('/').replace(/\\/g, '/') + '.php'),
+    path.join(root, 'vendor', vendor, moduleParts.join('-'), parts.slice(2).join('/') + '.php'),
+    path.join(root, 'app/code', parts.join('/') + '.php'),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  // Glob fallback — search for the class filename
+  const fileName = parts[parts.length - 1] + '.php';
+  try {
+    const matches = glob.sync(`**/${fileName}`, { cwd: root, absolute: true, nodir: true, ignore: ['**/Test/**', '**/test/**'] });
+    for (const m of matches) {
+      const content = readFileSync(m, 'utf-8').slice(0, 500);
+      if (content.includes(parts[parts.length - 1])) return m;
+    }
+  } catch {}
+  return '';
+}
+
+/**
+ * Trace the shipping rate modification chain:
+ * carriers → plugins on collectRates → ShippingRateModifier pool → totals collector
+ */
+async function traceShippingChain(carrierOrMethod) {
+  const root = config.magentoRoot;
+  const chain = { carriers: [], collectRatesPlugins: [], rateModifiers: [], totalsCollectors: [], fieldsets: [] };
+
+  // 1. Find carrier classes
+  const carrierQuery = carrierOrMethod
+    ? `carrier shipping ${carrierOrMethod} collectRates`
+    : 'carrier shipping collectRates AbstractCarrier';
+  const carrierRaw = await safeSearch(carrierQuery, 30);
+  const carriers = carrierRaw.map(normalizeResult).filter(r =>
+    r.path?.includes('/Carrier/') || r.path?.includes('/Model/Carrier')
+  );
+  chain.carriers = carriers.slice(0, 10).map(r => ({
+    path: r.path, className: r.className || null, methods: r.methods || []
+  }));
+
+  // 2. Find plugins on AbstractCarrierInterface::collectRates
+  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 carrierTargets = ['AbstractCarrier', 'CarrierInterface', 'AbstractCarrierInterface', 'AbstractCarrierOnline'];
+    for (const target of carrierTargets) {
+      if (!content.includes(target)) continue;
+      const typeBlockRegex = /<type\s+name="([^"]*)"[^>]*>([\s\S]*?)<\/type>/g;
+      let tm;
+      while ((tm = typeBlockRegex.exec(content)) !== null) {
+        if (!tm[1].includes(target)) continue;
+        const block = tm[2];
+        const pluginRegex = /<plugin\s+([^/>]*)\/?>/g;
+        let pm;
+        while ((pm = pluginRegex.exec(block)) !== null) {
+          const attrs = {};
+          const attrRe = /(\w+)="([^"]*)"/g;
+          let am;
+          while ((am = attrRe.exec(pm[1])) !== null) attrs[am[1]] = am[2];
+          let area = 'global';
+          const relPath = diFile.replace(root + '/', '');
+          if (relPath.includes('/etc/adminhtml/')) area = 'adminhtml';
+          else if (relPath.includes('/etc/frontend/')) area = 'frontend';
+          const pluginFile = attrs.type ? findClassFile(root, attrs.type) : '';
+          const pluginMethods = pluginFile ? extractPluginMethods(pluginFile) : [];
+          chain.collectRatesPlugins.push({
+            target: tm[1], pluginName: attrs.name || '', pluginClass: attrs.type || '',
+            disabled: attrs.disabled === 'true', sortOrder: attrs.sortOrder || null,
+            area, file: relPath, methods: pluginMethods
+          });
+        }
+      }
+    }
+  }
+
+  // 3. Find ShippingRateModifier implementations
+  const modifierRaw = await safeSearch('ShippingRateModifier shipping rate modifier', 20);
+  const modifiers = modifierRaw.map(normalizeResult).filter(r =>
+    r.path?.includes('Modifier') || r.path?.includes('modifier') ||
+    r.className?.includes('Modifier')
+  );
+  chain.rateModifiers = modifiers.slice(0, 10).map(r => ({
+    path: r.path, className: r.className || null, methods: r.methods || []
+  }));
+
+  // 4. Find shipping totals collectors
+  const totalsRaw = await safeSearch('shipping total collector quote address', 20);
+  const totals = totalsRaw.map(normalizeResult).filter(r =>
+    r.path?.includes('/Total/') || r.path?.includes('Shipping') ||
+    r.className?.includes('Shipping')
+  );
+  chain.totalsCollectors = totals.slice(0, 5).map(r => ({
+    path: r.path, className: r.className || null, methods: r.methods || []
+  }));
+
+  // 5. Find relevant fieldsets
+  const fieldsets = await parseFieldsetXml('sales_convert', null);
+  chain.fieldsets = fieldsets;
+
+  return chain;
+}
+
 function rerank(results, boosts = {}, weight = 0.3) {
   if (!boosts || Object.keys(boosts).length === 0) return results;
 
@@ -1027,6 +1249,9 @@ async function traceRoute(entryPoint, depth) {
   const best = ranked[0];
   if (best) {
     trace.controller = { path: best.path, className: best.className || null, methods: best.methods || [] };
+    // Add code snippet for the controller's execute() method
+    const execSnippet = readMethodSnippet(best.path, 'execute');
+    if (execSnippet) trace.controller.codeSnippet = execSnippet;
   }
 
   const routeConfigs = routeRaw.map(normalizeResult).filter(r => r.path?.includes('routes.xml'));
@@ -1039,7 +1264,13 @@ async function traceRoute(entryPoint, depth) {
     const pluginRaw = await safeSearch(`plugin interceptor ${best.className}`, 20);
     const plugins = pluginRaw.map(normalizeResult).filter(r => r.isPlugin || r.path?.includes('/Plugin/') || r.path?.includes('di.xml'));
     if (plugins.length > 0) {
-      trace.plugins = plugins.slice(0, 10).map(r => ({ path: r.path, className: r.className || null, methods: r.methods || [] }));
+      trace.plugins = plugins.slice(0, 10).map(r => {
+        const entry = { path: r.path, className: r.className || null, methods: r.methods || [] };
+        if (r.path && !r.path.endsWith('.xml')) {
+          entry.pluginMethods = extractPluginMethods(r.path);
+        }
+        return entry;
+      });
     }
   }
 
@@ -1075,6 +1306,13 @@ async function traceRoute(entryPoint, depth) {
     if (templates.length > 0) {
       trace.templates = templates.slice(0, 10).map(r => ({ path: r.path }));
     }
+
+    // Fieldset discovery — look for fieldsets related to the route domain
+    const domain = parts[0]; // e.g., "sales", "checkout", "catalog"
+    const fieldsets = await parseFieldsetXml(domain, null);
+    if (fieldsets.length > 0) {
+      trace.fieldsets = fieldsets;
+    }
   }
 
   return trace;
@@ -1103,6 +1341,12 @@ async function traceApi(entryPoint, depth) {
     const svcs = svcRaw.map(normalizeResult).filter(r => r.className?.includes(serviceShortName));
     if (svcs.length > 0) {
       trace.serviceClass = { path: svcs[0].path, className: svcs[0].className || serviceClassName, methods: svcs[0].methods || [] };
+      // Try to add code snippet for the main service method
+      const methodMatch = (webapis[0]?.searchText || '').match(/method="([^"]+)"/);
+      if (methodMatch) {
+        const svcSnippet = readMethodSnippet(svcs[0].path, methodMatch[1]);
+        if (svcSnippet) trace.serviceClass.codeSnippet = svcSnippet;
+      }
     }
   }
 
@@ -1168,7 +1412,15 @@ async function traceEvent(entryPoint, depth) {
   const obsRaw = await safeSearch(`event ${entryPoint} observer`, 30);
   const observers = obsRaw.map(normalizeResult).filter(r => r.isObserver || r.path?.includes('/Observer/') || r.path?.includes('events.xml'));
   if (observers.length > 0) {
-    trace.observers = observers.slice(0, 15).map(r => ({ eventName: entryPoint, path: r.path, className: r.className || null }));
+    trace.observers = observers.slice(0, 15).map(r => {
+      const entry = { eventName: entryPoint, path: r.path, className: r.className || null };
+      // Add execute() snippet for observer PHP classes
+      if (r.path && r.path.endsWith('.php')) {
+        const snippet = readMethodSnippet(r.path, 'execute');
+        if (snippet) entry.codeSnippet = snippet;
+      }
+      return entry;
+    });
   }
 
   if (depth === 'deep') {
@@ -1180,6 +1432,13 @@ async function traceEvent(entryPoint, depth) {
     if (origins.length > 0) {
       trace.origin = { path: origins[0].path, className: origins[0].className || null, methods: origins[0].methods || [] };
     }
+
+    // Fieldset discovery — look for fieldsets related to the event domain
+    const domain = entryPoint.split('_').slice(0, 2).join('_'); // e.g., "sales_convert", "sales_order"
+    const fieldsets = await parseFieldsetXml(domain, null);
+    if (fieldsets.length > 0) {
+      trace.fieldsets = fieldsets;
+    }
   }
 
   return trace;
@@ -1202,6 +1461,8 @@ async function traceCron(entryPoint, depth) {
   const handlers = handlerRaw.map(normalizeResult).filter(r => r.path?.includes('/Cron/'));
   if (handlers.length > 0) {
     trace.handler = { path: handlers[0].path, className: handlers[0].className || null, methods: handlers[0].methods || [] };
+    const cronSnippet = readMethodSnippet(handlers[0].path, 'execute');
+    if (cronSnippet) trace.handler.codeSnippet = cronSnippet;
   }
 
   if (depth === 'deep' && handlers[0]?.className) {
@@ -1307,6 +1568,32 @@ function formatSearchResults(results) {
         : r.searchText;
     }
 
+    // Code preview — read actual source lines for PHP files with known class/method
+    if (r.path && (r.path.endsWith('.php') || r.path.endsWith('.phtml'))) {
+      if (r.methodName) {
+        const preview = readMethodSnippet(r.path, r.methodName, 10);
+        if (preview) entry.codePreview = preview;
+      } else if (r.className) {
+        // Show class declaration + first few lines
+        const classShort = r.className.split('\\').pop();
+        const preview = readMethodSnippet(r.path, classShort ? `class ${classShort}` : null, 10);
+        if (!preview) {
+          // Fallback: read file header (namespace + class line)
+          const absP = r.path.startsWith('/') ? r.path : path.join(config.magentoRoot, r.path);
+          try {
+            const content = readFileSync(absP, 'utf-8');
+            const lines = content.split('\n');
+            const classLine = lines.findIndex(l => /^\s*(abstract\s+|final\s+)?class\s+/.test(l));
+            if (classLine >= 0) {
+              entry.codePreview = lines.slice(Math.max(0, classLine - 2), classLine + 8).join('\n');
+            }
+          } catch {}
+        } else {
+          entry.codePreview = preview;
+        }
+      }
+    }
+
     return entry;
   });
 
@@ -1889,6 +2176,7 @@ async function analyzeImpact(className) {
     diXmlReferences: [],
     instantiations: [],
     typeHints: [],
+    runtimeCallers: [],
     total: 0
   };
 
@@ -1907,6 +2195,7 @@ async function analyzeImpact(className) {
   ];
 
   // Check PHP files for direct references
+  const escapedShort = shortName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   for (const r of relatedPaths.slice(0, 40)) {
     const absPath = path.join(root, r.path);
     if (!existsSync(absPath) || !r.path.endsWith('.php')) continue;
@@ -1921,13 +2210,38 @@ async function analyzeImpact(className) {
       references.instantiations.push({ file: r.path, className: r.className });
     }
     if (content.includes(`@var ${shortName}`) || content.includes(`@param ${shortName}`) ||
-        content.match(new RegExp(`:\\s*${shortName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`))) {
+        content.match(new RegExp(`:\\s*${escapedShort}\\b`))) {
       references.typeHints.push({ file: r.path, className: r.className });
     }
+
+    // Runtime callers: find $this->property->method() where property is typed as this class
+    if (hasUse) {
+      const ctorMatch = content.match(/function\s+__construct\s*\(([\s\S]*?)\)\s*[{:]/);
+      if (ctorMatch) {
+        // Find constructor params typed as the target class
+        const paramRegex = new RegExp(`(?:${escapedShort}|${className.replace(/\\/g, '\\\\')})\\s+\\$(\\w+)`, 'g');
+        let pm;
+        while ((pm = paramRegex.exec(ctorMatch[1])) !== null) {
+          const propName = pm[1];
+          // Find all calls to this property in the file
+          const callRegex = new RegExp(`\\$this->${propName}->(\\w+)\\s*\\(`, 'g');
+          let cm;
+          while ((cm = callRegex.exec(content)) !== null) {
+            references.runtimeCallers.push({
+              file: r.path,
+              callerClass: r.className,
+              property: propName,
+              calledMethod: cm[1]
+            });
+          }
+        }
+      }
+    }
   }
 
   references.total = references.useStatements.length + references.diXmlReferences.length +
-                     references.instantiations.length + references.typeHints.length;
+                     references.instantiations.length + references.typeHints.length +
+                     references.runtimeCallers.length;
 
   return references;
 }
@@ -2617,6 +2931,25 @@ async function traceCallChain(startClass, startMethod, maxDepth = 3) {
   };
 
   const classFileMap = new Map();
+  const parentClassCache = new Map();
+
+  // Resolve parent class from extends declaration in PHP file content
+  function resolveParentFromContent(content) {
+    const extendsMatch = content.match(/class\s+\w+\s+extends\s+([\w\\]+)/);
+    if (!extendsMatch) return null;
+    const parent = extendsMatch[1];
+    // If it's a short name, resolve using use statements
+    if (!parent.includes('\\')) {
+      const useMatch = content.match(new RegExp(`use\\s+([\\w\\\\]+\\\\${parent})\\s*;`));
+      if (useMatch) return useMatch[1];
+      // Check namespace-relative
+      const nsMatch = content.match(/namespace\s+([\w\\]+)/);
+      if (nsMatch) return `${nsMatch[1]}\\${parent}`;
+      return parent;
+    }
+    // Leading backslash = fully qualified
+    return parent.replace(/^\\/, '');
+  }
 
   async function resolveClassFile(className) {
     const shortName = className.split('\\').pop();
@@ -2722,14 +3055,46 @@ async function traceCallChain(startClass, startMethod, maxDepth = 3) {
     const relativePath = filePath.replace(root + '/', '');
 
     // Extract method body (brace counting)
+    const escapedMethod = methodName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const methodRegex = new RegExp(
-      `function\\s+${methodName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\([^)]*\\)[^{]*\\{`
+      `function\\s+${escapedMethod}\\s*\\([^)]*\\)[^{]*\\{`
     );
-    const methodStart = content.search(methodRegex);
+    let methodStart = content.search(methodRegex);
+
+    // If method not found in this class, walk up the inheritance chain
+    let resolvedClass = className;
+    let resolvedContent = content;
+    let resolvedFilePath = filePath;
     if (methodStart === -1) {
-      result.chain.push({ depth, class: className, method: methodName, file: relativePath, status: 'method_not_found' });
-      return;
+      let currentContent = content;
+      let found = false;
+      const visited = new Set([className]);
+      for (let i = 0; i < 10; i++) { // max 10 parent levels
+        const parentFqcn = resolveParentFromContent(currentContent);
+        if (!parentFqcn || visited.has(parentFqcn)) break;
+        visited.add(parentFqcn);
+        const parentFile = await resolveClassFile(parentFqcn);
+        if (!parentFile) break;
+        let parentContent;
+        try { parentContent = readFileSync(parentFile, 'utf-8'); } catch { break; }
+        const parentMethodStart = parentContent.search(methodRegex);
+        if (parentMethodStart !== -1) {
+          resolvedClass = parentFqcn;
+          resolvedContent = parentContent;
+          resolvedFilePath = parentFile;
+          methodStart = parentMethodStart;
+          found = true;
+          break;
+        }
+        currentContent = parentContent;
+      }
+      if (!found) {
+        result.chain.push({ depth, class: className, method: methodName, file: relativePath, status: 'method_not_found' });
+        return;
+      }
     }
+    content = resolvedContent;
+    const resolvedRelPath = resolvedFilePath.replace(root + '/', '');
 
     let braceCount = 0;
     let bodyStart = content.indexOf('{', methodStart);
@@ -2741,8 +3106,11 @@ async function traceCallChain(startClass, startMethod, maxDepth = 3) {
     }
     const methodBody = content.slice(bodyStart, bodyEnd + 1);
 
+    // Show where method was actually found if inherited
+    const inheritedFrom = (resolvedClass !== className) ? resolvedClass : null;
     const chainEntry = {
       depth, class: className, method: methodName, file: relativePath,
+      ...(inheritedFrom ? { inheritedFrom, resolvedFile: resolvedRelPath } : {}),
       calls: [], dispatches: []
     };
 
@@ -2762,13 +3130,20 @@ async function traceCallChain(startClass, startMethod, maxDepth = 3) {
     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*[{:]/);
+      // Resolve property type from constructor — check the original class first, then the resolved (parent) class
       let resolvedType = null;
-      if (ctorMatch) {
-        const paramRegex = new RegExp(`([\\w\\\\]+)\\s+\\$${property}\\b`);
-        const pm = ctorMatch[1].match(paramRegex);
-        if (pm) resolvedType = pm[1];
+      let originalContent = content;
+      if (resolvedClass !== className) {
+        try { originalContent = readFileSync(filePath, 'utf-8'); } catch { originalContent = content; }
+      }
+      const contentSources = (resolvedClass !== className) ? [originalContent, content] : [content];
+      for (const src of contentSources) {
+        const ctorMatch = src.match(/function\s+__construct\s*\(([\s\S]*?)\)\s*[{:]/);
+        if (ctorMatch) {
+          const paramRegex = new RegExp(`([\\w\\\\]+)\\s+\\$${property}\\b`);
+          const pm = ctorMatch[1].match(paramRegex);
+          if (pm) { resolvedType = pm[1]; break; }
+        }
       }
       chainEntry.calls.push({ type: 'dependency', property, method: calledMethod, typeHint: resolvedType || null });
     }
@@ -2857,6 +3232,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: 'Enable query expansion with Magento domain synonyms for better recall (default: true)',
             default: true
           },
+          precise: {
+            type: 'boolean',
+            description: 'Precise mode for debugging: disables query expansion AND applies strict post-filtering — only returns results where the file content contains at least one query keyword. Use for specific debugging queries like "gift card subtotal infinite loop". Default: false.',
+            default: false
+          },
         },
         required: ['query']
       }
@@ -3199,6 +3579,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         }
       }
     },
+    {
+      name: 'magento_find_fieldset',
+      description: 'Find fieldset.xml definitions that control how data is copied between Magento entities (e.g., order→quote, quote→order). Shows which fields are copied for each aspect (to_order, to_edit, to_quote). Essential for understanding data conversion flows like reorder, order edit, and checkout.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          fieldset: {
+            type: 'string',
+            description: 'Fieldset name or partial match. Examples: "sales_copy_order", "sales_convert_quote", "sales_convert_order", "customer_account"'
+          },
+          aspect: {
+            type: 'string',
+            description: 'Aspect name filter. Examples: "to_order", "to_edit", "to_quote", "to_customer"'
+          }
+        }
+      }
+    },
+    {
+      name: 'magento_trace_shipping_chain',
+      description: 'Trace the complete shipping rate calculation chain: carrier classes → plugins on collectRates() → ShippingRateModifier pool → totals collectors → fieldset copy mappings. Use this to understand how shipping prices are calculated, modified, and propagated during checkout, reorder, or order edit.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          carrier: {
+            type: 'string',
+            description: 'Optional carrier or shipping method to focus on. Examples: "flatrate", "freeshipping", "tablerate", "innoship", "home_delivery", "pickup"'
+          }
+        }
+      }
+    },
     {
       name: 'magento_trace_flow',
       description: 'Trace Magento execution flow from an entry point (route, API endpoint, GraphQL mutation, event, or cron job). Chains multiple searches to map controller → plugins → observers → templates for a given request path. Use this to understand how a request is processed end-to-end.',
@@ -3442,6 +3852,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['eventName']
       }
     },
+    {
+      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).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          queries: {
+            type: 'array',
+            description: 'Array of tool calls to execute. Each entry has a "tool" name and "args" object.',
+            items: {
+              type: 'object',
+              properties: {
+                tool: { type: 'string', description: 'Magector tool name (e.g., "magento_find_class", "magento_find_plugin")' },
+                args: { type: 'object', description: 'Arguments for the tool call' }
+              },
+              required: ['tool', 'args']
+            },
+            maxItems: 10
+          }
+        },
+        required: ['queries']
+      }
+    },
   ]
 }));
 
@@ -3488,12 +3921,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     switch (name) {
       case 'magento_search': {
-        const searchQuery = args.expand !== false ? expandQuery(args.query) : args.query;
-        const raw = await rustSearchAsync(searchQuery, Math.max(args.limit || 10, 30));
+        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));
         const arr = Array.isArray(raw) ? raw : [];
         let results = arr.map(normalizeResult);
         // Hybrid BM25 rerank for better exact-match handling
         results = hybridRerank(results, args.query);
+        // Precise mode: strict post-filter — result must contain at least one significant query keyword
+        if (precise) {
+          const queryTerms = args.query.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+          results = results.filter(r => {
+            const haystack = [r.searchText, r.className, r.methodName, r.path, ...(r.methods || [])]
+              .filter(Boolean).join(' ').toLowerCase();
+            return queryTerms.some(term => haystack.includes(term));
+          });
+        }
         // Apply module filter if specified
         if (args.moduleFilter) {
           results = filterByModule(results, args.moduleFilter);
@@ -3696,6 +4139,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
         }
 
+        // Resolve plugin methods for DI registrations
+        const fpRoot = args.targetClass ? config.magentoRoot : null;
+        for (const reg of diRegistrations) {
+          if (reg.pluginClass && fpRoot) {
+            const pluginFile = findClassFile(fpRoot, reg.pluginClass);
+            if (pluginFile) {
+              reg.methods = extractPluginMethods(pluginFile);
+              reg.resolvedFile = pluginFile.replace(fpRoot + '/', '');
+            }
+          }
+        }
+
         let text = formatSearchResults(enrichedResults);
         if (diRegistrations.length > 0) {
           text += `\n\n### DI Plugin Registrations for ${args.targetClass} (${diRegistrations.length})\n`;
@@ -3703,6 +4158,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const disabledTag = reg.disabled ? ' **[DISABLED]**' : '';
             const sortTag = reg.sortOrder ? ` (sortOrder: ${reg.sortOrder})` : '';
             text += `- **${reg.pluginName}** → \`${reg.pluginClass}\` [${reg.area}]${sortTag}${disabledTag} (${reg.file})\n`;
+            if (reg.resolvedFile) {
+              text += `  PHP: \`${reg.resolvedFile}\`\n`;
+            }
+            if (reg.methods?.length > 0) {
+              for (const m of reg.methods) {
+                text += `  - \`${m.type}\` **${m.targetMethod}** → \`${m.name}()\`\n`;
+              }
+            }
           }
         }
 
@@ -4222,6 +4685,93 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
       }
 
+      case 'magento_find_fieldset': {
+        const fieldsets = await parseFieldsetXml(args.fieldset || null, args.aspect || null);
+        if (fieldsets.length === 0) {
+          return { content: [{ type: 'text', text: 'No fieldset.xml definitions found matching the criteria.' }] };
+        }
+        let text = `## Fieldset Definitions (${fieldsets.length} matches)\n\n`;
+        for (const fs of fieldsets) {
+          text += `### ${fs.scope ? `${fs.scope} / ` : ''}${fs.fieldset}\n`;
+          text += `File: \`${fs.file}\`\n`;
+          // Group fields by aspect
+          const byAspect = {};
+          for (const f of fs.fields) {
+            if (!byAspect[f.aspect]) byAspect[f.aspect] = [];
+            byAspect[f.aspect].push(f.field);
+          }
+          for (const [aspect, fields] of Object.entries(byAspect)) {
+            text += `- **${aspect}**: ${fields.map(f => `\`${f}\``).join(', ')}\n`;
+          }
+          text += '\n';
+        }
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_trace_shipping_chain': {
+        const chain = await traceShippingChain(args.carrier || null);
+        let text = `## Shipping Rate Chain\n\n`;
+
+        if (chain.carriers.length > 0) {
+          text += `### Carriers (${chain.carriers.length})\n`;
+          for (const c of chain.carriers) {
+            text += `- \`${c.className || c.path}\` (${c.path})\n`;
+            if (c.methods?.length > 0) text += `  Methods: ${c.methods.join(', ')}\n`;
+          }
+          text += '\n';
+        }
+
+        if (chain.collectRatesPlugins.length > 0) {
+          text += `### Plugins on collectRates (${chain.collectRatesPlugins.length})\n`;
+          for (const p of chain.collectRatesPlugins) {
+            const disabledTag = p.disabled ? ' **[DISABLED]**' : '';
+            const sortTag = p.sortOrder ? ` (sortOrder: ${p.sortOrder})` : '';
+            text += `- **${p.pluginName}** → \`${p.pluginClass}\` [${p.area}]${sortTag}${disabledTag}\n`;
+            text += `  Target: \`${p.target}\` | DI: \`${p.file}\`\n`;
+            if (p.methods?.length > 0) {
+              for (const m of p.methods) {
+                text += `  - \`${m.type}\` **${m.targetMethod}** → \`${m.name}()\`\n`;
+              }
+            }
+          }
+          text += '\n';
+        }
+
+        if (chain.rateModifiers.length > 0) {
+          text += `### Shipping Rate Modifiers (${chain.rateModifiers.length})\n`;
+          for (const m of chain.rateModifiers) {
+            text += `- \`${m.className || m.path}\` (${m.path})\n`;
+          }
+          text += '\n';
+        }
+
+        if (chain.totalsCollectors.length > 0) {
+          text += `### Totals Collectors (${chain.totalsCollectors.length})\n`;
+          for (const t of chain.totalsCollectors) {
+            text += `- \`${t.className || t.path}\` (${t.path})\n`;
+          }
+          text += '\n';
+        }
+
+        if (chain.fieldsets.length > 0) {
+          text += `### Related Fieldsets (${chain.fieldsets.length})\n`;
+          for (const fs of chain.fieldsets) {
+            const byAspect = {};
+            for (const f of fs.fields) {
+              if (!byAspect[f.aspect]) byAspect[f.aspect] = [];
+              byAspect[f.aspect].push(f.field);
+            }
+            text += `- **${fs.scope || fs.fieldset}** (${fs.file})\n`;
+            for (const [aspect, fields] of Object.entries(byAspect)) {
+              text += `  - ${aspect}: ${fields.map(f => `\`${f}\``).join(', ')}\n`;
+            }
+          }
+          text += '\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
       case 'magento_trace_flow': {
         const entryPoint = args.entryPoint;
         const entryType = args.entryType || 'auto';
@@ -4426,6 +4976,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           text += '\n';
         }
 
+        if (impact.runtimeCallers.length > 0) {
+          text += `### Runtime Callers (${impact.runtimeCallers.length})\n`;
+          text += '_Classes that inject this class and call its methods at runtime:_\n';
+          // Group by caller class for readability
+          const grouped = new Map();
+          for (const c of impact.runtimeCallers) {
+            const key = c.callerClass || c.file;
+            if (!grouped.has(key)) grouped.set(key, { file: c.file, methods: new Set() });
+            grouped.get(key).methods.add(`$this->${c.property}->${c.calledMethod}()`);
+          }
+          for (const [cls, info] of grouped) {
+            text += `- **\`${cls}\`** (\`${info.file}\`)\n`;
+            for (const m of info.methods) {
+              text += `  - \`${m}\`\n`;
+            }
+          }
+          text += '\n';
+        }
+
         if (impact.total === 0) {
           text += '_No references found. The class may be referenced under a different name or alias._\n';
         }
@@ -4633,6 +5202,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const status = entry.status ? ` [${entry.status}]` : '';
             text += `${indent}- **${entry.class}::${entry.method}**${status}`;
             if (entry.file) text += ` (${entry.file})`;
+            if (entry.inheritedFrom) text += `\n${indent}  _inherited from_ \`${entry.inheritedFrom}\` (${entry.resolvedFile})`;
             text += '\n';
 
             if (entry.calls) {
@@ -4746,6 +5316,100 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: 'text', text }] };
       }
 
+      case 'magento_batch': {
+        const queries = args.queries || [];
+        if (queries.length === 0) {
+          return { content: [{ type: 'text', text: 'No queries provided.' }] };
+        }
+        if (queries.length > 10) {
+          return { content: [{ type: 'text', text: 'Maximum 10 queries per batch.' }], isError: true };
+        }
+        // Run batch queries in parallel using existing standalone functions
+        const batchResults = await Promise.all(queries.map(async (q, idx) => {
+          try {
+            const a = q.args || {};
+            let text = '';
+            switch (q.tool) {
+              case 'magento_find_class': {
+                const ns = a.namespace || '';
+                const qr = `${a.className} ${ns}`.trim();
+                const raw = await rustSearchAsync(qr, 30);
+                const cl = a.className.toLowerCase();
+                const res = raw.map(normalizeResult).filter(r =>
+                  r.className?.toLowerCase().includes(cl) || r.path?.toLowerCase().includes(cl.replace(/\\/g, '/'))
+                );
+                text = formatSearchResults(res.slice(0, 5));
+                break;
+              }
+              case 'magento_find_plugin': {
+                const qr = `plugin interceptor ${a.targetClass || ''} ${a.targetMethod || ''}`.trim();
+                const raw = await rustSearchAsync(qr, 30);
+                const res = raw.map(normalizeResult).filter(r =>
+                  r.magentoType === 'plugin' || r.path?.toLowerCase().includes('plugin')
+                );
+                text = formatSearchResults(res.slice(0, 10));
+                break;
+              }
+              case 'magento_find_observer': {
+                const flow = await traceEventFlow(a.eventName);
+                text = `Observers: ${flow.observers.length}\n`;
+                for (const o of flow.observers.slice(0, 10)) {
+                  text += `- ${o.name}: ${o.instance}::${o.method} (${o.file})\n`;
+                }
+                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`;
+                for (const p of dep.plugins.slice(0, 5)) text += `- plugin: ${p.pluginName} → ${p.pluginClass}\n`;
+                for (const p of dep.preferences.slice(0, 5)) text += `- pref: ${p.for} → ${p.type}\n`;
+                break;
+              }
+              case 'magento_impact_analysis': {
+                const imp = await analyzeImpact(a.className);
+                text = `Total: ${imp.total} (use: ${imp.useStatements.length}, di: ${imp.diXmlReferences.length}, new: ${imp.instantiations.length}, type: ${imp.typeHints.length}, runtime: ${imp.runtimeCallers.length})\n`;
+                for (const c of imp.runtimeCallers.slice(0, 5)) text += `- ${c.callerClass}: $this->${c.property}->${c.calledMethod}()\n`;
+                break;
+              }
+              case 'magento_search': {
+                const precise = a.precise === true;
+                const sq = (a.expand !== false && !precise) ? expandQuery(a.query) : a.query;
+                const raw = await rustSearchAsync(sq, 30);
+                let res = raw.map(normalizeResult);
+                res = hybridRerank(res, a.query);
+                text = formatSearchResults(res.slice(0, a.limit || 5));
+                break;
+              }
+              case 'magento_find_callers': {
+                const callers = await findCallers(a.methodName, a.className);
+                text = `Callers: ${callers.callers?.length || 0}\n`;
+                for (const c of (callers.callers || []).slice(0, 10)) {
+                  text += `- ${c.class}::${c.method} (${c.path}:${c.line})\n`;
+                }
+                break;
+              }
+              case 'magento_find_event_flow': {
+                const flow = await traceEventFlow(a.eventName);
+                text = `Dispatchers: ${flow.dispatchers.length}, Observers: ${flow.observers.length}\n`;
+                for (const o of flow.observers.slice(0, 10)) text += `- ${o.name}: ${o.instance} (${o.file})\n`;
+                break;
+              }
+              default:
+                text = `Unsupported batch tool: ${q.tool}`;
+            }
+            return { idx, tool: q.tool, text };
+          } catch (err) {
+            return { idx, tool: q.tool, text: `Error: ${err.message}` };
+          }
+        }));
+
+        let text = `## Batch Results (${batchResults.length} queries)\n\n`;
+        for (const br of batchResults) {
+          text += `---\n### [${br.idx + 1}] ${br.tool}\n\n${br.text}\n\n`;
+        }
+        return { content: [{ type: 'text', text }] };
+      }
+
       default:
         return {
           content: [{