actionmcp 0.111.1 → 0.200.0

data/lib/action_mcp/server/sampling_request.rb

@@ -1,114 +1,376 @@
 # frozen_string_literal: true
 
+require "json_schemer"
+
 module ActionMCP
   module Server
     class SamplingRequest
-      class << self
-        attr_reader :default_messages, :default_system_prompt, :default_context,
-                    :default_model_hints, :default_intelligence_priority,
-                    :default_max_tokens, :default_temperature
+      UNSET = Object.new.freeze
+
+      TOOL_SCHEMA_OBJECT = {
+        "type" => "object",
+        "required" => [ "type" ],
+        "properties" => {
+          "$schema" => { "type" => "string" },
+          "properties" => {
+            "type" => "object",
+            "additionalProperties" => {
+              "type" => "object",
+              "properties" => {},
+              "additionalProperties" => true
+            }
+          },
+          "required" => { "type" => "array", "items" => { "type" => "string" } },
+          "type" => { "type" => "string", "const" => "object" }
+        }
+      }.freeze
+
+      SAMPLING_DEFINITIONS = Content::Validation::DEFINITIONS.merge(
+        "ProgressToken" => { "type" => %w[string integer] },
+        "Role" => { "type" => "string", "enum" => %w[assistant user] },
+        "ToolSchema" => TOOL_SCHEMA_OBJECT,
+        "ModelHint" => {
+          "type" => "object",
+          "properties" => { "name" => { "type" => "string" } }
+        },
+        "ModelPreferences" => {
+          "type" => "object",
+          "properties" => {
+            "hints" => {
+              "type" => "array",
+              "items" => { "$ref" => "#/$defs/ModelHint" }
+            },
+            "costPriority" => { "type" => "number", "minimum" => 0, "maximum" => 1 },
+            "speedPriority" => { "type" => "number", "minimum" => 0, "maximum" => 1 },
+            "intelligencePriority" => { "type" => "number", "minimum" => 0, "maximum" => 1 }
+          }
+        },
+        "ToolAnnotations" => {
+          "type" => "object",
+          "properties" => {
+            "destructiveHint" => { "type" => "boolean" },
+            "idempotentHint" => { "type" => "boolean" },
+            "openWorldHint" => { "type" => "boolean" },
+            "readOnlyHint" => { "type" => "boolean" },
+            "title" => { "type" => "string" }
+          }
+        },
+        "ToolExecution" => {
+          "type" => "object",
+          "properties" => {
+            "taskSupport" => {
+              "type" => "string",
+              "enum" => %w[forbidden optional required]
+            }
+          }
+        },
+        "Tool" => {
+          "type" => "object",
+          "required" => %w[inputSchema name],
+          "properties" => Content::Validation::META_PROPERTY.merge(
+            "annotations" => { "$ref" => "#/$defs/ToolAnnotations" },
+            "description" => { "type" => "string" },
+            "execution" => { "$ref" => "#/$defs/ToolExecution" },
+            "icons" => { "type" => "array", "items" => { "$ref" => "#/$defs/Icon" } },
+            "inputSchema" => { "$ref" => "#/$defs/ToolSchema" },
+            "name" => { "type" => "string" },
+            "outputSchema" => { "$ref" => "#/$defs/ToolSchema" },
+            "title" => { "type" => "string" }
+          )
+        },
+        "ToolChoice" => {
+          "type" => "object",
+          "properties" => {
+            "mode" => { "type" => "string", "enum" => %w[auto none required] }
+          }
+        },
+        "TaskMetadata" => {
+          "type" => "object",
+          "properties" => { "ttl" => { "type" => "integer" } }
+        },
+        "ToolUseContent" => {
+          "type" => "object",
+          "required" => %w[id input name type],
+          "properties" => Content::Validation::META_PROPERTY.merge(
+            "id" => { "type" => "string" },
+            "input" => { "type" => "object" },
+            "name" => { "type" => "string" },
+            "type" => { "type" => "string", "const" => "tool_use" }
+          )
+        },
+        "ToolResultContent" => {
+          "type" => "object",
+          "required" => %w[content toolUseId type],
+          "properties" => Content::Validation::META_PROPERTY.merge(
+            "content" => {
+              "type" => "array",
+              "items" => { "$ref" => "#/$defs/ContentBlock" }
+            },
+            "isError" => { "type" => "boolean" },
+            "structuredContent" => { "type" => "object" },
+            "toolUseId" => { "type" => "string" },
+            "type" => { "type" => "string", "const" => "tool_result" }
+          )
+        },
+        "SamplingMessageContentBlock" => {
+          "anyOf" => %w[TextContent ImageContent AudioContent ToolUseContent ToolResultContent].map do |name|
+            { "$ref" => "#/$defs/#{name}" }
+          end
+        },
+        "SamplingMessage" => {
+          "type" => "object",
+          "required" => %w[content role],
+          "properties" => Content::Validation::META_PROPERTY.merge(
+            "content" => {
+              "anyOf" => [
+                { "$ref" => "#/$defs/SamplingMessageContentBlock" },
+                {
+                  "type" => "array",
+                  "items" => { "$ref" => "#/$defs/SamplingMessageContentBlock" }
+                }
+              ]
+            },
+            "role" => { "$ref" => "#/$defs/Role" }
+          )
+        },
+        "CreateMessageRequestParams" => {
+          "type" => "object",
+          "required" => %w[maxTokens messages],
+          "properties" => {
+            "_meta" => {
+              "type" => "object",
+              "properties" => {
+                "progressToken" => { "$ref" => "#/$defs/ProgressToken" }
+              }
+            },
+            "includeContext" => {
+              "type" => "string",
+              "enum" => %w[allServers none thisServer]
+            },
+            "maxTokens" => { "type" => "integer" },
+            "messages" => {
+              "type" => "array",
+              "items" => { "$ref" => "#/$defs/SamplingMessage" }
+            },
+            "metadata" => { "type" => "object" },
+            "modelPreferences" => { "$ref" => "#/$defs/ModelPreferences" },
+            "stopSequences" => { "type" => "array", "items" => { "type" => "string" } },
+            "systemPrompt" => { "type" => "string" },
+            "task" => { "$ref" => "#/$defs/TaskMetadata" },
+            "temperature" => { "type" => "number" },
+            "toolChoice" => { "$ref" => "#/$defs/ToolChoice" },
+            "tools" => { "type" => "array", "items" => { "$ref" => "#/$defs/Tool" } }
+          }
+        }
+      ).freeze
+
+      PARAMS_SCHEMA = {
+        "$schema" => "https://json-schema.org/draft/2020-12/schema",
+        "$ref" => "#/$defs/CreateMessageRequestParams",
+        "$defs" => SAMPLING_DEFINITIONS
+      }.freeze
+      PARAMS_SCHEMER = JSONSchemer.schema(
+        PARAMS_SCHEMA,
+        formats: Content::Validation::FORMAT_VALIDATORS
+      )
 
