Class: ActionMCP::Session

Inherits:
ApplicationRecord show all
Includes:
MCPConsoleHelpers
Defined in:
app/models/action_mcp/session.rb,
app/models/action_mcp/session/task.rb,
app/models/action_mcp/session/message.rb,
app/models/action_mcp/session/subscription.rb

Overview

Represents an MCP session, which is a connection between a client and a server. Its role is to manage the communication channel and store information about the session, such as client and server capabilities, protocol version, and session status. It also manages the association with messages and subscriptions related to the session.

Defined Under Namespace

Classes: Message, Subscription, Task

Instance Method Summary collapse

Methods included from MCPConsoleHelpers

#message_flow

Instance Method Details

#begin_initialization! ⇒ Object 



178
179
180
181
182
 
# File 'app/models/action_mcp/session.rb', line 178

def begin_initialization!
  return false unless status == "pre_initialize" && !initialized?

  update(status: "initializing")
end

#cancel_in_flight_request(request_id) ⇒ Object

Marks an in-flight request received from the peer as cancelled. JSON-RPC IDs are scoped by direction, so an outbound request with the same ID must never be selected here.



104
105
106
107
108
109
110
111
112
113
 
# File 'app/models/action_mcp/session.rb', line 104

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&.rpc_method == JsonRpcHandlerBase::Methods::INITIALIZE

  request&.tap { |message| message.update!(request_cancelled: true) }
end

#capabilities_for_protocol(capabilities) ⇒ Object 



173
174
175
176
 
# File 'app/models/action_mcp/session.rb', line 173

def capabilities_for_protocol(capabilities)
  parsed = parsed_json_attribute(capabilities)
  parsed ? parsed.deep_dup : {}
end

#client_request_for_progress(progress_token) ⇒ Object

Locates the server-originated client request associated with a progress token. This is intentionally limited to MCP client request methods that ActionMCP can issue.



118
119
120
121
122
123
124
125
 
# File 'app/models/action_mcp/session.rb', line 118

def client_request_for_progress(progress_token)
  return if progress_token.nil?

  issued_client_requests.find do |request|
    request.data.dig("params", "_meta", "progressToken") == progress_token &&
      client_request_accepts_progress?(request)
  end
end

#client_request_for_task(task_id) ⇒ Object

Locates the task-augmented client request which created task_id.



128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'app/models/action_mcp/session.rb', line 128

def client_request_for_task(task_id)
  return unless task_id.is_a?(String) && task_id.present?

  response = messages.responses.where(direction: role).order(created_at: :desc).find do |message|
    message.data.dig("result", "task", "taskId") == task_id
  end
  return unless response

  issued_client_requests_with_id(response.data["id"]).find do |request|
    request.data.dig("params", "task").is_a?(Hash)
  end
end

#close! ⇒ Object 



76
77
78
79
80
81
82
83
84
85
 
# File 'app/models/action_mcp/session.rb', line 76

def close!
  if messages_count.zero?
    # if there are no messages, we can delete the session immediately
    destroy
    nil
  else
    update!(status: "closed", ended_at: Time.zone.now)
    subscriptions.delete_all # delete all subscriptions
  end
end

#consent_granted_for?(key) ⇒ Boolean

Checks if consent has been granted for a specific key

Parameters:

  • key (String) —

    The consent key (e.g., tool name or resource URI)

Returns:

  • (Boolean) —

    true if consent is granted, false otherwise



369
370
371
372
 
# File 'app/models/action_mcp/session.rb', line 369

def consent_granted_for?(key)
  consents_hash = consents.is_a?(String) ? JSON.parse(consents) : consents
  consents_hash&.key?(key) && consents_hash[key] == true
end

#grant_consent(key) ⇒ Boolean

Grants consent for a specific key

Parameters:

  • key (String) —

    The consent key to grant

Returns:

  • (Boolean) —

    true if saved successfully



377
378
379
380
381
382
 
# File 'app/models/action_mcp/session.rb', line 377

def grant_consent(key)
  self.consents = JSON.parse(consents) if consents.is_a?(String)
  self.consents ||= {}
  self.consents[key] = true
  save!
end

#initialize! ⇒ Object 



184
185
186
187
188
189
190
 
# File 'app/models/action_mcp/session.rb', line 184

def initialize!
  return false unless status == "initializing" && !initialized?

  self.initialized = true
  self.status = "initialized"
  save
end

#read(data) ⇒ Object 



97
98
99
 
# File 'app/models/action_mcp/session.rb', line 97

def read(data)
  messages.create!(data: data, direction: role)
end

#register_prompt(prompt_class_or_name) ⇒ Object 



