ruby-mcp-client 0.9.0 → 0.9.1

data/lib/mcp_client/client.rb

@@ -16,13 +16,17 @@ module MCPClient
     #   @return [Hash<String, MCPClient::Resource>] cache of resources by composite key (server_id:uri)
     # @!attribute [r] logger
     #   @return [Logger] logger for client operations
-    attr_reader :servers, :tool_cache, :prompt_cache, :resource_cache, :logger
+    # @!attribute [r] roots
+    #   @return [Array<MCPClient::Root>] list of MCP roots (MCP 2025-06-18)
+    attr_reader :servers, :tool_cache, :prompt_cache, :resource_cache, :logger, :roots
 
     # Initialize a new MCPClient::Client
     # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
     # @param logger [Logger, nil] optional logger, defaults to STDOUT
     # @param elicitation_handler [Proc, nil] optional handler for elicitation requests (MCP 2025-06-18)
-    def initialize(mcp_server_configs: [], logger: nil, elicitation_handler: nil)
+    # @param roots [Array<MCPClient::Root, Hash>, nil] optional list of roots (MCP 2025-06-18)
+    # @param sampling_handler [Proc, nil] optional handler for sampling requests (MCP 2025-06-18)
+    def initialize(mcp_server_configs: [], logger: nil, elicitation_handler: nil, roots: nil, sampling_handler: nil)
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
       @logger.progname = self.class.name
       @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
@@ -37,6 +41,10 @@ module MCPClient
       @notification_listeners = []
       # Elicitation handler (MCP 2025-06-18)
       @elicitation_handler = elicitation_handler
+      # Sampling handler (MCP 2025-06-18)
+      @sampling_handler = sampling_handler
+      # Roots (MCP 2025-06-18)
+      @roots = normalize_roots(roots)
       # Register default and user-defined notification handlers on each server
       @servers.each do |server|
         server.on_notification do |method, params|
@@ -49,6 +57,10 @@ module MCPClient
         if server.respond_to?(:on_elicitation_request)
           server.on_elicitation_request(&method(:handle_elicitation_request))
         end
+        # Register roots list handler on each server (MCP 2025-06-18)
+        server.on_roots_list_request(&method(:handle_roots_list_request)) if server.respond_to?(:on_roots_list_request)
+        # Register sampling handler on each server (MCP 2025-06-18)
+        server.on_sampling_request(&method(:handle_sampling_request)) if server.respond_to?(:on_sampling_request)
       end
     end
 
@@ -330,6 +342,16 @@ module MCPClient
       @notification_listeners << block
     end
 
+    # Set the roots for this client (MCP 2025-06-18)
+    # When roots are changed, a notification is sent to all connected servers
+    # @param new_roots [Array<MCPClient::Root, Hash>] the new roots to set
+    # @return [void]
+    def roots=(new_roots)
+      @roots = normalize_roots(new_roots)
+      # Notify servers that roots have changed
+      notify_roots_changed
+    end
+
     # Find a server by name
     # @param name [String] the name of the server to find
     # @return [MCPClient::ServerBase, nil] the server with the given name, or nil if not found
@@ -353,8 +375,10 @@ module MCPClient
     end
 
     # Call multiple tools in batch
-    # @param calls [Array<Hash>] array of calls in the form:
-    #   { name: tool_name, parameters: {...}, server: optional_server_name }
+    # @param calls [Array<Hash>] array of call hashes with keys:
+    #   - name: tool name (required)
+    #   - parameters: tool parameters (optional, default empty hash)
+    #   - server: server name for routing (optional)
     # @return [Array<Object>] array of results for each tool invocation
     def call_tools(calls)
       calls.map do |call|
@@ -459,6 +483,28 @@ module MCPClient
       srv.rpc_notify(method, params)
     end
 
+    # Request completion suggestions from a server (MCP 2025-06-18)
+    # @param ref [Hash] reference object (e.g., { 'type' => 'ref/prompt', 'name' => 'prompt_name' })
+    # @param argument [Hash] the argument being completed (e.g., { 'name' => 'arg_name', 'value' => 'partial' })
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def complete(ref:, argument:, server: nil)
+      srv = select_server(server)
+      srv.complete(ref: ref, argument: argument)
+    end
+
+    # Set the logging level on all connected servers (MCP 2025-06-18)
+    # To set on a specific server, use: client.find_server('name').log_level = 'debug'
+    # @param level [String] the log level ('debug', 'info', 'notice', 'warning', 'error',
+    #   'critical', 'alert', 'emergency')
+    # @return [Array<Hash>] results from servers
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def log_level=(level)
+      @servers.map { |srv| srv.log_level = level }
+    end
+
     private
 
     # Process incoming JSON-RPC notifications with default handlers
