feat: implement MCP elicitation with form and URL modes (#210)

Author: seuros

lib/action_mcp/configuration.rb

@@ -25,7 +25,6 @@ class Configuration
                   :logging_level,
                   :active_profile,
                   :profiles,
-                  :elicitation_enabled,
                   :verbose_logging,
                   # --- Authentication Options ---
                   :authentication_methods,
@@ -58,7 +57,6 @@ def initialize
       @list_changed = true
       @logging_level = :warning
       @resources_subscribe = false
-      @elicitation_enabled = false
       @verbose_logging = false
       @active_profile = :primary
       @profiles = default_profiles
@@ -280,7 +278,6 @@ def capabilities
         capabilities[:resources] = { subscribe: @resources_subscribe, listChanged: @list_changed }
       end
 
-      capabilities[:elicitation] = {} if @elicitation_enabled
 
       # Tasks capability (MCP 2025-11-25)
       if @tasks_enabled

lib/action_mcp/server/elicitation.rb

@@ -1,58 +1,126 @@
 # frozen_string_literal: true
 
+require_relative "elicitation_request"
+require_relative "url_elicitation_request"
+
 module ActionMCP
   module Server
-    # Handles elicitation requests from the server to the client
+    # Handles elicitation requests from the server to the client.
+    #
+    # Two modes per MCP 2025-11-25:
+    #   - Form mode: structured data collection with JSON Schema validation
+    #   - URL mode: out-of-band interaction via external URL (sensitive data, OAuth flows)
     module Elicitation
-      # Sends an elicitation request to the client to gather additional information
-      # @param request_id [String, Integer] The JSON-RPC request ID
-      # @param message [String] The message to present to the user
-      # @param requested_schema [Hash] The schema for the requested information
-      # @return [Hash] The elicitation response
-      def send_elicitation_request(request_id, message:, requested_schema:)
-        # Validate the requested schema
-        validate_elicitation_schema!(requested_schema)
-
-        params = {
+      URL_ELICITATION_REQUIRED_CODE = -32_042
+
+      # Send a form mode elicitation request to the client.
+      # @param message [String] Human-readable message explaining why input is needed
+      # @param requested_schema [Hash] JSON Schema for the expected response (primitive types only)
+      # @param _meta [Hash] Optional metadata (e.g. related task)
+      def send_elicitation_create(message:, requested_schema:, _meta: {})
+        require_client_elicitation_support!(:form)
+
+        request = ElicitationRequest.new(
+          message: message,
+          requested_schema: requested_schema,
+          _meta: _meta
+        )
+        request.assert_valid!
+
+        send_jsonrpc_request("elicitation/create", params: request.to_params)
+      end
+
+      # Send a URL mode elicitation request to the client.
+      # Used for sensitive data collection (API keys, OAuth, payments) that must not
+      # pass through the MCP client.
+      # @param message [String] Human-readable message explaining why navigation is needed
+      # @param url [String] The URL the user should navigate to
+      # @param elicitation_id [String] Unique identifier for this elicitation
+      # @param _meta [Hash] Optional metadata (e.g. related task)
+      def send_elicitation_create_url(message:, url:, elicitation_id: nil, _meta: {})
+        require_client_elicitation_support!(:url)
+
+        request = UrlElicitationRequest.new(
+          message: message,
+          url: url,
+          elicitation_id: elicitation_id,
+          _meta: _meta
+        )
+        request.assert_valid!
+
+        send_jsonrpc_request("elicitation/create", params: request.to_params)
+      end
+
+      # Send a completion notification for a URL mode elicitation.
+      # Informs the client that the out-of-band interaction has completed.
+      # @param elicitation_id [String] The elicitation ID from the original request
+      def send_elicitation_complete_notification(elicitation_id)
+        require_client_elicitation_support!(:url)
+        send_jsonrpc_notification(
+          "notifications/elicitation/complete",
+          { elicitationId: elicitation_id }
+        )
+      end
+
+      # Build a URLElicitationRequiredError response (-32042).
+      # Used when a request cannot proceed until an elicitation is completed.
+      # @param request_id [String, Integer] The JSON-RPC request ID to respond to
+      # @param message [String] Human-readable error message
+      # @param elicitations [Array<Hash>] Required URL mode elicitations
+      def send_url_elicitation_required_error(request_id, message:, elicitations:)
+        require_client_elicitation_support!(:url)
+
+        elicitations.each do |e|
+          raise ArgumentError, "Each elicitation must have mode: 'url'" unless e[:mode] == "url"
+          raise ArgumentError, "Each elicitation must have an elicitationId" unless e[:elicitationId].present?
+
+          UrlElicitationRequest.new(
+            message: e[:message],
+            url: e[:url],
+            elicitation_id: e[:elicitationId]
+          ).assert_valid!
+        end
+
+        error = {
+          code: URL_ELICITATION_REQUIRED_CODE,
           message: message,
-          requestedSchema: requested_schema
+          data: { elicitations: elicitations }
         }
 
-        send_jsonrpc_request(request_id, method: "elicitation/create", params: params)
+        send_jsonrpc_response(request_id, error: error)
       end
 
       private
 
-      # Validates that the requested schema follows the elicitation constraints
-      # Only allows primitive types without nesting
-      def validate_elicitation_schema!(schema)
-        unless schema.is_a?(Hash) && schema[:type] == "object"
-          raise ArgumentError, "Elicitation schema must be an object type"
-        end
+      # Check that the client declared support for the given elicitation mode.
+      # Elicitation is a client capability — servers MUST NOT send modes the client didn't declare.
+      def require_client_elicitation_support!(mode)
+        client_caps = session.client_capabilities || {}
+        elicitation_caps = client_caps["elicitation"] || client_caps[:elicitation]
 
-        properties = schema[:properties]
-        raise ArgumentError, "Elicitation schema must have properties" unless properties.is_a?(Hash)
+        raise UnsupportedElicitationError, "Client does not support elicitation" unless elicitation_caps.is_a?(Hash)
 
-        properties.each do |key, prop_schema|
-          validate_primitive_schema!(key, prop_schema)
+        if mode == :form
+          # Empty hash or explicit form: {} both mean form support (backward compat with 2025-06-18)
+          # But if client only declared url: {} without form, reject
+          form_cap = elicitation_caps["form"] || elicitation_caps[:form]
+          unless elicitation_caps.empty? || form_cap
+            raise UnsupportedElicitationError, "Client does not support form mode elicitation"
+          end
+          return
         end
-      end
 
-      # Validates individual property schemas are primitive types
-      def validate_primitive_schema!(key, schema)
-        raise ArgumentError, "Property '#{key}' must have a schema definition" unless schema.is_a?(Hash)
-
-        type = schema[:type]
-        case type
-        when "string"
-          # Valid string schema, check for enums
-          raise ArgumentError, "Property '#{key}' enum must be an array" if schema[:enum] && !schema[:enum].is_a?(Array)
-        when "number", "integer", "boolean"
-          # Valid primitive types
-        else
-          raise ArgumentError, "Property '#{key}' must be a primitive type (string, number, integer, boolean)"
+        # URL mode requires protocol version 2025-11-25+
+        unless session.protocol_version == "2025-11-25"
+          raise UnsupportedElicitationError, "URL mode elicitation requires protocol version 2025-11-25"
         end
+
+        # Client must explicitly declare url mode support (empty hash = form-only for 2025-06-18 clients)
+        url_cap = elicitation_caps["url"] || elicitation_caps[:url]
+        raise UnsupportedElicitationError, "Client does not support URL mode elicitation" unless url_cap
       end
     end
+
+    class UnsupportedElicitationError < StandardError; end
   end
 end

lib/action_mcp/server/elicitation_request.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Server
+    # Value object for form-mode elicitation requests.
+    # Validates that the requested schema follows MCP constraints:
+    # flat object with primitive properties only.
+    class ElicitationRequest
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      attribute :message, :string
+      attribute :requested_schema # Hash
+      attribute :_meta            # Hash, optional
+
+      validates :message, presence: true
+      validates :requested_schema, presence: true
+      validate :schema_must_be_object_with_properties, if: -> { requested_schema.present? }
+      validate :properties_must_be_primitive, if: -> { errors[:requested_schema].empty? && requested_schema.present? }
+
+      # Wrap incoming schema in indifferent access so both string and symbol keys work.
+      def requested_schema=(value)
+        super(value.is_a?(Hash) ? value.with_indifferent_access : value)
+      end
+
+      # @return [Hash] JSON-RPC params for elicitation/create
+      def to_params
+        params = { mode: "form", message: message, requestedSchema: requested_schema.to_hash.deep_symbolize_keys }
+        params[:_meta] = _meta if _meta.present?
+        params
+      end
+
+      # Validates and raises ArgumentError on failure (preserving public API).
+      # Named assert_valid! to avoid shadowing ActiveModel#validate!
+      def assert_valid!
+        return if valid?
+
+        raise ArgumentError, errors.full_messages.join(", ")
+      end
+
+      private
+
+      def schema_must_be_object_with_properties
+        unless requested_schema.is_a?(Hash) && requested_schema[:type] == "object"
+          errors.add(:requested_schema, "must be an object type")
+          return
+        end
+
+        properties = requested_schema[:properties]
+        errors.add(:requested_schema, "must have properties") unless properties.is_a?(Hash)
+      end
+
+      def properties_must_be_primitive
+        properties = requested_schema[:properties]
+        return unless properties.is_a?(Hash)
+
+        properties.each do |key, prop_schema|
+          validate_primitive_property(key, prop_schema)
+        end
+      end
+
+      def validate_primitive_property(key, schema)
+        unless schema.is_a?(Hash)
+          errors.add(:requested_schema, "property '#{key}' must have a schema definition")
+          return
+        end
+
+        case schema[:type]
+        when "string"
+          validate_string_enum(key, schema)
+        when "number", "integer", "boolean"
+          # valid primitive types
+        when "array"
+          validate_enum_array(key, schema)
+        else
+          errors.add(:requested_schema,
+            "property '#{key}' must be a primitive type (string, number, integer, boolean) or enum array")
+        end
+      end
+
+      def validate_string_enum(key, schema)
+        if schema[:enum] && !schema[:enum].is_a?(Array)
+          errors.add(:requested_schema, "property '#{key}' enum must be an array")
+        end
+      end
+
+      def validate_enum_array(key, schema)
+        items = schema[:items]
+        unless items.is_a?(Hash)
+          errors.add(:requested_schema, "property '#{key}' array must have items schema")
+          return
+        end
+
+        unless items[:enum].is_a?(Array) || items[:anyOf].is_a?(Array)
+          errors.add(:requested_schema, "property '#{key}' array items must be an enum (enum or anyOf)")
+        end
+      end
+    end
+  end
+end

lib/action_mcp/server/url_elicitation_request.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module ActionMCP
+  module Server
+    # Value object for URL-mode elicitation requests.
+    # Used for sensitive data collection (API keys, OAuth, payments)
+    # that must not pass through the MCP client.
+    class UrlElicitationRequest
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      attribute :message, :string
+      attribute :url, :string
+      attribute :elicitation_id, :string
+      attribute :_meta # Hash, optional
+
+      validates :message, presence: true
+      validates :url, presence: true
+      validate :url_must_be_valid_http, if: -> { url.present? }
+
+      def initialize(attributes = {})
+        super
+        self.elicitation_id = SecureRandom.uuid_v7 if elicitation_id.blank?
+      end
+
+      # @return [Hash] JSON-RPC params for elicitation/create
+      def to_params
+        params = {
+          mode: "url",
+          message: message,
+          url: url,
+          elicitationId: elicitation_id
+        }
+        params[:_meta] = _meta if _meta.present?
+        params
+      end
+
+      # Validates and raises ArgumentError on failure (preserving public API).
+      # Named assert_valid! to avoid shadowing ActiveModel#validate!
+      def assert_valid!
+        return if valid?
+
+        raise ArgumentError, errors.full_messages.join(", ")
+      end
+
+      private
+
+      def url_must_be_valid_http
+        parsed = URI.parse(url)
+        unless parsed.is_a?(URI::HTTP) && parsed.host.present?
+          errors.add(:url, "must be an HTTP or HTTPS URL with a host")
+        end
+      rescue URI::InvalidURIError
+        errors.add(:url, "is not a valid URI")
+      end
+    end
+  end
+end