Skip to content

feat(client): report typed response decode errors - #1473

Draft
jonxsong wants to merge 1 commit into
modelcontextprotocol:mainfrom
jonxsong:fix/1415-typed-response-decode-errors
Draft

jonxsong wants to merge 1 commit into
modelcontextprotocol:mainfrom
jonxsong:fix/1415-typed-response-decode-errors

Conversation

@jonxsong

Copy link
Copy Markdown

Typed client calls now report the field path and underlying Serde error when an invalid standard list or startup result falls through to CustomResult. Refs #1415.

Motivation and Context

A tools/list reply with a missing inputSchema on its second tool used to produce UnexpectedResponse. The untagged ServerResult enum discarded the failed typed decode and retained the JSON as CustomResult. The client knew which method it had called, but discarded that context at the mismatch. Startup similarly returned ExpectedInitResult with a debug rendering of the response.

After the change, the same tool reply reports invalid tools/list result at tools[1]: missing field `inputSchema` and exposes a serde_json::Error via Error::source(). The typed error path deserializes the retained JSON by reference. It runs for the four standard list methods, legacy initialize, and server/discover. Auto mode uses the same startup paths, including the legacy error stored in LegacyFallbackFailed.

How Has This Been Tested?

The nine wire-level tests exercise a Tokio duplex peer. On upstream 165f8fd, all eight diagnostics cases failed at the missing-source assertion and the compatibility case passed. All nine pass with the patch under all features, the non-local feature set, and the minimal client,transport-async-rw set. The tests cover a valid reply after a malformed list, the four list result types, legacy initialization, Discover, Auto, legacy fallback, a recognized wrong result, and a raw custom result.

Windows x86-64, Rust 1.96.1:

  • cargo test --offline --all-features with the Windows baseline filters: 1,214 passed, 32 ignored, 3 filtered.
  • cargo test --offline -p rmcp --features "$FEATURES" with the CI's 29 non-local features: 1,819 passed, 18 ignored, 8 filtered. The additional five filters cover the JS/Python harnesses requiring npm or uv.
  • cargo test --offline -p rmcp --lib --no-default-features: 206 passed.
  • cargo +nightly fmt --all -- --check, strict all-targets Clippy with all features and the 29 non-local features, and cargo check --offline --workspace --all-targets: passed.
  • cargo +1.88.0 check --offline --all-targets --all-features and cargo build --offline -p rmcp --no-default-features --features client: passed.

The three baseline filters were default_http_client_preserves_connection_failure_cause (#1364) and rmcp_crate_ships_license / rmcp_macros_crate_ships_license (symlink placeholders in this Windows checkout). The results above are local Windows results.

Breaking Changes

The two public error enums are already non-exhaustive. These cases now return ResponseDecode; consumers can inspect the method, path, and source. Valid results and custom requests keep the existing wire classification. A reply classified as a different known result still follows the existing unexpected-result handling.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • Relevant MCP documentation reviewed.
  • Repository style checks passed.
  • New and applicable existing tests pass locally, with the exclusions above.
  • Added error handling with a preserved source.
  • Documented the public error variants.

Additional context

serde_path_to_error is optional under client and is already used transitively in the workspace. The error API exposes serde_json::Error as the source. Scope discussion

OpenAI Codex investigated the issue, implemented the fix and tests, ran local validation, and drafted this PR.

Recover the Serde error and field path for standard list and startup results that fall through to CustomResult. Preserve existing result classification, success handling, and custom request behavior.
@github-actions github-actions Bot added T-test Testing related changes T-config Configuration file changes T-core Core library changes T-service Service layer changes labels Nov 18, 2026
@github-actions

Copy link
Copy Markdown
Contributor

@michaelneale is on triage rotation this week and is the reviewer for this one.

Labels come from the PR labeler. Please review the change.

Automated triage. Labels are a first pass and the assigned maintainer has the final say.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

T-config Configuration file changes T-core Core library changes T-service Service layer changes T-test Testing related changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant