@noleemits/vision-builder-control-mcp 4.111.0 → 4.114.0

package/index.js

@@ -111,7 +111,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.111.0';
+const VERSION = '4.114.0';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
 // v4.110.0: shared styling philosophy appended to every build/style tool so the
@@ -2464,7 +2464,7 @@ function getToolDefinitions() {
         },
         {
             name: 'create_post',
-            description: 'Create a WordPress post, page, or CPT. Supports content, excerpt, taxonomies, featured image, parent linking (by slug or ID), Elementor setup, and initial RankMath SEO data.',
+            description: 'Create a WordPress post, page, or CPT. Supports content, excerpt, taxonomies, featured image, parent linking (by slug or ID), an explicit publish date (for migrations), Elementor setup, and initial RankMath SEO data.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2473,6 +2473,8 @@ function getToolDefinitions() {
                     content: { type: 'string', description: 'Post content (block HTML or plain text)' },
                     excerpt: { type: 'string', description: 'Post excerpt' },
                     status: { type: 'string', enum: ['draft', 'publish', 'private', 'pending'], description: 'Post status (default: draft)' },
+                    date: { type: 'string', description: 'Explicit publish date in site-local time, "YYYY-MM-DD HH:MM:SS" (or any strtotime-parseable string). Use to PRESERVE original dates when migrating posts — omit and the post gets the current date.' },
+                    date_gmt: { type: 'string', description: 'Optional explicit UTC date. If omitted, derived from `date` via the site timezone.' },
                     slug: { type: 'string', description: 'URL slug (auto-generated if omitted)' },
                     parent: { type: 'number', description: 'Parent post ID (for hierarchical types). Use this OR parent_slug.' },
                     parent_slug: { type: 'string', description: 'Parent slug — looked up against the same post_type. Saves a follow-up update_post call.' },
@@ -2777,16 +2779,27 @@ function getToolDefinitions() {
         },
         {
             name: 'display_conditions',
-            description: 'Get or set Elementor Theme Builder display conditions on a template (header, footer, single, archive). Common conditions: "include/general" (entire site), "include/singular/page" (all pages), "include/singular/post" (all posts), "include/archive" (all archives).',
+            description: 'Get or set Elementor Theme Builder display conditions on a template (header, footer, single, archive). Common conditions: "include/general" (entire site), "include/singular/page" (all pages), "include/singular/post" (all posts), "include/archive" (all archives), "include/singular/{cpt}", "include/archive/{cpt}_archive". Conditions are VALIDATED against Elementor\'s registered conditions — a typo\'d slug returns condition_warnings (advisory) instead of silently no-op\'ing; pass strict:true to hard-refuse. Run list_display_conditions for the exact valid strings. On set, site caches are purged and a ?nocache verify hint is returned.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     template_id: { type: 'number', description: 'Template ID (from list_templates)' },
-                    conditions: { type: 'array', items: { type: 'string' }, description: 'Array of condition strings. Omit to read current conditions.' }
+                    conditions: { type: 'array', items: { type: 'string' }, description: 'Array of condition strings. Omit to read current conditions.' },
+                    strict: { type: 'boolean', description: 'If true, refuse the write when any condition does not match a registered Elementor condition. Default false (persist + warn).' }
                 },
                 required: ['template_id']
             }
         },
