ruby-mcp-client 2.0.0 → 3.0.0

data/lib/mcp_client/server_sse.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'request_meta_scope'
 require 'uri'
 require 'json'
 require 'monitor'
@@ -7,26 +8,41 @@ require 'logger'
 require 'faraday'
 require 'faraday/retry'
 require 'faraday/follow_redirects'
+require_relative 'deprecations'
 
 module MCPClient
   # Implementation of MCP server that communicates via Server-Sent Events (SSE)
   # Useful for communicating with remote MCP servers over HTTP
   #
+  # @deprecated The HTTP+SSE transport has been deprecated since MCP
+  #   2025-03-26 and is listed in the 2026-07-28 deprecated features
+  #   registry (SEP-2596); earliest removal is three months after SEP-2596
+  #   reaches Final. Use {MCPClient::ServerStreamableHTTP}.
+  #
   # @note Elicitation Support (MCP 2025-06-18)
   #   This transport FULLY supports server-initiated elicitation requests via bidirectional
   #   JSON-RPC. The server sends elicitation/create requests via the SSE stream, and the
   #   client responds via HTTP POST to the RPC endpoint. This provides full elicitation
   #   capability for remote servers.
   class ServerSSE < ServerBase
+    require_relative 'request_authorization'
     require_relative 'server_sse/sse_parser'
     require_relative 'server_sse/json_rpc_transport'
 
     include SseParser
     include JsonRpcTransport
+    # The credentials of the request this thread last sent, kept in the same
+    # slot, with the same empty-slot semantics, as on the other transports:
+    # {#cleanup} drops it with the rest of what this transport left behind.
+    include MCPClient::RequestAuthorization
 
     require_relative 'server_sse/reconnect_monitor'
 
     include ReconnectMonitor
+    # 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
 
     # Ratio of close_after timeout to ping interval
     CLOSE_AFTER_PING_RATIO = 2.5
@@ -40,6 +56,13 @@ module MCPClient
     MAX_RECONNECT_DELAY = 30
     JITTER_FACTOR = 0.25
 
+    # Maximum bytes the SSE parse buffer 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 response event.
+    MAX_SSE_BUFFER_BYTES = 32 * 1024 * 1024
+
     # @!attribute [r] base_url
     #   @return [String] The base URL of the MCP server
     # @!attribute [r] tools
@@ -91,8 +114,14 @@ module MCPClient
       @tools_data = nil
       @request_id = 0
       @sse_results = {}
+      # Ids of requests a caller is actively waiting on. Only responses for
+      # these ids are stored in @sse_results — everything else on the peer
+      # controlled stream is unsolicited and discarded.
+      @pending_request_ids = Set.new
       @mutex = Monitor.new
-      @buffer = ''
+      @buffer = +''
+      # How much of @buffer has already been searched for an event terminator
+      @buffer_scanned = 0
       @sse_connected = false
       @connection_established = false
       @connection_cv = @mutex.new_cond
@@ -131,21 +160,23 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt listing
     def list_prompts
-      @mutex.synchronize do
-        return @prompts if @prompts
-      end
+      # MCP 2026-07-28 caching: a list is served only while its hint is
+      # fresh, and only from the entry that carries the hint.
+      cached = fresh_list_value(:prompts) { @mutex.synchronize { @prompts } }
+      return cached if cached
+
+      @mutex.synchronize { @prompts_data = nil }
 
       begin
         ensure_initialized
 
-        prompts_data = request_prompts_list
+        prompts = request_prompts_list.map { |prompt_data| MCPClient::Prompt.from_json(prompt_data, server: self) }
         @mutex.synchronize do
-          @prompts = prompts_data.map do |prompt_data|
-            MCPClient::Prompt.from_json(prompt_data, server: self)
-          end
+          @prompts = attach_list_value(:prompts, prompts) ? prompts : nil
         end
 
-        @mutex.synchronize { @prompts }
+        # This request's own list, never a re-read of @prompts.
+        prompts
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -167,6 +198,12 @@ module MCPClient
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # 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::PromptGetError, "Error get prompt '#{prompt_name}': #{e.message}"
     rescue StandardError => e
       # For all other errors, wrap in PromptGetError
       raise MCPClient::Errors::PromptGetError, "Error get prompt '#{prompt_name}': #{e.message}"
@@ -179,16 +216,21 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource listing
     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_initialized
 
         params = {}
         params['cursor'] = cursor if cursor
