llm.rb 4.8.0 → 4.10.0

data/lib/llm/mcp/rpc.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+class LLM::MCP
+  ##
+  # The {LLM::MCP::RPC} module provides the JSON-RPC interface used by
+  # {LLM::MCP}. MCP uses JSON-RPC to exchange messages between a client
+  # and a server. A client sends a method name and its parameters as a
+  # request, and the server replies with either a result or an error.
+  #
+  # This module is responsible for composing those requests, applying
+  # the defaults needed by built-in MCP methods such as initialize,
+  # and reading responses for request methods. Notifications are sent
+  # without waiting for a response, and errors are raised as
+  # {LLM::MCP::Error}.
+  # @private
+  module RPC
+    ##
+    # Sends a method over the transport.
+    # @param [LLM::MCP::Transport] transport
+    #  The transport to write to
+    # @param [String] method
+    #  The method name to call
+    # @param [Hash] params
+    #  The parameters to send with the method call
+    # @return [Object, nil]
+    #  The result of the method call, or nil if it's a notification
+    def call(transport, method, params = {})
+      message = {jsonrpc: "2.0", method:, params: default_params(method).merge(params)}
+      if notification?(method)
+        transport.write(message)
+        nil
+      else
+        @request_id = (@request_id || -1) + 1
+        id = @request_id
+        transport.write(message.merge(id:))
+        recv(transport, id)
+      end
+    end
+
+    private
+
+    ##
+    # Reads a response from the transport.
+    # @param [LLM::MCP::Transport] transport
+    #  The transport to read from
+    # @param [Integer] id
+    #  The request id to wait for
+    # @raise [LLM::MCP::Error]
+    #  When the MCP process returns an error
+    # @return [Object, nil]
+    #  The result returned by the MCP process
+    def recv(transport, id)
+      poll(timeout:, ex: [IO::WaitReadable]) do
+        loop do
+          res = transport.read_nonblock
+          next unless res["id"] == id
+          if res["error"]
+            raise LLM::MCP::Error.from(response: res)
+          else
+            break res["result"]
+          end
+        end
+      end
+    end
+
+    ##
+    # Returns default parameters for built-in methods.
+    # @param [String] method
+    #  The method name
+    # @return [Hash]
+    def default_params(method)
+      case method
+      when "initialize"
+        {protocolVersion: "2025-03-26", capabilities: {}}
+      else
+        {}
+      end
+    end
+
+    ##
+    # Returns true when the method is a notification.
+    # @param [String] method
+    #  The method name
+    # @return [Boolean]
+    def notification?(method)
+      method.to_s.start_with?("notifications/")
+    end
+
+    ##
+    # Returns the maximum amount of time to wait when reading from an MCP process.
+    # @return [Integer]
+    def timeout
+      @timeout ||= 5
+    end
+
+    ##
+    # Runs a block until it succeeds, times out, or raises an unhandled exception.
+    # @param [Integer] timeout
+    #  The timeout for the block, in seconds
+    # @param [Array<Class>] ex
+    #  The exceptions to retry when raised
+    # @yield
+    #  The block to run
+    # @raise [LLM::MCP::TimeoutError]
+    #  When the block takes longer than the timeout
+    # @return [Object]
+    def poll(timeout:, ex: [])
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      loop do
+        return yield
+      rescue *ex
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+        raise LLM::MCP::TimeoutError, "MCP process timed out" if duration > timeout
+        sleep 0.05
+      end
+    end
+  end
+end

