ruby-mcp-client 0.9.0 → 1.0.0

data/lib/mcp_client/elicitation_validator.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Validates elicitation schemas and content per MCP 2025-11-25 spec.
+  # Schemas are restricted to flat objects with primitive property types:
+  #   string (with optional enum, pattern, format, minLength, maxLength)
+  #   number / integer (with optional minimum, maximum)
+  #   boolean
+  #   array (multi-select enum only, with items containing enum or anyOf)
+  module ElicitationValidator
+    # Allowed primitive types for schema properties
+    PRIMITIVE_TYPES = %w[string number integer boolean].freeze
+
+    # Allowed string formats per MCP spec
+    STRING_FORMATS = %w[email uri date date-time].freeze
+
+    # Validate that a requestedSchema conforms to MCP elicitation constraints.
+    # Returns an array of error messages (empty if valid).
+    # @param schema [Hash] the requestedSchema
+    # @return [Array<String>] validation errors
+    def self.validate_schema(schema)
+      errors = []
+      return errors unless schema.is_a?(Hash)
+
+      unless schema['type'] == 'object'
+        errors << "Schema type must be 'object', got '#{schema['type']}'"
+        return errors
+      end
+
+      properties = schema['properties']
+      return errors unless properties.is_a?(Hash)
+
+      properties.each do |name, prop|
+        errors.concat(validate_property(name, prop))
+      end
+
+      errors
+    end
+
+    # Validate a single property definition.
+    # @param name [String] property name
+    # @param prop [Hash] property schema
+    # @return [Array<String>] validation errors
+    def self.validate_property(name, prop)
+      errors = []
+      return errors unless prop.is_a?(Hash)
+
+      type = prop['type']
+
+      if type == 'array'
+        errors.concat(validate_array_property(name, prop))
+      elsif PRIMITIVE_TYPES.include?(type)
+        errors.concat(validate_primitive_property(name, prop))
+      else
+        errors << "Property '#{name}' has unsupported type '#{type}'"
+      end
+
+      errors
+    end
+
+    # Validate a primitive property (string, number, integer, boolean).
+    # @param name [String] property name
+    # @param prop [Hash] property schema
+    # @return [Array<String>] validation errors
+    def self.validate_primitive_property(name, prop)
+      errors = []
+      type = prop['type']
+
+      case type
+      when 'string'
+        if prop['format'] && !STRING_FORMATS.include?(prop['format'])
+          errors << "Property '#{name}' has unsupported format '#{prop['format']}'"
+        end
+        errors << "Property '#{name}' enum must be an array" if prop['enum'] && !prop['enum'].is_a?(Array)
+      when 'number', 'integer'
+        if prop.key?('minimum') && !prop['minimum'].is_a?(Numeric)
+          errors << "Property '#{name}' minimum must be numeric"
+        end
+        if prop.key?('maximum') && !prop['maximum'].is_a?(Numeric)
+          errors << "Property '#{name}' maximum must be numeric"
+        end
+      end
+
+      errors
+    end
+
+    # Validate an array property (multi-select enum only).
+    # @param name [String] property name
+    # @param prop [Hash] property schema
+    # @return [Array<String>] validation errors
+    def self.validate_array_property(name, prop)
+      errors = []
+      items = prop['items']
+
+      unless items.is_a?(Hash)
+        errors << "Property '#{name}' array type requires 'items' definition"
+        return errors
+      end
+
+      has_enum = items['enum'].is_a?(Array)
+      has_any_of = items['anyOf'].is_a?(Array)
+
+      errors << "Property '#{name}' array items must have 'enum' or 'anyOf'" unless has_enum || has_any_of
+
+      errors
+    end
+
+    # Validate content against a requestedSchema.
+    # Returns an array of error messages (empty if valid).
+    # @param content [Hash] the response content
+    # @param schema [Hash] the requestedSchema
+    # @return [Array<String>] validation errors
+    def self.validate_content(content, schema)
+      errors = []
+      return errors unless content.is_a?(Hash) && schema.is_a?(Hash)
+
+      properties = schema['properties'] || {}
+      required = Array(schema['required'])
+
+      # Check required fields
+      required.each do |field|
+        field_s = field.to_s
+        errors << "Missing required field '#{field_s}'" unless content.key?(field_s) || content.key?(field_s.to_sym)
+      end
+
+      # Validate each provided field
+      content.each do |field, value|
+        prop = properties[field.to_s]
+        next unless prop.is_a?(Hash)
+
+        errors.concat(validate_value(field.to_s, value, prop))
+      end
+
+      errors
+    end
+
+    # Validate a single value against its property schema.
+    # @param field [String] field name
+    # @param value [Object] the value to validate
+    # @param prop [Hash] property schema
+    # @return [Array<String>] validation errors
+    def self.validate_value(field, value, prop)
+      errors = []
+      type = prop['type']
+
+      case type
+      when 'string'
+        errors.concat(validate_string_value(field, value, prop))
+      when 'number', 'integer'
+        errors.concat(validate_number_value(field, value, prop))
+      when 'boolean'
+        errors << "Field '#{field}' must be a boolean" unless [true, false].include?(value)
+      when 'array'
+        errors.concat(validate_array_value(field, value, prop))
+      end
+
+      errors
+    end
+
+    # Validate a string value against its property schema.
+    # @param field [String] field name
+    # @param value [Object] the value
+    # @param prop [Hash] property schema
+    # @return [Array<String>] validation errors
+    def self.validate_string_value(field, value, prop)
+      errors = []
+
+      unless value.is_a?(String)
+        errors << "Field '#{field}' must be a string"
+        return errors
+      end
+
+      if prop['enum'].is_a?(Array) && !prop['enum'].include?(value)
+        errors << "Field '#{field}' must be one of: #{prop['enum'].join(', ')}"
+      end
+
+      if prop['oneOf'].is_a?(Array)
+        allowed = prop['oneOf'].map { |o| o['const'] }
+        errors << "Field '#{field}' must be one of: #{allowed.join(', ')}" unless allowed.include?(value)
+      end
+
+      if prop['pattern']
+        begin
+          unless value.match?(Regexp.new(prop['pattern']))
+            errors << "Field '#{field}' must match pattern '#{prop['pattern']}'"
+          end
+        rescue RegexpError
+          # Skip pattern validation if the pattern is invalid
+        end
+      end
+
+      if prop['minLength'] && value.length < prop['minLength']
+        errors << "Field '#{field}' must be at least #{prop['minLength']} characters"
+      end
+
+      if prop['maxLength'] && value.length > prop['maxLength']
+        errors << "Field '#{field}' must be at most #{prop['maxLength']} characters"
+      end
+
+      errors
+    end
+
+    # Validate a number value against its property schema.
+    # @param field [String] field name
+    # @param value [Object] the value
+    # @param prop [Hash] property schema
+    # @return [Array<String>] validation errors
+    def self.validate_number_value(field, value, prop)
+      errors = []
+
+      unless value.is_a?(Numeric)
+        errors << "Field '#{field}' must be a number"
+        return errors
+      end
+
+      errors << "Field '#{field}' must be an integer" if prop['type'] == 'integer' && !value.is_a?(Integer)
+
+      errors << "Field '#{field}' must be >= #{prop['minimum']}" if prop['minimum'] && value < prop['minimum']
+
+      errors << "Field '#{field}' must be <= #{prop['maximum']}" if prop['maximum'] && value > prop['maximum']
+
+      errors
+    end
+
+    # Validate an array value against its property schema (multi-select enum).
+    # @param field [String] field name
+    # @param value [Object] the value
+    # @param prop [Hash] property schema
+    # @return [Array<String>] validation errors
+    def self.validate_array_value(field, value, prop)
+      errors = []
+
+      unless value.is_a?(Array)
+        errors << "Field '#{field}' must be an array"
+        return errors
+      end
+
+      items = prop['items'] || {}
+      allowed = if items['enum'].is_a?(Array)
+                  items['enum']
+                elsif items['anyOf'].is_a?(Array)
+                  items['anyOf'].map { |o| o['const'] }
+                end
+
+      if allowed
+        value.each do |v|
+          errors << "Field '#{field}' contains invalid value '#{v}'" unless allowed.include?(v)
+        end
+      end
+
+      if prop['minItems'] && value.length < prop['minItems']
+        errors << "Field '#{field}' must have at least #{prop['minItems']} items"
+      end
+
+      if prop['maxItems'] && value.length > prop['maxItems']
+        errors << "Field '#{field}' must have at most #{prop['maxItems']} items"
+      end
+
+      errors
+    end
+  end
+end

