[Client][Schema][Server] Implement protocol version negotiation

[chr-hertel]

Groundwork for the 2026-07-28 spec release: makes the SDK's protocol version handling explicit and correct before the stateless/modern-era work lands on top of it.

The bug

InitializeHandler never read $request->protocolVersion. It answered every handshake with $configuration->protocolVersion (or the SDK default), so negotiation effectively did not exist — a client offering a revision the server supports could still be told to speak a different one.

The spec requires the opposite: if the server supports the requested version it MUST respond with that same version, and only counter-offer when it cannot honour the request.

Version registry

ProtocolVersion becomes the registry the other SDKs converged on — typescript-sdk's shared/protocolEras.ts and python-sdk's mcp_types/version.py:

ProtocolVersion::latest();             // newest, any era
ProtocolVersion::latestHandshake();    // newest reachable via `initialize`
ProtocolVersion::latestModern();
ProtocolVersion::oldest();
ProtocolVersion::handshakeVersions();  // ordered subsets
ProtocolVersion::modernVersions();
$version->isModern();
$version->isAtLeast($minimum);
$version->isOlderThan($other);

Ordering goes through declaration order, not string collation. Revision identifiers happen to be ISO dates today, but they are an enumerated set rather than an ordered scalar — future identifiers are not guaranteed to be date-shaped, and an unrecognized peer string must compare conservatively instead of accidentally sorting above a known revision ("zzz" > "2025-11-25" is true under string comparison).

Two eras

2026-07-28 is added as a known revision, and the set splits in two:

• handshake — 2025-11-25 and earlier: version negotiated through the initialize round-trip.
• modern — 2026-07-28+: no initialize at all; every request carries its version in _meta and servers advertise through server/discover.

The two lists are deliberately kept apart, mirroring the TypeScript SDK's reasoning, so that adding a revision to one era can never leak a version string into the other era's negotiation. A modern revision must never appear in an initialize exchange — that method does not exist in that era, and answering with one leaves a connection neither side can use.

Serving the modern era is follow-up work. This PR only teaches the SDK that the revision exists and must not be mis-negotiated.

Behaviour

Server (InitializeHandler) — negotiates, and stores the result on the session under protocol_version so downstream version-gated serialization has something to read:

Client requests	Server answers
a supported handshake version	that same version
unknown / malformed	newest handshake version
a modern version	newest handshake version (never a modern one)

Client (Client\Protocol::initialize()) — validates the counter-offer instead of silently ignoring it. InitializeResult::fromArray() uses tryFrom, so an unknown version previously became null and was dropped on the floor. A counter-offer the SDK cannot speak now fails the handshake (surfacing as ConnectionException through both transports) rather than continuing on a revision neither side agreed on. The negotiated version is recorded on ClientState. A client configured with a modern revision still offers the newest handshake version, mirroring the server-side invariant.

Transport — ProtocolVersionMiddleware defaults to handshakeVersions() rather than every declared case, so it stops accepting a modern version this server cannot yet serve. The header-absent fallback is now the named ProtocolVersion::DEFAULT_NEGOTIATED_VERSION instead of an inline V2025_03_26.

Points for review

1. Configuration::$protocolVersion shifts meaning — from "the version the server announces" to "pin the handshake to exactly this revision". A pin still wins over the client's request, so an explicit pin stays meaningful. If spec-echo should always win instead, that is a one-line change in InitializeHandler::supportedVersions().
2. ProtocolVersionMiddleware's default set narrowed. Anyone relying on the default to accept everything in the enum will now see 2026-07-28 rejected with 400. That is the intent — the alternative is advertising support that does not exist — but it is a visible default change. Its test was updated and one added asserting modern versions are rejected by default.
3. ProtocolVersion::cases() and handshakeVersions() now differ, so every call site has to pick one deliberately. Both current call sites were reviewed.
4. MessageInterface::PROTOCOL_VERSION left alone (still V2025_11_25, currently equal to latestHandshake()). It is a const so it cannot call a method; retiring it belongs with the modern-era work.

Testing

make cs and make phpstan clean; 957 tests pass (7 pre-existing skips).

New coverage: ProtocolVersionTest (era partition, ordering, the invariant that no modern revision leaks into the handshake list), Client\ProtocolTest (offer, counter-offer acceptance, rejection of unusable counter-offers), plus negotiation cases on InitializeHandlerTest.

Follow-ups this unblocks

Version-gated serialization is the next prerequisite: resultType on every result, ttlMs/cacheScope (#354), and the resource-not-found code flip (#359) all need to emit different shapes per negotiated version, which the DTOs cannot express today — jsonSerialize() takes no arguments. This PR provides the version to gate on; it does not build the gate.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR makes protocol version negotiation explicit and spec-correct across the SDK’s server handshake path, client handshake validation, and HTTP transport version filtering, while introducing an enum-based registry that partitions “handshake” vs “modern” eras.

Changes:

• Add a ProtocolVersion registry with ordered subsets (handshakeVersions() / modernVersions()), comparisons by declaration order, and a new known revision 2026-07-28.
• Fix server-side initialize negotiation to echo supported client requests, counter-offer appropriately, and persist the negotiated version on the session.
• Tighten client and transport behavior: clients validate/record negotiated versions; HTTP middleware defaults to accepting only handshake-era revisions.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Schema/Enum/ProtocolVersion.php	Adds modern-era revision + version registry helpers and ordering semantics.
src/Server/Handler/Request/InitializeHandler.php	Implements server-side negotiation + session persistence of negotiated version.
src/Server/Transport/Http/Middleware/ProtocolVersionMiddleware.php	Defaults supported versions to handshake-era only; uses named default for missing header.
src/Client/Protocol.php	Offers handshake-era version when configured modern; validates counter-offers; records negotiated version in state.
src/Client/State/ClientStateInterface.php	Adds protocol-version getters/setters to client state.
src/Client/State/ClientState.php	Stores negotiated protocol version on the client state.
tests/Unit/Schema/Enum/ProtocolVersionTest.php	Adds coverage for era split, accessors, comparisons, and defaults.
tests/Unit/Server/Handler/Request/InitializeHandlerTest.php	Adds negotiation and session-storage test coverage for InitializeHandler.
tests/Unit/Server/Transport/Http/Middleware/ProtocolVersionMiddlewareTest.php	Updates default-acceptance expectations to handshake-era and adds modern-rejection test.
tests/Unit/Client/ProtocolTest.php	Adds coverage for offered version, counter-offer acceptance, and counter-offer rejection.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.