ruby-mcp-client 0.8.1 → 0.9.1

data/lib/mcp_client/client.rb

@@ -16,12 +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
-    def initialize(mcp_server_configs: [], logger: nil)
+    # @param elicitation_handler [Proc, nil] optional handler for elicitation requests (MCP 2025-06-18)
+    # @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" }
@@ -34,6 +39,12 @@ module MCPClient
       @resource_cache = {}
       # JSON-RPC notification listeners
       @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|
@@ -42,6 +53,14 @@ module MCPClient
           # Invoke user-defined listeners
           @notification_listeners.each { |cb| cb.call(server, method, params) }
         end
+        # Register elicitation handler on each server
+        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
 
@@ -323,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
@@ -346,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|
@@ -452,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
@@ -473,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]
@@ -598,5 +682,177 @@ module MCPClient
               "Error reading resource '#{uri}': #{e.message} (Server: #{server_id})"
       end
     end
+
+    # Handle elicitation request from server (MCP 2025-06-18)
+    # @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)
+      # If no handler is configured, decline the request
+      unless @elicitation_handler
+        @logger.warn('Received elicitation request but no handler configured, declining')
+        return { 'action' => 'decline' }
+      end
+
+      message = params['message']
+      schema = params['schema'] || params['requestedSchema']
+      metadata = params['metadata']
+
+      begin
+        # Call the user-defined handler
+        result = case @elicitation_handler.arity
+                 when 0
+                   @elicitation_handler.call
+                 when 1
+                   @elicitation_handler.call(message)
+                 when 2, -1
+                   @elicitation_handler.call(message, schema)
+                 else
+                   @elicitation_handler.call(message, schema, metadata)
+                 end
+
+        # Validate and format response
+        case result
+        when Hash
+          if result['action']
+            normalised_action_response(result)
+          elsif result[:action]
+            # Convert symbol keys to strings
+            {
+              'action' => result[:action].to_s,
+              'content' => result[:content]
+            }.compact.then { |payload| normalised_action_response(payload) }
+          else
+            # Assume it's content for an accept action
+            { 'action' => 'accept', 'content' => result }
+          end
+        when nil
+          { 'action' => 'cancel' }
+        else
+          { 'action' => 'accept', 'content' => result }
+        end
+      rescue StandardError => e
+        @logger.error("Elicitation handler error: #{e.message}")
+        @logger.debug(e.backtrace.join("\n"))
+        { 'action' => 'decline' }
+      end
+    end
+
+    # Ensure the action value conforms to MCP spec (accept, decline, cancel)
+    # Falls back to accept for unknown action values.
+    def normalised_action_response(result)
+      action = result['action']
+      return result if %w[accept decline cancel].include?(action)
+
+      @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,9 +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' => {},
+        '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

@@ -76,7 +76,9 @@ module MCPClient
         retries: config[:retries] || 3,
         retry_backoff: config[:retry_backoff] || 1,
         name: config[:name],
-        logger: logger
+        logger: logger,
+        oauth_provider: config[:oauth_provider],
+        faraday_config: config[:faraday_config]
       )
     end
 
@@ -95,7 +97,9 @@ module MCPClient
         retries: config[:retries] || 3,
         retry_backoff: config[:retry_backoff] || 1,
         name: config[:name],
-        logger: logger
+        logger: logger,
+        oauth_provider: config[:oauth_provider],
+        faraday_config: config[:faraday_config]
       )
     end
 

data/lib/mcp_client/server_http.rb

@@ -12,6 +12,14 @@ module MCPClient
   # Implementation of MCP server that communicates via HTTP requests/responses
   # Useful for communicating with MCP servers that support HTTP-based transport
   # without Server-Sent Events streaming
+  #
+  # @note Elicitation Support (MCP 2025-06-18)
+  #   This transport does NOT support server-initiated elicitation requests.
+  #   The HTTP transport uses a pure request-response architecture where only the client
+  #   can initiate requests. For elicitation support, use one of these transports instead:
+  #   - ServerStdio: Full bidirectional JSON-RPC over stdin/stdout
+  #   - ServerSSE: Server requests via SSE stream, client responses via HTTP POST
+  #   - ServerStreamableHTTP: Server requests via SSE-formatted responses, client responses via HTTP POST
   class ServerHTTP < ServerBase
     require_relative 'server_http/json_rpc_transport'
 
@@ -47,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])
@@ -91,6 +100,7 @@ module MCPClient
                                       })
 
       @read_timeout = opts[:read_timeout]
+      @faraday_config = opts[:faraday_config]
       @tools = nil
       @tools_data = nil
       @request_id = 0
@@ -312,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
@@ -412,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/sse_parser.rb

@@ -31,6 +31,7 @@ module MCPClient
           data = JSON.parse(event[:data])
 
           return if process_error_in_message(data)
+          return if process_server_request?(data)
           return if process_notification?(data)
 
           process_response?(data)
@@ -58,6 +59,16 @@ module MCPClient
         true
       end
 
+      # Process a JSON-RPC request from server (has both id AND method)
+      # @param data [Hash] the parsed JSON payload
+      # @return [Boolean] true if we saw & handled a server request
+      def process_server_request?(data)
+        return false unless data['method'] && data.key?('id')
+
+        handle_server_request(data)
+        true
+      end
+
       # Process a JSON-RPC notification (no id => notification)
       # @param data [Hash] the parsed JSON payload
       # @return [Boolean] true if we saw & handled a notification