StatelessProtocolTest.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\Tests\Unit\Server\Stateless;

use Mcp\Event\ErrorEvent;
use Mcp\Event\RequestEvent;
use Mcp\Event\ResponseEvent;
use Mcp\Exception\MissingRequiredClientCapabilityException;
use Mcp\JsonRpc\MessageFactory;
use Mcp\Schema\ClientCapabilities;
use Mcp\Schema\Content\TextResourceContents;
use Mcp\Schema\Elicitation\ElicitationSchema;
use Mcp\Schema\Elicitation\StringSchemaDefinition;
use Mcp\Schema\Enum\CacheScope;
use Mcp\Schema\Enum\LoggingLevel;
use Mcp\Schema\Enum\ProtocolVersion;
use Mcp\Schema\Implementation;
use Mcp\Schema\JsonRpc\Error;
use Mcp\Schema\JsonRpc\Request;
use Mcp\Schema\JsonRpc\Response;
use Mcp\Schema\Notification\PromptListChangedNotification;
use Mcp\Schema\Notification\ResourceUpdatedNotification;
use Mcp\Schema\Notification\ToolListChangedNotification;
use Mcp\Schema\Request\CallToolRequest;
use Mcp\Schema\Request\DiscoverRequest;
use Mcp\Schema\Request\ElicitRequest;
use Mcp\Schema\Request\ListRootsRequest;
use Mcp\Schema\Result\DiscoverResult;
use Mcp\Schema\Result\InputRequiredResult;
use Mcp\Schema\Result\ReadResourceResult;
use Mcp\Schema\ServerCapabilities;
use Mcp\Server;
use Mcp\Server\Authorization\AccessToken;
use Mcp\Server\Configuration;
use Mcp\Server\Handler\Request\RequestHandlerInterface;
use Mcp\Server\RequestContext;
use Mcp\Server\Session\SessionInterface;
use Mcp\Server\Stateless\OriginatingRequestBinder;
use Mcp\Server\Stateless\RequestMeta;
use Mcp\Server\Stateless\RequestStateBinderInterface;
use Mcp\Server\Stateless\StatelessProtocol;
use Mcp\Server\Stateless\StatelessResult;
use Mcp\Server\Subscription\InMemoryNotificationBus;
use Mcp\Server\Suspension\NotificationSuspension;
use Mcp\Server\Wire\CachePolicy;
use Mcp\Tests\Unit\Fixtures\ThrowingRequest;
use Mcp\Tests\Unit\Server\Extension\ThingExtension;
use Mcp\Tests\Unit\Server\Extension\UnservedThingExtension;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
use Psr\EventDispatcher\EventDispatcherInterface;

class StatelessProtocolTest extends TestCase
{
    /**
     * @param array<string, mixed> $capabilities
     */
    private static function protocol(array $capabilities = [], ?EventDispatcherInterface $eventDispatcher = null): StatelessProtocol
    {
        $builder = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->addTool(static fn (): string => 'ok', name: 'plain_tool', description: 'Returns a fixed string')
            ->addTool(
                static function (RequestContext $context): string {
                    $gateway = $context->getClientGateway();

                    return implode(',', array_keys(array_filter([
                        'roots' => $gateway->supportsRoots(),
                        'sampling' => $gateway->supportsSampling(),
                        'sampling.tools' => $gateway->supportsSamplingTools(),
                        'elicitation' => $gateway->supportsElicitation(),
                        'elicitation.url' => $gateway->supportsElicitationUrl(),
                    ]))) ?: 'none';
                },
                name: 'probe_capabilities',
                description: 'Reports which client capabilities the gateway can see',
            )
            ->addTool(
                static function (RequestContext $context): string {
                    $gateway = $context->getClientGateway();
                    $gateway->progress(0, 100, 'starting');
                    $gateway->progress(100, 100, 'done');

                    return 'progressed';
                },
                name: 'progress_tool',
                description: 'Reports progress while it works',
            )
            ->addTool(
                static function (RequestContext $context): string {
                    $gateway = $context->getClientGateway();
                    foreach ([LoggingLevel::Debug, LoggingLevel::Info, LoggingLevel::Warning, LoggingLevel::Error] as $level) {
                        $gateway->log($level, $level->value.' message');
                    }

                    return 'logged';
                },
                name: 'logging_tool',
                description: 'Emits one message at each of four levels',
            )
            ->addTool(
                static function (RequestContext $context): string {
                    $logger = $context->getClientLogger();
                    $logger->debug('debug message');
                    $logger->info('info message');
                    $logger->warning('warning message');

                    return 'logged';
                },
                name: 'client_logger_tool',
                description: 'Logs through the PSR-3 client logger',
            )
            ->addTool(
                static function (): never {
                    throw new MissingRequiredClientCapabilityException(new ClientCapabilities(roots: false, sampling: true), 'needs sampling');
                },
                name: 'capability_tool',
                description: 'Always reports a missing client capability',
            )
            ->addTool(
                static function (RequestContext $context): string {
                    $answer = $context->getClientGateway()->elicit('name?', new ElicitationSchema(['n' => new StringSchemaDefinition('N')], ['n']));

                    return 'hello '.($answer->content['n'] ?? '?');
                },
                name: 'elicits_directly',
                description: 'Asks through the gateway, the way a handshake-era handler does',
            )
            ->addTool(
                static function (RequestContext $context): string {
                    $gateway = $context->getClientGateway();
                    $gateway->progress(0, 100, 'starting');

                    $answer = $gateway->elicit('name?', new ElicitationSchema(['n' => new StringSchemaDefinition('N')], ['n']));

                    return 'hello '.($answer->content['n'] ?? '?');
                },
                name: 'elicits_after_progress',
                description: 'Reports progress, then asks through the gateway',
            )
            ->addTool(
                static function (RequestContext $context): string {
                    // A kind this revision removed rather than reshaped: kept as
                    // a fixture so the refusal has something to refuse.
                    $context->getClientGateway()->request(new ListRootsRequest());

                    return 'unreachable';
                },
                name: 'asks_for_roots',
                description: 'Asks the client directly for something this revision removed',
            )
            ->addTool(
                static fn (): InputRequiredResult => new InputRequiredResult([
                    'consent' => ElicitRequest::forUrl('Approve out of band', 'https://example.com/consent'),
                ]),
                name: 'asks_by_url',
                description: 'Asks through a url-mode elicitation',
            )
            ->addTool(
                static function (RequestContext $context): InputRequiredResult {
                    $context->getClientGateway()->progress(0, 100, 'starting');

                    return new InputRequiredResult([
                        'consent' => ElicitRequest::forUrl('Approve out of band', 'https://example.com/consent'),
                    ]);
                },
                name: 'asks_by_url_after_progress',
                description: 'Emits progress, then asks through a url-mode elicitation',
            )
            ->addTool(
                static function (RequestContext $context): string {
                    $pairs = [];
                    foreach ($context->getTraceContext() as $key => $value) {
                        $pairs[] = $key.'='.$value;
                    }

                    return implode(';', $pairs) ?: 'none';
                },
                name: 'probe_trace',
                description: 'Reports the trace context it was called with',
            )
            ->addResource(static fn (): string => 'body', 'test://static', 'static', 'A static resource')
            ->addResource(
                static function (RequestContext $context): string|InputRequiredResult {
                    $input = $context->getInputContext();

                    if (null === $input || !$input->has('who')) {
                        return new InputRequiredResult([
                            'who' => new ElicitRequest('Who is asking?', new ElicitationSchema(['n' => new StringSchemaDefinition('N')], ['n'])),
                        ]);
                    }

                    return 'body for '.($input->response('who')['content']['n'] ?? '?');
                },
                'test://gated',
                'gated',
                'A resource that asks who is reading before it answers',
            );

        if (null !== $eventDispatcher) {
            $builder->setEventDispatcher($eventDispatcher);
        }

        return $builder->buildStateless([ProtocolVersion::V2026_07_28]);
    }

    /**
     * @param array<string, mixed>  $params
     * @param array<string, string> $extraHeaders
     *
     * @return array<string, mixed>
     */
    private static function call(StatelessProtocol $protocol, string $method, array $params = [], array $extraHeaders = [], array $capabilities = []): array
    {
        // Merged, not replaced: a test may add its own `_meta` members.
        $params['_meta'] = [
            RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
            RequestMeta::CLIENT_CAPABILITIES => (object) $capabilities,
            ...($params['_meta'] ?? []),
        ];

        return self::callWithHeaders($protocol, $method, $params, [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => $method,
            ...$extraHeaders,
        ]);
    }

