ruby_llm-mcp 0.8.0 → 1.0.0

data/lib/ruby_llm/mcp/native/transports/support/http_client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      module Transports
+        module Support
+          class HTTPClient
+            CONNECTION_KEY = :ruby_llm_mcp_client_connection
+
+            def self.connection
+              Thread.current[CONNECTION_KEY] ||= build_connection
+            end
+
+            def self.build_connection
+              HTTPX.with(
+                pool_options: {
+                  max_connections: RubyLLM::MCP.config.max_connections,
+                  pool_timeout: RubyLLM::MCP.config.pool_timeout
+                }
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/transports/support/rate_limiter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      module Transports
+        module Support
+          class RateLimiter
+            def initialize(limit: 10, interval: 1000)
+              @limit = limit
+              @interval = interval
+              @timestamps = []
+              @mutex = Mutex.new
+            end
+
+            def exceeded?
+              now = current_time
+
+              @mutex.synchronize do
+                purge_old(now)
+                @timestamps.size >= @limit
+              end
+            end
+
+            def add
+              now = current_time
+
+              @mutex.synchronize do
+                purge_old(now)
+                @timestamps << now
+              end
+            end
+
+            private
+
+            def current_time
+              Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            end
+
+            def purge_old(now)
+              cutoff = now - @interval
+              @timestamps.reject! { |t| t < cutoff }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/transports/support/timeout.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      module Transports
+        module Support
+          module Timeout
+            def with_timeout(seconds, request_id: nil)
+              result = nil
+              exception = nil
+
+              worker = Thread.new do
+                result = yield
+              rescue StandardError => e
+                exception = e
+              end
+
+              if worker.join(seconds)
+                raise exception if exception
+
+                result
+              else
+                worker.kill # stop the thread (can still have some risk if shared resources)
+                raise RubyLLM::MCP::Errors::TimeoutError.new(
+                  message: "Request timed out after #{seconds} seconds",
+                  request_id: request_id
+                )
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "native/messages"
+
+module RubyLLM
+  module MCP
+    # Native protocol implementation namespace
+    # This module contains the native Ruby MCP protocol implementation
+    module Native
+    end
+  end
+end

data/lib/ruby_llm/mcp/notification_handler.rb

@@ -3,11 +3,10 @@
 module RubyLLM
   module MCP
     class NotificationHandler
-      attr_reader :coordinator, :client
+      attr_reader :client
 
-      def initialize(coordinator)
-        @coordinator = coordinator
-        @client = coordinator.client
+      def initialize(client)
+        @client = client
       end
 
       def execute(notification)
@@ -25,7 +24,11 @@ module RubyLLM
         when "notifications/progress"
           process_progress_message(notification)
         when "notifications/cancelled"
-          # TODO: - do nothing at the moment until we support client operations
+          process_cancelled_notification(notification)
+        when "notifications/tasks/status"
+          process_task_status_notification(notification)
+        when "notifications/elicitation/complete"
+          process_elicitation_complete_notification(notification)
         else
           process_unknown_notification(notification)
         end
@@ -75,10 +78,45 @@ module RubyLLM
         end
       end
 
+      def process_cancelled_notification(notification)
+        request_id = notification.params["requestId"]
+        reason = notification.params["reason"] || "No reason provided"
+
+        RubyLLM::MCP.logger.info(
+          "Received cancellation for request #{request_id}: #{reason}"
+        )
+
+        outcome = client.cancel_in_flight_request(request_id)
+
+        case outcome
+        when :cancelled, :already_cancelled, :already_completed
+          RubyLLM::MCP.logger.debug("Cancellation outcome for #{request_id}: #{outcome}")
+        when :not_found
+          RubyLLM::MCP.logger.debug("Request #{request_id} was not found or already completed")
+        when :not_cancellable
+          RubyLLM::MCP.logger.warn("Request #{request_id} is not cancellable")
+        else
+          RubyLLM::MCP.logger.warn("Cancellation for #{request_id} returned unexpected outcome: #{outcome.inspect}")
+        end
+      end
+
       def process_unknown_notification(notification)
         message = "Unknown notification type: #{notification.type} params: #{notification.params.to_h}"
         RubyLLM::MCP.logger.error(message)
       end
+
+      def process_task_status_notification(notification)
+        return unless client.adapter.respond_to?(:task_status_notification)
+
+        client.adapter.task_status_notification(task: notification.params)
+      end
+
+      def process_elicitation_complete_notification(notification)
+        elicitation_id = notification.params["elicitationId"]
+        return if elicitation_id.nil?
+
+        Handlers::ElicitationRegistry.remove(elicitation_id)
+      end
     end
   end
 end

data/lib/ruby_llm/mcp/prompt.rb

@@ -21,10 +21,10 @@ module RubyLLM
         end
       end
 
-      attr_reader :name, :description, :arguments, :coordinator
+      attr_reader :name, :description, :arguments, :adapter
 
-      def initialize(coordinator, prompt)
-        @coordinator = coordinator
+      def initialize(adapter, prompt)
+        @adapter = adapter
         @name = prompt["name"]
         @description = prompt["description"]
         @arguments = parse_arguments(prompt["arguments"])
@@ -51,8 +51,8 @@ module RubyLLM
       alias say ask
 
       def complete(argument, value, context: nil)
-        if @coordinator.capabilities.completion?
-          result = @coordinator.completion_prompt(name: @name, argument: argument, value: value, context: context)
+        if @adapter.capabilities.completion?
+          result = @adapter.completion_prompt(name: @name, argument: argument, value: value, context: context)
           if result.error?
             return result.to_error
           end
@@ -80,7 +80,7 @@ module RubyLLM
       private
 
       def fetch_prompt_messages(arguments)
-        result = @coordinator.execute_prompt(
+        result = @adapter.execute_prompt(
           name: @name,
           arguments: arguments
         )
@@ -113,7 +113,7 @@ module RubyLLM
           attachment = MCP::Attachment.new(content["content"], content["mime_type"])
           MCP::Content.new(text: nil, attachments: [attachment])
         when "resource"
-          resource = Resource.new(coordinator, content["resource"])
+          resource = Resource.new(adapter, content["resource"])
           resource.to_content
         end
       end

data/lib/ruby_llm/mcp/railtie.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
-module RubyLLM
-  module MCP
-    class Railtie < Rails::Railtie
-      generators do
-        require_relative "../../generators/ruby_llm/mcp/install/install_generator"
-        require_relative "../../generators/ruby_llm/mcp/oauth/install_generator"
+if defined?(Rails::Railtie)
+  module RubyLLM
+    module MCP
+      class Railtie < Rails::Railtie
+        generators do
+          require_relative "../../generators/ruby_llm/mcp/install/install_generator"
+          require_relative "../../generators/ruby_llm/mcp/oauth/install_generator"
+        end
       end
     end
   end

data/lib/ruby_llm/mcp/resource.rb

@@ -1,18 +1,17 @@
 # frozen_string_literal: true
 
-require "httpx"
-
 module RubyLLM
   module MCP
     class Resource
-      attr_reader :uri, :name, :description, :mime_type, :coordinator, :subscribed
+      attr_reader :uri, :name, :description, :mime_type, :adapter, :subscribed, :apps_metadata
 
-      def initialize(coordinator, resource)
-        @coordinator = coordinator
+      def initialize(adapter, resource)
+        @adapter = adapter
         @uri = resource["uri"]
         @name = resource["name"]
         @description = resource["description"]
         @mime_type = resource["mimeType"]
+        @apps_metadata = Extensions::Apps::ResourceMetadata.new(resource[Extensions::Apps::Constants::META_KEY])
         if resource.key?("content_response")
           @content_response = resource["content_response"]
           @content = @content_response["text"] || @content_response["blob"]
@@ -36,8 +35,8 @@ module RubyLLM
       end
 
       def subscribe!
-        if @coordinator.capabilities.resource_subscribe?
-          @coordinator.resources_subscribe(uri: @uri)
+        if @adapter.capabilities.resource_subscribe?
+          @adapter.resources_subscribe(uri: @uri)
           @subscribed = true
         else
           message = "Resource subscribe is not available for this MCP server"
@@ -45,6 +44,16 @@ module RubyLLM
         end
       end
 
+      def unsubscribe!
+        if @adapter.capabilities.resource_subscribe?
+          @adapter.resources_unsubscribe(uri: @uri)
+          @subscribed = false
+        else
+          message = "Resource unsubscribe is not available for this MCP server"
+          raise Errors::Capabilities::ResourceSubscribeNotAvailable.new(message: message)
+        end
+      end
+
       def reset_content!
         @content = nil
         @content_response = nil
@@ -101,7 +110,7 @@ module RubyLLM
         when "http", "https"
           fetch_uri_content(uri)
         else # file:// or git://
-          @coordinator.resource_read(uri: uri)
+          @adapter.resource_read(uri: uri)
         end
       end
 

data/lib/ruby_llm/mcp/resource_template.rb

@@ -5,14 +5,15 @@ require "httpx"
 module RubyLLM
   module MCP
     class ResourceTemplate
-      attr_reader :uri, :name, :description, :mime_type, :coordinator, :template
+      attr_reader :uri, :name, :description, :mime_type, :adapter, :template, :apps_metadata
 
-      def initialize(coordinator, resource)
-        @coordinator = coordinator
+      def initialize(adapter, resource)
+        @adapter = adapter
         @uri = resource["uriTemplate"]
         @name = resource["name"]
         @description = resource["description"]
         @mime_type = resource["mimeType"]
+        @apps_metadata = Extensions::Apps::ResourceMetadata.new(resource[Extensions::Apps::Constants::META_KEY])
       end
 
       def fetch_resource(arguments: {})
@@ -20,7 +21,7 @@ module RubyLLM
         result = read_response(uri)
         content_response = result.value.dig("contents", 0)
 
-        Resource.new(coordinator, {
+        Resource.new(adapter, {
                        "uri" => uri,
                        "name" => "#{@name} (#{uri})",
                        "description" => @description,
@@ -34,8 +35,8 @@ module RubyLLM
       end
 
       def complete(argument, value, context: nil)
-        if @coordinator.capabilities.completion?
-          result = @coordinator.completion_resource(uri: @uri, argument: argument, value: value, context: context)
+        if @adapter.capabilities.completion?
+          result = @adapter.completion_resource(uri: @uri, argument: argument, value: value, context: context)
           result.raise_error! if result.error?
 
           response = result.value["completion"]
@@ -64,7 +65,7 @@ module RubyLLM
         when "http", "https"
           fetch_uri_content(uri)
         else # file:// or git://
-          @coordinator.resource_read(uri: uri)
+          @adapter.resource_read(uri: uri)
         end
       end
 

data/lib/ruby_llm/mcp/result.rb

@@ -32,6 +32,10 @@ module RubyLLM
 
         @result_is_error = response.dig("result", "isError") || false
         @next_cursor = response.dig("result", "nextCursor")
+
+        # Track whether result/error keys exist (for JSON-RPC detection)
+        @has_result = response.key?("result")
+        @has_error = response.key?("error")
       end
 
       REQUEST_METHODS.each do |method_name, method_value|
@@ -65,7 +69,7 @@ module RubyLLM
       end
 
       def notification?
-        @method&.include?("notifications") || false
+        @id.nil? && !@method.nil?
       end
 
       def next_cursor?
@@ -73,15 +77,15 @@ module RubyLLM
       end
 
       def request?
-        !@method.nil? && !notification? && @result.none? && @error.none?
+        !@id.nil? && !@method.nil?
       end
 
       def response?
-        !@id.nil? && (@result || @error.any?) && !@method
+        !@id.nil? && @method.nil? && (@has_result || @has_error)
       end
 
       def success?
-        !@result.empty?
+        @has_result
       end
 
       def tool_success?

data/lib/ruby_llm/mcp/roots.rb

@@ -5,9 +5,9 @@ module RubyLLM
     class Roots
       attr_reader :paths
 
-      def initialize(paths: [], coordinator: nil)
+      def initialize(paths: [], adapter: nil)
         @paths = paths
-        @coordinator = coordinator
+        @adapter = adapter
       end
 
       def active?
@@ -16,12 +16,12 @@ module RubyLLM
 
       def add(path)
         @paths << path
-        @coordinator.roots_list_change_notification
+        @adapter.roots_list_change_notification
       end
 
       def remove(path)
         @paths.delete(path)
-        @coordinator.roots_list_change_notification
+        @adapter.roots_list_change_notification
       end
 
       def to_request

data/lib/ruby_llm/mcp/sample.rb

@@ -47,15 +47,14 @@ module RubyLLM
       end
 
       def execute
-        return unless callback_guard_success?
+        # Check if handler is a class or block
+        handler = @coordinator.sampling_callback
 
-        model = preferred_model
-        return unless model
-
-        chat_message = chat(model)
-        @coordinator.sampling_create_message_response(
-          id: @id, message: chat_message, model: model
-        )
+        if Handlers.handler_class?(handler)
+          execute_with_handler_class(handler)
+        else
+          execute_with_block
+        end
       end
 
       def message
@@ -75,15 +74,86 @@ module RubyLLM
 
       private
 
-      def callback_guard_success?
-        return true unless @coordinator.client.sampling_callback_enabled?
+      # Execute using handler class
+      def execute_with_handler_class(handler_class)
+        handler_instance = handler_class.new(
+          sample: self,
+          coordinator: @coordinator
+        )
+
+        result = handler_instance.call
 
-        unless @coordinator.client.on[:sampling].call(self)
+        # Handle different return types
+        case result
+        when Hash
+          handle_handler_hash_result(result)
+        when TrueClass, FalseClass
+          handle_handler_boolean_result(result)
+        else
+          # Unexpected return type
+          RubyLLM::MCP.logger.error("Handler returned unexpected type: #{result.class}")
+          @coordinator.error_response(id: @id, message: "Internal error in sampling handler")
+        end
+      rescue StandardError => e
+        RubyLLM::MCP.logger.error("Error in sampling handler: #{e.message}\n#{e.backtrace.join("\n")}")
+        @coordinator.error_response(id: @id, message: "Error executing sampling request: #{e.message}")
+      end
+
+      # Handle hash result from handler
+      def handle_handler_hash_result(result)
+        if result[:accepted] == false
+          @coordinator.error_response(id: @id, message: result[:message] || REJECTED_MESSAGE)
+        elsif result[:accepted] == true && result[:response]
+          # Handler provided the response directly
+          model = preferred_model
+          return unless model
+
+          @coordinator.sampling_create_message_response(
+            id: @id, message: result[:response], model: model
+          )
+        else
+          # Invalid hash structure
+          @coordinator.error_response(id: @id, message: "Invalid handler response")
+        end
+      end
+
+      # Handle boolean result from handler
+      def handle_handler_boolean_result(result)
+        unless result
           @coordinator.error_response(id: @id, message: REJECTED_MESSAGE)
-          return false
+          return
         end
 
-        true
+        model = preferred_model
+        return unless model
+
+        chat_message = chat(model)
+        @coordinator.sampling_create_message_response(
+          id: @id, message: chat_message, model: model
+        )
+      end
+
+      # Execute using block (legacy/backward compatible)
+      def execute_with_block
+        callback_result = run_sampling_callback
+
+        case callback_result
+        when Hash
+          handle_handler_hash_result(callback_result)
+        when TrueClass, FalseClass
+          handle_handler_boolean_result(callback_result)
+        else
+          # Legacy compatibility: any truthy callback result means "allow sampling"
+          handle_handler_boolean_result(!!callback_result)
+        end
+      end
+
+      def run_sampling_callback
+        return true unless @coordinator.sampling_callback_enabled?
+
+        callback_result = @coordinator.sampling_callback&.call(self)
+        # If callback returns nil, it means no guard was configured - allow it
+        callback_result.nil? || callback_result
       rescue StandardError => e
         RubyLLM::MCP.logger.error("Error in callback guard: #{e.message}, #{e.backtrace.join("\n")}")
         @coordinator.error_response(id: @id, message: "Error executing sampling request")

data/lib/ruby_llm/mcp/schema_validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+
+module RubyLLM
+  module MCP
+    module SchemaValidator
+      module_function
+
+      def valid?(schema, data)
+        return true if schema.nil?
+
+        schemer(schema).valid?(data)
+      rescue StandardError
+        false
+      end
+
+      def valid_schema?(schema)
+        return true if schema.nil?
+
+        schemer(schema)
+        true
+      rescue StandardError
+        false
+      end
+
+      def schemer(schema)
+        JSONSchemer.schema(schema)
+      end
+      private_class_method :schemer
+    end
+  end
+end

data/lib/ruby_llm/mcp/server_capabilities.rb

@@ -44,6 +44,47 @@ module RubyLLM
       def logging?
         !@capabilities["logging"].nil?
       end
+
+      def tasks?
+        !@capabilities["tasks"].nil?
+      end
+
+      def tasks_list?
+        !@capabilities.dig("tasks", "list").nil?
+      end
+
+      def tasks_cancel?
+        !@capabilities.dig("tasks", "cancel").nil?
+      end
+
+      def task_augmented_tool_call?
+        !@capabilities.dig("tasks", "requests", "tools", "call").nil?
+      end
+
+      def extensions
+        value = @capabilities["extensions"]
+        value.is_a?(Hash) ? value : {}
+      end
+
+      def extension?(id)
+        !extension_capability(id).nil?
+      end
+
+      def extension_capability(id)
+        canonical_id = Extensions::Registry.canonicalize_id(id)
+        return nil if canonical_id.nil?
+
+        normalized_extensions[canonical_id]
+      end
+
+      private
+
+      def normalized_extensions
+        extensions.each_with_object({}) do |(id, value), acc|
+          canonical_id = Extensions::Registry.canonicalize_id(id) || id
+          acc[canonical_id] = value
+        end
+      end
     end
   end
 end