[Client][Server] Add Roots support

[wachterjohannes]

Adds support for the MCP Roots capability, letting a client expose file:// "workspace folders" that the server is allowed to operate on.

Client side

• ListRootsRequestHandler + RootsCallbackInterface — answer server roots/list requests from a user-provided callback (mirrors the existing SamplingRequestHandler / SamplingCallbackInterface pattern).
• Client::sendRootsListChanged() — send notifications/roots/list_changed. Guarded: it throws unless the client advertised the roots.listChanged capability, so a misconfigured client can't emit an undeclared notification.
• Mcp\Exception\RootsException — thrown from a roots callback, its message is forwarded to the server (same contract as SamplingException); any other throwable is logged and returned as a generic internal error.

Server side

• ClientGateway::listRoots() — request the client's roots (returns ListRootsResult, throws ClientException on an error response).
• ClientGateway::supportsRoots() — capability-gating helper alongside supportsElicitation().

Schema

• ListRootsResult::fromArray() — parse the client's response; Root continues to enforce the file:// URI scheme required by the spec.

Docs / examples / tests

• README + docs/client.md sections and a runnable examples/client/stdio_roots.php.
• Unit tests covering the handler, result parsing (incl. non-file:// rejection), capability serialization/round-trip, sendRootsListChanged() gating, and the ClientGateway roots methods.
• CHANGELOG entry under 0.7.0.

Conformance notes

• Root URIs are restricted to file:// per the current spec.
• roots capability presence gates roots/list; roots.listChanged gates the list_changed notification.

[chr-hertel]

Needs to move to a 0.8.0 section please

[wachterjohannes]

Moved to a new 0.8.0 section in 4c21047.

[chr-hertel]

i get why you're not using sendRequest - it's just a notification, but is this sufficient - we're skipping isConnected check here

[wachterjohannes]

Good catch — it was worse than just skipping the check: Protocol::sendNotification() sends via $this->transport?->send(), so on a disconnected client the notification was silently dropped instead of failing. It now throws a ConnectionException like sendRequest() does (capability check stays first), with a test for it. 5d278a9

[chr-hertel]

i don't think we need the try-catch block here

and, not sure, but can we demo it the other way around so that the list roots request actually is executed?

[wachterjohannes]

Both done in 5d278a9. try/catch is gone, and the demo is turned around: the client-communication server now has an inspect_workspace_roots tool using ClientGateway::supportsRoots()/listRoots(), and the example calls it — so the server really issues roots/list and the client's handler answers. Output when run:

Calling 'inspect_workspace_roots'...
[ROOTS] Server requested the client's list of roots

Result:
{
    "status": "ok",
    "message": "Client exposed 2 root(s).",
    "roots": [
        {"uri": "file:///home/user/projects/app", "name": "Application"},
        {"uri": "file:///home/user/projects/library", "name": "Library"}
    ]
}

The sendRootsListChanged() notification is kept at the end as a secondary demo.