ruby-mcp-client 2.0.0 → 3.0.0

data/lib/mcp_client/server_streamable_http.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'request_meta_scope'
 require 'uri'
 require 'json'
 require 'monitor'
@@ -22,6 +23,10 @@ module MCPClient
     require_relative 'server_streamable_http/json_rpc_transport'
 
     include JsonRpcTransport
+    # Every operation that may weigh a cache decision runs inside a scope
+    # that reserves the host request_meta evaluation for the request it
+    # leads to, and drops it when the operation ends.
+    prepend MCPClient::RequestMetaScope
 
     # Default values for connection settings
     DEFAULT_READ_TIMEOUT = 30
@@ -33,6 +38,52 @@ module MCPClient
     SSE_MAX_RECONNECT_DELAY = 30   # Maximum reconnect delay in seconds
     THREAD_JOIN_TIMEOUT = 5 # Timeout for thread cleanup
 
+    # Floor for the delay between resumption GETs. SEP-1699's polling pattern
+    # wants fast reconnects, so this is far smaller than the events-stream
+    # floor — it only prevents a peer-supplied "retry: 0" from turning the
+    # deadline window into a back-to-back request loop.
+    MIN_RESUMPTION_RECONNECT_DELAY = 0.01
+
+    # Maximum length of a server-supplied SSE event id retained as the
+    # resumption cursor. The id is echoed in the Last-Event-ID header of
+    # subsequent requests, so an unbounded value means unbounded retained
+    # memory and oversized outbound headers.
+    MAX_EVENT_ID_LENGTH = 1024
+
+    # Characters allowed in a retained event id: printable ASCII, since the
+    # value becomes an HTTP header value. Notably excludes CR/LF. The range
+    # starts at 0x20 because a space is legal inside a field value, and
+    # rejecting ids like "cursor 42" would silently strand resumption on a
+    # stale cursor.
+    EVENT_ID_PATTERN = /\A[\x20-\x7E]+\z/
+
+    # Ceiling on concurrent threads POSTing server-initiated responses
+    # (pongs, roots/sampling/elicitation replies, error responses). Each
+    # server request on the events stream costs one blocking HTTP POST in
+    # its own thread; without a bound, a peer flooding requests could
+    # accumulate threads and connections until the host is exhausted.
+    # Responses beyond the budget are dropped, with saturation logged at most
+    # once per SATURATION_LOG_INTERVAL seconds.
+    MAX_CONCURRENT_RESPONSE_POSTS = 8
+
+    # Minimum gap between "response budget saturated" warnings
+    SATURATION_LOG_INTERVAL = 5
+
+    # Floor for server-supplied retry directives on the long-lived events
+    # stream. The directive is peer-controlled: honoring "retry: 0" literally
+    # would let a hostile server that closes every stream drive a tight
+    # reconnect loop (sustained CPU/TLS/connection churn). Waiting longer
+    # than the directive stays SEP-1699 compliant — the retry field is a
+    # lower bound on the reconnect delay, not an exact schedule.
+    MIN_EVENTS_RECONNECT_DELAY = 0.1
+
+    # Maximum bytes an SSE parse buffer (events stream or resumption GET) may
+    # hold while waiting for an event terminator. The stream is
+    # peer-controlled: without a cap, a hostile server could withhold the
+    # blank-line delimiter forever and grow the buffer until the host runs
+    # out of memory. Generous enough for any legitimate JSON-RPC event.
+    MAX_SSE_BUFFER_BYTES = 32 * 1024 * 1024
+
     # @!attribute [r] base_url
     #   @return [String] The base URL of the MCP server
     # @!attribute [r] endpoint
@@ -97,7 +148,9 @@ module MCPClient
                                       })
 
       @read_timeout = opts[:read_timeout]
+      configure_protocol_mode(opts[:protocol], opts[:discover_timeout])
       @faraday_config = opts[:faraday_config]
+      @max_decompressed_body_bytes = validate_decompression_limit(opts[:max_decompressed_body_bytes])
       @tools = nil
       @tools_data = nil
       @prompts = nil
@@ -113,12 +166,18 @@ module MCPClient
       @last_event_id = nil
       @sse_retry_ms = nil
       @pending_stream_responses = {}
+      @response_post_count = 0
+      # Saturation bookkeeping for the response-POST budget
+      @dropped_response_posts = 0
+      @last_saturation_log_at = nil
       @oauth_provider = opts[:oauth_provider]
 
       # SSE events connection state
       @events_connection = nil
       @events_thread = nil
-      @buffer = '' # Buffer for partial SSE event data
+      @buffer = +'' # Buffer for partial SSE event data
+      # How much of @buffer has already been searched for an event terminator
+      @buffer_scanned = 0
       @elicitation_request_callback = nil # MCP 2025-06-18
       @roots_list_request_callback = nil # MCP 2025-06-18
       @sampling_request_callback = nil # MCP 2025-11-25
@@ -128,35 +187,39 @@ module MCPClient
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
     def connect
-      return true if @mutex.synchronize { @connection_established }
+      # Serialized: concurrent first requests must not each run the probe
+      # and possibly settle on different eras (the monitor is reentrant, so
+      # the request plumbing inside may take @mutex again).
+      @mutex.synchronize do
+        return true if @connection_established
 
