@diviops/mcp-server 0.2.28 → 1.0.0

package/README.md

@@ -41,7 +41,7 @@ claude mcp add diviops-mcp \
 
 > **Use `--env` flags, not the `env` command.** Claude Code's native `--env KEY=VALUE` flags survive copy-paste; the older `-- env KEY=VALUE` form (piping through unix `env`) breaks silently when any value contains a space. Quote any value with spaces (e.g. `--env "WP_PATH=/Users/you/Local Sites/site/app/public"`) — no backslash escaping needed inside quotes.
 
-**With WP-CLI** (optional — enables `diviops_wp_cli` tool):
+**With WP-CLI** (optional — enables `diviops_meta_wp_cli` tool):
 ```bash
 claude mcp add diviops-mcp \
   --env WP_URL=http://your-site.local \
@@ -96,80 +96,86 @@ 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 |
-| `diviops_server_info` | DiviOps server identity, version, license type, capabilities |
-| `diviops_list_pages` | List pages/posts with Divi status |
-| `diviops_get_page` | Get page details and raw content |
-| `diviops_get_page_layout` | Get parsed block tree (layout structure) |
-| `diviops_get_section` | Get a single section's markup by admin label |
-| `diviops_list_modules` | List all available Divi modules |
-| `diviops_get_module_schema` | Get attribute schema for a module (optimized by default, `raw: true` for full) |
-| `diviops_get_settings` | Get Divi site settings and theme options |
-| `diviops_get_global_colors` | Get global color palette |
-| `diviops_get_global_fonts` | Get global font definitions |
-| `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_meta_ping` | Test WordPress connection and Divi version |
+| `diviops_meta_info` | DiviOps server identity, version, license type, capabilities |
+| `diviops_page_list` | List pages/posts with Divi status |
+| `diviops_page_get` | Get page details and raw content |
+| `diviops_page_get_layout` | Get parsed block tree (layout structure) |
+| `diviops_section_get` | Get a single section's markup by admin label |
+| `diviops_schema_list_modules` | List all available Divi modules |
+| `diviops_schema_get_module` | Get attribute schema for a module (optimized by default, `raw: true` for full) |
+| `diviops_schema_get_settings` | Get Divi site settings and theme options |
+| `diviops_global_color_list` | Get global color palette |
+| `diviops_global_font_list` | Get global font definitions |
+| `diviops_meta_find_icon` | Search 1,989 icons by keyword (FA + Divi) |
+| `diviops_template_list` | List available MCP prompt templates |
+| `diviops_template_get` | 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`. 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 |
+| `diviops_library_list` | List saved Divi Library items |
+| `diviops_library_get` | Get a library item's block markup |
 | `diviops_render_preview` | Render block markup to HTML for preview |
 | `diviops_validate_blocks` | Validate block markup (structure, required attrs, known pitfalls) |
-| `diviops_list_tb_templates` | List Theme Builder templates with conditions and layout IDs |
-| `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 |
-
-### Write (28)
+| `diviops_tb_template_list` | List Theme Builder templates with conditions and layout IDs |
+| `diviops_tb_layout_get` | Get a Theme Builder layout's block markup (header/body/footer) |
+| `diviops_variable_list` | List design token variables (filter by type or prefix) |
+| `diviops_variable_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_variable_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_canvas_list` | List all canvas pages |
+| `diviops_canvas_get` | 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_field_group_list` | 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_field_group_get` | 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 (31)
 | Tool | Description |
 |------|-------------|
-| `diviops_create_page` | Create a new page with optional Divi content |
-| `diviops_update_page_content` | Full page content rewrite |
-| `diviops_append_section` | Append a section to existing page (start or end) |
-| `diviops_replace_section` | Replace a section by admin label |
-| `diviops_remove_section` | Remove a section by admin label |
-| `diviops_update_module` | Update specific module attributes by label or text match |
-| `diviops_move_module` | Move a block before/after another block (reorder modules, sections) |
-| `diviops_lock_module` | Lock a module so VB users cannot edit it (frontend renders normally) |
-| `diviops_unlock_module` | Unlock a module by removing `attrs.locked` (matches VB's absence convention) |
-| `diviops_clone_module` | Deep-copy a module + insert next to source within the same parent |
-| `diviops_add_global_color` | Add a new global color to Divi's palette (writes canonical shape; closes ET's bundle Zod gap that drops `label`) |
-| `diviops_update_global_color` | Update an existing global color by gcid (only provided fields change) |
-| `diviops_delete_global_color` | Delete a global color (refuses if `usedInPosts` non-empty unless `force=true`; customizer-bound defaults always protected) |
+| `diviops_page_create` | Create a new page with optional Divi content |
+| `diviops_page_update_content` | Full page content rewrite |
+| `diviops_section_append` | Append a section to existing page (start or end) |
+| `diviops_section_replace` | Replace a section by admin label |
+| `diviops_section_remove` | Remove a section by admin label |
+| `diviops_module_update` | Update specific module attributes by label or text match |
+| `diviops_module_move` | Move a block before/after another block (reorder modules, sections) |
+| `diviops_module_lock` | Lock a module so VB users cannot edit it (frontend renders normally) |
+| `diviops_module_unlock` | Unlock a module by removing `attrs.locked` (matches VB's absence convention) |
+| `diviops_module_clone` | Deep-copy a module + insert next to source within the same parent |
+| `diviops_global_color_create` | Add a new global color to Divi's palette (writes canonical shape; closes ET's bundle Zod gap that drops `label`) |
+| `diviops_global_color_update` | Update an existing global color by gcid (only provided fields change) |
+| `diviops_global_color_delete` | Delete a global color (refuses if `usedInPosts` non-empty unless `force=true`; customizer-bound defaults always protected) |
 | `diviops_preset_cleanup` | Remove spam/duplicate presets, bulk rename |
 | `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. 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_library_save` | Save block markup to Divi Library |
+| `diviops_tb_layout_update` | Update a Theme Builder layout's block markup |
+| `diviops_tb_template_create` | Create Theme Builder template with header/footer and conditions |
+| `diviops_variable_create` | 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_variable_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_variable_create`'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_variable_delete` | Delete a variable by ID. Returns HTTP 409 when live references exist unless `force=true` (use `diviops_variable_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_canvas_create` | Create a canvas page |
+| `diviops_canvas_update` | Update canvas content |
+| `diviops_canvas_delete` | 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 |
 |------|-------------|
