@noleemits/vision-builder-control-mcp 4.39.0 → 4.42.0

package/index.js

@@ -2,7 +2,8 @@
 /**
  * Noleemits Vision Builder Control MCP Server
  *
- * Provides 67 tools for building and managing WordPress/Elementor sites.
+ * Provides 69 tools for building and managing WordPress/Elementor sites.
+ * v4.42.0: audit_text + replace_text — unified search/replace across Elementor + post columns with literal/regex/fuzzy modes. Fuzzy mode tolerates NBSP, curly quotes/dashes, ideographic punctuation — fixes the "copy-pasted needle won't match" bug.
  * v4.35.0: PixelVault image integration — pixelvault_status, find_images, generate_image, get_batch_status, insert_image tools; proxy REST endpoints at /nvbc/v1/pixelvault/*.
  * v4.34.0: Design tokens auto-inject as CSS custom properties (--nvbc-color-*, --nvbc-fs-*, --nvbc-space-*) site-wide via wp_head; kit global CSS tools (get_kit_global_css, set_kit_global_css); get_kit_settings formatter handles gap-style objects.
  * v4.33.0: Elementor kit layout settings (get_kit_settings, set_kit_settings) — read/write container_width, viewports, gutter.
@@ -107,7 +108,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.39.0';
+const VERSION = '4.42.0';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
 // ================================================================
@@ -2632,9 +2633,20 @@ function getToolDefinitions() {
                 required: ['name']
             }
         },
+        {
+            name: 'list_menu_items',
+            description: 'List all items in a nav menu, in order. Returns each item\'s id, title, url, type, object (page/post/category/etc.), object_id, parent (parent item ID, 0 for top-level), order, target, classes (CSS class array), and description. Use before set_menu_items so you can patch one entry without losing the others.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    menu_id: { type: 'number', description: 'Menu ID from list_nav_menus' }
+                },
+                required: ['menu_id']
+            }
+        },
         {
             name: 'set_menu_items',
-            description: 'Bulk-replace all items in a nav menu. Each item: {title, url (for type=custom), type ("custom"|"post_type"|"taxonomy"), object ("page"|"post"|"category"), object_id, parent_index (for nesting — 0-based index of parent in this same array), target ("_blank")}. Items are inserted in order; nested items must come AFTER their parent in the array.',
+            description: 'Bulk-replace all items in a nav menu. Each item: {title, url (for type=custom), type ("custom"|"post_type"|"taxonomy"), object ("page"|"post"|"category"), object_id, parent_index (for nesting — 0-based index of parent in this same array), target ("_blank"), classes (CSS classes — string or array, applied as <li class="...">), description (free text shown by some menu widgets)}. Items are inserted in order; nested items must come AFTER their parent in the array.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2651,7 +2663,9 @@ function getToolDefinitions() {
                                 object:       { type: 'string', description: 'e.g. "page", "post", "category" — required when type !== "custom"' },
                                 object_id:    { type: 'number', description: 'WP object ID — required when type !== "custom"' },
                                 parent_index: { type: 'number', description: 'Index in this array of the parent item (for nesting). Omit for top-level.' },
-                                target:       { type: 'string', enum: ['_blank', ''], description: 'Optional. "_blank" opens in new tab.' }
+                                target:       { type: 'string', enum: ['_blank', ''], description: 'Optional. "_blank" opens in new tab.' },
+                                classes:      { description: 'CSS classes for the <li>. Pass a string ("mega-menu primary") or an array (["mega-menu", "primary"]). Useful for targeting specific items in CSS without relying on URL substrings.' },
+                                description:  { type: 'string', description: 'Optional description text. Some menu walkers render it; otherwise stored as data-description.' }
                             }
                         }
                     }
@@ -3054,6 +3068,42 @@ function getToolDefinitions() {
                 required: ['search', 'replace']
             }
         },
+        {
+            name: 'audit_text',
+            description: 'Unified text search across Elementor (full settings tree, every string value), post_content, post_title, and post_excerpt. The fuzzy mode tolerates unicode whitespace and punctuation variants — use it when a literal copy-pasted string mysteriously fails to match (NBSP between words, curly quotes/dashes/periods inserted by builders, etc.). Read-only.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    search: { type: 'string', description: 'Text or pattern to find.' },
+                    mode: { type: 'string', enum: ['literal', 'regex', 'fuzzy'], description: '"literal" (exact bytes), "regex" (PHP regex without delimiters, u flag forced), or "fuzzy" (tolerates NBSP, curly quotes/dashes/periods, ideographic whitespace). Default: literal.' },
+                    case_insensitive: { type: 'boolean', description: 'Ignore case. Default: false.' },
+                    stores: { type: 'array', items: { type: 'string', enum: ['elementor', 'post_content', 'post_title', 'post_excerpt'] }, description: 'Which stores to scan. Default: all four. Pass [\"elementor\"] to limit scope.' },
+                    post_type: { type: 'string', description: '"post", "page", "any", or a specific CPT slug. Default: any.' },
+                    include_drafts: { type: 'boolean', description: 'Include draft/private/pending posts. Default: true.' },
+                    limit: { type: 'number', description: 'Max posts to scan per store (default 1000, max 5000).' }
+                },
+                required: ['search']
+            }
+        },
+        {
+            name: 'replace_text',
+            description: 'Unified bulk find/replace across Elementor (entire settings tree), post_content, post_title, and post_excerpt. Same matching modes as audit_text — fuzzy mode is the fix for the "copy-pasted needle won\'t match" class of bug. ALWAYS dry_run=true first. Never changes post_modified date.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    search: { type: 'string', description: 'Text or pattern to find.' },
+                    replace: { type: 'string', description: 'Replacement text. For regex/fuzzy modes, $1 etc. work as backreferences in regex mode only.' },
+                    mode: { type: 'string', enum: ['literal', 'regex', 'fuzzy'], description: '"literal", "regex", or "fuzzy". Default: literal.' },
+                    case_insensitive: { type: 'boolean', description: 'Ignore case. Default: false.' },
+                    stores: { type: 'array', items: { type: 'string', enum: ['elementor', 'post_content', 'post_title', 'post_excerpt'] }, description: 'Stores to operate on. Default: all four.' },
+                    post_type: { type: 'string', description: '"post", "page", "any", CPT slug. Default: any.' },
+                    include_drafts: { type: 'boolean', description: 'Include draft/private/pending. Default: true.' },
+                    limit: { type: 'number', description: 'Max posts per store. Default 1000, max 5000.' },
+                    dry_run: { type: 'boolean', description: 'Preview without saving. Default: true (SAFE).' }
+                },
+                required: ['search', 'replace']
+            }
+        },
         {
             name: 'set_faq_schema',
             description: 'Set FAQPage JSON-LD schema on a single post. Stores in post meta and auto-injects into page head. Use for adding FAQ rich snippets to posts with Q&A content.',
@@ -4729,6 +4779,25 @@ async function handleToolCall(name, args) {
             : `Menu already existed: "${r.name}" (ID ${r.id})`);
     }
 
+    case 'list_menu_items': {
+        const r = await apiCall(`/menus/${args.menu_id}/items`);
+        if (!r.items || !r.items.length) return ok(`Menu ${args.menu_id} has no items.`);
+        const byParent = {};
+        r.items.forEach(it => { (byParent[it.parent || 0] ||= []).push(it); });
+        const lines = [];
+        const renderItem = (it, depth) => {
+            const indent = '  '.repeat(depth);
+            const target = it.type === 'custom'
+                ? it.url
+                : `${it.type}/${it.object}#${it.object_id}`;
+            const cls = Array.isArray(it.classes) && it.classes.length ? `  .${it.classes.join('.')}` : '';
+            lines.push(`${indent}[${it.id}] ${it.title} → ${target}${cls}`);
+            (byParent[it.id] || []).forEach(c => renderItem(c, depth + 1));
+        };
+        (byParent[0] || []).forEach(it => renderItem(it, 0));
+        return ok(`Menu ${r.menu_id} items (${r.items.length}):\n${lines.join('\n')}`);
+    }
+
     case 'set_menu_items': {
         const r = await apiCall(`/menus/${args.menu_id}/items`, 'POST', { items: args.items });
         const errLines = (r.errors || []).map(e => `  • #${e.index}: ${e.message}`);
@@ -5293,6 +5362,101 @@ async function handleToolCall(name, args) {
         return ok(out);
     }
 
+    case 'audit_text': {
+        const body = { search: stripCDATA(args.search) };
+        if (args.mode) body.mode = args.mode;
+        if (args.case_insensitive) body.case_insensitive = parseBool(args.case_insensitive, false);
+        if (args.stores) body.stores = args.stores;
+        if (args.post_type) body.post_type = args.post_type;
+        if (args.include_drafts !== undefined) body.include_drafts = parseBool(args.include_drafts, true);
+        if (args.limit) body.limit = args.limit;
+        const r = await apiCall('/audit-text', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+        const s = r.summary || { total_matches: 0, posts_affected: 0, by_store: {} };
+        let out = `=== AUDIT TEXT (${r.mode || 'literal'}${r.case_insensitive ? ', ci' : ''}) ===\n`;
+        out += `Search: "${r.search}"\n`;
+        out += `Stores: ${(r.stores || []).join(', ')}\n`;
+        out += `Total matches: ${s.total_matches} | Posts affected: ${s.posts_affected}\n`;
+        if (s.by_store && Object.keys(s.by_store).length) {
+            out += `By store: ${Object.entries(s.by_store).map(([k,v]) => `${k}=${v}`).join(', ')}\n`;
+        }
+        if (!r.matches?.length) {
+            out += '\nNo matches found.';
+            if (r.mode !== 'fuzzy') out += '\n💡 Try mode="fuzzy" to tolerate NBSP / curly punctuation.';
+            return ok(out);
+        }
+        // Group by post for readability
+        const groups = {};
+        r.matches.forEach(m => {
+            const key = `${m.post_id}|${m.post_title || ''}`;
+            (groups[key] = groups[key] || []).push(m);
+        });
+        Object.entries(groups).slice(0, 50).forEach(([key, ms]) => {
+            const [pid, title] = key.split('|');
+            out += `\n--- [${pid}] ${title} — ${ms.length} match(es) ---\n`;
+            ms.slice(0, 10).forEach(m => {
+                if (m.store === 'elementor') {
+                    out += `  [elementor.${m.widget || '?'}] ${m.element_id}.${m.field || ''}\n`;
+                } else {
+                    out += `  [${m.store}] ${m.field || ''}\n`;
+                }
+                out += `      raw: "${(m.raw_match || '').slice(0, 80).replace(/\n/g, ' ')}"\n`;
+                out += `      ctx: ${(m.context || '').slice(0, 160)}\n`;
+            });
+            if (ms.length > 10) out += `  … and ${ms.length - 10} more\n`;
+        });
+        if (Object.keys(groups).length > 50) out += `\n…and ${Object.keys(groups).length - 50} more posts (truncated)`;
+        return ok(out);
+    }
+
+    case 'replace_text': {
+        const body = {
+            search: stripCDATA(args.search),
+            replace: stripCDATA(args.replace),
+            dry_run: parseBool(args.dry_run, true),
+        };
+        if (args.mode) body.mode = args.mode;
+        if (args.case_insensitive) body.case_insensitive = parseBool(args.case_insensitive, false);
+        if (args.stores) body.stores = args.stores;
+        if (args.post_type) body.post_type = args.post_type;
+        if (args.include_drafts !== undefined) body.include_drafts = parseBool(args.include_drafts, true);
+        if (args.limit) body.limit = args.limit;
+        const r = await apiCall('/replace-text', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+        const s = r.summary || { total_matches: 0, posts_affected: 0, by_store: {} };
+        const tag = r.dry_run ? 'DRY RUN' : 'APPLIED';
+        let out = `=== REPLACE TEXT (${tag} · ${r.mode || 'literal'}${r.case_insensitive ? ', ci' : ''}) ===\n`;
+        out += `Search:  "${r.search}"\nReplace: "${r.replace}"\n`;
+        out += `Stores: ${(r.stores || []).join(', ')}\n`;
+        out += `Total matches: ${s.total_matches} | Posts affected: ${s.posts_affected}\n`;
+        if (s.by_store && Object.keys(s.by_store).length) {
+            out += `By store: ${Object.entries(s.by_store).map(([k,v]) => `${k}=${v}`).join(', ')}\n`;
+        }
+        if (!r.matches?.length) {
+            out += '\nNo matches found.';
+            if (r.mode !== 'fuzzy') out += '\n💡 Try mode="fuzzy" to tolerate NBSP / curly punctuation.';
+            return ok(out);
+        }
+        const groups = {};
+        r.matches.forEach(m => {
+            const key = `${m.post_id}|${m.post_title || ''}`;
+            (groups[key] = groups[key] || []).push(m);
+        });
+        Object.entries(groups).slice(0, 50).forEach(([key, ms]) => {
+            const [pid, title] = key.split('|');
+            out += `\n--- [${pid}] ${title} — ${ms.length} change(s) ---\n`;
+            ms.slice(0, 8).forEach(m => {
+                const loc = m.store === 'elementor'
+                    ? `elementor.${m.widget || '?'} ${m.element_id}.${m.field || ''}`
+                    : `${m.store}`;
+                out += `  [${loc}] "${(m.raw_match || '').slice(0, 60).replace(/\n/g, ' ')}"\n`;
+            });
+            if (ms.length > 8) out += `  … and ${ms.length - 8} more\n`;
+        });
+        if (r.dry_run) out += `\n(Dry run — no changes saved. Set dry_run=false to apply.)`;
+        return ok(out);
+    }
+
     case 'set_faq_schema': {
         const body = { post_id: args.post_id, faqs: args.faqs };
         if (args.dry_run !== undefined) body.dry_run = args.dry_run;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noleemits/vision-builder-control-mcp",
-  "version": "4.39.0",
+  "version": "4.42.0",
   "description": "Vision Builder Control MCP server - design token-driven page builder tools for WordPress/Elementor websites",
   "type": "module",
   "main": "index.js",