Proposal: Add a convienient way to filter the list of all registered abilities

[gziolo]

Figure out how to filter correctly all abilities when fetching them, given the expected high number of registered items by core and plugins.

Currently, it's only possible to find a single item or fetch all of them:

// Retrieving all abilities.
$abilities = wp_get_abilities();

// Retrieving a specific ability.
$ability = wp_get_ability( 'example/add-numbers' );

The same applies to the REST API, which offers WP_REST_Abilities_List_Controller that handles listing abilities and retrieving individual abilities:

• GET /wp-json/wp/v2/abilities – list all registered abilities.
• GET /wp-json/wp/v2/abilities/{name} – Get a specific ability by name.

Let's discuss possible approaches. For reference, the WP Feature API prototype offers a special WP_Feature_Query object that offers several filtering options:

https://github.com/Automattic/wp-feature-api/blob/82ff8af75ab607ec39dfbea3c1100807843922a3/includes/wp-feature.php#L51-L60

[gziolo]

I assigned Copilot to explore whether it could be helpful for brainstorming. Initial proposal:

• 🤖 Experiment: Add filtering capabilities to WordPress Abilities API #63

[galatanovidiu]

Thinking about MCP adapter + abilities, it might be helpful to have an expose_as_mcp flag in ability metadata.

Proposal:
- false: don’t expose at all on the default MCP server
- 'tool', 'resource', 'prompt': explicitly define how the ability should be exposed via MCP
- The default can be 'tool'

This gives us both a filter mechanism and a way to categorize abilities by type in the MCP adapter, which could help the adapter (or UIs) handle them appropriately.

---

For filtering abilities, we can use a simple filter. As an example:

/**
 * Query abilities by meta criteria.
 *
 * Criteria supports:
 * - ['expose_as_mcp' => 'resource']                     // strict scalar equality
 * - ['expose_as_mcp' => ['tool','resource']]            // any-of (IN)
 * - ['audience' => ['internal','admin']]                // array intersect
 * - ['!expose_as_mcp' => false]                         // NOT equals
 * - ['?tags' => true]                                   // exists
 *
 * @param array      $criteria
 * @param array|null $abilities Optional abilities array to filter. If null, read from registry.
 * @return array
 */
function wp_query_abilities( array $criteria, ?array $abilities = null ) : array {
    if ( null === $abilities ) {
        $abilities = WP_Abilities_Registry::get_instance()->get_all_registered();
    }

    return array_filter( $abilities, function( $ability ) use ( $criteria ) {
        $meta = ( isset( $ability['meta'] ) && is_array( $ability['meta'] ) ) ? $ability['meta'] : [];

        foreach ( $criteria as $key => $expected ) {
            // Operators:
            //  - "!foo" => NOT on "foo"
            //  - "?foo" => existence check on "foo"
            $negate = substr( $key, 0, 1 ) === '!';
            $exists = substr( $key, 0, 1 ) === '?';
            $meta_key = $negate || $exists ? substr( $key, 1 ) : $key;

            $has_key  = array_key_exists( $meta_key, $meta );
            $actual   = $has_key ? $meta[ $meta_key ] : null;

            if ( $exists ) {
                // ['?tags' => true] means key must exist (value ignored)
                $pass = (bool) $has_key === (bool) $expected;
            } else {
                // Normalize both actual/expected to arrays for "includes" semantics,
                // but keep strict equality when expected is scalar AND actual is scalar.
                if ( is_array( $expected ) ) {
                    $actArr = is_array( $actual ) ? $actual : ( null !== $actual ? [ $actual ] : [] );
                    $pass   = ! empty( array_intersect( $expected, $actArr ) );
                } else {
                    $pass = ( $actual === $expected );
                }
            }

            if ( $negate ) {
                $pass = ! $pass;
            }

            if ( ! $pass ) {
                return false;
            }
        }

        return true;
    } );
}

Example usage:

// All MCP resources:
$as_mcp_resources = wp_query_abilities( [ 'expose_as_mcp' => ['resource'] ] );

// Tool OR resource:
$exposed = wp_query_abilities( [ 'expose_as_mcp' => ['tool','resource'] ] );

// Private (explicitly false):
$private = wp_query_abilities( [ 'expose_as_mcp' => false ] );

// Audience includes "internal":
$internal = wp_query_abilities( [ 'audience' => ['internal'] ] );

// Must have "tags" meta key:
$with_tags = wp_query_abilities( [ '?tags' => true ] );

// NOT prompt:
$not_prompt = wp_query_abilities( [ '!expose_as_mcp' => 'prompt' ] );

[justlevine]

Thinking about MCP adapter + abilities, it might be helpful to have an expose_as_mcp flag in ability metadata.

Whole reason MCP Adapter exists in a separate repo is to keep it from becoming tech debt in core.

If the suggestion is that abilities need to opt in to MCP, then I'm against committing something MCP-specific into this repo/core. If the suggestion is opt out, that should be handled with a combination of an apply_filter() here + an add_filter() in MCP Adapter that uses $meta['show_in_mcp'] and not more unnecessary top-level args.