-| `diviops_wp_cli` | Run WP-CLI commands (allowlisted, requires `WP_PATH` or `WP_CLI_CMD`) |
-| `diviops_flush_static_cache` | Flush Divi's compiled CSS cache under `wp-content/et-cache/`. `wp cache flush` does NOT touch these files — the frontend can keep serving stale CSS after mutations. Delegates to Divi's native clearer (`ET_Core_PageResource::remove_static_resources`) when available — also clears Theme Builder / archive / taxonomy / home / notfound CSS, object cache, module features cache, post features cache, dynamic assets cache, Google Fonts cache, post meta caches. Falls back to a filesystem walk of numeric-named subdirs when Divi is inactive. Response includes `backend: "divi_native"` or `"fs_fallback"`. Exactly one selector required: `post_id`, `all`, or `after` (unix ts) — no default to `all` |
+| `diviops_meta_wp_cli` | Run WP-CLI commands (allowlisted, requires `WP_PATH` or `WP_CLI_CMD`) |
+| `diviops_meta_flush_cache` | Flush Divi's compiled CSS cache under `wp-content/et-cache/`. `wp cache flush` does NOT touch these files — the frontend can keep serving stale CSS after mutations. Delegates to Divi's native clearer (`ET_Core_PageResource::remove_static_resources`) when available — also clears Theme Builder / archive / taxonomy / home / notfound CSS, object cache, module features cache, post features cache, dynamic assets cache, Google Fonts cache, post meta caches. Falls back to a filesystem walk of numeric-named subdirs when Divi is inactive. Response includes `backend: "divi_native"` or `"fs_fallback"`. Exactly one selector required: `post_id`, `all`, or `after` (unix ts) — no default to `all` |
 
 ## WP-CLI Security
 
-The `diviops_wp_cli` tool validates every command against a safety allowlist before execution. Commands not on the list are rejected.
+The `diviops_meta_wp_cli` tool validates every command against a safety allowlist before execution. Commands not on the list are rejected.
 
 ### Default allowlist (always available)
 
@@ -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.
 
@@ -250,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_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_page_update_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)
 
@@ -265,7 +272,7 @@ Tool refuses the operation with an explanatory error when a safety check fails;
 **Current tools:**
 | Tool | Guard | Override |
 |------|-------|----------|
-| `diviops_delete_variable` | HTTP 409 when live references exist | `force=true` |
+| `diviops_variable_delete` | 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)
@@ -308,7 +315,7 @@ After setup, Claude can:
 Ensure `WP_URL`, `WP_USER`, and `WP_APP_PASSWORD` are all set. Check your `claude mcp add` command.
 
 ### "Connection failed" error
-- Verify the WP plugin is active: visit `{WP_URL}/wp-json/diviops/v1/settings` in your browser
+- Verify the WP plugin is active: visit `{WP_URL}/wp-json/diviops/v1/schema/settings` in your browser
 - Check Application Password is correct (try with curl first)
 
 ### "Version mismatch" error
@@ -320,7 +327,7 @@ The MCP server and WP plugin versions are incompatible. Update whichever side is
 
 ### Testing manually
 ```bash
-curl -u "username:apppassword" http://site.local/wp-json/diviops/v1/settings
+curl -u "username:apppassword" http://site.local/wp-json/diviops/v1/schema/settings
 ```
 
 ### Preset edits not visible on the frontend

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";
 /**
  * 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';
 /**
  * Compare two semver-like version strings (supports pre-release tags).
  *