@diviops/mcp-server 1.5.3 → 1.5.5

package/dist/envelope.d.ts

@@ -110,8 +110,44 @@ export declare function wrapResponse<T>(producer: () => Promise<T | DiviopsRespo
  * (e.g. shrink schema, project fields) without unwrapping by hand.
  */
 export declare function envelopeMap<T, U>(response: DiviopsResponse<T>, fn: (data: T) => U): DiviopsResponse<U>;
+/**
+ * Idempotency vocabulary surfaced to clients via `_meta.idempotent` on
+ * every tool response (#597). Mirrors the registration-level `_meta.idempotent`
+ * declared at each `registerTool()` callsite so per-call consumers see the
+ * field where they naturally look (response envelope), not just at
+ * `tools/list` discovery time.
+ */
+export type IdempotentVerdict = "true" | "false" | "conditional";
+/**
+ * Record a tool's idempotency verdict at registration time so per-call
+ * `serializeEnvelope(result, toolName)` can emit it on every response.
+ * Throws if the registration is missing `_meta.idempotent` — fail-loud
+ * matches `feedback_explicit_reject_over_silent_sanitize`: a tool that
+ * skipped the audit would silently lack the field, defeating #597.
+ */
+export declare function recordIdempotent(name: string, meta: {
+    idempotent?: string;
+} | undefined): void;
+/**
+ * Look up a tool's idempotency verdict. Returns undefined if the tool
+ * hasn't been recorded — caller decides whether to fail or skip emission.
+ */
+export declare function getRecordedIdempotent(name: string): IdempotentVerdict | undefined;
+/**
+ * Snapshot of the recorded table — used by tests + the CI gate. Returns
+ * a fresh object so callers can't mutate the live registry.
+ */
+export declare function snapshotIdempotentTable(): Record<string, IdempotentVerdict>;
 /**
  * Serialize a `DiviopsResponse` as the JSON string an MCP tool emits in its
  * `content[0].text` slot. Single emit point keeps the wire shape consistent.
+ *
+ * When `toolName` is provided AND the tool has been recorded via
+ * `recordIdempotent()`, injects `_meta.idempotent` onto the response
+ * envelope before serialization (#597). Per-call emission is a strict
+ * superset of the `tools/list` registration-level `_meta` surface — both
+ * keep working, per-call consumers get the field where they look. Applied
+ * to ok:true AND ok:false envelopes since idempotency is a property of
+ * the tool, not the call outcome.
  */
-export declare function serializeEnvelope<T>(response: DiviopsResponse<T>): string;
+export declare function serializeEnvelope<T>(response: DiviopsResponse<T>, toolName?: string): string;

package/dist/envelope.js

@@ -162,10 +162,71 @@ export function envelopeMap(response, fn) {
         return { ok: true, data: fn(response.data) };
     return response;
 }
+/**
+ * Tool-name → idempotent-verdict registry, populated at server startup by
+ * `recordIdempotent()` from each tool's registration `_meta`. The audit
+ * doc (`docs/idempotency-audit.md`) remains the single source of truth;
+ * this table is just the runtime mirror used to enrich per-call responses.
+ */
+const IDEMPOTENT_TABLE = new Map();
+/**
+ * Record a tool's idempotency verdict at registration time so per-call
+ * `serializeEnvelope(result, toolName)` can emit it on every response.
+ * Throws if the registration is missing `_meta.idempotent` — fail-loud
+ * matches `feedback_explicit_reject_over_silent_sanitize`: a tool that
+ * skipped the audit would silently lack the field, defeating #597.
+ */
+export function recordIdempotent(name, meta) {
+    const verdict = meta?.idempotent;
+    if (verdict !== "true" && verdict !== "false" && verdict !== "conditional") {
+        throw new Error(`Tool '${name}' is missing or has invalid _meta.idempotent declaration ` +
+            `(got: ${verdict === undefined ? "undefined" : JSON.stringify(verdict)}). ` +
+            `Every tool must declare idempotent: "true" | "false" | "conditional" ` +
+            `per docs/idempotency-audit.md.`);
+    }
+    IDEMPOTENT_TABLE.set(name, verdict);
+}
+/**
+ * Look up a tool's idempotency verdict. Returns undefined if the tool
+ * hasn't been recorded — caller decides whether to fail or skip emission.
+ */
+export function getRecordedIdempotent(name) {
+    return IDEMPOTENT_TABLE.get(name);
+}
+/**
+ * Snapshot of the recorded table — used by tests + the CI gate. Returns
+ * a fresh object so callers can't mutate the live registry.
+ */
+export function snapshotIdempotentTable() {
+    return Object.fromEntries(IDEMPOTENT_TABLE.entries());
+}
 /**
  * Serialize a `DiviopsResponse` as the JSON string an MCP tool emits in its
  * `content[0].text` slot. Single emit point keeps the wire shape consistent.
+ *
+ * When `toolName` is provided AND the tool has been recorded via
+ * `recordIdempotent()`, injects `_meta.idempotent` onto the response
+ * envelope before serialization (#597). Per-call emission is a strict
+ * superset of the `tools/list` registration-level `_meta` surface — both
+ * keep working, per-call consumers get the field where they look. Applied
+ * to ok:true AND ok:false envelopes since idempotency is a property of
+ * the tool, not the call outcome.
  */
-export function serializeEnvelope(response) {
-    return JSON.stringify(response);
+export function serializeEnvelope(response, toolName) {
+    if (toolName === undefined) {
+        return JSON.stringify(response);
+    }
+    const verdict = IDEMPOTENT_TABLE.get(toolName);
+    if (verdict === undefined) {
+        return JSON.stringify(response);
+    }
+    const existingMetaRaw = response._meta;
+    const existingMeta = typeof existingMetaRaw === "object" && existingMetaRaw !== null
+        ? existingMetaRaw
+        : {};
+    const enriched = {
+        ...response,
+        _meta: { ...existingMeta, idempotent: verdict },
+    };
+    return JSON.stringify(enriched);
 }

package/dist/index.js

@@ -13,7 +13,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { WPClient } from "./wp-client.js";
 import { MissingCapabilityError } from "./compatibility.js";
-import { ErrorCodes, envelopeMap, serializeEnvelope, withCode, wrapResponse, } from "./envelope.js";
+import { ErrorCodes, envelopeMap, recordIdempotent, serializeEnvelope, withCode, wrapResponse, } from "./envelope.js";
 import { optimizeSchema } from "./schema-optimizer.js";
 import { createWpCli } from "./wp-cli.js";
 import { findForeignVarRefs, scanAttrsForForeignVarRefs, isolationErrorResult, } from "./validate-attrs.js";
@@ -122,8 +122,20 @@ function registerPluginTool(name, config, handler) {
         }
         return handler(args);
     });
