Allow custom annotation fields to pass through McpAnnotationMapper

[galatanovidiu]

Problem

McpAnnotationMapper::map() uses a strict whitelist of known MCP annotation fields (readOnlyHint, destructiveHint, idempotentHint, openWorldHint, audience, priority, title, lastModified). Any annotation key not in this list is silently discarded during the mapping from WordPress Abilities API to MCP tools.

This prevents consumers from attaching domain-specific metadata to tool annotations.

Compliant MCP clients will ignore fields they don't recognize, so passing through additional fields is protocol-safe.

Proposed Change

After mapping known MCP annotation fields, preserve any remaining keys from the source annotations array. Unknown fields should be included as-is in the mapped output.

[flodufour]

Hi @galatanovidiu,

I’m new to PHP and WordPress, and I’d love to take my first steps by working on this issue. Would it be possible to have it assigned to me?

I’ve already looked at the code and the related tests, and I wanted to confirm: is the intended behavior to pass through only unknown annotation fields, while still excluding known fields that are not applicable to the current feature type?

Thanks in advance!

[galatanovidiu]

Hi @galatanovidiu,

I’m new to PHP and WordPress, and I’d love to take my first steps by working on this issue. Would it be possible to have it assigned to me?

I’ve already looked at the code and the related tests, and I wanted to confirm: is the intended behavior to pass through only unknown annotation fields, while still excluding known fields that are not applicable to the current feature type?

Thanks in advance!

Hey @flodufour, thanks for the interest and for looking into the code. Your question about
excluding known fields that aren't applicable to the current feature type is spot on.
That's exactly the intended behavior.

That said, I'd rather not assign this one as a first contribution. It looks simple on the
surface, but it touches the annotation mapping system, which needs a solid understanding of
how the plugin works, PHP type safety (we enforce PHPStan Level 8), WordPress coding
standards, and the existing test patterns. You'd also need to write unit tests that follow
the project's conventions, and getting all of that right without PHP/WordPress experience
would be pretty frustrating.

I don't want to discourage you from contributing to open source though. If you're looking
to get started with PHP and WordPress, the WordPress core project has some well-labeled
good-first-issues that are more beginner-friendly. Once you're more comfortable with the
ecosystem, you're welcome to pick up issues here.

[galatanovidiu]

Closing this after digging into it. The idea is sound and the MCP spec technically allows it, but the ecosystem doesn't support it yet.

What the spec says:
The MCP 2025-11-25 JSON Schema does not set additionalProperties: false on ToolAnnotations or Annotations, so custom fields are valid per the protocol. Compliant clients should ignore fields they don't recognize.

What actually happens:
Every official MCP SDK silently strips unknown annotation fields:

• TypeScript SDK — ToolAnnotationsSchema uses Zod v4's z.object(), which drops unknown keys during client-side parsing
• Python SDK — ToolAnnotations is a Pydantic model with default extra='ignore', so unknown fields are discarded on both construction and serialization
• PHP SDKs — all three (official mcp/sdk, community php-mcp/schema, and our wordpress/php-mcp-schema) only extract the 5 known fields in fromArray() and only output those in toArray()/jsonSerialize()

So even if we updated the mapper and our DTO layer to pass through custom fields, no client built with an official SDK would ever see them. The fields would travel over the wire but get dropped on the other end.

What works today:
The _meta field on Tool and Resource objects accepts arbitrary key-value pairs and survives round-tripping in all SDKs. If you need to attach domain-specific metadata to tools, _meta is the way to go for now.

Closing as won't fix. If the upstream SDKs add additionalProperties support for annotation types (e.g., z.looseObject() in TS, extra='allow' in Python), we can revisit this.