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
101 lines
4.6 KiB
PHP
101 lines
4.6 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\Transport\Http\Middleware;
|
|
|
|
use Http\Discovery\Psr17FactoryDiscovery;
|
|
use Mcp\Schema\Enum\ProtocolVersion;
|
|
use Mcp\Schema\JsonRpc\Error;
|
|
use Mcp\Server\Transport\Http\JsonRpcErrorResponse;
|
|
use Mcp\Server\Transport\StreamableHttpTransport;
|
|
use Psr\Http\Message\ResponseFactoryInterface;
|
|
use Psr\Http\Message\ResponseInterface;
|
|
use Psr\Http\Message\ServerRequestInterface;
|
|
use Psr\Http\Message\StreamFactoryInterface;
|
|
use Psr\Http\Server\MiddlewareInterface;
|
|
use Psr\Http\Server\RequestHandlerInterface;
|
|
|
|
/**
|
|
* Validates the `MCP-Protocol-Version` header against the SDK's supported set.
|
|
*
|
|
* Per the MCP Streamable HTTP spec, after the `initialize` handshake clients
|
|
* must echo the negotiated protocol version on every subsequent request via
|
|
* the `MCP-Protocol-Version` header. Servers MUST reject unknown or malformed
|
|
* values with `400 Bad Request`.
|
|
*
|
|
* When the header is absent the middleware passes the request through —
|
|
* the `initialize` round-trip does not carry the header, and legacy clients
|
|
* that omit it are tolerated.
|
|
*
|
|
* Validation is against a fixed set, not against the version a particular session
|
|
* negotiated: PSR-15 middleware runs before the transport resolves the session.
|
|
*
|
|
* @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header
|
|
*
|
|
* @author Volodymyr Panivko <sveneld300@gmail.com>
|
|
*/
|
|
final class ProtocolVersionMiddleware implements MiddlewareInterface
|
|
{
|
|
private ResponseFactoryInterface $responseFactory;
|
|
private StreamFactoryInterface $streamFactory;
|
|
|
|
/** @var list<string> */
|
|
private readonly array $supportedVersions;
|
|
|
|
/**
|
|
* @param list<ProtocolVersion>|null $supportedVersions Versions the server accepts. Defaults to {@see ProtocolVersion::handshakeVersions()}; modern revisions are excluded as their per-request negotiation is not served yet.
|
|
* @param ResponseFactoryInterface|null $responseFactory PSR-17 response factory (auto-discovered if null)
|
|
* @param StreamFactoryInterface|null $streamFactory PSR-17 stream factory (auto-discovered if null)
|
|
*/
|
|
public function __construct(
|
|
?array $supportedVersions = null,
|
|
?ResponseFactoryInterface $responseFactory = null,
|
|
?StreamFactoryInterface $streamFactory = null,
|
|
) {
|
|
$versions = $supportedVersions ?? ProtocolVersion::handshakeVersions();
|
|
$this->supportedVersions = array_values(array_map(static fn (ProtocolVersion $v): string => $v->value, $versions));
|
|
$this->responseFactory = $responseFactory ?? Psr17FactoryDiscovery::findResponseFactory();
|
|
$this->streamFactory = $streamFactory ?? Psr17FactoryDiscovery::findStreamFactory();
|
|
}
|
|
|
|
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
|
|
{
|
|
$headerValue = $request->getHeaderLine(StreamableHttpTransport::PROTOCOL_VERSION_HEADER);
|
|
|
|
// Spec backwards-compat: when the header is absent, the server SHOULD assume
|
|
// protocol version 2025-03-26 — the release in which Streamable HTTP and the
|
|
// header itself were introduced. This is deliberately lower than the SDK's
|
|
// own default so clients predating the header convention still get a
|
|
// deterministic protocol version applied. Servers that whitelist only newer
|
|
// versions in $supportedVersions will reject such requests with 400.
|
|
$version = '' === $headerValue ? ProtocolVersion::DEFAULT_HEADER_VERSION->value : $headerValue;
|
|
|
|
if (\in_array($version, $this->supportedVersions, true)) {
|
|
return $handler->handle($request);
|
|
}
|
|
|
|
$message = '' === $headerValue
|
|
? \sprintf(
|
|
'Missing %s header; backwards-compat default %s is not accepted. Supported versions: %s.',
|
|
StreamableHttpTransport::PROTOCOL_VERSION_HEADER,
|
|
$version,
|
|
implode(', ', $this->supportedVersions),
|
|
)
|
|
: \sprintf(
|
|
'Unsupported %s header value: %s. Supported versions: %s.',
|
|
StreamableHttpTransport::PROTOCOL_VERSION_HEADER,
|
|
$headerValue,
|
|
implode(', ', $this->supportedVersions),
|
|
);
|
|
|
|
return JsonRpcErrorResponse::create($this->responseFactory, $this->streamFactory, 400, Error::forInvalidParams($message));
|
|
}
|
|
}
|