Mcp Adapter Laravel Package

Getting Started

• This is the WordPress MCP Adapter (v0.7.1), not a Laravel package. It exposes WordPress “abilities” over the Model Context Protocol so AI clients can discover and call them. Laravel developers will usually consume it as an external MCP server or use it as a reference for building MCP endpoints.
• First steps: install/activate the plugin in WordPress, read the new site-owner setup guide, create an Application Password, configure an MCP client (Claude Desktop, MCP Inspector, etc.) with the server URL and credentials, then test a simple read-only ability.
• Where to look first: the README, the setup guide, the ability registration hooks/filters, and the MCP discovery endpoint. If you’re coming from Laravel, map “abilities” to Laravel actions/controllers and “Application Password” to a Sanctum/Passport token.
• First use case: expose one safe read-only ability such as “list posts” or “get site info,” verify discovery and invocation in MCP Inspector, then add write abilities behind capability checks.

Implementation Patterns

• Register abilities as thin wrappers around existing domain services. Give each ability a clear name, description, and JSON schema; validate input before calling WordPress APIs; return structured, predictable output.
• Use namespaced ability names and keep a stable discovery surface. Clients depend on descriptions and schemas, so version or deprecate abilities carefully.
• Authenticate with Application Passwords and scope abilities by WordPress capabilities. Do not expose admin-only abilities without explicit capability checks.
• For session-based HTTP transports, keep initialization payloads small. The new 4 KiB limit means you should avoid large metadata, inline icons, or bulky client info. Treat session storage as ephemeral.
• Test with real MCP clients, not just unit tests. Exercise discovery, success paths, unknown ability names, and abilities that are not exposed through MCP.
• If you’re building a Laravel equivalent, mirror this pattern: one MCP tool per action, schema validation via Form Requests, token auth via Sanctum, and a discovery endpoint that lists only public tools.

Gotchas and Tips

• Session payload limit: Initialization parameters over 4 KiB now fail with JSON-RPC -32602 (Invalid params). Existing oversized session data is cleared automatically; affected clients must reconnect once. Keep clientInfo lean.
• Client icons not persisted: clientInfo.icons is no longer retained for subsequent requests. Don’t depend on it for UI or authorization.
• Error code change: Unknown abilities and abilities not exposed through MCP now return ability_not_found instead of ability_not_public_mcp. Update client-side error handling and tests.
• Plugin loading conflicts: If another bundled copy of the adapter exists, the installed plugin’s autoloader is now registered first so version selection can run before the older copy loads. Still, avoid shipping duplicate bundled copies.
• Debugging: Check Application Password validity, endpoint URL, and MCP discovery first. Enable WordPress debug logging for JSON-RPC errors; unknown ability names no longer generate developer notices, so rely on the returned error.
• Extension points: Use the adapter’s registration hooks/filters to add abilities and customize error messages. Keep ability callbacks idempotent where possible and log calls for auditability.
• Security: The session storage fix is a reminder not to store sensitive or oversized data in session init. Treat all client-supplied metadata as untrusted.
• Release note: Releases below 0.7.0 are prevented from deployment to WordPress.org; pin to 0.7.1 or later if you rely on the session and error-handling fixes.