mcp 1.1.0 → 1.3.0

data/lib/mcp/client/mcp_param_headers.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    # The custom-header half of SEP-2243 (MCP 2026-07-28): scanning a tool's `inputSchema` for
+    # `x-mcp-header` declarations and encoding `tools/call` argument values into `Mcp-Param-{Name}` HTTP headers,
+    # with the `=?base64?...?=` sentinel for values that cannot ride as plain ASCII field values.
+    # Mirrors the TypeScript SDK's `mcpParamHeaders` codec; the standard-header half (`Mcp-Method`, `Mcp-Name`)
+    # lives with the transport.
+    #
+    # https://modelcontextprotocol.io/specification/draft/basic/transports/streamable-http#custom-headers-from-tool-parameters
+    module McpParamHeaders
+      # The fixed prefix every custom-parameter header carries.
+      HEADER_PREFIX = "Mcp-Param-"
+
+      # The schema-extension property name a tool's `inputSchema` carries.
+      X_MCP_HEADER_KEY = "x-mcp-header"
+
+      # RFC 9110 Section 5.1 `token` syntax (`1*tchar`): rejects empty names, spaces,
+      # control characters (including CR/LF), and the HTTP delimiters.
+      RFC9110_TOKEN = /\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/.freeze
+
+      # The spec text admits `string`, `integer`, and `boolean`. `number` is also accepted because
+      # the published conformance referee annotates `type: "number"` parameters and expects them
+      # mirrored; the TypeScript SDK makes the same accommodation.
+      PERMITTED_TYPES = ["string", "integer", "boolean", "number"].freeze
+
+      # JSON Schema keywords the SEP-2243 static-reachability constraint excludes from
+      # the `properties`-only chain. An `x-mcp-header` under any of these invalidates
+      # the tool definition rather than being silently ignored.
+      NON_REACHABLE_SUBSCHEMA_KEYWORDS = [
+        "items",
+        "prefixItems",
+        "contains",
+        "additionalProperties",
+        "unevaluatedProperties",
+        "unevaluatedItems",
+        "propertyNames",
+        "patternProperties",
+        "dependentSchemas",
+        "oneOf",
+        "anyOf",
+        "allOf",
+        "not",
+        "if",
+        "then",
+        "else",
+        "$defs",
+        "definitions",
+      ].freeze
+
+      # Keywords whose value maps names to subschemas rather than being one subschema or a list of them.
+      OBJECT_VALUED_SUBSCHEMA_KEYWORDS = ["patternProperties", "dependentSchemas", "$defs", "definitions"].freeze
+
+      # Integers beyond 2**53 - 1 lose precision in JSON number interchange, so they are not mirrored;
+      # the TypeScript SDK refuses unsafe integers the same way.
+      MAX_SAFE_INTEGER = (2**53) - 1
+
+      BASE64_SENTINEL_PREFIX = "=?base64?"
+      BASE64_SENTINEL_SUFFIX = "?="
+
+      class << self
+        # Scans a tool's `inputSchema` for `x-mcp-header` declarations and validates every constraint
+        # the spec places on them: RFC 9110 token names, case-insensitive uniqueness, primitive-typed
+        # declaring properties, and static reachability through a chain of `properties` keys only.
+        # Returns `{ valid: true, declarations: [...] }` with each declaration `{ path:, header_name:, type: }`,
+        # or `{ valid: false, reason: "..." }` on the first violation.
+        def scan(input_schema)
+          declarations = []
+          fault = visit(input_schema, [], true, declarations, {})
+
+          fault ? { valid: false, reason: fault } : { valid: true, declarations: declarations }
+        end
+
+        # Builds the `Mcp-Param-{Name}` headers for one `tools/call` from the scanned declarations and
+        # the call's `arguments`. A `null` or absent value omits its header (the spec's MUST-omit rows);
+        # a non-primitive or non-representable value is omitted rather than emitted malformed.
+        def build(declarations, arguments)
+          declarations.each_with_object({}) do |declaration, headers|
+            value = value_at_path(arguments, declaration[:path])
+            next if value.nil?
+
+            string_value = primitive_to_string(value)
+            next unless string_value
+
+            encoded = begin
+              encode_value(string_value)
+            rescue EncodingError
+              # A string that cannot be represented as UTF-8 (e.g. binary data) has no header
+              # representation; omit it like the other non-representable values.
+              next
+            end
+
+            headers["#{HEADER_PREFIX}#{declaration[:header_name]}"] = encoded
+          end
+        end
+
+        # Converts a primitive argument to its header string per the spec's type-conversion rules:
+        # strings pass through, booleans become lowercase `"true"` / `"false"`, and numbers become
+        # their decimal string. `nil` means "not representable: do not emit a header".
+        def primitive_to_string(value)
+          case value
+          when String
+            value
+          when true
+            "true"
+          when false
+            "false"
+          when Integer
+            value.abs <= MAX_SAFE_INTEGER ? value.to_s : nil
+          when Float
+            return unless value.finite?
+
+            # JSON has one number type: an integral float serializes without the fractional part,
+            # matching the `String(42.0)` the JavaScript reference emits.
+            value == value.truncate ? value.truncate.to_s : value.to_s
+          end
+        end
+
+        # Encodes a header value per the spec's value-encoding rules: a safe plain-ASCII field value
+        # passes through unchanged, everything else is wrapped as `=?base64?{base64-of-UTF-8}?=`.
+        def encode_value(value)
+          return value unless needs_base64?(value)
+
+          "#{BASE64_SENTINEL_PREFIX}#{[value.encode(Encoding::UTF_8)].pack("m0")}#{BASE64_SENTINEL_SUFFIX}"
+        end
+
+        private
+
+        def visit(node, path, reachable, declarations, seen_lower)
+          return unless node.is_a?(Hash)
+
+          if key?(node, X_MCP_HEADER_KEY)
+            fault = validate_declaration(node, path, reachable, declarations, seen_lower)
+
+            return fault if fault
+          end
+
+          properties = read(node, "properties")
+          if properties.is_a?(Hash)
+            properties.each do |key, child|
+              fault = visit(child, path + [key.to_s], reachable, declarations, seen_lower)
+
+              return fault if fault
+            end
+          end
+
+          # Static-reachability sweep: descend the keywords the `properties` chain MUST NOT pass
+          # through with `reachable: false`, so an annotation under any of them is reported.
+          # `$defs` covers `$ref`-within-`$defs`; chasing arbitrary `$ref` URIs is out of scope.
+          NON_REACHABLE_SUBSCHEMA_KEYWORDS.each do |keyword|
+            next unless (sub = read(node, keyword))
+
+            branches = if sub.is_a?(Array)
+              sub
+            elsif sub.is_a?(Hash) && OBJECT_VALUED_SUBSCHEMA_KEYWORDS.include?(keyword)
+              sub.values
+            else
+              [sub]
+            end
+
+            branches.each do |branch|
+              fault = visit(branch, path + ["<#{keyword}>"], false, declarations, seen_lower)
+
+              return fault if fault
+            end
+          end
+
+          nil
+        end
+
+        def validate_declaration(node, path, reachable, declarations, seen_lower)
+          if !reachable || path.empty?
+            return "#{path_name(path)}: x-mcp-header is only permitted on properties statically reachable via a chain of `properties` keys"
+
+          end
+
+          annotation = read(node, X_MCP_HEADER_KEY)
+
+          unless annotation.is_a?(String) && !annotation.empty?
+            return "#{path_name(path)}: x-mcp-header MUST be a non-empty string"
+          end
+
+          unless RFC9110_TOKEN.match?(annotation)
+            return "#{path_name(path)}: x-mcp-header `#{annotation}` is not a valid RFC 9110 token"
+          end
+
+          type = read(node, "type")
+          unless type.is_a?(String) && PERMITTED_TYPES.include?(type)
+            return "#{path_name(path)}: x-mcp-header is only permitted on primitive-typed properties " \
+              "(got `#{type.inspect}`)"
+          end
+
+          lower = annotation.downcase
+          prior = seen_lower[lower]
+          if prior
+            return "x-mcp-header `#{annotation}` is not case-insensitively unique (also declared as `#{prior}`)"
+          end
+
+          seen_lower[lower] = annotation
+          declarations << { path: path, header_name: annotation, type: type }
+          nil
+        end
+
+        # A value cannot ride as a plain ASCII field value when it is empty, already shaped like
+        # the Base64 sentinel (the spec's ambiguity rule), carries edge whitespace that field parsing
+        # would strip, or contains a byte outside visible ASCII plus interior tab.
+        def needs_base64?(value)
+          return true if value.empty?
+          return true if value.start_with?(BASE64_SENTINEL_PREFIX) && value.end_with?(BASE64_SENTINEL_SUFFIX)
+          return true if value != value.strip
+
+          value.each_byte.any? { |byte| byte != 0x09 && !byte.between?(0x20, 0x7e) }
+        end
+
+        def value_at_path(root, path)
+          path.reduce(root) do |node, key|
+            break unless node.is_a?(Hash)
+
+            read(node, key)
+          end
+        end
+
+        # Schemas and arguments arrive with string keys off the wire but may carry symbol keys
+        # when constructed in Ruby; read both forms like the SDK's other readers.
+        def read(hash, key)
+          value = hash[key]
+
+          value.nil? ? hash[key.to_sym] : value
+        end
+
+        def key?(hash, key)
+          hash.key?(key) || hash.key?(key.to_sym)
+        end
+
+        def path_name(path)
+          path.empty? ? "<root>" : path.join(".")
+        end
+      end
+    end
+  end
+end

