wordpress/mcp-adapter

MCP Adapter 0.6.1 repairs the production release ZIP. It contains no other changes.

Who should upgrade

Anyone running 0.6.0 from the mcp-adapter.zip release asset should upgrade. Installations built from source or required through Composer are unaffected.

Fixed

• The release ZIP no longer ships a Jetpack Autoloader class map that points to files the ZIP omits. In 0.6.0 the class map listed test-only global classes, including WP_CLI and WP_CLI_Command, and mapped them to files under tests/phpunit/, which the release artifact excludes. Any plugin calling class_exists( 'WP_CLI' ) on a normal web request could therefore trigger an uncaught fatal error. class_exists( 'WP_CLI' ) now returns false when WP-CLI is unavailable.

No API, hook, or protocol behavior changed. Upgrading from 0.6.0 requires no migration.

Thank you to @rebeccahum for reporting this in #283, their first contribution to MCP Adapter.

Full Changelog: v0.6.0...v0.6.1

MCP Adapter 0.6.0 improves protocol compatibility, resource metadata handling, session reliability, WP-CLI behavior, and coexistence with plugins that bundle their own copy of the adapter.

Before upgrading

• WordPress 6.9 or newer is now required. The standalone Abilities API plugin is no longer a supported installation path.
• Abilities with meta.public: true are now exposed through the default MCP server unless meta.mcp.public explicitly opts out. Existing permission callbacks and capability checks still apply.
• On multisite only, active Streamable HTTP sessions must reconnect once after upgrading because session storage moves from a network-wide key to separate per-site keys. Single-site installations are unaffected.
• The MIME validation helpers previously exposed by McpValidator have been removed. Integrations calling them directly should apply their own application-specific MIME validation.

MCP resources and metadata

• Preserve _meta on resource contents, embedded resources, content blocks, and prompt messages.
• Omit malformed _meta without discarding the payload it accompanies.
• Emit mimeType exactly as declared, including values with parameters such as text/html;profile=mcp-app.
• Correctly handle blob-only resource contents.
• Support resources/templates/list, returning an empty template list when no templates are available.
• Match resource URI schemes case-insensitively, so clients can read resources even when they normalize the scheme to lowercase.

These changes improve compatibility with MCP Apps and other clients that depend on resource metadata.

Reliability and compatibility

• Protect concurrent session mutations with bounded retries, reducing the risk of one request overwriting another session.
• Scope session storage by blog on WordPress multisite.
• Use Jetpack Autoloader so the newest available WP\MCP classes win when the standalone adapter and another plugin bundle different versions.
• Normalize empty arguments for schema-defining abilities, allowing valid zero-argument tool calls to execute correctly.

WP-CLI improvements

• Keep JSON-RPC stdout clean when wp mcp-adapter serve selects the default server.
• Use WP-CLI’s global --user argument instead of registering a conflicting local option.

Additional improvements

• Block direct execution of plugin PHP files.
• Clarify that the Abilities API is included in WordPress 6.9 and newer.
• Document the required ability category field and improve examples throughout the documentation.
• Expand automated compatibility, dependency, and Plugin Check coverage.

New contributors

Welcome to @johnbillion, @graham73may, @gziolo, @ustramooner, @matthewfarrugia, @robertocyrino, and @mathetos, who made their first contributions to MCP Adapter in this release.

Thank you to everyone who contributed code, documentation, testing, and reviews.

Full Changelog: v0.5.0...v0.6.0

Highlights

v0.5.0 is a major internal upgrade for MCP Adapter. The biggest change is the adoption of wordpress/php-mcp-schema across the plugin, so MCP responses now use typed protocol DTOs instead of hand-built arrays.

This gives us a more consistent and spec-aligned foundation for tools, resources, prompts, initialization, and error responses, while making future MCP spec updates easier to support.

For most users, this should be a seamless upgrade. Existing ability registration, create_server(), and WordPress hooks continue to work as before. If you have custom handlers, transports, or code that depends on internal component structures, review the migration guide for upgrade details.

Included in this release

• Full integration of wordpress/php-mcp-schema throughout the adapter
• Typed DTO-based handling for MCP tools, resources, prompts, initialization, and JSON-RPC errors
• Protocol version negotiation support for 2025-11-25, 2025-06-18, and 2024-11-05
• Validation, encapsulation, and type-safety improvements across the core and domain layers
• Security hardening with stricter input validation and fail-closed permission handling
• Better observability for protocol errors and isError tool responses
• Reduced SessionManager write amplification to lower lock contention
• Packaging and dependency updates, including the php-mcp-schema v0.1.1 follow-up for cleaner Composer dist archives

Documentation

Documentation was expanded significantly for this release, including:

• A new v0.5.0 migration guide
• Updated architecture documentation
• Improvements to the default server guide and troubleshooting docs
• README updates, including WordPress 6.9/7.0 notes
• Additional guidance for ability registration

