ruby-mcp-client 1.1.0 → 2.1.0

data/lib/mcp_client/schema_validator.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Self-contained JSON Schema validator used to check a tool call result's
+  # structuredContent against the tool's declared outputSchema (MCP 2025-11-25
+  # server/tools spec: "Clients SHOULD validate structured results against this
+  # schema"; the default schema dialect is JSON Schema 2020-12 per SEP-1613).
+  #
+  # Only the common JSON Schema keywords are supported:
+  # - type (single value or array of values), enum, const
+  # - properties, required (objects)
+  # - items, minItems, maxItems (arrays)
+  # - minLength, maxLength, pattern (strings)
+  # - minimum, maximum, exclusiveMinimum, exclusiveMaximum (numbers)
+  #
+  # The full JSON Schema 2020-12 vocabulary ($ref/$defs, allOf/anyOf/oneOf/not,
+  # conditional keywords, additionalProperties, format assertions, ...) is out
+  # of scope: unrecognized keywords are ignored rather than misapplied, so
+  # validation is best-effort — it may accept data a full validator would
+  # reject, but it does not reject data that conforms to the schema. So that
+  # this gap is never silent, {.unsupported_keywords} reports which unapplied
+  # validation keywords a schema uses; callers surface them as a warning.
+  module SchemaValidator
+    # JSON Schema 2020-12 keywords that affect validation but that this
+    # validator does not evaluate: applicator/reference keywords, assertion
+    # keywords (multipleOf, uniqueItems, contains bounds, property-count
+    # bounds, dependentRequired), and format (asserted by full validators in
+    # format-assertion mode). Their presence means validation is partial: data
+    # may pass here that a full validator would reject.
+    UNSUPPORTED_KEYWORDS = %w[
+      $ref $dynamicRef $defs allOf anyOf oneOf not if then else
+      additionalProperties patternProperties propertyNames dependentSchemas
+      prefixItems contains minContains maxContains uniqueItems
+      multipleOf format dependentRequired minProperties maxProperties
+      unevaluatedProperties unevaluatedItems
+    ].freeze
+
+    # Wall-clock budget for ALL pattern matching in a single validate call.
+    # Schemas come from the remote server, so an expensive expression must not
+    # be able to monopolize the calling thread.
+    #
+    # The budget is for the whole operation, not per match: a per-match limit
+    # multiplies, since the server also controls how many strings it sends
+    # (N array items under one pathological items.pattern costs N x limit).
+    PATTERN_MATCH_TIMEOUT = 1.0
+
+    # Floor for an individual match's timeout, so a nearly-exhausted budget
+    # still makes progress rather than failing every remaining pattern.
+    MIN_PATTERN_MATCH_TIMEOUT = 0.01
+
+    # Keywords whose value is a single subschema to walk.
+    SUBSCHEMA_KEYWORDS = %w[
+      items contains additionalProperties propertyNames not if then else
+      unevaluatedItems unevaluatedProperties
+    ].freeze
+
+    # Keywords whose value is a map of name => subschema.
+    SUBSCHEMA_MAP_KEYWORDS = %w[properties patternProperties $defs definitions dependentSchemas].freeze
+
+    # Keywords whose value is an array of subschemas.
+    SUBSCHEMA_ARRAY_KEYWORDS = %w[allOf anyOf oneOf prefixItems].freeze
+
+    # List the unsupported JSON Schema keywords a schema uses (anywhere: at the
+    # top level or nested in subschemas). Property names that merely look like
+    # keywords (e.g. a property called 'not') are not reported, and
+    # data-carrying keywords (enum/const/default/examples) are not scanned.
+    # @param schema [Object] the JSON schema (string or symbol keys)
+    # @return [Array<String>] unique unsupported keywords, in discovery order
+    def self.unsupported_keywords(schema)
+      found = []
+      collect_unsupported_keywords(schema, found)
+      found.uniq
+    end
+
+    # Recursively collect unsupported keywords from a schema.
+    # @param schema [Object] a (sub)schema; non-Hash values are ignored
+    # @param found [Array<String>] accumulator
+    # @return [void]
+    def self.collect_unsupported_keywords(schema, found)
+      return unless schema.is_a?(Hash)
+
+      schema = schema.transform_keys(&:to_s)
+      found.concat(schema.keys & UNSUPPORTED_KEYWORDS)
+      schema.each do |keyword, value|
+        if SUBSCHEMA_KEYWORDS.include?(keyword)
+          collect_unsupported_keywords(value, found)
+        elsif SUBSCHEMA_MAP_KEYWORDS.include?(keyword) && value.is_a?(Hash)
+          value.each_value { |subschema| collect_unsupported_keywords(subschema, found) }
+        elsif SUBSCHEMA_ARRAY_KEYWORDS.include?(keyword) && value.is_a?(Array)
+          value.each { |subschema| collect_unsupported_keywords(subschema, found) }
+        end
+      end
+    end
+
+    # Validate data against a JSON Schema subset.
+    # Schema and data hashes may use string or symbol keys.
+    # @param data [Object] the value to validate
+    # @param schema [Hash] the JSON schema
+    # @param path [String] JSON-pointer-style location used in error messages
+    # @return [Array<String>] human-readable validation errors (empty if valid)
+    def self.validate(data, schema, path: '#', deadline: nil)
+      return [] unless schema.is_a?(Hash)
+
+      # One deadline covers the entire (recursive) validation.
+      deadline ||= Process.clock_gettime(Process::CLOCK_MONOTONIC) + PATTERN_MATCH_TIMEOUT
+
+      schema = schema.transform_keys(&:to_s)
+      errors = []
+      errors.concat(validate_type(data, schema['type'], path)) if schema.key?('type')
+      errors.concat(validate_enum(data, schema, path))
+      case data
+      when Hash then errors.concat(validate_object(data, schema, path, deadline))
+      when Array then errors.concat(validate_array(data, schema, path, deadline))
+      when String then errors.concat(validate_string(data, schema, path, deadline))
+      when Numeric then errors.concat(validate_number(data, schema, path))
+      end
+      errors
+    end
+
+    # Validate the JSON type of a value.
+    # @param data [Object] the value
+    # @param type [String, Symbol, Array<String, Symbol>] expected type(s)
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_type(data, type, path)
+      types = (type.is_a?(Array) ? type : [type]).map(&:to_s)
+      return [] if types.any? { |t| type_match?(t, data) }
+
+      ["#{path}: expected type #{types.join(' or ')}, got #{json_type(data)}"]
+    end
+
+    # Whether a value matches a JSON Schema type name.
+    # Unknown type names are not enforced (returns true).
+    # @param type [String] the JSON Schema type name
+    # @param data [Object] the value
+    # @return [Boolean]
+    def self.type_match?(type, data)
+      case type
+      when 'object' then data.is_a?(Hash)
+      when 'array' then data.is_a?(Array)
+      when 'string' then data.is_a?(String)
+      when 'boolean' then data.equal?(true) || data.equal?(false)
+      when 'null' then data.nil?
+      when 'number' then data.is_a?(Numeric)
+      when 'integer' then integer?(data)
+      else true
+      end
+    end
+
+    # Whether a value is a JSON Schema integer. Per JSON Schema 2020-12 a
+    # number with a zero fractional part (e.g. 2.0) is a valid integer.
+    # @param data [Object] the value
+    # @return [Boolean]
+    def self.integer?(data)
+      return true if data.is_a?(Integer)
+      return false unless data.is_a?(Numeric)
+
+      (data % 1).zero?
+    end
+
+    # The JSON type name of a Ruby value (for error messages).
+    # @param data [Object] the value
+    # @return [String]
+    def self.json_type(data)
+      case data
+      when nil then 'null'
+      when true, false then 'boolean'
+      when Integer then 'integer'
+      when Numeric then 'number'
+      when String then 'string'
+      when Array then 'array'
+      when Hash then 'object'
+      else data.class.name
+      end
+    end
+
+    # Validate enum/const membership.
+    # @param data [Object] the value
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_enum(data, schema, path)
+      errors = []
+      if schema['enum'].is_a?(Array) && !schema['enum'].include?(data)
+        errors << "#{path}: value #{data.inspect} is not in enum #{schema['enum'].inspect}"
+      end
+      if schema.key?('const') && schema['const'] != data
+        errors << "#{path}: value #{data.inspect} does not equal const #{schema['const'].inspect}"
+      end
+      errors
+    end
+
+    # Validate an object against required/properties.
+    # @param data [Hash] the object
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_object(data, schema, path, deadline = nil)
+      errors = []
+      Array(schema['required']).each do |raw_name|
+        name = raw_name.to_s
+        errors << "#{path}: missing required property '#{name}'" unless data.key?(name) || data.key?(name.to_sym)
+      end
+      properties = schema['properties']
+      return errors unless properties.is_a?(Hash)
+
+      properties.each do |raw_name, prop_schema|
+        next unless prop_schema.is_a?(Hash)
+
+        name = raw_name.to_s
+        key = if data.key?(name)
+                name
+              elsif data.key?(name.to_sym)
+                name.to_sym
+              end
+        next if key.nil?
+
+        errors.concat(validate(data[key], prop_schema, path: "#{path}/#{name}", deadline: deadline))
+      end
+      errors
+    end
+
+    # Validate an array against items/minItems/maxItems.
+    # @param data [Array] the array
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_array(data, schema, path, deadline = nil)
+      errors = []
+      min_items = schema['minItems']
+      max_items = schema['maxItems']
+      if min_items.is_a?(Numeric) && data.length < min_items
+        errors << "#{path}: expected at least #{min_items} items, got #{data.length}"
+      end
+      if max_items.is_a?(Numeric) && data.length > max_items
+        errors << "#{path}: expected at most #{max_items} items, got #{data.length}"
+      end
+      items = schema['items']
+      if items.is_a?(Hash)
+        data.each_with_index do |item, idx|
+          errors.concat(validate(item, items, path: "#{path}/#{idx}", deadline: deadline))
+        end
+      end
+      errors
+    end
+
+    # Validate a string against minLength/maxLength/pattern.
+    # @param data [String] the string
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_string(data, schema, path, deadline = nil)
+      errors = []
+      min_length = schema['minLength']
+      max_length = schema['maxLength']
+      if min_length.is_a?(Numeric) && data.length < min_length
+        errors << "#{path}: string is shorter than minLength #{min_length}"
+      end
+      if max_length.is_a?(Numeric) && data.length > max_length
+        errors << "#{path}: string is longer than maxLength #{max_length}"
+      end
+      errors.concat(validate_pattern(data, schema['pattern'], path, deadline))
+      errors
+    end
+
+    # Validate a string against a regular-expression pattern.
+    # Invalid patterns are not enforced.
+    #
+    # The pattern comes from the tool's outputSchema, i.e. from the remote
+    # server, so matching runs against the validation-wide deadline: neither a
+    # single expensive expression nor many cheap-looking ones can pin the
+    # calling thread. A match that exceeds the budget is reported as a
+    # validation error rather than silently accepted — the value was never
+    # shown to satisfy the schema.
+    # @param data [String] the string
+    # @param pattern [Object] the pattern keyword value
+    # @param path [String] location for error messages
+    # @param deadline [Float, nil] monotonic deadline for the whole validation
+    # @return [Array<String>] validation errors
+    def self.validate_pattern(data, pattern, path, deadline = nil)
+      return [] unless pattern.is_a?(String)
+
+      remaining = pattern_budget_remaining(deadline)
+      return ["#{path}: pattern matching budget exhausted before #{pattern.inspect}"] if remaining.zero?
+
+      return [] if data.match?(Regexp.new(pattern, timeout: remaining))
+
+      ["#{path}: string does not match pattern #{pattern.inspect}"]
+    rescue Regexp::TimeoutError
+      ["#{path}: pattern #{pattern.inspect} exceeded the #{PATTERN_MATCH_TIMEOUT}s matching budget"]
+    rescue RegexpError
+      []
+    end
+
+    # Time left in the validation-wide pattern budget.
+    # @param deadline [Float, nil] monotonic deadline, or nil for a lone match
+    # @return [Float] seconds available for the next match; 0.0 when exhausted
+    def self.pattern_budget_remaining(deadline)
+      return PATTERN_MATCH_TIMEOUT unless deadline
+
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return 0.0 if remaining <= 0
+
+      [remaining, MIN_PATTERN_MATCH_TIMEOUT].max
+    end
+
+    # Validate a number against inclusive/exclusive bounds.
+    # @param data [Numeric] the number
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_number(data, schema, path)
+      errors = []
+      minimum = schema['minimum']
+      maximum = schema['maximum']
+      exclusive_min = schema['exclusiveMinimum']
+      exclusive_max = schema['exclusiveMaximum']
+      errors << "#{path}: value #{data} is less than minimum #{minimum}" if minimum.is_a?(Numeric) && data < minimum
+      errors << "#{path}: value #{data} is greater than maximum #{maximum}" if maximum.is_a?(Numeric) && data > maximum
+      if exclusive_min.is_a?(Numeric) && data <= exclusive_min
+        errors << "#{path}: value #{data} must be greater than exclusiveMinimum #{exclusive_min}"
+      end
+      if exclusive_max.is_a?(Numeric) && data >= exclusive_max
+        errors << "#{path}: value #{data} must be less than exclusiveMaximum #{exclusive_max}"
+      end
+      errors
+    end
+  end
+end

