ruby-mcp-client 1.0.1 → 1.1.0

data/lib/mcp_client/task.rb

@@ -1,65 +1,94 @@
 # 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
+  # Represents an MCP Task for long-running, task-augmented operations.
+  # Conforms to the MCP 2025-11-25 Tasks utility.
   #
-  # Task states: pending, running, completed, failed, cancelled
+  # Task statuses: working, input_required, completed, failed, cancelled.
+  # A task begins in `working`; completed/failed/cancelled are terminal.
   class Task
-    # Valid task states
-    VALID_STATES = %w[pending running completed failed cancelled].freeze
+    # Valid task statuses (MCP 2025-11-25)
+    VALID_STATUSES = %w[working input_required completed failed cancelled].freeze
 
-    attr_reader :id, :state, :progress_token, :progress, :total, :message, :result, :server
+    # Statuses from which a task will not transition further
+    TERMINAL_STATUSES = %w[completed failed cancelled].freeze
+
+    attr_reader :task_id, :status, :status_message, :created_at, :last_updated_at, :ttl, :poll_interval, :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 task_id [String] unique task identifier
+    # @param status [String] task status (working, input_required, completed, failed, cancelled)
+    # @param status_message [String, nil] optional human-readable status detail
+    # @param created_at [String, nil] ISO 8601 creation timestamp
+    # @param last_updated_at [String, nil] ISO 8601 last-update timestamp
+    # @param ttl [Integer, nil] retention duration in milliseconds since creation (nil = unspecified)
+    # @param poll_interval [Integer, nil] suggested polling interval in milliseconds
     # @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
+    def initialize(task_id:, status: 'working', status_message: nil, created_at: nil,
+                   last_updated_at: nil, ttl: nil, poll_interval: nil, server: nil)
+      validate_status!(status)
+      @task_id = task_id
+      @status = status
+      @status_message = status_message
+      @created_at = created_at
+      @last_updated_at = last_updated_at
+      @ttl = ttl
+      @poll_interval = poll_interval
       @server = server
     end
 
-    # Create a Task from a JSON hash
-    # @param json [Hash] the JSON hash with task fields
+    # Build a Task from a flat Task hash. This is the shape of GetTaskResult,
+    # CancelTaskResult, the items in a ListTasksResult, and the params of a
+    # notifications/tasks/status notification.
+    # @param json [Hash] the flat task hash
     # @param server [MCPClient::ServerBase, nil] optional server reference
     # @return [Task]
     def self.from_json(json, server: nil)
+      data = json || {}
       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],
+        task_id: extract_field(data, 'taskId', :task_id),
+        status: extract_field(data, 'status') || 'working',
+        status_message: extract_field(data, 'statusMessage', :status_message),
+        created_at: extract_field(data, 'createdAt', :created_at),
+        last_updated_at: extract_field(data, 'lastUpdatedAt', :last_updated_at),
+        ttl: extract_field(data, 'ttl'),
+        poll_interval: extract_field(data, 'pollInterval', :poll_interval),
         server: server
       )
     end
 
-    # Convert to JSON-serializable hash
+    # Build a Task from a CreateTaskResult, which wraps the task under `task`.
+    # @param result [Hash] the CreateTaskResult ({ 'task' => { ... } })
+    # @param server [MCPClient::ServerBase, nil] optional server reference
+    # @return [Task]
+    def self.from_create_result(result, server: nil)
+      task_data = (result && (result['task'] || result[:task])) || result
+      from_json(task_data, server: server)
+    end
+
+    # Read a value by camelCase string key, falling back to a snake_case symbol.
+    # Uses key? so an explicit null value is preserved (not treated as absent).
+    # @return [Object, nil]
+    def self.extract_field(data, str_key, sym_key = nil)
+      return data[str_key] if data.key?(str_key)
+      return data[str_key.to_sym] if data.key?(str_key.to_sym)
+      return data[sym_key] if sym_key && data.key?(sym_key)
+
+      nil
+    end
+    private_class_method :extract_field
+
+    # Convert to a spec-shaped, 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
+      # ttl is a REQUIRED Task field whose value may be null, so it is always
+      # included (even when nil). The other optional fields are omitted when nil.
+      hash = { 'taskId' => @task_id, 'status' => @status, 'ttl' => @ttl }
+      hash['statusMessage'] = @status_message if @status_message
+      hash['createdAt'] = @created_at if @created_at
+      hash['lastUpdatedAt'] = @last_updated_at if @last_updated_at
+      hash['pollInterval'] = @poll_interval if @poll_interval
+      hash
     end
 
     # Convert to JSON string
