Merge pull request #315 from koic/support_roots

Add `roots/list` and `notifications/roots/list_changed` support

README.md

@@ -38,6 +38,7 @@ It implements the Model Context Protocol specification, handling model context r
 - Supports resource registration and retrieval
 - Supports stdio & Streamable HTTP (including SSE) transports
 - Supports notifications for list changes (tools, prompts, resources)
+- Supports roots (server-to-client filesystem boundary queries)
 - Supports sampling (server-to-client LLM completion requests)
 
 ### Supported Methods
@@ -52,6 +53,7 @@ It implements the Model Context Protocol specification, handling model context r
 - `resources/read` - Retrieves a specific resource by name
 - `resources/templates/list` - Lists all registered resource templates and their schemas
 - `completion/complete` - Returns autocompletion suggestions for prompt arguments and resource URIs
+- `roots/list` - Requests filesystem roots from the client (server-to-client)
 - `sampling/createMessage` - Requests LLM completion from the client (server-to-client)
 - `elicitation/create` - Requests user input from the client (server-to-client)
 
@@ -891,6 +893,70 @@ server = MCP::Server.new(
 )
 ```
 
+### Roots
+
+The Model Context Protocol allows servers to request filesystem roots from clients through the `roots/list` method.
+Roots define the boundaries of where a server can operate, providing a list of directories and files the client has made available.
+
+**Key Concepts:**
+
+- **Server-to-Client Request**: Like sampling, roots listing is initiated by the server
+- **Client Capability**: Clients must declare `roots` capability during initialization
+- **Change Notifications**: Clients that support `roots.listChanged` send `notifications/roots/list_changed` when roots change
+
+**Using Roots in Tools:**
+
+Tools that accept a `server_context:` parameter can call `list_roots` on it.
+The request is automatically routed to the correct client session:
+
+```ruby
+class FileSearchTool < MCP::Tool
+  description "Search files within the client's project roots"
+  input_schema(
+    properties: {
+      query: { type: "string" }
+    },
+    required: ["query"]
+  )
+
+  def self.call(query:, server_context:)
+    roots = server_context.list_roots
+    root_uris = roots[:roots].map { |root| root[:uri] }
+
+    MCP::Tool::Response.new([{
+      type: "text",
+      text: "Searching in roots: #{root_uris.join(", ")}"
+    }])
+  end
+end
+```
+
+Result contains an array of root objects:
+
+```ruby
+{
+  roots: [
+    { uri: "file:///home/user/projects/myproject", name: "My Project" },
+    { uri: "file:///home/user/repos/backend", name: "Backend Repository" }
+  ]
+}
+```
+
+**Handling Root Changes:**
+
+Register a callback to be notified when the client's roots change:
+
+```ruby
+server.roots_list_changed_handler do
+  puts "Client's roots have changed, tools will see updated roots on next call."
+end
+```
+
+**Error Handling:**
+
+- Raises `RuntimeError` if client does not support `roots` capability
+- Raises `StandardError` if client returns an error response
+
 ### Sampling
 
 The Model Context Protocol allows servers to request LLM completions from clients through the `sampling/createMessage` method.

lib/mcp/methods.rb

@@ -73,14 +73,12 @@ module MCP
           require_capability!(method, capabilities, :completions)
         when ROOTS_LIST
           require_capability!(method, capabilities, :roots)
-        when NOTIFICATIONS_ROOTS_LIST_CHANGED
-          require_capability!(method, capabilities, :roots)
-          require_capability!(method, capabilities, :roots, :listChanged)
         when SAMPLING_CREATE_MESSAGE
           require_capability!(method, capabilities, :sampling)
         when ELICITATION_CREATE
           require_capability!(method, capabilities, :elicitation)
-        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
+        when INITIALIZE, PING, NOTIFICATIONS_INITIALIZED, NOTIFICATIONS_ROOTS_LIST_CHANGED,
+             NOTIFICATIONS_PROGRESS, NOTIFICATIONS_CANCELLED, NOTIFICATIONS_ELICITATION_COMPLETE
           # No specific capability required.
         end
       end

lib/mcp/server.rb

@@ -121,6 +121,7 @@ module MCP
         Methods::PING => ->(_) { {} },
         Methods::NOTIFICATIONS_INITIALIZED => ->(_) {},
         Methods::NOTIFICATIONS_PROGRESS => ->(_) {},
+        Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED => ->(_) {},
         Methods::COMPLETION_COMPLETE => ->(_) { DEFAULT_COMPLETION_RESULT },
         Methods::LOGGING_SET_LEVEL => method(:configure_logging_level),
 
@@ -218,6 +219,14 @@ module MCP
       report_exception(e, { notification: "log_message" })
     end
 
+    # Sets a handler for `notifications/roots/list_changed` notifications.
+    # Called when a client notifies the server that its filesystem roots have changed.
+    #
+    # @yield [params] The notification params (typically `nil`).
+    def roots_list_changed_handler(&block)
+      @handlers[Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED] = block
+    end
+
     # Sets a custom handler for `resources/read` requests.
     # The block receives the parsed request params and should return resource
     # contents. The return value is set as the `contents` field of the response.

lib/mcp/server_context.rb

@@ -30,6 +30,15 @@ module MCP
       @notification_target.notify_log_message(data: data, level: level, logger: logger, related_request_id: @related_request_id)
     end
 
+    # Delegates to the session so the request is scoped to the originating client.
+    def list_roots
+      if @notification_target.respond_to?(:list_roots)
+        @notification_target.list_roots(related_request_id: @related_request_id)
+      else
+        raise NoMethodError, "undefined method 'list_roots' for #{self}"
+      end
+    end
+
     # Delegates to the session so the request is scoped to the originating client.
     # Falls back to `@context` (via `method_missing`) when `@notification_target`
     # does not support sampling.

lib/mcp/server_session.rb

@@ -41,6 +41,15 @@ module MCP
       @client_capabilities || @server.client_capabilities
     end
 
+    # Sends a `roots/list` request scoped to this session.
+    def list_roots(related_request_id: nil)
+      unless client_capabilities&.dig(:roots)
+        raise "Client does not support roots."
+      end
+
+      send_to_transport_request(Methods::ROOTS_LIST, nil, related_request_id: related_request_id)
+    end
+
     # Sends a `sampling/createMessage` request scoped to this session.
     def create_sampling_message(related_request_id: nil, **kwargs)
       params = @server.build_sampling_params(client_capabilities, **kwargs)

test/mcp/methods_test.rb

@@ -68,10 +68,7 @@ module MCP
     ensure_capability_does_not_raise_for Methods::NOTIFICATIONS_INITIALIZED
 
     ensure_capability_raises_error_for Methods::ROOTS_LIST, required_capability_name: "roots"
-    ensure_capability_raises_error_for Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED, required_capability_name: "roots"
-    ensure_capability_raises_error_for Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED,
-      required_capability_name: "roots.listChanged",
-      capabilities: { roots: {} }
+    ensure_capability_does_not_raise_for Methods::NOTIFICATIONS_ROOTS_LIST_CHANGED
 
     ensure_capability_raises_error_for Methods::SAMPLING_CREATE_MESSAGE, required_capability_name: "sampling"
 

test/mcp/server_context_test.rb

@@ -41,6 +41,32 @@ module MCP
       assert_raises(NoMethodError) { server_context.nonexistent_method }
     end
 
+    test "ServerContext#list_roots delegates to notification_target" do
+      notification_target = mock
+      notification_target.expects(:list_roots).with(
+        related_request_id: nil,
+      ).returns({ roots: [{ uri: "file:///project", name: "Project" }] })
+
+      context = mock
+      progress = Progress.new(notification_target: notification_target, progress_token: nil)
+
+      server_context = ServerContext.new(context, progress: progress, notification_target: notification_target)
+
+      result = server_context.list_roots
+
+      assert_equal [{ uri: "file:///project", name: "Project" }], result[:roots]
+    end
+
+    test "ServerContext#list_roots raises NoMethodError when notification_target does not respond" do
+      notification_target = mock
+      context = mock
+      progress = Progress.new(notification_target: notification_target, progress_token: nil)
+
+      server_context = ServerContext.new(context, progress: progress, notification_target: notification_target)
+
+      assert_raises(NoMethodError) { server_context.list_roots }
+    end
+
     test "ServerContext#create_sampling_message delegates to notification_target over context" do
       notification_target = mock
       notification_target.expects(:create_sampling_message).with(

test/mcp/server_roots_test.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module MCP
+  class ServerRootsTest < ActiveSupport::TestCase
+    class MockTransport < Transport
+      attr_reader :requests
+
+      def initialize(server)
+        super
+        @requests = []
+      end
+
+      def send_request(method, params = nil)
+        @requests << { method: method, params: params }
+        {
+          roots: [
+            { uri: "file:///home/user/projects/myproject", name: "My Project" },
+          ],
+        }
+      end
+
+      def send_response(response); end
+      def send_notification(method, params = nil); end
+      def open; end
+      def close; end
+    end
+
+    setup do
+      @server = Server.new(
+        name: "test_server",
+        version: "1.0.0",
+      )
+
+      @mock_transport = MockTransport.new(@server)
+
+      @server.handle({
+        jsonrpc: "2.0",
+        method: "initialize",
+        id: 1,
+        params: {
+          protocolVersion: "2025-11-25",
+          capabilities: { roots: { listChanged: true } },
+          clientInfo: { name: "test-client", version: "1.0" },
+        },
+      })
+    end
+
+    test "roots_list_changed_handler registers callback invoked when notification received" do
+      callback_called = false
+
+      @server.roots_list_changed_handler do |_params|
+        callback_called = true
+      end
+
+      @server.handle({
+        jsonrpc: "2.0",
+        method: "notifications/roots/list_changed",
+      })
+
+      assert callback_called
+    end
+
+    test "notifications/roots/list_changed is handled as no-op by default" do
+      result = @server.handle({
+        jsonrpc: "2.0",
+        method: "notifications/roots/list_changed",
+      })
+
+      assert_nil result
+    end
+
+    test "init stores client capabilities" do
+      server = Server.new(name: "test", version: "1.0")
+      server.handle({
+        jsonrpc: "2.0",
+        method: "initialize",
+        id: 1,
+        params: {
+          protocolVersion: "2025-11-25",
+          capabilities: { roots: { listChanged: true } },
+          clientInfo: { name: "test-client", version: "1.0" },
+        },
+      })
+
+      assert_equal({ roots: { listChanged: true } }, server.client_capabilities)
+    end
+
+    test "init stores nil when client sends no capabilities" do
+      server = Server.new(name: "test", version: "1.0")
+      server.handle({
+        jsonrpc: "2.0",
+        method: "initialize",
+        id: 1,
+        params: {
+          protocolVersion: "2025-11-25",
+          clientInfo: { name: "test-client", version: "1.0" },
+        },
+      })
+
+      assert_nil server.client_capabilities
+    end
+
+    test "list_roots uses per-session capabilities via ServerSession" do
+      transport = MCP::Server::Transports::StreamableHTTPTransport.new(@server)
+
+      session_with_roots = ServerSession.new(server: @server, transport: transport, session_id: "s1")
+      session_with_roots.store_client_info(client: { name: "capable" }, capabilities: { roots: {} })
+      transport.instance_variable_get(:@sessions)["s1"] = { stream: nil, server_session: session_with_roots }
+
+      error_with_roots = assert_raises(RuntimeError) do
+        session_with_roots.list_roots
+      end
+      assert_equal("No active stream for roots/list request.", error_with_roots.message)
+
+      session_without_roots = ServerSession.new(server: @server, transport: transport, session_id: "s2")
+      session_without_roots.store_client_info(client: { name: "incapable" }, capabilities: {})
+
+      error = assert_raises(RuntimeError) do
+        session_without_roots.list_roots
+      end
+      assert_equal("Client does not support roots.", error.message)
+    end
+
+    test "ServerSession#client_capabilities falls back to server global capabilities" do
+      transport = MCP::Server::Transports::StreamableHTTPTransport.new(@server)
+
+      session = ServerSession.new(server: @server, transport: transport, session_id: "s3")
+      transport.instance_variable_get(:@sessions)["s3"] = { stream: nil, server_session: session }
+
+      error = assert_raises(RuntimeError) do
+        session.list_roots
+      end
+      assert_equal("No active stream for roots/list request.", error.message)
+    end
+
+    test "session init does not overwrite server global client_capabilities" do
+      server = Server.new(name: "test", version: "1.0")
+      MockTransport.new(server)
+
+      server.handle({
+        jsonrpc: "2.0",
+        method: "initialize",
+        id: 1,
+        params: {
+          protocolVersion: "2025-11-25",
+          capabilities: { roots: {} },
+          clientInfo: { name: "first-client", version: "1.0" },
+        },
+      })
+
+      assert_equal({ roots: {} }, server.client_capabilities)
+
+      transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+      session = ServerSession.new(server: server, transport: transport, session_id: "s1")
+
+      server.handle(
+        {
+          jsonrpc: "2.0",
+          method: "initialize",
+          id: 2,
+          params: {
+            protocolVersion: "2025-11-25",
+            capabilities: {},
+            clientInfo: { name: "second-client", version: "1.0" },
+          },
+        },
+        session: session,
+      )
+
+      assert_equal({ roots: {} }, server.client_capabilities)
+      assert_equal({}, session.client_capabilities)
+    end
+
+    test "ServerSession#list_roots uses session-scoped capabilities from HTTP init" do
+      server = Server.new(name: "test", version: "1.0")
+      transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+
+      session = ServerSession.new(server: server, transport: transport, session_id: "s1")
+      server.handle(
+        {
+          jsonrpc: "2.0",
+          method: "initialize",
+          id: 1,
+          params: {
+            protocolVersion: "2025-11-25",
+            capabilities: { roots: {} },
+            clientInfo: { name: "http-client", version: "1.0" },
+          },
+        },
+        session: session,
+      )
+
+      transport.instance_variable_get(:@sessions)["s1"] = { stream: nil, server_session: session }
+      error = assert_raises(RuntimeError) do
+        session.list_roots
+      end
+      assert_equal("No active stream for roots/list request.", error.message)
+    end
+  end
+end