@diviops/mcp-server 0.2.19 → 0.2.21

package/README.md

@@ -32,31 +32,33 @@ Go to **WP Admin -> Users -> Your Profile -> Application Passwords**:
 ### 3. Configure Claude Code
 
 ```bash
-claude mcp add diviops-mcp -- env \
-  WP_URL=http://your-site.local \
-  WP_USER=your-wp-username \
-  WP_APP_PASSWORD=xxxxXXXXxxxxXXXXxxxxXXXX \
-  npx @diviops/mcp-server
+claude mcp add diviops-mcp \
+  --env WP_URL=http://your-site.local \
+  --env WP_USER=your-wp-username \
+  --env WP_APP_PASSWORD=xxxxXXXXxxxxXXXXxxxxXXXX \
+  -- npx @diviops/mcp-server
 ```
 
+> **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):
 ```bash
-claude mcp add diviops-mcp -- env \
-  WP_URL=http://your-site.local \
-  WP_USER=your-wp-username \
-  WP_APP_PASSWORD=xxxxXXXXxxxxXXXXxxxxXXXX \
-  WP_PATH="/path/to/wordpress" \
-  npx @diviops/mcp-server
+claude mcp add diviops-mcp \
+  --env WP_URL=http://your-site.local \
+  --env WP_USER=your-wp-username \
+  --env WP_APP_PASSWORD=xxxxXXXXxxxxXXXXxxxxXXXX \
+  --env "WP_PATH=/path/to/wordpress" \
+  -- npx @diviops/mcp-server
 ```
 
 **With Docker-based WP-CLI** (optional — uses a custom command prefix):
 ```bash
-claude mcp add diviops-mcp -- env \
-  WP_URL=https://site-name.ddev.site \
-  WP_USER=your-wp-username \
-  WP_APP_PASSWORD=xxxxXXXXxxxxXXXXxxxxXXXX \
-  WP_CLI_CMD="ddev wp" \
-  npx @diviops/mcp-server
+claude mcp add diviops-mcp \
+  --env WP_URL=https://site-name.ddev.site \
+  --env WP_USER=your-wp-username \
+  --env WP_APP_PASSWORD=xxxxXXXXxxxxXXXXxxxxXXXX \
+  --env "WP_CLI_CMD=ddev wp" \
+  -- npx @diviops/mcp-server
 ```
 
 ### Environment Variables
@@ -186,6 +188,7 @@ These commands carry higher risk and require explicit opt-in via the `DIVIOPS_WP
 | Command | Risk | Why opt-in |
 |---------|------|------------|
 | `option update` | High | Can change site URL, admin email, or security settings |
+| `option delete` | High | Permanently removes a WP option (no undo) |
 | `post delete` | Medium | Permanently removes content |
 | `post meta delete` | Medium | Removes metadata |
 | `term delete` | Medium | Permanently removes taxonomy terms |
@@ -198,17 +201,29 @@ These commands carry higher risk and require explicit opt-in via the `DIVIOPS_WP
 To enable extended commands, add `DIVIOPS_WP_CLI_ALLOW` to your MCP registration:
 
 ```bash
-claude mcp add diviops-mcp -- env \
-  WP_URL=http://your-site.local \
-  WP_USER=admin \
-  WP_APP_PASSWORD=xxxx \
-  WP_PATH="/path/to/wordpress" \
-  DIVIOPS_WP_CLI_ALLOW="option update,post delete,search-replace" \
-  npx @diviops/mcp-server
+claude mcp add diviops-mcp \
+  --env WP_URL=http://your-site.local \
+  --env WP_USER=admin \
+  --env WP_APP_PASSWORD=xxxx \
+  --env "WP_PATH=/path/to/wordpress" \
+  --env "DIVIOPS_WP_CLI_ALLOW=option update,post delete,search-replace" \
+  -- npx @diviops/mcp-server
 ```
 
 Only list the specific commands you need. Unknown entries are ignored with a warning.
 