@@ -68,60 +97,63 @@ module MCPClient
       to_h.to_json(*)
     end
 
-    # Check if task is in a terminal state
+    # Whether the task is in a terminal status (completed, failed, cancelled)
     # @return [Boolean]
     def terminal?
-      %w[completed failed cancelled].include?(@state)
+      TERMINAL_STATUSES.include?(@status)
     end
 
-    # Check if task is still active (pending or running)
+    # Whether the task is still active (not terminal — working or input_required)
     # @return [Boolean]
     def active?
-      %w[pending running].include?(@state)
+      !terminal?
     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?
+    # Whether the task is waiting for input (status input_required)
+    # @return [Boolean]
+    def input_required?
+      @status == 'input_required'
+    end
 
-      (@progress.to_f / @total * 100).round(2)
+    # Whether the task is still running (status working)
+    # @return [Boolean]
+    def working?
+      @status == 'working'
     end
 
     # Check equality
     def ==(other)
       return false unless other.is_a?(Task)
 
-      id == other.id && state == other.state
+      task_id == other.task_id && status == other.status
     end
 
     alias eql? ==
 
     def hash
-      [id, state].hash
+      [task_id, status].hash
     end
 
     # String representation
     def to_s
-      parts = ["Task[#{@id}]: #{@state}"]
-      parts << "(#{@progress}/#{@total})" if @progress && @total
-      parts << "- #{@message}" if @message
+      parts = ["Task[#{@task_id}]: #{@status}"]
+      parts << "- #{@status_message}" if @status_message
       parts.join(' ')
     end
 
     def inspect
-      "#<MCPClient::Task id=#{@id.inspect} state=#{@state.inspect}>"
+      "#<MCPClient::Task task_id=#{@task_id.inspect} status=#{@status.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)
+    # Validate task status
+    # @param status [String] the status to validate
+    # @raise [ArgumentError] if the status is not valid
+    def validate_status!(status)
+      return if VALID_STATUSES.include?(status)
 
-      raise ArgumentError, "Invalid task state: #{state.inspect}. Must be one of: #{VALID_STATES.join(', ')}"
+      raise ArgumentError, "Invalid task status: #{status.inspect}. Must be one of: #{VALID_STATUSES.join(', ')}"
     end
   end
 end

data/lib/mcp_client/tool.rb

@@ -17,7 +17,10 @@ module MCPClient
     #   @return [Hash, nil] optional annotations describing tool behavior (e.g., readOnly, destructive)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this tool belongs to
-    attr_reader :name, :title, :description, :schema, :output_schema, :annotations, :server
+    # @!attribute [r] task_support
+    #   @return [String, nil] tool-level task negotiation (MCP 2025-11-25):
+    #     'forbidden' (default), 'optional', or 'required'; nil when not advertised
+    attr_reader :name, :title, :description, :schema, :output_schema, :annotations, :server, :task_support
 
     # Initialize a new Tool
     # @param name [String] the name of the tool
@@ -27,7 +30,9 @@ module MCPClient
     # @param output_schema [Hash, nil] optional JSON schema for structured tool outputs (MCP 2025-06-18)
     # @param annotations [Hash, nil] optional annotations describing tool behavior
     # @param server [MCPClient::ServerBase, nil] the server this tool belongs to
