Summary

This PR represents a comprehensive architectural restructuring of the WordPress MCP Adapter, addressing significant technical debt while introducing three major feature sets.

While I understand the importance of small, atomic PRs for easier review, the scope and interconnected nature of the issues made it impractical and time-consuming.

I hope this work unblocks a cleaner, more modular workflow moving forward.

What's New

1. HttpTransport - Modern Transport Infrastructure

The new HttpTransport class replaces the existing RestTransport and StreamableTransport implementations, providing a unified, more robust transport layer.

Key Features:

• Unified HTTP handling with dedicated request processing services (HttpRequestHandler, RequestRouter)
• Session management with user-based authentication (SessionManager, HttpSessionValidator)
• Standardized error responses via JsonRpcResponseBuilder with proper HTTP status code mapping
• Improved request context handling through HttpRequestContext and McpTransportContext
• Better separation of concerns with specialized infrastructure components

Technical Benefits:

• Provides consistent error handling across all HTTP-based transports
• Implements proper session lifecycle management for stateful operations
• Improves security through built-in authentication validation

2. Default Server with Layered Tools Architecture

A new default MCP server that automatically registers with the adapter, featuring a layered approach to exposing WordPress abilities as MCP tools.

Components:

• DefaultServerFactory: Automated server creation and registration
• Layered Tools System: Three specialized tools for ability discovery and execution:
  • DiscoverAbilitiesTool: Discovers available WordPress abilities
  • GetAbilityInfoTool: Retrieves detailed information about specific abilities
  • ExecuteAbilityTool: Executes abilities with proper parameter handling

Technical Benefits:

• Implements dynamic ability discovery without hard-coding tool definitions
• Provides a flexible execution model that adapts to WordPress capabilities
• Establishes a standardized interface for WordPress functionality access

3. STDIO Server Bridge for CLI Integration

Complete WP-CLI integration enabling MCP servers to be exposed through STDIO transport, making them accessible from command-line tools and external applications.

Features:

• WP-CLI Command: New wp mcp-adapter command for server management
• StdioServerBridge: Bridges MCP servers to STDIO for command-line communication
• Universal Server Access: Any registered MCP server can be accessed via CLI

Usage:

# Start an MCP server via STDIO
wp mcp-adapter serve --server=mcp-adapter-default-server --user=admin

# List available servers
wp mcp-adapter list

Technical Benefits:

• Enables STDIO transport protocol

4. MCP Component Type System & Auto-Discovery

Introduction of a type-based system for categorizing and automatically discovering MCP components (tools, resources, and prompts).

Key Features:

• Type Classification: Abilities can be explicitly marked as tool, resource, or prompt via meta.mcp.type
• Public Access Control: Fine-grained control over which abilities are exposed through MCP via meta.mcp.public
• Auto-Discovery: The default server automatically discovers resources and prompts based on their mcp.type without manual registration
• Default Behavior: Abilities default to type tool if not specified

Example:

wp_register_ability('my-plugin/post-resource', [
    'label' => 'Post Resource',
    'description' => 'Access WordPress posts',
    'meta' => [
        'mcp' => [
            'public' => true,     // Expose via MCP
            'type'   => 'resource' // Auto-discovered as resource
        ],
        'uri' => 'site://posts/{id}' // Resource-specific metadata
    ]
]);

Technical Benefits:

• Eliminates the need for manual registration of resources and prompts in the default server
• Provides clear component type distinction for better organization
• Enables the default server to automatically configure itself based on ability metadata

Architecture Improvements

Enhanced Core Infrastructure

• Component Registry (McpComponentRegistry): Centralized management of MCP components with improved lifecycle handling
• Transport Factory (McpTransportFactory): Standardized transport creation with dependency injection
• Handler Standardization (HandlerHelperTrait): Consistent implementation patterns across all handlers
• Improved Separation of Concerns: Clear boundaries between transport, server, and handler layers
• Better Dependency Management: Reduced coupling between components through interface-based design

Error Handling Improvements

• Standardized Error Codes: Consistent JSON-RPC error code mapping to HTTP status codes
• Structured Error Responses: JsonRpcResponseBuilder ensures uniform error format across all endpoints
• Enhanced Validation: Comprehensive validation for tool execution, request processing, and parameter handling
• Better Error Context: More informative error messages with proper error chain propagation

Code Quality Enhancements

• Type Safety: Improved type hints and generic specifications throughout the codebase
• Static Analysis: PHPStan compliance improvements with proper type annotations
• Code Standards: Full WordPress coding standards compliance
• Dependency Management: Updated to the latest versions of development dependencies
• Configuration Consistency: All hooks and filters use standardized mcp_adapter_ prefix

Testing & Quality Assurance

Comprehensive Test Coverage (26 test files added/modified):

• Unit tests for all new infrastructure components
• Integration tests for HTTP transport layer and request routing
• Session management and authentication flow tests
• Error handling consistency validation tests
• Handler trait behavior tests
• Transport infrastructure validation tests

Breaking Changes

Removed Components

• RestTransport: Removed and replaced by HttpTransport - all functionality preserved in the new implementation
• StreamableTransport: Removed and replaced by HttpTransport - enhanced streaming capabilities included
• Migration guide provided below for updating existing implementations

Filter Name Standardization

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

• mcp_rest_transport_* → mcp_adapter_rest_transport_*
• mcp_streamable_transport_* → mcp_adapter_streamable_transport_*
• Custom filter implementations require prefix updates

Migration Guide

Transport Migration

See the migration guide for detailed migration instructions.

Filter Migration

// Old filter names
add_filter('mcp_validation_enabled', $callback);

// New standardized names
add_filter('mcp_adapter_validation_enabled', $callback);

Implementation Details

New Infrastructure Components

• HttpTransport - Primary transport implementation with HTTP/1.1 and HTTP/2 support
• HttpRequestHandler - Request processing with proper header management
• HttpSessionValidator - Session validation with WordPress user integration
• SessionManager - Stateful session management with cleanup procedures
• RequestRouter - Intelligent request routing based on HTTP method and content type
• JsonRpcResponseBuilder - JSON-RPC compliant response formatting
• McpTransportContext - Enhanced transport context with better state management
• McpComponentRegistry - Component lifecycle management with proper initialization
• McpTransportFactory - Transport instantiation with configuration injection

CLI Implementation Components

• McpCommand - WP-CLI command implementation with subcommand support
• StdioServerBridge - STDIO transport bridge with proper stream handling

Default Server Tools

• DiscoverAbilitiesTool - WordPress ability discovery with metadata extraction
• ExecuteAbilityTool - Ability execution with parameter validation and error handling
• GetAbilityInfoTool - Detailed ability information retrieval
• DefaultServerFactory - Automated server creation with configuration management

Technical Debt Resolution

Resolved Issues

• Eliminated circular dependencies in the transport layer
• Fixed inconsistent error response formats
• Resolved session state management problems
• Addressed missing type hints and annotations

Architecture Improvements

• Implemented proper dependency injection patterns
• Established clear interface contracts
• Improved separation of concerns across layers
• Standardized configuration management
• Enhanced error propagation mechanisms

Future Technical Considerations

• Enhanced CLI commands for advanced server management scenarios
• Performance optimizations for high-concurrency environments
• Additional metadata-driven features for component discovery and management