-        result = rpc_request('resources/list', params)
+        epoch = cache_epoch(:resources)
+        answer = fetching_list_page(:resources, cursor) { rpc_request('resources/list', params) }
+        result = require_complete_result!(answer, 'resources/list')
+        # MCP 2026-07-28 caching: the first page's hint decides how long the
+        # cached list may be served, counted from receipt (the list is
+        # attached once converted).
+        record_cache_hint(:resources, result, epoch: epoch) unless cursor
 
         resources = (result['resources'] || []).map do |resource_data|
           MCPClient::Resource.from_json(resource_data, server: self)
@@ -197,7 +239,9 @@ module MCPClient
         resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
 
         @mutex.synchronize do
-          @resources_result = resources_result unless cursor
+          unless cursor
+            @resources_result = attach_list_value(:resources, resources_result) ? resources_result : nil
+          end
         end
 
         resources_result
@@ -217,9 +261,13 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource reading
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def read_resource(uri)
-      result = rpc_request('resources/read', { uri: uri })
-      contents = result['contents'] || []
-      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
+      ensure_initialized
+      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 to match test expectations
       raise
@@ -234,16 +282,35 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @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
+
       ensure_initialized
       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')
+      # MCP 2026-07-28 caching: the first page's hint decides freshness,
+      # counted from receipt (the list is attached once converted).
+      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'] }
+      @mutex.synchronize do
+        unless cursor
+          @templates_result = attach_list_value(:templates, templates_result) ? templates_result : nil
+        end
+      end
+
+      templates_result
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
       raise
     rescue StandardError => e
@@ -290,21 +357,23 @@ 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 list is served only while its hint is
+      # fresh, and only from the entry that carries the hint.
+      cached = fresh_list_value(:tools) { @mutex.synchronize { @tools } }
+      return cached if cached
+
+      @mutex.synchronize { @tools_data = nil }
 
       begin
         ensure_initialized
 
-        tools_data = request_tools_list
+        tools = request_tools_list.map { |tool_data| MCPClient::Tool.from_json(tool_data, server: self) }
         @mutex.synchronize do
-          @tools = tools_data.map do |tool_data|
-            MCPClient::Tool.from_json(tool_data, server: self)
-          end
+          @tools = attach_list_value(:tools, tools) ? tools : nil
         end
 
-        @mutex.synchronize { @tools }
+        # This request's own list, never a re-read of @tools.
+        tools
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -326,6 +395,12 @@ module MCPClient
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # 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}"
@@ -342,11 +417,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
@@ -356,13 +437,24 @@ 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_initialized
       require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
     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 setting log level: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
     end
@@ -371,7 +463,15 @@ 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 }
+      # An already-established connection is another use of the transport,
+      # and another chance at the notice: the first connect may have found
+      # notices disabled, a logger above WARN or a logger that raised, all of
+      # which leave the slot unspent. A long-lived connection would otherwise
+      # never retry it.
+      if @mutex.synchronize { @connection_established }
+        MCPClient::Deprecations.warn(:http_sse_transport, @logger)
+        return true
+      end
 
       # Check for pre-existing auth error (needed for tests)
       pre_existing_auth_error = @mutex.synchronize { @auth_error }
@@ -386,6 +486,10 @@ module MCPClient
         effective_timeout = [@read_timeout || 30, 30].min
         wait_for_connection(timeout: effective_timeout)
         start_activity_monitor
+        # The notice is about using the transport: MCPClient.connect builds
+        # (and tries) an SSE server while probing a URL that may end up on
+        # another transport, so only an established connection counts.
+        MCPClient::Deprecations.warn(:http_sse_transport, @logger)
         true
       rescue MCPClient::Errors::ConnectionError => e
         cleanup
@@ -410,6 +514,12 @@ module MCPClient
     #   multiple connection attempts. This is essential for proper reconnection
     #   logic and exponential backoff.
     def cleanup
+      # 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.
+      forget_transport_thread_state
+      bump_session_epoch
       @mutex.synchronize do
         # Set flags first before killing threads to prevent race conditions
         # where threads might check flags after they're set but before they're killed
@@ -423,7 +533,18 @@ module MCPClient
 
         # Reset the SSE parse buffer so a reconnect never inherits a leftover
         # partial event from the previous connection.
-        @buffer = ''
+        @buffer = +''
+        @buffer_scanned = 0
+
+        # Drop results nobody is waiting for, so peer-supplied state cannot
+        # accumulate across reconnects. Results for still-pending requests are
+        # KEPT: a response can arrive while its POST is still returning, and
+        # the waiter (which reconnects through ensure_sse_connection_active)
+        # is about to consume it. Discarding those reported a timeout for a
+        # tool call the server had already executed — inviting a duplicate
+        # manual retry. unregister_pending_request clears each entry when its
+        # request finishes, so nothing lingers.
+        @sse_results.select! { |id, _| @pending_request_ids.include?(id) }
 
         # Log cleanup for debugging
         @logger.debug('Cleaning up SSE connection')
