ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/mcp/client.rb

@@ -6,8 +6,10 @@ module RubyLLM
     # 2026-07-28 revision and falls back to the initialize handshake for
     # servers that predate it, declaring only its extensions so those
     # servers never call back. A server that rejects 2026-07-28 while
-    # listing it gets the request once more; one that answers the handshake
-    # with a revision missing from LEGACY_VERSIONS is disconnected.
+    # listing it gets the request once more; one that rejects it while
+    # listing a revision from LEGACY_VERSIONS, or without listing any,
+    # gets the handshake instead; one that answers the handshake with a
+    # revision missing from LEGACY_VERSIONS is disconnected.
     #
     # Servers that predate 2026-07-28 may announce that their tools,
     # prompts, or resources changed on the stream of any request. Those
@@ -18,21 +20,27 @@ module RubyLLM
     # never announce the status of tasks. Their subscription counts as
     # acknowledged once a ping confirms the session, starting a new one if
     # it ended.
-    class Client # :nodoc:
+    #
+    # An MCP builds its own client. Applications use one only to read
+    # #meta, when they send a server requests of their own.
+    class Client
+      # :stopdoc:
       VERSION = '2026-07-28'
       LEGACY_VERSIONS = %w[2025-11-25 2025-06-18 2025-03-26 2024-11-05].freeze
       UNSUPPORTED_VERSION = -32_022
       MODERN_ERRORS = [-32_020, -32_021, UNSUPPORTED_VERSION].freeze
       METHOD_NOT_FOUND = -32_601
       DISCOVERY_TIMEOUT = 10
+      PAGE_LIMIT = 1_000
       ACKNOWLEDGED = 'notifications/subscriptions/acknowledged'
       CHANGES = %w[
         notifications/tools/list_changed notifications/prompts/list_changed
         notifications/resources/list_changed notifications/resources/updated
       ].freeze
+      # :startdoc:
 
       # The answer to a request the server sends: RubyLLM only answers pings.
-      def self.reply(request)
+      def self.reply(request) # :nodoc:
         if request['method'] == 'ping'
           { jsonrpc: '2.0', id: request['id'], result: {} }
         else
@@ -40,9 +48,9 @@ module RubyLLM
         end
       end
 
-      attr_reader :version
+      attr_reader :version # :nodoc:
 
-      def initialize(transport, capabilities: {}, &on_change)
+      def initialize(transport, capabilities: {}, &on_change) # :nodoc:
         @transport = transport
         @capabilities = capabilities
         @on_change = on_change
@@ -50,25 +58,28 @@ module RubyLLM
         @subscribed = []
       end
 
-      def server
+      def server # :nodoc:
         @connecting.synchronize { @server ||= discover || handshake }
       end
 
-      def request(method, params = {}, headers: {}, &)
+      def request(method, params = {}, headers: {}, &) # :nodoc:
         server
         call(method, params, headers:, &)
-      rescue SessionExpired
-        @connecting.synchronize { @server = handshake }
+      rescue SessionExpired => e
+        reconnect(e.session)
         call(method, params, headers:, &)
       end
 
-      def list(method, key)
+      def list(method, key) # :nodoc:
         page = request(method)
         items = page.fetch(key, [])
-        while (cursor = page['nextCursor'])
+        PAGE_LIMIT.times do
+          cursor = page['nextCursor'] or break
           page = request(method, { cursor: })
           items += page.fetch(key, [])
         end
+        raise Error, "The server did not finish #{method} in #{PAGE_LIMIT} pages" if page['nextCursor']
+
         items
       end
 
@@ -76,18 +87,18 @@ module RubyLLM
       # each notification of the subscription, starting with the server's
       # acknowledgment. Returns when the server ends the subscription and
       # raises Error when it refuses one or the stream breaks.
-      def listen(changes, &)
+      def listen(changes, &) # :nodoc:
         server
         raise ConfigurationError, 'The MCP transport does not respond to listen' unless @transport.respond_to?(:listen)
 
         modern? ? subscribe(changes, &) : listen_to_session(changes, &)
       end
 
