@diviops/mcp-server 1.5.21 → 1.5.24

package/README.md

@@ -41,11 +41,13 @@ claude mcp add diviops-mcp \
   --env WP_URL=http://your-site.local \
   --env WP_USER=your-wp-username \
   --env WP_APP_PASSWORD=xxxxXXXXxxxxXXXXxxxxXXXX \
-  -- npx @diviops/mcp-server
+  -- npx -y --package @diviops/mcp-server diviops-mcp
 ```
 
 Then ask Claude: **"List the pages on my site."** Claude calls `diviops_page_list` and renders the result. You're authoring with the suite.
 
+For Claude Desktop JSON, use `"command": "npx"` with args `["-y", "--package", "@diviops/mcp-server", "diviops-mcp"]`. The package also ships `diviops-preset`, so the explicit package/bin form is required; `npx @diviops/mcp-server` cannot reliably infer which bin to run.
+
 For a deeper walkthrough (containerized environments, WP-CLI configuration, troubleshooting installation), see [setup-guide.md](../docs/setup-guide.md).
 
 ## Example workflow
@@ -64,7 +66,7 @@ The skill enforces the Divi block format, the design system, and the response co
 
 ## Tools at a glance
 
-The server exposes **73 always-on 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 **74 always-on 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 |
 |----------|----------|---------------|
@@ -219,6 +221,7 @@ The server connects via standard WordPress REST API and works with any environme
 Common quick fixes — full reference in [troubleshooting.md](../docs/troubleshooting.md).
 
 - **"Missing required environment variable(s)"** — ensure `WP_URL`, `WP_USER`, `WP_APP_PASSWORD` are all set on `claude mcp add`.
+- **`npx @diviops/mcp-server` fails with "could not determine executable to run"** — use `npx -y --package @diviops/mcp-server diviops-mcp`; this explicitly selects the MCP server bin.
 - **"Connection failed"** — verify the plugin is active by visiting `{WP_URL}/wp-json/diviops/v1/schema/settings`; test the credentials with `curl -u "user:pass" …`.
 - **"This tool requires plugin capability"** — the plugin doesn't advertise the capability this tool needs. Update the plugin to the latest release.
 - **Preset edits not visible on the frontend** — Divi serves frontend CSS from `wp-content/et-cache/{post_id}/`, which `wp cache flush` doesn't touch. Use `diviops_meta_flush_cache` after preset writes.

package/dist/index.js

@@ -15,6 +15,7 @@ import { WPClient } from "./wp-client.js";
 import { MissingCapabilityError } from "./compatibility.js";
 import { ErrorCodes, envelopeMap, recordIdempotent, serializeEnvelope, withCode, wrapResponse, } from "./envelope.js";
 import { optimizeSchema } from "./schema-optimizer.js";
+import { schemaModuleRoute } from "./schema-route.js";
 import { createWpCli } from "./wp-cli.js";
 import { findForeignVarRefs, scanAttrsForForeignVarRefs, isolationErrorResult, } from "./validate-attrs.js";
 import { readFileSync, readdirSync } from "fs";
@@ -347,7 +348,7 @@ registerPluginTool("diviops_schema_get_module", {
             content: [{ type: "text", text: serializeEnvelope(failure, "diviops_schema_get_module") }],
         };
     }
-    const result = await wp.requestEnveloped(`/schema/module/${encodeURIComponent(module_name)}`);
+    const result = await wp.requestEnveloped(schemaModuleRoute(module_name));
     const projected = envelopeMap(result, (data) => raw ? data : optimizeSchema(data));
     return {
         content: [
@@ -1773,6 +1774,50 @@ registerPluginTool("diviops_tb_layout_update", {
         ],
     };
 });
+registerPluginTool("diviops_tb_layout_block_insert", {
+    description: "Insert one or more serialized Divi blocks into an existing Theme Builder layout without replacing the whole layout. Target a unique parent with `parent_selector` (for example `divi/group[adminLabel=\"Legal Col\"]`, or `divi/group` only when it is unique) or an explicit zero-based `parent_path` from the parsed block tree such as `0.1.2`. `position=append|prepend` inserts as children of the target block; `position=before|after` inserts beside the target within its parent. Ambiguous selectors return ok:false with code 'invalid_input'; missing targets return 'not_found'. The route parses and validates the inserted blocks, rejects malformed pseudo-escapes such as bare `u003c`, validates the final serialized layout before saving, and returns a no-op when the exact requested block sequence already exists at the insertion point." +
+        DRY_RUN_DESC_SUFFIX,
+    inputSchema: {
+        layout_id: z.number().int().describe("Theme Builder layout post ID to mutate"),
+        parent_selector: z
+            .string()
+            .optional()
+            .describe('Unique selector such as `divi/group[adminLabel="Legal Col"]` or `divi/column`. Provide exactly one of parent_selector or parent_path.'),
+        parent_path: z
+            .string()
+            .optional()
+            .describe('Zero-based parsed-tree path such as `0`, `0.1`, or `0.1.2`. Provide exactly one of parent_selector or parent_path.'),
+        position: z
+            .enum(["append", "prepend", "before", "after"])
+            .optional()
+            .default("append")
+            .describe("Where to insert relative to the target block."),
+        content: z.string().describe("One or more serialized Divi blocks to insert"),
+        dry_run: DRY_RUN_FIELD,
+    },
+    annotations: { idempotentHint: false },
+    _meta: { idempotent: "conditional" },
+}, async ({ layout_id, parent_selector, parent_path, position, content, dry_run }) => {
+    const body = {
+        content,
+        position: position ?? "append",
+    };
+    if (parent_selector !== undefined)
+        body.parent_selector = parent_selector;
+    if (parent_path !== undefined)
+        body.parent_path = parent_path;
+    if (dry_run)
+        body.dry_run = true;
+    const result = await wp.requestEnveloped(`/theme-builder/layout/block-insert/${layout_id}`, {
+        method: "POST",
+        body,
+    });
+    return {
+        content: [
+            { type: "text", text: serializeEnvelope(result, "diviops_tb_layout_block_insert") },
+        ],
+    };
+});
 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. Pass condition=\"default\" (case-insensitive) or an empty string to register the template as the catch-all Default Website Template — the route writes the `_et_default = '1'` flag with an empty `_et_use_on`, matching the meta shape Divi's TB router gates the default route on; any other condition string lands in `_et_use_on` unchanged. Default Website Template is a singleton scoped to the active Theme Builder master: if the active master's `_et_template` linked list already names an et_template carrying `_et_default = '1'` (regardless of `_et_enabled` status — the router resolves by linked-list position before checking the enable-gate, so a disabled existing default linked ahead of the new one would still shadow it), the route rejects with code `tb_template.default_already_exists` (HTTP 409) and `error.data.existing_default_id` + `error.data.master_post_id`. Templates outside the active master's linked list (orphan defaults, library-cloned-master defaults) cannot shadow the router's pick and DO NOT block creation. Caller resolves a real conflict by trashing the existing default (diviops_tb_template_trash) or pinning this template to a specific condition; the route never silently flips the existing default's flag or proceeds with non-deterministic router state. If the Theme Builder master post is missing (fresh substrate that never opened Divi → Theme Builder in WP Admin), the route auto-bootstraps one with the same shape Divi creates on first admin visit and returns `data.master_post_bootstrapped: true` so callers can audit the side-effect. Returns the standardized envelope { ok, data?, error: { code, message, hint? } }; failures during master-post bootstrap or template/layout insert surface the underlying WP_Error code (commonly `db_insert_error`, `db_update_error`, or other slugs from the WordPress vocabulary), not a generic `wp_error` — branch on `error.code` against the WP slug, not against a hard-coded string. The literal `wp_error` slug only surfaces when the upstream WP_Error has an empty code." +
         DRY_RUN_DESC_SUFFIX,
