ruby_llm-mcp 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53435b09aee8d32aaede3da3463b8fb782a6d00f6abcabc3b9925f1301cd60c9
-  data.tar.gz: 366cf4d89bef7f79904cd897a7db006ee21a8766c8ff1675e51225576e8c87f4
+  metadata.gz: 2dd0be50f01aa4fd126828c9c4f81d2e5a7b3cb35f4b32a4ed8e3e4deb731202
+  data.tar.gz: d6efbfbb3345544da2e201968ff26ff1e238a72efc95e7eb5cc2cb77adaaaf94
 SHA512:
-  metadata.gz: 94754a9b6d8799252bebfb19ccc3dedfc6767fdbe07468960ed3eb56978954d734425f79b366fb92610f4c059970a0607c249b3c6c35bca943fbab7e5a721e77
-  data.tar.gz: d0e757cdc7d064ffc4334b0b1c2a1ebc1feff3dc684d35d28f0b51ce5761a3c80ad427654767fae97da8c8ddacbc182d3d896ef4dedc45ce4d6d8e6297b81fe3
+  metadata.gz: 769aa222a4f5afd5dc124f1fa1bb62771fd2d2dd5d60211fa3f86e664aa030811600f7ee448ec7607a7d244d2d6f961a9ded088f3db7eaa611fff8041528b6c1
+  data.tar.gz: d3a494430dcce6c0ee9246f6378d682771458c0009779c3e7f34aba43309b2ba6b72722ddbbc9e8d2b84061358cc8375f5fedd19c76a187795fce5adfd49338b

data/README.md

@@ -103,13 +103,39 @@ response = chat.ask("Can you help me search for recent files in my project?")
 puts response
 ```
 
+### Human in the Loop
+
+You can use the `on_human_in_the_loop` callback to allow the human to intervene in the tool call. This is useful for tools that require human input or programic input to verify if the tool should be executed.
+
+For tool calls that have access to do important operations, there SHOULD always be a human in the loop with the ability to deny tool invocations.
+
+```ruby
+client.on_human_in_the_loop do |name, params|
+  name == "add" && params[:a] == 1 && params[:b] == 2
+end
+
+tool = client.tool("add")
+result = tool.execute(a: 1, b: 2)
+puts result # 3
+
+# If the human in the loop returns false, the tool call will be cancelled
+result = tool.execute(a: 2, b: 2)
+puts result # Tool execution error: Tool call was cancelled by the client
+```
+
+tool = client.tool("add")
+result = tool.execute(a: 1, b: 2)
+puts result
+
+````
+
 ### Support Complex Parameters
 
 If you want to support complex parameters, like an array of objects it currently requires a patch to RubyLLM itself. This is planned to be temporary until the RubyLLM is updated.
 
 ```ruby
 RubyLLM::MCP.support_complex_parameters!
-```
+````
 
 ### Streaming Responses with Tool Calls
 
@@ -341,6 +367,14 @@ client.restart!
 client.stop
 ```
 
+### Ping
+
+You can ping the MCP server to check if it is alive:
+
+```ruby
+client.ping # => true or false
+```
+
 ## Refreshing Cached Data
 
 The client caches tools, resources, prompts, and resource templates list calls are cached to reduce round trips back to the MCP server. You can refresh this cache:
@@ -363,6 +397,71 @@ prompt = client.prompt("daily_greeting", refresh: true)
 template = client.resource_template("user_logs", refresh: true)
 ```
 
+## Notifications
+
+MCPs can produce notifications that happen in an async nature outside normal calls to the MCP server.
+
+### Subscribing to a Resource Update
+
+By default, the client will look for any resource cha to resource updates and refresh the resource content when it changes.
+
+### Logging Notifications
+
+MCPs can produce logging notifications for long-running tool operations. Logging notifications allow tools to send real-time updates about their execution status.
+
+```ruby
+client.on_logging do |logging|
+  puts "Logging: #{logging.level} - #{logging.message}"
+end
+
+# Execute a tool that supports logging notifications
+tool = client.tool("long_running_operation")
+result = tool.execute(operation: "data_processing")
+
+# Logging: info - Processing data...
+# Logging: info - Processing data...
+# Logging: warning - Something went wrong but not major...
+```
+
+Different levels of logging are supported:
+
+```ruby
+client.on_logging(RubyLLM::MCP::Logging::WARNING) do |logging|
+  puts "Logging: #{logging.level} - #{logging.message}"
+end
+
+# Execute a tool that supports logging notifications
+tool = client.tool("long_running_operation")
+result = tool.execute(operation: "data_processing")
+
+# Logging: warning - Something went wrong but not major...
+```
+
+### Progress Notifications
+
+MCPs can produce progress notifications for long-running tool operations. Progress notifications allow tools to send real-time updates about their execution status.
+
+**Note:** that we only support progress notifications for tool calls today.
+
+```ruby
+# Set up progress tracking
+client.on_progress do |progress|
+  puts "Progress: #{progress.progress}% - #{progress.message}"
+end
+
+# Execute a tool that supports progress notifications
+tool = client.tool("long_running_operation")
+result = tool.execute(operation: "data_processing")
+
+# Progress 25% - Processing data...
+# Progress 50% - Processing data...
+# Progress 75% - Processing data...
+# Progress 100% - Processing data...
+puts result
+
+# Result: { status: "success", data: "Processed data" }
+```
+
 ## Transport Types
 
 ### SSE (Server-Sent Events)
@@ -411,7 +510,27 @@ client = RubyLLM::MCP.client(
 )
 ```
 
