actionmcp 0.83.4 → 0.100.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07c0477f4e98cef701c55861a54b06530246aa72aa7e4cb573fbf2d523c0ae54
-  data.tar.gz: 9bdff393572212ee32d0430ba2887292f35b0489a0753399a27a5f7a16aa3fac
+  metadata.gz: 9b01884f2ba4ded4a59d6c235583edbd00dae36da78215da26a1fbf83039838f
+  data.tar.gz: c97745755f33ece7ce05a4a2a904cde23e3fe67c3f1ecf9ee0cc962e6bdc9177
 SHA512:
-  metadata.gz: d84067880b719178839887ec9aed55236486a1b8ed60859d1885303ac71b83525c3a52ee4c9267cf1b84044f467668b2a05ec06485d31666d0057838ab789b3a
-  data.tar.gz: b4f687ea0485632c75670c64c9d8953cc340fc45ed774993a0ce2c661c30e05e5429047fb30146c6450e66e1b72ea2be6aae8977127e9cdbedb50e5b578186fd
+  metadata.gz: 545540e721a557860d9263873c841fd703afd1ea9bed05ea489b738c5a81594cc6f560fdf3959d6d9ff992b3e4b247eb8efead8f5f234946429903b00ce06a96
+  data.tar.gz: 8c4a3d2abe05b4f65b26e6dfdd751350973e029341c8ed8bb1e3f880a046477afd59ce236a71d6e607dd82ab3220eaac1c3ee462c7c8861c1ec79a814eaa42ca

data/app/controllers/action_mcp/application_controller.rb

@@ -9,7 +9,6 @@ module ActionMCP
 
     include Engine.routes.url_helpers
     include JSONRPC_Rails::ControllerHelpers
-    include ActionController::Live
     include ActionController::Instrumentation
 
     # Provides the ActionMCP::Session for the current request.
@@ -27,136 +26,15 @@ module ActionMCP
       @session_key ||= "action_mcp-sessions-#{mcp_session.id}"
     end
 
-    # Handles GET requests for establishing server-initiated SSE streams (2025-03-26 spec).
+    # Handles GET requests - returns 405 Method Not Allowed as per MCP spec.
+    # SSE streaming is not supported. Clients should use Tasks for async operations.
     # <rails-lens:routes:begin>
     # ROUTE: /, name: mcp_get, via: GET
     # <rails-lens:routes:end>
     def show