Contributors

• @galatanovidiu
• @jonathanbossenger
• @JasonTheAdams
• @spenserhale
• @karthikeya-io
• @itsgajendraSingh

New Contributors

• @spenserhale made their first contribution in #44
• @karthikeya-io made their first contribution in #169
• @itsgajendraSingh made their first contribution in #165

Full Changelog: v0.4.1...v0.5.0

What's Changed

• fix: Correct JSON-RPC error response structure and HTTP status codes by @galatanovidiu in #106
• Properly return error messages when using unnested error formats in ToolsHandler by @priethor in #90

New Contributors

• @priethor made their first contribution in #90

Full Changelog: v0.4.0...v0.4.1

Co-authored-by: priethor [email protected]
Co-authored-by: galatanovidiu [email protected]

This patch release focuses on MCP specification compliance and project improvements.

Bug Fixes

• Flattened Schema Handling (#93): Added automatic transformation of flattened schemas (string, number, boolean, array) to MCP-compatible object schemas. The MCP specification requires all tool input schemas to be of type "object" - abilities using flattened schemas now work correctly.

Improvements

• Tool Annotations Mapping (#91): Fixed annotation field name mismatches between WordPress Abilities API format and MCP specification. The adapter now correctly maps readonly → readOnlyHint, destructive → destructiveHint, and idempotent → idempotentHint for full protocol compliance.

• Added .gitattributes to exclude development files from releases (#94)

• Added GNU General Public License v2 (#97)

Documentation

• Fixed missing comma in transport permissions example (#85)

• Applied WordPress PHP documentation standards (#92)

New Contributors

• @huzaifaalmesbah made their first contribution in #85
• @BrianHenryIE made their first contribution in #94
• @jeffpaul made their first contribution in #97

Full Changelog: v0.3.0...v0.4.0

Version 0.3.0 introduces significant architectural improvements with enhanced observability, streamlined transport infrastructure, and better error handling compliance.

Breaking Changes

Observability System Changes

Event Naming with Status Tags

All observability events now use unified names with a status tag instead of separate success/failure event names.

Before:
$handler->record_event('mcp.request.success', ['method' => 'tools/call']);
$handler->record_event('mcp.request.error', ['method' => 'tools/call']);

After:
$handler->record_event('mcp.request', ['status' => 'success', 'method' => 'tools/call']);
$handler->record_event('mcp.request', ['status' => 'error', 'method' => 'tools/call']);

Instance-Based Handlers

Observability handlers now use instance methods instead of static methods. If you have custom handlers implementing McpObservabilityHandlerInterface, update from static to instance methods:

// Before
class MyHandler implements McpObservabilityHandlerInterface {
    public static function record_event(string $event, array $tags = []): void { }
    public static function record_timing(string $metric, float $duration_ms, array $tags = []): void { }
}

// After
class MyHandler implements McpObservabilityHandlerInterface {
    public function record_event(string $event, array $tags = [], ?float $duration_ms = null): void {
        // Single method handles both events and timing
    }
}

Removed Method

McpObservabilityHelperTrait::record_error_event() has been removed. Use record_event() with status and error categorization instead.

Transport Layer Changes

Removed Transports

RestTransport and StreamableTransport have been removed and replaced by the unified HttpTransport class, which provides all functionality of both previous implementations with enhanced capabilities.

Migration:

All existing servers using these transports should update to use HttpTransport:

use WP\MCP\Transport\HttpTransport;

$adapter->create_server(
    'my-server',
    'namespace',
    'mcp',
    'Server Name',
    'Description',
    '1.0.0',
    [ HttpTransport::class ],  // Updated
    ErrorLogMcpErrorHandler::class
);

Hook Name Standardization

All WordPress filter/action names now use the mcp_adapter_ prefix for consistency:

// Before
add_filter('mcp_validation_enabled', $callback);

// After
add_filter('mcp_adapter_validation_enabled', $callback);## What's New

Unified HTTP Transport

The new HttpTransport class provides a modern, spec-compliant transport implementation with session management, streaming support, and enhanced error handling.

Enhanced Error Handling

Comprehensive refactoring to use WP_Error pattern throughout the codebase, replacing exceptions for better WordPress integration. All error responses now comply with the MCP specification format.

Metadata-Driven Observability

Observability events are now recorded centrally at the transport layer with automatic metadata extraction from handler responses, providing richer context and better performance tracking.

Improved Documentation

Updated guides covering transport permissions, custom transport implementation, error handling patterns, and comprehensive migration instructions.

Bug Fixes

• Fixed metadata leaking into tool response content
• Fixed null parameter handling in Prompts and Resources handlers
• Fixed parameter handling for abilities without input schemas
• Fixed WP_Error handling across all handler types
• Fixed prompt input schema validation
• Fixed WP-CLI initialization timing issues

Full Migration Guide

See docs/migration/v0.3.0.md for detailed migration instructions and examples.

What's Changed

• Updating composer instructions by @jonathanbossenger in #10
• chore: scaffold repo for WPCS and WordPress/* by @justlevine in #14
• chore: configure PHPStan by @justlevine in #13
• ci: setup test workflow for PHPCS/PHPStan by @justlevine in #15
• dev: downgrade php 7.4 by @justlevine in #16
• dev: scaffold WordPress plugin wrapper by @justlevine in #18
• Update MCP server creation instructions in README by @jonathanbossenger in #21
• dev: move src to includes and post-scaffold cleanup by @justlevine in #20
• chore(phpstan): add PHP8 stubs for WP polyfills by @justlevine in #29
• Introduce Props Bot workflow by @desrosj in #30
• Use abilities instead of capabilities by @aaronjorbin in #25
• ci: reenable codecov by @justlevine in #28
• dev!: cleanup and update compatibility with abilities-api v0.1.0 by @justlevine in #27
• dev!: refactor non-registry functionality from Core/McpAdapter by @justlevine in #26
• Add type property to empty input schema by @stormrockwell in #36
• Add structuredContent to tool callback response by @finleyjchen in #37
• chore: backfill props for #36 and #37 by @justlevine in #41
• Relax parameter validation to allow some falsy values as parameters. by @aaronfc in #43
• Major Refactor: Enhanced Transport Infrastructure, Default Server, and CLI Support by @galatanovidiu in #48
• Fix tool error handling to comply with MCP specification by @galatanovidiu in #73
• Fix WP_Error handling in PromptsHandler and ResourcesHandler by @galatanovidiu in #74
• Fix parameter handling for abilities without input schemas on ExecuteAbilityAbility by @galatanovidiu in #76
• Add wp_ prefix to hook names. by @mindctrl in #81
• Doc updates by @jonathanbossenger in #83
• Fix metadata appearing in tool response content by @galatanovidiu in #72
• Fix prompt parameter validation by converting input_schema to MCP arguments by @galatanovidiu in #78
• Fix null parameter handling in Prompts and Resources handlers by @galatanovidiu in #77
• Docs: Update testing guide to use wp-env workflow by @galatanovidiu in #67
• Refactor error handling: Replace exceptions with WP_Error pattern by @galatanovidiu in #71
• Ensures init action fires before initializing in WP-CLI by @galatanovidiu in #86

New Contributors

• @justlevine made their first contribution in #14
• @desrosj made their first contribution in #30
• @aaronjorbin made their first contribution in #25
• @stormrockwell made their first contribution in #36
• @finleyjchen made their first contribution in #37
• @aaronfc made their first contribution in #43
• @mindctrl made their first contribution in #81

Full Changelog: v0.1.0...v0.3.0

First Stable Release of WordPress MCP Adapter

The WordPress MCP Adapter is now ready for production use! This foundational library bridges WordPress's Abilities API with the Model Context Protocol (MCP), enabling WordPress applications to expose their functionality to AI agents in a standardized, secure, and extensible way.

What's Included

Core Features

• Ability-to-MCP Conversion: Automatically transforms WordPress abilities into MCP tools, resources, and prompts
• Multi-Server Management: Create and manage multiple MCP servers with unique configurations
• Extensible Transport Layer:
  • Built-in REST API (RestTransport) and Streaming (StreamableTransport) protocols
  • Custom transport support via McpTransportInterface
  • Multiple transport methods per server
• Robust Error Handling:
  • Default WordPress-compatible error logging
  • Custom error handlers via McpErrorHandlerInterface
  • Server-specific error handling strategies
• Built-in Observability: Metrics tracking with configurable handlers
• Comprehensive Validation: Built-in validation for tools, resources, and prompts
• Granular Permission Control: Transport-level authentication and authorization

MCP Component Support

• Tools: Convert abilities into executable MCP tools for interactive operations
• Resources: Expose abilities as MCP resources for data access
• Prompts: Transform abilities into structured MCP prompts for AI guidance
• Server Discovery: Automatic registration and discovery of MCP servers

Enterprise-Ready Architecture

• Composer Package: Designed for flexible integration, not as a WordPress plugin
• Version Conflict Resolution: Uses Jetpack Autoloader for seamless multi-plugin compatibility
• Production Scalability: Supports complex, multi-server enterprise architectures
• Extensibility: Interface-based design for custom transports, error handlers, and observability

What's Changed

• Initial Commit by @galatanovidiu in #3
• Enhance README.md with detailed installation instructions by @galatanovidiu in #4
• Correct namespace for WP\MCP\Core\McpAdapter by @jonathanbossenger in #5
• Add version 0.1.0 to composer.json by @galatanovidiu in #6

New Contributors

• @galatanovidiu made their first contribution in #3
• @jonathanbossenger made their first contribution in #5

Full Changelog: https://github.com/WordPress/mcp-adapter/commits/v0.1.0