data/lib/mcp_client/errors.rb

@@ -47,5 +47,14 @@ module MCPClient
 
     # Raised when multiple resources with the same URI exist across different servers
     class AmbiguousResourceURI < MCPError; end
+
+    # Raised when transport type cannot be determined from target URL/command
+    class TransportDetectionError < MCPError; end
+
+    # Raised when a task is not found
+    class TaskNotFound < MCPError; end
+
+    # Raised when there's an error creating or managing a task
+    class TaskError < MCPError; end
   end
 end

data/lib/mcp_client/http_transport_base.rb

@@ -58,6 +58,7 @@ module MCPClient
           # Apply base headers but prioritize session termination headers
           @headers.each { |k, v| req.headers[k] = v }
           req.headers['Mcp-Session-Id'] = @session_id
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
         end
 
         if response.success?
@@ -138,6 +139,7 @@ module MCPClient
 
       @server_info = result['serverInfo']
       @capabilities = result['capabilities']
+      @protocol_version = result['protocolVersion']
     end
 
     # Send a JSON-RPC request to the server and wait for result
@@ -256,14 +258,20 @@ module MCPClient
     end
 
     # Create a Faraday connection for HTTP requests
+    # Applies default configuration first, then allows user customization via @faraday_config block
     # @return [Faraday::Connection] the configured connection
     def create_http_connection
