actionmcp 0.111.1 → 0.200.0

data/lib/action_mcp/server/base_session.rb

@@ -70,8 +70,15 @@ module ActionMCP
         initialized
       end
 
+      def begin_initialization!
+        return false unless status == "pre_initialize" && !initialized?
+
+        self.status = "initializing"
+        save
+      end
+
       def initialize!
-        return false if initialized?
+        return false unless status == "initializing" && !initialized?
 
         self.initialized = true
         self.status = "initialized"
@@ -86,23 +93,11 @@ module ActionMCP
 
       # Message management
       def write(data)
-        @messages << {
-          data: data,
-          direction: role == "server" ? "client" : "server",
-          created_at: Time.current
-        }
-        @message_counter.increment
-        self.messages_count = @message_counter.value
+        record_message(data, writer_role)
       end
 
       def read(data)
-        @messages << {
-          data: data,
-          direction: role,
-          created_at: Time.current
-        }
-        @message_counter.increment
-        self.messages_count = @message_counter.value
+        record_message(data, role)
       end
 
       def messages
@@ -113,6 +108,42 @@ module ActionMCP
         SubscriptionCollection.new(@subscriptions)
       end
 
+      def cancel_in_flight_request(request_id)
+        return if request_id.nil?
+
+        request = received_requests_with_id(request_id).find do |message|
+          !message[:request_acknowledged] && !message[:request_cancelled]
+        end
+        return if request && message_payload(request)[:method] == JsonRpcHandlerBase::Methods::INITIALIZE
+
+        request&.tap { |message| message[:request_cancelled] = true }
+      end
+
+      def client_request_for_progress(progress_token)
+        return if progress_token.nil?
+
+        issued_client_requests.find do |request|
+          message_payload(request).dig(:params, :_meta, :progressToken) == progress_token &&
+            client_request_accepts_progress?(request)
+        end
+      end
+
+      def client_request_for_task(task_id)
+        return unless task_id.is_a?(String) && task_id.present?
+
+        response = @messages.reverse_each.find do |message|
+          message[:direction] == role &&
+            message_payload(message).dig(:result, :task, :taskId) == task_id
+        end
+        return unless response
+
+        response_id = message_payload(response)[:id]
+        issued_client_requests.find do |request|
+          payload = message_payload(request)
+          payload[:id] == response_id && payload.dig(:params, :task).is_a?(Hash)
+        end
+      end
+
       # Capability methods
       def server_capabilities_payload
         payload = {
@@ -150,6 +181,10 @@ module ActionMCP
         @subscriptions.delete_if { |s| s[:uri] == uri }
       end
 
+      def resource_subscribed?(uri)
+        @subscriptions.any? { |subscription| subscription[:uri] == uri }
+      end
+
       # Progress notification
       def send_progress_notification(progressToken:, progress:, total: nil, message: nil)
         handler = ActionMCP::Server::TransportHandler.new(self)
@@ -280,20 +315,91 @@ module ActionMCP
 
       private
 
-      def capabilities_for_protocol(capabilities)
-        filtered =
-          if capabilities.respond_to?(:deep_dup)
-            capabilities.deep_dup
-          elsif capabilities
-            capabilities.dup
-          else
-            {}
-          end
-        return filtered if protocol_version == "2025-11-25"
+      CLIENT_REQUEST_METHODS = %w[sampling/createMessage elicitation/create].freeze
+      TERMINAL_CLIENT_TASK_STATUSES = %w[cancelled completed failed].freeze
+
+      def record_message(data, direction)
+        payload = data.respond_to?(:to_h) ? data.to_h : data
+        entry = {
+          data: data,
+          direction: direction,
+          request_acknowledged: false,
+          request_cancelled: false,
+          is_ping: payload.is_a?(Hash) && (payload[:method] || payload["method"]) == "ping",
+          created_at: Time.current
+        }
+        @messages << entry
+        acknowledge_request(entry)
+        @message_counter.increment
+        self.messages_count = @message_counter.value
+        entry
+      end
+
+      def acknowledge_request(response)
+        payload = message_payload(response)
+        return unless payload.key?(:id) && (payload.key?(:result) || payload.key?(:error))
+
+        request = @messages.reverse_each.find do |message|
+          next if message.equal?(response) || message[:direction] == response[:direction]
+
+          request_payload = message_payload(message)
+          request_payload.key?(:method) && request_payload[:id] == payload[:id]
+        end
+        return unless request
+
+        request[:request_acknowledged] = true
+        response[:is_ping] = request[:is_ping]
+      end
+
+      def received_requests_with_id(request_id)
+        @messages.reverse_each.select do |message|
+          payload = message_payload(message)
+          message[:direction] == role && payload.key?(:method) && payload[:id] == request_id
+        end
+      end
+
+      def issued_client_requests
+        @messages.reverse_each.select do |message|
+          payload = message_payload(message)
+          message[:direction] == writer_role && CLIENT_REQUEST_METHODS.include?(payload[:method])
+        end
+      end
+
+      def client_request_accepts_progress?(request)
+        return true unless request[:request_acknowledged]
+
+        request_id = message_payload(request)[:id]
+        response = @messages.reverse_each.find do |message|
+          payload = message_payload(message)
+          message[:direction] == role && payload[:id] == request_id && payload.key?(:result)
+        end
+        task = message_payload(response).dig(:result, :task) if response
+        return false unless task.is_a?(Hash) && task[:taskId].is_a?(String)
+
+        latest_status = @messages.reverse_each.filter_map do |message|
+          payload = message_payload(message)
+          next unless message[:direction] == role
+          next unless payload[:method] == JsonRpcHandlerBase::Methods::NOTIFICATIONS_TASKS_STATUS
+          next unless payload.dig(:params, :taskId) == task[:taskId]
 
-        filtered.delete("tasks")
-        filtered.delete(:tasks)
-        filtered
+          payload.dig(:params, :status)
+        end.first
+
+        !TERMINAL_CLIENT_TASK_STATUSES.include?(latest_status || task[:status])
+      end
+
+      def message_payload(message)
+        data = message[:data]
+        data = data.to_h if data.respond_to?(:to_h)
+        data.is_a?(Hash) ? data.with_indifferent_access : {}.with_indifferent_access
+      end
+
+      def writer_role
+        role == "server" ? "client" : "server"
+      end
+
+      def capabilities_for_protocol(capabilities)
+        capabilities ? capabilities.deep_dup : {}
       end
 
       def normalize_name(class_or_name, type)

data/lib/action_mcp/server/base_session_store.rb

@@ -10,7 +10,7 @@ module ActionMCP
       end
 
       def create_session(session_id = nil, attributes = {})
-        session_id ||= SecureRandom.hex(6)
+        session_id ||= SecureRandom.hex(16)
 
         session_data = {
           id: session_id,

data/lib/action_mcp/server/capabilities.rb

@@ -13,53 +13,33 @@ module ActionMCP
         client_protocol_version = params["protocolVersion"]
         client_info = params["clientInfo"]
         client_capabilities = params["capabilities"]
-        session_id = params["sessionId"]
-
-        unless client_protocol_version.is_a?(String) && client_protocol_version.present?
+        unless client_protocol_version.is_a?(String)
           return send_jsonrpc_error(request_id, :invalid_params, "Missing or invalid 'protocolVersion'")
         end
 
-        unless ActionMCP::SUPPORTED_VERSIONS.include?(client_protocol_version)
-          error_message = "Unsupported protocol version. Client requested '#{client_protocol_version}' but server supports #{ActionMCP::SUPPORTED_VERSIONS.join(', ')}"
-          error_data = {
-            supported: ActionMCP::SUPPORTED_VERSIONS,
-            requested: client_protocol_version
-          }
-          return send_jsonrpc_error(request_id, :invalid_params, error_message, error_data)
-        end
-
-        unless client_info.is_a?(Hash)
+        unless client_info.is_a?(Hash) && client_info["name"].is_a?(String) && client_info["version"].is_a?(String)
           return send_jsonrpc_error(request_id, :invalid_params, "Missing or invalid 'clientInfo'")
         end
         unless client_capabilities.is_a?(Hash)
           return send_jsonrpc_error(request_id, :invalid_params, "Missing or invalid 'capabilities'")
         end
 
-        # Handle session resumption if sessionId provided
-        if session_id
-          existing_session = ActionMCP::Session.find_by(id: session_id)
-          if existing_session&.initialized?
-            # Resume existing session - update transport reference
-            transport.instance_variable_set(:@session, existing_session)
-
-            # Return existing session info
-            capabilities_payload = existing_session.server_capabilities_payload
-            capabilities_payload[:protocolVersion] = client_protocol_version
-            return send_jsonrpc_response(request_id, result: capabilities_payload)
-          end
+        negotiated_version = if ActionMCP::SUPPORTED_VERSIONS.include?(client_protocol_version)
+                               client_protocol_version
+        else
+                               ActionMCP::LATEST_VERSION
         end
 
-        # Create new session if not resuming
         session.store_client_info(client_info)
         session.store_client_capabilities(client_capabilities)
-        session.set_protocol_version(client_protocol_version)
+        session.set_protocol_version(negotiated_version)
 
-        unless session.initialize!
-          return send_jsonrpc_error(request_id, :internal_error, "Failed to initialize session")
+        unless session.begin_initialization!
+          return send_jsonrpc_error(request_id, :invalid_request, "Session has already started initialization")
         end
 
         capabilities_payload = session.server_capabilities_payload
-        capabilities_payload[:protocolVersion] = client_protocol_version
+        capabilities_payload[:protocolVersion] = negotiated_version
 
         send_jsonrpc_response(request_id, result: capabilities_payload)
       end

data/lib/action_mcp/server/client_notifications.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Server
+    # Correlates client notifications with server session state. Applications
+    # can consume the resulting Rails notifications without ActionMCP keeping
+    # callback objects in a persistent session.
+    module ClientNotifications
+      def receive_cancelled_notification(params)
+        params = normalize_client_notification_params(params)
+        request = if session.respond_to?(:cancel_in_flight_request)
+                    session.cancel_in_flight_request(params[:requestId])
+        end
+        return log_unmatched_client_notification("cancellation", params[:requestId]) unless request
+
+        instrument_client_notification("request_cancelled", request, params)
+        request
+      end
+
+      def receive_progress_notification(params)
+        params = normalize_client_notification_params(params)
+        request = if session.respond_to?(:client_request_for_progress)
+                    session.client_request_for_progress(params[:progressToken])
+        end
+        return log_unmatched_client_notification("progress token", params[:progressToken]) unless request
+
+        instrument_client_notification("request_progress", request, params)
+        request
+      end
+
+      def receive_task_status_notification(params)
+        params = normalize_client_notification_params(params)
+        request = if session.respond_to?(:client_request_for_task)
+                    session.client_request_for_task(params[:taskId])
+        end
+        return log_unmatched_client_notification("task", params[:taskId]) unless request
+
+        instrument_client_notification("task_status", request, params)
+        request
+      end
+
+      private
+
+      def normalize_client_notification_params(params)
+        params.respond_to?(:to_h) ? params.to_h.with_indifferent_access : {}.with_indifferent_access
+      end
+
+      def instrument_client_notification(event, request, params)
+        ActiveSupport::Notifications.instrument(
+          "#{event}.action_mcp",
+          session: session,
+          request: request,
+          params: params
+        )
+      end
+
+      def log_unmatched_client_notification(kind, identifier)
+        Rails.logger.debug("Ignoring MCP notification for unknown #{kind}: #{identifier.inspect}")
+        nil
+      end
+    end
+  end
+end

data/lib/action_mcp/server/completions.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Server
+    module Completions
+      MAX_COMPLETION_VALUES = 100
+
+      def send_completion_complete(request_id, params)
+        unless completion_capability?
+          send_jsonrpc_error(request_id, :method_not_found, "Completions are not available for this session")
+          return
+        end
+
+        if (validation_error = ProtocolValidator.request_params_validation_error("completion/complete", params))
+          send_jsonrpc_error(request_id, validation_error.code, validation_error.message)
+          return
+        end
+
+        params = params.with_indifferent_access
+        definition = completion_definition(params[:ref], params.dig(:argument, :name))
+        unless definition
+          send_jsonrpc_error(request_id, :invalid_params, "Unknown completion reference or argument")
+          return
+        end
+
+        values = matching_completion_values(definition, params.dig(:argument, :value))
+        result = {
+          completion: {
+            values: values.first(MAX_COMPLETION_VALUES),
+            total: values.length,
+            hasMore: values.length > MAX_COMPLETION_VALUES
+          }
+        }
+        send_jsonrpc_response(request_id, result: result)
+      end
+
+      private
+
+      def completion_capability?
+        capabilities = (session.server_capabilities || {}).with_indifferent_access
+        capabilities.key?(:completions)
+      end
+
+      def completion_definition(reference, argument_name)
+        case reference[:type]
+        when "ref/prompt"
+          prompt = session.registered_prompts.find { |candidate| candidate.prompt_name == reference[:name] }
+          prompt&.arguments&.find do |argument|
+            (argument[:name] || argument["name"]).to_s == argument_name
+          end
+        when "ref/resource"
+          template = session.registered_resource_templates.find do |candidate|
+            candidate.uri_template == reference[:uri]
+          end
+          template&.parameters&.find { |name, _definition| name.to_s == argument_name }&.last
+        end
+      end
+
+      def matching_completion_values(definition, current_value)
+        enum = definition[:enum] || definition["enum"]
+        return [] unless enum.is_a?(Array)
+
+        prefix = current_value.downcase
+        enum.map(&:to_s).select { |value| value.downcase.start_with?(prefix) }
+      end
+    end
+  end
+end

data/lib/action_mcp/server/elicitation.rb

@@ -17,13 +17,15 @@ module ActionMCP
       # @param message [String] Human-readable message explaining why input is needed
       # @param requested_schema [Hash] JSON Schema for the expected response (primitive types only)
       # @param _meta [Hash] Optional metadata (e.g. related task)
-      def send_elicitation_create(message:, requested_schema:, _meta: {})
+      def send_elicitation_create(message:, requested_schema:, _meta: {}, task: nil)
         require_client_elicitation_support!(:form)
+        require_client_elicitation_task_support! if task
 
         request = ElicitationRequest.new(
           message: message,
           requested_schema: requested_schema,
-          _meta: _meta
+          _meta: _meta,
+          task: task
         )
         request.assert_valid!
 
@@ -37,14 +39,16 @@ module ActionMCP
       # @param url [String] The URL the user should navigate to
       # @param elicitation_id [String] Unique identifier for this elicitation
       # @param _meta [Hash] Optional metadata (e.g. related task)
-      def send_elicitation_create_url(message:, url:, elicitation_id: nil, _meta: {})
+      def send_elicitation_create_url(message:, url:, elicitation_id: nil, _meta: {}, task: nil)
         require_client_elicitation_support!(:url)
+        require_client_elicitation_task_support! if task
 
         request = UrlElicitationRequest.new(
           message: message,
           url: url,
           elicitation_id: elicitation_id,
-          _meta: _meta
+          _meta: _meta,
+          task: task
         )
         request.assert_valid!
 
@@ -56,6 +60,10 @@ module ActionMCP
       # @param elicitation_id [String] The elicitation ID from the original request
       def send_elicitation_complete_notification(elicitation_id)
         require_client_elicitation_support!(:url)
+        unless elicitation_id.is_a?(String) && elicitation_id.present?
+          raise ArgumentError, "elicitation_id must be a non-empty string"
+        end
+
         send_jsonrpc_notification(
           "notifications/elicitation/complete",
           { elicitationId: elicitation_id }
@@ -69,22 +77,35 @@ module ActionMCP
       # @param elicitations [Array<Hash>] Required URL mode elicitations
       def send_url_elicitation_required_error(request_id, message:, elicitations:)
         require_client_elicitation_support!(:url)
+        raise ArgumentError, "message must be a string" unless message.is_a?(String)
+        raise ArgumentError, "elicitations must be an array" unless elicitations.is_a?(Array)
 
-        elicitations.each do |e|
-          raise ArgumentError, "Each elicitation must have mode: 'url'" unless e[:mode] == "url"
-          raise ArgumentError, "Each elicitation must have an elicitationId" unless e[:elicitationId].present?
+        normalized_elicitations = elicitations.map do |elicitation|
+          unless elicitation.respond_to?(:to_h) && elicitation.to_h.is_a?(Hash)
+            raise ArgumentError, "Each elicitation must be an object"
+          end
 
-          UrlElicitationRequest.new(
-            message: e[:message],
-            url: e[:url],
-            elicitation_id: e[:elicitationId]
-          ).assert_valid!
+          attributes = elicitation.to_h.with_indifferent_access
+          raise ArgumentError, "Each elicitation must have mode: 'url'" unless attributes[:mode] == "url"
+          raise ArgumentError, "Each elicitation must have an elicitationId" unless attributes[:elicitationId].present?
+
+          request = UrlElicitationRequest.new(
+            message: attributes[:message],
+            url: attributes[:url],
+            elicitation_id: attributes[:elicitationId],
+            _meta: attributes[:_meta],
+            task: attributes[:task]
+          )
+          request.assert_valid!
+
+          extensions = attributes.except(:mode, :message, :url, :elicitationId, :_meta, :task)
+          request.to_params.merge(extensions)
         end
 
         error = {
           code: URL_ELICITATION_REQUIRED_CODE,
           message: message,
-          data: { elicitations: elicitations }
+          data: { elicitations: normalized_elicitations }
         }
 
         send_jsonrpc_response(request_id, error: error)
@@ -101,23 +122,24 @@ module ActionMCP
         raise UnsupportedElicitationError, "Client does not support elicitation" unless elicitation_caps.is_a?(Hash)
 
         if mode == :form
-          # Empty hash or explicit form: {} both mean form support (backward compat with 2025-06-18)
-          # But if client only declared url: {} without form, reject
           form_cap = elicitation_caps["form"] || elicitation_caps[:form]
-          unless elicitation_caps.empty? || form_cap
-            raise UnsupportedElicitationError, "Client does not support form mode elicitation"
-          end
+          raise UnsupportedElicitationError, "Client does not support form mode elicitation" unless form_cap.is_a?(Hash)
           return
         end
 
-        # URL mode requires protocol version 2025-11-25+
-        unless session.protocol_version == "2025-11-25"
-          raise UnsupportedElicitationError, "URL mode elicitation requires protocol version 2025-11-25"
-        end
-
-        # Client must explicitly declare url mode support (empty hash = form-only for 2025-06-18 clients)
         url_cap = elicitation_caps["url"] || elicitation_caps[:url]
-        raise UnsupportedElicitationError, "Client does not support URL mode elicitation" unless url_cap
+        raise UnsupportedElicitationError, "Client does not support URL mode elicitation" unless url_cap.is_a?(Hash)
+      end
+
+      def require_client_elicitation_task_support!
+        client_capabilities = session.client_capabilities || {}
+        tasks = client_capabilities["tasks"] || client_capabilities[:tasks]
+        requests = tasks.is_a?(Hash) && (tasks["requests"] || tasks[:requests])
+        elicitation = requests.is_a?(Hash) && (requests["elicitation"] || requests[:elicitation])
+        create = elicitation.is_a?(Hash) && (elicitation["create"] || elicitation[:create])
+        return if create.is_a?(Hash)
+
+        raise UnsupportedElicitationError, "Client does not support task-augmented elicitation"
       end
     end