ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/mcp.rb

@@ -31,6 +31,7 @@ module RubyLLM
   # writing.
   class MCP
     include Support::Inspectable
+    include Support::Rescuable
 
     INPUT_ROUNDS = 10
     INPUT_REQUESTS = %i[form url].freeze
@@ -47,14 +48,36 @@ module RubyLLM
     UNKNOWN_TOOL_ERRORS = [-32_601, -32_602].freeze
 
     SETTINGS = %i[
-      @url @command @directory @env @headers @bearer_token @timeout @input_names @only @except @prefix
+      @url @allow_http @command @directory @env @headers @bearer_token @timeout @input_names @only @except @prefix
       @tool_declarations @approvals @deferrals @callbacks @oauth @input_requests @extensions @log_level
     ].freeze
     private_constant :SETTINGS, :INPUT_ROUNDS, :INPUT_REQUESTS, :INLINE_SETTINGS, :EXTENSIONS, :POLL_INTERVAL,
                      :LOG_LEVELS, :UNKNOWN_TOOL_ERRORS
 
+    ##
+    # :singleton-method: rescue_from
+    # :call-seq: rescue_from(*exception_classes, with: nil, &block)
+    #
+    # Registers a handler for exceptions raised while one of the server's
+    # tools runs in a chat, the way Tool.rescue_from does for a Tool. Name
+    # the handler with +with:+ or pass a block; either runs on the MCP
+    # instance, so declared ::inputs are available. The handler's return
+    # value becomes the call's result. Re-raise to stop the chat.
+    #
+    #   class Linear < RubyLLM::MCP
+    #     url "https://mcp.linear.app/mcp"
+    #
+    #     rescue_from RubyLLM::MCP::Error do |error|
+    #       { error: "Linear couldn't answer: #{error.message}" }
+    #     end
+    #   end
+    #
+    # A handler declared here comes before one declared on MCP::Tool. Tool
+    # classes added with ::tool use their own handlers.
+
     class << self
       attr_writer :default_name # :nodoc:
+      attr_reader :allow_http # :nodoc:
 
       def inherited(subclass) # :nodoc:
         super
@@ -65,15 +88,22 @@ module RubyLLM
         subclass.transport(@transport) if @transport
       end
 
-      # Sets the server's Streamable HTTP endpoint. Plain HTTP is only
-      # allowed for loopback addresses. Called with no argument, returns the
-      # configured value.
+      # Sets the server's Streamable HTTP endpoint. Called with no argument,
+      # returns the configured value.
       #
       #   url "https://mcp.linear.app/mcp"
       #
-      def url(value = nil)
+      # Plain HTTP is only allowed for loopback addresses. Pass
+      # <tt>allow_http: true</tt> for a server on a network you trust, such as
+      # a Compose or Kubernetes service. Anyone on that network can read and
+      # change the traffic, including any token you send.
+      #
+      #   url "http://tools:4011/mcp", allow_http: true
+      #
+      def url(value = nil, allow_http: false)
         return @url if value.nil?
 
+        @allow_http = allow_http
         @url = value
       end
 
@@ -106,8 +136,8 @@ module RubyLLM
       # <tt>notify(message, version:)</tt> and
       # <tt>cancel(notification, version:)</tt> send a notification, and
       # +close+ releases the connection until the next request. Raise
-      # MCP::Error when the server cannot be reached. The transport handles
-      # its own authentication and timeouts.
+      # RubyLLM::ConnectionError when the server cannot be reached. The
+      # transport handles its own authentication and timeouts.
       def transport(value = nil, &block)
         return @transport if value.nil? && block.nil?
 
@@ -124,8 +154,11 @@ module RubyLLM
         @directory = value
       end
 
-      # Adds environment variables for a stdio server's process. Values may
-      # be blocks or method names. Called with no arguments, returns them.
+      # Adds environment variables for a stdio server's process, which
+      # inherits only a short list of safe variables from the application.
+      # Values override inherited ones and may be blocks or method names,
+      # read each time the process starts. Called with no arguments, returns
+      # them.
       #
       #   env NODE_ENV: "production", API_KEY: -> { user.api_key }
       #
@@ -145,9 +178,7 @@ module RubyLLM
         @headers = headers.merge(name.to_s => block || value)
       end
 
-      def headers # :nodoc:
-        @headers || {}
-      end
+      def headers = @headers || {} # :nodoc:
 
       # Sets the bearer token sent in the +Authorization+ header. Pass the
       # token, a method name, or a block. Called with no argument, returns the
