[Client] Implement setMaxRetries connection retries

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
     ->setClientInfo('My Application', '1.0.0', 'Description of my client')
     ->setInitTimeout(30)      // Seconds to wait for initialization
     ->setRequestTimeout(120)  // Seconds to wait for request responses
-    ->setMaxRetries(3)        // Retry attempts for failed connections
+    ->setMaxRetries(3)        // Retries for failed connections
     ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+    ->setMaxRetries(0)  // Fail on the first failed attempt
+    ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+    private const RETRY_BASE_DELAY_MS = 100;
+
     private ?TransportInterface $transport = null;
 
     public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
     /**
      * Connect to an MCP server using the provided transport.
      *
-     * @throws ConnectionException If connection or initialization fails
+     * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+     *
+     * @throws ConnectionException If connection or initialization fails on every attempt
      */
     public function connect(TransportInterface $transport): void
     {
         $this->transport = $transport;
         $this->protocol->connect($transport, $this->config);
 
-        $transport->connect();
+        $maxAttempts = $this->config->maxRetries + 1;
+
+        for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+            try {
+                $transport->connect();
+
+                $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+                return;
+            } catch (ConnectionException $e) {
+                // initialize() flags the session before sending the initialized
+                // notification, so a failure in between leaves the flag set.
+                $this->protocol->getState()->setInitialized(false);
 
-        $this->logger->info('Client connected and initialized');
+                $transport->close();
+
+                if ($attempt === $maxAttempts) {
+                    throw $e;
+                }
+
+                $this->logger->warning('Connection attempt failed, retrying', [
+                    'attempt' => $attempt,
+                    'max_attempts' => $maxAttempts,
+                    'exception' => $e,
+                ]);
+
+                usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+            }
+        }
     }
 
     /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
     }
 
     /**
-     * Set maximum retry attempts for failed connections.
+     * Set the number of times a failed connection attempt is retried.
+     *
+     * Counts retries, not attempts: 3 means one initial attempt plus up to three
+     * retries. Pass 0 to fail on the first failure. Only applies to
+     * {@see Client::connect()}; individual requests are never retried.
      */
     public function setMaxRetries(int $retries): self
     {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
         if ($requestTimeout < 1) {
             throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
         }
+
+        if ($maxRetries < 0) {
+            throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+        }
     }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
         }
 
         $this->state->addPendingRequest($requestId, $timeout);
-        $this->sendRequest($request);
 
-        $immediate = $this->state->consumeResponse($requestId);
-        if (null !== $immediate) {
-            $this->logger->debug('Received immediate response', ['id' => $requestId]);
+        try {
+            $this->sendRequest($request);
 
-            return $immediate;
-        }
+            $immediate = $this->state->consumeResponse($requestId);
+            if (null !== $immediate) {
+                $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
-        $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+                return $immediate;
+            }
 
-        return \Fiber::suspend([
-            'type' => 'await_response',
-            'request_id' => $requestId,
-            'timeout' => $timeout,
-        ]);
+            $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+            return \Fiber::suspend([
+                'type' => 'await_response',
+                'request_id' => $requestId,
+                'timeout' => $timeout,
+            ]);
+        } finally {
+            // Only the response path clears it, so a request that timed out or
+            // whose send() threw would stay pending and fail every later one.
+            $this->state->removePendingRequest($requestId);
+        }
     }
 
     /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?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.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+    ->setServerInfo('integration-server', '1.0.0')
+    ->addTool(
+        static function (): string {
+            sleep(2);
+
+            return 'late';
+        },
+        name: 'slow',
+        description: 'Answers well after the client stopped waiting.',
+    )
+    ->addTool(
+        static fn (): string => 'quick',
+        name: 'fast',
+        description: 'Returns at once.',
+    )
+    ->build()
+    ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?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.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+    exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+    exit(1);
+}
+
+Server::builder()
+    ->setServerInfo('integration-server', '1.0.0')
+    ->addTool(
+        static fn (): string => 'quick',
+        name: 'fast',
+        description: 'Returns at once.',
+    )
+    ->build()
+    ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
      */
     protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
     {
-        $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
         $this->client = ($client ?? $this->clientBuilder())->build();
 
         try {
-            $this->client->connect(new StdioTransport(
-                command: \PHP_BINARY,
-                args: [$script],
-                // proc_open() replaces the environment rather than adding to it.
-                env: [] === $env ? null : array_merge(getenv(), $env),
-            ));
+            $this->client->connect($this->transport($fixture, $env));
         } catch (ConnectionException $e) {
             // The transport discards the child's stderr, so a fixture dying on
             // startup arrives here as a bare timeout.
-            $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+            $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
         }
 
         return $this->client;
     }
 
+    /**
+     * A transport that will spawn a fixture server, without connecting it.
+     *
+     * Tests that assert on a failing connection need the transport by itself,
+     * since {@see self::connect()} turns that failure into a test failure.
+     *
+     * @param array<string, string> $env added to the server process environment
+     */
+    protected function transport(string $fixture, array $env = []): StdioTransport
+    {
+        return new StdioTransport(
+            command: \PHP_BINARY,
+            args: [self::script($fixture)],
+            // proc_open() replaces the environment rather than adding to it.
+            env: [] === $env ? null : array_merge(getenv(), $env),
+        );
+    }
+
+    private static function script(string $fixture): string
+    {
+        return __DIR__.'/Fixture/'.$fixture.'.php';
+    }
+
     protected function tearDown(): void
     {
         $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?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\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+    #[TestDox('an abandoned response is not handed to the next request')]
+    public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+    {
+        $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+        try {
+            $client->callTool('slow');
+            $this->fail('The slow tool should have outlived the request timeout.');
+        } catch (RequestException) {
+        }
+
+        // The server is still executing the abandoned call and cannot answer
+        // anything until it returns, so the next request has to wait it out.
+        sleep(2);
+
+        // Without the pending request being cleared this answers 'late': the
+        // response the client gave up on, handed to the request after it.
+        $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+    }
+}