@@ -2046,7 +2091,7 @@ registerLocalTool("diviops_meta_wp_cli", {
 }, async ({ command }) => {
     const response = await wrapResponse(async () => {
         if (!wpCli) {
-            withCode("meta_wp_cli.not_configured", "WP-CLI not configured.", 'Set the WP_PATH environment variable to your WordPress installation path. Example: claude mcp add diviops-mcp -- env WP_URL=http://site.local WP_USER=admin WP_APP_PASSWORD="xxxx" WP_PATH="/Users/you/Local Sites/your-site/app/public" npx @diviops/mcp-server. Local site ID is auto-detected from WP_PATH; set LOCAL_SITE_ID explicitly if needed.');
+            withCode("meta_wp_cli.not_configured", "WP-CLI not configured.", 'Set the WP_PATH environment variable to your WordPress installation path. Example: claude mcp add diviops-mcp --env WP_URL=http://site.local --env WP_USER=admin --env WP_APP_PASSWORD=xxxx --env "WP_PATH=/Users/you/Local Sites/your-site/app/public" -- npx -y --package @diviops/mcp-server diviops-mcp. Local site ID is auto-detected from WP_PATH; set LOCAL_SITE_ID explicitly if needed.');
         }
         const result = await wpCli.run(command);
         if (!result.success) {

package/dist/schema-route.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeSchemaModuleName(moduleName: string): string;
+export declare function schemaModuleRoute(moduleName: string): string;

package/dist/schema-route.js

@@ -0,0 +1,7 @@
+export function normalizeSchemaModuleName(moduleName) {
+    const trimmed = moduleName.trim();
+    return trimmed.startsWith("divi/") ? trimmed.slice("divi/".length) : trimmed;
+}
+export function schemaModuleRoute(moduleName) {
+    return `/schema/module/${encodeURIComponent(normalizeSchemaModuleName(moduleName))}`;
+}

package/package.json

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