Add request-level Metadata injection for tool handlers

[AgentSlim]

This Pull Request implements the feature discussed in Issue #159:
Expose request-level metadata to tool handlers.
• Introduced a new Mcp\Schema\Metadata value object to represent request-scoped metadata from the MCP message envelope.
• Updated the handler invocation logic so that parameters type-hinted as Metadata automatically receive the _meta portion of the incoming request.
• Enhanced CallToolHandler to forward the envelope metadata into the parameter resolver.
• Added comprehensive unit tests covering:
• metadata injection
• fallback behavior when no metadata is provided
• error handling during parameter resolution
• backwards-compatibility with existing tool handlers
• Updated documentation with usage examples showing how tool authors can access metadata such as securitySchema.

Motivation and Context

This change addresses Issue #159, which highlights that tool handlers currently cannot access metadata from the request envelope.
Many real-world use cases depend on this metadata — for example:
• authorization logic based on a securitySchema
• tenant or environment selection
• contextual behavior determined by the client request

Previously, developers had to rely on indirect workarounds (middleware, global state, decorators), because metadata was lost before reaching the handler.
This feature introduces a clean, explicit, opt-in approach based on type-hinting, keeping handler signatures transparent and predictable.

How Has This Been Tested?

• Added new unit tests verifying metadata extraction and injection.
• Validated that existing handlers without a Metadata parameter continue working unchanged.
• Tested optional and missing metadata cases to ensure robust behavior.
• Verified handler execution flow with a real tool using a securitySchema passed via _meta.

Breaking Changes

This change is not breaking.
Existing handlers and configurations continue to work as before.
Metadata is injected only when a parameter explicitly type-hints Mcp\Schema\Metadata.

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

This approach is fully backward-compatible and future-proof.
The type-hint-based injection model can be extended later to support additional request-level context types (e.g., full request object, execution context, or transport metadata).

[Nxooah]

Hi, very well done. I need exactly the same thing. Hopefully it will be merged soon.

[Nyholm]

Thank you. I appreciate the idea.

Correct me if Im wrong, but this is not specified in the mcp protocol, is it?

[chr-hertel]

The spec only states this about metadata:
https://modelcontextprotocol.io/specification/2025-11-25/basic/index#meta

but it's not helpful if you can't access it when used - this is what this PR is about

[CodeWithKyrian]

Exactly!

On a related note, maybe this is a good time to revisit the Context object idea. Beyond just Meta and ClientGateway, there are probably going to be more things handlers need access to over time, and having a single injectable Context that exposes all request-scoped services feels like the cleanest long-term approach.

Once auth lands, this becomes even more relevant, since handlers will likely need access to user/session state without turning parameters into part of the Tool schema.

CC @chr-hertel @Nyholm @soyuka

[soyuka]

In my opinion we should provide the tooling so that users can access part of the request they need, though indeed we shouldn't multiply context value objects that can be injected as its an open door to too many changes (though this would be probably detected through argument resolving).

👍 @CodeWithKyrian a context would be nice, I'm usually preferring array structures then objects when it comes to exposing such context but in our case it may be cleaner with an object. We must think about changes and BC-layers though as the protocol being quite immature it'll probably change a lot, so does this library. I suggest that we should make clear to users that every bits of this context can probably be undefined and that the API should be prepared for that. To me it'd make sense to expose the full Request and leave users pick what they need (with a higher Meta abstraction getter if we feel it improves the DX).

[Nyholm]

I did implement a single injectable RequestContext in #176. I think that ticks all the boxes and maybe even replace this PR.