actionmcp 0.83.4 → 0.100.0

data/lib/action_mcp/server/tasks.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Server
+    # Tasks module for MCP 2025-11-25 specification
+    # Provides methods for handling task-related requests:
+    # - tasks/get: Get task status and data
+    # - tasks/result: Get task result (blocking until terminal state)
+    # - tasks/list: List tasks for the session
+    # - tasks/cancel: Cancel a task
+    module Tasks
+      # Get task status and metadata
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param task_id [String] Task ID to retrieve
+      def send_tasks_get(request_id, task_id)
+        task = find_task(task_id)
+        return unless task
+
+        send_jsonrpc_response(request_id, result: { task: task.to_task_data })
+      end
+
+      # Get task result, blocking until task reaches terminal state
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param task_id [String] Task ID to get result for
+      def send_tasks_result(request_id, task_id)
+        task = find_task(task_id)
+        return unless task
+
+        # If task is not in terminal state, wait for it
+        # In async execution, client should poll or use SSE for notifications
+        unless task.terminal?
+          send_jsonrpc_error(request_id, :invalid_request,
+                             "Task is not yet complete. Current status: #{task.status}")
+          return
+        end
+
+        send_jsonrpc_response(request_id, result: task.to_task_result)
+      end
+
+      # List tasks for the session with optional pagination
+      # @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
+
+        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
+
+        send_jsonrpc_response(request_id, result: result)
+      end
+
+      # Cancel a task
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param task_id [String] Task ID to cancel
+      def send_tasks_cancel(request_id, task_id)
+        task = find_task(task_id)
+        return unless task
+
+        if task.terminal?
+          send_jsonrpc_error(request_id, :invalid_params,
+                             "Cannot cancel task in terminal status: #{task.status}")
+          return
+        end
+
+        task.cancel!
+        send_jsonrpc_response(request_id, result: { task: task.to_task_data })
+      end
+
+      # Resume a task from input_required state
+      # @param request_id [String, Integer] JSON-RPC request ID
+      # @param task_id [String] Task ID to resume
+      # @param input [Object] Input data for the task
+      def send_tasks_resume(request_id, task_id, input)
+        task = find_task(task_id)
+        return unless task
+
+        unless task.input_required?
+          send_jsonrpc_error(request_id, :invalid_params,
+                             "Task is not awaiting input. Current status: #{task.status}")
+          return
+        end
+
+        # Store input in continuation state
+        continuation = task.continuation_state || {}
+        continuation[:input] = input
+        task.update!(continuation_state: continuation)
+
+        # Resume task and re-enqueue job
+        task.resume_from_continuation!
+
+        send_jsonrpc_response(request_id, result: { task: task.to_task_data })
+      end
+
+      # Send task status notification
+      # @param task [ActionMCP::Session::Task] Task to notify about
+      def send_task_status_notification(task)
+        send_jsonrpc_notification(
+          JsonRpcHandlerBase::Methods::NOTIFICATIONS_TASKS_STATUS,
+          { task: task.to_task_data }
+        )
+      end
+
+      private
+
+      def find_task(task_id)
+        task = session.tasks.find_by(id: task_id)
+        unless task
+          Rails.logger.warn "Task not found: #{task_id}"
+          # Note: we need the request_id to send error, but this is called from handler
+          # The handler should handle the nil return
+        end
+        task
+      end
+    end
+  end
+end

data/lib/action_mcp/server/tools.rb

@@ -58,6 +58,20 @@ module ActionMCP
           return
         end
 
+        # Check for task-augmented execution (MCP 2025-11-25)
+        task_params = _meta["task"] || _meta[:task]
+        if task_params && tasks_enabled?
+          handle_task_augmented_tool_call(request_id, tool_name, arguments, _meta, task_params)
+          return
+        end
+
+        # Standard synchronous execution
+        execute_tool_synchronously(request_id, tool_class, tool_name, arguments, _meta)
+      end
+
+      private
+
+      def execute_tool_synchronously(request_id, tool_class, tool_name, arguments, _meta)
         begin
           # Create tool and set execution context with request info
           tool = tool_class.new(arguments)
@@ -106,7 +120,39 @@ module ActionMCP
         end
       end
 