-      def modern?
+      def modern? # :nodoc:
         version == VERSION
       end
 
-      def close
+      def close # :nodoc:
         @connecting.synchronize do
           @transport.close
           @server = nil
@@ -96,6 +107,27 @@ module RubyLLM
         end
       end
 
+      # Returns the +_meta+ the client adds to every request it sends a
+      # server on the 2026-07-28 revision: the revision, the client's name
+      # and version, and its capabilities. Merge it into requests you send
+      # the server yourself, so they describe the client the same way:
+      #
+      #   meta = RubyLLM::MCP::Client.new(transport).meta
+      #   # => { "io.modelcontextprotocol/protocolVersion" => "2026-07-28",
+      #   #      "io.modelcontextprotocol/clientInfo" => { name: "ruby_llm", version: "2.2.0" },
+      #   #      "io.modelcontextprotocol/clientCapabilities" => {} }
+      #   params = { name: "roots", arguments: {}, _meta: meta }
+      #
+      # Servers on an older revision get none of these fields: they learn
+      # the same from the initialize handshake.
+      def meta
+        {
+          'io.modelcontextprotocol/protocolVersion' => VERSION,
+          'io.modelcontextprotocol/clientInfo' => client_info,
+          'io.modelcontextprotocol/clientCapabilities' => @capabilities
+        }
+      end
+
       private
 
       def discover
@@ -103,7 +135,7 @@ module RubyLLM
         result = call('server/discover', timeout: DISCOVERY_TIMEOUT)
         result if Array(result['supportedVersions']).include?(VERSION)
       rescue Error => e
-        raise if MODERN_ERRORS.include?(e.code)
+        raise if MODERN_ERRORS.include?(e.code) && !predates_revision?(e)
       end
 
       def handshake
@@ -167,11 +199,15 @@ module RubyLLM
         listened = changes.except(:taskIds).transform_keys(&:to_s)
         yield({ 'method' => ACKNOWLEDGED, 'params' => { 'notifications' => listened } })
         @transport.listen(nil, version:, &)
-      rescue SessionExpired
-        @connecting.synchronize { @server = handshake }
+      rescue SessionExpired => e
+        reconnect(e.session)
         raise
       end
 
+      def reconnect(expired)
+        @connecting.synchronize { @server = handshake if @server.nil? || @transport.session.equal?(expired) }
+      end
+
       def cancels?(notification, request)
         notification['method'] == 'notifications/cancelled' && notification.dig('params', 'requestId') == request[:id]
       end
@@ -182,14 +218,25 @@ module RubyLLM
 
       def answer(response)
         error = response['error']
-        raise Error.new(error['message'], code: error['code'], data: error['data']) if error
+        raise Error.new(provider_message: error['message'], code: error['code'], data: error['data']) if error
 
         response['result']
       end
 
       def offers_version?(error)
+        modern? && error.code == UNSUPPORTED_VERSION && supported_versions(error).include?(VERSION)
+      end
+
+      def predates_revision?(error)
+        return false unless error.code == UNSUPPORTED_VERSION
+
+        supported = supported_versions(error)
+        supported.empty? || supported.intersect?(LEGACY_VERSIONS)
+      end
+
+      def supported_versions(error)
         supported = error.data['supported'] if error.data.is_a?(Hash)
-        modern? && error.code == UNSUPPORTED_VERSION && Array(supported).include?(VERSION)
+        Array(supported)
       end
 
       def message(method, params = {}, id: nil)
@@ -197,14 +244,6 @@ module RubyLLM
         { jsonrpc: '2.0', id:, method:, params: }.compact
       end
 
-      def meta
-        {
-          'io.modelcontextprotocol/protocolVersion' => VERSION,
-          'io.modelcontextprotocol/clientInfo' => client_info,
-          'io.modelcontextprotocol/clientCapabilities' => @capabilities
-        }
-      end
-
       def client_info
         { name: 'ruby_llm', version: RubyLLM::VERSION }
       end

data/lib/ruby_llm/mcp/collection.rb

@@ -14,11 +14,36 @@ module RubyLLM
 
       def initialize # :nodoc:
         @servers = {}