+        {
+            name: 'list_display_conditions',
+            description: 'List the EXACT valid Theme Builder display-condition strings registered on this site (Elementor Pro), optionally filtered by post_type substring. Use before display_conditions to avoid silent no-ops — e.g. a CPT archive is "include/archive/{cpt}_archive", not "include/archive/{cpt}". Returns a fallback note when Pro is unavailable.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    post_type: { type: 'string', description: 'Optional substring filter (e.g. "team_member") to narrow to one type\'s singular + archive conditions.' }
+                }
+            }
+        },
 
         // ── Nav menus (v4.29.0) ──
         {
@@ -2894,7 +2907,7 @@ function getToolDefinitions() {
         },
         {
             name: 'migrate_extracted_md',
-            description: 'One-shot migration: take an extract-format markdown chunk and create or update a CPT post with cleaned HTML body, featured image, parent linking, and RankMath SEO. Idempotent: re-running with the same slug+post_type updates instead of duplicating. Pass md_content (preferred) or md_path. Use hero_basename to look up the featured image by filename instead of attachment ID.',
+            description: 'One-shot migration: take an extract-format OR standard markdown chunk and create or update a CPT post with cleaned HTML body, featured image, parent linking, and RankMath SEO. Idempotent: re-running with the same slug+post_type updates instead of duplicating. md_content MUST be a STRING (markdown/plain text/clean HTML) — passing an array/object is now rejected with an error (it previously produced a silent "<p>Array</p>" corrupt write). Pass md_content (preferred) or md_path (string file path). Use hero_basename to look up the featured image by filename instead of attachment ID. For plain prose, ordinary markdown works; extract-format adds frontmatter blocks (## H1, **Meta description:**, etc.) that are parsed into title/SEO and stripped from the body.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3079,7 +3092,7 @@ function getToolDefinitions() {
         // ── Element Operations (v3.6.0) ──
         {
             name: 'add_element',
-            description: 'Add a widget or container into a parent container on a page. Pass the full Elementor element JSON (elType, widgetType, settings, etc.). If no ID is provided, one will be auto-generated. Use position to insert at a specific index. NESTED COLUMN PRESET (v4.86.0): instead of element, pass preset="cols-3" (or cols-2, cols-4, sidebar-left, sidebar-right, split, stack) to drop a gap-safe column row AS A CHILD of parent_id. The scaffold ships content_width:full on the row AND every column, so no boxed `.e-con-inner` wrapper is injected and flex-row children never stack — this is the reusable fix for multi-column rows inside an existing section. Columns are empty; fill them with further add_element calls. GUARDRAIL: classic Elementor section/column elType is rejected (use containers); pass legacy:true to override.' + CSS_PHILOSOPHY,
+            description: 'Add a widget or container into a parent container on a page. Pass the full Elementor element JSON (elType, widgetType, settings, etc.). If no ID is provided, one will be auto-generated. Use position to insert at a specific index. NESTED COLUMN PRESET (v4.86.0): instead of element, pass preset="cols-3" (or cols-2, cols-4, sidebar-left, sidebar-right, split, stack) to drop a gap-safe column row AS A CHILD of parent_id. The scaffold ships content_width:full on the row AND every column, so no boxed `.e-con-inner` wrapper is injected and flex-row children never stack — this is the reusable fix for multi-column rows inside an existing section. Columns are empty; fill them with further add_element calls. GUARDRAIL: classic Elementor section/column elType is rejected (use containers); pass legacy:true to override. DYNAMIC CONTAINER LINK: Elementor does NOT render a clickable <a> for a container whose link is a dynamic tag (e.g. post-url) — static container links work, but for a dynamic clickable card put the post-url link on a heading/button widget inside the card (you\'ll get a warning if you set a dynamic container link).' + CSS_PHILOSOPHY,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3095,6 +3108,24 @@ function getToolDefinitions() {
                 required: ['page_id', 'parent_id']
             }
         },
+        {
+            name: 'add_dynamic_field',
+            description: 'Add a dynamic-data widget to a loop-item / single / archive template — a STANDARD widget (heading/text-editor/image) carrying the correct Elementor __dynamic__ tag. Use this INSTEAD of the theme-post-* widgets (theme-post-title/-excerpt/-featured-image), which are unreliable when authored via REST (they render placeholders). Types: title→heading+post-title, excerpt→text-editor+post-excerpt, content→text-editor+post-content, featured_image→image+post-featured-image, acf→heading+acf (pass field = the ACF field key/name). The widget renders the current post\'s data inside loop/single context.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_id:   { type: 'number', description: 'Template (or page) ID to add into' },
+                    parent_id: { type: 'string', description: 'Elementor ID of the parent container' },
+                    type:      { type: 'string', enum: ['title', 'excerpt', 'content', 'featured_image', 'acf'], description: 'Which post field to bind.' },
+                    field:     { type: 'string', description: 'For type=acf: the ACF field key or name to bind.' },
+                    tag:       { type: 'string', description: 'Override the dynamic tag name (advanced — e.g. a custom registered tag).' },
+                    settings:  { type: 'object', description: 'Extra widget settings to merge (e.g. typography, header_size, link). additionalProperties.', additionalProperties: true },
+                    position:  { type: 'number', description: 'Optional 0-based insert index. Omit to append.' },
+                    force:     { type: 'boolean', description: 'Override edit locks.' }
+                },
+                required: ['page_id', 'parent_id', 'type']
+            }
+        },
         {
             name: 'get_element',
             description: 'Get a single element\'s full settings and metadata by its Elementor ID. Returns elType, widgetType, all settings, and a summary of children (for containers). Use this to inspect an element before updating it.',
@@ -3196,7 +3227,7 @@ function getToolDefinitions() {
         },
         {
             name: 'convert_to_gutenberg',
-            description: 'Phase 2 migration tool — convert an Elementor page/post\'s content to native core Gutenberg blocks. NON-DESTRUCTIVE: the source is never modified. mode=preview (default) returns the block markup; mode=ir returns the intermediate representation (node list) for debugging; mode=new_draft creates a fresh draft and returns its edit URL. The new draft mirrors the source post type by default (post→post, page→page); override with target_type. Rich text-editor content that is not a single paragraph falls back to a lossless wp:html block. The output is pure core blocks — converted content does NOT depend on this plugin to render.',
+            description: 'Phase 2 migration tool — convert an ELEMENTOR page/post\'s content to native core Gutenberg blocks. SCOPE: Elementor pages ONLY (reads _elementor_data); a classic/HTML post returns not_elementor — there is no automated classic-HTML → blocks path (store clean semantic HTML in post_content, it renders as a Classic block). NON-DESTRUCTIVE: the source is never modified. mode=preview (default) returns the block markup; mode=ir returns the intermediate representation (node list) for debugging; mode=new_draft creates a fresh draft and returns its edit URL. The new draft mirrors the source post type by default (post→post, page→page); override with target_type. Rich text-editor content that is not a single paragraph falls back to a lossless wp:html block. The output is pure core blocks — converted content does NOT depend on this plugin to render.',
             inputSchema: { type: 'object', properties: {
                 page_id: { type: 'integer', description: 'Source Elementor page/post ID to convert.' },
                 mode: { type: 'string', enum: ['preview', 'ir', 'new_draft'], description: 'preview (default) | ir | new_draft' },
@@ -3486,14 +3517,15 @@ function getToolDefinitions() {
         },
         {
             name: 'get_widget_schema',
-            description: 'Read the full settings schema for one widget or element type — every accepted control with type, label, default, options, responsive flag, and section grouping. For atomic V4 widgets, returns the serialized props_schema instead (different system). Use to avoid having to read Elementor source. Pass section to scope to one control section, search to filter by control-name substring, or keys_only=true for just the names. v4.44.3+.',
+            description: 'Read the full settings schema for one widget or element type — every accepted control with type, label, default, options, responsive flag, and section grouping. For atomic V4 widgets, returns the serialized props_schema instead (different system). Use to avoid having to read Elementor source. By DEFAULT the universal Advanced-tab control groups (margin/padding/motion-effects/transform/background/border/masking/responsive/custom-css/attributes) are EXCLUDED — they are ~200-300 identical boilerplate controls on every widget; pass include_common=true to include them. Pass section to scope to one control section (overrides the common filter), search to filter by control-name substring, or keys_only=true for just the names. v4.44.3+.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     widget_type: { type: 'string', description: 'Widget or element name (e.g. "heading", "e-heading", "container", "image", "button"). Use list_widget_types to enumerate.' },
-                    section:     { type: 'string', description: 'Restrict to controls inside this control section (e.g. "section_title_style").' },
-                    search:      { type: 'string', description: 'Substring filter on control name.' },
-                    keys_only:   { type: 'boolean', description: 'Return only control name + type per entry (slim payload). Default: false.' }
+                    section:     { type: 'string', description: 'Restrict to controls inside this control section (e.g. "section_title_style"). Overrides the default common-section filter.' },
+                    search:      { type: 'string', description: 'Substring filter on control name. Overrides the default common-section filter.' },
+                    keys_only:   { type: 'boolean', description: 'Return only control name + type per entry (slim payload). Default: false.' },
+                    include_common: { type: 'boolean', description: 'Include the universal Advanced-tab boilerplate controls (transform/effects/background/responsive/custom-css/etc.). Default: false — they are hidden to save tokens.' }
                 },
                 required: ['widget_type']
             }
@@ -5223,12 +5255,13 @@ async function handleToolCall(name, args) {
         const body = { title: args.title };
         const passthrough = ['post_type', 'content', 'excerpt', 'status', 'slug',
             'parent', 'parent_slug', 'taxonomies', 'featured_image_id',
-            'featured_image_basename', 'elementor', 'seo', 'dedupe_by_title'];
+            'featured_image_basename', 'elementor', 'seo', 'dedupe_by_title',
+            'date', 'date_gmt'];
         for (const k of passthrough) if (args[k] !== undefined) body[k] = args[k];
         const r = await apiCall('/posts', 'POST', body);
         if (!r.success) return ok(`Failed: ${r.message || 'Unknown error'}`);
         const prefix = r.was_existing ? 'Post already existed (dedupe hit)' : 'Post created';
-        return ok(`${prefix}!\nID: ${r.id} | Type: ${r.type} | Status: ${r.status}\nTitle: ${r.title}\nSlug: ${r.slug}\nURL: ${r.url}\nEdit: ${r.edit_url}`);
+        return ok(`${prefix}!\nID: ${r.id} | Type: ${r.type} | Status: ${r.status}\nTitle: ${r.title}\nSlug: ${r.slug}${r.date ? ` | Date: ${r.date}` : ''}\nURL: ${r.url}\nEdit: ${r.edit_url}`);
     }
 
     case 'get_post_by_slug': {
@@ -5558,10 +5591,22 @@ async function handleToolCall(name, args) {
 
     case 'display_conditions': {
         if (args.conditions) {
-            const r = await apiCall(`/templates/${args.template_id}/display-conditions`, 'POST', {
-                conditions: args.conditions,
-            });
-            return ok(`Set ${r.conditions.length} condition(s) on "${r.title}" (ID: ${r.template_id}):\n${r.conditions.join('\n')}`);
+            const body = { conditions: args.conditions };
+            if (args.strict !== undefined) body.strict = args.strict;
+            const r = await apiCall(`/templates/${args.template_id}/display-conditions`, 'POST', body);
+            if (r.code || r.error) {
+                let m = `Failed: ${r.message || r.error}`;
+                if (Array.isArray(r.warnings) && r.warnings.length) m += `\n  - ${r.warnings.join('\n  - ')}`;
+                if (r.hint) m += `\n${r.hint}`;
+                return ok(m);
+            }
+            let msg = `Set ${r.conditions.length} condition(s) on "${r.title}" (ID: ${r.template_id}):\n${r.conditions.join('\n')}`;
+            if (Array.isArray(r.condition_warnings) && r.condition_warnings.length) {
+                msg += `\n⚠️  CONDITION WARNINGS (persisted anyway — these may not match anything):\n  - ${r.condition_warnings.join('\n  - ')}\n  Run list_display_conditions for valid strings.`;
+            }
+            if (r.caches_purged && r.caches_purged.length) msg += `\nCaches purged: ${r.caches_purged.join(', ')}`;
+            if (r.verify_hint) msg += `\n${r.verify_hint}`;
+            return ok(msg);
         } else {
             const r = await apiCall(`/templates/${args.template_id}/display-conditions`);
             const conds = r.conditions && r.conditions.length ? r.conditions.join('\n') : '(none)';
@@ -5569,6 +5614,18 @@ async function handleToolCall(name, args) {
         }
     }
 
+    case 'list_display_conditions': {
+        const params = new URLSearchParams();
+        if (args.post_type) params.set('post_type', args.post_type);
+        const r = await apiCall(`/templates/conditions/available?${params.toString()}`);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        if (!r.available) return ok(`Condition listing unavailable.\n${r.note}`);
+        let out = `Valid display conditions (${r.count}${r.post_type ? `, filtered: "${r.post_type}"` : ''}):\n`;
+        out += r.conditions.map(c => `  ${c}`).join('\n');
+        out += `\n\n${r.note}`;
+        return ok(out);
+    }
+
     case 'list_nav_menus': {
         const r = await apiCall('/menus');
         if (!r.menus || !r.menus.length) return ok('No nav menus found.');
@@ -5808,7 +5865,43 @@ async function handleToolCall(name, args) {
         if (args.force) body.force = true;
         const r = await apiCall(`/pages/${args.page_id}/add-element`, 'POST', body);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
-        return ok(`Element added!\nPage: ${r.page_id}\nParent: ${r.parent_id}\nNew element ID: ${r.element_id}${r.position !== null && r.position !== undefined ? `\nPosition: ${r.position}` : ' (appended)'}`);
+        let addMsg = `Element added!\nPage: ${r.page_id}\nParent: ${r.parent_id}\nNew element ID: ${r.element_id}${r.position !== null && r.position !== undefined ? `\nPosition: ${r.position}` : ' (appended)'}`;
+        if (Array.isArray(r.warnings) && r.warnings.length) addMsg += `\n⚠️  ${r.warnings.join('\n⚠️  ')}`;
+        return ok(addMsg);
+    }
+
+    case 'add_dynamic_field': {
+        // Emit a standard widget + the correct __dynamic__ tag (the proven-rendering
+        // form), instead of the unreliable theme-post-* widgets.
+        const MAP = {
+            title:          { widgetType: 'heading',     control: 'title',  tag: 'post-title',          base: { title: '', header_size: 'h2' } },
+            excerpt:        { widgetType: 'text-editor', control: 'editor', tag: 'post-excerpt',        base: { editor: '' } },
+            content:        { widgetType: 'text-editor', control: 'editor', tag: 'post-content',        base: { editor: '' } },
+            featured_image: { widgetType: 'image',       control: 'image',  tag: 'post-featured-image', base: { image: { url: '', id: '' } } },
+            acf:            { widgetType: 'heading',     control: 'title',  tag: 'acf',                 base: { title: '', header_size: 'h2' } },
+        };
+        const m = MAP[args.type];
+        if (!m) return ok(`Failed: unknown type "${args.type}". Use one of: ${Object.keys(MAP).join(', ')}.`);
+        if (args.type === 'acf' && !args.field) return ok('Failed: type=acf requires a `field` (the ACF field key/name).');
+
+        // Elementor dynamic-tag shortcode: [elementor-tag id="<7-char>" name="<tag>" settings="<urlencoded-json>"]
+        const tagId = Array.from({ length: 7 }, () => 'abcdef0123456789'[Math.floor(Math.random() * 16)]).join('');
+        const tagSettings = {};
+        if (args.type === 'acf') tagSettings.key = args.field;
+        const enc = encodeURIComponent(JSON.stringify(tagSettings));
+        const dynamicValue = `[elementor-tag id="${tagId}" name="${args.tag || m.tag}" settings="${enc}"]`;
+
+        const settings = Object.assign({}, m.base, args.settings || {}, {
+            __dynamic__: Object.assign({}, (args.settings && args.settings.__dynamic__) || {}, { [m.control]: dynamicValue }),
+        });
+        const element = { elType: 'widget', widgetType: m.widgetType, settings };
+
+        const body = { parent_id: args.parent_id, element };
+        if (args.position !== undefined) body.position = args.position;
+        if (args.force) body.force = true;
+        const r = await apiCall(`/pages/${args.page_id}/add-element`, 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+        return ok(`Dynamic field added!\nType: ${args.type} → ${m.widgetType} widget bound to "${args.tag || m.tag}"${args.field ? ` (field: ${args.field})` : ''}\nElement ID: ${r.element_id} (parent ${r.parent_id})\nIt renders the current post's data in loop/single context.`);
     }
 
     case 'get_element': {
@@ -6720,6 +6813,7 @@ async function handleToolCall(name, args) {
         if (args.section) params.set('section', args.section);
         if (args.search) params.set('search', args.search);
         if (args.keys_only) params.set('keys_only', '1');
+        if (args.include_common) params.set('include_common', '1');
         const r = await apiCall(`/widget-schema?${params.toString()}`);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
         let out =
@@ -6746,6 +6840,9 @@ async function handleToolCall(name, args) {
             out += `  ${name.padEnd(36)} ${meta.join(' | ')}${dflt}\n`;
             if (c.label && !args.keys_only) out += `${' '.repeat(38)}label: ${c.label}\n`;
         }
+        if (r.excluded_common && r.excluded_common.controls > 0) {
+            out += `\n(${r.excluded_common.controls} universal Advanced-tab controls hidden across ${r.excluded_common.sections.length} sections — pass include_common=true to see them.)`;
+        }
         return ok(out);
     }
 

package/package.json

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