+    recordIdempotent(name, config?._meta);
     server.registerTool(name, config, wrapped);
 }
+/**
+ * Server-local tools (no plugin dependency) register via this thin shim
+ * instead of `server.registerTool` directly. Same recording obligation
+ * as `registerPluginTool` — every tool surface needs `_meta.idempotent`
+ * captured into the runtime table so `serializeEnvelope(result, name)`
+ * can emit it on per-call responses (#597).
+ */
+function registerLocalTool(name, config, handler) {
+    recordIdempotent(name, config?._meta);
+    server.registerTool(name, config, handler);
+}
 /* eslint-enable @typescript-eslint/no-explicit-any */
 // ── dry_run convention ──────────────────────────────────────────────
 //
@@ -172,7 +184,7 @@ registerPluginTool("diviops_page_list", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_page_list") },
         ],
     };
 });
@@ -187,7 +199,7 @@ registerPluginTool("diviops_page_get", {
     const result = await wp.requestEnveloped(`/page/get/${page_id}`);
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_page_get") },
         ],
     };
 });
@@ -209,7 +221,7 @@ registerPluginTool("diviops_page_get_layout", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_page_get_layout") },
         ],
     };
 });
@@ -221,7 +233,7 @@ registerPluginTool("diviops_schema_list_modules", {
     const result = await wp.requestEnveloped("/schema/modules");
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_schema_list_modules") },
         ],
     };
 });
