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

tests/Unit/Client/ClientTest.php

@@ -0,0 +1,79 @@
+<?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\Unit\Client;
+
+use Mcp\Client;
+use Mcp\Client\State\ClientStateInterface;
+use Mcp\Client\Transport\TransportInterface;
+use Mcp\Exception\ConnectionException;
+use Mcp\Exception\RuntimeException;
+use Mcp\Schema\ClientCapabilities;
+use PHPUnit\Framework\TestCase;
+
+final class ClientTest extends TestCase
+{
+    public function testSendRootsListChangedSendsNotificationWhenCapabilityDeclared(): void
+    {
+        $sent = [];
+        $transport = $this->createMock(TransportInterface::class);
+        $transport->method('send')->willReturnCallback(static function (string $data) use (&$sent): void {
+            $sent[] = $data;
+        });
+        // Stand in for a completed initialize handshake, which the transport drives.
+        $transport->method('setState')->willReturnCallback(static function (ClientStateInterface $state): void {
+            $state->setInitialized(true);
+        });
+
+        $client = Client::builder()
+            ->setClientInfo('Roots Test', '1.0.0')
+            ->setCapabilities(new ClientCapabilities(roots: true, rootsListChanged: true))
+            ->build();
+
+        $client->connect($transport);
+        $client->sendRootsListChanged();
+
+        $this->assertCount(1, $sent);
+        $decoded = json_decode($sent[0], true);
+        $this->assertSame('notifications/roots/list_changed', $decoded['method']);
+    }
+
+    public function testSendRootsListChangedThrowsWhenCapabilityNotDeclared(): void
+    {
+        $transport = $this->createMock(TransportInterface::class);
+        $transport->expects($this->never())->method('send');
+
+        $client = Client::builder()
+            ->setClientInfo('Roots Test', '1.0.0')
+            ->setCapabilities(new ClientCapabilities(roots: true))
+            ->build();
+
+        $client->connect($transport);
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('roots.listChanged');
+
+        $client->sendRootsListChanged();
+    }
+
+    public function testSendRootsListChangedThrowsWhenNotConnected(): void
+    {
+        $client = Client::builder()
+            ->setClientInfo('Roots Test', '1.0.0')
+            ->setCapabilities(new ClientCapabilities(roots: true, rootsListChanged: true))
+            ->build();
+
+        $this->expectException(ConnectionException::class);
+        $this->expectExceptionMessage('Client is not connected.');
+
+        $client->sendRootsListChanged();
+    }
+}