@diviops/mcp-server 1.5.7 → 1.5.9

package/README.md

@@ -1,8 +1,8 @@
 # DiviOps MCP Server
 
-**AI-driven WordPress site authoring — Divi-native, with the rest of WP in scope.**
+**An AI harness for WordPress site authoring — Divi-native today, WordPress-wide by design.**
 
-Programmatic site authoring through Claude Code, Claude Desktop, and any other MCP client. Built on Divi 5 as the page authoring foundation, the suite also handles WordPress data models — custom post types, Secure Custom Fields, taxonomies, site audits, and hybrid sites where Divi authors the marketing pages and custom PHP templates handle the dynamic ones, with design tokens harmonized across both surfaces. Pairs with a WordPress companion plugin and ships alongside a Claude skill that knows the Divi 5 block format.
+The Node.js MCP server inside the DiviOps harness. It gives Claude Code, Claude Desktop, and other MCP clients a typed control layer over WordPress site state, dispatching to the DiviOps Agent plugin for Divi 5 page authoring, SCF and CPT data models, design tokens, presets, library and Theme Builder templates, site audits, and safe WP-CLI passthrough. Pairs with the `divi-5-builder` Claude skill so the agent applies Divi's block format and design rules correctly.
 
 ```
 Claude Code <-> MCP Server (stdio) <-> WordPress REST API <-> DiviOps Agent plugin
@@ -57,14 +57,14 @@ Claude orchestrates a few tool calls in sequence:
 1. `diviops_global_color_list` — discovers your brand palette.
 2. `diviops_template_list` / `diviops_template_get` — pulls a verified hero template that matches the request.
 3. `diviops_page_create` — creates `Spring Launch` as a draft with the hero block markup.
-4. `diviops_validate_blocks` — confirms the markup is well-formed before save.
-5. `diviops_render_preview` — returns the rendered HTML so you can verify before publishing.
+4. `diviops_validate_blocks` — confirms the markup is well-formed before save. Accepts inline `content` or a `page_id` to validate already-saved markup.
+5. `diviops_render_preview` — returns the rendered HTML so you can verify before publishing. Accepts inline `content` or a `page_id` to preview an existing page.
 
 The skill enforces the Divi block format, the design system, and the response contract throughout — you stay at the prompt level.
 
 ## Tools at a glance
 
-The server exposes **67 tools** across the categories below. Each category links to representative tools; the full table lives in [server-reference.md](../docs/server-reference.md).
+The server exposes **70 tools** across the categories below. Each category links to representative tools; the full table lives in [server-reference.md](../docs/server-reference.md).
 
 | Category | Use case | Tool prefixes |
 |----------|----------|---------------|

package/dist/index.js

@@ -443,7 +443,7 @@ registerPluginTool("diviops_global_color_delete", {
     return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_global_color_delete") }] };
 });
 registerPluginTool("diviops_global_font_list", {
-    description: "Get the global font definitions from Divi settings. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }.",
+    description: "List the DiviOps-managed global fonts registered under `et_global_data.global_fonts`. ALWAYS returns the normalized shape `{ count: number, fonts: { <gfid>: <record>, ... } }` — even on empty substrates (count:0, fonts:{}), never bare `false`. Distinct from the variable-manager font tokens (`gvid-*` under `et_global_data.global_variables.fonts`, surfaced via `diviops_variable_list({type:\"fonts\"})`) — `global_font_*` is the DiviOps-controlled font catalog presets bind to via canonical `gfid-` slugs. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }.",
     annotations: { idempotentHint: true },
     _meta: { idempotent: "true" },
 }, async () => {
@@ -454,6 +454,158 @@ registerPluginTool("diviops_global_font_list", {
         ],
     };
 });