-    def initialize(name:, description:, schema:, title: nil, output_schema: nil, annotations: nil, server: nil)
+    # @param task_support [String, nil] execution.taskSupport value (MCP 2025-11-25)
+    def initialize(name:, description:, schema:, title: nil, output_schema: nil, annotations: nil, server: nil,
+                   task_support: nil)
       @name = name
       @title = title
       @description = description
@@ -35,6 +40,7 @@ module MCPClient
       @output_schema = output_schema
       @annotations = annotations
       @server = server
+      @task_support = task_support
     end
 
     # Create a Tool instance from JSON data
@@ -48,6 +54,8 @@ module MCPClient
       output_schema = data['outputSchema'] || data[:outputSchema]
       annotations = data['annotations'] || data[:annotations]
       title = data['title'] || data[:title]
+      execution = data['execution'] || data[:execution]
+      task_support = execution && (execution['taskSupport'] || execution[:taskSupport])
       new(
         name: data['name'] || data[:name],
         description: data['description'] || data[:description],
@@ -55,7 +63,8 @@ module MCPClient
         title: title,
         output_schema: output_schema,
         annotations: annotations,
-        server: server
+        server: server,
+        task_support: task_support
       )
     end
 
@@ -114,21 +123,25 @@ module MCPClient
 
     # Check the readOnlyHint annotation (MCP 2025-11-25)
     # When true, the tool does not modify its environment.
-    # @return [Boolean] defaults to true when not specified
+    # Per the MCP ToolAnnotations schema the default is false, i.e. a tool
+    # without this hint is assumed to potentially modify its environment.
+    # @return [Boolean] defaults to false when not specified
     def read_only_hint?
-      return true unless @annotations
+      return false unless @annotations
 
-      fetch_annotation_hint('readOnlyHint', :readOnlyHint, true)
+      fetch_annotation_hint('readOnlyHint', :readOnlyHint, false)
     end
 
     # Check the destructiveHint annotation (MCP 2025-11-25)
     # When true, the tool may perform destructive updates.
-    # Only meaningful when readOnlyHint is false.
-    # @return [Boolean] defaults to false when not specified
+    # Only meaningful when readOnlyHint is false. Per the MCP ToolAnnotations
+    # schema the default is true, i.e. a non-read-only tool without this hint
+    # is assumed to be potentially destructive.
+    # @return [Boolean] defaults to true when not specified
     def destructive_hint?
-      return false unless @annotations
+      return true unless @annotations
 
-      fetch_annotation_hint('destructiveHint', :destructiveHint, false)
+      fetch_annotation_hint('destructiveHint', :destructiveHint, true)
     end
 
     # Check the idempotentHint annotation (MCP 2025-11-25)
@@ -156,6 +169,31 @@ module MCPClient
       !@output_schema.nil? && !@output_schema.empty?
     end
 
+    # Whether task-augmented execution is allowed for this tool (MCP 2025-11-25).
+    # True when execution.taskSupport is 'optional' or 'required'.
+    # @return [Boolean]
+    def supports_task?
+      %w[optional required].include?(@task_support)
+    end
+
+    # Whether task-augmented execution is required for this tool
+    # @return [Boolean]
+    def task_required?
+      @task_support == 'required'
+    end
+
+    # Whether task-augmented execution is optional for this tool
+    # @return [Boolean]
+    def task_optional?
+      @task_support == 'optional'
+    end
+
+    # Whether task-augmented execution is forbidden (the default when unset)
+    # @return [Boolean]
+    def task_forbidden?
+      @task_support.nil? || @task_support == 'forbidden'
+    end
+
     private
 
     # Fetch a boolean annotation hint, checking both string and symbol keys.

data/lib/mcp_client/version.rb

@@ -2,7 +2,7 @@
 
 module MCPClient
   # Current version of the MCP client gem
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 
   # MCP protocol version (date-based) - unified across all transports
   PROTOCOL_VERSION = '2025-11-25'

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mcp-client
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Szymon Kurcab
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-22 00:00:00.000000000 Z
+date: 2026-07-04 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '8.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement