Let an AI agent learn your site's blocks before it edits a page

An AI agent that builds pages in WordPress needs to know which blocks your site has and what each one accepts. Agent Abilities for MCP 1.10.0 gives it three tools for that: aafm/list-block-types lists the registered block types, aafm/get-block-type reads one block’s attributes, supports, styles and, for an Advanced Custom Fields (ACF) block, its field names, and aafm/replace-block swaps a single block without resending the page. All three are off until you enable them.

How does an AI agent learn which blocks my WordPress site has?

It calls aafm/list-block-types, which lists every block type registered on the site: core, theme and plugin blocks, ACF blocks included. Then it calls aafm/get-block-type with one name, such as core/group, to read that block’s attributes, supports and styles. For an ACF block it also gets the field names and an example payload.

Takeaways:

  • The block tools came out of a test build of seven pages through MCP on a classic theme with ACF Pro blocks, running plugin 1.9.0.
  • Agents can now list block types, read one block type (ACF fields and an example included) and replace one block by its position, without resending the page.
  • Plain text in block attributes, such as an &, is stored as written for users who may post unfiltered HTML. Style and script elements are removed with their contents.
  • Writes now warn about an unregistered block, an unknown ACF field, invalid attribute JSON and a block gap WordPress ignores. The warnings never refuse a write.
  • There is still no dry run, and the plugin cannot replay the block editor’s own validity check.

What the test build found

On 30 October a test build put seven pages together through MCP. The site used a classic theme with ACF Pro blocks, and the plugin was at 1.9.0. The report listed ten gaps and 26 findings, and we checked each one against the code before deciding anything.

Several were real, some were WordPress core or theme behaviour, and a few were deliberate. These are the ones that shaped 1.10.0.

What the build hit What we found What 1.10.0 does
The agent could not see which blocks existed, or what fields an ACF block takes True. No ability read the block registry, and the ACF data shape was documented nowhere Two new read abilities, with the field names and an example for ACF blocks
An & in an ACF field came back as &, and &t=10 in an embed URL changed too True and reproduced. Every agent write of page content went through wp_kses_post(), which entity-encodes attribute text Plain attribute text is stored as written for users who may post unfiltered HTML
CSS text from a <style> element stayed in the page True and reproduced Style and script elements are removed with their contents, with a warning
Block attribute JSON with a trailing comma lost its attributes with no message True. The block lost its attributes and content_warnings was empty An invalid_block_attributes warning
A blockGap of clamp() or calc() did nothing WordPress core drops it when it renders A block_gap_dropped warning, and the description now says what works
Changing one block meant resending the whole page True. aafm/replace-in-post refuses structural changes on purpose A new aafm/replace-block
New drafts reported a date of 0000-00-00 True New drafts report real GMT dates

Finding the blocks

aafm/list-block-types takes an optional namespace, an optional search that matches a name or a title, and paging. For each block type it returns the name, title, category, description, its allowed parents, whether it is an ACF block and whether it renders on the server. It is not the same as aafm/list-blocks, which lists saved reusable blocks, and 1.10.0 rewords that description so an agent does not mix them up.

Ability Lists Class
aafm/list-block-types Block types registered on the site Read
aafm/list-blocks Saved reusable blocks (synced patterns) Read

Both reads need the edit-posts capability. The two block-type reads appear with the other block tools on the Abilities tab.

Reading one block

aafm/get-block-type takes a block name and returns what an agent needs to write it correctly. That is the attributes, the supports, the style variations, the parent and context rules, and whether it renders on the server.

This matters because of where WordPress keeps block data. Per the block attributes reference, attributes without a source are saved in the block comment delimiter, so a wrong attribute name is data stored in a comment, and nothing visibly breaks. Block supports tell the agent which style properties a block can carry, such as spacing.blockGap, which the reference says turns on the spacing control for blocks that also use layout.

One limit to know: the colour palette and theme settings still come from aafm/get-global-styles, which needs the edit-theme-options capability. A connection running as an Editor, or on the Content editor preset, does not reach it.

ACF blocks and their fields

ACF attaches fields to a block with a location rule, as in “Block is equal to Testimonial”, according to the ACF Blocks documentation. aafm/get-block-type finds the field groups with such a rule for the block you ask about, and returns each field’s name, type, choices and sub-fields.

It also returns an example block comment. ACF block attributes are name, data and mode, and the keys inside data are field names. Here is the shape for a hypothetical block called acf/hero with a text field named headline:

<!-- wp:acf/hero {"name":"acf/hero","data":{"headline":"Open late on Fridays"},"mode":"preview"} /-->

