actionmcp 0.107.1 → 0.109.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be05e5d56452910d6c725b15041b68b41b12830f38bd5661ba5c363403ef8df7
-  data.tar.gz: 4ead1672cb76e8c1ff4057062f6396cc68d290abf0ab7c0e0562f2d438ddd8a7
+  metadata.gz: dbc03b1ba75f2efaf3c94ff2e664d3ca4e21013e8c55651f1fccff0b8c4e889b
+  data.tar.gz: 1576d864115954653182d05080352a28b7be2a11c8fb376f0e426503a320eb7f
 SHA512:
-  metadata.gz: f0d3ed2611e1347f24a1b6422c9d1628d85cbce23e9b9db13996aca9d9133d03e50bf6b45b26a0f4afa5795314b5285e70e545ecfd2e40ef71294bfc13241b03
-  data.tar.gz: fbdf20f97d3324d4adc6d9905ff45dc662ea9a039e6682e884a614fb02a14726b32c17c84785856188d9dea2babbe7aefd9d8d2d0c1c4171facaf69d1dcd02ce
+  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).
@@ -712,10 +731,12 @@ This will create:
 
 ## Authentication with Gateway
 
-ActionMCP provides a Gateway system for handling authentication. The Gateway allows you to authenticate users and make them available throughout your MCP components.
+ActionMCP provides a Gateway system for handling authentication. The Gateway allows you to authenticate users and make them available throughout your MCP components. For the full gateway reference including identifier classes, session persistence, profile switching, and production hardening tips, see **[GATEWAY.md](GATEWAY.md)**.
 
 ActionMCP uses a Gateway pattern with pluggable identifiers for authentication. You can implement custom authentication strategies using session-based auth, API keys, bearer tokens, or integrate with existing authentication systems like Warden, Devise, or external OAuth providers.
 
+> **Note:** Auth errors return HTTP 200 with a JSON-RPC error payload (not HTTP 401). This is correct per the MCP specification — all MCP communication uses JSON-RPC over HTTP, and protocol-level errors are expressed within the JSON-RPC envelope. The `initialize` request bypasses authentication per MCP spec.
+
 ### Creating an ApplicationGateway
 
 When you run the install generator, it creates an `ApplicationGateway` class:
@@ -986,26 +1007,68 @@ class ToolTest < ActiveSupport::TestCase
   include ActionMCP::TestHelper
 
   test "CalculateSumTool returns the correct sum" do
-    assert_tool_findable("calculate_sum")
-    result = execute_tool("calculate_sum", a: 5, b: 10)
-    assert_tool_output(result, "15.0")
+    assert_mcp_tool_findable("calculate_sum")
+    result = execute_mcp_tool("calculate_sum", a: 5, b: 10)
+    assert_mcp_tool_output("15.0", result)
   end
 
   test "AnalyzeCodePrompt returns the correct analysis" do