+      class << self
         def configure
           yield self
         end
 
-        def messages(messages = nil)
-          if messages
-            @default_messages = messages.map do |msg|
-              mutate_content(msg)
-            end
-          end
-          @messages ||= []
+        def messages(value = UNSET)
+          @default_messages = value.map { |message| normalize_message(message) } unless value.equal?(UNSET)
+          @default_messages ||= []
         end
 
-        def system_prompt(prompt = nil)
-          @default_system_prompt = prompt if prompt
+        def system_prompt(value = UNSET)
+          @default_system_prompt = value unless value.equal?(UNSET)
           @default_system_prompt
         end
 
-        def include_context(context = nil)
-          @default_context = context if context
+        def include_context(value = UNSET)
+          @default_context = value unless value.equal?(UNSET)
           @default_context
         end
 
-        def model_hints(hints = nil)
-          @default_model_hints = hints if hints
-          @model_hints ||= []
+        def model_hints(value = UNSET)
+          @default_model_hints = value unless value.equal?(UNSET)
+          @default_model_hints ||= []
         end
 
-        def intelligence_priority(priority = nil)
-          @default_intelligence_priority = priority if priority
-          @intelligence_priority ||= 0.9
+        def intelligence_priority(value = UNSET)
+          @default_intelligence_priority = value unless value.equal?(UNSET)
+          @default_intelligence_priority.nil? ? 0.9 : @default_intelligence_priority
         end
 
