@diviops/mcp-server 0.1.0 → 0.2.1

package/README.md

@@ -91,9 +91,9 @@ The server connects via standard WordPress REST API and works with any environme
 
 > **WP-CLI note:** `WP_PATH` keeps the existing Local by Flywheel behavior by running `wp` directly on the host filesystem. For Docker-based environments (DDEV, wp-env, DevKinsta, WordPress Studio), set `WP_CLI_CMD` to the wrapper command instead. When `WP_CLI_CMD` is set, the server executes the wrapper from `WP_PATH` if provided, otherwise from its current working directory. The MCP server still validates the requested WP-CLI subcommand against its allowlist before executing either path.
 
-## Available Tools (43)
+## Available Tools (46)
 
-### Read (24)
+### Read (25)
 | Tool | Description |
 |------|-------------|
 | `diviops_test_connection` | Test WordPress connection and Divi version |
@@ -111,6 +111,7 @@ The server connects via standard WordPress REST API and works with any environme
 | `diviops_list_templates` | List available MCP prompt templates |
 | `diviops_get_template` | Get a specific template's block markup |
 | `diviops_preset_audit` | Audit presets with referenced/unreferenced analysis |
+| `diviops_preset_scan_orphans` | List page-referenced preset UUIDs missing from the D5 registry (separates dangling orphans from D4-legacy refs) |
 | `diviops_list_library` | List saved Divi Library items |
 | `diviops_get_library_item` | Get a library item's block markup |
 | `diviops_render_preview` | Render block markup to HTML for preview |
@@ -121,7 +122,7 @@ The server connects via standard WordPress REST API and works with any environme
 | `diviops_list_canvases` | List all canvas pages |
 | `diviops_get_canvas` | Get canvas content |
 
-### Write (17)
+### Write (20)
 | Tool | Description |
 |------|-------------|
 | `diviops_create_page` | Create a new page with optional Divi content |
@@ -132,6 +133,8 @@ The server connects via standard WordPress REST API and works with any environme
 | `diviops_update_module` | Update specific module attributes by label or text match |
 | `diviops_move_module` | Move a block before/after another block (reorder modules, sections) |
 | `diviops_preset_cleanup` | Remove spam/duplicate presets, bulk rename |
+| `diviops_preset_create` | Write a new preset to the D5 registry (module or group type, supports `divi/column` etc.) |
+| `diviops_preset_reassign` | Rewrite `modulePreset` references across pages (dry-run by default; optional `strip_inline` removes redundant inline attrs) |
 | `diviops_preset_update` | Update a specific preset (name, attrs) |
 | `diviops_preset_delete` | Delete a preset by ID |
 | `diviops_save_to_library` | Save block markup to Divi Library |
@@ -154,16 +157,20 @@ The `diviops_wp_cli` tool validates every command against a safety allowlist bef
 
 ### Default allowlist (always available)
 
-Read-only commands plus non-destructive writes needed for core MCP functionality:
+Read-only commands plus non-destructive writes needed for core MCP functionality and local development workflows:
 
 | Category | Commands |
 |----------|----------|
 | Options | `option get`, `option list` |
 | Posts | `post list`, `post get`, `post create`, `post update` |
 | Post meta | `post meta get`, `post meta list`, `post meta set`, `post meta update` |
+| Post types | `post-type list`, `post-type get` |
+| Taxonomies | `taxonomy list`, `term list`, `term create`, `term update` |
+| ACF / SCF | `acf export`, `acf import`, `acf field-group list`, `acf field-group get` |
 | Users | `user list` |
 | Cache | `cache flush`, `transient delete`, `rewrite flush` |
-| Info | `cron event list`, `plugin list`, `theme list`, `menu list`, `term list`, `term create`, `site url` |
+| Export | `export` (WXR data export to file) |
+| Info | `cron event list`, `plugin list`, `theme list`, `menu list`, `site url` |
 
 ### Extended commands (opt-in)
 
@@ -174,6 +181,9 @@ These commands carry higher risk and require explicit opt-in via the `DIVIOPS_WP
 | `option update` | High | Can change site URL, admin email, or security settings |
 | `post delete` | Medium | Permanently removes content |
 | `post meta delete` | Medium | Removes metadata |
+| `term delete` | Medium | Permanently removes taxonomy terms |
+| `search-replace` | High | Bulk database modification — can corrupt content if misused |
+| `import` | Medium | Bulk content ingestion from WXR files |
 | `plugin activate` | Medium | Can enable untrusted plugins |
 | `plugin deactivate` | Medium | Can disable security plugins |
 | `eval-file` | Critical | Executes arbitrary PHP from a file path |
@@ -186,12 +196,16 @@ claude mcp add diviops-mcp -- env \
   WP_USER=admin \
   WP_APP_PASSWORD=xxxx \
   WP_PATH="/path/to/wordpress" \
-  DIVIOPS_WP_CLI_ALLOW="option update,post delete" \
+  DIVIOPS_WP_CLI_ALLOW="option update,post delete,search-replace" \
   npx @diviops/mcp-server
 ```
 
 Only list the specific commands you need. Unknown entries are ignored with a warning.
 