data/lib/mcp/client/modern_envelope.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../request_envelope"
+
+module MCP
+  class Client
+    # Stamps the SEP-2575 per-request `_meta` envelope onto outgoing modern requests.
+    # The reserved key names are shared with the server-side `MCP::RequestEnvelope`.
+    # Reserved keys always win over caller-supplied `_meta` entries because they are
+    # wire vocabulary the SDK is responsible for; every other entry is preserved.
+    module ModernEnvelope
+      extend self
+
+      # Returns a copy of `request` with `params._meta` carrying the modern triple.
+      # Neither `request` nor its nested hashes are mutated.
+      def stamp(request, protocol_version:, client_info:, capabilities:)
+        params_key = request.key?("params") ? "params" : :params
+        params = request[params_key] || {}
+        meta_key = params.key?("_meta") ? "_meta" : :_meta
+        meta = params[meta_key] || {}
+
+        stamped_meta = meta.merge(
+          RequestEnvelope::PROTOCOL_VERSION_META_KEY.to_sym => protocol_version,
+          RequestEnvelope::CLIENT_INFO_META_KEY.to_sym => client_info,
+          RequestEnvelope::CLIENT_CAPABILITIES_META_KEY.to_sym => capabilities,
+        )
+
+        request.merge(params_key => params.merge(meta_key => stamped_meta))
+      end
+    end
+  end
+end

