@diviops/mcp-server 0.2.23 → 0.2.29

package/README.md

@@ -96,9 +96,9 @@ The server connects via standard WordPress REST API and works with any environme
 
 > **WP-CLI note:** `WP_PATH` keeps the existing Local by Flywheel behavior by running `wp` directly on the host filesystem. For Docker-based environments (DDEV, wp-env, DevKinsta, WordPress Studio), set `WP_CLI_CMD` to the wrapper command instead. When `WP_CLI_CMD` is set, the server executes the wrapper from `WP_PATH` if provided, otherwise from its current working directory. The MCP server still validates the requested WP-CLI subcommand against its allowlist before executing either path.
 
-## Available Tools (55)
+## Available Tools (63)
 
-### Read (26)
+### Read (30)
 | Tool | Description |
 |------|-------------|
 | `diviops_test_connection` | Test WordPress connection and Divi version |
@@ -115,7 +115,7 @@ The server connects via standard WordPress REST API and works with any environme
 | `diviops_find_icon` | Search 1,989 icons by keyword (FA + Divi) |
 | `diviops_list_templates` | List available MCP prompt templates |
 | `diviops_get_template` | Get a specific template's block markup |
-| `diviops_preset_audit` | Audit presets with referenced/unreferenced analysis. Walks both page content and in-registry `groupPresets` chains; exposes `block_ref_count`, `group_ref_count`, `referenced_by_presets` |
+| `diviops_preset_audit` | Audit presets with referenced/unreferenced analysis. Walks both page content and in-registry `groupPresets` chains; exposes `block_ref_count`, `group_ref_count`, `referenced_by_presets`. Also reports `orphan_default_pointers` — per-bucket `default` pointers referencing UUIDs missing from `items[]` (legacy damage from past unsafe deletes; clear via `diviops_preset_set_default` in bucket-addressed mode: `type` + `module` + `unset=true`) |
 | `diviops_preset_scan_orphans` | List page-referenced preset UUIDs missing from the D5 registry (separates dangling orphans from D4-legacy refs) |
 | `diviops_list_library` | List saved Divi Library items |
 | `diviops_get_library_item` | Get a library item's block markup |
@@ -125,10 +125,14 @@ The server connects via standard WordPress REST API and works with any environme
 | `diviops_get_tb_layout` | Get a Theme Builder layout's block markup (header/body/footer) |
 | `diviops_list_variables` | List design token variables (filter by type or prefix) |
 | `diviops_variables_scan_orphans` | Find `gvid-`/`gcid-` refs with no backing Variable Manager entry (orphans render as invalid CSS) + unused variables (defined, never referenced). Scans pages, Theme Builder layouts (header/body/footer), Divi Library items, canvas pages, and the preset registry |
+| `diviops_variables_used_on_page` | Detect which `gvid-` (numeric/font) IDs a single page emits — the exact set Divi 5.4.0+ uses to scope selective `:root{--gvid-*}` CSS variable emission. Walks the same content stack the frontend assembles (post_content + active TB header/body/footer + appended canvases + presets). `gcid-` colors are out of scope (separate emission path). Use for per-page orphan validation, preflight before bulk variable rename, or to debug why a numeric/font variable doesn't render on a specific page. Read-only |
 | `diviops_list_canvases` | List all canvas pages |
 | `diviops_get_canvas` | Get canvas content |
+| `diviops_scf_status` | Show SCF (Secure Custom Fields) sync status — pending JSON-vs-DB drift across field groups, post types, taxonomies, options pages. Wraps `wp scf json status` |
+| `diviops_scf_list_field_groups` | List all SCF/ACF field groups (post_name = ACF key, post_title, post_status, post_modified). Queries the `acf-field-group` post type via `wp post list` (works on SCF 6.8.4+ and older ACF) |
+| `diviops_scf_get_field_group` | Fetch a single SCF/ACF field-group post by ACF key (`group_abc123` → post_name) or numeric WP post ID. For the parsed/structured field tree, use `diviops_scf_export --field-groups=<key> --stdout` |
 
-### Write (27)
+### Write (31)
 | Tool | Description |
 |------|-------------|
 | `diviops_create_page` | Create a new page with optional Divi content |
@@ -148,16 +152,20 @@ The server connects via standard WordPress REST API and works with any environme
 | `diviops_preset_create` | Write a new preset to the D5 registry (module or group type, supports `divi/column` etc.). Optional `make_default: true` sets it as the bucket's default; optional `priority` controls stack-merge order |
 | `diviops_preset_reassign` | Rewrite `modulePreset` references across pages (dry-run by default; optional `strip_inline` removes redundant inline attrs) |
 | `diviops_preset_update` | Update a specific preset (name, attrs, priority) |
-| `diviops_preset_delete` | Delete a preset by ID |
-| `diviops_preset_set_default` | Set or clear the per-module/group default preset (defaults apply to NEW instances only — use `diviops_preset_reassign` for retroactive swaps) |
+| `diviops_preset_delete` | Delete a preset by ID. Refuses with HTTP 409 `preset_is_default` when the target is the registered default for its bucket — clear the pointer first via `diviops_preset_set_default` with `unset=true`, or pass `force=true` to delete and clear the pointer in one write |
+| `diviops_preset_set_default` | Set or clear the per-module/group default preset. Two modes: by `preset_id` (UUID-addressed; auto-resolves bucket) or by `type` + `module` + `unset=true` (bucket-addressed clear, used to repair orphan default pointers when the UUID is gone from `items[]`). Defaults apply to NEW instances only — use `diviops_preset_reassign` for retroactive swaps |
 | `diviops_save_to_library` | Save block markup to Divi Library |
 | `diviops_update_tb_layout` | Update a Theme Builder layout's block markup |
 | `diviops_create_tb_template` | Create Theme Builder template with header/footer and conditions |
 | `diviops_create_variable` | Create a design token variable. For `type=numbers` fluid tokens, pass `min`+`max` shorthand (anchors default to 320px/1920px) or explicit `targets` like `{"320px":"20px","1920px":"60px"}` — server generates arithmetically-correct `clamp()` instead of hand-written math that silently under-reaches the stated max. All-px inputs emit px (root-agnostic). Rem inputs OR rem output require explicit opt-in: pass `output_unit="rem"` (accepts the 1rem=16px default) or `root_font_size_px:N` (declares your site's actual root font-size, e.g. `10` for `html { font-size: 62.5% }`, `20` for `html { font-size: 20px }`) |
+| `diviops_create_fluid_system` | Batch-emit a fluid typography + spacing + radius variable set in one call. Mirrors Divi 5.4.0's Variable Generator Modal at the algorithm level (clamp() math is identical to `diviops_create_variable`'s fluid mode) but layers profile-selectable anchors over it: `divi-default` (360→1350) matches ET's defaults, `wide` (320→1920) matches the diviops convention, `custom` takes explicit anchors. Each category is independent and optional. Typography uses modular-scale chains (named ratios `major-third`/`perfect-fifth`/`golden`/etc., or raw numbers) — h1 = largest, hN = base. Spacing/radius support `linear` or `geometric` step distributions. `dry_run: true` returns the full plan without persisting; `overwrite: false` (default) skips existing IDs. Single atomic write to the registry — mid-batch failures roll back cleanly |
 | `diviops_delete_variable` | Delete a variable by ID. Returns HTTP 409 when live references exist unless `force=true` (use `diviops_variables_scan_orphans` to find reference locations). Returns HTTP 403 for Divi's customizer-bound defaults (`gcid-primary-color`, `gcid-secondary-color`, `gcid-heading-color`, `gcid-body-color`, `gcid-link-color` — managed via WP Customizer) |
 | `diviops_create_canvas` | Create a canvas page |
 | `diviops_update_canvas` | Update canvas content |
 | `diviops_delete_canvas` | Delete a canvas page |