@@ -204,16 +235,25 @@ module RubyLLM
       #   oauth owner: :user, client_id: ENV["WIKI_CLIENT_ID"], client_secret: ENV["WIKI_CLIENT_SECRET"],
       #         identity_provider: { issuer: "https://acme.okta.com", client_id: ENV["OKTA_CLIENT_ID"],
       #                              client_secret: ENV["OKTA_CLIENT_SECRET"], id_token: -> { user.id_token } }
+      #
+      # +authorization_params:+ adds query parameters to MCP#authorization_url
+      # that the authorization server needs, such as Google's
+      # +access_type+, which it requires before it issues a refresh token.
+      # It may be a block or method name, and so may its values. The
+      # parameters RubyLLM sets itself, such as +client_id+, +state+, and
+      # +scope+, raise ArgumentError.
+      #
+      #   oauth authorization_params: { access_type: "offline", prompt: "consent" }
       def oauth(owner: nil, scopes: nil, client_id: nil, client_secret: nil, grant: nil, private_key: nil,
-                assertion: nil, identity_provider: nil)
+                assertion: nil, identity_provider: nil, authorization_params: nil)
         raise ArgumentError, "Unknown OAuth grant: #{grant}" unless grant.nil? || OAuth::GRANTS.include?(grant)
 
-        @oauth = { owner:, scopes:, client_id:, client_secret:, grant:, private_key:, assertion:, identity_provider: }
+        OAuth.check_authorization_params(authorization_params) if authorization_params.is_a?(Hash)
+        @oauth = { owner:, scopes:, client_id:, client_secret:, grant:, private_key:, assertion:, identity_provider:,
+                   authorization_params: }
       end
 
-      def oauth_settings # :nodoc:
-        @oauth
-      end
+      def oauth_settings = @oauth # :nodoc:
 
       # Sets how many seconds a request to the server may take. Defaults to
       # the configured +request_timeout+.
@@ -334,9 +374,7 @@ module RubyLLM
         @deferrals = deferrals + [names.flatten.map(&:to_s)]
       end
 
-      def deferrals # :nodoc:
-        @deferrals || []
-      end
+      def deferrals = @deferrals || [] # :nodoc:
 
       # Registers a callback for the progress the server reports while it
       # works on a request. Pass a method name or a block; either runs on
@@ -369,11 +407,14 @@ module RubyLLM
         add_callback(:after_change, method, block)
       end
 
-      # Sets the kinds of requests for input the server may send: +:form+,
-      # +:url+, or both, the default. Pass +false+ when your app cannot
-      # show them to anyone, so a call never waits on an answer that will
-      # not come. RubyLLM declines requests of other kinds. Called with no
-      # arguments, returns the accepted kinds.
+      # Sets the kinds of questions the server may ask the person (see
+      # Question): +:form+, for values, +:url+, to visit a page, or both, the
+      # default. Pass +false+ when your app cannot show them to anyone, so a
+      # call never waits on an answer that will not come. RubyLLM declines
+      # questions of other kinds, and asks to visit anything but a web page
+      # (an +http+ or +https+ address), so a link to the page can't run
+      # script in your app. Called with no arguments, returns the accepted
+      # kinds.
       #
       #   input_requests false
       #   input_requests :url
@@ -388,13 +429,15 @@ module RubyLLM
         @input_requests = kinds
       end
 
-      # Registers a callback for the server's requests for input from the
-      # user. Pass a method name or a block; either runs on the MCP instance
-      # with an MCP::InputRequest to answer or decline. In a chat, a request
-      # no callback answers pauses the tool call; see Chat#pending_inputs.
+      # Registers a callback for the server's questions to the person. Pass
+      # a method name or a block; either runs on the MCP instance with a
+      # Question to answer or decline. In a chat, a question no callback
+      # answers pauses the tool call; see Chat#pending_questions. Answer
+      # only the questions you recognize: an answer a question can't take
+      # raises ArgumentError from the call.
       #
       #   before_input_request :ask_operator
-      #   before_input_request { |request| request.answer(environment: "staging") }
+      #   before_input_request { |question| question.decline if question.url? }
       #
       def before_input_request(method = nil, &block)
         add_callback(:before_input_request, method, block)
@@ -457,12 +500,21 @@ module RubyLLM
         default_name_for(url:, command:) if url || command
       end
 
