ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/mcp/param_headers.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Mirrors tool arguments marked with +x-mcp-header+ into Mcp-Param-*
+    # HTTP headers, as 2026-07-28 requires, so intermediaries can route on
+    # them. Tools that declare invalid headers are left out entirely.
+    module ParamHeaders # :nodoc:
+      TOKEN = /\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/
+      TYPES = %w[string integer boolean].freeze
+      SCHEMA_MAPS = %w[$defs definitions patternProperties dependentSchemas dependencies].freeze
+      SCHEMA_VALUES = %w[
+        items prefixItems additionalItems contains additionalProperties unevaluatedItems unevaluatedProperties
+        propertyNames allOf anyOf oneOf not if then else contentSchema
+      ].freeze
+
+      module_function
+
+      def valid?(definition)
+        declared = declarations(definition)
+        names = declared.map { |_, header, _| header.to_s.downcase }
+        valid = declared.all? { |path, header, schema| valid_declaration?(path, header, schema) }
+        return true if valid && names.uniq.size == names.size
+
+        RubyLLM.logger.warn { "Ignoring MCP tool #{definition['name']}: it declares invalid x-mcp-header values" }
+        false
+      end
+
+      def for(definition, arguments)
+        declarations(definition).each_with_object({}) do |(path, header, _), headers|
+          value = argument_at(arguments, path)
+          headers[header] = value.to_s unless value.nil?
+        end
+      end
+
+      def declarations(definition)
+        schema_declarations(definition['inputSchema'], [])
+      end
+
+      def valid_declaration?(path, header, schema)
+        path&.any? && header.is_a?(String) && header.match?(TOKEN) && TYPES.include?(schema['type'])
+      end
+
+      def schema_declarations(schema, path)
+        return [] unless schema.is_a?(Hash)
+
+        declared = schema.key?('x-mcp-header') ? [[path, schema['x-mcp-header'], schema]] : []
+        declared + property_declarations(schema['properties'], path) +
+          unreachable_schemas(schema).flat_map { |child| schema_declarations(child, nil) }
+      end
+
+      def property_declarations(properties, path)
+        return [] unless properties.is_a?(Hash)
+
+        properties.flat_map do |property, child|
+          schema_declarations(child, path && [*path, property])
+        end
+      end
+
+      def unreachable_schemas(schema)
+        schema.flat_map do |keyword, children|
+          case keyword
+          when *SCHEMA_MAPS
+            children.is_a?(Hash) ? children.values : []
+          when *SCHEMA_VALUES
+            children.is_a?(Array) ? children : [children]
+          else
+            []
+          end
+        end
+      end
+
+      def argument_at(arguments, path)
+        path.reduce(arguments) do |value, property|
+          break unless value.is_a?(Hash)
+
+          argument = value[property.to_sym]
+          argument.nil? ? value[property] : argument
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/prompt.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # A prompt an MCP server offers: messages written by the server and
+    # filled in with your arguments. Ask a chat with it like a question.
+    #
+    #   github.prompts                     # => [#<RubyLLM::MCP::Prompt name: "code_review", ...>]
+    #   review = github.prompt(:code_review, code: diff)
+    #   review.messages                    # => [#<RubyLLM::Message role: :user, ...>]
+    #   chat.ask review
+    #
+    class Prompt
+      include Support::Inspectable
+
+      # An argument a prompt takes.
+      Argument = Struct.new(:name, :description, :required, keyword_init: true) do
+        # Returns whether the prompt needs this argument.
+        def required?
+          required == true
+        end
+      end
+
+      # The prompt's name.
+      attr_reader :name
+
+      # A human-readable title, or +nil+.
+      attr_reader :title
+
+      # What the prompt does, or +nil+.
+      attr_reader :description
+
+      # The arguments the prompt takes, as Argument objects.
+      attr_reader :arguments
+
+      def initialize(mcp, data, messages: nil) # :nodoc:
+        @mcp = mcp
+        @name = data['name']
+        @title = data['title']
+        @description = data['description']
+        @arguments = Array(data['arguments']).map do |argument|
+          Argument.new(name: argument['name'].to_sym, description: argument['description'],
+                       required: argument['required'])
+        end
+        @messages = messages
+      end
+
+      # Returns the prompt's messages as Message objects. A prompt from
+      # MCP#prompts has none until you fill it in with MCP#prompt.
+      def messages
+        @messages || []
+      end
+
+      # Asks the server to complete an argument's partial value. Pass one
+      # argument to complete and any others that are already filled in.
+      # Returns an Array of suggested values.
+      #
+      #   github.prompts.first.suggest(language: "ru")  # => ["ruby", "rust"]
+      #
+      def suggest(**arguments)
+        @mcp.suggest({ type: 'ref/prompt', name: }, arguments)
+      end
+
+      private
+
+      def inspect_attributes
+        { name:, arguments: arguments.map(&:name), messages: messages.size.nonzero? }
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/resource.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # A resource on an MCP server: a file, a record, or any data the server
+    # names with a URI. Pass one to a chat like any attachment, or save it.
+    #
+    #   readme = files.resource("file:///project/README.md")
+    #   readme.content                 # => "# My Project..."
+    #   readme.save("README.md")
+    #   chat.ask "Summarize this", with: readme
+    #
+    # Resources from MCP#resources are read from the server the first time
+    # their content is needed.
+    class Resource
+      include Support::Inspectable
+
+      # The URI that identifies the resource on its server.
+      attr_reader :uri
+
+      # The resource's name.
+      attr_reader :name
+
+      # A human-readable title, or +nil+.
+      attr_reader :title
+
+      # What the resource is, or +nil+.
+      attr_reader :description
+
+      # The MIME type the server reports, or +nil+.
+      attr_reader :mime_type
+
+      # The +_meta+ the server sent with the resource, as a Hash with String
+      # keys, empty when there is none. A resource read with MCP#resource
+      # has the +_meta+ of its contents; one from MCP#resources has the
+      # +_meta+ of the listing.
+      attr_reader :meta
+
+      def initialize(mcp, data) # :nodoc:
+        @mcp = mcp
+        @uri = data['uri']
+        @name = data['name'] || Content.filename(uri)
+        @title = data['title']
+        @description = data['description']
+        @mime_type = data['mimeType']
+        @meta = data['_meta'] || {}
+        @data = data
+      end
+
+      # Returns the resource's content: text for text resources, bytes for
+      # binary ones.
+      def content
+        @content ||= if @data.key?('text') then @data['text']
+                     elsif @data.key?('blob') then Base64.decode64(@data['blob'])
+                     else @mcp.resource(uri).content
+                     end
+      end
+
+      # Returns the content as a String of bytes.
+      def to_blob
+        content.b
+      end
+
+      # Writes the content to +path+, expanding it first. Returns +path+.
+      def save(path)
+        File.binwrite(File.expand_path(path), to_blob)
+        path
+      end
+
+      # Returns the resource as an Attachment, which is how chats take it
+      # through +with:+.
+      def to_attachment
+        filename = Content.filename(uri)
+        Attachment.new(StringIO.new(to_blob), filename: filename.empty? ? name : filename)
+      end
+
+      private
+
+      def inspect_attributes
+        { uri:, name:, mime_type: }
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/resource_template.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # A family of resources on an MCP server, named by a URI template.
+    #
+    #   template = files.resource_templates.first
+    #   template.uri                        # => "file:///{path}"
+    #   template.suggest(path: "app/mo")    # => ["app/models/"]
+    #   files.resource(template.uri, path: "Gemfile")
+    #
+    class ResourceTemplate
+      include Support::Inspectable
+
+      OPERATORS = {
+        '' => [',', false], '+' => [',', true], '#' => [',', true], '/' => ['/', false],
+        '.' => ['.', false], ';' => [';', false], '?' => ['&', false], '&' => ['&', false]
+      }.freeze
+      NAMED_OPERATORS = %w[? & ;].freeze
+      private_constant :OPERATORS, :NAMED_OPERATORS
+
+      # The URI template, such as <tt>"file:///{path}"</tt>.
+      attr_reader :uri
+
+      # The template's name.
+      attr_reader :name
+
+      # A human-readable title, or +nil+.
+      attr_reader :title
+
+      # What the resources are, or +nil+.
+      attr_reader :description
+
+      # The MIME type of the resources, or +nil+.
+      attr_reader :mime_type
+
+      def self.expand(template, variables) # :nodoc:
+        variables = variables.transform_keys(&:to_s)
+        template.gsub(%r{\{([+#./;?&]?)([^{}]+)\}}) do
+          expand_expression(Regexp.last_match(1), Regexp.last_match(2).split(','), variables)
+        end
+      end
+
+      def self.expand_expression(operator, specs, variables) # :nodoc:
+        separator, reserved = OPERATORS.fetch(operator)
+        values = specs.filter_map { |spec| expand_variable(spec, operator, separator, reserved, variables) }
+        return '' if values.empty?
+
+        prefix = ['', '+'].include?(operator) ? '' : operator
+        "#{prefix}#{values.join(separator)}"
+      end
+
+      # Expands one variable with its prefix (+:3+) and explode (+*+)
+      # modifiers. Array values join with the operator's separator when
+      # exploded and with commas otherwise.
+      def self.expand_variable(spec, operator, separator, reserved, variables) # :nodoc:
+        explode = spec.end_with?('*')
+        name, length = spec.delete_suffix('*').split(':')
+        return unless variables.key?(name)
+
+        parts = Array(variables[name]).map { |part| encode(length ? part.to_s[0, length.to_i] : part.to_s, reserved) }
+        named = NAMED_OPERATORS.include?(operator)
+        return parts.map { |part| named ? "#{name}=#{part}" : part }.join(separator) if explode
+
+        named ? "#{name}=#{parts.join(',')}" : parts.join(',')
+      end
+
+      def self.encode(value, reserved) # :nodoc:
+        pattern = reserved ? %r{[^A-Za-z0-9\-._~:/?#\[\]@!$&'()*+,;=%]} : /[^A-Za-z0-9\-._~]/
+        value.gsub(pattern) { |char| char.bytes.map { |byte| format('%%%02X', byte) }.join }
+      end
+
+      def initialize(mcp, data) # :nodoc:
+        @mcp = mcp
+        @uri = data['uriTemplate']
+        @name = data['name']
+        @title = data['title']
+        @description = data['description']
+        @mime_type = data['mimeType']
+      end
+
+      # Asks the server to complete a variable's partial value. Pass one
+      # variable to complete and any others that are already filled in.
+      # Returns an Array of suggested values.
+      #
+      #   template.suggest(path: "app/mo")  # => ["app/models/"]
+      #
+      def suggest(**variables)
+        @mcp.suggest({ type: 'ref/resource', uri: }, variables)
+      end
+
+      private
+
+      def inspect_attributes
+        { uri:, name: }
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/result.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # The result of calling an MCP tool. Text, files, and structured data
+    # each have their own reader.
+    #
+    #   result = linear.list_issues(query: "bug")
+    #   result.text        # => "Found 3 issues..."
+    #   result.structured  # => { "issues" => [...] }
+    #   result.attachments # => [#<RubyLLM::Attachment ...>]
+    #   result.meta        # => { "com.linear/request_id" => "..." }
+    #
+    # In a chat, the result of a tool with a UI stays on its tool result
+    # message as Message#mcp_result, so your app can render the UI again.
+    class Result
+      include Support::Inspectable
+
+      # The text of the result, with text blocks joined by blank lines.
+      attr_reader :text
+
+      # Images, audio, and embedded files, as Attachment objects.
+      attr_reader :attachments
+
+      # The structured content, parsed from JSON, or +nil+.
+      attr_reader :structured
+
+      # The result's +_meta+ as the server sent it: a Hash with String
+      # keys, empty when there is none.
+      attr_reader :meta
+
+      # The URI of the UI that renders the result, from its tool's
+      # MCP::Tool#ui_uri, or +nil+ for a tool without one.
+      attr_reader :ui_uri
+
+      def self.load(data) # :nodoc:
+        new(data['result'], data['ui_uri'])
+      end
+
+      def initialize(data, ui_uri = nil) # :nodoc:
+        @data = data
+        @ui_uri = ui_uri
+        @structured = data['structuredContent']
+        @meta = data['_meta'] || {}
+        @text, @attachments = Content.read(data['content'])
+      end
+
+      # Returns whether the tool reported a failure.
+      def error?
+        @data['isError'] == true
+      end
+
+      # Returns what a chat sends to the model: the text, or the structured
+      # content as JSON when there is no text, followed by any attachments.
+      def content
+        body = text.empty? && structured ? JSON.generate(structured) : text
+        attachments.empty? ? body : [body, *attachments]
+      end
+
+      # Returns the result as the server sent it.
+      def to_h
+        @data
+      end
+
+      def dump # :nodoc:
+        { 'ui_uri' => ui_uri, 'result' => to_h }
+      end
+
+      private
+
+      def inspect_attributes
+        { text:, structured:, attachments: attachments.size.nonzero?, error: error? || nil, ui_uri: }
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/session_expired.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Raised by a transport when the session of a server that predates
+    # 2026-07-28 has ended, so the client starts a new one: the server
+    # answered 404, or its stdio process exited.
+    class SessionExpired < Error; end # :nodoc:
+  end
+end

data/lib/ruby_llm/mcp/stdio.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'io/wait'
+require 'open3'
+
+module RubyLLM
+  class MCP
+    # stdio. The server is a child process that reads one JSON-RPC message
+    # per line on stdin and writes one per line on stdout. Reads never block
+    # past the deadline, even on a partial line. It starts on the
+    # first request, restarts after it exits, and handles one request at a
+    # time. Its stderr is the parent's. A server that predates 2026-07-28
+    # keeps its session for the life of its process, so after a restart its
+    # requests raise SessionExpired until the client initializes it again.
+    #
+    # Subscriptions share the channel, so whichever thread reads a message
+    # that belongs to one hands it to the subscription's listener: a
+    # request waiting for its answer, or the listener itself while no
+    # request reads. A listener stops when CancelledError is raised in its
+    # thread, so it reads and writes with that deferred.
+    class Stdio # :nodoc:
+      SHUTDOWN_GRACE = 2
+      CHECK_INTERVAL = 0.5
+      SUBSCRIPTION_ID = 'io.modelcontextprotocol/subscriptionId'
+
+      # The messages of the subscription opened by request +id+, or with no
+      # +id+, the changes a server that predates subscriptions announces.
+      Subscription = Struct.new(:id, :messages) do
+        def claims?(message)
+          return !message.key?('id') && Client::CHANGES.include?(message['method']) if id.nil?
+
+          params = message['params'].is_a?(Hash) ? message['params'] : {}
+          params.dig('_meta', SUBSCRIPTION_ID) == id || answer?(message) ||
+            (message['method'] == 'notifications/cancelled' && params['requestId'] == id)
+        end
+
+        def answer?(message)
+          !id.nil? && message['id'] == id && !message.key?('method')
+        end
+      end
+
+      def initialize(command, env: {}, directory: nil, timeout: nil, config: RubyLLM.config)
+        @command = Array(command).map(&:to_s)
+        @env = env.to_h { |key, value| [key.to_s, value.to_s] }
+        @directory = directory&.to_s
+        @timeout = timeout || config.request_timeout
+        @lock = Mutex.new
+        @subscriptions = []
+      end
+
+      def request(message, version: nil, timeout: nil, **, &)
+        @lock.synchronize do
+          check_session(version)
+          write(message)
+          @session = @process if message[:method] == 'initialize'
+          await(message[:id], timeout || @timeout, &)
+        end
+      end
+
+      def notify(message, **)
+        @lock.synchronize { write(message) }
+        nil
+      end
+
+      def cancel(notification, **)
+        notify(notification)
+      end
+
+      def listen(message, **)
+        subscription = Subscription.new(message&.dig(:id), Queue.new)
+        process = uninterrupted { @lock.synchronize { subscribe(subscription, message) } }
+        loop do
+          until subscription.messages.empty?
+            reply = subscription.messages.pop
+            return reply if subscription.answer?(reply)
+
+            yield reply
+          end
+          raise Error, "#{name} exited" unless @process.equal?(process)
+
+          receive(subscription)
+        end
+      rescue IOError
+        raise Error, "#{name} exited"
+      ensure
+        uninterrupted { @lock.synchronize { @subscriptions.delete(subscription) } }
+      end
+
+      def close
+        @lock.synchronize { stop }
+      end
+
+      private
+
+      def check_session(version)
+        return if version.nil? || version == Client::VERSION || (@process&.alive? && @process.equal?(@session))
+
+        raise SessionExpired, "#{name} exited"
+      end
+
+      def subscribe(subscription, message)
+        raise Error, "#{name} exited" unless message || @process&.alive?
+
+        @subscriptions << subscription
+        write(message) if message
+        @process
+      end
+
+      def receive(subscription)
+        read = uninterrupted do
+          next false unless @lock.try_lock
+
+          begin
+            drain
+          ensure
+            @lock.unlock
+          end
+          true
+        end
+        return sleep(CHECK_INTERVAL) unless read
+
+        @stdout.wait_readable(CHECK_INTERVAL) if subscription.messages.empty?
+      end
+
+      def drain
+        loop do
+          while (line = @buffer.slice!(/\A[^\n]*\n/))
+            message = parse(line)
+            handled?(message) if message
+          end
+          chunk = @stdout.read_nonblock(65_536, exception: false)
+          return if chunk == :wait_readable
+
+          exited unless chunk
+          @buffer << chunk
+        end
+      end
+
+      def handled?(message)
+        return true if route(message)
+        return false unless message.key?('method') && message.key?('id')
+
+        answer(message)
+        true
+      end
+
+      def route(message)
+        @subscriptions.find { |subscription| subscription.claims?(message) }&.messages&.push(message)
+      end
+
+      def uninterrupted(&)
+        Thread.handle_interrupt(CancelledError => :never, &)
+      end
+
+      def await(id, timeout)
+        deadline = monotonic_now + timeout
+        loop do
+          reply = read(deadline)
+          return reply if reply['id'] == id && !reply.key?('method')
+
+          yield reply if !handled?(reply) && reply.key?('method') && block_given?
+        end
+      end
+
+      def write(message)
+        start unless @process&.alive?
+        @stdin.puts JSON.generate(message)
+        @stdin.flush
+      rescue Errno::EPIPE, IOError
+        stop
+        raise Error, "#{name} exited"
+      end
+
+      def read(deadline)
+        loop do
+          message = parse(next_line(deadline))
+          return message if message
+        end
+      end
+
+      def parse(line)
+        return if line.strip.empty?
+
+        message = JSON.parse(line)
+        message if message.is_a?(Hash)
+      rescue JSON::ParserError
+        RubyLLM.logger.debug { "#{name} wrote a line that is not JSON" }
+        nil
+      end
+
+      def next_line(deadline)
+        loop do
+          line = @buffer.slice!(/\A[^\n]*\n/)
+          return line if line
+
+          remaining = deadline - monotonic_now
+          raise Error, "#{name} did not answer in time" unless remaining.positive?
+
+          Support::Cancellation.check
+          next unless @stdout.wait_readable([remaining, CHECK_INTERVAL].min)
+
+          chunk = @stdout.read_nonblock(65_536, exception: false)
+          next if chunk == :wait_readable
+
+          exited unless chunk
+          @buffer << chunk
+        end
+      end
+
+      def exited
+        stop
+        raise Error, "#{name} exited"
+      end
+
+      def answer(request)
+        write(Client.reply(request))
+      end
+
+      def start
+        options = @directory ? { chdir: @directory } : {}
+        @stdin, @stdout, @process = Open3.popen2(@env, *@command, **options)
+        @buffer = +''
+      end
+
+      def stop
+        return unless @process
+
+        @stdin.close unless @stdin.closed?
+        @stdout.close unless @stdout.closed?
+        terminate unless @process.join(SHUTDOWN_GRACE)
+        @process = nil
+      end
+
+      def terminate
+        Process.kill('TERM', @process.pid)
+        Process.kill('KILL', @process.pid) unless @process.join(SHUTDOWN_GRACE)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def name
+        File.basename(@command.first.to_s)
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end