@@ -480,12 +526,43 @@ module MCPClient
       when 'notifications/resources/list_changed'
         logger.warn("[#{server_id}] Resource list has changed, clearing resource cache")
         @resource_cache.clear
+      when 'notifications/message'
+        # MCP 2025-06-18: Handle logging messages from server
+        handle_log_message(server_id, params)
       else
         # Log unknown notification types for debugging purposes
         logger.debug("[#{server_id}] Received unknown notification: #{method} - #{params}")
       end
     end
 
+    # Handle logging message notification from server (MCP 2025-06-18)
+    # @param server_id [String] server identifier for log prefix
+    # @param params [Hash] log message params (level, logger, data)
+    # @return [void]
+    def handle_log_message(server_id, params)
+      level = params['level'] || 'info'
+      logger_name = params['logger']
+      data = params['data']
+
+      # Format the message
+      prefix = logger_name ? "[#{server_id}:#{logger_name}]" : "[#{server_id}]"
+      message = data.is_a?(String) ? data : data.inspect
+
+      # Map MCP log levels to Ruby Logger levels
+      case level.to_s.downcase
+      when 'debug'
+        logger.debug("#{prefix} #{message}")
+      when 'info', 'notice'
+        logger.info("#{prefix} #{message}")
+      when 'warning'
+        logger.warn("#{prefix} #{message}")
+      when 'error', 'critical', 'alert', 'emergency'
+        logger.error("#{prefix} #{message}")
+      else
+        logger.info("#{prefix} [#{level}] #{message}")
+      end
+    end
+
     # Select a server based on index, name, type, or instance
     # @param server_arg [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [MCPClient::ServerBase]
@@ -607,7 +684,7 @@ module MCPClient
     end
 
     # Handle elicitation request from server (MCP 2025-06-18)
-    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param _request_id [String, Integer] the JSON-RPC request ID (unused at client layer)
     # @param params [Hash] the elicitation parameters
     # @return [Hash] the elicitation response
     def handle_elicitation_request(_request_id, params)
@@ -670,5 +747,112 @@ module MCPClient
       @logger.warn("Unknown elicitation action '#{action}', defaulting to accept")
       result.merge('action' => 'accept')
     end
+
+    # Normalize roots array - convert Hashes to Root objects (MCP 2025-06-18)
+    # @param roots [Array<MCPClient::Root, Hash>, nil] the roots to normalize
+    # @return [Array<MCPClient::Root>] normalized roots array
+    def normalize_roots(roots)
+      return [] if roots.nil?
+
+      roots.map do |root|
+        case root
+        when MCPClient::Root
+          root
+        when Hash
+          MCPClient::Root.from_json(root)
+        else
+          raise ArgumentError, "Invalid root type: #{root.class}. Expected MCPClient::Root or Hash."
+        end
+      end
+    end
+
+    # Handle roots/list request from server (MCP 2025-06-18)
+    # @param _request_id [String, Integer] the JSON-RPC request ID (unused, kept for callback signature)
+    # @param _params [Hash] the request parameters (unused)
+    # @return [Hash] the roots list response
+    def handle_roots_list_request(_request_id, _params)
+      { 'roots' => @roots.map(&:to_h) }
+    end
+
+    # Send notification to all servers that roots have changed (MCP 2025-06-18)
+    # @return [void]
+    def notify_roots_changed
+      @servers.each do |server|
+        server.rpc_notify('notifications/roots/list_changed', {})
+      rescue StandardError => e
+        server_id = server.name ? "#{server.class}[#{server.name}]" : server.class
+        @logger.warn("[#{server_id}] Failed to send roots/list_changed notification: #{e.message}")
+      end
+    end
+
+    # Handle sampling/createMessage request from server (MCP 2025-06-18)
+    # @param _request_id [String, Integer] the JSON-RPC request ID (unused, kept for callback signature)
+    # @param params [Hash] the sampling parameters (messages, modelPreferences, systemPrompt, maxTokens)
+    # @return [Hash] the sampling response (role, content, model, stopReason)
+    def handle_sampling_request(_request_id, params)
+      # If no handler is configured, return an error
+      unless @sampling_handler
+        @logger.warn('Received sampling request but no handler configured')
+        return { 'error' => { 'code' => -1, 'message' => 'Sampling not supported' } }
+      end
+
+      messages = params['messages'] || []
+      model_preferences = params['modelPreferences']
+      system_prompt = params['systemPrompt']
+      max_tokens = params['maxTokens']
+
+      begin
+        # Call the user-defined handler
+        result = case @sampling_handler.arity
+                 when 0
+                   @sampling_handler.call
+                 when 1
+                   @sampling_handler.call(messages)
+                 when 2
+                   @sampling_handler.call(messages, model_preferences)
+                 when 3
+                   @sampling_handler.call(messages, model_preferences, system_prompt)
+                 else
+                   @sampling_handler.call(messages, model_preferences, system_prompt, max_tokens)
+                 end
+
+        # Validate and format response
+        validate_sampling_response(result)
+      rescue StandardError => e
+        @logger.error("Sampling handler error: #{e.message}")
+        @logger.debug(e.backtrace.join("\n"))
+        { 'error' => { 'code' => -1, 'message' => "Sampling error: #{e.message}" } }
+      end
+    end
+
+    # Validate sampling response from handler (MCP 2025-06-18)
+    # @param result [Hash] the result from the sampling handler
+    # @return [Hash] validated sampling response
+    def validate_sampling_response(result)
+      return { 'error' => { 'code' => -1, 'message' => 'Sampling rejected' } } if result.nil?
+
+      # Convert symbol keys to string keys
+      result = result.transform_keys(&:to_s) if result.is_a?(Hash) && result.keys.first.is_a?(Symbol)
+
+      # Ensure required fields are present
+      unless result.is_a?(Hash) && result['content']
+        return {
+          'role' => 'assistant',
+          'content' => { 'type' => 'text', 'text' => result.to_s },
+          'model' => 'unknown',
+          'stopReason' => 'endTurn'
+        }
+      end
+
+      # Set defaults for missing fields
+      result['role'] ||= 'assistant'
+      result['model'] ||= 'unknown'
+      result['stopReason'] ||= 'endTurn'
+
+      # Normalize content if it's a string
+      result['content'] = { 'type' => 'text', 'text' => result['content'] } if result['content'].is_a?(String)
+
+      result
+    end
   end
 end

