@diviops/mcp-server 0.2.28 → 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 (57)
+## Available Tools (63)
 
-### Read (27)
+### Read (30)
 | Tool | Description |
 |------|-------------|
 | `diviops_test_connection` | Test WordPress connection and Divi version |
@@ -128,8 +128,11 @@ The server connects via standard WordPress REST API and works with any environme
 | `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 (28)
+### Write (31)
 | Tool | Description |
 |------|-------------|
 | `diviops_create_page` | Create a new page with optional Divi content |
@@ -160,6 +163,9 @@ The server connects via standard WordPress REST API and works with any environme
 | `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 |
@@ -182,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) |
@@ -237,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.
 

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.43";
+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.43';
+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
@@ -1322,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()
@@ -1345,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.",

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.28",
+  "version": "0.2.29",
   "description": "MCP server exposing Divi 5 Visual Builder as tools for Claude",
   "type": "module",
   "main": "dist/index.js",