ruby-mcp-client 0.8.0 → 0.9.0

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)
@@ -161,26 +168,34 @@ module MCPClient
     end
 
     # List all resources available from the MCP server
-    # @return [Array<MCPClient::Resource>] list of available resources
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resources array and optional nextCursor
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource listing
-    def list_resources
+    def list_resources(cursor: nil)
       @mutex.synchronize do
-        return @resources if @resources
+        return @resources_result if @resources_result && !cursor
       end
 
       begin
         ensure_initialized
 
-        resources_data = request_resources_list
+        params = {}
+        params['cursor'] = cursor if cursor
+        result = rpc_request('resources/list', params)
+
+        resources = (result['resources'] || []).map do |resource_data|
+          MCPClient::Resource.from_json(resource_data, server: self)
+        end
+
+        resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+
         @mutex.synchronize do
-          @resources = resources_data.map do |resource_data|
-            MCPClient::Resource.from_json(resource_data, server: self)
-          end
+          @resources_result = resources_result unless cursor
         end
 
-        @mutex.synchronize { @resources }
+        resources_result
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -191,15 +206,15 @@ module MCPClient
 
     # Read a resource by its URI
     # @param uri [String] the URI of the resource to read
-    # @return [Object] the resource contents
+    # @return [Array<MCPClient::ResourceContent>] array of resource contents
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource reading
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def read_resource(uri)
-      rpc_request('resources/read', {
-                    uri: uri
-                  })
+      result = rpc_request('resources/read', { uri: uri })
+      contents = result['contents'] || []
+      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -208,6 +223,58 @@ module MCPClient
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{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
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
+    def list_resource_templates(cursor: nil)
+      ensure_initialized
+      params = {}
+      params['cursor'] = cursor if cursor
+      result = rpc_request('resources/templates/list', params)
+
+      templates = (result['resourceTemplates'] || []).map do |template_data|
+        MCPClient::ResourceTemplate.from_json(template_data, server: self)
+      end
+
+      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+    end
+
+    # Subscribe to resource updates
+    # @param uri [String] the URI of the resource to subscribe to
+    # @return [Boolean] true if subscription successful
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
+    def subscribe_resource(uri)
+      ensure_initialized
+      rpc_request('resources/subscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
+    end
+
+    # Unsubscribe from resource updates
+    # @param uri [String] the URI of the resource to unsubscribe from
+    # @return [Boolean] true if unsubscription successful
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
+    def unsubscribe_resource(uri)
+      ensure_initialized
+      rpc_request('resources/unsubscribe', { uri: uri })
+      true
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
+    end
+
     # List all tools available from the MCP server
     # @return [Array<MCPClient::Tool>] list of available tools
     # @raise [MCPClient::Errors::ServerError] if server returns an error
@@ -349,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/json_rpc_transport.rb

@@ -34,6 +34,11 @@ module MCPClient
           raise MCPClient::Errors::ConnectionError, "Initialize failed: #{err['message']}"
         end
 
+        # Store server info and capabilities
+        result = res['result'] || {}
+        @server_info = result['serverInfo']
+        @capabilities = result['capabilities']
+
         # Send initialized notification
         notif = build_jsonrpc_notification('notifications/initialized', {})
         @stdin.puts(notif.to_json)

data/lib/mcp_client/server_stdio.rb

@@ -39,13 +39,24 @@ module MCPClient
       @next_id = 1
       @pending = {}
       @initialized = false
+      @server_info = nil
+      @capabilities = nil
       initialize_logger(logger)
       @max_retries   = retries
       @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
+    # @return [Hash, nil] Server information
+    attr_reader :server_info
+
+    # Server capabilities from the initialize response
+    # @return [Hash, nil] Server capabilities
+    attr_reader :capabilities
+
     # Connect to the MCP server by launching the command process via stdin/stdout
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
@@ -85,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
 
@@ -149,27 +168,32 @@ module MCPClient
     end
 
     # List all resources available from the MCP server
-    # @return [Array<MCPClient::Resource>] list of available resources
+    # @param cursor [String, nil] optional cursor for pagination
+    # @return [Hash] result containing resources array and optional nextCursor
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource listing
-    def list_resources
+    def list_resources(cursor: nil)
       ensure_initialized
       req_id = next_id
-      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'resources/list', 'params' => {} }
+      params = {}
+      params['cursor'] = cursor if cursor
+      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'resources/list', 'params' => params }
       send_request(req)
       res = wait_response(req_id)
       if (err = res['error'])
         raise MCPClient::Errors::ServerError, err['message']
       end
 
-      (res.dig('result', 'resources') || []).map { |td| MCPClient::Resource.from_json(td, server: self) }
+      result = res['result'] || {}
+      resources = (result['resources'] || []).map { |td| MCPClient::Resource.from_json(td, server: self) }
+      { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error listing resources: #{e.message}"
     end
 
     # Read a resource by its URI
     # @param uri [String] the URI of the resource to read
-    # @return [Object] the resource contents
+    # @return [Array<MCPClient::ResourceContent>] array of resource contents
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource reading
     def read_resource(uri)
@@ -188,11 +212,87 @@ module MCPClient
         raise MCPClient::Errors::ServerError, err['message']
       end
 
-      res['result']
+      result = res['result'] || {}
+      contents = result['contents'] || []
+      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{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
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
+    def list_resource_templates(cursor: nil)
+      ensure_initialized
+      req_id = next_id
+      params = {}
+      params['cursor'] = cursor if cursor
+      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'resources/templates/list', 'params' => params }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      result = res['result'] || {}
+      templates = (result['resourceTemplates'] || []).map { |td| MCPClient::ResourceTemplate.from_json(td, server: self) }
+      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+    end
+
+    # Subscribe to resource updates
+    # @param uri [String] the URI of the resource to subscribe to
+    # @return [Boolean] true if subscription successful
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
+    def subscribe_resource(uri)
+      ensure_initialized
+      req_id = next_id
+      req = {
+        'jsonrpc' => '2.0',
+        'id' => req_id,
+        'method' => 'resources/subscribe',
+        'params' => { 'uri' => uri }
+      }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      true
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
+    end
+
+    # Unsubscribe from resource updates
+    # @param uri [String] the URI of the resource to unsubscribe from
+    # @return [Boolean] true if unsubscription successful
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
+    def unsubscribe_resource(uri)
+      ensure_initialized
+      req_id = next_id
+      req = {
+        'jsonrpc' => '2.0',
+        'id' => req_id,
+        'method' => 'resources/unsubscribe',
+        'params' => { 'uri' => uri }
+      }
+      send_request(req)
+      res = wait_response(req_id)
+      if (err = res['error'])
+        raise MCPClient::Errors::ServerError, err['message']
+      end
+
+      true
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
+    end
+
     # List all tools available from the MCP server
     # @return [Array<MCPClient::Tool>] list of available tools
     # @raise [MCPClient::Errors::ServerError] if server returns an error
@@ -240,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')