+        @built = {}.compare_by_identity
       end
 
-      def <<(server) # :nodoc:
+      def initialize_copy(source) # :nodoc:
+        super
+        @servers = @servers.dup
+        @built = @built.dup
+      end
+
+      def connect(server, chat) # :nodoc:
+        server = server.new.tap { |built| @built[built] = chat } if server.is_a?(Class)
+        replaced = self[server.name]
+        check_name(server, replaced) if replaced
+        release(replaced, chat) unless replaced.equal?(server)
         @servers[server.name.to_sym] = server
-        self
+      end
+
+      def disconnect(chat) # :nodoc:
+        each { |server| release(server, chat) }
+      end
+
+      # The tools of the servers that can be reached.
+      def reachable_tools # :nodoc:
+        flat_map { |server| Outages.tools(server) }
+      end
+
+      # The names of the servers that can't be reached.
+      def unreachable # :nodoc:
+        reachable_tools
+        select { |server| Outages.down?(server) }.map(&:name)
       end
 
       # Returns the server named +name+, or +nil+.
@@ -42,6 +67,18 @@ module RubyLLM
 
       private
 
+      def check_name(server, connected)
+        return unless server.class.derived_name? && connected.class.derived_name?
+        return if server.class.endpoint == connected.class.endpoint
+
+        raise ArgumentError, "MCP servers #{connected.class.endpoint} and #{server.class.endpoint} are both named " \
+                             "#{server.name.inspect}. Pass name: to RubyLLM.mcp to tell them apart"
+      end
+
+      def release(server, chat)
+        server.close if @built[server].equal?(chat) && @built.delete(server)
+      end
+
       def method_missing(name, *arguments)
         return super unless arguments.empty? && @servers.key?(name)
 

data/lib/ruby_llm/mcp/content.rb

@@ -29,9 +29,14 @@ module RubyLLM
       end
 
       def attachment(data, mime_type, name)
+        file(Base64.decode64(data.to_s), mime_type, name)
+      end
+
+      def file(bytes, mime_type, name)
+        name = name.to_s.empty? ? 'resource' : name.to_s
         extension = Marcel::TYPE_EXTS[mime_type]&.first
-        name = "#{name}.#{extension}" unless name.to_s.include?('.') || extension.nil?
-        Attachment.new(StringIO.new(Base64.decode64(data.to_s)), filename: name.to_s)
+        name = "#{name}.#{extension}" unless name.include?('.') || extension.nil?
+        Attachment.new(StringIO.new(bytes), filename: name)
       end
 
       def filename(uri)

data/lib/ruby_llm/mcp/error.rb

@@ -17,10 +17,16 @@ module RubyLLM
       # Additional information the server attached to the error, or +nil+.
       attr_reader :data
 
-      def initialize(message = nil, code: nil, data: nil, response: nil) # :nodoc:
+      def initialize(message = nil, code: nil, data: nil, response: nil, error_code: code, **) # :nodoc:
         @code = code
         @data = data
-        super(message, response:)
+        super(message, response:, error_code:, **)
+      end
+
+      private
+
+      def redacted_source
+        'The MCP server'
       end
     end
   end

data/lib/ruby_llm/mcp/http.rb

@@ -4,14 +4,17 @@ module RubyLLM
   class MCP
     # Streamable HTTP. Every message is its own POST, answered with a JSON
     # body or with an event stream that carries the request's notifications
-    # before its response. Plain HTTP is only allowed on loopback addresses,
-    # URLs cannot carry credentials, and redirects are never followed. A cancelled chat closes the stream,
+    # before its response. Plain HTTP is only allowed on loopback addresses
+    # unless +allow_http+ opts in, URLs cannot carry credentials, and redirects
+    # are never followed. A cancelled chat closes the stream,
     # which is how 2026-07-28 cancels a request. Servers that predate it may
     # keep a session, which ends with a DELETE when the transport closes.
     #
     # When a stream ends before the response, 2026-07-28 sends the request
