@diviops/mcp-server 1.1.0 → 1.2.0

package/README.md

@@ -320,8 +320,11 @@ Ensure `WP_URL`, `WP_USER`, and `WP_APP_PASSWORD` are all set. Check your `claud
 - 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
-The MCP server and WP plugin versions are incompatible. Update whichever side is older.
+### "This tool requires plugin capability" error
+A specific tool failed at the per-tool capability gate (#486) because the active diviops-agent plugin doesn't advertise that capability. Update the plugin to ≥ 1.2.0 (the version that introduced the capability map). Other tools the older plugin does support keep working — the gate is per-tool, not a global floor.
+
+### "Server too old for plugin" error
+The plugin returned HTTP 426 because this MCP server is below the plugin's `MIN_SERVER_VERSION`. Update the MCP server (`npm install -g @diviops/mcp-server@latest` or rebuild from source).
 
 ### "Permission denied" errors
 - The WP user must have `edit_posts` capability (Editor or Admin role)

package/dist/compatibility.d.ts

@@ -1,8 +1,21 @@
 /**
- * Version compatibility between MCP server and WP plugin.
+ * Server↔plugin compatibility surface.
+ *
+ * As of #486, the global `MIN_PLUGIN_VERSION` floor is gone. Compatibility
+ * is now decided per-tool against a capability map returned by the plugin's
+ * `/handshake`. See `wp-client.ts` (handshake parse) and `index.ts`
+ * (`requireCapability` gate at each plugin-touching tool entry).
+ *
+ * Implicit floor: pre-1.2.0 plugins emit `capabilities` as a string[] of
+ * coarse namespace tags, not the per-tool map this server expects.
+ * `wp-client.ts` normalizes that legacy shape to an empty map, which makes
+ * every gated tool fail fast with the upgrade hint. So while there is no
+ * declared `MIN_PLUGIN_VERSION` constant, the capability-map shape change
+ * effectively sets a 1.2.0 floor for any tool that calls `requireCapability`.
+ *
+ * `compareVersions` is kept exported because handshake helper code and
+ * future per-tool soft-deprecation messages may want it.
  */
-/** Minimum WP plugin version this server requires. */
-export declare const MIN_PLUGIN_VERSION = "1.1.0";
 /**
  * Compare two semver-like version strings (supports pre-release tags).
  *
@@ -14,6 +27,15 @@ export declare const MIN_PLUGIN_VERSION = "1.1.0";
  * Pre-release versions (e.g. 1.0.0-beta.22) sort before their release (1.0.0).
  */
 export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * Shape returned by `POST /diviops/v1/handshake`.
+ *
+ * `capabilities` is a per-tool map keyed by post-rename tool slug
+ * (without the `diviops_` prefix). Older plugins (pre-1.2.0) emit
+ * a string[] of coarse namespace keys; the server normalizes that
+ * legacy shape to an empty map (every gated tool then fails fast
+ * with an upgrade hint, which is the intended behavior).
+ */
 export interface HandshakeResult {
     compatible: boolean;
     plugin_version: string;
@@ -22,5 +44,16 @@ export interface HandshakeResult {
         active: boolean;
         version: string | null;
     };
-    capabilities: string[];
+    capabilities: Record<string, boolean>;
+}
+/**
+ * Thrown when a tool handler calls `requireCapability(key)` and the
+ * plugin's handshake response did not include `key`. The server's
+ * tool dispatch wraps this into the MCP error response, surfacing
+ * the upgrade hint to the agent.
+ */
+export declare class MissingCapabilityError extends Error {
+    readonly capability: string;
+    readonly pluginVersion: string;
+    constructor(capability: string, pluginVersion: string);
 }

package/dist/compatibility.js

@@ -1,8 +1,21 @@
 /**
- * Version compatibility between MCP server and WP plugin.
+ * Server↔plugin compatibility surface.
+ *
+ * As of #486, the global `MIN_PLUGIN_VERSION` floor is gone. Compatibility
+ * is now decided per-tool against a capability map returned by the plugin's
+ * `/handshake`. See `wp-client.ts` (handshake parse) and `index.ts`
+ * (`requireCapability` gate at each plugin-touching tool entry).
+ *
+ * Implicit floor: pre-1.2.0 plugins emit `capabilities` as a string[] of
+ * coarse namespace tags, not the per-tool map this server expects.
+ * `wp-client.ts` normalizes that legacy shape to an empty map, which makes
+ * every gated tool fail fast with the upgrade hint. So while there is no
+ * declared `MIN_PLUGIN_VERSION` constant, the capability-map shape change
+ * effectively sets a 1.2.0 floor for any tool that calls `requireCapability`.
+ *
+ * `compareVersions` is kept exported because handshake helper code and
+ * future per-tool soft-deprecation messages may want it.
  */
-/** Minimum WP plugin version this server requires. */
-export const MIN_PLUGIN_VERSION = '1.1.0';
 /**
  * Compare two semver-like version strings (supports pre-release tags).
  *
@@ -66,3 +79,20 @@ export function compareVersions(a, b) {
     }
     return 0;
 }
+/**
+ * Thrown when a tool handler calls `requireCapability(key)` and the
+ * plugin's handshake response did not include `key`. The server's
+ * tool dispatch wraps this into the MCP error response, surfacing
+ * the upgrade hint to the agent.
+ */
+export class MissingCapabilityError extends Error {
+    capability;
+    pluginVersion;
+    constructor(capability, pluginVersion) {
+        super(`Tool requires plugin capability "${capability}", which is not present in the active diviops-agent plugin (version ${pluginVersion}). ` +
+            'Upgrade the diviops-agent plugin to the version shipped alongside this MCP server release.');
+        this.capability = capability;
+        this.pluginVersion = pluginVersion;
+        this.name = 'MissingCapabilityError';
+    }
+}

package/dist/index.js

@@ -12,6 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { WPClient } from "./wp-client.js";
+import { MissingCapabilityError } from "./compatibility.js";
 import { optimizeSchema } from "./schema-optimizer.js";
 import { createWpCli } from "./wp-cli.js";
 import { findForeignVarRefs, scanAttrsForForeignVarRefs, isolationErrorResult, } from "./validate-attrs.js";
@@ -82,8 +83,49 @@ const server = new McpServer({
     name: "diviops-mcp",
     version: SERVER_VERSION,
 });
+let handshakeState = { kind: "pending" };
+function requireCapability(key) {
+    // Only gate when we have a real capability map. On handshake failure,
+    // bypass the gate so the underlying request surfaces the actual cause
+    // (auth, network, 5xx) rather than misattributing it to the plugin
+    // version.
+    if (handshakeState.kind !== "ok")
+        return;
+    if (!handshakeState.capabilities[key]) {
+        throw new MissingCapabilityError(key, handshakeState.pluginVersion);
+    }
+}
+// `any` here is deliberate, not laziness. McpServer.registerTool is a
+// multi-overload generic whose `cb`/`InputArgs` machinery doesn't compose
+// with `Parameters<typeof server.registerTool>` (overload collapse to
+// `never`). Restating its Zod-driven generics in this thin wrapper buys
+// no real safety — the per-callsite `inputSchema` Zod object at every
+// usage site below is what enforces actual argument shape; this helper
+// only adds a capability-check + an error envelope on top, both shape-
+// independent. Scope: 4 narrow suppressions, all in this 25-line block.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function registerPluginTool(name, config, handler) {
+    const key = name.replace(/^diviops_/, "");
+    const wrapped = (async (args) => {
+        try {
+            requireCapability(key);
+        }
+        catch (e) {
+            if (e instanceof MissingCapabilityError) {
+                return {
+                    content: [{ type: "text", text: e.message }],
+                    isError: true,
+                };
+            }
+            throw e;
+        }
+        return handler(args);
+    });
+    server.registerTool(name, config, wrapped);
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
 // ── Read Tools ───────────────────────────────────────────────────────
-server.registerTool("diviops_page_list", {
+registerPluginTool("diviops_page_list", {
     description: "List pages/posts in the WordPress site. Returns title, ID, URL, status, and whether each page uses Divi builder.",
     inputSchema: {
         post_type: z
@@ -112,7 +154,7 @@ server.registerTool("diviops_page_list", {
         ],
     };
 });
-server.registerTool("diviops_page_get", {
+registerPluginTool("diviops_page_get", {
     description: "Get detailed info about a specific page including its raw Divi block content.",
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -125,7 +167,7 @@ server.registerTool("diviops_page_get", {
         ],
     };
 });
-server.registerTool("diviops_page_get_layout", {
+registerPluginTool("diviops_page_get_layout", {
     description: "Get the parsed block tree for a page. Returns slim targeting metadata by default (block names, admin labels, text previews, auto_index). Use full: true for complete attrs (warning: can be very large on complex pages).",
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -145,7 +187,7 @@ server.registerTool("diviops_page_get_layout", {
         ],
     };
 });
-server.registerTool("diviops_schema_list_modules", {
+registerPluginTool("diviops_schema_list_modules", {
     description: "List all available Divi modules (block types) with their names, titles, and categories. Use this to discover what modules can be used in layouts.",
 }, async () => {
     const result = await wp.request("/schema/modules");
@@ -155,7 +197,7 @@ server.registerTool("diviops_schema_list_modules", {
         ],
     };
 });
-server.registerTool("diviops_schema_get_module", {
+registerPluginTool("diviops_schema_get_module", {
     description: "Get the attribute schema for a Divi module. Returns optimized schema by default (~70% smaller) with content-relevant fields only. Use raw: true for the full schema including CSS selectors and VB metadata.",
     inputSchema: {
         module_name: z
@@ -176,7 +218,7 @@ server.registerTool("diviops_schema_get_module", {
         ],
     };
 });
-server.registerTool("diviops_schema_get_settings", {
+registerPluginTool("diviops_schema_get_settings", {
     description: "Get Divi site settings including theme options, site info, and builder version. Useful for understanding the site context before generating content.",
 }, async () => {
     const result = await wp.request("/schema/settings");
@@ -186,7 +228,7 @@ server.registerTool("diviops_schema_get_settings", {
         ],
     };
 });
-server.registerTool("diviops_global_color_list", {
+registerPluginTool("diviops_global_color_list", {
     description: "Get the global color palette defined in Divi. Returns all global colors that can be referenced by modules.",
 }, async () => {
     const result = await wp.request("/global-color/list");
@@ -196,7 +238,7 @@ server.registerTool("diviops_global_color_list", {
         ],
     };
 });
-server.registerTool("diviops_global_color_create", {
+registerPluginTool("diviops_global_color_create", {
     description: "Add a new global color to Divi's palette. The plugin mints a fresh `gcid-<uuid>` ID (the server forwards the color entry without an id and the WP-side handler generates one) and writes to the et_global_data option in the canonical Divi shape `{color, folder, label, lastUpdated, status, usedInPosts}`. The color appears in the VB color picker after save and can be referenced via `$variable({type:color,value:{name:gcid-...}})$` tokens. Note: Divi's AI Agent bundle has a Zod schema gap that drops `label` on its own writes — our PHP path goes around that bug by writing directly to the option. CONCURRENCY: this is a read-modify-write on a single WP option with no conflict detection. If a Visual Builder session holds stale global data, its next save can clobber colors written here in the interim. Coordinate writes when VB sessions are active, or have the user reload VB after MCP color writes.",
     inputSchema: {
         color: z
@@ -230,7 +272,7 @@ server.registerTool("diviops_global_color_create", {
     });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
 });
-server.registerTool("diviops_global_color_update", {
+registerPluginTool("diviops_global_color_update", {
     description: "Update an existing global color by gcid. Only provided fields are updated; omitted fields are preserved. The lastUpdated timestamp is bumped on every write. Use diviops_global_color_list first to find the gcid for a color. CONCURRENCY: same VB-session race caveat as diviops_global_color_create — the write is read-modify-write on a single WP option, so an active VB session's next save can clobber this update.",
     inputSchema: {
         gcid: z
@@ -269,7 +311,7 @@ server.registerTool("diviops_global_color_update", {
     });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
 });
-server.registerTool("diviops_global_color_delete", {
+registerPluginTool("diviops_global_color_delete", {
     description: "Delete a global color from the registry by gcid. Refuses by default if the color is tracked as referenced by any post (per Divi's `usedInPosts` index — pass `force: true` to delete anyway; orphan refs will render as invalid CSS until pages are re-saved through VB). Always refuses to delete the 5 customizer-bound defaults (gcid-primary-color, gcid-secondary-color, gcid-heading-color, gcid-body-color, gcid-link-color) regardless of force — those must be edited via WP Customizer. CONCURRENCY: same VB-session race caveat as diviops_global_color_create — an active VB session's next save can re-introduce a color we just deleted if the session held stale data.",
     inputSchema: {
         gcid: z
@@ -291,7 +333,7 @@ server.registerTool("diviops_global_color_delete", {
     });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
 });
-server.registerTool("diviops_global_font_list", {
+registerPluginTool("diviops_global_font_list", {
     description: "Get the global font definitions from Divi settings.",
 }, async () => {
     const result = await wp.request("/global-font/list");
@@ -301,7 +343,7 @@ server.registerTool("diviops_global_font_list", {
         ],
     };
 });
-server.registerTool("diviops_meta_find_icon", {
+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.",
     inputSchema: {
         query: z
@@ -327,7 +369,7 @@ server.registerTool("diviops_meta_find_icon", {
     };
 });
 // ── Write Tools ──────────────────────────────────────────────────────
-server.registerTool("diviops_page_update_content", {
+registerPluginTool("diviops_page_update_content", {
     description: "Update the content of a page with Divi block markup. The content should be valid WordPress block markup using divi/* blocks. IMPORTANT: This overwrites the entire page content.",
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID to update"),
@@ -349,7 +391,7 @@ server.registerTool("diviops_page_update_content", {
         ],
     };
 });
-server.registerTool("diviops_render_preview", {
+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.",
     inputSchema: {
         content: z.string().describe("Divi block markup to render to HTML"),
@@ -365,7 +407,7 @@ server.registerTool("diviops_render_preview", {
         ],
     };
 });
-server.registerTool("diviops_validate_blocks", {
+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 errors and warnings.",
     inputSchema: {
         content: z.string().describe("Divi block markup to validate"),
@@ -381,7 +423,7 @@ server.registerTool("diviops_validate_blocks", {
         ],
     };
 });
-server.registerTool("diviops_section_append", {
+registerPluginTool("diviops_section_append", {
     description: "Append a Divi section to an existing page without overwriting other content. Use this to incrementally build pages.",
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -408,7 +450,7 @@ server.registerTool("diviops_section_append", {
         ],
     };
 });
-server.registerTool("diviops_section_replace", {
+registerPluginTool("diviops_section_replace", {
     description: "Replace a section on a page. Target by admin label OR text content. Use occurrence when multiple sections match.",
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -450,7 +492,7 @@ server.registerTool("diviops_section_replace", {
         ],
     };
 });
-server.registerTool("diviops_section_remove", {
+registerPluginTool("diviops_section_remove", {
     description: "Remove a section from a page. Target by admin label OR text content. Use occurrence when multiple sections match.",
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -486,7 +528,7 @@ server.registerTool("diviops_section_remove", {
         ],
     };
 });
-server.registerTool("diviops_section_get", {
+registerPluginTool("diviops_section_get", {
     description: "Get the raw block markup of a section. Target by admin label OR text content. Use occurrence when multiple sections match. Returns total_matches warning when duplicates exist.",
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -520,7 +562,7 @@ server.registerTool("diviops_section_get", {
         ],
     };
 });
-server.registerTool("diviops_module_update", {
+registerPluginTool("diviops_module_update", {
     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"),
@@ -570,7 +612,7 @@ server.registerTool("diviops_module_update", {
         ],
     };
 });
-server.registerTool("diviops_module_move", {
+registerPluginTool("diviops_module_move", {
     description: 'Move a module to a new position on the page. Specify source and target blocks using auto_index (e.g. "text:3"), admin label, or text content. Position "before" or "after" the target. Works with any block type including sections, rows, and modules. Both blocks are found in the original content, so auto_index values refer to positions before the move.',
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -644,7 +686,7 @@ server.registerTool("diviops_module_move", {
         ],
     };
 });
-server.registerTool("diviops_module_lock", {
+registerPluginTool("diviops_module_lock", {
     description: 'Lock a module so VB users cannot edit it. Sets attrs.locked = {desktop: {value: "on"}} per Divi\'s per-breakpoint convention (verified via VB-save probe). Locked modules render normally on frontend; only VB-side editing is gated. Same targeting pattern as diviops_module_update — pick one of label / match_text / auto_index. Use diviops_module_unlock to reverse.',
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -666,7 +708,7 @@ server.registerTool("diviops_module_lock", {
     const result = await wp.request(`/module/lock/${page_id}`, { method: "POST", body });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
 });
-server.registerTool("diviops_module_unlock", {
+registerPluginTool("diviops_module_unlock", {
     description: "Unlock a module by removing attrs.locked entirely. Matches Divi VB's convention: unlocked = attribute absent (NOT {value: 'off'}) — VB doesn't write a falsy value on unlock, it removes the field. Same targeting pattern as diviops_module_lock.",
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -688,7 +730,7 @@ server.registerTool("diviops_module_unlock", {
     const result = await wp.request(`/module/unlock/${page_id}`, { method: "POST", body });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
 });
-server.registerTool("diviops_module_clone", {
+registerPluginTool("diviops_module_clone", {
     description: 'Clone a module by deep-copying its block JSON and inserting it next to the source within the same parent container. Position controls before/after placement (default "after"). Module IDs are reassigned by Divi at render time from the block tree position, so the clone gets fresh IDs automatically. Same targeting pattern as diviops_module_lock.',
     inputSchema: {
         page_id: z.number().describe("WordPress post/page ID"),
@@ -713,7 +755,7 @@ server.registerTool("diviops_module_clone", {
     const result = await wp.request(`/module/clone/${page_id}`, { method: "POST", body });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
 });
-server.registerTool("diviops_page_create", {
+registerPluginTool("diviops_page_create", {
     description: "Create a new WordPress page, optionally with Divi block content.",
     inputSchema: {
         title: z.string().describe("Page title"),
@@ -744,7 +786,7 @@ server.registerTool("diviops_page_create", {
         ],
     };
 });
-server.registerTool("diviops_page_trash", {
+registerPluginTool("diviops_page_trash", {
     description: "Trash or permanently delete a page/post. Defaults to trash (reversible via WP Admin → Trash). Pass force=true to permanently delete (wp_delete_post — irreversible). Idempotent: trashing an already-trashed post is a no-op. Pass dry_run=true to preview without mutating. Replaces wp-cli `post delete --force=0|1` routing for AI-agent callers (typed input, deterministic envelope).",
     inputSchema: {
         post_id: z.number().int().describe("WordPress post/page ID"),
@@ -773,7 +815,7 @@ server.registerTool("diviops_page_trash", {
         ],
     };
 });
-server.registerTool("diviops_page_update_status", {
+registerPluginTool("diviops_page_update_status", {
     description: "Update a page's post_status. Valid statuses: publish, draft, private, pending, future. status='future' requires date_gmt (ISO 8601 UTC, must be in the future) — server writes both post_date_gmt and the site-tz post_date so WP's scheduler picks it up. status='publish' on a previously-scheduled post clears the future date so it publishes immediately. Idempotent: same-status update is a no-op. Pass dry_run=true to preview. Replaces wp-cli `post update --post_status=...` routing.",
     inputSchema: {
         post_id: z.number().int().describe("WordPress post/page ID"),
@@ -808,7 +850,7 @@ server.registerTool("diviops_page_update_status", {
     };
 });
 // ── Preset Tools ────────────────────────────────────────────────────
-server.registerTool("diviops_preset_audit", {
+registerPluginTool("diviops_preset_audit", {
     description: "Audit all Divi presets (module + group). Each entry reports `block_ref_count` (page-content refs via modulePreset / groupPreset block markup), `group_ref_count` (in-registry chain refs from other presets — module presets via top-level `groupPresets.<slot>.presetId`, group presets via `attrs.groupPreset.<slot>.presetId`), and `referenced` (true if either > 0). Group presets that are chain-referenced also expose `referenced_by_presets` (UUIDs of the presets that wire them in — typically module presets, but type-agnostic). Use this before deleting — orphan-cleanup based only on page refs would silently wipe load-bearing chain-wired group presets (font, border, box-shadow, spacing, button). Also reports `orphan_default_pointers`: per-bucket `default` pointers that reference a UUID no longer present in `items[]` (caused by past unsafe deletes). Render-safe but blocks Divi's lazy recreate-on-VB-use path; clear via diviops_preset_set_default with unset=true on the affected module/group.",
 }, async () => {
     const result = await wp.request("/preset/audit");
@@ -818,7 +860,7 @@ server.registerTool("diviops_preset_audit", {
         ],
     };
 });
-server.registerTool("diviops_preset_cleanup", {
+registerPluginTool("diviops_preset_cleanup", {
     description: 'Clean up presets. Default: remove spam presets. Optional: dedup=true to also remove duplicates, action="rename_strip_prefix" with prefix to strip a name prefix, or action="remove_orphans" with scope="spam"|"all" to remove unreferenced presets. Use dry_run: true (default) to preview.',
     inputSchema: {
         dry_run: z
@@ -864,7 +906,7 @@ server.registerTool("diviops_preset_cleanup", {
         ],
     };
 });
-server.registerTool("diviops_preset_update", {
+registerPluginTool("diviops_preset_update", {
     description: "Update a specific preset by ID. Can rename, replace its style attributes, and/or change its stack priority. Note: Divi serves frontend CSS from a per-post static cache at wp-content/et-cache/{post_id}/ that wp cache flush does NOT invalidate — if you're verifying a preset change on the rendered frontend, delete that dir for affected pages to force regeneration. Server-side preset state updates immediately; only the pre-rendered CSS file is stale.",
     inputSchema: {
         preset_id: z.string().describe("Preset ID (UUID or short ID)"),
@@ -897,7 +939,7 @@ server.registerTool("diviops_preset_update", {
         ],
     };
 });
-server.registerTool("diviops_preset_delete", {
+registerPluginTool("diviops_preset_delete", {
     description: "Delete a specific preset by ID. Use diviops_preset_audit first to verify the preset is unreferenced before deleting. Refuses with 409 preset_is_default if the target is the registered default for its module/group 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.",
     inputSchema: {
         preset_id: z.string().describe("Preset ID to delete"),
@@ -920,7 +962,7 @@ server.registerTool("diviops_preset_delete", {
         ],
     };
 });
-server.registerTool("diviops_preset_create", {
+registerPluginTool("diviops_preset_create", {
     description: 'Create a new preset in the Divi 5 registry. For module presets, supply module_name (e.g. "divi/column", "divi/button", "divi/section"), name, and attrs. For group (attribute-level) presets, set type="group" and supply group_name ("divi/font", "divi/button", etc.), group_id ("designTitleText", "button", etc.), and optionally primary_attr_name.',
     inputSchema: {
         module_name: z
@@ -979,7 +1021,7 @@ server.registerTool("diviops_preset_create", {
         ],
     };
 });
-server.registerTool("diviops_preset_reassign", {
+registerPluginTool("diviops_preset_reassign", {
     description: 'Reassign a preset UUID across page content. Covers both module-level refs (`attrs.modulePreset[...]`) and attribute-level group-preset refs (`attrs.groupPreset.<slot>.presetId`), plus — for group presets — registry chain refs: module-bucket presets via top-level `groupPresets.<slot>.presetId`, group-bucket presets via `attrs.groupPreset.<slot>.presetId`. The `scope` param controls which ref types are walked (default "both", auto-selects based on new_uuid\'s bucket). Cross-bucket swaps (module ↔ group) are rejected. When `strip_inline=true` (default), strips inline attrs that duplicate the new preset\'s attrs (otherwise inline wins over preset): for module scope, strips from block root; for group scope, strips per-slot using Divi\'s own slot→target-path resolver (handles composite button groups, `-id-classes` suffix, FormField/checkbox/radio `attrName` mappings, cross-module translation). Both scopes enforce a singular-stack guard (skip strip when slot holds multiple presets). Unmappable group slots skip strip and emit a per-slot advisory at `summary.strip_advisory_per_slot[<module>::<slot>]`; neighbor slots are unaffected. Defaults to dry-run — set mode="apply" to actually rewrite. Use this to consolidate repeated inline styling into a reusable preset after creating one with diviops_preset_create.',
     inputSchema: {
         old_uuid: z
@@ -1028,7 +1070,7 @@ server.registerTool("diviops_preset_reassign", {
         ],
     };
 });
-server.registerTool("diviops_preset_scan_orphans", {
+registerPluginTool("diviops_preset_scan_orphans", {
     description: "Scan page content for modulePreset UUIDs that are not in the D5 registry. Categorizes as dangling orphans (preset was deleted, reference remains) or D4-legacy candidates (preset exists in the legacy builder_global_presets_ng option but not in D5). Use before diviops_preset_reassign to identify stale UUIDs for consolidation.",
 }, async () => {
     const result = await wp.request("/preset/scan-orphans");
@@ -1038,7 +1080,7 @@ server.registerTool("diviops_preset_scan_orphans", {
         ],
     };
 });
-server.registerTool("diviops_preset_set_default", {
+registerPluginTool("diviops_preset_set_default", {
     description: "Set or clear the per-module/group default preset. Two addressing modes: (1) preset_id mode — walks both buckets to locate the preset by UUID, then points the containing module/group's `default` slot at it (or clears it with unset=true). (2) Bucket-addressed clear — pass type + module + unset=true to clear an orphan default pointer when the preset_id no longer exists in items[] (the preset_id walk path can't locate orphans — that's the very state being repaired; surfaced via diviops_preset_audit's `orphan_default_pointers`). Defaults apply to NEW module instances only — existing modules keep their current preset bindings (use diviops_preset_reassign for retroactive swaps). Use diviops_preset_audit's `is_default` and `orphan_default_pointers` fields to verify state before/after.",
     inputSchema: {
         preset_id: z
@@ -1079,7 +1121,7 @@ server.registerTool("diviops_preset_set_default", {
     };
 });
 // ── Library Tools ───────────────────────────────────────────────────
-server.registerTool("diviops_library_list", {
+registerPluginTool("diviops_library_list", {
     description: "List saved Divi Library items. Filter by layout_type (section, row, module) and scope (global, non_global).",
     inputSchema: {
         layout_type: z
@@ -1111,7 +1153,7 @@ server.registerTool("diviops_library_list", {
         ],
     };
 });
-server.registerTool("diviops_library_get", {
+registerPluginTool("diviops_library_get", {
     description: "Get a Divi Library item's content by ID. Returns the raw block markup that can be used with diviops_section_append or diviops_page_update_content.",
     inputSchema: {
         item_id: z.number().describe("Library item ID"),
@@ -1124,7 +1166,7 @@ server.registerTool("diviops_library_get", {
         ],
     };
 });
-server.registerTool("diviops_library_save", {
+registerPluginTool("diviops_library_save", {
     description: 'Save Divi block markup to the Divi Library for reuse. Saved items appear in the VB\'s "Add From Library" panel.',
     inputSchema: {
         title: z.string().describe("Display name for the library item"),
@@ -1159,7 +1201,7 @@ server.registerTool("diviops_library_save", {
     };
 });
 // ── Theme Builder Tools ─────────────────────────────────────────────
-server.registerTool("diviops_tb_template_list", {
+registerPluginTool("diviops_tb_template_list", {
     description: "List all Theme Builder templates with their conditions, layout IDs, and enabled status. Shows which template applies to which pages/post types.",
     inputSchema: {
         per_page: z
@@ -1183,7 +1225,7 @@ server.registerTool("diviops_tb_template_list", {
         ],
     };
 });
-server.registerTool("diviops_tb_layout_get", {
+registerPluginTool("diviops_tb_layout_get", {
     description: "Get a Theme Builder layout's block markup content (header, body, or footer). Use the layout IDs from diviops_tb_template_list.",
     inputSchema: {
         layout_id: z
@@ -1198,7 +1240,7 @@ server.registerTool("diviops_tb_layout_get", {
         ],
     };
 });
-server.registerTool("diviops_tb_layout_update", {
+registerPluginTool("diviops_tb_layout_update", {
     description: "Update a Theme Builder layout's block markup (header, body, or footer). Replaces the full content.",
     inputSchema: {
         layout_id: z.number().describe("Layout post ID to update"),
@@ -1215,7 +1257,7 @@ server.registerTool("diviops_tb_layout_update", {
         ],
     };
 });
-server.registerTool("diviops_tb_template_create", {
+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.",
     inputSchema: {
         title: z.string().describe('Template name (e.g. "Landing Pages")'),
@@ -1245,7 +1287,7 @@ server.registerTool("diviops_tb_template_create", {
     };
 });
 // ── Canvas Tools ────────────────────────────────────────────────────
-server.registerTool("diviops_canvas_create", {
+registerPluginTool("diviops_canvas_create", {
     description: "Create a canvas (off-canvas workspace) linked to a page. Used for popups, off-canvas menus, modals. Content uses standard Divi block markup.",
     inputSchema: {
         title: z
@@ -1289,7 +1331,7 @@ server.registerTool("diviops_canvas_create", {
         ],
     };
 });
-server.registerTool("diviops_canvas_list", {
+registerPluginTool("diviops_canvas_list", {
     description: "List canvases (off-canvas workspaces). Filter by parent page or list all.",
     inputSchema: {
         parent_page_id: z
@@ -1318,7 +1360,7 @@ server.registerTool("diviops_canvas_list", {
         ],
     };
 });
-server.registerTool("diviops_canvas_get", {
+registerPluginTool("diviops_canvas_get", {
     description: "Get a canvas's block content and metadata.",
     inputSchema: {
         canvas_post_id: z
@@ -1333,7 +1375,7 @@ server.registerTool("diviops_canvas_get", {
         ],
     };
 });
-server.registerTool("diviops_canvas_update", {
+registerPluginTool("diviops_canvas_update", {
     description: "Update a canvas's content and/or metadata. Content replaces the entire canvas.",
     inputSchema: {
         canvas_post_id: z.number().describe("Canvas post ID"),
@@ -1368,7 +1410,7 @@ server.registerTool("diviops_canvas_update", {
         ],
     };
 });
-server.registerTool("diviops_canvas_delete", {
+registerPluginTool("diviops_canvas_delete", {
     description: "Delete a canvas. This permanently removes the canvas post.",
     inputSchema: {
         canvas_post_id: z.number().describe("Canvas post ID to delete"),
@@ -1851,7 +1893,7 @@ server.registerTool("diviops_template_get", {
     };
 });
 // ── Variable Manager CRUD ─────────────────────────────────────────────
-server.registerTool("diviops_variable_list", {
+registerPluginTool("diviops_variable_list", {
     description: "List all design token variables from the Divi Variable Manager. Colors (gcid-*) come from et_global_data, numbers/strings/etc (gvid-*) from et_divi_global_variables. Filter by type or ID prefix.",
     inputSchema: {
         type: z
@@ -1876,7 +1918,7 @@ server.registerTool("diviops_variable_list", {
         ],
     };
 });
-server.registerTool("diviops_variable_create", {
+registerPluginTool("diviops_variable_create", {
     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. All-px inputs emit px (safe default, 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 for correct rem emission on non-16px-root sites). Mutually exclusive with value.',
     inputSchema: {
         type: z
@@ -1944,7 +1986,7 @@ server.registerTool("diviops_variable_create", {
         ],
     };
 });
-server.registerTool("diviops_variable_create_fluid_system", {
+registerPluginTool("diviops_variable_create_fluid_system", {
     description: "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. Each category is independent and optional. Use for: (1) bootstrapping a design system in one call instead of 20+ individual diviops_variable_create invocations; (2) mirroring ET's variable layout so your tokens coexist with VB-generated ones in the Variable Manager; (3) deterministic preflight via dry_run before committing the registry change. By default, refuses to overwrite existing IDs (returns them in `skipped`) — pass overwrite=true to update in place. Persists in a single atomic write to the variable registry; mid-batch failures roll back cleanly.",
     inputSchema: {
         profile: z
@@ -2112,7 +2154,7 @@ server.registerTool("diviops_variable_create_fluid_system", {
         ],
     };
 });
-server.registerTool("diviops_variable_delete", {
+registerPluginTool("diviops_variable_delete", {
     description: "Delete a design token variable by ID. Auto-detects storage from ID prefix (gcid-* = colors, gvid-* = numbers/strings/etc). Returns HTTP 409 when live references exist unless force=true — run diviops_variable_scan_orphans to see where the references live. Returns HTTP 403 for Divi's customizer-bound defaults (gcid-primary-color, gcid-secondary-color, gcid-heading-color, gcid-body-color, gcid-link-color); those are managed via WP Customizer theme options and can't be deleted via this tool.",
     inputSchema: {
         id: z
@@ -2135,7 +2177,7 @@ server.registerTool("diviops_variable_delete", {
         ],
     };
 });
-server.registerTool("diviops_variable_scan_orphans", {
+registerPluginTool("diviops_variable_scan_orphans", {
     description: "Scan pages, Theme Builder layouts (header/body/footer), Divi Library items, canvas pages, and the preset registry for gvid-/gcid- references that have no backing entry in the Variable Manager (orphans), plus variables defined but referenced nowhere (unused). Orphans render as invalid CSS on the frontend — the $variable()$ resolver falls through with no fallback. Use after a deletion with force=true, or periodically as a hygiene check. Symmetric to diviops_preset_scan_orphans.",
 }, async () => {
     const result = await wp.request("/variable/scan-orphans");
@@ -2145,7 +2187,7 @@ server.registerTool("diviops_variable_scan_orphans", {
         ],
     };
 });
-server.registerTool("diviops_variable_used_on_page", {
+registerPluginTool("diviops_variable_used_on_page", {
     description: "Detect which numeric/font variable IDs a single page actually 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 Theme Builder header/body/footer template content + appended canvas content (interaction targets etc.), plus presets referenced by that content. NOTE: this is `gvid-*` only — color variables (`gcid-*`) are emitted via a separate path (`GlobalData` color block) that is NOT scoped per-page in 5.4.0; this tool returns gvid IDs only. Use for per-page orphan validation (complements global diviops_variable_scan_orphans), preflight before bulk variable rename (know which pages are affected), or to debug why a numeric/font variable doesn't render on a specific page. Read-only. Returns variable_ids (sorted, deduped), count, and the tb_template_ids resolved for that post.",
     inputSchema: {
         post_id: z
@@ -2162,7 +2204,7 @@ server.registerTool("diviops_variable_used_on_page", {
         ],
     };
 });
-server.registerTool("diviops_meta_flush_cache", {
+registerPluginTool("diviops_meta_flush_cache", {
     description: "Flush Divi's compiled static CSS cache under wp-content/et-cache/. wp cache flush does NOT touch these files — the frontend can keep serving stale CSS after a preset/variable/module mutation until the cache is cleared. Delegates to Divi's native ET_Core_PageResource::remove_static_resources when available (response backend: \"divi_native\"), which additionally clears Theme Builder CSS scattered across other post dirs, archive/taxonomy/home/notfound CSS, the object cache, module features cache, post features cache, Google Fonts cache, dynamic assets cache, and post meta caches. Falls back to a targeted filesystem walk of numeric-named et-cache subdirs when the Divi class is absent (backend: \"fs_fallback\"). Provide exactly one selector — no site-wide default to prevent accidental full flush. Idempotent: missing cache root returns 200 with empty list.",
     inputSchema: {
         post_id: z
@@ -2203,24 +2245,38 @@ server.registerTool("diviops_meta_flush_cache", {
 });
 // ── Start ────────────────────────────────────────────────────────────
 async function main() {
-    // Version handshake — verify plugin compatibility before accepting tool calls.
+    // Capability handshake — populate the per-tool gate map (#486).
     try {
         const hs = await wp.handshake(SERVER_VERSION);
+        handshakeState = {
+            kind: "ok",
+            capabilities: hs.capabilities,
+            pluginVersion: hs.plugin_version,
+        };
         const diviInfo = hs.divi.active
             ? `Divi ${hs.divi.version ?? "unknown"}`
             : "Divi not active";
-        console.error(`Handshake OK: plugin ${hs.plugin_version}, ${diviInfo}, ${hs.capabilities.length} capabilities`);
+        const capCount = Object.keys(hs.capabilities).filter((k) => hs.capabilities[k]).length;
+        console.error(`Handshake OK: plugin ${hs.plugin_version}, ${diviInfo}, ${capCount} capabilities`);
+        if (capCount === 0) {
+            console.error("Warning: plugin returned an empty capability map. Plugin-touching tools will fail with an upgrade hint. Update diviops-agent to ≥1.2.0.");
+        }
     }
     catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
-        // Version mismatch — fatal (HTTP 426 from plugin, or client-side minimum check).
-        if (msg.includes("WordPress API error (426)") ||
-            msg.includes("below the minimum required")) {
-            console.error(`Version mismatch: ${msg}`);
+        // Plugin rejected this server as too old (HTTP 426) — fatal.
+        if (msg.includes("WordPress API error (426)")) {
+            console.error(`Server too old for plugin: ${msg}`);
             process.exit(1);
         }
-        // Other errors (network, auth) — warn but continue, tools will fail individually.
-        console.error(`Handshake warning: ${msg}`);
+        // Network / auth / other transient failure — mark the gate as
+        // failed so plugin-touching tools fall through to their own
+        // wp.request() calls and surface the real error (401, 5xx, etc.)
+        // instead of being misreported as missing capabilities.
+        // Codex review on PR #525: pre-#486 behavior surfaced the actual
+        // cause; the gate must preserve that.
+        handshakeState = { kind: "failed" };
+        console.error(`Handshake warning (gate disabled): ${msg}`);
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/wp-client.d.ts

@@ -30,12 +30,17 @@ export declare class WPClient {
         message: string;
     }>;
     /**
-     * Perform version handshake with the WP plugin.
+     * Perform a capability handshake with the WP plugin.
      *
-     * Verifies that the plugin version is compatible with this server.
-     * Throws on:
-     * - Network errors or any non-2xx HTTP response (401/403/426/503).
-     * - Plugin version below {@link MIN_PLUGIN_VERSION}.
+     * As of #486 there is no global plugin-version floor — compatibility is
+     * decided per-tool against `result.capabilities`. This method only:
+     *  - issues the request (network/auth errors propagate)
+     *  - normalizes the legacy pre-1.2.0 shape (`capabilities: string[]`)
+     *    into the post-1.2.0 shape (`capabilities: Record<string,boolean>`)
+     *    so the rest of the server can assume a uniform map.
+     *
+     * The plugin still rejects servers below its own MIN_SERVER_VERSION
+     * with HTTP 426 — that error surfaces here as a regular request error.
      */
     handshake(serverVersion: string): Promise<HandshakeResult>;
 }

package/dist/wp-client.js

@@ -4,7 +4,6 @@
  * Uses WP Application Passwords (built into WP 5.6+) for auth.
  * Generate one at: WP Admin → Users → Your Profile → Application Passwords.
  */
-import { MIN_PLUGIN_VERSION, compareVersions, } from './compatibility.js';
 /**
  * Normalize quote-escape pathologies inside `$variable(...)$` token regions only.
  *
@@ -161,22 +160,33 @@ export class WPClient {
         }
     }
     /**
-     * Perform version handshake with the WP plugin.
+     * Perform a capability handshake with the WP plugin.
      *
-     * Verifies that the plugin version is compatible with this server.
-     * Throws on:
-     * - Network errors or any non-2xx HTTP response (401/403/426/503).
-     * - Plugin version below {@link MIN_PLUGIN_VERSION}.
+     * As of #486 there is no global plugin-version floor — compatibility is
+     * decided per-tool against `result.capabilities`. This method only:
+     *  - issues the request (network/auth errors propagate)
+     *  - normalizes the legacy pre-1.2.0 shape (`capabilities: string[]`)
+     *    into the post-1.2.0 shape (`capabilities: Record<string,boolean>`)
+     *    so the rest of the server can assume a uniform map.
+     *
+     * The plugin still rejects servers below its own MIN_SERVER_VERSION
+     * with HTTP 426 — that error surfaces here as a regular request error.
      */
     async handshake(serverVersion) {
         const result = await this.request('/handshake', {
             method: 'POST',
             body: { mcp_server_version: serverVersion },
         });
-        // Server-side check passed — now verify plugin meets our minimum.
-        if (compareVersions(result.plugin_version, MIN_PLUGIN_VERSION) < 0) {
-            throw new Error(`WP plugin version ${result.plugin_version} is below the minimum required ${MIN_PLUGIN_VERSION}. ` +
-                'Please update the diviops-agent plugin.');
+        // Pre-1.2.0 plugins emit `capabilities` as a string[] of coarse
+        // namespace tags. Coerce to an empty map so per-tool gates fail fast
+        // with the upgrade hint instead of silently passing because of a
+        // shape mismatch.
+        if (Array.isArray(result.capabilities)) {
+            result.capabilities = {};
+        }
+        else if (result.capabilities === null ||
+            typeof result.capabilities !== 'object') {
+            result.capabilities = {};
         }
         return result;
     }

package/package.json

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