data/lib/llm/mcp/transport/http/event_handler.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module LLM::MCP::Transport
+  ##
+  # The {LLM::MCP::Transport::HTTP::EventHandler LLM::MCP::Transport::HTTP::EventHandler}
+  # class adapts generic server-sent event callbacks into decoded JSON-RPC
+  # messages for {LLM::MCP::Transport::HTTP LLM::MCP::Transport::HTTP}.
+  # It accumulates event data until a blank line terminates the current
+  # event, then parses the payload as JSON and yields it to the callback
+  # given at initialization.
+  # @private
+  class HTTP::EventHandler
+    ##
+    # @yieldparam [Hash] message
+    #  A decoded JSON-RPC message
+    # @return [LLM::MCP::Transport::HTTP::EventHandler]
+    def initialize(&on_message)
+      @on_message = on_message
+      reset
+    end
+
+    ##
+    # Receives the SSE event name.
+    # @param [LLM::EventStream::Event] event
+    #  The event stream event
+    # @return [void]
+    def on_event(event)
+      @event = event.value
+    end
+
+    ##
+    # Receives one line of SSE data.
+    # @param [LLM::EventStream::Event] event
+    #  The event stream event
+    # @return [void]
+    def on_data(event)
+      @data << event.value.to_s
+    end
+
+    # The generic event stream parser dispatches one line at a time.
+    # A blank line terminates the current SSE event.
+    # @param [LLM::EventStream::Event] event
+    #  The event stream event
+    # @return [void]
+    def on_chunk(event)
+      flush if event.chunk == "\n"
+    end
+
+    private
+
+    def flush
+      return reset if @data.empty? && @event.nil?
+      payload = @data.join("\n")
+      reset
+      return if payload.empty? || payload == "[DONE]"
+      @on_message.call(LLM.json.load(payload))
+    rescue *LLM.json.parser_error
+      reset
+    end
+
+    def reset
+      @event = nil
+      @data = []
+    end
+  end
+end

data/lib/llm/mcp/transport/http.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module LLM::MCP::Transport
+  ##
+  # The {LLM::MCP::Transport::HTTP LLM::MCP::Transport::HTTP} class
+  # provides an HTTP transport for {LLM::MCP LLM::MCP}. It sends
+  # JSON-RPC messages with HTTP POST requests and buffers response
+  # messages for non-blocking reads.
+  class HTTP
+    require_relative "http/event_handler"
+
+    ##
+    # @param [String] url
+    #  The URL for the MCP HTTP endpoint
+    # @param [Hash] headers
+    #  Extra headers to send with requests
+    # @param [Integer, nil] timeout
+    #  The timeout in seconds. Defaults to nil
+    # @return [LLM::MCP::Transport::HTTP]
+    def initialize(url:, headers: {}, timeout: nil)
+      @uri = URI.parse(url)
+      @use_ssl = @uri.scheme == "https"
+      @headers = headers
+      @timeout = timeout
+      @queue = []
+      @monitor = Monitor.new
+      @running = false
+    end
+
+    ##
+    # Starts the HTTP transport.
+    # @raise [LLM::MCP::Error]
+    #  When the transport is already running
+    # @return [void]
+    def start
+      lock do
+        raise LLM::MCP::Error, "MCP transport is already running" if running?
+        @queue.clear
+        @running = true
+      end
+    end
+
+    ##
+    # Stops the HTTP transport and closes the connection.
+    # This method is idempotent.
+    # @return [void]
+    def stop
+      lock do
+        return nil unless running?
+        @running = false
+        nil
+      end
+    end
+
+    ##
+    # Writes a JSON-RPC message via HTTP POST.
+    # @param [Hash] message
+    #  The JSON-RPC message
+    # @raise [LLM::MCP::Error]
+    #  When the transport is not running or the HTTP request fails
+    # @return [void]
+    def write(message)
+      raise LLM::MCP::Error, "MCP transport is not running" unless running?
+      http = Net::HTTP.start(uri.host, uri.port, use_ssl:, open_timeout: timeout, read_timeout: timeout)
+      req = Net::HTTP::Post.new(uri.path, headers.merge("content-type" => "application/json"))
+      req.body = LLM.json.dump(message)
+      http.request(req) do |res|
+        unless Net::HTTPSuccess === res
+          raise LLM::MCP::Error, "MCP transport write failed with HTTP #{res.code}"
+        end
+        read(res)
+      end
+    end
+
+    ##
+    # Reads the next queued message without blocking.
+    # @raise [LLM::MCP::Error]
+    #  When the transport is not running
+    # @raise [IO::WaitReadable]
+    #  When no complete message is available to read
+    # @return [Hash]
+    def read_nonblock
+      lock do
+        raise LLM::MCP::Error, "MCP transport is not running" unless running?
+        raise IO::WaitReadable if @queue.empty?
+        @queue.shift
+      end
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true when the MCP server connection is alive
+    def running?
+      @running
+    end
+
+    private
+
+    attr_reader :uri, :use_ssl, :headers, :timeout
+
+    def enqueue(message)
+      lock { @queue << message }
+    end
+
+    def read(res)
+      if res["content-type"].to_s.include?("text/event-stream")
+        parser = LLM::EventStream::Parser.new
+        parser.register EventHandler.new { enqueue(_1) }
+        res.read_body { parser << _1 }
+        parser.free
+      else
+        body = +""
+        res.read_body { body << _1 }
+        enqueue(LLM.json.load(body)) unless body.empty?
+      end
+    end
+
+    def lock(&)
+      @monitor.synchronize(&)
+    end
+  end
+end

