ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/server_base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'deprecations'
+
 module MCPClient
   # Base class for MCP servers - serves as the interface for different server implementations
   class ServerBase
@@ -7,8 +9,10 @@ module MCPClient
     #   @return [String] the name of the server
     attr_reader :name
 
-    # Initialize the server with a name
-    # @param name [String, nil] server name
+    # @!attribute [r] read_timeout
+    #   @return [Numeric, nil] the configured per-request timeout in seconds, when the transport has one
+    attr_reader :read_timeout
+
     # Server-declared instructions from the initialize result, if any
     # @return [String, nil]
     attr_reader :instructions
@@ -25,6 +29,8 @@ module MCPClient
       @client_info = info.transform_keys(&:to_s)
     end
 
+    # Initialize the server with a name
+    # @param name [String, nil] server name
     def initialize(name: nil)
       @name = name
     end
@@ -147,6 +153,15 @@ module MCPClient
     # @param method [String] the JSON-RPC method the caller wants to send
     # @raise [MCPClient::Errors::CapabilityError]
     def require_capability!(*path, method:)
+      # A DiscoverResult that may no longer be reused is re-fetched on the
+      # next use of what it declared (MCP 2026-07-28 caching: a stale result
+      # is re-fetched on access) BEFORE the capability is judged at all: the
+      # server may have enabled a capability the old result lacked, or
+      # withdrawn one it still lists.
+      if respond_to?(:modern?, true) && modern? && discovery_refresh_needed?
+        @logger&.debug("The server/discover result may not be reused; refreshing it before #{method}")
+        rpc_request('server/discover')
+      end
       return if capability?(*path)
 
       raise MCPClient::Errors::CapabilityError,
@@ -154,11 +169,57 @@ module MCPClient
             "required for #{method}"
     end
 
+    # Whether the DiscoverResult behind the negotiated capabilities may still
+    # answer for the request about to go out.
+    #
+    # It is a cacheable result like any other, so it is bound by both of the
+    # caching rules the lists and reads obey: its ttlMs, counted from receipt
+    # (a result with no hint, or a zero, negative or malformed one, is stale
+    # at once), and — for a privately scoped result, which is what a server
+    # that declares no scope gets — the authorization context and effective
+    # parameters of the request that produced it. "Private responses MUST NOT
+    # be shared across authorization contexts (e.g. a different access token
+    # requires a different cache)", and the capabilities a server declares
+    # are exactly the kind of answer that differs between two tokens.
+    # @return [Boolean]
+    def discovery_refresh_needed?
+      return false unless respond_to?(:discovery_fresh?, true)
+      return true unless discovery_fresh?
+      return false unless respond_to?(:cache_fresh?, true)
+
+      reusable = cache_fresh?(:discover)
+      # The lookup holds the evaluation of the host's request_meta for the
+      # request it expected to follow. Nothing is sent when the result stands,
+      # so it is dropped rather than left on this thread for whichever request
+      # goes out next (see ResultCaching#release_serving_request_meta).
+      release_serving_request_meta if reusable && respond_to?(:release_serving_request_meta, true)
+      !reusable
+    end
+
     # Clean up the server connection
     def cleanup
       raise NotImplementedError, 'Subclasses must implement cleanup'
     end
 
+    # How many times this transport's session ended (cleanup, a restarted
+    # stdio process, a reconnect). Anything scoped to a session — task ids
+    # and their bookkeeping — is keyed by it, so state from a previous
+    # session never colours the next one.
+    # @return [Integer]
+    def session_epoch
+      @session_epoch || 0
+    end
+
+    protected
+
+    # Mark the current session as ended.
+    # @return [void]
+    def bump_session_epoch
+      @session_epoch = session_epoch + 1
+    end
+
+    public
+
     # Send a JSON-RPC request and return the result
     # @param method [String] JSON-RPC method name
     # @param params [Hash] parameters for the request
@@ -186,6 +247,31 @@ module MCPClient
       end
     end
 