+      def derived_name? # :nodoc:
+        name.nil? && @default_name.nil?
+      end
+
+      def endpoint # :nodoc:
+        url || Array(command).join(' ')
+      end
+
       # Builds an anonymous MCP class from keywords, as RubyLLM.mcp does.
-      def define(name: nil, headers: {}, env: {}, oauth: nil, extensions: nil, **settings) # :nodoc:
+      def define(name: nil, headers: {}, env: {}, oauth: nil, extensions: nil, allow_http: false, **settings) # :nodoc:
         check_inline_settings(name, settings)
 
         Class.new(self) do
           settings.each { |setting, value| public_send(setting, value) unless value.nil? }
+          url(settings[:url], allow_http:)
           headers.each { |header_name, value| header(header_name, value) }
           Array(extensions).each { |extension_name, options| extension(extension_name, **options.to_h) }
           env(**env)
@@ -495,14 +547,15 @@ module RubyLLM
       def default_name_for(url:, command:)
         return File.basename(Array(command).first.to_s) unless url
 
-        labels = URI(url).host.split('.')[0...-1] - %w[mcp api www]
+        labels = HTTP.parse(url).host.split('.')
+        labels = labels[0...-1] - %w[mcp api www] unless labels.one? || labels.all?(/\A\d+\z/)
         labels.join('_')
       end
     end
 
     # Creates an MCP. Keywords are the values of the declared ::inputs.
     # Pass a Context as +context:+ to connect with its configuration: its
-    # +faraday_adapter+, +http_proxy+, and +request_timeout+ apply to the
+    # +faraday_adapter+, +http_proxy+, +ssl+, and +request_timeout+ apply to the
     # server's requests and to its OAuth requests.
     #
     #   Linear.new(user: current_user)
@@ -545,6 +598,8 @@ module RubyLLM
       end
     end
 
+    def tools_listed? = !@tools.nil? # :nodoc:
+
     # Calls the server tool +name+ with +arguments+ and returns an
     # MCP::Result. Every server tool is also a method:
     #
@@ -629,9 +684,9 @@ module RubyLLM
     end
 
     # Returns whether +tool+, one of this MCP's tools, is deferred
-    # according to ::defer or a Tool class's own Tool.defer.
+    # according to ::defer or the tool's own Tool#deferred?.
     def defers?(tool) # :nodoc:
-      return true if tool.class.deferred?
+      return true if tool.deferred?
 
       self.class.deferrals.any? do |names|
         names.empty? || (tool.respond_to?(:server_name) && names.include?(tool.server_name))
@@ -641,13 +696,12 @@ module RubyLLM
     # Runs +tool+, one of this MCP's tools, with the model's +arguments+.
     def run(tool, arguments, input: nil) # :nodoc:
       arguments = arguments.transform_keys(&:to_sym)
-      fixed = tool.fixed_arguments.transform_values { |value| value.is_a?(Proc) ? instance_exec(&value) : value }
-      params = { name: tool.server_name, arguments: arguments.merge(fixed) }
-      outcome = call_tool(params, input:)
-      return outcome if outcome.is_a?(Task)
+      params = { name: tool.server_name, arguments: arguments.merge(tool.resolved_fixed_arguments) }
+      outcome = Outages.calling(self, tool, input) { call_tool(params, input:) }
+      return outcome if outcome.is_a?(Task) || outcome.is_a?(Outages::Failure)
 
       result = Result.new(outcome, tool.ui_uri)
-      return { error: result.text } if result.error?
+      return result.ui_uri ? result : { error: result.text } if result.error?
 
       tool.wrap ? apply(tool.wrap, result, **arguments) : result
     end
@@ -672,7 +726,7 @@ module RubyLLM
     def await_task(task, timeout: nil, interval: nil) # :nodoc:
       limit = timeout || self.class.timeout || config.request_timeout
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + limit
-      until task.done?
+      until task.complete?
         ask_for_task_input(task) if task.status == :input_required
         remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
         raise Error, "Task #{task.id} did not finish in #{limit} seconds" unless remaining.positive?
@@ -680,7 +734,7 @@ module RubyLLM
         Support::Cancellation.pause([interval || poll_interval(task), remaining].min)
         task.refresh
       end
-      raise task.error unless task.completed?
+      raise task.error unless task.succeeded?
 
       task
     end