-      begin
-        @mutex.synchronize do
+        begin
           @connection_established = false
           @initialized = false
-        end
 
-        # Test connectivity with a simple HTTP request
-        test_connection
+          # Test connectivity with a simple HTTP request
+          test_connection
 
-        # Perform MCP initialization handshake
-        perform_initialize
+          # Establish the protocol era: server/discover for a modern server,
+          # the initialize handshake for a legacy one.
+          negotiate_protocol
 
-        # Start long-lived GET connection for server events
-        start_events_connection
+          # Long-lived GET stream for server events: legacy only. MCP
+          # 2026-07-28 removed the GET endpoint; change notifications arrive
+          # on subscriptions/listen streams instead.
+          start_events_connection unless modern?
 
-        @mutex.synchronize do
           @connection_established = true
           @initialized = true
-        end
 
-        true
-      rescue MCPClient::Errors::ConnectionError => e
-        cleanup
-        raise e
-      rescue StandardError => e
-        cleanup
-        raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
+          true
+        rescue MCPClient::Errors::ConnectionError => e
+          cleanup
+          raise e
+        rescue StandardError => e
+          cleanup
+          raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
+        end
       end
     end
 
@@ -166,21 +229,18 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool listing
     def list_tools
-      @mutex.synchronize do
-        return @tools if @tools
-      end
-
+      # MCP 2026-07-28 caching: a cached list is served only while fresh, and
+      # only from the entry that carries its hint.
+      cached = fresh_list_value(:tools) { @mutex.synchronize { @tools } }
+      return cached if cached
+
+      # Stale: the raw page cache must go too, or the re-fetch would be
+      # answered from memory.
+      @mutex.synchronize { @tools_data = nil }
       begin
         ensure_connected
 
-        tools_data = request_tools_list
-        @mutex.synchronize do
-          @tools = tools_data.map do |tool_data|
-            MCPClient::Tool.from_json(tool_data, server: self)
-          end
-        end
-
-        @mutex.synchronize { @tools }
+        refetch_or_serve_stale(:tools, stale_list_entry(:tools)) { fetch_tools_list }
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -199,9 +259,15 @@ module MCPClient
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def call_tool(tool_name, parameters)
       rpc_request('tools/call', build_named_request_params(tool_name, parameters))
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ValidationError
       # Re-raise connection/transport errors directly to match test expectations
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
     rescue StandardError => e
       # For all other errors, wrap in ToolCallError
       raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
@@ -228,11 +294,17 @@ module MCPClient
       require_capability!('completions', method: 'completion/complete')
       params = { ref: ref, argument: argument }
       params[:context] = context if context
-      result = rpc_request('completion/complete', params)
+      result = require_complete_result!(rpc_request('completion/complete', params), 'completion/complete')
       result['completion'] || { 'values' => [] }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
            MCPClient::Errors::CapabilityError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
     end
@@ -242,13 +314,31 @@ module MCPClient
     #   'critical', 'alert', 'emergency')
     # @return [Hash] empty result on success
     # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @deprecated Logging is deprecated since MCP 2026-07-28 (SEP-2577);
+    #   earliest removal is the first revision released on or after
+    #   2027-07-28. Have the server log to stderr (stdio) or use
+    #   OpenTelemetry instead.
     def log_level=(level)
+      MCPClient::Deprecations.warn(:logging, @logger)
       ensure_connected
+      # MCP 2026-07-28 removed logging/setLevel: the level travels per request
+      # in _meta["io.modelcontextprotocol/logLevel"].
+      if modern?
+        @log_level = validate_log_level!(level)
+        return
+      end
+
       require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
-           MCPClient::Errors::CapabilityError
+           MCPClient::Errors::CapabilityError, ArgumentError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
     end
@@ -257,29 +347,40 @@ module MCPClient
     # @return [Array<MCPClient::Prompt>] list of available prompts
     # @raise [MCPClient::Errors::PromptGetError] if prompts list retrieval fails
     def list_prompts
-      @mutex.synchronize do
-        return @prompts if @prompts
-      end
+      cached = fresh_list_value(:prompts) { @mutex.synchronize { @prompts } }
+      return cached if cached
 
+      @mutex.synchronize { @prompts_data = nil }
       begin
         ensure_connected
-
-        prompts_data = request_prompts_list
-        @mutex.synchronize do
-          @prompts = prompts_data.map do |prompt_data|
-            MCPClient::Prompt.from_json(prompt_data, server: self)
-          end
-        end
-
-        @mutex.synchronize { @prompts }
+        refetch_or_serve_stale(:prompts, stale_list_entry(:prompts)) { fetch_prompts_list }
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
-        # Re-raise these errors directly
         raise
       rescue StandardError => e
         raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
       end
     end
 
+    # Fetch and cache the prompt list.
+    # @return [Array<MCPClient::Prompt>]
+    def fetch_prompts_list
+      ensure_connected
+
+      prompts = request_prompts_list.map { |prompt_data| MCPClient::Prompt.from_json(prompt_data, server: self) }
+      @mutex.synchronize do
+        @prompts = attach_list_value(:prompts, prompts) ? prompts : nil
+      end
+
+      # This request's own list, never a re-read of @prompts (another
+      # request may have stored its list in between).
+      prompts
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      # Re-raise these errors directly
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
+    end
+
     # Get a prompt with the given parameters
     # @param prompt_name [String] the name of the prompt to get
     # @param parameters [Hash] the parameters to pass to the prompt