data/lib/mcp/client/oauth/bounded_body.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # Bounds an OAuth response body while it arrives, rather than after it has been buffered.
+      # Discovery documents, registration responses, and token responses are all small by definition,
+      # so a body that keeps growing is never something worth holding in memory. Matches the 4 MiB cap of
+      # `MCP::Client::HTTP::MAX_MESSAGE_BYTES` and `MCP::Client::Stdio::MAX_LINE_BYTES`.
+      class BoundedBody
+        MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+        # Raised while the body is read. Each caller translates it into its own error type,
+        # so this never reaches an embedder.
+        class TooLargeError < StandardError; end
+
+        # What the OAuth code reads from a response. The Faraday response itself is not passed on,
+        # so a later caller cannot reach the unbounded `response.body` by accident.
+        Response = Struct.new(:status, :body)
+
+        def initialize(max_bytes: MAX_RESPONSE_BYTES)
+          @max_bytes = max_bytes
+          @buffer = +""
+        end
+
+        # Faraday `on_data` streaming callback. The chunks arrive decompressed: the default `Net::HTTP` adapter negotiates
+        # `Accept-Encoding` itself and reads the body through `Net::HTTPResponse#inflater`, so a small compressed body
+        # that expands past the cap is refused partway through the expansion rather than after it. That holds only while
+        # the connection leaves `Accept-Encoding` to the adapter; see `Flow#default_http_client`.
+        def on_data
+          proc do |chunk, _received_bytes, _env|
+            @buffer << chunk
+
+            raise TooLargeError, too_large_message if @buffer.bytesize > @max_bytes
+          end
+        end
+
+        # The status paired with the bounded body. Adapters that ignore `on_data` leave the buffer empty and deliver
+        # the whole body in `response.body`, so that path is measured here instead; the bytes are already allocated by then,
+        # but refusing them still keeps an over-cap document out of `JSON.parse`.
+        def response_for(response)
+          Response.new(response.status, bounded_body(response))
+        end
+
+        private
+
+        def bounded_body(response)
+          return @buffer unless @buffer.empty?
+
+          body = response.body
+          body = body.is_a?(String) ? body : body.to_s
+          raise TooLargeError, too_large_message if body.bytesize > @max_bytes
+
+          body
+        end
+
+        def too_large_message
+          # Not "the authorization server": protected resource metadata comes from the MCP server's own origin,
+          # so this message covers endpoints on both sides of the flow.
+          "Response body from the OAuth endpoint exceeds #{@max_bytes} bytes"
+        end
+      end
+
+      private_constant :BoundedBody
+    end
+  end
+end

