Fix(mcp): Unreachable structured content branch in invoke_mcp_tool

[Kunmeer-SyedMohamedHyder]

Summary

This PR handles the MCP tool output where structured content could never be returned exclusively when use_structured_content=True. The conditional logic checked for content length first, making the structured content branch unreachable when both content types were present.

Before (broken logic):

if len(result.content) == 1:
    tool_output = result.content[0].model_dump_json()
elif server.use_structured_content and result.structuredContent:  # Never reached!
    tool_output = json.dumps(result.structuredContent)

After (fixed logic):

if server.use_structured_content and result.structuredContent:
    tool_output = json.dumps(result.structuredContent)
else:
    # Fall back to regular text content processing
    if len(result.content) == 1:
        tool_output = result.content[0].model_dump_json()

Example usage:

# MCP server with structured content enabled
server = MCPServer(use_structured_content=True)

# When invoke_mcp_tool processes a tool that returns both text and structured content:
# - Text content: "Found 2 users"
# - Structured content: {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}

result = await MCPUtil.invoke_mcp_tool(server, tool, context, input_json)

# Before fix: Would return '{"type":"text","text":"Found 2 users","annotations":null,"meta":null}'
# After fix: Returns '{"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}'

Test plan

I've added thorough test coverage to make sure this fix works properly:

• Created tests for 9 different scenarios to verify structured content takes priority when it should, and falls back correctly when it shouldn't
• Added specific tests to ensure the core priority logic works as expected and that we didn't break any existing functionality
• Confirmed that the tests catch the original bug (unreachable code) and validate that our fix actually solves the problem

Issue number

Fixes #1236

Checks

• I've added new tests (if relevant) - Added comprehensive parameterized tests and individual test functions for all structured content scenarios
• I've added/updated the relevant documentation - Code comments updated to explain the fix and logic flow
• I've run make lint and make format - Code follows project formatting standards
• I've made sure tests pass - All existing tests continue to pass, and new structured content tests validate the fix