data/lib/llm/mcp/transport/stdio.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module LLM::MCP::Transport
+  ##
+  # The {LLM::MCP::Transport::Stdio LLM::MCP::Transport::Stdio} class
+  # provides a stdio transport for {LLM::MCP LLM::MCP}. It sends JSON-RPC
+  # messages to an MCP process over stdin and stdout and delegates process
+  # lifecycle management to {LLM::MCP::Command LLM::MCP::Command}.
+  class Stdio
+    ##
+    # Returns a new Stdio transport instance.
+    # @param command [LLM::MCP::Command]
+    #  The command to run for the MCP process
+    # @return [LLM::MCP::Transport::Stdio]
+    def initialize(command:)
+      @command = command
+    end
+
+    ##
+    # Starts an MCP process over a stdio transport.
+    # This method is non-blocking and returns immediately.
+    # @raise [LLM::Error]
+    #  When the transport is already running
+    # @return [void]
+    def start
+      if command.alive?
+        raise LLM::MCP::Error, "MCP transport is already running"
+      else
+        command.start
+      end
+    end
+
+    ##
+    # Closes the connection to the MCP process.
+    # This method is idempotent and can be called multiple times without error.
+    # @return [void]
+    def stop
+      command.stop
+    end
+
+    ##
+    # Writes a message to the MCP process.
+    # @param [Hash] message
+    #  The message to write
+    # @raise [LLM::Error]
+    #  When the transport is not running
+    # @return [void]
+    def write(message)
+      if command.alive?
+        command.write(LLM.json.dump(message))
+      else
+        raise LLM::MCP::Error, "MCP transport is not running"
+      end
+    end
+
+    ##
+    # Reads a message from the MCP process without blocking.
+    # @raise [LLM::Error]
+    #  When the transport is not running
+    # @raise [IO::WaitReadable]
+    #  When no complete message is available to read
+    # @return [Hash]
+    #  The next message from the MCP process
+    def read_nonblock
+      if command.alive?
+        LLM.json.load(command.read_nonblock)
+      else
+        raise LLM::MCP::Error, "MCP transport is not running"
+      end
+    end
+
+    ##
+    # Waits for the command to exit.
+    # This method is blocking and will return only after the
+    # process has exited.
+    # @return [void]
+    def wait
+      command.wait
+    end
+
+    private
+
+    attr_reader :command, :stdin, :stdout, :stderr
+  end
+end

