@noleemits/vision-builder-control-mcp 4.45.2 → 4.46.1

package/index.js

@@ -2,7 +2,8 @@
 /**
  * Noleemits Vision Builder Control MCP Server
  *
- * Provides 69 tools for building and managing WordPress/Elementor sites.
+ * Provides 71 tools for building and managing WordPress/Elementor sites.
+ * v4.46.0: Saxon-feedback batch — capability_check tool (probe site plugin version + registered routes); replace_widget_content tool (full-setting replacement scoped by widget type, with exclude_match for idempotency — kills the "swap form HTML on 32 pages" use case in one call); list_elements flat-filter mode (widget_type / container_title / settings_contains — no more 5–15k-token tree dumps for ID discovery); find_replace now scans html + shortcode widget content; replace_text + audit_text auto-scope (post_type=any + no limit defaults to 200/store instead of 1000 to bound runtime); check_page_lock surfaces elementor_data_size + recently-expired _edit_lock to diagnose "hang despite unlocked" (slow save_post cascade, not lock); set_time_limit(300) on bulk ops + remove_section; clearer 404 errors that point at capability_check; list_posts accepts `limit` as alias for `per_page`.
  * v4.45.0: patch_kit_global_css — surgical CSS operations (remove_rule, remove_selector_from_rules, find_replace) without full-payload round-trip; solves 30k-token MCP param-size barrier for large kits.
  * 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/*.
@@ -50,6 +51,7 @@
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { startParentWatchdog } from "./parent-watchdog.js";
 import {
     CallToolRequestSchema,
     ListToolsRequestSchema,
@@ -109,7 +111,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.45.2';
+const VERSION = '4.46.1';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
 // ================================================================
@@ -1741,12 +1743,28 @@ async function apiCall(endpoint, method = 'GET', body = null) {
         if (body) options.body = JSON.stringify(body);
 
         const response = await fetch(url, options);
-        const data = await response.json();
-        if (!response.ok) throw new Error(data.message || `HTTP ${response.status}`);
+        let data;
+        try { data = await response.json(); } catch (_e) { data = {}; }
+        if (!response.ok) {
+            // v4.46.0+: clearer error when the backend doesn't have this route registered
+            // (almost always means the site's NVBC plugin is older than the MCP server expects).
+            if (response.status === 404 && (data.code === 'rest_no_route' || /No route was found/i.test(data.message || ''))) {
+                const err = new Error(
+                    `Backend route missing on this site: ${method} ${endpoint}. ` +
+                    `The connected WordPress site is running an older version of noleemits-vision-builder-control ` +
+                    `that doesn't expose this endpoint. Run the capability_check tool to see the site's plugin version ` +
+                    `+ registered routes, then update the site plugin if needed.`
+                );
+                err.code = 'rest_no_route';
+                throw err;
+            }
+            throw new Error(data.message || `HTTP ${response.status}`);
+        }
         return data;
     } catch (err) {
         if (err.name === 'AbortError') {
-            throw new Error(`Request timed out after ${FETCH_TIMEOUT_MS / 1000}s: ${method} ${endpoint}`);
+            throw new Error(`Request timed out after ${FETCH_TIMEOUT_MS / 1000}s: ${method} ${endpoint}. ` +
+                `For bulk tools, narrow scope with post_type / limit / chunk_size and retry.`);
         }
         throw err;
     } finally {
@@ -1879,6 +1897,11 @@ function getToolDefinitions() {
             description: 'Check connection to Vision Builder Control WordPress plugin',
             inputSchema: { type: 'object', properties: {} }
         },
+        {
+            name: 'capability_check',
+            description: 'Probe the connected WordPress site for the actual plugin version + every REST route the plugin has registered. Use when a tool returns "Backend route missing on this site" / "No route was found" — this confirms the site is running an older plugin version than the MCP server expects. Output includes a mismatch report comparing MCP-required routes against what the backend actually exposes, so callers can decide whether to update the site plugin. v4.46.0+.',
+            inputSchema: { type: 'object', properties: {} }
+        },
         {
             name: 'get_design_tokens',
             description: 'Get all design tokens (colors, typography, spacing, URLs, buttons, globals_map). Tokens are cached for 5 minutes.',
@@ -2091,13 +2114,16 @@ function getToolDefinitions() {
         },
         {
             name: 'list_elements',
-            description: 'List the element tree inside a page or specific section. Shows IDs, types, widget names, and text previews for every container and widget. Use to find element IDs before remove_element.',
+            description: 'List the element tree inside a page or specific section. Shows IDs, types, widget names, and text previews for every container and widget. Use to find element IDs before remove_element. v4.46.0+: pass any of widget_type / container_title / settings_contains to switch to FLAT-FILTER MODE — returns only matching widget stubs ({id, widget, path, parent_id, label}) instead of the full tree. Strongly recommended for ID lookup on large pages to avoid 5–15K-token tree dumps.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     page_id: { type: 'number', description: 'WordPress page ID' },
-                    section_index: { type: 'number', description: 'Only show this section (0-based). Omit to show all sections.' },
-                    depth: { type: 'number', description: 'Max nesting depth (default: 10). When exceeded, returns children_ids stubs with {id, type, widget}.' }
+                    section_index: { type: 'number', description: 'Only show this section (0-based). Omit to show all sections. Ignored in flat-filter mode.' },
+                    depth: { type: 'number', description: 'Max nesting depth (default: 10). When exceeded, returns children_ids stubs with {id, type, widget}. Ignored in flat-filter mode.' },
+                    widget_type: { type: 'string', description: 'FLAT-FILTER. Match elements with this widgetType (e.g. "html", "heading", "button", "loop-grid"). Case-insensitive. v4.46.0+.' },
+                    container_title: { type: 'string', description: 'FLAT-FILTER. Match elements whose own or ancestor section/container settings._title contains this substring (case-insensitive). E.g. "SF contact form" finds widgets inside any container labeled "SF contact form". v4.46.0+.' },
+                    settings_contains: { type: 'string', description: 'FLAT-FILTER. Match elements whose serialized settings JSON contains this substring (case-insensitive). Use to find widgets by content predicate, e.g. settings_contains:"webto.salesforce.com". v4.46.0+.' }
                 },
                 required: ['page_id']
             }
@@ -2133,7 +2159,7 @@ function getToolDefinitions() {
         },
         {
             name: 'check_page_lock',
-            description: 'Check if a page is being edited by someone in the Elementor editor or by another MCP operation. Returns WP post lock (user, time) and MCP transient lock info. Use before write operations to avoid conflicts.',
+            description: 'Check if a page is being edited. Reports the same two locks that write operations (remove_section, update_element, etc.) actually enforce: WP _edit_lock postmeta within its 150s active window + nvbc_mcp_lock transient. v4.46.0+: also returns elementor_data_size_bytes — a multi-MB tree is the #1 cause of "hangs" that look like lock contention but are actually slow save_post / Elementor CSS regeneration after the write commits. If this tool reports unlocked but a write op still appears to stall, the cause is downstream of the lock check (post-save hook chain on a big page), not the lock itself — force=true on the write op will not help with that.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2204,7 +2230,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. 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.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2298,7 +2324,7 @@ function getToolDefinitions() {
         },
         {
             name: 'find_replace',
-            description: 'Global find & replace across all Elementor pages. Searches heading titles, text-editor HTML, button text, image-box titles/descriptions, icon-box titles/descriptions, icon-list items, toggle titles/content, and image alt text. Supports literal text or regex. Never changes post_modified date (Elementor meta only). Always preview with dry_run=true first.',
+            description: 'Global find & replace across all Elementor pages. Searches heading titles, text-editor HTML, button text, html widget content (v4.46.0+), shortcode widget content (v4.46.0+), image-box titles/descriptions, icon-box titles/descriptions, icon-list items, toggle titles/content, and image alt text. Also rewrites URL fields (button_link, image.url, icon-list link.url, image.alt) and href attributes inside text-editor HTML. Supports literal text or regex. Never changes post_modified date (Elementor meta only). Always preview with dry_run=true first.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2367,7 +2393,8 @@ function getToolDefinitions() {
                     category: { type: 'string', description: 'Filter by category: ID (number) or slug (string). Only applies to post types with categories.' },
                     date_after: { type: 'string', description: 'Filter posts after this date (YYYY-MM-DD)' },
                     date_before: { type: 'string', description: 'Filter posts before this date (YYYY-MM-DD)' },
-                    per_page: { type: 'number', description: 'Results per page, max 100 (default: 50)' },
+                    per_page: { type: 'number', description: 'Results per page, max 100 (default: 50). `limit` is accepted as an alias (v4.46.0+).' },
+                    limit: { type: 'number', description: 'Alias for per_page (v4.46.0+).' },
                     page: { type: 'number', description: 'Page number (default: 1)' }
                 }
             }
@@ -3142,16 +3169,16 @@ function getToolDefinitions() {
                     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.' },
+                    post_type: { type: 'string', description: '"post", "page", "any", or a specific CPT slug. Default: any. Note: with post_type=any + no explicit limit, the per-store cap is 200 (v4.46.0+); pass limit explicitly for broader sweeps.' },
                     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).' }
+                    limit: { type: 'number', description: 'Max posts to scan per store. Default 1000 for narrow post_type, 200 when post_type=any. 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.',
+            description: 'Unified bulk find/replace across Elementor (entire settings tree — including html widget content, text-editor HTML, headings, button text, every nested setting), 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. v4.46.0+: when post_type=any and limit is omitted, per-store cap drops to 200 (was 1000) — pass an explicit `limit` to scan more. If this tool returns 404/"Backend route missing", run capability_check to see if the site\'s plugin is older than v4.42.0.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3160,14 +3187,34 @@ function getToolDefinitions() {
                     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.' },
+                    post_type: { type: 'string', description: '"post", "page", "any", CPT slug. Default: any. Note: with "any" + no explicit limit, the per-store cap is 200; pass limit explicitly for broader sweeps.' },
                     include_drafts: { type: 'boolean', description: 'Include draft/private/pending. Default: true.' },
-                    limit: { type: 'number', description: 'Max posts per store. Default 1000, max 5000.' },
+                    limit: { type: 'number', description: 'Max posts per store. Default 1000 for narrow post_type, 200 when post_type=any. Max 5000. Pass an explicit number to widen unbounded scans.' },
                     dry_run: { type: 'boolean', description: 'Preview without saving. Default: true (SAFE).' }
                 },
                 required: ['search', 'replace']
             }
         },
+        {
+            name: 'replace_widget_content',
+            description: 'Replace an entire widget setting (full overwrite, not substring) on every widget that matches a content predicate. Migration tool for tasks like swapping a Salesforce form HTML in every html widget that still contains "webto.salesforce.com" — substring tools like replace_text or find_replace cannot do this safely because you need to overwrite the whole setting, not splice the new value into the old one. Use exclude_match for idempotency (skip widgets already migrated to the new content). ALWAYS dry_run=true first to preview which widgets would be touched. v4.46.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    widget_type: { type: 'string', description: 'Elementor widgetType to target, e.g. "html", "shortcode", "text-editor". Case-insensitive.' },
+                    setting: { type: 'string', description: 'Which setting on that widget to read+overwrite, e.g. "html" for the html widget, "editor" for text-editor, "shortcode" for shortcode widget.' },
+                    search: { type: 'string', description: 'Content predicate — only widgets whose setting contains this substring match.' },
+                    replace_with: { type: 'string', description: 'The COMPLETE new value for the setting (not a substring replacement — the whole setting value gets overwritten with this).' },
+                    exclude_match: { type: 'string', description: 'Optional. Skip the widget if its setting already contains this substring. Use for idempotency, e.g. exclude_match:"saxon-contact-form" to avoid re-migrating already-migrated widgets.' },
+                    post_type: { type: 'string', description: '"post" | "page" | "any" (default) | CPT slug.' },
+                    include_drafts: { type: 'boolean', description: 'Include draft/private/pending. Default: true.' },
+                    limit: { type: 'number', description: 'Max posts to scan. Default 200 when post_type=any, 1000 otherwise. Max 5000.' },
+                    case_insensitive: { type: 'boolean', description: 'Case-insensitive match for search + exclude_match. Default: false.' },
+                    dry_run: { type: 'boolean', description: 'Preview without saving. Default: true (SAFE).' }
+                },
+                required: ['widget_type', 'setting', 'search', 'replace_with']
+            }
+        },
         {
             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.',
@@ -3857,6 +3904,70 @@ async function handleToolCall(name, args) {
         }
     }
 
+    case 'capability_check': {
+        try {
+            const r = await apiCall('/health?include_routes=1');
+            const routes = r.routes || {};
+            const exposedPaths = new Set(Object.keys(routes));
+
+            // Required-route map: which backend route each MCP tool depends on.
+            // Keep this in sync with the most commonly-failing routes — not exhaustive.
+            const requiredRoutes = {
+                replace_text: '/nvbc/v1/replace-text',
+                audit_text: '/nvbc/v1/audit-text',
+                find_replace: '/nvbc/v1/find-replace',
+                replace_widget_content: '/nvbc/v1/replace-widget-content',
+                list_elements: '/nvbc/v1/pages/{id}/elements',
+                remove_section: '/nvbc/v1/pages/{id}/remove-section',
+                update_element: '/nvbc/v1/pages/{id}/update-element',
+                check_page_lock: '/nvbc/v1/pages/{id}/lock-status',
+                patch_kit_global_css: '/nvbc/v1/kit-global-css/patch',
+                search_kit_global_css: '/nvbc/v1/search-kit-global-css',
+                audit_unused_kit_css: '/nvbc/v1/audit-unused-kit-css',
+                get_widget_schema: '/nvbc/v1/widget-schema',
+                list_widget_types: '/nvbc/v1/widget-types',
+            };
+
+            // Backend paths use literal regex placeholders like (?P<id>\d+); strip them for compare
+            const normalize = (path) => path
+                .replace(/\(\?P<\w+>[^)]+\)/g, '{id}')
+                .replace(/^\/wp-json/, '');
+
+            const exposedNormalized = new Set();
+            Object.keys(routes).forEach(p => exposedNormalized.add(normalize(p)));
+
+            const available = [];
+            const missing = [];
+            Object.entries(requiredRoutes).forEach(([tool, route]) => {
+                if (exposedNormalized.has(route)) available.push(tool);
+                else missing.push({ tool, route });
+            });
+
+            let msg = `=== CAPABILITY CHECK ===\n`;
+            msg += `Plugin: v${r.version}\n`;
+            msg += `MCP server: v${VERSION}\n`;
+            msg += `Total routes registered: ${Object.keys(routes).length}\n\n`;
+
+            if (missing.length === 0) {
+                msg += `✅ All ${available.length} probed MCP tools have matching backend routes.\n`;
+            } else {
+                msg += `⚠️  ${missing.length} MCP tool(s) have NO matching backend route on this site:\n`;
+                missing.forEach(m => { msg += `   • ${m.tool}  (needs ${m.route})\n`; });
+                msg += `\nThese tools will return 404 / "Backend route missing" until the site's NVBC plugin is updated.\n`;
+                msg += `Available tools (${available.length}): ${available.join(', ')}\n`;
+            }
+
+            msg += `\n--- Full route list (${Object.keys(routes).length}) ---\n`;
+            Object.entries(routes).sort().forEach(([route, methods]) => {
+                msg += `  ${(methods || []).join(',').padEnd(12)} ${route}\n`;
+            });
+
+            return ok(msg);
+        } catch (e) {
+            return ok(`capability_check failed: ${e.message}\n\nThis likely means the site is unreachable, the plugin is older than v4.46.0 (no /health?include_routes endpoint), or credentials are wrong.`);
+        }
+    }
+
     case 'get_design_tokens': {
         const tokens = await getDesignTokens();
         return ok(`=== DESIGN TOKENS ===\n\n${JSON.stringify(tokens, null, 2)}`);
@@ -4133,10 +4244,32 @@ async function handleToolCall(name, args) {
         const params = new URLSearchParams();
         if (args.section_index !== undefined) params.set('section_index', args.section_index);
         if (args.depth !== undefined) params.set('depth', args.depth);
+        if (args.widget_type) params.set('widget_type', args.widget_type);
+        if (args.container_title) params.set('container_title', args.container_title);
+        if (args.settings_contains) params.set('settings_contains', args.settings_contains);
         const qs = params.toString() ? `?${params.toString()}` : '';
         const r = await apiCall(`/pages/${args.page_id}/elements${qs}`);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
 
+        // Flat-filter mode (v4.46.0+)
+        if (r.mode === 'filtered') {
+            const filt = r.filter || {};
+            let msg = `Page ${args.page_id}: ${r.total_sections} sections — filter ${JSON.stringify(filt)}\n`;
+            msg += `Matches: ${r.match_count}\n${'─'.repeat(50)}\n`;
+            if (!r.elements.length) {
+                msg += '(no matches)\n';
+                return ok(msg);
+            }
+            r.elements.forEach(el => {
+                const label = el.widget ? `[${el.widget}]` : `<${el.type}>`;
+                msg += `${label} id:${el.id}`;
+                if (el.label) msg += ` "${el.label}"`;
+                if (el.parent_id) msg += ` (parent ${el.parent_id})`;
+                msg += `\n  path: ${el.path}\n`;
+            });
+            return ok(msg);
+        }
+
         function formatTree(el, indent) {
             let line = '  '.repeat(indent);
             if (el.type === 'widget') {
@@ -4201,15 +4334,33 @@ async function handleToolCall(name, args) {
     case 'check_page_lock': {
         const r = await apiCall(`/pages/${args.page_id}/lock-status`);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
-        if (!r.locked) return ok(`Page ${args.page_id}: Not locked — safe to edit.`);
-        let msg = `Page ${args.page_id}: LOCKED\n`;
-        if (r.wp_lock) {
-            msg += `  WP Editor: ${r.wp_lock.user} (${r.wp_lock.age_seconds}s ago)\n`;
+
+        const sizeKB = r.elementor_data_size_bytes != null
+            ? Math.round(r.elementor_data_size_bytes / 1024)
+            : null;
+        const big = sizeKB != null && sizeKB > 500;  // >500KB tree often triggers slow save cascade
+
+        let msg = '';
+        if (!r.locked) {
+            msg += `Page ${args.page_id}: Not locked — safe to edit.\n`;
+        } else {
+            msg += `Page ${args.page_id}: LOCKED\n`;
+            if (r.wp_lock) msg += `  WP Editor: ${r.wp_lock.user} (${r.wp_lock.age_seconds}s ago, expires in ${r.wp_lock.expires_in_seconds}s)\n`;
+            if (r.mcp_lock) msg += `  MCP Tool: ${r.mcp_lock.tool} (started ${r.mcp_lock.time})\n`;
+            msg += `Use force=true on write operations to override.\n`;
         }
-        if (r.mcp_lock) {
-            msg += `  MCP Tool: ${r.mcp_lock.tool} (started ${r.mcp_lock.time})\n`;
+
+        // v4.46.0+: surface a recently-expired _edit_lock + page size so callers can
+        // diagnose "hang despite unlocked" symptoms (almost always slow post-save cascade).
+        if (r.wp_lock_raw && !r.wp_lock_raw.considered_active) {
+            msg += `\nRecently-expired WP _edit_lock: user=${r.wp_lock_raw.user}, age=${r.wp_lock_raw.age_seconds}s (past the 150s active window). Not enforced, but Elementor may still be writing autosaves in the background.\n`;
+        }
+        if (sizeKB != null) {
+            msg += `\nElementor data: ${sizeKB} KB`;
+            if (big) {
+                msg += `  ⚠️  Large tree — expect 10–120s wait on write operations (remove_section/update_element) due to save_post → CSS regen cascade. This is NOT a lock; force=true won't help. Use the MCP fetch timeout, not retries.`;
+            }
         }
-        msg += `\nUse force=true on write operations to override.`;
         return ok(msg);
     }
 
@@ -4592,7 +4743,9 @@ async function handleToolCall(name, args) {
         if (args.category) params.set('category', args.category);
         if (args.date_after) params.set('date_after', args.date_after);
         if (args.date_before) params.set('date_before', args.date_before);
-        if (args.per_page) params.set('per_page', args.per_page);
+        // v4.46.0+: accept `limit` as alias for `per_page` — callers frequently mistype it
+        const perPage = args.per_page ?? args.limit;
+        if (perPage) params.set('per_page', perPage);
         if (args.page) params.set('page', args.page);
         const qs = params.toString() ? `?${params.toString()}` : '';
         const r = await apiCall(`/posts${qs}`);
@@ -5628,6 +5781,11 @@ async function handleToolCall(name, args) {
         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`;
+        if (r.scope) {
+            out += `Scope: post_type=${r.scope.post_type}, limit_per_store=${r.scope.limit_per_store}`;
+            if (r.scope.limit_was_default) out += ' (default)';
+            out += `\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`;
@@ -5635,6 +5793,9 @@ async function handleToolCall(name, args) {
         if (!r.matches?.length) {
             out += '\nNo matches found.';
             if (r.mode !== 'fuzzy') out += '\n💡 Try mode="fuzzy" to tolerate NBSP / curly punctuation.';
+            if (r.scope && r.scope.limit_was_default && r.scope.post_type === 'any') {
+                out += `\n💡 Default limit (${r.scope.limit_per_store}) may have truncated the scan. Pass limit:5000 to widen.`;
+            }
             return ok(out);
         }
         const groups = {};
@@ -5657,6 +5818,63 @@ async function handleToolCall(name, args) {
         return ok(out);
     }
 
+    case 'replace_widget_content': {
+        const body = {
+            widget_type: args.widget_type,
+            setting: args.setting,
+            search: stripCDATA(args.search),
+            replace_with: stripCDATA(args.replace_with),
+            dry_run: parseBool(args.dry_run, true),
+        };
+        if (args.exclude_match) body.exclude_match = stripCDATA(args.exclude_match);
+        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;
+        if (args.case_insensitive) body.case_insensitive = parseBool(args.case_insensitive, false);
+
+        const r = await apiCall('/replace-widget-content', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+
+        const s = r.summary || {};
+        const tag = r.dry_run ? 'DRY RUN' : 'APPLIED';
+        let out = `=== REPLACE WIDGET CONTENT (${tag}) ===\n`;
+        out += `Widget: ${r.widget_type}.${r.setting}\n`;
+        out += `Search:  "${r.search}"\n`;
+        if (r.exclude_match) out += `Exclude: "${r.exclude_match}"\n`;
+        out += `Replace with: ${(r.replace_with || '').slice(0, 120)}${(r.replace_with || '').length > 120 ? '…' : ''}\n`;
+        if (r.scope) {
+            out += `Scope: post_type=${r.scope.post_type}, limit=${r.scope.limit}`;
+            if (r.scope.limit_was_default) out += ' (default)';
+            out += `, posts_scanned=${r.scope.posts_scanned}\n`;
+        }
+        out += `Widgets matched: ${s.widgets_matched || 0}`;
+        if (r.dry_run) out += ` | would_replace: ${s.widgets_matched - (s.widgets_skipped_excluded || 0)}`;
+        else out += ` | replaced: ${s.widgets_replaced || 0}`;
+        out += ` | skipped (excluded): ${s.widgets_skipped_excluded || 0}\n`;
+        out += `Posts affected: ${s.posts_affected || 0}\n`;
+
+        if (!r.matches?.length) {
+            out += `\nNo widgets matched.`;
+            if (r.scope && r.scope.limit_was_default && r.scope.post_type === 'any') {
+                out += `\n💡 Default limit (${r.scope.limit}) may have truncated. Pass limit:5000 to widen.`;
+            }
+            return ok(out);
+        }
+
+        r.matches.slice(0, 50).forEach(m => {
+            out += `\n--- [${m.post_id}] ${m.post_title} — ${m.hits.length} widget(s) ---\n`;
+            m.hits.slice(0, 5).forEach(h => {
+                out += `  ${h.status} | id:${h.element_id}\n`;
+                out += `    old: ${(h.preview_old || '').replace(/\n/g, ' ').slice(0, 100)}\n`;
+                if (h.preview_new) out += `    new: ${(h.preview_new || '').replace(/\n/g, ' ').slice(0, 100)}\n`;
+            });
+            if (m.hits.length > 5) out += `  … and ${m.hits.length - 5} more\n`;
+        });
+        if (r.matches.length > 50) out += `\n…and ${r.matches.length - 50} more posts (truncated)`;
+        if (r.dry_run) out += `\n\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;
@@ -7034,9 +7252,17 @@ let _server = null;
 let _transport = null;
 
 async function startStdio() {
-    // Keepalive FIRST — ensures event loop never empties, even if stdin closes
+    // Keepalive FIRST — ensures event loop never empties, even if stdin closes.
+    // The parent-watchdog below intentionally bypasses this with process.exit(0)
+    // when it detects the owning host session is gone.
     global._mcpKeepAlive = setInterval(() => {}, 30000);
 
+    // Parent-watchdog: walks ancestry to find Claude Code / VS Code / Cursor /
+    // owning terminal, then heartbeats it. Catches force-killed parents on
+    // Windows where stdin close + SIGTERM never arrive. Disable with
+    // NVBC_MCP_PARENT_WATCH=0. No-op in HTTP mode (only called from stdio).
+    startParentWatchdog();
+
     // Monitor stdin/stdout lifecycle (diagnostic)
     process.stdin.on('end', () => {
         console.error('[LIFECYCLE] stdin ended');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noleemits/vision-builder-control-mcp",
-  "version": "4.45.2",
+  "version": "4.46.1",
   "description": "Vision Builder Control MCP server - design token-driven page builder tools for WordPress/Elementor websites",
   "type": "module",
   "main": "index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "index.js",
+    "parent-watchdog.js",
     "README.md"
   ],
   "scripts": {

package/parent-watchdog.js

@@ -0,0 +1,163 @@
+/**
+ * Parent-watchdog for the stdio MCP server.
+ *
+ * Walks the parent-process chain at startup to find the "owning" session
+ * (typically Claude Code / VS Code / Cursor / a terminal), then heartbeats
+ * its existence every few seconds. When the owner dies — whether cleanly
+ * or via SIGKILL / taskkill /F / OS crash — the watchdog terminates this
+ * process. Solves the orphan-accumulation leak where the global keepalive
+ * interval in index.js was preventing exit after the host crashed.
+ *
+ * Works regardless of intermediate wrappers (npx, npm.cmd, cmd.exe) because
+ * the chain walk skips over them and locks onto the last non-system ancestor.
+ *
+ * Disable per-process via NVBC_MCP_PARENT_WATCH=0.
+ */
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { platform } from 'node:os';
+
+const CHECK_INTERVAL_MS = 7000;
+const MAX_CHAIN_DEPTH = 32;
+
+const SYSTEM_ROOTS_WIN = new Set([
+    'explorer.exe', 'services.exe', 'svchost.exe', 'wininit.exe',
+    'smss.exe', 'csrss.exe', 'lsass.exe', 'winlogon.exe',
+    'system', 'system idle process', 'registry', 'memory compression',
+]);
+
+/**
+ * Snapshot every process on the system in one syscall.
+ * Returns Map<pid, { pid, ppid, name }>.
+ * Spawning PowerShell once is ~400ms; spawning it N times is N × 400ms,
+ * which is why per-step queries were timing out before the watchdog could arm.
+ */
+function snapshotWindows() {
+    const out = execSync(
+        'powershell -NoProfile -Command "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name | ConvertTo-Json -Compress"',
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000, windowsHide: true, maxBuffer: 32 * 1024 * 1024 }
+    );
+    const data = JSON.parse(out);
+    const map = new Map();
+    for (const row of (Array.isArray(data) ? data : [data])) {
+        map.set(row.ProcessId, {
+            pid: row.ProcessId,
+            ppid: row.ParentProcessId,
+            name: String(row.Name || ''),
+        });
+    }
+    return map;
+}
+
+function snapshotPosix() {
+    // ps is universal. Single fork, all processes, parseable.
+    const out = execSync('ps -axo pid=,ppid=,comm=', {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000, maxBuffer: 32 * 1024 * 1024,
+    });
+    const map = new Map();
+    for (const line of out.split('\n')) {
+        const m = line.match(/^\s*(\d+)\s+(\d+)\s+(.*)$/);
+        if (!m) continue;
+        const pid = parseInt(m[1], 10);
+        const ppid = parseInt(m[2], 10);
+        map.set(pid, { pid, ppid, name: m[3].trim() });
+    }
+    return map;
+}
+
+/**
+ * Walk up from process.pid using an in-memory snapshot. Returns the last
+ * non-system ancestor PID, or null.
+ */
+function findOwningAncestor() {
+    const os = platform();
+    let snapshot;
+    try {
+        snapshot = os === 'win32' ? snapshotWindows() : snapshotPosix();
+    } catch (err) {
+        throw new Error(`process snapshot failed: ${err.message}`);
+    }
+
+    let cur = process.pid;
+    let lastNonSystem = null;
+    let depth = 0;
+
+    while (depth++ < MAX_CHAIN_DEPTH) {
+        const info = snapshot.get(cur);
+        if (!info || !info.ppid) break;
+
+        const ppid = info.ppid;
+        if (ppid === 0) break; // Windows pseudo-root.
+        if (os !== 'win32' && ppid === 1) break; // POSIX init/systemd/launchd.
+
+        if (os === 'win32') {
+            const parentInfo = snapshot.get(ppid);
+            if (!parentInfo) break;
+            if (SYSTEM_ROOTS_WIN.has((parentInfo.name || '').toLowerCase())) break;
+        }
+
+        lastNonSystem = ppid;
+        cur = ppid;
+    }
+
+    return lastNonSystem;
+}
+
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        if (e.code === 'ESRCH') return false;
+        // EPERM: process exists, we just can't signal it. Still alive.
+        return true;
+    }
+}
+
+/**
+ * Start the parent-watchdog. Should only be called from stdio mode.
+ *
+ * @returns {{ ownerPid: number|null, enabled: boolean, reason?: string }}
+ */
+export function startParentWatchdog() {
+    if (process.env.NVBC_MCP_PARENT_WATCH === '0') {
+        console.error('[WATCHDOG] disabled via NVBC_MCP_PARENT_WATCH=0');
+        return { ownerPid: null, enabled: false, reason: 'env_disabled' };
+    }
+
+    let ownerPid = null;
+
+    // Explicit override — watch this PID instead of walking the chain.
+    // Escape hatch for unusual process trees (tmux, screen, supervisor).
+    const override = parseInt(process.env.NVBC_MCP_WATCHDOG_OWNER_PID || '', 10);
+    if (Number.isFinite(override) && override > 0) {
+        ownerPid = override;
+    } else {
+        try {
+            ownerPid = findOwningAncestor();
+        } catch (err) {
+            console.error(`[WATCHDOG] ancestry walk failed: ${err.message} — watchdog disabled`);
+            return { ownerPid: null, enabled: false, reason: 'walk_failed' };
+        }
+    }
+
+    if (!ownerPid) {
+        console.error('[WATCHDOG] no non-system ancestor found — watchdog disabled (daemonized run?)');
+        return { ownerPid: null, enabled: false, reason: 'no_ancestor' };
+    }
+
+    console.error(`[WATCHDOG] watching parent session pid=${ownerPid} (interval=${CHECK_INTERVAL_MS}ms)`);
+
+    const interval = setInterval(() => {
+        if (!isAlive(ownerPid)) {
+            console.error(`[WATCHDOG] parent pid=${ownerPid} is gone — shutting down`);
+            // Bypass the global keepalive + beforeExit safety net in index.js.
+            process.exit(0);
+        }
+    }, CHECK_INTERVAL_MS);
+
+    interval.unref();
+
+    return { ownerPid, enabled: true };
+}