-      private
+      # Handle task-augmented tool calls per MCP 2025-11-25 specification
+      # Creates a Task record and executes the tool asynchronously
+      def handle_task_augmented_tool_call(request_id, tool_name, arguments, _meta, task_params)
+        # Extract task configuration
+        ttl = task_params["ttl"] || task_params[:ttl] || 60_000
+        poll_interval = task_params["pollInterval"] || task_params[:pollInterval] || 5_000
+
+        # Create task record
+        task = session.tasks.create!(
+          request_method: "tools/call",
+          request_name: tool_name,
+          request_params: {
+            name: tool_name,
+            arguments: arguments,
+            _meta: _meta
+          },
+          ttl: ttl,
+          poll_interval: poll_interval
+        )
+
+        # Return CreateTaskResult immediately
+        send_jsonrpc_response(request_id, result: { task: task.to_task_data })
+
+        # Execute tool asynchronously via ActiveJob
+        ToolExecutionJob.perform_later(task.id, tool_name, arguments, _meta)
+      rescue StandardError => e
+        Rails.logger.error "Failed to create task: #{e.class} - #{e.message}"
+        send_jsonrpc_error(request_id, :internal_error, "Failed to create task")
+      end
+
+      def tasks_enabled?
+        ActionMCP.configuration.tasks_enabled
+      end
 
       def format_registry_items(registry, protocol_version = nil)
         registry.map { |item| item.klass.to_h(protocol_version: protocol_version) }

data/lib/action_mcp/server/transport_handler.rb

@@ -19,6 +19,7 @@ module ActionMCP
       include  Sampling
       include  Roots
       include  Elicitation
+      include  Tasks
       include  ResponseCollector # Must be included last to override write_message
 
       # @param [ActionMCP::Session] session

data/lib/action_mcp/tool.rb

@@ -29,6 +29,8 @@ module ActionMCP
     class_attribute :_output_schema_builder, instance_accessor: false, default: nil
     class_attribute :_additional_properties, instance_accessor: false, default: nil
     class_attribute :_cached_schema_property_keys, instance_accessor: false, default: nil
+    class_attribute :_task_support, instance_accessor: false, default: :forbidden
+    class_attribute :_resumable_steps_block, instance_accessor: false, default: nil
 
     # --------------------------------------------------------------------------
     # Tool Name and Description DSL
@@ -40,11 +42,27 @@ module ActionMCP
     def self.tool_name(name = nil)
       if name
         self._capability_name = name
+        re_register_if_needed
+        name
       else
         _capability_name || default_tool_name
       end
     end
 
+    # Re-registers the tool if it was already registered under a different name
+    # @return [void]
+    def self.re_register_if_needed
+      return if abstract?
+      return unless _registered_name # Not yet registered
+
+      new_name = capability_name
+      return if _registered_name == new_name # No change
+
+      ActionMCP::ToolsRegistry.re_register(self, _registered_name)
+    end
+
+    private_class_method :re_register_if_needed
+
     # Returns a default tool name based on the class name.
     #
     # @return [String] The default tool name.
@@ -178,6 +196,60 @@ module ActionMCP
         _requires_consent
       end
 
+      # --------------------------------------------------------------------------
+      # Task Support DSL (MCP 2025-11-25)
+      # --------------------------------------------------------------------------
+      # Sets or retrieves the task support mode for this tool
+      # @param mode [Symbol, nil] :required, :optional, or :forbidden (default)
+      # @return [Symbol] The current task support mode
+      def task_support(mode = nil)
+        if mode
+          unless %i[required optional forbidden].include?(mode)
+            raise ArgumentError, "task_support must be :required, :optional, or :forbidden"
+          end
+
+          self._task_support = mode
+        else
+          _task_support
+        end
+      end
+
+      # Convenience methods for task support
+      def task_required!
+        self._task_support = :required
+      end
+
+      def task_optional!
+        self._task_support = :optional
+      end
+
+      def task_forbidden!
+        self._task_support = :forbidden
+      end
+
+      # Returns the execution metadata including task support
+      def execution_metadata
+        {
+          taskSupport: _task_support.to_s
+        }
+      end
+
+      # --------------------------------------------------------------------------
+      # Resumable Steps DSL (ActiveJob::Continuable support)
+      # --------------------------------------------------------------------------
+      # Defines resumable execution steps for long-running tools
+      # @param block [Proc] Block containing step definitions
+      # @return [void]
+      def resumable_steps(&block)
+        self._resumable_steps_block = block
+      end
+
+      # Checks if tool has resumable steps defined
+      # @return [Boolean]
+      def resumable_steps_defined?
+        _resumable_steps_block.present?
+      end
+
       # Sets or retrieves the additionalProperties setting for the input schema
       # @param enabled [Boolean, Hash] true to allow any additional properties,
       #   false to disallow them, or a Hash for typed additional properties