data/lib/mcp_client/server_base.rb

@@ -9,6 +9,22 @@ module MCPClient
 
     # Initialize the server with a name
     # @param name [String, nil] server name
+    # Server-declared instructions from the initialize result, if any
+    # @return [String, nil]
+    attr_reader :instructions
+
+    # Host-supplied Implementation info sent as clientInfo during initialize
+    # (MCP 2025-11-25 Implementation: name, version, plus optional title,
+    # description, websiteUrl, icons). Defaults to the gem's identity.
+    # @param info [Hash] implementation info; must include name and version
+    # @raise [ArgumentError] when name or version is missing
+    def client_info=(info)
+      raise ArgumentError, 'client_info must include name' unless info['name'] || info[:name]
+      raise ArgumentError, 'client_info must include version' unless info['version'] || info[:version]
+
+      @client_info = info.transform_keys(&:to_s)
+    end
+
     def initialize(name: nil)
       @name = name
     end
@@ -83,11 +99,61 @@ module MCPClient
     end
 
     # Get server capabilities
+    # MCP 2025-11-25 tasks: all messages related to a task MUST carry the
+    # io.modelcontextprotocol/related-task key in _meta. Reserved key name:
+    RELATED_TASK_META_KEY = 'io.modelcontextprotocol/related-task'
+
+    # Echo the related-task _meta of an incoming server request onto the
+    # outgoing result, so responses to task-related requests (elicitation or
+    # sampling during input_required) stay associated with their task.
+    # @param result [Hash] the outgoing JSON-RPC result payload
+    # @param params [Hash, nil] the incoming request params
+    # @return [Hash] result with related-task _meta merged when applicable
+    def merge_related_task_meta(result, params)
+      related = params.is_a?(Hash) ? params.dig('_meta', RELATED_TASK_META_KEY) : nil
+      return result unless related && result.is_a?(Hash) && !result.key?('error')
+
+      meta = (result['_meta'] || {}).merge(RELATED_TASK_META_KEY => related)
+      result.merge('_meta' => meta)
+    end
+
     # @return [Hash, nil] server capabilities
     def capabilities
       raise NotImplementedError, 'Subclasses must implement capabilities'
     end
 