-    # again with a new ID, while older servers resume the stream from its
-    # last event ID after the wait they ask for, a few times at most.
+    # again with a new ID, unless it is a tool call that +idempotent+ does
+    # not vouch for, since the server may have run it. Older servers resume
+    # the stream from its last event ID after the wait they ask for. Either
+    # happens a few times at most.
     #
     # A subscription's stream stays open, so it gets a connection of its
     # own: callbacks it runs can make requests of their own, even through
@@ -30,6 +33,12 @@ module RubyLLM
       RECONNECT_DELAY = 1
       CHECK_INTERVAL = 0.1
 
+      def self.parse(url)
+        URI(url.to_s)
+      rescue URI::InvalidURIError
+        raise ArgumentError, 'The MCP server URL is malformed', cause: nil
+      end
+
       def self.secure?(url)
         uri = URI(url.to_s)
         return false if uri.userinfo
@@ -41,15 +50,27 @@ module RubyLLM
         LOOPBACK_HOSTS.include?(URI(url.to_s).hostname)
       end
 
-      def initialize(url, headers: {}, timeout: nil, unauthorized: nil, responded: nil, config: RubyLLM.config)
-        @url = URI(url)
-        unless self.class.secure?(@url)
-          raise ArgumentError, "MCP servers must use HTTPS without credentials in the URL: #{url}"
-        end
+      # Returns whether +url+ is a web page's address, an +http+ or +https+
+      # one. A server's page to visit must be, since anything else, such as
+      # a javascript: address, would run in the app that links to it.
+      def self.web?(url)
+        URI(url.to_s).is_a?(URI::HTTP)
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # The session of a server that predates 2026-07-28: the ID the server gave its session, or +nil+.
+      attr_reader :session
+
+      def initialize(url, allow_http: false, headers: {}, timeout: nil, unauthorized: nil, responded: nil,
+                     idempotent: nil, config: RubyLLM.config)
+        @url = self.class.parse(url)
+        check_url(allow_http)
 
         @headers = headers
         @unauthorized = unauthorized
         @responded = responded
+        @idempotent = idempotent
         @timeout = timeout || config.request_timeout
         @connect = lambda do
           Transport::Connection.basic(config) do |faraday|
@@ -64,7 +85,7 @@ module RubyLLM
         stream = post(message, version:, timeout:, params: headers, &)
         RECONNECTS.times do
           if version == Client::VERSION
-            break unless stream.interrupted?
+            break unless resend?(stream, message)
 
             stream = post(message.merge(id: SecureRandom.uuid), version:, timeout:, params: headers, &)
           else
@@ -90,8 +111,6 @@ module RubyLLM
 
         stream = post(message, version:, connection: streams, &)
         stream.answer || raise(Error, "#{@url.host} closed the subscription")
-      rescue Faraday::Error => e
-        raise Error, e.message
       end
 
       def close
@@ -111,6 +130,14 @@ module RubyLLM
 
       private
 
+      def check_url(allow_http)
+        raise ArgumentError, 'MCP server URLs cannot carry credentials' if @url.userinfo
+        return if self.class.secure?(@url) || (allow_http && @url.scheme == 'http')
+
+        raise ArgumentError, 'MCP servers must use HTTPS, or plain HTTP on a loopback address. ' \
+                             'For a server on a network you trust, pass allow_http: true with the url'
+      end
+
       def post(message, version:, timeout: nil, params: {}, connection: @connection, recovered: [], &on_notification)
         session = @session unless message[:method] == 'initialize'
         stream = Stream.new(message[:id], &receiver(version, on_notification))
@@ -126,11 +153,11 @@ module RubyLLM
         remember(message, version, stream.headers)
         stream
       rescue Faraday::Error => e
-        raise unless e.response
+        raise unanswered(e, stream) unless e.response
 
         responded(e.response[:headers])
         return stream if answered?(stream)
-        raise SessionExpired, "#{@url.host} ended the session" if expired?(e.response, message, session)
+        raise SessionExpired.new("#{@url.host} ended the session", session:) if expired?(e.response, message, session)
 
         recovery = recover(e.response, recovered)
         if recovery
@@ -143,29 +170,30 @@ module RubyLLM
 
       def resume(stream, version:, timeout:, &on_notification)
         wait(stream.retry_after || RECONNECT_DELAY)
