@noleemits/vision-builder-control-mcp 4.119.0 → 4.120.0

package/index.js

@@ -111,7 +111,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.119.0';
+const VERSION = '4.120.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
@@ -3164,15 +3164,18 @@ function getToolDefinitions() {
         },
         {
             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.',
+            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→typed ACF tag (acf-text/acf-number/acf-image/acf-url). For type=acf set `field` (the ACF field NAME) and optionally `field_type` (default text) and `source`: "post" (default — current/queried post) or "options" (an ACF OPTIONS page → renders the same site-wide value on EVERY page). Requires the field group to be attached to an options page (see update_acf_field_group).',
             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).' },
+                    type:      { type: 'string', enum: ['title', 'excerpt', 'content', 'featured_image', 'acf'], description: 'Which field to bind.' },
+                    field:     { type: 'string', description: 'For type=acf: the ACF field NAME to bind (e.g. "stat_success").' },
+                    field_type:{ type: 'string', enum: ['text', 'number', 'url', 'image'], description: 'For type=acf: ACF field type → picks the native tag (acf-text/acf-number/acf-url/acf-image) and host widget. Default "text".' },
+                    source:    { type: 'string', enum: ['post', 'options'], description: 'For type=acf: "post" (default) resolves against the current/queried post; "options" resolves against the ACF options page → same value site-wide.' },
+                    field_key: { type: 'string', description: 'For type=acf + source=post: optional exact ACF field key (e.g. "field_abc123") for a precise binding (key encoded as "<field_key>:<field>"). Ignored when source=options.' },
+                    tag:       { type: 'string', description: 'Override the dynamic tag name for non-acf types (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.' }
@@ -3665,22 +3668,22 @@ function getToolDefinitions() {
         },
         {
             name: 'get_acf_fields',
-            description: 'Get all ACF field values for a specific post. Returns field names, labels, types, and current values. Supports all ACF field types including repeater and group fields.',
+            description: 'Get all ACF field values for a specific post — OR for an ACF options page. Returns field names, labels, types, and current values. Supports all ACF field types including repeater and group fields. For a site-wide ACF options page, pass post_id="options" (or a custom options post_id). Use list_acf_option_pages to discover registered options pages.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    post_id: { type: 'number', description: 'WordPress post ID to get ACF fields for.' }
+                    post_id: { type: ['number', 'string'], description: 'WordPress post ID (number) to read, OR the string "options" for the ACF options page (or a custom options post_id).' }
                 },
                 required: ['post_id']
             }
         },
         {
             name: 'set_acf_fields',
-            description: 'Set/update ACF field values on a post. Accepts a JSON object of field_name: value pairs. Always dry_run=true first to preview.',
+            description: 'Set/update ACF field values on a post — OR on an ACF options page (site-wide). Accepts a JSON object of field_name: value pairs. Always dry_run=true first to preview. For a site-wide options page, pass post_id="options".',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    post_id: { type: 'number', description: 'WordPress post ID to update.' },
+                    post_id: { type: ['number', 'string'], description: 'WordPress post ID (number) to update, OR the string "options" for the ACF options page (or a custom options post_id).' },
                     fields: { type: 'object', description: 'Object of field_name: value pairs. Example: {"hero_title": "New Title", "show_sidebar": true}' },
                     dry_run: { type: 'boolean', description: 'Preview changes without saving (default: true). Set false to apply.' }
                 },
@@ -3749,6 +3752,40 @@ function getToolDefinitions() {
                 required: ['group_key']
             }
         },