+    # Whether the server declared the given (possibly nested) capability
+    # during initialization.
+    # @param path [Array<String, Symbol>] capability key path, e.g. 'logging'
+    #   or 'resources', 'subscribe'
+    # @return [Boolean]
+    def capability?(*path)
+      node = begin
+        capabilities
+      rescue NotImplementedError
+        nil
+      end
+      path.each do |key|
+        return false unless node.is_a?(Hash)
+
+        node = node[key.to_s]
+      end
+      !node.nil? && node != false
+    end
+
+    # Raise unless the server negotiated the given capability (MCP lifecycle:
+    # "Only use capabilities that were successfully negotiated").
+    # @param path [Array<String, Symbol>] capability key path
+    # @param method [String] the JSON-RPC method the caller wants to send
+    # @raise [MCPClient::Errors::CapabilityError]
+    def require_capability!(*path, method:)
+      return if capability?(*path)
+
+      raise MCPClient::Errors::CapabilityError,
+            "Server #{name || self.class.name} did not declare the #{path.join('.')} capability " \
+            "required for #{method}"
+    end
+
     # Clean up the server connection
     def cleanup
       raise NotImplementedError, 'Subclasses must implement cleanup'

data/lib/mcp_client/server_factory.rb

@@ -99,7 +99,10 @@ module MCPClient
         name: config[:name],
         logger: logger,
         oauth_provider: config[:oauth_provider],