data/lib/llm/mcp.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::MCP LLM::MCP} class provides access to servers that
+# implement the Model Context Protocol. MCP defines a standard way for
+# clients and servers to exchange capabilities such as tools, prompts,
+# resources, and other structured interactions.
+#
+# In llm.rb, {LLM::MCP LLM::MCP} currently supports stdio and HTTP
+# transports and focuses on discovering tools that can be used through
+# {LLM::Context LLM::Context} and {LLM::Agent LLM::Agent}.
+class LLM::MCP
+  require "monitor"
+  require_relative "mcp/error"
+  require_relative "mcp/command"
+  require_relative "mcp/rpc"
+  require_relative "mcp/pipe"
+  require_relative "mcp/transport/http"
+  require_relative "mcp/transport/stdio"
+
+  include RPC
+
+  ##
+  # @param [LLM::Provider, nil] llm
+  #  The provider to use for MCP transports that need one
+  # @param [Hash, nil] stdio The configuration for the stdio transport
+  # @option stdio [Array<String>] :argv
+  #  The command to run for the MCP process
+  # @option stdio [Hash] :env
+  #  The environment variables to set for the MCP process
+  # @option stdio [String, nil] :cwd
+  #  The working directory for the MCP process
+  # @param [Hash, nil] http The configuration for the HTTP transport
+  # @option http [String] :url
+  #  The URL for the MCP HTTP endpoint
+  # @option http [Hash] :headers
+  #  Extra headers for requests
+  # @param [Integer] timeout The maximum amount of time to wait when reading from an MCP process
+  # @return [LLM::MCP] A new MCP instance
+  def initialize(llm = nil, stdio: nil, http: nil, timeout: 30)
+    @llm = llm
+    @monitor = Monitor.new
+    @timeout = timeout
+    if stdio && http
+      raise ArgumentError, "stdio and http are mutually exclusive"
+    elsif stdio
+      @command = Command.new(**stdio)
+      @transport = Transport::Stdio.new(command:)
+    elsif http
+      @transport = Transport::HTTP.new(**http, timeout:)
+    else
+      raise ArgumentError, "stdio or http is required"
+    end
+  end
+
+  ##
+  # Starts the MCP process.
+  # @return [void]
+  def start
+    lock do
+      transport.start
+      call(transport, "initialize", {clientInfo: {name: "llm.rb", version: LLM::VERSION}})
+      call(transport, "notifications/initialized")
+    end
+  end
+
+  ##
+  # Stops the MCP process.
+  # @return [void]
+  def stop
+    lock do
+      transport.stop
+      nil
+    end
+  end
+
+  ##
+  # Returns the tools provided by the MCP process.
+  # @return [Array<Class<LLM::Tool>>]
+  def tools
+    lock do
+      res = call(transport, "tools/list")
+      res["tools"].map { LLM::Tool.mcp(self, _1) }
+    end
+  end
+
+  ##
+  # Calls a tool by name with the given arguments
+  # @param [String] name The name of the tool to call
+  # @param [Hash] arguments The arguments to pass to the tool
+  # @return [Object] The result of the tool call
+  def call_tool(name, arguments = {})
+    lock do
+      res = call(transport, "tools/call", {name:, arguments:})
+      adapt_tool_result(res)
+    end
+  end
+
+  private
+
+  attr_reader :llm, :command, :transport, :timeout
+
+  def adapt_tool_result(result)
+    if result["structuredContent"]
+      result["structuredContent"]
+    elsif result["content"]
+      {content: result["content"]}
+    else
+      result
+    end
+  end
+
+  def lock(&)
+    @monitor.synchronize(&)
+  end
+end

data/lib/llm/message.rb

@@ -26,7 +26,7 @@ module LLM
     def initialize(role, content, extra = {})
       @role = role.to_s
       @content = content
-      @extra = extra
+      @extra = LLM::Object.from(extra)
     end
 
     ##
@@ -34,8 +34,9 @@ module LLM
     # @return [Hash]
     def to_h
       {role:, content:,
-       tools: @extra[:tool_calls],
-       original_tool_calls: extra[:original_tool_calls]}.compact
+       tools: extra.tool_calls,
+       usage:,
+       original_tool_calls: extra.original_tool_calls}.compact
     end
 
     ##
@@ -69,8 +70,9 @@ module LLM
     ##
     # @return [Array<LLM::Function>]
     def functions
-      @functions ||= tool_calls.map do |fn|
-        function = available_tools.find { _1.name.to_s == fn["name"] }.dup
+      @functions ||= tool_calls.filter_map do |fn|
+        function = available_tools.find { _1.name.to_s == fn["name"] } || next
+        function = function.dup
         function.tap { _1.id = fn.id }
         function.tap { _1.arguments = fn.arguments }
       end
