magector 1.2.10 → 1.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "1.2.10",
+  "version": "1.2.12",
   "description": "Semantic code search for Magento 2 — index, search, MCP server",
   "type": "module",
   "main": "src/mcp-server.js",
@@ -21,7 +21,9 @@
     "validate:keep": "node src/cli.js validate --verbose --keep",
     "benchmark": "node src/cli.js benchmark",
     "test": "node tests/mcp-server.test.js",
-    "test:no-index": "node tests/mcp-server.test.js --no-index"
+    "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"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -31,10 +33,10 @@
     "ruvector": "^0.1.96"
   },
   "optionalDependencies": {
-    "@magector/cli-darwin-arm64": "1.2.10",
-    "@magector/cli-linux-x64": "1.2.10",
-    "@magector/cli-linux-arm64": "1.2.10",
-    "@magector/cli-win32-x64": "1.2.10"
+    "@magector/cli-darwin-arm64": "1.2.12",
+    "@magector/cli-linux-x64": "1.2.12",
+    "@magector/cli-linux-arm64": "1.2.12",
+    "@magector/cli-win32-x64": "1.2.12"
   },
   "keywords": [
     "magento",

package/src/mcp-server.js

@@ -14,7 +14,8 @@ import {
   ListResourcesRequestSchema,
   ReadResourceRequestSchema
 } from '@modelcontextprotocol/sdk/types.js';
-import { execFileSync } from 'child_process';
+import { execFileSync, spawn } from 'child_process';
+import { createInterface } from 'readline';
 import { existsSync } from 'fs';
 import { stat } from 'fs/promises';
 import { glob } from 'glob';
@@ -47,7 +48,112 @@ const rustEnv = {
   RUST_LOG: 'error',
 };
 
-function rustSearch(query, limit = 10) {
+/**
+ * Query cache: avoid re-embedding identical queries.
+ * Keyed by "query|limit", capped at 200 entries (LRU eviction).
+ */
+const searchCache = new Map();
+const CACHE_MAX = 200;
+
+function cacheSet(key, value) {
+  if (searchCache.size >= CACHE_MAX) {
+    const oldest = searchCache.keys().next().value;
+    searchCache.delete(oldest);
+  }
+  searchCache.set(key, value);
+}
+
+// ─── Persistent Rust Serve Process ──────────────────────────────
+// Keeps ONNX model + HNSW index loaded; eliminates ~2.6s cold start per query.
+// Falls back to execFileSync if serve mode unavailable.
+
+let serveProcess = null;
+let serveReady = false;
+let servePending = new Map();
+let serveNextId = 1;
+let serveReadline = null;
+
+function startServeProcess() {
+  try {
+    const proc = spawn(config.rustBinary, [
+      'serve',
+      '-d', config.dbPath,
+      '-c', config.modelCache
+    ], { stdio: ['pipe', 'pipe', 'pipe'], env: rustEnv });
+
+    proc.on('error', () => { serveProcess = null; serveReady = false; });
+    proc.on('exit', () => { serveProcess = null; serveReady = false; });
+    proc.stderr.on('data', () => {}); // drain stderr
+
+    serveReadline = createInterface({ input: proc.stdout });
+    serveReadline.on('line', (line) => {
+      let parsed;
+      try { parsed = JSON.parse(line); } catch { return; }
+
+      // First line is ready signal
+      if (parsed.ready) {
+        serveReady = true;
+        return;
+      }
+
+      // Route response to pending request by order (FIFO)
+      if (servePending.size > 0) {
+        const [id, resolver] = servePending.entries().next().value;
+        servePending.delete(id);
+        resolver.resolve(parsed);
+      }
+    });
+
+    serveProcess = proc;
+  } catch {
+    serveProcess = null;
+    serveReady = false;
+  }
+}
+
+function serveQuery(command, params = {}, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const id = serveNextId++;
+    const timer = setTimeout(() => {
+      servePending.delete(id);
+      reject(new Error('Serve query timeout'));
+    }, timeoutMs);
+    servePending.set(id, {
+      resolve: (v) => { clearTimeout(timer); resolve(v); }
+    });
+    const msg = JSON.stringify({ command, ...params });
+    serveProcess.stdin.write(msg + '\n');
+  });
+}
+
+async function rustSearchAsync(query, limit = 10) {
+  const cacheKey = `${query}|${limit}`;
+  if (searchCache.has(cacheKey)) {
+    return searchCache.get(cacheKey);
+  }
+
+  // Try persistent serve process first
+  if (serveProcess && serveReady) {
+    try {
+      const resp = await serveQuery('search', { query, limit });
+      if (resp.ok && resp.data) {
+        cacheSet(cacheKey, resp.data);
+        return resp.data;
+      }
+    } catch {
+      // Fall through to execFileSync
+    }
+  }
+
+  // Fallback: cold-start execFileSync
+  return rustSearchSync(query, limit);
+}
+
+function rustSearchSync(query, limit = 10) {
+  const cacheKey = `${query}|${limit}`;
+  if (searchCache.has(cacheKey)) {
+    return searchCache.get(cacheKey);
+  }
   const result = execFileSync(config.rustBinary, [
     'search', query,
     '-d', config.dbPath,
@@ -55,10 +161,18 @@ function rustSearch(query, limit = 10) {
     '-l', String(limit),
     '-f', 'json'
   ], { encoding: 'utf-8', timeout: 30000, stdio: ['pipe', 'pipe', 'pipe'], env: rustEnv });
-  return JSON.parse(result);
+  const parsed = JSON.parse(result);
+  cacheSet(cacheKey, parsed);
+  return parsed;
+}
+
+// Keep backward compat: synchronous wrapper (used by tools)
+function rustSearch(query, limit = 10) {
+  return rustSearchSync(query, limit);
 }
 
 function rustIndex(magentoRoot) {
+  searchCache.clear(); // invalidate cache on reindex
   const result = execFileSync(config.rustBinary, [
     'index',
     '-m', magentoRoot,
@@ -72,7 +186,7 @@ function rustStats() {
   const result = execFileSync(config.rustBinary, [
     'stats',
     '-d', config.dbPath
-  ], { encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'], env: rustEnv });
+  ], { encoding: 'utf-8', timeout: 30000, stdio: ['pipe', 'pipe', 'pipe'], env: rustEnv });
   // Parse text output: "Total vectors: N" and "Embedding dim: N"
   const vectors = result.match(/Total vectors:\s*(\d+)/)?.[1] || '0';
   const dim = result.match(/Embedding dim:\s*(\d+)/)?.[1] || '384';
@@ -127,7 +241,9 @@ function normalizeResult(r) {
     magentoType: meta.magento_type || meta.magentoType,
     className: meta.class_name || meta.className,
     methodName: meta.method_name || meta.methodName,
+    methods: meta.methods || [],
     namespace: meta.namespace,
+    searchText: meta.search_text || meta.searchText || '',
     isPlugin: meta.is_plugin || meta.isPlugin,
     isController: meta.is_controller || meta.isController,
     isObserver: meta.is_observer || meta.isObserver,
@@ -140,34 +256,78 @@ function normalizeResult(r) {
   };
 }
 
+/**
+ * Re-rank results by boosting scores for metadata matches.
+ * @param {Array} results - normalized results
+ * @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)
+ */
+function rerank(results, boosts = {}, weight = 0.3) {
+  if (!boosts || Object.keys(boosts).length === 0) return results;
+
+  return results.map(r => {
+    let bonus = 0;
+    if (boosts.fileType && r.type === boosts.fileType) bonus += weight;
+    if (boosts.pathContains) {
+      const patterns = Array.isArray(boosts.pathContains) ? boosts.pathContains : [boosts.pathContains];
+      for (const p of patterns) {
+        if (r.path?.toLowerCase().includes(p.toLowerCase())) bonus += weight;
+      }
+    }
+    if (boosts.isPlugin && r.isPlugin) bonus += weight;
+    if (boosts.isController && r.isController) bonus += weight;
+    if (boosts.isObserver && r.isObserver) bonus += weight;
+    if (boosts.isRepository && r.isRepository) bonus += weight;
+    if (boosts.isResolver && r.isResolver) bonus += weight;
+    if (boosts.isModel && r.isModel) bonus += weight;
+    if (boosts.isBlock && r.isBlock) bonus += weight;
+    if (boosts.magentoType && r.magentoType === boosts.magentoType) bonus += weight;
+    return { ...r, score: (r.score || 0) + bonus };
+  }).sort((a, b) => b.score - a.score);
+}
+
 function formatSearchResults(results) {
   if (!results || results.length === 0) {
-    return 'No results found.';
+    return JSON.stringify({ results: [], count: 0 });
   }
 
-  return results.map((r, i) => {
-    const header = `## Result ${i + 1} (score: ${r.score?.toFixed(3) || 'N/A'})`;
-
-    const meta = [
-      `**Path:** ${r.path || 'unknown'}`,
-      r.module ? `**Module:** ${r.module}` : null,
-      r.magentoType ? `**Magento Type:** ${r.magentoType}` : null,
-      r.area && r.area !== 'global' ? `**Area:** ${r.area}` : null,
-      r.className ? `**Class:** ${r.className}` : null,
-      r.namespace ? `**Namespace:** ${r.namespace}` : null,
-      r.methodName ? `**Method:** ${r.methodName}` : null,
-      r.type ? `**File Type:** ${r.type}` : null,
-    ].filter(Boolean).join('\n');
-
-    let badges = '';
-    if (r.isPlugin) badges += ' `plugin`';
-    if (r.isController) badges += ' `controller`';
-    if (r.isObserver) badges += ' `observer`';
-    if (r.isRepository) badges += ' `repository`';
-    if (r.isResolver) badges += ' `graphql-resolver`';
-
-    return `${header}\n${meta}${badges}`;
-  }).join('\n\n---\n\n');
+  const formatted = results.map((r, i) => {
+    const entry = {
+      rank: i + 1,
+      score: r.score ? parseFloat(r.score.toFixed(3)) : null,
+      path: r.path || 'unknown',
+    };
+    if (r.module) entry.module = r.module;
+    if (r.className) entry.className = r.className;
+    if (r.namespace) entry.namespace = r.namespace;
+    if (r.methodName) entry.methodName = r.methodName;
+    if (r.methods && r.methods.length > 0) entry.methods = r.methods;
+    if (r.magentoType) entry.magentoType = r.magentoType;
+    if (r.type) entry.fileType = r.type;
+    if (r.area && r.area !== 'global') entry.area = r.area;
+
+    // Badges — concise role indicators
+    const badges = [];
+    if (r.isPlugin) badges.push('plugin');
+    if (r.isController) badges.push('controller');
+    if (r.isObserver) badges.push('observer');
+    if (r.isRepository) badges.push('repository');
+    if (r.isResolver) badges.push('graphql-resolver');
+    if (r.isModel) badges.push('model');
+    if (r.isBlock) badges.push('block');
+    if (badges.length > 0) entry.badges = badges;
+
+    // Snippet — first 300 chars of indexed content for quick assessment
+    if (r.searchText) {
+      entry.snippet = r.searchText.length > 300
+        ? r.searchText.slice(0, 300) + '...'
+        : r.searchText;
+    }
+
+    return entry;
+  });
+
+  return JSON.stringify({ results: formatted, count: formatted.length });
 }
 
 // ─── MCP Server ─────────────────────────────────────────────────
@@ -189,17 +349,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: 'magento_search',
-      description: 'Search Magento codebase semantically. Find classes, methods, configurations, templates by describing what you need.',
+      description: 'Search Magento codebase semantically — find any PHP class, method, XML config, PHTML template, JS file, or GraphQL schema by describing what you need in natural language. Use this as a general-purpose search when no specialized tool fits. See also: magento_find_class, magento_find_method, magento_find_config for targeted searches.',
       inputSchema: {
         type: 'object',
         properties: {
           query: {
             type: 'string',
-            description: 'Natural language search query (e.g., "product price calculation", "checkout controller", "customer authentication")'
+            description: 'Natural language search query describing what you want to find. Examples: "product price calculation logic", "checkout controller", "customer authentication", "add to cart", "order placement flow"'
           },
           limit: {
             type: 'number',
-            description: 'Maximum results to return (default: 10)',
+            description: 'Maximum results to return (default: 10, max: 100)',
             default: 10
           }
         },
@@ -208,17 +368,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_class',
-      description: 'Find a specific PHP class, interface, or trait in Magento',
+      description: 'Find a PHP class, interface, abstract class, or trait by name in Magento. Locates repositories, models, resource models, blocks, helpers, controllers, API interfaces, and data objects. See also: magento_find_plugin (interceptors for this class), magento_find_preference (DI overrides), magento_find_method (methods in the class).',
       inputSchema: {
         type: 'object',
         properties: {
           className: {
             type: 'string',
-            description: 'Class name to find (e.g., "ProductRepository", "AbstractModel")'
+            description: 'Full or partial PHP class name. Examples: "ProductRepository", "AbstractModel", "CartManagementInterface", "CustomerData", "StockItemRepository"'
           },
           namespace: {
             type: 'string',
-            description: 'Optional namespace filter'
+            description: 'Optional PHP namespace filter to narrow results. Example: "Magento\\Catalog\\Model"'
           }
         },
         required: ['className']
@@ -226,17 +386,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_method',
-      description: 'Find implementations of a specific method across Magento',
+      description: 'Find implementations of a PHP method or function across the Magento codebase. Searches method names, function definitions, and class method lists. See also: magento_find_class (parent class), magento_find_plugin (interceptors around this method).',
       inputSchema: {
         type: 'object',
         properties: {
           methodName: {
             type: 'string',
-            description: 'Method name to find (e.g., "execute", "getPrice", "save")'
+            description: 'PHP method or function name to find. Examples: "execute", "getPrice", "save", "getById", "getList", "beforeSave", "afterDelete", "toHtml", "dispatch"'
           },
           className: {
             type: 'string',
-            description: 'Optional class name filter'
+            description: 'Optional class name to narrow method search. Example: "ProductRepository"'
           }
         },
         required: ['methodName']
@@ -244,18 +404,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_config',
-      description: 'Find XML configuration files and nodes in Magento',
+      description: 'Find XML configuration files and nodes in Magento — di.xml (dependency injection), events.xml (observers), routes.xml (routing), system.xml (admin config), webapi.xml (REST/SOAP), module.xml (module declarations), layout XML. See also: magento_find_observer (events.xml), magento_find_preference (di.xml), magento_find_api (webapi.xml).',
       inputSchema: {
         type: 'object',
         properties: {
           query: {
             type: 'string',
-            description: 'Configuration to find (e.g., "di.xml preference", "routes.xml", "system.xml field")'
+            description: 'What configuration to find. Examples: "di.xml preference for ProductRepository", "routes.xml catalog", "system.xml payment field", "events.xml checkout", "layout xml catalog_product_view"'
           },
           configType: {
             type: 'string',
             enum: ['di', 'routes', 'system', 'events', 'webapi', 'module', 'layout', 'other'],
-            description: 'Type of configuration'
+            description: 'Type of XML configuration: di (dependency injection/preferences/virtualTypes), routes (URL routing), system (admin config fields/sections), events (event observers/listeners), webapi (REST/SOAP endpoint definitions), module (module.xml declarations/setup_version), layout (page layout XML/blocks/containers)'
           }
         },
         required: ['query']
@@ -263,18 +423,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_template',
-      description: 'Find PHTML templates in Magento',
+      description: 'Find PHTML template files in Magento for frontend or admin rendering. Locates view templates for product pages, checkout, customer account, cart, CMS, catalog listing, and more. See also: magento_find_block (Block class rendering the template).',
       inputSchema: {
         type: 'object',
         properties: {
           query: {
             type: 'string',
-            description: 'Template description (e.g., "product listing", "checkout form", "customer account")'
+            description: 'Template description or filename pattern. Examples: "product listing", "checkout form", "customer account dashboard", "minicart", "breadcrumbs", "category view", "order summary"'
           },
           area: {
             type: 'string',
             enum: ['frontend', 'adminhtml', 'base'],
-            description: 'Magento area'
+            description: 'Magento area: frontend (customer-facing storefront), adminhtml (admin panel), base (shared/fallback)'
           }
         },
         required: ['query']
@@ -282,20 +442,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_index',
-      description: 'Index or re-index Magento codebase for semantic search (uses Rust core)',
+      description: 'Index or re-index the Magento codebase for semantic search. Run this after code changes to update the search index. Indexes PHP, XML, JS, PHTML, and GraphQL files.',
       inputSchema: {
         type: 'object',
         properties: {
           path: {
             type: 'string',
-            description: 'Path to Magento root (uses configured path if not specified)'
+            description: 'Absolute path to Magento 2 root directory. Uses configured MAGENTO_ROOT if not specified.'
           },
         }
       }
     },
     {
       name: 'magento_stats',
-      description: 'Get index statistics from Rust core',
+      description: 'Get index statistics — total indexed vectors, embedding dimensions, and database path. Use this to verify the index is loaded and check its size.',
       inputSchema: {
         type: 'object',
         properties: {}
@@ -303,30 +463,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_plugin',
-      description: 'Find plugins (interceptors) for a class or method - before/after/around methods',
+      description: 'Find Magento plugins (interceptors) that modify class behavior via before/after/around methods. Locates Plugin classes and di.xml interceptor declarations. See also: magento_find_class (target class details), magento_find_method (intercepted method), magento_find_config with configType=di.',
       inputSchema: {
         type: 'object',
         properties: {
           targetClass: {
             type: 'string',
-            description: 'Class being intercepted (e.g., "ProductRepository", "CartManagement")'
+            description: 'Class being intercepted by plugins. Examples: "ProductRepository", "CartManagement", "CustomerRepository", "OrderRepository", "Topmenu"'
           },
           targetMethod: {
             type: 'string',
-            description: 'Method being intercepted (e.g., "save", "getList")'
+            description: 'Specific method being intercepted. Examples: "save", "getList", "getById", "getHtml", "dispatch"'
           }
         }
       }
     },
     {
       name: 'magento_find_observer',
-      description: 'Find observers for a specific event',
+      description: 'Find event observers (listeners) for a Magento event. Locates Observer classes and events.xml declarations. See also: magento_find_config with configType=events for raw XML.',
       inputSchema: {
         type: 'object',
         properties: {
           eventName: {
             type: 'string',
-            description: 'Event name (e.g., "checkout_cart_add_product_complete", "sales_order_place_after")'
+            description: 'Magento event name. Examples: "checkout_cart_add_product_complete", "sales_order_place_after", "catalog_product_save_after", "customer_login", "controller_action_predispatch"'
           }
         },
         required: ['eventName']
@@ -334,13 +494,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_preference',
-      description: 'Find DI preference overrides for an interface or class',
+      description: 'Find DI preference overrides — which concrete class implements an interface or replaces another class via di.xml. See also: magento_find_class (implementation details), magento_find_config with configType=di.',
       inputSchema: {
         type: 'object',
         properties: {
           interfaceName: {
             type: 'string',
-            description: 'Interface or class name to find preferences for (e.g., "ProductRepositoryInterface")'
+            description: 'Interface or class name to find preference/implementation for. Examples: "ProductRepositoryInterface", "StoreManagerInterface", "LoggerInterface", "OrderRepositoryInterface", "CustomerRepositoryInterface"'
           }
         },
         required: ['interfaceName']
@@ -348,18 +508,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_api',
-      description: 'Find REST/SOAP API endpoints and their implementations',
+      description: 'Find REST and SOAP API endpoint definitions in webapi.xml and their service class implementations. See also: magento_find_config with configType=webapi, magento_find_class (service class).',
       inputSchema: {
         type: 'object',
         properties: {
           query: {
             type: 'string',
-            description: 'API endpoint URL pattern or service method (e.g., "/V1/products", "getList")'
+            description: 'API endpoint URL pattern or service method name. Examples: "/V1/products", "/V1/orders", "/V1/carts", "/V1/customers", "/V1/categories", "getList", "save"'
           },
           method: {
             type: 'string',
             enum: ['GET', 'POST', 'PUT', 'DELETE'],
-            description: 'HTTP method filter'
+            description: 'Filter by HTTP method: GET (read), POST (create), PUT (update), DELETE (remove)'
           }
         },
         required: ['query']
@@ -367,18 +527,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_controller',
-      description: 'Find controllers by route or action',
+      description: 'Find MVC controllers by frontend or admin route path. Maps URL routes to Controller action classes with execute() method. See also: magento_find_config with configType=routes.',
       inputSchema: {
         type: 'object',
         properties: {
           route: {
             type: 'string',
-            description: 'Route path (e.g., "catalog/product/view", "checkout/cart/add")'
+            description: 'URL route path in frontName/controller/action format. Examples: "catalog/product/view", "checkout/cart/add", "customer/account/login", "sales/order/view", "cms/page/view", "wishlist/index/add"'
           },
           area: {
             type: 'string',
             enum: ['frontend', 'adminhtml'],
-            description: 'Magento area'
+            description: 'Magento area: frontend (storefront routes) or adminhtml (admin panel routes)'
           }
         },
         required: ['route']
@@ -386,13 +546,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_block',
-      description: 'Find Block classes by name or template',
+      description: 'Find Magento Block classes used for view rendering and template logic. Blocks bridge controllers and templates. See also: magento_find_template (PHTML template rendered by the block), magento_find_config with configType=layout.',
       inputSchema: {
         type: 'object',
         properties: {
           query: {
             type: 'string',
-            description: 'Block class name or functionality (e.g., "Product\\View", "cart totals")'
+            description: 'Block class name or functionality description. Examples: "Product\\View", "cart totals", "category listing", "customer account navigation", "order view", "Topmenu"'
           }
         },
         required: ['query']
@@ -400,13 +560,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_cron',
-      description: 'Find cron jobs by name or schedule',
+      description: 'Find scheduled cron jobs defined in crontab.xml and their handler classes in Cron/ directories. See also: magento_find_config for crontab.xml raw XML.',
       inputSchema: {
         type: 'object',
         properties: {
           jobName: {
             type: 'string',
-            description: 'Cron job name or pattern (e.g., "catalog_product", "indexer")'
+            description: 'Cron job name or keyword. Examples: "catalog_product", "indexer", "sitemap", "currency", "newsletter", "reindex", "aggregate", "clean"'
           }
         },
         required: ['jobName']
@@ -414,18 +574,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_graphql',
-      description: 'Find GraphQL types, queries, mutations, or resolvers',
+      description: 'Find GraphQL schema definitions (.graphqls), types, queries, mutations, and resolver PHP classes. See also: magento_find_class (resolver implementation), magento_find_method (resolver execute method).',
       inputSchema: {
         type: 'object',
         properties: {
           query: {
             type: 'string',
-            description: 'GraphQL type, query, or mutation name (e.g., "products", "createCustomer", "CartItemInterface")'
+            description: 'GraphQL type, query, mutation, or interface name. Examples: "products", "createCustomer", "CartItemInterface", "cart", "categoryList", "placeOrder", "createEmptyCart"'
           },
           schemaType: {
             type: 'string',
             enum: ['type', 'query', 'mutation', 'interface', 'resolver'],
-            description: 'Type of GraphQL schema element'
+            description: 'Filter by GraphQL schema element: type (object types), query (read operations), mutation (write operations), interface (shared contracts), resolver (PHP resolver classes)'
           }
         },
         required: ['query']
@@ -433,13 +593,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_find_db_schema',
-      description: 'Find database table definitions and columns',
+      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).',
       inputSchema: {
         type: 'object',
         properties: {
           tableName: {
             type: 'string',
-            description: 'Table name pattern (e.g., "catalog_product", "sales_order")'
+            description: 'Database table name or pattern. Examples: "catalog_product_entity", "sales_order", "customer_entity", "quote", "cms_page", "inventory_source"'
           }
         },
         required: ['tableName']
@@ -447,13 +607,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_module_structure',
-      description: 'Get complete structure of a Magento module - all its classes, configs, templates',
+      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.',
       inputSchema: {
         type: 'object',
         properties: {
           moduleName: {
             type: 'string',
-            description: 'Full module name (e.g., "Magento_Catalog", "Vendor_CustomModule")'
+            description: 'Full Magento module name in Vendor_Module format. Examples: "Magento_Catalog", "Magento_Sales", "Magento_Customer", "Magento_Checkout", "Vendor_CustomModule"'
           }
         },
         required: ['moduleName']
@@ -461,17 +621,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_analyze_diff',
-      description: 'Analyze git diffs for risk scoring, change classification, and per-file analysis. Works on commits or staged changes.',
+      description: 'Analyze git diffs for risk scoring, change classification, and per-file impact analysis. Works on specific commits or staged changes. Useful for code review.',
       inputSchema: {
         type: 'object',
         properties: {
           commitHash: {
             type: 'string',
-            description: 'Git commit hash to analyze. If omitted, analyzes staged changes.'
+            description: 'Git commit hash to analyze. If omitted, analyzes currently staged (git add) changes instead.'
           },
           staged: {
             type: 'boolean',
-            description: 'Analyze staged (git add) changes instead of a commit',
+            description: 'Set true to analyze staged changes, false to require commitHash. Default: true.',
             default: true
           }
         }
@@ -479,21 +639,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'magento_complexity',
-      description: 'Analyze code complexity (cyclomatic complexity, function count, lines) for Magento files. Finds complex hotspots.',
+      description: 'Analyze code complexity — cyclomatic complexity, function count, and line count for PHP files. Identifies complex hotspots and rates each file. Use for refactoring prioritization.',
       inputSchema: {
         type: 'object',
         properties: {
           module: {
             type: 'string',
-            description: 'Magento module to analyze (e.g., "Magento_Catalog"). Finds all PHP files in the module.'
+            description: 'Magento module to analyze. Finds all PHP files in the module. Examples: "Magento_Catalog", "Magento_Checkout", "Magento_Sales"'
           },
           path: {
             type: 'string',
-            description: 'Specific file or directory path to analyze'
+            description: 'Specific file or directory path to analyze instead of a module name'
           },
           threshold: {
             type: 'number',
-            description: 'Minimum cyclomatic complexity to report (default: 0, show all)',
+            description: 'Minimum cyclomatic complexity to report. Set higher (e.g., 10) to only see complex files. Default: 0 (show all)',
             default: 0
           }
         }
@@ -508,7 +668,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     switch (name) {
       case 'magento_search': {
-        const raw = rustSearch(args.query, args.limit || 10);
+        const raw = await rustSearchAsync(args.query, args.limit || 10);
         const results = raw.map(normalizeResult);
         return {
           content: [{
@@ -519,10 +679,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'magento_find_class': {
-        const query = `class ${args.className} ${args.namespace || ''}`.trim();
-        const raw = rustSearch(query, 10);
+        const ns = args.namespace || '';
+        const query = `${args.className} ${ns}`.trim();
+        const raw = await rustSearchAsync(query, 30);
+        const classLower = args.className.toLowerCase();
         const results = raw.map(normalizeResult).filter(r =>
-          r.className?.toLowerCase().includes(args.className.toLowerCase())
+          r.className?.toLowerCase().includes(classLower) ||
+          r.path?.toLowerCase().includes(classLower.replace(/\\/g, '/'))
         );
         return {
           content: [{
@@ -533,12 +696,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'magento_find_method': {
-        const query = `function ${args.methodName} ${args.className || ''}`.trim();
-        const raw = rustSearch(query, 20);
-        const results = raw.map(normalizeResult).filter(r =>
-          r.methodName?.toLowerCase() === args.methodName.toLowerCase() ||
-          r.path?.toLowerCase().includes(args.methodName.toLowerCase())
+        const query = `method ${args.methodName} function ${args.className || ''}`.trim();
+        const raw = await rustSearchAsync(query, 30);
+        const methodLower = args.methodName.toLowerCase();
+        let results = raw.map(normalizeResult).filter(r =>
+          r.methodName?.toLowerCase() === methodLower ||
+          r.methodName?.toLowerCase().includes(methodLower) ||
+          r.methods?.some(m => m.toLowerCase() === methodLower || m.toLowerCase().includes(methodLower)) ||
+          r.path?.toLowerCase().includes(methodLower)
         );
+        // Boost exact method matches to top
+        results = results.map(r => {
+          const exact = r.methodName?.toLowerCase() === methodLower ||
+            r.methods?.some(m => m.toLowerCase() === methodLower);
+          return { ...r, score: (r.score || 0) + (exact ? 0.5 : 0) };
+        }).sort((a, b) => b.score - a.score);
         return {
           content: [{
             type: 'text',
@@ -552,12 +724,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (args.configType && args.configType !== 'other') {
           query = `${args.configType}.xml ${args.query}`;
         }
-        const raw = rustSearch(query, 10);
-        const results = raw.map(normalizeResult);
+        const raw = await rustSearchAsync(query, 30);
+        const pathBoost = args.configType ? [`${args.configType}.xml`] : ['.xml'];
+        let normalized = raw.map(normalizeResult);
+        // Prefer XML results when configType is specified, but don't hard-exclude
+        if (args.configType) {
+          const xmlOnly = normalized.filter(r =>
+            r.type === 'xml' || r.path?.endsWith('.xml') || r.path?.includes('.xml')
+          );
+          if (xmlOnly.length > 0) normalized = xmlOnly;
+        }
+        const results = rerank(normalized, { fileType: 'xml', pathContains: pathBoost });
         return {
           content: [{
             type: 'text',
-            text: formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 10))
           }]
         };
       }
@@ -566,12 +747,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         let query = args.query;
         if (args.area) query = `${args.area} ${query}`;
         query += ' template phtml';
-        const raw = rustSearch(query, 10);
-        const results = raw.map(normalizeResult);
+        const raw = await rustSearchAsync(query, 15);
+        const results = rerank(raw.map(normalizeResult), { pathContains: ['.phtml'] });
         return {
           content: [{
             type: 'text',
-            text: formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 10))
           }]
         };
       }
@@ -602,45 +783,48 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (args.targetClass) query += ` ${args.targetClass}`;
         if (args.targetMethod) query += ` ${args.targetMethod} before after around`;
 
-        const raw = rustSearch(query, 15);
-        const results = raw.map(normalizeResult).filter(r =>
+        const raw = await rustSearchAsync(query, 30);
+        let results = raw.map(normalizeResult).filter(r =>
           r.isPlugin || r.path?.includes('/Plugin/') || r.path?.includes('di.xml')
         );
+        results = rerank(results, { isPlugin: true, pathContains: ['/Plugin/', 'di.xml'] });
 
         return {
           content: [{
             type: 'text',
-            text: formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 15))
           }]
         };
       }
 
       case 'magento_find_observer': {
         const query = `event ${args.eventName} observer`;
-        const raw = rustSearch(query, 15);
-        const results = raw.map(normalizeResult).filter(r =>
+        const raw = await rustSearchAsync(query, 30);
+        let results = raw.map(normalizeResult).filter(r =>
           r.isObserver || r.path?.includes('/Observer/') || r.path?.includes('events.xml')
         );
+        results = rerank(results, { isObserver: true, pathContains: ['events.xml', '/Observer/'] });
 
         return {
           content: [{
             type: 'text',
-            text: `## Observers for event: ${args.eventName}\n\n` + formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 15))
           }]
         };
       }
 
       case 'magento_find_preference': {
-        const query = `preference ${args.interfaceName}`;
-        const raw = rustSearch(query, 15);
-        const results = raw.map(normalizeResult).filter(r =>
+        const query = `preference ${args.interfaceName} di.xml type`;
+        const raw = await rustSearchAsync(query, 30);
+        let results = raw.map(normalizeResult).filter(r =>
           r.path?.includes('di.xml')
         );
+        results = rerank(results, { fileType: 'xml', pathContains: ['di.xml'] });
 
         return {
           content: [{
             type: 'text',
-            text: `## Preferences for: ${args.interfaceName}\n\n` + formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 15))
           }]
         };
       }
@@ -649,26 +833,40 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         let query = `webapi route ${args.query}`;
         if (args.method) query += ` method="${args.method}"`;
 
-        const raw = rustSearch(query, 15);
-        const results = raw.map(normalizeResult);
+        const raw = await rustSearchAsync(query, 30);
+        let results = rerank(raw.map(normalizeResult), { pathContains: ['webapi.xml'] });
 
         return {
           content: [{
             type: 'text',
-            text: `## API Endpoints matching: ${args.query}\n\n` + formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 15))
           }]
         };
       }
 
       case 'magento_find_controller': {
         const parts = args.route.split('/');
-        const query = `controller ${parts.join(' ')} execute action`;
+        // Map route to Magento namespace: catalog/product/view → Catalog Controller Product View
+        const namespaceParts = parts.map(p => p.charAt(0).toUpperCase() + p.slice(1));
+        const query = `${namespaceParts.join(' ')} controller execute action`;
 
-        const raw = rustSearch(query, 15);
+        const raw = await rustSearchAsync(query, 30);
         let results = raw.map(normalizeResult).filter(r =>
           r.isController || r.path?.includes('/Controller/')
         );
 
+        // Boost results whose path matches the route segments
+        if (parts.length >= 2) {
+          const pathPattern = parts.map(p => p.charAt(0).toUpperCase() + p.slice(1));
+          results.sort((a, b) => {
+            const aPath = a.path || '';
+            const bPath = b.path || '';
+            const aMatches = pathPattern.filter(p => aPath.includes(p)).length;
+            const bMatches = pathPattern.filter(p => bPath.includes(p)).length;
+            return bMatches - aMatches;
+          });
+        }
+
         if (args.area) {
           results = results.filter(r => r.area === args.area || r.path?.includes(`/${args.area}/`));
         }
@@ -676,37 +874,39 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return {
           content: [{
             type: 'text',
-            text: `## Controllers for route: ${args.route}\n\n` + formatSearchResults(results)
+            text: formatSearchResults(results)
           }]
         };
       }
 
       case 'magento_find_block': {
         const query = `block ${args.query}`;
-        const raw = rustSearch(query, 15);
-        const results = raw.map(normalizeResult).filter(r =>
+        const raw = await rustSearchAsync(query, 30);
+        let results = raw.map(normalizeResult).filter(r =>
           r.isBlock || r.path?.includes('/Block/')
         );
+        results = rerank(results, { isBlock: true, pathContains: ['/Block/'] });
 
         return {
           content: [{
             type: 'text',
-            text: formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 15))
           }]
         };
       }
 
       case 'magento_find_cron': {
         const query = `cron job ${args.jobName}`;
-        const raw = rustSearch(query, 15);
-        const results = raw.map(normalizeResult).filter(r =>
+        const raw = await rustSearchAsync(query, 30);
+        let results = raw.map(normalizeResult).filter(r =>
           r.path?.includes('crontab.xml') || r.path?.includes('/Cron/')
         );
+        results = rerank(results, { pathContains: ['crontab.xml', '/Cron/'] });
 
         return {
           content: [{
             type: 'text',
-            text: `## Cron jobs matching: ${args.jobName}\n\n` + formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 15))
           }]
         };
       }
@@ -715,37 +915,39 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         let query = `graphql ${args.query}`;
         if (args.schemaType) query += ` ${args.schemaType}`;
 
-        const raw = rustSearch(query, 15);
-        const results = raw.map(normalizeResult).filter(r =>
+        const raw = await rustSearchAsync(query, 40);
+        let results = raw.map(normalizeResult).filter(r =>
           r.isResolver || r.path?.includes('/Resolver/') ||
           r.path?.includes('.graphqls') || r.type === 'graphql'
         );
+        results = rerank(results, { isResolver: true, pathContains: ['.graphqls', '/Resolver/'] });
 
         return {
           content: [{
             type: 'text',
-            text: `## GraphQL matching: ${args.query}\n\n` + formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 15))
           }]
         };
       }
 
       case 'magento_find_db_schema': {
-        const query = `table ${args.tableName} column db_schema`;
-        const raw = rustSearch(query, 15);
-        const results = raw.map(normalizeResult).filter(r =>
+        const query = `db_schema.xml table ${args.tableName} column declarative schema`;
+        const raw = await rustSearchAsync(query, 40);
+        let results = raw.map(normalizeResult).filter(r =>
           r.path?.includes('db_schema.xml')
         );
+        results = rerank(results, { fileType: 'xml', pathContains: ['db_schema.xml'] });
 
         return {
           content: [{
             type: 'text',
-            text: `## Database schema for: ${args.tableName}\n\n` + formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, 15))
           }]
         };
       }
 
       case 'magento_module_structure': {
-        const raw = rustSearch(args.moduleName, 100);
+        const raw = await rustSearchAsync(args.moduleName, 100);
         const moduleName = args.moduleName.replace('_', '/');
         const results = raw.map(normalizeResult).filter(r =>
           r.path?.includes(moduleName) || r.module?.includes(args.moduleName)
@@ -914,9 +1116,25 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 });
 
 async function main() {
+  // Try to start persistent Rust serve process for fast queries
+  try {
+    startServeProcess();
+    // Give it a moment to load model+index
+    await new Promise(r => setTimeout(r, 100));
+  } catch {
+    // Non-fatal: falls back to execFileSync per query
+  }
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error('Magector MCP server started (Rust core backend)');
 }
 
+// Cleanup on exit
+process.on('exit', () => {
+  if (serveProcess) {
+    serveProcess.kill();
+  }
+});
+
 main().catch(console.error);