Expose CWA content management to AI assistants through API Platform's MCP support (McpTool / McpResource)

Start by reading vendor/api-platform/core/src/Mcp, src/Metadata/Mcp*.php, and the API Platform MCP documentation, then inspect the bundle's existing API operations and Behat matrix. Define the opt-in detection boundary and authentication approach before implementing the proposed read-only resources and admin-only tools; done means the 4.4 matrix remains green and REST security, validation, cache, and Mercure behavior are preserved.

Why

API Platform 5 adds experimental support for the Model Context Protocol (MCP). This is how AI assistants (Claude, IDE agents and so on) discover and call "tools" on a server. We like to adopt new capabilities early, and CWA is a good fit: it would let an editor manage a site by asking in plain language, with every action still going through the API's existing security and validation.

For example:

• "Create a page called Summer Offers on the Standard layout at /summer-offers."
• "Add a text block to the top of the home page saying we're closed on Monday."
• "Schedule the new pricing page to go live next Friday at 9am."
• "Which pages are still drafts?" / "What goes live this week?"
• "Resend the verification email to [email protected]."

What API Platform provides

The component is marked @experimental. It lives in vendor/api-platform/core/src/Mcp and src/Metadata/Mcp*.php; the docs are at https://api-platform.com/docs/core/mcp/.

• McpTool (extends HttpOperation) exposes an operation as an MCP tool, rather than as an HTTP route.
  • It's declared on a class (#[McpTool(name:, description:, processor:)]) or in a resource's mcp: [...] array.
  • The resource class becomes the tool's input schema. Input is deserialised and validated with the usual validation groups; processor / provider and operation security apply; the result is returned as MCP content (structuredContent by default).
• McpResource exposes read-only data as context an assistant can read. McpToolCollection is a tool that returns a collection.
• Config: api_platform.mcp (can be disabled) with format, default jsonld.
• Requirements: api-platform/* ^5.0, mcp/sdk ^0.8, and Symfony's MCP bundle for the server transport.

Constraint

The bundle supports api-platform/core: ^4.4 || ^5.0, and the MCP component needs 5. MCP support must therefore be opt-in and self-detecting: registered only when API Platform 5, mcp/sdk and the MCP bundle are installed, and inert otherwise. That keeps the 4.4 leg of the Behat matrix green, and adds no dependency for apps that don't want it.

Proposal (first slice)

Start small, and read-heavy:

1. Resources (read-only): the route tree with each route's own and effective go-live state; pages and their templates; draft versus published components; and the site config.
2. Tools (write, admin only):
   • create a page or page data;
   • create a route (path, parent, liveAt);
   • add a component to a group (type, position, data), honouring allowedComponents and #[ExplicitAllowOnly];
   • update a component's data;
   • publish, or schedule a publish (future publishedAt);
   • resend verification;
   • purge the page cache.

Each tool should wrap the same processors, validators, and security as the REST operations — never a parallel path — so an assistant can do exactly what a signed-in admin can, and nothing more.

Open questions

• Authentication. How does an MCP client authenticate? Options: the existing JWT or cookie, a per-user token, or the OAuth flow the MCP spec describes. Nothing should be callable anonymously, and the admin role check must hold.
• Drafts and publishing. Should tools write to drafts by default and publish only when asked, as the admin UI does?
• Cache and Mercure. Tool writes must purge the same surrogate keys and publish the same Mercure updates as REST writes. Worth a Behat scenario that proves it.
• Audit. Record which actions came from an assistant.
• Stability. The component is experimental. Pin versions, keep it behind a flag, and expect API changes between minor releases.
• Scope in the module. None is needed for the first slice: MCP clients talk to the API directly. The admin UI could later show that a change came from an assistant.