@@ -322,6 +394,12 @@ module ActionMCP
       annotations = annotations_for_protocol(protocol_version)
       result[:annotations] = annotations if annotations.any?
 
+      # Add execution metadata (MCP 2025-11-25)
+      # Only include if not default (forbidden) to minimize payload
+      if _task_support && _task_support != :forbidden
+        result[:execution] = execution_metadata
+      end
+
       # Add _meta if present
       result[:_meta] = _meta if _meta.any?
 
@@ -438,6 +516,28 @@ module ActionMCP
       raise NotImplementedError, "Subclasses must implement the perform method"
     end
 
+    # Request user/client input and pause execution
+    # @param prompt [String] The prompt/question for the user
+    # @param context [Hash] Additional context about the input request
+    # @return [void]
+    def request_input!(prompt:, context: {})
+      @_input_required = { prompt: prompt, context: context }
+      throw :halt_execution # Use throw to exit perform block
+    end
+
+    # Report progress for long-running tool operations
+    # Only available when tool is running in task-augmented mode
+    # @param percent [Integer] Progress percentage (0-100)
+    # @param message [String] Optional progress message
+    # @param cursor [Integer, String] Optional cursor for iteration state
+    # @return [void]
+    def report_progress!(percent:, message: nil, cursor: nil)
+      return unless @_task # Only available in task-augmented mode
+
+      @_task.update_progress!(percent: percent, message: message)
+      @_task.record_step!(:in_progress, cursor: cursor) if cursor
+    end
+
     private
 
     # Helper method for tools to manually report errors

data/lib/action_mcp/version.rb

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

data/lib/action_mcp.rb

@@ -25,7 +25,6 @@ Zeitwerk::Loader.for_gem.tap do |loader|
   )
 
   loader.inflector.inflect("action_mcp" => "ActionMCP")
-  loader.inflector.inflect("sse_listener" => "SSEListener")
 end.setup
 
 module ActionMCP
@@ -34,12 +33,12 @@ module ActionMCP
 
   # Protocol version constants
   SUPPORTED_VERSIONS = [
-    "2025-06-18", # Dr. Identity McBouncer - elicitation, structured output, resource links
-    "2025-03-26"  # The Persistent Negotiator - StreamableHTTP, resumability, audio support
+    "2025-11-25", # The Task Master - Tasks, icons, tool naming, polling SSE
+    "2025-06-18"  # Dr. Identity McBouncer - elicitation, structured output, resource links
   ].freeze
 
   LATEST_VERSION = SUPPORTED_VERSIONS.first.freeze
-  DEFAULT_PROTOCOL_VERSION = "2025-03-26" # Default to initial stable version for backwards compatibility
+  DEFAULT_PROTOCOL_VERSION = "2025-06-18" # Default to previous stable version for backwards compatibility
   class << self
     # Returns a Rack-compatible application for serving MCP requests
     # This makes ActionMCP.server work similar to ActionCable.server

data/lib/tasks/action_mcp_tasks.rake

@@ -179,10 +179,7 @@ namespace :action_mcp do
 
     # Transport Configuration
     puts "\n\e[36mTransport Configuration:\e[0m"
-    puts "  SSE Heartbeat Interval: #{config.sse_heartbeat_interval}s"
-    puts "  Post Response Preference: #{config.post_response_preference}"
-    puts "  SSE Event Retention Period: #{config.sse_event_retention_period}"
-    puts "  Max Stored SSE Events: #{config.max_stored_sse_events}"
+    puts "  Protocol Version: #{config.protocol_version}"
 
     # Pub/Sub Adapter
     puts "\n\e[36mPub/Sub Adapter:\e[0m"
@@ -332,37 +329,6 @@ namespace :action_mcp do
       puts "  Error accessing message data: #{e.message}"
     end
 
