docs: rebuild readme.txt for the WordPress.org listing - #285
Conversation
Follows WordPress/ai's structure and moves the full changelog inline so the .org Changelog tab isn't empty. Also drops the CHANGELOG.md entries that pointed at a file which never existed, and corrects LICENSE to LICENSE.md. See WordPress#178
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## trunk #285 +/- ##
=========================================
Coverage 88.17% 88.17%
Complexity 1259 1259
=========================================
Files 54 54
Lines 4120 4120
=========================================
Hits 3633 3633
Misses 487 487
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
There was a problem hiding this comment.
Pull request overview
This PR updates the plugin’s WordPress.org-facing metadata by rebuilding readme.txt to match WordPress.org expectations (installation instructions, FAQ, inline changelog, upgrade notices, contributors), and aligns packaging config so release artifacts include the correct license file and don’t reference non-existent files.
Changes:
- Reworked
readme.txtfor WordPress.org: updated installation flow, added “For Developers” + FAQ, and inlined changelog + upgrade notices. - Updated npm packaging file list to include
LICENSE.md(actual filename) and removed references to missing files. - Removed
.gitattributesexport-ignore entry for a non-existentCHANGELOG.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| readme.txt | Rebuilt WordPress.org readme sections (installation, FAQ, full changelog, upgrade notice) and updated contributors. |
| package.json | Fixed packaged file list by replacing LICENSE with LICENSE.md and removing CHANGELOG.md. |
| .gitattributes | Removed export-ignore for CHANGELOG.md since it’s not present in the repo. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| - `wp mcp-adapter serve` keeps JSON-RPC stdout clean when selecting the default server. | ||
| - WP-CLI's global `--user` argument is used instead of registering a conflicting local option. | ||
|
|
||
| = 0.5.0 - 2026-04-15 = |
There was a problem hiding this comment.
IMO better to put this and everything earlier into CHANGELOG.md to keep this file from getting unwieldly. Once we hit 1.0 (i'm assuming the submission itself), we'd want everything pre-release in CHANGELOG.md and out of this file.
| == For Developers == | ||
|
|
||
| MCP Adapter is built to be extended, and can also be consumed directly as a library. | ||
|
|
||
| **Use it as a Composer dependency:** | ||
|
|
||
| `composer require wordpress/mcp-adapter` | ||
|
|
||
| If you vendor the library inside your own plugin, load it through the [Jetpack Autoloader](https://github.com/Automattic/jetpack-autoloader) so that every plugin on the site resolves the same `WP\MCP` implementation. Running an independently namespace-prefixed copy alongside the plugin is not supported. | ||
|
|
||
| **Extend the adapter:** | ||
|
|
||
| * **Custom Transports** – Implement `McpTransportInterface` to add transport protocols beyond the built-in HTTP and STDIO support. | ||
| * **Custom Error Handlers** – Implement `McpErrorHandlerInterface` for per-server error handling strategies. | ||
| * **Observability Handlers** – Record events and timings into your own metrics pipeline. | ||
| * **Multiple Servers** – Use `create_server()` to run several MCP servers with independent configurations. | ||
| * **Hooks** – Filters and actions throughout the codebase, all prefixed `mcp_adapter_`. | ||
|
|
There was a problem hiding this comment.
I'd strip all of this from here
- The audience of this file are end users installing it from W.org
- Once it's on w.org Composer installation should be a last resort.
- Single source of truth, as part of the docs cleanup we want fewer places repeating the same things.
There was a problem hiding this comment.
Will drop it.
Turns out it wasn't rendering as its own section anyway.
| = What do I need to run this? = | ||
|
|
||
| WordPress 6.9 or newer and PHP 7.4 or newer. The Abilities API is included in WordPress core from 6.9, so no additional plugin is required. | ||
|
|
There was a problem hiding this comment.
Isn't this redundant? We have Requires headers...
There was a problem hiding this comment.
Dropping it.
Want to keep one bit though, that the Abilities API ships in core from 6.9 so you don't need the separate plugin. That's not in any header and 0.6.0 dropped support for the standalone one. I'll fold it into the "What is MCP Adapter?" answer unless you'd rather it sat somewhere else.
There was a problem hiding this comment.
IWhy would anyone think you need a separate plugin? That sounds like an AI Slop decision-log piece of information, so id rather it sat nowhere. The plugin requires WordPress 6.9+ - that's all that the user needs to know, IMO, not that before WordPress 6.9 this plugin won't work and the Abilities API doesn't exist...
There was a problem hiding this comment.
RIght, make sense! I addressed you suggestions, please take a look again!
| = Can another plugin bundle MCP Adapter as a library? = | ||
|
|
||
| Yes, via `composer require wordpress/mcp-adapter`. Load it through the Jetpack Autoloader so that all plugins on the site resolve the same `WP\MCP` implementation. Running an independently namespace-prefixed copy alongside the plugin is not supported. | ||
|
|
There was a problem hiding this comment.
Same as above, it's possible but we want to bury this possibility as much as possible in the docs.
| 3. Join the conversation in [#core-ai on WordPress Slack](https://wordpress.slack.com/archives/C08TJ8BPULS). | ||
| 4. Browse the [GitHub repository](https://github.com/WordPress/mcp-adapter) and open issues or pull requests. | ||
|
|
||
| == Frequently Asked Questions == |
There was a problem hiding this comment.
I would add two more (imo the most important ones):
- What is MCP?
- What is MCP Adapter? (This is where we stress that it's just a server + transport, and any consumable functionality (e.g. abilities) come from somewhere else.
There was a problem hiding this comment.
Agreed, those are the important ones. Adding both.
Drops the For Developers section and two FAQ entries, adds What is MCP and What is MCP Adapter, and moves releases before 0.6.0 into CHANGELOG.md. See WordPress#285
Drops the For Developers section and two FAQ entries, adds What is MCP and What is MCP Adapter, and moves releases before 0.6.0 into CHANGELOG.md. See WordPress#285
5a43279 to
8ddaffb
Compare
What?
See #178
Rebuilds
readme.txtfor the WordPress.org listing, followingWordPress/ai/readme.txt. Also removes two packaging entries for files that aren't in the repo.Why?
A few things would be wrong on the .org page as it stands. The Changelog tab would be empty, because
== Changelog ==just links out to GitHub releases.== Installation ==tells people to download from a GitHub release, which won't be right once the plugin is in the directory. There's no FAQ. AndContributors:only listswordpressdotorg.Separately,
package.jsonfileslistsCHANGELOG.mdandLICENSE. Neither file exists, and.gitattributesexport-ignoresCHANGELOG.mdat the same time, so the two disagree.How?
For Developers,Frequently Asked QuestionsandUpgrade Noticesections. The full changelog is now inline, 0.6.1 back to 0.1.0, with the breaking changes repeated underUpgrade Notice.Installationnow starts with the plugin directory. Composer and Jetpack Autoloader notes moved intoFor Developers.Stable tag: 0.6.1, to matchmcp-adapter.php.CHANGELOG.mdentries frompackage.jsonand.gitattributes, and changedLICENSEtoLICENSE.md, which is the real filename.Contributors is now
wordpressdotorg, ovidiu-galatan. @gziolo asked forgalatanovidiuin #178, but that's the GitHub handle, and this field needs a WordPress.org username.profiles.wordpress.org/galatanovidiu/404s andovidiu-galatanworks. The parser drops names it can't find, so the GitHub handle would have credited nobody. Happy to change it if I've picked the wrong person.Use of AI Tools
AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Writing the readme.txt text and turning the existing release notes into the inline changelog. I checked everything against the repo and against the .org readme parser, and I'm responsible for what's here.
Testing Instructions
npm run plugin-zipand check thatreadme.txtandLICENSE.mdare both in the zip.Stable tagmatchesVersioninmcp-adapter.php. Both should be0.6.1.Every section is under the parser's limits. The biggest is Changelog, at 906 words out of 5,000.
Changelog Entry