magector 2.3.0 → 2.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Technology-aware MCP server for Magento 2 and Adobe Commerce with intelligent indexing and search.**
 
-Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 28 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks *"how are checkout totals calculated?"* and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).
+Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 34 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks *"how are checkout totals calculated?"* and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).
 
 [![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org)
 [![Node.js](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org)
@@ -58,7 +58,7 @@ The result: your AI assistant calls one MCP tool and gets ranked, pattern-enrich
 - **Complexity analysis** -- cyclomatic complexity, function count, and hotspot detection across modules
 - **Fast** -- 10-45ms queries via persistent serve process, batched ONNX embedding with adaptive thread scaling
 - **LLM description enrichment** -- generate natural-language descriptions of di.xml files using Claude, stored in SQLite, and prepend them to embedding text so descriptions influence vector search ranking (not just post-retrieval display)
-- **MCP server** -- 28 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
+- **MCP server** -- 34 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
 - **Clean architecture** -- Rust core handles all indexing/search, Node.js MCP server delegates to it
 
 ---
@@ -70,7 +70,7 @@ flowchart LR
   subgraph node ["Node.js Layer"]
     direction TB
     G["CLI<br/>init · index · search · describe"]
-    E["MCP Server<br/>28 tools · LRU cache"]
+    E["MCP Server<br/>34 tools · LRU cache"]
     F["Persistent Serve Process"]
     G --> F
     E --> F
@@ -369,7 +369,7 @@ npx magector index --force
 
 ## MCP Server Tools
 
-The MCP server exposes 28 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
+The MCP server exposes 34 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
 
 ### Output Format
 
@@ -432,7 +432,10 @@ All search tools return structured JSON:
 | `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_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)** |
 | `magento_find_layout` | Find layout XML files by handle or content -- lists blocks, containers, and referenceBlock declarations |
+| `magento_trace_data_flow` | Trace how a data attribute flows: find all setters (magic setter, setData, addData) and getters (magic getter, getData) across PHP and XML **(v2.3)** |
+| `magento_trace_call_chain` | Trace internal method call chain: follows `$this->method()`, `$this->dep->method()`, and `dispatch()` calls to build an execution tree **(v2.2)** |
 
 Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event, `camelCase` → GraphQL, `path/segments` → route), or override with `entryType`. Use `depth: "shallow"` (entry + config + plugins) or `depth: "deep"` (adds observers, layout, templates, DI preferences).
 
@@ -442,6 +445,9 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 |------|-------------|
 | `magento_impact_analysis` | Analyze impact of changing a class -- finds use statements, DI references, direct instantiations, and type hints across the codebase |
 | `magento_find_test` | Find PHPUnit tests for a given class/method -- searches Test/ directories for coverage, mocks, and assertions |
+| `magento_find_implementors` | Find all classes implementing a given PHP interface -- scans `implements` keywords and di.xml `<preference>` declarations **(v2.2)** |
+| `magento_find_callers` | Find all call sites of a method across PHP and XML files -- `->method()` and `::method()` calls **(v2.2)** |
+| `magento_find_di_wiring` | Complete DI picture for a class: preferences, plugins, constructor args, virtual types, and argument overrides from di.xml **(v2.2)** |
 
 ### Diagnostics
 
@@ -470,9 +476,22 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 
 - **Hybrid BM25+vector search** -- combines text frequency scoring with semantic vector similarity for better exact class name matches
 - **Query expansion** -- automatically expands queries with Magento domain synonyms (plugin → interceptor, checkout → cart/quote/totals, etc.)
-- **Module filtering** -- `moduleFilter` parameter on `magento_search` to limit results by vendor/module pattern (supports wildcards, e.g., `"Vendor_*"`)
+- **Module filtering** -- `moduleFilter` parameter on `magento_search` to limit results by vendor/module pattern. Accepts a single string or array of strings. Supports wildcards, e.g., `"Vendor_*"` or `["Acme_PaymentGateway", "Acme_FreeShipping"]`
 - **Non-blocking reindex** -- old index stays usable during background rebuild; new index is built to a temp path and swapped in atomically on completion
 
+### Deep Code Analysis (v2.2)
+
+- **`magento_find_implementors`** -- find all classes implementing a PHP interface (PHP `implements` + di.xml `<preference>`)
+- **`magento_find_callers`** -- find all call sites of a method across PHP and XML files
+- **`magento_find_di_wiring`** -- complete DI picture: preferences, plugins, constructor args, virtual types, argument overrides
+- **`magento_trace_call_chain`** -- trace internal method execution chain: `$this->method()`, `$this->dep->method()`, and `dispatch()` calls with event→observer resolution
+
+### Data Flow & Event Tracing (v2.3)
+
+- **`magento_trace_data_flow`** -- trace all setters and getters for a data attribute (magic methods, setData/getData, addData, constants, XML references). Answers "who writes/reads `custom_discounted_price_incl_tax` on `Quote\Address`?"
+- **`magento_find_event_dispatchers`** -- grep-based exact search for all PHP locations dispatching a specific event, with method context and surrounding code. Complements `magento_find_event_flow` with higher precision.
+- **`magento_find_plugin` area context** -- enriched output shows DI area (frontend/adminhtml/global/graphql) and explicit di.xml plugin registrations when `targetClass` is provided
+
 ### Tool Cross-References
 
 Each tool description includes "See also" hints to help AI clients chain tools effectively:
@@ -549,6 +568,12 @@ magento_trace_flow({ entryPoint: "checkout/cart/add", depth: "deep" })
 magento_trace_flow({ entryPoint: "/V1/products" })
 magento_trace_flow({ entryPoint: "placeOrder", entryType: "graphql" })
 magento_trace_flow({ entryPoint: "sales_order_place_after" })
+magento_trace_data_flow({ attributeKey: "custom_discounted_price_incl_tax", modelClass: "Quote\\Address" })
+magento_find_event_dispatchers({ eventName: "custom_discount_rule_validation_before" })
+magento_find_implementors({ interfaceName: "ProductRepositoryInterface" })
+magento_find_callers({ methodName: "collectTotals", className: "TotalsCollector" })
+magento_find_di_wiring({ className: "CartManagementInterface" })
+magento_trace_call_chain({ className: "Magento\\Quote\\Model\\QuoteManagement", methodName: "submit" })
 ```
 
 ---
@@ -629,7 +654,7 @@ cd rust-core && cargo run --release -- validate -m ./magento2 --skip-index
 magector/
 ├── src/                          # Node.js source
 │   ├── cli.js                    # CLI entry point (npx magector <command>)
-│   ├── mcp-server.js             # MCP server (20 tools, structured JSON output)
+│   ├── mcp-server.js             # MCP server (34 tools, structured JSON output)
 │   ├── binary.js                 # Platform binary resolver
 │   ├── model.js                  # ONNX model resolver/downloader
 │   ├── init.js                   # Full init command (index + IDE config)

package/package.json

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

package/src/mcp-server.js

@@ -32,6 +32,8 @@ import {
 } from 'ruvector/dist/analysis/complexity.js';
 import { resolveBinary } from './binary.js';
 import { resolveModels } from './model.js';
+import { createRequire } from 'module';
+const __pkg = createRequire(import.meta.url)('../package.json');
 
 const config = {
   dbPath: process.env.MAGECTOR_DB || './.magector/index.db',
@@ -2816,7 +2818,7 @@ async function traceCallChain(startClass, startMethod, maxDepth = 3) {
 const server = new Server(
   {
     name: 'magector',
-    version: '2.1.1'
+    version: __pkg.version
   },
   {
     capabilities: {
@@ -2848,7 +2850,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
               { 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".'
+            description: 'Filter results by vendor/module pattern(s). Accepts a single string or array of strings. Supports wildcards and vendor prefix matching. Uses "/" or "_" interchangeably as separator. Examples: "Vendor_*", ["Acme_PaymentGateway", "Acme_FreeShipping"], "Magento_Catalog".'
           },
           expand: {
             type: 'boolean',
@@ -3086,7 +3088,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_db_schema',
-      description: 'Find database table definitions, columns, indexes, and constraints declared in db_schema.xml (Magento declarative schema). See also: magento_find_class (model/resource model for the table).',
+      description: 'Find database table definitions, columns, indexes, and constraints declared in db_schema.xml (Magento declarative schema) AND legacy Setup scripts (InstallSchema, UpgradeSchema). Covers both modern declarative schema and legacy $setup->newTable() / addColumn() table definitions. See also: magento_find_trigger (DB triggers), magento_find_table_usage (cross-module table references).',
       inputSchema: {
         type: 'object',
         properties: {
@@ -3098,6 +3100,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['tableName']
       }
     },
+    {
+      name: 'magento_find_trigger',
+      description: 'Find MySQL database trigger definitions in Magento Setup scripts. Detects triggers created via TriggerFactory (setName, setTable, setEvent, setTime, addStatement, createTrigger). Returns trigger name, target table, event type (INSERT/UPDATE/DELETE), timing (BEFORE/AFTER), and SQL statements. Use when investigating DB-level automation, trigger chains, or performance issues caused by cascading triggers.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          triggerName: {
+            type: 'string',
+            description: 'Optional trigger name or pattern to search for. If omitted, finds all triggers in the codebase.'
+          },
+          tableName: {
+            type: 'string',
+            description: 'Optional table name to find triggers targeting this table.'
+          }
+        }
+      }
+    },
+    {
+      name: 'magento_find_table_usage',
+      description: 'Find all code that references a database table — across db_schema.xml, Setup scripts (InstallSchema/UpgradeSchema), raw SQL (Zend_Db_Expr, $connection->query), getTable() calls, and resource model definitions. Builds a cross-module dependency map showing who reads/writes/creates a given table. Essential for impact analysis of schema changes.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          tableName: {
+            type: 'string',
+            description: 'Database table name to find all references for. Examples: "salesrule_ordered", "catalog_product_entity", "quote_item"'
+          }
+        },
+        required: ['tableName']
+      }
+    },
     {
       name: 'magento_module_structure',
       description: 'Get the complete structure of a Magento module — lists all controllers, models, blocks, plugins, observers, API classes, XML configs, and templates. Provides an overview of module architecture.',
@@ -3330,7 +3363,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {
           methodName: {
             type: 'string',
-            description: 'Method name to find callers for. Examples: "execute", "save", "collectTotals", "copySalesRuleIdsFromParentToDrmaxQuote"'
+            description: 'Method name to find callers for. Examples: "execute", "save", "collectTotals", "copySalesRuleIdsFromParentToChildQuote"'
           },
           className: {
             type: 'string',
@@ -3362,7 +3395,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {
           className: {
             type: 'string',
-            description: 'Full PHP class name (FQCN) to start tracing from. Examples: "DrmaxMarketplace\\OrderSplit\\Model\\CreateOrder\\CreateChildOrder", "Magento\\Quote\\Model\\QuoteManagement"'
+            description: 'Full PHP class name (FQCN) to start tracing from. Examples: "Vendor\\OrderSplit\\Model\\CreateOrder\\CreateChildOrder", "Magento\\Quote\\Model\\QuoteManagement"'
           },
           methodName: {
             type: 'string',
@@ -3379,13 +3412,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       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.',
+      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 custom_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"'
+            description: 'The snake_case data attribute key to trace. Examples: "custom_discounted_price_incl_tax", "base_grand_total", "custom_free_shipping_price", "subtotal_with_discount"'
           },
           modelClass: {
             type: 'string',
@@ -3403,7 +3436,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         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"'
+            description: 'Magento event name to find dispatchers for. Examples: "sales_order_place_after", "custom_discount_rule_validation_before", "checkout_cart_add_product_complete"'
           }
         },
         required: ['eventName']
@@ -3807,17 +3840,160 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'magento_find_db_schema': {
-        const query = `db_schema.xml table ${args.tableName} column declarative schema`;
-        const raw = await rustSearchAsync(query, 40);
-        let results = raw.map(normalizeResult).filter(r =>
+        // Search both declarative schema (db_schema.xml) and legacy Setup scripts
+        const declQuery = `db_schema.xml table ${args.tableName} column declarative schema`;
+        const legacyQuery = `create_table ${args.tableName} legacy_schema table_created ${args.tableName} setup install schema newTable addColumn`;
+        const [declRaw, legacyRaw] = await Promise.all([
+          rustSearchAsync(declQuery, 40),
+          rustSearchAsync(legacyQuery, 30)
+        ]);
+
+        let declResults = declRaw.map(normalizeResult).filter(r =>
           r.path?.includes('db_schema.xml')
         );
-        results = rerank(results, { fileType: 'xml', pathContains: ['db_schema.xml'] });
+        declResults = rerank(declResults, { fileType: 'xml', pathContains: ['db_schema.xml'] });
+
+        let legacyResults = legacyRaw.map(normalizeResult).filter(r => {
+          const p = r.path || '';
+          return (p.includes('/Setup/') || p.includes('InstallSchema') ||
+                  p.includes('UpgradeSchema') || p.includes('/Patch/')) &&
+                 (r.snippet?.toLowerCase().includes(args.tableName.toLowerCase()) ||
+                  r.searchText?.toLowerCase().includes(args.tableName.toLowerCase()));
+        });
+
+        // Deduplicate by path
+        const seen = new Set(declResults.map(r => r.path));
+        for (const r of legacyResults) {
+          if (!seen.has(r.path)) {
+            seen.add(r.path);
+            declResults.push(r);
+          }
+        }
+
+        // Add section headers
+        let output = '';
+        const xmlResults = declResults.filter(r => r.path?.includes('db_schema.xml'));
+        const setupResults = declResults.filter(r => !r.path?.includes('db_schema.xml'));
+
+        if (xmlResults.length > 0) {
+          output += formatSearchResults(xmlResults.slice(0, 10));
+        }
+        if (setupResults.length > 0) {
+          output += `\n\n### Legacy Setup Scripts (InstallSchema/UpgradeSchema)\n`;
+          output += formatSearchResults(setupResults.slice(0, 10));
+        }
 
         return {
           content: [{
             type: 'text',
-            text: formatSearchResults(results.slice(0, 15))
+            text: output || formatSearchResults([])
+          }]
+        };
+      }
+
+      case 'magento_find_trigger': {
+        // Search for DB trigger definitions in Setup scripts
+        const triggerTerm = args.triggerName || args.tableName || '';
+        const query = `db_trigger create_trigger sql_trigger TriggerFactory createTrigger setName setEvent ${triggerTerm} setup database_trigger trigger`;
+        const raw = await rustSearchAsync(query, 50);
+        let results = raw.map(normalizeResult).filter(r => {
+          const p = r.path || '';
+          const s = (r.searchText || '') + ' ' + (r.snippet || '');
+          // Must be a Setup file that contains trigger-related terms
+          return (p.includes('/Setup/') || p.includes('InstallSchema') ||
+                  p.includes('UpgradeSchema') || p.includes('/Patch/')) &&
+                 (s.toLowerCase().includes('trigger') || s.includes('db_trigger') || s.includes('create_trigger'));
+        });
+
+        // If searching for specific trigger/table, filter further
+        if (triggerTerm) {
+          const term = triggerTerm.toLowerCase();
+          const filtered = results.filter(r => {
+            const s = ((r.searchText || '') + ' ' + (r.snippet || '')).toLowerCase();
+            return s.includes(term);
+          });
+          if (filtered.length > 0) results = filtered;
+        }
+
+        results = rerank(results, { pathContains: ['/Setup/', 'UpgradeSchema', 'InstallSchema'] });
+
+        return {
+          content: [{
+            type: 'text',
+            text: results.length > 0
+              ? `### DB Trigger Definitions\n\n` + formatSearchResults(results.slice(0, 15)) +
+                `\n\n**Tip:** Read the matched Setup files to see trigger names, target tables, events (INSERT/UPDATE/DELETE), timing (BEFORE/AFTER), and SQL statements.`
+              : `No database triggers found${triggerTerm ? ` matching "${triggerTerm}"` : ''}. Triggers are defined in Setup scripts using TriggerFactory.`
+          }]
+        };
+      }
+
+      case 'magento_find_table_usage': {
+        const table = args.tableName;
+        // Multi-query strategy: search declarative schema, setup scripts, and inline SQL references
+        const queries = [
+          `table ${table} db_schema.xml declarative schema column`,
+          `sql_table ${table} table_reference ${table} Zend_Db_Expr getTable`,
+          `create_table ${table} legacy_schema setup trigger ${table}`,
+          `${table.replace(/_/g, ' ')} resource model collection`,
+        ];
+
+        const rawResults = await Promise.all(queries.map(q => rustSearchAsync(q, 25)));
+        const allResults = rawResults.flat().map(normalizeResult);
+
+        // Deduplicate by path
+        const pathMap = new Map();
+        for (const r of allResults) {
+          if (!r.path) continue;
+          const s = ((r.searchText || '') + ' ' + (r.snippet || '')).toLowerCase();
+          if (s.includes(table.toLowerCase()) || r.path.includes('db_schema.xml')) {
+            if (!pathMap.has(r.path) || (r.score || 0) > (pathMap.get(r.path).score || 0)) {
+              pathMap.set(r.path, r);
+            }
+          }
+        }
+        const unique = Array.from(pathMap.values());
+
+        // Categorize results
+        const categories = {
+          'Declarative Schema (db_schema.xml)': unique.filter(r => r.path?.includes('db_schema.xml')),
+          'Setup Scripts (InstallSchema/UpgradeSchema/Patch)': unique.filter(r => {
+            const p = r.path || '';
+            return !p.includes('db_schema.xml') &&
+              (p.includes('/Setup/') || p.includes('InstallSchema') ||
+               p.includes('UpgradeSchema') || p.includes('/Patch/'));
+          }),
+          'PHP Code (raw SQL, getTable, Zend_Db_Expr)': unique.filter(r => {
+            const p = r.path || '';
+            return p.endsWith('.php') && !p.includes('db_schema.xml') &&
+              !p.includes('/Setup/') && !p.includes('InstallSchema') &&
+              !p.includes('UpgradeSchema') && !p.includes('/Patch/');
+          }),
+          'XML Config': unique.filter(r => {
+            const p = r.path || '';
+            return p.endsWith('.xml') && !p.includes('db_schema.xml');
+          }),
+        };
+
+        let output = `### Table Usage: \`${table}\`\n\n`;
+        output += `Found ${unique.length} file(s) referencing this table.\n\n`;
+
+        for (const [category, items] of Object.entries(categories)) {
+          if (items.length > 0) {
+            output += `#### ${category} (${items.length})\n`;
+            output += formatSearchResults(items.slice(0, 8));
+            output += '\n';
+          }
+        }
+
+        if (unique.length === 0) {
+          output += `No references found for table "${table}". Try a broader search with magento_search.`;
+        }
+
+        return {
+          content: [{
+            type: 'text',
+            text: output
           }]
         };
       }