ruby_llm-mcp 0.7.1 → 1.0.0

data/lib/ruby_llm/mcp/extensions/apps/resource_metadata.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Extensions
+      module Apps
+        class ResourceMetadata
+          attr_reader :csp, :permissions, :domain, :prefers_border, :raw
+
+          def initialize(raw)
+            @raw = raw.is_a?(Hash) ? raw : {}
+
+            ui_meta = @raw[Constants::UI_KEY]
+            @csp = ui_meta&.dig(Constants::CSP_KEY)
+            @permissions = ui_meta&.dig(Constants::PERMISSIONS_KEY)
+            @domain = ui_meta&.dig(Constants::DOMAIN_KEY)
+            @prefers_border = ui_meta&.dig(Constants::PREFERS_BORDER_KEY)
+            @prefers_border = ui_meta&.dig(Constants::PREFERS_BORDER_ALT_KEY) if @prefers_border.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/extensions/apps/tool_metadata.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Extensions
+      module Apps
+        class ToolMetadata
+          attr_reader :resource_uri, :visibility, :raw
+
+          def initialize(raw)
+            @raw = raw.is_a?(Hash) ? raw : {}
+
+            ui_meta = @raw[Constants::UI_KEY]
+            @resource_uri = ui_meta&.dig(Constants::RESOURCE_URI_KEY) || @raw[Constants::LEGACY_RESOURCE_URI_KEY]
+
+            @visibility = normalize_visibility(ui_meta&.dig(Constants::VISIBILITY_KEY))
+          end
+
+          def model_visible?
+            @visibility.include?("model")
+          end
+
+          def app_visible?
+            @visibility.include?("app")
+          end
+
+          private
+
+          def normalize_visibility(value)
+            normalized = case value
+                         when nil
+                           Constants::DEFAULT_VISIBILITY
+                         when Array
+                           value
+                         else
+                           [value]
+                         end
+
+            normalized.map(&:to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/extensions/configuration.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Extensions
+      class Configuration
+        def initialize
+          reset!
+        end
+
+        def register(id, config = {})
+          canonical_id = Registry.canonicalize_id(id)
+          if canonical_id.nil?
+            raise ArgumentError, "Extension id is required"
+          end
+
+          unless config.nil? || config.is_a?(Hash)
+            raise ArgumentError, "Extension config for '#{canonical_id}' must be a Hash"
+          end
+
+          @extensions = Registry.merge(@extensions, { canonical_id => config })
+          self
+        end
+
+        def enable_apps(config = {})
+          normalized = Registry.deep_stringify_keys(config || {})
+          validate_apps_config!(normalized)
+          normalized[Apps::Constants::MIME_TYPES_KEY] ||= [Apps::Constants::APP_HTML_MIME_TYPE]
+
+          register(Constants::UI_EXTENSION_ID, normalized)
+        end
+
+        def to_h
+          Registry.normalize_map(@extensions)
+        end
+
+        def empty?
+          to_h.empty?
+        end
+
+        def reset!
+          @extensions = {}
+          self
+        end
+
+        private
+
+        def validate_apps_config!(config)
+          misplaced_keys = [
+            Apps::Constants::UI_KEY,
+            Apps::Constants::RESOURCE_URI_KEY,
+            Apps::Constants::LEGACY_RESOURCE_URI_KEY,
+            Apps::Constants::VISIBILITY_KEY
+          ]
+
+          if misplaced_keys.any? { |key| config.key?(key) }
+            raise ArgumentError,
+                  "MCP Apps extension config uses client capability fields (for example, 'mimeTypes'); " \
+                  "tool metadata fields like 'resourceUri' and 'visibility' belong in tool _meta.ui"
+          end
+
+          mime_types = config[Apps::Constants::MIME_TYPES_KEY]
+          return if mime_types.nil?
+
+          unless mime_types.is_a?(Array) && mime_types.all? { |value| value.is_a?(String) && !value.empty? }
+            raise ArgumentError, "'mimeTypes' must be an array of non-empty strings"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/extensions/constants.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Extensions
+      module Constants
+        UI_EXTENSION_ID = "io.modelcontextprotocol/ui"
+        APPS_EXTENSION_ALIAS = "io.modelcontextprotocol/apps"
+
+        EXTENSION_ALIASES = {
+          APPS_EXTENSION_ALIAS => UI_EXTENSION_ID
+        }.freeze
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/extensions/registry.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Extensions
+      module Registry
+        module_function
+
+        def canonicalize_id(id)
+          return nil if id.nil?
+
+          normalized = id.to_s.strip
+          return nil if normalized.empty?
+
+          Constants::EXTENSION_ALIASES.fetch(normalized, normalized)
+        end
+
+        def normalize_map(value)
+          return {} unless value.is_a?(Hash)
+
+          value.each_with_object({}) do |(id, config), acc|
+            canonical_id = canonicalize_id(id)
+            next if canonical_id.nil?
+
+            acc[canonical_id] = normalize_value(config)
+          end
+        end
+
+        def merge(global_extensions, client_extensions)
+          merged = normalize_map(global_extensions)
+          normalize_map(client_extensions).each do |id, config|
+            merged[id] = deep_merge_values(merged[id], config)
+          end
+          merged
+        end
+
+        def deep_merge_values(base_value, override_value)
+          if base_value.is_a?(Hash) && override_value.is_a?(Hash)
+            deep_merge_hashes(base_value, override_value)
+          else
+            normalize_value(override_value)
+          end
+        end
+
+        def normalize_value(value)
+          case value
+          when nil
+            {}
+          when Hash
+            deep_stringify_keys(value)
+          else
+            value
+          end
+        end
+
+        def deep_stringify_keys(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested_value), acc|
+              acc[key.to_s] = deep_stringify_keys(nested_value)
+            end
+          when Array
+            value.map { |item| deep_stringify_keys(item) }
+          else
+            value
+          end
+        end
+
+        def deep_merge_hashes(base_hash, override_hash)
+          merged = base_hash.dup
+
+          override_hash.each do |key, value|
+            merged[key] = if merged[key].is_a?(Hash) && value.is_a?(Hash)
+                            deep_merge_hashes(merged[key], value)
+                          else
+                            deep_stringify_keys(value)
+                          end
+          end
+
+          merged
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/handlers/approval_decision.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      # Normalized decision returned by human-in-the-loop handlers.
+      class ApprovalDecision
+        VALID_STATUSES = %i[approved denied deferred].freeze
+
+        attr_reader :status, :reason, :approval_id, :timeout, :promise
+
+        def initialize(status:, reason: nil, approval_id: nil, timeout: nil, promise: nil)
+          @status = status.to_sym
+          @reason = reason
+          @approval_id = approval_id
+          @timeout = timeout
+          @promise = promise
+        end
+
+        def self.approved
+          new(status: :approved)
+        end
+
+        def self.denied(reason: "Denied by user")
+          new(status: :denied, reason: reason)
+        end
+
+        def self.deferred(approval_id:, timeout:)
+          new(status: :deferred, approval_id: approval_id, timeout: timeout)
+        end
+
+        def self.from_handler_result(result, approval_id:, default_timeout: nil)
+          unless result.is_a?(Hash)
+            raise Errors::InvalidApprovalDecision.new(
+              message: "Human-in-the-loop handler must return a Hash, got #{result.class}"
+            )
+          end
+
+          status = (result[:status] || result["status"])&.to_sym
+          unless VALID_STATUSES.include?(status)
+            raise Errors::InvalidApprovalDecision.new(
+              message: "Human-in-the-loop handler returned invalid status '#{status.inspect}'"
+            )
+          end
+
+          case status
+          when :approved
+            approved
+          when :denied
+            denied(reason: result[:reason] || result["reason"] || "Denied by user")
+          when :deferred
+            timeout = result[:timeout] || result["timeout"] || default_timeout
+            validate_timeout!(timeout)
+            deferred(approval_id: approval_id, timeout: timeout.to_f)
+          end
+        end
+
+        def with_promise(promise)
+          self.class.new(
+            status: status,
+            reason: reason,
+            approval_id: approval_id,
+            timeout: timeout,
+            promise: promise
+          )
+        end
+
+        def approved?
+          status == :approved
+        end
+
+        def denied?
+          status == :denied
+        end
+
+        def deferred?
+          status == :deferred
+        end
+
+        private_class_method def self.validate_timeout!(timeout)
+          unless timeout.is_a?(Numeric) && timeout.positive?
+            raise Errors::InvalidApprovalDecision.new(
+              message: "Deferred approvals require a positive timeout"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/handlers/async_response.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      # Represents an async response for deferred completion
+      class AsyncResponse
+        attr_reader :elicitation_id, :state, :result, :error
+
+        VALID_STATES = %i[pending completed rejected cancelled timed_out].freeze
+
+        # Initialize async response
+        # @param elicitation_id [String] ID of the elicitation
+        # @param timeout [Integer, nil] optional timeout in seconds
+        # @param timeout_handler [Proc, Symbol, nil] handler for timeout
+        def initialize(elicitation_id:, timeout: nil, timeout_handler: nil)
+          @elicitation_id = elicitation_id
+          @state = :pending
+          @result = nil
+          @error = nil
+          @mutex = Mutex.new
+          @timeout = timeout
+          @timeout_handler = timeout_handler
+          @completion_callbacks = []
+          @created_at = Time.now
+
+          RubyLLM::MCP.logger.debug("AsyncResponse created for #{@elicitation_id} with timeout: #{@timeout || 'none'}")
+          schedule_timeout if @timeout
+        end
+
+        # Complete the async operation with data
+        # @param data [Object] the completion data
+        def complete(data)
+          callbacks_to_execute = nil
+
+          transitioned = transition_state(:completed) do
+            @result = data
+            callbacks_to_execute = @completion_callbacks.dup
+          end
+
+          if transitioned
+            duration = Time.now - @created_at
+            RubyLLM::MCP.logger.debug("AsyncResponse #{@elicitation_id} completed after #{duration.round(3)}s")
+          end
+
+          # Execute callbacks outside mutex to avoid deadlocks
+          execute_callbacks_safely(callbacks_to_execute, :completed, data) if transitioned && callbacks_to_execute
+        end
+
+        # Reject the async operation
+        # @param reason [String] reason for rejection
+        def reject(reason)
+          callbacks_to_execute = nil
+
+          transitioned = transition_state(:rejected) do
+            @error = reason
+            callbacks_to_execute = @completion_callbacks.dup
+          end
+
+          execute_callbacks_safely(callbacks_to_execute, :rejected, reason) if transitioned && callbacks_to_execute
+        end
+
+        # Cancel the async operation
+        # @param reason [String] reason for cancellation
+        def cancel(reason)
+          callbacks_to_execute = nil
+
+          transitioned = transition_state(:cancelled) do
+            @error = reason
+            callbacks_to_execute = @completion_callbacks.dup
+          end
+
+          execute_callbacks_safely(callbacks_to_execute, :cancelled, reason) if transitioned && callbacks_to_execute
+        end
+
+        # Mark as timed out
+        def timeout!
+          callbacks_to_execute = nil
+
+          transitioned = transition_state(:timed_out) do
+            @error = "Operation timed out"
+            callbacks_to_execute = @completion_callbacks.dup
+          end
+
+          execute_callbacks_safely(callbacks_to_execute, :timed_out, @error) if transitioned && callbacks_to_execute
+        end
+
+        # Register a callback for when operation completes/fails
+        # @param callback [Proc] callback to execute
+        def on_complete(&callback)
+          @mutex.synchronize do
+            @completion_callbacks << callback
+          end
+        end
+
+        # Check if operation is pending
+        def pending?
+          @state == :pending
+        end
+
+        # Check if operation is completed
+        def completed?
+          @state == :completed
+        end
+
+        # Check if operation is rejected
+        def rejected?
+          @state == :rejected
+        end
+
+        # Check if operation is cancelled
+        def cancelled?
+          @state == :cancelled
+        end
+
+        # Check if operation timed out
+        def timed_out?
+          @state == :timed_out
+        end
+
+        # Check if operation is finished (any terminal state)
+        def finished?
+          !pending?
+        end
+
+        private
+
+        # Transition to new state (thread-safe)
+        def transition_state(new_state)
+          @mutex.synchronize do
+            return false unless @state == :pending
+            return false unless VALID_STATES.include?(new_state)
+
+            @state = new_state
+            yield if block_given?
+            true
+          end
+        end
+
+        # Execute callbacks safely in isolation
+        # @param callbacks [Array] callbacks to execute
+        # @param state [Symbol] the state to pass to callbacks
+        # @param data [Object] the data to pass to callbacks
+        def execute_callbacks_safely(callbacks, state, data)
+          return unless callbacks
+
+          callbacks.each do |callback|
+            callback.call(state, data)
+          rescue StandardError => e
+            RubyLLM::MCP.logger.error(
+              "Error in async response callback: #{e.message}\n#{e.backtrace.join("\n")}"
+            )
+            # Continue executing other callbacks even if one fails
+          end
+        end
+
+        # Schedule timeout check
+        def schedule_timeout
+          Thread.new do
+            sleep @timeout
+            if pending?
+              timeout!
+              handle_timeout
+            end
+          end
+        end
+
+        # Handle timeout event
+        def handle_timeout
+          if @timeout_handler.is_a?(Proc)
+            @timeout_handler.call
+          end
+        rescue StandardError => e
+          RubyLLM::MCP.logger.error(
+            "Error in timeout handler: #{e.message}\n#{e.backtrace.join("\n")}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/handlers/concerns/approval_actions.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      module Concerns
+        # Provides action methods for human-in-the-loop approval handlers
+        module ApprovalActions
+          attr_reader :approval_id, :tool_name, :parameters
+
+          protected
+
+          # Approve the tool execution
+          # @return [Hash] structured approval response
+          def approve
+            { status: :approved }
+          end
+
+          # Deny the tool execution
+          # @param reason [String] reason for denial
+          # @return [Hash] structured denial response
+          def deny(reason = "Denied by user")
+            { status: :denied, reason: reason }
+          end
+
+          # Defer approval to complete asynchronously via registry.
+          # @param timeout [Numeric, nil] timeout in seconds; falls back to handler timeout
+          # @return [Hash] structured deferred response
+          def defer(timeout: nil)
+            resolved_timeout = timeout || (respond_to?(:timeout) ? self.timeout : nil)
+            { status: :deferred, timeout: resolved_timeout }
+          end
+
+          # Override guard_failed to return denial (if GuardChecks is included)
+          def guard_failed(message)
+            deny(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/handlers/concerns/async_execution.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      module Concerns
+        # Provides async execution capabilities for handlers
+        module AsyncExecution
+          def self.included(base)
+            base.extend(ClassMethods)
+          end
+
+          module ClassMethods
+            # Mark this handler as async (returns pending response)
+            # @param timeout [Integer, nil] optional timeout in seconds
+            def async_execution(timeout: nil)
+              @async = true
+              @async_timeout = timeout if timeout
+            end
+
+            # Check if handler is async
+            def async?
+              @async == true
+            end
+
+            # Get async timeout
+            attr_reader :async_timeout
+
+            # Inherit async settings from parent classes
+            def inherited(subclass)
+              super
+              subclass.instance_variable_set(:@async, @async)
+              subclass.instance_variable_set(:@async_timeout, @async_timeout)
+            end
+          end
+
+          # Check if this handler instance is async
+          def async?
+            self.class.async?
+          end
+
+          # Get timeout value for this handler
+          def timeout
+            @options[:timeout] || self.class.async_timeout
+          end
+
+          protected
+
+          # Create an async response for deferred completion
+          # @param elicitation_id [String, nil] ID for the async operation (auto-detected if not provided)
+          # @param timeout_handler [Proc, Symbol, nil] handler for timeout
+          # @return [AsyncResponse] async response object
+          def defer(elicitation_id: nil, timeout_handler: nil)
+            # Auto-detect ID from elicitation or approval_id if not provided
+            id = elicitation_id ||
+                 (respond_to?(:elicitation) && elicitation&.id) ||
+                 (respond_to?(:approval_id) && approval_id)
+
+            unless id
+              raise ArgumentError,
+                    "elicitation_id must be provided or handler must have elicitation/approval_id"
+            end
+
+            AsyncResponse.new(
+              elicitation_id: id,
+              timeout: timeout,
+              timeout_handler: timeout_handler
+            )
+          end
+
+          # Create a promise for async operations
+          # @return [Promise] promise object
+          def create_promise
+            Promise.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/handlers/concerns/elicitation_actions.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      module Concerns
+        # Provides action methods for elicitation request handlers
+        module ElicitationActions
+          attr_reader :elicitation
+
+          protected
+
+          # Accept the elicitation with structured response
+          # @param response [Hash] the structured response data
+          # @return [Hash] structured acceptance response
+          def accept(response)
+            { action: :accept, response: response }
+          end
+
+          # Reject the elicitation
+          # @param reason [String] reason for rejection
+          # @return [Hash] structured rejection response
+          def reject(reason)
+            { action: :reject, reason: reason }
+          end
+
+          # Cancel the elicitation
+          # @param reason [String] reason for cancellation
+          # @return [Hash] structured cancellation response
+          def cancel(reason)
+            { action: :cancel, reason: reason }
+          end
+
+          # Default action when timeout occurs
+          def default_timeout_action
+            reject("Elicitation timed out")
+          end
+        end
+      end
+    end
+  end
+end