feat: Structured task management (MCP 2025-11-25)

lib/mcp_client.rb

@@ -10,6 +10,7 @@
 require_relative 'mcp_client/audio_content'
 require_relative 'mcp_client/root'
 require_relative 'mcp_client/elicitation_validator'
+require_relative 'mcp_client/task'
 require_relative 'mcp_client/server_base'
 require_relative 'mcp_client/server_stdio'
 require_relative 'mcp_client/server_sse'

lib/mcp_client/client.rb

@@ -497,6 +497,76 @@ def complete(ref:, argument:, context: nil, server: nil)
       srv.complete(ref: ref, argument: argument, context: context)
     end
 
+    # Create a new task on a server (MCP 2025-11-25)
+    # Tasks represent long-running operations that can report progress
+    # @param method [String] the method to execute as a task
+    # @param params [Hash] parameters for the task method
+    # @param progress_token [String, nil] optional token for receiving progress notifications
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the created task
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskError] if task creation fails
+    def create_task(method, params: {}, progress_token: nil, server: nil)
+      srv = select_server(server)
+      rpc_params = { method: method, params: params }
+      rpc_params[:progressToken] = progress_token if progress_token
+
+      begin
+        result = srv.rpc_request('tasks/create', rpc_params)
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError => e
+        raise MCPClient::Errors::TaskError, "Error creating task: #{e.message}"
+      end
+    end
+
+    # Get the current state of a task (MCP 2025-11-25)
+    # @param task_id [String] the ID of the task to query
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the task with current state
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
+    # @raise [MCPClient::Errors::TaskError] if retrieving the task fails
+    def get_task(task_id, server: nil)
+      srv = select_server(server)
+
+      begin
+        result = srv.rpc_request('tasks/get', { id: task_id })
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError => e
+        if e.message.include?('not found') || e.message.include?('unknown task')
+          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
+        end
+
+        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
+      rescue MCPClient::Errors::TransportError => e
+        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
+      end
+    end
+
+    # Cancel a running task (MCP 2025-11-25)
+    # @param task_id [String] the ID of the task to cancel
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the task with updated (cancelled) state
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
+    # @raise [MCPClient::Errors::TaskError] if cancellation fails
+    def cancel_task(task_id, server: nil)
+      srv = select_server(server)
+
+      begin
+        result = srv.rpc_request('tasks/cancel', { id: task_id })
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError => e
+        if e.message.include?('not found') || e.message.include?('unknown task')
+          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
+        end
+
+        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+      rescue MCPClient::Errors::TransportError => e
+        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+      end
+    end
+
     # Set the logging level on all connected servers (MCP 2025-06-18)
     # To set on a specific server, use: client.find_server('name').log_level = 'debug'
     # @param level [String] the log level ('debug', 'info', 'notice', 'warning', 'error',

lib/mcp_client/errors.rb

@@ -50,5 +50,11 @@ class AmbiguousResourceURI < MCPError; end
 
     # Raised when transport type cannot be determined from target URL/command
     class TransportDetectionError < MCPError; end
+
+    # Raised when a task is not found
+    class TaskNotFound < MCPError; end
+
+    # Raised when there's an error creating or managing a task
+    class TaskError < MCPError; end
   end
 end

lib/mcp_client/task.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Represents an MCP Task for long-running operations with progress tracking
+  # Tasks follow the MCP 2025-11-25 specification for structured task management
+  #
+  # Task states: pending, running, completed, failed, cancelled
+  class Task
+    # Valid task states
+    VALID_STATES = %w[pending running completed failed cancelled].freeze
+
+    attr_reader :id, :state, :progress_token, :progress, :total, :message, :result, :server
+
+    # Create a new Task
+    # @param id [String] unique task identifier
+    # @param state [String] task state (pending, running, completed, failed, cancelled)
+    # @param progress_token [String, nil] optional token for tracking progress
+    # @param progress [Integer, nil] current progress value
+    # @param total [Integer, nil] total progress value
+    # @param message [String, nil] human-readable status message
+    # @param result [Object, nil] task result (when completed)
+    # @param server [MCPClient::ServerBase, nil] the server this task belongs to
+    def initialize(id:, state: 'pending', progress_token: nil, progress: nil, total: nil,
+                   message: nil, result: nil, server: nil)
+      validate_state!(state)
+      @id = id
+      @state = state
+      @progress_token = progress_token
+      @progress = progress
+      @total = total
+      @message = message
+      @result = result
+      @server = server
+    end
+
+    # Create a Task from a JSON hash
+    # @param json [Hash] the JSON hash with task fields
+    # @param server [MCPClient::ServerBase, nil] optional server reference
+    # @return [Task]
+    def self.from_json(json, server: nil)
+      new(
+        id: json['id'] || json[:id],
+        state: json['state'] || json[:state] || 'pending',
+        progress_token: json['progressToken'] || json[:progressToken] || json[:progress_token],
+        progress: json['progress'] || json[:progress],
+        total: json['total'] || json[:total],
+        message: json['message'] || json[:message],
+        result: json.key?('result') ? json['result'] : json[:result],
+        server: server
+      )
+    end
+
+    # Convert to JSON-serializable hash
+    # @return [Hash]
+    def to_h
+      result = { 'id' => @id, 'state' => @state }
+      result['progressToken'] = @progress_token if @progress_token
+      result['progress'] = @progress if @progress
+      result['total'] = @total if @total
+      result['message'] = @message if @message
+      result['result'] = @result unless @result.nil?
+      result
+    end
+
+    # Convert to JSON string
+    # @return [String]
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    # Check if task is in a terminal state
+    # @return [Boolean]
+    def terminal?
+      %w[completed failed cancelled].include?(@state)
+    end
+
+    # Check if task is still active (pending or running)
+    # @return [Boolean]
+    def active?
+      %w[pending running].include?(@state)
+    end
+
+    # Calculate progress percentage
+    # @return [Float, nil] percentage (0.0-100.0) or nil if progress info unavailable
+    def progress_percentage
+      return nil unless @progress && @total&.positive?
+
+      (@progress.to_f / @total * 100).round(2)
+    end
+
+    # Check equality
+    def ==(other)
+      return false unless other.is_a?(Task)
+
+      id == other.id && state == other.state
+    end
+
+    alias eql? ==
+
+    def hash
+      [id, state].hash
+    end
+
+    # String representation
+    def to_s
+      parts = ["Task[#{@id}]: #{@state}"]
+      parts << "(#{@progress}/#{@total})" if @progress && @total
+      parts << "- #{@message}" if @message
+      parts.join(' ')
+    end
+
+    def inspect
+      "#<MCPClient::Task id=#{@id.inspect} state=#{@state.inspect}>"
+    end
+
+    private
+
+    # Validate task state
+    # @param state [String] the state to validate
+    # @raise [ArgumentError] if the state is not valid
+    def validate_state!(state)
+      return if VALID_STATES.include?(state)
+
+      raise ArgumentError, "Invalid task state: #{state.inspect}. Must be one of: #{VALID_STATES.join(', ')}"
+    end
+  end
+end