actionmcp 0.108.0 → 0.110.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 917d5120acc0a5cb82cb4a9516a65e59370f922dfe2828670e1117a5d1d26934
-  data.tar.gz: a77bd78234661ee4ef52cafff59f5d6c856e94728bca98832c926928635e8e94
+  metadata.gz: b49e1bd20853c60ec17b35b3ba822a275b8258800ce615707dcf85ecaa606dc8
+  data.tar.gz: c1abbbe666dbea818abde461aaae5d65f867700fa96e6d5c8011b12b10be1fcd
 SHA512:
-  metadata.gz: 6110ec397f08c3e8cbc2fe54a20f22bae3f600ad005e82f254bf6eeea7ba07c3bee1fc28a337a6263725fff213fdcbf092b08000285bdff0958b16fa5a958ccf
-  data.tar.gz: f57f192f165bf2a5d44d18189e6107eb0ab951eeaf4f88ddc92fa2e3208bcc4bfe7a7d6aed9cd0e01b2951d07e6e8b2826f75e6033054130b304707b0bec03b1
+  metadata.gz: 984a0a14b69ed4684ee7054db880320711c18613d4f5242922ac6eeb6946fb4c21954831c4ac935796f234f3abf8e691bc24c8ab219910fce8f9dd7a77600828
+  data.tar.gz: 8356febeb0097488d56a50e42160cf09c5e9be1e9952bf170fefb6f56e991079efc183bbca2e2080d2d3d9406c21a57e9211888eee405171bc4730903904559e

data/README.md