@@ -263,12 +275,12 @@ registerPluginTool("diviops_schema_get_module", {
                 },
             };
             return {
-                content: [{ type: "text", text: serializeEnvelope(failure) }],
+                content: [{ type: "text", text: serializeEnvelope(failure, "diviops_schema_get_module") }],
             };
         }
         const result = await wp.requestEnveloped("/schema/module/dump-all");
         return {
-            content: [{ type: "text", text: serializeEnvelope(result) }],
+            content: [{ type: "text", text: serializeEnvelope(result, "diviops_schema_get_module") }],
         };
     }
     if (!module_name) {
@@ -280,14 +292,14 @@ registerPluginTool("diviops_schema_get_module", {
             },
         };
         return {
-            content: [{ type: "text", text: serializeEnvelope(failure) }],
+            content: [{ type: "text", text: serializeEnvelope(failure, "diviops_schema_get_module") }],
         };
     }
     const result = await wp.requestEnveloped(`/schema/module/${encodeURIComponent(module_name)}`);
     const projected = envelopeMap(result, (data) => raw ? data : optimizeSchema(data));
     return {
         content: [
-            { type: "text", text: serializeEnvelope(projected) },
+            { type: "text", text: serializeEnvelope(projected, "diviops_schema_get_module") },
         ],
     };
 });
@@ -299,7 +311,7 @@ registerPluginTool("diviops_schema_get_settings", {
     const result = await wp.requestEnveloped("/schema/settings");
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_schema_get_settings") },
         ],
     };
 });
@@ -311,7 +323,7 @@ registerPluginTool("diviops_global_color_list", {
     const result = await wp.requestEnveloped("/global-color/list");
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_global_color_list") },
         ],
     };
 });
@@ -354,7 +366,7 @@ registerPluginTool("diviops_global_color_create", {
         method: "POST",
         body,
     });
-    return { content: [{ type: "text", text: serializeEnvelope(result) }] };
+    return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_global_color_create") }] };
 });
 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. NOTE: the underlying upsert is merge-mode — supplying a gcid that doesn't yet exist creates a new color with that gcid (provided it satisfies the gcid charset/length rules) rather than failing as 'not found'. Pre-check via diviops_global_color_list if you need strict-update semantics. 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. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; malformed gcid charset/length returns code 'invalid_input' with `error.data` documenting the failed field; non-CSS color value returns code 'invalid_input'; attempts to write to a customizer-bound default (gcid-primary-color / gcid-secondary-color / gcid-heading-color / gcid-body-color / gcid-link-color) return code 'variable.customizer_default_immutable' (HTTP 403) with `error.data = { id, managed_by: 'wp_customizer' }` — same code as diviops_variable_delete because the identity is identical (5.4+ unified gcid-* into the variable manager while preserving customizer-binding for the five legacy defaults)." +
@@ -400,10 +412,10 @@ registerPluginTool("diviops_global_color_update", {
         method: "POST",
         body,
     });
-    return { content: [{ type: "text", text: serializeEnvelope(result) }] };
+    return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_global_color_update") }] };
 });
 registerPluginTool("diviops_global_color_delete", {
-    description: "Delete a global color from the registry by gcid. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }. Live-reference soft-block: returns code 'conflict' (HTTP 409) when Divi's `usedInPosts` index lists references — `error.data = { id, ref_count, used_in_posts }` carries Divi's pass-through reference list (Divi-maintained on VB save; element shape is whatever Divi emits, NOT the discriminated-union `locations[]` shape diviops_variable_delete builds via parse_blocks). Pass `force: true` to override; 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 — returns code 'variable.customizer_default_immutable' (HTTP 403) with `error.data = { id, managed_by: 'wp_customizer' }`. Missing gcids return 'not_found' (HTTP 404). Malformed gcid (empty or missing `gcid-` prefix) returns 'invalid_input'. 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." +
+    description: "Delete a global color from the registry by gcid. 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 (mirrors diviops_variable_delete) — MCP-authored content is detected reliably, not just VB-saved content. 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 render as invalid CSS until pages are re-authored. 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 — returns code 'variable.customizer_default_immutable' (HTTP 403) with `error.data = { id, managed_by: 'wp_customizer' }`. Missing gcids return 'not_found' (HTTP 404). Malformed gcid (empty or missing `gcid-` prefix) returns 'invalid_input'. 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." +
         DRY_RUN_DESC_SUFFIX,
     inputSchema: {
         gcid: z
@@ -413,7 +425,7 @@ registerPluginTool("diviops_global_color_delete", {
             .boolean()
             .optional()
             .default(false)
-            .describe("If true, delete even when usedInPosts shows live references. Customizer-bound defaults remain protected regardless."),
+            .describe("If true, delete even when live references exist. Customizer-bound defaults remain protected regardless."),
         dry_run: DRY_RUN_FIELD,
     },
     annotations: { idempotentHint: true },
@@ -428,7 +440,7 @@ registerPluginTool("diviops_global_color_delete", {
         method: "POST",
         body,
     });
-    return { content: [{ type: "text", text: serializeEnvelope(result) }] };
+    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? } }.",
@@ -438,7 +450,7 @@ registerPluginTool("diviops_global_font_list", {
     const result = await wp.requestEnveloped("/global-font/list");
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_global_font_list") },
         ],
     };
 });
