fix(resources): mirror annotations into meta.mcp to silence 0.5.0 deprecation

[oxyc]

Problem

Every WP-CLI run against a site with mcp-adapter 0.5.0 logs four deprecation notices:

[WARNING] Ability meta key "annotations" is deprecated. Use "mcp.annotations" instead. | Context: {"ability":"gds\/block-types-list","deprecated_key":"annotations"}
[WARNING] ... {"ability":"gds\/site-map"}
[WARNING] ... {"ability":"gds\/design-theme-json"}
[WARNING] ... {"ability":"gds\/acf-fields"}

mcp-adapter 0.5.0 resolves resource meta through get_mcp_meta() (Domain/Resources/RegisterAbilityAsMcpResource.php:299), which prefers meta.mcp.{key} and logs a deprecation when it falls back to the top-level key. #29/#30 moved uri/mimeType into meta.mcp but left annotations at the top level.

Only these four abilities warn because tools go through a different path (RegisterAbilityAsMcpTool.php:143) that still reads top-level meta.annotations and does not deprecate it.

Note the notice is unavoidable by deletion: WP core always populates top-level meta.annotations with defaults (class-wp-ability.php:333), so the deprecated branch is permanently reachable. Providing a valid mcp.annotations that wins the lookup is the only way to silence it.

Change

Mirror annotations into meta.mcp for the four resource abilities: BlockCatalogResource, SiteMapResource, ThemeJsonResource, AcfFieldsResource.

The top-level copy is retained deliberately — it is load-bearing, not legacy cruft:

• Tools still read only $ability_meta['annotations'], on 0.5.0 and on trunk today. There is no mcp.annotations support on the tool path at all.
• Adapters < 0.5.0 read top-level for resources too.

Removing it would silently drop annotations from every tool ability. Comments in each file now say so.

Backwards compatibility

Verified against the actual sources:

mcp-adapter	Resource annotations lookup	Effect of this PR
v0.3.0	$ability_meta['annotations'] only	inert — nested copy ignored, top-level still read
v0.4.1	$ability_meta['annotations'] only	inert — same
v0.5.0	mcp.annotations → top-level fallback + deprecation	notice silenced

Nothing rejects the extra key: every meta['mcp'] consumer in the adapter (all versions incl. trunk) is a targeted ?? lookup on a named key (public, type, uri, mimeType, icons, _meta) — no unknown-key validation. WP core validates only that meta is an array, top-level meta.annotations is an array, and show_in_rest is a bool.

SchemaValidationTest::test_all_abilities_have_annotations asserts top-level annotations exists — still satisfied.

Verification

• composer lint → pass
• composer stan → no errors
• Applied to a live site (btb-transformers, mcp-adapter v0.5.0) and ran wp cache flush → clean output, zero deprecation notices
• mcp-adapter-discover-abilities still returns the full ability list

🤖 Generated with Claude Code