ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/mcp/http.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+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,
+    # 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.
+    #
+    # 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
+    # adapters that keep one connection per thread. Older servers send
+    # changes on the session's event stream instead.
+    #
+    # A server's own requests, on any stream, are answered right away on
+    # another connection: pings with a result, the rest with method not
+    # found, so a server never waits on RubyLLM.
+    class HTTP # :nodoc:
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+      HEADER_SAFE = /\A[\x21-\x7E](?:[\x20-\x7E]*[\x21-\x7E])?\z/
+      ENCODED_HEADER = /\A=\?base64\?.*\?=\z/
+      CLOSE_TIMEOUT = 5
+      RECONNECTS = 3
+      RECONNECT_DELAY = 1
+      CHECK_INTERVAL = 0.1
+
+      def self.secure?(url)
+        uri = URI(url.to_s)
+        return false if uri.userinfo
+
+        uri.scheme == 'https' || (uri.scheme == 'http' && loopback?(uri))
+      end
+
+      def self.loopback?(url)
+        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
+
+        @headers = headers
+        @unauthorized = unauthorized
+        @responded = responded
+        @timeout = timeout || config.request_timeout
+        @connect = lambda do
+          Transport::Connection.basic(config) do |faraday|
+            faraday.options.timeout = timeout if timeout
+            faraday.adapter config.faraday_adapter
+          end
+        end
+        @connection = @connect.call
+      end
+
+      def request(message, version:, timeout: nil, headers: {}, &)
+        stream = post(message, version:, timeout:, params: headers, &)
+        RECONNECTS.times do
+          if version == Client::VERSION
+            break unless stream.interrupted?
+
+            stream = post(message.merge(id: SecureRandom.uuid), version:, timeout:, params: headers, &)
+          else
+            break unless resumable?(stream, timeout || @timeout)
+
+            stream = resume(stream, version:, timeout:, &)
+          end
+        end
+        stream.answer || raise(Error, "#{@url.host} did not answer #{message[:method]}")
+      end
+
+      def notify(message, version:)
+        post(message, version:)
+        nil
+      end
+
+      def cancel(notification, version:)
+        notify(notification, version:) unless version == Client::VERSION
+      end
+
+      def listen(message, version:, &)
+        return listen_to_session(version:, &) unless message
+
+        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
+        session = @session
+        @session = nil
+        return unless session
+
+        response = @connection.delete(@url) do |request|
+          request.headers.update({ 'MCP-Protocol-Version' => @version, 'Mcp-Session-Id' => session }.compact)
+          request.headers.update(custom_headers('DELETE'))
+          request.options.timeout = CLOSE_TIMEOUT
+        end
+        responded(response.headers)
+      rescue Faraday::Error => e
+        responded(e.response[:headers]) if e.response
+      end
+
+      private
+
+      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))
+        stream.read do
+          connection.post(@url) do |request|
+            request.headers.update(headers(message, version, session))
+            params.each { |name, value| request.headers["Mcp-Param-#{name}"] = header_value(value) }
+            request.body = JSON.generate(message)
+            stream.attach(request, timeout)
+          end
+        end
+        responded(stream.headers)
+        remember(message, version, stream.headers)
+        stream
+      rescue Faraday::Error => e
+        raise 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)
+
+        recovery = recover(e.response, recovered)
+        if recovery
+          return post(message, version:, timeout:, params:, connection:, recovered: [*recovered, recovery],
+                      &on_notification)
+        end
+
+        raise failure(e.response, stream)
+      end
+
+      def resume(stream, version:, timeout:, &on_notification)
+        wait(stream.retry_after || RECONNECT_DELAY)
+        resumed = Stream.new(stream.id, &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)
+        stream = Stream.new(nil, &receiver(version, on_notification))
+        get(stream, version:, connection: streams)
+        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 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)
+        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)
+            request.headers.update(custom_headers('GET'))
+            stream.attach(request, timeout)
+          end
+        end
+        responded(stream.headers)
+        stream
+      rescue Faraday::Error => e
+        responded(e.response[:headers]) if e.response
+        raise
+      end
+
+      def streams
+        @streams ||= @connect.call
+      end
+
+      def receiver(version, on_notification)
+        ->(message) { message.key?('id') ? answer(message, version:) : on_notification&.call(message) }
+      end
+
+      def answer(request, version:)
+        post(Client.reply(request), version:, connection: answers)
+      rescue RubyLLM::Error, Faraday::Error => e
+        RubyLLM.logger.debug { "#{@url.host} did not take the answer to #{request['method']}: #{e.message}" }
+      end
+
+      def answers
+        @answers ||= @connect.call
+      end
+
+      def resumable?(stream, limit)
+        stream.interrupted? && stream.last_event_id && (limit.nil? || (stream.retry_after || 0) <= limit)
+      end
+
+      def wait(seconds)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        loop do
+          Support::Cancellation.check
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break unless remaining.positive?
+
+          sleep [remaining, CHECK_INTERVAL].min
+        end
+      end
+
+      def remember(message, version, headers)
+        @version = version if version
+        @session = headers['mcp-session-id'] if message[:method] == 'initialize'
+      end
+
+      def expired?(response, message, session)
+        session && message[:id] && response[:status] == 404
+      end
+
+      # Some servers, such as Google's Drive preview, send a complete
+      # JSON-RPC result with an error status. The result is the answer.
+      def answered?(stream)
+        stream.answer&.key?('result')
+      end
+
+      # Returns how a rejected request recovered, such as with a new token
+      # or a nonce for its proof, unless it already recovered that way.
+      def recover(response, recovered)
+        status = response[:status]
+        return unless @unauthorized && [401, 403].include?(status)
+
+        recovery = @unauthorized.call(response[:headers] || {}, status, recovered)
+        recovery if status == 401
+      end
+
+      def responded(headers)
+        @responded&.call(headers || {})
+      end
+
+      def headers(message, version, session)
+        {
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json, text/event-stream',
+          'MCP-Protocol-Version' => version,
+          'Mcp-Session-Id' => session,
+          'Mcp-Method' => message[:method],
+          'Mcp-Name' => header_value(message.dig(:params, :name) || message.dig(:params, :uri) ||
+                                     message.dig(:params, :taskId))
+        }.compact.merge(custom_headers('POST'))
+      end
+
+      def custom_headers(verb)
+        @headers.respond_to?(:call) ? @headers.call(verb) : @headers
+      end
+
+      def header_value(value)
+        return if value.nil?
+
+        value = value.to_s
+        return value if value.empty? || (value.match?(HEADER_SAFE) && !value.match?(ENCODED_HEADER))
+
+        "=?base64?#{Base64.strict_encode64(value)}?="
+      end
+
+      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))
+        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))
+        end
+      end
+
+      def response_for(response)
+        Faraday::Response.new(status: response[:status], response_headers: response[:headers],
+                              body: response[:body])
+      end
+
+      # Collects the answers in one response and yields the messages the
+      # server sends of its own, notifications and requests, as they arrive.
+      # 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.
+      class Stream # :nodoc:
+        attr_reader :id, :headers
+
+        def initialize(id, &on_message)
+          @id = id
+          @on_message = on_message
+          @parser = Transport::EventStreamParser.new
+          @body = +''
+          @replies = []
+          @headers = {}
+        end
+
+        def attach(request, timeout)
+          request.options.timeout = timeout if timeout
+          request.options.on_data = method(:feed).to_proc
+        end
+
+        def read(&)
+          response = catch(self, &)
+          @headers = response.headers if @headers.empty? && response.respond_to?(:headers)
+          self
+        rescue Faraday::ConnectionFailed
+          raise unless events?
+
+          self
+        end
+
+        def feed(chunk, _size = nil, env = nil)
+          Support::Cancellation.check
+          @headers = env.response_headers if env&.response_headers
+          return @body << chunk if @events == false
+
+          if @events.nil?
+            @body << chunk
+            return if @body.strip.empty?
+
+            @events = !@body.lstrip.start_with?('{', '[')
+            chunk = @body
+          end
+          return unless @events
+
+          @parser.feed(chunk) { |_type, data| receive_event(data) }
+          throw self if answer
+        end
+
+        def replies
+          receive(@body) if @events == false && @replies.empty?
+          @replies
+        end
+
+        def answer
+          replies.find { |reply| !reply.key?('method') && reply['id'] == id }
+        end
+
+        def interrupted?
+          events? && answer.nil?
+        end
+
+        def last_event_id
+          @parser.last_event_id unless @parser.last_event_id.empty?
+        end
+
+        def retry_after
+          @parser.reconnection_time / 1000.0 if @parser.reconnection_time
+        end
+
+        private
+
+        def events?
+          @events == true
+        end
+
+        def receive_event(data)
+          receive(data) unless data.empty?
+        end
+
+        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
+          end
+        rescue JSON::ParserError
+          RubyLLM.logger.debug { 'MCP server sent a message that is not JSON' }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/input_request.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # A server's request for input from the user while it works on a call,
+    # received by MCP.before_input_request callbacks. A form request asks
+    # for values; a URL request asks the user to visit a page, such as to
+    # connect an account.
+    #
+    #   before_input_request do |request|
+    #     if request.url?
+    #       system "open", request.url
+    #       request.answer
+    #     else
+    #       request.answer(environment: "staging")
+    #     end
+    #   end
+    #
+    # In a chat, a request no callback answers pauses the tool call until
+    # Chat#answer or Chat#decline settles it; see Chat#pending_inputs.
+    class InputRequest
+      include Support::Inspectable
+
+      # A value a form request asks for.
+      Field = Struct.new(:name, :type, :title, :description, :required, :choices, :default, keyword_init: true) do
+        # Returns whether the server needs this value.
+        def required?
+          required == true
+        end
+      end
+
+      # Why the server needs the input.
+      attr_reader :message
+
+      # The page a URL request asks the user to visit, or +nil+.
+      attr_reader :url
+
+      # The values a form request asks for, as Field objects.
+      attr_reader :fields
+
+      attr_reader :key, :response # :nodoc:
+
+      # The ToolCall paused on this request, when it came from a chat.
+      attr_reader :tool_call
+
+      def self.from_h(data, tool_call: nil) # :nodoc:
+        new(data['key'], data['params'], response: data['response'], tool_call:)
+      end
+
+      def initialize(key, params, response: nil, tool_call: nil) # :nodoc:
+        @key = key
+        @params = params
+        @response = response
+        @tool_call = tool_call
+        @message = params['message']
+        @url = params['url'] if params['mode'] == 'url'
+        @fields = fields_from(params['requestedSchema'] || {})
+      end
+
+      # Returns whether the server asks the user to visit #url.
+      def url?
+        !url.nil?
+      end
+
+      # Returns whether the server asks for #fields.
+      def form?
+        !url?
+      end
+
+      # Accepts the request. A form request takes the values as keywords,
+      # and the fields you leave out take the defaults the server gave
+      # them; a URL request takes none, meaning the user agreed to visit
+      # the page.
+      def answer(**values)
+        @response = { action: 'accept', content: (with_defaults(values) unless url?) }.compact
+      end
+
+      # Declines the request.
+      def decline
+        @response = { action: 'decline' }
+      end
+
+      # Returns whether the request has been answered or declined.
+      def answered?
+        !response.nil?
+      end
+
+      def to_h # :nodoc:
+        { 'key' => key, 'params' => @params, 'response' => response&.transform_keys(&:to_s) }.compact
+      end
+
+      private
+
+      def with_defaults(values)
+        fields.reject { |field| field.default.nil? }.to_h { |field| [field.name, field.default] }
+              .merge(values).transform_keys(&:to_s)
+      end
+
+      def fields_from(schema)
+        required = Array(schema['required'])
+        schema.fetch('properties', {}).map do |name, property|
+          Field.new(name: name.to_sym, type: property['type'], title: property['title'],
+                    description: property['description'], required: required.include?(name),
+                    choices: choices(property), default: property['default'])
+        end
+      end
+
+      def choices(property)
+        options = property['enum'] || Array(property['oneOf'] || property.dig('items', 'anyOf')).map { |o| o['const'] }
+        options unless options.empty?
+      end
+
+      def inspect_attributes
+        { message:, url:, fields: fields.map(&:name) }
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/input_required_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Raised when a server needs input from the user and no
+    # MCP.before_input_request callback answered. Its message includes what
+    # the server asked for, and #requests has the MCP::InputRequest objects.
+    # In a chat, the tool call pauses instead, and Chat#pending_inputs
+    # returns the requests.
+    class InputRequiredError < Error
+      def initialize(server, input) # :nodoc:
+        @input = input
+        asks = requests.map { |request| [request.message, request.url].compact.join(' ') }
+        super("#{server} needs input from the user: #{asks.join('; ')}")
+      end
+
+      # The unanswered MCP::InputRequest objects.
+      def requests
+        @input['requests'].reject(&:answered?)
+      end
+
+      # Returns everything needed to answer the requests later and resume
+      # the call, as a Hash that serializes to JSON.
+      def to_h # :nodoc:
+        @input.merge('requests' => @input['requests'].map(&:to_h)).compact
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/listener.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Keeps a subscription to a server's changes open in a thread of its
+    # own, so the notifications reach the MCP while chats and requests go
+    # on. #start returns once the server acknowledges the subscription.
+    # When a stream ends, the listener subscribes again after a delay that
+    # starts at a second and doubles up to a minute, and gives up when the
+    # server agrees to send nothing or does not know the method. Changes
+    # made in between are lost, so once the server acknowledges again, the
+    # +resumed+ callable receives what the listener listens to.
+    #
+    # Stopping raises CancelledError in the listener's thread. Callbacks run
+    # with that deferred, so a stop never cuts one short, and inside the
+    # Rails executor when Rails is loaded. The thread reports no progress
+    # to a chat that started it. A forked child does not inherit the
+    # thread, so it listens again only when started again.
+    class Listener # :nodoc:
+      RETRY_DELAY = 1
+      MAX_RETRY_DELAY = 60
+      STOP_TIMEOUT = 5
+
+      def initialize(client, name:, timeout:, resumed: nil, &on_notification)
+        @client = client
+        @name = name
+        @timeout = timeout
+        @resumed = resumed
+        @on_notification = on_notification
+        @control = Mutex.new
+        @lock = Mutex.new
+        @acknowledged = ConditionVariable.new
+      end
+
+      # Listens for +changes+, a subscriptions/listen filter, instead of
+      # whatever the listener heard before. Returns the changes the server
+      # agreed to send, or +nil+ when there is nothing to listen for.
+      def start(changes)
+        @control.synchronize do
+          next @state if running? && changes == @changes
+
+          halt
+          launch(changes) unless changes.empty?
+        end
+      end
+
+      def stop
+        @control.synchronize { halt }
+      end
+
+      private
+
+      def running?
+        @pid == Process.pid && @thread&.alive?
+      end
+
+      def launch(changes)
+        @changes = changes
+        @pid = Process.pid
+        @state = nil
+        @thread = Thread.new { Support::ProgressReporter.listen(nil) { run } }
+        @thread.name = 'ruby_llm-mcp-listener'
+        @thread.report_on_exception = false
+        acknowledgment
+      end
+
+      def acknowledgment
+        settled = settle_within(@timeout)
+        return @state if @state.is_a?(Hash)
+
+        halt
+        raise @state if settled
+
+        raise Error, "#{@name} did not acknowledge the subscription"
+      end
+
+      def settle_within(timeout)
+        deadline = monotonic_now + timeout
+        @lock.synchronize do
+          until @state
+            remaining = deadline - monotonic_now
+            return false unless remaining.positive?
+
+            @acknowledged.wait(@lock, remaining)
+          end
+          true
+        end
+      end
+
+      def run
+        delay = RETRY_DELAY
+        loop do
+          opened = monotonic_now
+          ending = subscribe
+          break unless again?(ending)
+
+          delay = RETRY_DELAY if monotonic_now - opened >= MAX_RETRY_DELAY
+          pause(delay * (1 + rand) / 2, ending)
+          delay = [delay * 2, MAX_RETRY_DELAY].min
+        end
+      rescue CancelledError
+        nil
+      end
+
+      def pause(seconds, ending)
+        reason = ending ? "stopped sending changes: #{ending.message}" : 'ended the subscription'
+        RubyLLM.logger.warn { "#{@name} #{reason}; listening again in #{seconds.round(1)}s" }
+        sleep(seconds)
+      end
+
+      def subscribe
+        @client.listen(@changes) { |notification| receive(notification) }
+        nil
+      rescue CancelledError
+        raise
+      rescue StandardError => e
+        e
+      end
+
+      def receive(notification)
+        acknowledged = notification['method'] == Client::ACKNOWLEDGED
+        listened = notification.dig('params', 'notifications') || {}
+        resumed = acknowledged && @resumed && @state.is_a?(Hash)
+        Thread.handle_interrupt(CancelledError => :never) do
+          dispatch(@on_notification, notification)
+          dispatch(@resumed, listened) if resumed
+        end
+        settle(listened) if acknowledged
+      end
+
+      def dispatch(callback, argument)
+        executor = defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.executor
+        executor ? executor.wrap { callback.call(argument) } : callback.call(argument)
+      rescue StandardError => e
+        RubyLLM.logger.error { "#{@name} after_change callback failed: #{e.class}: #{e.message}" }
+      end
+
+      def again?(ending)
+        unless @state.is_a?(Hash)
+          settle(ending || Error.new("#{@name} ended the subscription before acknowledging it"))
+          return false
+        end
+
+        !@state.empty? && !(ending.is_a?(Error) && ending.code == Client::METHOD_NOT_FOUND)
+      end
+
+      def settle(state)
+        @lock.synchronize do
+          @state = state
+          @acknowledged.broadcast
+        end
+      end
+
+      def halt
+        thread = @thread
+        @thread = nil
+        return unless thread&.alive? && @pid == Process.pid
+
+        thread.raise(CancelledError)
+        thread.join(STOP_TIMEOUT) unless thread == Thread.current
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end