+        {
+            name: 'list_acf_option_pages',
+            description: 'List registered ACF options pages (ACF Pro). Returns each page title, menu_slug, and the post_id string to pass to get_acf_fields/set_acf_fields (default "options"). Use this to confirm a site-wide settings page exists before reading/writing options data. If none exist, create one with register_acf_option_page.',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'register_acf_option_page',
+            description: 'Register (and persist) an ACF options page so site-wide fields can be stored once and read on every page (ACF Pro). Idempotent by menu_slug. The page is persisted in a WP option and re-registered on every load via acf/init — so it survives. After creating, attach field groups to it with update_acf_field_group (options_page=<menu_slug>), then read/write values with post_id "options".',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_title: { type: 'string', description: 'Display title, e.g. "Site Settings".' },
+                    menu_slug: { type: 'string', description: 'Optional admin menu slug. Defaults to a slug of page_title.' },
+                    parent_slug: { type: 'string', description: 'Optional parent menu slug to nest under (e.g. "options-general.php" or another options page slug).' }
+                },
+                required: ['page_title']
+            }
+        },
+        {
+            name: 'update_acf_field_group',
+            description: 'Patch an EXISTING ACF field group\'s metadata (title / active / location) without deleting+recreating it — so field keys that Elementor dynamic tags reference are preserved. Use to attach an orphaned group to an options page (options_page=<menu_slug>) or to post types. Pass a full ACF `location` array for advanced rules, or use post_types[]/options_page convenience builders.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    group_key: { type: 'string', description: 'ACF field group key (e.g. "group_6a2315c28164f"). Use list_acf_field_groups to discover.' },
+                    title: { type: 'string', description: 'Optional new title.' },
+                    active: { type: 'boolean', description: 'Optional active flag.' },
+                    options_page: { type: 'string', description: 'Attach the group to this options-page menu_slug (builds an options_page location rule).' },
+                    post_types: { type: 'array', items: { type: 'string' }, description: 'Attach the group to these post types (builds post_type location rules).' },
+                    location: { type: 'array', description: 'Advanced: a full ACF location rule array (overrides post_types/options_page). Shape: [[{param,operator,value}]].' }
+                },
+                required: ['group_key']
+            }
+        },
         // ── Audits ──
         {
             name: 'audit_orphan_pages',
@@ -6035,17 +6072,60 @@ async function handleToolCall(name, args) {
             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' } },
         };
+
+        // ── ACF: native Elementor Pro ACF dynamic tag ──────────────────────────
+        // Elementor's ACF tags are typed: acf-text / acf-number / acf-image / etc.
+        // (NOT a generic "acf" tag). The value resolves from settings.key, which
+        // Elementor splits on ":" — `Dynamic_Value_Provider::get_value()`:
+        //   key = "options:<field_name>"     → get_field_object(<field_name>, 'options')  [site-wide]
+        //   key = "<field_key>:<field_name>" → resolves against the current/queried post
+        //   key = "<field_name>" (bare)      → resolves by name against the queried post
+        // So options-context binding is simply the "options:" prefix.
+        if (args.type === 'acf') {
+            if (!args.field) return ok('Failed: type=acf requires a `field` (the ACF field name).');
+            const ACF_TAGS = {
+                text:      { tag: 'acf-text',      widgetType: 'heading',     control: 'title',  base: { title: '', header_size: 'h2' } },
+                number:    { tag: 'acf-number',    widgetType: 'heading',     control: 'title',  base: { title: '', header_size: 'h2' } },
+                url:       { tag: 'acf-url',       widgetType: 'text-editor', control: 'editor', base: { editor: '' } },
+                image:     { tag: 'acf-image',     widgetType: 'image',       control: 'image',  base: { image: { url: '', id: '' } } },
+            };
+            const ft = (args.field_type || 'text').toLowerCase();
+            const a = ACF_TAGS[ft];
+            if (!a) return ok(`Failed: unknown field_type "${ft}". Use one of: ${Object.keys(ACF_TAGS).join(', ')}.`);
+
+            const source = (args.source || 'post').toLowerCase();
+            let key;
+            if (source === 'options') key = `options:${args.field}`;
+            else if (args.field_key) key = `${args.field_key}:${args.field}`;
+            else key = args.field; // bare name → resolves against the queried post
+
+            const tagId = Array.from({ length: 7 }, () => 'abcdef0123456789'[Math.floor(Math.random() * 16)]).join('');
+            const enc = encodeURIComponent(JSON.stringify({ key }));
+            const dynamicValue = `[elementor-tag id="${tagId}" name="${a.tag}" settings="${enc}"]`;
+
+            const settings = Object.assign({}, a.base, args.settings || {}, {
+                __dynamic__: Object.assign({}, (args.settings && args.settings.__dynamic__) || {}, { [a.control]: dynamicValue }),
+            });
+            const element = { elType: 'widget', widgetType: a.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'}`);
+            const ctx = source === 'options'
+                ? 'It resolves against the ACF OPTIONS context, so it renders the same site-wide value on EVERY page.'
+                : 'It renders the current/queried post\'s ACF value (loop/single context).';
+            return ok(`Dynamic ACF field added!\nField: ${args.field} (${ft}) | source: ${source}\nTag: ${a.tag} → ${a.widgetType} widget | key: "${key}"\nElement ID: ${r.element_id} (parent ${r.parent_id})\n${ctx}`);
+        }
+
         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).');
+        if (!m) return ok(`Failed: unknown type "${args.type}". Use one of: ${Object.keys(MAP).join(', ')}, acf.`);
 
         // 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 enc = encodeURIComponent(JSON.stringify({}));
         const dynamicValue = `[elementor-tag id="${tagId}" name="${args.tag || m.tag}" settings="${enc}"]`;
 
         const settings = Object.assign({}, m.base, args.settings || {}, {
@@ -6058,7 +6138,7 @@ 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(`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.`);
+        return ok(`Dynamic field added!\nType: ${args.type} → ${m.widgetType} widget bound to "${args.tag || m.tag}"\nElement ID: ${r.element_id} (parent ${r.parent_id})\nIt renders the current post's data in loop/single context.`);
     }
 
     case 'get_element': {
@@ -7130,6 +7210,8 @@ async function handleToolCall(name, args) {
             r.field_groups.forEach(g => {
                 out += `\n[${g.key}] ${g.title} ${g.active ? '' : '(INACTIVE)'}\n`;
                 if (g.post_types?.length) out += `  Post types: ${g.post_types.join(', ')}\n`;
+                if (g.option_pages?.length) out += `  Options pages: ${g.option_pages.join(', ')}\n`;
+                if (!g.post_types?.length && !g.option_pages?.length) out += `  Location: (none — orphaned)\n`;
                 if (g.fields?.length) {
                     g.fields.forEach(f => {
                         out += `  • ${f.name} (${f.type}) — "${f.label}"${f.required ? ' *required' : ''}\n`;
@@ -7146,9 +7228,9 @@ async function handleToolCall(name, args) {
     }
 
     case 'get_acf_fields': {
-        const r = await apiCall(`/acf-fields?post_id=${args.post_id}`);
+        const r = await apiCall(`/acf-fields?post_id=${encodeURIComponent(args.post_id)}`);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
-        let out = `=== ACF FIELDS: ${r.post_title} (ID:${r.post_id}) ===\n`;
+        let out = `=== ACF FIELDS: ${r.post_title} (${r.is_options ? 'options' : 'ID:' + r.post_id}) ===\n`;
         if (!r.fields?.length) {
             out += 'No ACF fields found for this post.\n';
         } else {
@@ -7246,6 +7328,52 @@ async function handleToolCall(name, args) {
         return ok(msg);
     }
 
+    case 'list_acf_option_pages': {
+        const r = await apiCall('/acf-option-pages');
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `=== ACF OPTIONS PAGES (${r.count}) ===\n`;
+        if (!r.option_pages?.length) {
+            out += 'No ACF options pages registered.\n';
+        } else {
+            r.option_pages.forEach(p => {
+                out += `\n• ${p.page_title}\n  menu_slug: ${p.menu_slug}\n  post_id:   ${p.post_id}\n`;
+                if (p.parent_slug) out += `  parent:    ${p.parent_slug}\n`;
+            });
+        }
+        if (r.note) out += `\n${r.note}\n`;
+        return ok(out);
+    }
+
+    case 'register_acf_option_page': {
+        const body = { page_title: args.page_title };
+        if (args.menu_slug) body.menu_slug = args.menu_slug;
+        if (args.parent_slug) body.parent_slug = args.parent_slug;
+        const r = await apiCall('/acf-option-pages', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = r.created ? `=== ACF OPTIONS PAGE REGISTERED ===\n` : `=== ACF OPTIONS PAGE (already existed) ===\n`;
+        out += `Title: ${r.page_title}\nmenu_slug: ${r.menu_slug}\npost_id: ${r.post_id}\n`;
+        if (r.note) out += `\n${r.note}\n`;
+        return ok(out);
+    }
+
+    case 'update_acf_field_group': {
+        const body = { group_key: args.group_key };
+        if (args.title !== undefined) body.title = args.title;
+        if (args.active !== undefined) body.active = args.active;
+        if (args.options_page !== undefined) body.options_page = args.options_page;
+        if (args.post_types !== undefined) body.post_types = args.post_types;
+        if (args.location !== undefined) body.location = args.location;
+        const r = await apiCall('/acf-field-group', 'PATCH', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `=== ACF FIELD GROUP UPDATED ===\n`;
+        out += `[${r.key}] ${r.title}${r.active ? '' : ' (INACTIVE)'}\n`;
+        out += `Changed: ${(r.changed || []).join(', ')}\n`;
+        if (r.post_types?.length) out += `Post types: ${r.post_types.join(', ')}\n`;
+        if (r.option_pages?.length) out += `Options pages: ${r.option_pages.join(', ')}\n`;
+        if (r.note) out += `\n${r.note}\n`;
+        return ok(out);
+    }
+
     case 'audit_orphan_pages': {
         const r = await apiCall('/audit-orphan-pages');
         let msg = `=== ORPHAN PAGES ===\nTotal pages: ${r.total_pages} | Linked: ${r.linked_pages} | Orphans: ${r.orphan_count}\n`;

package/package.json

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