By Fahad Murtaza · 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.