+registerPluginTool("diviops_global_font_create", {
+    description: "Create a new global font in DiviOps's registry under `et_global_data.global_fonts`. Mints a fresh `gfid-<uuid>` if `id` is omitted; otherwise uses the supplied id (must match `gfid-[0-9a-z-]{1,80}`; auto-prefixes `gfid-` if missing). Strict create — collision on existing id returns `conflict` (HTTP 409) with `error.data = { id, existing }`; use diviops_global_font_update to modify an existing record. Stored shape: `{ family, source, weights[], subsets[], label, fallback, status, lastUpdated }`. Required: `family` (CSS family name, e.g. \"Sora\") + `source` (one of `google`/`system`/`custom`). Distinct from `diviops_variable_create({type:\"fonts\"})` which writes `gvid-*` font tokens to the variable manager — `global_font_*` is the DiviOps catalog presets bind via `gfid-` slugs. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; input-shape rejections (malformed id, invalid source enum, non-array weights/subsets, missing required `family`/`source` for a new entry) collapse onto `invalid_input` with structured `error.data`." +
+        DRY_RUN_DESC_SUFFIX,
+    inputSchema: {
+        family: z
+            .string()
+            .describe('CSS font family name (e.g. "Sora", "Inter", "JetBrains Mono"). Stored as the bare name; consumers wrap in single quotes when emitting CSS.'),
+        source: z
+            .enum(["google", "system", "custom"])
+            .describe('Font source: "google" (Google Fonts), "system" (system/web-safe families), or "custom" (self-hosted/CDN).'),
+        id: z
+            .string()
+            .optional()
+            .describe('Optional explicit gfid (e.g. "gfid-oa-sora"). Auto-prefixes `gfid-` if missing; must match `[0-9a-z-]{1,80}` after the prefix. Omit to mint a fresh `gfid-<uuid>`.'),
+        weights: z
+            .array(z.union([z.number(), z.string()]))
+            .optional()
+            .describe('Font weights to load. Accepts integers (100,200,...,900) or keyword strings ("normal","bold","lighter","bolder"). Defaults to []. Drives Google Fonts URL composition + loader hints.'),
+        subsets: z
+            .array(z.string())
+            .optional()
+            .describe('Character subsets (e.g. ["latin","latin-ext"]). Defaults to []. Permissive — not allowlisted server-side (Google adds new subsets regularly).'),
+        label: z
+            .string()
+            .optional()
+            .describe('Human-readable display label. Defaults to the family name.'),
+        fallback: z
+            .string()
+            .optional()
+            .describe('CSS fallback chain appended after the family name (e.g. "sans-serif", "Georgia, serif"). Defaults to empty.'),
+        status: z
+            .enum(["active", "archived"])
+            .optional()
+            .default("active")
+            .describe('Font status — "active" (visible) or "archived" (hidden but preserved).'),
+        dry_run: DRY_RUN_FIELD,
+    },
+    annotations: { idempotentHint: false },
+    _meta: { idempotent: "false" },
+}, async ({ family, source, id, weights, subsets, label, fallback, status, dry_run }) => {
+    const body = { family, source };
+    if (id !== undefined)
+        body.id = id;
+    if (weights !== undefined)
+        body.weights = weights;
+    if (subsets !== undefined)
+        body.subsets = subsets;
+    if (label !== undefined)
+        body.label = label;
+    if (fallback !== undefined)
+        body.fallback = fallback;
+    if (status)
+        body.status = status;
+    if (dry_run)
+        body.dry_run = true;
+    const result = await wp.requestEnveloped("/global-font/create", {
+        method: "POST",
+        body,
+    });
+    return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_global_font_create") }] };
+});
+registerPluginTool("diviops_global_font_update", {
+    description: "Update an existing global font by gfid. Strict update — `id` must reference an existing record; unknown gfid returns `not_found` (HTTP 404) with `error.data = { id }` (unlike `diviops_global_color_update`'s merge-mode semantics). Partial: only supplied fields are written, omitted fields preserved; `lastUpdated` bumped on every write. To rename a font's family slug, use diviops_global_font_delete + diviops_global_font_create — `family` itself can be updated in place but the `gfid` identity is immutable via this tool. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; malformed id charset/length returns 'invalid_input'; missing `id` returns 'invalid_input' with `error.data.missing = \"id\"`; invalid source enum / non-array weights / non-array subsets return 'invalid_input' with structured `error.data`." +
+        DRY_RUN_DESC_SUFFIX,
+    inputSchema: {
+        id: z
+            .string()
+            .describe('Global font ID (e.g. "gfid-oa-sora"). Required. Get from diviops_global_font_list.'),
+        family: z
+            .string()
+            .optional()
+            .describe('New CSS family name. Omit to keep existing.'),
+        source: z
+            .enum(["google", "system", "custom"])
+            .optional()
+            .describe('New source. Omit to keep existing.'),
+        weights: z
+            .array(z.union([z.number(), z.string()]))
+            .optional()
+            .describe('New weights array. Omit to keep existing; pass [] to clear.'),
+        subsets: z
+            .array(z.string())
+            .optional()
+            .describe('New subsets array. Omit to keep existing; pass [] to clear.'),
+        label: z
+            .string()
+            .optional()
+            .describe('New label. Pass empty string to clear.'),
+        fallback: z
+            .string()
+            .optional()
+            .describe('New CSS fallback chain. Pass empty string to clear.'),
+        status: z
+            .enum(["active", "archived"])
+            .optional()
+            .describe('New status — "active" or "archived". Omit to keep existing.'),
+        dry_run: DRY_RUN_FIELD,
+    },
+    annotations: { idempotentHint: false },
+    _meta: { idempotent: "conditional" },
+}, async ({ id, family, source, weights, subsets, label, fallback, status, dry_run }) => {
+    const body = { id };
+    if (family !== undefined)
+        body.family = family;
+    if (source !== undefined)
+        body.source = source;
+    if (weights !== undefined)
+        body.weights = weights;
+    if (subsets !== undefined)
+        body.subsets = subsets;
+    if (label !== undefined)
+        body.label = label;
+    if (fallback !== undefined)
+        body.fallback = fallback;
+    if (status)
+        body.status = status;
+    if (dry_run)
+        body.dry_run = true;
+    const result = await wp.requestEnveloped("/global-font/update", {
+        method: "POST",
+        body,
+    });
+    return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_global_font_update") }] };
+});
+registerPluginTool("diviops_global_font_delete", {
+    description: "Delete a global font from the registry by gfid. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }. Live-reference detection uses parse_blocks over post_content across pages / TB layouts / library / canvas + the preset registry (parallel to diviops_variable_delete / diviops_global_color_delete) — MCP-authored content is detected reliably. Returns code 'conflict' (HTTP 409) when references exist with `error.data = { id, ref_count, locations[], scan_truncated, scanned_posts }`. Pass `force: true` to override; orphan refs will fall back to the browser default until pages are re-authored. Missing gfid returns 'not_found' (HTTP 404) with `error.data = { id }`. Malformed gfid (empty or missing `gfid-` prefix) returns 'invalid_input'. Unlike global_color_delete, no customizer-bound `gfid-*` defaults exist to protect — the Divi customizer-bound font defaults live in `heading_font` / `body_font` plain WP options, not this registry." +
+        DRY_RUN_DESC_SUFFIX,
+    inputSchema: {
+        id: z
+            .string()
+            .describe('Global font ID to delete (must start with "gfid-").'),
+        force: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("If true, delete even when live references exist."),
+        dry_run: DRY_RUN_FIELD,
+    },
+    annotations: { idempotentHint: true },
+    _meta: { idempotent: "true" },
+}, async ({ id, force, dry_run }) => {
+    const body = { id };
+    if (force)
+        body.force = true;
+    if (dry_run)
+        body.dry_run = true;
+    const result = await wp.requestEnveloped("/global-font/delete", {
+        method: "POST",
+        body,
+    });
+    return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_global_font_delete") }] };
+});
 registerPluginTool("diviops_meta_find_icon", {
     description: "Search for icons by keyword. Returns matching icons with unicode, type (fa/divi), and weight. Use the returned unicode/type/weight in Blurb icon or Icon module attributes. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }.",
     inputSchema: {
@@ -512,16 +664,38 @@ registerPluginTool("diviops_page_update_content", {
     };
 });
 registerPluginTool("diviops_render_preview", {
-    description: "Render Divi block markup to HTML. Use this to preview what the output will look like before saving. Useful for validation. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { rendered_html: string }. Errors map to `invalid_input` (non-string content) or `divi_error` (parser/render exception, with truncated message and full detail in `error.data.detail`).",
+    description: "Render Divi block markup to HTML. Accepts EITHER inline `content` (string of block markup) OR `page_id` (loads `post_content` from the DB, requires edit_post capability on the page — useful for previewing shipped pages without round-tripping the markup blob). Provide exactly one. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { rendered_html: string }. Errors map to `invalid_input` (neither/both supplied, or invalid page_id), `forbidden` (caller lacks edit_post on the page), `not_found` (page_id does not exist), or `divi_error` (parser/render exception, with truncated message and full detail in `error.data.detail`).",
     inputSchema: {
-        content: z.string().describe("Divi block markup to render to HTML"),
+        content: z
+            .string()
+            .optional()
+            .describe("Divi block markup to render to HTML. Provide exactly one of {content, page_id}."),
+        page_id: z
+            .number()
+            .int()
+            .optional()
+            .describe("WordPress post/page ID to read post_content from the DB. Requires edit_post capability on the page. Provide exactly one of {content, page_id}."),
     },
     annotations: { idempotentHint: true },
     _meta: { idempotent: "true" },
-}, async ({ content }) => {
+}, async ({ content, page_id }) => {
+    if (page_id !== undefined) {
+        try {
+            requireCapability("validate_render_by_page_id");
+        }
+        catch (e) {
+            if (e instanceof MissingCapabilityError) {
+                return {
+                    content: [{ type: "text", text: e.message }],
+                    isError: true,
+                };
+            }
+            throw e;
+        }
+    }
     const result = await wp.requestEnveloped("/render", {
         method: "POST",
-        body: { content },
+        body: { content, page_id },
     });
     return {
         content: [
@@ -530,16 +704,38 @@ registerPluginTool("diviops_render_preview", {
     };
 });
 registerPluginTool("diviops_validate_blocks", {
-    description: "Validate Divi block markup before saving. Checks structure (malformed comments, unknown blocks, missing builderVersion), required attributes (layout display on containers), and known pitfalls (button padding path, icon.enable, gradient enabled/positions). Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { valid: bool, total_blocks: number, errors: Finding[], warnings: Finding[] } where each Finding is { block, index, code, message, path? }. Note: shape errors detected in the markup surface as success-branch `data.errors[]` entries (NOT `validation_failed` envelopes) — the findings array is the payload, not an error. The envelope's error branch fires only for tool-level failures (`invalid_input` for non-string content; `divi_error` for an exception in the walker).",
+    description: "Validate Divi block markup before saving. Accepts EITHER inline `content` (string of block markup) OR `page_id` (loads `post_content` from the DB, requires edit_post capability on the page — useful for regression checks on shipped pages without round-tripping the markup blob). Provide exactly one. Checks structure (malformed comments, unknown blocks, missing builderVersion), required attributes (layout display on containers), and known pitfalls (button padding path, icon.enable, gradient enabled/positions). Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { valid: bool, total_blocks: number, errors: Finding[], warnings: Finding[] } where each Finding is { block, index, code, message, path? }. Note: shape errors detected in the markup surface as success-branch `data.errors[]` entries (NOT `validation_failed` envelopes) — the findings array is the payload, not an error. The envelope's error branch fires only for tool-level failures (`invalid_input` for neither/both supplied or invalid page_id; `forbidden` for missing edit_post; `not_found` for unknown page_id; `divi_error` for an exception in the walker).",
     inputSchema: {
-        content: z.string().describe("Divi block markup to validate"),
+        content: z
+            .string()
+            .optional()
+            .describe("Divi block markup to validate. Provide exactly one of {content, page_id}."),
+        page_id: z
+            .number()
+            .int()
+            .optional()
+            .describe("WordPress post/page ID to read post_content from the DB. Requires edit_post capability on the page. Provide exactly one of {content, page_id}."),
     },
     annotations: { idempotentHint: true },
     _meta: { idempotent: "true" },
-}, async ({ content }) => {
+}, async ({ content, page_id }) => {
+    if (page_id !== undefined) {
+        try {
+            requireCapability("validate_render_by_page_id");
+        }
+        catch (e) {
+            if (e instanceof MissingCapabilityError) {
+                return {
+                    content: [{ type: "text", text: e.message }],
+                    isError: true,
+                };
+            }
+            throw e;
+        }
+    }
     const result = await wp.requestEnveloped("/validate/blocks", {
         method: "POST",
-        body: { content },
+        body: { content, page_id },
     });
     return {
         content: [
@@ -1490,13 +1686,13 @@ registerPluginTool("diviops_tb_layout_update", {
     };
 });
 registerPluginTool("diviops_tb_template_create", {
-    description: "Create a Theme Builder template with custom header and/or footer. Automatically creates layout posts, sets conditions, and links to Theme Builder. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; missing Theme Builder master post returns ok:false with code 'wp_error' and a hint to open the Divi Theme Builder once to initialize it." +
+    description: "Create a Theme Builder template with custom header and/or footer. Automatically creates layout posts, sets conditions, and links to Theme Builder. Pass condition=\"default\" (case-insensitive) or an empty string to register the template as the catch-all Default Website Template — the route writes the `_et_default = '1'` flag with an empty `_et_use_on`, matching the meta shape Divi's TB router gates the default route on; any other condition string lands in `_et_use_on` unchanged. Default Website Template is a singleton scoped to the active Theme Builder master: if the active master's `_et_template` linked list already names an et_template carrying `_et_default = '1'` (regardless of `_et_enabled` status — the router resolves by linked-list position before checking the enable-gate, so a disabled existing default linked ahead of the new one would still shadow it), the route rejects with code `tb_template.default_already_exists` (HTTP 409) and `error.data.existing_default_id` + `error.data.master_post_id`. Templates outside the active master's linked list (orphan defaults, library-cloned-master defaults) cannot shadow the router's pick and DO NOT block creation. Caller resolves a real conflict by trashing the existing default (diviops_tb_template_trash) or pinning this template to a specific condition; the route never silently flips the existing default's flag or proceeds with non-deterministic router state. If the Theme Builder master post is missing (fresh substrate that never opened Divi → Theme Builder in WP Admin), the route auto-bootstraps one with the same shape Divi creates on first admin visit and returns `data.master_post_bootstrapped: true` so callers can audit the side-effect. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; failures during master-post bootstrap or template/layout insert surface the underlying WP_Error code (commonly `db_insert_error`, `db_update_error`, or other slugs from the WordPress vocabulary), not a generic `wp_error` — branch on `error.code` against the WP slug, not against a hard-coded string. The literal `wp_error` slug only surfaces when the upstream WP_Error has an empty code." +
         DRY_RUN_DESC_SUFFIX,
     inputSchema: {
         title: z.string().describe('Template name (e.g. "Landing Pages")'),
         condition: z
             .string()
-            .describe('Condition string (e.g. "singular:post_type:page:all", "singular:post_type:project:all", "archive:taxonomy:category:all")'),
+            .describe('Condition string. Pass "default" (case-insensitive) or "" for the catch-all Default Website Template (sets `_et_default = 1`). Otherwise a Divi router-recognized location string such as "singular:post_type:page:all", "singular:post_type:project:all", "archive:taxonomy:category:all", "homepage", or "404" (lands in `_et_use_on`).'),
         header_content: z
             .string()
             .optional()

package/dist/wp-client.js

@@ -73,6 +73,32 @@ const BLOCK_CONTENT_KEYS = new Set([
     'header_content', // create_tb_template
     'footer_content', // create_tb_template
 ]);
+/**
+ * Endpoints whose target storage is a PHP-serialized WP option (or other
+ * non-JSON serialization) rather than block-markup `post_content`. For these,
+ * quote-escape normalization is harmful: the under-escape pass inserts literal
+ * `\` characters into bare-`"`-containing `$variable(...)$` token strings,
+ * which are then PHP-serialized verbatim into the option — producing the
+ * pathological `\"` (literal backslash + quote) byte sequence inside the
+ * stored value where canonical VB output stores a bare `"` (the surrounding
+ * PHP array provides all the structure; the string itself is uninterpreted).
+ *
+ * The frontend-render side tolerates the malformed bytes via a regex-based
+ * extractor, but the VB-UI field-display layer strict-parses the inner
+ * payload and silently falls back to placeholder values when it can't decode
+ * — see #716.
+ *
+ * Match by endpoint prefix so any future `/preset/*` route inherits the
+ * exclusion automatically. Block-markup writers (`/section/*`, `/module/*`,
+ * `/page/*`, `/canvas/*`, `/tb-layout/*`, `/tb-template/*`, `/library/save`,
+ * `/render-preview`, `/validate-blocks`) still receive normalization.
+ */
+const NON_BLOCK_STORAGE_PREFIXES = [
+    '/preset/',
+];
+function endpointSkipsNormalization(endpoint) {
+    return NON_BLOCK_STORAGE_PREFIXES.some((prefix) => endpoint.startsWith(prefix));
+}
 function normalizeBody(value, withinBlockTree = false) {
     if (typeof value === 'string') {
         return withinBlockTree ? normalizeQuoteEscapes(value) : value;
@@ -121,7 +147,8 @@ export class WPClient {
             },
         };
         if (body && method !== 'GET') {
-            fetchOptions.body = JSON.stringify(normalizeBody(body));
+            const normalized = endpointSkipsNormalization(endpoint) ? body : normalizeBody(body);
+            fetchOptions.body = JSON.stringify(normalized);
         }
         const response = await fetch(url, fetchOptions);
         if (!response.ok) {
@@ -183,7 +210,8 @@ export class WPClient {
             },
         };
         if (body && method !== 'GET') {
-            fetchOptions.body = JSON.stringify(normalizeBody(body));
+            const normalized = endpointSkipsNormalization(endpoint) ? body : normalizeBody(body);
+            fetchOptions.body = JSON.stringify(normalized);
         }
         const response = await fetch(url, fetchOptions);
         const rawBody = await response.text();

package/package.json

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