Repository navigation
README references to archived abilities api project #150
Description
The README continues to reference the need for the abilities api however the abilities api was merged into core?
Metadata
Metadata
Assignees
Labels
No labels
{{ message }}
Activity
Update README.md for WordPress 6.9/7.0 compatibility
Update README.md for WordPress 6.9/7.0 changes (#165)
mathetos commentedon Jun 24, 2026
README.md was mostly updated in #165 and #204. Remaining drift in readme.txt and the getting-started guides is covered in #223. Suggest closing when that PR merges, or now if maintainers prefer to track doc cleanup only on the PR.
After more review I submitted #223 to address this as well as some other stray items. But per @justlevine 's guidance I'm taking a more wholistic look.
mathetos commentedon Jun 25, 2026
@justlevine I wanted to expand on what this issue implies, since the install/core-Abilities-API drift is only part of the picture.
My PR (#223) started with just the narrow slice (readme.txt and getting-started still read like you need a separate Abilities API install, Composer-first in places README already fixed in #165/#204).
After reviewing the docs in more detail, I see the broader gap that you're highlighting and how it's more of a strategic issue, not just inconsistent examples. The conversation we had on June 24 in Core AI reemphasized that new core/site abilities belong in the AI plugin (and the Abilities API in core), not on the MCP adapter as the primary registration target. A lot of our docs still teach the older model: register arbitrary abilities, set
mcp.public, treat the default server as general-purpose AI integration. That lines up with friction in issues like #213 and #183, and with copy-paste examples that omitcategoryormcp.publicand generate support noise (#135).The architectural context I think we need to make explicit is that WordPress deliberately adopted an adapter pattern for MCP, not explicit flat tooling. On the default server, MCP clients see a thin surface (the meta-tools) and reach everything else through discover → inspect → execute. Abilities live in WordPress first; MCP is one consumer via the adapter, not the place where site capabilities should be defined or primarily documented. Custom servers are the supported path when an integrator wants explicit tooling with a fixed tool list upfront. That framing is why most abilities belong in core or the AI plugin, and only rarely need any direct MCP exposure at all.
When an ability does belong in MCP, I think docs should teach a narrow decision path (most registrations should stop before this): register in the Abilities layer with a clear owner and permissions first; only then ask whether an external MCP client must discover and invoke it. If yes, prefer a custom server when the integration is a small, stable, curated set; use
mcp.publicon the default server's discovery index only when a general-purpose agent should find it at runtime and the site owner intends that exposure. The adapter's own meta-abilities are the exception: they are MCP-protocol affordances, not site CRUD. Everything else should be rare and deliberate, not the hello-world path.So I see what you mean, and my PR needs to be updated if it's going to close #150, but only once we align on the comprehensive doc fix for Abilities in core and the AI plugin.
Here is a quick proposal for what that might look like:
README.md. Explain adapter-vs-explicit-tooling before features or install steps, then spell out who registers what: core and the AI plugin for site abilities, this plugin for MCP protocol adaptation (meta-tools and transports), and custom servers when integrators want explicit tool lists. Include the short "when does an ability belong in MCP?" decision path above somcp.publicreads as rare publishing to the adapter, not as how you AI-enable a site.docs/guides/default-server.mdanddocs/architecture/overview.md(or a smalldocs/guides/adapter-pattern.md). The default server implements layered discovery; custom servers opt into explicit tooling. Tie that design choice to why abilities are not native MCP tools by default.docs/guides/creating-abilities.mdaround registration first, MCP second. Walk through Abilities API registration and ownership, then when (rarely) to publish to MCP viamcp.publicor a custom server list, with anti-patterns called out explicitly.docs/getting-started/README.md,installation.md,basic-examples.md). Point readers to the AI plugin for site abilities instead of create-post-on-default-server as the primary path, and use registration examples withcategoryand the correct hooks so copy-paste does not reproduce wp_register_ability returns NULL when called from plugin duringwp_abilities_api_init#135-style failures.docs/troubleshooting/common-issues.md. Add a short section on common mistakes, such as a missing category, an ability that never shows up on the default server, or registering "for MCP" before the ability belongs anywhere in WordPress.AGENTS.mdanddocs/README.md. Add a doc map and audience order, link to a smalldocs/contributing/documentation.mdor CONTRIBUTING subsection (Diataxis-style conventions, WP doc style guide), and keep those files focused on navigation and guardrails rather than the strategic story.Happy to expand #223 along these lines once we have consensus on the direction above.
galatanovidiu commentedon Jul 3, 2026
Thanks @mathetos, this is really useful.
The original issue here is narrow: the docs told people to install the standalone Abilities API, which is now in core (6.9+). That part is already fixed on trunk by #165 and #204, and #223 cleans up the last stale lines in readme.txt and the getting-started guides. So I'd say #150 is resolved once #223 merges.
Your bigger proposal (adapter pattern front and center, abilities-in-core first,
mcp.publicas the rare case) is a different, larger piece of work. I don't want it to get buried under a doc bug from March. Can you open a separate issue for it? Your 6-bullet outline above is a great starting point. That way it gets its own scope and we can track it properly.@justlevine does that split make sense to you?
docs: clarify Abilities API is core in 6.9+ (fixes WordPress#150) (Wo…