+| `diviops_scf_export` | Export SCF schema (field groups, post types, taxonomies, options pages) as JSON to a directory under the safe-root, or to stdout. Wraps `wp scf json export` |
+| `diviops_scf_import` | Import SCF schema from a JSON file (mutates DB; idempotent — existing items are updated). Wraps `wp scf json import <file>` |
+| `diviops_scf_sync` | Apply pending JSON-on-disk SCF changes to the DB. Defaults to `dry_run: true` for safety. Wraps `wp scf json sync` |
 
 ### Utility (2)
 | Tool | Description |
@@ -180,7 +188,7 @@ Read-only commands plus non-destructive writes needed for core MCP functionality
 | Post meta | `post meta get`, `post meta list`, `post meta set`, `post meta update` |
 | Post types | `post-type list`, `post-type get` |
 | Taxonomies | `taxonomy list`, `term list`, `term create`, `term update` |
-| ACF / SCF | `acf export`, `acf import`, `acf field-group list`, `acf field-group get` |
+| ACF / SCF | `acf export`, `acf import`, `acf field-group list`, `acf field-group get`, `scf json {status,sync,import,export}` (also aliased as `acf json …` per SCF 6.8.4+) |
 | Users | `user list` |
 | Cache | `cache flush`, `transient delete`, `rewrite flush` |
 | Export | `export` (WXR data export to file) |
@@ -235,12 +243,13 @@ The sentinel grants exactly the extended set above — it does NOT unlock anythi
 
 ### Filesystem flag validation
 