+    # Open a long-lived notification stream (MCP 2026-07-28 subscriptions/listen).
+    # @param notifications [Hash] the SubscriptionFilter (tools_list_changed,
+    #   prompts_list_changed, resources_list_changed, resource_subscriptions,
+    #   snake_case or camelCase; an extension's own field, such as the tasks
+    #   extension's task_ids, once it has registered it — see
+    #   {MCPClient::Subscription.register_filter_field})
+    # @param ack_timeout [Numeric, false, nil] seconds to wait for the
+    #   server's acknowledgment before giving the listen up; nil takes the
+    #   transport's own read timeout, false waits for ever
+    # @yield [method, params] notifications delivered on the subscription
+    # @return [MCPClient::Subscription]
+    def listen(notifications:, ack_timeout: nil, &listener)
+      raise NotImplementedError, 'Subclasses must implement listen'
+    end
+
+    # Cancel a subscription opened with {#listen}.
+    # @param subscription [MCPClient::Subscription]
+    # @return [void]
+    def cancel_subscription(subscription)
+      raise NotImplementedError, 'Subclasses must implement cancel_subscription'
+    end
+
+    # @return [Logger] the transport logger
+    attr_reader :logger
+
     # Ping the MCP server to check connectivity (zero-parameter heartbeat call)
     # @return [Object] result from the ping request
     def ping
@@ -199,6 +285,43 @@ module MCPClient
       @notification_callback = block
     end
 
+    # Register a callback for the caches a notification invalidates, run
+    # *before* the notification is delivered to a subscription's listeners.
+    #
+    # A host layered above the transport (MCPClient::Client) keeps caches of
+    # its own, and they have to be gone by the time a listener reacting to a
+    # `list_changed` notification calls the cached list method. `on_notification`
+    # cannot serve for that: it is the last routing step, deliberately after
+    # the delivery, because it is host code that may block on the very reader
+    # the delivery came from. So the invalidation gets a hook of its own, ahead
+    # of the delivery, and only the invalidation goes on it.
+    # @yield [method, params] invoked before the notification is delivered
+    # @return [void]
+    # @see MCPClient::JsonRpcCommon#notify_cache_invalidation for where it runs
+    def on_cache_invalidation(&block)
+      @cache_invalidation_callback = block
+    end
+
+    # Map a resources/read error response to ResourceNotFound. MCP 2026-07-28
+    # (server/resources.mdx "Error Handling"): a missing resource is reported
+    # with -32602 (Invalid params); "for backwards compatibility, clients
+    # SHOULD also accept -32002 as a resource not found error".
+    # @param uri [String] the requested resource URI
+    # @param error [MCPClient::Errors::ServerError] the server's error response
+    # @return [MCPClient::Errors::ResourceNotFound]
+    def resource_not_found_error(uri, error)
+      MCPClient::Errors::ResourceNotFound.new("Resource '#{uri}' not found: #{error.message}")
+    end
+
+    # Whether a resources/read error response means the resource does not
+    # exist, given this session's protocol era.
+    # @param error [MCPClient::Errors::ServerError] the server's error response
+    # @return [Boolean]
+    def resource_not_found_response?(error)
+      modern = respond_to?(:modern?) && modern?
+      MCPClient::Errors::Codes.resource_not_found_code?(error.code, modern: modern)
+    end
+
     # Safety bound on the number of pages followed when auto-paginating a
     # cursor-based list operation, to protect against a server that returns
     # a nextCursor indefinitely.
@@ -228,7 +351,10 @@ module MCPClient
         items.concat(Array(page_items))
         pages += 1
 
-        break if next_cursor.nil? || next_cursor.to_s.empty?
+        # Only a missing (null) nextCursor ends the list: a cursor is opaque,
+        # and the empty string is one a server may hand out. A cursor handed
+        # out twice stops the walk below.
+        break if next_cursor.nil?
 
         if seen_cursors[next_cursor]
           @logger.warn("Pagination for #{kind} stopped: server returned a repeated cursor #{next_cursor.inspect}")
@@ -259,9 +385,95 @@ module MCPClient
     # @return [Array<Hash>] all raw item hashes collected across pages
     # @raise [MCPClient::Errors::TransportError] if a page result is not a Hash or Array
     def request_paginated_list(method, key)
