actionmcp 0.108.0 → 0.109.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 917d5120acc0a5cb82cb4a9516a65e59370f922dfe2828670e1117a5d1d26934
-  data.tar.gz: a77bd78234661ee4ef52cafff59f5d6c856e94728bca98832c926928635e8e94
+  metadata.gz: dbc03b1ba75f2efaf3c94ff2e664d3ca4e21013e8c55651f1fccff0b8c4e889b
+  data.tar.gz: 1576d864115954653182d05080352a28b7be2a11c8fb376f0e426503a320eb7f
 SHA512:
-  metadata.gz: 6110ec397f08c3e8cbc2fe54a20f22bae3f600ad005e82f254bf6eeea7ba07c3bee1fc28a337a6263725fff213fdcbf092b08000285bdff0958b16fa5a958ccf
-  data.tar.gz: f57f192f165bf2a5d44d18189e6107eb0ab951eeaf4f88ddc92fa2e3208bcc4bfe7a7d6aed9cd0e01b2951d07e6e8b2826f75e6033054130b304707b0bec03b1
+  metadata.gz: da5bcfd15ecc9e76b4ac6c557a84a95cf91090520ec7d11fb6c3652168c80cc1820660a8311b8b173db8bd4a1773a26cd53e83b2bae4fb6874f0b79aff489482
+  data.tar.gz: 28235fee76f77b9a7a87cca20a149231d31649a980e2d19480fde5f38543d0aa7ca61d16e7d97d89a83de9d849dda6c9e323e03cbc73dacca68572a7ba2dbaf5

data/README.md