data/lib/mcp_client/errors.rb

@@ -47,5 +47,8 @@ module MCPClient
 
     # Raised when multiple resources with the same URI exist across different servers
     class AmbiguousResourceURI < MCPError; end
+
+    # Raised when transport type cannot be determined from target URL/command
+    class TransportDetectionError < MCPError; end
   end
 end

data/lib/mcp_client/http_transport_base.rb

@@ -256,14 +256,20 @@ module MCPClient
     end
 
     # Create a Faraday connection for HTTP requests
+    # Applies default configuration first, then allows user customization via @faraday_config block
     # @return [Faraday::Connection] the configured connection
     def create_http_connection
-      Faraday.new(url: @base_url) do |f|
+      conn = Faraday.new(url: @base_url) do |f|
         f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
         f.options.open_timeout = @read_timeout
         f.options.timeout = @read_timeout
         f.adapter Faraday.default_adapter
       end
+
+      # Apply user's Faraday customizations after defaults
+      @faraday_config&.call(conn)
+
+      conn
     end
 
     # Log HTTP response (to be overridden by specific transports)

data/lib/mcp_client/json_rpc_common.rb

@@ -62,11 +62,15 @@ module MCPClient
     # Generate initialization parameters for MCP protocol
     # @return [Hash] the initialization parameters
     def initialization_params
+      capabilities = {
+        'elicitation' => {}, # MCP 2025-06-18: Support for server-initiated user interactions
+        'roots' => { 'listChanged' => true }, # MCP 2025-06-18: Support for roots
+        'sampling' => {} # MCP 2025-06-18: Support for server-initiated LLM sampling
+      }
+
       {
         'protocolVersion' => MCPClient::PROTOCOL_VERSION,
-        'capabilities' => {
-          'elicitation' => {} # MCP 2025-06-18: Support for server-initiated user interactions
-        },
+        'capabilities' => capabilities,
         'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
       }
     end

data/lib/mcp_client/root.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Represents an MCP Root - a URI that defines a boundary where servers can operate
+  # Roots are declared by clients to inform servers about relevant resources and their locations
+  class Root
+    attr_reader :uri, :name
+
+    # Create a new Root
+    # @param uri [String] The URI for the root (typically file:// URI)
+    # @param name [String, nil] Optional human-readable name for display purposes
+    def initialize(uri:, name: nil)
+      @uri = uri
+      @name = name
+    end
+
+    # Create a Root from a JSON hash
+    # @param json [Hash] The JSON hash with 'uri' and optional 'name' keys
+    # @return [Root]
+    def self.from_json(json)
+      new(
+        uri: json['uri'] || json[:uri],
+        name: json['name'] || json[:name]
+      )
+    end
+
+    # Convert to JSON-serializable hash
+    # @return [Hash]
+    def to_h
+      result = { 'uri' => @uri }
+      result['name'] = @name if @name
+      result
+    end
+
+    # Convert to JSON string
+    # @return [String]
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    # Check equality
+    def ==(other)
+      return false unless other.is_a?(Root)
+
+      uri == other.uri && name == other.name
+    end
+
+    alias eql? ==
+
+    def hash
+      [uri, name].hash
+    end
+
+    # String representation
+    def to_s
+      name ? "#{name} (#{uri})" : uri
+    end
+
+    def inspect
+      "#<MCPClient::Root uri=#{uri.inspect} name=#{name.inspect}>"
+    end
+  end
+end

