 |
VOOZH | about |
|
VOOZH | about |
Complete example demonstrating resource registration and consumption through the ResourcesHandler.
The ResourcesHandler class processes MCP protocol requests for resource operations. Resources provide read-only access to data sources, uniquely identified by URIs. The handler implements two MCP protocol methods: resources/list and resources/read.
Resources are created by registering WordPress abilities with meta.mcp.type = 'resource' (see page 4.1). Unlike tools (page 4.3), resources are read-only and focused on data retrieval.
The ResourcesHandler class depends on McpServer for accessing registered resources and uses HandlerHelperTrait for parameter extraction. It delegates error logging to the server's error_handler.
ResourcesHandler Class Dependencies
| Dependency | Type | Purpose |
|---|---|---|
$mcp | McpServer | Access to resource registry and error handler |
HandlerHelperTrait | Trait | Parameter extraction via extract_params() |
McpErrorFactory | Static Class | Standardized error response generation |
Sources: includes/Handlers/Resources/ResourcesHandler.php19-36
The handler implements two MCP protocol methods that map to the resources capability of the Model Context Protocol specification.
| Handler Method | MCP Protocol Method | Parameters | Returns |
|---|---|---|---|
list_resources() | resources/list | request_id (optional) | Array of resources with metadata |
read_resource() | resources/read | params['uri'], request_id (optional) | Resource contents with metadata |
ResourcesHandler Method Flow
Sources: includes/Handlers/Resources/ResourcesHandler.php46-60 includes/Handlers/Resources/ResourcesHandler.php70-207
Returns all registered resources from the MCP server. Each McpResource is serialized using its to_array() method, which formats the resource according to MCP protocol specifications.
list_resources() Execution Flow
The method iterates over all resources from McpServer::get_resources() and calls to_array() on each, collecting them into a resources array. The _metadata field tracks the component type and total count for observability purposes.
Sources: includes/Handlers/Resources/ResourcesHandler.php46-60
Retrieves content for a specific resource identified by URI. This is the primary method for accessing resource data and includes comprehensive error handling and permission checking.
read_resource() Decision Tree
The method performs the following operations in sequence:
| Step | Operation | Error Condition |
|---|---|---|
| 1 | extract_params($params) | Returns URI string |
| 2 | Validate URI presence | Missing → missing_parameter error |
| 3 | $mcp->get_resource($uri) | Not found → resource_not_found error |
| 4 | $resource->get_ability() | WP_Error → ability_retrieval_failed error |
| 5 | $ability->check_permissions() | False/WP_Error → permission_denied error |
| 6 | $ability->execute() | WP_Error → wp_error error |
| 7 | Catch exceptions | Exception → execution_failed error |
| 8 | Return contents | Success with metadata |
Sources: includes/Handlers/Resources/ResourcesHandler.php70-207
The method uses HandlerHelperTrait::extract_params() to normalize parameter input. The URI parameter is required and must be a non-empty string.
If the URI is missing, the method returns immediately with a missing_parameter error.
Sources: includes/Handlers/Resources/ResourcesHandler.php72-82
The handler retrieves the McpResource instance by calling $mcp->get_resource($uri). This performs a registry lookup in the McpServer instance.
Resource Lookup in McpServer
If get_resource() returns null, the handler returns a resource_not_found error with the URI in the metadata.
Sources: includes/Handlers/Resources/ResourcesHandler.php85-97
Resources are uniquely identified by URIs stored in the meta.uri field during ability registration. The ResourcesHandler uses URIs as the primary lookup key for resources/read requests.
URIs follow a scheme-based format to organize resources by domain. Common patterns include:
| URI Pattern | Example | Purpose |
|---|---|---|
wordpress://site/* | wordpress://site/config | Site-level data |
wordpress://user/* | wordpress://user/profile | User-specific data |
wordpress://content/* | wordpress://content/posts/recent | Content data |
wordpress://plugin/* | wordpress://plugin/settings | Plugin-specific data |
URI-Based Resource Lookup Flow
When an ability is registered with meta.mcp.type = 'resource', the meta.uri field becomes the resource's unique identifier. This URI must be globally unique within the MCP server instance.
The URI serves as both a human-readable identifier and a programmatic key for resource lookup.
Sources: includes/Handlers/Resources/ResourcesHandler.php85-86
The read_resource() method implements a two-step permission check: first verifying resource existence, then delegating to the ability's permission_callback.
Permission Checking Flow in read_resource()
The handler calls $ability->check_permissions() without arguments. The ability's permission_callback is responsible for implementing authorization logic.
| Return Value | Meaning | Handler Behavior |
|---|---|---|
true | Permission granted | Proceeds to execute() |
false | Permission denied (generic) | Returns permission_denied error |
WP_Error | Permission denied (detailed) | Returns error with custom message and code |
When check_permissions() returns a WP_Error, the error code becomes the failure_reason in metadata, and the error message is included in the response. This allows fine-grained permission denial explanations.
Sources: includes/Handlers/Resources/ResourcesHandler.php129-150
All permission-related errors include comprehensive metadata for debugging and observability:
Sources: includes/Handlers/Resources/ResourcesHandler.php141-149
The read_resource() method implements comprehensive error handling for all failure scenarios. Each error includes structured metadata for observability and debugging.
All errors follow a consistent format with both JSON-RPC error objects and metadata:
| Error Type | Trigger | Error Code | Factory Method | Metadata Fields |
|---|---|---|---|---|
| Missing Parameter | No uri in params | -32602 | missing_parameter() | failure_reason: 'missing_parameter' |
| Resource Not Found | get_resource() returns null | -32002 | resource_not_found() | resource_uri, failure_reason: 'not_found' |
| Ability Retrieval Failed | get_ability() returns WP_Error | -32603 | internal_error() | resource_uri, resource_name, failure_reason: 'ability_retrieval_failed', error_code |
| Permission Denied | check_permissions() returns false/WP_Error | -32001 | permission_denied() | resource_uri, resource_name, ability_name, failure_reason |
| WP_Error Returned | execute() returns WP_Error | -32603 | internal_error() | resource_uri, resource_name, ability_name, failure_reason: 'wp_error', error_code |
| Exception Thrown | Exception during execution | -32603 | internal_error() | resource_uri, failure_reason: 'execution_failed', error_type |
Error Handling Decision Tree in read_resource()
The handler selectively logs errors using $mcp->error_handler->log(). Only internal failures (ability retrieval, WP_Error, exceptions) are logged; client errors (missing parameters, not found, permission denied) are not logged.
Logged Errors:
Ability Retrieval Failed - When get_ability() returns WP_Error
WP_Error During Execution - When execute() returns WP_Error
Exception During Execution - When execute() throws exception
Sources: includes/Handlers/Resources/ResourcesHandler.php74-82 includes/Handlers/Resources/ResourcesHandler.php88-96 includes/Handlers/Resources/ResourcesHandler.php107-126 includes/Handlers/Resources/ResourcesHandler.php140-149 includes/Handlers/Resources/ResourcesHandler.php155-176 includes/Handlers/Resources/ResourcesHandler.php188-205
Resources support two mutually exclusive content types returned by the ability's execute() callback: text or blob.
Text resources return string content (JSON, XML, plain text, etc.). The ability's execute() callback should return the content directly or in a structured format.
Blob resources return base64-encoded binary data. The ability's execute() callback should return base64-encoded content with optional MIME type.
The ResourcesHandler extracts content from the ability's execution result:
contents key, uses contents value['contents' => <value>]Content Extraction Logic Sources: includes/Handlers/Resources/ResourcesHandler.php152-187
Resources provide standardized serialization methods for MCP protocol compatibility. The to_array() method formats resource data according to specification requirements, while to_json() provides JSON encoding for transport.
The serialization follows MCP specification field naming conventions, with optional fields included only when they contain values.
| Resource Property | MCP Field | Notes |
|---|---|---|
uri | uri | Required, unique identifier |
name | name | Optional display name |
description | description | Optional description |
mime_type | mimeType | Optional content type |
text | text | Optional text content |
blob | blob | Optional binary content |
annotations | annotations | Optional metadata |
Resource Serialization Process Sources: src/Domain/Resources/McpResource.php308-339 src/Domain/Resources/McpResource.php346-348
Refresh this wiki