-      unless request.accepts.any? { |type| type.to_s == "text/event-stream" }
-        return render_not_acceptable("Client must accept 'text/event-stream' for GET requests.")
-      end
-
-      session_id_from_header = extract_session_id
-      return render_bad_request("Mcp-Session-Id header is required for GET requests.") unless session_id_from_header
-
-      session = mcp_session
-      if session.nil? || session.new_record?
-        return render_not_found("Session not found.")
-      elsif !session.initialized?
-        return render_bad_request("Session is not fully initialized.")
-      elsif session.status == "closed"
-        return render_not_found("Session has been terminated.")
-      end
-
-      # Authenticate the request via gateway
-      authenticate_gateway!
-      return if performed?
-
-      last_event_id = request.headers["Last-Event-ID"].presence
-      if last_event_id && ActionMCP.configuration.verbose_logging
-        Rails.logger.info "Unified SSE (GET): Resuming from Last-Event-ID: #{last_event_id}"
-      end
-
-      response.headers["Content-Type"] = "text/event-stream"
-      response.headers["X-Accel-Buffering"] = "no"
-      response.headers["Cache-Control"] = "no-cache"
-      response.headers["Connection"] = "keep-alive"
-      # Add MCP-Protocol-Version header for established sessions
-      response.headers["MCP-Protocol-Version"] = session.protocol_version
-
-      if ActionMCP.configuration.verbose_logging
-        Rails.logger.info "Unified SSE (GET): Starting stream for session: #{session.id}"
-      end
-
-      sse = SSE.new(response.stream)
-      listener = SSEListener.new(session)
-      connection_active = Concurrent::AtomicBoolean.new
-      connection_active.make_true
-      heartbeat_active = Concurrent::AtomicBoolean.new
-      heartbeat_active.make_true
-      heartbeat_task = nil
-
-      listener_started = listener.start do |message|
-        write_sse_event(sse, session, message)
-      end
-
-      unless listener_started
-        Rails.logger.error "Unified SSE (GET): Listener failed to activate for session: #{session.id}"
-        connection_active.make_false
-        return
-      end
-
-      if last_event_id.present? && last_event_id.to_i.positive?
-        begin
-          missed_events = session.get_sse_events_after(last_event_id.to_i)
-          if missed_events.any?
-            if ActionMCP.configuration.verbose_logging
-              Rails.logger.info "Unified SSE (GET): Sending #{missed_events.size} missed events for session: #{session.id}"
-            end
-            missed_events.each do |event|
-              sse.write(event.to_sse)
-            end
-          elsif ActionMCP.configuration.verbose_logging
-            if ActionMCP.configuration.verbose_logging
-              Rails.logger.info "Unified SSE (GET): No missed events to send for session: #{session.id}"
-            end
-          end
-        rescue StandardError => e
-          Rails.logger.error "Unified SSE (GET): Error sending missed events: #{e.message}"
-        end
-      end
-
-      heartbeat_interval = ActionMCP.configuration.sse_heartbeat_interval || 15.seconds
-      heartbeat_sender = lambda do
-        if connection_active.true? && !response.stream.closed?
-          begin
-            # Send a proper JSON-RPC notification for heartbeat
-            ping_notification = {
-              jsonrpc: "2.0",
-              method: "notifications/ping",
-              params: {}
-            }
-            future = Concurrent::Promises.future { write_sse_event(sse, session, ping_notification) }
-            future.value!(5)
-            if heartbeat_active.true?
-              heartbeat_task = Concurrent::ScheduledTask.execute(heartbeat_interval, &heartbeat_sender)
-            end
-          rescue Concurrent::TimeoutError
-            Rails.logger.warn "Unified SSE (GET): Heartbeat timed out for session: #{session.id}, closing."
-            connection_active.make_false
-          rescue StandardError => e
-            if ActionMCP.configuration.verbose_logging
-              Rails.logger.debug "Unified SSE (GET): Heartbeat error for session: #{session.id}: #{e.message}"
-            end
-            connection_active.make_false
-          end
-        else
-          heartbeat_active.make_false
-        end
-      end
-
-      heartbeat_task = Concurrent::ScheduledTask.execute(heartbeat_interval, &heartbeat_sender)
-      sleep 0.1 while connection_active.true? && !response.stream.closed?
-    rescue ActionController::Live::ClientDisconnected, IOError => e
-      if ActionMCP.configuration.verbose_logging
-        Rails.logger.debug "Unified SSE (GET): Client disconnected for session: #{session&.id}: #{e.message}"
-      end
-    rescue StandardError => e
-      Rails.logger.error "Unified SSE (GET): Unexpected error for session: #{session&.id}: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
-    ensure
-      if ActionMCP.configuration.verbose_logging
-        Rails.logger.debug "Unified SSE (GET): Cleaning up connection for session: #{session&.id}"
-      end
-      heartbeat_active&.make_false
-      heartbeat_task&.cancel
-      listener&.stop
-      cleanup_old_sse_events(session) if session
-      sse&.close
-      begin
-        response.stream&.close
-      rescue StandardError
-        nil
-      end
+      # 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.
+      head :method_not_allowed
     end
 
     # Handles POST requests containing client JSON-RPC messages according to 2025-03-26 spec.
@@ -211,15 +89,6 @@ module ActionMCP
 
       result = json_rpc_handler.call(jsonrpc_params)
       process_handler_results(result, session, session_initially_missing, is_initialize_request)
-    rescue ActionController::Live::ClientDisconnected, IOError => e
-      if ActionMCP.configuration.verbose_logging
-        Rails.logger.debug "Unified SSE (POST): Client disconnected during response: #{e.message}"
-      end
-      begin
-        response.stream&.close
-      rescue StandardError
-        nil
-      end
     rescue StandardError => e
       Rails.logger.error "Unified POST Error: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
       id = begin
@@ -271,9 +140,9 @@ module ActionMCP
       header_version = request.headers["MCP-Protocol-Version"] || request.headers["mcp-protocol-version"]
       session = mcp_session
 
-      # If header is missing, assume 2025-03-26 for backward compatibility as per spec
+      # If header is missing, assume 2025-06-18 for backward compatibility as per spec
       if header_version.nil?
-        ActionMCP.logger.debug "MCP-Protocol-Version header missing, assuming 2025-03-26 for backward compatibility"
+        ActionMCP.logger.debug "MCP-Protocol-Version header missing, assuming 2025-06-18 for backward compatibility"
         return true
       end
 
@@ -298,7 +167,6 @@ module ActionMCP
         end
       end
 
-      ActionMCP.logger.debug "MCP-Protocol-Version header validation passed: #{header_version}"
       true
     end
 