-        faraday_config: config[:faraday_config]
+        faraday_config: config[:faraday_config],
+        max_decompressed_body_bytes:
+          config[:max_decompressed_body_bytes] ||
+            MCPClient::ServerStreamableHTTP::JsonRpcTransport::MAX_DECOMPRESSED_BODY_BYTES
       )
     end
 

data/lib/mcp_client/server_http/json_rpc_transport.rb

@@ -12,15 +12,16 @@ module MCPClient
 
       # Parse an HTTP JSON-RPC response
       # @param response [Faraday::Response] the HTTP response
+      # @param _request [Hash, nil] the originating JSON-RPC request (unused)
       # @return [Hash] the parsed result
       # @raise [MCPClient::Errors::TransportError] if parsing fails
       # @raise [MCPClient::Errors::ServerError] if the response contains an error
-      def parse_response(response)
+      def parse_response(response, _request = nil)
         body = response.body.strip
         data = JSON.parse(body)
         process_jsonrpc_response(data)
       rescue JSON::ParserError => e
-        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{describe_parse_error(e)}"
       end
     end
   end

data/lib/mcp_client/server_http.rb

@@ -183,10 +183,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def call_tool(tool_name, parameters)
-      rpc_request('tools/call', {
-                    name: tool_name,
-                    arguments: parameters
-                  })
+      rpc_request('tools/call', build_named_request_params(tool_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -271,10 +268,7 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt interpolation
     def get_prompt(prompt_name, parameters)
-      rpc_request('prompts/get', {
-                    name: prompt_name,
-                    arguments: parameters
-                  })
+      rpc_request('prompts/get', build_named_request_params(prompt_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       raise
     rescue StandardError => e
@@ -336,11 +330,14 @@ module MCPClient
     # @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)
+      ensure_connected
+      require_capability!('completions', method: 'completion/complete')
       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
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
@@ -352,8 +349,11 @@ module MCPClient
     # @return [Hash] empty result on success
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def log_level=(level)
+      ensure_connected
+      require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
@@ -384,9 +384,12 @@ module MCPClient
     # @return [Boolean] true if subscription successful
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
     def subscribe_resource(uri)
+      ensure_connected
+      require_capability!('resources', 'subscribe', method: 'resources/subscribe')
       rpc_request('resources/subscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
@@ -397,9 +400,12 @@ module MCPClient
     # @return [Boolean] true if unsubscription successful
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
     def unsubscribe_resource(uri)
+      ensure_connected
+      require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
       rpc_request('resources/unsubscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"