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 



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

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.



99
100
101
102
103
104
105
106
107
108
 
# File 'app/models/action_mcp/session.rb', line 99

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 



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

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.



113
114
115
116
117
118
119
120
 
# File 'app/models/action_mcp/session.rb', line 113

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.



123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'app/models/action_mcp/session.rb', line 123

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 



71
72
73
74
75
76
77
78
79
80
 
# File 'app/models/action_mcp/session.rb', line 71

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



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

def consent_granted_for?(key)
  consents[key] == true
end

#consents ⇒ Object

Consent management methods as per MCP specification These methods manage user consents for tools and resources



361
362
363
364
365
366
 
# File 'app/models/action_mcp/session.rb', line 361

def consents
  value = super
  return {} if value.nil? || value == ""

  value.is_a?(String) ? JSON.parse(value) : value
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



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

def grant_consent(key)
  update!(consents: consents.merge(key => true))
end

#initialize! ⇒ Object 



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

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

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

#read(data) ⇒ Object 



92
93
94
 
# File 'app/models/action_mcp/session.rb', line 92

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

#register_prompt(prompt_class_or_name) ⇒ Object 



246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'app/models/action_mcp/session.rb', line 246

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 



275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'app/models/action_mcp/session.rb', line 275

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



217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'app/models/action_mcp/session.rb', line 217

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 



319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'app/models/action_mcp/session.rb', line 319

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 



332
333
334
335
336
337
338
339
340
341
342
343
 
# File 'app/models/action_mcp/session.rb', line 332

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



305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'app/models/action_mcp/session.rb', line 305

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 



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

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

#resource_subscribed?(uri) ⇒ Boolean

Returns:

  • (Boolean) 


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

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

#resource_unsubscribe(uri) ⇒ Object 



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

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



385
386
387
388
389
 
# File 'app/models/action_mcp/session.rb', line 385

def revoke_consent(key)
  return unless consents.key?(key)

  update!(consents: consents.except(key))
end

#send_ping! ⇒ Object 



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

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 



205
206
207
208
209
210
211
212
213
214
 
# File 'app/models/action_mcp/session.rb', line 205

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 



160
161
162
 
# File 'app/models/action_mcp/session.rb', line 160

def server_capabilities
  parsed_json_attribute(super)
end

#server_capabilities=(value) ⇒ Object 



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

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

#server_capabilities_payload ⇒ Object 



148
149
150
151
152
153
154
155
156
157
158
 
# File 'app/models/action_mcp/session.rb', line 148

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 



136
137
138
 
# File 'app/models/action_mcp/session.rb', line 136

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

#store_client_capabilities(capabilities) ⇒ Object 



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

def store_client_capabilities(capabilities)
  self.client_capabilities = capabilities
end

#store_client_info(info) ⇒ Object 



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

def store_client_info(info)
  self.client_info = info
end

#unregister_prompt(prompt_class_or_name) ⇒ Object 



260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'app/models/action_mcp/session.rb', line 260

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 



289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'app/models/action_mcp/session.rb', line 289

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 



231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'app/models/action_mcp/session.rb', line 231

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) 


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

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

#uses_all_resources? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

#uses_all_tools? ⇒ Boolean

Helper methods to check if using all capabilities

Returns:

  • (Boolean) 


346
347
348
 
# File 'app/models/action_mcp/session.rb', line 346

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

#write(data) ⇒ Object

MESSAGING dispatch



83
84
85
86
87
88
89
90
 
# File 'app/models/action_mcp/session.rb', line 83

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.generate(data) if data.is_a?(Hash)

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