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