ruby_llm-mcp 0.5.1 → 0.6.0

data/lib/ruby_llm/mcp/client.rb

@@ -8,6 +8,7 @@ module RubyLLM
       extend Forwardable
 
       attr_reader :name, :config, :transport_type, :request_timeout, :log_level, :on, :roots
+      attr_accessor :linked_resources
 
       def initialize(name:, transport_type:, start: true, request_timeout: MCP.config.request_timeout, config: {})
         @name = name
@@ -26,6 +27,8 @@ module RubyLLM
 
         @log_level = nil
 
+        @linked_resources = []
+
         setup_roots
         setup_sampling
 
@@ -72,7 +75,8 @@ module RubyLLM
 
         fetch(:resources, refresh) do
           resources = @coordinator.resource_list
-          build_map(resources, MCP::Resource)
+          resources = build_map(resources, MCP::Resource)
+          include_linked_resources(resources)
         end
 
         @resources.values
@@ -157,7 +161,10 @@ module RubyLLM
       end
 
       def on_logging(level: Logging::WARNING, &block)
-        @coordinator.set_logging(level: level)
+        @on_logging_level = level
+        if alive?
+          @coordinator.set_logging(level: level)
+        end
 
         @on[:logging] = block
         self
@@ -172,6 +179,37 @@ module RubyLLM
         self
       end
 
+      def elicitation_enabled?
+        @on.key?(:elicitation) && !@on[:elicitation].nil?
+      end
+
+      def on_elicitation(&block)
+        @on[:elicitation] = block
+        self
+      end
+
+      def to_h
+        {
+          name: @name,
+          transport_type: @transport_type,
+          request_timeout: @request_timeout,
+          start: @start,
+          config: @config,
+          on: @on,
+          tools: @tools,
+          resources: @resources,
+          resource_templates: @resource_templates,
+          prompts: @prompts,
+          log_level: @log_level
+        }
+      end
+
+      alias as_json to_h
+
+      def inspect
+        "#<#{self.class.name}:0x#{object_id.to_s(16)} #{to_h.map { |k, v| "#{k}: #{v}" }.join(', ')}>"
+      end
+
       private
 
       def setup_coordinator
@@ -199,6 +237,14 @@ module RubyLLM
         end
       end
 
+      def include_linked_resources(resources)
+        @linked_resources.each do |resource|
+          resources[resource.name] = resource
+        end
+
+        resources
+      end
+
       def setup_roots
         @roots = Roots.new(paths: MCP.config.roots, coordinator: @coordinator)
       end
@@ -206,6 +252,14 @@ module RubyLLM
       def setup_sampling
         @on[:sampling] = MCP.config.sampling.guard
       end
+
+      def setup_event_handlers
+        @on[:progress] = MCP.config.on_progress
+        @on[:human_in_the_loop] = MCP.config.on_human_in_the_loop
+        @on[:logging] = MCP.config.on_logging
+        @on_logging_level = MCP.config.on_logging_level
+        @on[:elicitation] = MCP.config.on_elicitation
+      end
     end
   end
 end

data/lib/ruby_llm/mcp/completion.rb

@@ -3,9 +3,10 @@
 module RubyLLM
   module MCP
     class Completion
-      attr_reader :values, :total, :has_more
+      attr_reader :argument, :values, :total, :has_more
 
-      def initialize(values:, total:, has_more:)
+      def initialize(argument:, values:, total:, has_more:)
+        @argument = argument
         @values = values
         @total = total
         @has_more = has_more

data/lib/ruby_llm/mcp/configuration.rb

@@ -92,8 +92,10 @@ module RubyLLM
                     :sampling,
                     :max_connections,
                     :pool_timeout,
+                    :protocol_version,
                     :config_path,
-                    :launch_control
+                    :launch_control,
+                    :on_logging_level
 
       attr_writer :logger, :mcp_configuration
 
@@ -127,6 +129,26 @@ module RubyLLM
         @mcp_configuration + load_mcps_config
       end
 
+      def on_progress(&block)
+        @on_progress = block if block_given?
+        @on_progress
+      end
+
+      def on_human_in_the_loop(&block)
+        @on_human_in_the_loop = block if block_given?
+        @on_human_in_the_loop
+      end
+
+      def on_logging(&block)
+        @on_logging = block if block_given?
+        @on_logging
+      end
+
+      def on_elicitation(&block)
+        @on_elicitation = block if block_given?
+        @on_elicitation
+      end
+
       def inspect
         redacted = lambda do |name, value|
           if name.match?(/_id|_key|_secret|_token$/)
@@ -180,6 +202,13 @@ module RubyLLM
 
         # Sampling configuration
         @sampling.reset!
