[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.

src/Server/ClientGateway.php

@@ -32,8 +32,10 @@ use Mcp\Schema\Notification\LoggingMessageNotification;
 use Mcp\Schema\Notification\ProgressNotification;
 use Mcp\Schema\Request\CreateSamplingMessageRequest;
 use Mcp\Schema\Request\ElicitRequest;
+use Mcp\Schema\Request\ListRootsRequest;
 use Mcp\Schema\Result\CreateSamplingMessageResult;
 use Mcp\Schema\Result\ElicitResult;
+use Mcp\Schema\Result\ListRootsResult;
 use Mcp\Server\Session\SessionInterface;
 
 /**
@@ -188,6 +190,49 @@ class ClientGateway
         return ElicitResult::fromArray($response->result);
     }
 
+    /**
+     * Request the list of filesystem roots exposed by the client.
+     *
+     * Roots are the client's "workspace folders" — the directories or files the
+     * server is allowed to operate on. The client answers the roots/list request
+     * with a list of file:// URIs.
+     *
+     * @param int $timeout The timeout in seconds
+     *
+     * @return ListRootsResult The roots exposed by the client
+     *
+     * @throws ClientException if the client request results in an error message
+     */
+    public function listRoots(int $timeout = 120): ListRootsResult
+    {
+        $request = new ListRootsRequest();
+
+        $response = $this->request($request, $timeout);
+
+        if ($response instanceof Error) {
+            throw new ClientException($response);
+        }
+
+        return ListRootsResult::fromArray($response->result);
+    }
+
+    /**
+     * Check if the connected client supports roots.
+     *
+     * Roots allow servers to ask the client for the set of directories or files
+     * it is permitted to operate on. This method checks the client's advertised
+     * capabilities to determine if roots/list requests are supported.
+     *
+     * @return bool True if the client supports roots, false otherwise
+     */
+    public function supportsRoots(): bool
+    {
+        $capabilities = (array) $this->session->get('client_capabilities', []);
+
+        // MCP spec: capability presence indicates support (value is typically {} or [])
+        return \array_key_exists('roots', $capabilities);
+    }
+
     /**
      * Check if the connected client supports elicitation.
      *
@@ -199,7 +244,7 @@ class ClientGateway
      */
     public function supportsElicitation(): bool
     {
-        $capabilities = $this->session->get('client_capabilities', []);
+        $capabilities = (array) $this->session->get('client_capabilities', []);
 
         // MCP spec: capability presence indicates support (value is typically {} or [])
         return \array_key_exists('elicitation', $capabilities);