@@ -465,7 +477,7 @@ registerPluginTool("diviops_meta_find_icon", {
     const result = await wp.requestEnveloped(`/meta/find-icon?q=${encodeURIComponent(query)}&type=${type ?? "all"}&limit=${limit ?? 10}`);
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_meta_find_icon") },
         ],
     };
 });
@@ -495,7 +507,7 @@ registerPluginTool("diviops_page_update_content", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_page_update_content") },
         ],
     };
 });
@@ -513,7 +525,7 @@ registerPluginTool("diviops_render_preview", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_render_preview") },
         ],
     };
 });
@@ -531,7 +543,7 @@ registerPluginTool("diviops_validate_blocks", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_validate_blocks") },
         ],
     };
 });
@@ -565,7 +577,7 @@ registerPluginTool("diviops_section_append", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_section_append") },
         ],
     };
 });
@@ -613,7 +625,7 @@ registerPluginTool("diviops_section_replace", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_section_replace") },
         ],
     };
 });
@@ -655,7 +667,7 @@ registerPluginTool("diviops_section_remove", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_section_remove") },
         ],
     };
 });
@@ -691,7 +703,7 @@ registerPluginTool("diviops_section_get", {
     const result = await wp.requestEnveloped(`/section/get/${page_id}?${qs}`);
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_section_get") },
         ],
     };
 });
@@ -747,7 +759,7 @@ registerPluginTool("diviops_module_update", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_module_update") },
         ],
     };
 });
@@ -827,7 +839,7 @@ registerPluginTool("diviops_module_move", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_module_move") },
         ],
     };
 });
@@ -857,7 +869,7 @@ registerPluginTool("diviops_module_lock", {
     if (dry_run)
         body.dry_run = true;
     const result = await wp.requestEnveloped(`/module/lock/${page_id}`, { method: "POST", body });
-    return { content: [{ type: "text", text: serializeEnvelope(result) }] };
+    return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_module_lock") }] };
 });
 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. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; missing module returns 'not_found' with `error.data.target_kind = \"module\"`." +
@@ -885,7 +897,7 @@ registerPluginTool("diviops_module_unlock", {
     if (dry_run)
         body.dry_run = true;
     const result = await wp.requestEnveloped(`/module/unlock/${page_id}`, { method: "POST", body });
-    return { content: [{ type: "text", text: serializeEnvelope(result) }] };
+    return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_module_unlock") }] };
 });
 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. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; missing module returns code "not_found" with error.data.target_kind = "module", malformed parent containers surface code "divi_error" (HTTP 500).' +
@@ -916,7 +928,7 @@ registerPluginTool("diviops_module_clone", {
     if (dry_run)
         body.dry_run = true;
     const result = await wp.requestEnveloped(`/module/clone/${page_id}`, { method: "POST", body });
-    return { content: [{ type: "text", text: serializeEnvelope(result) }] };
+    return { content: [{ type: "text", text: serializeEnvelope(result, "diviops_module_clone") }] };
 });
 registerPluginTool("diviops_page_create", {
     description: "Create a new WordPress page, optionally with Divi block content. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; non-string content or invalid status return code 'invalid_input' with `error.data` documenting the failed field." +
@@ -952,7 +964,7 @@ registerPluginTool("diviops_page_create", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_page_create") },
         ],
     };
 });
@@ -983,7 +995,7 @@ registerPluginTool("diviops_page_trash", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_page_trash") },
         ],
     };
 });
@@ -1019,7 +1031,7 @@ registerPluginTool("diviops_page_update_status", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_page_update_status") },
         ],
     };
 });
@@ -1032,7 +1044,7 @@ registerPluginTool("diviops_preset_audit", {
     const result = await wp.requestEnveloped("/preset/audit");
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_preset_audit") },
         ],
     };
 });
@@ -1080,7 +1092,7 @@ registerPluginTool("diviops_preset_cleanup", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_preset_cleanup") },
         ],
     };
 });
@@ -1119,7 +1131,7 @@ registerPluginTool("diviops_preset_update", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_preset_update") },
         ],
     };
 });