@@ -741,8 +795,9 @@ module RubyLLM
     #   reports.listen(tasks: chat.pending_tasks)
     #
     # Without +resources+ or +tasks+, does nothing for a server that
-    # announces no changes. Raises MCP::Error when the server cannot be
-    # reached or does not send updates for the resources or tasks.
+    # announces no changes. Raises RubyLLM::ConnectionError when a server
+    # over HTTP cannot be reached, and MCP::Error when the server does not
+    # send updates for the resources or tasks.
     def listen(resources: [], tasks: [])
       uris = resources.map { |resource| resource.respond_to?(:uri) ? resource.uri : resource.to_s }
       ids = tasks.map { |task| task.respond_to?(:id) ? task.id : task.to_s }
@@ -793,9 +848,9 @@ module RubyLLM
     end
 
     def responses(requests)
-      requests.to_h do |request|
-        request = InputRequest.from_h(request) if request.is_a?(Hash)
-        [request.key, request.response]
+      requests.to_h do |question|
+        question = Question.from_h(question) if question.is_a?(Hash)
+        [question.key, question.response&.except('note')]
       end
     end
 
@@ -816,8 +871,8 @@ module RubyLLM
     def check_task(task, answered_requests)
       update_task(task, answered_requests) if answered_requests
       task.refresh
-      return task.data['result'] if task.completed?
-      raise task.error if task.done?
+      return task.data['result'] if task.succeeded?
+      raise task.error if task.complete?
 
       ask_for_task_input(task) if task.status == :input_required
       task
@@ -838,7 +893,8 @@ module RubyLLM
     end
 
     def poll_interval(task)
-      task.poll_interval || POLL_INTERVAL
+      interval = task.poll_interval
+      interval&.positive? ? interval : POLL_INTERVAL
     end
 
     def finish(task)
@@ -846,7 +902,7 @@ module RubyLLM
     rescue StandardError
       begin
         task.cancel
-      rescue Error, Faraday::Error => e
+      rescue RubyLLM::Error, Faraday::Error => e
         RubyLLM.logger.debug { "#{name} could not cancel task #{task.id}: #{e.message}" }
       end
       raise
@@ -856,18 +912,20 @@ module RubyLLM
       result.fetch('inputRequests', {}).filter_map do |key, request|
         next unless request['method'] == 'elicitation/create'
 
-        InputRequest.new(key, request['params'] || {}).tap do |input_request|
-          next input_request.decline unless accepts?(input_request)
+        Question.new(key, request['params'] || {}).tap do |question|
+          next question.decline unless accepts?(question)
 
           self.class.callbacks(:before_input_request).each do |callback|
-            apply(callback, input_request) unless input_request.answered?
+            apply(callback, question) unless question.answered?
           end
         end
       end
     end
 
-    def accepts?(input_request)
-      self.class.input_requests.include?(input_request.url? ? :url : :form)
+    def accepts?(question)
+      return self.class.input_requests.include?(:form) unless question.url?
+
+      self.class.input_requests.include?(:url) && HTTP.web?(question.url)
     end
 
     def send_request(method, params)
@@ -1032,17 +1090,23 @@ module RubyLLM
       if settings.transport
         resolve(settings.transport)
       elsif settings.url
-        HTTP.new(resolve(settings.url), headers: method(:request_headers), timeout: settings.timeout,
-                                        unauthorized: method(:unauthorized), responded: method(:responded), config:)
+        HTTP.new(resolve(settings.url), allow_http: settings.allow_http, headers: method(:request_headers),
+                                        timeout: settings.timeout, unauthorized: method(:unauthorized),
+                                        responded: method(:responded), idempotent: method(:idempotent?), config:)
       elsif settings.command
         Stdio.new(settings.command.map { |part| resolve(part) },
-                  env: settings.env.transform_values { |value| resolve(value) },
+                  env: -> { settings.env.transform_values { |value| resolve(value) } },
                   directory: resolve(settings.directory), timeout: settings.timeout, config:)
       else
         raise ConfigurationError, "#{settings.name || 'MCP'} needs a url, a command, or a transport"
       end
     end
 
+    def idempotent?(name)
+      definition = @server_tools&.find { |server_tool| server_tool['name'] == name }
+      !definition.nil? && Tool.new(self, definition).idempotent?
+    end
+
     def request_headers(verb)
       headers = self.class.headers.transform_values { |value| resolve(value) }
       return headers.merge(oauth.authorization_headers(verb)) if self.class.oauth_settings