[Client][Schema][Server] Implement protocol version negotiation (#403)

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

The `initialize` handler never looked at the version the client asked for:
it always answered with the server's configured version (or the SDK default),
so a client offering a revision the server supports could still be told to
speak a different one. The spec requires echoing back a supported request and
only counter-offering when the requested version cannot be honoured.

Turns ProtocolVersion into the registry the other SDKs converged on
(typescript-sdk's protocolEras.ts, python-sdk's mcp_types/version.py):
`latestHandshake()`, `handshakeVersions()`, `modernVersions()` and ordered
comparison through `isAtLeast()`. Comparison goes through declaration order
rather than string collation, so an unrecognized peer string compares
conservatively instead of accidentally sorting above a known revision. The
one throw the enum can produce is the SDK's own LogicException, so a consumer
catching `Mcp\Exception\ExceptionInterface` does not miss it.

Adds 2026-07-28 as a known revision and splits the set into two eras:
handshake (2025-11-25 and earlier, negotiated via `initialize`) and modern
(2026-07-28+, per-request `_meta`). The lists are kept apart so a modern
revision can never leak into an `initialize` exchange, which has no
`initialize` at all. Serving the modern era is follow-up work; this only
teaches the SDK that the revision exists and must not be mis-negotiated.
Deliberately absent is any "newest revision in any era" accessor, which
would hand back the one revision the handshake must never offer.

Server: negotiates and stores the result on the session. A version pinned in
Configuration still pins the handshake to exactly that revision.
Client: validates the counter-offer and fails the handshake instead of
continuing on a revision it cannot speak; records the negotiated version on
the client state, readable through the new Client::getProtocolVersion().

The HTTP middleware now defaults to the handshake versions rather than every
declared case, so it stops accepting a modern version the server cannot yet
serve. When the header is absent it falls back to
ProtocolVersion::DEFAULT_NEGOTIATED_VERSION (2025-03-26), the revision that
introduced both Streamable HTTP and the header itself.

The negotiation behaviour is one provideNegotiationTable() data provider
whose rows are the documented table -- supported revision echoed back,
unknown or malformed counter-offered, modern counter-offered -- so the docs
and the suite cannot drift apart. The supported-revision rows iterate
handshakeVersions() rather than a literal list, so declaring a new handshake
revision extends the table automatically, and the "never answer with a modern
revision" assertion runs on every row.

Documented in server-builder.md (the enum registry, how the server answers a
handshake, what pinning changes), transports.md (the header check) and
client.md (the client's side), all linking the spec's versioning section.

* [Client][Docs][Schema][Server] Warn when the configured protocol version cannot be negotiated

* Log a warning instead of silently falling back when a modern revision is
  configured on the client or pinned on the server builder.
* Document that setProtocolVersion() does not restrict the MCP-Protocol-Version
  header check, which validates against a fixed set.
* Pin every revision's era in a test, so a new case declared past the modern
  boundary fails instead of dropping out of the handshake set.
* Add CHANGELOG entry.

* [Client][Docs][Schema][Server] Rename version fallback constant and trim comments

src/Server/Handler/Request/InitializeHandler.php

@@ -11,6 +11,7 @@
 
 namespace Mcp\Server\Handler\Request;
 
+use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\Implementation;
 use Mcp\Schema\JsonRpc\Request;
 use Mcp\Schema\JsonRpc\Response;
@@ -47,6 +48,9 @@ final class InitializeHandler implements RequestHandlerInterface
         $session->set('client_info', $request->clientInfo->jsonSerialize());
         $session->set('client_capabilities', $request->capabilities->jsonSerialize());
 
+        $negotiated = $this->negotiate($request->protocolVersion);
+        $session->set('protocol_version', $negotiated->value);
+
         return new Response(
             $request->getId(),
             new InitializeResult(
@@ -54,8 +58,49 @@ final class InitializeHandler implements RequestHandlerInterface
                 $this->configuration->serverInfo ?? new Implementation(),
                 $this->configuration?->instructions,
                 null,
-                $this->configuration?->protocolVersion,
+                $negotiated,
             ),
         );
     }
+
+    /**
+     * Picks the protocol version to answer an `initialize` handshake with.
+     *
+     * If the client asked for a version this server supports, the spec requires
+     * responding with that exact version. Otherwise the server counter-offers
+     * the newest version it does support and leaves it to the client to decide
+     * whether it can continue on that revision or must disconnect.
+     */
+    private function negotiate(string $requested): ProtocolVersion
+    {
+        $supported = $this->supportedVersions();
+        $version = ProtocolVersion::tryFrom($requested);
+
+        if (null !== $version && \in_array($version, $supported, true)) {
+            return $version;
+        }
+
+        return $supported[\count($supported) - 1];
+    }
+
+    /**
+     * Versions this server is willing to negotiate over `initialize`.
+     *
+     * A version configured on the server pins the handshake to exactly that
+     * revision. Modern revisions are never offered here: they have no
+     * `initialize` at all, so a client that reached this handler cannot speak
+     * one, and answering with it would leave the connection unusable.
+     *
+     * @return non-empty-list<ProtocolVersion>
+     */
+    private function supportedVersions(): array
+    {
+        $configured = $this->configuration?->protocolVersion;
+
+        if (null !== $configured && !$configured->isModern()) {
+            return [$configured];
+        }
+
+        return ProtocolVersion::handshakeVersions();
+    }
 }