+
+        # Event handlers
+        @on_progress = nil
+        @on_human_in_the_loop = nil
+        @on_elicitation = nil
+        @on_logging_level = nil
+        @on_logging = nil
       end
     end
   end

data/lib/ruby_llm/mcp/coordinator.rb

@@ -5,9 +5,6 @@ require "logger"
 module RubyLLM
   module MCP
     class Coordinator
-      PROTOCOL_VERSION = "2025-03-26"
-      PV_2024_11_05 = "2024-11-05"
-
       attr_reader :client, :transport_type, :config, :capabilities, :protocol_version
 
       def initialize(client, transport_type:, config: {})
@@ -15,7 +12,7 @@ module RubyLLM
         @transport_type = transport_type
         @config = config
 
-        @protocol_version = PROTOCOL_VERSION
+        @protocol_version = MCP.config.protocol_version || MCP::Protocol.default_negotiated_version
 
         @transport = nil
         @capabilities = nil
@@ -28,7 +25,7 @@ module RubyLLM
       def request(body, **options)
         transport.request(body, **options)
       rescue RubyLLM::MCP::Errors::TimeoutError => e
-        if transport&.alive?
+        if transport&.alive? && !e.request_id.nil?
           cancelled_notification(reason: "Request timed out", request_id: e.request_id)
         end
         raise e
@@ -62,6 +59,16 @@ module RubyLLM
 
         # Extract and store the negotiated protocol version
         negotiated_version = initialize_response.value["protocolVersion"]
+
+        if negotiated_version && !MCP::Protocol.supported_version?(negotiated_version)
+          raise Errors::UnsupportedProtocolVersion.new(
+            message: <<~MESSAGE
+              Unsupported protocol version, and could not negotiate a supported version: #{negotiated_version}.
+              Supported versions: #{MCP::Protocol.supported_versions.join(', ')}
+            MESSAGE
+          )
+        end
+
         @protocol_version = negotiated_version if negotiated_version
 
         # Set the protocol version on the transport for subsequent requests
@@ -71,13 +78,17 @@ module RubyLLM
 
         @capabilities = RubyLLM::MCP::ServerCapabilities.new(initialize_response.value["capabilities"])
         initialize_notification
+
+        if client.logging_handler_enabled?
+          set_logging(level: client.on_logging_level)
+        end
       end
 
       def stop_transport
         @transport&.close
         @capabilities = nil
         @transport = nil
-        @protocol_version = PROTOCOL_VERSION
+        @protocol_version = MCP::Protocol.default_negotiated_version
       end
 
       def restart_transport
@@ -150,6 +161,11 @@ module RubyLLM
         RubyLLM::MCP::Requests::ToolCall.new(self, **args).call
       end
 
+      def register_resource(resource)
+        @client.linked_resources << resource
+        @client.resources[resource.name] = resource
+      end
+
       def resource_list(cursor: nil)
         result = RubyLLM::MCP::Requests::ResourceList.new(self, cursor: cursor).call
         result.raise_error! if result.error?
@@ -239,6 +255,10 @@ module RubyLLM
         RubyLLM::MCP::Responses::Error.new(self, **args).call
       end
 
+      def elicitation_response(**args)
+        RubyLLM::MCP::Responses::Elicitation.new(self, **args).call
+      end
+
       def client_capabilities
         capabilities = {}
 
@@ -252,6 +272,10 @@ module RubyLLM
           capabilities[:sampling] = {}
         end
 
+        if client.elicitation_enabled?
+          capabilities[:elicitation] = {}
+        end
+
         capabilities
       end
 

data/lib/ruby_llm/mcp/elicitation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json-schema"
+
+module RubyLLM
+  module MCP
+    class Elicitation
+      ACCEPT_ACTION = "accept"
+      CANCEL_ACTION = "cancel"
+      REJECT_ACTION = "reject"
+
+      attr_writer :structured_response
+
+      def initialize(coordinator, result)
+        @coordinator = coordinator
+        @result = result
+        @id = result.id
+
+        @message = @result.params["message"]
+        @requested_schema = @result.params["requestedSchema"]
+      end
+
+      def execute
+        success = @coordinator.client.on[:elicitation].call(self)
+        if success
+          valid = validate_response
+          if valid
+            @coordinator.elicitation_response(id: @id, action: ACCEPT_ACTION, content: @structured_response)
+          else
+            @coordinator.elicitation_response(id: @id, action: CANCEL_ACTION, content: nil)
+          end
+        else
+          @coordinator.elicitation_response(id: @id, action: REJECT_ACTION, content: nil)
+        end
+      end
+
+      def message
+        @result.params["message"]
+      end
+
+      def validate_response
+        JSON::Validator.validate(@requested_schema, @structured_response)
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/errors.rb

@@ -58,6 +58,8 @@ module RubyLLM
       end
 
       class UnknownRequest < BaseError; end