-        def max_tokens(tokens = nil)
-          @default_max_tokens = tokens if tokens
-          @max_tokens ||= 500
+        def max_tokens(value = UNSET)
+          @default_max_tokens = value unless value.equal?(UNSET)
+          @default_max_tokens.nil? ? 500 : @default_max_tokens
         end
 
-        def temperature(temp = nil)
-          @default_temperature = temp if temp
-          @temperature ||= 0.7
+        def temperature(value = UNSET)
+          @default_temperature = value unless value.equal?(UNSET)
+          @default_temperature.nil? ? 0.7 : @default_temperature
+        end
+
+        def validate_params!(params)
+          raise ArgumentError, "Sampling request params must be an object" unless params.is_a?(Hash)
+
+          wire_params = params.deep_stringify_keys
+          errors = PARAMS_SCHEMER.validate(wire_params).to_a
+          unless errors.empty?
+            pointers = errors.map { |error| error["data_pointer"].presence || "/" }.uniq
+            raise ArgumentError, "Sampling request must match MCP 2025-11-25 at #{pointers.join(', ')}"
+          end
+
+          validate_tool_conversation!(wire_params.fetch("messages"))
+          params
         end
 
         private
 
-        def mutate_content(msg)
-          content = msg[:content]
-          if content.is_a?(ActionMCP::Content) || (content.respond_to?(:to_h) && !content.is_a?(Hash))
-            { role: msg[:role], content: content.to_h }
-          else
-            msg
+        def validate_tool_conversation!(messages)
+          expected_ids = nil
+          seen_tool_use_ids = {}
+
+          messages.each_with_index do |message, index|
+            blocks = message["content"].is_a?(Array) ? message["content"] : [ message["content"] ]
+            tool_results = blocks.select { |block| block["type"] == "tool_result" }
+
+            if expected_ids
+              validate_tool_results!(message, blocks, tool_results, expected_ids, index)
+              expected_ids = nil
+              next
+            end
+
+            if tool_results.any?
+              validate_tool_result_message!(message, blocks, index)
+              invalid_tool_conversation!(index, "tool results do not match a preceding tool use")
+            end
+
+            tool_uses = blocks.select { |block| block["type"] == "tool_use" }
+            next if tool_uses.empty?
+
+            unless message["role"] == "assistant"
+              invalid_tool_conversation!(index, "tool uses must be in an assistant message")
+            end
+
+            ids = tool_uses.map { |tool_use| tool_use.fetch("id") }
+            reject_duplicate_ids!(ids, index, "tool use")
+
+            if (duplicate = ids.find { |id| seen_tool_use_ids.key?(id) })
+              invalid_tool_conversation!(index, "tool use ID #{duplicate.inspect} is not unique")
+            end
+
+            ids.each { |id| seen_tool_use_ids[id] = true }
+            expected_ids = ids
+          end
+
+          return unless expected_ids
+
+          invalid_tool_conversation!(messages.length, "assistant tool uses are missing their next user results")
+        end
+
+        def validate_tool_results!(message, blocks, tool_results, expected_ids, index)
+          validate_tool_result_message!(message, blocks, index)
+
+          result_ids = tool_results.map { |tool_result| tool_result.fetch("toolUseId") }
+          reject_duplicate_ids!(result_ids, index, "tool result")
+          return if result_ids.sort == expected_ids.sort
+
+          invalid_tool_conversation!(index, "tool result IDs must exactly match the preceding tool use IDs")
+        end
+
+        def validate_tool_result_message!(message, blocks, index)
+          valid = message["role"] == "user" && blocks.any? &&
+                  blocks.all? { |block| block["type"] == "tool_result" }
+          return if valid
+
+          invalid_tool_conversation!(index, "tool result messages must be user messages containing only results")
+        end
+
+        def reject_duplicate_ids!(ids, index, label)
+          return if ids.uniq.length == ids.length
+
+          invalid_tool_conversation!(index, "#{label} IDs must not contain duplicates")
+        end
+
+        def invalid_tool_conversation!(index, reason)
+          raise ArgumentError,
+                "Sampling request must match MCP 2025-11-25 at /messages/#{index}: #{reason}"
+        end
+
+        def normalize_message(message)
+          raise ArgumentError, "Sampling messages must be objects" unless message.is_a?(Hash)
+
+          normalized = message.symbolize_keys
+          content = normalized[:content]
+          if content.respond_to?(:to_h) && !content.is_a?(Hash) && !content.is_a?(Array)
+            normalized[:content] = content.to_h
           end