-    # SSE Event Statistics (if table exists)
-    puts "\n\e[36mSSE Event Statistics:\e[0m"
-
-    begin
-      if ActionMCP::ApplicationRecord.connection.table_exists?("action_mcp_sse_events")
-        total_events = ActionMCP::Session::SSEEvent.count
-        puts "  Total SSE Events: #{total_events}"
-
-        if total_events.positive?
-          # Recent events
-          recent_events = ActionMCP::Session::SSEEvent.where("created_at > ?", 1.hour.ago).count
-          puts "  SSE Events (Last Hour): #{recent_events}"
-
-          # Events by session
-          events_by_session = ActionMCP::Session::SSEEvent.joins(:session)
-                                                          .group("action_mcp_sessions.id")
-                                                          .count
-                                                          .sort_by { |_session_id, count| -count }
-                                                          .first(5)
-          puts "  Top Sessions by SSE Events:"
-          events_by_session.each do |session_id, count|
-            puts "    #{session_id}: #{count} events"
-          end
-        end
-      else
-        puts "  SSE Events table not found"
-      end
-    rescue StandardError => e
-      puts "  Error accessing SSE event data: #{e.message}"
-    end
-
     # Storage Information
     puts "\n\e[36mStorage Information:\e[0m"
     puts "  Session Store Type: #{ActionMCP.configuration.session_store_type}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: actionmcp
 version: !ruby/object:Gem::Version
-  version: 0.83.4
+  version: 0.100.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -9,20 +9,34 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.0
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: 8.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: 8.1.0
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -71,14 +85,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: 8.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: 8.1.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: state_machines-activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.100.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.100.0
 - !ruby/object:Gem::Dependency
   name: json_schemer
   requirement: !ruby/object:Gem::Requirement
@@ -121,19 +149,25 @@ files:
 - README.md
 - Rakefile
 - app/controllers/action_mcp/application_controller.rb
+- app/jobs/action_mcp/tool_execution_job.rb
 - app/models/action_mcp.rb
 - app/models/action_mcp/application_record.rb
 - app/models/action_mcp/session.rb
 - app/models/action_mcp/session/message.rb
 - app/models/action_mcp/session/resource.rb
-- app/models/action_mcp/session/sse_event.rb
 - app/models/action_mcp/session/subscription.rb
+- app/models/action_mcp/session/task.rb
 - app/models/concerns/action_mcp/mcp_console_helpers.rb
 - app/models/concerns/action_mcp/mcp_message_inspect.rb
 - config/routes.rb
 - db/migrate/20250512154359_consolidated_migration.rb
 - db/migrate/20250715070713_add_consents_to_action_mcp_sess.rb
 - db/migrate/20250727000001_remove_oauth_support.rb
+- db/migrate/20251125000001_create_action_mcp_session_tasks.rb
+- db/migrate/20251126000001_add_continuation_state_to_action_mcp_session_tasks.rb
+- db/migrate/20251203000001_remove_sse_support.rb
+- db/migrate/20251204000001_add_progress_to_session_tasks.rb
+- db/test.sqlite3
 - exe/actionmcp_cli
 - lib/action_mcp.rb
 - lib/action_mcp/base_response.rb
@@ -223,6 +257,7 @@ files:
 - lib/action_mcp/server/handlers/prompt_handler.rb
 - lib/action_mcp/server/handlers/resource_handler.rb
 - lib/action_mcp/server/handlers/router.rb
+- lib/action_mcp/server/handlers/task_handler.rb
 - lib/action_mcp/server/handlers/tool_handler.rb
 - lib/action_mcp/server/json_rpc_handler.rb
 - lib/action_mcp/server/messaging_service.rb
@@ -237,11 +272,11 @@ files:
 - lib/action_mcp/server/session_store_factory.rb
 - lib/action_mcp/server/simple_pub_sub.rb
 - lib/action_mcp/server/solid_mcp_adapter.rb
+- lib/action_mcp/server/tasks.rb
 - 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/volatile_session_store.rb