+
+      class UnsupportedProtocolVersion < BaseError; end
     end
   end
 end

data/lib/ruby_llm/mcp/prompt.rb

@@ -50,16 +50,17 @@ module RubyLLM
 
       alias say ask
 
-      def complete(argument, value)
+      def complete(argument, value, context: nil)
         if @coordinator.capabilities.completion?
-          result = @coordinator.completion_prompt(name: @name, argument: argument, value: value)
+          result = @coordinator.completion_prompt(name: @name, argument: argument, value: value, context: context)
           if result.error?
             return result.to_error
           end
 
           response = result.value["completion"]
 
-          Completion.new(values: response["values"], total: response["total"], has_more: response["hasMore"])
+          Completion.new(argument: argument, values: response["values"], total: response["total"],
+                         has_more: response["hasMore"])
         else
           message = "Completion is not available for this MCP server"
           raise Errors::Capabilities::CompletionNotAvailable.new(message: message)

data/lib/ruby_llm/mcp/protocol.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Protocol
+      module_function
+
+      LATEST_PROTOCOL_VERSION = "2025-06-18"
+      DEFAULT_NEGOTIATED_PROTOCOL_VERSION = "2025-03-26"
+      SUPPORTED_PROTOCOL_VERSIONS = [
+        LATEST_PROTOCOL_VERSION,
+        "2025-03-26",
+        "2024-11-05",
+        "2024-10-07"
+      ].freeze
+
+      def supported_version?(version)
+        SUPPORTED_PROTOCOL_VERSIONS.include?(version)
+      end
+
+      def supported_versions
+        SUPPORTED_PROTOCOL_VERSIONS
+      end
+
+      def latest_version
+        LATEST_PROTOCOL_VERSION
+      end
+
+      def default_negotiated_version
+        DEFAULT_NEGOTIATED_PROTOCOL_VERSION
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/requests/completion_prompt.rb

@@ -4,11 +4,12 @@ module RubyLLM
   module MCP
     module Requests
       class CompletionPrompt
-        def initialize(coordinator, name:, argument:, value:)
+        def initialize(coordinator, name:, argument:, value:, context: nil)
           @coordinator = coordinator
           @name = name
           @argument = argument
           @value = value
+          @context = context
         end
 
         def call
@@ -30,8 +31,17 @@ module RubyLLM
               argument: {
                 name: @argument,
                 value: @value
-              }
-            }
+              },
+              context: format_context
+            }.compact
+          }
+        end
+
+        def format_context
+          return nil if @context.nil?
+
+          {
+            arguments: @context
           }
         end
       end

data/lib/ruby_llm/mcp/requests/completion_resource.rb

@@ -4,11 +4,12 @@ module RubyLLM
   module MCP
     module Requests
       class CompletionResource
-        def initialize(coordinator, uri:, argument:, value:)
+        def initialize(coordinator, uri:, argument:, value:, context: nil)
           @coordinator = coordinator
           @uri = uri
           @argument = argument
           @value = value
+          @context = context
         end
 
         def call
@@ -30,8 +31,17 @@ module RubyLLM
               argument: {
                 name: @argument,
                 value: @value
-              }
-            }
+              },
+              context: format_context
+            }.compact
+          }
+        end
+
+        def format_context
+          return nil if @context.nil?
+
+          {
+            arguments: @context
           }
         end
       end

data/lib/ruby_llm/mcp/resource.rb

@@ -61,7 +61,6 @@ module RubyLLM
 
       def to_content
         content = self.content
-
         case content_type
         when "text"
           MCP::Content.new(text: "#{name}: #{description}\n\n#{content}")
@@ -89,7 +88,7 @@ module RubyLLM
       def content_type
         return "text" if @content_response.nil?
 
-        if @content_response.key?("blob")
+        if @content_response.key?("blob") && !@content_response["blob"].nil?
           "blob"
         else
           "text"

data/lib/ruby_llm/mcp/resource_template.rb

@@ -33,14 +33,15 @@ module RubyLLM
         fetch_resource(arguments: arguments).to_content
       end
 
-      def complete(argument, value)
+      def complete(argument, value, context: nil)
         if @coordinator.capabilities.completion?
-          result = @coordinator.completion_resource(uri: @uri, argument: argument, value: value)
+          result = @coordinator.completion_resource(uri: @uri, argument: argument, value: value, context: context)
           result.raise_error! if result.error?
 
           response = result.value["completion"]
 
-          Completion.new(values: response["values"], total: response["total"], has_more: response["hasMore"])
+          Completion.new(argument: argument, values: response["values"], total: response["total"],
+                         has_more: response["hasMore"])
         else
           message = "Completion is not available for this MCP server"
           raise Errors::Capabilities::CompletionNotAvailable.new(message: message)

