@noleemits/vision-builder-control-mcp 4.48.5 → 4.74.3

package/index.js

@@ -111,7 +111,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.48.5';
+const VERSION = '4.74.3';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
 // ================================================================
@@ -2002,6 +2002,21 @@ function getToolDefinitions() {
             description: 'Get all component style presets (saved overrides + resolved values with fallbacks). Shows which components have customizable styles.',
             inputSchema: { type: 'object', properties: {} }
         },
+        {
+            name: 'get_section_presets',
+            description: 'List all available section layout presets (cols-2, cols-3, cols-4, sidebar-left, sidebar-right, split, stack). Returns preset key, label, description, supported engines (v3/v4), and child column count. Use these keys with the append_section preset param to scaffold gap-safe multi-column layouts without writing Elementor JSON. v3 = classic Container widget. v4 = atomic e-flexbox (Elementor 3.25+).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    engine: {
+                        type: 'string',
+                        enum: ['v3', 'v4'],
+                        description: 'Optional. Filter by engine. Omit to return all presets.',
+                    },
+                },
+                required: [],
+            },
+        },
         {
             name: 'set_component_presets',
             description: 'Save style presets for a specific component. Empty values reset to defaults. Requires manage_options capability.',
@@ -2026,7 +2041,7 @@ function getToolDefinitions() {
                 type: 'object',
                 properties: {
                     page_id: { type: 'number', description: 'WordPress page ID' },
-                    category: { type: 'string', description: 'Component category: heroes, intros, stats, conditions, comparisons, videos, ctas, teams, tabs, blocks, cards' },
+                    category: { type: 'string', description: 'Component category: heroes, intros, stats, comparisons, ctas, teams, tabs, blocks, cards' },
                     name: { type: 'string', description: 'Component name (e.g., "hero-two-col-soft-blue", "stats-bar-4col-dark")' },
                     variables: { type: 'object', description: 'Variable values to populate (heading, description, buttons, etc.)' },
                     position: { type: 'string', description: 'Where to add: "append" (default), "prepend", or numeric index' },
@@ -2230,7 +2245,7 @@ function getToolDefinitions() {
         },
         {
             name: 'update_element',
-            description: 'Update any element\'s settings by its Elementor ID or path. Patch widget properties like hover_color, background_color, __globals__ overrides, text, link URLs, etc. Supports dot-notation for nested keys (e.g. "__globals__.hover_color"). Supports element_path as alternative to element_id (e.g. "sectionId/1/0" = section → child 1 → child 0). Use list_elements or export_page first to find the element ID and current settings. IMPORTANT: Prefer settings_json (JSON string) over settings (object) for reliable MCP transport. AUTO-INJECTED KEYS: background_background:"classic" auto-set when you set background_color; typography_typography:"custom" auto-set when you set font properties; flex_grow expands to all 3 required keys; grid column strings auto-wrapped in object format. ICON WIDGET: For view="default" use "icon_size" for dimensions. For view="stacked" or "framed" (circle/square background) use "size" instead — "icon_size" is silently ignored in stacked/framed mode. LOOP-GRID WIDGET: query settings use the prefix "post_query_" (post_query_post_type, post_query_orderby, post_query_order, post_query_posts_per_page) — NOT "posts_post_type". Setting "posts_post_type" is silently accepted but ignored. LOOP-CAROUSEL WIDGET: also uses "post_query_" prefix — NOT the older Elementor "query_" prefix. Both loop-grid and loop-carousel share the same query-control prefix; if you used "query_post_type" the write is silently accepted and ignored. Pull current settings via get_element first to confirm the prefix before patching. RACE CONDITION: when patching multiple elements on the SAME page in parallel, use batch_update_elements instead — parallel update_element calls can clobber each other. ATOMIC SCHEMA VALIDATION (v4.42.5+): writes that violate the Elementor V4 atomic schema are rejected up front (HTTP 400 invalid_atomic_setting) instead of silently corrupting the page. Currently enforced: e-heading.tag ∈ {h1..h6}, e-paragraph.tag ∈ {p, span}. If you need a non-heading visual element styled like an eyebrow, use e-paragraph (tag=p or span) — not e-heading with tag=div. NATIVE GRID/FLEX TIP: for container layout (grid columns, flex direction, gap), prefer set_container_layout — it produces WYSIWYG-editable native settings instead of forcing you to assemble the raw Elementor schema.',
+            description: 'Update any element\'s settings by its Elementor ID or path. Patch widget properties like hover_color, background_color, __globals__ overrides, text, link URLs, etc. Supports dot-notation for nested keys (e.g. "__globals__.hover_color"). Supports element_path as alternative to element_id (e.g. "sectionId/1/0" = section → child 1 → child 0). Use list_elements or export_page first to find the element ID and current settings. IMPORTANT: Prefer settings_json (JSON string) over settings (object) for reliable MCP transport. AUTO-INJECTED KEYS: background_background:"classic" auto-set when you set background_color; typography_typography:"custom" auto-set when you set font properties; flex_grow expands to all 3 required keys; grid column strings auto-wrapped in object format. ICON WIDGET: For view="default" use "icon_size" for dimensions. For view="stacked" or "framed" (circle/square background) use "size" instead — "icon_size" is silently ignored in stacked/framed mode. LOOP-GRID WIDGET: query settings use the prefix "post_query_" (post_query_post_type, post_query_orderby, post_query_order, post_query_posts_per_page) — NOT "posts_post_type". Setting "posts_post_type" is silently accepted but ignored. LOOP-CAROUSEL WIDGET: also uses "post_query_" prefix — NOT the older Elementor "query_" prefix. Both loop-grid and loop-carousel share the same query-control prefix; if you used "query_post_type" the write is silently accepted and ignored. Pull current settings via get_element first to confirm the prefix before patching. RACE CONDITION: when patching multiple elements on the SAME page in parallel, use batch_update_elements instead — parallel update_element calls can clobber each other. ATOMIC SCHEMA VALIDATION (v4.42.5+): writes that violate the Elementor V4 atomic schema are rejected up front (HTTP 400 invalid_atomic_setting) instead of silently corrupting the page. Currently enforced: e-heading.tag ∈ {h1..h6}, e-paragraph.tag ∈ {p, span}. If you need a non-heading visual element styled like an eyebrow, use e-paragraph (tag=p or span) — not e-heading with tag=div. NATIVE GRID/FLEX TIP: for container layout (grid columns, flex direction, gap), prefer set_container_layout — it produces WYSIWYG-editable native settings instead of forcing you to assemble the raw Elementor schema. NOTE: On V4 atomic elements (e-flexbox, e-section, e-div-block, e-grid), visual props (background_color, padding, etc.) are written to settings but V4 renders from the styles array — they will not apply visually. The response will include a warnings[] array when this occurs. Use set_kit_global_css with [data-id="<id>"] as the workaround.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2354,6 +2369,22 @@ function getToolDefinitions() {
                 required: ['source_page_id', 'element_id', 'target_page_id']
             }
         },
+        {
+            name: 'duplicate_children',
+            description: 'Clone every child of a source container (deep clone + fresh Elementor IDs) and insert the clones into a target container. Defaults to the SAME container — exactly what a seamless CSS marquee/carousel loop needs (the track must hold two identical copies of its item set so it can translateX(-50%) and loop). Unlike copy_element (which only drops a clone at the page top level), this inserts INTO a nested container. Use list_elements to find the container ID. Pass times>1 to append multiple copies.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_id: { type: 'number', description: 'WordPress page ID' },
+                    source_container_id: { type: 'string', description: 'Container whose children are cloned' },
+                    target_container_id: { type: 'string', description: 'Container to insert clones into. Defaults to source_container_id (duplicate in place).' },
+                    times: { type: 'number', description: 'Number of extra copies to append (default: 1)' },
+                    position: { type: 'string', description: '"append" (default) or "prepend"' },
+                    force: { type: 'boolean', description: 'Override edit locks (default: false)' }
+                },
+                required: ['page_id', 'source_container_id']
+            }
+        },
         {
             name: 'check_links',
             description: 'Check all URLs on Elementor pages for broken links (404, 500, timeout). Results are cached per-URL for 24 hours — subsequent calls are instant for already-checked URLs. Use force_refresh=true to re-fetch everything.',
@@ -3082,7 +3113,7 @@ function getToolDefinitions() {
         },
         {
             name: 'manage_redirects',
-            description: 'Manage RankMath 301 redirects. Actions: "create" (add redirects), "list" (show all), "delete" (remove by ID). Source paths should NOT include the site subdirectory prefix (e.g. /treatment-options/old-slug/), but destination paths SHOULD include it (e.g. /deuk/treatment-options/new-slug/).',
+            description: 'Manage RankMath 301 redirects. Actions: "create" (add redirects), "list" (show all), "delete" (remove by ID). Source paths should NOT include any site subdirectory prefix (e.g. /old-slug/); destination paths SHOULD include the subdirectory if the site uses one (e.g. /subdir/new-slug/).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3135,6 +3166,11 @@ function getToolDefinitions() {
             description: 'Read-only WordPress database health audit. Reports: post revision count (+ top pages by revision), expired transient count, autoloaded options total size + top 10 largest, orphaned postmeta count. Includes actionable cleanup recommendations. No data is modified.',
             inputSchema: { type: 'object', properties: {} }
         },
+        {
+            name: 'audit_builder_footprint',
+            description: 'Read-only builder/migration audit — scopes an Elementor → Gutenberg/Kadence migration in ONE call. Reports across ALL public post types: per-post-type split of elementor/gutenberg/classic; the complete Elementor rebuild worklist (every Elementor-built page/post/CPT item with section counts); ghost-data detection (items carrying _elementor_data but not flagged as Elementor); all elementor_library templates with their display conditions; orphaned-condition detection (conditions pointing at deleted posts); active theme and detected builders. No data is modified.',
+            inputSchema: { type: 'object', properties: { post_types: { type: 'string', description: 'Optional comma-separated post type slugs to scope the breakdown (e.g. "post,page,services"). Default: all public types.' } } }
+        },
         {
             name: 'audit_image_sizes',
             description: 'Scan Elementor pages for images using oversized WordPress sizes ("full" or "large"). Reports element ID, widget type, current size, actual file dimensions, and recommended size. Use to identify images that could be replaced with smaller WP registered sizes (medium_large, medium) to reduce page weight.',
@@ -3597,17 +3633,19 @@ function getToolDefinitions() {
         },
         {
             name: 'append_section',
-            description: 'Append a section to an existing page or template without downloading the full template. Pass the section JSON directly — no need to export, merge, and re-upload. Useful for adding CTA sections, footers, or any reusable block.',
+            description: 'Append a section to an existing page or template. Pass full section JSON OR use the preset param for instant gap-safe column layouts. PRESET SHORTHAND: pass preset="cols-3" (or cols-2, cols-4, sidebar-left, sidebar-right, split, stack) and the scaffold JSON is generated for you — no manual flex-grow JSON needed. The section param becomes optional when using preset; any settings in section are merged into the preset root (use it to set background_color, css_classes, _title, etc.). engine param selects v3 (classic Container) or v4 (atomic e-flexbox); auto-detected if omitted.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     target_id: { type: 'number', description: 'Page or template ID to append to' },
-                    section: { type: 'object', description: 'Full Elementor section object (must have elType and elements)' },
+                    section: { type: 'object', description: 'Full Elementor section object (must have elType and elements). Optional when preset is provided — only pass to override root settings (background, title, etc.).' },
+                    preset: { type: 'string', enum: ['cols-2', 'cols-3', 'cols-4', 'sidebar-left', 'sidebar-right', 'split', 'stack'], description: 'Layout preset name. When provided, section JSON is auto-generated. Columns are empty scaffolds — add content with add_element after.' },
+                    engine: { type: 'string', enum: ['v3', 'v4'], description: 'Elementor engine for preset. v3 = classic Container. v4 = atomic e-flexbox. Auto-detected from ELEMENTOR_VERSION if omitted.' },
                     position: { type: 'string', description: 'Where to place: "end" (default), "start", or numeric index' },
                     regenerate_ids: { type: 'boolean', description: 'Regenerate all element IDs to avoid collisions (default: true)' },
                     force: { type: 'boolean', description: 'Override edit locks (default: false)' }
                 },
-                required: ['target_id', 'section']
+                required: ['target_id']
             }
         },
         {
@@ -3807,7 +3845,7 @@ function getToolDefinitions() {
                 properties: {
                     profile: {
                         type: 'object',
-                        description: 'Key-value pairs to update. Example: {"site_name": "Deuk Spine", "primary_color": "#084D8F"}'
+                        description: 'Key-value pairs to update. Example: {"site_name": "Acme Inc.", "primary_color": "#2563EB"}'
                     }
                 },
                 required: ['profile']
@@ -3899,7 +3937,105 @@ function getToolDefinitions() {
                     applies_to: { type: 'string', enum: ['container', 'widget', 'heading', 'button', 'image', 'any'], description: 'Filter to classes that apply to this element type.' }
                 }
             }
-        }
+        },
+        {
+            name: 'list_element_classes',
+            description: 'Show the CSS classes assigned to elements on a page. Handles both v4 atomic (settings.classes) and v3 legacy (settings.css_classes) formats. Also shows whether each class is registered in the Elementor Global Classes registry (so the editor can show it as a named chip). If element_id is omitted, scans all elements and returns only those that have at least one class.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_id:    { type: 'number', description: 'WordPress page ID' },
+                    element_id: { type: 'string', description: '(Optional) Specific element ID. If omitted, scans all elements on the page.' }
+                },
+                required: ['page_id']
+            }
+        },
+        {
+            name: 'repair_page_classes',
+            description: 'Fix existing pages where element class values are stored as plain label strings instead of Elementor Global Classes registry IDs. Without this fix, the Elementor editor shows "local" chips instead of named class chips. Run once per page that was built before v4.66.1. Use dry_run: true to preview what would change before committing.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_id: { type: 'number', description: 'WordPress page ID to repair' },
+                    dry_run: { type: 'boolean', description: 'If true, reports what would change without writing (default: false)' }
+                },
+                required: ['page_id']
+            }
+        },
+        {
+            name: 'manage_element_classes',
+            description: 'Add, remove, or replace CSS classes on an Elementor element. Auto-detects v4 atomic (settings.classes) vs v3 (settings.css_classes) format. Newly added classes are auto-registered as stubs in the Elementor Global Classes registry so the editor shows them as named chips rather than "local". Actions: "add" appends without duplicates, "remove" strips the named classes, "set" replaces all classes on the element.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_id:    { type: 'number', description: 'WordPress page ID' },
+                    element_id: { type: 'string', description: 'Elementor element ID to update' },
+                    action:     { type: 'string', enum: ['add', 'remove', 'set'], description: '"add" appends without duplicates; "remove" strips the named classes; "set" replaces all classes' },
+                    classes:    { type: 'array', items: { type: 'string' }, description: 'Class names (not registry IDs). e.g. ["nvbc-hero", "nvbc-band--dark"]' }
+                },
+                required: ['page_id', 'element_id', 'action', 'classes']
+            }
+        },
+        {
+            name: 'upsert_class',
+            description: 'Define or update a site CSS class — stores metadata in the class registry AND writes the CSS body to the active kit\'s global CSS. Replaces the two-step workflow of patch_kit_global_css + manage_element_classes. The class appears in list_classes with source=[site]. Optional apply_to: attach the class to element IDs on specific pages in the same call. To update an existing class\'s CSS, call again with the same name — the kit CSS block is replaced, not appended. v4.69.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name:        { type: 'string', description: 'CSS class name without leading dot. Lowercase, hyphens and underscores only. e.g. "ef-font-display"' },
+                    css:         { type: 'string', description: 'CSS property declarations for the class body — no selector, no braces. e.g. "font-size: clamp(40px, 5vw, 72px); font-family: \'Cormorant Garamond\', serif;"' },
+                    description: { type: 'string', description: 'Human-readable description shown in list_classes output.' },
+                    category:    { type: 'string', enum: ['hero', 'cards', 'layout', 'grid', 'spacing', 'typography', 'decorative', 'utility'], description: 'Category for list_classes grouping. Default: "utility".' },
+                    applies_to:  { type: 'array', items: { type: 'string' }, description: 'Element types this class applies to. Default: ["any"].' },
+                    apply_to:    {
+                        type: 'array',
+                        description: 'Optional: attach this class to these elements in the same call.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                page_id:    { type: 'number', description: 'WordPress page ID' },
+                                element_id: { type: 'string', description: 'Elementor element ID' }
+                            },
+                            required: ['page_id', 'element_id']
+                        }
+                    }
+                },
+                required: ['name']
+            }
+        },
+        {
+            name: 'delete_class',
+            description: 'Remove a site-custom class from the class registry AND remove its CSS block from the active kit\'s global CSS. Cannot delete plugin built-in classes (source=plugin). v4.69.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'CSS class name to remove (no leading dot).' }
+                },
+                required: ['name']
+            }
+        },
+        {
+            name: 'list_class_snapshots',
+            description: 'List version-history snapshots of the CSS class system (registry + stylesheet). Each entry shows id, time, label, author, and whether it was auto-captured before a mutation. v4.74.0+.',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'create_class_snapshot',
+            description: 'Manually capture the current CSS class state (registry custom classes + stylesheet) as a restorable snapshot. No-op if nothing changed since the last snapshot. v4.74.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: { label: { type: 'string', description: 'Human label for this snapshot, e.g. "before ef-* migration".' } },
+            }
+        },
+        {
+            name: 'restore_class_snapshot',
+            description: 'Restore the CSS class system to a previous snapshot (by id from list_class_snapshots). The current state is auto-snapshotted first, so restore is itself reversible. v4.74.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: { id: { type: 'string', description: 'Snapshot id from list_class_snapshots.' } },
+                required: ['id']
+            }
+        },
     ];
 }
 