@@ -315,7 +315,7 @@ class BatchIndexTool < ApplicationMCPTool
 end
 ```
 
-Call it as a task from a client by adding `_meta.task` (creates a Task record and runs the tool via `ToolExecutionJob`):
+Call it as a task from a client by adding top-level `task` params (creates a Task record and runs the tool via `ToolExecutionJob`):
 
 ```json
 {
@@ -325,12 +325,27 @@ Call it as a task from a client by adding `_meta.task` (creates a Task record an
   "params": {
     "name": "batch_index",
     "arguments": { "items": ["a", "b", "c"] },
-    "_meta": { "task": { "ttl": 120000, "pollInterval": 2000 } }
+    "task": { "ttl": 120000 }
   }
 }
 ```
 
-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 with `tasks/result`.
+By default, `tasks/result` uses spec-aligned blocking HTTP: if the task is still working, the request waits until the task reaches `completed`, `failed`, `cancelled`, or `input_required`, then returns one JSON response. Configure the wait bounds for your Rails app:
+
+```ruby
+config.action_mcp.tasks_result_strategy = :blocking_http
+config.action_mcp.tasks_result_timeout = 30.seconds
+config.action_mcp.tasks_result_poll_interval = 0.25.seconds
+```
+
+Rails apps that cannot hold request workers open can opt into `:polling_only`, where clients must poll `tasks/get` until terminal or `input_required` before calling `tasks/result`. This is a deliberate MCP spec deviation:
+
+```ruby
+config.action_mcp.tasks_result_strategy = :polling_only
+```
+
+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 +506,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).
@@ -1263,6 +1297,21 @@ For comprehensive client documentation, including examples, session management,
 - **Implement proper authorization** in your tools and prompts
 - **Validate all inputs** using property definitions and Rails validations
 - **Use consent management** for sensitive operations
+- **Protect against DNS rebinding**: ActionMCP validates the `Origin` header on every request. If `Origin` is present and its host doesn't match the server's own host, the server returns HTTP 403 with a JSON-RPC error body (no `id`), as required by the MCP spec. Non-browser clients (Claude Desktop, CLI tools) don't send `Origin` and are unaffected. To allow additional trusted origins, configure `allowed_origins`:
+
+  ```ruby
+  # config/initializers/action_mcp.rb
+  ActionMCP.configure do |config|
+    config.allowed_origins = ["app.example.com", "api.example.com"]
+  end
+  ```
+
+  For defence-in-depth, also configure Rails' `ActionDispatch::HostAuthorization` to restrict which `Host` headers are accepted (a separate check against host-header injection):
+
+  ```ruby
+  # config/environments/production.rb
+  config.hosts = ["api.example.com"]
+  ```
 
 ### Performance
 

data/app/controllers/action_mcp/application_controller.rb

@@ -11,6 +11,9 @@ module ActionMCP
     include JSONRPC_Rails::ControllerHelpers
     include ActionController::Instrumentation
 
+    # Origin validation is enforced by ActionMCP::Middleware::OriginValidation
+    # (see engine.rb) so invalid requests are rejected before routing.
+
     # Provides the ActionMCP::Session for the current request.
     # Handles finding existing sessions via header/param or initializing a new one.
     # Specific controllers/handlers might need to enforce session ID presence based on context.
@@ -34,6 +37,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 +99,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 +132,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 +333,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/jobs/action_mcp/tool_execution_job.rb

@@ -53,6 +53,7 @@ module ActionMCP
       session = task.session
       unless session
         task.update(status_message: "Session not found")
+        task.result_payload = { code: -32_603, message: "Session not found" }
         task.mark_failed!
         return nil
       end
@@ -64,6 +65,10 @@ module ActionMCP
       tool_class = session.registered_tools.find { |t| t.tool_name == tool_name }
       unless tool_class
         @task.update(status_message: "Tool '#{tool_name}' not found")
+        @task.result_payload = {
+          code: -32_601,
+          message: "Tool '#{tool_name}' not found"
+        }
         @task.mark_failed!
         return nil
       end
@@ -101,12 +106,13 @@ module ActionMCP
     def update_task_result(task, result)
       return if task.terminal? # Guard against double-complete
 
-      if result.is_error
-        task.result_payload = result.to_h
+      payload = result.to_h
+      if result.is_error || payload[:isError] || payload["isError"]
+        task.result_payload = payload
         task.status_message = result.respond_to?(:error_message) ? result.error_message : "Tool returned error"
         task.mark_failed!
       else
-        task.result_payload = result.to_h
+        task.result_payload = payload
         task.record_step!(:completed)
         task.complete!
       end
@@ -123,6 +129,10 @@ module ActionMCP
 
       task.update(
         status_message: "Job failed: #{error.message}",
+        result_payload: {
+          code: -32_603,
+          message: "Job failed: #{error.message}"
+        },
         continuation_state: {
           step: :failed,
           error: { class: error.class.name, message: error.message },

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

@@ -52,6 +52,8 @@ module ActionMCP
     #   input_required -> completed | failed | cancelled
     #
     class Task < ApplicationRecord
+      RELATED_TASK_META_KEY = "io.modelcontextprotocol/related-task"
+
       self.table_name = "action_mcp_session_tasks"
 
       attribute :id, :string, default: -> { SecureRandom.uuid_v7 }
@@ -68,7 +70,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
@@ -131,6 +141,10 @@ module ActionMCP
         status.in?(%w[completed failed cancelled])
       end
 
+      def result_ready?
+        terminal? || input_required?
+      end
+
       # Check if task is in a non-terminal state
       def non_terminal?
         !terminal?
@@ -140,32 +154,73 @@ module ActionMCP
       # @return [Hash] Task data for JSON-RPC responses
       def to_task_data
         data = {
-          id: id,
+          taskId: id,
           status: status,
-          lastUpdatedAt: last_updated_at.iso8601(3)
+          createdAt: created_at.iso8601(3),
+          lastUpdatedAt: last_updated_at.iso8601(3),
+          ttl: ttl
         }
         data[:statusMessage] = status_message if status_message.present?
-
-        # Add progress if available (ActiveJob::Continuable support)
-        if progress_percent.present? || progress_message.present?
-          data[:progress] = {}.tap do |progress|
-            progress[:percent] = progress_percent if progress_percent.present?
-            progress[:message] = progress_message if progress_message.present?
-          end
-        end
+        data[:pollInterval] = poll_interval if poll_interval.present?
 
         data
       end
 
-      # Convert to full task result format
-      # @return [Hash] Complete task with result for tasks/result response
-      def to_task_result
+      def to_create_task_result
         {
           task: to_task_data,
-          result: result_payload
+          _meta: related_task_meta
         }
       end
 
+      # Convert to the original request's result payload for tasks/result.
+      # The result carries related-task metadata because its structure does not
+      # otherwise include the task identifier.
+      # @return [Hash] Result payload for tasks/result response
+      def to_task_result
+        payload = result_payload.is_a?(Hash) ? result_payload.deep_dup : {}
+        meta = payload.delete("_meta") || payload.delete(:_meta) || {}
+        meta = meta.to_h if meta.respond_to?(:to_h)
+        meta = {} unless meta.is_a?(Hash)
+
+        payload[:_meta] = meta.deep_merge(related_task_meta)
+        payload
+      end
+
+      def to_task_error
+        return unless result_payload.is_a?(Hash)
+
+        code = result_payload["code"] || result_payload[:code]
+        message = result_payload["message"] || result_payload[:message]
+        return unless code && message
+        return if result_payload.key?("content") || result_payload.key?(:content)
+        return if result_payload.key?("isError") || result_payload.key?(:isError)
+
+        error = { code: code, message: message }
+        data = result_payload["data"] || result_payload[:data]
+        error[:data] = data unless data.nil?
+        error
+      end
+
+      def related_task_meta
+        {
+          RELATED_TASK_META_KEY => {
+            "taskId" => id
+          }
+        }
+      end
+
+      def request_meta_with_related_task(meta = nil)
+        existing_meta =
+          if meta.respond_to?(:to_h)
+            meta.to_h.deep_dup
+          else
+            {}
+          end
+
+        existing_meta.deep_merge(related_task_meta)
+      end
+
       # Broadcast status change notification to the session
       # @param transition [StateMachines::Transition] The state transition that occurred
       def broadcast_status_change(transition = nil)

data/app/models/action_mcp/session.rb

@@ -114,7 +114,7 @@ module ActionMCP
       payload = {
         protocolVersion: protocol_version || ActionMCP::DEFAULT_PROTOCOL_VERSION,
         serverInfo: server_info,
-        capabilities: server_capabilities
+        capabilities: capabilities_for_protocol(server_capabilities)
       }
       # Add instructions at top level if configured
       instructions = ActionMCP.configuration.instructions
@@ -130,6 +130,23 @@ module ActionMCP
       super(parsed_json_attribute(value))
     end
 
+    def capabilities_for_protocol(capabilities)
+      parsed = parsed_json_attribute(capabilities)
+      filtered =
+        if parsed.respond_to?(:deep_dup)
+          parsed.deep_dup
+        elsif parsed
+          parsed.dup
+        else
+          {}
+        end
+      return filtered if protocol_version == "2025-11-25"
+
+      filtered.delete("tasks")
+      filtered.delete(:tasks)
+      filtered
+    end
+
     def initialize!
       # update the session initialized to true
       return false if initialized?

data/lib/action_mcp/apps.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  # Constants for the MCP Apps extension (ext-apps, SEP-1865, draft 2026-01-26).
+  # See: https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx
+  module Apps
+    EXTENSION_KEY = "io.modelcontextprotocol/ui"
+    VISIBILITY_VALUES = %w[model app].freeze
+    URI_SCHEME = %r{\Aui://\S+\z}
+    MIME_TYPE = MimeTypes::APP_HTML
+
+    # `_meta.ui.csp` directive keys per ext-apps spec.
+    CSP_KEYS = %i[connectDomains resourceDomains frameDomains baseUriDomains].freeze
+
+    # Accepts http/https origins only. Wildcard subdomain (`https://*.example.com`),
+    # ports, and paths are allowed. WebSocket origins (ws://, wss://) are not
+    # accepted by ActionMCP — declare them via `ws://` over fetch if you must.
+    ORIGIN_PATTERN = %r{\Ahttps?://[^\s"'<>]+\z}
+  end
+end

data/lib/action_mcp/capability.rb

@@ -32,6 +32,11 @@ module ActionMCP
 
     delegate :session_data, to: :session, allow_nil: true
 
+    # Returns true when the connected client advertises the MCP Apps UI extension.
+    def client_supports_ui?
+      !session&.client_capabilities&.dig("extensions", Apps::EXTENSION_KEY).nil?
+    end
+
     # use _capability_name or default_capability_name
     def self.capability_name
       _capability_name || default_capability_name

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,
@@ -46,19 +45,23 @@ module ActionMCP
                   :tasks_enabled,
                   :tasks_list_enabled,
                   :tasks_cancel_enabled,
+                  :tasks_result_strategy,
+                  :tasks_result_timeout,
+                  :tasks_result_poll_interval,
                   # --- Schema Validation Options ---
                   :validate_structured_content,
                   # --- Allowed identity keys for gateway ---
                   :allowed_identity_keys,
                   # --- JSON-RPC Path ---
-                  :base_path
+                  :base_path,
+                  # --- Origin validation (DNS rebinding protection) ---
+                  :allowed_origins
 
     def initialize
       @logging_enabled = false
       @list_changed = true
       @logging_level = :warning
       @resources_subscribe = false
-      @elicitation_enabled = false
       @verbose_logging = false
       @active_profile = :primary
       @profiles = default_profiles
@@ -72,6 +75,13 @@ module ActionMCP
       @tasks_enabled = false
       @tasks_list_enabled = true
       @tasks_cancel_enabled = true
+      @tasks_result_strategy = :blocking_http
+      @tasks_result_timeout = 30.seconds
+      @tasks_result_poll_interval = 0.25
+
+      # 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
@@ -94,6 +104,9 @@ module ActionMCP
 
       # Path for JSON-RPC endpoint
       @base_path = "/"
+
+      # Allowed origins for DNS rebinding protection (nil = derive from request.host)
+      @allowed_origins = nil
     end
 
     def name
@@ -132,6 +145,36 @@ 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 tasks_result_strategy=(value)
+      strategy = value.to_sym
+      unless %i[blocking_http polling_only].include?(strategy)
+        raise ArgumentError, "tasks_result_strategy must be :blocking_http or :polling_only, got: #{value.inspect}"
+      end
+
+      @tasks_result_strategy = strategy
+    end
+
+    def tasks_result_timeout=(value)
+      @tasks_result_timeout = normalize_positive_duration(value, "tasks_result_timeout")
+    end
+
+    def tasks_result_poll_interval=(value)
+      @tasks_result_poll_interval = normalize_positive_duration(value, "tasks_result_poll_interval")
+    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 +306,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 +425,22 @@ 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
+
+      self.tasks_result_strategy = config["tasks_result_strategy"] if config.key?("tasks_result_strategy")
+      self.tasks_result_timeout = config["tasks_result_timeout"] if config.key?("tasks_result_timeout")
+      if config.key?("tasks_result_poll_interval")
+        self.tasks_result_poll_interval = config["tasks_result_poll_interval"]
+      end
+
+      # Extract allowed origins for DNS rebinding protection
+      if config["allowed_origins"]
+        @allowed_origins = Array(config["allowed_origins"])
+      end
     end
 
     def should_include_all?(type)
@@ -405,6 +463,13 @@ module ActionMCP
       Array(instructions).map(&:to_s)
     end
 
+    def normalize_positive_duration(value, setting_name)
+      duration = value.respond_to?(:to_f) ? value.to_f : value.to_s.to_f
+      raise ArgumentError, "#{setting_name} must be positive, got: #{value.inspect}" unless duration.positive?
+
+      duration
+    end
+
     def ensure_mcp_components_loaded
       # Only load if we haven't loaded yet - but in development, always reload
       return if @mcp_components_loaded && !Rails.env.development?

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/engine.rb

@@ -46,6 +46,9 @@ module ActionMCP
     end
 
     initializer "action_mcp.insert_middleware" do |app|
+      config.middleware.use ActionDispatch::HostAuthorization, app.config.hosts if app.config.hosts.present?
+      config.middleware.use ActionMCP::Middleware::OriginValidation,
+                            [ ActionMCP.configuration.base_path ].compact.freeze
       config.middleware.use JSONRPC_Rails::Middleware::Validator, [ ActionMCP.configuration.base_path ].compact.freeze
     end
 

data/lib/action_mcp/json_rpc_handler_base.rb

@@ -40,7 +40,6 @@ module ActionMCP
       TASKS_RESULT = "tasks/result"
       TASKS_LIST = "tasks/list"
       TASKS_CANCEL = "tasks/cancel"
-      TASKS_RESUME = "tasks/resume"
 
       # Task notifications
       NOTIFICATIONS_TASKS_STATUS = "notifications/tasks/status"