+          normalized
         end
       end
 
-      attr_accessor :system_prompt, :model_hints, :intelligence_priority, :max_tokens, :temperature
+      attr_accessor :system_prompt, :model_hints, :cost_priority, :speed_priority,
+                    :intelligence_priority, :max_tokens, :temperature, :stop_sequences,
+                    :metadata, :tools, :tool_choice, :task, :request_meta
       attr_reader :messages, :context
 
       def initialize
-        @messages = self.class.default_messages.dup
-        @system_prompt = self.class.default_system_prompt
-        @context = self.class.default_context
-        @model_hints = self.class.default_model_hints.dup
-        @intelligence_priority = self.class.default_intelligence_priority
-        @max_tokens = self.class.default_max_tokens
-        @temperature = self.class.default_temperature
+        @messages = self.class.messages.map(&:deep_dup)
+        @system_prompt = self.class.system_prompt
+        @context = self.class.include_context
+        @model_hints = self.class.model_hints.deep_dup
+        @intelligence_priority = self.class.intelligence_priority
+        @max_tokens = self.class.max_tokens
+        @temperature = self.class.temperature
 
         yield self if block_given?
       end
 
       def messages=(value)
-        @messages = value.map do |msg|
-          self.class.send(:mutate_content, msg)
-        end
+        @messages = value.map { |message| self.class.send(:normalize_message, message) }
       end
 
       def include_context=(value)
         @context = value
       end
 
-      def add_message(content, role: "user")
-        if content.is_a?(Content::Base) || (content.respond_to?(:to_h) && !content.is_a?(Hash))
-          @messages << { role: role, content: content.to_h }
-        else
-          content = Content::Text.new(content, annotations: nil).to_h if content.is_a?(String)
-          @messages << { role: role, content: content }
+      def add_message(content, role: "user", _meta: nil)
+        if content.respond_to?(:to_h) && !content.is_a?(Hash) && !content.is_a?(Array)
+          content = content.to_h
         end
+        content = Content::Text.new(content, annotations: nil).to_h if content.is_a?(String)
+
+        message = { role: role, content: content }
+        message[:_meta] = _meta if _meta
+        @messages << message
       end
 
       def to_h
-        {
-          messages: messages.map { |msg| { role: msg[:role], content: msg[:content] } },
+        params = {
+          messages: messages.map { |message| message.slice(:role, :content, :_meta).compact },
           systemPrompt: system_prompt,
           includeContext: context,
           modelPreferences: {
-            hints: model_hints.map { |name| { name: name } },
+            hints: model_hints.map { |hint| hint.is_a?(Hash) ? hint : { name: hint } },
+            costPriority: cost_priority,
+            speedPriority: speed_priority,
             intelligencePriority: intelligence_priority
-          },
+          }.compact,
           maxTokens: max_tokens,
-          temperature: temperature
+          temperature: temperature,
+          stopSequences: stop_sequences,
+          metadata: metadata,
+          tools: tools,
+          toolChoice: tool_choice,
+          task: task,
+          _meta: request_meta
         }.compact
+
+        self.class.validate_params!(params)
       end
     end
   end

data/lib/action_mcp/server/tasks.rb

@@ -5,7 +5,7 @@ module ActionMCP
     # 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 or input_required state)
+    # - tasks/result: Get task result (blocking until a terminal state)
     # - tasks/list: List tasks for the session
     # - tasks/cancel: Cancel a task
     module Tasks
@@ -19,35 +19,17 @@ module ActionMCP
         send_jsonrpc_response(request_id, result: task.to_task_data)
       end
 
-      # Get task result, blocking until task reaches terminal or input_required state
+      # Get task result, blocking until the task reaches a 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
 
-        unless task.result_ready?
-          case ActionMCP.configuration.tasks_result_strategy
-          when :polling_only
-            send_jsonrpc_error(
-              request_id,
-              :invalid_request,
-              "Task is not ready. Poll tasks/get over HTTP until the task reaches a terminal or input_required status, then retry tasks/result."
-            )
-            return
-          else
-            task = wait_for_result_ready_task(task_id)
-            unless task&.result_ready?
-              send_jsonrpc_response(
-                request_id,
-                error: {
-                  code: -32_000,
-                  message: "Timed out waiting for task '#{task_id}' to reach a terminal or input_required status"
-                }
-              )
-              return
-            end
-          end
+        task = wait_for_terminal_task(task_id) unless task.terminal?
+        unless task
+          send_jsonrpc_error(request_id, :invalid_params, "Task '#{task_id}' not found")
+          return
         end
 
         if (error = task.to_task_error)
@@ -83,19 +65,28 @@ module ActionMCP
         task = find_task(task_id)
         return unless task
 
-        if task.terminal?
+        terminal_status = nil
+        task.with_lock do
+          if task.terminal?
+            terminal_status = task.status
+            next
+          end
+
+          task.status_message = "The task was cancelled by request." if task.status_message.blank?
+          task.result_payload ||= {
+            code: -32_000,
+            message: "Task was cancelled"
+          }
+          task.save! if task.changed?
+          task.cancel!
+        end
+
+        if terminal_status
           send_jsonrpc_error(request_id, :invalid_params,
-                             "Cannot cancel task in terminal status: #{task.status}")
+                             "Cannot cancel task in terminal status: #{terminal_status}")
           return
         end
 
-        task.status_message = "The task was cancelled by request." if task.status_message.blank?
-        task.result_payload ||= {
-          code: -32_000,
-          message: "Task was cancelled"
-        }
-        task.save! if task.changed?
-        task.cancel!
         send_jsonrpc_response(request_id, result: task.to_task_data)
       end
 
@@ -144,17 +135,12 @@ module ActionMCP
         task
       end
 
-      def wait_for_result_ready_task(task_id)
-        deadline = monotonic_time + ActionMCP.configuration.tasks_result_timeout.to_f
-
+      def wait_for_terminal_task(task_id)
         loop do
           task = load_task_for_result(task_id)
-          return task if task.nil? || task.result_ready?
-
-          remaining = deadline - monotonic_time
-          return task unless remaining.positive?
+          return task if task.nil? || task.terminal?
 
-          sleep [ ActionMCP.configuration.tasks_result_poll_interval.to_f, remaining ].min
+          sleep ActionMCP.configuration.tasks_result_poll_interval.to_f
         end
       end
 
@@ -163,10 +149,6 @@ module ActionMCP
           session.tasks.find_by(id: task_id)
         end
       end
-
-      def monotonic_time
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
     end
   end
 end