-      collect_paginated(key) do |cursor|
+      # The cursor the page request now in flight carries, so a rejection can
+      # be told apart from an -32602 the first page's request earned.
+      page = { cursor: nil }
+      restarting_rejected_cursor(key, page) { collect_list_pages(method, key, page) }
+    end
+
+    # Collect a paginated list once more from its first page when the server
+    # rejects a cursor it had issued.
+    #
+    # MCP pagination: a cursor the server no longer accepts (-32602) ends the
+    # sequence the pages collected so far belong to, so the list is collected
+    # again from the beginning rather than failing a caller who only asked for
+    # a list. A second rejection is the server's answer and is raised, as is a
+    # rejection of the first page's own request — it carries no cursor.
+    # @param key [String] the result array key (for the log line)
+    # @param page [Hash] holds the cursor of the request in flight
+    # @yield collects every page of the list
+    # @return [Object] the block's value
+    def restarting_rejected_cursor(key, page)
+      restarted = false
+      begin
+        page[:cursor] = nil
+        yield
+      rescue MCPClient::Errors::ServerError => e
+        raise if restarted || !page[:cursor] || !cursor_rejected?(e)
+
+        @logger.warn("Pagination for #{key} restarted: the server rejected a cursor it had issued")
+        restarted = true
+        retry
+      end
+    end
+
+    # @param error [MCPClient::Errors::ServerError] a page request's failure
+    # @return [Boolean] whether it rejects the cursor the request carried
+    def cursor_rejected?(error)
+      respond_to?(:invalid_cursor_error?, true) && invalid_cursor_error?(error)
+    end
+
+    # Send one page request of an auto-paginated list, dropping the entry the
+    # list is cached under when the server rejects the cursor it carried.
+    #
+    # A cursor names a position in one sequence of pages: once the server has
+    # forgotten it, the pages cached from that sequence are gone with it, and
+    # a restart that then fails transiently must not serve them back. Only the
+    # entry goes — the fetch already collecting this list replaces the
+    # transport's own copy, and an invalidation of a fetch's own making is not
+    # a change the host has to hear about (which would restart that fetch).
+    # A rejection of the first page's request carries no cursor and says
+    # nothing about the cache, so it leaves it alone.
+    # @param kind [Symbol, nil] the list kind
+    # @param cursor [String, nil] the cursor this page request carries
+    # @yield sends the page request
+    # @return [Object] the block's value
+    def fetch_list_page(kind, cursor)
+      yield
+    rescue MCPClient::Errors::ServerError => e
+      raise unless kind && cursor && cursor_rejected?(e) && respond_to?(:invalidate_cache, true)
+
+      invalidate_cache(kind)
+      raise
+    end
+
+    # Collect every page of a list, recording what each page was answered
+    # under so the cache can bind the combined list to it.
+    # @param method [String] the list method
+    # @param key [String] the result array key
+    # @param page [Hash] holds the cursor of the request in flight
+    # @return [Array<Hash>] all raw item hashes collected across pages
+    def collect_list_pages(method, key, page)
+      pages = []
+      received_ats = []
+      contexts = []
+      fingerprints = []
+      page[:cursor] = nil
+      epoch = list_cache_epoch(method) if respond_to?(:list_cache_epoch, true)
+      kind = respond_to?(:list_kind_for, true) ? list_kind_for(method) : nil
+      items = collect_paginated(key) do |cursor|
         params = cursor ? { cursor: cursor } : {}
-        result = rpc_request(method, params)
+        started = respond_to?(:monotonic_now, true) ? monotonic_now : nil
+        page[:cursor] = cursor
+        # A cursor the server no longer accepts ends the sequence its pages
+        # belong to: what was cached under that sequence goes with it, so a
+        # restart that then fails cannot serve it back (MCP pagination).
+        answer = fetch_list_page(kind, cursor) { rpc_request(method, params) }
+        result = require_complete_result!(answer, method)
+        pages << result
+        received_ats << response_received_at(since: started) if respond_to?(:response_received_at, true)
+        contexts << (respond_to?(:request_authorization_context, true) ? request_authorization_context : nil)
+        fingerprints << (respond_to?(:request_params_fingerprint, true) ? request_params_fingerprint : nil)
         case result
         when Hash
           [result[key] || [], result['nextCursor']]