data/lib/mcp_client/server_factory.rb

@@ -77,7 +77,8 @@ module MCPClient
         retry_backoff: config[:retry_backoff] || 1,
         name: config[:name],
         logger: logger,
-        oauth_provider: config[:oauth_provider]
+        oauth_provider: config[:oauth_provider],
+        faraday_config: config[:faraday_config]
       )
     end
 
@@ -97,7 +98,8 @@ module MCPClient
         retry_backoff: config[:retry_backoff] || 1,
         name: config[:name],
         logger: logger,
-        oauth_provider: config[:oauth_provider]
+        oauth_provider: config[:oauth_provider],
+        faraday_config: config[:faraday_config]
       )
     end
 

data/lib/mcp_client/server_http.rb

@@ -55,6 +55,7 @@ module MCPClient
     # @option options [String, nil] :name Optional name for this server
     # @option options [Logger, nil] :logger Optional logger
     # @option options [MCPClient::Auth::OAuthProvider, nil] :oauth_provider Optional OAuth provider
+    # @option options [Proc, nil] :faraday_config Optional block to customize the Faraday connection
     def initialize(base_url:, **options)
       opts = default_options.merge(options)
       super(name: opts[:name])
@@ -99,6 +100,7 @@ module MCPClient
                                       })
 
       @read_timeout = opts[:read_timeout]
+      @faraday_config = opts[:faraday_config]
       @tools = nil
       @tools_data = nil
       @request_id = 0
@@ -320,6 +322,33 @@ module MCPClient
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     end
 
+    # Request completion suggestions from the server (MCP 2025-06-18)
+    # @param ref [Hash] reference to complete (prompt or resource)
+    # @param argument [Hash] the argument being completed (e.g., { 'name' => 'arg_name', 'value' => 'partial' })
+    # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def complete(ref:, argument:)
+      result = rpc_request('completion/complete', { ref: ref, argument: argument })
+      result['completion'] || { 'values' => [] }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
+    end
+
+    # Set the logging level on the server (MCP 2025-06-18)
+    # @param level [String] the log level ('debug', 'info', 'notice', 'warning', 'error',
+    #   'critical', 'alert', 'emergency')
+    # @return [Hash] empty result on success
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def log_level=(level)
+      rpc_request('logging/setLevel', { level: level })
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
+    end
+
     # List all resource templates available from the MCP server
     # @param cursor [String, nil] optional cursor for pagination
     # @return [Hash] result containing resourceTemplates array and optional nextCursor
@@ -420,7 +449,8 @@ module MCPClient
         retry_backoff: 1,
         name: nil,
         logger: nil,
-        oauth_provider: nil
+        oauth_provider: nil,
+        faraday_config: nil
       }
     end
 

data/lib/mcp_client/server_sse.rb

@@ -105,6 +105,8 @@ module MCPClient
       @last_activity_time = Time.now
       @activity_timer_thread = nil
       @elicitation_request_callback = nil # MCP 2025-06-18
+      @roots_list_request_callback = nil # MCP 2025-06-18
+      @sampling_request_callback = nil # MCP 2025-06-18
     end
 
     # Stream tool call fallback for SSE transport (yields single result)
@@ -307,15 +309,11 @@ module MCPClient
     # Call a tool with the given parameters
     # @param tool_name [String] the name of the tool to call
     # @param parameters [Hash] the parameters to pass to the tool