-    assert_prompt_findable("analyze_code")
-    result = execute_prompt("analyze_code", language: "Ruby", code: "def hello; puts 'Hello, world!'; end")
-    assert_equal "Analyzing Ruby code: def hello; puts 'Hello, world!'; end", assert_prompt_output(result)
+    assert_mcp_prompt_findable("analyze_code")
+    result = execute_mcp_prompt("analyze_code", language: "Ruby", code: "def hello; puts 'Hello, world!'; end")
+    assert_mcp_prompt_output("Analyzing Ruby code: def hello; puts 'Hello, world!'; end", result)
   end
 end
 ```
 
-The TestHelper provides several assertion methods:
-- `assert_tool_findable(name)` - Verifies a tool exists and is registered
-- `assert_prompt_findable(name)` - Verifies a prompt exists and is registered
-- `execute_tool(name, **args)` - Executes a tool with arguments
-- `execute_prompt(name, **args)` - Executes a prompt with arguments
-- `assert_tool_output(result, expected)` - Asserts tool output matches expected text
-- `assert_prompt_output(result)` - Extracts and returns prompt output for assertions
+The TestHelper provides several assertion and execution methods:
+
+**Tools:**
+- `assert_mcp_tool_findable(name)` - Verifies a tool exists and is registered
+- `execute_mcp_tool(name, **args)` - Executes a tool with arguments and asserts success
+- `execute_mcp_tool_with_error(name, **args)` - Executes a tool without asserting success (for testing error cases)
+- `assert_mcp_tool_output(expected, response)` - Asserts tool output matches expected content
+
+**Prompts:**
+- `assert_mcp_prompt_findable(name)` - Verifies a prompt exists and is registered
+- `execute_mcp_prompt(name, **args)` - Executes a prompt with arguments
+- `assert_mcp_prompt_output(expected, response)` - Asserts prompt output matches expected content
+
+**Resource Templates:**
+- `assert_mcp_resource_template_findable(name)` - Verifies a resource template exists and is registered
+- `resolve_mcp_resource(uri)` - Resolves a resource URI and asserts success
+- `resolve_mcp_resource_with_error(uri)` - Resolves a resource URI without asserting success (for testing error cases)
+
+**General:**
+- `assert_mcp_error_code(code, response)` - Asserts a specific JSON-RPC error code
+
+### Testing Resource Templates
+
+```ruby
+require "test_helper"
+require "action_mcp/test_helper"
+
+class ProductResourceTest < ActiveSupport::TestCase
+  include ActionMCP::TestHelper
+
+  test "product template is registered" do
+    assert_mcp_resource_template_findable("products")
+  end
+
+  test "resolves a product resource by URI" do
+    resp = resolve_mcp_resource("ecommerce://products/1")
+
+    assert resp.success?
+    assert_not_empty resp.contents
+    assert_equal "application/json", resp.contents.first.mime_type
+  end
+
+  test "returns error for nonexistent product" do
+    resp = resolve_mcp_resource_with_error("ecommerce://products/0")
+
+    assert resp.is_error
+  end
+end
+```
 
 ## Inspecting Your MCP Server
 

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
 
@@ -70,6 +71,11 @@ module ActionMCP
         end
       end
 
+      if session.nil?
+        id = jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil
+        return render_not_found("Session not found.", id)
+      end
+
       if session.new_record?
         session.save!
         response.headers[MCP_SESSION_ID_HEADER] = session.id
@@ -90,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
@@ -123,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
@@ -324,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/app/models/action_mcp/session.rb

@@ -172,6 +172,7 @@ module ActionMCP
     def register_tool(tool_class_or_name)
       tool_name = normalize_name(tool_class_or_name, :tool)
       return false unless tool_exists?(tool_name)
+      return true if uses_all_tools?
 
       self.tool_registry ||= []
       unless self.tool_registry.include?(tool_name)
@@ -184,8 +185,13 @@ module ActionMCP
 
     def unregister_tool(tool_class_or_name)
       tool_name = normalize_name(tool_class_or_name, :tool)
-      self.tool_registry ||= []
 
+      if uses_all_tools?
+        return unless tool_exists?(tool_name)
+        expand_tool_registry!
+      end
+
+      self.tool_registry ||= []
       return unless self.tool_registry.delete(tool_name)
 
       save!
@@ -195,6 +201,7 @@ module ActionMCP
     def register_prompt(prompt_class_or_name)
       prompt_name = normalize_name(prompt_class_or_name, :prompt)
       return false unless prompt_exists?(prompt_name)
+      return true if uses_all_prompts?
 
       self.prompt_registry ||= []
       unless self.prompt_registry.include?(prompt_name)
@@ -207,8 +214,13 @@ module ActionMCP
 
     def unregister_prompt(prompt_class_or_name)
       prompt_name = normalize_name(prompt_class_or_name, :prompt)
-      self.prompt_registry ||= []
 
+      if uses_all_prompts?
+        return unless prompt_exists?(prompt_name)
+        expand_prompt_registry!
+      end
+
+      self.prompt_registry ||= []
       return unless self.prompt_registry.delete(prompt_name)
 
       save!
@@ -218,6 +230,7 @@ module ActionMCP
     def register_resource_template(template_class_or_name)
       template_name = normalize_name(template_class_or_name, :resource_template)
       return false unless resource_template_exists?(template_name)
+      return true if uses_all_resources?
 
       self.resource_registry ||= []
       unless self.resource_registry.include?(template_name)
@@ -230,8 +243,13 @@ module ActionMCP
 
     def unregister_resource_template(template_class_or_name)
       template_name = normalize_name(template_class_or_name, :resource_template)
-      self.resource_registry ||= []
 
+      if uses_all_resources?
+        return unless resource_template_exists?(template_name)
+        expand_resource_registry!
+      end
+
+      self.resource_registry ||= []
       return unless self.resource_registry.delete(template_name)
 
       save!
@@ -348,6 +366,20 @@ module ActionMCP
       self.resource_registry = [ "*" ]
     end
 
+    # Expand wildcard registries to explicit name lists so individual
+    # entries can be removed without breaking the wildcard check.
+    def expand_tool_registry!
+      self.tool_registry = ActionMCP.configuration.filtered_tools.map(&:name)
+    end
+
+    def expand_prompt_registry!
+      self.prompt_registry = ActionMCP.configuration.filtered_prompts.map(&:name)
+    end
+
+    def expand_resource_registry!
+      self.resource_registry = ActionMCP.configuration.filtered_resources.map(&:name)
+    end
+
     def normalize_name(class_or_name, type)
       case class_or_name
       when String

data/db/migrate/20250512154359_consolidated_migration.rb

@@ -1,113 +1,102 @@
 # frozen_string_literal: true
 
-class ConsolidatedMigration < ActiveRecord::Migration[8.0]
-  def change
-    # Only create tables if they don't exist to avoid deleting existing data
-
-    # Create sessions table
-    unless table_exists?(:action_mcp_sessions)
-      create_table :action_mcp_sessions, id: :string do |t|
-        t.string :role, null: false, default: 'server', comment: 'The role of the session'
-        t.string :status, null: false, default: 'pre_initialize'
-        t.datetime :ended_at, comment: 'The time the session ended'
-        t.string :protocol_version
-        t.json :server_capabilities, comment: 'The capabilities of the server'
-        t.json :client_capabilities, comment: 'The capabilities of the client'
-        t.json :server_info, comment: 'The information about the server'
-        t.json :client_info, comment: 'The information about the client'
-        t.boolean :initialized, null: false, default: false
-        t.integer :messages_count, null: false, default: 0
-        t.json :tool_registry, default: []
-        t.json :prompt_registry, default: []
-        t.json :resource_registry, default: []
-        t.timestamps
-      end
-    end
-
-    # Create session messages table
-    unless table_exists?(:action_mcp_session_messages)
-      create_table :action_mcp_session_messages do |t|
-        t.references :session, null: false,
-                               foreign_key: { to_table: :action_mcp_sessions,
-                                              on_delete: :cascade,
-                                              on_update: :cascade,
-                                              name: 'fk_action_mcp_session_messages_session_id' }, type: :string
-        t.string :direction, null: false, comment: 'The message recipient', default: 'client'
-        t.string :message_type, null: false, comment: 'The type of the message'
-        t.string :jsonrpc_id
-        t.json :message_json
-        t.boolean :is_ping, default: false, null: false, comment: 'Whether the message is a ping'
-        t.boolean :request_acknowledged, default: false, null: false
-        t.boolean :request_cancelled, null: false, default: false
-        t.timestamps
-      end
-    end
-
-    # Create session subscriptions table
-    unless table_exists?(:action_mcp_session_subscriptions)
-      create_table :action_mcp_session_subscriptions do |t|
-        t.references :session,
-                     null: false,
-                     foreign_key: { to_table: :action_mcp_sessions, on_delete: :cascade },
-                     type: :string
-        t.string :uri, null: false
-        t.datetime :last_notification_at
-        t.timestamps
-      end
-    end
-
-    # Add missing columns to existing tables if they exist
-
-    # For action_mcp_sessions
-    if table_exists?(:action_mcp_sessions)
-      unless column_exists?(:action_mcp_sessions, :tool_registry)
-        add_column :action_mcp_sessions, :tool_registry, :json, default: []
-      end
-
-      unless column_exists?(:action_mcp_sessions, :prompt_registry)
-        add_column :action_mcp_sessions, :prompt_registry, :json, default: []
-      end
-
-      unless column_exists?(:action_mcp_sessions, :resource_registry)
-        add_column :action_mcp_sessions, :resource_registry, :json, default: []
-      end
+class ConsolidatedMigration < ActiveRecord::Migration[8.1]
+  def up
+    create_table :action_mcp_sessions, id: :string, if_not_exists: true do |t|
+      t.string :role, null: false, default: "server", comment: "The role of the session"
+      t.string :status, null: false, default: "pre_initialize"
+      t.datetime :ended_at, comment: "The time the session ended"
+      t.string :protocol_version
+      t.json :server_capabilities, comment: "The capabilities of the server"
+      t.json :client_capabilities, comment: "The capabilities of the client"
+      t.json :server_info, comment: "The information about the server"
+      t.json :client_info, comment: "The information about the client"
+      t.boolean :initialized, null: false, default: false
+      t.integer :messages_count, null: false, default: 0
+      t.json :tool_registry, default: []
+      t.json :prompt_registry, default: []
+      t.json :resource_registry, default: []
+      t.json :consents, default: {}, null: false
+      t.json :session_data, default: {}, null: false
+      t.timestamps
     end
 
-    # For action_mcp_session_messages
-    return unless table_exists?(:action_mcp_session_messages)
-
-    unless column_exists?(:action_mcp_session_messages, :is_ping)
-      add_column :action_mcp_session_messages, :is_ping, :boolean, default: false, null: false,
-                                                                   comment: 'Whether the message is a ping'
-    end
-
-    unless column_exists?(:action_mcp_session_messages, :request_acknowledged)
-      add_column :action_mcp_session_messages, :request_acknowledged, :boolean, default: false, null: false
+    add_column :action_mcp_sessions, :consents, :json, default: {}, null: false unless column_exists?(:action_mcp_sessions, :consents)
+    add_column :action_mcp_sessions, :session_data, :json, default: {}, null: false unless column_exists?(:action_mcp_sessions, :session_data)
+
+    create_table :action_mcp_session_messages, if_not_exists: true do |t|
+      t.references :session, null: false,
+                             foreign_key: { to_table: :action_mcp_sessions,
+                                            on_delete: :cascade,
+                                            on_update: :cascade,
+                                            name: "fk_action_mcp_session_messages_session_id" },
+                             type: :string
+      t.string :direction, null: false, comment: "The message recipient", default: "client"
+      t.string :message_type, null: false, comment: "The type of the message"
+      t.string :jsonrpc_id
+      t.json :message_json
+      t.boolean :is_ping, default: false, null: false, comment: "Whether the message is a ping"
+      t.boolean :request_acknowledged, default: false, null: false
+      t.boolean :request_cancelled, null: false, default: false
+      t.timestamps
     end
 
-    unless column_exists?(:action_mcp_session_messages, :request_cancelled)
-      add_column :action_mcp_session_messages, :request_cancelled, :boolean, null: false, default: false
+    add_column :action_mcp_session_messages, :is_ping, :boolean, default: false, null: false unless column_exists?(:action_mcp_session_messages, :is_ping)
+    add_column :action_mcp_session_messages, :request_acknowledged, :boolean, default: false, null: false unless column_exists?(:action_mcp_session_messages, :request_acknowledged)
+    add_column :action_mcp_session_messages, :request_cancelled, :boolean, default: false, null: false unless column_exists?(:action_mcp_session_messages, :request_cancelled)
+
+    create_table :action_mcp_session_subscriptions, if_not_exists: true do |t|
+      t.references :session, null: false,
+                             foreign_key: { to_table: :action_mcp_sessions, on_delete: :cascade },
+                             type: :string
+      t.string :uri, null: false
+      t.datetime :last_notification_at
+      t.timestamps
     end
 
-    if column_exists?(:action_mcp_session_messages, :message_text)
-      remove_column :action_mcp_session_messages, :message_text
+    create_table :action_mcp_session_tasks, id: :string, if_not_exists: true do |t|
+      t.references :session, null: false,
+                             foreign_key: { to_table: :action_mcp_sessions,
+                                            on_delete: :cascade,
+                                            on_update: :cascade,
+                                            name: "fk_action_mcp_session_tasks_session_id" },
+                             type: :string
+      t.string :status, null: false, default: "working"
+      t.string :status_message
+      t.string :request_method, comment: "e.g., tools/call, prompts/get"
+      t.string :request_name, comment: "e.g., tool name, prompt name"
+      t.json :request_params, comment: "Original request params"
+      t.json :result_payload, comment: "Final result data"
+      t.integer :ttl, comment: "Time to live in milliseconds"
+      t.integer :poll_interval, comment: "Suggested polling interval in milliseconds"
+      t.datetime :last_updated_at, null: false
+      t.json :continuation_state, default: {}
+      t.integer :progress_percent, comment: "Task progress as percentage 0-100"
+      t.string :progress_message, comment: "Human-readable progress message"
+      t.datetime :last_step_at
+      t.timestamps
+
+      t.index :status
+      t.index %i[session_id status]
+      t.index :created_at
     end
 
-    return unless column_exists?(:action_mcp_session_messages, :direction)
-
-    # SQLite3 doesn't support changing column comments
-    return unless connection.adapter_name.downcase != 'sqlite'
-
-    change_column_comment :action_mcp_session_messages, :direction, 'The message recipient'
-  end
-
-  private
-
-  def table_exists?(table_name)
-    ActionMCP::ApplicationRecord.connection.table_exists?(table_name)
-  end
-
-  def column_exists?(table_name, column_name)
-    ActionMCP::ApplicationRecord.connection.column_exists?(table_name, column_name)
+    add_column :action_mcp_session_tasks, :continuation_state, :json, default: {} unless column_exists?(:action_mcp_session_tasks, :continuation_state)
+    add_column :action_mcp_session_tasks, :progress_percent, :integer unless column_exists?(:action_mcp_session_tasks, :progress_percent)
+    add_column :action_mcp_session_tasks, :progress_message, :string unless column_exists?(:action_mcp_session_tasks, :progress_message)
+    add_column :action_mcp_session_tasks, :last_step_at, :datetime unless column_exists?(:action_mcp_session_tasks, :last_step_at)
+
+    # Remove deprecated tables if they exist
+    drop_table :action_mcp_oauth_clients, if_exists: true
+    drop_table :action_mcp_oauth_tokens, if_exists: true
+    drop_table :action_mcp_sse_events, if_exists: true
+    drop_table :action_mcp_session_resources, if_exists: true
+
+    # Remove deprecated columns if they exist
+    remove_column :action_mcp_sessions, :oauth_access_token if column_exists?(:action_mcp_sessions, :oauth_access_token)
+    remove_column :action_mcp_sessions, :oauth_refresh_token if column_exists?(:action_mcp_sessions, :oauth_refresh_token)
+    remove_column :action_mcp_sessions, :oauth_token_expires_at if column_exists?(:action_mcp_sessions, :oauth_token_expires_at)
+    remove_column :action_mcp_sessions, :oauth_user_context if column_exists?(:action_mcp_sessions, :oauth_user_context)
+    remove_column :action_mcp_sessions, :sse_event_counter if column_exists?(:action_mcp_sessions, :sse_event_counter)
   end
 end

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