-      Faraday.new(url: @base_url) do |f|
+      conn = Faraday.new(url: @base_url) do |f|
         f.request :retry, max: @max_retries, interval: @retry_backoff, backoff_factor: 2
         f.options.open_timeout = @read_timeout
         f.options.timeout = @read_timeout
         f.adapter Faraday.default_adapter
       end
+
+      # Apply user's Faraday customizations after defaults
+      @faraday_config&.call(conn)
+
+      conn
     end
 
     # Log HTTP response (to be overridden by specific transports)

data/lib/mcp_client/json_rpc_common.rb

@@ -62,11 +62,15 @@ module MCPClient
     # Generate initialization parameters for MCP protocol
     # @return [Hash] the initialization parameters
     def initialization_params
+      capabilities = {
+        'elicitation' => {}, # MCP 2025-11-25: Support for server-initiated user interactions
+        'roots' => { 'listChanged' => true }, # MCP 2025-11-25: Support for roots
+        'sampling' => {} # MCP 2025-11-25: Support for server-initiated LLM sampling
+      }
+
       {
         'protocolVersion' => MCPClient::PROTOCOL_VERSION,
-        'capabilities' => {
-          'elicitation' => {} # MCP 2025-06-18: Support for server-initiated user interactions
-        },
+        'capabilities' => capabilities,
         'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
       }
     end

data/lib/mcp_client/resource.rb

@@ -41,6 +41,14 @@ module MCPClient
       @server = server
     end
 
+    # Return the lastModified annotation value (ISO 8601 timestamp string)
+    # @return [String, nil] the lastModified timestamp, or nil if not set
+    def last_modified
+      return nil unless @annotations.is_a?(Hash)
+
+      @annotations['lastModified'] || @annotations[:lastModified]
+    end
+
     # Create a Resource instance from JSON data
     # @param data [Hash] JSON data from MCP server
     # @param server [MCPClient::ServerBase, nil] the server this resource belongs to

data/lib/mcp_client/resource_link.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of an MCP resource link in tool result content
+  # A resource link references a server resource that can be read separately.
+  # Used in tool results to point clients to available resources (MCP 2025-11-25).
+  class ResourceLink
+    # @!attribute [r] uri
+    #   @return [String] URI of the linked resource
+    # @!attribute [r] name
+    #   @return [String] the name of the linked resource
+    # @!attribute [r] description
+    #   @return [String, nil] optional human-readable description
+    # @!attribute [r] mime_type
+    #   @return [String, nil] optional MIME type of the resource
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations that provide hints to clients
+    # @!attribute [r] title
+    #   @return [String, nil] optional display title for the resource
+    # @!attribute [r] size
+    #   @return [Integer, nil] optional size of the resource in bytes
+    attr_reader :uri, :name, :description, :mime_type, :annotations, :title, :size
+
+    # Initialize a resource link
+    # @param uri [String] URI of the linked resource
+    # @param name [String] the name of the linked resource
+    # @param description [String, nil] optional human-readable description
+    # @param mime_type [String, nil] optional MIME type of the resource
+    # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    # @param title [String, nil] optional display title for the resource
+    # @param size [Integer, nil] optional size of the resource in bytes
+    def initialize(uri:, name:, description: nil, mime_type: nil, annotations: nil, title: nil, size: nil)
+      @uri = uri
+      @name = name
+      @description = description
+      @mime_type = mime_type
+      @annotations = annotations
+      @title = title
+      @size = size
+    end
+
+    # Create a ResourceLink instance from JSON data
+    # @param data [Hash] JSON data from MCP server (content item with type 'resource_link')
+    # @return [MCPClient::ResourceLink] resource link instance
+    def self.from_json(data)
+      new(
+        uri: data['uri'],
+        name: data['name'],
+        description: data['description'],
+        mime_type: data['mimeType'],
+        annotations: data['annotations'],
+        title: data['title'],
+        size: data['size']
+      )
+    end
+
+    # The content type identifier for this content type
+    # @return [String] 'resource_link'
+    def type
+      'resource_link'
+    end
+  end
+end

