feat: add MCP version compatibility scenarios

[LucaButBoring]

Adds coverage for clients that communicate with both draft and initialization-era MCP servers.

The client scenario verifies that a dual-era client sends a valid modern request before falling back to the fixed 2025-11-25 protocol version. The reference client caches the detected server era by HTTP origin and repeats detection when a cached legacy assumption fails.

Legacy-server response behavior remains a non-scored diagnostic because the MCP specification permits legacy servers to reject, ignore, or process an era-ambiguous request under legacy semantics.

Motivation and Context

The draft Streamable HTTP compatibility rules define a specific fallback sequence for clients that support both protocol eras. A client sends a valid modern request first. It falls back only when the server returns HTTP 400 without a recognized modern JSON-RPC error.

The previous implementation accepted any HTTP 4xx response, omitted the required Mcp-Method header, and treated legacy-server behavior as a scored conformance requirement. These checks could accept invalid client behavior and require behavior that the specification does not impose on legacy servers.

The change adds shared compatibility helpers for request construction, response classification, bounded body handling, and strict JSON-RPC error-envelope validation. It also removes the normative legacy-server scenario from the registry and retains equivalent coverage as a diagnostic.

How Has This Been Tested?

The following validation passed locally:

• Focused compatibility and registry suite: 5 files and 48 tests
• Full test suite: 48 files and 558 tests
• TypeScript type checking, ESLint, and Prettier through npm run check
• Package build through npm run build
• The version-backcompat client scenario through the conformance CLI
• The public legacy-server fixture, including initialization, notifications/initialized, and tools/list

The tests cover:

• Valid modern probe headers, method metadata, and JSON-RPC request shape
• Recognized modern error codes -32020, -32021, and -32022
• Empty, non-JSON, malformed, mismatched, and oversized HTTP 400 responses
• Non-400 HTTP status handling
• Strict legacy protocol-version negotiation
• Per-origin era caching and repeated detection after a cached assumption fails
• Transport cleanup and fixture process shutdown
• Scalar and oversized request-body rejection

Breaking Changes

No user code or configuration changes are required.

The draft client suite no longer includes pending scenarios. The legacy-server compatibility check is no longer a scored conformance scenario because the specification does not define one required legacy-server response.

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

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

The initialization-era boundary is fixed at 2025-11-25. It does not derive from the repository's latest protocol-version constant.

Modern error recognition requires an HTTP 400 response with an application/json content type and a valid JSON-RPC 2.0 error envelope. The response ID must match the modern probe request ID.

The fixture subprocess binds to 127.0.0.1 on an operating-system-selected port. Direct execution of the example server continues to use port 3010 by default.

This PR was written using GPT-5.6 Sol in Kiro Crew.

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/@modelcontextprotocol/conformance@464

commit: 969cfeb