data/lib/action_mcp/server/tool_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Server
+    module ToolResult
+      module_function
+
+      def normalize(response)
+        payload = response.to_h
+        code = payload[:code] || payload["code"]
+        return response unless response.error? && code == -32_602
+
+        execution_error(
+          payload[:message] || payload["message"],
+          data: payload[:data] || payload["data"]
+        )
+      end
+
+      def execution_error(message, data: nil)
+        details = data.is_a?(Array) ? data.join(", ") : nil
+        text = [ message, details ].compact_blank.join(": ")
+
+        ToolResponse.new.tap { |response| response.report_tool_error(text) }
+      end
+    end
+  end
+end

data/lib/action_mcp/server/tools.rb

@@ -31,7 +31,7 @@ module ActionMCP
 
         unless tool_class
           Rails.logger.error "Tool not found: #{tool_name}. Registered tools: #{session.registered_tools.map(&:tool_name).join(', ')}"
-          send_jsonrpc_error(request_id, :method_not_found,
+          send_jsonrpc_error(request_id, :invalid_params,
                              "Tool '#{tool_name}' not found or not registered for this session")
           return
         end
@@ -51,8 +51,7 @@ module ActionMCP
         task_requested = !task_params.nil?
 
         if task_requested && !tasks_enabled?
-          send_jsonrpc_error(request_id, :method_not_found,
-                             "Task-augmented execution is not available for this session")
+          execute_tool_synchronously(request_id, tool_class, tool_name, arguments, _meta)
           return
         end
 
@@ -74,7 +73,7 @@ module ActionMCP
           return
         end
 
-        if !task_requested && task_support == :required
+        if !task_requested && tasks_enabled? && task_support == :required
           send_jsonrpc_error(request_id, :method_not_found,
                              "Tool '#{tool_name}' requires task-augmented execution")
           return
@@ -89,7 +88,7 @@ module ActionMCP
       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)
+          tool = tool_class.from_wire(arguments)
           tool.with_context({
                               session: session,
                               request: {
@@ -117,6 +116,8 @@ module ActionMCP
                      tool.call
           end
 
+          result = ToolResult.normalize(result)
+
           if result.is_error
             # Protocol error
             send_jsonrpc_response(request_id, error: result.to_h)
@@ -125,11 +126,9 @@ module ActionMCP
             send_jsonrpc_response(request_id, result: result.to_h)
           end
         rescue ArgumentError => e
-          # Handle parameter validation errors (e.g. alias conflicts)
-          send_jsonrpc_error(request_id, :invalid_params, e.message)
+          send_jsonrpc_response(request_id, result: ToolResult.execution_error(e.message).to_h)
         rescue ActiveModel::UnknownAttributeError => e
-          # Undeclared param on a strict tool — message already names the key + tool
-          send_jsonrpc_error(request_id, :invalid_params, e.message)
+          send_jsonrpc_response(request_id, result: ToolResult.execution_error(e.message).to_h)
         rescue StandardError => e
           # Log the actual error for debugging
           Rails.logger.error "Tool execution error: #{e.class} - #{e.message}"
@@ -177,7 +176,10 @@ module ActionMCP
       end
 
       def tasks_enabled?
-        ActionMCP.configuration.tasks_enabled && session.protocol_version == "2025-11-25"
+        return false unless session.protocol_version == "2025-11-25"
+
+        capabilities = (session.server_capabilities || {}).with_indifferent_access
+        capabilities.dig(:tasks, :requests, :tools, :call).is_a?(Hash)
       end
 
       def tool_task_support(tool_class)

data/lib/action_mcp/server/transport_handler.rb

@@ -3,6 +3,7 @@
 require_relative "pagination"
 require_relative "response_collector"
 require_relative "base_messaging"
+require_relative "client_notifications"
 
 module ActionMCP
   module Server
@@ -14,10 +15,12 @@ module ActionMCP
 
       include  Pagination
       include  MessagingService
+      include  ClientNotifications
       include  Capabilities
       include  Tools
       include  Prompts
       include  Resources
+      include  Completions
       include  Sampling
       include  Roots
       include  Elicitation