-## Configuration Options
+## RubyLLM::MCP and Client Configuration Options
+
+MCP comes with some common configuration options that can be set on the client.
+
+```ruby
+RubyLLM::MCP.configure do |config|
+  # Set the progress handler
+  config.support_complex_parameters!
+
+  # Set parameters on the built in logger
+  config.log_file = $stdout
+  config.log_level = Logger::ERROR
+
+  # Or add a custom logger
+  config.logger = Logger.new(STDOUT)
+end
+```
+
+### MCP Client Options
+
+MCP client options are set on the client itself.
 
 - `name`: A unique identifier for your MCP client
 - `transport_type`: Either `:sse`, `:streamable`, or `:stdio`

data/lib/ruby_llm/mcp/capabilities.rb

@@ -9,7 +9,11 @@ module RubyLLM
         @capabilities = capabilities
       end
 
-      def resources_list_changed?
+      def resources_list?
+        !@capabilities["resources"].nil?
+      end
+
+      def resources_list_changes?
         @capabilities.dig("resources", "listChanged") || false
       end
 
@@ -17,13 +21,29 @@ module RubyLLM
         @capabilities.dig("resources", "subscribe") || false
       end
 
-      def tools_list_changed?
+      def tools_list?
+        !@capabilities["tools"].nil?
+      end
+
+      def tools_list_changes?
         @capabilities.dig("tools", "listChanged") || false
       end
 
+      def prompt_list?
+        !@capabilities["prompts"].nil?
+      end
+
+      def prompt_list_changes?
+        @capabilities.dig("prompts", "listChanged") || false
+      end
+
       def completion?
         !@capabilities["completions"].nil?
       end
+
+      def logging?
+        !@capabilities["logging"].nil?
+      end
     end
   end
 end

data/lib/ruby_llm/mcp/client.rb

@@ -7,29 +7,47 @@ module RubyLLM
     class Client
       extend Forwardable
 
-      attr_reader :name, :config, :transport_type, :request_timeout
+      attr_reader :name, :config, :transport_type, :request_timeout, :log_level, :on
 
-      def initialize(name:, transport_type:, start: true, request_timeout: 8000, config: {})
+      def initialize(name:, transport_type:, start: true, request_timeout: MCP.config.request_timeout, config: {})
         @name = name
         @config = config.merge(request_timeout: request_timeout)
         @transport_type = transport_type.to_sym
         @request_timeout = request_timeout
 
-        @coordinator = Coordinator.new(self, transport_type: @transport_type, config: @config)
+        @coordinator = setup_coordinator
 
-        start_transport if start
+        @on = {}
+        @tools = {}
+        @resources = {}
+        @resource_templates = {}
+        @prompts = {}
+
+        @log_level = nil
+
+        @coordinator.start_transport if start
       end
 
-      def_delegators :@coordinator, :start_transport, :stop_transport, :restart_transport, :alive?, :capabilities
+      def_delegators :@coordinator, :alive?, :capabilities, :ping
 
-      alias start start_transport
-      alias stop stop_transport
-      alias restart! restart_transport
+      def start
+        @coordinator.start_transport
+      end
+
+      def stop
+        @coordinator.stop_transport
+      end
+
+      def restart!
+        @coordinator.restart_transport
+      end
 
       def tools(refresh: false)
+        return [] unless capabilities.tools_list?
+
         fetch(:tools, refresh) do
-          tools_data = @coordinator.tool_list.dig("result", "tools")
-          build_map(tools_data, MCP::Tool)
+          tools = @coordinator.tool_list
+          build_map(tools, MCP::Tool)
         end
 
         @tools.values
@@ -41,10 +59,16 @@ module RubyLLM
         @tools[name]
       end
 
+      def reset_tools!
+        @tools = {}
+      end
+
       def resources(refresh: false)
+        return [] unless capabilities.resources_list?
+
         fetch(:resources, refresh) do