data/lib/mcp/client/oauth/discovery.rb

@@ -8,7 +8,7 @@ module MCP
     module OAuth
       # Stateless helpers that map MCP-authorization spec URLs and headers into something
       # the `Flow` orchestrator and `MCP::Client::HTTP` transport can act on.
-      # The module bundles five concerns that share no state but are closely related to
+      # The module bundles six concerns that share no state but are closely related to
       # the spec's "Discovery" and "Communication Security" sections:
       #
       # - **`WWW-Authenticate` parsing** (`parse_www_authenticate`): pulls
@@ -22,6 +22,10 @@ module MCP
       # - **Communication Security check** (`secure_url?`): enforces "HTTPS only"
       #   for every OAuth-facing URL, with the loopback carve-out described in
       #   `secure_url?`'s comment.
+      # - **Destination checks** (`same_origin?`, `private_network_host?`):
+      #   answer *where* a URL points, which the scheme alone does not. `Flow` uses
+      #   them to refuse server-supplied discovery URLs aimed at hosts the MCP server
+      #   has no business steering the client toward.
       # - **URL canonicalization** (`canonicalize_url`): normalizes scheme,
       #   host, port, path, percent-encoded dot segments, and fragments
       #   so two URLs that *refer to the same resource* compare as equal,
@@ -193,6 +197,51 @@ module MCP
             false
           end
 
+          # Returns true when `url` and `other` share an origin: same scheme, same host,
+          # and same port. Scheme and host compare case-insensitively, and an implicit default port compares
+          # equal to the same port written out, because `URI::HTTP#port` already resolves to the default.
+          #
+          # Anything that fails to parse or carries no host returns false, so a caller using this as
+          # a security gate refuses rather than admits on malformed input.
+          def same_origin?(url, other)
+            uri = URI.parse(url.to_s)
+            other_uri = URI.parse(other.to_s)
+            return false if uri.host.nil? || uri.host.empty?
+            return false if other_uri.host.nil? || other_uri.host.empty?
+
+            uri.scheme&.downcase == other_uri.scheme&.downcase &&
+              uri.host.downcase == other_uri.host.downcase &&
+              uri.port == other_uri.port
+          rescue URI::InvalidURIError
+            false
+          end
+
+          # Returns true when `host` is an IP literal that is not reachable from the public internet,
+          # or the `localhost` name. The ranges are the ones RFC 9728 Section 7.7 and the MCP security best practices name
+          # as SSRF targets, so `169.254.0.0/16` covers the `169.254.169.254` cloud metadata address that motivates the check.
+          #
+          # Hostnames are deliberately NOT resolved. A lookup here would be a second network request driven by
+          # the same untrusted input, and the address it returned could differ from the one the HTTP client connects to
+          # a moment later, so the check would read as a guarantee it cannot make. That leaves names like `vault.corp.internal`
+          # out of reach of this predicate; it is one layer of an SSRF defense, not the whole of one.
+          def private_network_host?(host)
+            return false if host.nil? || host.empty?
+
+            normalized = host.downcase
+            return true if normalized == "localhost"
+
+            literal = normalized.delete_prefix("[").delete_suffix("]")
+            address = parse_ip_address(literal)
+            return numeric_ipv4_spelling?(literal) unless address
+
+            # `::ffff:169.254.169.254` addresses the same interface as `169.254.169.254`,
+            # so compare the IPv4 form rather than letting the mapped spelling through.
+            address = address.native if address.ipv6? && address.ipv4_mapped?
+
+            ranges = address.ipv4? ? PRIVATE_IPV4_RANGES : PRIVATE_IPV6_RANGES
+            ranges.any? { |range| range.include?(address) }
+          end
+
           # Returns true when `url` satisfies the structural requirements for
           # a Client ID Metadata Document URL per the MCP 2025-11-25
           # authorization specification and `draft-ietf-oauth-client-id-metadata-document-00`.
@@ -287,20 +336,17 @@ module MCP
             uri.to_s
           end
 