@@ -330,7 +330,7 @@ Call it as a task from a client by adding `_meta.task` (creates a Task record an
 }
 ```
 
-Poll task status with `tasks/get` or fetch the result when finished with `tasks/result`. Use `tasks/cancel` to stop non-terminal tasks.
+Poll task status with `tasks/get` or fetch the result when finished with `tasks/result`. Use `tasks/cancel` to stop non-terminal tasks. `tasks/list` returns tasks in recent-first order and always paginates (default 50 per page, or `pagination_page_size` if configured). The response includes an opaque `nextCursor` when more results are available — treat cursors as opaque tokens.
 
 ### ActionMCP::ResourceTemplate
 
@@ -491,6 +491,25 @@ end
 
 For dynamic versioning, consider adding the `rails_app_version` gem.
 
+### Pagination
+
+All list endpoints (`tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`) support cursor-based pagination per the MCP specification. Pagination is **off by default** — set `pagination_page_size` to enable:
+
+```ruby
+config.action_mcp.pagination_page_size = 10
+```
+
+Or in `config/mcp.yml`:
+
+```yaml
+shared:
+  pagination_page_size: 10
+```
+
+When set, responses include an opaque `nextCursor` when more items are available. When `nil` (default), all items are returned in a single response. Enable only when your clients support cursor-based pagination.
+
+`tasks/list` always paginates regardless of this setting (defaults to 50 per page, or `pagination_page_size` if configured).
+
 ### Server Instructions
 
 Server instructions help LLMs understand **what your server is for** and **when to use it**. They describe the server's purpose and goal, not technical details like rate limits or authentication (tools are self-documented via their own descriptions).

data/app/controllers/action_mcp/application_controller.rb

@@ -34,6 +34,7 @@ module ActionMCP
     def show
       # MCP Streamable HTTP spec allows servers to return 405 if they don't support SSE.
       # ActionMCP uses Tasks for async operations instead of SSE streaming.
+      response.headers["Allow"] = "POST, DELETE"
       head :method_not_allowed
     end
 
@@ -95,7 +96,7 @@ module ActionMCP
       result = json_rpc_handler.call(jsonrpc_params)
       process_handler_results(result, session, session_initially_missing, is_initialize_request)
     rescue StandardError => e
-      Rails.logger.error "Unified POST Error: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
+      Rails.error.report(e, handled: true, severity: :error)
       id = begin
         jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil
       rescue StandardError
@@ -128,7 +129,7 @@ module ActionMCP
         Rails.logger.info "Unified DELETE: Terminated session: #{session.id}" if ActionMCP.configuration.verbose_logging
         head :no_content
       rescue StandardError => e
-        Rails.logger.error "Unified DELETE: Error terminating session #{session.id}: #{e.class} - #{e.message}"
+        Rails.error.report(e, handled: true, severity: :error)
         render_internal_server_error("Failed to terminate session.")
       end
     end
@@ -329,7 +330,7 @@ module ActionMCP
       rescue ActionMCP::UnauthorizedError => e
         render_unauthorized(e.message)
       rescue StandardError => e
-        Rails.logger.error "Gateway authentication error: #{e.class} - #{e.message}"
+        Rails.error.report(e, handled: true, severity: :error)
         render_unauthorized("Authentication system error")
       end
     end

data/app/models/action_mcp/session/task.rb

@@ -68,7 +68,15 @@ module ActionMCP
       # Scopes - state_machines >= 0.100.0 auto-generates .with_status(:state) scopes
       scope :terminal, -> { with_status(:completed, :failed, :cancelled) }
       scope :non_terminal, -> { with_status(:working, :input_required) }
-      scope :recent, -> { order(created_at: :desc) }
+      scope :recent, -> { order(created_at: :desc, id: :desc) }
+      scope :before_recent, lambda { |task|
+        table = arel_table
+
+        where(
+          table[:created_at].lt(task.created_at)
+            .or(table[:created_at].eq(task.created_at).and(table[:id].lt(task.id)))
+        )
+      }
 
       # State machine definition per MCP spec
       state_machine :status, initial: :working do

data/lib/action_mcp/configuration.rb

@@ -25,7 +25,6 @@ module ActionMCP
                   :logging_level,
                   :active_profile,
                   :profiles,
-                  :elicitation_enabled,
                   :verbose_logging,
                   # --- Authentication Options ---
                   :authentication_methods,
@@ -58,7 +57,6 @@ module ActionMCP
       @list_changed = true
       @logging_level = :warning
       @resources_subscribe = false
-      @elicitation_enabled = false
       @verbose_logging = false
       @active_profile = :primary
       @profiles = default_profiles
@@ -73,6 +71,10 @@ module ActionMCP
       @tasks_list_enabled = true
       @tasks_cancel_enabled = true
 
+      # Pagination - nil means off. Set a number to enable with that page size.
+      # Most MCP clients (including Claude Code) don't follow nextCursor yet.
+      @pagination_page_size = nil
+
       # Schema validation - disabled by default for backward compatibility
       @validate_structured_content = false
 
@@ -132,6 +134,19 @@ module ActionMCP
       @allowed_identity_keys = Array(value).map(&:to_s).freeze
     end
 
+    # Pagination page size. nil = pagination disabled, positive integer = enabled.
+    attr_reader :pagination_page_size
+
+    def pagination_page_size=(value)
+      if value.nil?
+        @pagination_page_size = nil
+      else
+        size = value.to_i
+        raise ArgumentError, "pagination_page_size must be a positive integer, got: #{value.inspect}" unless size > 0
+        @pagination_page_size = size
+      end
+    end
+
     def gateway_class
       # Resolve gateway class lazily to account for Zeitwerk autoloading
       # This allows ApplicationGateway to be loaded from app/mcp even if the
@@ -263,7 +278,6 @@ module ActionMCP
         capabilities[:resources] = { subscribe: @resources_subscribe, listChanged: @list_changed }
       end
 
-      capabilities[:elicitation] = {} if @elicitation_enabled
 
       # Tasks capability (MCP 2025-11-25)
       if @tasks_enabled
@@ -383,6 +397,11 @@ module ActionMCP
       if config["server_instructions"]
         @server_instructions = parse_instructions(config["server_instructions"])
       end
+
+      # Extract pagination page size (nil = off, positive integer = on)
+      if config.key?("pagination_page_size")
+        self.pagination_page_size = config["pagination_page_size"]
+      end
     end
 
     def should_include_all?(type)

data/lib/action_mcp/content/resource.rb

@@ -9,7 +9,8 @@ module ActionMCP
       # @return [String] The MIME type of the resource.
       # @return [String, nil] The text content of the resource (optional).
       # @return [String, nil] The base64-encoded blob of the resource (optional).
-      attr_reader :uri, :mime_type, :text, :blob, :annotations
+      # @return [Hash, nil] Optional extension metadata (serialized on the wire as `_meta`).
+      attr_reader :uri, :mime_type, :text, :blob, :annotations, :meta
 
       # Initializes a new Resource content.
       #
@@ -18,17 +19,30 @@ module ActionMCP
       # @param text [String, nil] The text content of the resource (optional).
       # @param blob [String, nil] The base64-encoded blob of the resource (optional).
       # @param annotations [Hash, nil] Optional annotations for the resource.
-      def initialize(uri, mime_type = "text/plain", text: nil, blob: nil, annotations: nil)
+      # @param meta [Hash, #to_hash, #to_h, nil] Optional extension metadata. Emitted on the wire as `_meta`.
+      def initialize(uri, mime_type = "text/plain", text: nil, blob: nil, annotations: nil, meta: nil)
         super("resource", annotations: annotations)
         @uri = uri
         @mime_type = mime_type
         @text = text
         @blob = blob
         @annotations = annotations
+        @meta =
+          if meta.nil?
+            nil
+          elsif meta.respond_to?(:to_hash)
+            meta.to_hash
+          elsif meta.respond_to?(:to_h)
+            meta.to_h
+          else
+            raise ArgumentError, "meta must respond to :to_hash or :to_h, got: #{meta.class}"
+          end
       end
 
       # Returns a hash representation of the resource content.
       # Per MCP spec, embedded resources have type "resource" with a nested resource object.
+      # `meta` is emitted as `_meta` on the inner resource hash (TextResourceContents /
+      # BlobResourceContents), not on the outer content envelope.
       #
       # @return [Hash] The hash representation of the resource content.
       def to_h
@@ -36,6 +50,7 @@ module ActionMCP
         inner[:text] = @text if @text
         inner[:blob] = @blob if @blob
         inner[:annotations] = @annotations if @annotations
+        inner[:_meta] = @meta if @meta && !@meta.empty?
 
         { type: @type, resource: inner }
       end

data/lib/action_mcp/resource.rb

@@ -4,7 +4,7 @@ module ActionMCP
   # Represents a resource with its metadata.
   # Used by resources/list to describe concrete resources.
   class Resource
-    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations
+    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations, :meta
 
     # @param uri [String] The URI of the resource
     # @param name [String] Display name of the resource
@@ -13,7 +13,8 @@ module ActionMCP
     # @param mime_type [String, nil] MIME type of the resource content
     # @param size [Integer, nil] Size of the resource in bytes
     # @param annotations [Hash, nil] Optional annotations
-    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil)
+    # @param meta [Hash, #to_hash, #to_h, nil] Optional extension metadata. Emitted on the wire as `_meta`.
+    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil, meta: nil)
       @uri = uri
       @name = name
       @title = title
@@ -21,6 +22,16 @@ module ActionMCP
       @mime_type = mime_type
       @size = size
       @annotations = annotations
+      @meta =
+        if meta.nil?
+          nil
+        elsif meta.respond_to?(:to_hash)
+          meta.to_hash
+        elsif meta.respond_to?(:to_h)
+          meta.to_h
+        else
+          raise ArgumentError, "meta must respond to :to_hash or :to_h, got: #{meta.class}"
+        end
       freeze
     end
 
@@ -35,6 +46,7 @@ module ActionMCP
       hash[:mimeType] = mime_type if mime_type
       hash[:size] = size if size
       hash[:annotations] = annotations if annotations
+      hash[:_meta] = meta if meta && !meta.empty?
       hash
     end
 
@@ -46,12 +58,12 @@ module ActionMCP
       other.is_a?(Resource) && uri == other.uri && name == other.name &&
         title == other.title && description == other.description &&
         mime_type == other.mime_type && size == other.size &&
-        annotations == other.annotations
+        annotations == other.annotations && meta == other.meta
     end
     alias eql? ==
 
     def hash
-      [ uri, name, title, description, mime_type, size, annotations ].hash
+      [ uri, name, title, description, mime_type, size, annotations, meta ].hash
     end
   end
 end

data/lib/action_mcp/resource_template.rb

@@ -156,8 +156,9 @@ module ActionMCP
       # @param mime_type [String, nil] Falls back to template mime_type
       # @param size [Integer, nil] Size in bytes
       # @param annotations [Hash, nil] Optional annotations
+      # @param meta [Hash, #to_hash, #to_h, nil] Optional extension metadata passed through to the Resource (emitted as `_meta`)
       # @return [ActionMCP::Resource]
-      def build_resource(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil)
+      def build_resource(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil, meta: nil)
         ActionMCP::Resource.new(
           uri: uri,
           name: name,
@@ -165,7 +166,8 @@ module ActionMCP
           description: description || @description,
           mime_type: mime_type || @mime_type,
           size: size,
-          annotations: annotations
+          annotations: annotations,
+          meta: meta
         )
       end
 

data/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

data/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

data/lib/action_mcp/server/handlers/prompt_handler.rb

@@ -35,8 +35,8 @@ module ActionMCP
           transport.send_prompts_get(id, name, arguments)
         end
 
-        def handle_prompts_list(id, _params)
-          transport.send_prompts_list(id)
+        def handle_prompts_list(id, params)
+          transport.send_prompts_list(id, params)
         end
 
         def extract_name(params)

data/lib/action_mcp/server/pagination.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Server
+    # Shared cursor-based pagination for all list endpoints.
+    #
+    # Two strategies:
+    #   1. Offset-based — for in-memory arrays (tools, prompts, resource templates).
+    #   2. Keyset-based — for ActiveRecord relations (tasks). Stable under concurrent writes.
+    #
+    # When pagination_page_size is nil (default), returns all items
+    # unless the caller passes force: true or the client sends a cursor.
+    module Pagination
+      DEFAULT_PAGE_SIZE = 10
+
+      # Offset-based pagination for in-memory collections (tools, prompts, resources).
+      # For ActiveRecord relations, use paginate_by_keyset instead.
+      #
+      # @param collection [Array] Items to paginate
+      # @param cursor [String, nil] Opaque cursor from the client
+      # @param page_size [Integer, nil] Override page size (nil = use config)
+      # @param force [Boolean] Force pagination even when globally disabled
+      # @return [Array(Array, String|nil)] [page_items, next_cursor_or_nil]
+      def paginate(collection, cursor: nil, page_size: nil, force: false)
+        effective_page_size = page_size || pagination_page_size
+        items = Array(collection)
+
+        return [ items, nil ] unless force || effective_page_size || cursor
+
+        page_size = effective_page_size || DEFAULT_PAGE_SIZE
+        offset = decode_offset_cursor(cursor)
+        page = items.drop(offset).take(page_size + 1)
+
+        has_more = page.size > page_size
+        page = page.first(page_size) if has_more
+        next_cursor = has_more ? encode_offset_cursor(offset + page_size) : nil
+
+        [ page, next_cursor ]
+      end
+
+      # Keyset-based pagination for ActiveRecord relations.
+      # Uses a single column as cursor (must be unique + ordered).
+      # The relation MUST already be ordered by that column.
+      #
+      # @param relation [ActiveRecord::Relation] Ordered AR relation
+      # @param cursor [String, nil] Opaque keyset cursor (Base64-encoded column value)
+      # @param page_size [Integer] Page size
+      # @param column [Symbol] Column to use as cursor key (default: :id)
+      # @return [Array(Array, String|nil)] [page_items, next_cursor_or_nil]
+      def paginate_by_keyset(relation, cursor: nil, page_size: DEFAULT_PAGE_SIZE, column: :id)
+        if cursor
+          value = decode_keyset_cursor(cursor)
+          relation = relation.where(column => ...value)
+        end
+
+        page = relation.limit(page_size + 1).to_a
+        has_more = page.size > page_size
+        items = has_more ? page.first(page_size) : page
+        next_cursor = has_more ? encode_keyset_cursor(items.last, column) : nil
+
+        [ items, next_cursor ]
+      end
+
+      private
+
+      def pagination_page_size
+        ActionMCP.configuration.pagination_page_size
+      end
+
+      # --- Offset cursors (in-memory arrays) ---
+
+      def decode_offset_cursor(cursor)
+        return 0 if cursor.nil?
+        raise CursorError, "Cursor must be a non-empty string" unless cursor.is_a?(String) && !cursor.empty?
+
+        decoded = Base64.urlsafe_decode64(cursor)
+        raise CursorError, "Invalid cursor format" unless decoded.match?(/\A\d+\z/)
+        decoded.to_i
+      rescue ArgumentError
+        raise CursorError, "Invalid cursor encoding"
+      end
+
+      def encode_offset_cursor(offset)
+        Base64.urlsafe_encode64(offset.to_s, padding: false)
+      end
+
+      # --- Keyset cursors (ActiveRecord) ---
+
+      def decode_keyset_cursor(cursor)
+        raise CursorError, "Cursor must be a non-empty string" unless cursor.is_a?(String) && !cursor.empty?
+        Base64.urlsafe_decode64(cursor)
+      rescue ArgumentError
+        raise CursorError, "Invalid cursor encoding"
+      end
+
+      def encode_keyset_cursor(record, column)
+        value = record.public_send(column)
+        Base64.urlsafe_encode64(value.to_s, padding: false)
+      end
+    end
+
+    # Raised when a client provides a malformed cursor.
+    # Handlers catch this and return -32602 (Invalid params).
+    class CursorError < StandardError; end
+  end
+end

data/lib/action_mcp/server/prompts.rb

@@ -3,10 +3,15 @@
 module ActionMCP
   module Server
     module Prompts
-      def send_prompts_list(request_id)
-        # Use session's registered prompts
-        prompts = session.registered_prompts.map(&:to_h)
-        send_jsonrpc_response(request_id, result: { prompts: prompts })
+      def send_prompts_list(request_id, params = {})
+        page, next_cursor = paginate(session.registered_prompts, cursor: params["cursor"])
+
+        result = { prompts: page.map(&:to_h) }
+        result[:nextCursor] = next_cursor if next_cursor
+
+        send_jsonrpc_response(request_id, result: result)
+      rescue Server::CursorError => e
+        send_jsonrpc_error(request_id, :invalid_params, e.message)
       end
 
       def send_prompts_get(request_id, prompt_name, params)

data/lib/action_mcp/server/resources.rb

@@ -3,73 +3,23 @@
 module ActionMCP
   module Server
     module Resources
-      # Default page size for cursor-based pagination
-      RESOURCES_PAGE_SIZE = 100
-
       # Send list of concrete resources to the client.
       # Aggregates resources from templates that implement self.list.
       #
       # @param request_id [String, Integer] The ID of the request to respond to
       # @param params [Hash] Optional params including "cursor" for pagination
       def send_resources_list(request_id, params = {})
-        templates = session.registered_resource_templates
-
-        # Collect resources from templates that implement list
-        all_resources = []
-        seen_uris = {}
-
-        templates.each do |template_class|
-          next unless template_class.lists_resources?
-
-          begin
-            listed = template_class.list(session: session)
-          rescue StandardError => e
-            Rails.logger.error "[MCP] Error listing resources from #{template_class.name}: #{e.message}"
-            next
-          end
-
-          unless listed.is_a?(Array)
-            Rails.logger.warn "[MCP] #{template_class.name}.list returned #{listed.class}, expected Array; skipping"
-            next
-          end
+        all_resources = collect_resources(request_id)
+        return unless all_resources # nil means an error was already sent
 
-          listed.each do |resource|
-            unless resource.is_a?(ActionMCP::Resource)
-              Rails.logger.warn "[MCP] #{template_class.name}.list returned non-Resource: #{resource.class}"
-              next
-            end
+        page, next_cursor = paginate(all_resources, cursor: params["cursor"])
 
-            # Validate the listed URI is readable by the declaring template
-            unless template_class.readable_uri?(resource.uri)
-              Rails.logger.warn "[MCP] #{template_class.name}.list returned URI not readable by its own template: #{resource.uri}"
-              next
-            end
-
-            # Deduplicate by URI
-            if (existing = seen_uris[resource.uri])
-              if existing == resource
-                # Identical duplicate, skip silently
-                next
-              else
-                # Conflicting metadata for same URI
-                send_jsonrpc_error(request_id, :invalid_params,
-                  "Resource URI collision: '#{resource.uri}' listed by multiple templates with conflicting metadata")
-                return
-              end
-            end
-
-            seen_uris[resource.uri] = resource
-            all_resources << resource
-          end
-        end
+        result = { resources: page.map(&:to_h) }
+        result[:nextCursor] = next_cursor if next_cursor
 
-        # Apply cursor-based pagination
-        result = paginate_resources(all_resources, params["cursor"])
-        if result == :invalid_cursor
-          send_jsonrpc_error(request_id, :invalid_params, "Invalid cursor value")
-          return
-        end
         send_jsonrpc_response(request_id, result: result)
+      rescue Server::CursorError => e
+        send_jsonrpc_error(request_id, :invalid_params, e.message)
       end
 
       # Send list of resource templates to the client
@@ -80,13 +30,14 @@ module ActionMCP
         templates = session.registered_resource_templates.map(&:to_h)
         log_resource_templates
 
-        # Apply cursor-based pagination
-        result = paginate_templates(templates, params["cursor"])
-        if result == :invalid_cursor
-          send_jsonrpc_error(request_id, :invalid_params, "Invalid cursor value")
-          return
-        end
+        page, next_cursor = paginate(templates, cursor: params["cursor"])
+
+        result = { resourceTemplates: page }
+        result[:nextCursor] = next_cursor if next_cursor
+
         send_jsonrpc_response(request_id, result: result)
+      rescue Server::CursorError => e
+        send_jsonrpc_error(request_id, :invalid_params, e.message)
       end
 
       # Read and return the contents of a resource
@@ -159,82 +110,73 @@ module ActionMCP
 
       private
 
+      # Collect all concrete resources from templates that implement list.
+      # Returns nil if a URI collision error was sent.
+      # @return [Array<ActionMCP::Resource>, nil]
+      def collect_resources(request_id)
+        all_resources = []
+        seen_uris = {}
+
+        session.registered_resource_templates.each do |template_class|
+          next unless template_class.lists_resources?
+
+          begin
+            listed = template_class.list(session: session)
+          rescue StandardError => e
+            Rails.logger.error "[MCP] Error listing resources from #{template_class.name}: #{e.message}"
+            next
+          end
+
+          unless listed.is_a?(Array)
+            Rails.logger.warn "[MCP] #{template_class.name}.list returned #{listed.class}, expected Array; skipping"
+            next
+          end
+
+          listed.each do |resource|
+            unless resource.is_a?(ActionMCP::Resource)
+              Rails.logger.warn "[MCP] #{template_class.name}.list returned non-Resource: #{resource.class}"
+              next
+            end
+
+            unless template_class.readable_uri?(resource.uri)
+              Rails.logger.warn "[MCP] #{template_class.name}.list returned URI not readable by its own template: #{resource.uri}"
+              next
+            end
+
+            if (existing = seen_uris[resource.uri])
+              if existing == resource
+                next
+              else
+                send_jsonrpc_error(request_id, :invalid_params,
+                  "Resource URI collision: '#{resource.uri}' listed by multiple templates with conflicting metadata")
+                return nil
+              end
+            end
+
+            seen_uris[resource.uri] = resource
+            all_resources << resource
+          end
+        end
+
+        all_resources
+      end
+
       # Normalize a content object to MCP ReadResourceResult content shape.
       #
-      # @return [Hash] with keys: uri, mimeType, and text or blob
+      # @return [Hash] with keys: uri, mimeType, text or blob, and optional _meta
       def normalize_read_content(content, _uri)
         case content
         when ActionMCP::Content::Resource
           inner = { uri: content.uri, mimeType: content.mime_type }
           inner[:text] = content.text if content.text
           inner[:blob] = content.blob if content.blob
+          inner[:_meta] = content.meta if content.meta && !content.meta.empty?
           inner
         else
           content.respond_to?(:to_h) ? content.to_h : content
         end
       end
 
-      # Paginate a list of resources with cursor support.
-      #
-      # @param resources [Array<ActionMCP::Resource>] All resources
-      # @param cursor [String, nil] Base64-encoded offset cursor
-      # @return [Hash] Result hash with :resources and optional :nextCursor
-      def paginate_resources(resources, cursor)
-        offset = decode_cursor(cursor)
-        return :invalid_cursor if offset == :invalid
-
-        page = resources[offset, RESOURCES_PAGE_SIZE] || []
-
-        result = { resources: page.map(&:to_h) }
-
-        next_offset = offset + RESOURCES_PAGE_SIZE
-        if next_offset < resources.size
-          result[:nextCursor] = encode_cursor(next_offset)
-        end
-
-        result
-      end
-
-      # Paginate a list of templates with cursor support.
-      #
-      # @param templates [Array<Hash>] All template hashes
-      # @param cursor [String, nil] Base64-encoded offset cursor
-      # @return [Hash] Result hash with :resourceTemplates and optional :nextCursor
-      def paginate_templates(templates, cursor)
-        offset = decode_cursor(cursor)
-        return :invalid_cursor if offset == :invalid
-
-        page = templates[offset, RESOURCES_PAGE_SIZE] || []
-
-        result = { resourceTemplates: page }
-
-        next_offset = offset + RESOURCES_PAGE_SIZE
-        if next_offset < templates.size
-          result[:nextCursor] = encode_cursor(next_offset)
-        end
-
-        result
-      end
-
-      # Decode a cursor string to a non-negative integer offset.
-      # Returns 0 for nil cursors, :invalid for malformed/negative/non-string values.
-      def decode_cursor(cursor)
-        return 0 if cursor.nil?
-        return :invalid unless cursor.is_a?(String) && !cursor.empty?
-
-        decoded = Base64.strict_decode64(cursor)
-        return :invalid unless decoded.match?(/\A\d+\z/)
-
-        decoded.to_i
-      rescue ArgumentError
-        :invalid
-      end
-
-      # Encode an integer offset as a cursor string.
-      def encode_cursor(offset)
-        Base64.strict_encode64(offset.to_s)
-      end
-
       # Log all registered resource templates
       def log_resource_templates
         Rails.logger.debug "Registered Resource Templates: #{ActionMCP::ResourceTemplatesRegistry.resource_templates.keys}"

data/lib/action_mcp/server/tasks.rb

@@ -37,25 +37,21 @@ module ActionMCP
         send_jsonrpc_response(request_id, result: task.to_task_result)
       end
 
-      # List tasks for the session with optional pagination
+      # List tasks for the session with keyset pagination.
+      # Tasks always paginate (AR-backed, can grow unbounded).
+      # Cursor is the last task id from the previous page. We resolve it
+      # through AR so the boundary matches the recent scope exactly.
       # @param request_id [String, Integer] JSON-RPC request ID
       # @param cursor [String, nil] Pagination cursor
       def send_tasks_list(request_id, cursor: nil)
-        # Parse cursor if provided
-        offset = cursor.to_i if cursor.present?
-        offset ||= 0
-        limit = 50
+        page, next_cursor = paginate_tasks_by_recent(cursor: cursor, page_size: pagination_page_size || 50)
 
-        tasks = session.tasks.recent.offset(offset).limit(limit + 1)
-        has_more = tasks.length > limit
-        tasks = tasks.first(limit)
-
-        result = {
-          tasks: tasks.map(&:to_task_data)
-        }
-        result[:nextCursor] = (offset + limit).to_s if has_more
+        result = { tasks: page.map(&:to_task_data) }
+        result[:nextCursor] = next_cursor if next_cursor
 
         send_jsonrpc_response(request_id, result: result)
+      rescue Server::CursorError => e
+        send_jsonrpc_error(request_id, :invalid_params, e.message)
       end
 
       # Cancel a task
@@ -120,6 +116,30 @@ module ActionMCP
         end
         task
       end
+
+      def paginate_tasks_by_recent(cursor:, page_size:)
+        relation = session.tasks.recent
+
+        if cursor
+          cursor_task = find_task_cursor(cursor)
+          relation = relation.before_recent(cursor_task)
+        end
+
+        page = relation.limit(page_size + 1).to_a
+        has_more = page.size > page_size
+        items = has_more ? page.first(page_size) : page
+        next_cursor = has_more ? encode_keyset_cursor(items.last, :id) : nil
+
+        [ items, next_cursor ]
+      end
+
+      def find_task_cursor(cursor)
+        task_id = decode_keyset_cursor(cursor)
+        task = session.tasks.select(:id, :created_at).find_by(id: task_id)
+        raise Server::CursorError, "Invalid cursor" unless task
+
+        task
+      end
     end
   end
 end

data/lib/action_mcp/server/tools.rb

@@ -5,35 +5,24 @@ module ActionMCP
     module Tools
       def send_tools_list(request_id, params = {})
         protocol_version = session.protocol_version
-        # Extract progress token from _meta if provided
         progress_token = params.dig("_meta", "progressToken")
 
-        # Send initial progress notification if token is provided
         if progress_token
-          send_progress_notification(
-            progressToken: progress_token,
-            progress: 0,
-            message: "Starting tools list retrieval"
-          )
+          send_progress_notification(progressToken: progress_token, progress: 0, message: "Starting tools list retrieval")
         end
 
-        # Use session's registered tools instead of global registry
-        registered_tools = session.registered_tools
+        page, next_cursor = paginate(session.registered_tools, cursor: params["cursor"])
 
-        tools = registered_tools.map do |tool_class|
-          tool_class.to_h(protocol_version: protocol_version)
-        end
+        result = { tools: page.map { |t| t.to_h(protocol_version: protocol_version) } }
+        result[:nextCursor] = next_cursor if next_cursor
 
-        # Send completion progress notification if token is provided
         if progress_token
-          send_progress_notification(
-            progressToken: progress_token,
-            progress: 100,
-            message: "Tools list retrieval complete"
-          )
+          send_progress_notification(progressToken: progress_token, progress: 100, message: "Tools list retrieval complete")
         end
 
-        send_jsonrpc_response(request_id, result: { tools: tools })
+        send_jsonrpc_response(request_id, result: result)
+      rescue Server::CursorError => e
+        send_jsonrpc_error(request_id, :invalid_params, e.message)
       end
 
       def send_tools_call(request_id, tool_name, arguments, _meta = {})

data/lib/action_mcp/server/transport_handler.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "pagination"
 require_relative "response_collector"
 require_relative "base_messaging"
 
@@ -11,6 +12,7 @@ module ActionMCP
       delegate :initialize!, :initialized?, to: :session
       delegate :read, :write, to: :session
 
+      include  Pagination
       include  MessagingService
       include  Capabilities
       include  Tools

data/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

data/lib/action_mcp/version.rb

@@ -2,7 +2,7 @@
 
 require_relative "gem_version"
 module ActionMCP
-  VERSION = "0.108.0"
+  VERSION = "0.109.0"
 
   class << self
     alias version gem_version

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: actionmcp
 version: !ruby/object:Gem::Version
-  version: 0.108.0
+  version: 0.109.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -218,6 +218,7 @@ files:
 - lib/action_mcp/server/base_session_store.rb
 - lib/action_mcp/server/capabilities.rb
 - lib/action_mcp/server/elicitation.rb
+- lib/action_mcp/server/elicitation_request.rb
 - lib/action_mcp/server/error_aware.rb
 - lib/action_mcp/server/error_handling.rb
 - lib/action_mcp/server/handlers/logging_handler.rb
@@ -228,6 +229,7 @@ files:
 - lib/action_mcp/server/handlers/tool_handler.rb
 - lib/action_mcp/server/json_rpc_handler.rb
 - lib/action_mcp/server/messaging_service.rb
+- lib/action_mcp/server/pagination.rb
 - lib/action_mcp/server/prompts.rb
 - lib/action_mcp/server/registry_management.rb
 - lib/action_mcp/server/resources.rb
@@ -241,6 +243,7 @@ files:
 - lib/action_mcp/server/test_session_store.rb
 - lib/action_mcp/server/tools.rb
 - lib/action_mcp/server/transport_handler.rb
+- lib/action_mcp/server/url_elicitation_request.rb
 - lib/action_mcp/server/volatile_session_store.rb
 - lib/action_mcp/string_array.rb
 - lib/action_mcp/tagged_stream_logging.rb