Prompts Handler

Purpose and Scope

The PromptsHandler processes MCP prompt-related requests (prompts/list and prompts/get). It manages prompt discovery and execution, supporting both builder-based prompts (direct execution without abilities) and ability-based prompts (traditional WordPress Abilities API execution). This handler is part of the MCP request processing pipeline.

For information about creating prompts via the WordPress Abilities API, see Creating Abilities. For prompt schema transformation, see Schema Transformation. For transport-level request routing, see Request Router.

Sources: includes/Handlers/Prompts/PromptsHandler.php1-246

---

Architecture and Dependencies

The PromptsHandler class follows the same architectural pattern as other MCP handlers, with a dependency on McpServer for accessing registered prompts and error handling infrastructure.

Class Structure

Sources: includes/Handlers/Prompts/PromptsHandler.php19-36

Dependencies

Dependency	Type	Purpose
McpServer	Constructor injection	Provides access to prompt registry, error handler
HandlerHelperTrait	Trait	Provides extract_params() helper method
McpErrorFactory	Static factory	Creates standardized JSON-RPC error responses

Sources: includes/Handlers/Prompts/PromptsHandler.php10-36

---

Method: list_prompts

The list_prompts() method handles the prompts/list MCP request, returning all registered prompts available on the server.

Execution Flow

Sources: includes/Handlers/Prompts/PromptsHandler.php39-60

Implementation Details

The method performs the following operations:

1. Retrieve prompts: Calls $this->mcp->get_prompts() to get all registered McpPrompt instances
2. Convert to array: Calls to_array() on each prompt to serialize it
3. Return response: Returns array with prompts and _metadata fields

Response Format

Field	Type	Description
prompts	array	Array of prompt definitions, each containing name, description, arguments
_metadata.component_type	string	Always "prompts"
_metadata.prompts_count	int	Number of prompts returned

Sources: includes/Handlers/Prompts/PromptsHandler.php46-60

---

Method: get_prompt

The get_prompt() method handles the prompts/get MCP request, executing a specific prompt and returning generated messages. It supports two execution paths: builder-based and ability-based.

Dual Execution Model

Sources: includes/Handlers/Prompts/PromptsHandler.php63-245

Parameter Extraction and Validation

The method first extracts and validates required parameters:

1. Extract params: Uses extract_params() from HandlerHelperTrait to normalize request parameters
2. Validate name: Checks for required name parameter
3. Retrieve prompt: Calls $this->mcp->get_prompt($prompt_name)

Sources: includes/Handlers/Prompts/PromptsHandler.php70-97

---

Builder-Based Execution

Builder-based prompts execute directly through the McpPrompt object without involving the WordPress Abilities API. This path is used when $prompt->is_builder_based() returns true.

Builder-Based Flow

Sources: includes/Handlers/Prompts/PromptsHandler.php103-128

Implementation Details

Builder-based execution follows these steps:

1. Permission check: Calls check_permission_direct($arguments) which returns a boolean
2. Execute: Calls execute_direct($arguments) to generate messages
3. Metadata: Adds metadata with is_builder: true

Sources: includes/Handlers/Prompts/PromptsHandler.php103-128

---

Ability-Based Execution

Ability-based prompts execute through the traditional WordPress Abilities API, using WP_Ability instances. This is the default path when is_builder_based() returns false.

Ability-Based Flow

Sources: includes/Handlers/Prompts/PromptsHandler.php130-224

Implementation Details

Ability-based execution involves these steps:

1. Get ability: Calls $prompt->get_ability() to retrieve the underlying WP_Ability instance
2. Handle retrieval errors: If is_wp_error($ability), logs and returns error
3. Normalize arguments: If ability has no input schema and arguments are empty, sets arguments to null (required by WP_Ability::validate_input())
4. Permission check: Calls $ability->check_permissions($arguments), which returns true, false, or WP_Error
5. Execute: Calls $ability->execute($arguments)
6. Handle execution errors: If result is WP_Error, logs and returns error
7. Metadata: Adds metadata with is_builder: false and ability_name

Sources: includes/Handlers/Prompts/PromptsHandler.php130-224

Permission Check Detail

The permission check extracts detailed error information when check_permissions() returns a WP_Error:

Sources: includes/Handlers/Prompts/PromptsHandler.php167-188

---

Error Handling

The PromptsHandler implements comprehensive error handling with logging and standardized error responses.

Error Types and Responses

Sources: includes/Handlers/Prompts/PromptsHandler.php74-244

Error Response Format

All error responses follow a consistent structure:

Field	Type	Description
error	object	JSON-RPC error object from McpErrorFactory
_metadata.component_type	string	Always "prompt"
_metadata.prompt_name	string	Name of the prompt (if available)
_metadata.failure_reason	string	Error category: missing_parameter, not_found, permission_denied, ability_retrieval_failed, wp_error, execution_failed
_metadata.is_builder	bool	Whether this was builder-based (if reached execution stage)
_metadata.ability_name	string	Ability name (ability-based prompts only)
_metadata.error_code	string	WP_Error code (if applicable)
_metadata.error_type	string	Exception class name (for caught Throwables)

Sources: includes/Handlers/Prompts/PromptsHandler.php74-244

Logging Integration

The handler logs errors to the server's configured error handler:

Error logging occurs for:

• Ability retrieval failures includes/Handlers/Prompts/PromptsHandler.php141-147
• WP_Error results from execution includes/Handlers/Prompts/PromptsHandler.php194-201
• Throwable exceptions includes/Handlers/Prompts/PromptsHandler.php226-233

Sources: includes/Handlers/Prompts/PromptsHandler.php141-233

Exception Handling

A top-level try-catch wraps the entire execution flow to handle unexpected exceptions:

Sources: includes/Handlers/Prompts/PromptsHandler.php225-244

---

Request and Response Formats

list_prompts Request

MCP Method: prompts/list

Parameters: None

Example JSON-RPC Request:

list_prompts Response

Success Response:

Sources: includes/Handlers/Prompts/PromptsHandler.php46-60

get_prompt Request

MCP Method: prompts/get

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Name of the prompt to execute
arguments	object	No	Arguments to pass to the prompt

Example JSON-RPC Request:

get_prompt Response

Success Response (Builder-Based):

Success Response (Ability-Based):

Error Response:

Sources: includes/Handlers/Prompts/PromptsHandler.php70-244

---

Integration Points

The PromptsHandler integrates with several other system components:

Component Interactions

Sources: includes/Handlers/Prompts/PromptsHandler.php1-246

Related Components

Component	Relationship	Purpose
RequestRouter	Upstream	Routes prompts/list and prompts/get requests to this handler
McpServer	Dependency	Provides prompt registry and error handler
McpPrompt	Data model	Represents individual prompts with execution logic
WP_Ability	Data model	Underlying ability for ability-based prompts
McpErrorFactory	Utility	Creates standardized JSON-RPC errors
HandlerHelperTrait	Helper	Provides extract_params() method

For details on registering prompts, see Creating Abilities. For prompt component structure, see Domain Conversions. For request routing, see Request Router.

Sources: includes/Handlers/Prompts/PromptsHandler.php1-246