[Client][Server] Add Roots support (#395)

* [Client][Server] Add Roots support

Wire up the MCP "roots" capability on both sides:

Client (php-sdk as client):
- RootsCallbackInterface + ListRootsRequestHandler answer server roots/list
  requests, mirroring the Sampling handler.
- Client::sendRootsListChanged() emits notifications/roots/list_changed.

Server (php-sdk as server):
- ClientGateway::listRoots() requests the client's roots, and
  supportsRoots() reports whether the client advertised the capability,
  normalizing the stored capabilities to an array so an empty
  capabilities object (\stdClass) doesn't cause a TypeError.
- Add ListRootsResult::fromArray() (used by listRoots()).
- ListRootsRequestHandler forwards RootsException messages to the server
  (new Mcp\Exception\RootsException), mirroring SamplingRequestHandler.
- Client::sendRootsListChanged() throws when the client did not advertise
  the roots.listChanged capability.

Examples, docs and tests:
- examples/README/docs advertise
  `new ClientCapabilities(roots: true, rootsListChanged: true)` before
  sending notifications/roots/list_changed.
- CHANGELOG entry for Roots (unreleased 0.7.0 section at the time).
- Unit tests for capability serialization/round-trip, sendRootsListChanged
  gating, and RootsException message forwarding.

phpunit, php-cs-fixer and phpstan green.

* [Client][Server] Address review: schema validation, changelog section, connection guard, working example

Responds to chr-hertel's review of the Roots support:

- ListRootsResult::fromArray() rejects non-array root elements instead of
  accepting malformed entries silently.
- CHANGELOG entry moved to the next unreleased section as the release
  train advanced past it (0.7.0 -> 0.8.0).
- Client::sendRootsListChanged() went straight to
  Protocol::sendNotification(), which sends via
  `$this->transport?->send()` -- on a client that is not connected the
  notification was silently dropped. It now throws a ConnectionException
  like sendRequest() does.
- The stdio example only advertised the roots capability, so the
  roots/list handler never actually ran. The client-communication demo
  server gets an `inspect_workspace_roots` tool that calls
  ClientGateway::supportsRoots()/listRoots(); the example calls it, so
  the server actually issues roots/list and the client answers it.
  Dropped the try/catch wrapper from the example.
- ClientTest's connected-client mock now goes through setState() so
  isConnected() reflects a real handshake instead of a stubbed flag.

phpunit, php-cs-fixer and phpstan green.

examples/client/stdio_roots.php

@@ -0,0 +1,85 @@
+<?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.
+ */
+
+/**
+ * STDIO Roots Example.
+ *
+ * This example demonstrates the "roots" client capability:
+ * - The client advertises the `roots` capability during initialization.
+ * - It answers server `roots/list` requests via a RootsCallbackInterface,
+ *   exposing a couple of `file://` workspace folders.
+ * - Calling the server's `inspect_workspace_roots` tool makes the server issue
+ *   a `roots/list` request, so the handler below actually runs.
+ * - It notifies the server when its list of roots changes.
+ *
+ * Usage: php examples/client/stdio_roots.php
+ */
+
+require_once __DIR__.'/../../vendor/autoload.php';
+
+use Mcp\Client;
+use Mcp\Client\Handler\Request\ListRootsRequestHandler;
+use Mcp\Client\Handler\Request\RootsCallbackInterface;
+use Mcp\Client\Transport\StdioTransport;
+use Mcp\Schema\ClientCapabilities;
+use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Request\ListRootsRequest;
+use Mcp\Schema\Result\ListRootsResult;
+use Mcp\Schema\Root;
+
+$rootsRequestHandler = new ListRootsRequestHandler(new class implements RootsCallbackInterface {
+    public function __invoke(ListRootsRequest $request): ListRootsResult
+    {
+        echo "[ROOTS] Server requested the client's list of roots\n";
+
+        return new ListRootsResult([
+            new Root('file:///home/user/projects/app', 'Application'),
+            new Root('file:///home/user/projects/library', 'Library'),
+        ]);
+    }
+});
+
+$client = Client::builder()
+    ->setClientInfo('STDIO Roots Test', '1.0.0')
+    ->setInitTimeout(30)
+    ->setRequestTimeout(120)
+    ->setCapabilities(new ClientCapabilities(roots: true, rootsListChanged: true))
+    ->addRequestHandler($rootsRequestHandler)
+    ->build();
+
+$transport = new StdioTransport(
+    command: 'php',
+    args: [__DIR__.'/../server/client-communication/server.php'],
+);
+
+echo "Connecting to MCP server...\n";
+$client->connect($transport);
+
+$serverInfo = $client->getServerInfo();
+echo 'Connected to: '.($serverInfo->name ?? 'unknown')."\n\n";
+
+// The server tool asks the client for its roots, which triggers the handler above.
+echo "Calling 'inspect_workspace_roots'...\n";
+$result = $client->callTool(name: 'inspect_workspace_roots');
+
+echo "\nResult:\n";
+foreach ($result->content as $content) {
+    if ($content instanceof TextContent) {
+        echo $content->text."\n";
+    }
+}
+
+// Whenever the client's workspace folders change, notify the server so it can
+// request an updated list via roots/list.
+echo "\nNotifying the server that the roots list changed...\n";
+$client->sendRootsListChanged();
+
+$client->disconnect();

examples/server/client-communication/ClientAwareService.php

@@ -25,6 +25,42 @@ final class ClientAwareService
         $this->logger->info('SamplingTool instantiated for sampling example.');
     }
 
+    /**
+     * Ask the client which workspace folders the server is allowed to operate on.
+     *
+     * Demonstrates the server side of the "roots" client capability: the tool
+     * issues a roots/list request that the client answers from its own handler.
+     *
+     * @return array{status: string, message: string, roots?: list<array{uri: string, name: string|null}>}
+     */
+    #[McpTool(name: 'inspect_workspace_roots', description: 'Ask the client for its workspace roots via a roots/list request.')]
+    public function inspectWorkspaceRoots(RequestContext $context): array
+    {
+        $clientGateway = $context->getClientGateway();
+
+        if (!$clientGateway->supportsRoots()) {
+            return [
+                'status' => 'unsupported',
+                'message' => 'Client does not expose roots. Advertise the "roots" capability and register a ListRootsRequestHandler to let the server discover your workspace folders.',
+            ];
+        }
+
+        $result = $clientGateway->listRoots();
+
+        $roots = [];
+        foreach ($result->roots as $root) {
+            $roots[] = ['uri' => $root->uri, 'name' => $root->name];
+        }
+
+        $clientGateway->log(LoggingLevel::Info, \sprintf('Client exposed %d root(s).', \count($roots)));
+
+        return [
+            'status' => 'ok',
+            'message' => \sprintf('Client exposed %d root(s).', \count($roots)),
+            'roots' => $roots,
+        ];
+    }
+
     /**
      * @return array{incident: string, recommended_actions: string, model: string}
      */