@@ -4168,6 +4304,22 @@ async function handleToolCall(name, args) {
         return ok(out);
     }
 
+    case 'get_section_presets': {
+        try {
+            const r = await apiCall('/section-presets');
+            if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+            const list = Array.isArray(r) ? r : [];
+            if (list.length === 0) return ok('No section presets found.');
+            const filtered = args.engine ? list.filter(p => p.engines.includes(args.engine)) : list;
+            const lines = filtered.map(p =>
+                `• ${p.key.padEnd(16)} ${p.label} (${p.engines.join('/')}, ${p.children} col${p.children !== 1 ? 's' : ''})\n  ${p.description}`
+            );
+            return ok(`Available section layout presets:\n\n${lines.join('\n\n')}\n\nUse with: append_section(target_id, preset="<key>", engine="v3|v4")`);
+        } catch (err) {
+            return ok(`Failed: ${err.message}`);
+        }
+    }
+
     case 'set_component_presets': {
         const r = await apiCall('/component-presets', 'POST', {
             component_id: args.component_id,
@@ -4715,6 +4867,25 @@ async function handleToolCall(name, args) {
         return ok(msg);
     }
 
+    case 'duplicate_children': {
+        const body = {
+            page_id: args.page_id,
+            source_container_id: args.source_container_id,
+        };
+        if (args.target_container_id) body.target_container_id = args.target_container_id;
+        if (args.times) body.times = args.times;
+        if (args.position) body.position = args.position;
+        if (args.force) body.force = true;
+        const r = await apiCall('/duplicate-children', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+        let msg = `Children duplicated!\n`;
+        msg += `Source container: ${r.source_container_id} (${r.children_per_copy} children)\n`;
+        msg += `Target container: ${r.target_container_id}\n`;
+        msg += `Copies appended: ${r.times} → ${r.total_cloned} new elements (${r.position})\n`;
+        msg += `New IDs: ${(r.new_ids || []).join(', ')}`;
+        return ok(msg);
+    }
+
     case 'check_links': {
         const params = new URLSearchParams();
         if (args.page_id)       params.set('page_id', args.page_id);
@@ -5672,6 +5843,70 @@ async function handleToolCall(name, args) {
         return ok(out);
     }
 
+    case 'audit_builder_footprint': {
+        const params = new URLSearchParams();
+        if (args.post_types) params.set('post_types', args.post_types);
+        const qs = params.toString() ? `?${params}` : '';
+        const r = await apiCall(`/audit-builder-footprint${qs}`);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        const s = r.summary;
+        let out = `=== BUILDER FOOTPRINT / MIGRATION AUDIT ===\n`;
+        out += `Active theme: ${r.active_theme.name} (template: ${r.active_theme.template})\n`;
+        const activeBuilders = Object.entries(r.builders).filter(([, v]) => v).map(([k]) => k);
+        out += `Builders detected: ${activeBuilders.join(', ')}\n`;
+        out += `\nElementor items to rebuild: ${s.elementor_items_total}`;
+        const byType = Object.entries(s.elementor_by_type || {}).map(([t, c]) => `${c} ${t}`).join(', ');
+        if (byType) out += ` (${byType})`;
+        out += `\nTemplates: ${s.templates_total} (${s.site_wide_templates} site-wide)\n`;
+        out += `Ghost-data items: ${s.ghost_data_items} | Orphaned conditions: ${s.orphaned_conditions}\n`;
+
+        out += `\n--- Builder split by post type ---\n`;
+        r.by_post_type.forEach(t => {
+            out += `  ${t.label} (${t.post_type}): ${t.total} total — ${t.elementor} elementor / ${t.gutenberg} gutenberg / ${t.classic} classic\n`;
+        });
+
+        if (r.elementor_items.length) {
+            out += `\n--- Elementor rebuild worklist ---\n`;
+            r.elementor_items.forEach(it => {
+                out += `  [${it.id}] ${it.title} (${it.type}, ${it.status}) — ${it.sections} section(s)\n`;
+            });
+        }
+
+        if (r.ghost_data.length) {
+            out += `\n--- Ghost Elementor data (converted, stale data left behind) ---\n`;
+            r.ghost_data.forEach(g => {
+                out += `  [${g.id}] ${g.title} (${g.type}) — ${g.sections} section(s) of stale data\n`;
+            });
+        }
+
+        if (r.templates.length) {
+            out += `\n--- Elementor templates ---\n`;
+            r.templates.forEach(tp => {
+                const flags = [];
+                if (tp.site_wide) flags.push('SITE-WIDE');
+                if (tp.orphaned_conditions.length) flags.push(`${tp.orphaned_conditions.length} ORPHANED`);
+                const flagStr = flags.length ? ` [${flags.join(', ')}]` : '';
+                out += `  [${tp.id}] ${tp.title} (${tp.template_type})${flagStr}\n`;
+                if (tp.conditions.length) out += `      conditions: ${tp.conditions.join('; ')}\n`;
+                if (tp.orphaned_conditions.length) out += `      orphaned: ${tp.orphaned_conditions.join('; ')}\n`;
+            });
+        }
+
+        out += `\n--- DB health ---\n`;
+        out += `  Orphaned postmeta: ${r.db_health.orphaned_postmeta} | Revisions: ${r.db_health.revisions}\n`;
+        if (r.db_health.elementor_autoload_options?.length) {
+            out += `  Elementor autoloaded options:\n`;
+            r.db_health.elementor_autoload_options.forEach(o => { out += `    ${o.size_kb} KB — ${o.name}\n`; });
+        }
+
+        if (r.recommendations?.length) {
+            out += `\n--- Recommendations ---\n`;
+            r.recommendations.forEach(rec => { out += `  • ${rec}\n`; });
+        }
+        out += `\nNote: ${r.note}`;
+        return ok(out);
+    }
+
     case 'audit_image_sizes': {
         const params = new URLSearchParams();
         if (args.page_id) params.set('page_id', args.page_id);
@@ -6311,6 +6546,7 @@ async function handleToolCall(name, args) {
         if (args.quality) body.quality = args.quality;
         const r = await apiCall('/pixelvault/generate', 'POST', body);
         if (r.error || r.code) return ok(`Generation failed: ${r.detail || r.message || r.error} [${r.category || ''}]`);
+        if (!r.batch_id) return ok('Generation failed: PixelVault returned no batch_id. Cannot poll. Check PixelVault queue endpoint response.');
         let out = `=== IMAGE GENERATION STARTED ===\n`;
         out += `Batch ID: ${r.batch_id}\n`;
         out += `Status:   ${r.status || 'generating'}\n`;
@@ -7270,6 +7506,26 @@ async function handleToolCall(name, args) {
         return ok(`Front page set to "${r.front_page_title}" (ID: ${r.front_page_id})${r.blog_page_id ? `\nBlog page: ${r.blog_page_id}` : ''}`);
     }
 
+    case 'list_class_snapshots': {
+        const r = await apiCall('/class-snapshots');
+        const snaps = r.snapshots || [];
+        if (!snaps.length) return ok('No class snapshots yet.');
+        let msg = `Class snapshots (newest first):\n`;
+        for (const s of snaps) {
+            const when = new Date(s.time * 1000).toISOString().replace('T', ' ').slice(0, 16);
+            msg += `  ${s.id}\n    ${when} · ${s.label} · by ${s.author}${s.auto ? ' · auto' : ''}\n    ${s.custom_count} custom classes${s.has_stylesheet ? ' · custom stylesheet' : ' · default stylesheet'}\n`;
+        }
+        return ok(msg);
+    }
+    case 'create_class_snapshot': {
+        const r = await apiCall('/class-snapshots', 'POST', { label: args.label || '' });
+        return ok(r.created ? `Snapshot created: ${r.id}` : `Not created: ${r.reason || 'unknown'}`);
+    }
+    case 'restore_class_snapshot': {
+        const r = await apiCall(`/class-snapshots/${encodeURIComponent(args.id)}/restore`, 'POST');
+        return ok(r.restored ? `Restored snapshot ${args.id}. (Prior state was auto-snapshotted first.)` : `Restore failed: ${r.message || r.code || 'unknown'}`);
+    }
+
     case 'list_classes': {
         const params = new URLSearchParams();
         if (args.category)   params.set('category', args.category);
@@ -7294,10 +7550,191 @@ async function handleToolCall(name, args) {
                 msg += `  .${c.name}  ${src}\n`;
                 msg += `    ${c.description}\n`;
                 msg += `    Applies to: ${tags}\n`;
+                if (c.source === 'site' && c.css) {
+                    const preview = c.css.split('\n')[0].trim();
+                    msg += `    CSS: ${preview}${c.css.includes('\n') ? ' …' : ''}\n`;
+                }
+            }
+            msg += '\n';
+        }
+
+        return ok(msg);
+    }
+
+    case 'upsert_class': {
+        // 1. Save class definition to registry (with optional css field)
+        const regBody = {
+            name:        args.name,
+            description: args.description || '',
+            category:    args.category    || 'utility',
+            applies_to:  args.applies_to  || ['any'],
+        };
+        if (args.css) regBody.css = args.css;
+
+        const r = await apiCall('/class-registry/custom', 'POST', regBody);
+        if (r.error || r.code) return ok(`Failed to save class definition: ${r.message || r.error}`);
+
+        let msg = `Class .${args.name} saved to registry.\n`;
+
+        // 2. Write CSS block to kit global CSS when css is provided
+        if (args.css) {
+            const startMarker = `/* nvbc-class: .${args.name} */`;
+            const endMarker   = `/* /nvbc-class: .${args.name} */`;
+            const cssBlock    = `${startMarker}\n.${args.name} {\n  ${args.css.trim()}\n}\n${endMarker}`;
+
+            const kitCss  = await apiCall('/kit-global-css');
+            const existing = kitCss.css || '';
+
+            const escStart = startMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const escEnd   = endMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const blockRe  = new RegExp(escStart + '[\\s\\S]*?' + escEnd);
+
+            const newCss = blockRe.test(existing)
+                ? existing.replace(blockRe, cssBlock)
+                : (existing.trimEnd() + '\n\n' + cssBlock + '\n');
+
+            const cssResult = await apiCall('/kit-global-css', 'POST', { css: newCss });
+            msg += cssResult.success
+                ? `CSS block written to kit global CSS for .${args.name}.\n`
+                : `Warning: class metadata saved but kit CSS write failed: ${cssResult.message || 'unknown'}\n`;
+        }
+
+        // 3. Attach to elements if apply_to provided
+        if (args.apply_to?.length) {
+            for (const target of args.apply_to) {
+                const r2 = await apiCall(`/pages/${target.page_id}/element-classes`, 'POST', {
+                    element_id: target.element_id,
+                    action:     'add',
+                    classes:    [args.name],
+                });
+                msg += r2.success !== false
+                    ? `Added .${args.name} to element ${target.element_id} on page ${target.page_id}.\n`
+                    : `Failed to add to element ${target.element_id} on page ${target.page_id}: ${r2.message || 'unknown'}\n`;
             }
+        }
+
+        return ok(msg);
+    }
+
+    case 'delete_class': {
+        // 1. Remove from registry
+        const delResult = await apiCall(`/class-registry/custom/${encodeURIComponent(args.name)}`, 'DELETE');
+        if (delResult.code || delResult.error) {
+            return ok(`Failed to remove class from registry: ${delResult.message || delResult.error}`);
+        }
+
+        let msg = `Class .${args.name} removed from registry.\n`;
+
+        // 2. Remove CSS block from kit global CSS
+        const startMarker = `/* nvbc-class: .${args.name} */`;
+        const endMarker   = `/* /nvbc-class: .${args.name} */`;
+        const escStart    = startMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const escEnd      = endMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const blockRe     = new RegExp('\\n*' + escStart + '[\\s\\S]*?' + escEnd + '\\n*');
+
+        const kitCss  = await apiCall('/kit-global-css');
+        const existing = kitCss.css || '';
+
+        if (blockRe.test(existing)) {
+            const newCss    = existing.replace(blockRe, '\n').replace(/\n{3,}/g, '\n\n');
+            const cssResult = await apiCall('/kit-global-css', 'POST', { css: newCss });
+            msg += cssResult.success
+                ? `CSS block for .${args.name} removed from kit global CSS.\n`
+                : `Warning: registry entry deleted but kit CSS removal failed: ${cssResult.message || 'unknown'}\n`;
+        } else {
+            msg += `No managed CSS block found for .${args.name} in kit global CSS (may have been set manually — remove it there if needed).\n`;
+        }
+
+        return ok(msg);
+    }
+
+    case 'repair_page_classes': {
+        const r = await apiCall(`/pages/${args.page_id}/repair-element-classes`, 'POST', {
+            dry_run: args.dry_run ?? false,
+        });
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+
+        let msg = `${r.dry_run ? '[DRY RUN] ' : ''}Page ${r.page_id} — ${r.message}\n`;
+        if (r.classes?.length) {
+            msg += `\nClasses affected:\n`;
+            for (const cls of r.classes) msg += `  .${cls}\n`;
+        }
+        return ok(msg);
+    }
+
+    case 'list_element_classes': {
+        const params = new URLSearchParams();
+        if (args.element_id) params.set('element_id', args.element_id);
+
+        const r = await apiCall(`/pages/${args.page_id}/element-classes?${params}`);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+
+        if (args.element_id) {
+            const el = r.element;
+            let msg = `=== Element: ${el.element_id} ===\n`;
+            msg += `Type: ${el.elType}${el.widgetType ? '/' + el.widgetType : ''}`;
+            if (el.title) msg += ` "${el.title}"`;
             msg += '\n';
+
+            if (el.v4_classes.length) {
+                msg += `\nV4 Atomic Classes (${el.v4_classes.length}):\n`;
+                for (const cls of el.v4_classes) msg += `  .${cls}\n`;
+            }
+            if (el.v3_classes.length) {
+                msg += `\nV3 Classes (${el.v3_classes.length}):\n`;
+                for (const cls of el.v3_classes) msg += `  .${cls}\n`;
+            }
+            if (!el.v4_classes.length && !el.v3_classes.length) {
+                msg += '\nNo classes assigned.\n';
+            }
+            if (el.registered.length) {
+                msg += `\nRegistered in Global Classes:\n`;
+                for (const reg of el.registered) {
+                    msg += `  .${reg.label}  [${reg.id}]${reg.has_css ? ' (has CSS)' : ' (stub only)'}\n`;
+                }
+            }
+            if (el.unregistered.length) {
+                msg += `\nNot in Global Classes registry (no editor chip):\n`;
+                for (const cls of el.unregistered) msg += `  .${cls}\n`;
+            }
+            return ok(msg);
+        }
+
+        // Page scan
+        if (!r.elements?.length) {
+            return ok(`No elements with classes found on page ${args.page_id}.`);
+        }
+
+        let msg = `=== Element Classes — Page ${args.page_id} (${r.count} elements with classes) ===\n\n`;
+        for (const el of r.elements) {
+            const all     = [...(el.v4_classes || []), ...(el.v3_classes || [])];
+            const typeStr = el.elType + (el.widgetType ? '/' + el.widgetType : '');
+            const titleStr = el.title ? ` "${el.title}"` : '';
+            msg += `${el.element_id}  [${typeStr}]${titleStr}\n`;
+            msg += `  ${all.join('  ')}\n`;
         }
+        return ok(msg);
+    }
+
+    case 'manage_element_classes': {
+        const r = await apiCall(`/pages/${args.page_id}/element-classes`, 'POST', {
+            element_id: args.element_id,
+            action:     args.action,
+            classes:    args.classes,
+        });
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
 
+        const el  = r.element;
+        const all = el ? [...(el.v4_classes || []), ...(el.v3_classes || [])] : r.classes;
+
+        let msg = `Classes ${r.action}d on ${r.element_id} (${r.format})\n`;
+        msg += `Classes now: ${all.length ? all.join(', ') : '(none)'}\n`;
+        if (el?.registered?.length) {
+            msg += `Registered: ${el.registered.map(x => x.label).join(', ')}\n`;
+        }
+        if (el?.unregistered?.length) {
+            msg += `Auto-registered stubs: ${el.unregistered.join(', ')}\n`;
+        }
         return ok(msg);
     }
 

package/package.json

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