data/lib/ruby_llm/mcp/response_handler.rb

@@ -20,6 +20,9 @@ module RubyLLM
         elsif result.sampling?
           handle_sampling_response(result)
           true
+        elsif result.elicitation?
+          handle_elicitation_response(result)
+          true
         else
           handle_unknown_request(result)
           RubyLLM::MCP.logger.error("MCP client was sent unknown method type and could not respond: #{result.inspect}")
@@ -30,6 +33,7 @@ module RubyLLM
       private
 
       def handle_roots_response(result)
+        RubyLLM::MCP.logger.info("Roots request: #{result.inspect}")
         if client.roots.active?
           coordinator.roots_list_response(id: result.id, roots: client.roots)
         else
@@ -44,10 +48,15 @@ module RubyLLM
           return
         end
 
-        RubyLLM::MCP.logger.info("Sampling response: #{result.inspect}")
+        RubyLLM::MCP.logger.info("Sampling request: #{result.inspect}")
         Sample.new(result, coordinator).execute
       end
 
+      def handle_elicitation_response(result)
+        RubyLLM::MCP.logger.info("Elicitation request: #{result.inspect}")
+        Elicitation.new(coordinator, result).execute
+      end
+
       def handle_unknown_request(result)
         coordinator.error_response(id: result.id,
                                    message: "Unknown method and could not respond: #{result.method}",

data/lib/ruby_llm/mcp/responses/elicitation.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Responses
+      class Elicitation
+        def initialize(coordinator, id:, action:, content:)
+          @coordinator = coordinator
+          @id = id
+          @action = action
+          @content = content
+        end
+
+        def call
+          @coordinator.request(elicitation_response_body, add_id: false, wait_for_response: false)
+        end
+
+        private
+
+        def elicitation_response_body
+          {
+            jsonrpc: "2.0",
+            id: @id,
+            result: {
+              action: @action,
+              content: @content
+            }.compact
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/result.rb

@@ -17,7 +17,8 @@ module RubyLLM
       REQUEST_METHODS = {
         ping: "ping",
         roots: "roots/list",
-        sampling: "sampling/createMessage"
+        sampling: "sampling/createMessage",
+        elicitation: "elicitation/create"
       }.freeze
 
       def initialize(response, session_id: nil)

data/lib/ruby_llm/mcp/tool.rb

@@ -36,6 +36,10 @@ module RubyLLM
         @mcp_name = tool_response["name"]
         @description = tool_response["description"].to_s
         @parameters = create_parameters(tool_response["inputSchema"])
+
+        @input_schema = tool_response["inputSchema"]
+        @output_schema = tool_response["outputSchema"]
+
         @annotations = tool_response["annotations"] ? Annotation.new(tool_response["annotations"]) : nil
       end
 
@@ -59,6 +63,15 @@ module RubyLLM
           return { error: "Tool execution error: #{text_values}" }
         end
 
+        if result.value.key?("structuredContent") && !@output_schema.nil?
+          is_valid = JSON::Validator.validate(@output_schema, result.value["structuredContent"])
+          unless is_valid
+            return { error: "Structued outputs was not invalid: #{result.value['structuredContent']}" }
+          end
+
+          return text_values
+        end
+
         if text_values.empty?
           create_content_for_message(result.value.dig("content", 0))
         else
@@ -79,12 +92,12 @@ module RubyLLM
 
       private
 
-      def create_parameters(input_schema)
+      def create_parameters(schema)
         params = {}
-        return params if input_schema["properties"].nil?
+        return params if schema["properties"].nil?
 
-        input_schema["properties"].each_key do |key|
-          param_data = input_schema.dig("properties", key)
+        schema["properties"].each_key do |key|
+          param_data = schema.dig("properties", key)
 
           param = if param_data.key?("oneOf") || param_data.key?("anyOf") || param_data.key?("allOf")
                     process_union_parameter(key, param_data)
@@ -152,10 +165,25 @@ module RubyLLM
             "name" => name,
             "description" => description,
             "uri" => content.dig("resource", "uri"),
-            "content" => content["resource"]
+            "mimeType" => content.dig("resource", "mimeType"),
+            "content_response" => {
+              "text" => content.dig("resource", "text"),
+              "blob" => content.dig("resource", "blob")
+            }
+          }
+
+          resource = Resource.new(coordinator, resource_data)
+          resource.to_content
+        when "resource_link"
+          resource_data = {
+            "name" => content["name"],
+            "uri" => content["uri"],
+            "description" => content["description"],
+            "mimeType" => content["mimeType"]
           }
 
           resource = Resource.new(coordinator, resource_data)
+          @coordinator.register_resource(resource)
           resource.to_content
         end
       end