<?php
/**
* AbilitiesTracking class file.
*/
declare( strict_types=1 );
namespace Automattic\WooCommerce\Internal\Abilities;
use Automattic\Jetpack\Status;
use WP_Error;
use WP_REST_Request;
defined( 'ABSPATH' ) || exit;
/**
* Records a Tracks event for each WooCommerce ability invocation.
*
* Hooks only collect data in memory. Events are sent once per request on shutdown through the batched
* Tracks client. Ability input and output are never recorded, except the name of a registered ability an agent
* looks up through the MCP Adapter.
*
* WordPress 7.0 only fires hooks around successful executions, so failures there are recorded on shutdown
* with an `unknown` error code and no duration. WordPress 7.1+ hooks expose the other outcomes. A missing
* input schema is returned before those hooks and stays `unknown`.
*
* @since 11.3.0
*/
class AbilitiesTracking {
/**
* Tracks event name, without the `wcadmin_` prefix.
*
* @var string
*/
private const EVENT_NAME = 'ability_called';
/**
* Tracks event for agents looking up abilities through the MCP Adapter, without the `wcadmin_` prefix.
*
* @var string
*/
private const DISCOVERY_EVENT_NAME = 'ability_discovered';
/**
* Channels whose calls are recorded: agent entry points, not plugin internals.
*
* @var string[]
*/
private const TRACKED_CHANNELS = array( 'mcp', 'rest', 'cli' );
/**
* Only abilities in this namespace are tracked.
*
* @var string
*/
private const ABILITY_PREFIX = 'woocommerce/';
/**
* Upper bound of tracked invocations per request, to keep memory and the shutdown flush bounded.
*
* @var int
*/
private const MAX_EVENTS_PER_REQUEST = 25;
/**
* Matches the core Abilities API route that runs an ability.
*
* @var string
*/
private const ABILITIES_RUN_ROUTE_REGEX = '#^/wp-abilities/v\d+/abilities/.+/run$#i';
/**
* Known MCP clients, as normalized name tokens mapped to the recorded value. Checked in order.
*
* @var array<string, string>
*/
private const KNOWN_MCP_CLIENTS = array(
'claude_code' => 'claude_code',
'claude' => 'claude',
'codex' => 'codex',
'chatgpt' => 'chatgpt',
'openai' => 'chatgpt',
'cursor' => 'cursor',
'windsurf' => 'windsurf',
'vscode' => 'vscode',
'visual_studio_code' => 'vscode',
'copilot' => 'copilot',
'gemini' => 'gemini',
'cline' => 'cline',
'goose' => 'goose',
'zed' => 'zed',
'mcp_inspector' => 'mcp_inspector',
'mcp_wordpress_remote' => 'mcp_wordpress_remote',
);
/**
* Value sent for properties that don't apply or are unknown.
*
* @var string
*/
private const NONE = 'none';
/**
* Open ability invocations, innermost last.
*
* @var array<int, array{name: string, channel: string, rest_namespace: string, external_client: string, start: float, executing: bool}>
*/
private array $frames = array();
/**
* Tracks properties of events waiting to be sent.
*
* @var array<int, array<string, mixed>>
*/
private array $events = array();
/**
* Whether this request is an MCP request: an MCP Adapter tool call happened, or the request has MCP HTTP headers.
*
* @var bool|null Null until checked.
*/
private ?bool $is_mcp_request = null;
/**
* MCP client recorded with events, resolved when first needed.
*
* @var string|null
*/
private ?string $external_client = null;
/**
* REST requests being dispatched, outermost first.
*
* @var array<int, WP_REST_Request<array<string, mixed>>>
*/
private array $rest_requests = array();
/**
* Number of invocations opened when each REST request in $rest_requests started dispatching.
*
* @var int[]
*/
private array $rest_frames_opened = array();
/**
* Number of events not recorded because the per-request limit was reached.
*
* @var int
*/
private int $events_dropped = 0;
/**
* Number of invocations opened in this request.
*
* @var int
*/
private int $frames_opened = 0;
/**
* Constructor.
*/
public function __construct() {
add_action( 'init', array( $this, 'handle_init' ) );
}
/**
* Attach the tracking hooks when the store allows usage tracking, or on multisite.
*
* Consent is per site and a request can switch sites, so on multisite the hooks are always attached and consent is
* checked for each call instead.
*
* @internal
*/
public function handle_init(): void {
if ( ! is_multisite() && ! self::is_tracking_allowed() ) {
return;
}
add_action( 'wp_ability_invoked', array( $this, 'handle_wp_ability_invoked' ) );
add_filter( 'wp_ability_normalize_input', array( $this, 'handle_wp_ability_normalize_input' ), PHP_INT_MAX, 2 );
add_filter( 'wp_pre_execute_ability', array( $this, 'handle_wp_pre_execute_ability' ), PHP_INT_MAX, 2 );
add_filter( 'wp_ability_validate_input', array( $this, 'handle_wp_ability_validate_input' ), PHP_INT_MAX, 3 );
add_filter( 'wp_ability_permission_result', array( $this, 'handle_wp_ability_permission_result' ), PHP_INT_MAX, 2 );
add_action( 'wp_before_execute_ability', array( $this, 'handle_wp_before_execute_ability' ) );
add_filter( 'wp_ability_execute_result', array( $this, 'handle_wp_ability_execute_result' ), PHP_INT_MAX, 2 );
add_filter( 'wp_ability_validate_output', array( $this, 'handle_wp_ability_validate_output' ), PHP_INT_MAX, 3 );
add_action( 'wp_after_execute_ability', array( $this, 'handle_wp_after_execute_ability' ), 10, 2 );
add_filter( 'mcp_adapter_pre_tool_call', array( $this, 'handle_mcp_adapter_pre_tool_call' ) );
add_filter( 'rest_request_before_callbacks', array( $this, 'handle_rest_request_before_callbacks' ), 10, 3 );
add_filter( 'rest_request_after_callbacks', array( $this, 'handle_rest_request_after_callbacks' ), 10, 3 );
// Last, so ability calls made by other shutdown handlers are recorded too.
add_action( 'shutdown', array( $this, 'handle_shutdown' ), PHP_INT_MAX );
}
/**
* Handle the wp_ability_invoked action (WordPress 7.1+), which fires for every call.
*
* @internal
*
* @param string $ability_name The ability name.
*/
public function handle_wp_ability_invoked( $ability_name ): void {
if ( self::is_tracked_ability( $ability_name ) ) {
$this->open_frame( $ability_name, false );
}
}
/**
* Handle the wp_ability_normalize_input filter (WordPress 7.1+), to record a rejected normalization.
*
* A missing input schema never reaches this filter. That failure stays unclosed and is recorded as unknown.
*
* @internal
*
* @param mixed $input The normalized input, or a WP_Error when a filter rejected it. Not recorded.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_normalize_input( $input, $ability_name ) {
if ( is_wp_error( $input ) ) {
$this->close_frame( $ability_name, false, $input );
}
return $input;
}
/**
* Handle the wp_pre_execute_ability filter (WordPress 7.1+), to record short-circuited calls.
*
* @internal
*
* @param mixed $pre The pre-computed result, or the core sentinel to continue execution.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_pre_execute_ability( $pre, $ability_name ) {
// WP_Filter_Sentinel ships with WordPress 7.1, which the PHPStan WordPress stubs predate (see #69841).
if ( ! $pre instanceof \WP_Filter_Sentinel ) { // @phpstan-ignore class.notFound
$this->close_frame( $ability_name, false, $pre );
}
return $pre;
}
/**
* Handle the wp_ability_validate_input filter (WordPress 7.1+), to record invalid input.
*
* @internal
*
* @param mixed $is_valid True, or false or a WP_Error when the input is invalid.
* @param mixed $input The input. Not recorded.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_validate_input( $is_valid, $input, $ability_name ) {
unset( $input );
$error = self::get_validation_error( $is_valid, 'ability_invalid_input' );
if ( $error ) {
$this->close_frame( $ability_name, false, $error );
}
return $is_valid;
}
/**
* Handle the wp_ability_permission_result filter (WordPress 7.1+), to record permission denials.
*
* @internal
*
* @param mixed $permission True when the call is allowed.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_permission_result( $permission, $ability_name ) {
if ( true !== $permission ) {
// Matches the error WP_Ability::execute() returns for denied calls.
$error = new WP_Error( 'ability_invalid_permissions' );
// The MCP Adapter checks permission before executing and never runs a refused call, so no frame is open.
// Only a tool call counts: other permission checks in the same request aren't refused calls.
if ( self::is_tracked_ability( $ability_name ) && null === $this->find_frame( $ability_name, false ) && $this->is_json_rpc_tool_call() ) {
$this->add_event( $this->create_frame( $ability_name, false ), $error, false );
++$this->frames_opened;
} else {
$this->close_frame( $ability_name, false, $error );
}
}
return $permission;
}
/**
* Handle the wp_before_execute_ability action.
*
* @internal
*
* @param string $ability_name The ability name.
*/
public function handle_wp_before_execute_ability( $ability_name ): void {
if ( ! self::is_tracked_ability( $ability_name ) ) {
return;
}
$index = $this->find_frame( $ability_name, false );
if ( null !== $index ) {
// Opened by wp_ability_invoked; time only the execution so durations match on WordPress 7.0.
$frame = $this->frames[ $index ];
$frame['executing'] = true;
$frame['start'] = microtime( true );
$this->frames[ $index ] = $frame;
return;
}
$this->open_frame( $ability_name, true );
}
/**
* Handle the wp_ability_execute_result filter (WordPress 7.1+), to record execution errors.
*
* @internal
*
* @param mixed $result The execution result. Not recorded.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_execute_result( $result, $ability_name ) {
if ( is_wp_error( $result ) ) {
$this->close_frame( $ability_name, true, $result );
}
return $result;
}
/**
* Handle the wp_ability_validate_output filter (WordPress 7.1+), to record invalid output.
*
* @internal
*
* @param mixed $is_valid True, or false or a WP_Error when the output is invalid.
* @param mixed $output The output. Not recorded.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_validate_output( $is_valid, $output, $ability_name ) {
unset( $output );
$error = self::get_validation_error( $is_valid, 'ability_invalid_output' );
if ( $error ) {
$this->close_frame( $ability_name, true, $error );
}
return $is_valid;
}
/**
* Handle the wp_after_execute_ability action, which fires after a successful execution.
*
* @internal
*
* @param string $ability_name The ability name.
* @param mixed $input The input. Only read for MCP Adapter discovery.
*/
public function handle_wp_after_execute_ability( $ability_name, $input = null ): void {
$this->close_frame( $ability_name, true, null );
$this->record_discovery( $ability_name, $input );
}
/**
* Handle the mcp_adapter_pre_tool_call filter, to mark the request as an MCP request.
*
* Covers MCP Adapter transports without MCP HTTP headers, such as STDIO.
*
* @internal
*
* @param mixed $args The tool arguments.
* @return mixed The unchanged arguments.
*/
public function handle_mcp_adapter_pre_tool_call( $args ) {
$this->is_mcp_request = true;
return $args;
}
/**
* Handle the rest_request_before_callbacks filter, to know which REST routes are being dispatched.
*
* @internal
*
* @param mixed $response The response, or null to continue dispatching.
* @param mixed $handler The route handler.
* @param mixed $request The request.
* @return mixed The unchanged response.
*/
public function handle_rest_request_before_callbacks( $response, $handler, $request ) {
unset( $handler );
if ( $request instanceof WP_REST_Request ) {
$this->rest_requests[] = $request;
$this->rest_frames_opened[] = $this->frames_opened;
}
return $response;
}
/**
* Handle the rest_request_after_callbacks filter.
*
* Also records run requests that the Abilities API rejected before execution, for example on permission checks.
*
* @internal
*
* @param mixed $response The response.
* @param mixed $handler The route handler.
* @param mixed $request The request.
* @return mixed The unchanged response.
*/
public function handle_rest_request_after_callbacks( $response, $handler, $request ) {
unset( $handler );
if ( ! $request instanceof WP_REST_Request ) {
return $response;
}
$frames_opened_before = (int) array_pop( $this->rest_frames_opened );
$ability_name = $request['name'];
if (
is_wp_error( $response )
// Abilities not exposed to REST look like unknown routes to callers; probing them isn't ability usage.
&& 'rest_ability_not_found' !== $response->get_error_code()
&& $this->frames_opened === $frames_opened_before
&& 1 === preg_match( self::ABILITIES_RUN_ROUTE_REGEX, $request->get_route() )
&& self::is_tracked_ability( $ability_name )
&& wp_has_ability( $ability_name )
&& self::is_tracking_allowed()
) {
$this->add_event( $this->create_frame( $ability_name, false ), $response, false );
}
array_pop( $this->rest_requests );
return $response;
}
/**
* Handle the shutdown action: record calls that never finished, then send the queued events.
*
* @internal
*/
public function handle_shutdown(): void {
while ( $this->frames ) {
$this->add_event( array_pop( $this->frames ), null, false );
}
if ( ! $this->events ) {
return;
}
$this->flush_events();
// This runs after WC_Tracks_Client's own send at priority 20, so the queued pixels are sent here.
try {
$this->send_queued_pixels();
} catch ( \Throwable $e ) {
unset( $e );
}
}
/**
* Queue one event in the batched Tracks client, which sends queued events on shutdown.
*
* @param array<string, mixed> $properties All Tracks properties of the event.
*/
protected function send_event( array $properties ): void {
$user = wp_get_current_user();
// WC_Tracks::record_event() skips the test suite, whose users use the wptests_ table prefix.
if ( $user instanceof \WP_User && 'wptests_capabilities' === $user->cap_key ) {
return;
}
\WC_Tracks_Client::record_event_batched( $properties );
}
/**
* Send the pixels queued in the batched Tracks client now.
*/
protected function send_queued_pixels(): void {
\WC_Tracks_Client::send_batched_pixels();
}
/**
* Whether this process can outlive many requests' worth of calls, such as an MCP STDIO server run with WP-CLI.
*
* @return bool
*/
protected function is_long_running_process(): bool {
return defined( 'WP_CLI' ) && WP_CLI;
}
/**
* Hand the recorded events to the Tracks client.
*/
private function flush_events(): void {
// Runs on shutdown, where an exception would also stop later shutdown callbacks.
try {
$last = array_key_last( $this->events );
if ( null !== $last && $this->events_dropped > 0 ) {
$this->events[ $last ]['events_dropped'] = $this->events_dropped;
$this->events_dropped = 0;
}
$events = $this->events;
$this->events = array();
} catch ( \Throwable $e ) {
unset( $e );
return;
}
foreach ( $events as $properties ) {
try {
$this->send_event( $properties );
} catch ( \Throwable $e ) {
unset( $e );
}
}
}
/**
* Start tracking an invocation.
*
* @param string $ability_name The ability name.
* @param bool $executing Whether execution already started (WordPress 7.0 path).
*/
private function open_frame( string $ability_name, bool $executing ): void {
// Consent is per site, and the site can change mid-request with switch_to_blog().
if ( ! self::is_tracking_allowed() ) {
return;
}
// Only agent entry points. Direct PHP and cron calls are plugin internals and could add a pixel to every page view.
if ( ! in_array( $this->get_channel(), self::TRACKED_CHANNELS, true ) ) {
return;
}
// Calls that fail without a closing hook keep their frame until shutdown. Recording the oldest one as an
// unknown failure keeps the stack bounded and lets later closing hooks still find their own frame.
if ( count( $this->frames ) >= self::MAX_EVENTS_PER_REQUEST ) {
$oldest = $this->frames[0];
array_shift( $this->frames );
$this->add_event( $oldest, null, false );
}
$this->frames[] = $this->create_frame( $ability_name, $executing );
++$this->frames_opened;
}
/**
* Create the record of an invocation, with the context it started in.
*
* @param string $ability_name The ability name.
* @param bool $executing Whether execution already started.
* @return array{name: string, channel: string, rest_namespace: string, external_client: string, start: float, executing: bool}
*/
private function create_frame( string $ability_name, bool $executing ): array {
$channel = $this->get_channel();
return array(
'name' => $ability_name,
'channel' => $channel,
'rest_namespace' => $this->get_rest_namespace(),
// Resolved now: the request metadata it reads is gone once the REST request finishes.
'external_client' => 'mcp' === $channel ? $this->get_external_client() : self::NONE,
'start' => microtime( true ),
'executing' => $executing,
);
}
/**
* Finish tracking the innermost open invocation of an ability.
*
* Invocations opened after it are calls that failed without a closing hook. On WordPress 7.0, a failed recursive
* call of the same ability can't be told apart from the outer call, so their outcomes can swap; counts stay right.
*
* @param mixed $ability_name The ability name.
* @param bool $executing Execution state the invocation must be in; hooks before and after execution share filters with other callers.
* @param mixed $result Null for success, a WP_Error for failure, or a short-circuited result.
*/
private function close_frame( $ability_name, bool $executing, $result ): void {
if ( ! self::is_tracked_ability( $ability_name ) ) {
return;
}
$index = $this->find_frame( $ability_name, $executing );
if ( null === $index ) {
return;
}
$frame = $this->frames[ $index ];
foreach ( array_splice( $this->frames, $index ) as $offset => $closed_frame ) {
if ( $offset > 0 ) {
$this->add_event( $closed_frame, null, false );
}
}
// Only executed calls report a duration, so it always measures execution.
$this->add_event( $frame, is_wp_error( $result ) ? $result : true, $frame['executing'] );
}
/**
* Find the innermost open invocation of an ability in a given execution state.
*
* Matching the state keeps a recursive call that failed without a closing hook from hiding its outer call.
*
* @param string $ability_name The ability name.
* @param bool $executing Whether the invocation must have started executing.
* @return int|null Index in the frames stack, or null when none is open.
*/
private function find_frame( string $ability_name, bool $executing ): ?int {
for ( $index = count( $this->frames ) - 1; $index >= 0; $index-- ) {
if ( $ability_name === $this->frames[ $index ]['name'] && $executing === $this->frames[ $index ]['executing'] ) {
return $index;
}
}
return null;
}
/**
* Queue a finished invocation as an ability_called event.
*
* @param array{name: string, channel: string, rest_namespace: string, external_client: string, start: float, executing: bool} $frame The invocation.
* @param true|WP_Error|null $outcome True for success, a WP_Error for a known failure, null for an unknown failure.
* @param bool $has_duration Whether the duration is known.
*/
private function add_event( array $frame, $outcome, bool $has_duration ): void {
$error_code = self::NONE;
if ( $outcome instanceof WP_Error ) {
$error_code = self::get_error_code( $outcome );
} elseif ( null === $outcome ) {
$error_code = 'unknown';
}
$event = array(
'ability_name' => self::get_event_ability_name( $frame['name'] ),
'outcome' => true === $outcome ? 'success' : 'error',
'error_code' => $error_code,
'channel' => $frame['channel'],
'rest_namespace' => $frame['rest_namespace'],
'external_client' => $frame['external_client'],
);
if ( $has_duration ) {
$event['duration_ms'] = (int) round( ( microtime( true ) - $frame['start'] ) * 1000 );
}
// Unknown failures are recorded later than the call (WordPress 7.0 has no hook for them), so they keep the call's
// start time. Site and user are still read now; they differ only if the request switched them since.
$this->queue_event( self::EVENT_NAME, $event, null === $outcome ? $frame['start'] : null );
}
/**
* Record an agent looking up abilities through the MCP Adapter: `get-ability-info` for a tracked ability, or
* `discover-abilities`. A separate event, so ability_called stays one row per call. Successful lookups only.
*
* @param mixed $ability_name The ability that ran.
* @param mixed $input Its input.
*/
private function record_discovery( $ability_name, $input ): void {
if ( 'mcp-adapter/discover-abilities' === $ability_name ) {
$looked_up = null;
} elseif ( 'mcp-adapter/get-ability-info' === $ability_name && is_array( $input ) && self::is_tracked_ability( $input['ability_name'] ?? null ) && wp_has_ability( $input['ability_name'] ) ) {
$looked_up = $input['ability_name'];
} else {
return;
}
$channel = $this->get_channel();
if ( ! in_array( $channel, self::TRACKED_CHANNELS, true ) ) {
return;
}
$this->queue_event(
self::DISCOVERY_EVENT_NAME,
array(
'ability_name' => null === $looked_up ? self::NONE : self::get_event_ability_name( $looked_up ),
'discovery' => null === $looked_up ? 'list' : 'info',
'channel' => $channel,
'external_client' => 'mcp' === $channel ? $this->get_external_client() : self::NONE,
)
);
}
/**
* Add the properties every event carries and queue the event for sending.
*
* Properties are built now, so the user, site and time are those of the call rather than of shutdown.
*
* @param string $event_name Event name, without the `wcadmin_` prefix.
* @param array<string, mixed> $event Event-specific properties.
* @param float|null $started microtime() to record as the event time, or null for now.
*/
private function queue_event( string $event_name, array $event, ?float $started = null ): void {
// Telemetry must never break the ability call: this runs third-party filters and Jetpack code inside core's hooks.
try {
if ( count( $this->events ) >= self::MAX_EVENTS_PER_REQUEST ) {
if ( ! $this->is_long_running_process() ) {
++$this->events_dropped;
return;
}
$this->flush_events();
$this->send_queued_pixels();
}
// The call itself may have turned tracking off.
if ( ! self::is_tracking_allowed() ) {
return;
}
// Web requests from logged-out visitors aren't merchant or agent usage, and anyone could trigger them.
$auth = self::get_auth_method();
if ( 'none' === $auth && ! ( defined( 'WP_CLI' ) && WP_CLI ) && ! wp_doing_cron() ) {
return;
}
$event['auth'] = $auth;
// Many local installs (localhost, .local, .test, DDEV, Lando) still report production.
$event['is_test'] = ( 'production' !== wp_get_environment_type() || ( class_exists( Status::class ) && ( new Status() )->is_local_site() ) ) ? 'true' : 'false';
$event['is_a11n'] = self::is_a11n() ? 'true' : 'false';
$properties = \WC_Tracks::get_properties( \WC_Tracks::PREFIX . $event_name, $event );
// The request URL and referrer can carry ability input, e.g. in the query string of GET run requests.
unset( $properties['_dl'], $properties['_dr'] );
if ( null !== $started ) {
$properties['_ts'] = number_format( round( $started * 1000 ), 0, '', '' );
}
$this->events[] = $properties;
} catch ( \Throwable $e ) {
unset( $e );
}
}
/**
* Ability name as recorded: the `/` becomes `__`, and hyphens stay, so `products-query` and `products_query` stay
* different events.
*
* @param string $ability_name Ability name.
* @return string
*/
private static function get_event_ability_name( string $ability_name ): string {
return implode( '__', explode( '/', strtolower( $ability_name ), 2 ) );
}
/**
* Identify how the ability was invoked.
*
* @return string
*/
private function get_channel(): string {
if ( $this->is_mcp_request() ) {
return 'mcp';
}
foreach ( $this->rest_requests as $request ) {
if ( 1 === preg_match( self::ABILITIES_RUN_ROUTE_REGEX, $request->get_route() ) ) {
return 'rest';
}
}
// Before WP-CLI: `wp cron event run` defines DOING_CRON, and that is scheduled work, not an agent.
if ( wp_doing_cron() ) {
return 'cron';
}
if ( defined( 'WP_CLI' ) && WP_CLI ) {
return 'cli';
}
return 'other';
}
/**
* Whether this is an MCP request.
*
* MCP Streamable HTTP clients send MCP-Protocol-Version on every request after initialization (2025-06-18 and
* later) and Mcp-Session-Id when the server assigned a session, whichever server implementation handles them.
*
* @return bool
*/
private function is_mcp_request(): bool {
if ( null === $this->is_mcp_request ) {
$this->is_mcp_request = isset( $_SERVER['HTTP_MCP_PROTOCOL_VERSION'] ) || isset( $_SERVER['HTTP_MCP_SESSION_ID'] );
}
return $this->is_mcp_request || $this->is_json_rpc_tool_call();
}
/**
* Whether the outermost REST request is a JSON-RPC `tools/call`, as every MCP tool call over HTTP is, including from
* 2025-03-26 clients that send no MCP headers. Batches (2025-03-26) are checked message by message.
*
* @return bool
*/
private function is_json_rpc_tool_call(): bool {
$request = $this->rest_requests[0] ?? null;
$body = $request ? $request->get_json_params() : null;
if ( ! is_array( $body ) ) {
return false;
}
foreach ( isset( $body['jsonrpc'] ) ? array( $body ) : $body as $message ) {
if ( is_array( $message ) && '2.0' === ( $message['jsonrpc'] ?? null ) && 'tools/call' === ( $message['method'] ?? null ) ) {
return true;
}
}
return false;
}
/**
* Get the namespace of the outermost REST route being dispatched, such as `wp_abilities` or `mcp`.
*
* Only the namespace is used: the rest of the route can hold IDs.
*
* @return string
*/
private function get_rest_namespace(): string {
if ( ! $this->rest_requests ) {
return self::NONE;
}
$segments = explode( '/', ltrim( $this->rest_requests[0]->get_route(), '/' ), 2 );
return self::normalize_value( $segments[0] );
}
/**
* Get the error code to record for an error.
*
* Codes are normally fixed slugs, but any filter can return an error whose code was built from input, so codes
* that don't look like slugs are recorded as `other`.
*
* @param WP_Error $error The error.
* @return string
*/
private static function get_error_code( WP_Error $error ): string {
$code = (string) $error->get_error_code();
return 1 === preg_match( '/^[A-Za-z0-9_-]{1,64}$/', $code ) ? self::normalize_value( $code ) : 'other';
}
/**
* Get the error a validation filter result stands for, matching how WP_Ability treats it.
*
* @param mixed $is_valid The filtered validation result.
* @param string $default_code Error code to use when the result is false.
* @return WP_Error|null The error, or null when the value is valid.
*/
private static function get_validation_error( $is_valid, string $default_code ): ?WP_Error {
if ( false === $is_valid ) {
return new WP_Error( $default_code );
}
return is_wp_error( $is_valid ) && $is_valid->has_errors() ? $is_valid : null;
}
/**
* Identify how the caller authenticated, so agents can be told apart from people in wp-admin.
*
* @return string `application_password`, `jetpack`, `cookie`, `other` (another REST authentication method) or
* `none` (logged out, WP-CLI or cron).
*/
private static function get_auth_method(): string {
if ( function_exists( 'rest_get_authenticated_app_password' ) && rest_get_authenticated_app_password() ) {
return 'application_password';
}
if ( self::is_jetpack_signed_request() ) {
return 'jetpack';
}
if ( ! is_user_logged_in() || ( defined( 'WP_CLI' ) && WP_CLI ) || wp_doing_cron() ) {
return 'none';
}
if ( wp_is_serving_rest_request() ) {
global $wp_rest_auth_cookie;
return true === $wp_rest_auth_cookie ? 'cookie' : 'other';
}
return 'cookie';
}
/**
* Whether Jetpack authenticated this request with a blog or user token signature.
*
* Jetpack is only asked when the request carries its signature arguments, so its REST authentication isn't
* initialized here on other requests.
*
* @return bool
*/
private static function is_jetpack_signed_request(): bool {
// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Only checks for the presence of Jetpack's signature arguments.
if ( ! isset( $_GET['token'], $_GET['signature'] ) ) {
return false;
}
$rest_authentication = 'Automattic\Jetpack\Connection\Rest_Authentication';
return is_callable( array( $rest_authentication, 'is_signed_with_blog_token' ) )
&& is_callable( array( $rest_authentication, 'is_signed_with_user_token' ) )
&& ( $rest_authentication::is_signed_with_blog_token() || $rest_authentication::is_signed_with_user_token() );
}
/**
* Whether an Automattician made the call: signed in on WordPress.com, or through the Automattic proxy.
*
* Only detectable on WordPress.com and Atomic; always false elsewhere.
*
* @return bool
*/
private static function is_a11n(): bool {
if ( function_exists( 'is_automattician' ) && is_automattician() ) {
return true;
}
if ( defined( 'AT_PROXIED_REQUEST' ) && AT_PROXIED_REQUEST ) {
return true;
}
if ( function_exists( 'wpcom_is_proxied_request' ) ) {
return (bool) wpcom_is_proxied_request();
}
if ( isset( $_SERVER['A8C_PROXIED_REQUEST'] ) && is_string( $_SERVER['A8C_PROXIED_REQUEST'] ) ) {
return '1' === sanitize_text_field( wp_unslash( $_SERVER['A8C_PROXIED_REQUEST'] ) );
}
return defined( 'A8C_PROXIED_REQUEST' ) && A8C_PROXIED_REQUEST;
}
/**
* Whether the current site allows usage tracking.
*
* Unlike WC_Site_Tracking::is_tracking_enabled() alone, this requires the stored opt-in: that method also treats a
* posted `wc_tracker_checkbox=yes` (the onboarding opt-in) as consent, and any visitor can post to the REST API.
*
* @return bool
*/
private static function is_tracking_allowed(): bool {
try {
return 'yes' === get_option( 'woocommerce_allow_tracking' ) && \WC_Site_Tracking::is_tracking_enabled();
} catch ( \Throwable $e ) {
// The consent filters are third-party code; a failure there must not break the ability call.
return false;
}
}
/**
* Whether an ability is in the tracked namespace.
*
* @param mixed $ability_name The ability name.
* @return bool
*/
private static function is_tracked_ability( $ability_name ): bool {
return is_string( $ability_name ) && 0 === strpos( $ability_name, self::ABILITY_PREFIX );
}
/**
* Get the MCP client, as one of the known clients, `other` or `none`.
*
* The client supplies its own name, so only known clients are recorded by name.
*
* @return string
*/
private function get_external_client(): string {
try {
return $this->resolve_external_client();
} catch ( \Throwable $e ) {
// The session lookup is MCP Adapter code; a failure there must not break the ability call.
return self::NONE;
}
}
/**
* Resolve and cache the MCP client.
*
* @return string
*/
private function resolve_external_client(): string {
if ( null === $this->external_client ) {
$name = $this->get_mcp_client_name_from_request() ?? self::get_mcp_client_name_from_session();
if ( null === $name ) {
$this->external_client = self::NONE;
} else {
$this->external_client = 'other';
$tokens = '_' . self::normalize_value( $name ) . '_';
foreach ( self::KNOWN_MCP_CLIENTS as $needle => $client ) {
if ( false !== strpos( $tokens, '_' . $needle . '_' ) ) {
$this->external_client = $client;
break;
}
}
}
}
return $this->external_client;
}
/**
* Get the MCP client name from the request metadata, which MCP 2026-07-28 sends with every request.
*
* @return string|null
*/
private function get_mcp_client_name_from_request(): ?string {
$request = $this->rest_requests[0] ?? null;
$message = $request ? $request->get_json_params() : null;
$name = is_array( $message ) ? ( $message['params']['_meta']['io.modelcontextprotocol/clientInfo']['name'] ?? null ) : null;
return is_string( $name ) ? $name : null;
}
/**
* Get the MCP client name from the MCP Adapter session (MCP 2025-11-25 and earlier).
*
* @return string|null
*/
private static function get_mcp_client_name_from_session(): ?string {
$session_manager = array( 'WP\MCP\Transport\Infrastructure\SessionManager', 'get_session' );
$session_id = isset( $_SERVER['HTTP_MCP_SESSION_ID'] ) && is_string( $_SERVER['HTTP_MCP_SESSION_ID'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_MCP_SESSION_ID'] ) ) : '';
if ( '' === $session_id || ! get_current_user_id() || ! is_callable( $session_manager ) ) {
return null;
}
$session = call_user_func( $session_manager, get_current_user_id(), $session_id );
$name = is_array( $session ) ? ( $session['client_params']['clientInfo']['name'] ?? null ) : null;
return is_string( $name ) ? $name : null;
}
/**
* Convert a value to lowercase words separated by underscores, as Tracks property values expect.
*
* @param string $value The value.
* @param int|null $max_length Maximum length, or null for no limit.
* @return string The normalized value, or 'none' when nothing is left.
*/
private static function normalize_value( string $value, ?int $max_length = 64 ): string {
$value = trim( (string) preg_replace( '/[^a-z0-9]+/', '_', strtolower( $value ) ), '_' );
if ( '' === $value ) {
return self::NONE;
}
return null === $max_length ? $value : (string) substr( $value, 0, $max_length );
}
}