eb20453f49* [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
106 lines
3.3 KiB
PHP
106 lines
3.3 KiB
PHP
<?php
|
|
|
|
/*
|
|
* This file is part of the official PHP MCP SDK.
|
|
*
|
|
* A collaboration between Symfony and the PHP Foundation.
|
|
*
|
|
* For the full copyright and license information, please view the LICENSE
|
|
* file that was distributed with this source code.
|
|
*/
|
|
|
|
namespace Mcp\Server\Handler\Request;
|
|
|
|
use Mcp\Schema\Enum\ProtocolVersion;
|
|
use Mcp\Schema\Implementation;
|
|
use Mcp\Schema\JsonRpc\Request;
|
|
use Mcp\Schema\JsonRpc\Response;
|
|
use Mcp\Schema\Request\InitializeRequest;
|
|
use Mcp\Schema\Result\InitializeResult;
|
|
use Mcp\Schema\ServerCapabilities;
|
|
use Mcp\Server\Configuration;
|
|
use Mcp\Server\Session\SessionInterface;
|
|
|
|
/**
|
|
* @implements RequestHandlerInterface<InitializeResult>
|
|
*
|
|
* @author Christopher Hertel <mail@christopher-hertel.de>
|
|
*/
|
|
final class InitializeHandler implements RequestHandlerInterface
|
|
{
|
|
public function __construct(
|
|
public readonly ?Configuration $configuration = null,
|
|
) {
|
|
}
|
|
|
|
public function supports(Request $request): bool
|
|
{
|
|
return $request instanceof InitializeRequest;
|
|
}
|
|
|
|
/**
|
|
* @return Response<InitializeResult>
|
|
*/
|
|
public function handle(Request $request, SessionInterface $session): Response
|
|
{
|
|
\assert($request instanceof InitializeRequest);
|
|
|
|
$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(
|
|
$this->configuration->capabilities ?? new ServerCapabilities(),
|
|
$this->configuration->serverInfo ?? new Implementation(),
|
|
$this->configuration?->instructions,
|
|
null,
|
|
$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();
|
|
}
|
|
}
|