-The three DEFAULT-tier filesystem commands (`wp export`, `acf export <path>`, `acf import <path>`) are second-pass validated against a safe root so wrong-path arguments can't write WXR to the web root or read ACF configs from arbitrary locations.
+The DEFAULT-tier filesystem commands (`wp export`, `acf export <path>`, `acf import <path>`, `scf json export --dir=<path>`, `scf json import <file>`, plus the `acf json …` aliases) are second-pass validated against a safe root so wrong-path arguments can't write WXR / schema JSON to the web root or read configs from arbitrary locations.
 
 - **Safe root**: `<WP_PATH>/.diviops-tmp/` by default (auto-created on first use in host mode). Override with `DIVIOPS_WP_CLI_SAFE_FS_ROOT=/absolute/path`. All path arguments must canonicalize under this directory; symlinks are resolved via `realpath` so a planted symlink inside the safe root pointing outside it is caught.
 - **`wp export` must pass `--dir=<path-under-safe-root>`** (or `--stdout`). Without `--dir`, wp-cli writes to the current working directory; on prod that's typically the web root.
 - **`--filename_format=` must be a filename template**, not a path — separators (`/`, `\`) are rejected so a crafted template can't escape `--dir`'s scope.
 - **`acf export/import`'s positional path** must resolve under the safe root.
+- **`scf json export`'s `--dir=` flag** must resolve under the safe root (or pass `--stdout` for in-memory transfer). **`scf json import`'s positional `<file>` path** must resolve under the safe root.
 - **Wrapper mode (`WP_CLI_CMD`)**: the host-derived safe root doesn't correspond to the wrapper's filesystem (e.g., container paths like `/www/app`), so `DIVIOPS_WP_CLI_SAFE_FS_ROOT` is **required** and must be set to the container-namespace path. FS-sensitive commands are rejected with a clear error if it's missing.
 - **Escape hatch**: `DIVIOPS_WP_CLI_UNSAFE_FS=1` disables validation entirely. Appropriate for trusted single-user local-dev setups that don't want the guard.
 
@@ -248,7 +257,7 @@ The three DEFAULT-tier filesystem commands (`wp export`, `acf export <path>`, `a
 
 ## Safety Patterns
 
-High-risk or bulk destructive tools follow one of two conventions to guard against unintended mutation. Both are stateless (no session tokens between calls), but they guard differently: Pattern A is a **stateless gate** — the first call mutates when the safety check passes, refuses with an explanatory error when it fires. Pattern B is **preview-before-commit** — the first call never mutates; an explicit apply step is required. Tools without a gate (e.g., `diviops_preset_delete`, `diviops_update_page_content`) execute their mutation directly — whether to adopt a pattern is a per-tool design decision, not a retrofit requirement.
+High-risk or bulk destructive tools follow one of two conventions to guard against unintended mutation. Both are stateless (no session tokens between calls), but they guard differently: Pattern A is a **stateless gate** — the first call mutates when the safety check passes, refuses with an explanatory error when it fires. Pattern B is **preview-before-commit** — the first call never mutates; an explicit apply step is required. Tools without a gate (e.g., `diviops_update_page_content`) execute their mutation directly — whether to adopt a pattern is a per-tool design decision, not a retrofit requirement.
 
 ### Pattern A — `force: false/true` (refuse-with-override)
 
@@ -264,6 +273,7 @@ Tool refuses the operation with an explanatory error when a safety check fails;
 | Tool | Guard | Override |
 |------|-------|----------|
 | `diviops_delete_variable` | HTTP 409 when live references exist | `force=true` |
+| `diviops_preset_delete` | HTTP 409 `preset_is_default` when target is the registered default for its bucket | `force=true` (deletes + clears the `default` pointer in the same write) |
 
 ### Pattern B — `mode: "dry-run"/"apply"` (preview-then-commit)
 

package/dist/compatibility.d.ts

@@ -2,7 +2,7 @@
  * Version compatibility between MCP server and WP plugin.
  */
 /** Minimum WP plugin version this server requires. */
-export declare const MIN_PLUGIN_VERSION = "1.0.0-beta.38";
+export declare const MIN_PLUGIN_VERSION = "1.0.0-beta.44";
 /**
  * Compare two semver-like version strings (supports pre-release tags).
  *

package/dist/compatibility.js

@@ -2,7 +2,7 @@
  * Version compatibility between MCP server and WP plugin.
  */
 /** Minimum WP plugin version this server requires. */
-export const MIN_PLUGIN_VERSION = '1.0.0-beta.38';
+export const MIN_PLUGIN_VERSION = '1.0.0-beta.44';
 /**
  * Compare two semver-like version strings (supports pre-release tags).
  *

package/dist/index.js

@@ -521,7 +521,7 @@ server.registerTool("diviops_get_section", {
     };
 });
 server.registerTool("diviops_update_module", {
-    description: 'Update specific attributes of a module. Target by auto_index (e.g. "text:5"), admin label, or text content. Uses dot notation for attribute paths. Example: {"content.decoration.headingFont.h2.font.desktop.value.color": "#ff0000"}. Priority: auto_index > label > match_text. Use occurrence with label when duplicates exist.',
+    description: 'Update specific attributes of a module. Target by auto_index (e.g. "text:5"), admin label, or text content. Uses dot notation for attribute paths. Example: {"content.decoration.headingFont.h2.font.desktop.value.color": "#ff0000"}. For paths whose key segments contain literal dots — notably Composable Settings preset slots like groupPreset["title.decoration.spacing"] — escape the inner dots with `\\.` to keep the segment intact: {"groupPreset.title\\\\.decoration\\\\.spacing.presetId": ["uuid"]}. Priority: auto_index > label > match_text. Use occurrence with label when duplicates exist.',
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
         label: z
@@ -746,7 +746,7 @@ server.registerTool("diviops_create_page", {
 });
 // ── Preset Tools ────────────────────────────────────────────────────
 server.registerTool("diviops_preset_audit", {
-    description: "Audit all Divi presets (module + group). Each entry reports `block_ref_count` (page-content refs via modulePreset / groupPreset block markup), `group_ref_count` (in-registry chain refs from other presets — module presets via top-level `groupPresets.<slot>.presetId`, group presets via `attrs.groupPreset.<slot>.presetId`), and `referenced` (true if either > 0). Group presets that are chain-referenced also expose `referenced_by_presets` (UUIDs of the presets that wire them in — typically module presets, but type-agnostic). Use this before deleting — orphan-cleanup based only on page refs would silently wipe load-bearing chain-wired group presets (font, border, box-shadow, spacing, button).",
+    description: "Audit all Divi presets (module + group). Each entry reports `block_ref_count` (page-content refs via modulePreset / groupPreset block markup), `group_ref_count` (in-registry chain refs from other presets — module presets via top-level `groupPresets.<slot>.presetId`, group presets via `attrs.groupPreset.<slot>.presetId`), and `referenced` (true if either > 0). Group presets that are chain-referenced also expose `referenced_by_presets` (UUIDs of the presets that wire them in — typically module presets, but type-agnostic). Use this before deleting — orphan-cleanup based only on page refs would silently wipe load-bearing chain-wired group presets (font, border, box-shadow, spacing, button). Also reports `orphan_default_pointers`: per-bucket `default` pointers that reference a UUID no longer present in `items[]` (caused by past unsafe deletes). Render-safe but blocks Divi's lazy recreate-on-VB-use path; clear via diviops_preset_set_default with unset=true on the affected module/group.",
 }, async () => {
     const result = await wp.request("/preset-audit");
     return {
@@ -835,14 +835,21 @@ server.registerTool("diviops_preset_update", {
     };
 });
 server.registerTool("diviops_preset_delete", {
-    description: "Delete a specific preset by ID. Use diviops_preset_audit first to verify the preset is unreferenced before deleting.",
+    description: "Delete a specific preset by ID. Use diviops_preset_audit first to verify the preset is unreferenced before deleting. Refuses with 409 preset_is_default if the target is the registered default for its module/group bucket — clear the pointer first via diviops_preset_set_default with unset=true, or pass force=true to delete and clear the pointer in one write.",
     inputSchema: {
         preset_id: z.string().describe("Preset ID to delete"),
+        force: z
+            .boolean()
+            .optional()
+            .describe("When true, deletes the preset even if it is the registered default and clears the default pointer in the same write. Default false (refuse-by-default)."),
     },
-}, async ({ preset_id }) => {
+}, async ({ preset_id, force }) => {
+    const body = { preset_id };
+    if (force !== undefined)
+        body.force = force;
     const result = await wp.request("/preset-delete", {
         method: "POST",
-        body: { preset_id },
+        body,
     });
     return {
         content: [
@@ -969,18 +976,33 @@ server.registerTool("diviops_preset_scan_orphans", {
     };
 });
 server.registerTool("diviops_preset_set_default", {
-    description: "Set or clear the per-module/group default preset. Walks both buckets to locate the preset by UUID, then points the containing module/group's `default` slot at it. Pass unset=true to clear the slot back to none. Defaults apply to NEW module instances only — existing modules keep their current preset bindings (use diviops_preset_reassign for retroactive swaps). Use diviops_preset_audit's `is_default` field to verify state before/after.",
+    description: "Set or clear the per-module/group default preset. Two addressing modes: (1) preset_id mode — walks both buckets to locate the preset by UUID, then points the containing module/group's `default` slot at it (or clears it with unset=true). (2) Bucket-addressed clear — pass type + module + unset=true to clear an orphan default pointer when the preset_id no longer exists in items[] (the preset_id walk path can't locate orphans — that's the very state being repaired; surfaced via diviops_preset_audit's `orphan_default_pointers`). Defaults apply to NEW module instances only — existing modules keep their current preset bindings (use diviops_preset_reassign for retroactive swaps). Use diviops_preset_audit's `is_default` and `orphan_default_pointers` fields to verify state before/after.",
     inputSchema: {
         preset_id: z
             .string()
-            .describe("Preset UUID. Bucket (module vs. group) and target module/group are auto-resolved from the registry — no need to specify them."),
+            .optional()
+            .describe("Preset UUID. Bucket (module vs. group) and target module/group are auto-resolved from the registry — no need to specify them. Required unless using bucket-addressed clear (type + module + unset=true) to repair an orphan default pointer."),
+        type: z
+            .enum(["module", "group"])
+            .optional()
+            .describe("Bucket-addressed clear: bucket type. Required together with `module` and `unset=true` to clear an orphan default pointer (UUID gone from items[] but `default` still references it)."),
+        module: z
+            .string()
+            .optional()
+            .describe('Bucket-addressed clear: module slug or group key (e.g. "divi/blurb", "divi/font"). Required together with `type` and `unset=true`.'),
         unset: z
             .boolean()
             .optional()
-            .describe("If true, clear the default pointer for the module/group this preset lives in (regardless of whether this preset is currently the default). Defaults to false (set the preset as the default)."),
+            .describe("If true, clear the default pointer. With preset_id, clears the bucket containing that preset. With type+module, clears that bucket directly (use this form for orphan-pointer repair). Defaults to false (set the preset as the default — preset_id required)."),
     },
-}, async ({ preset_id, unset }) => {
-    const body = { preset_id };
+}, async ({ preset_id, type, module, unset }) => {
+    const body = {};
+    if (preset_id !== undefined)
+        body.preset_id = preset_id;
+    if (type !== undefined)
+        body.type = type;
+    if (module !== undefined)
+        body.module = module;
     if (unset)
         body.unset = true;
     const result = await wp.request("/preset-set-default", {
@@ -1300,7 +1322,7 @@ server.registerTool("diviops_delete_canvas", {
 });
 // ── WP-CLI ──────────────────────────────────────────────────────────
 server.registerTool("diviops_wp_cli", {
-    description: "Run a WP-CLI command on the WordPress site. Requires WP_PATH env var (LOCAL_SITE_ID auto-detected from Local by Flywheel), or WP_CLI_CMD for containerized wrappers. Commands validated against a safety allowlist. Default tier covers read ops across options/posts/post-types/taxonomies/users/info/core/db, non-destructive writes (post/term create+update, post meta read/write, cache/rewrite/transient flush), ACF schema ops (export/import/list/get field-group), and WXR export. Extended tier (requires DIVIOPS_WP_CLI_ALLOW env var) adds destructive or bulk-modifying ops: option update, post/post meta/term delete, search-replace, import, plugin activate/deactivate, eval-file. Filesystem-touching commands (`wp export`, `acf export/import`) are additionally constrained: path arguments must resolve under a safe root (defaults to `<WP_PATH>/.diviops-tmp/`, overridable via DIVIOPS_WP_CLI_SAFE_FS_ROOT, disable via DIVIOPS_WP_CLI_UNSAFE_FS=1); `wp export` requires an explicit `--dir=<path>` (or `--stdout`). In WP_CLI_CMD wrapper mode, DIVIOPS_WP_CLI_SAFE_FS_ROOT is required for FS-sensitive commands. Use --format=json for structured output. Full allowlist + tier rationale + filesystem semantics in the MCP server README.",
+    description: "Run a WP-CLI command on the WordPress site. Requires WP_PATH env var (LOCAL_SITE_ID auto-detected from Local by Flywheel), or WP_CLI_CMD for containerized wrappers. Commands validated against a safety allowlist. Default tier covers read ops across options/posts/post-types/taxonomies/users/info/core/db, non-destructive writes (post/term create+update, post meta read/write, cache/rewrite/transient flush), ACF/SCF schema ops (`acf export/import/field-group list/get` plus SCF 6.8.4+ `scf json {status,sync,import,export}` and the `acf json …` aliases), and WXR export. Extended tier (requires DIVIOPS_WP_CLI_ALLOW env var) adds destructive or bulk-modifying ops: option update, post/post meta/term delete, search-replace, import, plugin activate/deactivate, eval-file. Filesystem-touching commands (`wp export`, `acf export/import`, `scf|acf json export/import`) are additionally constrained: path arguments must resolve under a safe root (defaults to `<WP_PATH>/.diviops-tmp/`, overridable via DIVIOPS_WP_CLI_SAFE_FS_ROOT, disable via DIVIOPS_WP_CLI_UNSAFE_FS=1); `wp export` and `scf json export` require an explicit `--dir=<path>` (or `--stdout`). In WP_CLI_CMD wrapper mode, DIVIOPS_WP_CLI_SAFE_FS_ROOT is required for FS-sensitive commands. Prefer the typed `diviops_scf_*` wrappers for SCF round-trips — they're easier to invoke and accept the same safe-root scoping. Use --format=json for structured output. Full allowlist + tier rationale + filesystem semantics in the MCP server README.",
     inputSchema: {
         command: z
             .string()
@@ -1323,6 +1345,275 @@ server.registerTool("diviops_wp_cli", {
         : `Error: ${result.error}\n${result.output}`;
     return { content: [{ type: "text", text: output }] };
 });
+// ── SCF (Secure Custom Fields / ACF) wrappers ───────────────────────
+//
+// Typed wrappers over SCF 6.8.4+'s `wp scf json {status,sync,import,export}`
+// CLI family (also reachable as `wp acf json …`). The plugin file at
+// wp-content/plugins/secure-custom-fields/src/CLI/JsonCommand.php is the
+// upstream source of truth for flag shapes — keep these wrappers aligned.
+function ensureWpCli() {
+    if (!wpCli) {
+        return {
+            ok: false,
+            text: "WP-CLI not configured. Set WP_PATH (Local by Flywheel auto-detect) " +
+                "or WP_CLI_CMD (containerized wrappers) to enable SCF round-trip tools.",
+        };
+    }
+    return { ok: true };
+}
+function pushScfFlag(args, name, value) {
+    if (!value)
+        return;
+    // Each `--name=value` becomes a single argv entry — execFile handles spaces
+    // and quotes inside the value transparently. No string concatenation, no
+    // parseCommand round-trip, so values like "Bob's Group" or filenames with
+    // spaces flow through verbatim.
+    args.push(`--${name}=${value}`);
+}
+server.registerTool("diviops_scf_status", {
+    description: "Show SCF (Secure Custom Fields) sync status — how many field groups, post types, taxonomies, and options pages have JSON-on-disk newer than the database (or absent from DB). Read-only. Wraps `wp scf json status`. Requires SCF 6.8.4+ and WP_PATH or WP_CLI_CMD.",
+    inputSchema: {
+        type: z
+            .enum(["field-group", "post-type", "taxonomy", "options-page"])
+            .optional()
+            .describe("Limit to a single item type. Defaults to all types. options-page requires ACF PRO."),
+        detailed: z
+            .boolean()
+            .optional()
+            .describe("List the individual pending items (key/title/type/action) instead of just counts."),
+    },
+}, async ({ type, detailed }) => {
+    const gate = ensureWpCli();
+    if (!gate.ok) {
+        return { content: [{ type: "text", text: gate.text }] };
+    }
+    const args = ["scf", "json", "status", "--format=json"];
+    pushScfFlag(args, "type", type);
+    if (detailed)
+        args.push("--detailed");
+    const result = await wpCli.runArgs(args);
+    const output = result.success
+        ? result.output
+        : `Error: ${result.error}\n${result.output}`;
+    return { content: [{ type: "text", text: output }] };
+});
+server.registerTool("diviops_scf_export", {
+    description: "Export SCF field groups, post types, taxonomies, and options pages as JSON — to a directory under the safe-root (`<WP_PATH>/.diviops-tmp/` by default, override via DIVIOPS_WP_CLI_SAFE_FS_ROOT) or to stdout. Wraps `wp scf json export`. Either `dir` or `stdout: true` is required. Filters can be combined; without filters, all items are exported. Note: SCF writes a fixed filename `acf-export-YYYY-MM-DD.json` inside `dir` — two exports on the same day silently overwrite. Copy/rename if you're archiving baselines.",
+    inputSchema: {
+        dir: z
+            .string()
+            .optional()
+            .describe("Absolute output directory under the WP-CLI safe-root. Mutually exclusive with `stdout`. SCF writes a single `acf-export-YYYY-MM-DD.json` file inside this dir."),
+        stdout: z
+            .boolean()
+            .optional()
+            .describe("Print JSON to stdout instead of writing a file. Mutually exclusive with `dir`."),
+        field_groups: z
+            .string()
+            .optional()
+            .describe("Comma-separated field-group ACF keys (`group_abc123`) or admin titles (`My Field Group`). NOT WP post slugs — SCF matches against the def's `key` field or its `title` (case-insensitive). Use `diviops_scf_list_field_groups` to discover keys (post_name column)."),
+        post_types: z
+            .string()
+            .optional()
+            .describe("Comma-separated SCF post-type def keys (`post_type_xxx`) or admin titles (`Programm`). IMPORTANT: this is the SCF def's identifier, NOT the registered post-type slug (`event`, `book`). The registered slug is what `wp post list` and REST URLs use, but SCF's filter matches against the def's `key` field or its `title`. To discover def keys, run `diviops_scf_export --stdout` (no filter) and inspect the top-level entries with `parent='post-type'`."),
+        taxonomies: z
+            .string()
+            .optional()
+            .describe("Comma-separated SCF taxonomy def keys (`taxonomy_xxx`) or admin titles. Same caveat as `post_types`: NOT the registered taxonomy slug — the SCF def's `key` or `title`. Discover via `diviops_scf_export --stdout`."),
+        options_pages: z
+            .string()
+            .optional()
+            .describe("Comma-separated options-page def keys or admin titles. Requires ACF PRO."),
+    },
+}, async ({ dir, stdout, field_groups, post_types, taxonomies, options_pages }) => {
+    const gate = ensureWpCli();
+    if (!gate.ok) {
+        return { content: [{ type: "text", text: gate.text }] };
+    }
+    if (!dir && !stdout) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Error: pass either `dir` (absolute path under DIVIOPS_WP_CLI_SAFE_FS_ROOT) or `stdout: true`.",
+                },
+            ],
+        };
+    }
+    if (dir && stdout) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Error: `dir` and `stdout` are mutually exclusive — pick one.",
+                },
+            ],
+        };
+    }
+    const args = ["scf", "json", "export"];
+    if (stdout)
+        args.push("--stdout");
+    pushScfFlag(args, "dir", dir);
+    pushScfFlag(args, "field-groups", field_groups);
+    pushScfFlag(args, "post-types", post_types);
+    pushScfFlag(args, "taxonomies", taxonomies);
+    pushScfFlag(args, "options-pages", options_pages);
+    const result = await wpCli.runArgs(args);
+    const output = result.success
+        ? result.output
+        : `Error: ${result.error}\n${result.output}`;
+    return { content: [{ type: "text", text: output }] };
+});
+server.registerTool("diviops_scf_import", {
+    description: "Import SCF field groups, post types, taxonomies, options pages from a JSON file. Mutates the database. File path must resolve under the safe-root (`<WP_PATH>/.diviops-tmp/` by default, override via DIVIOPS_WP_CLI_SAFE_FS_ROOT). Idempotent — existing items with matching keys are updated. Wraps `wp scf json import <file>`.",
+    inputSchema: {
+        file: z
+            .string()
+            .describe("Absolute path to the .json file to import. Must resolve under DIVIOPS_WP_CLI_SAFE_FS_ROOT."),
+    },
+}, async ({ file }) => {
+    const gate = ensureWpCli();
+    if (!gate.ok) {
+        return { content: [{ type: "text", text: gate.text }] };
+    }
+    const result = await wpCli.runArgs(["scf", "json", "import", file]);
+    const output = result.success
+        ? result.output
+        : `Error: ${result.error}\n${result.output}`;
+    return { content: [{ type: "text", text: output }] };
+});
+server.registerTool("diviops_scf_sync", {
+    description: "Apply pending JSON-on-disk SCF changes to the database. Reads JSON files from the theme/plugin acf-json directory and creates/updates DB entries. Defaults to `dry_run: true` for safety — caller must opt in to mutation. Wraps `wp scf json sync`.",
+    inputSchema: {
+        type: z
+            .enum(["field-group", "post-type", "taxonomy", "options-page"])
+            .optional()
+            .describe("Limit sync to a single item type."),
+        key: z
+            .string()
+            .optional()
+            .describe("Sync only the item with this ACF key (e.g. `group_abc123`)."),
+        dry_run: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Preview pending changes without mutating the database. Defaults to true. Pass `false` to commit."),
+    },
+}, async ({ type, key, dry_run }) => {
+    const gate = ensureWpCli();
+    if (!gate.ok) {
+        return { content: [{ type: "text", text: gate.text }] };
+    }
+    const args = ["scf", "json", "sync"];
+    pushScfFlag(args, "type", type);
+    pushScfFlag(args, "key", key);
+    if (dry_run !== false)
+        args.push("--dry-run");
+    const result = await wpCli.runArgs(args);
+    const output = result.success
+        ? result.output
+        : `Error: ${result.error}\n${result.output}`;
+    return { content: [{ type: "text", text: output }] };
+});
+server.registerTool("diviops_scf_list_field_groups", {
+    description: "List all SCF/ACF field groups in the database (post_name = ACF key, post_title, post_status, post_modified). Read-only. Queries the underlying `acf-field-group` post type via `wp post list` — works on both SCF 6.8.4+ (which dropped the legacy `wp acf field-group …` family in favor of the `wp scf json` namespace) and older ACF installs.",
+}, async () => {
+    const gate = ensureWpCli();
+    if (!gate.ok) {
+        return { content: [{ type: "text", text: gate.text }] };
+    }
+    const result = await wpCli.runArgs([
+        "post",
+        "list",
+        "--post_type=acf-field-group",
+        "--post_status=any",
+        "--fields=ID,post_name,post_title,post_status,post_modified",
+        "--format=json",
+    ]);
+    const output = result.success
+        ? result.output
+        : `Error: ${result.error}\n${result.output}`;
+    return { content: [{ type: "text", text: output }] };
+});
+server.registerTool("diviops_scf_get_field_group", {
+    description: "Fetch a single SCF/ACF field group from the `acf-field-group` post type — by ACF key (`group_abc123`, looked up via `post_name`) or by numeric WP post ID. Returns the WP post fields (post_name, post_title, post_content with serialized fields blob, post_status, post_modified). For the parsed/structured field tree including nested fields, use `diviops_scf_export --field-groups=<key> --stdout` instead. Read-only. SCF 6.8.4 dropped the legacy `wp acf field-group get` command, so this wrapper queries the post type directly via `wp post`.",
+    inputSchema: {
+        key: z
+            .string()
+            .describe("ACF field-group key (`group_abc123`, matched against post_name) or numeric WP post ID."),
+    },
+}, async ({ key }) => {
+    const gate = ensureWpCli();
+    if (!gate.ok) {
+        return { content: [{ type: "text", text: gate.text }] };
+    }
+    // If the input looks like a numeric ID, hand it to `wp post get` directly.
+    // Otherwise treat it as an ACF key and resolve via post_name first.
+    const isNumericId = /^\d+$/.test(key);
+    if (isNumericId) {
+        const result = await wpCli.runArgs([
+            "post",
+            "get",
+            key,
+            "--format=json",
+        ]);
+        const output = result.success
+            ? result.output
+            : `Error: ${result.error}\n${result.output}`;
+        return { content: [{ type: "text", text: output }] };
+    }
+    // Resolve ACF key → post ID via `wp post list --name=<key>`. Single-row
+    // lookup; returns [] if the key isn't found.
+    const lookup = await wpCli.runArgs([
+        "post",
+        "list",
+        "--post_type=acf-field-group",
+        "--post_status=any",
+        `--name=${key}`,
+        "--fields=ID",
+        "--format=json",
+    ]);
+    if (!lookup.success) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error looking up field-group key "${key}": ${lookup.error}\n${lookup.output}`,
+                },
+            ],
+        };
+    }
+    let postId = null;
+    try {
+        const rows = JSON.parse(lookup.output);
+        if (Array.isArray(rows) && rows.length > 0) {
+            postId = String(rows[0].ID);
+        }
+    }
+    catch {
+        // Fall through — postId stays null, return a clear "not found" error.
+    }
+    if (!postId) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `No field-group found for key "${key}". Use diviops_scf_list_field_groups to see available keys (post_name field).`,
+                },
+            ],
+        };
+    }
+    const result = await wpCli.runArgs([
+        "post",
+        "get",
+        postId,
+        "--format=json",
+    ]);
+    const output = result.success
+        ? result.output
+        : `Error: ${result.error}\n${result.output}`;
+    return { content: [{ type: "text", text: output }] };
+});
 // ── Connection ──────────────────────────────────────────────────────
 server.registerTool("diviops_test_connection", {
     description: "Test the connection to the WordPress site and verify the Divi MCP plugin is active.",
@@ -1590,6 +1881,174 @@ server.registerTool("diviops_create_variable", {
         ],
     };
 });
+server.registerTool("diviops_create_fluid_system", {
+    description: "Batch-emit a fluid typography + spacing + radius variable set in one call — mirrors Divi 5.4.0's Variable Generator Modal at the algorithm level (clamp() math is identical to diviops_create_variable's fluid mode) but layers profile-selectable anchors over it. Each category is independent and optional. Use for: (1) bootstrapping a design system in one call instead of 20+ individual diviops_create_variable invocations; (2) mirroring ET's variable layout so your tokens coexist with VB-generated ones in the Variable Manager; (3) deterministic preflight via dry_run before committing the registry change. By default, refuses to overwrite existing IDs (returns them in `skipped`) — pass overwrite=true to update in place. Persists in a single atomic write to the variable registry; mid-batch failures roll back cleanly.",
+    inputSchema: {
+        profile: z
+            .enum(["divi-default", "wide", "custom"])
+            .optional()
+            .default("divi-default")
+            .describe('Anchor preset for the underlying clamp() math. "divi-default" (360→1350) matches Divi 5.4.0\'s Variable Generator Modal defaults; "wide" (320→1920) covers a wider device span (the diviops convention); "custom" requires custom_anchors. Affects ALL three categories uniformly.'),
+        custom_anchors: z
+            .object({
+            min_viewport_px: z.number().positive(),
+            max_viewport_px: z.number().positive(),
+        })
+            .refine((a) => a.max_viewport_px > a.min_viewport_px, {
+            message: "custom_anchors.max_viewport_px must be > min_viewport_px",
+        })
+            .optional()
+            .describe('Required when profile="custom". Defines the (min_viewport_px, max_viewport_px) pair the clamp() formulas anchor to. max must be > min. (The profile/custom_anchors pairing is also enforced server-side, returning 400 invalid_profile if profile="custom" is sent without custom_anchors.)'),
+        typography: z
+            .object({
+            base_px: z
+                .number()
+                .positive()
+                .describe("Base body size in px. Step N's value = base_px × ratio^(steps-1). h1 = largest (top of chain), hN = base."),
+            ratio: z
+                .union([
+                z.number().positive(),
+                z.enum([
+                    "minor-second",
+                    "major-second",
+                    "minor-third",
+                    "major-third",
+                    "perfect-fourth",
+                    "augmented-fourth",
+                    "perfect-fifth",
+                    "golden",
+                ]),
+            ])
+                .describe("Modular-scale ratio. Pass a named scale ('major-third'=1.25, 'perfect-fifth'=1.5, 'golden'=1.618, etc.) or a raw number. Step N is base × ratio^(steps-N), so h1 (step 1) is the largest size when steps>1."),
+            steps: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .describe("Number of typography steps to emit (e.g. 6 = h1..h6). Cap is 20 to prevent runaway scale chains."),
+            max_ratio: z
+                .union([
+                z.number().positive(),
+                z.enum([
+                    "minor-second",
+                    "major-second",
+                    "minor-third",
+                    "major-third",
+                    "perfect-fourth",
+                    "augmented-fourth",
+                    "perfect-fifth",
+                    "golden",
+                ]),
+            ])
+                .optional()
+                .describe("Optional ratio at max viewport. Defaults to ratio (same chain at both anchors). Pass a larger value (e.g. ratio=1.2 + max_ratio=1.333) for a more dramatic scale on large screens."),
+            fluid_growth: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Multiplicative growth factor at max viewport. Default 1.0 = discrete (each step emits a fixed value, no clamp growth). Common values: 1.2-1.5 for moderate fluid scaling. Step N's clamp goes from `base × ratio^(steps-N)` at min_viewport to `base × max_ratio^(steps-N) × fluid_growth` at max_viewport."),
+            name_prefix: z
+                .string()
+                .optional()
+                .describe("ID prefix per step. Default 'h' → IDs become gvid-{namespace}-size-h1..hN. Pass 'display' for hero sizes ('gvid-{namespace}-size-display1..')."),
+        })
+            .optional(),
+        spacing: z
+            .object({
+            min_px: z.number().min(0),
+            max_px: z.number().positive(),
+            steps: z.number().int().min(1).max(30),
+            scale: z
+                .enum(["linear", "geometric"])
+                .optional()
+                .default("linear")
+                .describe("Distribution between min_px and max_px. 'linear' = equal arithmetic spacing (best for spacing scales). 'geometric' = equal multiplicative spacing (best for typography-like scales). geometric requires min_px > 0."),
+            fluid_growth: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Multiplicative growth factor at max viewport. Default 1.0 = discrete (each spacing token is constant across viewports — typical design-system behavior). > 1.0 = fluid (each token scales from `value` at min_viewport to `value × fluid_growth` at max_viewport)."),
+            name_prefix: z
+                .string()
+                .optional()
+                .describe("ID prefix. Default 'space' → gvid-{namespace}-space-1..N."),
+        })
+            .optional(),
+        radius: z
+            .object({
+            min_px: z.number().min(0),
+            max_px: z.number().positive(),
+            steps: z.number().int().min(1).max(30),
+            scale: z.enum(["linear", "geometric"]).optional().default("linear"),
+            fluid_growth: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Multiplicative growth factor at max viewport. Default 1.0 = discrete. Most radius tokens stay discrete; pass > 1.0 only when you want corners to grow with viewport."),
+            name_prefix: z
+                .string()
+                .optional()
+                .describe("ID prefix. Default 'rounded' → gvid-{namespace}-rounded-1..N."),
+        })
+            .optional(),
+        namespace: z
+            .string()
+            .regex(/^[a-z0-9_-]+$/i, {
+            message: "namespace must match [a-z0-9_-]+ (case-insensitive; lowercased server-side). Inputs outside this charset are rejected explicitly rather than silently rewritten — passing 'o a' or 'oa!' would alias onto the default 'oa' namespace and risk overwriting unrelated tokens.",
+        })
+            .optional()
+            .default("oa")
+            .describe("Namespace inserted into every generated ID (gvid-{namespace}-*). Default 'oa' matches existing diviops convention. Validated against [a-z0-9_-]+ on both client and server (rejects rather than sanitizes — see message for rationale)."),
+        output_unit: z
+            .enum(["rem", "px"])
+            .optional()
+            .describe('Unit for emitted clamp() formulas. Defaults to "px" (root-agnostic, safe). Pass "rem" to opt into rem emission (bakes the 1rem=16px assumption unless root_font_size_px is also passed).'),
+        root_font_size_px: z
+            .number()
+            .positive()
+            .optional()
+            .describe("Site's actual root font-size in px. Pass for non-16px-root sites (e.g. 10 for `html { font-size: 62.5% }`). Passing this alone implies output_unit='rem'."),
+        dry_run: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Preview the full plan without persisting. Returns identical `created`/`skipped` shape so callers can audit IDs and clamp() values before committing."),
+        overwrite: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When false (default), existing IDs land in `skipped` with the existing value. When true, each existing ID is updated in place (label + value rewritten, order preserved)."),
+    },
+}, async ({ profile, custom_anchors, typography, spacing, radius, namespace, output_unit, root_font_size_px, dry_run, overwrite, }) => {
+    const body = { profile };
+    if (custom_anchors !== undefined)
+        body.custom_anchors = custom_anchors;
+    if (typography !== undefined)
+        body.typography = typography;
+    if (spacing !== undefined)
+        body.spacing = spacing;
+    if (radius !== undefined)
+        body.radius = radius;
+    if (namespace !== undefined)
+        body.namespace = namespace;
+    if (output_unit !== undefined)
+        body.output_unit = output_unit;
+    if (root_font_size_px !== undefined)
+        body.root_font_size_px = root_font_size_px;
+    if (dry_run !== undefined)
+        body.dry_run = dry_run;
+    if (overwrite !== undefined)
+        body.overwrite = overwrite;
+    const result = await wp.request("/variables-create-fluid-system", {
+        method: "POST",
+        body,
+    });
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result) },
+        ],
+    };
+});
 server.registerTool("diviops_delete_variable", {
     description: "Delete a design token variable by ID. Auto-detects storage from ID prefix (gcid-* = colors, gvid-* = numbers/strings/etc). Returns HTTP 409 when live references exist unless force=true — run diviops_variables_scan_orphans to see where the references live. Returns HTTP 403 for Divi's customizer-bound defaults (gcid-primary-color, gcid-secondary-color, gcid-heading-color, gcid-body-color, gcid-link-color); those are managed via WP Customizer theme options and can't be deleted via this tool.",
     inputSchema: {
@@ -1623,6 +2082,23 @@ server.registerTool("diviops_variables_scan_orphans", {
         ],
     };
 });
+server.registerTool("diviops_variables_used_on_page", {
+    description: "Detect which numeric/font variable IDs a single page actually emits — the exact set Divi 5.4.0+ uses to scope selective `:root{--gvid-*}` CSS variable emission. Walks the same content stack the frontend assembles: post_content + active Theme Builder header/body/footer template content + appended canvas content (interaction targets etc.), plus presets referenced by that content. NOTE: this is `gvid-*` only — color variables (`gcid-*`) are emitted via a separate path (`GlobalData` color block) that is NOT scoped per-page in 5.4.0; this tool returns gvid IDs only. Use for per-page orphan validation (complements global diviops_variables_scan_orphans), preflight before bulk variable rename (know which pages are affected), or to debug why a numeric/font variable doesn't render on a specific page. Read-only. Returns variable_ids (sorted, deduped), count, and the tb_template_ids resolved for that post.",
+    inputSchema: {
+        post_id: z
+            .number()
+            .int()
+            .positive()
+            .describe("WordPress post/page ID. The page does not need to be Divi-built — TB templates and canvases attached to non-Divi posts are still scanned."),
+    },
+}, async ({ post_id }) => {
+    const result = await wp.request(`/variables-used-on-page/${post_id}`);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result) },
+        ],
+    };
+});
 server.registerTool("diviops_flush_static_cache", {
     description: "Flush Divi's compiled static CSS cache under wp-content/et-cache/. wp cache flush does NOT touch these files — the frontend can keep serving stale CSS after a preset/variable/module mutation until the cache is cleared. Delegates to Divi's native ET_Core_PageResource::remove_static_resources when available (response backend: \"divi_native\"), which additionally clears Theme Builder CSS scattered across other post dirs, archive/taxonomy/home/notfound CSS, the object cache, module features cache, post features cache, Google Fonts cache, dynamic assets cache, and post meta caches. Falls back to a targeted filesystem walk of numeric-named et-cache subdirs when the Divi class is absent (backend: \"fs_fallback\"). Provide exactly one selector — no site-wide default to prevent accidental full flush. Idempotent: missing cache root returns 200 with empty list.",
     inputSchema: {

package/dist/wp-cli-fs-validator.d.ts

@@ -53,8 +53,12 @@ export declare function fsValidationDisabled(): boolean;
 export declare function ensureSafeFsRoot(safeRoot: string): void;
 /**
  * Identify which FS-sensitive command a parsed arg vector represents.
- * Returns the canonical prefix ("export", "acf export", "acf import") or
- * null if the args don't match a FS-sensitive command.
+ * Returns the canonical prefix ("export", "acf export", "scf json export"…)
+ * or null if the args don't match a FS-sensitive command.
+ *
+ * Checks 3-, 2-, then 1-word prefixes — longer matches win so that
+ * `scf json export` is identified as the SCF command (not bare `export`)
+ * even though both share the trailing word.
  */
 export declare function matchFsSensitiveCommand(args: string[]): string | null;
 /**

package/dist/wp-cli-fs-validator.js

@@ -31,11 +31,19 @@ const SAFE_FS_ROOT_OVERRIDE_ENV = 'DIVIOPS_WP_CLI_SAFE_FS_ROOT';
  * DEFAULT-tier commands whose arguments can write/read to arbitrary paths.
  * EXTENDED-tier FS commands (`import`, `eval-file`) are opt-in and not
  * validated here — opting in implies accepting the path-scope risk.
+ *
+ * SCF 6.8.4 introduced `wp scf json export|import` (and `wp acf json …`
+ * aliases). `export` takes `--dir=<directory>` (flag, like `wp export`);
+ * `import` takes a positional `<file>` path (like the legacy `acf import`).
  */
 const FS_SENSITIVE_COMMANDS = [
     'export',
     'acf export',
     'acf import',
+    'scf json export',
+    'scf json import',
+    'acf json export',
+    'acf json import',
 ];
 /**
  * Resolve the effective safe filesystem root for this wp-cli instance.
@@ -70,12 +78,19 @@ export function ensureSafeFsRoot(safeRoot) {
 }
 /**
  * Identify which FS-sensitive command a parsed arg vector represents.
- * Returns the canonical prefix ("export", "acf export", "acf import") or
- * null if the args don't match a FS-sensitive command.
+ * Returns the canonical prefix ("export", "acf export", "scf json export"…)
+ * or null if the args don't match a FS-sensitive command.
+ *
+ * Checks 3-, 2-, then 1-word prefixes — longer matches win so that
+ * `scf json export` is identified as the SCF command (not bare `export`)
+ * even though both share the trailing word.
  */
 export function matchFsSensitiveCommand(args) {
     if (args.length === 0)
         return null;
+    const threeWord = args.slice(0, 3).join(' ');
+    if (FS_SENSITIVE_COMMANDS.includes(threeWord))
+        return threeWord;
     const twoWord = args.slice(0, 2).join(' ');
     if (FS_SENSITIVE_COMMANDS.includes(twoWord))
         return twoWord;
@@ -333,5 +348,52 @@ export function validateFilesystemFlags(args, safeRoot, opts = {}) {
         }
         return { allowed: true };
     }
+    if (cmd === 'scf json export' || cmd === 'acf json export') {
+        // SCF 6.8.4's `wp scf|acf json export` uses `--dir=<dir>` (or `--stdout`)
+        // for output destination — same flag shape as `wp export`. Reuse the same
+        // extractor; `--filename_format` is `wp export`-only and irrelevant here.
+        const { dir, stdout } = extractExportFlags(args);
+        if (stdout) {
+            // Writes JSON to stdout; no FS write to validate.
+            return { allowed: true };
+        }
+        if (!dir) {
+            // Let wp-cli surface its own "must specify --dir or --stdout" error
+            // rather than returning a redundant allowlist rejection.
+            return { allowed: true };
+        }
+        const rel = rejectIfRelative(dir, `${cmd} --dir`, safeRootCanonical);
+        if (rel)
+            return rel;
+        if (!isPathUnderSafeRoot(dir, safeRootCanonical)) {
+            return {
+                allowed: false,
+                reason: `${cmd} --dir="${dir}" resolves outside the safe filesystem root ` +
+                    `"${safeRootCanonical}". Use a path under the safe root, or set ` +
+                    `${UNSAFE_FS_ENV}=1 to disable validation.`,
+            };
+        }
+        return { allowed: true };
+    }
+    if (cmd === 'scf json import' || cmd === 'acf json import') {
+        // `wp scf|acf json import <file>` — positional file path at args[3]
+        // (after the 3-word command prefix). Same safe-root rules as `acf import`.
+        const userPath = extractPositionalAfterPrefix(args, 3);
+        if (!userPath) {
+            return { allowed: true };
+        }
+        const rel = rejectIfRelative(userPath, cmd, safeRootCanonical);
+        if (rel)
+            return rel;
+        if (!isPathUnderSafeRoot(userPath, safeRootCanonical)) {
+            return {
+                allowed: false,
+                reason: `${cmd} "${userPath}" resolves outside the safe filesystem root ` +
+                    `"${safeRootCanonical}". Use a path under the safe root, or set ` +
+                    `${UNSAFE_FS_ENV}=1 to disable validation.`,
+            };
+        }
+        return { allowed: true };
+    }
     return { allowed: true };
 }

