| name | wp-mcp-generator |
| description | Generate full-coverage MCP for any WordPress plugin. Given a plugin .zip or .org slug, install it, understand it deeply (its code is the source of truth; exercising it confirms and surfaces gaps), design an agent-ergonomic ability surface, and ship a companion "ability pack" plugin that registers those abilities via the WP Abilities API — which Agent Connector for WP (mcp-adapter) auto-exposes as MCP. Done is measured by you actually being able to drive the plugin through the abilities to get the results you intend, verified. Use when asked to build/generate MCP tools or abilities for a WP plugin. |
WP Plugin → Full-Coverage MCP Generator
You are turning an arbitrary WordPress plugin into an MCP surface that lets an agent
control everything a human admin can do with that plugin — and you must prove it
works, not assume it. The output is a companion ability pack plugin.
This skill gives you the standard, the principles, and the tools. It deliberately
does not give you a plugin-specific recipe. Every plugin is different; you derive the
right tactics yourself by reading its code and using it. Trust your exploration.
The standard of done (read this first)
You can accomplish any task a human admin could accomplish with this plugin, by
calling the abilities you registered — and you have verified each one end to end.
Not "I wrapped the endpoints." Not "the abilities return 200." The bar is: you, acting
as the agent, can get the intended real-world result, confirmed from more than one
independent vantage point (the UI shows it, the database holds it, the plugin renders it).
If an ability doesn't let you do that, it isn't done — keep working.
Two non-negotiable principles
1. The code is the source of truth. A plugin's true data model — where it stores
things, in what shape, how it loads and saves them, what validation runs — lives in its
PHP, not in its UI. Read all of it. Exercising the UI is how you confirm your reading
and discover where to look next; it is not how you achieve understanding. When the UI
and your reading of the code disagree, the code (and the database) win — go find why.
2. Design for the agent, not for code-reuse. The abilities are a synthesized API
built for an agent's convenience. They are not a mirror of the plugin's storage model or
its existing endpoints. Optimize relentlessly for minimal input and task-level
verbs: the agent should pass only the delta it cares about, never re-send a whole
structure it isn't changing. If giving the agent that ergonomics means implementing logic
the plugin doesn't have, implement it. Ease of use for the agent outranks reusing existing
code every time.
You will frequently discover that the cleanest way to honor both principles is to read
the current state through the plugin's own loader, make your small change in your
companion plugin's PHP, and persist through the plugin's own save path so its validation
and hooks still run. You don't need to be told to do this for any specific plugin — you
will arrive at it (or something better) by understanding how the plugin loads and saves.
What you produce
- A companion ability pack plugin under
wp/wp-content/plugins/ (start from
scaffold/ — see "Using the scaffold"). It registers categories + abilities and, where
needed, carries the adapter logic that makes those abilities ergonomic.
- A coverage report (
coverage/coverage-report.md in the pack) mapping every surface
and every admin task to an ability — or to an explicit excluded, with reason.
- A populated inventory (
coverage/inventory.json) — the structured understanding
that backs the coverage claim.
The loop (how "full coverage" becomes objective, not a vibe)
Run this loop. Do not declare done until all three termination conditions hold.
A. Understand — from code, then from use.
- Read the entire plugin. Build the inventory as you go (
coverage/inventory.schema.json
documents the shape). Capture surfaces (every way the admin interacts — admin pages,
settings, REST routes, AJAX actions, CPTs/taxonomies, shortcodes/blocks, cron, caps, CLI),
data stores (every option key, table + schema, meta key, CPT — with its load and save
paths), and tasks (the verbs an admin performs).
- Then exercise it for real in Playwright at
http://wordpress/. To reach wp-admin, mint a
one-time login URL with the agent-connector-for-wp/create-admin-login-link ability and open
it in the browser — no username/password needed, and it works whatever the site's admin
credentials are.
Diff the database around each action (tools/db-diff.sh) to see exactly what each task
mutates and to catch stores/actions your code read missed. Watch the save requests and
any client-side state — that is often where a builder's true document format reveals itself.
B. Design + implement abilities for everything understood so far, following the
principles above. Prefer many small ergonomic verbs over few structural mega-operations.
Where the agent would benefit from knowing valid shapes (field types, node kinds, option
enums), register introspection abilities so it can discover them at runtime instead of
guessing.
C. Exercise both paths and cross-check. For each task, do it (a) via your ability and
(b) via the real UI, and confirm the resulting state converges. Disagreement = a bug or a
nuance you missed — fix it, and feed any newly-discovered surface back into A.
D. Repeat until all three hold:
- Coverage — every inventory surface and task maps to an ability or an explicit
excluded-with-reason.
- Discovery saturation — further exploration rounds (UI walking + DB diffing + re-reading
code) surface nothing new.
- Functional acceptance — every ability passes its acceptance check (below). No ability
ships known-broken.
Acceptance: triangulate, then keep fixing
For each ability, define the intent ("add a text field named X to group Y"), call the
ability, and confirm the outcome from independent vantage points — typically the UI
(Playwright shows/renders it), the database (wp db query / wp option get), and a REST
read where one exists. Triangulation is what catches "wrote the DB but the UI ignores it"
and "looks right in the UI but didn't persist." On failure: diagnose, fix the ability (or
your understanding), re-run. The loop does not exit with a failing ability.
Call your own abilities through MCP exactly as a real agent would:
mcp-adapter-execute-ability (discover with mcp-adapter-discover-abilities,
inspect with mcp-adapter-get-ability-info). Don't shortcut by calling your PHP directly —
test the surface the agent will actually use.
Environment (how to actually do the work here)
- WP-CLI runs in your workspace shell —
wp plugin install <zip-or-slug> --activate,
wp db query, wp option get, wp post list, etc. Files are live under wp/; edit them
directly. This is your fastest path — prefer it over MCP for setup and inspection.
- Install the target from a
.zip path or a .org slug with wp plugin install.
Snapshot a clean baseline first (wp db export) so you can roll back between exploration
passes — some actions send mail, hit external services, or delete data.
- Drive the UI with the Playwright MCP browser pointed at
http://wordpress/
(http://localhost:8080 is not reachable from the browser container).
- Run abilities through the
wordpress MCP server (the mcp-adapter-* tools).
- Run code inside the live WP runtime when you need a plugin function in request context:
agent-connector-for-wp/php-eval via mcp-adapter-execute-ability.
- Scope: free .org plugins and unlocked commercial
.zips (no license gating). Multisite
is out of scope. Frontend/JS state is in scope — inspect it. Note per-plugin any feature
that needs an external service the sandbox can't reach.
Using the scaffold
scaffold/ is a ready-to-fill ability-pack plugin that already obeys the Agent Connector
convention (you write no auth/permission/domain/audit code — Agent Connector injects all
of it). To start a pack:
- Copy
scaffold/ to wp/wp-content/plugins/unofficial-abilities-for-<target>/.
- Rename the main file to match the folder and fill its header placeholders — crucially
Agent Connector Target: <target-plugin-file> (e.g. woocommerce/woocommerce.php), and
pick your vendor namespace <vendor> for ability names (<vendor>/add-field). Never use
the agent-connector-for-wp/ namespace. Leave Version: 0.0.0-dev untouched — the
release CI stamps the real version into the built zip on merge; never hand-set it.
- Add abilities as files under
abilities/ using ACFW_Pack::ability([...]) and categories
with ACFW_Pack::category(...). Put reimplemented/adapter logic under src/.
- Keep
coverage/inventory.json and coverage/coverage-report.md current as you go — they
are deliverables, not notes.
The exact registration arg contract (label, description, category, input_schema, output_schema,
execute_callback, annotations, optional summarize) is documented in
wp/wp-content/plugins/agent-connector-for-wp/docs/registering-abilities.md — read it once.
Write precise descriptions and tight input schemas: they are the product, because they are
what makes an agent succeed or fail at choosing and calling the ability.
Failure modes to avoid
- Mirroring storage as CRUD. Forcing the agent to re-send a whole field group / document
/ settings blob to change one thing. Give it a verb that takes the delta.
- Understanding from the UI instead of the code. The UI samples; the code is complete.
- Calling your own PHP to "verify." Verify through the MCP surface + independent vantage
points, the way the real agent will hit it.
- Silent coverage gaps. If you exclude a surface, say so and why in the coverage report.
An unexplained gap reads as "covered" when it isn't.
- Shipping reimplemented logic you didn't round-trip through the plugin. If you mutate a
document/structure yourself, prove the plugin still accepts and renders it.
