[Client] Speak the 2026-07-28 lifecycle (#456)

* [Client] Speak the 2026-07-28 lifecycle

On that revision the client opens with server/discover instead of
initialize, stamps each request's _meta with the protocol version, its own
capabilities and client info, and sends the standard Mcp-Method / Mcp-Name /
Mcp-Param-* headers an intermediary routes on. ToolCatalog is what knows,
from the tool list, which arguments a call has to mirror.

An input_required result is answered rather than surfaced: InputRequestResolver
asks the host's elicitation, sampling and roots handlers and retries the same
request carrying inputResponses and the requestState the server sent.

McpHeader holds the header names and the =?base64?…?= sentinel, so the two
sides no longer keep their own copies of the same rules.

* Fix CI baseline drift and address Copilot review findings

Drop stale expected-failure entries the new client fixture now passes.

Copilot review: fix McpHeader round-trip for a wrapper-shaped literal,
encode empty/numeric-keyed inputResponses as a JSON object, stop the
incident example repeating side effects on MRTR retry, and reset
ToolCatalog on reconnect instead of carrying the previous server's
verdicts.

* Skip DualEraExampleTestCase on PHP 8.1

PHP_CLI_SERVER_WORKERS does not reliably fork multiple php -S
workers there (php/php-src#9400), reproducing the single-worker
deadlock the extra workers exist to avoid.

tests/Integration/DualEraElicitationTest.php

@@ -0,0 +1,105 @@
+<?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\Integration;
+
+use Mcp\Schema\Enum\ProtocolVersion;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * The elicitation example, driven from both eras against one endpoint.
+ *
+ * This is the example where the two lifecycles genuinely part ways: the
+ * handshake era can interrupt a call to ask the user something, and the modern
+ * era cannot. Its handlers fork in one place — a private `ask()` — and these
+ * tests are what say the fork works both ways round.
+ */
+final class DualEraElicitationTest extends DualEraExampleTestCase
+{
+    protected const ANSWERS = [
+        'confirm' => true,
+        'party_size' => 4,
+        'date' => '2026-09-01',
+        'dietary' => 'vegan',
+        'rating' => '5',
+        'comments' => 'Excellent',
+    ];
+
+    protected static function server(): string
+    {
+        return __DIR__.'/../../examples/server/elicitation/server.php';
+    }
+
+    protected static function portBase(): int
+    {
+        return 9500;
+    }
+
+    #[DataProvider('provideEras')]
+    #[TestDox('a confirmation is collected on $_dataName')]
+    public function testConfirmAction(ProtocolVersion $era): void
+    {
+        $client = $this->connect($era, elicitation: true);
+
+        $result = $client->callTool('confirm_action', ['actionDescription' => 'delete the staging database']);
+
+        $this->assertStringContainsString('Action confirmed', self::text($result));
+
+        $client->disconnect();
+    }
+
+    #[DataProvider('provideEras')]
+    #[TestDox('a multi-field form is collected on $_dataName')]
+    public function testBookRestaurant(ProtocolVersion $era): void
+    {
+        $client = $this->connect($era, elicitation: true);
+
+        $result = $client->callTool('book_restaurant', ['restaurantName' => 'Osteria']);
+
+        $this->assertStringContainsString('Reservation confirmed at Osteria for 4 guests', self::text($result));
+
+        $client->disconnect();
+    }
+
+    #[DataProvider('provideEras')]
+    #[TestDox('feedback with an optional field is collected on $_dataName')]
+    public function testCollectFeedback(ProtocolVersion $era): void
+    {
+        $client = $this->connect($era, elicitation: true);
+
+        $result = $client->callTool('collect_feedback', ['topic' => 'the new checkout flow']);
+
+        $this->assertStringContainsString('Thank you for your feedback', self::text($result));
+
+        $client->disconnect();
+    }
+
+    #[DataProvider('provideEras')]
+    #[TestDox('a client that declares no elicitation is told what to do instead, on $_dataName')]
+    public function testWithoutTheCapability(ProtocolVersion $era): void
+    {
+        $client = $this->connect($era);
+
+        // Both eras refuse an ask the client cannot answer. The handshake era
+        // finds out from the capability the client declared at initialize, the
+        // modern era from the envelope on this very request — and the example
+        // says the same thing either way.
+        try {
+            $answer = self::text($client->callTool('confirm_action', ['actionDescription' => 'anything']));
+            $this->assertStringContainsString('does not support elicitation', $answer);
+        } catch (\Throwable $e) {
+            $this->assertStringContainsString('did not declare it can provide', $e->getMessage());
+        }
+
+        $client->disconnect();
+    }
+}

tests/Integration/DualEraExampleTestCase.php

@@ -0,0 +1,144 @@
+<?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\Integration;
+
+use Mcp\Client;
+use Mcp\Client\Handler\Request\RequestHandlerInterface;
+use Mcp\Client\Transport\HttpTransport;
+use Mcp\Schema\ClientCapabilities;
+use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Enum\ElicitAction;
+use Mcp\Schema\Enum\ProtocolVersion;
+use Mcp\Schema\JsonRpc\Request;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\ElicitRequest;
+use Mcp\Schema\Result\CallToolResult;
+use Mcp\Schema\Result\ElicitResult;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Process\Process;
+
+/**
+ * Base for tests that drive one example server from both protocol eras.
+ *
+ * The example is started once, on one port, and every client in the test
+ * reaches it at that one URL — which is the property being tested. Nothing here
+ * mounts a second endpoint or restarts anything between eras.
+ *
+ * @author Christopher Hertel <mail@christopher-hertel.de>
+ */
+abstract class DualEraExampleTestCase extends TestCase
+{
+    /** Answers whatever the server elicits, so a tool that asks can complete. */
+    protected const ANSWERS = [];
+
+    private ?Process $server = null;
+    private int $port;
+
+    /** Absolute path to the example's server script. */
+    abstract protected static function server(): string;
+
+    /** Port range base, so concurrent test classes do not collide. */
+    abstract protected static function portBase(): int;
+
+    protected function setUp(): void
+    {
+        // PHP_CLI_SERVER_WORKERS does not reliably fork more than one worker on
+        // PHP 8.1 (see php/php-src#9400), which reproduces the very deadlock the
+        // extra workers exist to avoid: every request below hangs to the test
+        // timeout instead of running. Skip until either PHP 8.1 is dropped or
+        // this suite stops depending on `php -S` for multi-worker concurrency.
+        if (\PHP_VERSION_ID < 80200) {
+            $this->markTestSkipped('php -S does not reliably fork multiple workers on PHP 8.1 (PHP_CLI_SERVER_WORKERS); see php/php-src#9400.');
+        }
+
+        $this->port = static::portBase() + (getmypid() % 200);
+
+        // More than one worker because the handshake era needs it: a tool that
+        // asks the client mid-call holds its SSE response open while the client
+        // POSTs the answer on a second connection. One worker deadlocks there —
+        // a property of `php -S`, not of the server.
+        $this->server = new Process(
+            ['php', '-S', \sprintf('127.0.0.1:%d', $this->port), static::server()],
+            env: ['PHP_CLI_SERVER_WORKERS' => '4'],
+        );
+        $this->server->start();
+
+        $deadline = microtime(true) + 5;
+        while (microtime(true) < $deadline) {
+            if (@fsockopen('127.0.0.1', $this->port, $errno, $error, 0.1)) {
+                return;
+            }
+
+            usleep(50_000);
+        }
+
+        $this->fail(\sprintf('The example server did not start: %s', $this->server->getErrorOutput()));
+    }
+
+    protected function tearDown(): void
+    {
+        $this->server?->stop();
+    }
+
+    /**
+     * @return iterable<string, array{ProtocolVersion}>
+     */
+    public static function provideEras(): iterable
+    {
+        yield 'the handshake era' => [ProtocolVersion::V2025_11_25];
+        yield 'the modern era' => [ProtocolVersion::V2026_07_28];
+    }
+
+    protected static function text(CallToolResult $result): string
+    {
+        $first = $result->content[0] ?? null;
+
+        self::assertInstanceOf(TextContent::class, $first);
+
+        return $first->text;
+    }
+
+    protected function connect(ProtocolVersion $era, bool $elicitation = false): Client
+    {
+        $builder = Client::builder()
+            ->setClientInfo('dual-era-integration-client', '1.0.0')
+            ->setProtocolVersion($era)
+            ->setRequestTimeout(10);
+
+        if ($elicitation) {
+            $answers = static::ANSWERS;
+
+            $builder->setCapabilities(new ClientCapabilities(elicitation: true));
+            $builder->addRequestHandler(new class($answers) implements RequestHandlerInterface {
+                /** @param array<string, mixed> $answers */
+                public function __construct(private readonly array $answers)
+                {
+                }
+
+                public function supports(Request $request): bool
+                {
+                    return $request instanceof ElicitRequest;
+                }
+
+                public function handle(Request $request): Response
+                {
+                    return new Response($request->getId(), new ElicitResult(ElicitAction::Accept, $this->answers));
+                }
+            });
+        }
+
+        $client = $builder->build();
+        $client->connect(new HttpTransport(\sprintf('http://127.0.0.1:%d/', $this->port)));
+
+        return $client;
+    }
+}

tests/Integration/HandshakeTest.php

@@ -59,11 +59,16 @@ final class HandshakeTest extends IntegrationTestCase
         yield 'server pins a newer revision' => [ProtocolVersion::V2024_11_05, ProtocolVersion::V2025_11_25, ProtocolVersion::V2025_11_25];
         yield 'both pin the same revision' => [ProtocolVersion::V2025_06_18, ProtocolVersion::V2025_06_18, ProtocolVersion::V2025_06_18];
 
-        // Neither side reaches the modern era through `initialize`, so
-        // configuring it falls back to the handshake set on both ends.
-        yield 'client configured modern' => [ProtocolVersion::V2026_07_28, null, $latest];
+        // A modern client does not negotiate at all: it skips the handshake and
+        // states its revision on every request, so what it was configured with
+        // is what it reports. This server never answers `server/discover`, so
+        // there is nothing to reconcile against either.
+        yield 'client configured modern' => [ProtocolVersion::V2026_07_28, null, ProtocolVersion::V2026_07_28];
+        yield 'both configured modern' => [ProtocolVersion::V2026_07_28, ProtocolVersion::V2026_07_28, ProtocolVersion::V2026_07_28];
+
+        // The server end still falls back: a handshake-era client offered a
+        // revision, and `initialize` cannot answer with a modern one.
         yield 'server configured modern' => [ProtocolVersion::V2025_06_18, ProtocolVersion::V2026_07_28, ProtocolVersion::V2025_06_18];
-        yield 'both configured modern' => [ProtocolVersion::V2026_07_28, ProtocolVersion::V2026_07_28, $latest];
     }
 
     #[TestDox('the handshake carries the server identity to the client')]