data/lib/mcp_client/root.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Represents an MCP Root - a URI that defines a boundary where servers can operate
+  # Roots are declared by clients to inform servers about relevant resources and their locations
+  class Root
+    attr_reader :uri, :name
+
+    # Create a new Root
+    # @param uri [String] The URI for the root (typically file:// URI)
+    # @param name [String, nil] Optional human-readable name for display purposes
+    def initialize(uri:, name: nil)
+      @uri = uri
+      @name = name
+    end
+
+    # Create a Root from a JSON hash
+    # @param json [Hash] The JSON hash with 'uri' and optional 'name' keys
+    # @return [Root]
+    def self.from_json(json)
+      new(
+        uri: json['uri'] || json[:uri],
+        name: json['name'] || json[:name]
+      )
+    end
+
+    # Convert to JSON-serializable hash
+    # @return [Hash]
+    def to_h
+      result = { 'uri' => @uri }
+      result['name'] = @name if @name
+      result
+    end
+
+    # Convert to JSON string
+    # @return [String]
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    # Check equality
+    def ==(other)
+      return false unless other.is_a?(Root)
+
+      uri == other.uri && name == other.name
+    end
+
+    alias eql? ==
+
+    def hash
+      [uri, name].hash
+    end
+
+    # String representation
+    def to_s
+      name ? "#{name} (#{uri})" : uri
+    end
+
+    def inspect
+      "#<MCPClient::Root uri=#{uri.inspect} name=#{name.inspect}>"
+    end
+  end
+end

data/lib/mcp_client/server_factory.rb

@@ -77,7 +77,8 @@ module MCPClient
         retry_backoff: config[:retry_backoff] || 1,
         name: config[:name],
         logger: logger,
-        oauth_provider: config[:oauth_provider]
+        oauth_provider: config[:oauth_provider],
+        faraday_config: config[:faraday_config]
       )
     end
 
@@ -97,7 +98,8 @@ module MCPClient
         retry_backoff: config[:retry_backoff] || 1,
         name: config[:name],
         logger: logger,
-        oauth_provider: config[:oauth_provider]
+        oauth_provider: config[:oauth_provider],
+        faraday_config: config[:faraday_config]
       )
     end
 

data/lib/mcp_client/server_http.rb

@@ -55,6 +55,7 @@ module MCPClient
     # @option options [String, nil] :name Optional name for this server
     # @option options [Logger, nil] :logger Optional logger
     # @option options [MCPClient::Auth::OAuthProvider, nil] :oauth_provider Optional OAuth provider
+    # @option options [Proc, nil] :faraday_config Optional block to customize the Faraday connection
     def initialize(base_url:, **options)
       opts = default_options.merge(options)
       super(name: opts[:name])
@@ -99,6 +100,7 @@ module MCPClient
                                       })
 
       @read_timeout = opts[:read_timeout]
+      @faraday_config = opts[:faraday_config]
       @tools = nil
       @tools_data = nil
       @request_id = 0
@@ -193,15 +195,22 @@ module MCPClient
       raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
     end
 
-    # Override apply_request_headers to add session headers for MCP protocol
+    # Override apply_request_headers to add session and protocol version headers
     def apply_request_headers(req, request)
       super
 
-      # Add session header if we have one (for non-initialize requests)
-      return unless @session_id && request['method'] != 'initialize'
+      # Add session and protocol version headers for non-initialize requests
+      return unless request['method'] != 'initialize'
 
-      req.headers['Mcp-Session-Id'] = @session_id
-      @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+      if @session_id
+        req.headers['Mcp-Session-Id'] = @session_id
+        @logger.debug("Adding session header: Mcp-Session-Id: #{@session_id}")
+      end
+
+      return unless @protocol_version
+
+      req.headers['Mcp-Protocol-Version'] = @protocol_version
+      @logger.debug("Adding protocol version header: Mcp-Protocol-Version: #{@protocol_version}")
     end
 
     # Override handle_successful_response to capture session ID
@@ -320,6 +329,36 @@ module MCPClient
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     end
 
+    # Request completion suggestions from the server (MCP 2025-06-18)
+    # @param ref [Hash] reference to complete (prompt or resource)
+    # @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 resource templates available from the MCP server
     # @param cursor [String, nil] optional cursor for pagination
     # @return [Hash] result containing resourceTemplates array and optional nextCursor
@@ -420,7 +459,8 @@ module MCPClient
         retry_backoff: 1,
         name: nil,
         logger: nil,
-        oauth_provider: nil
+        oauth_provider: nil,
+        faraday_config: nil
       }
     end