ruby-mcp-client 0.8.1 → 0.9.1

data/lib/mcp_client/server_sse.rb

@@ -11,6 +11,12 @@ require 'faraday/follow_redirects'
 module MCPClient
   # Implementation of MCP server that communicates via Server-Sent Events (SSE)
   # Useful for communicating with remote MCP servers over HTTP
+  #
+  # @note Elicitation Support (MCP 2025-06-18)
+  #   This transport FULLY supports server-initiated elicitation requests via bidirectional
+  #   JSON-RPC. The server sends elicitation/create requests via the SSE stream, and the
+  #   client responds via HTTP POST to the RPC endpoint. This provides full elicitation
+  #   capability for remote servers.
   class ServerSSE < ServerBase
     require_relative 'server_sse/sse_parser'
     require_relative 'server_sse/json_rpc_transport'
@@ -98,6 +104,9 @@ module MCPClient
       # Time of last activity
       @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)
@@ -300,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,
@@ -322,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
@@ -409,6 +441,225 @@ module MCPClient
       end
     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]
+    def on_elicitation_request(&block)
+      @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]
+    def handle_server_request(msg)
+      request_id = msg['id']
+      method = msg['method']
+      params = msg['params'] || {}
+
+      @logger.debug("Received server request: #{method} (id: #{request_id})")
+
+      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}")
+      end
+    rescue StandardError => e
+      @logger.error("Error handling server request: #{e.message}")
+      send_error_response(request_id, -32_603, "Internal error: #{e.message}")
+    end
+
+    # Handle elicitation/create request from server (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param params [Hash] the elicitation parameters
+    # @return [void]
+    def handle_elicitation_create(request_id, params)
+      # If no callback is registered, decline the request
+      unless @elicitation_request_callback
+        @logger.warn('Received elicitation request but no callback registered, declining')
+        send_elicitation_response(request_id, { 'action' => 'decline' })
+        return
+      end
+
+      # Call the registered callback
+      result = @elicitation_request_callback.call(request_id, params)
+
+      # Send the response back to the server
+      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)
+    # @return [void]
+    def send_elicitation_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 elicitation response: #{e.message}")
+    end
+
+    # Send error response back to server via HTTP POST (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param code [Integer] the error code
+    # @param message [String] the error message
+    # @return [void]
+    def send_error_response(request_id, code, message)
+      ensure_initialized
+
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'error' => {
+          'code' => code,
+          'message' => message
+        }
+      }
+
+      # Send response via HTTP POST to the RPC endpoint
+      post_jsonrpc_response(response)
+    rescue StandardError => e
+      @logger.error("Error sending error response: #{e.message}")
+    end
+
+    # Post a JSON-RPC response message to the server via HTTP
+    # @param response [Hash] the JSON-RPC response
+    # @return [void]
+    # @private
+    def post_jsonrpc_response(response)
+      unless @rpc_endpoint
+        @logger.error('Cannot send response: RPC endpoint not available')
+        return
+      end
+
+      # Use the same connection pattern as post_json_rpc_request
+      uri = URI.parse(@base_url)
+      base = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+      @rpc_conn ||= create_json_rpc_connection(base)
+
+      json_body = JSON.generate(response)
+
+      @rpc_conn.post do |req|
+        req.url @rpc_endpoint
+        req.headers['Content-Type'] = 'application/json'
+        @headers.each { |k, v| req.headers[k] = v }
+        req.body = json_body
+      end
+
+      @logger.debug("Sent response via HTTP POST: #{json_body}")
+    rescue StandardError => e
+      @logger.error("Failed to send response via HTTP POST: #{e.message}")
+    end
+
     private
 
     # Start the SSE thread to listen for events

data/lib/mcp_client/server_stdio.rb

@@ -46,6 +46,9 @@ module MCPClient
       @retry_backoff = retry_backoff
       @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-06-18
     end
 
     # Server info from the initialize response