+> **Note on `acf import`**: included in the default allowlist because it's an idempotent dev-time schema operation (re-creates field groups from JSON). Bulk content imports use `wp import` instead, which is opt-in.
+
+> **Known limitation — filesystem access**: Validation is prefix-based, not flag-aware. Commands that read from or write to the filesystem (`acf export`/`acf import`, `export`, opt-in `import`/`eval-file`) can target any path reachable by the WP-CLI user. For shared or multi-tenant environments, consider wrapping the MCP server with a stricter proxy or running it under an account with limited filesystem permissions. Flag-level validation is a candidate future enhancement.
+
 ## Example Usage
 
 After setup, Claude can:

package/dist/index.js

@@ -661,6 +661,100 @@ server.registerTool("diviops_preset_delete", {
         ],
     };
 });
+server.registerTool("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
+            .string()
+            .describe('Divi module slug (e.g. "divi/column", "divi/button", "divi/section"). For group presets, this is still required and describes the module the preset originated from.'),
+        name: z.string().describe("Display name for the new preset"),
+        attrs: z
+            .record(z.string(), z.any())
+            .describe("Full module attribute bag (same shape as a module's top-level attrs in block markup). Saved to both attrs and styleAttrs."),
+        type: z
+            .enum(["module", "group"])
+            .optional()
+            .default("module")
+            .describe('"module" (default) or "group" for attribute-level presets.'),
+        group_name: z
+            .string()
+            .optional()
+            .describe('Group name (e.g. "divi/font", "divi/button"). Required when type="group".'),
+        group_id: z
+            .string()
+            .optional()
+            .describe('Group id (e.g. "designTitleText", "designText", "button"). Required when type="group".'),
+        primary_attr_name: z
+            .string()
+            .optional()
+            .describe('Primary attr name for the group (e.g. "title" for designTitleText). Optional.'),
+    },
+}, async ({ module_name, name, attrs, type, group_name, group_id, primary_attr_name }) => {
+    if (type === "group" && (!group_name || !group_id)) {
+        throw new Error('type="group" requires both group_name and group_id. Example: group_name="divi/font", group_id="designTitleText".');
+    }
+    const body = { module_name, name, attrs, type };
+    if (group_name)
+        body.group_name = group_name;
+    if (group_id)
+        body.group_id = group_id;
+    if (primary_attr_name)
+        body.primary_attr_name = primary_attr_name;
+    const result = await wp.request("/preset-create", { method: "POST", body });
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+server.registerTool("diviops_preset_reassign", {
+    description: 'Reassign a preset UUID across page content. Walks pages and rewrites modules referencing old_uuid in their modulePreset array to reference new_uuid. Optionally strips inline attrs that duplicate the new preset\'s attrs (otherwise inline wins over preset). 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
+            .string()
+            .describe("Preset UUID to replace (can be a dangling/orphan UUID)"),
+        new_uuid: z
+            .string()
+            .describe("New preset UUID to insert. Must already exist in the registry."),
+        page_ids: z
+            .array(z.number().int().positive())
+            .optional()
+            .describe("Restrict to specific post IDs. Omit to scan all pages and posts."),
+        mode: z
+            .enum(["dry-run", "apply"])
+            .optional()
+            .default("dry-run")
+            .describe('"dry-run" (default) returns the diff without writing. "apply" rewrites page content.'),
+        strip_inline: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("If true (default), strip inline attrs that deep-equal the new preset's attrs so the preset actually takes effect. Set false to swap UUIDs only."),
+    },
+}, async ({ old_uuid, new_uuid, page_ids, mode, strip_inline }) => {
+    const body = { old_uuid, new_uuid, mode, strip_inline };
+    if (page_ids)
+        body.page_ids = page_ids;
+    const result = await wp.request("/preset-reassign", {
+        method: "POST",
+        body,
+    });
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
+server.registerTool("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");
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ],
+    };
+});
 // ── Library Tools ───────────────────────────────────────────────────
 server.registerTool("diviops_list_library", {
     description: "List saved Divi Library items. Filter by layout_type (section, row, module) and scope (global, non_global).",
@@ -968,7 +1062,7 @@ server.registerTool("diviops_delete_canvas", {
 });
 // ── WP-CLI ──────────────────────────────────────────────────────────
 server.registerTool("diviops_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). Commands validated against a safety allowlist. Default tier: read commands, post create/update, post meta read/write, cache/rewrite flush, term create. Extended tier (requires DIVIOPS_WP_CLI_ALLOW env var): option update, post delete, post meta delete, plugin activate/deactivate, eval-file. Use --format=json for structured output.",
+    description: "Run a WP-CLI command on the WordPress site. Requires WP_PATH env var (LOCAL_SITE_ID auto-detected from Local by Flywheel). Commands validated against a safety allowlist. Default tier covers read ops across options/posts/post-types/taxonomies/users/info, non-destructive writes (post/term create+update, post meta read/write, cache/rewrite/transient flush), ACF schema ops (export/import/list/get field-group), 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. Use --format=json for structured output. Full allowlist + tier rationale in the MCP server README.",
     inputSchema: {
         command: z
             .string()
@@ -1032,7 +1126,7 @@ server.registerTool("diviops_server_info", {
     };
 });
 // ── Resources ────────────────────────────────────────────────────────
-server.resource("divi-block-format-guide", "divi://block-format-guide", async () => ({
+server.registerResource("divi-block-format-guide", "divi://block-format-guide", {}, async () => ({
     contents: [
         {
             uri: "divi://block-format-guide",

package/dist/wp-cli.js

@@ -26,32 +26,57 @@ const DEFAULT_COMMANDS = [
     'post meta list',
     'post meta set',
     'post meta update',
+    // Post types (read-only)
+    'post-type list',
+    'post-type get',
+    // Taxonomies (read + non-destructive write)
+    'taxonomy list',
+    'term list',
+    'term create',
+    'term update',
+    // ACF / SCF (schema ops — idempotent dev-time workflow)
+    'acf export',
+    'acf import',
+    'acf field-group list',
+    'acf field-group get',
     // Users (read-only)
     'user list',
     // Cache (non-destructive maintenance)
     'cache flush',
     'transient delete',
     'rewrite flush',
+    // Export (reads data, writes to file only)
+    'export',
     // Info (read-only)
     'cron event list',
     'plugin list',
     'theme list',
     'menu list',
-    'term list',
-    'term create',
     'site url',
 ];
 /**
  * Extended commands that require explicit opt-in via DIVIOPS_WP_CLI_ALLOW env var.
- * These carry higher risk: destructive operations, arbitrary code execution,
- * or the ability to disable security features.
+ * These carry higher risk: destructive operations, bulk database modification,
+ * arbitrary code execution, or the ability to disable security features.
+ *
+ * To enable, set a comma-separated subset, e.g.:
+ *   DIVIOPS_WP_CLI_ALLOW="option update,post delete,search-replace"
+ *
+ * Only list the specific commands you need — unknown entries are ignored.
  *
- * To enable, set: DIVIOPS_WP_CLI_ALLOW="option update,post delete,eval-file"
+ * Known limitation: validation is prefix-based, not flag-aware. Commands that
+ * touch the filesystem (acf export/import, export, eval-file) can write to
+ * or read from any path reachable by the WP-CLI user. For shared environments
+ * consider wrapping the MCP server with a stricter proxy or running it under
+ * an account with limited filesystem permissions.
  */
 const EXTENDED_COMMANDS = [
     'option update', // Can change site URL, admin email, active plugins
     'post delete', // Destructive — permanently removes content
     'post meta delete', // Destructive — removes metadata
+    'term delete', // Destructive — removes taxonomy terms
+    'search-replace', // Bulk DB modification — highest-risk content op
+    'import', // Bulk content ingestion from WXR files
     'plugin activate', // Can enable untrusted plugins
     'plugin deactivate', // Can disable security plugins
     'eval-file', // Executes arbitrary PHP from a file path

package/dist/wp-client.js

@@ -47,6 +47,10 @@ export class WPClient {
             catch {
                 errorMessage = errorBody;
             }
+            if (response.status === 429) {
+                const retryAfter = response.headers.get('Retry-After') || '60';
+                throw new Error(`Rate limited: ${errorMessage} (retry after ${retryAfter}s)`);
+            }
             throw new Error(`WordPress API error (${response.status}): ${errorMessage}`);
         }
         return response.json();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diviops/mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "MCP server exposing Divi 5 Visual Builder as tools for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {