ruby_llm-mcp 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c414a0306ebefcb35dcb599406a0092e554e1389aebfa812597e7072e304cf88
-  data.tar.gz: 25b384446ad37b3422bf64e1f9b15413bd8cd64636dbf50ad8ae861e4dc4589d
+  metadata.gz: 2dd0be50f01aa4fd126828c9c4f81d2e5a7b3cb35f4b32a4ed8e3e4deb731202
+  data.tar.gz: d6efbfbb3345544da2e201968ff26ff1e238a72efc95e7eb5cc2cb77adaaaf94
 SHA512:
-  metadata.gz: abbca445c4ecb2ee7a3f2af4457f47aff5337ac981426746184cb0cb63e699b606116d5db983d8d4183557896675743a14bada2af4dd3d54d85066183fe34653
-  data.tar.gz: d8007f3ee983eb3a8e2e76ad2b0daa8ead92bc6347e3352d8d569fab770056026a29237a76182c137459663b54cb4b364df93fb7e968a2d783d1c96fe98f4774
+  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

@@ -1,223 +1,191 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module RubyLLM
   module MCP
     class Client
-      PROTOCOL_VERSION = "2025-03-26"
-      PV_2024_11_05 = "2024-11-05"
+      extend Forwardable
 
-      attr_reader :name, :config, :transport_type, :transport, :request_timeout, :reverse_proxy_url, :protocol_version,
-                  :capabilities
+      attr_reader :name, :config, :transport_type, :request_timeout, :log_level, :on
 
-      def initialize(name:, transport_type:, start: true, request_timeout: 8000, reverse_proxy_url: nil, config: {}) # rubocop:disable Metrics/ParameterLists
+      def initialize(name:, transport_type:, start: true, request_timeout: MCP.config.request_timeout, config: {})
         @name = name
-        @config = config
-        @protocol_version = PROTOCOL_VERSION
-        @headers = config[:headers] || {}
-
+        @config = config.merge(request_timeout: request_timeout)
         @transport_type = transport_type.to_sym
-        @transport = nil
+        @request_timeout = request_timeout
 
-        @capabilities = nil
+        @coordinator = setup_coordinator
 
-        @request_timeout = request_timeout
-        @reverse_proxy_url = reverse_proxy_url
+        @on = {}
+        @tools = {}
+        @resources = {}
+        @resource_templates = {}
+        @prompts = {}
 
-        if start
-          self.start
-        end
-      end
+        @log_level = nil
 
-      def request(body, **options)
-        @transport.request(body, **options)
+        @coordinator.start_transport if start
       end
 
-      def start
-        case @transport_type
-        when :sse
-          @transport = RubyLLM::MCP::Transport::SSE.new(@config[:url], request_timeout: @request_timeout,
-                                                                       headers: @headers)
-        when :stdio
-          @transport = RubyLLM::MCP::Transport::Stdio.new(@config[:command], request_timeout: @request_timeout,
-                                                                             args: @config[:args], env: @config[:env])
-        when :streamable
-          @transport = RubyLLM::MCP::Transport::Streamable.new(@config[:url], request_timeout: @request_timeout,
-                                                                              headers: @headers)
-        else
-          raise "Invalid transport type: #{transport_type}"
-        end
+      def_delegators :@coordinator, :alive?, :capabilities, :ping
 
-        @initialize_response = initialize_request
-        @capabilities = RubyLLM::MCP::Capabilities.new(@initialize_response["result"]["capabilities"])
-        notification_request
+      def start
+        @coordinator.start_transport
       end
 
       def stop
-        @transport&.close
-        @transport = nil
+        @coordinator.stop_transport
       end
 
       def restart!
-        stop
-        start
-      end
-
-      def alive?
-        !!@transport&.alive?
+        @coordinator.restart_transport
       end
 
       def tools(refresh: false)
-        @tools = nil if refresh
-        @tools ||= fetch_and_create_tools
+        return [] unless capabilities.tools_list?
+
+        fetch(:tools, refresh) do
+          tools = @coordinator.tool_list
+          build_map(tools, MCP::Tool)
+        end
+
         @tools.values
       end
 
       def tool(name, refresh: false)
-        @tools = nil if refresh
-        @tools ||= fetch_and_create_tools
+        tools(refresh: refresh)
 
         @tools[name]
       end
 
+      def reset_tools!
+        @tools = {}
+      end
+
       def resources(refresh: false)
-        @resources = nil if refresh
-        @resources ||= fetch_and_create_resources
+        return [] unless capabilities.resources_list?
+
+        fetch(:resources, refresh) do
+          resources = @coordinator.resource_list
+          build_map(resources, MCP::Resource)
+        end
+
         @resources.values
       end
 
       def resource(name, refresh: false)
-        @resources = nil if refresh
-        @resources ||= fetch_and_create_resources
+        resources(refresh: refresh)
 
         @resources[name]
       end
 
+      def reset_resources!
+        @resources = {}
+      end
+
       def resource_templates(refresh: false)
-        @resource_templates = nil if refresh
-        @resource_templates ||= fetch_and_create_resource_templates
+        return [] unless capabilities.resources_list?
+
+        fetch(:resource_templates, refresh) do
+          resource_templates = @coordinator.resource_template_list
+          build_map(resource_templates, MCP::ResourceTemplate)
+        end
+
         @resource_templates.values
       end
 
       def resource_template(name, refresh: false)
-        @resource_templates = nil if refresh
-        @resource_templates ||= fetch_and_create_resource_templates
+        resource_templates(refresh: refresh)
 
         @resource_templates[name]
       end
 
-      def prompts(refresh: false)
-        @prompts = nil if refresh
-        @prompts ||= fetch_and_create_prompts
-        @prompts.values
+      def reset_resource_templates!
+        @resource_templates = {}
       end
 
-      def prompt(name, refresh: false)
-        @prompts = nil if refresh
-        @prompts ||= fetch_and_create_prompts
-
-        @prompts[name]
-      end
+      def prompts(refresh: false)
+        return [] unless capabilities.prompt_list?
 
-      def execute_tool(**args)
-        RubyLLM::MCP::Requests::ToolCall.new(self, **args).call
-      end
+        fetch(:prompts, refresh) do
+          prompts = @coordinator.prompt_list
+          build_map(prompts, MCP::Prompt)
+        end
 
-      def resource_read_request(**args)
-        RubyLLM::MCP::Requests::ResourceRead.new(self, **args).call
+        @prompts.values
       end
 
-      def completion_resource(**args)
-        RubyLLM::MCP::Requests::CompletionResource.new(self, **args).call
-      end
+      def prompt(name, refresh: false)
+        prompts(refresh: refresh)
 
-      def completion_prompt(**args)
-        RubyLLM::MCP::Requests::CompletionPrompt.new(self, **args).call
+        @prompts[name]
       end
 
-      def execute_prompt(**args)
-        RubyLLM::MCP::Requests::PromptCall.new(self, **args).call
+      def reset_prompts!
+        @prompts = {}
       end
 
-      private
-
-      def initialize_request
-        RubyLLM::MCP::Requests::Initialization.new(self).call
+      def tracking_progress?
+        @on.key?(:progress) && !@on[:progress].nil?
       end
 
-      def notification_request
-        RubyLLM::MCP::Requests::Notification.new(self).call
+      def on_progress(&block)
+        @on[:progress] = block
+        self
       end
 
-      def tool_list_request
-        RubyLLM::MCP::Requests::ToolList.new(self).call
+      def human_in_the_loop?
+        @on.key?(:human_in_the_loop) && !@on[:human_in_the_loop].nil?
       end
 
-      def resources_list_request
-        RubyLLM::MCP::Requests::ResourceList.new(self).call
+      def on_human_in_the_loop(&block)
+        @on[:human_in_the_loop] = block
+        self
       end
 
-      def resource_template_list_request
-        RubyLLM::MCP::Requests::ResourceTemplateList.new(self).call
+      def logging_handler_enabled?
+        @on.key?(:logging) && !@on[:logging].nil?
       end
 
-      def prompt_list_request
-        RubyLLM::MCP::Requests::PromptList.new(self).call
+      def logging_enabled?
+        !@log_level.nil?
       end
 
-      def fetch_and_create_tools
-        tools_response = tool_list_request
-        tools_response = tools_response["result"]["tools"]
-
-        tools = {}
-        tools_response.each do |tool|
-          new_tool = RubyLLM::MCP::Tool.new(self, tool)
-          tools[new_tool.name] = new_tool
-        end
+      def on_logging(level: Logging::WARNING, logger: nil, &block)
+        @coordinator.set_logging(level: level)
 
-        tools
+        @on[:logging] = if block_given?
+                          block
+                        else
+                          lambda do |notification|
+                            @coordinator.default_process_logging_message(notification, logger: logger)
+                          end
+                        end
+        self
       end
 
-      def fetch_and_create_resources
-        resources_response = resources_list_request
-        resources_response = resources_response["result"]["resources"]
-
-        resources = {}
-        resources_response.each do |resource|
-          new_resource = RubyLLM::MCP::Resource.new(self, resource)
-          resources[new_resource.name] = new_resource
-        end
+      private
 
-        resources
+      def setup_coordinator
+        Coordinator.new(self,
+                        transport_type: @transport_type,
+                        config: @config)
       end
 
-      def fetch_and_create_resource_templates
-        resource_templates_response = resource_template_list_request
-        resource_templates_response = resource_templates_response["result"]["resourceTemplates"]
-
-        resource_templates = {}
-        resource_templates_response.each do |resource_template|
-          new_resource_template = RubyLLM::MCP::ResourceTemplate.new(self, resource_template)
-          resource_templates[new_resource_template.name] = new_resource_template
+      def fetch(cache_key, refresh)
+        instance_variable_set("@#{cache_key}", {}) if refresh
+        if instance_variable_get("@#{cache_key}").empty?
+          instance_variable_set("@#{cache_key}", yield)
         end
-
-        resource_templates
+        instance_variable_get("@#{cache_key}")
       end
 
-      def fetch_and_create_prompts
-        prompts_response = prompt_list_request
-        prompts_response = prompts_response["result"]["prompts"]
-
-        prompts = {}
-        prompts_response.each do |prompt|
-          new_prompt = RubyLLM::MCP::Prompt.new(self,
-                                                name: prompt["name"],
-                                                description: prompt["description"],
-                                                arguments: prompt["arguments"])
-
-          prompts[new_prompt.name] = new_prompt
+      def build_map(raw_data, klass)
+        raw_data.each_with_object({}) do |item, acc|
+          instance = klass.new(@coordinator, item)
+          acc[instance.name] = instance
         end
-
-        prompts
       end
     end
   end

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