251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'app/models/action_mcp/session.rb', line 251

def register_prompt(prompt_class_or_name)
  prompt_name = normalize_name(prompt_class_or_name, :prompt)
  return false unless prompt_exists?(prompt_name)
  return true if uses_all_prompts?

  self.prompt_registry ||= []
  unless self.prompt_registry.include?(prompt_name)
    self.prompt_registry << prompt_name
    save!
    send_prompts_list_changed_notification
  end
  true
end

#register_resource_template(template_class_or_name) ⇒ Object 



280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'app/models/action_mcp/session.rb', line 280

def register_resource_template(template_class_or_name)
  template_name = normalize_name(template_class_or_name, :resource_template)
  return false unless resource_template_exists?(template_name)
  return true if uses_all_resources?

  self.resource_registry ||= []
  unless self.resource_registry.include?(template_name)
    self.resource_registry << template_name
    save!
    send_resources_list_changed_notification
  end
  true
end

#register_tool(tool_class_or_name) ⇒ Object

Registry management methods



222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'app/models/action_mcp/session.rb', line 222

def register_tool(tool_class_or_name)
  tool_name = normalize_name(tool_class_or_name, :tool)
  return false unless tool_exists?(tool_name)
  return true if uses_all_tools?

  self.tool_registry ||= []
  unless self.tool_registry.include?(tool_name)
    self.tool_registry << tool_name
    save!
    send_tools_list_changed_notification
  end
  true
end

#registered_prompts ⇒ Object 



324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'app/models/action_mcp/session.rb', line 324

def registered_prompts
  if prompt_registry == [ "*" ]
    # filtered_prompts returns a RegistryScope with Item objects, need to extract the klass
    ActionMCP.configuration.filtered_prompts.map(&:klass)
  else
    (self.prompt_registry || []).filter_map do |prompt_name|
      ActionMCP::PromptsRegistry.find(prompt_name)
    rescue StandardError
      nil
    end
  end
end

#registered_resource_templates ⇒ Object 



337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'app/models/action_mcp/session.rb', line 337

def registered_resource_templates
  if resource_registry == [ "*" ]
    # filtered_resources returns a RegistryScope with Item objects, need to extract the klass
    ActionMCP.configuration.filtered_resources.map(&:klass)
  else
    (self.resource_registry || []).filter_map do |template_name|
      ActionMCP::ResourceTemplatesRegistry.find(template_name)
    rescue StandardError
      nil
    end
  end
end

#registered_tools ⇒ Object

Get registered items for this session



310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'app/models/action_mcp/session.rb', line 310

def registered_tools
  # Special case: ['*'] means use all available tools dynamically
  if tool_registry == [ "*" ]
    # filtered_tools returns a RegistryScope with Item objects, need to extract the klass
    ActionMCP.configuration.filtered_tools.map(&:klass)
  else
    (self.tool_registry || []).filter_map do |tool_name|
      ActionMCP::ToolsRegistry.find(tool_name)
    rescue StandardError
      nil
    end
  end
end

#resource_subscribe(uri) ⇒ Object 



198
199
200
 
# File 'app/models/action_mcp/session.rb', line 198

def resource_subscribe(uri)
  subscriptions.find_or_create_by(uri: uri)
end

#resource_subscribed?(uri) ⇒ Boolean

Returns:

  • (Boolean) 


206
207
208
 
# File 'app/models/action_mcp/session.rb', line 206

def resource_subscribed?(uri)
  subscriptions.exists?(uri: uri)
end

#resource_unsubscribe(uri) ⇒ Object 



202
203
204
 
# File 'app/models/action_mcp/session.rb', line 202

def resource_unsubscribe(uri)
  subscriptions.find_by(uri: uri)&.destroy
end

#revoke_consent(key) ⇒ void

This method returns an undefined value.

Revokes consent for a specific key

Parameters:

  • key (String) —

    The consent key to revoke



387
388
389
390
391
392
393
 
# File 'app/models/action_mcp/session.rb', line 387

def revoke_consent(key)
  self.consents = JSON.parse(self.consents) if self.consents.is_a?(String)
  return unless consents&.key?(key)

  consents.delete(key)
  save!
end

#send_ping! ⇒ Object 



192
193
194
195
196
 
# File 'app/models/action_mcp/session.rb', line 192

def send_ping!
  Session.logger.silence do
    write(JSON_RPC::Request.new(id: Time.now.to_i, method: "ping"))
  end
end

#send_progress_notification(progressToken:, progress:, total: nil, message: nil) ⇒ Object 



210
211
212
213
214
215
216
217
218
219
 
