Skip to content

Commit 227c7a5

Browse files
Abilities: Mark abilities as public with the meta.public flag (#55104)
* Abilities: Mark abilities as public with the meta.public flag - Add meta.public to all 35 abilities; keep show_in_rest and meta.mcp - Require the flag in every ability test - Update the ship-wp-ability skill, templates and docs, plus changelogs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Abilities: Mark Social abilities as public with the meta.public flag Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 982b5c5 commit 227c7a5

37 files changed

Lines changed: 151 additions & 5 deletions

File tree

‎.agents/skills/ship-wp-ability.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,9 @@ For every entry in `get_abilities()`:
119119
- `execute_callback` — `[ __CLASS__, 'method_name' ]`. Method signature is `( $input = null )`. Return value is a plain array (or `WP_Error`). Keep the shape **high-signal** — don't return raw `$mod` / `WP_Post` / option dumps; summarize. See the anti-patterns section of `references/agent-ergonomics.md`.
120120
- `permission_callback` — `[ __CLASS__, 'can_method' ]`. See the permissions table below.
121121
- `meta.annotations` — `readonly`, `destructive`, `idempotent` booleans. These must match execute behavior; `wp-abilities-verify` will flag mismatches.
122-
- `meta.mcp` — every ability gets `'mcp' => array( 'public' => true, 'type' => 'tool' )`. This is what surfaces the ability to MCP-bridged AI agents as a tool. Matches the convention used by Stats / Boost / Modules abilities; leaving it off makes the ability invisible to MCP consumers even though it shows up in `/wp-abilities/v1/abilities/`. Flip `public => false` only when the ability is for internal callers and explicitly shouldn't be agent-discoverable.
123-
- `meta.show_in_rest` — `true` when the ability should be callable via REST.
122+
- `meta.public` — `true` for every agent-facing ability. This is the WordPress-level flag that marks an ability as available to clients. MCP adapter 0.6.0+ falls back to it when `meta.mcp.public` is not set, and WordPress 7.1+ uses it as the default for `show_in_rest`.
123+
- `meta.show_in_rest` — keep `true` explicit. WordPress 7.0 does not derive it from `meta.public`, so leaving it out hides the ability from `/wp-abilities/v1/abilities/` there.
124+
- `meta.mcp` — every ability also gets `'mcp' => array( 'public' => true, 'type' => 'tool' )`. MCP adapters older than 0.6.0 read only `meta.mcp.public`, so keep it alongside `meta.public`. For an ability meant only for internal callers, set both `meta.public` and `meta.mcp.public` to `false`: an explicit `meta.mcp.public` overrides `meta.public` for MCP. Also set `show_in_rest` to `false` unless those callers need REST, because an explicit `true` keeps the ability in `/wp-abilities/v1/abilities/` and in WordPress.com's remote ability discovery. Leave that slug out of the public-flag test in `references/test-templates.md`.
124125
- **Do NOT set `category`** in the spec. `Registrar` auto-injects it. Setting it duplicates info that drifts.
125126
- `WP_Error` codes — use the shared vocabulary in `wp-abilities-api/references/error-code-vocabulary.md` (`<plugin>_not_initialized`, `<plugin>_missing_<field>`, `<plugin>_invalid_<field>`, `<plugin>_<resource>_data_unavailable`). The **message** should tell the agent *what to do next* — e.g. "Unknown module slug. Call jetpack-modules/get-modules to enumerate." — not just restate the error condition.
126127
- **Pagination** — any list-shaped read needs `page`/`per_page` (or `limit`/`cursor`) with a `default` of ~20 and a `maximum` of ~100. Enforce the max in the callback. Even if today's dataset is small, don't ship ability specs that return unbounded lists.

‎.agents/skills/ship-wp-ability/references/class-skeleton.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,7 @@ class <Name>_Abilities extends Registrar {
135135
'destructive' => false,
136136
'idempotent' => true,
137137
),
138+
'public' => true,
138139
'mcp' => array(
139140
'public' => true,
140141
'type' => 'tool',
@@ -181,6 +182,7 @@ class <Name>_Abilities extends Registrar {
181182
'destructive' => false,
182183
'idempotent' => true,
183184
),
185+
'public' => true,
184186
'mcp' => array(
185187
'public' => true,
186188
'type' => 'tool',

‎.agents/skills/ship-wp-ability/references/test-templates.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,17 @@ class <Name>_Abilities_Test extends WP_UnitTestCase {
104104
}
105105
}
106106

107+
public function test_every_ability_opts_into_mcp_as_public_tool() {
108+
foreach ( <Name>_Abilities::get_abilities() as $slug => $spec ) {
109+
$this->assertArrayHasKey( 'public', $spec['meta'], "{$slug} must declare meta.public." );
110+
$this->assertTrue( $spec['meta']['public'], "{$slug} must be marked public." );
111+
$this->assertTrue( $spec['meta']['show_in_rest'], "{$slug} must be exposed through the Abilities REST API." );
112+
$this->assertArrayHasKey( 'mcp', $spec['meta'], "{$slug} must publish meta.mcp." );
113+
$this->assertTrue( $spec['meta']['mcp']['public'], "{$slug} must opt into MCP." );
114+
$this->assertSame( 'tool', $spec['meta']['mcp']['type'], "{$slug} must be exposed as an MCP tool." );
115+
}
116+
}
117+
107118
// -------------------- Registrar wiring --------------------
108119

109120
public function test_init_registers_nothing_when_gate_filter_is_false() {
@@ -388,6 +399,17 @@ class <Name>AbilitiesTest extends TestCase {
388399
}
389400
}
390401

402+
public function test_every_ability_opts_into_mcp_as_public_tool(): void {
403+
foreach ( <Name>_Abilities::get_abilities() as $slug => $spec ) {
404+
$this->assertArrayHasKey( 'public', $spec['meta'], "{$slug} must declare meta.public." );
405+
$this->assertTrue( $spec['meta']['public'], "{$slug} must be marked public." );
406+
$this->assertTrue( $spec['meta']['show_in_rest'], "{$slug} must be exposed through the Abilities REST API." );
407+
$this->assertArrayHasKey( 'mcp', $spec['meta'], "{$slug} must publish meta.mcp." );
408+
$this->assertTrue( $spec['meta']['mcp']['public'], "{$slug} must opt into MCP." );
409+
$this->assertSame( 'tool', $spec['meta']['mcp']['type'], "{$slug} must be exposed as an MCP tool." );
410+
}
411+
}
412+
391413
// -------------------- Registrar wiring --------------------
392414

393415
public function test_init_is_disabled_by_default(): void {
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Significance: patch
2+
Type: changed
3+
4+
Abilities: Mark abilities as public with the `meta.public` flag.

‎projects/packages/backup/src/abilities/class-backup-abilities.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,7 @@ public static function get_abilities(): array {
215215
'destructive' => false,
216216
'idempotent' => true,
217217
),
218+
'public' => true,
218219
'mcp' => array(
219220
'public' => true,
220221
'type' => 'tool',
@@ -295,6 +296,7 @@ public static function get_abilities(): array {
295296
'destructive' => false,
296297
'idempotent' => true,
297298
),
299+
'public' => true,
298300
'mcp' => array(
299301
'public' => true,
300302
'type' => 'tool',
@@ -346,6 +348,7 @@ public static function get_abilities(): array {
346348
'destructive' => false,
347349
'idempotent' => true,
348350
),
351+
'public' => true,
349352
'mcp' => array(
350353
'public' => true,
351354
'type' => 'tool',
@@ -381,6 +384,7 @@ public static function get_abilities(): array {
381384
'destructive' => false,
382385
'idempotent' => false,
383386
),
387+
'public' => true,
384388
'mcp' => array(
385389
'public' => true,
386390
'type' => 'tool',

‎projects/packages/backup/tests/php/abilities/Backup_Abilities_Test.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,8 @@ public function test_every_ability_declares_public_rest_mcp_and_output_contract(
261261
$this->assertArrayHasKey( 'output_schema', $spec, "Ability {$slug} missing output_schema." );
262262
$this->assertNotEmpty( $spec['output_schema'], "Ability {$slug} must declare a non-empty output_schema." );
263263
$this->assertArrayHasKey( 'meta', $spec, "Ability {$slug} missing meta." );
264+
$this->assertArrayHasKey( 'public', $spec['meta'], "Ability {$slug} must declare meta.public." );
265+
$this->assertTrue( $spec['meta']['public'], "{$slug} must be marked public." );
264266
$this->assertArrayHasKey( 'mcp', $spec['meta'], "Ability {$slug} must publish meta.mcp." );
265267
$this->assertSame(
266268
array(
@@ -306,6 +308,7 @@ public function test_request_backup_contract_is_public_non_idempotent_write_tool
306308
'destructive' => false,
307309
'idempotent' => false,
308310
),
311+
'public' => true,
309312
'mcp' => array(
310313
'public' => true,
311314
'type' => 'tool',
@@ -497,6 +500,7 @@ public function test_registered_abilities_preserve_public_schema_and_meta_contra
497500

498501
$meta = $registered[ $slug ]->get_meta();
499502
$this->assertSame( $spec['meta']['annotations'], $meta['annotations'], "{$slug} registered annotations drifted." );
503+
$this->assertSame( $spec['meta']['public'], $meta['public'], "{$slug} registered public metadata drifted." );
500504
$this->assertSame( $spec['meta']['mcp'], $meta['mcp'], "{$slug} registered MCP metadata drifted." );
501505
$this->assertSame( $spec['meta']['show_in_rest'], $meta['show_in_rest'], "{$slug} registered show_in_rest metadata drifted." );
502506
}
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Significance: patch
2+
Type: changed
3+
4+
Abilities: Mark abilities as public with the `meta.public` flag.

‎projects/packages/connection/docs/abilities.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ A read-only, idempotent ability that is safe to poll. It takes no input and retu
2929

3030
**Permissions:** Access is gated on `current_user_can( 'jetpack_admin_page' )`, mirroring the capability used by the Jetpack admin page.
3131

32-
**MCP:** This ability is opted into the MCP tool surface (`meta.mcp.public = true`), so it is exposed as a public MCP tool.
32+
**MCP:** This ability is marked public (`meta.public = true`) and keeps the MCP opt-in (`meta.mcp.public = true`) for older MCP adapters, so it is exposed as a public MCP tool.
3333

3434
## Initialization
3535

‎projects/packages/connection/src/abilities/class-connection-abilities.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,7 @@ private static function spec_get_connection_status(): array {
102102
'destructive' => false,
103103
'idempotent' => true,
104104
),
105+
'public' => true,
105106
'show_in_rest' => true,
106107
'mcp' => array(
107108
'public' => true,

‎projects/packages/connection/tests/php/abilities/Connection_Abilities_Test.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -428,6 +428,9 @@ public function test_get_connection_status_reports_connected_state_with_options_
428428

429429
public function test_every_ability_opts_into_mcp_as_public_tool(): void {
430430
foreach ( Connection_Abilities::get_abilities() as $slug => $spec ) {
431+
$this->assertArrayHasKey( 'public', $spec['meta'], "{$slug} must declare meta.public." );
432+
$this->assertTrue( $spec['meta']['public'], "{$slug} must be marked public." );
433+
$this->assertTrue( $spec['meta']['show_in_rest'], "{$slug} must be exposed through the Abilities REST API." );
431434
$this->assertArrayHasKey( 'mcp', $spec['meta'], "{$slug} must publish meta.mcp." );
432435
$this->assertTrue( $spec['meta']['mcp']['public'], "{$slug} must opt into MCP." );
433436
$this->assertSame( 'tool', $spec['meta']['mcp']['type'], "{$slug} must be exposed as an MCP tool." );

0 commit comments

Comments
 (0)