-          resources_data = @coordinator.resource_list.dig("result", "resources")
-          build_map(resources_data, MCP::Resource)
+          resources = @coordinator.resource_list
+          build_map(resources, MCP::Resource)
         end
 
         @resources.values
@@ -56,10 +80,16 @@ module RubyLLM
         @resources[name]
       end
 
+      def reset_resources!
+        @resources = {}
+      end
+
       def resource_templates(refresh: false)
+        return [] unless capabilities.resources_list?
+
         fetch(:resource_templates, refresh) do
-          templates_data = @coordinator.resource_template_list.dig("result", "resourceTemplates")
-          build_map(templates_data, MCP::ResourceTemplate)
+          resource_templates = @coordinator.resource_template_list
+          build_map(resource_templates, MCP::ResourceTemplate)
         end
 
         @resource_templates.values
@@ -71,10 +101,16 @@ module RubyLLM
         @resource_templates[name]
       end
 
+      def reset_resource_templates!
+        @resource_templates = {}
+      end
+
       def prompts(refresh: false)
+        return [] unless capabilities.prompt_list?
+
         fetch(:prompts, refresh) do
-          prompts_data = @coordinator.prompt_list.dig("result", "prompts")
-          build_map(prompts_data, MCP::Prompt)
+          prompts = @coordinator.prompt_list
+          build_map(prompts, MCP::Prompt)
         end
 
         @prompts.values
@@ -86,11 +122,63 @@ module RubyLLM
         @prompts[name]
       end
 
+      def reset_prompts!
+        @prompts = {}
+      end
+
+      def tracking_progress?
+        @on.key?(:progress) && !@on[:progress].nil?
+      end
+
+      def on_progress(&block)
+        @on[:progress] = block
+        self
+      end
+
+      def human_in_the_loop?
+        @on.key?(:human_in_the_loop) && !@on[:human_in_the_loop].nil?
+      end
+
+      def on_human_in_the_loop(&block)
+        @on[:human_in_the_loop] = block
+        self
+      end
+
+      def logging_handler_enabled?
+        @on.key?(:logging) && !@on[:logging].nil?
+      end
+
+      def logging_enabled?
+        !@log_level.nil?
+      end
+
+      def on_logging(level: Logging::WARNING, logger: nil, &block)
+        @coordinator.set_logging(level: level)
+
+        @on[:logging] = if block_given?
+                          block
+                        else
+                          lambda do |notification|
+                            @coordinator.default_process_logging_message(notification, logger: logger)
+                          end
+                        end
+        self
+      end
+
       private
 
+      def setup_coordinator
+        Coordinator.new(self,
+                        transport_type: @transport_type,
+                        config: @config)
+      end
+
       def fetch(cache_key, refresh)
-        instance_variable_set("@#{cache_key}", nil) if refresh
-        instance_variable_get("@#{cache_key}") || instance_variable_set("@#{cache_key}", yield)
+        instance_variable_set("@#{cache_key}", {}) if refresh
+        if instance_variable_get("@#{cache_key}").empty?
+          instance_variable_set("@#{cache_key}", yield)
+        end
+        instance_variable_get("@#{cache_key}")
       end
 
       def build_map(raw_data, klass)

data/lib/ruby_llm/mcp/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    class Configuration
+      attr_accessor :request_timeout, :log_file, :log_level, :has_support_complex_parameters
+      attr_writer :logger
+
+      REQUEST_TIMEOUT_DEFAULT = 8000
+
+      def initialize
+        set_defaults
+      end
+
+      def reset!
+        set_defaults
+      end
+
+      def support_complex_parameters!
+        return if @has_support_complex_parameters
+
+        @has_support_complex_parameters = true
+        RubyLLM::MCP.support_complex_parameters!
+      end
+
+      def logger
+        @logger ||= Logger.new(
+          log_file,
+          progname: "RubyLLM::MCP",
+          level: log_level
+        )
+      end
+
+      def inspect
+        redacted = lambda do |name, value|
+          if name.match?(/_id|_key|_secret|_token$/)
+            value.nil? ? "nil" : "[FILTERED]"
+          else
+            value
+          end
+        end
+
+        inspection = instance_variables.map do |ivar|
+          name = ivar.to_s.delete_prefix("@")
+          value = redacted[name, instance_variable_get(ivar)]
+          "#{name}: #{value}"
+        end.join(", ")
+
+        "#<#{self.class}:0x#{object_id.to_s(16)} #{inspection}>"
+      end
+
+      private
+
+      def set_defaults
+        # Connection configuration
+        @request_timeout = REQUEST_TIMEOUT_DEFAULT
+
+        # Logging configuration
+        @log_file = $stdout
+        @log_level = ENV["RUBYLLM_MCP_DEBUG"] ? Logger::DEBUG : Logger::INFO
+        @has_support_complex_parameters = false
+        @logger = nil
+      end
+    end
+  end
+end