fix(transport): accept nested x-mcp-header annotations

[DaleSeo]

Fixes #1354.

Motivation and Context

The 2026-07-28 Streamable HTTP spec allows x-mcp-header on any property you can reach from the schema root using only properties keys. rmcp only handled top-level annotations, so it dropped tools with nested annotations from tools/list and only read top-level argument values when building headers.

Now, annotations are collected along the full properties chain, with each annotation's path. The existing checks for valid tokens, primitive types, and duplicates that differ only in case apply at every level. The client reads the header value from the full path, and the server checks it there too. If part of the path is missing, the client leaves out the header.

How Has This Been Tested?

Added tests

Breaking Changes

There are no API changes, but one behavior has changed. The old code only checked properties, so it silently ignored annotations under items, composition or conditional keywords, $defs or $ref targets, and the schema root. The spec says those annotations make the tool invalid, so the client now leaves those tools out of tools/list and logs a warning.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[github-actions]

@bolinfest is on triage rotation this week and is the reviewer for this one.

Automated classification did not run for this one, so it needs a full manual pass.

_{Automated triage. Labels are a first pass and the assigned maintainer has the final say.}

[gocamille]

This looks good to me, thanks @DaleSeo! I checked the new tests against main and they all fail there for the right reason. I had a minor ask for the body: the server side changes too (an inline nested annotation now gets -32020 when the header is missing), so maybe a sentence in Breaking Changes would be useful.

[gocamille]

Thank you @DaleSeo 👍