@@ -469,9 +590,48 @@ module MCPClient
         @sse_conn = nil
 
         @tools = nil
+        @tools_data = nil
+        @prompts = nil
+        @prompts_data = nil
+        @resources_result = nil
+        @templates_result = nil
         # Don't clear auth error as we need it for reporting the correct error
         # Don't reset @consecutive_ping_failures or @reconnect_attempts as they're tracked across reconnections
       end
+      # Cached results and their hints belong to the connection that was just
+      # torn down (MCP 2026-07-28 caching); outside @mutex, as the cache has
+      # its own lock.
+      clear_result_cache
+    end
+
+    # The authorization context of this transport (MCP 2026-07-28 caching,
+    # cacheScope "private"): HTTP+SSE sends the static Authorization header
+    # it was configured with, so that header is both what the next request
+    # would carry and what the last one carried.
+    # @param _kind [Symbol, String, nil] the cache kind (every request carries the same header)
+    # @return [String, nil]
+    def current_authorization_context(_kind = nil)
+      # Through Faraday's case-insensitive table, so several spellings of
+      # the header in the configured hash resolve to the one value a
+      # request would actually carry.
+      authorization_fingerprint(authorization_header_value(faraday_headers(@headers)))
+    end
+
+    # Remember the Authorization a request actually carried once it was sent,
+    # for a request that recorded none of its own. What binds the result is
+    # what the request was built with: `response.env` is mutable and the
+    # response phase may rewrite it (a redaction, a redirect that strips the
+    # header), which would file an authenticated result under the anonymous
+    # context.
+    # @param response [Faraday::Response, nil]
+    # @return [void]
+    def note_sent_authorization(response)
+      return if request_authorization_recorded?
+
+      env = response.respond_to?(:env) ? response.env : nil
+      return unless env.respond_to?(:request_headers) && env.request_headers
+
+      note_request_authorization(authorization_header_value(env.request_headers))
     end
 
     # Register a callback for elicitation requests (MCP 2025-06-18)
@@ -482,6 +642,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)
@@ -489,6 +656,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)
@@ -519,8 +691,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 a server-initiated ping request (MCP ping utility)
@@ -572,6 +747,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))
@@ -604,10 +783,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)
 
@@ -714,10 +901,11 @@ module MCPClient
         # header on all HTTP requests after the initialize handshake.
         req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
         @headers.each { |k, v| req.headers[k] = v }
+        note_request_authorization(authorization_header_value(req.headers))
         req.body = json_body
       end
 
-      @logger.debug("Sent response via HTTP POST: #{json_body}")
+      @logger.debug("Sent response via HTTP POST: #{describe_jsonrpc_message(response)}")
     rescue StandardError => e
       @logger.error("Failed to send response via HTTP POST: #{e.message}")
     end
@@ -777,6 +965,7 @@ module MCPClient
     def establish_sse_connection(conn, sse_path)
       conn.get(sse_path) do |req|
         @headers.each { |k, v| req.headers[k] = v }
+        note_request_authorization(authorization_header_value(req.headers))
 
         req.options.on_data = proc do |chunk, _bytes|
           process_sse_chunk(chunk.dup) if chunk && !chunk.empty?
@@ -839,7 +1028,14 @@ module MCPClient
     # Process an SSE chunk from the server
     # @param chunk [String] the chunk to process
     def process_sse_chunk(chunk)
-      @logger.debug("Processing SSE chunk: #{chunk.inspect}")
+      # Every event in this chunk arrived together, before any of them was
+      # decoded or dispatched: a response is dated from that moment, so a
+      # slow callback on an earlier event in the same chunk cannot make it
+      # look younger than the ttlMs its server sent (MCP 2026-07-28 caching).
+      arrived = monotonic_now if respond_to?(:monotonic_now, true)
+      # Size only: the chunk is raw wire data carrying sampling prompts,
+      # elicitation content and tool results.
+      @logger.debug("Processing SSE chunk (#{describe_body_size(chunk)})")
 
       # Only record activity for real events
       record_activity if chunk.include?('event:')
@@ -850,7 +1046,7 @@ module MCPClient
       event_buffers = extract_complete_events(chunk)
 
       # Process extracted events outside the mutex to avoid deadlocks
-      event_buffers&.each { |event_data| parse_and_handle_sse_event(event_data) }
+      event_buffers&.each { |event_data| parse_and_handle_sse_event(event_data, arrived) }
     end
 
     # Check if the error represents an authorization error
@@ -897,21 +1093,61 @@ module MCPClient
     # @return [Array<String>, nil] array of complete events or nil if none
     # @private
     def extract_complete_events(chunk)