@@ -272,6 +484,22 @@ module MCPClient
                 "Invalid #{method} response: expected an object or array, got #{result.class}"
         end
       end
+      # MCP 2026-07-28 caching: every page carries its own ttlMs; the list is
+      # fresh only as long as its shortest-lived page, and pages fetched
+      # under differing credentials or parameters are never served combined.
+      if respond_to?(:record_list_cache_hint, true)
+        record_list_cache_hint(method, pages, received_ats, contexts: contexts, params: fingerprints, epoch: epoch)
+      end
+      items
+    end
+
+    # Whether a cached list of the given kind may still be served (MCP
+    # 2026-07-28 caching); transports without freshness hints keep caching
+    # until a change notification.
+    # @param _kind [Symbol]
+    # @return [Boolean]
+    def cache_fresh?(_kind)
+      true
     end
 
     # Initialize logger with proper formatter handling

data/lib/mcp_client/server_factory.rb

@@ -38,7 +38,9 @@ module MCPClient
         read_timeout: config[:read_timeout] || MCPClient::ServerStdio::READ_TIMEOUT,
         name: config[:name],
         logger: logger,
-        env: config[:env] || {}
+        env: config[:env] || {},
+        protocol: config[:protocol] || :auto,
+        discover_timeout: config[:discover_timeout]
       )
     end
 
@@ -78,7 +80,9 @@ module MCPClient
         name: config[:name],
         logger: logger,
         oauth_provider: config[:oauth_provider],
-        faraday_config: config[:faraday_config]
+        faraday_config: config[:faraday_config],
+        protocol: config[:protocol] || :auto,
+        discover_timeout: config[:discover_timeout]
       )
     end
 
@@ -102,7 +106,9 @@ module MCPClient
         faraday_config: config[:faraday_config],
         max_decompressed_body_bytes:
           config[:max_decompressed_body_bytes] ||
-            MCPClient::ServerStreamableHTTP::JsonRpcTransport::MAX_DECOMPRESSED_BODY_BYTES
+            MCPClient::ServerStreamableHTTP::JsonRpcTransport::MAX_DECOMPRESSED_BODY_BYTES,
+        protocol: config[:protocol] || :auto,
+        discover_timeout: config[:discover_timeout]
       )
     end
 

data/lib/mcp_client/server_http/json_rpc_transport.rb

@@ -12,17 +12,232 @@ module MCPClient
 
       # Parse an HTTP JSON-RPC response
       # @param response [Faraday::Response] the HTTP response
-      # @param _request [Hash, nil] the originating JSON-RPC request (unused)
+      # @param request [Hash, nil] the originating JSON-RPC request
       # @return [Hash] the parsed result
       # @raise [MCPClient::Errors::TransportError] if parsing fails
       # @raise [MCPClient::Errors::ServerError] if the response contains an error
-      def parse_response(response, _request = nil)
-        body = response.body.strip
-        data = JSON.parse(body)
+      # A host's `conn.response :json` middleware decodes the body before it
+      # reaches here — the README offers that middleware for the error path,
+      # and it applies to every response — so an already-decoded object is
+      # taken as it is rather than parsed a second time. An event-stream body
+      # is never decoded by that middleware, so it is still the raw text.
+      def parse_response(response, request = nil)
+        # Host code a stream listener reached raised while the body was still
+        # arriving: that is this exchange's failure (already marked as a
+        # nested exchange's, so no recovery acts on it), raised in place of
+        # the response it was interleaved with — as it is when the completed
+        # body is parsed.
+        failure = stream_listener_error(response)
+        raise failure if failure
+
+        body = response.body
+        headers = response.respond_to?(:headers) ? response.headers || {} : {}
+        content_type = headers['content-type'] || headers['Content-Type'] || ''
+        # MCP 2026-07-28 Streamable HTTP: the server answers with either a
+        # single JSON object or an SSE stream scoped to the request; the
+        # client MUST support both.
+        data = if content_type.include?('text/event-stream')
+                 # Not stripped: the blank line that terminates the final
+                 # event is what makes it a delivered event at all.
+                 response_from_sse(body.to_s, request && request['id'], live_event_count(response))
+               elsif body.is_a?(String)
+                 JSON.parse(body.strip)
+               else
+                 body
+               end
         process_jsonrpc_response(data)
       rescue JSON::ParserError => e
         raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{describe_parse_error(e)}"
       end
