ExecuteAbilityAbility

The ExecuteAbilityAbility class provides a meta-ability that enables dynamic execution of any registered WordPress ability through the MCP protocol. This is the primary execution layer that AI agents use to invoke WordPress functionality.

For information about registering custom abilities, see Creating Abilities. For details on how this ability is exposed via MCP tools, see Tools Handler.

Overview and Purpose

ExecuteAbilityAbility serves as an execution proxy that:

• Accepts an ability name and parameters as input
• Validates security at multiple layers
• Executes the target ability
• Returns standardized success/error responses

This design allows AI agents to discover available abilities through DiscoverAbilitiesAbility and then execute them dynamically without requiring hardcoded tool implementations for each ability.

Location: includes/Abilities/ExecuteAbilityAbility.php26-223

Key Characteristics:

• Ability name: mcp-adapter/execute-ability
• Category: mcp-adapter
• Annotations: readonly=false, destructive=true, idempotent=false
• Uses McpAbilityHelperTrait for common security checks

Sources: includes/Abilities/ExecuteAbilityAbility.php26-80

Registration and Schema

Registration

The ability is registered via ExecuteAbilityAbility::register() during the mcp_adapter_init action hook:

Sources: includes/Abilities/ExecuteAbilityAbility.php32-80

Input Schema

Property	Type	Required	Description
ability_name	string	Yes	Full name of the ability to execute
parameters	object	Yes	Parameters to pass to the target ability

The schema enforces additionalProperties: false to prevent unexpected parameters.

Sources: includes/Abilities/ExecuteAbilityAbility.php39-52

Output Schema

Property	Type	Required	Description
success	boolean	Yes	Whether execution succeeded
data	any	No	Result data from the ability (on success)
error	string	No	Error message (on failure)

The data property accepts all JSON types: object, array, string, number, integer, boolean, null. This flexibility accommodates diverse ability return values.

Sources: includes/Abilities/ExecuteAbilityAbility.php54-68 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php435-466

Security Architecture

Multi-Layer Security Model

Diagram: Four-layer security validation for ExecuteAbilityAbility

Sources: includes/Abilities/ExecuteAbilityAbility.php82-127 includes/Abilities/McpAbilityHelperTrait.php1-100

Layer 1: User Authentication

Validates that a WordPress user is authenticated via is_user_logged_in().

Implementation: includes/Abilities/ExecuteAbilityAbility.php134-151

Error Code: authentication_required

Purpose: Ensures caller identity verification - anonymous access is not permitted for dynamic ability execution.

Sources: includes/Abilities/ExecuteAbilityAbility.php136-138 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php165-181

Layer 2: Capability Check

Verifies the authenticated user has a minimum WordPress capability, default read. This can be customized via filter:

Implementation: includes/Abilities/ExecuteAbilityAbility.php141-148

Error Code: insufficient_capability

Purpose: Provides a baseline authorization level. For example, you could require edit_posts to restrict execution to content editors and above.

Sources: includes/Abilities/ExecuteAbilityAbility.php141-148 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php183-213

Layer 3: MCP Exposure Check

Validates that the target ability has meta.mcp.public = true. This check is performed by check_ability_mcp_exposure() from McpAbilityHelperTrait.

Implementation: includes/Abilities/McpAbilityHelperTrait.php41-70

Error Code: ability_not_public_mcp

Purpose: Prevents execution of internal/private abilities not intended for MCP exposure. Only abilities explicitly marked for public MCP access can be executed.

Sources: includes/Abilities/McpAbilityHelperTrait.php41-70 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php215-252

Layer 4: Target Ability Permission

Delegates to the target ability's own permission_callback with the provided parameters.

Implementation: includes/Abilities/ExecuteAbilityAbility.php112-126

Error Handling: Returns WP_Error objects unchanged, converts other falsy values to boolean false.

Purpose: Respects each ability's granular permission logic, allowing abilities to implement custom authorization (e.g., checking specific post ownership).

Sources: includes/Abilities/ExecuteAbilityAbility.php118-126 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php72-80 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php82-91

Permission Checking Flow