@@ -119,7 +121,7 @@ module LLM
     # @return [LLM::Response, nil]
     #  Returns the response associated with the message, or nil
     def response
-      extra[:response]
+      extra.response
     end
 
     ##
@@ -129,7 +131,7 @@ module LLM
     # Returns annotations associated with the message
     # @return [Array<LLM::Object>]
     def annotations
-      @annotations ||= LLM::Object.from(extra["annotations"] || [])
+      @annotations ||= LLM::Object.from(extra.annotations || [])
     end
 
     ##
@@ -139,8 +141,7 @@ module LLM
     # Returns token usage statistics
     # @return [LLM::Object, nil]
     def usage
-      return nil unless response
-      @usage ||= response.usage
+      @usage ||= extra.usage || response&.usage
     end
     alias_method :token_usage, :usage
 
@@ -163,11 +164,12 @@ module LLM
     private
 
     def tool_calls
-      @tool_calls ||= LLM::Object.from(@extra[:tool_calls] || [])
+      @tool_calls ||= LLM::Object.from(extra.tool_calls || [])
     end
 
     def available_tools
-      response&.__tools__ || []
+      tools = extra.tools || response&.__tools__ || []
+      tools.map { _1.respond_to?(:function) ? _1.function : _1 }
     end
   end
 end

data/lib/llm/model.rb

@@ -34,7 +34,7 @@ class LLM::Model
   # @return [Boolean]
   def chat?
     return true if anthropic?
-    return [*(raw.supportedGenerationMethods || [])].include?("generateContent") if gemini?
+    return [*(raw.supportedGenerationMethods || [])].include?("generateContent") if google?
     openai_compatible_chat?
   end
 
@@ -96,7 +96,7 @@ class LLM::Model
     raw.type == "model" && raw.key?(:display_name) && raw.key?(:created_at)
   end
 
-  def gemini?
+  def google?
     raw.key?(:supportedGenerationMethods)
   end
 

data/lib/llm/prompt.rb

@@ -5,20 +5,20 @@
 # a single request from multiple role-aware messages.
 # A prompt is not just a string. It is an ordered chain of
 # messages with explicit roles (for example `system` and `user`).
-# Use {LLM::Session#prompt} when building a prompt inside a session.
+# Use {LLM::Context#prompt} when building a prompt inside a session.
 # Use `LLM::Prompt.new(provider)` directly when you want to construct
 # or pass prompt objects around explicitly.
 #
 # @example
 #   llm = LLM.openai(key: ENV["KEY"])
-#   ses = LLM::Session.new(llm)
+#   ctx = LLM::Context.new(llm)
 #
-#   prompt = ses.prompt do
+#   prompt = ctx.prompt do
 #     system "Your task is to assist the user"
 #     user "Hello. Can you assist me?"
 #   end
 #
-#   res = ses.talk(prompt)
+#   res = ctx.talk(prompt)
 class LLM::Prompt
   ##
   # @param [LLM::Provider] provider
@@ -57,7 +57,7 @@ class LLM::Prompt
   #  The message content
   # @return [void]
   def user(content)
-    chat(content, role: @provider.user_role)
+    talk(content, role: @provider.user_role)
   end
 
   ##
@@ -65,7 +65,7 @@ class LLM::Prompt
   #  The message content
   # @return [void]
   def system(content)
-    chat(content, role: @provider.system_role)
+    talk(content, role: @provider.system_role)
   end
 
   ##
@@ -73,7 +73,7 @@ class LLM::Prompt
   #  The message content
   # @return [void]
   def developer(content)
-    chat(content, role: @provider.developer_role)
+    talk(content, role: @provider.developer_role)
   end
 
   ##
@@ -82,4 +82,14 @@ class LLM::Prompt
   def to_a
     @buffer.dup
   end
+
+  ##
+  # Returns true when two prompts have the same buffer
+  # @param [LLM::Prompt] other
+  # @return [Boolean]
+  def ==(other)
+    return false unless LLM::Prompt === other
+    @buffer == other.to_a
+  end
+  alias_method :eql?, :==
 end