@@ -320,28 +188,14 @@ module ActionMCP
       request.headers[MCP_SESSION_ID_HEADER].presence
     end
 
-    # Checks if the client's Accept header includes the required types.
-    def accepts_valid_content_types?
-      request.accepts.any? { |type| type.to_s == "application/json" } &&
-        request.accepts.any? { |type| type.to_s == "text/event-stream" }
-    end
-
-    # Checks if the Accept headers for POST are valid according to server preference.
+    # Checks if the Accept headers for POST are valid.
     def post_accept_headers_valid?
-      if ActionMCP.configuration.post_response_preference == :sse
-        accepts_valid_content_types?
-      else
-        request.accepts.any? { |type| type.to_s == "application/json" }
-      end
+      request.accepts.any? { |type| type.to_s == "application/json" }
     end
 
     # Returns the appropriate error message for POST Accept header validation.
     def post_accept_headers_error_message
-      if ActionMCP.configuration.post_response_preference == :sse
-        "Client must accept 'application/json' and 'text/event-stream'"
-      else
-        "Client must accept 'application/json'"
-      end
+      "Client must accept 'application/json'"
     end
 
     # Checks if the parsed body represents an 'initialize' request.
@@ -372,19 +226,11 @@ module ActionMCP
                   result
       end
 
-      # Determine response format
-      server_preference = ActionMCP.configuration.post_response_preference
-      use_sse = (server_preference == :sse)
       add_session_header = is_initialize_request && session_initially_missing && session.persisted?
-
-      if use_sse
-        render_sse_response(payload, session, add_session_header)
-      else
-        render_json_response(payload, session, add_session_header)
-      end
+      render_json_response(payload, session, add_session_header)
     end
 
-    # Renders the JSON-RPC response(s) as a direct JSON HTTP response.
+    # Renders the JSON-RPC response as a JSON HTTP response.
     def render_json_response(payload, session, add_session_header)
       response.headers[MCP_SESSION_ID_HEADER] = session.id if add_session_header
       # Add MCP-Protocol-Version header if session has been initialized
@@ -393,62 +239,6 @@ module ActionMCP
       render json: payload, status: :ok
     end
 
-    # Renders the JSON-RPC response(s) as an SSE stream.
-    def render_sse_response(payload, session, add_session_header)
-      response.headers[MCP_SESSION_ID_HEADER] = session.id if add_session_header
-      # Add MCP-Protocol-Version header if session has been initialized
-      response.headers["MCP-Protocol-Version"] = session.protocol_version if session&.initialized?
-      response.headers["Content-Type"] = "text/event-stream"
-      response.headers["X-Accel-Buffering"] = "no"
-      response.headers["Cache-Control"] = "no-cache"
-      response.headers["Connection"] = "keep-alive"
-      sse = SSE.new(response.stream)
-      write_sse_event(sse, session, payload)
-    ensure
-      sse&.close
-      begin
-        response.stream&.close
-      rescue StandardError
-        nil
-      end
-      Rails.logger.debug "Unified SSE (POST): Response stream closed." if ActionMCP.configuration.verbose_logging
-    end
-
-    # Helper to write a JSON payload as an SSE event with a unique ID.
-    # Also stores the event for potential resumability.
-    def write_sse_event(sse, session, payload)
-      event_id = session.increment_sse_counter!
-      # Ensure we're always writing valid JSON strings
-      data = case payload
-      when String
-               payload
-      when Hash
-               MultiJson.dump(payload)
-      else
-               MultiJson.dump(payload.to_h)
-      end
-      # Use the SSE class's write method with proper options
-      # According to MCP spec, we need to send with event type "message"
-      sse.write(data, event: "message", id: event_id)
-
-      begin
-        session.store_sse_event(event_id, payload, session.max_stored_sse_events)
-      rescue StandardError => e
-        Rails.logger.error "Failed to store SSE event for resumability: #{e.message}"
-      end
-    end
-
-    # Helper to clean up old SSE events for a session
-    def cleanup_old_sse_events(session)
-      retention_period = session.sse_event_retention_period
-      count = session.cleanup_old_sse_events(retention_period)
-      if count.positive? && ActionMCP.configuration.verbose_logging
-        Rails.logger.debug "Cleaned up #{count} old SSE events for session: #{session.id}"
-      end
-    rescue StandardError => e
-      Rails.logger.error "Error cleaning up old SSE events: #{e.message}"
-    end
-
     def format_tools_list(tools, session)
       protocol_version = session.protocol_version || ActionMCP.configuration.protocol_version
       tools.map { |tool| tool.klass.to_h(protocol_version: protocol_version) }