-    # @return [Object] the result of the tool invocation
+    # @return [Object] the result of the tool invocation (with string keys for backward compatibility)
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
-    # Call a tool with the given parameters
-    # @param tool_name [String] the name of the tool to call
-    # @param parameters [Hash] the parameters to pass to the tool
-    # @return [Object] the result of the tool invocation (with string keys for backward compatibility)
     def call_tool(tool_name, parameters)
       rpc_request('tools/call', {
                     name: tool_name,
@@ -329,6 +327,33 @@ module MCPClient
       raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
     end
 
+    # Request completion suggestions from the server (MCP 2025-06-18)
+    # @param ref [Hash] reference object (e.g., { 'type' => 'ref/prompt', 'name' => 'prompt_name' })
+    # @param argument [Hash] the argument being completed (e.g., { 'name' => 'arg_name', 'value' => 'partial' })
+    # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def complete(ref:, argument:)
+      result = rpc_request('completion/complete', { ref: ref, argument: argument })
+      result['completion'] || { 'values' => [] }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
+    end
+
+    # Set the logging level on the server (MCP 2025-06-18)
+    # @param level [String] the log level ('debug', 'info', 'notice', 'warning', 'error',
+    #   'critical', 'alert', 'emergency')
+    # @return [Hash] empty result on success
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def log_level=(level)
+      rpc_request('logging/setLevel', { level: level })
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
+    end
+
     # Connect to the MCP server over HTTP/HTTPS with SSE
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
@@ -423,6 +448,20 @@ module MCPClient
       @elicitation_request_callback = block
     end
 
+    # Register a callback for roots/list requests (MCP 2025-06-18)
+    # @param block [Proc] callback that receives (request_id, params) and returns response hash
+    # @return [void]
+    def on_roots_list_request(&block)
+      @roots_list_request_callback = block
+    end
+
+    # Register a callback for sampling requests (MCP 2025-06-18)
+    # @param block [Proc] callback that receives (request_id, params) and returns response hash
+    # @return [void]
+    def on_sampling_request(&block)
+      @sampling_request_callback = block
+    end
+
     # Handle incoming JSON-RPC request from server (MCP 2025-06-18)
     # @param msg [Hash] the JSON-RPC request message
     # @return [void]
@@ -436,6 +475,10 @@ module MCPClient
       case method
       when 'elicitation/create'
         handle_elicitation_create(request_id, params)
+      when 'roots/list'
+        handle_roots_list(request_id, params)
+      when 'sampling/createMessage'
+        handle_sampling_create_message(request_id, params)
       else
         # Unknown request method, send error response
         send_error_response(request_id, -32_601, "Method not found: #{method}")
@@ -464,6 +507,88 @@ module MCPClient
       send_elicitation_response(request_id, result)
     end
 
+    # Handle roots/list request from server (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param params [Hash] the request parameters
+    # @return [void]
+    def handle_roots_list(request_id, params)
+      # If no callback is registered, return empty roots list
+      unless @roots_list_request_callback
+        @logger.debug('Received roots/list request but no callback registered, returning empty list')
+        send_roots_list_response(request_id, { 'roots' => [] })
+        return
+      end
+
+      # Call the registered callback
+      result = @roots_list_request_callback.call(request_id, params)
+
+      # Send the response back to the server
+      send_roots_list_response(request_id, result)
+    end
+
+    # Send roots/list response back to server via HTTP POST (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param result [Hash] the roots list result
+    # @return [void]
+    def send_roots_list_response(request_id, result)
+      ensure_initialized
+
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'result' => result
+      }
+
+      # Send response via HTTP POST to the RPC endpoint
+      post_jsonrpc_response(response)
+    rescue StandardError => e
+      @logger.error("Error sending roots/list response: #{e.message}")
+    end
+
+    # Handle sampling/createMessage request from server (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param params [Hash] the sampling parameters
+    # @return [void]
+    def handle_sampling_create_message(request_id, params)
+      # If no callback is registered, return error
+      unless @sampling_request_callback
+        @logger.warn('Received sampling request but no callback registered, returning error')
+        send_error_response(request_id, -1, 'Sampling not supported')
+        return
+      end
+
+      # Call the registered callback
+      result = @sampling_request_callback.call(request_id, params)
+
+      # Send the response back to the server
+      send_sampling_response(request_id, result)
+    end
+
+    # Send sampling response back to server via HTTP POST (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param result [Hash] the sampling result (role, content, model, stopReason)
+    # @return [void]
+    def send_sampling_response(request_id, result)
+      ensure_initialized
+
+      # Check if result contains an error
+      if result.is_a?(Hash) && result['error']
+        send_error_response(request_id, result['error']['code'] || -1, result['error']['message'] || 'Sampling error')
+        return
+      end
+
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'result' => result
+      }
+
+      # Send response via HTTP POST to the RPC endpoint
+      post_jsonrpc_response(response)
+    rescue StandardError => e
+      @logger.error("Error sending sampling response: #{e.message}")
+    end
+
     # Send elicitation response back to server via HTTP POST (MCP 2025-06-18)
     # @param request_id [String, Integer] the JSON-RPC request ID
     # @param result [Hash] the elicitation result (action and optional content)