Divi Pro 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.
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)
- 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_attsper 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=onand default_et_pb_page_layoutwhen 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_Safetyhelper reads WordPress core's_edit_lockpost 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 abuilder_session_activecode rather than clobber the in-progress edit. Passforce: trueto bypass the guard when you know the state.
These aren't optional add-ons — every write tool below calls them.
_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."
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.
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.
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 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 — write tools soft-erroring because the Visual Builder is open on the target post
- Undo token errors — expired, consumed, or handler missing
- Pro tool returned upgrade prompt with valid license
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. 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.
- 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_pagewithsource_post_id: 42) - The exact error message returned (from the MCP client's chat surface), plus any
ofid_xxxxxreference 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