Class: MCPClient::Task

Inherits:
Object
  • Object
show all
Defined in:
lib/mcp_client/task.rb

Overview

Represents an MCP Task for long-running, task-augmented operations. Conforms to the MCP 2025-11-25 Tasks utility.

Task statuses: working, input_required, completed, failed, cancelled. A task begins in working; completed/failed/cancelled are terminal.

Constant Summary collapse

VALID_STATUSES =

Valid task statuses (MCP 2025-11-25)

%w[working input_required completed failed cancelled].freeze
TERMINAL_STATUSES =

Statuses from which a task will not transition further

%w[completed failed cancelled].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(task_id:, status: 'working', status_message: nil, created_at: nil, last_updated_at: nil, ttl: nil, poll_interval: nil, server: nil) ⇒ Task

Create a new Task

Parameters:

  • task_id (String) —

    unique task identifier

  • status (String) (defaults to: 'working') —

    task status (working, input_required, completed, failed, cancelled)

  • status_message (String, nil) (defaults to: nil) —

    optional human-readable status detail

  • created_at (String, nil) (defaults to: nil) —

    ISO 8601 creation timestamp

  • last_updated_at (String, nil) (defaults to: nil) —

    ISO 8601 last-update timestamp

  • ttl (Integer, nil) (defaults to: nil) —

    retention duration in milliseconds since creation (nil = unspecified)

  • poll_interval (Integer, nil) (defaults to: nil) —

    suggested polling interval in milliseconds

  • server (MCPClient::ServerBase, nil) (defaults to: nil) —

    the server this task belongs to



27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/mcp_client/task.rb', line 27

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

Instance Attribute Details

#created_at ⇒ Object (readonly)

Returns the value of attribute created_at.



16
17
18
 
# File 'lib/mcp_client/task.rb', line 16

def created_at
  @created_at
end

#last_updated_at ⇒ Object (readonly)

Returns the value of attribute last_updated_at.



16
17
18
 
# File 'lib/mcp_client/task.rb', line 16

def last_updated_at
  @last_updated_at
end

#poll_interval ⇒ Object (readonly)

Returns the value of attribute poll_interval.



16
17
18
 
# File 'lib/mcp_client/task.rb', line 16

def poll_interval
  @poll_interval
end

#server ⇒ Object (readonly)

Returns the value of attribute server.



16
17
18
 
# File 'lib/mcp_client/task.rb', line 16

def server
  @server
end

#status ⇒ Object (readonly)

Returns the value of attribute status.



16
17
18
 
# File 'lib/mcp_client/task.rb', line 16

def status
  @status
end

#status_message ⇒ Object (readonly)

Returns the value of attribute status_message.



16
17
18
 
# File 'lib/mcp_client/task.rb', line 16

def status_message
  @status_message
end

#task_id ⇒ Object (readonly)

Returns the value of attribute task_id.



16
17
18
 
# File 'lib/mcp_client/task.rb', line 16

def task_id
  @task_id
end

#ttl ⇒ Object (readonly)

Returns the value of attribute ttl.



16
17
18
 
# File 'lib/mcp_client/task.rb', line 16

def ttl
  @ttl
end

Class Method Details

.from_create_result(result, server: nil) ⇒ Task

Build a Task from a CreateTaskResult, which wraps the task under task.

Parameters:

  • result (Hash) —

    the CreateTaskResult ({ 'task' => { ... } })

  • server (MCPClient::ServerBase, nil) (defaults to: nil) —

    optional server reference

Returns:



64
65
66
67
 
# File 'lib/mcp_client/task.rb', line 64

def self.from_create_result(result, server: nil)
  task_data = (result && (result['task'] || result[:task])) || result
  from_json(task_data, server: server)
end

.from_json(json, server: nil) ⇒ Task

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.

Parameters:

  • json (Hash) —

    the flat task hash

  • server (MCPClient::ServerBase, nil) (defaults to: nil) —

    optional server reference

Returns:



46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/mcp_client/task.rb', line 46

def self.from_json(json, server: nil)
  data = json || {}
  new(
    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

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

Check equality



125
126
127
128
129
 
# File 'lib/mcp_client/task.rb', line 125

def ==(other)
  return false unless other.is_a?(Task)

  task_id == other.task_id && status == other.status
end

#active? ⇒ Boolean

Whether the task is still active (not terminal — working or input_required)

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/mcp_client/task.rb', line 108

def active?
  !terminal?
end

#hash ⇒ Object 



133
134
135
 
# File 'lib/mcp_client/task.rb', line 133

def hash
  [task_id, status].hash
end

#input_required? ⇒ Boolean

Whether the task is waiting for input (status input_required)

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/mcp_client/task.rb', line 114

def input_required?
  @status == 'input_required'
end

#inspect ⇒ Object 



144
145
146
 
# File 'lib/mcp_client/task.rb', line 144

def inspect
  "#<MCPClient::Task task_id=#{@task_id.inspect} status=#{@status.inspect}>"
end

#terminal? ⇒ Boolean

Whether the task is in a terminal status (completed, failed, cancelled)

Returns:

  • (Boolean) 


102
103
104
 
# File 'lib/mcp_client/task.rb', line 102

def terminal?
  TERMINAL_STATUSES.include?(@status)
end

#to_h ⇒ Hash

Convert to a spec-shaped, JSON-serializable hash

Returns:

  • (Hash) 


83
84
85
86
87
88
89
90
91
92
 
# File 'lib/mcp_client/task.rb', line 83

def to_h
  # 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

#to_json ⇒ String

Convert to JSON string

Returns:

  • (String) 


96
97
98
 
# File 'lib/mcp_client/task.rb', line 96

def to_json(*)
  to_h.to_json(*)
end

#to_s ⇒ Object

String representation



138
139
140
141
142
 
# File 'lib/mcp_client/task.rb', line 138

def to_s
  parts = ["Task[#{@task_id}]: #{@status}"]
  parts << "- #{@status_message}" if @status_message
  parts.join(' ')
end

#working? ⇒ Boolean

Whether the task is still running (status working)

Returns:

  • (Boolean) 


120
121
122
 
# File 'lib/mcp_client/task.rb', line 120

def working?
  @status == 'working'
end