+
+      # Every complete event of a response stream is handed over while the
+      # body is still arriving, so a legacy server's request on the stream
+      # is answered — and a progress notification delivered — before the
+      # server has to end the response. A notification has no response
+      # stream worth reading incrementally.
+      # @param request [Hash] the JSON-RPC message being sent
+      # @return [Proc, nil]
+      def response_stream_listener(request)
+        return nil unless request.is_a?(Hash) && request.key?('id')
+
+        ->(event) { dispatch_live_sse_event(event) }
+      end
+
+      # Act on one event as it arrives: requests and notifications are
+      # routed now, responses wait for the completed body. A failing
+      # callback is not allowed to abort the read of the response it was
+      # interleaved with: the capture middleware holds it and parse_response
+      # raises it once the body is in.
+      # @param event [String] one complete, LF-normalized SSE event
+      # @return [void]
+      def dispatch_live_sse_event(event)
+        message = sse_event_message(event)
+        dispatch_sse_message(message) if message && message['method']
+      end
+
+      # Pick the JSON-RPC response to the request out of an SSE-framed body,
+      # forwarding request-scoped notifications (progress, log messages) to
+      # the notification callback — except the `live` leading events, which
+      # were already routed as they arrived. Server-initiated requests are
+      # not permitted on a 2026-07-28 response stream and are dropped.
+      # @param sse_body [String] the text/event-stream body
+      # @param request_id [Integer, String, nil] id of the originating request
+      # @param live [Integer] events already dispatched while the body arrived
+      # @return [Hash] the JSON-RPC response
+      # @raise [MCPClient::Errors::TransportError] when the stream carries no response
+      def response_from_sse(sse_body, request_id, live = 0)
+        responses = []
+        saw_invalid_json = false
+        sse_events(sse_body).each_with_index do |event, index|
+          message = sse_event_message(event)
+          saw_invalid_json = true if message.nil? && event.lines.any? { |l| l.start_with?('data:') }
+          next unless message
+
+          if message['method']
+            dispatch_sse_message(message) if index >= live
+          else
+            responses << message
+          end
+        end
+        matched = responses.find { |m| request_id.nil? || m['id'] == request_id || m['id'].to_s == request_id.to_s }
+        matched ||= tolerated_id_mismatch(responses, request_id)
+        return matched if matched
+
+        # Every event that reaches here is terminated, so a data line that did
+        # not parse is a delivered (malformed) answer rather than a break
+        # inside one: the server ran the request, and re-issuing would run it
+        # again.
+        if saw_invalid_json
+          raise MCPClient::Errors::TransportError,
+                'Invalid JSON response from server: SSE event carried no valid JSON-RPC message'
+        end
+
+        # The stream closed without the response: on a modern server the
+        # request is lost and must be re-issued (see rpc_request).
+        if modern?
+          raise MCPClient::Errors::ResponseStreamClosedError, 'SSE stream closed before delivering the response'
+        end
+
+        raise MCPClient::Errors::TransportError, 'No JSON-RPC response found in SSE response'
+      end
+
+      # Split a response stream into events, in the order and count the
+      # stream listener saw them.
+      #
+      # SSE line terminators are CRLF, CR or LF; a server framing its events
+      # with bare CR still delimits them, so normalize before splitting. An
+      # event is dispatched at its terminating blank line, so a body that
+      # ends inside an event delivered nothing for it: on a modern server
+      # that event is dropped (and a missing response re-issued). A legacy
+      # server keeps the benefit of the doubt this transport always gave it.
+      # @param sse_body [String] the text/event-stream body
+      # @return [Array<String>] the events, without their terminators
+      def sse_events(sse_body)
+        normalized = modern? ? complete_sse_events(sse_body) : normalize_sse_newlines(sse_body)
+        events = normalized.split("\n\n", -1)
+        events.pop if events.last.to_s.empty?
+        events
+      end
+
+      # @param event [String] one LF-normalized SSE event
+      # @return [Hash, nil] the JSON-RPC message its data lines carry, if any
+      def sse_event_message(event)
+        data_lines = event.lines.map(&:chomp).select { |l| l.start_with?('data:') }
+        return nil if data_lines.empty?
+
+        parse_sse_message(data_lines.map { |l| l.sub(/\Adata:\s*/, '') }.join("\n"))
+      end
+
+      # The only response on a stream, when its id is not the one asked for.
+      #
+      # A legacy server that echoes ids loosely — a string where an integer
+      # went out, or an id an intermediary rewrote — still gets the benefit of
+      # the doubt. A modern one does not: no response to THIS request arrived,
+      # so the request was lost and MCP 2026-07-28 says to re-issue it rather
+      # than complete it with the answer to something else.
+      # @param responses [Array<Hash>] the responses the stream carried
+      # @param request_id [Integer, String, nil] id of the originating request
+      # @return [Hash, nil] the response to accept, or nil to treat as lost
+      def tolerated_id_mismatch(responses, request_id)
+        return nil if modern? || responses.size != 1
+
+        @logger.warn("SSE response id #{responses.first['id'].inspect} does not match request id " \
+                     "#{request_id.inspect}; accepting the only response on the stream")
+        responses.first
+      end
+
+      # Route a non-response message: notifications go to the callback, and a
+      # server-initiated request is answered on a legacy stream and dropped on
+      # a modern one.
+      # @param message [Hash] a JSON-RPC request or notification
+      # @return [void]
+      def dispatch_sse_message(message)
+        # Host code reached from here -- a notification listener -- 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_sse_message_now(message) }
+      end
+
+      # @param message [Hash] a JSON-RPC request or notification
+      # @return [void]
+      def dispatch_sse_message_now(message)
+        unless message.key?('id')
+          route_notification(message['method'], message['params'])
+          return
+        end
+
+        # MCP 2026-07-28: "The server MUST NOT send independent JSON-RPC
+        # requests on this stream" and clients MUST NOT POST responses to it,
+        # so there is nothing to answer with. Judged by the ESTABLISHED era:
+        # while the probe is in flight the version is only a proposal, and a
+        # legacy server may be waiting for its ping on the probe's stream.
+        if protocol_era == :modern
+          @logger.warn("Ignoring server-initiated request #{message['method']} on a response stream")
+          return
+        end
+
+        answer_server_request(message)
+      end
+
+      # Answer a server-initiated request on a legacy (2025-11-25 and earlier)
+      # response stream, where the server may send one and a receiver "MUST
+      # respond promptly" to ping. This transport serves no other
+      # server-initiated method — it has no elicitation, roots or sampling
+      # callbacks — so those get the JSON-RPC method-not-found answer rather
+      # than silence, which would leave the server waiting.
+      # @param message [Hash] the server's JSON-RPC request
+      # @return [void]
+      def answer_server_request(message)
+        send_http_request(server_request_answer(message))
+      rescue StandardError => e
+        @logger.error("Failed to answer server request #{message['method']}: #{e.message}")
+      end
+
+      # @param message [Hash] the server's JSON-RPC request
+      # @return [Hash] the JSON-RPC response to POST back
+      def server_request_answer(message)
+        answer = { 'jsonrpc' => '2.0', 'id' => message['id'] }
+        return answer.merge('result' => {}) if message['method'] == 'ping'
+
+        @logger.warn("Answering unsupported server request #{message['method']} with method not found")
+        answer.merge('error' => { 'code' => MCPClient::Errors::Codes::METHOD_NOT_FOUND,
+                                  'message' => "Method not found: #{message['method']}" })
+      end
+
+      # @param json [String] one SSE event's data
+      # @return [Hash, nil] the parsed JSON-RPC message, nil when unusable
+      def parse_sse_message(json)
+        message = JSON.parse(json)
+        return message if message.is_a?(Hash)
+
+        @logger.warn("Skipping non-object JSON-RPC message in SSE event (#{message.class})")
+        nil
+      rescue JSON::ParserError => e
+        @logger.warn("Skipping invalid JSON in SSE event: #{describe_parse_error(e, json)}")
+        nil
+      end
     end
   end
 end