@diviops/mcp-server 0.2.6 → 0.2.8

package/README.md

@@ -141,7 +141,7 @@ The server connects via standard WordPress REST API and works with any environme
 | `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 |
+| `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. Px inputs only in this MVP; rem inputs should be converted to px (1rem=16px) before calling |
 | `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 |
@@ -208,6 +208,49 @@ Only list the specific commands you need. Unknown entries are ignored with a war
 
 > **Known limitation — filesystem access**: Validation is prefix-based, not flag-aware. Commands that read from or write to the filesystem (`acf export`/`acf import`, `export`, opt-in `import`/`eval-file`) can target any path reachable by the WP-CLI user. For shared or multi-tenant environments, consider wrapping the MCP server with a stricter proxy or running it under an account with limited filesystem permissions. Flag-level validation is a candidate future enhancement.
 
+## 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.
+
+### Pattern A — `force: false/true` (refuse-with-override)
+
+Tool refuses the operation with an explanatory error when a safety check fails; caller reviews the reason and retries with `force=true` to commit. Single round-trip on the happy path, single retry on the override path.
+
+**Fit criteria:**
+- Operation targets a **single item** (one variable, one preset, one page)
+- Safety check is **binary** (safe / not safe)
+- The reason for blocking is compact enough to fit in the error body (e.g., "3 live references")
+- The caller can decide from the error alone — no full diff needed
+
+**Current tools:**
+| Tool | Guard | Override |
+|------|-------|----------|
+| `diviops_delete_variable` | HTTP 409 when live references exist | `force=true` |
+
+### Pattern B — `mode: "dry-run"/"apply"` (preview-then-commit)
+
+Tool returns a preview of the changes it would make; caller reviews the diff, then re-invokes with the apply flag to commit. Two round-trips by design — the preview itself is the value.
+
+**Fit criteria:**
+- Operation touches **many items** (bulk reassign, bulk cleanup)
+- The *preview is the value* — caller wants the full list of changes before committing
+- Side effects don't fit in a one-line reason (e.g., "142 preset refs across 18 pages rewritten from UUID X to UUID Y")
+- Two round-trips are acceptable because the caller is already in review mode
+
+**Current tools:**
+| Tool | Preview flag | Commit flag |
+|------|--------------|-------------|
+| `diviops_preset_reassign` | `mode: "dry-run"` (default) | `mode: "apply"` |
+| `diviops_preset_cleanup` | `dry_run: true` (default) | `dry_run: false` |
+
+> Both preview-then-commit tools share the same semantic pattern but use different parameter shapes (`mode` enum vs `dry_run` bool). Both predate this convention and stay as-is for caller compatibility. **New bulk tools should use the enum form** (`mode: "dry-run" | "apply"`) — it's more extensible if future modes are needed (`"interactive"`, `"selective"`, etc.) and keeps the interface consistent as the tool set grows.
+
+### Picking a pattern for a new tool
+
+Ask: **single item or many?** If single, Pattern A. If many, Pattern B.
+
+Don't introduce a third pattern (`confirmation_token`, session-based preview, etc.) unless a tool has a genuine need that neither A nor B covers — both patterns above are stateless and flexible enough for most cases.
+
 ## Example Usage
 
 After setup, Claude can:

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.22";
+export declare const MIN_PLUGIN_VERSION = "1.0.0-beta.28";
 /**
  * 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.22';
+export const MIN_PLUGIN_VERSION = '1.0.0-beta.28';
 /**
  * Compare two semver-like version strings (supports pre-release tags).
  *

package/dist/index.js

@@ -1285,7 +1285,7 @@ server.registerTool("diviops_list_variables", {
     };
 });
 server.registerTool("diviops_create_variable", {
-    description: 'Create a design token variable in the Divi Variable Manager. Colors (type "colors") use gcid-* IDs and hex values. Numbers/strings/etc use gvid-* IDs.',
+    description: 'Create a design token variable in the Divi Variable Manager. Colors (type "colors") use gcid-* IDs and hex values. Numbers/strings/etc use gvid-* IDs. For type="numbers" fluid tokens, pass min+max shorthand (anchors default to 320px/1920px) or explicit targets — server generates arithmetically-correct clamp() formulas. Px inputs only in this MVP; rem inputs must be converted to px (1rem=16px) before calling. Mutually exclusive with value.',
     inputSchema: {
         type: z
             .enum(["colors", "numbers", "strings", "images", "links", "fonts"])
@@ -1299,12 +1299,36 @@ server.registerTool("diviops_create_variable", {
             .describe("Human-readable label shown in the VB Variable Manager"),
         value: z
             .string()
-            .describe('Variable value: hex color for colors (e.g. "#3a7a6a"), CSS value for numbers (e.g. "clamp(30px, 8vw, 100px)")'),
+            .optional()
+            .describe('Variable value (required unless using fluid min/max/targets for type=numbers): hex color for colors (e.g. "#3a7a6a"), CSS value for numbers (e.g. "clamp(30px, 8vw, 100px)" or "2rem")'),
+        min: z
+            .string()
+            .optional()
+            .describe('Fluid minimum value in px (e.g. "20px"). Paired with max. Anchors default to 320px/1920px. type="numbers" only. Rem not supported — convert to px (1rem=16px) before calling.'),
+        max: z
+            .string()
+            .optional()
+            .describe('Fluid maximum value in px (e.g. "60px"). Paired with min.'),
+        targets: z
+            .record(z.string(), z.string())
+            .refine((m) => !m || Object.keys(m).length === 2, {
+            message: "targets must contain exactly 2 viewport entries",
+        })
+            .optional()
+            .describe('Explicit two-anchor fluid spec, px only. Example: {"320px":"20px","1920px":"60px"} → clamp(20px, 12px + 2.5vw, 60px). Exactly 2 entries required. type="numbers" only. Mutually exclusive with min/max.'),
     },
-}, async ({ type, id, label, value }) => {
-    const body = { type, label, value };
+}, async ({ type, id, label, value, min, max, targets }) => {
+    const body = { type, label };
+    if (value !== undefined)
+        body.value = value;
     if (id)
         body.id = id;
+    if (min !== undefined)
+        body.min = min;
+    if (max !== undefined)
+        body.max = max;
+    if (targets !== undefined)
+        body.targets = targets;
     const result = await wp.request("/variable/create", {
         method: "POST",
         body,
@@ -1367,7 +1391,7 @@ server.registerTool("diviops_flush_static_cache", {
             .int()
             .positive()
             .optional()
-            .describe("Unix timestamp — iterate numeric subdirs with mtime greater than this value, flushing each. Useful for flushing entries touched since a known deployment or mutation batch. Native clearer runs once per matched post."),
+            .describe("Unix timestamp — flush Divi CSS files (et-*.css) with mtime strictly greater than this value. Useful for flushing entries touched since a known deployment or mutation batch. Native backend does a single-pass filesystem sweep covering numeric post dirs AND archive/taxonomy/home/notfound/global subtrees in one walk (Visual Builder -vb-* runtime CSS preserved); fs_fallback iterates numeric post dirs whose latest file mtime > after. `flushed` lists numeric post_ids whose files were actually deleted; `skipped` lists numeric post_ids that exist but had no files pass the filter."),
     },
 }, async ({ post_id, all, after }) => {
     const body = {};

package/package.json

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