fix(gateway): preserve structured tool results

[Xuleileon]

Summary

Preserve structuredContent and protocol-level _meta when forwarding downstream tools/call results through the gateway.

Problem

A downstream server can advertise an outputSchema and correctly return both text content and structuredContent. The gateway previously reduced that response to only content plus isError while routing it, then constructed a new CallToolResult from those two fields.

Strict MCP clients consequently rejected otherwise successful tool calls with an error like:

Tool <qualified-name> has an output schema but did not return structured content

This is not specific to one downstream implementation: it affects any tool that advertises an output schema and returns structured output.

Root cause

The result was narrowed at two gateway boundaries:

1. RoutingService converted the downstream CallToolResult into a custom ToolCallResult containing only content and is_error.
2. The MCP handler reconstructed a fresh success/error result from those fields.

Both transformations discarded structured_content; protocol-level meta was discarded for the same reason.

Fix

• Carry structured_content and meta through ToolCallResult.
• Centralize conversion to and from CallToolResult so both routing boundaries preserve the same fields.
• Add a regression test covering text content, structured content, metadata, and the success state across the round trip.

No downstream server changes are required.

Verification

• cargo +1.88.0 fmt --all -- --check
• cargo +1.88.0 test -p mcpmux-gateway — 145 passed, 0 failed
• cargo +1.88.0 build --release -p mcpmux
• End-to-end checks against output-schema tools confirmed that responses routed through the gateway retain both content and structuredContent and pass client-side output validation.

Scope

The patch is limited to the gateway result-conversion path and one regression test. It does not change downstream servers, tool schemas, permissions, or feature-set routing.

[its-mash]

@claude review this PR

[claude]

Claude finished @its-mash's task in 1m 51s —— View job

---

Review: preserve structured tool results

• Gather context (diff, changed files)
• Understand the fix (structured content / meta preservation)
• Review crates/mcpmux-gateway/src/pool/routing.rs
• Review crates/mcpmux-gateway/src/mcp/handler.rs
• Check regression test coverage
• Post final review

Summary

This is a well-scoped fix. The root cause analysis is correct: ToolCallResult previously only carried content + is_error, so both the routing boundary (routing.rs) and the MCP handler boundary (handler.rs) discarded structured_content and meta when rebuilding CallToolResult. Centralizing the conversion in ToolCallResult::from_mcp_result / ToolCallResult::into_mcp_result (crates/mcpmux-gateway/src/pool/routing.rs:59-88) is the right fix — it guarantees both boundaries stay in sync going forward instead of duplicating field-by-field mapping logic.

Things that look good

• Single construction site for ToolCallResult (routing.rs:320) already updated to use from_mcp_result, so no other call site could silently regress.
• handler.rs:863-865 now just calls tool_result.into_mcp_result() instead of manually rebuilding content/is_error — removes the duplicated success/error branch that was dropping structured_content.
• The regression test (routing.rs:754-780) round-trips a CallToolResult with text content, structured_content, and _meta, and asserts all three survive — this is exactly the right test for the reported bug (strict clients rejecting output-schema tools).
• from_mcp_result stays private and into_mcp_result is pub(crate), consistent with existing visibility conventions in this module.

Minor / non-blocking observations

1. Double JSON round-trip for content (routing.rs:62-66 then 74-78): content items go Content -> Value in from_mcp_result and back Value -> Content in into_mcp_result. This was already the pattern before this PR (not a regression), but since ToolCallResult now exists purely to bridge these two conversions, a future cleanup could consider carrying Vec<Content> directly to avoid the extra serialize/deserialize pass and the associated filter_map silently dropping any item that fails to deserialize.
2. Similar narrowing exists elsewhere: read_resource (handler.rs:1127-1141) still converts through Vec<Value> → Vec<ResourceContents> and constructs a fresh ReadResourceResult::new(contents), which would drop any _meta on that result the same way call_tool used to. Out of scope for this PR (which is intentionally scoped to tool calls per the "Scope" section), but worth a follow-up if resource reads ever need to carry protocol-level metadata.
3. Test only covers the success path with structured content; an explicit case asserting is_error: true + structured_content survives the round trip together would close the loop, though the existing assertions already exercise is_error conversion logic.

None of these block the fix — the core bug (structured content and _meta being dropped) is correctly addressed and covered by a targeted regression test.

Branch: agent/preserve-structured-content