Python: feat(mcp): add full _meta field support for CallToolResult objects

[bostdiek]

Motivation and Context

The Agent Framework library violated the official Model Context Protocol (MCP) specification by completely dropping the _meta field from CallToolResult responses. This prevented applications from accessing critical metadata such as token usage, cost information, performance metrics, and error states that MCP servers provide.

Problems this solves:

1. Protocol compliance violation - The framework was not respecting the official MCP specification
2. Loss of critical metadata - Token usage, costs, and performance metrics were being dropped
3. Broken error handling - The isError field was not being preserved for proper error state detection
4. Integration issues - Prevented proper monitoring and cost tracking of MCP tool usage

This change ensures full compliance with the official MCP specification and enables proper tool metadata access for applications.

Description

Core Changes:

• Enhanced _mcp_call_tool_result_to_ai_contents() function to extract and preserve the complete _meta field from CallToolResult objects
• Implemented metadata merging into the additional_properties field of converted content items following the framework's existing patterns
• Added graceful handling for missing, None, or non-dict _meta values to ensure robustness
• Maintained complete backward compatibility - all existing workflows continue to work unchanged

Technical Implementation:

• Uses getattr() for safe _meta field extraction to handle version compatibility
• Supports both dict-like metadata and object-attribute metadata structures
• Merges metadata with existing additional_properties without overwriting
• Stores non-dict _meta values under a special _meta key for edge case handling

Enhanced Functionality:

• Error state integration: Preserves isError flags for proper error handling workflows
• Cost tracking: Enables access to token usage and API cost information
• Performance monitoring: Preserves execution time and performance metrics
• Debugging support: Maintains all metadata for troubleshooting and monitoring

Comprehensive Testing:
Added 8 new test functions covering all scenarios:

• _meta with isError=True error scenarios
• Arbitrary metadata preservation (token usage, costs, etc.)
• Metadata merging with existing additional_properties
• Object-attribute _meta structures
• Missing _meta field handling
• Non-dict _meta values
• Regression tests for existing successful workflows
• Integration testing with the call_tool() method

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible (8 new tests, all 68 total tests passing)
• Is this a breaking change? No - this is fully backward compatible and maintains all existing functionality

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_mcp.py	367	58	84%	184, 194–195, 216, 241, 256, 262, 266, 268, 359, 386, 420–421, 423–431, 433–435, 438–439, 485, 500, 518, 559, 572, 575–576, 580, 590, 614, 617–618, 622, 632, 663, 682, 684, 691–692, 711, 713, 719–722, 739–743, 871
TOTAL	15463	2354	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2183	127 💤	0 ❌	0 🔥	57.310s ⏱️

[Copilot]

Pull Request Overview

This PR adds full support for extracting and preserving the _meta field from MCP CallToolResult objects to ensure compliance with the Model Context Protocol specification. Previously, all metadata including error states, token usage, costs, and performance metrics were being dropped during conversion.

Key changes:

• Enhanced the _mcp_call_tool_result_to_ai_contents() function to extract and merge _meta field data into content items' additional_properties
• Added comprehensive test coverage with 8 new test functions covering error states, arbitrary metadata, object attributes, edge cases, and integration scenarios
• Updated sample documentation to reflect the new metadata extraction capabilities

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
python/packages/core/agent_framework/_mcp.py	Core implementation of _meta field extraction and merging logic with support for dicts, objects with __dict__, and non-dict values
python/packages/core/tests/core/test_mcp.py	Added 8 comprehensive test functions covering metadata extraction scenarios including errors, arbitrary data, object attributes, merging, and edge cases
python/samples/getting_started/agents/openai/openai_chat_client_with_local_mcp.py	Updated docstring to document the new metadata extraction feature

[eavanvalkenburg]

thanks for looking into this, let's make it a bit more complete!