ruby-mcp-client 0.9.0 → 1.0.0

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-11-25
     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,36 @@ 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' })
+    # @param context [Hash, nil] optional context for the completion (MCP 2025-11-25)
+    # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def complete(ref:, argument:, context: nil)
+      params = { ref: ref, argument: argument }
+      params[:context] = context if context
+      result = rpc_request('completion/complete', params)
+      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 +451,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-11-25)
+    # @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 +478,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 +510,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-11-25)
+    # @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-11-25)
+    # @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)

data/lib/mcp_client/server_stdio.rb

@@ -47,6 +47,8 @@ module MCPClient
       @read_timeout  = read_timeout
       @env           = env || {}
       @elicitation_request_callback = nil # MCP 2025-06-18
+      @roots_list_request_callback = nil # MCP 2025-06-18
+      @sampling_request_callback = nil # MCP 2025-11-25
     end
 
     # Server info from the initialize response
@@ -340,6 +342,59 @@ 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' })
+    # @param context [Hash, nil] optional context for the completion (MCP 2025-11-25)
+    # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def complete(ref:, argument:, context: nil)
+      ensure_initialized
+      req_id = next_id
+      params = { 'ref' => ref, 'argument' => argument }
+      params['context'] = context if context
+      req = {
+        'jsonrpc' => '2.0',
+        'id' => req_id,
+        'method' => 'completion/complete',
+        'params' => params
+      }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      res.dig('result', 'completion') || { 'values' => [] }
+    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)
+      ensure_initialized
+      req_id = next_id
+      req = {
+        'jsonrpc' => '2.0',
+        'id' => req_id,
+        'method' => 'logging/setLevel',
+        'params' => { 'level' => level }
+      }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      res['result'] || {}
+    rescue StandardError => e
+      raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
+    end
+
     # Register a callback for elicitation requests (MCP 2025-06-18)
     # @param block [Proc] callback that receives (request_id, params) and returns response hash
     # @return [void]
@@ -347,6 +402,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-11-25)
+    # @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]
@@ -360,6 +429,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}")
@@ -388,6 +461,76 @@ 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
+
+    # Handle sampling/createMessage request from server (MCP 2025-11-25)
+    # @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 roots/list response back to server (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)
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'result' => result
+      }
+      send_message(response)
+    end
+
+    # Send sampling response back to server (MCP 2025-11-25)
+    # @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)
+      # 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_message(response)
+    end
+
     # Send elicitation response back to server (MCP 2025-06-18)
     # @param request_id [String, Integer] the JSON-RPC request ID
     # @param result [Hash] the elicitation result (action and optional content)

data/lib/mcp_client/server_streamable_http.rb

@@ -97,6 +97,7 @@ module MCPClient
                                       })
 
       @read_timeout = opts[:read_timeout]
+      @faraday_config = opts[:faraday_config]
       @tools = nil
       @tools_data = nil
       @prompts = nil
@@ -117,6 +118,8 @@ module MCPClient
       @events_thread = nil
       @buffer = '' # Buffer for partial SSE event data
       @elicitation_request_callback = nil # MCP 2025-06-18
+      @roots_list_request_callback = nil # MCP 2025-06-18
+      @sampling_request_callback = nil # MCP 2025-11-25
     end
 
     # Connect to the MCP server over Streamable HTTP
@@ -216,6 +219,36 @@ module MCPClient
       end
     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' })
+    # @param context [Hash, nil] optional context for the completion (MCP 2025-11-25)
+    # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def complete(ref:, argument:, context: nil)
+      params = { ref: ref, argument: argument }
+      params[:context] = context if context
+      result = rpc_request('completion/complete', params)
+      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 prompts available from the MCP server
     # @return [Array<MCPClient::Prompt>] list of available prompts
     # @raise [MCPClient::Errors::PromptGetError] if prompts list retrieval fails
@@ -363,10 +396,17 @@ module MCPClient
     def apply_request_headers(req, request)
       super
 
-      # Add session header if we have one (for non-initialize requests)
-      if @session_id && request['method'] != 'initialize'
-        req.headers['Mcp-Session-Id'] = @session_id
-        @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+      # Add session and protocol version headers for non-initialize requests
+      if request['method'] != 'initialize'
+        if @session_id
+          req.headers['Mcp-Session-Id'] = @session_id
+          @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+        end
+
+        if @protocol_version
+          req.headers['Mcp-Protocol-Version'] = @protocol_version
+          @logger.debug("Adding protocol version header: Mcp-Protocol-Version: #{@protocol_version}")
+        end
       end
 
       # Add Last-Event-ID header for resumability (if available)
@@ -459,6 +499,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-11-25)
+    # @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
+
     private
 
     def perform_initialize
@@ -483,7 +537,8 @@ module MCPClient
         retry_backoff: 1,
         name: nil,
         logger: nil,
-        oauth_provider: nil
+        oauth_provider: nil,
+        faraday_config: nil
       }
     end
 
@@ -629,6 +684,9 @@ module MCPClient
           end
         end
 
+        # Apply user's Faraday customizations after defaults
+        @faraday_config&.call(conn)
+
         @logger.debug("Establishing SSE events connection to #{@endpoint}") if @logger.level <= Logger::DEBUG
 
         response = conn.get(@endpoint) do |req|
@@ -682,6 +740,7 @@ module MCPClient
     def apply_events_headers(req)
       @headers.each { |k, v| req.headers[k] = v }
       req.headers['Mcp-Session-Id'] = @session_id if @session_id
+      req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
     end
 
     # Process event chunks from the server
@@ -792,6 +851,7 @@ module MCPClient
         response = conn.post(@endpoint) do |req|
           @headers.each { |k, v| req.headers[k] = v }
           req.headers['Mcp-Session-Id'] = @session_id if @session_id
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
           req.body = pong_response.to_json
         end
 
@@ -818,6 +878,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}")
@@ -849,6 +913,84 @@ module MCPClient
       send_elicitation_response(elicitation_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
+
+    # Handle sampling/createMessage request from server (MCP 2025-11-25)
+    # @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 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)
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'result' => result
+      }
+
+      # Send response via HTTP POST
+      post_jsonrpc_response(response)
+    rescue StandardError => e
+      @logger.error("Error sending roots/list response: #{e.message}")
+    end
+
+    # Send sampling response back to server via HTTP POST (MCP 2025-11-25)
+    # @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)
+      # 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
+      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)
     # For streamable HTTP, this is sent as a JSON-RPC request (not response)
     # because HTTP is unidirectional.
@@ -910,6 +1052,7 @@ module MCPClient
         resp = conn.post(@endpoint) do |req|
           @headers.each { |k, v| req.headers[k] = v }
           req.headers['Mcp-Session-Id'] = @session_id if @session_id
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
           req.body = json_body
         end