@@ -1144,7 +1156,7 @@ registerPluginTool("diviops_preset_delete", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_preset_delete") },
         ],
     };
 });
@@ -1210,7 +1222,7 @@ registerPluginTool("diviops_preset_create", {
     const result = await wp.requestEnveloped("/preset/create", { method: "POST", body });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_preset_create") },
         ],
     };
 });
@@ -1261,7 +1273,7 @@ registerPluginTool("diviops_preset_reassign", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_preset_reassign") },
         ],
     };
 });
@@ -1273,7 +1285,7 @@ registerPluginTool("diviops_preset_scan_orphans", {
     const result = await wp.requestEnveloped("/preset/scan-orphans");
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_preset_scan_orphans") },
         ],
     };
 });
@@ -1319,7 +1331,7 @@ registerPluginTool("diviops_preset_set_default", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_preset_set_default") },
         ],
     };
 });
@@ -1354,7 +1366,7 @@ registerPluginTool("diviops_library_list", {
     const result = await wp.requestEnveloped("/library/items", { params });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_library_list") },
         ],
     };
 });
@@ -1369,7 +1381,7 @@ registerPluginTool("diviops_library_get", {
     const result = await wp.requestEnveloped(`/library/item/${item_id}`);
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_library_get") },
         ],
     };
 });
@@ -1405,7 +1417,7 @@ registerPluginTool("diviops_library_save", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_library_save") },
         ],
     };
 });
@@ -1432,7 +1444,7 @@ registerPluginTool("diviops_tb_template_list", {
     const result = await wp.requestEnveloped("/theme-builder/template/list", { params });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_tb_template_list") },
         ],
     };
 });
@@ -1449,7 +1461,7 @@ registerPluginTool("diviops_tb_layout_get", {
     const result = await wp.requestEnveloped(`/theme-builder/layout/get/${layout_id}`);
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_tb_layout_get") },
         ],
     };
 });
@@ -1473,7 +1485,7 @@ registerPluginTool("diviops_tb_layout_update", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_tb_layout_update") },
         ],
     };
 });
@@ -1509,13 +1521,13 @@ registerPluginTool("diviops_tb_template_create", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_tb_template_create") },
         ],
     };
 });
 // ── Canvas Tools ────────────────────────────────────────────────────
 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. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; missing parent_page_id returns ok:false with code 'not_found'; non-string content / malformed canvas_id / append_to_main outside {above, below} returns 'invalid_input'." +
+    description: "Create a canvas (off-canvas workspace) linked to a page. Used for popups, off-canvas menus, modals. Content uses standard Divi block markup. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; missing parent_page_id returns ok:false with code 'not_found'; non-string content / malformed canvas_id / append_to_main outside {above, below} returns 'invalid_input'. Returns code 'conflict' (HTTP 409) when a canvas with the same title already exists under the same parent_page_id — error.data = { existing_canvas_id, parent_page_id, title }. Mirrors diviops_preset_create's uniqueness contract." +
         DRY_RUN_DESC_SUFFIX,
     inputSchema: {
         title: z
@@ -1542,7 +1554,7 @@ registerPluginTool("diviops_canvas_create", {
         dry_run: DRY_RUN_FIELD,
     },
     annotations: { idempotentHint: false },
-    _meta: { idempotent: "false" },
+    _meta: { idempotent: "conditional" },
 }, async ({ title, parent_page_id, content, canvas_id, append_to_main, z_index, dry_run, }) => {
     const body = {
         title,
@@ -1560,7 +1572,7 @@ registerPluginTool("diviops_canvas_create", {
     const result = await wp.requestEnveloped("/canvas/create", { method: "POST", body });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_canvas_create") },
         ],
     };
 });
@@ -1591,7 +1603,7 @@ registerPluginTool("diviops_canvas_list", {
     const result = await wp.requestEnveloped("/canvas/list", { params });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_canvas_list") },
         ],
     };
 });
@@ -1608,7 +1620,7 @@ registerPluginTool("diviops_canvas_get", {
     const result = await wp.requestEnveloped(`/canvas/get/${canvas_post_id}`);
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_canvas_get") },
         ],
     };
 });
@@ -1649,7 +1661,7 @@ registerPluginTool("diviops_canvas_update", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_canvas_update") },
         ],
     };
 });
@@ -1679,7 +1691,7 @@ registerPluginTool("diviops_canvas_duplicate", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_canvas_duplicate") },
         ],
     };
 });
@@ -1702,12 +1714,12 @@ registerPluginTool("diviops_canvas_delete", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_canvas_delete") },
         ],
     };
 });
 // ── WP-CLI ──────────────────────────────────────────────────────────
-server.registerTool("diviops_meta_wp_cli", {
+registerLocalTool("diviops_meta_wp_cli", {
     description: "Run a WP-CLI command on the WordPress site. Requires WP_PATH env var (LOCAL_SITE_ID auto-detected from Local by Flywheel), or WP_CLI_CMD for containerized wrappers. Commands validated against a safety allowlist. Default tier covers read ops across options/posts/post-types/taxonomies/users/info/core/db, non-destructive writes (post/term create+update, post meta read/write, cache/rewrite/transient flush, `plugin update` from authenticated sources), ACF/SCF schema ops (`acf export/import/field-group list/get` plus SCF 6.8.4+ `scf json {status,sync,import,export}` and the `acf json …` aliases), and WXR export. Extended tier (requires DIVIOPS_WP_CLI_ALLOW env var) adds destructive or bulk-modifying ops: option update, post/post meta/term delete, search-replace, import, plugin activate/deactivate, eval-file. Filesystem-touching commands (`wp export`, `acf export/import`, `scf|acf json export/import`) are additionally constrained: path arguments must resolve under a safe root (defaults to `<WP_PATH>/.diviops-tmp/`, overridable via DIVIOPS_WP_CLI_SAFE_FS_ROOT, disable via DIVIOPS_WP_CLI_UNSAFE_FS=1); `wp export` and `scf json export` require an explicit `--dir=<path>` (or `--stdout`). In WP_CLI_CMD wrapper mode, DIVIOPS_WP_CLI_SAFE_FS_ROOT is required for FS-sensitive commands. Prefer the typed `diviops_scf_*` wrappers for SCF round-trips — they're easier to invoke and accept the same safe-root scoping. Use --format=json for structured output. Full allowlist + tier rationale + filesystem semantics in the MCP server README. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }. Success payload: { stdout: string, stderr: string, exit_code: 0 }. Four failure modes converge on 'meta_wp_cli.command_failed' with error.data = { exit_code: number | null, stdout: string, stderr: string }: (a) numeric exit_code — wp-cli ran and exited non-zero; stdout/stderr are raw streams verbatim. (b) exit_code=null and message starts with 'wp-cli command terminated:' — execFile launched the child but it was killed (timeout or signal); stdout/stderr carry whatever streamed before the kill. (c) exit_code=null and message starts with 'wp-cli could not spawn:' — the OS refused to start the child (ENOENT/EACCES/EPERM); child never ran, stdout/stderr are empty. (d) exit_code=null and message is the rejection reason — pre-execution rejection by the allowlist / FS validator; rejection reason synthesized into error.data.stderr because the child never ran. A missing wp-cli configuration surfaces as 'meta_wp_cli.not_configured'. stdout is always passed through as a string (no server-side JSON parse) — pass --format=json and parse on the caller side when you want structured output.",
     inputSchema: {
         command: z
@@ -1803,7 +1815,7 @@ server.registerTool("diviops_meta_wp_cli", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_meta_wp_cli") },
         ],
     };
 });
@@ -1894,7 +1906,7 @@ function failScfCommand(result, args) {
         command: [...args],
     });
 }