-        resumed = Stream.new(stream.id, &receiver(version, on_notification))
+        resumed = Stream.new(stream.id, stream, &receiver(version, on_notification))
         get(resumed, version:, timeout:, last_event_id: stream.last_event_id)
       rescue Faraday::Error
         resumed
       end
 
       def listen_to_session(version:, &on_notification)
+        session = @session
         stream = Stream.new(nil, &receiver(version, on_notification))
-        get(stream, version:, connection: streams)
+        get(stream, version:, connection: streams, session:)
         nil
       rescue Faraday::Error => e
-        raise Error, e.message unless e.response
-        raise SessionExpired, "#{@url.host} ended the session" if e.response[:status] == 404 && @session
+        raise unanswered(e, stream) unless e.response
+        raise SessionExpired.new("#{@url.host} ended the session", session:) if e.response[:status] == 404 && session
         raise Error.new("#{@url.host} sends no events", code: Client::METHOD_NOT_FOUND) if e.response[:status] == 405
 
         raise failure(e.response, stream)
       end
 
-      def get(stream, version:, timeout: nil, last_event_id: nil, connection: @connection)
+      def get(stream, version:, timeout: nil, last_event_id: nil, connection: @connection, session: @session)
         stream.read do
           connection.get(@url) do |request|
             request.headers.update({ 'Accept' => 'text/event-stream', 'MCP-Protocol-Version' => version,
-                                     'Mcp-Session-Id' => @session, 'Last-Event-ID' => last_event_id }.compact)
+                                     'Mcp-Session-Id' => session, 'Last-Event-ID' => last_event_id }.compact)
             request.headers.update(custom_headers('GET'))
             stream.attach(request, timeout)
           end
@@ -187,7 +215,7 @@ module RubyLLM
 
       def answer(request, version:)
         post(Client.reply(request), version:, connection: answers)
-      rescue RubyLLM::Error, Faraday::Error => e
+      rescue RubyLLM::Error => e
         RubyLLM.logger.debug { "#{@url.host} did not take the answer to #{request['method']}: #{e.message}" }
       end
 
@@ -195,6 +223,10 @@ module RubyLLM
         @answers ||= @connect.call
       end
 
+      def resend?(stream, message)
+        stream.interrupted? && (message[:method] != 'tools/call' || @idempotent&.call(message.dig(:params, :name)))
+      end
+
       def resumable?(stream, limit)
         stream.interrupted? && stream.last_event_id && (limit.nil? || (stream.retry_after || 0) <= limit)
       end
@@ -267,14 +299,32 @@ module RubyLLM
       def failure(response, stream)
         case response[:status]
         when 401 then UnauthorizedError.new("#{@url.host} requires authorization", response: response_for(response))
-        when 403 then ForbiddenError.new("#{@url.host} refused the request", response: response_for(response))
+        when 403 then forbidden(response)
         else
           error = stream.replies.first&.fetch('error', nil) || {}
-          Error.new(error['message'] || "#{@url.host} answered HTTP #{response[:status]}",
-                    code: error['code'], data: error['data'], response: response_for(response))
+          fallback = "#{@url.host} answered HTTP #{response[:status]}" unless error['message']
+          Error.new(fallback, provider_message: error['message'], provider: @url.host,
+                              code: error['code'], data: error['data'], response: response_for(response))
         end
       end
 
+      def forbidden(response)
+        challenges = OAuth.challenge(response[:headers]&.[]('WWW-Authenticate')).values.select { |c| c[:error] }
+        challenge = challenges.find { |c| c[:error] == 'insufficient_scope' } || challenges.first || {}
+        details = { response: response_for(response), provider: @url.host, error_code: challenge[:error],
+                    provider_message: challenge[:error_description] || challenge[:error] }
+        message = "#{@url.host} refused the request"
+        return ForbiddenError.new(message, **details) unless challenge[:error] == 'insufficient_scope'
+
+        InsufficientScopeError.new(message, scopes: challenge[:scope].to_s.split, **details)
+      end
+
+      def unanswered(error, stream)
+        return error if stream.raised?(error)
+
+        ConnectionError.new(error.message, provider: @url.host)
+      end
+
       def response_for(response)
         Faraday::Response.new(status: response[:status], response_headers: response[:headers],
                               body: response[:body])
