Description

Summary

Implement support for the optional _meta field in CallToolRequestParams as defined in the MCP
specification (2025-11-25).

Background

The MCP specification defines an optional _meta field in tool call requests that allows clients to
pass arbitrary metadata alongside tool invocations. This metadata can be used for:

• Request tracking and correlation
• Client context information
• Debugging and observability
• Testing metadata propagation in MCP implementations

Current State

Yardstick currently does not support the _meta field in tool call requests, which limits its
usefulness as a testing server for:

• Validating that MCP clients properly send metadata
• Testing that MCP proxies/routers preserve metadata
• Verifying metadata-based behaviors in MCP implementations

Proposed Changes

1. Tool Handler

   • Accept _meta field in tool call requests
   • Parse and validate the metadata structure
   • Echo back metadata in responses (for testing purposes)

2. Test Tools

   • Add a test tool that specifically validates _meta handling (e.g., echo_meta)
   • Return metadata in tool results to verify round-trip behavior
   • Support testing metadata propagation scenarios

3. Logging/Output

   • Log received _meta fields for debugging
   • Include metadata in any diagnostic output

Acceptance Criteria

• _meta field is accepted in tool call requests
• Server does not reject requests containing _meta
• Test tool(s) can echo back received metadata
• Metadata is logged for debugging purposes
• Unit tests validate metadata handling
• Documentation updated with _meta usage examples

Use Cases for Testing

• Validate that Virtual MCP servers preserve _meta when forwarding
• Test that proxies don't strip metadata from requests
• Verify metadata-based request correlation in observability systems
• Test custom metadata extensions in MCP implementations

References

• MCP Specification: CallToolRequestParams

Additional Context

As a testing server, Yardstick should support all standard MCP features including optional fields like
_meta to enable comprehensive testing of MCP implementations.