+#### Wildcard / "god-mode" (local dev only)
+
+For trusted local-dev environments where you don't want to re-list every extended command per site, the values `*` and `all` grant the full extended set:
+
+```bash
+--env "DIVIOPS_WP_CLI_ALLOW=*"
+```
+
+The sentinel grants exactly the extended set above — it does NOT unlock anything beyond it (notably: `db query` stays out by design). The server emits a startup warning to stderr whenever the wildcard is active, so the broad grant is never silent. Auto-adopts new extended commands on future versions.
+
+> **Don't use this in shared or production environments.** Pin the specific commands you need with the comma-separated form instead.
+
 > **Note on `acf import`**: included in the default allowlist because it's an idempotent dev-time schema operation (re-creates field groups from JSON). Bulk content imports use `wp import` instead, which is opt-in.
 
 ### Filesystem flag validation

package/dist/wp-cli.js

@@ -90,6 +90,7 @@ const DEFAULT_COMMANDS = [
  */
 const EXTENDED_COMMANDS = [
     'option update', // Can change site URL, admin email, active plugins
+    'option delete', // Destructive — permanently removes a WP option
     'post delete', // Destructive — permanently removes content
     'post meta delete', // Destructive — removes metadata
     'term delete', // Destructive — removes taxonomy terms
@@ -104,6 +105,14 @@ function buildAllowlist() {
     const extra = process.env.DIVIOPS_WP_CLI_ALLOW?.trim();
     if (!extra)
         return DEFAULT_COMMANDS;
+    // Wildcard sentinel — convenience for trusted local-dev environments. Grants
+    // every entry in EXTENDED_COMMANDS but does NOT unlock anything beyond it
+    // (notably: `db query` stays out — see #361 Chunk B). Always emits a startup
+    // warning so the broad grant is never silent.
+    if (extra === '*' || extra === 'all') {
+        console.warn(`[diviops] DIVIOPS_WP_CLI_ALLOW="${extra}" — granting ALL ${EXTENDED_COMMANDS.length} extended commands. Intended for trusted local-dev only.`);
+        return [...DEFAULT_COMMANDS, ...EXTENDED_COMMANDS];
+    }
     const requested = extra.split(',').map((s) => s.trim()).filter(Boolean);
     const granted = new Set(DEFAULT_COMMANDS);
     for (const cmd of requested) {

package/dist/wp-client.js

@@ -6,43 +6,88 @@
  */
 import { MIN_PLUGIN_VERSION, compareVersions, } from './compatibility.js';
 /**
- * Normalize over-escaped variable-token quote sequences inside `$variable(...)$`
- * token regions only.
+ * Normalize quote-escape pathologies inside `$variable(...)$` token regions only.
  *
- * Divi block-attrs JSON uses `\"` (2-byte) for inner quotes inside Divi variable
- * tokens. Two over-escaped forms can leak in via callers that round-trip
- * pre-existing broken bytes:
- *   - `\u0022` (11 bytes literal) — the mass-corruption form (backslash
- *     itself unicode-escaped, observed in the wild on Divi 5.3.x sites)
- *   - `\\u0022`     (7 bytes literal) — produced when a caller passes the
- *     6-byte `"` form through an extra JSON-encoding layer
+ * Divi block-attrs JSON uses `\"` (2-byte: backslash + quote) for inner quotes
+ * inside variable token payloads. Three pathological forms can leak in through
+ * callers and silently break the WP block parser at write time.
  *
- * Both decode to the same value after Divi's resolver, but cause render asymmetry
- * across attr paths (`background.color`, `spacing.margin`, `border.color`,
- * `layout.columnGap` silently fail to resolve). We normalize defensively so any
- * write — clean or pre-broken — settles on canonical bytes.
+ * Over-escape (existing #395/#396 fix). Two forms produced when callers
+ * round-trip pre-existing broken bytes:
+ *   - `\u005cu0022` (11 bytes literal) — the
+ *     mass-corruption form (backslash itself unicode-escaped, observed in the
+ *     wild on Divi 5.3.x sites)
+ *   - `\\u0022`     (7 bytes literal: 2 backslashes + `u0022`) — produced when
+ *     a caller passes the 6-byte unicode-escape form through an extra
+ *     JSON-encoding layer
+ *   These cause render-only failure: the resolver can't decode the token, and
+ *   attr paths like `background.color`, `spacing.margin`, `border.color`,
+ *   `layout.columnGap` silently fall through to defaults (or leak literal
+ *   `0022` into emitted CSS).
+ *
+ * Under-escape (#409 fix). One form produced when an agent transcribes
+ * `get_section` markup (which emits inner quotes as `"` HTML entities) and
+ * a layer in the agent → MCP → WP pipeline strips one level of escaping:
+ *   - bare `"` (1 byte) — the inner quote loses its `\` prefix and prematurely
+ *     terminates the OUTER block-attrs string at parse time. The WP block
+ *     parser then silently drops ALL attrs from the affected module. Section
+ *     appears to save (`success: true`) but renders empty / broken.
+ *
+ * We normalize defensively so any write — clean, pre-broken, or
+ * agent-transcribed — settles on canonical 2-byte `\"`.
+ *
+ * Order matters: collapse over-escapes first, then escape under-escapes. The
+ * negative lookbehind on the under-escape rule skips `\"` produced by the
+ * over-escape pass (and any already-canonical input). Idempotent.
  *
  * Scope is intentionally narrow: rewrites only happen inside `$variable(...)$`
  * regions (Divi's actual resolver boundary). Bytes outside those regions —
  * arbitrary user text, code samples, string-variable values that happen to
- * contain `\u0022` — are left untouched.
+ * contain `\u005cu0022`, `\\u0022`, or bare `"` — are left untouched.
  */
 function normalizeQuoteEscapes(s) {
-    return s.replace(/\$variable\([^$]*?\)\$/g, (token) => token.replace(/(?:\\u005cu0022|\\\\u0022)/g, '\\"'));
+    return s.replace(/\$variable\([^$]*?\)\$/g, (token) => {
+        // Pass 1: collapse over-escaped forms (#395/#396) to canonical \"
+        let normalized = token.replace(/(?:\\u005cu0022|\\\\u0022)/g, '\\"');
+        // Pass 2: escape any bare " (#409) to canonical \" — negative lookbehind
+        // skips properly-escaped quotes produced by Pass 1 or already canonical.
+        normalized = normalized.replace(/(?<!\\)"/g, '\\"');
+        return normalized;
+    });
 }
-function normalizeBody(value) {
-    if (typeof value === 'string')
-        return normalizeQuoteEscapes(value);
+/**
+ * Body keys whose values (and descendants) carry Divi block markup or block
+ * attribute trees, where `$variable(...)$` token-region normalization is the
+ * intended behavior. Strings reachable only through other top-level keys
+ * — variable values, labels, match-text predicates, descriptions, etc.
+ * — are passed through verbatim so a literal `$variable({"x":"y"})$`
+ * docs example in a `string_variable_value` is preserved (#409 review:
+ * Codex-flagged regression — without this scoping, the bare-quote pass would
+ * silently rewrite literal token-shaped substrings in user-prose fields).
+ */
+const BLOCK_CONTENT_KEYS = new Set([
+    'content', // update_page_content, render_preview, validate_blocks,
+    // append_section, replace_section, update_tb_layout,
+    // save_to_library, create_page
+    'attrs', // update_module — attr values embedded in block JSON
+    'header_content', // create_tb_template
+    'footer_content', // create_tb_template
+]);
+function normalizeBody(value, withinBlockTree = false) {
+    if (typeof value === 'string') {
+        return withinBlockTree ? normalizeQuoteEscapes(value) : value;
+    }
     if (Array.isArray(value))
-        return value.map(normalizeBody);
+        return value.map((v) => normalizeBody(v, withinBlockTree));
     // Restrict recursion to plain objects so Date / RegExp / class instances
     // with custom `toJSON` keep their canonical serialization.
     if (value &&
         typeof value === 'object' &&
         Object.getPrototypeOf(value) === Object.prototype) {
         const out = {};
-        for (const [k, v] of Object.entries(value))
-            out[k] = normalizeBody(v);
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = normalizeBody(v, withinBlockTree || BLOCK_CONTENT_KEYS.has(k));
+        }
         return out;
     }
     return value;

package/package.json

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