ruby-mcp-client 0.8.1 → 0.9.1

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,12 +91,13 @@ 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'
                                       })
 
       @read_timeout = opts[:read_timeout]
+      @faraday_config = opts[:faraday_config]
       @tools = nil
       @tools_data = nil
       @prompts = nil
@@ -116,6 +117,9 @@ module MCPClient
       @events_connection = nil
       @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-06-18
     end
 
     # Connect to the MCP server over Streamable HTTP
@@ -215,6 +219,33 @@ 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' })
+    # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def complete(ref:, argument:)
+      result = rpc_request('completion/complete', { ref: ref, argument: argument })
+      result['completion'] || { 'values' => [] }
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
+    end
+
+    # Set the logging level on the server (MCP 2025-06-18)
+    # @param level [String] the log level ('debug', 'info', 'notice', 'warning', 'error',
+    #   'critical', 'alert', 'emergency')
+    # @return [Hash] empty result on success
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def log_level=(level)
+      rpc_request('logging/setLevel', { level: level })
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
+    end
+
     # List all prompts available from the MCP server
     # @return [Array<MCPClient::Prompt>] list of available prompts
     # @raise [MCPClient::Errors::PromptGetError] if prompts list retrieval fails
@@ -451,6 +482,27 @@ 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
+
     private
 
     def perform_initialize
@@ -475,7 +527,8 @@ module MCPClient
         retry_backoff: 1,
         name: nil,
         logger: nil,
-        oauth_provider: nil
+        oauth_provider: nil,
+        faraday_config: nil
       }
     end
 
@@ -621,6 +674,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|
@@ -755,12 +811,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 +852,205 @@ 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)
+      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 (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
+
+    # 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 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-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 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.
+    # @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

data/lib/mcp_client/tool.rb

@@ -8,20 +8,28 @@ module MCPClient
     # @!attribute [r] description
     #   @return [String] the description of the tool
     # @!attribute [r] schema
-    #   @return [Hash] the JSON schema for the tool
+    #   @return [Hash] the JSON schema for the tool inputs
+    # @!attribute [r] output_schema
+    #   @return [Hash, nil] optional JSON schema for structured tool outputs (MCP 2025-06-18)
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations describing tool behavior (e.g., readOnly, destructive)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this tool belongs to
-    attr_reader :name, :description, :schema, :server
+    attr_reader :name, :description, :schema, :output_schema, :annotations, :server
 
     # Initialize a new Tool
     # @param name [String] the name of the tool
     # @param description [String] the description of the tool
-    # @param schema [Hash] the JSON schema for the tool
+    # @param schema [Hash] the JSON schema for the tool inputs
+    # @param output_schema [Hash, nil] optional JSON schema for structured tool outputs (MCP 2025-06-18)
+    # @param annotations [Hash, nil] optional annotations describing tool behavior
     # @param server [MCPClient::ServerBase, nil] the server this tool belongs to
-    def initialize(name:, description:, schema:, server: nil)
+    def initialize(name:, description:, schema:, output_schema: nil, annotations: nil, server: nil)
       @name = name
       @description = description
       @schema = schema
+      @output_schema = output_schema
+      @annotations = annotations
       @server = server
     end
 
@@ -33,10 +41,14 @@ module MCPClient
       # Some servers (Playwright MCP CLI) use 'inputSchema' instead of 'schema'
       # Handle both string and symbol keys
       schema = data['inputSchema'] || data[:inputSchema] || data['schema'] || data[:schema]
+      output_schema = data['outputSchema'] || data[:outputSchema]
+      annotations = data['annotations'] || data[:annotations]
       new(
         name: data['name'] || data[:name],
         description: data['description'] || data[:description],
         schema: schema,
+        output_schema: output_schema,
+        annotations: annotations,
         server: server
       )
     end
@@ -74,6 +86,30 @@ module MCPClient
       }
     end
 
+    # Check if the tool is marked as read-only
+    # @return [Boolean] true if the tool is read-only
+    def read_only?
+      @annotations && @annotations['readOnly'] == true
+    end
+
+    # Check if the tool is marked as destructive
+    # @return [Boolean] true if the tool is destructive
+    def destructive?
+      @annotations && @annotations['destructive'] == true
+    end
+
+    # Check if the tool requires confirmation before execution
+    # @return [Boolean] true if the tool requires confirmation
+    def requires_confirmation?
+      @annotations && @annotations['requiresConfirmation'] == true
+    end
+
+    # Check if the tool supports structured outputs (MCP 2025-06-18)
+    # @return [Boolean] true if the tool has an output schema defined
+    def structured_output?
+      !@output_schema.nil? && !@output_schema.empty?
+    end
+
     private
 
     # Recursively remove "$schema" keys that are not accepted by Vertex AI

data/lib/mcp_client/version.rb

@@ -2,8 +2,8 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '0.8.1'
+  VERSION = '0.9.1'
 
   # MCP protocol version (date-based) - unified across all transports
-  PROTOCOL_VERSION = '2025-03-26'
+  PROTOCOL_VERSION = '2025-06-18'
 end