[Client][Server] Add Roots support#395
Open
wachterjohannes wants to merge 3 commits into
Open
Conversation
…y::listRoots) 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. - Add ListRootsResult::fromArray() (used by listRoots()). Includes unit tests, a runnable examples/client/stdio_roots.php example, and docs/README/CHANGELOG updates. phpunit, php-cs-fixer and phpstan green. Co-Authored-By: Claude <noreply@anthropic.com>
0.6.0 is already released; the Roots additions belong under a new unreleased 0.7.0 section rather than the shipped 0.6.0. Co-Authored-By: Claude <noreply@anthropic.com>
…rding, docs & tests Applies the five findings from the PR #1 code review: 1. Spec conformance: examples/docs/README now advertise `new ClientCapabilities(roots: true, rootsListChanged: true)` before sending `notifications/roots/list_changed`. 2. `ClientGateway::supportsRoots()`/`supportsElicitation()` normalize the stored capabilities to an array, avoiding a TypeError when a client advertised an empty capabilities object (\stdClass). 3. `Client::sendRootsListChanged()` now throws when the client did not advertise the `roots.listChanged` capability. 4. Add tests: capability serialization/round-trip, sendRootsListChanged gating (sends when declared, throws otherwise), RootsException message forwarding, and rejection of non-file:// root URIs. 5. `ListRootsRequestHandler` forwards `RootsException` messages to the server (new Mcp\Exception\RootsException), mirroring SamplingRequestHandler. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012NrvzihxUvQzDSoWzjsm58
wachterjohannes
requested review from
CodeWithKyrian,
Nyholm,
chr-hertel and
soyuka
as code owners
chr-hertel
added
Client
chr-hertel
requested changes
Jul 14, 2026
Comment on lines
+49
to
+52
| $roots = array_map( | ||
| static fn (array $root): Root => Root::fromArray($root), | ||
| array_values($data['roots']), | ||
| ); |
Member
There was a problem hiding this comment.
flaky in case roots doesn't carry an array as element => TypeError
chr-hertel
added
the
needs more work
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 serverroots/listrequests from a user-provided callback (mirrors the existingSamplingRequestHandler/SamplingCallbackInterfacepattern).Client::sendRootsListChanged()— sendnotifications/roots/list_changed. Guarded: it throws unless the client advertised theroots.listChangedcapability, 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 asSamplingException); any other throwable is logged and returned as a generic internal error.Server side
ClientGateway::listRoots()— request the client's roots (returnsListRootsResult, throwsClientExceptionon an error response).ClientGateway::supportsRoots()— capability-gating helper alongsidesupportsElicitation().Schema
ListRootsResult::fromArray()— parse the client's response;Rootcontinues to enforce thefile://URI scheme required by the spec.Docs / examples / tests
docs/client.mdsections and a runnableexamples/client/stdio_roots.php.file://rejection), capability serialization/round-trip,sendRootsListChanged()gating, and theClientGatewayroots methods.0.7.0.Conformance notes
file://per the current spec.rootscapability presence gatesroots/list;roots.listChangedgates thelist_changednotification.