-          # Returns true when `prm` (a PRM `resource` URL) covers `server`
-          # (the MCP endpoint URL): same scheme/host/port, with PRM's path being
-          # a prefix of the server's path. When PRM also advertises a query
-          # string, the server's query MUST be identical to it
-          # (otherwise a hijacked PRM that advertises `?tenant=evil` would cover
-          # an MCP server at `?tenant=victim` and let the attacker mint
-          # a different tenant's token for the same origin + path).
-          # PRM with *no* query (URI#query returns `nil`) acts as a generic identifier
-          # over the origin + path prefix and covers any server query.
+          # Returns true when `prm` (a PRM `resource` URL) covers `server` (the MCP endpoint URL):
+          # same scheme/host/port, with PRM's path being a prefix of the server's path. When PRM
+          # also advertises a query string, the server's query MUST be identical to it (otherwise
+          # a hijacked PRM that advertises `?tenant=evil` would cover an MCP server at `?tenant=victim`
+          # and let the attacker mint a different tenant's token for the same origin + path).
+          # PRM with *no* query (URI#query returns `nil`) acts as a generic identifier over
+          # the origin + path prefix and covers any server query.
           #
-          # An empty query (`prm_url?` -- URI#query returns `""`) is NOT
-          # treated as wildcard: it represents the URI literally `<...>?`,
-          # which is distinct from "no query at all" and from any non-empty query,
-          # so it must match exactly.
+          # An empty query (`prm_url?` -- URI#query returns `""`) is NOT treated as wildcard:
+          # it represents the URI literally `<...>?`, which is distinct from "no query at all"
+          # and from any non-empty query, so it must match exactly.
           #
           # Both arguments must already be canonicalized.
           def resource_covers?(prm:, server:)
@@ -340,6 +386,29 @@ module MCP
           IPV6_LOOPBACK = IPAddr.new("::1")
           private_constant :IPV4_LOOPBACK_RANGE, :IPV6_LOOPBACK
 
+          # Backing ranges for `private_network_host?`.
+          #
+          # `0.0.0.0/8` is "this network" and `100.64.0.0/10` is the carrier-grade NAT
+          # space; neither is a destination a legitimate authorization server publishes,
+          # and both are reachable enough from a client's network position to be worth
+          # refusing. `::/96` covers the unspecified address, IPv6 loopback, and
+          # the deprecated IPv4-compatible form (`::10.0.0.1`) in one range.
+          PRIVATE_IPV4_RANGES = [
+            IPAddr.new("0.0.0.0/8"),
+            IPAddr.new("10.0.0.0/8"),
+            IPAddr.new("100.64.0.0/10"),
+            IPAddr.new("127.0.0.0/8"),
+            IPAddr.new("169.254.0.0/16"),
+            IPAddr.new("172.16.0.0/12"),
+            IPAddr.new("192.168.0.0/16"),
+          ].freeze
+          PRIVATE_IPV6_RANGES = [
+            IPAddr.new("::/96"),
+            IPAddr.new("fc00::/7"),
+            IPAddr.new("fe80::/10"),
+          ].freeze
+          private_constant :PRIVATE_IPV4_RANGES, :PRIVATE_IPV6_RANGES
+
           def loopback_host?(host)
             return false if host.nil? || host.empty?
 
@@ -362,6 +431,31 @@ module MCP
             nil
           end
 
+          # Matches one part of the `inet_aton` numeric grammar: hexadecimal (`0x7f`),
+          # octal (`0177`), or decimal (`127`).
+          INET_ATON_PART = /\A(?:0x\h+|0[0-7]*|[1-9]\d*)\z/.freeze
+          private_constant :INET_ATON_PART
+
+          # Returns true when `host` is written in the numeric IPv4 grammar `inet_aton` accepts
+          # and `IPAddr` rejects: one to four dot-separated parts, each hexadecimal, octal, or
+          # decimal, with the last part filling the remaining bytes. `2130706433`, `127.1`, and
+          # `0x7f000001` all reach 127.0.0.1, and `0xa9fea9fe` reaches the cloud metadata address,
+          # so a check that understood only the canonical form would refuse `169.254.169.254`
+          # while waving through every other spelling of it.
+          #
+          # Such a host is refused outright rather than decoded and range-checked, because its
+          # value is resolver-dependent: a leading zero reads as octal on one platform and decimal
+          # on another, which is the difference between 8.0.0.1 and 10.0.0.1 for `010.0.0.1`.
+          # Deciding here which one it meant would leave whichever reading was not taken as a way
+          # through. No authorization server is legitimately addressed in this notation, so
+          # refusing the grammar entirely costs nothing and leaves no spelling to miss.
+          def numeric_ipv4_spelling?(host)
+            parts = host.split(".", -1)
+            return false if parts.empty? || parts.length > 4
+
+            parts.all? { |part| INET_ATON_PART.match?(part) }
+          end
+
           # A redirect URI counts as native when it uses a custom non-http(s) scheme
           # (e.g. `com.example.app:/callback`) or when it is an http(s) URI whose host is
           # a loopback address. A URI without a scheme or one that fails to parse is not native.