ruby_llm-mcp 0.5.0 → 0.6.0

data/lib/generators/ruby_llm/mcp/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RubyLlm
+  module Mcp
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Install RubyLLM MCP configuration files"
+
+        def create_initializer
+          template "initializer.rb", "config/initializers/ruby_llm_mcp.rb"
+        end
+
+        def create_config_file
+          template "mcps.yml", "config/mcps.yml"
+        end
+
+        def display_readme
+          readme "README.txt" if behavior == :invoke
+        end
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/mcp/templates/README.txt

@@ -0,0 +1,32 @@
+RubyLLM MCP has been successfully installed!
+
+The following files have been created:
+
+  config/initializers/ruby_llm_mcp.rb - Main configuration file
+  config/mcps.json                    - MCP servers configuration
+
+Next steps:
+
+1. Edit config/initializers/ruby_llm_mcp.rb to configure your MCP settings
+2. Edit config/mcps.json to define your MCP servers
+3. Install any MCP servers you want to use (e.g., npm install @modelcontextprotocol/server-filesystem) or use remote MCPs
+4. Update environment variables for any MCP servers that require authentication
+
+Example usage in your Rails application:
+
+  # With Ruby::MCP installed in a controller or service
+  clients = RubyLLM::MCP.clients
+
+  # Get all tools use the configured client
+  tools = RubyLLM::MCP.tools
+
+  # Or use the configured client
+  client = RubyLLM::MCP.clients["file-system"]
+
+  # Or use the configured client
+  tools = client.tools
+
+
+For more information, visit: https://github.com/patvice/ruby_llm-mcp
+
+===============================================================================

data/lib/generators/ruby_llm/mcp/templates/initializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Configure RubyLLM MCP
+RubyLLM::MCP.configure do |config|
+  # Request timeout in milliseconds
+  config.request_timeout = 8000
+
+  # Maximum connections in the pool
+  config.max_connections = Float::INFINITY
+
+  # Pool timeout in seconds
+  config.pool_timeout = 5
+
+  # Enable complex parameter support for various providers
+  config.support_complex_parameters!
+
+  # Path to MCPs configuration file
+  config.config_path = Rails.root.join("config", "mcps.yml")
+
+  # Launch MCPs (:automatic, :manual)
+  config.launch_control = :automatic
+
+  # Configure roots for file system access
+  # config.roots = [
+  #   Rails.root.to_s
+  # ]
+
+  # Configure sampling (optional)
+  config.sampling.enabled = false
+
+  # Set preferred model for sampling
+  # config.sampling.preferred_model do
+  #   # Return the preferred model name
+  #   "claude-3-5-sonnet-20240620"
+  # end
+
+  # Set a guard for sampling
+  # config.sampling.guard do
+  #   # Return true to enable sampling, false to disable
+  #   Rails.env.development?
+  # end
+end

data/lib/generators/ruby_llm/mcp/templates/mcps.yml

@@ -0,0 +1,9 @@
+mcp_servers:
+  filesystem:
+    transport_type: stdio
+    command: npx
+    args:
+      - "@modelcontextprotocol/server-filesystem"
+      - "<%%= Rails.root %>"
+    env: {}
+    with_prefix: true

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)