Get the plugin
WP MCP/Guides/Guide

By · Published · Updated

Restructure a long Gutenberg post with surgical block edits

You have a 3,000 word post that grew in the wrong order. The conclusion is halfway down, two sections should swap, one heading is a paragraph in bold, and there is a duplicate image. Pasting the whole thing into an AI chat and pasting the result back would rewrite every block, break the ones you did not touch, and leave you nothing to undo. WP MCP edits the post the way a careful editor would: one block at a time, by address, with the rest untouched.

Free or Pro? Free. get-page-snapshot, parse-blocks, update-block, move-block, remove-block, duplicate-block, list-revisions, diff-revisions and rollback-operation all ship in the free plugin.

What you need

  • WP MCP installed and connected to your AI client. The connection docs cover it.
  • A post written in the block editor (Gutenberg). The post ID is in the URL of its edit screen (post=1234).

Step 1: get the lay of the land

Ask for an outline before you ask for changes.

› Give me an outline of post 1234: headings, how many blocks, images and links.

The agent calls get-page-snapshot with post_id: 1234. It returns a structure summary with block counts, a content outline in document order, a media and link inventory, and confirms the post is a Gutenberg post rather than a builder page. This is the cheap read: no block markup, just the shape.

Then ask for the detailed map:

› Parse the blocks of post 1234 so we can reference them by position.

parse-blocks returns the block tree. Each block has a path, an array of zero-based indexes that descends into innerBlocks (so [7] is the eighth top-level block and [7, 2] is the third block inside it), and the response carries a content_hash for the whole post. Every write below has to present that hash as expected_hash. If anyone edits the post in between, the hash no longer matches and the write is refused instead of overwriting their work.

Step 2: move sections

› Move the "Pricing" section (the heading at path [14] and its paragraphs) to
  just before the "FAQ" heading.

The agent calls move-block with from_path and to_index for the heading and each paragraph, re-reading parse-blocks between calls because each move changes the hash and the positions. If the section is wrapped in a group block, one move-block on the group path moves the whole section at once.

Ask it to pass a session_id on every call so the whole restructure is one undoable unit.

Step 3: fix a block in place

› The bold paragraph at path [9] should be an H2 heading. Keep its text.

update-block targets a single block by path and replaces its attrs (the full attribute set) and, for a leaf block, its inner_html. The agent reads the paragraph text from the parse, then writes it back as a heading block with level: 2. Every other block in the post stays byte-identical. This is the surgical part: you are not asking the agent to rewrite the post, you are asking it to change one addressed block.

Rewrites work the same way:

› Tighten the intro at path [1] to two sentences.

The agent proposes the new text, you approve, and update-block writes it to that one path.

Step 4: remove and duplicate

› Delete the second copy of the hero image at path [11].

remove-block takes a path and expected_hash. For a reusable element:

› Duplicate the call-to-action group at path [6] and put the copy at the end.

duplicate-block clones the block at path, then move-block places the copy where you want it.

Step 5: verify

Ask for the outline again:

› Show me the new outline of post 1234.

get-page-snapshot should now show the headings in the order you wanted. Open the post in the editor as well. Because WP MCP writes through the normal post save, WordPress has created revisions too. Ask:

› Diff the current post against the revision from before we started.

list-revisions finds the revision IDs and diff-revisions shows exactly which blocks changed. If the diff shows a block you did not mean to touch, that is your signal to undo.

Step 6: undo one edit, or all of them

Each write was snapshotted first. list-operations shows them with their operation_id and session_id.

› Undo the heading change at path [9], keep everything else.

rollback-operation restores that one snapshot.

› Roll the whole restructure back.

rollback-session unwinds every operation in the session in reverse order. Because the moves and edits were addressed by path, the rollback is precise: the post returns to the state captured before the first write.

What “surgical” buys you

Whole-content rewrites are the main way AI damages WordPress posts: block comments get malformed, image IDs vanish, the editor shows “This block contains unexpected or invalid content”. Path-addressed edits with a hash check avoid all of it, and the snapshot per write means you never need a backup to try something.

Next step

The free plugin covers everything in this guide. If you also want to build new block types from a spec, drive Elementor, or edit pages built with other page builders, see the pricing page for what Pro adds.

Common questions

How can AI reorder sections in a long WordPress post without rewriting it?

WP MCP edits one block at a time by its path. The agent reads the tree with parse-blocks, then uses move-block, update-block or remove-block on the addressed blocks, so every other block stays byte-identical.

What is the expected_hash in WP MCP block edits?

It is the content_hash returned by parse-blocks for the whole post. Each write must present it, and if someone edited the post in between the hash no longer matches and the write is refused instead of overwriting their work.

How do I undo a block edit or a whole restructure?

Every write is snapshotted first. rollback-operation restores a single edit by its operation_id, and rollback-session unwinds every operation that shared a session_id, in reverse order.

Are the block editing tools free?

Yes. get-page-snapshot, parse-blocks, update-block, move-block, remove-block, duplicate-block, list-revisions, diff-revisions and rollback-operation all ship in the free WP MCP plugin.

How do I check what the AI changed in a post?

Ask for the outline again with get-page-snapshot, then use list-revisions and diff-revisions to compare the current post with the revision from before you started. The diff shows exactly which blocks changed.

All WP MCP guides, or see every plugin integration. Topic: Gutenberg and block suites.