# File 'app/models/action_mcp/session.rb', line 210

def send_progress_notification(progressToken:, progress:, total: nil, message: nil)
  # Create a transport handler to send the notification
  handler = ActionMCP::Server::TransportHandler.new(self)
  handler.send_progress_notification(
    progressToken: progressToken,
    progress: progress,
    total: total,
    message: message
  )
end

#server_capabilities ⇒ Object 



165
166
167
 
# File 'app/models/action_mcp/session.rb', line 165

def server_capabilities
  parsed_json_attribute(super)
end

#server_capabilities=(value) ⇒ Object 



169
170
171
 
# File 'app/models/action_mcp/session.rb', line 169

def server_capabilities=(value)
  super(parsed_json_attribute(value))
end

#server_capabilities_payload ⇒ Object 



153
154
155
156
157
158
159
160
161
162
163
 
# File 'app/models/action_mcp/session.rb', line 153

def server_capabilities_payload
  payload = {
    protocolVersion: protocol_version || ActionMCP::DEFAULT_PROTOCOL_VERSION,
    serverInfo: server_info,
    capabilities: capabilities_for_protocol(server_capabilities)
  }
  # Add instructions at top level if configured
  instructions = ActionMCP.configuration.instructions
  payload[:instructions] = instructions if instructions
  payload
end

#set_protocol_version(version) ⇒ Object 



141
142
143
 
# File 'app/models/action_mcp/session.rb', line 141

def set_protocol_version(version)
  update(protocol_version: version)
end

#store_client_capabilities(capabilities) ⇒ Object 



149
150
151
 
# File 'app/models/action_mcp/session.rb', line 149

def store_client_capabilities(capabilities)
  self.client_capabilities = capabilities
end

#store_client_info(info) ⇒ Object 



145
146
147
 
# File 'app/models/action_mcp/session.rb', line 145

def store_client_info(info)
  self.client_info = info
end

#unregister_prompt(prompt_class_or_name) ⇒ Object 



265
266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'app/models/action_mcp/session.rb', line 265

def unregister_prompt(prompt_class_or_name)
  prompt_name = normalize_name(prompt_class_or_name, :prompt)

  if uses_all_prompts?
    return unless prompt_exists?(prompt_name)
    expand_prompt_registry!
  end

  self.prompt_registry ||= []
  return unless self.prompt_registry.delete(prompt_name)

  save!
  send_prompts_list_changed_notification
end

#unregister_resource_template(template_class_or_name) ⇒ Object 



294
295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'app/models/action_mcp/session.rb', line 294

def unregister_resource_template(template_class_or_name)
  template_name = normalize_name(template_class_or_name, :resource_template)

  if uses_all_resources?
    return unless resource_template_exists?(template_name)
    expand_resource_registry!
  end

  self.resource_registry ||= []
  return unless self.resource_registry.delete(template_name)

  save!
  send_resources_list_changed_notification
end

#unregister_tool(tool_class_or_name) ⇒ Object 



236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'app/models/action_mcp/session.rb', line 236

def unregister_tool(tool_class_or_name)
  tool_name = normalize_name(tool_class_or_name, :tool)

  if uses_all_tools?
    return unless tool_exists?(tool_name)
    expand_tool_registry!
  end

  self.tool_registry ||= []
  return unless self.tool_registry.delete(tool_name)

  save!
  send_tools_list_changed_notification
end

#uses_all_prompts? ⇒ Boolean

Returns:

  • (Boolean) 


355
356
357
 
# File 'app/models/action_mcp/session.rb', line 355

def uses_all_prompts?
  prompt_registry == [ "*" ]
end

#uses_all_resources? ⇒ Boolean

Returns:

  • (Boolean) 


359
360
361
 
# File 'app/models/action_mcp/session.rb', line 359

def uses_all_resources?
  resource_registry == [ "*" ]
end

#uses_all_tools? ⇒ Boolean

Helper methods to check if using all capabilities

Returns:

  • (Boolean) 


351
352
353
 
# File 'app/models/action_mcp/session.rb', line 351

def uses_all_tools?
  tool_registry == [ "*" ]
end

#write(data) ⇒ Object

MESSAGING dispatch



88
89
90
91
92
93
94
95
 
# File 'app/models/action_mcp/session.rb', line 88

def write(data)
  if data.is_a?(JSON_RPC::Request) || data.is_a?(JSON_RPC::Response) || data.is_a?(JSON_RPC::Notification)
    data = data.to_json
  end
  data = MultiJson.dump(data) if data.is_a?(Hash)

  messages.create!(data: data, direction: writer_role)
end