WordPress Core Abilities

[Jameswlepage]

As the Abilities API is developed for inclusion in WordPress Core, we need to define a default set of abilities that will be bundled with it. This proposal outlines a foundational set of abilities intended to be safe, useful for the majority of use cases, and non-destructive by default.

All ability names below follow the established namespace/ability-name convention enforced by the API. The core namespace is used to designate that they are part of the WordPress Core set.

Proposed Core Abilities

Site and Settings

• core/get-site-info (WordPress 6.9)
• core/get-environment-info (WordPress 6.9)
• core/read-settings (AI Plugin 1.1, Add a core/settings ability #691)
• core/manage-settings (Add a core/manage-settings ability #764)

Users

• core/get-user-info (WordPress 6.9)
• core/read-users (AI Plugin 1.2, New Ability: core/read-users #774)
  • core/get-user
  • core/find-users
• core/update-user-info

Posts and Pages

• core/read-content (AI Plugin 1.2, Add core/read-content ability #739)
  • core/find-posts
  • core/get-post
  • core/find-pages
  • core/get-page
• core/create-post
• core/update-post
• core/create-page
• core/update-page

Media

• core/find-media-items
• core/get-media-item
• core/upload-media-item
• core/update-media-item

Taxonomy

• core/find-categories
• core/get-category
• core/find-tags
• core/get-tag

Comments

• core/find-comments
• core/get-comment

Menus

• core/get-menu-locations
• core/get-menu

Themes

• core/get-active-theme
• core/list-themes

Plugins

• core/list-plugins
• core/get-plugin
• core/activate-plugin
• core/deactivate-plugin
• core/update-plugin

Out of Scope for this Proposal

• Deleting content, users, or media.
• Installing or uninstalling plugins and themes.
• Theme switching.
• Creating or modifying menus.
• Any actions that cannot be easily reversed.

Open Questions

1. Plugin Management: This proposal includes abilities to activate, deactivate, and update plugins. Given the potential for site instability, what guardrails are essential? Should these actions be limited to an allowlist of specific plugins by default to prevent unintended changes?

2. Destructive Actions: This initial set deliberately excludes destructive actions like deleting posts or users. Should a future version include them? If so, what additional security measures, like a 'trash' or 'undo' ability, would be required to maintain a high degree of safety?

[galatanovidiu]

For:

Posts and Pages

• core/find-posts
• core/get-post
• core/create-post
• core/update-post
• core/find-pages
• core/get-page
• core/create-page
• core/update-page

I would combine them to do CRUD operations on any public CPT. This will reduce the number of tools by only adding one extra input, post_type.
Something similar to: https://github.com/galatanovidiu/mcp-adapter-implementation-example/blob/main/src/Abilities/Posts/ListPosts.php#L28

[justlevine]

Open Questions

1. Plugin Management: This proposal includes abilities to activate, deactivate, and update plugins. Given the potential for site instability, what guardrails are essential?

Imo this q is solved by recognizing that these are destructive actions, and considering them beyond the scope for now:

• core/update-plugin causes irreversible changes to files and potentially database structures, would need a mechanism to "roll back" the update (files + db) to the specific pre-update version.
• core/deactivate-plugin:
  • can often cause database changes as well (Delete settings on deactivate is a common option), though that could be worked around by requiring plugins who use register_deactivation_hook() to allowlist in, via a (theorycraft) ability_supports( 'core/deactivate-plugin', 'my-plugin-name ),
  • However, the ability to "break" frontend site functionality is easily worse with Theme switching and modifying menus.
• core/activate-plugin: The least "destructive" of all three, but
  • IMO still on par with Theme switching and modifying menus (though not as easy to reverse than e.g. a FSE theme switch or a menu revision).
  • Without core/deactivate-plugin it's not reversable at all.

2. Destructive Actions: This initial set deliberately excludes destructive actions like deleting posts or users. Should a future version include them?

This seems like a great candidate for exploration and iteration in AI Experiments

---

All ability names below follow the established namespace/ability-name convention enforced by the API. The core namespace is used to designate that they are part of the WordPress Core set.

Surfacing since there's no GH issue/discussion to tag: @galatanovidiu brought up the idea (Slack) of having a "clear definition" of what namespaces should represent, and the possibility of groupings via nested namespaces.

[marcochiesi]

I appreciate the in-depth discussion on this topic. I'd like to contribute a few points to the conversation:

• Abilities as "One More Way": I envision the abilities API as "one more way" for users to achieve results, as an alternative to the WordPress admin UI. Of course, we must ensure users are fully aware of what's happening and confirm potentially destructive actions. For this, the Model Context Protocol (MCP) standard includes a feature called "elicitation," which allows the MCP server to request additional information from the user (such as confirmation) before executing a task. More information here.
• Handling Destructive Operations: For the reason above, I would not limit plugin management or other destructive operations, as long as we can guarantee that the user is forced to confirm before proceeding. We should simply ensure that LLMs do not perform such actions without explicit confirmation. I believe over-engineering with the possibility of "undo" actions is out of scope. Currently, when using the standard WordPress UI, the user cannot easily undo these destructive operations.
• Unified CRUD Interface: I agree with the proposal of having a unified CRUD interface for all post types with a post_type parameter. This approach is consistent with existing WordPress functions like wp_insert_post, wp_update_post, etc, which promotes a familiar and standardized development experience.

[gziolo]

For this, the Model Context Protocol (MCP) standard includes a feature called "elicitation," which allows the MCP server to request additional information from the user (such as confirmation) before executing a task. More information here.

@marcochiesi, some great feedback here. It deserves its own issue, as this topic is more nuanced. In particular, MCP is a great example where some additional hints help to distinguish the type of operation. I can think of more use cases, like including information whether something is read-only, what's a safe action, what's a destructive action, and what's a resource (an image or other media). It's going to be useful with MCP, but also with the existing Command Palette in WP Admin to provide some unified workflows. Would you like to expand on this topic with your thoughts in a newly created issue?

[marcochiesi]

@marcochiesi, some great feedback here. It deserves its own issue [...]

It makes sense, however, I am not totally sure if this should be territory for the Abilities API or for the MCP Adapter project (or maybe both), so I am unsure about where to post such issue. A possible approach could be:

• The Abilities API should be responsible for providing the necessary information including metadata or "hints" that describe the nature of each action (e.g., read-only, safe, destructive). This makes the API a reliable and declarative source of truth about what each ability does.
• The MCP adapter (or any client consuming the API) should be responsible for the logic. It would read the hints provided by the API and, based on that information, decide how to handle the action. For a destructive action, the adapter would trigger a user confirmation prompt (elicitation) before proceeding.

WDYT?

[justlevine]

@marcochiesi the current separation of concerns has the Abilities API (this repo) responsible for allowing functionality to be called decoupled from traditional WordPress flows. The goal is to be able to register abilities once, and not need to tech-debt/reinvent every time a new way of interacting with WordPress sites (via AI, but tbh in any decoupled context) is hyped.

The MCP Adapter provides a MCP-compatibile API shape for the exposed WordPress functionality. The only logic there should be what's needed to interact with the ability.

If/when other standards (e.g. A2A) gain traction, those "last-mile" Adapters will all be able to reuse abilities, independently of adoption/adaptation of MCP.

It's even possible that in the mid-to-long term future even REST/GraphQL endpoints can be API wrappers for the same abilities, but that's obviously long ways before even being a discussion.

[claytoncollie]

@Jameswlepage Back to your original statement about the work that the initial build is going to achieve. From reading the list, I can't help but see some similarities between the WP CLI and the REST API. As people stated above, this is "just another way" to interact with WordPress. As such, the naming conventions, namespaces, aliases, class/function names, and features should closely align with those existing APIs. This is more of a philosophical comment, and I hope you can lean on the other teams and APIs to flesh out your feature set and naming conventions.

[gziolo]

@swissspidy, do you have some recommendations on how to shape the general-purpose abilities based on your experience with both WP CLI and trying to map REST API endpoints to tools from your MCP for WordPress work? The following issue comes to my mind:

• Revisit tools approach mcp-wp/ai-command#58

[swissspidy]

Sure. Let me try to address some of the points raised in this discussion so far in general:

First, I agree with @marcochiesi regarding destructive actions. It's not the Abilities API's or the MCP adapter's job to limit destructive options or implement additional safeguards like rollbacks or opt-in. We already have permission checks, allowlists, and and concepts such as elicitations in MCP. And if you interact with abilities through the Command Palette, deactivating a plugin is not different from clicking the link on a plugin page. Thus, we should not deliberately exclude anything in this regard. This is out of scope.

The Abilities API should definitely have a way to provide as much metadata as possible (e.g. read-only, destructive, idempotent, requires confirmation, etc.)

Second, @galatanovidiu is right that we need to combine CRUD operations as much as possible. Separate tools per post type or so do not make sense. When it comes to MCP, providers usually have hard limits on the number of tools. Last I checked, 128 for OpenAI, 512 for Google. So there we need to keep that in mind.

For such CRUD operations, WP-CLI is definitely a good example. wp post works for any post type, just pass the --post_type argument. The REST API is different, every post type has its own route. Both have pros and cons. Also worth noting that WP-CLI covers way more than the REST API as well (e.g. there is a command to install translations, but no REST route for that).

When I think about using abilities via a command palette to create new content and I type "Create a new ...", as a user I would love to see different options "Create a new page", "Create a new product", and so on. However, for an MCP use case, I only want one create_post tool that takes a post_type argument. Is this something we could reflect in the API design somehow?

I think that would cover both scenarios: a granular list of abilities for users, and a more condensed list for machines. Hope that makes sense :-)

[justlevine]

It's not the Abilities API's or the MCP adapter's job to limit destructive options ... Thus, we should not deliberately exclude anything in this regard.

My understanding of "scope" in this context was regarding the short deadline between now and WP6.9 Beta 1 and our need to prioritize and not ship tech debt into core. It's not about excluding destructive actions entirely but doing them iteratively and additively.

To your actual point:

Unlike Command Palette et al, MCP allows for autonomous execution of destructive action without proving user intent. So IMO there's at least some additional consideration that needs to occur. It might not be something that belongs in abilities-api, maybe it's not something in MCP Adapter, maybe it's only in the client, or somewhere else altogether. (Whatever "it" is).

---

When I think about using abilities via a command palette to create new content and I type "Create a new ...", as a user I would love to see different options "Create a new page", "Create a new product", and so on. However, for an MCP use case, I only want one create_post tool that takes a post_type argument. Is this something we could reflect in the API design somehow?

From the way you're describing this, it sounds like this should be an implementation detail to be solved in the CP and MCP implementations eg

• Command Palette would just loop through the input schema -in this example the post_type enum- to translate arguments into semantic commands
• MCP could group them with certain meta or by simply respecting nested namespaces if we go that route here.

Assumedly, translating abilities to REST endpoints or CLI commands or GraphQL mutations, or whatever other existing or future use case for abilities would similarly reach their ideal shape by inferring from the schema / meta where possible.

Or is there something more explicit/deterministic you have in mind?