data/app/jobs/action_mcp/tool_execution_job.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  # ActiveJob for executing tools asynchronously in task-augmented mode
+  # Part of MCP 2025-11-25 Tasks specification with ActiveJob::Continuable support
+  class ToolExecutionJob < ActiveJob::Base
+    include ActiveJob::Continuable
+
+    queue_as :mcp_tasks
+
+    # Retry configuration for transient failures
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3
+
+    # Ensure tasks reach terminal state on permanent failure
+    discard_on StandardError do |job, error|
+      handle_job_discard(job, error)
+    end
+
+    # @param task_id [String] Task ID
+    # @param tool_name [String] Name of the tool to execute
+    # @param arguments [Hash] Tool arguments
+    # @param meta [Hash] Request metadata
+    def perform(task_id, tool_name, arguments, meta = {})
+      @task = step(:load_task, task_id)
+      return if @task.nil? || @task.terminal?
+
+      @session = step(:validate_session, @task)
+      return unless @session
+
+      @tool = step(:prepare_tool, @session, tool_name, arguments)
+      return unless @tool
+
+      step(:execute_tool) do
+        result = execute_with_reloader(@tool, @session)
+        update_task_result(@task, result)
+      end
+    end
+
+    private
+
+    def load_task(task_id)
+      task = Session::Task.find_by(id: task_id)
+      unless task
+        Rails.logger.error "[ToolExecutionJob] Task not found: #{task_id}"
+        return nil
+      end
+
+      task.record_step!(:job_started)
+      task
+    end
+
+    def validate_session(task)
+      session = task.session
+      unless session
+        task.update(status_message: "Session not found")
+        task.mark_failed!
+        return nil
+      end
+
+      session
+    end
+
+    def prepare_tool(session, tool_name, arguments)
+      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.mark_failed!
+        return nil
+      end
+
+      # Create and configure tool instance
+      tool = tool_class.new(arguments)
+      tool.with_context({
+        session: session,
+        request: {
+          params: @task.request_params
+        }
+      })
+
+      tool
+    end
+
+    def execute_with_reloader(tool, session)
+      if Rails.env.development?
+        # Preserve Current attributes across reloader boundary
+        current_user = ActionMCP::Current.user
+        current_gateway = ActionMCP::Current.gateway
+
+        Rails.application.reloader.wrap do
+          ActionMCP::Current.user = current_user
+          ActionMCP::Current.gateway = current_gateway
+          tool.call
+        end
+      else
+        tool.call
+      end
+    end
+
+    def update_task_result(task, result)
+      return if task.terminal? # Guard against double-complete
+
+      if result.is_error
+        task.result_payload = result.to_h
+        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.record_step!(:completed)
+        task.complete!
+      end
+    end
+
+    def self.handle_job_discard(job, error)
+      task_id = job.arguments.first
+      task = Session::Task.find_by(id: task_id)
+      return unless task&.persisted?
+      return if task.terminal?
+
+      Rails.logger.error "[ToolExecutionJob] Discarding job for task #{task_id}: #{error.class} - #{error.message}"
+      Rails.logger.error error.backtrace&.first(10)&.join("\n")
+
+      task.update(
+        status_message: "Job failed: #{error.message}",
+        continuation_state: {
+          step: :failed,
+          error: { class: error.class.name, message: error.message },
+          timestamp: Time.current.iso8601
+        }
+      )
+      task.mark_failed!
+    end
+  end
+end

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

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "state_machines-activerecord"
+
+module ActionMCP
+  class Session
+    # Represents a Task in an MCP session as per MCP 2025-11-25 specification.
+    # Tasks provide durable state machines for tracking async request execution.
+    #
+    # State Machine:
+    #   working -> input_required -> working (via resume)
+    #   working -> completed | failed | cancelled
+    #   input_required -> completed | failed | cancelled
+    #
+    class Task < ApplicationRecord
+      self.table_name = "action_mcp_session_tasks"
+
+      attribute :id, :string, default: -> { SecureRandom.uuid_v7 }
+
+      belongs_to :session, class_name: "ActionMCP::Session", inverse_of: :tasks
+
+      # JSON columns are handled natively by Rails 8.1+
+      # No serialize needed for json column types
+
+      # Validations
+      validates :status, presence: true
+      validates :last_updated_at, presence: true
+
+      # 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) }
+
+      # State machine definition per MCP spec
+      state_machine :status, initial: :working do
+        # Terminal states
+        state :completed
+        state :failed
+        state :cancelled
+
+        # Non-terminal states
+        state :working
+        state :input_required
+
+        # Transition to input_required when awaiting user/client input
+        event :require_input do
+          transition working: :input_required
+        end
+
+        # Resume from input_required back to working
+        event :resume do
+          transition input_required: :working
+        end
+
+        # Complete the task successfully
+        event :complete do
+          transition %i[working input_required] => :completed
+        end
+
+        # Mark the task as failed due to an error
+        # Note: Using 'mark_failed' instead of 'fail' to avoid conflict with Object#fail
+        event :mark_failed do
+          transition %i[working input_required] => :failed
+        end
+
+        # Cancel the task
+        event :cancel do
+          transition %i[working input_required] => :cancelled
+        end
+
+        # After any transition, update timestamp and broadcast
+        after_transition do |task, transition|
+          task.update_column(:last_updated_at, Time.current)
+          task.broadcast_status_change(transition)
+        end
+      end
+
+      # Callbacks
+      before_validation :set_last_updated_at, on: :create
+
+      # TTL management
+      # @return [Boolean] true if task has exceeded its TTL
+      def expired?
+        return false if ttl.nil?
+
+        # TTL is stored in milliseconds (MCP spec)
+        created_at + (ttl / 1000.0).seconds < Time.current
+      end
+
+      # Check if task is in a terminal state
+      def terminal?
+        status.in?(%w[completed failed cancelled])
+      end
+
+      # Check if task is in a non-terminal state
+      def non_terminal?
+        !terminal?
+      end
+
+      # Convert to task data format per MCP spec
+      # @return [Hash] Task data for JSON-RPC responses
+      def to_task_data
+        data = {
+          id: id,
+          status: status,
+          lastUpdatedAt: last_updated_at.iso8601(3)
+        }
+        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
+      end
+
+      # Convert to full task result format
+      # @return [Hash] Complete task with result for tasks/result response
+      def to_task_result
+        {
+          task: to_task_data,
+          result: result_payload
+        }
+      end
+
+      # Broadcast status change notification to the session
+      # @param transition [StateMachines::Transition] The state transition that occurred
+      def broadcast_status_change(transition = nil)
+        return unless session
+
+        handler = ActionMCP::Server::TransportHandler.new(session)
+        handler.send_task_status_notification(self)
+      rescue StandardError => e
+        Rails.logger.warn "Failed to broadcast task status change: #{e.message}"
+      end
+
+      # Continuation State Management (for ActiveJob::Continuable support)
+
+      # Record step execution state for job resumption
+      # @param step_name [Symbol] Name of the step
+      # @param cursor [Integer, String] Optional cursor for resuming iteration
+      # @param data [Hash] Additional step data to persist
+      def record_step!(step_name, cursor: nil, data: {})
+        update!(
+          continuation_state: {
+            step: step_name,
+            cursor: cursor,
+            data: data,
+            timestamp: Time.current.iso8601
+          },
+          last_step_at: Time.current
+        )
+      end
+
+      # Store partial result fragment (for streaming/incremental results)
+      # @param result_fragment [Hash] Partial result to append
+      def store_partial_result!(result_fragment)
+        payload = result_payload || {}
+        payload[:partial] ||= []
+        payload[:partial] << result_fragment
+        update!(result_payload: payload)
+      end
+
+      # Update progress indicators for long-running tasks
+      # @param percent [Integer] Progress percentage (0-100)
+      # @param message [String] Optional progress message
+      def update_progress!(percent:, message: nil)
+        update!(
+          progress_percent: percent.clamp(0, 100),
+          progress_message: message,
+          last_step_at: Time.current
+        )
+      end
+
+      # Transition to input_required state and store pending input prompt
+      # @param prompt [String] The prompt/question for the user
+      # @param context [Hash] Additional context about the input request
+      def await_input!(prompt:, context: {})
+        record_step!(:awaiting_input, data: { prompt: prompt, context: context })
+        require_input!
+      end
+
+      # Resume task from input_required state and re-enqueue job
+      # @return [void]
+      def resume_from_continuation!
+        return unless input_required?
+
+        resume!
+        # Re-enqueue the job to continue execution
+        ActionMCP::ToolExecutionJob.perform_later(id, request_name, request_params, {})
+      end
+
+      private
+
+      def set_last_updated_at
+        self.last_updated_at ||= Time.current
+      end
+    end
+  end
+end