@@ -290,6 +391,12 @@ module MCPClient
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::PromptGetError, "Error getting prompt '#{prompt_name}': #{e.message}"
     rescue StandardError => e
       # For all other errors, wrap in PromptGetError
       raise MCPClient::Errors::PromptGetError, "Error getting prompt '#{prompt_name}': #{e.message}"
@@ -300,44 +407,69 @@ module MCPClient
     # @return [Hash] result containing resources array and optional nextCursor
     # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
     def list_resources(cursor: nil)
-      @mutex.synchronize do
-        return @resources_result if @resources_result && !cursor
-      end
+      cached = cursor ? nil : fresh_list_value(:resources) { @mutex.synchronize { @resources_result } }
+      return cached if cached
 
       begin
         ensure_connected
-
-        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_result = resources_result unless cursor
+        unless cursor
+          return refetch_or_serve_stale(:resources, stale_list_entry(:resources)) do
+            fetch_resources_list(nil)
+          end
         end
 
-        resources_result
+        fetch_resources_list(cursor)
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
-        # Re-raise these errors directly
         raise
       rescue StandardError => e
         raise MCPClient::Errors::ResourceReadError, "Error listing resources: #{e.message}"
       end
     end
 
+    # Fetch one page of resources/list, caching the first page.
+    # @param cursor [String, nil]
+    # @return [Hash]
+    def fetch_resources_list(cursor)
+      params = {}
+      params['cursor'] = cursor if cursor
+      epoch = cache_epoch(:resources)
+      answer = fetching_list_page(:resources, cursor) { rpc_request('resources/list', params) }
+      result = require_complete_result!(answer, 'resources/list')
+      record_cache_hint(:resources, result, epoch: epoch) unless cursor
+
+      resources = (result['resources'] || []).map do |resource_data|
+        MCPClient::Resource.from_json(resource_data, server: self)
+      end
+
+      resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+
+      # A list invalidated while in flight is returned but not cached.
+      @mutex.synchronize do
+        unless cursor
+          @resources_result = attach_list_value(:resources, resources_result) ? resources_result : nil
+        end
+      end
+
+      resources_result
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      # Re-raise these errors directly
+      raise
+    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 [Array<MCPClient::ResourceContent>] array of resource contents
     # @raise [MCPClient::Errors::ResourceReadError] if resource reading fails
     def read_resource(uri)
-      result = rpc_request('resources/read', { uri: uri })
-      contents = result['contents'] || []
-      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
+      ensure_connected
+      read_resource_with_cache(uri) { |sent| rpc_request('resources/read', { uri: sent }) }
+    rescue MCPClient::Errors::ServerError => e
+      raise if e.protocol_error?
+      raise resource_not_found_error(uri, e) if resource_not_found_response?(e)
+
+      raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly
       raise
@@ -351,19 +483,52 @@ module MCPClient
     # @return [Hash] result containing resourceTemplates array and optional nextCursor
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
     def list_resource_templates(cursor: nil)
+      # Only a list the server itself bounded is served from here: a
+      # positive ttlMs means no second request, while a list with no hint
+      # (a 2025-11-25 server) is asked for again, as it was before this
+      # transport cached anything (MCP 2026-07-28 caching).
+      cached = cursor ? nil : hinted_list_value(:templates)
+      return cached if cached
+
+      begin
+        ensure_connected
+        unless cursor
+          return refetch_or_serve_stale(:templates, stale_list_entry(:templates)) do
+            fetch_templates_list(nil)
+          end
+        end
+
+        fetch_templates_list(cursor)
+      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
+    end
+
+    # Fetch one page of resources/templates/list, caching the first page.
+    # @param cursor [String, nil]
+    # @return [Hash]
+    def fetch_templates_list(cursor)
       params = {}
       params['cursor'] = cursor if cursor
-      result = rpc_request('resources/templates/list', params)
+      epoch = cache_epoch(:templates)
+      answer = fetching_list_page(:templates, cursor) { rpc_request('resources/templates/list', params) }
+      result = require_complete_result!(answer, 'resources/templates/list')
+      record_cache_hint(:templates, result, epoch: epoch) unless cursor
 
       templates = (result['resourceTemplates'] || []).map do |template_data|
         MCPClient::ResourceTemplate.from_json(template_data, server: self)
       end