    /**
     * The header-exact variant: nothing is filled in, so a test can leave a
     * required header out.
     *
     * @param array<string, mixed>  $params
     * @param array<string, string> $headers
     *
     * @return array<string, mixed>
     */
    private static function callWithHeaders(
        StatelessProtocol $protocol,
        string $method,
        array $params = [],
        array $headers = [],
        ?string $metaVersion = null,
    ): array {
        $params['_meta'] ??= [
            RequestMeta::PROTOCOL_VERSION => $metaVersion ?? ProtocolVersion::V2026_07_28->value,
            RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
        ];

        $result = $protocol->handle(
            json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => $method, 'params' => $params], \JSON_THROW_ON_ERROR),
            $headers,
        );

        return [
            'status' => $result->httpStatus,
            'body' => json_decode($result->toJson(), true, flags: \JSON_THROW_ON_ERROR),
        ];
    }

    #[TestDox('the gateway sees the capabilities this request declared, not an empty session')]
    public function testClientCapabilitiesReachTheGateway(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'probe_capabilities', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'probe_capabilities'],
            ['roots' => new \stdClass(), 'elicitation' => ['url' => new \stdClass()], 'sampling' => ['tools' => new \stdClass()]],
        );

        $this->assertSame(200, $answer['status']);
        $this->assertSame(
            'roots,sampling,sampling.tools,elicitation,elicitation.url',
            $answer['body']['result']['content'][0]['text'],
        );
    }

    #[TestDox('a client declaring nothing is reported as declaring nothing')]
    public function testEmptyCapabilitiesReportNone(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'probe_capabilities', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'probe_capabilities'],
        );

        $this->assertSame('none', $answer['body']['result']['content'][0]['text']);
    }

    /**
     * @return iterable<string, array{string, array<string, mixed>}>
     */
    public static function removedMethods(): iterable
    {
        yield 'ping' => ['ping', []];
        yield 'logging/setLevel' => ['logging/setLevel', ['level' => 'info']];
        yield 'resources/subscribe' => ['resources/subscribe', ['uri' => 'test://static']];
        yield 'resources/unsubscribe' => ['resources/unsubscribe', ['uri' => 'test://static']];
    }

    /**
     * @param array<string, mixed> $params
     */
    #[DataProvider('removedMethods')]
    #[TestDox('a method this revision removed is answered as unknown')]
    public function testRemovedMethodsAreUnknown(string $method, array $params): void
    {
        $answer = self::call(self::protocol(), $method, $params);

        $this->assertSame(404, $answer['status']);
        $this->assertSame(Error::METHOD_NOT_FOUND, $answer['body']['error']['code']);
    }

    #[TestDox('a known method with malformed params is an invalid request, not an unknown method')]
    public function testMalformedRequestIsNotAnUnknownMethod(): void
    {
        $answer = self::call(self::protocol(), 'tools/list', ['cursor' => [1]]);

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::INVALID_REQUEST, $answer['body']['error']['code']);
    }

    #[TestDox('a request class that crashes while hydrating is answered without leaking the failure')]
    public function testCrashWhileHydratingIsAnswered(): void
    {
        $protocol = new StatelessProtocol(
            [],
            new MessageFactory([ThrowingRequest::class]),
            new Configuration(new Implementation('test-server', '1.0.0'), new ServerCapabilities()),
        );

        $answer = self::call($protocol, 'test/throwing');

        $this->assertSame(404, $answer['status']);
        $this->assertSame(Error::METHOD_NOT_FOUND, $answer['body']['error']['code']);
        $this->assertStringNotContainsString('must not leak', json_encode($answer['body'], \JSON_THROW_ON_ERROR));
    }

    #[TestDox('a handshake-era client opening with "initialize" is told which revisions are served')]
    public function testInitializeNamesTheServedRevisions(): void
    {
        $result = self::protocol()->handle(json_encode([
            'jsonrpc' => '2.0',
            'id' => 1,
            'method' => 'initialize',
            'params' => ['protocolVersion' => '2025-11-25', 'capabilities' => new \stdClass(), 'clientInfo' => ['name' => 'legacy', 'version' => '1.0.0']],
        ], \JSON_THROW_ON_ERROR));

        $answer = json_decode($result->toJson(), true);

        $this->assertSame(400, $result->httpStatus);
        $this->assertSame(Error::UNSUPPORTED_PROTOCOL_VERSION, $answer['error']['code']);
        $this->assertSame(1, $answer['id']);
        $this->assertSame('2025-11-25', $answer['error']['data']['requested']);
        $this->assertSame([ProtocolVersion::V2026_07_28->value], $answer['error']['data']['supported']);
    }

    /**
     * Drains a streaming result into the frames it would write.
     *
     * @return list<array<string, mixed>>
     */
    private static function frames(StatelessResult $result): array
    {
        $frames = [];
        $stream = $result->frames;
        self::assertNotNull($stream);

        foreach ($stream() as $frame) {
            if (null !== $frame) {
                $frames[] = $frame;
            }
        }

        return $frames;
    }

    /**
     * @param array<string, mixed> $meta
     */
    private static function callStreaming(StatelessProtocol $protocol, string $tool, array $meta = []): StatelessResult
    {
        return $protocol->handle(json_encode([
            'jsonrpc' => '2.0',
            'id' => 7,
            'method' => 'tools/call',
            'params' => [
                'name' => $tool,
                'arguments' => new \stdClass(),
                '_meta' => [
                    RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
                    RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
                    ...$meta,
                ],
            ],
        ], \JSON_THROW_ON_ERROR), [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'tools/call',
            'Mcp-Name' => $tool,
            'Accept' => 'application/json, text/event-stream',
        ]);
    }

    #[TestDox('progress notifications reach the client on the response stream')]
    public function testProgressStreamsBeforeTheResponse(): void
    {
        $result = self::callStreaming(self::protocol(), 'progress_tool', ['progressToken' => 'tok-1']);

        $this->assertTrue($result->isStream());

        $frames = self::frames($result);

        $this->assertCount(3, $frames);
        $this->assertSame('notifications/progress', $frames[0]['method']);
        $this->assertSame('tok-1', $frames[0]['params']['progressToken']);
        $this->assertSame('notifications/progress', $frames[1]['method']);
        $this->assertSame(7, $frames[2]['id']);
        $this->assertSame('complete', $frames[2]['result']['resultType']);
    }

    #[TestDox('without a progress token the handler emits nothing and gets a plain response')]
    public function testProgressWithoutATokenIsNotStreamed(): void
    {
        $result = self::callStreaming(self::protocol(), 'progress_tool');

        $this->assertFalse($result->isStream());
        $this->assertSame(200, $result->httpStatus);
    }

    #[TestDox('a client that will not read a stream gets its notifications dropped, not a stream')]
    public function testNotificationsAreDroppedWithoutAnAcceptingClient(): void
    {
        $result = self::protocol()->handle(json_encode([
            'jsonrpc' => '2.0',
            'id' => 7,
            'method' => 'tools/call',
            'params' => [
                'name' => 'progress_tool',
                'arguments' => new \stdClass(),
                '_meta' => [
                    RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
                    RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
                    'progressToken' => 'tok-1',
                ],
            ],
        ], \JSON_THROW_ON_ERROR), [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'tools/call',
            'Mcp-Name' => 'progress_tool',
            'Accept' => 'application/json',
        ]);

        $this->assertFalse($result->isStream());
        $this->assertSame(200, $result->httpStatus);
    }

    #[TestDox('a request naming no log level receives no log notifications')]
    public function testLoggingIsSilentWithoutARequestedLevel(): void
    {
        $result = self::callStreaming(self::protocol(), 'logging_tool');

        $this->assertFalse($result->isStream());
    }

    #[TestDox('a request naming a log level receives the messages at or above it')]
    public function testLoggingHonoursTheRequestedLevel(): void
    {
        $frames = self::frames(self::callStreaming(self::protocol(), 'logging_tool', [RequestMeta::LOG_LEVEL => 'warning']));

        $levels = [];
        foreach ($frames as $frame) {
            if ('notifications/message' === ($frame['method'] ?? null)) {
                $levels[] = $frame['params']['level'];
            }
        }

        // The tool emits debug, info, warning and error.
        $this->assertSame(['warning', 'error'], $levels);
    }

    #[TestDox('a lower requested level lets more through')]
    public function testLoggingAtDebugLetsEverythingThrough(): void
    {
        $frames = self::frames(self::callStreaming(self::protocol(), 'logging_tool', [RequestMeta::LOG_LEVEL => 'debug']));

        $levels = [];
        foreach ($frames as $frame) {
            if ('notifications/message' === ($frame['method'] ?? null)) {
                $levels[] = $frame['params']['level'];
            }
        }

        $this->assertSame(['debug', 'info', 'warning', 'error'], $levels);
    }

    #[TestDox('the client logger honours the requested level instead of its warning default')]
    public function testClientLoggerHonoursTheRequestedLevel(): void
    {
        $frames = self::frames(self::callStreaming(self::protocol(), 'client_logger_tool', [RequestMeta::LOG_LEVEL => 'info']));

        $levels = [];
        foreach ($frames as $frame) {
            if ('notifications/message' === ($frame['method'] ?? null)) {
                $levels[] = $frame['params']['level'];
            }
        }

        $this->assertSame(['info', 'warning'], $levels);
    }

    #[TestDox('an error raised before any notification keeps its own status')]
    public function testEarlyFailureIsStillAStatusCode(): void
    {
        $result = self::callStreaming(self::protocol(), 'capability_tool');

        $this->assertFalse($result->isStream());
        $this->assertSame(400, $result->httpStatus);

        $body = json_decode($result->toJson(), true, flags: \JSON_THROW_ON_ERROR);
        $this->assertSame(Error::MISSING_REQUIRED_CLIENT_CAPABILITY, $body['error']['code']);
    }

    #[TestDox('a server-initiated request this revision removed is refused')]
    public function testServerInitiatedRequestIsRefused(): void
    {
        $result = self::callStreaming(self::protocol(), 'asks_for_roots');

        $body = json_decode($result->toJson(), true, flags: \JSON_THROW_ON_ERROR);

        $this->assertSame(500, $result->httpStatus);
        $this->assertStringContainsString('no server-initiated requests', $body['error']['message']);
        $this->assertStringContainsString('"roots/list"', $body['error']['message']);
        $this->assertStringContainsString('InputRequiredResult', $body['error']['message']);
    }

    #[TestDox('a gateway elicitation becomes the ask this revision carries in the result')]
    public function testGatewayElicitationBecomesAnAsk(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'elicits_directly', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'elicits_directly'],
            ['elicitation' => new \stdClass()],
        );

        $this->assertSame(200, $answer['status']);
        $this->assertSame('input_required', $answer['body']['result']['resultType']);
        // Unnamed, so filed under its position among the handler's asks.
        $this->assertSame('elicitation/create', $answer['body']['result']['inputRequests']['elicitation_1']['method']);
        // Nothing is answered yet, so there is nothing to carry.
        $this->assertArrayNotHasKey('requestState', $answer['body']['result']);
    }

    #[TestDox('the retry resumes the gateway call the ask came from')]
    public function testGatewayElicitationResumesOnRetry(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            [
                'name' => 'elicits_directly',
                'arguments' => new \stdClass(),
                'inputResponses' => ['elicitation_1' => ['action' => 'accept', 'content' => ['n' => 'ada']]],
            ],
            ['Mcp-Name' => 'elicits_directly'],
            ['elicitation' => new \stdClass()],
        );

        $this->assertSame(200, $answer['status']);
        $this->assertSame('hello ada', $answer['body']['result']['content'][0]['text']);
    }

    #[TestDox('a gateway ask that follows a notification ends the stream it opened')]
    public function testGatewayElicitationEndsAnOpenStream(): void
    {
        $result = self::callStreaming(self::protocol(), 'elicits_after_progress', [
            'progressToken' => 'p1',
            RequestMeta::CLIENT_CAPABILITIES => ['elicitation' => new \stdClass()],
        ]);

        $this->assertTrue($result->isStream());

        $frames = self::frames($result);
        $this->assertSame('notifications/progress', $frames[0]['method']);
        $this->assertSame('input_required', $frames[1]['result']['resultType']);
    }

    #[TestDox('an ask the client did not declare it can answer is refused before it is minted')]
    public function testUndeclaredGatewayElicitationIsRefused(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'elicits_directly', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'elicits_directly'],
        );

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::MISSING_REQUIRED_CLIENT_CAPABILITY, $answer['body']['error']['code']);
    }

    /**
     * A handler asking twice: the second round has to remember the first
     * round's answer, which is what the `requestState` is for.
     *
     * @param string|list<string>|null $key the signing key or key ring, a fixed test key by default
     */
    private static function twoAskProtocol(bool $signed = true, ?RequestStateBinderInterface $binder = null, string|array|null $key = null, ?EventDispatcherInterface $eventDispatcher = null): StatelessProtocol
    {
        $builder = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->addTool(
                static function (RequestContext $context): string {
                    $gateway = $context->getClientGateway();
                    $schema = new ElicitationSchema(['v' => new StringSchemaDefinition('V')], ['v']);

                    $when = $gateway->elicit('When?', $schema, key: 'when')->content['v'] ?? null;
                    $seat = $gateway->elicit('Seat?', $schema, key: 'seat')->content['v'] ?? null;

                    // Fail here rather than answering '/' and failing downstream.
                    if (!\is_string($when) || !\is_string($seat)) {
                        throw new \RuntimeException('An elicitation answer arrived without its value.');
                    }

                    return $when.'/'.$seat;
                },
                name: 'books_flight',
                description: 'Asks twice before it answers',
            );

        if ($signed) {
            $builder->setRequestState($key ?? str_repeat('k', 32), binder: $binder);
        }

        if (null !== $eventDispatcher) {
            $builder->setEventDispatcher($eventDispatcher);
        }

        return $builder->buildStateless([ProtocolVersion::V2026_07_28]);
    }

    /**
     * @param array<string, mixed> $params
     *
     * @return array<string, mixed>
     */
    private static function book(StatelessProtocol $protocol, array $params = []): array
    {
        return self::call(
            $protocol,
            'tools/call',
            ['name' => 'books_flight', 'arguments' => new \stdClass(), ...$params],
            ['Mcp-Name' => 'books_flight'],
            ['elicitation' => new \stdClass()],
        );
    }

    #[TestDox('a handler asking twice is served one ask per round, remembering the first')]
    public function testNamedAsksCarryAcrossRounds(): void
    {
        $protocol = self::twoAskProtocol();

        $first = self::book($protocol);
        $this->assertSame('input_required', $first['body']['result']['resultType']);
        $this->assertSame(['when'], array_keys($first['body']['result']['inputRequests']));
        // Nothing answered yet, so nothing to carry.
        $this->assertArrayNotHasKey('requestState', $first['body']['result']);

        $second = self::book($protocol, [
            'inputResponses' => ['when' => ['action' => 'accept', 'content' => ['v' => 'morning']]],
        ]);
        $this->assertSame('input_required', $second['body']['result']['resultType']);
        $this->assertSame(['seat'], array_keys($second['body']['result']['inputRequests']));
        $this->assertIsString($second['body']['result']['requestState']);

        // The client echoes the state and answers only what it was just asked.
        $third = self::book($protocol, [
            'inputResponses' => ['seat' => ['action' => 'accept', 'content' => ['v' => 'aisle']]],
            'requestState' => $second['body']['result']['requestState'],
        ]);
        $this->assertSame(200, $third['status']);
        $this->assertSame('morning/aisle', $third['body']['result']['content'][0]['text']);
    }

    /**
     * A {@see self::book()} that can carry other arguments and an access token.
     *
     * @param array<string, mixed> $params
     * @param array<string, mixed> $arguments
     *
     * @return array<string, mixed>
     */
    private static function bookAs(StatelessProtocol $protocol, ?AccessToken $token, array $params = [], array $arguments = []): array
    {
        $result = $protocol->handle(json_encode([
            'jsonrpc' => '2.0',
            'id' => 1,
            'method' => 'tools/call',
            'params' => [
                'name' => 'books_flight',
                'arguments' => (object) $arguments,
                '_meta' => [
                    RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
                    RequestMeta::CLIENT_CAPABILITIES => ['elicitation' => new \stdClass()],
                ],
                ...$params,
            ],
        ], \JSON_THROW_ON_ERROR), [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'tools/call',
            'Mcp-Name' => 'books_flight',
        ], $token);

        return [
            'status' => $result->httpStatus,
            'body' => json_decode($result->toJson(), true, flags: \JSON_THROW_ON_ERROR),
        ];
    }

    private static function alice(string $subject = 'alice'): AccessToken
    {
        return new AccessToken(['flights'], ['iss' => 'https://auth.example.com', 'client_id' => 'app', 'sub' => $subject]);
    }

    /**
     * The second round of a {@see self::twoAskProtocol()} call, which mints
     * the state carrying the first answer.
     */
    private function mintedState(StatelessProtocol $protocol, ?AccessToken $token, array $arguments = []): string
    {
        $round = self::bookAs($protocol, $token, [
            'inputResponses' => ['when' => ['action' => 'accept', 'content' => ['v' => 'morning']]],
        ], $arguments);

        $this->assertIsString($round['body']['result']['requestState'] ?? null);

        return $round['body']['result']['requestState'];
    }

    #[TestDox('a bound state verifies on a retry of the same call by the same principal')]
    public function testBoundStateVerifiesOnTheSameCall(): void
    {
        $protocol = self::twoAskProtocol(binder: new OriginatingRequestBinder());
        $state = $this->mintedState($protocol, self::alice(), ['to' => 'BER']);

        $answer = self::bookAs($protocol, self::alice(), [
            'inputResponses' => ['seat' => ['action' => 'accept', 'content' => ['v' => 'aisle']]],
            'requestState' => $state,
        ], ['to' => 'BER']);

        $this->assertSame(200, $answer['status']);
        $this->assertSame('morning/aisle', $answer['body']['result']['content'][0]['text']);
    }

    /**
     * @return iterable<string, array{array<string, mixed>, ?AccessToken}>
     */
    public static function otherCalls(): iterable
    {
        yield 'other arguments' => [['to' => 'CDG'], self::alice()];
        yield 'other principal' => [['to' => 'BER'], self::alice('mallory')];
        yield 'no principal' => [['to' => 'BER'], null];
    }

    /**
     * @param array<string, mixed> $arguments
     */
    #[DataProvider('otherCalls')]
    #[TestDox('a bound state echoed on another call is refused like a forged one: $_dataName')]
    public function testBoundStateRefusedOnAnotherCall(array $arguments, ?AccessToken $token): void
    {
        $protocol = self::twoAskProtocol(binder: new OriginatingRequestBinder());
        $state = $this->mintedState($protocol, self::alice(), ['to' => 'BER']);

        $answer = self::bookAs($protocol, $token, [
            'inputResponses' => ['seat' => ['action' => 'accept', 'content' => ['v' => 'aisle']]],
            'requestState' => $state,
        ], $arguments);

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::INVALID_PARAMS, $answer['body']['error']['code']);
        $this->assertSame('The supplied requestState failed verification.', $answer['body']['error']['message']);
    }

    #[TestDox('the binder sees the request as sent and its access token')]
    public function testBinderSeesTheRequestAndToken(): void
    {
        $binder = new class implements RequestStateBinderInterface {
            /** @var list<array{string, array<string, mixed>, ?string}> */
            public array $calls = [];

            public function bind(Request $request, ?AccessToken $accessToken): string
            {
                \assert($request instanceof CallToolRequest);
                $this->calls[] = [$request->name, $request->arguments, $accessToken?->getSubject()];

                return 'fixed';
            }
        };

        $this->mintedState(self::twoAskProtocol(binder: $binder), self::alice(), ['to' => 'BER']);

        $this->assertSame([['books_flight', ['to' => 'BER'], 'alice']], $binder->calls);
    }

    #[TestDox('a state binds to the request as sent, whatever a RequestEvent listener turns it into')]
    public function testBindingIgnoresARequestEventListener(): void
    {
        $events = [];
        $listener = static function (object $event): void {
            if ($event instanceof RequestEvent && $event->getRequest() instanceof CallToolRequest) {
                $request = $event->getRequest();
                $event->setRequest((new CallToolRequest('books_flight', ['to' => 'rewritten']))->withId($request->getId())->withMeta($request->getMeta()));
            }
        };

        $protocol = self::twoAskProtocol(binder: new OriginatingRequestBinder(), eventDispatcher: $this->eventDispatcher($events, $listener));
        $state = $this->mintedState($protocol, self::alice(), ['to' => 'BER']);
        $input = [
            'inputResponses' => ['seat' => ['action' => 'accept', 'content' => ['v' => 'aisle']]],
            'requestState' => $state,
        ];

        $this->assertSame(400, self::bookAs($protocol, self::alice(), $input, ['to' => 'CDG'])['status']);
        $this->assertSame('morning/aisle', self::bookAs($protocol, self::alice(), $input, ['to' => 'BER'])['body']['result']['content'][0]['text']);
    }

    #[TestDox('a binder that throws fails the request with an internal error instead of escaping to the transport')]
    public function testThrowingBinderFailsTheRequest(): void
    {
        $binder = new class implements RequestStateBinderInterface {
            public function bind(Request $request, ?AccessToken $accessToken): string
            {
                throw new \RuntimeException('No principal claim on the token.');
            }
        };

        $answer = self::bookAs(self::twoAskProtocol(binder: $binder), self::alice(), arguments: ['to' => 'BER']);

        $this->assertSame(500, $answer['status']);
        $this->assertSame(Error::INTERNAL_ERROR, $answer['body']['error']['code']);
        $this->assertStringNotContainsString('principal', $answer['body']['error']['message']);
    }

    #[TestDox('a state minted before a binder was configured is refused once one is')]
    public function testUnboundStateRefusedByABindingServer(): void
    {
        $state = $this->mintedState(self::twoAskProtocol(), self::alice());

        $answer = self::bookAs(self::twoAskProtocol(binder: new OriginatingRequestBinder()), self::alice(), [
            'inputResponses' => ['seat' => ['action' => 'accept', 'content' => ['v' => 'aisle']]],
            'requestState' => $state,
        ]);

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::INVALID_PARAMS, $answer['body']['error']['code']);
    }

    #[TestDox('without a binder, a state verifies on any call, as before')]
    public function testUnboundStateIsNotTiedToTheCall(): void
    {
        $protocol = self::twoAskProtocol();
        $state = $this->mintedState($protocol, self::alice(), ['to' => 'BER']);

        $answer = self::bookAs($protocol, self::alice('mallory'), [
            'inputResponses' => ['seat' => ['action' => 'accept', 'content' => ['v' => 'aisle']]],
            'requestState' => $state,
        ], ['to' => 'CDG']);

        $this->assertSame(200, $answer['status']);
        $this->assertSame('morning/aisle', $answer['body']['result']['content'][0]['text']);
    }

    #[TestDox('a server rotating its key still serves the retry of a call the old key signed')]
    public function testRetryServedAcrossAKeyRotation(): void
    {
        $oldKey = str_repeat('o', 32);
        $newKey = str_repeat('n', 32);

        $second = self::book(self::twoAskProtocol(key: $oldKey), [
            'inputResponses' => ['when' => ['action' => 'accept', 'content' => ['v' => 'morning']]],
        ]);
        $retry = [
            'inputResponses' => ['seat' => ['action' => 'accept', 'content' => ['v' => 'aisle']]],
            'requestState' => $second['body']['result']['requestState'],
        ];

        $rotated = self::book(self::twoAskProtocol(key: [$newKey, $oldKey]), $retry);
        $this->assertSame(200, $rotated['status']);
        $this->assertSame('morning/aisle', $rotated['body']['result']['content'][0]['text']);

        $retired = self::book(self::twoAskProtocol(key: [$newKey]), $retry);
        $this->assertSame(400, $retired['status']);
        $this->assertSame('The supplied requestState failed verification.', $retired['body']['error']['message']);
    }

    #[TestDox('carrying an answer to the next round without a signing key fails loudly')]
    public function testCarryingAnAnswerNeedsASigningKey(): void
    {
        $answer = self::book(self::twoAskProtocol(signed: false), [
            'inputResponses' => ['when' => ['action' => 'accept', 'content' => ['v' => 'morning']]],
        ]);

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::INTERNAL_ERROR, $answer['body']['error']['code']);
    }

    #[TestDox('an answer that does not parse is asked for again')]
    public function testMalformedAnswerIsAskedAgain(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            [
                'name' => 'elicits_directly',
                'arguments' => new \stdClass(),
                // Accepted, but a form-mode acceptance carries content.
                'inputResponses' => ['elicitation_1' => ['action' => 'accept']],
            ],
            ['Mcp-Name' => 'elicits_directly'],
            ['elicitation' => new \stdClass()],
        );

        $this->assertSame(200, $answer['status']);
        $this->assertSame('input_required', $answer['body']['result']['resultType']);
        $this->assertArrayHasKey('elicitation_1', $answer['body']['result']['inputRequests']);
    }

    #[TestDox('a request\'s trace context reaches the handler')]
    public function testTraceContextReachesTheHandler(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            [
                'name' => 'probe_trace',
                'arguments' => new \stdClass(),
                '_meta' => [
                    RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
                    RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
                    'traceparent' => '00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01',
                    'baggage' => 'tenant=acme',
                ],
            ],
            ['Mcp-Name' => 'probe_trace'],
        );

        $this->assertSame(
            'traceparent=00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01;baggage=tenant=acme',
            $answer['body']['result']['content'][0]['text'],
        );
    }

    #[TestDox('a native traceparent/tracestate header reaches the handler when `_meta` carries none')]
    public function testHttpTraceHeadersReachTheHandler(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'probe_trace', 'arguments' => new \stdClass()],
            [
                'Mcp-Name' => 'probe_trace',
                'traceparent' => '00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01',
                'tracestate' => 'acme=1',
            ],
        );

        $this->assertSame(
            'traceparent=00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01;tracestate=acme=1',
            $answer['body']['result']['content'][0]['text'],
        );
    }

    #[TestDox('`_meta` trace context wins over a conflicting native header')]
    public function testMetaTraceContextWinsOverHeader(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            [
                'name' => 'probe_trace',
                'arguments' => new \stdClass(),
                '_meta' => [
                    RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
                    RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
                    'traceparent' => '00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01',
                ],
            ],
            [
                'Mcp-Name' => 'probe_trace',
                'traceparent' => '00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01',
            ],
        );

        $this->assertSame(
            'traceparent=00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01',
            $answer['body']['result']['content'][0]['text'],
        );
    }

    #[TestDox('notifications caused by a traced request carry its trace context')]
    public function testNotificationsCarryTheTraceContext(): void
    {
        $result = self::callStreaming(self::protocol(), 'progress_tool', [
            'progressToken' => 'tok-1',
            'traceparent' => '00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01',
        ]);

        $frames = self::frames($result);

        $this->assertSame(
            '00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01',
            $frames[0]['params']['_meta']['traceparent'],
        );
    }

    #[TestDox('an untraced request adds no trace metadata')]
    public function testUntracedRequestAddsNothing(): void
    {
        $frames = self::frames(self::callStreaming(self::protocol(), 'progress_tool', ['progressToken' => 'tok-1']));

        $this->assertArrayNotHasKey('traceparent', $frames[0]['params']['_meta'] ?? []);
    }

    #[TestDox('a missing resource answers -32602 with the uri, not the retired -32002')]
    public function testResourceNotFoundUsesInvalidParams(): void
    {
        $answer = self::call(
            self::protocol(),
            'resources/read',
            ['uri' => 'test://absent'],
            ['Mcp-Name' => 'test://absent'],
        );

        $this->assertSame(Error::INVALID_PARAMS, $answer['body']['error']['code']);
        $this->assertSame('test://absent', $answer['body']['error']['data']['uri']);
    }

    #[TestDox('an unknown tool is a bad parameter, not an unknown method')]
    public function testUnknownToolUsesInvalidParams(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'no_such_tool', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'no_such_tool'],
        );

        $this->assertSame(Error::INVALID_PARAMS, $answer['body']['error']['code']);
    }

    #[TestDox('an unknown prompt is a bad parameter too')]
    public function testUnknownPromptUsesInvalidParams(): void
    {
        $answer = self::call(
            self::protocol(),
            'prompts/get',
            ['name' => 'no_such_prompt', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'no_such_prompt'],
        );

        $this->assertSame(Error::INVALID_PARAMS, $answer['body']['error']['code']);
    }

    #[TestDox('this revision never emits the codes it reserved')]
    public function testReservedCodesAreNeverEmitted(): void
    {
        $protocol = self::protocol();

        $answers = [
            self::call($protocol, 'resources/read', ['uri' => 'test://absent'], ['Mcp-Name' => 'test://absent']),
            self::call($protocol, 'tools/call', ['name' => 'nope', 'arguments' => new \stdClass()], ['Mcp-Name' => 'nope']),
            self::call($protocol, 'prompts/get', ['name' => 'nope', 'arguments' => new \stdClass()], ['Mcp-Name' => 'nope']),
        ];

        foreach ($answers as $answer) {
            // -32002 (resource not found) and -32042 (url elicitation required)
            // are reserved by earlier revisions and never reused.
            $this->assertNotContains($answer['body']['error']['code'], [-32002, -32042]);
        }
    }

    #[TestDox('resources/read can ask for input before it answers')]
    public function testResourceReadCanAskForInput(): void
    {
        $answer = self::call(
            self::protocol(),
            'resources/read',
            ['uri' => 'test://gated'],
            ['Mcp-Name' => 'test://gated'],
            ['elicitation' => new \stdClass()],
        );

        $this->assertSame(200, $answer['status']);
        $this->assertSame('input_required', $answer['body']['result']['resultType']);
        $this->assertArrayHasKey('who', $answer['body']['result']['inputRequests']);

        // Interim results are not cacheable and carry no hints.
        $this->assertArrayNotHasKey('ttlMs', $answer['body']['result']);
        $this->assertArrayNotHasKey('cacheScope', $answer['body']['result']);
    }

    #[TestDox('an ask the client cannot answer is refused with -32021, not sent')]
    public function testUndeclaredInputRequestIsRefused(): void
    {
        // The client declared nothing, so it has no way to answer an
        // elicitation — and a retry carrying one could never arrive.
        $answer = self::call(
            self::protocol(),
            'resources/read',
            ['uri' => 'test://gated'],
            ['Mcp-Name' => 'test://gated'],
        );

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::MISSING_REQUIRED_CLIENT_CAPABILITY, $answer['body']['error']['code']);
        $this->assertArrayHasKey('elicitation', $answer['body']['error']['data']['requiredCapabilities']);
    }

    #[TestDox('url-mode elicitation needs its own declaration, which form does not satisfy')]
    public function testUrlElicitationNeedsItsOwnDeclaration(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'asks_by_url', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'asks_by_url'],
            ['elicitation' => new \stdClass()],
        );

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::MISSING_REQUIRED_CLIENT_CAPABILITY, $answer['body']['error']['code']);
        $this->assertArrayHasKey('url', $answer['body']['error']['data']['requiredCapabilities']['elicitation']);
    }

    #[TestDox('a client declaring url mode gets the ask')]
    public function testUrlElicitationPassesWhenDeclared(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'asks_by_url', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'asks_by_url'],
            ['elicitation' => ['url' => new \stdClass()]],
        );

        $this->assertSame(200, $answer['status']);
        $this->assertSame('input_required', $answer['body']['result']['resultType']);
    }

    #[TestDox('an ask the client cannot answer is refused with -32021 even mid-stream')]
    public function testUndeclaredInputRequestIsRefusedWhenStreamed(): void
    {
        // The handler emits progress before its InputRequiredResult, so the
        // answer goes out on the response stream, not a plain 400 — the gate
        // still has to apply there.
        $result = self::callStreaming(self::protocol(), 'asks_by_url_after_progress', ['progressToken' => 'tok-1']);

        $this->assertTrue($result->isStream());

        $frames = self::frames($result);
        $this->assertNotEmpty($frames);
        $last = json_decode(json_encode($frames[array_key_last($frames)], \JSON_THROW_ON_ERROR), true, flags: \JSON_THROW_ON_ERROR);

        $this->assertSame(Error::MISSING_REQUIRED_CLIENT_CAPABILITY, $last['error']['code']);
        $this->assertArrayHasKey('url', $last['error']['data']['requiredCapabilities']['elicitation']);
    }

    #[TestDox('a resource can set its own freshness, overriding the policy')]
    public function testResourceAuthoredCacheHintsWin(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setCachePolicy(CachePolicy::default(60_000, CacheScope::Public))
            ->addResource(
                static fn (): ReadResourceResult => new ReadResourceResult(
                    [new TextResourceContents('test://volatile', 'text/plain', 'now')],
                    ttlMs: 250,
                    cacheScope: CacheScope::Private,
                ),
                'test://volatile',
                'volatile',
                'A resource that decides its own freshness',
            )
            ->addResource(static fn (): string => 'body', 'test://plain', 'plain', 'A resource that defers to policy')
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $volatile = self::call($protocol, 'resources/read', ['uri' => 'test://volatile'], ['Mcp-Name' => 'test://volatile']);
        $this->assertSame(250, $volatile['body']['result']['ttlMs']);
        $this->assertSame('private', $volatile['body']['result']['cacheScope']);

        $plain = self::call($protocol, 'resources/read', ['uri' => 'test://plain'], ['Mcp-Name' => 'test://plain']);
        $this->assertSame(60_000, $plain['body']['result']['ttlMs']);
        $this->assertSame('public', $plain['body']['result']['cacheScope']);
    }

    #[TestDox('a first-round read carries caching hints')]
    public function testFirstRoundReadIsCacheable(): void
    {
        $answer = self::call(
            self::protocol(),
            'resources/read',
            ['uri' => 'test://static'],
            ['Mcp-Name' => 'test://static'],
        );

        $this->assertArrayHasKey('ttlMs', $answer['body']['result']);
        $this->assertArrayHasKey('cacheScope', $answer['body']['result']);
    }

    #[TestDox('a result produced by a multi round-trip retry carries hints that forbid caching it')]
    public function testMrtrRetryResultIsNotCacheable(): void
    {
        $answer = self::call(
            self::protocol(),
            'resources/read',
            [
                'uri' => 'test://gated',
                'inputResponses' => ['who' => ['action' => 'accept', 'content' => ['n' => 'ada']]],
            ],
            ['Mcp-Name' => 'test://gated'],
            ['elicitation' => new \stdClass()],
        );

        $this->assertSame('complete', $answer['body']['result']['resultType']);
        $this->assertSame(0, $answer['body']['result']['ttlMs']);
        $this->assertSame('private', $answer['body']['result']['cacheScope']);
    }

    #[TestDox('a listen stream acknowledges, then carries what the client asked for')]
    public function testListenStreamDeliversSubscribedNotifications(): void
    {
        $bus = new InMemoryNotificationBus();

        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setCapabilities(new ServerCapabilities(toolsListChanged: true, resourcesListChanged: true, resourcesSubscribe: true))
            ->setNotificationBus($bus)
            ->setSubscriptionLifetime(0.8)
            ->addTool(static fn (): string => 'ok', name: 'a_tool', description: 'x')
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $result = $protocol->handle(json_encode([
            'jsonrpc' => '2.0',
            'id' => 42,
            'method' => 'subscriptions/listen',
            'params' => [
                'notifications' => ['toolsListChanged' => true, 'resourceSubscriptions' => ['file:///watched']],
                '_meta' => [
                    RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
                    RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
                ],
            ],
        ], \JSON_THROW_ON_ERROR), [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'subscriptions/listen',
        ]);

        $this->assertTrue($result->isStream());

        $frames = [];
        $published = false;
        $stream = $result->frames;
        $this->assertNotNull($stream);

        foreach ($stream() as $frame) {
            if (null === $frame) {
                // Publish once the stream is established, so the notifications
                // arrive the way a concurrent request would deliver them.
                if (!$published) {
                    $bus->publish(new ToolListChangedNotification());
                    $bus->publish(new PromptListChangedNotification());
                    $bus->publish(new ResourceUpdatedNotification('file:///watched'));
                    $bus->publish(new ResourceUpdatedNotification('file:///ignored'));
                    $published = true;
                }

                continue;
            }

            $frames[] = $frame;
        }

        $methods = array_map(static fn (array $frame): string => $frame['method'] ?? 'response', $frames);

        // The acknowledgment MUST come first, the declined types must not come
        // at all, and the graceful closure ends it.
        $this->assertSame([
            'notifications/subscriptions/acknowledged',
            'notifications/tools/list_changed',
            'notifications/resources/updated',
            'response',
        ], $methods);

        $this->assertSame(['toolsListChanged' => true, 'resourceSubscriptions' => ['file:///watched']], (array) $frames[0]['params']['notifications']);
        $this->assertSame('file:///watched', $frames[2]['params']['uri']);

        // Every message on the stream names the subscription it belongs to.
        foreach ([$frames[0], $frames[1], $frames[2]] as $frame) {
            $this->assertSame(42, $frame['params']['_meta'][RequestMeta::SUBSCRIPTION_ID]);
        }

        $this->assertSame(42, $frames[3]['id']);
        $this->assertSame(42, $frames[3]['result']['_meta'][RequestMeta::SUBSCRIPTION_ID]);
        $this->assertSame('complete', $frames[3]['result']['resultType']);
    }

    /**
     * A request the way stdio carries it: the metadata inline, no headers.
     *
     * @param array<string, mixed> $params
     */
    private static function inlineRequest(string $method, array $params = []): string
    {
        $params['_meta'] = [
            RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
            RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
            ...($params['_meta'] ?? []),
        ];

        return json_encode(['jsonrpc' => '2.0', 'id' => 9, 'method' => $method, 'params' => $params], \JSON_THROW_ON_ERROR);
    }

    #[TestDox('a message off a transport without headers is answered without them')]
    public function testInlineMessageNeedsNoHeaders(): void
    {
        $protocol = self::protocol();
        $message = self::inlineRequest('tools/call', ['name' => 'plain_tool', 'arguments' => new \stdClass()]);

        // The same message over HTTP is missing headers it has to carry.
        $this->assertSame(Error::HEADER_MISMATCH, json_decode($protocol->handle($message)->toJson(), true)['error']['code']);

        $result = $protocol->handleInline($message);

        $this->assertSame(200, $result->httpStatus);
        $this->assertSame('ok', json_decode($result->toJson(), true)['result']['content'][0]['text']);
    }

    #[TestDox('an inline request streams its progress without being asked to')]
    public function testInlineProgressIsStreamed(): void
    {
        $result = self::protocol()->handleInline(self::inlineRequest('tools/call', [
            'name' => 'progress_tool',
            'arguments' => new \stdClass(),
            '_meta' => ['progressToken' => 'tok-1'],
        ]));

        $this->assertTrue($result->isStream());

        $frames = self::frames($result);

        $this->assertSame(['notifications/progress', 'notifications/progress'], [$frames[0]['method'], $frames[1]['method']]);
        $this->assertSame(9, $frames[2]['id']);
    }

    #[TestDox('an inline listen stream leaves the pacing to its consumer')]
    public function testInlineListenIsNotPaced(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setCapabilities(new ServerCapabilities(toolsListChanged: true))
            ->setNotificationBus(new InMemoryNotificationBus())
            ->setSubscriptionLifetime(60)
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $result = $protocol->handleInline(self::inlineRequest('subscriptions/listen', ['notifications' => ['toolsListChanged' => true]]));

        $this->assertTrue($result->isStream());

        $stream = $result->frames;
        $this->assertNotNull($stream);

        $frames = $stream();
        $started = microtime(true);

        $this->assertSame('notifications/subscriptions/acknowledged', $frames->current()['method']);

        // A paced stream sleeps between polls, stalling the shared stdio channel.
        for ($i = 0; $i < 5; ++$i) {
            $frames->next();
            $this->assertNull($frames->current());
        }

        $this->assertLessThan(0.2, microtime(true) - $started);
    }

    #[TestDox('an inline listen stream outlives the subscription lifetime, since its consumer ends it')]
    public function testInlineListenIsNotBoundedByTheLifetime(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setCapabilities(new ServerCapabilities(toolsListChanged: true))
            ->setNotificationBus(new InMemoryNotificationBus())
            ->setSubscriptionLifetime(0.01)
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $result = $protocol->handleInline(self::inlineRequest('subscriptions/listen', ['notifications' => ['toolsListChanged' => true]]));

        $stream = $result->frames;
        $this->assertNotNull($stream);

        $frames = $stream();
        $frames->current();
        usleep(20_000);

        for ($i = 0; $i < 3; ++$i) {
            $frames->next();
            $this->assertTrue($frames->valid());
            $this->assertNull($frames->current());
        }
    }

    #[TestDox('the acknowledgment drops types the server cannot honour')]
    public function testAcknowledgmentReflectsWhatTheServerCanDo(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setCapabilities(new ServerCapabilities(toolsListChanged: true, promptsListChanged: false))
            ->setNotificationBus(new InMemoryNotificationBus())
            ->setSubscriptionLifetime(0.05)
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $result = $protocol->handle(json_encode([
            'jsonrpc' => '2.0',
            'id' => 1,
            'method' => 'subscriptions/listen',
            'params' => [
                'notifications' => ['toolsListChanged' => true, 'promptsListChanged' => true],
                '_meta' => [
                    RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
                    RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
                ],
            ],
        ], \JSON_THROW_ON_ERROR), [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'subscriptions/listen',
        ]);

        $first = null;
        $stream = $result->frames;
        $this->assertNotNull($stream);

        foreach ($stream() as $frame) {
            if (null !== $frame) {
                $first = $frame;
                break;
            }
        }

        $this->assertSame(['toolsListChanged' => true], (array) $first['params']['notifications']);
    }

    /**
     * @return iterable<string, array{ServerCapabilities, array<string, mixed>}>
     */
    public static function listensThatCarryNothing(): iterable
    {
        yield 'requested type not announced' => [new ServerCapabilities(toolsListChanged: false), ['notifications' => ['toolsListChanged' => true]]];
        yield 'resource updates without resource subscribe' => [new ServerCapabilities(resourcesSubscribe: false), ['notifications' => ['resourceSubscriptions' => ['file:///watched']]]];
        yield 'nothing requested' => [new ServerCapabilities(toolsListChanged: true), ['notifications' => []]];
        yield 'no notifications member' => [new ServerCapabilities(toolsListChanged: true), []];
    }

    /**
     * @param array<string, mixed> $params
     */
    #[DataProvider('listensThatCarryNothing')]
    #[TestDox('a listen stream that can carry nothing ends right after the acknowledgment')]
    public function testListenWithAnEmptyAgreedFilterEndsAtOnce(ServerCapabilities $capabilities, array $params): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setCapabilities($capabilities)
            ->setSubscriptionLifetime(60)
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $params['_meta'] = [
            RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
            RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
        ];

        $result = $protocol->handle(json_encode([
            'jsonrpc' => '2.0',
            'id' => 7,
            'method' => 'subscriptions/listen',
            'params' => $params,
        ], \JSON_THROW_ON_ERROR), [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'subscriptions/listen',
        ]);

        $this->assertTrue($result->isStream());

        $stream = $result->frames;
        $this->assertNotNull($stream);

        $started = microtime(true);
        $frames = iterator_to_array($stream(), false);

        // No poll tick, so the 60 second lifetime is not waited out.
        $this->assertCount(2, $frames);
        $this->assertLessThan(0.2, microtime(true) - $started);

        $this->assertSame('notifications/subscriptions/acknowledged', $frames[0]['method']);
        $this->assertEquals(new \stdClass(), $frames[0]['params']['notifications']);
        $this->assertSame(7, $frames[0]['params']['_meta'][RequestMeta::SUBSCRIPTION_ID]);

        $this->assertSame(7, $frames[1]['id']);
        $this->assertSame('complete', $frames[1]['result']['resultType']);
        $this->assertSame(7, $frames[1]['result']['_meta'][RequestMeta::SUBSCRIPTION_ID]);
    }

    #[TestDox('an inline listen stream that can carry nothing ends too, instead of waiting for its consumer')]
    public function testInlineListenWithAnEmptyAgreedFilterEndsAtOnce(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setCapabilities(new ServerCapabilities(toolsListChanged: false))
            ->setNotificationBus(new InMemoryNotificationBus())
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $result = $protocol->handleInline(self::inlineRequest('subscriptions/listen', ['notifications' => ['toolsListChanged' => true]]));

        $stream = $result->frames;
        $this->assertNotNull($stream);

        $frames = iterator_to_array($stream(), false);

        $this->assertCount(2, $frames);
        $this->assertSame('notifications/subscriptions/acknowledged', $frames[0]['method']);
        $this->assertSame(9, $frames[1]['id']);
        $this->assertSame('complete', $frames[1]['result']['resultType']);
    }

    #[TestDox('an extension method is served by the extension that claims it')]
    public function testExtensionMethodIsServed(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->enableExtension(new ThingExtension())
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $answer = self::callWithHeaders($protocol, 'com.example/things.list', [], [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'com.example/things.list',
        ]);

        $this->assertSame(200, $answer['status']);
        $this->assertSame(['a', 'b'], $answer['body']['result']['things']);
    }

    #[TestDox('the extension is advertised under capabilities.extensions')]
    public function testExtensionIsAdvertised(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->enableExtension(new ThingExtension())
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $answer = self::call($protocol, 'server/discover');

        $this->assertSame(['flavour' => 'vanilla'], (array) $answer['body']['result']['capabilities']['extensions']['com.example/things']);
    }

    #[TestDox('listChanged is announced on server/discover when a notification bus delivers it')]
    public function testListChangedIsAdvertisedWithANotificationBus(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setNotificationBus(new InMemoryNotificationBus())
            ->addTool(static fn (): string => 'ok', 'alpha')
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $capabilities = self::call($protocol, 'server/discover')['body']['result']['capabilities'];

        $this->assertTrue($capabilities['tools']['listChanged']);
    }

    #[TestDox('a method of an extension this server has never heard of stays generic')]
    public function testUnknownExtensionMethodStaysGeneric(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $answer = self::callWithHeaders($protocol, 'com.example/things.list', [], [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'com.example/things.list',
        ]);

        $this->assertSame(404, $answer['status']);
        $this->assertSame(Error::METHOD_NOT_FOUND, $answer['body']['error']['code']);
        // The extension was never enabled, so it never entered the method map
        // — there is nothing to name it by.
        $this->assertStringContainsString('com.example/things.list', $answer['body']['error']['message']);
        $this->assertStringNotContainsString('extension', $answer['body']['error']['message']);
    }

    #[TestDox('a method of an extension this server does not serve says so by name')]
    public function testUnservedExtensionMethodNamesItsExtension(): void
    {
        $protocol = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->enableExtension(new UnservedThingExtension())
            ->buildStateless([ProtocolVersion::V2026_07_28]);

        $answer = self::callWithHeaders($protocol, 'com.example/things.list', [], [
            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
            'Mcp-Method' => 'com.example/things.list',
        ]);

        $this->assertSame(404, $answer['status']);
        $this->assertSame(Error::METHOD_NOT_FOUND, $answer['body']['error']['code']);
        $this->assertStringContainsString('com.example/unserved-things', $answer['body']['error']['message']);
    }

    #[TestDox('a notification is acknowledged with no body, never answered')]
    public function testNotificationIsAcknowledged(): void
    {
        $result = self::protocol()->handle(
            json_encode(['jsonrpc' => '2.0', 'method' => 'notifications/something', 'params' => []], \JSON_THROW_ON_ERROR),
            ['Mcp-Method' => 'notifications/something'],
        );

        $this->assertTrue($result->isEmpty());
        $this->assertSame(202, $result->httpStatus);
    }

    #[TestDox('a notification for a removed method is refused with no body')]
    public function testRemovedNotificationIsRefused(): void
    {
        $result = self::protocol()->handle(
            json_encode(['jsonrpc' => '2.0', 'method' => 'notifications/initialized'], \JSON_THROW_ON_ERROR),
            ['Mcp-Method' => 'notifications/initialized'],
        );

        $this->assertTrue($result->isEmpty());
        $this->assertSame(400, $result->httpStatus);
    }

    #[TestDox('an error for a request whose id could not be read omits the id')]
    public function testUnreadableIdIsOmittedRatherThanEmptied(): void
    {
        $result = self::protocol()->handle('{"jsonrpc":"2.0","id":{"bad":1},"method":"tools/list"}', []);

        $body = json_decode($result->toJson(), true, flags: \JSON_THROW_ON_ERROR);

        $this->assertArrayNotHasKey('id', $body);
        $this->assertSame(Error::INVALID_REQUEST, $body['error']['code']);
    }

    #[TestDox('an error for a readable id still echoes it')]
    public function testReadableIdIsEchoed(): void
    {
        $answer = self::callWithHeaders(self::protocol(), 'tools/list', [], ['Mcp-Method' => 'tools/list']);

        $this->assertSame(1, $answer['body']['id']);
    }

    #[TestDox('a POST without the MCP-Protocol-Version header is refused')]
    public function testMissingProtocolVersionHeaderIsRefused(): void
    {
        $answer = self::callWithHeaders(
            self::protocol(),
            'tools/list',
            [],
            ['Mcp-Method' => 'tools/list'],
        );

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::HEADER_MISMATCH, $answer['body']['error']['code']);
        $this->assertStringContainsString('MCP-Protocol-Version', $answer['body']['error']['message']);
    }

    #[TestDox('a header contradicting the _meta version outranks an unsupported version')]
    public function testContradictingProtocolVersionHeaderIsRefused(): void
    {
        $answer = self::callWithHeaders(
            self::protocol(),
            'tools/list',
            [],
            ['Mcp-Method' => 'tools/list', 'MCP-Protocol-Version' => '2025-11-25'],
        );

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::HEADER_MISMATCH, $answer['body']['error']['code']);
    }

    #[TestDox('an unsupported version carries the supported set the client can retry from')]
    public function testUnsupportedProtocolVersionCarriesSupportedSet(): void
    {
        $answer = self::callWithHeaders(
            self::protocol(),
            'tools/list',
            [],
            ['Mcp-Method' => 'tools/list', 'MCP-Protocol-Version' => '1900-01-01'],
            '1900-01-01',
        );

        $this->assertSame(400, $answer['status']);
        $this->assertSame(Error::UNSUPPORTED_PROTOCOL_VERSION, $answer['body']['error']['code']);
        $this->assertSame('1900-01-01', $answer['body']['error']['data']['requested']);
        $this->assertSame([ProtocolVersion::V2026_07_28->value], $answer['body']['error']['data']['supported']);
    }

    #[TestDox('elicitation without a named mode reports form, not url')]
    public function testElicitationDefaultsToFormMode(): void
    {
        $answer = self::call(
            self::protocol(),
            'tools/call',
            ['name' => 'probe_capabilities', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'probe_capabilities'],
            ['elicitation' => new \stdClass()],
        );

        $this->assertSame('elicitation', $answer['body']['result']['content'][0]['text']);
    }

    /**
     * @param list<object>                  $events
     * @param (\Closure(object): void)|null $listener
     */
    private function eventDispatcher(array &$events, ?\Closure $listener = null): EventDispatcherInterface
    {
        $eventDispatcher = $this->createStub(EventDispatcherInterface::class);
        $eventDispatcher->method('dispatch')->willReturnCallback(static function (object $event) use (&$events, $listener): object {
            $events[] = $event;

            if (null !== $listener) {
                $listener($event);
            }

            return $event;
        });

        return $eventDispatcher;
    }

    #[TestDox('request and response events are dispatched for a modern-era request')]
    public function testRequestAndResponseEventsAreDispatched(): void
    {
        $events = [];

        $answer = self::call(
            self::protocol(eventDispatcher: $this->eventDispatcher($events)),
            'tools/call',
            ['name' => 'plain_tool', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'plain_tool'],
        );

        $this->assertSame(200, $answer['status']);
        $this->assertCount(2, $events);
        $this->assertInstanceOf(RequestEvent::class, $events[0]);
        $this->assertSame('tools/call', $events[0]->getMethod());
        $this->assertInstanceOf(ResponseEvent::class, $events[1]);
    }

    #[TestDox('a request replaced by a RequestEvent listener is the one handled')]
    public function testRequestEventCanReplaceTheRequest(): void
    {
        $events = [];
        $listener = static function (object $event): void {
            if ($event instanceof RequestEvent) {
                $request = $event->getRequest();
                $event->setRequest((new CallToolRequest('plain_tool', []))->withId($request->getId())->withMeta($request->getMeta()));
            }
        };

        $answer = self::call(
            self::protocol(eventDispatcher: $this->eventDispatcher($events, $listener)),
            'tools/call',
            ['name' => 'probe_trace', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'probe_trace'],
        );

        $this->assertSame('ok', $answer['body']['result']['content'][0]['text']);
    }

    #[TestDox('an error event is dispatched and can replace the error of a modern-era request')]
    public function testErrorEventIsDispatched(): void
    {
        $events = [];
        $listener = static function (object $event): void {
            if ($event instanceof ErrorEvent) {
                $event->setError(Error::forInvalidParams('replaced', $event->getError()->id));
            }
        };

        $answer = self::call(
            self::protocol(eventDispatcher: $this->eventDispatcher($events, $listener)),
            'tools/call',
            ['name' => 'capability_tool', 'arguments' => new \stdClass()],
            ['Mcp-Name' => 'capability_tool'],
        );

        $this->assertCount(2, $events);
        $this->assertInstanceOf(RequestEvent::class, $events[0]);
        $this->assertInstanceOf(ErrorEvent::class, $events[1]);
        $this->assertInstanceOf(MissingRequiredClientCapabilityException::class, $events[1]->getThrowable());
        $this->assertSame('replaced', $answer['body']['error']['message']);
    }

    #[TestDox('a response event is dispatched for a streamed response too')]
    public function testResponseEventIsDispatchedWhenStreamed(): void
    {
        $events = [];

        $frames = self::frames(self::callStreaming(self::protocol(eventDispatcher: $this->eventDispatcher($events)), 'progress_tool', ['progressToken' => 'tok-1']));

        $this->assertCount(3, $frames);
        $this->assertCount(2, $events);
        $this->assertInstanceOf(RequestEvent::class, $events[0]);
        $this->assertInstanceOf(ResponseEvent::class, $events[1]);
    }

    #[TestDox('server/discover is answered by the default handler exactly as before it was one')]
    public function testDiscoverDefaultAnswer(): void
    {
        $answer = self::call(self::discoverProtocol(), 'server/discover');

        $this->assertSame(200, $answer['status']);
        $this->assertSame([
            'jsonrpc' => '2.0',
            'id' => 1,
            'result' => [
                'supportedVersions' => [ProtocolVersion::V2026_07_28->value],
                'capabilities' => ['logging' => [], 'completions' => [], 'tools' => []],
                'instructions' => 'Call plain_tool first.',
                'resultType' => 'complete',
                'ttlMs' => 0,
                'cacheScope' => 'private',
                '_meta' => [RequestMeta::SERVER_INFO => ['name' => 'test-server', 'version' => '1.0.0']],
            ],
        ], $answer['body']);
    }

    #[TestDox('server/discover is answered with plain JSON to a client that accepts a stream')]
    public function testDiscoverIsNeverStreamed(): void
    {
        $result = self::discoverProtocol(self::discoverHandler('Streams are for tools.', notify: true))->handle(
            json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'server/discover', 'params' => ['_meta' => [
                RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
                RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
            ]]], \JSON_THROW_ON_ERROR),
            [
                'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
                'Mcp-Method' => 'server/discover',
                'Accept' => 'application/json, text/event-stream',
            ],
        );

        $this->assertFalse($result->isStream());
        $this->assertSame(200, $result->httpStatus);
        $this->assertSame('Streams are for tools.', json_decode($result->toJson(), true, flags: \JSON_THROW_ON_ERROR)['result']['instructions']);
    }

    #[TestDox('a server/discover handler added to the builder answers instead of the default')]
    public function testCustomDiscoverHandlerReplacesTheDefault(): void
    {
        $answer = self::call(self::discoverProtocol(self::discoverHandler('Stateless clients: use plain_tool only.')), 'server/discover');

        $this->assertSame(200, $answer['status']);
        $this->assertSame('Stateless clients: use plain_tool only.', $answer['body']['result']['instructions']);
        // The codec still stamps the wire vocabulary onto a custom result.
        $this->assertSame('complete', $answer['body']['result']['resultType']);
        $this->assertSame('test-server', $answer['body']['result']['_meta'][RequestMeta::SERVER_INFO]['name']);
    }

    #[TestDox('server/discover dispatches request and response events, and a listener can change the answer')]
    public function testDiscoverDispatchesEvents(): void
    {
        $events = [];
        $listener = static function (object $event): void {
            if ($event instanceof ResponseEvent && $event->getRequest() instanceof DiscoverRequest) {
                $result = $event->getResponse()->result;
                \assert($result instanceof DiscoverResult);
                $event->setResponse(new Response($event->getResponse()->getId(), new DiscoverResult($result->supportedVersions, $result->capabilities, 'Changed by a listener.')));
            }
        };

        $answer = self::call(self::discoverProtocol(eventDispatcher: $this->eventDispatcher($events, $listener)), 'server/discover');

        $this->assertCount(2, $events);
        $this->assertInstanceOf(RequestEvent::class, $events[0]);
        $this->assertSame('server/discover', $events[0]->getMethod());
        $this->assertInstanceOf(ResponseEvent::class, $events[1]);
        $this->assertSame('Changed by a listener.', $answer['body']['result']['instructions']);
    }

    /**
     * @param RequestHandlerInterface<DiscoverResult>|null $discoverHandler
     */
    private static function discoverProtocol(?RequestHandlerInterface $discoverHandler = null, ?EventDispatcherInterface $eventDispatcher = null): StatelessProtocol
    {
        $builder = Server::builder()
            ->setServerInfo('test-server', '1.0.0')
            ->setInstructions('Call plain_tool first.')
            ->addTool(static fn (): string => 'ok', name: 'plain_tool', description: 'Returns a fixed string');

        if (null !== $discoverHandler) {
            $builder->addRequestHandler($discoverHandler);
        }

        if (null !== $eventDispatcher) {
            $builder->setEventDispatcher($eventDispatcher);
        }

        return $builder->buildStateless([ProtocolVersion::V2026_07_28]);
    }

    /**
     * @return RequestHandlerInterface<DiscoverResult>
     */
    private static function discoverHandler(string $instructions, bool $notify = false): RequestHandlerInterface
    {
        return new class($instructions, $notify) implements RequestHandlerInterface {
            public function __construct(
                private readonly string $instructions,
                private readonly bool $notify,
            ) {
            }

            public function supports(Request $request): bool
            {
                return $request instanceof DiscoverRequest;
            }

            /**
             * @return Response<DiscoverResult>
             */
            public function handle(Request $request, SessionInterface $session): Response
            {
                if ($this->notify) {
                    // Would open a stream for any other method.
                    \Fiber::suspend(new NotificationSuspension(new ToolListChangedNotification(), $session->getId()->toRfc4122()));
                }

                return new Response($request->getId(), new DiscoverResult(
                    [ProtocolVersion::V2026_07_28],
                    new ServerCapabilities(),
                    $this->instructions,
                ));
            }
        };
    }
}