ruby-mcp-client 0.8.1 → 0.9.0

data/lib/mcp_client/client.rb

@@ -21,7 +21,8 @@ module MCPClient
     # 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)
+    def initialize(mcp_server_configs: [], logger: nil, elicitation_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 +35,8 @@ module MCPClient
       @resource_cache = {}
       # JSON-RPC notification listeners
       @notification_listeners = []
+      # Elicitation handler (MCP 2025-06-18)
+      @elicitation_handler = elicitation_handler
       # Register default and user-defined notification handlers on each server
       @servers.each do |server|
         server.on_notification do |method, params|
@@ -42,6 +45,10 @@ 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
       end
     end
 
@@ -598,5 +605,70 @@ 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
+    # @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
   end
 end

data/lib/mcp_client/json_rpc_common.rb

@@ -64,7 +64,9 @@ module MCPClient
     def initialization_params
       {
         'protocolVersion' => MCPClient::PROTOCOL_VERSION,
-        'capabilities' => {},
+        'capabilities' => {
+          'elicitation' => {} # MCP 2025-06-18: Support for server-initiated user interactions
+        },
         'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
       }
     end

data/lib/mcp_client/server_factory.rb

@@ -76,7 +76,8 @@ module MCPClient
         retries: config[:retries] || 3,
         retry_backoff: config[:retry_backoff] || 1,
         name: config[:name],
-        logger: logger
+        logger: logger,
+        oauth_provider: config[:oauth_provider]
       )
     end
 
@@ -95,7 +96,8 @@ module MCPClient
         retries: config[:retries] || 3,
         retry_backoff: config[:retry_backoff] || 1,
         name: config[:name],
-        logger: logger
+        logger: logger,
+        oauth_provider: config[:oauth_provider]
       )
     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'
 

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

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,7 @@ module MCPClient
       # Time of last activity
       @last_activity_time = Time.now
       @activity_timer_thread = nil
+      @elicitation_request_callback = nil # MCP 2025-06-18
     end
 
     # Stream tool call fallback for SSE transport (yields single result)
@@ -409,6 +416,125 @@ 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
+
+    # 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)
+      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
+
+    # 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,7 @@ module MCPClient
       @retry_backoff = retry_backoff
       @read_timeout  = read_timeout
       @env           = env || {}
+      @elicitation_request_callback = nil # MCP 2025-06-18
     end
 
     # Server info from the initialize response
@@ -95,12 +96,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 +340,96 @@ module MCPClient
       raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{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
+
+    # 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)
+      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
+
+    # 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')

data/lib/mcp_client/server_streamable_http.rb

@@ -9,9 +9,9 @@ require 'faraday/retry'
 require 'faraday/follow_redirects'
 
 module MCPClient
-  # Implementation of MCP server that communicates via Streamable HTTP transport (MCP 2025-03-26)
+  # Implementation of MCP server that communicates via Streamable HTTP transport (MCP 2025-06-18)
   # This transport uses HTTP POST for RPC calls with optional SSE responses, and GET for event streams
-  # Compliant with MCP specification version 2025-03-26
+  # Compliant with MCP specification version 2025-06-18
   #
   # Key features:
   # - Supports server-sent events (SSE) for real-time notifications
@@ -91,7 +91,7 @@ module MCPClient
       @headers = opts[:headers].merge({
                                         'Content-Type' => 'application/json',
                                         'Accept' => 'text/event-stream, application/json',
-                                        'Accept-Encoding' => 'gzip, deflate',
+                                        'Accept-Encoding' => 'gzip',
                                         'User-Agent' => "ruby-mcp-client/#{MCPClient::VERSION}",
                                         'Cache-Control' => 'no-cache'
                                       })
@@ -116,6 +116,7 @@ module MCPClient
       @events_connection = nil
       @events_thread = nil
       @buffer = '' # Buffer for partial SSE event data
+      @elicitation_request_callback = nil # MCP 2025-06-18
     end
 
     # Connect to the MCP server over Streamable HTTP
@@ -451,6 +452,13 @@ 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
+
     private
 
     def perform_initialize
@@ -755,12 +763,12 @@ module MCPClient
         # Handle ping requests from server (keepalive mechanism)
         if message['method'] == 'ping' && message.key?('id')
           handle_ping_request(message['id'])
+        elsif message['method'] && message.key?('id')
+          # Handle server-to-client requests (MCP 2025-06-18)
+          handle_server_request(message)
         elsif message['method'] && !message.key?('id')
           # Handle server notifications (messages without id)
           @notification_callback&.call(message['method'], message['params'])
-        elsif message.key?('id')
-          # This might be a server-to-client request (future MCP versions)
-          @logger.warn("Received unhandled server request: #{message['method']}")
         end
       rescue JSON::ParserError => e
         @logger.error("Invalid JSON in server message: #{e.message}")
@@ -796,5 +804,123 @@ module MCPClient
         @logger.error("Failed to send pong response: #{e.message}")
       end
     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)
+      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 (used as elicitationId)
+    # @param params [Hash] the elicitation parameters
+    # @return [void]
+    def handle_elicitation_create(request_id, params)
+      # The request_id is the elicitationId per MCP spec
+      elicitation_id = request_id
+
+      # 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(elicitation_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(elicitation_id, result)
+    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.
+    # @param elicitation_id [String] the elicitation ID from the server
+    # @param result [Hash] the elicitation result (action and optional content)
+    # @return [void]
+    def send_elicitation_response(elicitation_id, result)
+      params = {
+        'elicitationId' => elicitation_id,
+        'action' => result['action']
+      }
+
+      # Only include content if present (typically for 'accept' action)
+      params['content'] = result['content'] if result['content']
+
+      request = {
+        'jsonrpc' => '2.0',
+        'method' => 'elicitation/response',
+        'params' => params
+      }
+
+      # Send as a JSON-RPC request via HTTP POST
+      post_jsonrpc_response(request)
+    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)
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'error' => {
+          'code' => code,
+          'message' => message
+        }
+      }
+
+      # Send response via HTTP POST to the 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)
+      # Send response in a separate thread to avoid blocking event processing
+      Thread.new do
+        conn = http_connection
+        json_body = JSON.generate(response)
+
+        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.body = json_body
+        end
+
+        if resp.success?
+          @logger.debug("Sent JSON-RPC response: #{json_body}")
+        else
+          @logger.warn("Failed to send JSON-RPC response: HTTP #{resp.status}")
+        end
+      rescue StandardError => e
+        @logger.error("Failed to send JSON-RPC response: #{e.message}")
+      end
+    end
   end
 end