Diagram: Permission checking decision tree in check_permission()

Sources: includes/Abilities/ExecuteAbilityAbility.php82-127

Error Codes in Permission Checking

Error Code	Condition	HTTP Status
missing_ability_name	Empty or missing ability_name parameter	400
authentication_required	User not logged in	401
insufficient_capability	User lacks required capability (default: read)	403
ability_not_public_mcp	Target ability meta.mcp.public is not true	403
ability_not_found	Target ability does not exist in registry	404
Target-specific	Target ability's permission_callback returns WP_Error	Varies

Sources: includes/Abilities/ExecuteAbilityAbility.php82-127 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php93-166

Execution Flow

Execute Method Implementation

Diagram: Execution flow showing double permission check and error handling

Sources: includes/Abilities/ExecuteAbilityAbility.php154-222

Defense-in-Depth Permission Check

The execute() method re-validates permissions even though WordPress core already called check_permission() during ability invocation:

Location: includes/Abilities/ExecuteAbilityAbility.php173-182

Rationale: Protects against direct method invocation bypassing WordPress's ability execution pipeline.

Sources: includes/Abilities/ExecuteAbilityAbility.php173-182

Result Handling

The execute() method normalizes three types of results:

1. Successful execution: Wraps result in {success: true, data: <result>}
2. WP_Error return: Converts to {success: false, error: <message>}
3. Exception thrown: Catches and converts to {success: false, error: <message>}

Implementation: includes/Abilities/ExecuteAbilityAbility.php200-221

Sources: includes/Abilities/ExecuteAbilityAbility.php200-221 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php267-406

Usage Examples

Successful Execution

Input:

Output:

Sources: tests/Fixtures/DummyAbility.php69-92 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php267-285

Permission Denied

Input:

Output:

Sources: tests/Fixtures/DummyAbility.php95-113 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php82-91

Ability Not Found

Input:

Output:

Sources: tests/Unit/Abilities/ExecuteAbilityAbilityTest.php316-330

Execution Exception

Input:

Output:

Sources: tests/Fixtures/DummyAbility.php138-157 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php370-406

Code Entity Reference

Class Structure

Diagram: Class structure showing trait composition

Method Reference

Method	Visibility	Return Type	Purpose
register()	public static	void	Registers the ability with WordPress
check_permission($input)	public static	bool|WP_Error	Validates multi-layer permissions
execute($input)	public static	array	Executes target ability with error handling
validate_user_access()	private static	bool|WP_Error	Validates authentication and capabilities

Sources: includes/Abilities/ExecuteAbilityAbility.php26-223

Dependencies

• WordPress Abilities API: Uses wp_register_ability(), wp_get_ability()
• WordPress User Functions: Uses is_user_logged_in(), current_user_can()
• McpAbilityHelperTrait: Inherits check_ability_mcp_exposure() method

Sources: includes/Abilities/ExecuteAbilityAbility.php27-223 includes/Abilities/McpAbilityHelperTrait.php1-100

Annotations and Metadata

The ability is registered with the following annotations:

Annotation	Value	Meaning
readonly	false	Can modify system state
destructive	true	May perform destructive operations (depends on target ability)
idempotent	false	Multiple executions may have different effects

Location: includes/Abilities/ExecuteAbilityAbility.php72-76

Security Note: The destructive=true annotation reflects that this ability can execute any public ability, including those that modify or delete data. The actual destructiveness depends on the target ability being executed.

Sources: includes/Abilities/ExecuteAbilityAbility.php72-76 tests/Unit/Abilities/ExecuteAbilityAbilityTest.php468-479

Integration with MCP Tools

When exposed via the MCP protocol, ExecuteAbilityAbility becomes an MCP tool that AI agents can invoke. The Tools Handler (see Tools Handler) automatically:

1. Lists this tool in tools/list responses
2. Routes tools/call requests with name: "mcp-adapter/execute-ability" to this ability
3. Transforms input/output schemas to MCP-compatible format via SchemaTransformer (see Schema Transformation)

Sources: includes/Abilities/ExecuteAbilityAbility.php1-223