feat(abilities): expose templates tool group via the WordPress Abilities API

[zackkatz]

What changed

Exposes the templates tool group (list_templates, get_template, update_template, reset_template) via the WordPress Abilities API / MCP Adapter (BLOCK-34) — the follow-up flagged in the BLOCK-29 PR.

Starting state on fresh origin/develop (worth stating plainly, since it changes the shape of this PR): TEMPLATE_TOOLS was already wired into scripts/export-abilities-manifest.mjs's buildManifest() — the committed manifest already carried all 4 templates tools at 32 tools total / 29 non-yoast ability ids, since ability registration is manifest-driven and doesn't depend on Tool_Executor actually knowing how to run a tool. Two real gaps remained:

1. No gate parity. update_template/reset_template resolved to the manifest's default edit_post permission — the same as every ordinary per-block write — so the Abilities/MCP-Adapter surface could write to a template with none of the gk_block_api_template_edits toggle checking the REST routes (POST /template, POST /template/reset) enforce. An agent connected over the Adapter could bypass the operator's off-by-default consent entirely.
2. No execution. Tool_Executor::execute() had no case for any of the 4 tool names, so every call 400'd with "Unknown Block MCP tool" regardless of permission.

Fix

• scripts/export-abilities-manifest.mjs: new TEMPLATE_EDIT permission bucket (update_template, reset_template) → manifest permission 'template_edit', checked before the edit_post fallback. Regenerated tools.manifest.json — still 32 tools, only the two permission values change.
• Abilities_Registry::check_tool_permission(): new 'template_edit' case that calls REST_Controller::check_template_edit_permissions() directly — the exact method the REST routes use as their permission_callback. No gate logic is duplicated or re-implemented; both surfaces share one source of truth for the toggle + capability check.
• Tool_Executor::execute(): dispatch cases + execute_list_templates() / execute_get_template() / execute_update_template() / execute_reset_template(), each delegating to the matching REST_Controller handler via the existing call_controller() pattern (hand-built WP_REST_Request + set_url_params()/set_body_params()) every other ability already uses.
• AGENTS.md: the "Add an MCP tool" recipe gets a 4th step covering the Abilities-wiring gap this issue backfilled — a new tool-group file needs an explicit import in the export script, a permission mapping, and a Tool_Executor case, none of which step 3 (npm run build) alone provides.

TDD: red before green (commit history is the proof, not squashed)

1. 393d9dc test(abilities): templates group registration + gate parity [red] — new tests/Abilities/TemplateAbilitiesTest.php (registration presence, read execution, 8 gate-parity scenarios) + 3 new assertions in tests/abilities-manifest.test.ts (group presence, read permission, template_edit permission) + minor additions to AbilitiesRegistryTest's existing readonly/destructive-annotation tests. Confirmed genuinely red against unmodified origin/develop:

   $ vendor/bin/phpunit -c tests/phpunit.xml tests/Abilities/
   Tests: 153, Assertions: 360, Failures: 8.
   

   $ npm test -- tests/abilities-manifest.test.ts
   Tests  1 failed | 4 passed (5)
   

2. 6a58fab feat(abilities): wire templates group execution + gate parity [green] — the fix described above. All 8 PHP failures + the 1 TS failure go green; nothing else regresses.
3. bc484b3 docs(agents): add the Abilities-wiring step to the Add-an-MCP-tool recipe.

Acceptance criteria