-      event_buffers = nil
+      event_buffers = []
       @mutex.synchronize do
-        @buffer += chunk
-
-        # Extract all complete events from the buffer
-        # Handle both Unix (\n\n) and Windows (\r\n\r\n) line endings
-        event_buffers = []
-        while (event_end = @buffer.index("\n\n") || @buffer.index("\r\n\r\n"))
-          event_data = extract_single_event(event_end)
-          event_buffers << event_data
+        # Append in place. `@buffer += chunk` allocates and copies the whole
+        # buffer on every callback, so an unterminated event delivered in N
+        # chunks costs O(N^2) copying — memory stays capped but a peer can
+        # still burn CPU and thrash the allocator on the way there.
+        @buffer << chunk
+
+        # Rescan only the newly arrived bytes, backing up by the longest
+        # delimiter minus one so one split across two chunks is still found.
+        scan_from = [@buffer_scanned - 3, 0].max
+        while (event_end = next_event_end(scan_from))
+          event_buffers << extract_single_event(event_end)
+          # The buffer shifted; what remains is short (one event at most).
+          scan_from = 0
+          @buffer_scanned = 0
         end
+        @buffer_scanned = @buffer.length
+
+        # Whatever is left is a partial event still awaiting its terminator.
+        # The cap is applied here rather than before appending so a single
+        # oversized chunk that DOES contain complete events is still parsed.
+        fail_oversized_sse_buffer! if @buffer.bytesize > MAX_SSE_BUFFER_BYTES
       end
       event_buffers
     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_event_end(offset)
+      lf = @buffer.index("\n\n", offset)
+      crlf = @buffer.index("\r\n\r\n", offset)
+      [lf, crlf].compact.min
+    end
+
+    # Drop an oversized partial event and fail the connection.
+    #
+    # Recording the cause matters: this runs inside Faraday's on_data callback
+    # on the SSE worker thread, whose generic rescue would otherwise leave
+    # callers with a bare "connection lost" and no reason. Mirrors the
+    # endpoint-URI failure path so wait_for_connection surfaces it promptly.
+    # @raise [MCPClient::Errors::ConnectionError] always
+    def fail_oversized_sse_buffer!
+      message = "SSE event exceeded the maximum buffered size (#{MAX_SSE_BUFFER_BYTES} bytes) " \
+                'without a terminator'
+      @buffer = +''
+      @buffer_scanned = 0
+      @connection_error = message
+      @connection_established = false
+      @connection_cv.broadcast
+      @logger.error(message)
+      raise MCPClient::Errors::ConnectionError, message
+    end
+
     # Extract a single event from the buffer
     # @param event_end [Integer] the position where the event ends
     # @return [String] the extracted event data
@@ -946,16 +1182,32 @@ module MCPClient
     # @return [Array<Hash>] the prompts data
     # @raise [MCPClient::Errors::PromptGetError] if prompts list retrieval fails
     # @private
-    def request_prompts_list
+    # Drop a cached list so the next access re-fetches it (change
+    # notification, MCP 2026-07-28 caching).
+    # @param kind [Symbol] :tools, :prompts or :resources
+    # @return [void]
+    def invalidate_list_cache(kind)
       @mutex.synchronize do
-        return @prompts_data.dup if @prompts_data
+        case kind
+        when :tools
+          @tools = nil
+          @tools_data = nil
+        when :prompts
+          @prompts = nil
+          @prompts_data = nil
+        when :resources
+          @resources_result = nil
+        when :templates
+          # resources/list_changed covers resources/templates/list too.
+          @templates_result = nil
+        end
       end
+    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 }
+    def request_prompts_list
+      # 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
@@ -963,23 +1215,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
     # @private
     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 && result['resources']
-        @mutex.synchronize do
-          @resources_data = result['resources']
-        end
-        return @mutex.synchronize { @resources_data.dup }
-      elsif result
-        @mutex.synchronize do
-          @resources_data = result
-        end
-        return @mutex.synchronize { @resources_data.dup }
-      end
+      return result['resources'].dup if result && result['resources']
+      return result.dup if result
 
       raise MCPClient::Errors::ResourceReadError, 'Failed to get resources list from JSON-RPC request'
     end
@@ -989,17 +1229,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] if tools list retrieval fails
     # @private
     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. The
-      # SSE parser no longer writes @tools_data per page, so this method is the
-      # sole writer and only ever caches the COMPLETE list.
-      tools = request_paginated_list('tools/list', 'tools')
-
-      @mutex.synchronize { @tools_data = tools }
-      @mutex.synchronize { @tools_data.dup }
+      # 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
   end
 end