Surface Modern client consumption helpers in mcpcompat

[JAORMX]

Summary

Why: PR3 of the Phase 1 mcpcompat stateless work (after #185, #187). Gives downstream ToolHive the additive shim surface to consume MCP 2026-07-28 backends and classify Modern responses without importing go-sdk directly. go-sdk v1.7's client Connect already does the Modern wire negotiation, so this is re-exporting/adapting, not new protocol logic.

What (all additive — no existing exported signature changed):

• Re-export the 2026-07-28 error codes as shim-owned constants: HEADER_MISMATCH=-32020, MISSING_REQUIRED_CLIENT_CAPABILITIES=-32021, UNSUPPORTED_PROTOCOL_VERSION=-32022. Kept as local literals (matching the file's pattern, not aliases); a test pins them to the exported gosdk.Code* values so a renumber on a future SDK bump fails loudly.
• CallToolResult.NeedsInput() — capture the wire resultType discriminator in UnmarshalJSON (go-sdk emits "input_required" for an MRTR input-required result) and expose an accessor mirroring go-sdk's. MarshalJSON unchanged (the shim result is consumed/classified, never re-forwarded).
• client.WithoutMultiRoundTrip() — opt out of go-sdk's automatic multi-round-trip so an input-required result surfaces to the caller instead of being auto-fulfilled. Detection only for now (documented): the shim doesn't yet model InputRequests/RequestState, so fulfilling/retrying through the shim isn't supported.
• Documented the per-backend protocol-version pin gap (#5911): the shim passes nil ClientSessionOptions to Connect and can't force a version because the field is unexported upstream — upstream ask recommended.

Deferred (no consumer yet — tracked here, deliberately not left as code TODOs)

• DiscoverResult/SupportedVersions surfacing, per-request _meta.protocolVersion echo — go-sdk's Connect handles negotiation internally.
• Cacheable/cacheScope/ttlMs on client-consumed results — no client-side cache consumer.
• InputRequests/RequestState on the shim CallToolResult — needed only to act on/forward an input-required result (NeedsInput needs only resultType). If ToolHive later forwards Modern input-required results, it must add resultType+InputRequests+RequestState together and update MarshalJSON.
• NeedsInput is CallTool-scoped for PR3 (not GetPrompt/ReadResource) — intended.

Review

Two Opus panels (MCP-correctness + code-quality/API-compat) confirmed correct/additive; their cleanups are applied (dead const removed, error-code test pinned to go-sdk consts, WithoutMultiRoundTrip doc softened to detection-only).

Depends on

Follows #185/#187 (merged). Same pre-release constraint (release guard blocks tagging until go-sdk v1.7.0 final).

Test plan

• task test (race) — Modern error-code constants pinned to go-sdk; NeedsInput() across wire shapes; MRTR opt-out surfaces input-required (err==nil, NeedsInput()==true, handler once) vs default MRTR errors
• task lint — 0 issues
• task license-check — clean
• go build ./... — clean

🤖 Generated with Claude Code

[jhrozek]

Reviewed this and put the fixes in #190, stacked on this branch rather than pushed here — that way you keep the merge decision and I keep my review on #189. Merge it, cherry-pick it, or tell me to rebase it into your commit; whatever you prefer.

One real bug. WithoutMultiRoundTrip() disables go-sdk's MRTR handling for all three MRTR-capable methods — the middleware intercepts tools/call, prompts/get and resources/read — but only CallToolResult models resultType. CallTool survives because it converts via jsonConvert; convertGetPromptResult and convertReadResourceResult are hand-written field-by-field, so they drop the field. Result: with the opt-out set, an input-required prompt or resource read returns err == nil with zero messages/contents, indistinguishable from an empty success. Reproduced against a stateless 2026-07-28 backend before fixing. #190 adds NeedsInput to both types and populates it in both converters.

Six doc/test items, the notable one being HEADER_MISMATCH: its comment described matching against "the initial InitializeRequest", but 2026-07-28 is stateless with no handshake — -32020 validates headers against the same request's own body. go-sdk's own comment has it right; the shim's rewording lost the meaning. Also marked -32002/-32042 as legacy (the draft spec says this revision MUST NOT emit either), fixed the WithoutMultiRoundTrip "consulted when the client connects" rationale (go-sdk reads it in NewClient, which Initialize calls), added a regression test for the documented MarshalJSON-drops-resultType invariant, and pinned the assert.Error-only MRTR subtest to the actual -32602 / "client does not support elicitation" contract.

One thing I deliberately left for you rather than deciding on your behalf: whether the classification should be an unexported field + SetNeedsInput(bool) (what #190 does, matching your CallToolResult shape) or an exported ResultType string tagged json:"-" with exported consts. There's a decent argument for the latter — SetNeedsInput(true) on a server-built result silently does nothing since MarshalJSON drops the field, and this package already uses exported + json:"-" for RawInputSchema/Extra. It'd touch your CallToolResult field too, so it's your call. Details in #190.

Nothing else blocking from my side. The resultType-not-re-emitted decision checks out, by the way — I traced toolhive's forwarding paths and nothing re-forwards a shim CallToolResult today (vMCP converts through vmcp.ToolCallResult, which has no equivalent field; pkg/authz/response_filter.go still uses mark3labs types). Worth noting in the migration issue as the one spot where an unexported non-re-emitted field could become a silent regression.