[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

@@ -55,6 +55,8 @@
  */
 class Client
 {
+    private const RETRY_BASE_DELAY_MS = 100;
+
     private ?TransportInterface $transport = null;
 
     public function __construct(
@@ -75,16 +77,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

@@ -11,6 +11,7 @@
 
 namespace Mcp\Client;
 
+use Mcp\Exception\InvalidArgumentException;
 use Mcp\Schema\ClientCapabilities;
 use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\Implementation;
@@ -30,5 +31,8 @@ public function __construct(
         public readonly int $requestTimeout = 120,
         public readonly int $maxRetries = 3,
     ) {
+        if ($maxRetries < 0) {
+            throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+        }
     }
 }

src/Client/Protocol.php

@@ -145,22 +145,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);
+        }
     }
 
     /**