# Divi Pro Tools

> Reference for the 8 Divi Pro tools in Royal MCP Pro: clone pages, replace images, library CRUD, D4 to D5 migration prep and preset ops on Divi 4 and Divi 5.

- Canonical: <https://royalplugins.com/support/royal-mcp-pro/divi-tools/>
- Last updated: 2026-09-20
- HTML version: <https://royalplugins.com/support/royal-mcp-pro/divi-tools/>

---

Complete reference for the 8 Divi Pro tools in Royal MCP Pro. All tools work on Divi 4 (shortcode-based), Divi 5 (block-based), and mixed content on the same page. Every destructive operation returns a 72-hour undo token.

Dual-format support

Divi 4 and Divi 5 are first-class targets on every tool. Format is detected per-post from the actual content shape — presence of `divi/section` blocks (Divi 5) or `[et_pb_section]` shortcodes (Divi 4), or both (mixed). Empty `post_content` with `_et_pb_use_builder=on` is treated as Divi 4. Detection returns one of `divi_4_shortcodes` / `divi_5_blocks` / `mixed` / `not_divi`.

## Prerequisites

- Divi theme or Divi Builder plugin active (any version from 4.x through the current 5.x line)
- Royal MCP Pro installed and licensed (see [Getting Started](https://royalplugins.com/support/royal-mcp-pro/getting-started/))
- MCP client connected to your site

Tools that touch content will refuse on non-Divi pages (posts without `_et_pb_use_builder` meta or `[et_pb_*` shortcodes / `divi/*` blocks). This is a guard, not a bug — use core WP tools for non-Divi content.

## Shared safety layer

Every Divi Pro write tool runs through a shared safety layer before touching content:

- **Format validation.** Divi 4 shortcode content is parsed with `shortcode_parse_atts` per top-level tag (not raw regex) and validated for matched open/close pairs. Invalid content is refused; the write never fires.
- **Meta preservation.** Writes re-assert `_et_pb_use_builder=on` and default `_et_pb_page_layout` when missing, so the post stays visible in Divi's builder after any REST edit.
- **Static CSS purge.** Divi caches per-post CSS via `ET_Core_PageResource::remove_static_resources()`. Every write tool fires this purge after a successful save so design changes reach visitors immediately.
- **Builder-session guard.** The portfolio-wide `Builder_Safety` helper reads WordPress core's `_edit_lock` post meta before any write. If the Visual Builder (or Elementor, or the block editor) has an active session on the target post — measured as a lock set within the last 150 seconds — the write soft-errors with a `builder_session_active` code rather than clobber the in-progress edit. Pass `force: true` to bypass the guard when you know the state.

These aren't optional add-ons — every write tool below calls them.

Why `_edit_lock`?

The lock is set by WordPress core (`wp_set_post_lock`) and respected by every builder that hooks into core's editing surface. Anchoring the guard on the core lock rather than a Divi-specific signal means the same protection applies across Divi 4, Divi 5, Elementor, Gutenberg, Bricks, Beaver Builder, and Oxygen — no per-builder integration required.

## The 8 tools

### divi\_clone\_page

Duplicate a Divi page/post (D4 shortcode, D5 blocks, or mixed) as a new draft. Preserves all `_et_pb_*` meta, regenerates D5 clientIds, validates D4 shortcode structure before write.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `source_post_id` required | `integer` | Post ID to clone from. Must be a Divi-built page. |
| `new_title` required | `string` | Title for the created clone. |
| `new_status` | `string` | Publish state for the clone. One of `draft` (default) / `publish` / `private` / `pending`. |

#### Example

```
Clone post 42 as a draft titled "Homepage V2 Test" using divi_clone_page.
```

Undo: 72h token — consuming it deletes the created post.

### divi\_replace\_image

Swap an image URL across every image-bearing Divi element on a post — module `src`, `background_image`, D5 image block URLs, gallery entries. Dual-format aware.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `post_id` required | `integer` | Divi-built post/page ID to modify. Refuses on non-Divi content. |
| `find_url` required | `string` | Existing image URL to search for (exact match). |
| `replace_url` required | `string` | New image URL to substitute. |

#### Example

```
On post 42, replace the image at https://example.com/wp-content/uploads/2024/old-hero.jpg with https://example.com/wp-content/uploads/2026/new-hero.jpg using divi_replace_image.
```

Undo: 72h token — restores prior `post_content` and meta.

### divi\_import\_template

Apply an `et_pb_layout` library entry to a target page. `mode=merge` appends (top or bottom); `mode=replace` overwrites (with backup meta stamp). Dual-format aware — logs warning on target/template format mismatch.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target_post_id` required | `integer` | The post/page ID that receives the imported template. |
| `template_id` required | `integer` | ID of the `et_pb_layout` library item to apply. Use `divi_library_*` tools to discover / manage. |
| `mode` | `string` | `merge` = append template content (default). `replace` = overwrite target content (backup stamped to a versioned meta key). |
| `position` | `string` | Merge mode only. `top` or `bottom` (default `bottom`). |

#### Example

```
Import library template 128 into page 42 as a replacement using divi_import_template with mode=replace.
```

Undo: 72h token — restores prior `post_content`.

### divi\_library\_create

Create a new `et_pb_layout` library item with explicit format and layout type. Validates D4 shortcode structure before insert; refuses invalid content. Optional global taxonomy assignment.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `title` required | `string` | Display title for the library item. |
| `content` required | `string` | `object` | Divi content — D4 shortcode string or D5 block markup. |
| `layout_type` required | `string` | One of `layout` / `section` / `row` / `module`. |
| `format` required | `string` | `divi_4_shortcodes` or `divi_5_blocks`. NOT auto-detected — caller must be explicit to avoid silent conversions. |
| `is_global` | `boolean` | If `true`, marks as a global module (edits propagate to every reference). Default `false`. |

Undo: 72h token — deletes the created item.

### divi\_library\_update

Update a Divi library item. Format changes NOT allowed — use `divi_convert_shortcodes_to_blocks` for that path. Validates D4 shortcode content pre-write.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `template_id` required | `integer` | ID of the `et_pb_layout` item to update. |
| `title` | `string` | Optional. New display title. |
| `content` | `string` | `object` | Optional. New content — must match the item's original format (D4 ↔ D5 change is refused). |
| `is_global` | `boolean` | Optional. Toggle global-module status. |

Undo: 72h token — restores prior `post_content` and meta.

### divi\_library\_delete

Trash a Divi library item. Refuses when the item is a global module referenced by any post/page unless `force:true`.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `template_id` required | `integer` | ID of the `et_pb_layout` item to trash. |
| `force` | `boolean` | Bypass the global-in-use guard (deletes even if pages reference this global module). Default `false`. |

Undo: 72h token — untrashes the item.

### divi\_convert\_shortcodes\_to\_blocks ⭐

Audit + prepare Divi 4 → Divi 5 migration. Scans posts for D4 / D5 / mixed / not\_divi state, optionally backs up D4 `post_content` to a snapshot meta key, and returns the Divi admin URL for the human/agent to click "Migrate This Site to Divi 5."

How the migration actually completes

Elegant Themes has not published a programmatic migration API. This tool prepares and backs up but defers the actual shortcode-to-block conversion to Divi's own admin UI. The tool returns the admin URL where you (or the agent) click Migrate. Full workflow: [Divi 4 → 5 Migrator guide](https://royalplugins.com/support/royal-mcp-pro/divi-migrator-guide/).

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `post_ids` | `array<integer>` | Optional. If omitted, scans all posts/pages with `_et_pb_use_builder=on`. |
| `dry_run` | `boolean` | Default `true` — report without backing up. |
| `backup` | `boolean` | Default `true` when `dry_run=false` — snapshots D4 `post_content` into a recoverable meta key. |
| `post_types` | `array<string>` | Default `[post, page]` when scanning. |

#### Example

```
Run a dry-run audit of Divi 4 vs 5 content across all pages using divi_convert_shortcodes_to_blocks.

Then commit backups (dry_run=false) so I can safely run Divi's own Migrate button.
```

Undo: 72h token — restores backed-up posts to their pre-scan state.

### divi\_apply\_global\_preset

Apply a Divi 5 preset assignment to every matching module across one page or all pages. Divi 5 only — refuses D4 posts (direct users to `divi_convert_shortcodes_to_blocks` first).

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `post_id` required | `integer` | Anchor post ID. Required even in `all_matching_pages` scope (used for cap check). |
| `module_type` required | `string` | Divi 5 block namespace slug of the target module — e.g. `divi/button`, `divi/heading`, `divi/image`. |
| `preset_id` required | `integer` | Divi 5 preset ID to apply. Discover via Divi's admin preset library. |
| `scope` | `string` | `page` = only the anchor post (default, requires `edit_post`). `all_matching_pages` = every Divi post site-wide (requires `manage_options`). |

#### Example

```
Apply preset 7 to every divi/button module on post 42 using divi_apply_global_preset.

Now apply the same preset across all matching pages site-wide.
```

Undo: 72h token — restores prior `post_content` per touched post.

## Related documentation

- [**Divi 4 → 5 Migrator guide**](https://royalplugins.com/support/royal-mcp-pro/divi-migrator-guide/) — end-to-end workflow for the flagship tool
- [Divi Page Cloning workflow](https://royalplugins.com/support/royal-mcp-pro/divi-page-cloning-workflow/) — retarget + rebrand scenarios
- [Undo Tokens explainer](https://royalplugins.com/support/royal-mcp-pro/#undo-tokens) — how to consume the tokens returned by every write tool
- [Builder Session Detected troubleshoot](https://royalplugins.com/support/royal-mcp-pro/builder-session-detected-force-override/) — when to close the editor vs. pass `force=true`
- [Royal MCP Free docs](https://royalplugins.com/support/royal-mcp/) — setup, OAuth, MCP client configuration (the underlying surface Pro uses)

## Still Stuck? Two-Step Support Path

If a Divi Pro tool isn't behaving the way you expected, work through these two steps in order — most tool-level failures resolve at Step 1 because they're actually MCP-connection or host-layer issues, not Divi-specific.

### Step 1: Start with the Royal MCP Troubleshooting Guide

[**Royal MCP Troubleshooting — Start Here**](https://royalplugins.com/support/royal-mcp/troubleshooting-start-here/) covers the 4-step diagnostic checklist for MCP-layer issues: edge/host probes, cache and WAF interference, OAuth discovery failures, and connector-side error codes. If Claude can't reach your site at all, the tool call never fires — that guide is where to start.

For Pro-specific patterns:

- [Builder session detected](https://royalplugins.com/support/royal-mcp-pro/builder-session-detected-force-override/) — write tools soft-erroring because the Visual Builder is open on the target post
- [Undo token errors](https://royalplugins.com/support/royal-mcp-pro/undo-token-errors/) — expired, consumed, or handler missing
- [Pro tool returned upgrade prompt with valid license](https://royalplugins.com/support/royal-mcp-pro/pro-tool-returned-upgrade-prompt/)

### Step 2: Email priority support

If you've worked through Start Here and the relevant Pro-specific doc and the issue still isn't resolved, email priority support from your purchase email address at **[support@royalplugins.com](mailto:support@royalplugins.com)**. Priority email support is included with your license — typical response within 24 hours. **Never include your license key in email**; we look it up from your purchase address.

What to include in your email

- **Your hosting provider** (SiteGround, Cloudways, Hostinger, Kinsta, WP Engine, Liquid Web, self-hosted VPS, etc.)
- **Royal MCP Pro version** from WP Admin → Plugins
- **Divi version** from **Appearance → Themes** (click the active Divi theme card) OR your Divi Builder plugin version from **WP Admin → Plugins**
- **Active caching plugins** (LiteSpeed Cache, WP Rocket, W3 Total Cache, SpeedyCache, Hummingbird, none)
- **Active security plugins** (Wordfence, Defender Pro, Solid Security, NinjaFirewall, none)
- **Cloudflare or CDN** in front of the site? If yes, is “Manage AI Bots” or “Bot Fight Mode” on?
- **Which MCP client** — claude.ai web custom connector, Claude Desktop with `mcp-remote`, ChatGPT MCP, Cursor, or another MCP-compatible client
- **The exact Divi tool name and args** you called (e.g. `divi_clone_page` with `source_post_id: 42`)
- **The exact error message returned** (from the MCP client's chat surface), plus any `ofid_xxxxx` reference code if claude.ai shows one
- **Screenshot of the most recent `oauth:` row in Activity Log** AND **the most recent Pro tool row in Audit Log** with View Details expanded (or confirmation that the logs are empty after a reproduced failure)
- **The target post's format** — call `divi_get_page_format` (free tool) on the post and include the result

[← Documentation Hub](https://royalplugins.com/support/royal-mcp-pro/)
[Elementor Pro Tools →](https://royalplugins.com/support/royal-mcp-pro/elementor-pro-tools/)