@diviops/mcp-server 1.5.6 → 1.5.7

package/README.md

@@ -64,7 +64,7 @@ The skill enforces the Divi block format, the design system, and the response co
 
 ## Tools at a glance
 
-The server exposes **66 tools** across the categories below. Each category links to representative tools; the full table lives in [server-reference.md](../docs/server-reference.md).
+The server exposes **67 tools** across the categories below. Each category links to representative tools; the full table lives in [server-reference.md](../docs/server-reference.md).
 
 | Category | Use case | Tool prefixes |
 |----------|----------|---------------|
@@ -108,6 +108,10 @@ Tools return a standardized envelope. The shape lets clients branch on `ok` and
 
 Namespaces extend the vocabulary using the `<namespace>.<reason>` convention — e.g. `meta_wp_cli.command_failed`, `scf.not_configured`, `preset.bucket_mismatch`, `variable.customizer_default_immutable`. Namespace-prefixed codes carry structured `error.data` documenting the failure (exit codes, conflicting fields, reference counts, etc.). Per-tool descriptions name the codes each tool emits and the `error.data` shape that accompanies them.
 
+### Per-tool `error.data` extensions
+
+Some tools attach a structured `error.data` payload alongside the `code`/`message`/`hint` envelope — e.g. `meta_wp_cli` carries `{ exit_code, stdout, stderr }` on `meta_wp_cli.command_failed`, `global_color_delete` carries `{ id, ref_count, locations[], scan_truncated, scanned_posts[] }` on `conflict`, and conflict-class adopters across `canvas_*`/`library_*`/`variable_*` echo the conflicting fields. The shape is per-tool and documented in each tool's description prose, not in this canonical envelope summary. The summary stays terse because (a) most tools never emit `error.data` and advertising it universally would be misleading, and (b) the per-tool shape diverges and `data?: unknown` would be information-free. The runtime mechanism is `withCode`'s 4th `data` argument (server-local) / `envelope_error()`'s `$data` parameter (plugin-routed); both flow through `wrapResponse` to land on `error.data`.
+
 ### `dry_run` plan shape
 
 Every write tool accepts `dry_run: boolean` (default `false`). When `true`, the response carries a uniform plan shape and no state is mutated:

package/dist/envelope.d.ts

@@ -24,17 +24,21 @@ export type DiviopsErrorBody = {
     message: string;
     hint?: string;
     /**
-     * Optional structured payload attached to the error envelope. Used by
-     * tools whose failure mode carries machine-readable detail beyond a
-     * code/message pair — e.g. `meta_wp_cli` exposes
-     * `error.data = { exit_code, stdout, stderr }` so callers can branch
-     * on the wp-cli exit code without parsing the message string. Tools
-     * that don't need it omit the field entirely.
+     * Optional structured payload attached to the error envelope. Carried
+     * via `withCode`'s 4th `data` argument (server-local) or the plugin's
+     * `envelope_error()` `$data` parameter (plugin-routed) — e.g.
+     * `meta_wp_cli` emits `{ exit_code, stdout, stderr }`,
+     * `global_color_delete` emits `{ id, ref_count, locations[], ... }` on
+     * `conflict`, and conflict-class adopters echo conflicting fields.
      *
-     * Naming convention: when a namespace-specific error code attaches
-     * `data`, list the field shape in the tool's description and in
-     * tools.md "Response shape" so consumers know what to expect per
-     * code without runtime probing.
+     * The shape is per-tool and documented in each tool's description
+     * prose, not in this canonical type. The type stays `unknown` because
+     * (a) most tools never emit `error.data` so advertising it universally
+     * would be misleading, and (b) the per-tool shape diverges and a
+     * concrete union here would be information-free for consumers.
+     *
+     * See `diviops-server/README.md` "Per-tool error.data extensions" for
+     * the codified convention.
      */
     data?: unknown;
 };

package/dist/index.js

@@ -1525,6 +1525,37 @@ registerPluginTool("diviops_tb_template_create", {
         ],
     };
 });
+registerPluginTool("diviops_tb_template_trash", {
+    description: "Trash (or permanently delete) a Theme Builder template AND its linked header/body/footer layouts AND scrub the `_et_template` meta refs on the Theme Builder master post. Closes the orphan-meta gap left by `diviops_page_trash` / wp-cli `post delete` on linked layouts: the typed wrapper does the cleanup atomically. Defaults to trash (reversible via WP Admin → Trash). Pass `force=true` to permanently delete (wp_delete_post — irreversible, one-shot: a repeat call after a successful force-delete returns 'not_found' because the template post is gone from the DB). Idempotency applies to the default trash mode only: a repeat call after a successful trash-mode cleanup returns ok:true with `data.already_trashed = true` (mirrors `diviops_page_trash`). If a prior trash-mode call partially succeeded (some layouts already trashed, master meta still carries refs), the next call detects already-trashed targets via pre-state checks, skips the no-op WP destructor calls (which would otherwise return false), and still runs the meta scrub — `data.linked_layouts[].skipped` and `data.template_skipped` flag the targets that were already at the end-state. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; missing template_id returns 'not_found' (HTTP 404), delete-permission failures return 'forbidden' (HTTP 403); per-step trash/delete/meta-scrub failures return the namespaced 'tb_template.command_failed' (HTTP 500) with `error.data.failed_step` ∈ { 'layout_destroy', 'template_destroy', 'meta_scrub' } plus `template_id` and `force`." +
+        DRY_RUN_DESC_SUFFIX,
+    inputSchema: {
+        template_id: z
+            .number()
+            .int()
+            .describe("Theme Builder template post ID (the `et_template` post). Discover via diviops_tb_template_list — NOT the linked layout IDs."),
+        force: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, permanently delete (skips trash). Default false moves to trash."),
+        dry_run: DRY_RUN_FIELD,
+    },
+    annotations: { idempotentHint: false },
+    _meta: { idempotent: "conditional" },
+}, async ({ template_id, force, dry_run }) => {
+    const result = await wp.requestEnveloped(`/theme-builder/template/trash/${template_id}`, {
+        method: "POST",
+        body: {
+            force: force ?? false,
+            dry_run: dry_run ?? false,
+        },
+    });
+    return {
+        content: [
+            { type: "text", text: serializeEnvelope(result, "diviops_tb_template_trash") },
+        ],
+    };
+});
 // ── 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'. 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." +

package/package.json

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