-server.registerTool("diviops_scf_status", {
+registerLocalTool("diviops_scf_status", {
     description: "Show SCF (Secure Custom Fields) sync status — how many field groups, post types, taxonomies, and options pages have JSON-on-disk newer than the database (or absent from DB). Read-only. Wraps `wp scf json status`. Requires SCF 6.8.4+ and WP_PATH or WP_CLI_CMD. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { stdout: string, stderr: string }. wp-cli failures map to 'scf.command_failed' with `error.data = { exit_code, stdout, stderr, failure_kind, command }` (four failure_kind branches: 'exited'/'killed'/'spawn_failed'/'rejected' — see tools.md). Missing wp-cli configuration surfaces as 'scf.not_configured'.",
     inputSchema: {
         type: z
@@ -1922,11 +1934,11 @@ server.registerTool("diviops_scf_status", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_scf_status") },
         ],
     };
 });
-server.registerTool("diviops_scf_export", {
+registerLocalTool("diviops_scf_export", {
     description: "Export SCF field groups, post types, taxonomies, and options pages as JSON — to a directory under the safe-root (`<WP_PATH>/.diviops-tmp/` by default, override via DIVIOPS_WP_CLI_SAFE_FS_ROOT) or to stdout. Wraps `wp scf json export`. Either `dir` or `stdout: true` is required. Filters can be combined; without filters, all items are exported. Note: SCF writes a fixed filename `acf-export-YYYY-MM-DD.json` inside `dir` — two exports on the same day silently overwrite. Copy/rename if you're archiving baselines. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { stdout: string, stderr: string }. Pre-wp-cli input rejections (neither/both of `dir`/`stdout`) return code 'invalid_input' with `error.data` documenting the failed fields. wp-cli failures map to 'scf.command_failed' (same shape as scf_status). Missing wp-cli configuration surfaces as 'scf.not_configured'.",
     inputSchema: {
         dir: z
@@ -1980,11 +1992,11 @@ server.registerTool("diviops_scf_export", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_scf_export") },
         ],
     };
 });
-server.registerTool("diviops_scf_import", {
+registerLocalTool("diviops_scf_import", {
     description: "Import SCF field groups, post types, taxonomies, options pages from a JSON file. Mutates the database. File path must resolve under the safe-root (`<WP_PATH>/.diviops-tmp/` by default, override via DIVIOPS_WP_CLI_SAFE_FS_ROOT). Idempotent — existing items with matching keys are updated. Wraps `wp scf json import <file>`. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { stdout: string, stderr: string }. wp-cli failures (missing/unreadable file, malformed JSON, allowlist or FS-validator rejection) map to 'scf.command_failed' with `error.data = { exit_code, stdout, stderr, failure_kind, command }`. Missing wp-cli configuration surfaces as 'scf.not_configured'.",
     inputSchema: {
         file: z
@@ -2004,11 +2016,11 @@ server.registerTool("diviops_scf_import", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_scf_import") },
         ],
     };
 });
-server.registerTool("diviops_scf_sync", {
+registerLocalTool("diviops_scf_sync", {
     description: "Apply pending JSON-on-disk SCF changes to the database. Reads JSON files from the theme/plugin acf-json directory and creates/updates DB entries. Defaults to `dry_run: true` for safety — caller must opt in to mutation. Wraps `wp scf json sync`. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { dry_run: boolean, stdout: string, stderr: string }. NOTE: `dry_run` is passed through as wp-cli's `--dry-run` flag — the upstream output shape is wp-cli's plain-text summary, NOT the standard `data.plan = { summary, changes[] }` shape used by plugin-routed `dry_run` tools. The `dry_run` boolean is reflected in the success payload so callers can branch without re-checking input args, but the SCF-on-disk preview is what wp-cli produced. wp-cli failures map to 'scf.command_failed'; missing wp-cli configuration surfaces as 'scf.not_configured'.",
     inputSchema: {
         type: z
@@ -2047,11 +2059,11 @@ server.registerTool("diviops_scf_sync", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_scf_sync") },
         ],
     };
 });
-server.registerTool("diviops_scf_field_group_list", {
+registerLocalTool("diviops_scf_field_group_list", {
     description: "List all SCF/ACF field groups in the database (post_name = ACF key, post_title, post_status, post_modified). Read-only. Queries the underlying `acf-field-group` post type via `wp post list` — works on both SCF 6.8.4+ (which dropped the legacy `wp acf field-group …` family in favor of the `wp scf json` namespace) and older ACF installs. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is `Array<{ ID, post_name, post_title, post_status, post_modified }>` parsed from wp-cli's JSON output (or an empty array on no results). wp-cli failures map to 'scf.command_failed'; missing wp-cli configuration surfaces as 'scf.not_configured'.",
     annotations: { idempotentHint: true },
     _meta: { idempotent: "true" },
@@ -2082,11 +2094,11 @@ server.registerTool("diviops_scf_field_group_list", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_scf_field_group_list") },
         ],
     };
 });
-server.registerTool("diviops_scf_field_group_get", {
+registerLocalTool("diviops_scf_field_group_get", {
     description: "Fetch a single SCF/ACF field group from the `acf-field-group` post type — by ACF key (`group_abc123`, looked up via `post_name`) or by numeric WP post ID. Returns the WP post fields (post_name, post_title, post_content with serialized fields blob, post_status, post_modified). For the parsed/structured field tree including nested fields, use `diviops_scf_export --field-groups=<key> --stdout` instead. Read-only. SCF 6.8.4 dropped the legacy `wp acf field-group get` command, so this wrapper queries the post type directly via `wp post`. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is the parsed `wp post get --format=json` object. Unresolvable key (no row in the `acf-field-group` post type and not a numeric ID that wp-cli accepts) returns code 'not_found' with hint pointing to diviops_scf_field_group_list. wp-cli failures map to 'scf.command_failed'; missing wp-cli configuration surfaces as 'scf.not_configured'.",
     inputSchema: {
         key: z
@@ -2157,12 +2169,12 @@ server.registerTool("diviops_scf_field_group_get", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_scf_field_group_get") },
         ],
     };
 });
 // ── Connection ──────────────────────────────────────────────────────
-server.registerTool("diviops_meta_ping", {
+registerLocalTool("diviops_meta_ping", {
     description: "Test the connection to the WordPress site and verify the Divi MCP plugin is active. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is { connected: true, message: \"Connected to Divi <version>\" } and connection failure surfaces as { ok: false, error: { code: 'wp_error', message } } with the underlying transport message preserved.",
     annotations: { idempotentHint: true },
     _meta: { idempotent: "true" },
@@ -2176,11 +2188,11 @@ server.registerTool("diviops_meta_ping", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_meta_ping") },
         ],
     };
 });
-server.registerTool("diviops_meta_info", {
+registerLocalTool("diviops_meta_info", {
     description: "Returns DiviOps MCP server identity, version, license type, and available capabilities. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }.",
     annotations: { idempotentHint: true },
     _meta: { idempotent: "true" },
@@ -2207,7 +2219,7 @@ server.registerTool("diviops_meta_info", {
     }));
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_meta_info") },
         ],
     };
 });
@@ -2305,7 +2317,7 @@ function loadTemplates() {
 }
 const templates = loadTemplates();
 // Register a list tool so Claude can discover available templates
-server.registerTool("diviops_template_list", {
+registerLocalTool("diviops_template_list", {
     description: "List available Divi page section templates. Each template contains verified block markup patterns that can be used as a base for page generation. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; success payload is an array of { name, description, customizable, requires_css }.",
     annotations: { idempotentHint: true },
     _meta: { idempotent: "true" },
@@ -2318,11 +2330,11 @@ server.registerTool("diviops_template_list", {
     })));
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_template_list") },
         ],
     };
 });
-server.registerTool("diviops_template_get", {
+registerLocalTool("diviops_template_get", {
     description: "Get a specific Divi template with verified block markup, customizable variables, and usage notes. Use this to generate pages based on proven patterns. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }. Missing template names return ok:false with code 'not_found' and error.data.available: string[] listing the registered template names.",
     inputSchema: {
         template_name: z
@@ -2341,7 +2353,7 @@ server.registerTool("diviops_template_get", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(response) },
+            { type: "text", text: serializeEnvelope(response, "diviops_template_get") },
         ],
     };
 });
@@ -2369,7 +2381,7 @@ registerPluginTool("diviops_variable_list", {
     const result = await wp.requestEnveloped("/variable/list", { params });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_variable_list") },
         ],
     };
 });
@@ -2443,7 +2455,7 @@ registerPluginTool("diviops_variable_create", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_variable_create") },
         ],
     };
 });
@@ -2613,7 +2625,7 @@ registerPluginTool("diviops_variable_create_fluid_system", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_variable_create_fluid_system") },
         ],
     };
 });
@@ -2643,7 +2655,7 @@ registerPluginTool("diviops_variable_delete", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_variable_delete") },
         ],
     };
 });
@@ -2655,7 +2667,7 @@ registerPluginTool("diviops_variable_scan_orphans", {
     const result = await wp.requestEnveloped("/variable/scan-orphans");
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_variable_scan_orphans") },
         ],
     };
 });
@@ -2674,7 +2686,7 @@ registerPluginTool("diviops_variable_used_on_page", {
     const result = await wp.requestEnveloped(`/variable/used-on-page/${post_id}`);
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_variable_used_on_page") },
         ],
     };
 });
@@ -2720,7 +2732,7 @@ registerPluginTool("diviops_meta_flush_cache", {
     });
     return {
         content: [
-            { type: "text", text: serializeEnvelope(result) },
+            { type: "text", text: serializeEnvelope(result, "diviops_meta_flush_cache") },
         ],
     };
 });

package/package.json

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