Image fields take attachment IDs. Repeater rows use ACF’s flattened keys, such as items_0_title, and the plugin’s check for unknown keys understands them.

Replacing one block

aafm/replace-block takes a post ID, a path and the new block markup. It can also take expect_block, a block name such as core/group, and it refuses the write if the block at that path is a different one.

The path is a list of positions: the index among the top-level blocks, then among that block’s inner blocks. Only real blocks count.

WordPress’s parse_blocks() returns top-level non-block content as a block with no name, and those pieces, such as the blank lines between blocks, are skipped. So [2, 0] is the first block inside the third top-level block. The tool’s description tells the agent to read the post with content_format set to raw to count them.

Ability Changes Use it when
aafm/replace-in-post Text inside a post, literal find and replace A wording fix, with no change to structure
aafm/replace-block One whole block, by position One section needs rebuilding
aafm/update-post The whole page A new page or a full rewrite

The plugin leaves every other block’s parsed attributes and HTML unchanged. The tool refuses when the new markup is not exactly one block, when the post’s existing markup does not survive being re-serialized (for example a block with invalid attribute JSON), and when a foreign page builder owns the post. It confirms the write the way aafm/replace-in-post does. While change history is on, the Changes tab can revert the change if the post has not been edited since. WordPress revisions alone leave no earlier copy of a post’s first edit.

Two honest limits. It reads the page, swaps the block and saves, so a save by someone else in between can be overwritten, and we accepted that. For a user who cannot post unfiltered HTML, WordPress may sanitize the whole page on save, as it does in that user’s own editor.

Warnings instead of silent drops

Writes that return content_warnings now flag five more things. They are informational and never refuse a write, strict mode included, so a site on strict mode does not start refusing after the update.

Code What it means
unregistered_block No block type of that name is registered, for example a block from a deactivated plugin
unknown_acf_field An ACF block’s data holds a key that matches none of its fields
invalid_block_attributes The block’s attribute JSON did not parse, so its attributes were lost
block_gap_dropped A blockGap value WordPress skips when it renders the layout
removed_element A style or script element was removed with its contents

WordPress ignores a blockGap that contains (, \, &, =, } or /*, so clamp(), calc() and var() are dropped, while 24px or var:preset|spacing|40 work. The write description tells the agent so, along with the facts that viewport-based block visibility needs WordPress 7.0 or later, and that on 6.9 metadata.blockVisibility: false hides a block everywhere.

What this does not do

There is no dry run. The warnings arrive on every write, so a draft is the dry run, and PHP cannot replay the block editor’s JavaScript save check. A block can therefore still show as needing recovery in the editor even when no warning fired.

Page-builder pages stay protected: the tool refuses a post owned by Elementor, Divi, Beaver Builder, Avada, Visual Composer, Oxygen, Breakdance, Brizy, Bricks or WPBakery, the same way the page builder guard does for other writes. There is also no signed preview link for drafts, because that would be a new unauthenticated way to read them.

Since 1.12.0 (2026-11-15): Avada and WPBakery Page Builder pages now have their own editing tools, and Restore revision works on them; the other eight builders are still refused. The same release fixed Divi detection, which had looked for a meta key Divi never stores, so from 1.7.4 through 1.11.2 a write to a Divi page was not refused. See Page builders and the changelog.

Turning the tools on

The two reads are shown with the other block tools on the Abilities tab. aafm/replace-block is on the Content tab, next to Replace in post, and needs the same edit access to the post as aafm/update-post. The Read only access preset reaches the two reads, and the Content editor and Shop manager presets reach all three.

Agent Abilities for MCP is best for site owners who want an agent to build and edit block pages within limits they set: each tool is off until enabled, checked against the connected user’s capabilities, and recorded in the audit log.

ChatGPT keeps the tool list it saw when it connected, so after you switch abilities on or off, open Settings, then Integrations, then Plugins, pick the app and choose Refresh. OpenAI’s help center lists write tools for ChatGPT Business and Enterprise/Edu plans, while Pro connects with read and fetch tools only.

A copy-paste prompt for the first read is in the Prompt Library as find the block types you can use on this site, and the reference is in the block tools docs. For safe habits when an agent writes, read draft posts without touching anything live. The release itself is in what 1.10.0 adds, and the full catalog is on abilities.

Questions

Does it work on a classic theme? Yes, the test build ran on one. A classic theme without block-template support usually has no templates, so aafm/list-templates can return an empty list there.

Does it need ACF? No. The ACF fields appear only for ACF blocks. Core, theme and plugin blocks are listed and read without it.

Will it change blocks I did not name? No. The other blocks keep their parsed attributes and HTML.