+      templates_result = { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
 
-      { '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}"
+      @mutex.synchronize do
+        unless cursor
+          @templates_result = attach_list_value(:templates, templates_result) ? templates_result : nil
+        end
+      end
+
+      templates_result
     end
 
     # Subscribe to resource updates
@@ -373,6 +538,13 @@ module MCPClient
     def subscribe_resource(uri)
       ensure_connected
       require_capability!('resources', 'subscribe', method: 'resources/subscribe')
+      # MCP 2026-07-28 replaced resources/subscribe with a subscriptions/listen
+      # stream carrying resourceSubscriptions.
+      if modern?
+        subscribe_resource_via_listen(uri)
+        return true
+      end
+
       rpc_request('resources/subscribe', { uri: uri })
       true
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
@@ -389,6 +561,11 @@ module MCPClient
     def unsubscribe_resource(uri)
       ensure_connected
       require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
+      if modern?
+        unsubscribe_resource_via_listen(uri)
+        return true
+      end
+
       rpc_request('resources/unsubscribe', { uri: uri })
       true
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
@@ -402,6 +579,10 @@ module MCPClient
     def apply_request_headers(req, request)
       super
 
+      # Modern servers have no session; the base class added the 2026-07-28
+      # request metadata headers.
+      return if modern?
+
       # Add session and protocol version headers for non-initialize requests
       return unless request['method'] != 'initialize'
 
@@ -429,7 +610,7 @@ module MCPClient
       session_id = response.headers['mcp-session-id'] || response.headers['Mcp-Session-Id']
       if session_id
         if valid_session_id?(session_id)
-          @session_id = session_id
+          capture_session_id(session_id)
           @logger.debug("Captured session ID: #{@session_id}")
         else
           @logger.warn("Invalid session ID format received: #{session_id.inspect}")
@@ -452,6 +633,10 @@ module MCPClient
     # Clean up the server connection
     # Properly closes HTTP connections, stops threads, and clears cached state
     def cleanup
+      # Only an established session ends a task's namespace; a sessionless
+      # (MCP 2026-07-28) connection is merely closed, and a connection that
+      # never came up has nothing to end — see #ending_session?.
+      bump_session_epoch if ending_session?
       @mutex.synchronize do
         return unless @connection_established || @initialized
 
@@ -461,6 +646,9 @@ module MCPClient
         @connection_established = false
         @initialized = false
 
+        # Subscription streams (MCP 2026-07-28) end with the connection
+        close_listen_streams
+
         # Attempt to terminate session before cleanup
         begin
           terminate_session if @session_id
@@ -492,10 +680,27 @@ module MCPClient
         @prompts_data = nil
         @resources = nil
         @resources_data = nil
-        @buffer = ''
+        @resources_result = nil
+        @templates_result = nil
+        @buffer = +''
+        @buffer_scanned = 0
 
         @logger.info('Cleanup completed')
       end
+      # Cached results and their hints belong to the connection (and its
+      # authorization context) that was just torn down; outside @mutex, as
+      # the cache has its own lock.
+      clear_result_cache
+    ensure
+      # Everything this transport left on this thread — the notes of the
+      # entries it served and recorded, the credentials, parameters and
+      # metadata of its requests — describes a slice that will never be
+      # tagged and a request that will never be made. Dropped after the
+      # session was terminated, never before: the DELETE that terminates it
+      # is a request of this transport's own, and the recorder on its
+      # connection would put its Authorization fingerprint straight back on
+      # this thread.
+      forget_transport_thread_state
     end
 
     # Register a callback for elicitation requests (MCP 2025-06-18)
@@ -506,6 +711,13 @@ module MCPClient
     end
 
     # Register a callback for roots/list requests (MCP 2025-06-18)
+    #
+    # @deprecated Roots is deprecated since MCP 2026-07-28 (SEP-2577); earliest
+    #   removal is the first revision released on or after 2027-07-28. Registering
+    #   a handler is not itself use of Roots — a handler that answers with no root
+    #   exposes nothing deprecated — but a handler that answers with a root adopts
+    #   the deprecated feature and raises the notice. Pass directories or files
+    #   through tool parameters, resource URIs or server configuration instead.
     # @param block [Proc] callback that receives (request_id, params) and returns response hash
     # @return [void]
     def on_roots_list_request(&block)
@@ -513,6 +725,11 @@ module MCPClient
     end
 
     # Register a callback for sampling requests (MCP 2025-11-25)
+    #
+    # @deprecated Sampling is deprecated since MCP 2026-07-28 (SEP-2577); earliest
+    #   removal is the first revision released on or after 2027-07-28. Integrate
+    #   directly with the LLM provider API instead of serving
+    #   sampling/createMessage.
     # @param block [Proc] callback that receives (request_id, params) and returns response hash
     # @return [void]
     def on_sampling_request(&block)
@@ -534,6 +751,17 @@ module MCPClient
 
     # Default options for server initialization
     # @return [Hash] Default options
+    # Validate the configured decompression ceiling.
+    # @param value [Object] the max_decompressed_body_bytes option
+    # @return [Integer] the validated positive byte limit
+    # @raise [ArgumentError] if the value is not a positive Integer
+    def validate_decompression_limit(value)
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError,
+            "max_decompressed_body_bytes must be a positive Integer, got #{value.inspect}"
+    end
+
     def default_options
       {
         endpoint: '/rpc',
@@ -544,7 +772,10 @@ module MCPClient
         name: nil,
         logger: nil,
         oauth_provider: nil,
-        faraday_config: nil
+        faraday_config: nil,
+        max_decompressed_body_bytes: JsonRpcTransport::MAX_DECOMPRESSED_BODY_BYTES,
+        protocol: :auto,
+        discover_timeout: nil
       }
     end
 
@@ -569,65 +800,50 @@ module MCPClient
     # @return [void]
     # @raise [MCPClient::Errors::ConnectionError] if connection is not established
     def ensure_connected
-      return if @mutex.synchronize { @connection_established && @initialized }
+      # Serialized on the transport monitor (reentrant, so the nested
+      # cleanup/connect may take it again): checking the flags and acting on
+      # them must be one step. Otherwise a caller that observed "disconnected"
+      # can be overtaken by one that reconnects, and then tear that fresh
+      # connection down — terminating its session and re-running the era
+      # probe.
+      @mutex.synchronize do
+        return if @connection_established && @initialized
 
-      @logger.debug('Connection not active, attempting to reconnect before request')
-      cleanup
-      connect
+        @logger.debug('Connection not active, attempting to reconnect before request')
+        cleanup
+        connect
+      end
     end
 
     # Request the tools list using JSON-RPC
     # @return [Array<Hash>] the tools data
     # @raise [MCPClient::Errors::ToolCallError] if tools list retrieval fails
     def request_tools_list
-      @mutex.synchronize do
-        return @tools_data.dup if @tools_data
-      end
-
       # Follow nextCursor across pages so the full tool list is returned even
-      # when the server paginates.
-      tools = request_paginated_list('tools/list', 'tools')
-
-      @mutex.synchronize { @tools_data = tools }
-      @mutex.synchronize { @tools_data.dup }
+      # when the server paginates. The raw pages are this fetch's own: a
+      # shared copy could answer a concurrent caller under other
+      # credentials with a privately scoped list (MCP 2026-07-28 caching).
+      request_paginated_list('tools/list', 'tools')
     end
 
     # Request the prompts list using JSON-RPC
     # @return [Array<Hash>] the prompts data
     # @raise [MCPClient::Errors::PromptGetError] if prompts list retrieval fails
     def request_prompts_list
-      @mutex.synchronize do
-        return @prompts_data.dup if @prompts_data
-      end
-
-      # Follow nextCursor across pages so the full prompt list is returned.
-      prompts = request_paginated_list('prompts/list', 'prompts')
-
-      @mutex.synchronize { @prompts_data = prompts }
-      @mutex.synchronize { @prompts_data.dup }
+      # Follow nextCursor across pages so the full prompt list is returned;
+      # the raw pages are this fetch's own (see request_tools_list).
+      request_paginated_list('prompts/list', 'prompts')
     end
 
     # Request the resources list using JSON-RPC
     # @return [Array<Hash>] the resources data
     # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
     def request_resources_list
-      @mutex.synchronize do
-        return @resources_data if @resources_data
-      end
-
+      # The raw list is this fetch's own (see request_tools_list).
       result = rpc_request('resources/list')
 
-      if result.is_a?(Hash) && result['resources']
-        @mutex.synchronize do
-          @resources_data = result['resources']
-        end
-        return @mutex.synchronize { @resources_data.dup }
-      elsif result.is_a?(Array) || result
-        @mutex.synchronize do
-          @resources_data = result
-        end
-        return @mutex.synchronize { @resources_data.dup }
-      end
+      return result['resources'].dup if result.is_a?(Hash) && result['resources']
+      return result.dup if result.is_a?(Array) || result
 
       raise MCPClient::Errors::ResourceReadError, 'Failed to get resources list from JSON-RPC request'
     end
@@ -723,12 +939,17 @@ module MCPClient
     end
 
     # Reconnect delay for the events stream: the server's SSE retry directive
-    # (in ms) when present, otherwise the caller's backoff value.
+    # (in ms) when present, otherwise the caller's backoff value. The
+    # peer-controlled directive is floored at MIN_EVENTS_RECONNECT_DELAY so a
+    # zero/near-zero value cannot drive a tight reconnect loop; the
+    # deadline-bounded resumption loop intentionally keeps honoring zero.
     # @param fallback_seconds [Numeric] exponential-backoff fallback
     # @return [Numeric] delay in seconds
     def events_reconnect_delay(fallback_seconds)
       retry_ms = @sse_retry_ms
-      retry_ms ? retry_ms / 1000.0 : fallback_seconds
+      return fallback_seconds unless retry_ms
+
+      [retry_ms / 1000.0, MIN_EVENTS_RECONNECT_DELAY].max
     end
 
     # Wait for a response replayed after the POST stream was closed before
@@ -770,8 +991,11 @@ module MCPClient
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @read_timeout
       state = { cursor: cursor, retry_ms: retry_ms }
       # SEP-1699: the client MUST respect the server's retry directive before
-      # attempting to reconnect.
-      delay = retry_ms ? retry_ms / 1000.0 : 0
+      # attempting to reconnect. With no directive the FIRST GET goes out
+      # immediately, as before this change: delaying it adds latency to every
+      # resumption and, on a short read_timeout, can burn the whole budget
+      # before any I/O happens.
+      delay = retry_ms ? resumption_delay(retry_ms) : 0
 
       loop do
         sleep(delay) if delay.positive?
@@ -779,10 +1003,21 @@ module MCPClient
         break unless @mutex.synchronize { @pending_stream_responses.key?(request_id) }
         break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
 
-        delay = state[:retry_ms] ? state[:retry_ms] / 1000.0 : SSE_RECONNECT_DELAY
+        delay = resumption_delay(state[:retry_ms])
       end
     end
 
+    # Delay before the next resumption GET: the peer's retry directive when
+    # present, floored so "retry: 0" cannot turn the deadline window into a
+    # back-to-back request loop, otherwise the standard reconnect delay.
+    # @param retry_ms [Integer, nil] retry directive in milliseconds
+    # @return [Numeric] delay in seconds
+    def resumption_delay(retry_ms)
+      return SSE_RECONNECT_DELAY unless retry_ms
+
+      [retry_ms / 1000.0, MIN_RESUMPTION_RECONNECT_DELAY].max
+    end
+
     # One GET with the current cursor; complete SSE events are dispatched
     # through the standard server-message path, which routes replayed
     # responses to their registered waiters. `id:` and `retry:` fields
@@ -803,6 +1038,10 @@ module MCPClient
         req.options.on_data = proc do |chunk, _bytes|
           buffer << chunk
           process_resumption_buffer(buffer, state)
+          # A peer replaying delimiter-free data must not grow this buffer
+          # without bound: abort the GET (rescued below); the deadline-bounded
+          # resumption loop decides whether to retry with a fresh buffer.
+          enforce_sse_buffer_cap!(buffer)
         end
       end
     rescue StandardError => e
@@ -815,10 +1054,16 @@ module MCPClient
     # @param state [Hash] mutable resumption state (:cursor, :retry_ms)
     # @return [void]
     def process_resumption_buffer(buffer, state)
-      while (separator = buffer.match(/\r\n\r\n|\n\n/))
+      # Same incremental scan as the events stream: without a cursor every
+      # chunk re-matched the whole accumulated buffer from byte zero.
+      scan_from = [state[:scanned].to_i - 3, 0].max
+      while (separator = buffer.match(/\r\n\r\n|\n\n/, scan_from))
         event_text = buffer.slice!(0, separator.end(0))
         handle_resumption_event(event_text, state)
+        scan_from = 0
+        state[:scanned] = 0
       end
+      state[:scanned] = buffer.length
     end
 
     # Parse one SSE event received on a resumption stream: track `id:` lines
@@ -835,7 +1080,9 @@ module MCPClient
           data_lines << line.sub(/\Adata:\s*/, '')
         elsif line.start_with?('id:')
           id = line.sub(/\Aid:\s*/, '').strip
-          state[:cursor] = id unless id.empty?
+          # Same validation as the events stream: this cursor is echoed in
+          # the Last-Event-ID header of the next resumption GET.
+          state[:cursor] = id if retainable_event_id?(id)
         elsif line.start_with?('retry:')
           raw = line.sub(/\Aretry:\s*/, '').strip
           state[:retry_ms] = raw.to_i if raw.match?(/\A\d+\z/)
@@ -865,6 +1112,7 @@ module MCPClient
       req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
       # MCP: authorization MUST be included in every HTTP request
       @oauth_provider&.apply_authorization(req)
+      note_request_authorization(req.headers['Authorization'])
       # SEP-1699: resumption is via GET with the Last-Event-ID cursor, so the
       # server can replay messages missed since the last received event.
       last_event_id = @mutex.synchronize { @last_event_id }
@@ -875,22 +1123,64 @@ module MCPClient
     # Buffers partial chunks and processes complete SSE events
     # @param chunk [String] the chunk to process
     def process_event_chunk(chunk)
-      @logger.debug("Processing event chunk: #{chunk.inspect}") if @logger.level <= Logger::DEBUG
+      # Size only: the chunk is raw wire data carrying sampling prompts,
+      # elicitation content and tool results.
+      @logger.debug("Processing event chunk (#{describe_body_size(chunk)})") if @logger.level <= Logger::DEBUG
 
       @mutex.synchronize do
-        @buffer += chunk
-
-        # Extract complete events (SSE format: events end with double newline)
-        while (event_end = @buffer.index("\n\n") || @buffer.index("\r\n\r\n"))
+        # Append in place and scan only the newly arrived bytes. `+= chunk`
+        # reallocated and copied the whole buffer per callback, and each
+        # search restarted at index 0, so an unterminated event delivered in
+        # N chunks cost O(N^2) work: capped memory, uncapped CPU.
+        @buffer << chunk
+
+        scan_from = [@buffer_scanned - 3, 0].max
+        while (event_end = next_buffer_event_end(scan_from))
           event_data = extract_event(event_end)
           parse_and_handle_event(event_data)
+          scan_from = 0
+          @buffer_scanned = 0
+        end
+        @buffer_scanned = @buffer.length
+
+        # Everything left is a partial event awaiting its terminator; cap how
+        # much a peer may accumulate. The raise propagates (unlike processing
+        # errors below) so the events loop drops this connection and its
+        # backoff takes over — memory stays bounded either way.
+        begin
+          enforce_sse_buffer_cap!(@buffer)
+        rescue MCPClient::Errors::ConnectionError
+          @buffer = +''
+          @buffer_scanned = 0
+          raise
         end
       end
+    rescue MCPClient::Errors::ConnectionError
+      raise
     rescue StandardError => e
       @logger.error("Error processing event chunk: #{e.message}")
       @logger.debug(e.backtrace.join("\n")) if @logger.level <= Logger::DEBUG
     end
 
+    # Index of the earliest event terminator at or after an offset.
+    # @param offset [Integer] character offset to start searching from
+    # @return [Integer, nil] index of the terminator, or nil if none yet
+    def next_buffer_event_end(offset)
+      lf = @buffer.index("\n\n", offset)
+      crlf = @buffer.index("\r\n\r\n", offset)
+      [lf, crlf].compact.min
+    end
+
+    # @param buffer [String] a partial-event SSE buffer
+    # @raise [MCPClient::Errors::ConnectionError] when the buffer exceeds MAX_SSE_BUFFER_BYTES
+    def enforce_sse_buffer_cap!(buffer)
+      return if buffer.bytesize <= MAX_SSE_BUFFER_BYTES
+
+      raise MCPClient::Errors::ConnectionError,
+            "SSE event exceeded the maximum buffered size (#{MAX_SSE_BUFFER_BYTES} bytes) " \
+            'without a terminator'
+    end
+
     # Extract a single event from the buffer
     # @param event_end [Integer] the position where the event ends
     # @return [String] the extracted event data
@@ -922,9 +1212,12 @@ module MCPClient
           # SSE allows multiple data lines that should be joined with newlines
           data_lines << line[5..].strip
         elsif line.start_with?('id:')
-          # Track event ID for resumability (MCP future enhancement)
+          # Track event ID for resumability (MCP future enhancement). The id
+          # is peer-controlled and gets echoed in the Last-Event-ID header, so
+          # only a bounded, header-safe value is retained; the previous valid
+          # cursor is kept when one is rejected.
           event[:id] = line[3..].strip
-          @last_event_id = event[:id]
+          @last_event_id = event[:id] if retainable_event_id?(event[:id])
         elsif line.start_with?('retry:')
           # SEP-1699: the client MUST respect the server's retry directive
           # (milliseconds) when reconnecting; zero is a valid directive.
@@ -947,10 +1240,19 @@ module MCPClient
       return if data.empty?
 
       begin
-        dispatch_server_message(JSON.parse(data))
+        message = JSON.parse(data)
+        unless message.is_a?(Hash)
+          # A JSON-parseable scalar/array is not a JSON-RPC message; dispatch
+          # would raise on it. Log the type, never the value.
+          @logger.warn("Skipping non-object JSON-RPC message on the events stream (#{message.class})")
+          return
+        end
+
+        dispatch_server_message(message)
       rescue JSON::ParserError => e
-        @logger.error("Invalid JSON in server message: #{e.message}")
-        @logger.debug("Raw data: #{data.inspect}") if @logger.level <= Logger::DEBUG
+        # The parser message names the failure position, not the payload; the
+        # payload itself stays out of the log.
+        @logger.error("Invalid JSON in server message: #{describe_parse_error(e, data)}")
       end
     end
 
@@ -959,6 +1261,29 @@ module MCPClient
     # interleaved on a POST SSE response stream.
     # @param message [Hash] the parsed JSON-RPC message
     def dispatch_server_message(message)
+      # Host code reached from here -- a notification listener, a handler for
+      # a server-initiated request -- may issue a request of its own while the
+      # response that carried this message is still being parsed. That request
+      # is an exchange of its own, and the call still waiting for this response
+      # must keep both its recorded definition and its own failures
+      # (HttpTransportBase::RequestRecovery#dispatching_to_host).
+      dispatching_to_host { dispatch_server_message_now(message) }
+    end
+
+    # @param message [Hash] the parsed JSON-RPC message
+    def dispatch_server_message_now(message)
+      if protocol_era == :modern && message['method'] && message.key?('id')
+        # MCP 2026-07-28: "The server MUST NOT send independent JSON-RPC
+        # requests on this stream" — server-to-client interactions are
+        # embedded in InputRequiredResult. There is no response channel
+        # either (clients MUST NOT POST responses), so the request is dropped.
+        # Judged by the ESTABLISHED era: while the probe is in flight a legacy
+        # server may be waiting for its ping on the probe's own stream.
+        @logger.warn("Ignoring server-initiated request #{message['method']} on a response stream: " \
+                     'not permitted by MCP 2026-07-28')
+        return
+      end
+
       # Handle ping requests from server (keepalive mechanism)
       if message['method'] == 'ping' && message.key?('id')
         handle_ping_request(message['id'])
@@ -967,7 +1292,7 @@ module MCPClient
         handle_server_request(message)
       elsif message['method'] && !message.key?('id')
         # Handle server notifications (messages without id)
-        @notification_callback&.call(message['method'], message['params'])
+        route_notification(message['method'], message['params'])
       elsif message.key?('id')
         # A response replayed on the events stream after its POST stream was
         # closed before delivery (SEP-1699 resumption)
@@ -985,26 +1310,9 @@ module MCPClient
         result: {}
       }
 
-      # Send pong response in a separate thread to avoid blocking event processing
-      Thread.new do
-        conn = http_connection
-        response = conn.post(@endpoint) do |req|
-          @headers.each { |k, v| req.headers[k] = v }
-          req.headers['Mcp-Session-Id'] = @session_id if @session_id
-          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
-          # MCP: authorization MUST be included in every HTTP request
-          @oauth_provider&.apply_authorization(req)
-          req.body = pong_response.to_json
-        end
-
-        if response.success?
-          @logger.debug("Sent pong response for ping ID: #{ping_id}") if @logger.level <= Logger::DEBUG
-        else
-          @logger.warn("Failed to send pong response: HTTP #{response.status}")
-        end
-      rescue StandardError => e
-        @logger.error("Failed to send pong response: #{e.message}")
-      end
+      # Pongs go through the same bounded response path as every other
+      # server-initiated reply, so a ping flood cannot fan out threads.
+      post_jsonrpc_response(pong_response)
     end
 
     # Handle incoming JSON-RPC request from server (MCP 2025-06-18)
@@ -1029,8 +1337,11 @@ module MCPClient
         send_error_response(request_id, -32_601, "Method not found: #{method}")
       end
     rescue StandardError => e
+      # The exception message is host-internal (file paths, connection
+      # strings, library internals): log it locally, but answer the peer with
+      # a constant message so failures cannot be used to probe the host.
       @logger.error("Error handling server request: #{e.message}")
-      send_error_response(request_id, -32_603, "Internal error: #{e.message}")
+      send_error_response(request_id, -32_603, 'Internal error')
     end
 
     # Handle elicitation/create request from server (MCP 2025-11-25)
@@ -1067,6 +1378,10 @@ module MCPClient
 
       # Call the registered callback
       result = @roots_list_request_callback.call(request_id, params)
+      # Serving a roots/list answer that carries a root means this host
+      # declared, and is using, the deprecated Roots capability (SEP-2577) —
+      # with or without a Client. An empty answer is not use of it.
+      warn_roots_deprecated(result)
 
       # Send the response back to the server (echoing related-task _meta)
       send_roots_list_response(request_id, merge_related_task_meta(result, params))
@@ -1080,10 +1395,18 @@ module MCPClient
       # 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')
+        # sampling.mdx § Error Handling reserves -1 for "User rejected sampling
+        # request"; a capability this client never declared is an unsupported
+        # method (-32601, Method not found), as Client#handle_sampling_request answers.
+        send_error_response(request_id, -32_601, 'Sampling not supported')
         return
       end
 
+      # Sampling, and the includeContext values it may carry, are deprecated
+      # (SEP-2577, SEP-2596) — with or without a Client.
+      warn_sampling_deprecated(params)
+      return if refused_undeclared_sampling_tools?(request_id, params)
+
       # Call the registered callback
       result = @sampling_request_callback.call(request_id, params)
 
@@ -1184,7 +1507,31 @@ module MCPClient
     # @return [void]
     # @private
     def post_jsonrpc_response(response)
-      # Send response in a separate thread to avoid blocking event processing
+      # Send the response in a separate thread to avoid blocking event
+      # processing, but never beyond the concurrency budget: server requests
+      # arrive at the peer's rate, and each unanswered POST would otherwise
+      # pin one thread and one connection.
+      unless acquire_response_post_slot
+        log_response_post_saturation
+        return
+      end
+
+      begin
+        start_response_post_thread(response)
+      rescue ThreadError => e
+        # Thread.new failed, so the ensure inside the block never runs and the
+        # reservation would leak. Eight such failures would silently mute this
+        # instance's replies for the rest of its life, including after
+        # reconnect (cleanup does not reset the counter).
+        release_response_post_slot
+        @logger.error("Failed to start response POST thread: #{e.message}")
+      end
+    end
+
+    # Spawn the worker that POSTs one server-initiated response.
+    # @param response [Hash] the JSON-RPC response
+    # @return [Thread]
+    def start_response_post_thread(response)
       Thread.new do
         conn = http_connection
         json_body = JSON.generate(response)
@@ -1195,17 +1542,60 @@ module MCPClient
           req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
           # MCP: authorization MUST be included in every HTTP request
           @oauth_provider&.apply_authorization(req)
+          note_request_authorization(req.headers['Authorization'])
           req.body = json_body
         end
 
         if resp.success?
-          @logger.debug("Sent JSON-RPC response: #{json_body}")
+          @logger.debug("Sent JSON-RPC response: #{describe_jsonrpc_message(response)}")
         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}")