package/dist/wp-cli.d.ts

@@ -15,15 +15,31 @@ interface WpCliConfig {
 }
 export declare function createWpCli(config: WpCliConfig): {
     /**
-     * Execute a WP-CLI command. Returns stdout on success.
-     * Commands are parsed into args and validated against an allowlist.
-     * Uses execFile (no shell) to prevent command injection.
+     * Execute a WP-CLI command from a string. Parsed via parseCommand
+     * (single/double-quote toggling, no escape support). Validated against
+     * the allowlist. Uses execFile (no shell) to prevent command injection.
+     *
+     * Prefer `runArgs` from typed wrappers — it skips parseCommand entirely
+     * so user-supplied values containing apostrophes/quotes flow through
+     * verbatim instead of being mis-split.
      */
     run(command: string): Promise<{
         success: boolean;
         output: string;
         error?: string;
     }>;
+    /**
+     * Execute a WP-CLI command from a pre-built argv array. Skips
+     * parseCommand so values containing whitespace, apostrophes, or
+     * quotes pass through unmodified. Same allowlist + FS-safe-root
+     * validation as `run`. Use this from typed wrappers that already
+     * have the args structured (no string concatenation needed).
+     */
+    runArgs(args: string[]): Promise<{
+        success: boolean;
+        output: string;
+        error?: string;
+    }>;
     /** Return the list of allowed commands and available extensions. */
     getAllowedCommands(): {
         allowed: string[];

package/dist/wp-cli.js

@@ -40,6 +40,20 @@ const DEFAULT_COMMANDS = [
     'acf import',
     'acf field-group list',
     'acf field-group get',
+    // SCF 6.8.4+ adds `wp scf json {status,sync,import,export}` (also aliased as
+    // `wp acf json …`). All four are dev-time schema ops — `status`/`sync` are
+    // diff/apply against on-disk JSON, `import` re-creates DB entries from JSON,
+    // `export` writes DB schema to JSON. Same tier semantics as the legacy `acf`
+    // entries above; FS-touching subcommands (export, import) are second-pass
+    // validated below.
+    'scf json status',
+    'scf json sync',
+    'scf json import',
+    'scf json export',
+    'acf json status',
+    'acf json sync',
+    'acf json import',
+    'acf json export',
     // Users (read-only)
     'user list',
     // Cache (non-destructive maintenance)
@@ -319,66 +333,91 @@ export function createWpCli(config) {
     const runOptions = customWpCliCmd
         ? { ...execOptions, env, cwd: config.wpPath }
         : { ...execOptions, env };
-    return {
-        /**
-         * Execute a WP-CLI command. Returns stdout on success.
-         * Commands are parsed into args and validated against an allowlist.
-         * Uses execFile (no shell) to prevent command injection.
-         */
-        async run(command) {
-            const args = parseCommand(command);
-            const check = isCommandAllowed(args);
-            if (!check.allowed) {
-                return { success: false, output: '', error: check.reason };
+    // Internal argv-based runner — used by both `run(string)` (after
+    // parseCommand) and `runArgs(string[])` (skip parseCommand). Typed
+    // wrappers should call runArgs to bypass parseCommand's quote-toggling
+    // weakness: when a value contains an apostrophe (e.g. label "Bob's
+    // Group", file path /tmp/it's-fine.json), parseCommand mis-splits the
+    // argv because it treats the embedded `'` as a quote toggle. Passing
+    // pre-built argv eliminates the parsing step entirely so user-provided
+    // strings flow through verbatim — execFile (no shell) handles them
+    // correctly. Raised in PR #473 review (Copilot/Gemini both flagged).
+    const runArgv = async (args) => {
+        const check = isCommandAllowed(args);
+        if (!check.allowed) {
+            return { success: false, output: '', error: check.reason };
+        }
+        // Second-pass FS validation for commands whose flags/args can read/write
+        // arbitrary paths. Scoped to DEFAULT-tier FS commands only — EXTENDED
+        // (`import`, `eval-file`) are opt-in via DIVIOPS_WP_CLI_ALLOW, so opting
+        // in signals the caller accepts path-scope risk. Skip entirely when the
+        // user explicitly disables via DIVIOPS_WP_CLI_UNSAFE_FS=1.
+        //
+        // Wrapper mode (WP_CLI_CMD set) is gated separately inside
+        // validateFilesystemFlags — host-derived safe roots don't correspond to
+        // the wrapper's filesystem namespace, so the validator requires an
+        // explicit DIVIOPS_WP_CLI_SAFE_FS_ROOT there. We also skip the host-side
+        // mkdir in wrapper mode since the safe root is either container-scoped
+        // (user-managed) or unset (validator rejects).
+        if (!fsValidationDisabled() && matchFsSensitiveCommand(args)) {
+            const safeRoot = resolveSafeFsRoot(config.wpPath);
+            if (!customWpCliCmd) {
+                ensureSafeFsRoot(safeRoot);
             }
-            // Second-pass FS validation for commands whose flags/args can read/write
-            // arbitrary paths. Scoped to DEFAULT-tier FS commands only — EXTENDED
-            // (`import`, `eval-file`) are opt-in via DIVIOPS_WP_CLI_ALLOW, so opting
-            // in signals the caller accepts path-scope risk. Skip entirely when the
-            // user explicitly disables via DIVIOPS_WP_CLI_UNSAFE_FS=1.
-            //
-            // Wrapper mode (WP_CLI_CMD set) is gated separately inside
-            // validateFilesystemFlags — host-derived safe roots don't correspond to
-            // the wrapper's filesystem namespace, so the validator requires an
-            // explicit DIVIOPS_WP_CLI_SAFE_FS_ROOT there. We also skip the host-side
-            // mkdir in wrapper mode since the safe root is either container-scoped
-            // (user-managed) or unset (validator rejects).
-            if (!fsValidationDisabled() && matchFsSensitiveCommand(args)) {
-                const safeRoot = resolveSafeFsRoot(config.wpPath);
-                if (!customWpCliCmd) {
-                    ensureSafeFsRoot(safeRoot);
+            const fsCheck = validateFilesystemFlags(args, safeRoot, {
+                isWrapper: !!customWpCliCmd,
+            });
+            if (!fsCheck.allowed) {
+                return { success: false, output: '', error: fsCheck.reason };
+            }
+        }
+        const fullArgs = customWpCliCmd
+            ? [...prefixArgs, ...args, '--no-color']
+            : [...args, `--path=${config.wpPath}`, '--no-color'];
+        return new Promise((resolve) => {
+            execFile(executable, fullArgs, runOptions, (error, stdout, stderr) => {
+                // Filter PHP deprecation warnings from output
+                const output = (stdout + '\n' + stderr)
+                    .split('\n')
+                    .filter((line) => !line.includes('Deprecated:') && !line.includes('PHP Deprecated'))
+                    .join('\n')
+                    .trim();
+                if (error) {
+                    const detail = error.killed
+                        ? 'Command timed out'
+                        : error.signal
+                            ? `Killed by signal ${error.signal}`
+                            : `Exit code ${error.code ?? 'unknown'}`;
+                    resolve({ success: false, output, error: detail });
                 }
-                const fsCheck = validateFilesystemFlags(args, safeRoot, {
-                    isWrapper: !!customWpCliCmd,
-                });
-                if (!fsCheck.allowed) {
-                    return { success: false, output: '', error: fsCheck.reason };
+                else {
+                    resolve({ success: true, output });
                 }
-            }
-            const fullArgs = customWpCliCmd
-                ? [...prefixArgs, ...args, '--no-color']
-                : [...args, `--path=${config.wpPath}`, '--no-color'];
-            return new Promise((resolve) => {
-                execFile(executable, fullArgs, runOptions, (error, stdout, stderr) => {
-                    // Filter PHP deprecation warnings from output
-                    const output = (stdout + '\n' + stderr)
-                        .split('\n')
-                        .filter((line) => !line.includes('Deprecated:') && !line.includes('PHP Deprecated'))
-                        .join('\n')
-                        .trim();
-                    if (error) {
-                        const detail = error.killed
-                            ? 'Command timed out'
-                            : error.signal
-                                ? `Killed by signal ${error.signal}`
-                                : `Exit code ${error.code ?? 'unknown'}`;
-                        resolve({ success: false, output, error: detail });
-                    }
-                    else {
-                        resolve({ success: true, output });
-                    }
-                });
             });
+        });
+    };
+    return {
+        /**
+         * Execute a WP-CLI command from a string. Parsed via parseCommand
+         * (single/double-quote toggling, no escape support). Validated against
+         * the allowlist. Uses execFile (no shell) to prevent command injection.
+         *
+         * Prefer `runArgs` from typed wrappers — it skips parseCommand entirely
+         * so user-supplied values containing apostrophes/quotes flow through
+         * verbatim instead of being mis-split.
+         */
+        async run(command) {
+            return runArgv(parseCommand(command));
+        },
+        /**
+         * Execute a WP-CLI command from a pre-built argv array. Skips
+         * parseCommand so values containing whitespace, apostrophes, or
+         * quotes pass through unmodified. Same allowlist + FS-safe-root
+         * validation as `run`. Use this from typed wrappers that already
+         * have the args structured (no string concatenation needed).
+         */
+        async runArgs(args) {
+            return runArgv(args);
         },
         /** Return the list of allowed commands and available extensions. */
         getAllowedCommands() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diviops/mcp-server",
-  "version": "0.2.23",
+  "version": "0.2.29",
   "description": "MCP server exposing Divi 5 Visual Builder as tools for Claude",
   "type": "module",
   "main": "dist/index.js",