# wordpress/mcp-adapter architecture

> Architecture diagram of the GitHub repository wordpress/mcp-adapter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wordpress/mcp-adapter
- Repository: https://github.com/wordpress/mcp-adapter

## Overview

MCP Adapter exposes WordPress Abilities API functionality to MCP clients as tools, resources, and prompts. Clients connect through HTTP or WP-CLI STDIO; requests are handled by a server and dispatched to the relevant MCP operation, which checks permissions and executes the registered ability or component before returning protocol results. The README also documents multiple servers, custom transports, per-server authentication, and pluggable error handling and observability. The tree and excerpts support these subsystem boundaries; some internal wiring is not shown, so uncertain call edges are omitted.

Main entry points: [`includes/Core/McpServer.php`](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Core/McpServer.php) (MCP server), [`includes/Transport/Infrastructure/RequestRouter.php`](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/RequestRouter.php) (Request router), [`includes/Core/McpComponentRegistry.php`](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Core/McpComponentRegistry.php) (Component registry), [`includes/Handlers/Tools/ToolsHandler.php`](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Tools/ToolsHandler.php) (Tools handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transports["Client transports"]
  node_http["HTTP transport<br/>[HttpTransport.php]"]
  node_http_handler["HTTP request handler"]
  node_wire["Wire orchestrator"]
  node_decoder["JSON-RPC decoder"]
  node_router["Request router<br/>[RequestRouter.php]"]
  node_sessions["Session manager<br/>[SessionManager.php]"]
  node_cli["STDIO bridge"]
  node_cli_command["WP-CLI command<br/>[McpCommand.php]"]
end

subgraph group_server["Server core"]
  node_plugin["Plugin bootstrap<br/>[Plugin.php]"]
  node_server_factory["Default server factory"]
  node_server["MCP server<br/>[McpServer.php]"]
  node_registry["Component registry"]
  node_transport_factory["Transport factory"]
end

subgraph group_exposure["Ability exposure"]
  node_tool_component["Tool component<br/>[McpTool.php]"]
  node_resource_component["Resource component<br/>[McpResource.php]"]
  node_prompt_component["Prompt component<br/>[McpPrompt.php]"]
  node_ability_tool["Ability as tool"]
  node_ability_resource["Ability as resource"]
  node_ability_prompt["Ability as prompt"]
  node_meta_tools["Ability meta-tools"]
end

subgraph group_operations["MCP operations"]
  node_tools_handler["Tools handler<br/>[ToolsHandler.php]"]
  node_resources_handler["Resources handler"]
  node_prompts_handler["Prompts handler<br/>[PromptsHandler.php]"]
  node_initialize_handler["Initialize handler"]
end

subgraph group_support["Runtime support"]
  node_user_meta[("WordPress user meta")]
  node_error_handling["Error handling"]
  node_observability["Observability"]
end

node_client(("MCP client"))
node_wpcli(("WP-CLI user"))
node_abilities_api["WordPress Abilities API"]

node_client -->|"sends HTTP"| node_http
node_http -->|"handles requests"| node_http_handler
node_http_handler -->|"processes wire data"| node_wire
node_client -->|"connects via STDIO"| node_cli_command
node_wpcli -->|"invokes"| node_cli_command
node_cli_command -->|"bridges STDIO"| node_cli
node_cli -->|"serves requests"| node_server
node_wire -->|"decodes JSON-RPC"| node_decoder
node_wire -->|"routes requests"| node_router
node_http_handler -->|"validates sessions"| node_sessions
node_sessions -->|"reads and writes"| node_user_meta
node_plugin -->|"creates default server"| node_server_factory
node_server_factory -->|"builds server"| node_server
node_server -->|"registers components"| node_registry
node_server -->|"creates transports"| node_transport_factory
node_router -->|"dispatches tool calls"| node_tools_handler
node_router -->|"dispatches resource requests"| node_resources_handler
node_router -->|"dispatches prompt requests"| node_prompts_handler
node_router -->|"dispatches initialization"| node_initialize_handler
node_server -->|"provides server context"| node_tools_handler
node_server -->|"provides server context"| node_resources_handler
node_server -->|"provides server context"| node_prompts_handler
node_server -->|"provides server context"| node_initialize_handler
node_registry -->|"registers tools"| node_tool_component
node_registry -->|"registers resources"| node_resource_component
node_registry -->|"registers prompts"| node_prompt_component
node_ability_tool -->|"wraps abilities"| node_abilities_api
node_ability_resource -->|"wraps abilities"| node_abilities_api
node_ability_prompt -->|"wraps abilities"| node_abilities_api
node_ability_tool -->|"registers tool"| node_tool_component
node_ability_resource -->|"registers resource"| node_resource_component
node_ability_prompt -->|"registers prompt"| node_prompt_component
node_tools_handler -->|"executes tool"| node_tool_component
node_resources_handler -->|"reads resource"| node_resource_component
node_prompts_handler -->|"executes prompt"| node_prompt_component
node_meta_tools -->|"discovers and executes"| node_abilities_api
node_tools_handler -->|"builds protocol errors"| node_error_handling
node_resources_handler -->|"builds protocol errors"| node_error_handling
node_prompts_handler -->|"builds protocol errors"| node_error_handling

click node_http "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/HttpTransport.php"
click node_http_handler "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/HttpRequestHandler.php"
click node_wire "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/McpWireOrchestrator.php"
click node_decoder "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/JsonRpcRequestDecoder.php"
click node_router "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/RequestRouter.php"
click node_sessions "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/SessionManager.php"
click node_cli "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Cli/StdioServerBridge.php"
click node_cli_command "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Cli/McpCommand.php"
click node_plugin "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Plugin.php"
click node_server_factory "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Servers/DefaultServerFactory.php"
click node_server "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Core/McpServer.php"
click node_registry "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Core/McpComponentRegistry.php"
click node_transport_factory "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Core/McpTransportFactory.php"
click node_tools_handler "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Tools/ToolsHandler.php"
click node_resources_handler "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Resources/ResourcesHandler.php"
click node_prompts_handler "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Prompts/PromptsHandler.php"
click node_initialize_handler "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Initialize/InitializeHandler.php"
click node_tool_component "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Tools/McpTool.php"
click node_resource_component "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Resources/McpResource.php"
click node_prompt_component "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Prompts/McpPrompt.php"
click node_ability_tool "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Tools/RegisterAbilityAsMcpTool.php"
click node_ability_resource "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Resources/RegisterAbilityAsMcpResource.php"
click node_ability_prompt "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php"
click node_meta_tools "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Abilities/ExecuteAbilityAbility.php"
click node_error_handling "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Infrastructure/ErrorHandling/McpErrorFactory.php"
click node_observability "https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Infrastructure/Observability/Contracts/McpObservabilityHandlerInterface.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_http,node_http_handler,node_wire,node_decoder,node_router,node_sessions,node_cli,node_cli_command,node_client,node_wpcli toneBlue
class node_plugin,node_server_factory,node_server,node_registry,node_transport_factory toneAmber
class node_tool_component,node_resource_component,node_prompt_component,node_ability_tool,node_ability_resource,node_ability_prompt,node_meta_tools,node_abilities_api toneMint
class node_tools_handler,node_resources_handler,node_prompts_handler,node_initialize_handler toneRose
class node_user_meta,node_error_handling,node_observability toneIndigo
```

## Components

### Client transports

- [HTTP transport](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/HttpTransport.php): `includes/Transport/HttpTransport.php`
- [HTTP request handler](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/HttpRequestHandler.php): `includes/Transport/Infrastructure/HttpRequestHandler.php`
- [Wire orchestrator](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/McpWireOrchestrator.php): `includes/Transport/Infrastructure/McpWireOrchestrator.php`
- [JSON-RPC decoder](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/JsonRpcRequestDecoder.php): `includes/Transport/Infrastructure/JsonRpcRequestDecoder.php`
- [Request router](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/RequestRouter.php): `includes/Transport/Infrastructure/RequestRouter.php`
- [Session manager](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Transport/Infrastructure/SessionManager.php): `includes/Transport/Infrastructure/SessionManager.php`
- [STDIO bridge](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Cli/StdioServerBridge.php): `includes/Cli/StdioServerBridge.php`
- [WP-CLI command](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Cli/McpCommand.php): `includes/Cli/McpCommand.php`

### Server core

- [Plugin bootstrap](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Plugin.php): `includes/Plugin.php`
- [Default server factory](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Servers/DefaultServerFactory.php): `includes/Servers/DefaultServerFactory.php`
- [MCP server](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Core/McpServer.php): `includes/Core/McpServer.php`
- [Component registry](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Core/McpComponentRegistry.php): `includes/Core/McpComponentRegistry.php`
- [Transport factory](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Core/McpTransportFactory.php): `includes/Core/McpTransportFactory.php`

### Ability exposure

- [Tool component](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Tools/McpTool.php): `includes/Domain/Tools/McpTool.php`
- [Resource component](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Resources/McpResource.php): `includes/Domain/Resources/McpResource.php`
- [Prompt component](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Prompts/McpPrompt.php): `includes/Domain/Prompts/McpPrompt.php`
- [Ability as tool](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Tools/RegisterAbilityAsMcpTool.php): `includes/Domain/Tools/RegisterAbilityAsMcpTool.php`
- [Ability as resource](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Resources/RegisterAbilityAsMcpResource.php): `includes/Domain/Resources/RegisterAbilityAsMcpResource.php`
- [Ability as prompt](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php): `includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php`
- [Ability meta-tools](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Abilities/ExecuteAbilityAbility.php): `includes/Abilities/ExecuteAbilityAbility.php`

### MCP operations

- [Tools handler](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Tools/ToolsHandler.php): `includes/Handlers/Tools/ToolsHandler.php`
- [Resources handler](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Resources/ResourcesHandler.php): `includes/Handlers/Resources/ResourcesHandler.php`
- [Prompts handler](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Prompts/PromptsHandler.php): `includes/Handlers/Prompts/PromptsHandler.php`
- [Initialize handler](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Handlers/Initialize/InitializeHandler.php): `includes/Handlers/Initialize/InitializeHandler.php`

### Runtime support

- **WordPress user meta**
- [Error handling](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Infrastructure/ErrorHandling/McpErrorFactory.php): `includes/Infrastructure/ErrorHandling/McpErrorFactory.php`
- [Observability](https://github.com/wordpress/mcp-adapter/blob/trunk/includes/Infrastructure/Observability/Contracts/McpObservabilityHandlerInterface.php): `includes/Infrastructure/Observability/Contracts/McpObservabilityHandlerInterface.php`

### Other components

- **MCP client**
- **WP-CLI user**
- **WordPress Abilities API**

## Connections

- MCP client → HTTP transport: sends HTTP
- HTTP transport → HTTP request handler: handles requests
- HTTP request handler → Wire orchestrator: processes wire data
- MCP client → WP-CLI command: connects via STDIO
- WP-CLI user → WP-CLI command: invokes
- WP-CLI command → STDIO bridge: bridges STDIO
- STDIO bridge → MCP server: serves requests
- Wire orchestrator → JSON-RPC decoder: decodes JSON-RPC
- Wire orchestrator → Request router: routes requests
- HTTP request handler → Session manager: validates sessions
- Session manager → WordPress user meta: reads and writes
- Plugin bootstrap → Default server factory: creates default server
- Default server factory → MCP server: builds server
- MCP server → Component registry: registers components
- MCP server → Transport factory: creates transports
- Request router → Tools handler: dispatches tool calls
- Request router → Resources handler: dispatches resource requests
- Request router → Prompts handler: dispatches prompt requests
- Request router → Initialize handler: dispatches initialization
- MCP server → Tools handler: provides server context
- MCP server → Resources handler: provides server context
- MCP server → Prompts handler: provides server context
- MCP server → Initialize handler: provides server context
- Component registry → Tool component: registers tools
- Component registry → Resource component: registers resources
- Component registry → Prompt component: registers prompts
- Ability as tool → WordPress Abilities API: wraps abilities
- Ability as resource → WordPress Abilities API: wraps abilities
- Ability as prompt → WordPress Abilities API: wraps abilities
- Ability as tool → Tool component: registers tool
- Ability as resource → Resource component: registers resource
- Ability as prompt → Prompt component: registers prompt
- Tools handler → Tool component: executes tool
- Resources handler → Resource component: reads resource
- Prompts handler → Prompt component: executes prompt
- Ability meta-tools → WordPress Abilities API: discovers and executes
- Tools handler → Error handling: builds protocol errors
- Resources handler → Error handling: builds protocol errors
- Prompts handler → Error handling: builds protocol errors