+      ensure
+        release_response_post_slot
+      end
+    end
+
+    # Warn that the response-POST budget is saturated, at most once per
+    # SATURATION_LOG_INTERVAL.
+    #
+    # The peer controls how often this path is reached, so logging every
+    # rejection (at WARN, which the default logger emits) would just trade a
+    # thread-exhaustion vector for a log-volume one. The peer-supplied request
+    # id is deliberately omitted for the same reason.
+    # @return [void]
+    def log_response_post_saturation
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      dropped = @mutex.synchronize do
+        @dropped_response_posts += 1
+        next nil if @last_saturation_log_at && now - @last_saturation_log_at < SATURATION_LOG_INTERVAL
+
+        @last_saturation_log_at = now
+        @dropped_response_posts
       end
+      return unless dropped
+
+      @logger.warn("Dropping server-initiated responses: #{MAX_CONCURRENT_RESPONSE_POSTS} " \
+                   "response POSTs already in flight (#{dropped} dropped so far)")
+    end
+
+    # Reserve one slot of the response-POST concurrency budget.
+    # @return [Boolean] whether a slot was available
+    def acquire_response_post_slot
+      @mutex.synchronize do
+        return false if @response_post_count >= MAX_CONCURRENT_RESPONSE_POSTS
+
+        @response_post_count += 1
+        true
+      end
+    end
+
+    # Release a slot reserved by acquire_response_post_slot.
+    # @return [void]
+    def release_response_post_slot
+      @mutex.synchronize { @response_post_count -= 1 }
     end
   end
 end