Merge remote-tracking branch 'origin/main' into list-pagination-support

Author: patvice

README.md

@@ -12,6 +12,7 @@ This project is a Ruby client for the [Model Context Protocol (MCP)](https://mod
 - 🛠️ **Tool Integration**: Automatically converts MCP tools into RubyLLM-compatible tools
 - 📄 **Resource Management**: Access and include MCP resources (files, data) and resource templates in conversations
 - 🎯 **Prompt Integration**: Use predefined MCP prompts with arguments for consistent interactions
+- 🎛️ **Client Features**: Support for sampling and roots
 - 🎨 **Enhanced Chat Interface**: Extended RubyLLM chat methods for seamless MCP integration
 - 📚 **Simple API**: Easy-to-use interface that integrates seamlessly with RubyLLM
 
@@ -462,6 +463,81 @@ puts result
 # Result: { status: "success", data: "Processed data" }
 ```
 
+## Client Features
+
+The RubyLLM::MCP client provides support functionality that can be exposed to MCP servers. These features must be explicitly configured before creating client objects to ensure you're opting into this functionality.
+
+### Roots
+
+Roots provide MCP servers with access to underlying file system information. The implementation starts with a lightweight approach due to the MCP specification's current limitations on root usage.
+
+When roots are configured, the client will:
+
+- Expose roots as a supported capability to MCP servers
+- Support dynamic addition and removal of roots during the client lifecycle
+- Fire `notifications/roots/list_changed` events when roots are modified
+
+#### Configuration
+
+```ruby
+RubyLLM::MCP.config do |config|
+  config.roots = ["to/a/path", Rails.root]
+end
+
+client = RubyLLM::MCP::Client.new(...)
+```
+
+#### Usage
+
+```ruby
+# Access current root paths
+client.roots.paths
+# => ["to/a/path", #<Pathname:/to/rails/root/path>]
+
+# Add a new root (fires list_changed notification)
+client.roots.add("new/path")
+client.roots.paths
+# => ["to/a/path", #<Pathname:/to/rails/root/path>, "new/path"]
+
+# Remove a root (fires list_changed notification)
+client.roots.remove("to/a/path")
+client.roots.paths
+# => [#<Pathname:/to/rails/root/path>, "new/path"]
+```
+
+### Sampling
+
+Sampling allows MCP servers to offload LLM requests to the MCP client rather than making them directly from the server. This enables MCP servers to optionally use LLM connections through the client.
+
+#### Configuration
+
+```ruby
+RubyLLM::MCP.configure do |config|
+  config.sampling.enabled = true
+  config.sampling.preferred_model = "gpt-4.1"
+
+  # Optional: Use a block for dynamic model selection
+  config.sampling.preferred_model do |model_preferences|
+    model_preferences.hints.first
+  end
+
+  # Optional: Add guards to filter sampling requests
+  config.sampling.guard do |sample|
+    sample.message.include("Hello")
+  end
+end
+```
+
+#### How It Works
+
+With the above configuration:
+
+- Clients will respond to all incoming sample requests using the specified model (`gpt-4.1`)
+- Sample messages will only be approved if they contain the word "Hello" (when using the guard)
+- The `preferred_model` can be a string or a proc that provides dynamic model selection based on MCP server characteristics
+
+The `preferred_model` proc receives model preferences from the MCP server, allowing you to make intelligent model selection decisions based on the server's requirements for success.
+
 ## Transport Types
 
 ### SSE (Server-Sent Events)

lib/ruby_llm/chat.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-# This is an override of the RubyLLM::Chat class to convient methods for easy MCP support
+# This is an override of the RubyLLM::Chat class to add convenient methods to more
+# easily work with the MCP clients.
 module RubyLLM
   class Chat
     def with_resources(*resources, **args)

lib/ruby_llm/mcp.rb

@@ -4,15 +4,6 @@
 require "zeitwerk"
 require_relative "chat"
 
-loader = Zeitwerk::Loader.for_gem_extension(RubyLLM)
-loader.inflector.inflect("mcp" => "MCP")
-loader.inflector.inflect("sse" => "SSE")
-loader.inflector.inflect("openai" => "OpenAI")
-loader.inflector.inflect("streamable_http" => "StreamableHTTP")
-
-loader.setup
-loader.eager_load
-
 module RubyLLM
   module MCP
     module_function
@@ -43,3 +34,11 @@ def logger
     end
   end
 end
+
+loader = Zeitwerk::Loader.for_gem_extension(RubyLLM)
+loader.inflector.inflect("mcp" => "MCP")
+loader.inflector.inflect("sse" => "SSE")
+loader.inflector.inflect("openai" => "OpenAI")
+loader.inflector.inflect("streamable_http" => "StreamableHTTP")
+
+loader.setup

lib/ruby_llm/mcp/client.rb

@@ -7,7 +7,7 @@ module MCP
     class Client
       extend Forwardable
 
-      attr_reader :name, :config, :transport_type, :request_timeout, :log_level, :on
+      attr_reader :name, :config, :transport_type, :request_timeout, :log_level, :on, :roots
 
       def initialize(name:, transport_type:, start: true, request_timeout: MCP.config.request_timeout, config: {})
         @name = name
@@ -25,10 +25,13 @@ def initialize(name:, transport_type:, start: true, request_timeout: MCP.config.
 
         @log_level = nil
 
+        setup_roots
+        setup_sampling
+
         @coordinator.start_transport if start
       end
 
-      def_delegators :@coordinator, :alive?, :capabilities, :ping
+      def_delegators :@coordinator, :alive?, :capabilities, :ping, :client_capabilities
 
       def start
         @coordinator.start_transport
@@ -165,6 +168,15 @@ def on_logging(level: Logging::WARNING, logger: nil, &block)
         self
       end
 
+      def sampling_callback_enabled?
+        @on.key?(:sampling) && !@on[:sampling].nil?
+      end
+
+      def on_sampling(&block)
+        @on[:sampling] = block
+        self
+      end
+
       private
 
       def setup_coordinator
@@ -187,6 +199,14 @@ def build_map(raw_data, klass)
           acc[instance.name] = instance
         end
       end
+
+      def setup_roots
+        @roots = Roots.new(paths: MCP.config.roots, coordinator: @coordinator)
+      end
+
+      def setup_sampling
+        @on[:sampling] = MCP.config.sampling.guard
+      end
     end
   end
 end

lib/ruby_llm/mcp/configuration.rb

@@ -3,12 +3,48 @@
 module RubyLLM
   module MCP
     class Configuration
-      attr_accessor :request_timeout, :log_file, :log_level, :has_support_complex_parameters
+      class Sampling
+        attr_accessor :enabled
+        attr_writer :preferred_model
+
+        def initialize
+          set_defaults
+        end
+
+        def reset!
+          set_defaults
+        end
+
+        def guard(&block)
+          @guard = block if block_given?
+          @guard
+        end
+
+        def preferred_model(&block)
+          @preferred_model = block if block_given?
+          @preferred_model
+        end
+
+        def enabled?
+          @enabled
+        end
+
+        private
+
+        def set_defaults
+          @enabled = false
+          @preferred_model = nil
+          @guard = nil
+        end
+      end
+
+      attr_accessor :request_timeout, :log_file, :log_level, :has_support_complex_parameters, :roots, :sampling
       attr_writer :logger
 
       REQUEST_TIMEOUT_DEFAULT = 8000
 
       def initialize
+        @sampling = Sampling.new
         set_defaults
       end
 
@@ -60,6 +96,9 @@ def set_defaults
         @log_level = ENV["RUBYLLM_MCP_DEBUG"] ? Logger::DEBUG : Logger::INFO
         @has_support_complex_parameters = false
         @logger = nil
+        @roots = []
+
+        @sampling.reset!
       end
     end
   end