[Client] Feat: Implement MCP client component (#192)

* feat(client): add complete MCP client SDK with STDIO and HTTP transports

Add Client, Builder, ClientProtocol, ClientSession, and transport
implementations for communicating with MCP servers. Supports tools, resources, prompts, and real-time progress/logging notifications.

* refactor(examples): reorganize examples into server/ and client/ folders

* feat: add SamplingRequestHandler for handling server sampling requests

* feat: add setLoggingLevel method to control server logging verbosity

* refactor: make progress token dependent on request ID

* docs: Update server IP in usage instructions and add notes on sampling server requirements.

* feat: add complete() method for completion/complete requests

* refactor: properly parse and type initialize result

* refactor: standardize method names

* fix: revert changes to server related components

* fix: revert changes to server related components

* refactor: Restructure client transports and handlers into dedicated namespaces.

* fix: cs and php-stan errors fixes(partial)

* feat: Refactor request handlers to return `Response` or `Error` objects directly, adding a `SamplingException` and error logging for sampling requests.

* feat: Replace `ClientTransportInterface` with `TransportInterface` and move response result deserialization to client methods.

* refactor: remove redundant timeout check for intialize on transports

The processFiber that executes per tick while fiber is suspended already handles timeouts while waiting

* feat: broaden symfony/http-client dependency to support Symfony 5.4 to 8.0

* Update examples/client/README.md

Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>

* Update examples/client/README.md

Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>

* refactor: remove outgoing message queue from session and simplify transport send method to directly dispatch messages.

* refactor: Replace ClientSession with ClientState for clearer intent on runtime state management

* refactor: rename connectAndInitialize to connect for consistency

* chore: cs fix

* chore: use SamplingCallbackInterface instead of a closure for sampling request handler

---------

Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>

src/Client/Handler/Request/SamplingRequestHandler.php

@@ -0,0 +1,67 @@
+<?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\Client\Handler\Request;
+
+use Mcp\Exception\SamplingException;
+use Mcp\Schema\JsonRpc\Error;
+use Mcp\Schema\JsonRpc\Request;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\CreateSamplingMessageRequest;
+use Mcp\Schema\Result\CreateSamplingMessageResult;
+use Psr\Log\LoggerInterface;
+use Psr\Log\NullLogger;
+
+/**
+ * Handler for sampling requests from the server.
+ *
+ * The MCP server may request the client to sample an LLM during tool execution.
+ * This handler wraps a user-provided callback that performs the actual LLM call.
+ *
+ * @implements RequestHandlerInterface<CreateSamplingMessageResult>
+ *
+ * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ */
+class SamplingRequestHandler implements RequestHandlerInterface
+{
+    public function __construct(
+        private readonly SamplingCallbackInterface $callback,
+        private readonly LoggerInterface $logger = new NullLogger(),
+    ) {
+    }
+
+    public function supports(Request $request): bool
+    {
+        return $request instanceof CreateSamplingMessageRequest;
+    }
+
+    /**
+     * @return Response<CreateSamplingMessageResult>|Error
+     */
+    public function handle(Request $request): Response|Error
+    {
+        \assert($request instanceof CreateSamplingMessageRequest);
+
+        try {
+            $result = $this->callback->__invoke($request);
+
+            return new Response($request->getId(), $result);
+        } catch (SamplingException $e) {
+            $this->logger->error('Sampling failed: '.$e->getMessage());
+
+            return Error::forInternalError($e->getMessage(), $request->getId());
+        } catch (\Throwable $e) {
+            $this->logger->error('Unexpected error during sampling', ['exception' => $e]);
+
+            return Error::forInternalError('Error while sampling LLM', $request->getId());
+        }
+    }
+}