-- lib/action_mcp/sse_listener.rb
 - lib/action_mcp/string_array.rb
 - lib/action_mcp/tagged_stream_logging.rb
 - lib/action_mcp/test_helper.rb

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

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-# <rails-lens:schema:begin>
-# table = "action_mcp_sse_events"
-# database_dialect = "SQLite"
-#
-# columns = [
-#   { name = "id", type = "integer", primary_key = true, nullable = false },
-#   { name = "session_id", type = "string", nullable = false },
-#   { name = "event_id", type = "integer", nullable = false },
-#   { name = "data", type = "text", nullable = false },
-#   { name = "created_at", type = "datetime", nullable = false },
-#   { name = "updated_at", type = "datetime", nullable = false }
-# ]
-#
-# indexes = [
-#   { name = "index_action_mcp_sse_events_on_created_at", columns = ["created_at"] },
-#   { name = "index_action_mcp_sse_events_on_session_id_and_event_id", columns = ["session_id", "event_id"], unique = true },
-#   { name = "index_action_mcp_sse_events_on_session_id", columns = ["session_id"] }
-# ]
-#
-# foreign_keys = [
-#   { column = "session_id", references_table = "action_mcp_sessions", references_column = "id" }
-# ]
-#
-# == Notes
-# - Association 'session' should specify inverse_of
-# - String column 'session_id' has no length limit - consider adding one
-# <rails-lens:schema:end>
-module ActionMCP
-  class Session
-    # Represents a Server-Sent Event (SSE) in an MCP session
-    # These events are stored for potential resumption when a client reconnects
-    class SSEEvent < ApplicationRecord
-      self.table_name = "action_mcp_sse_events"
-
-      belongs_to :session, class_name: "ActionMCP::Session"
-
-      # Validations
-      validates :event_id, presence: true, numericality: { only_integer: true, greater_than: 0 }
-      validates :data, presence: true
-
-      # Scopes
-      scope :recent, -> { order(event_id: :desc) }
-      scope :after_id, ->(id) { where("event_id > ?", id) }
-      scope :before, ->(time) { where("created_at < ?", time) }
-
-      # Serializes the data as JSON if it's not already a string
-      def data_for_stream
-        return data if data.is_a?(String)
-
-        data.is_a?(Hash) ? data.to_json : data.to_s
-      end
-
-      # Generates the SSE formatted event string
-      # @return [String] The formatted SSE event
-      def to_sse
-        "id: #{event_id}\ndata: #{data_for_stream}\n\n"
-      end
-    end
-  end
-end

data/lib/action_mcp/sse_listener.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-require "concurrent/atomic/atomic_boolean"
-require "concurrent/promise"
-
-module ActionMCP
-  # Listener class to subscribe to session messages via PubSub adapter.
-  class SSEListener
-    delegate :session_key, :adapter, to: :@session
-
-    # @param session [ActionMCP::Session]
-    def initialize(session)
-      @session = session
-      @stopped = Concurrent::AtomicBoolean.new
-      @subscription_active = Concurrent::AtomicBoolean.new
-    end
-
-    # Start listening using PubSub adapter
-    # @yield [Hash] Yields parsed message received from the pub/sub channel
-    # @return [Boolean] True if subscription was successful within timeout, false otherwise.
-    def start(&callback)
-      success_callback = lambda {
-        @subscription_active.make_true
-      }
-
-      message_callback = lambda { |raw_message|
-        process_message(raw_message, callback)
-      }
-
-      # Subscribe using the PubSub adapter
-      adapter.subscribe(session_key, message_callback, success_callback)
-
-      wait_for_subscription
-    end
-
-    # Stops the listener
-    def stop
-      return if @stopped.true?
-
-      @stopped.make_true
-    end
-
-    private
-
-    def process_message(raw_message, callback)
-      return if @stopped.true?
-
-      begin
-        # Check if the message is a valid JSON string or has a message attribute
-        if raw_message.is_a?(String) && valid_json_format?(raw_message)
-          message = MultiJson.load(raw_message)
-          callback&.call(message)
-        end
-      rescue StandardError => e
-        Rails.logger.error "SSEListener: Error processing message: #{e.message}"
-        Rails.logger.error "SSEListener: Backtrace: #{e.backtrace.join("\n")}"
-      end
-    end
-
-    def valid_json_format?(string)
-      return false if string.blank?
-
-      string = string.strip
-      (string.start_with?("{") && string.end_with?("}")) ||
-        (string.start_with?("[") && string.end_with?("]"))
-    end
-
-    def wait_for_subscription
-      subscription_future = Concurrent::Promises.future do
-        sleep 0.1 while !@subscription_active.true? && !@stopped.true?
-        @subscription_active.true?
-      end
-
-      begin
-        subscription_future.value(5) || @subscription_active.true?
-      rescue Concurrent::TimeoutError
-        false
-      end
-    end
-  end
-end