@@ -95,12 +98,20 @@ module MCPClient
     def handle_line(line)
       msg = JSON.parse(line)
       @logger.debug("Received line: #{line.chomp}")
+
+      # Dispatch JSON-RPC requests from server (has id AND method) - MCP 2025-06-18
+      if msg['method'] && msg.key?('id')
+        handle_server_request(msg)
+        return
+      end
+
       # Dispatch JSON-RPC notifications (no id, has method)
       if msg['method'] && !msg.key?('id')
         @notification_callback&.call(msg['method'], msg['params'])
         return
       end
-      # Handle standard JSON-RPC responses
+
+      # Handle standard JSON-RPC responses (has id, no method)
       id = msg['id']
       return unless id
 
@@ -331,6 +342,234 @@ 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:)
+      ensure_initialized
+      req_id = next_id
+      req = {
+        'jsonrpc' => '2.0',
+        'id' => req_id,
+        'method' => 'completion/complete',
+        'params' => { 'ref' => ref, 'argument' => argument }
+      }
+      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]
+    def on_elicitation_request(&block)
+      @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]
+    def handle_server_request(msg)
+      request_id = msg['id']
+      method = msg['method']
+      params = msg['params'] || {}
+
+      @logger.debug("Received server request: #{method} (id: #{request_id})")
+
+      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}")
+      end
+    rescue StandardError => e
+      @logger.error("Error handling server request: #{e.message}")
+      send_error_response(request_id, -32_603, "Internal error: #{e.message}")
+    end
+
+    # Handle elicitation/create request from server (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param params [Hash] the elicitation parameters
+    # @return [void]
+    def handle_elicitation_create(request_id, params)
+      # If no callback is registered, decline the request
+      unless @elicitation_request_callback
+        @logger.warn('Received elicitation request but no callback registered, declining')
+        send_elicitation_response(request_id, { 'action' => 'decline' })
+        return
+      end
+
+      # Call the registered callback
+      result = @elicitation_request_callback.call(request_id, params)
+
+      # Send the response back to the server
+      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-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 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-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)
+      # 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)
+    # @return [void]
+    def send_elicitation_response(request_id, result)
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'result' => result
+      }
+      send_message(response)
+    end
+
+    # Send error response back to server (MCP 2025-06-18)
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @param code [Integer] the error code
+    # @param message [String] the error message
+    # @return [void]
+    def send_error_response(request_id, code, message)
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'error' => {
+          'code' => code,
+          'message' => message
+        }
+      }
+      send_message(response)
+    end
+
+    # Send a JSON-RPC message to the server
+    # @param message [Hash] the message to send
+    # @return [void]
+    def send_message(message)
+      json = JSON.generate(message)
+      @stdin.puts(json)
+      @stdin.flush
+      @logger.debug("Sent message: #{json}")
+    rescue StandardError => e
+      @logger.error("Error sending message: #{e.message}")
+    end
+
     # Clean up the server connection
     # Closes all stdio handles and terminates any running processes and threads
     # @return [void]

data/lib/mcp_client/server_streamable_http/json_rpc_transport.rb

@@ -2,6 +2,9 @@
 
 require_relative '../http_transport_base'
 
+require 'zlib'
+require 'stringio'
+
 module MCPClient
   class ServerStreamableHTTP
     # JSON-RPC request/notification plumbing for Streamable HTTP transport
@@ -23,8 +26,12 @@ module MCPClient
       # @raise [MCPClient::Errors::TransportError] if parsing fails
       # @raise [MCPClient::Errors::ServerError] if the response contains an error
       def parse_response(response)
-        body = response.body.strip
+        body = response.body
         content_type = response.headers['content-type'] || response.headers['Content-Type'] || ''
+        content_encoding = response.headers['content-encoding'] || response.headers['Content-Encoding'] || ''
+
+        body = Zlib::GzipReader.new(StringIO.new(body)).read if content_encoding.include?('gzip')
+        body = body&.strip
 
         # Determine response format based on Content-Type header per MCP 2025 spec
         data = if content_type.include?('text/event-stream')