• TEMPLATE_TOOLS reachable through the manifest export and Abilities_Registry/Tool_Executor (already true for the manifest; Tool_Executor execution is new here).
• Manifest/ability-id counts verified against the actual current baseline (32 / 29), not a guessed number — confirmed by inspecting the committed JSON directly before writing any assertion.
• update_template/reset_template ability permission callbacks honor gk_block_api_template_edits + gk/block-mcp/templates/allow-edits exactly as the REST routes do — proven by delegating to the identical method, and by 8 PHPUnit scenarios plus live MCP-transport smoke evidence below (toggle off denies an editor and an admin's own filter-forced-off case; toggle on + edit_posts succeeds and persists; toggle on + no capability still denies a subscriber; edit_theme_options alone succeeds — the "self" connection path).
• AGENTS.md's "Add an MCP tool" recipe updated.

Gate output (real numbers, run in the worktree)

$ npm test
 Test Files  54 passed (54)
      Tests  849 passed (849)

$ npm run build
  dist/index.cjs  3.6mb
  Copied dist/index.cjs -> wordpress-plugin/gk-block-mcp/assets/mcp-server/index.cjs

$ npx tsx scripts/export-abilities-manifest.mjs && git diff --exit-code wordpress-plugin/gk-block-mcp/includes/abilities/tools.manifest.json
Wrote 32 tools to .../tools.manifest.json
(no diff — exit 0)

$ composer test          (from wordpress-plugin/gk-block-mcp)
OK (1398 tests, 18856 assertions)
OK (28 tests, 82 assertions)     [yoast group]
OK (11 tests, 25 assertions)     [mcp-adapter group]
OK (5 tests, 37 assertions)      [multisite]

$ composer lint
FOUND 0 ERRORS AND 0 WARNINGS

$ composer analyze
[OK] No errors

Siteminter smoke — real MCP Adapter HTTP transport, not wp-cli fallback

Fresh site blockmcp-c (WordPress 7.0.2 — Abilities API ships in core; the separate WordPress MCP Adapter plugin isn't bundled, so I installed it from its GitHub Release (v0.5.0) to exercise the real path rather than falling back to direct wp_get_ability()->execute() calls). Plugin symlinked to the worktree; both toggles (gk_block_api_abilities_enabled, gk_block_api_template_edits) exercised live.

MCP initialize handshake (real session, real Mcp-Session-Id):

$ curl -u admin:*** -X POST http://localhost:8936/wp-json/gk-block-mcp/mcp \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'
HTTP/1.1 200 OK
Mcp-Session-Id: f007e3d4-b8dc-4b66-ae8f-c08a20d5e064
{"jsonrpc":"2.0","id":1,"result":{...,"serverInfo":{"name":"Block MCP","version":"2.1.0"},...}}

tools/list — all 4 template tools present among 29 total:

template tools: ['gk-block-mcp-list-templates', 'gk-block-mcp-get-template', 'gk-block-mcp-update-template', 'gk-block-mcp-reset-template']

Gate parity, toggle OFF → tools/call update-template denied (admin, who has every capability — proves the toggle, not a capability gap, is what's blocking):

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Editing theme templates is turned off for this site. A site administrator can enable it under Block MCP → Settings."}],"isError":true}}

Toggle ON → tools/call update-template succeeds, creates the override:

{"jsonrpc":"2.0","id":4,"result":{"structuredContent":{"success":true,"wp_id":4,"override_created":true,"revert_hint":"Call reset_template...","warnings":[],"before_revision_id":0,"revision_id":5},"isError":false}}

Verified independently via wp-cli and a real page render:

$ wp post list --post_type=wp_template_part --fields=ID,post_title,post_name,post_status
ID  post_title  post_name  post_status
4   Header      header     publish

$ wp post term list 4 wp_theme --format=table
term_id  name              slug              taxonomy
2        twentytwentyfive  twentytwentyfive  wp_theme

$ curl -s http://localhost:8936/ | grep -o "MCP-ADAPTER-SMOKE"
MCP-ADAPTER-SMOKE

tools/call get-template confirms the read side sees the override too:

source: custom wp_id: 4
content contains marker: True

Capability half of the gate — a subscriber denied even with the toggle ON (proves the toggle widens what a capable actor may do, it doesn't replace the capability check):

{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"You do not have permission to edit templates."}],"isError":true}}

tools/call reset-template — deletes the override, full round trip:

{"jsonrpc":"2.0","id":6,"result":{"structuredContent":{"success":true,"id":"twentytwentyfive//header","wp_id":4},"isError":false}}

$ wp post list --post_type=wp_template_part --name=header --fields=ID,post_status
(empty — post 4 is gone)

$ curl -s http://localhost:8936/ | grep -o "MCP-ADAPTER-SMOKE"
(empty — reverted)

Site destroyed after this run; confirmed no leftover containers.

Fixes BLOCK-34
https://linear.app/gravitykit/issue/BLOCK-34/expose-the-templates-tool-group-via-the-wordpress-abilities-adapter

https://claude.ai/code/session_013YcSbKroBJjPanX3okQrT3

[linear-code]

BLOCK-34

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 29 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d4946811-eade-4ff9-a1ae-9545982f9095

📥 Commits

Reviewing files that changed from the base of the PR and between 0b6db23 and bc484b3.

📒 Files selected for processing (8)

• AGENTS.md
• scripts/export-abilities-manifest.mjs
• tests/abilities-manifest.test.ts
• wordpress-plugin/gk-block-mcp/includes/abilities/tools.manifest.json
• wordpress-plugin/gk-block-mcp/includes/class-abilities-registry.php
• wordpress-plugin/gk-block-mcp/includes/class-tool-executor.php
• wordpress-plugin/gk-block-mcp/tests/Abilities/AbilitiesRegistryTest.php
• wordpress-plugin/gk-block-mcp/tests/Abilities/TemplateAbilitiesTest.php

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/block-34-expose-the-templates-tool-group-via-the-wordpress-abilities

---

_{Comment @coderabbitai help to get the list of available commands.}