@@ -285,15 +335,24 @@ module RubyLLM
       # The body is either a single JSON value or a server-sent event
       # stream; the first character tells them apart. An event stream stops
       # being read once it carries the answer to request +id+, since servers
-      # may keep it open, and one that breaks midway counts as ended. Only
-      # answers are kept, so a stream that stays open does not grow.
-      # Faraday 2 passes the response headers with each chunk; Faraday 1
-      # has them only once the response ends.
+      # may keep it open, and one that breaks midway counts as ended. The
+      # stop raises so adapters that pool sockets can discard the connection
+      # instead of returning it with unread bytes. Only answers are kept, so
+      # a stream that stays open does not grow. A stream that resumes another
+      # starts from its last event ID and reconnection time, as an event
+      # source keeps both across reconnections. Faraday 2 passes the response
+      # headers with each chunk; Faraday 1 has them only once the response ends,
+      # so there it reads on, and a stream that stays open ends at the timeout.
       class Stream # :nodoc:
+        class Abandoned < StandardError # :nodoc:
+        end
+
         attr_reader :id, :headers
 
-        def initialize(id, &on_message)
+        def initialize(id, resumed = nil, &on_message)
           @id = id
+          @last_event_id = resumed&.last_event_id
+          @retry_after = resumed&.retry_after
           @on_message = on_message
           @parser = Transport::EventStreamParser.new
           @body = +''
@@ -307,13 +366,23 @@ module RubyLLM
         end
 
         def read(&)
-          response = catch(self, &)
+          response = yield
           @headers = response.headers if @headers.empty? && response.respond_to?(:headers)
           self
-        rescue Faraday::ConnectionFailed
-          raise unless events?
+        rescue Abandoned
+          self
+        rescue Faraday::ConnectionFailed => e
+          raise if raised?(e) || !events?
 
           self
+        rescue Faraday::TimeoutError => e
+          raise if raised?(e) || !answer
+
+          self
+        end
+
+        def raised?(error)
+          @raised.equal?(error)
         end
 
         def feed(chunk, _size = nil, env = nil)
@@ -331,11 +400,11 @@ module RubyLLM
           return unless @events
 
           @parser.feed(chunk) { |_type, data| receive_event(data) }
-          throw self if answer
+          abandon_if_answered
         end
 
         def replies
-          receive(@body) if @events == false && @replies.empty?
+          receive(@body.slice!(0..)) if @events == false && !@body.empty?
           @replies
         end
 
@@ -348,11 +417,11 @@ module RubyLLM
         end
 
         def last_event_id
-          @parser.last_event_id unless @parser.last_event_id.empty?
+          @parser.last_event_id.empty? ? @last_event_id : @parser.last_event_id
         end
 
         def retry_after
-          @parser.reconnection_time / 1000.0 if @parser.reconnection_time
+          @parser.reconnection_time ? @parser.reconnection_time / 1000.0 : @retry_after
         end
 
         private
@@ -361,6 +430,10 @@ module RubyLLM
           @events == true
         end
 
+        def abandon_if_answered
+          raise Abandoned if answer && !@headers.empty?
+        end
+
         def receive_event(data)
           receive(data) unless data.empty?
         end
@@ -368,11 +441,18 @@ module RubyLLM
         def receive(data)
           parsed = JSON.parse(data)
           (parsed.is_a?(Array) ? parsed : [parsed]).grep(Hash).each do |reply|
-            reply['method'] ? @on_message&.call(reply) : @replies << reply
+            reply['method'] ? deliver(reply) : @replies << reply
           end
         rescue JSON::ParserError
           RubyLLM.logger.debug { 'MCP server sent a message that is not JSON' }
         end
+
+        def deliver(message)
+          @on_message&.call(message)
+        rescue StandardError => e
+          @raised = e
+          raise
+        end
       end
     end
   end