actionmcp 0.201.3 → 0.203.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +51 -0
  3. data/app/controllers/action_mcp/application_controller.rb +21 -36
  4. data/app/jobs/action_mcp/tool_execution_job.rb +57 -27
  5. data/app/models/action_mcp/session/task.rb +2 -1
  6. data/app/models/action_mcp/session.rb +1 -233
  7. data/lib/action_mcp/callbacks.rb +22 -115
  8. data/lib/action_mcp/capability.rb +44 -0
  9. data/lib/action_mcp/configuration.rb +26 -14
  10. data/lib/action_mcp/content/audio.rb +3 -21
  11. data/lib/action_mcp/content/base.rb +7 -0
  12. data/lib/action_mcp/content/binary.rb +30 -0
  13. data/lib/action_mcp/content/image.rb +3 -21
  14. data/lib/action_mcp/content/validation.rb +37 -38
  15. data/lib/action_mcp/content.rb +0 -33
  16. data/lib/action_mcp/custom_methods.rb +61 -0
  17. data/lib/action_mcp/dev_reloader.rb +19 -0
  18. data/lib/action_mcp/lifecycle_callbacks.rb +28 -0
  19. data/lib/action_mcp/log_subscriber.rb +15 -21
  20. data/lib/action_mcp/output_schema_builder.rb +18 -31
  21. data/lib/action_mcp/prompt.rb +8 -59
  22. data/lib/action_mcp/request_meta.rb +11 -0
  23. data/lib/action_mcp/resource_callbacks.rb +22 -149
  24. data/lib/action_mcp/resource_response.rb +3 -7
  25. data/lib/action_mcp/resource_template.rb +1 -0
  26. data/lib/action_mcp/schema_context.rb +50 -0
  27. data/lib/action_mcp/server/base_session.rb +7 -173
  28. data/lib/action_mcp/server/handlers/dispatching.rb +38 -0
  29. data/lib/action_mcp/server/handlers/prompt_handler.rb +6 -12
  30. data/lib/action_mcp/server/handlers/resource_handler.rb +6 -23
  31. data/lib/action_mcp/server/handlers/task_handler.rb +14 -31
  32. data/lib/action_mcp/server/handlers/tool_handler.rb +4 -11
  33. data/lib/action_mcp/server/json_rpc_handler.rb +17 -1
  34. data/lib/action_mcp/server/prompts.rb +8 -17
  35. data/lib/action_mcp/server/resources.rb +4 -28
  36. data/lib/action_mcp/server/result_response.rb +19 -0
  37. data/lib/action_mcp/server/sampling_request.rb +26 -43
  38. data/lib/action_mcp/server/session_registries.rb +127 -0
  39. data/lib/action_mcp/server/tools.rb +23 -33
  40. data/lib/action_mcp/server/transport_handler.rb +0 -6
  41. data/lib/action_mcp/tagged_stream_logging.rb +9 -5
  42. data/lib/action_mcp/tool.rb +67 -71
  43. data/lib/action_mcp/version.rb +1 -1
  44. data/lib/action_mcp.rb +4 -0
  45. data/lib/tasks/action_mcp_tasks.rake +22 -44
  46. metadata +11 -3
  47. data/lib/action_mcp/server/handlers/router.rb +0 -33
@@ -38,7 +38,7 @@ module ActionMCP
38
38
  "properties" => {
39
39
  "hints" => {
40
40
  "type" => "array",
41
- "items" => { "$ref" => "#/$defs/ModelHint" }
41
+ "items" => Content::Validation.ref("ModelHint")
42
42
  },
43
43
  "costPriority" => { "type" => "number", "minimum" => 0, "maximum" => 1 },
44
44
  "speedPriority" => { "type" => "number", "minimum" => 0, "maximum" => 1 },
@@ -68,13 +68,13 @@ module ActionMCP
68
68
  "type" => "object",
69
69
  "required" => %w[inputSchema name],
70
70
  "properties" => Content::Validation::META_PROPERTY.merge(
71
- "annotations" => { "$ref" => "#/$defs/ToolAnnotations" },
71
+ "annotations" => Content::Validation.ref("ToolAnnotations"),
72
72
  "description" => { "type" => "string" },
73
- "execution" => { "$ref" => "#/$defs/ToolExecution" },
74
- "icons" => { "type" => "array", "items" => { "$ref" => "#/$defs/Icon" } },
75
- "inputSchema" => { "$ref" => "#/$defs/ToolSchema" },
73
+ "execution" => Content::Validation.ref("ToolExecution"),
74
+ "icons" => { "type" => "array", "items" => Content::Validation.ref("Icon") },
75
+ "inputSchema" => Content::Validation.ref("ToolSchema"),
76
76
  "name" => { "type" => "string" },
77
- "outputSchema" => { "$ref" => "#/$defs/ToolSchema" },
77
+ "outputSchema" => Content::Validation.ref("ToolSchema"),
78
78
  "title" => { "type" => "string" }
79
79
  )
80
80
  },
@@ -104,7 +104,7 @@ module ActionMCP
104
104
  "properties" => Content::Validation::META_PROPERTY.merge(
105
105
  "content" => {
106
106
  "type" => "array",
107
- "items" => { "$ref" => "#/$defs/ContentBlock" }
107
+ "items" => Content::Validation.ref("ContentBlock")
108
108
  },
109
109
  "isError" => { "type" => "boolean" },
110
110
  "structuredContent" => { "type" => "object" },
@@ -113,9 +113,7 @@ module ActionMCP
113
113
  )
114
114
  },
115
115
  "SamplingMessageContentBlock" => {
116
- "anyOf" => %w[TextContent ImageContent AudioContent ToolUseContent ToolResultContent].map do |name|
117
- { "$ref" => "#/$defs/#{name}" }
118
- end
116
+ "anyOf" => Content::Validation.refs(*%w[TextContent ImageContent AudioContent ToolUseContent ToolResultContent])
119
117
  },
120
118
  "SamplingMessage" => {
121
119
  "type" => "object",
@@ -123,14 +121,14 @@ module ActionMCP
123
121
  "properties" => Content::Validation::META_PROPERTY.merge(
124
122
  "content" => {
125
123
  "anyOf" => [
126
- { "$ref" => "#/$defs/SamplingMessageContentBlock" },
124
+ Content::Validation.ref("SamplingMessageContentBlock"),
127
125
  {
128
126
  "type" => "array",
129
- "items" => { "$ref" => "#/$defs/SamplingMessageContentBlock" }
127
+ "items" => Content::Validation.ref("SamplingMessageContentBlock")
130
128
  }
131
129
  ]
132
130
  },
133
- "role" => { "$ref" => "#/$defs/Role" }
131
+ "role" => Content::Validation.ref("Role")
134
132
  )
135
133
  },
136
134
  "CreateMessageRequestParams" => {
@@ -140,7 +138,7 @@ module ActionMCP
140
138
  "_meta" => {
141
139
  "type" => "object",
142
140
  "properties" => {
143
- "progressToken" => { "$ref" => "#/$defs/ProgressToken" }
141
+ "progressToken" => Content::Validation.ref("ProgressToken")
144
142
  }
145
143
  },
146
144
  "includeContext" => {
@@ -150,16 +148,16 @@ module ActionMCP
150
148
  "maxTokens" => { "type" => "integer" },
151
149
  "messages" => {
152
150
  "type" => "array",
153
- "items" => { "$ref" => "#/$defs/SamplingMessage" }
151
+ "items" => Content::Validation.ref("SamplingMessage")
154
152
  },
155
153
  "metadata" => { "type" => "object" },
156
- "modelPreferences" => { "$ref" => "#/$defs/ModelPreferences" },
154
+ "modelPreferences" => Content::Validation.ref("ModelPreferences"),
157
155
  "stopSequences" => { "type" => "array", "items" => { "type" => "string" } },
158
156
  "systemPrompt" => { "type" => "string" },
159
- "task" => { "$ref" => "#/$defs/TaskMetadata" },
157
+ "task" => Content::Validation.ref("TaskMetadata"),
160
158
  "temperature" => { "type" => "number" },
161
- "toolChoice" => { "$ref" => "#/$defs/ToolChoice" },
162
- "tools" => { "type" => "array", "items" => { "$ref" => "#/$defs/Tool" } }
159
+ "toolChoice" => Content::Validation.ref("ToolChoice"),
160
+ "tools" => { "type" => "array", "items" => Content::Validation.ref("Tool") }
163
161
  }
164
162
  }
165
163
  ).freeze
@@ -184,35 +182,20 @@ module ActionMCP
184
182
  @default_messages ||= []
185
183
  end
186
184
 
187
- def system_prompt(value = UNSET)
188
- @default_system_prompt = value unless value.equal?(UNSET)
189
- @default_system_prompt
190
- end
191
-
192
- def include_context(value = UNSET)
193
- @default_context = value unless value.equal?(UNSET)
194
- @default_context
195
- end
196
-
197
185
  def model_hints(value = UNSET)
198
186
  @default_model_hints = value unless value.equal?(UNSET)
199
187
  @default_model_hints ||= []
200
188
  end
201
189
 
202
- def intelligence_priority(value = UNSET)
203
- @default_intelligence_priority = value unless value.equal?(UNSET)
204
- @default_intelligence_priority.nil? ? 0.9 : @default_intelligence_priority
205
- end
206
-
207
- def max_tokens(value = UNSET)
208
- @default_max_tokens = value unless value.equal?(UNSET)
209
- @default_max_tokens.nil? ? 500 : @default_max_tokens
210
- end
211
-
212
- def temperature(value = UNSET)
213
- @default_temperature = value unless value.equal?(UNSET)
214
- @default_temperature.nil? ? 0.7 : @default_temperature
215
- end
190
+ # Class-level defaults: called with a value to set it, without one to read it.
191
+ { system_prompt: nil, include_context: nil, intelligence_priority: 0.9, max_tokens: 500, temperature: 0.7 }
192
+ .each do |name, fallback|
193
+ define_method(name) do |value = UNSET|
194
+ instance_variable_set(:"@default_#{name}", value) unless value.equal?(UNSET)
195
+ stored = instance_variable_get(:"@default_#{name}")
196
+ stored.nil? ? fallback : stored
197
+ end
198
+ end
216
199
 
217
200
  def validate_params!(params)
218
201
  raise ArgumentError, "Sampling request params must be an object" unless params.is_a?(Hash)
@@ -0,0 +1,127 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ActionMCP
4
+ module Server
5
+ # Per-session tool, prompt and resource-template registries shared by the
6
+ # in-memory BaseSession and the ActiveRecord Session. A registry of ["*"]
7
+ # exposes everything the active profile allows.
8
+ module SessionRegistries
9
+ Kind = Data.define(:registry, :lookup, :name_method, :filtered, :list)
10
+
11
+ KINDS = {
12
+ tool: Kind.new(:tool_registry, "ActionMCP::ToolsRegistry", :tool_name, :filtered_tools, "tools"),
13
+ prompt: Kind.new(:prompt_registry, "ActionMCP::PromptsRegistry", :prompt_name, :filtered_prompts, "prompts"),
14
+ resource_template: Kind.new(:resource_registry, "ActionMCP::ResourceTemplatesRegistry", :capability_name,
15
+ :filtered_resources, "resources")
16
+ }.freeze
17
+
18
+ WILDCARD = [ "*" ].freeze
19
+
20
+ def initialize!
21
+ return false unless status == "initializing" && !initialized?
22
+
23
+ self.initialized = true
24
+ self.status = "initialized"
25
+ save
26
+ end
27
+
28
+ def send_progress_notification(progressToken:, progress:, total: nil, message: nil)
29
+ ActionMCP::Server::TransportHandler.new(self).send_progress_notification(
30
+ progressToken: progressToken, progress: progress, total: total, message: message
31
+ )
32
+ end
33
+
34
+ { tool: "tools", prompt: "prompts", resource_template: "resource_templates" }.each do |kind, plural|
35
+ define_method(:"register_#{kind}") { |class_or_name| register_capability(kind, class_or_name) }
36
+ define_method(:"unregister_#{kind}") { |class_or_name| unregister_capability(kind, class_or_name) }
37
+ define_method(:"registered_#{plural}") { registered_capabilities(kind) }
38
+ end
39
+
40
+ { tools: :tool, prompts: :prompt, resources: :resource_template }.each do |suffix, kind|
41
+ define_method(:"uses_all_#{suffix}?") { uses_all?(kind) }
42
+ end
43
+
44
+ private
45
+
46
+ KINDS.each_value do |kind|
47
+ define_method(:"send_#{kind.list}_list_changed_notification") do
48
+ return unless server_capabilities.dig(kind.list, "listChanged")
49
+
50
+ write(JSON_RPC::Notification.new(method: "notifications/#{kind.list}/list_changed"))
51
+ end
52
+ end
53
+
54
+ def register_capability(kind, class_or_name)
55
+ name = normalize_name(class_or_name, kind)
56
+ return false unless capability_exists?(kind, name)
57
+ return true if uses_all?(kind)
58
+
59
+ names = registry_names(kind)
60
+ unless names.include?(name)
61
+ names << name
62
+ save!
63
+ send("send_#{KINDS[kind].list}_list_changed_notification")
64
+ end
65
+ true
66
+ end
67
+
68
+ def unregister_capability(kind, class_or_name)
69
+ name = normalize_name(class_or_name, kind)
70
+
71
+ if uses_all?(kind)
72
+ return unless capability_exists?(kind, name)
73
+
74
+ expand_registry!(kind)
75
+ end
76
+
77
+ return unless registry_names(kind).delete(name)
78
+
79
+ save!
80
+ send("send_#{KINDS[kind].list}_list_changed_notification")
81
+ end
82
+
83
+ def registered_capabilities(kind)
84
+ return ActionMCP.configuration.public_send(KINDS[kind].filtered).map(&:klass) if uses_all?(kind)
85
+
86
+ (public_send(KINDS[kind].registry) || []).filter_map do |name|
87
+ registry_for(kind).find(name)
88
+ rescue StandardError
89
+ nil
90
+ end
91
+ end
92
+
93
+ def uses_all?(kind)
94
+ public_send(KINDS[kind].registry) == WILDCARD
95
+ end
96
+
97
+ def registry_names(kind)
98
+ public_send(KINDS[kind].registry) || public_send(:"#{KINDS[kind].registry}=", [])
99
+ end
100
+
101
+ # Replaces the wildcard with the explicit names it stood for, so one entry can be removed.
102
+ def expand_registry!(kind)
103
+ names = ActionMCP.configuration.public_send(KINDS[kind].filtered).map(&:name)
104
+ public_send(:"#{KINDS[kind].registry}=", names)
105
+ end
106
+
107
+ def capability_exists?(kind, name)
108
+ registry_for(kind).find(name)
109
+ true
110
+ rescue ActionMCP::RegistryBase::NotFound
111
+ false
112
+ end
113
+
114
+ def registry_for(kind)
115
+ KINDS[kind].lookup.constantize
116
+ end
117
+
118
+ def normalize_name(class_or_name, kind)
119
+ case class_or_name
120
+ when String then class_or_name
121
+ when Class then class_or_name.public_send(KINDS[kind].name_method)
122
+ else raise ArgumentError, "Expected String or Class, got #{class_or_name.class}"
123
+ end
124
+ end
125
+ end
126
+ end
127
+ end
@@ -3,6 +3,8 @@
3
3
  module ActionMCP
4
4
  module Server
5
5
  module Tools
6
+ include ResultResponse
7
+
6
8
  def send_tools_list(request_id, params = {})
7
9
  protocol_version = session.protocol_version
8
10
  progress_token = params.dig("_meta", "progressToken")
@@ -13,7 +15,7 @@ module ActionMCP
13
15
 
14
16
  page, next_cursor = paginate(session.registered_tools, cursor: params["cursor"])
15
17
 
16
- result = { tools: page.map { |t| t.to_h(protocol_version: protocol_version) } }
18
+ result = { tools: page.filter_map { |tool_class| listed_tool(tool_class, protocol_version) } }
17
19
  result[:nextCursor] = next_cursor if next_cursor
18
20
 
19
21
  if progress_token
@@ -31,8 +33,7 @@ module ActionMCP
31
33
 
32
34
  unless tool_class
33
35
  Rails.logger.error "Tool not found: #{tool_name}. Registered tools: #{session.registered_tools.map(&:tool_name).join(', ')}"
34
- send_jsonrpc_error(request_id, :invalid_params,
35
- "Tool '#{tool_name}' not found or not registered for this session")
36
+ send_tool_not_found(request_id, tool_name)
36
37
  return
37
38
  end
38
39
 
@@ -85,6 +86,18 @@ module ActionMCP
85
86
 
86
87
  private
87
88
 
89
+ # A tool whose schema procs fail is reported and left out of the listing.
90
+ def listed_tool(tool_class, protocol_version)
91
+ tool_class.to_h(protocol_version: protocol_version, session: session)
92
+ rescue SchemaResolutionError => e
93
+ Rails.error.report(e, handled: true, severity: :error, context: { tool: tool_class.tool_name })
94
+ nil
95
+ end
96
+
97
+ def send_tool_not_found(request_id, tool_name)
98
+ send_jsonrpc_error(request_id, :invalid_params, "Tool '#{tool_name}' not found or not registered for this session")
99
+ end
100
+
88
101
  def execute_tool_synchronously(request_id, tool_class, tool_name, arguments, _meta)
89
102
  begin
90
103
  # Create tool and set execution context with request info
@@ -100,37 +113,18 @@ module ActionMCP
100
113
  }
101
114
  })
102
115
 
103
- # Wrap tool execution with Rails reloader for development
104
- result = if Rails.env.development?
105
- # Preserve Current attributes across reloader boundary
106
- current_user = ActionMCP::Current.user
107
- current_gateway = ActionMCP::Current.gateway
108
- current_session_data = ActionMCP::Current.session_data
109
-
110
- Rails.application.reloader.wrap do
111
- # Restore Current attributes inside reloader
112
- ActionMCP::Current.user = current_user
113
- ActionMCP::Current.gateway = current_gateway
114
- ActionMCP::Current.session_data = current_session_data
115
- tool.call
116
- end
117
- else
118
- tool.call
119
- end
120
-
121
- result = ToolResult.normalize(result)
116
+ result = DevReloader.wrap { tool.call }
122
117
 
123
- if result.is_error
124
- # Protocol error
125
- send_jsonrpc_response(request_id, error: result.to_h)
126
- else
127
- # Success OR tool execution error - both are valid JSON-RPC responses
128
- send_jsonrpc_response(request_id, result: result.to_h)
129
- end
118
+ # Tool execution errors travel as results; only protocol errors become JSON-RPC errors
119
+ send_result_response(request_id, ToolResult.normalize(result))
130
120
  rescue ArgumentError => e
131
121
  send_jsonrpc_response(request_id, result: ToolResult.execution_error(e.message).to_h)
132
122
  rescue ActiveModel::UnknownAttributeError => e
133
123
  send_jsonrpc_response(request_id, result: ToolResult.execution_error(e.message).to_h)
124
+ rescue SchemaResolutionError => e
125
+ # Unlisted for this caller, so it answers like an unknown tool.
126
+ Rails.error.report(e, handled: true, severity: :error, context: { tool: tool_name })
127
+ send_tool_not_found(request_id, tool_name)
134
128
  rescue StandardError => e
135
129
  # Log the actual error for debugging
136
130
  Rails.logger.error "Tool execution error: #{e.class} - #{e.message}"
@@ -189,10 +183,6 @@ module ActionMCP
189
183
 
190
184
  (tool_class.task_support || :forbidden).to_sym
191
185
  end
192
-
193
- def format_registry_items(registry, protocol_version = nil)
194
- registry.map { |item| item.klass.to_h(protocol_version: protocol_version) }
195
- end
196
186
  end
197
187
  end
198
188
  end
@@ -38,12 +38,6 @@ module ActionMCP
38
38
  def send_pong(request_id)
39
39
  send_jsonrpc_response(request_id, result: {})
40
40
  end
41
-
42
- private
43
-
44
- def format_registry_items(registry)
45
- registry.map { |item| item.klass.to_h }
46
- end
47
41
  end
48
42
  end
49
43
  end
@@ -12,28 +12,32 @@ module ActionMCP
12
12
  # ——— Outbound: any frame we ‘write’ to the wire ———
13
13
  def write_message(data)
14
14
  pretty = json_normalise(data)
15
- log_with_tags("MCP", "TX") { ActionMCP.logger.debug("#{BLUE_TX}#{pretty}#{CLR}") }
15
+ log_frame("TX", :debug, BLUE_TX, pretty)
16
16
  super
17
17
  rescue StandardError => e
18
- log_with_tags("MCP", "TX") { ActionMCP.logger.error("#{RED_FATAL}#{e.message}#{CLR}") }
18
+ log_frame("TX", :error, RED_FATAL, e.message)
19
19
  raise
20
20
  end
21
21
 
22
22
  # ——— Inbound: every raw line handed to the JSON‑RPC handler ———
23
23
  def read(line)
24
24
  pretty = json_normalise(line)
25
- log_with_tags("MCP", "RX") { ActionMCP.logger.debug("#{GREEN_RX}#{pretty}#{CLR}") }
25
+ log_frame("RX", :debug, GREEN_RX, pretty)
26
26
  super
27
27
  rescue MultiJSON::ParseError => e
28
- log_with_tags("MCP", "RX") { ActionMCP.logger.warn("#{YELLOW_ERR}Bad JSON → #{e.message}#{CLR}") }
28
+ log_frame("RX", :warn, YELLOW_ERR, "Bad JSON → #{e.message}")
29
29
  raise
30
30
  rescue StandardError => e
31
- log_with_tags("MCP", "RX") { ActionMCP.logger.error("#{RED_FATAL}#{e.message}#{CLR}") }
31
+ log_frame("RX", :error, RED_FATAL, e.message)
32
32
  raise
33
33
  end
34
34
 
35
35
  private
36
36
 
37
+ def log_frame(direction, level, color, text)
38
+ log_with_tags("MCP", direction) { ActionMCP.logger.public_send(level, "#{color}#{text}#{CLR}") }
39
+ end
40
+
37
41
  # Helper method to handle tagged logging across different logger types
38
42
  def log_with_tags(*tags, &block)
39
43
  if ActionMCP.logger.respond_to?(:tagged)
@@ -15,6 +15,10 @@ module ActionMCP
15
15
  include ActionMCP::CurrentHelpers
16
16
  extend ActionMCP::SchemaHelpers
17
17
 
18
+ # JSON Schema keywords the collection DSL places on the array itself;
19
+ # the rest describe each item.
20
+ COLLECTION_ARRAY_KEYWORDS = %i[minItems maxItems uniqueItems].freeze
21
+
18
22
  # --------------------------------------------------------------------------
19
23
  # Class Attributes for Tool Metadata and Schema
20
24
  # --------------------------------------------------------------------------
@@ -26,12 +30,12 @@ module ActionMCP
26
30
  class_attribute :_required_properties, instance_accessor: false, default: []
27
31
  class_attribute :_annotations, instance_accessor: false, default: {}
28
32
  class_attribute :_output_schema, instance_accessor: false, default: nil
29
- class_attribute :_meta, instance_accessor: false, default: {}
30
33
  class_attribute :_requires_consent, instance_accessor: false, default: false
31
34
  class_attribute :_output_schema_builder, instance_accessor: false, default: nil
32
35
  class_attribute :_additional_properties, instance_accessor: false, default: false
33
36
  class_attribute :_cached_schema_property_keys, instance_accessor: false, default: nil
34
37
  class_attribute :_input_schemer, instance_accessor: false, default: nil
38
+ class_attribute :_dynamic_schema, instance_accessor: false, default: nil
35
39
  class_attribute :_output_schemer, instance_accessor: false, default: nil
36
40
  class_attribute :_property_aliases, instance_accessor: false, default: {}
37
41
  class_attribute :_task_support, instance_accessor: false, default: :forbidden
@@ -47,47 +51,18 @@ module ActionMCP
47
51
  # @param name [String, nil] Optional. The name to set for the tool.
48
52
  # @return [String] The current tool name.
49
53
  def self.tool_name(name = nil)
50
- if name
51
- self._capability_name = name
52
- re_register_if_needed
53
- name
54
- else
55
- _capability_name || default_tool_name
56
- end
57
- end
58
-
59
- # Re-registers the tool if it was already registered under a different name
60
- # @return [void]
61
- def self.re_register_if_needed
62
- return if abstract?
63
- return unless _registered_name # Not yet registered
64
-
65
- new_name = capability_name
66
- return if _registered_name == new_name # No change
67
-
68
- ActionMCP::ToolsRegistry.re_register(self, _registered_name)
69
- end
70
-
71
- private_class_method :re_register_if_needed
72
-
73
- # Returns a default tool name based on the class name.
74
- #
75
- # @return [String] The default tool name.
76
- def self.default_tool_name
77
- return "" if name.nil?
78
-
79
- name.underscore.gsub("/", "__").sub(/_tool$/, "")
54
+ name ? assign_capability_name(name) : capability_name
80
55
  end
81
56
 
82
57
  class << self
83
- alias default_capability_name default_tool_name
58
+ alias default_tool_name default_capability_name
84
59
 
85
60
  def type
86
61
  :tool
87
62
  end
88
63
 
89
- def unregister_from_registry
90
- ActionMCP::ToolsRegistry.unregister(self) if ActionMCP::ToolsRegistry.store.values.include?(self)
64
+ def registry
65
+ ActionMCP::ToolsRegistry
91
66
  end
92
67
 
93
68
  # Hook called when a class inherits from Tool
@@ -183,16 +158,6 @@ module ActionMCP
183
158
  _output_schema
184
159
  end
185
160
 
186
- # Sets or retrieves the _meta field
187
- def meta(data = nil)
188
- if data
189
- raise ArgumentError, "_meta must be a hash" unless data.is_a?(Hash)
190
-
191
- self._meta = _meta.merge(data)
192
- else
193
- _meta
194
- end
195
- end
196
161
 
197
162
  # Declares the UI resource this tool renders. Merges a `ui:` entry into
198
163
  # `_meta` so the tool listing advertises the dashboard.
@@ -312,10 +277,11 @@ module ActionMCP
312
277
  _cached_schema_property_keys
313
278
  end
314
279
 
315
- def input_schema
316
- properties = _schema_properties.deep_dup
280
+ # @param session [ActionMCP::Session, nil] Session handed to keyword procs.
281
+ def input_schema(session: nil)
282
+ properties = SchemaContext.new(session, tool_name).resolve(_schema_properties)
317
283
  _property_aliases.each do |alias_name, property_name|
318
- properties[alias_name] = _schema_properties.fetch(property_name).deep_dup
284
+ properties[alias_name] = properties.fetch(property_name).deep_dup
319
285
  end
320
286
 
321
287
  schema = {
@@ -342,8 +308,18 @@ module ActionMCP
342
308
  schema
343
309
  end
344
310
 
345
- def input_schemer
346
- self._input_schemer ||= SchemaValidator.compile(input_schema, context: "input schema for #{tool_name}")
311
+ # Compiled validator for the input schema. Cached per class, except when a
312
+ # keyword is a proc: those resolve on every build, so the validator does too.
313
+ def input_schemer(session: nil)
314
+ return compile_input_schemer(input_schema(session: session)) if dynamic_schema?
315
+
316
+ self._input_schemer ||= compile_input_schemer(input_schema)
317
+ end
318
+
319
+ # Whether any schema keyword is a proc resolved at build time.
320
+ def dynamic_schema?
321
+ self._dynamic_schema = SchemaContext.dynamic?(_schema_properties) if _dynamic_schema.nil?
322
+ _dynamic_schema
347
323
  end
348
324
 
349
325
  def output_schemer
@@ -396,6 +372,16 @@ module ActionMCP
396
372
  def invalidate_schema_cache
397
373
  self._cached_schema_property_keys = nil
398
374
  self._input_schemer = nil
375
+ self._dynamic_schema = nil
376
+ end
377
+
378
+ def compile_input_schemer(schema)
379
+ SchemaValidator.compile(schema, context: "input schema for #{tool_name}")
380
+ end
381
+
382
+ # DSL keywords arrive in Ruby style (max_items) and leave as JSON Schema (maxItems).
383
+ def schema_keywords(opts)
384
+ opts.transform_keys { |key| key.to_s.camelize(:lower).to_sym }
399
385
  end
400
386
  end
401
387
 
@@ -412,8 +398,15 @@ module ActionMCP
412
398
  # @param description [String, nil] Optional description for the property.
413
399
  # @param required [Boolean] Whether the property is required (default: false).
414
400
  # @param default [Object, nil] The default value for the property.
415
- # @param opts [Hash] Additional options for the JSON Schema.
401
+ # @param opts [Hash] Additional JSON Schema keywords, in snake_case
402
+ # (min_length, multiple_of) or their JSON Schema spelling. A keyword given
403
+ # as a proc runs each time the schema is built (tools/list and argument
404
+ # validation) through ActionMCP::SchemaContext, which exposes session and
405
+ # current_user.
416
406
  # @return [void]
407
+ #
408
+ # @example
409
+ # property :tool, type: "string", enum: -> { current_user.allowed_tools }
417
410
  def self.property(prop_name, type: "string", description: nil, required: false, default: nil, **opts)
418
411
  if _property_aliases.key?(prop_name.to_s)
419
412
  raise ArgumentError, "Cannot define property '#{prop_name}' because it is already defined as an alias"
@@ -424,7 +417,7 @@ module ActionMCP
424
417
  # Build the JSON Schema definition.
425
418
  prop_definition = { type: type }
426
419
  prop_definition[:description] = description if description && !description.empty?
427
- prop_definition.merge!(opts) if opts.any?
420
+ prop_definition.merge!(schema_keywords(opts)) if opts.any?
428
421
 
429
422
  self._schema_properties = _schema_properties.merge(prop_name.to_s => prop_definition)
430
423
  new_required = _required_properties.dup
@@ -445,8 +438,15 @@ module ActionMCP
445
438
  # @param description [String, nil] Optional description for the collection.
446
439
  # @param required [Boolean] Whether the collection is required (default: false).
447
440
  # @param default [Array, nil] The default value for the collection.
441
+ # @param opts [Hash] Additional JSON Schema keywords, in snake_case or their
442
+ # JSON Schema spelling. Array keywords (min_items, max_items, unique_items)
443
+ # apply to the array; every other keyword (enum, format, minimum, pattern,
444
+ # ...) applies to each item. Procs resolve as for #property.
448
445
  # @return [void]
449
- def self.collection(prop_name, type:, description: nil, required: false, default: [])
446
+ #
447
+ # @example
448
+ # collection :labels, type: "string", enum: -> { current_user.labels }, min_items: 1, unique_items: true
449
+ def self.collection(prop_name, type:, description: nil, required: false, default: [], **opts)
450
450
  raise ArgumentError, "Type is required for a collection" if type.nil?
451
451
 
452
452
  if _property_aliases.key?(prop_name.to_s)
@@ -455,8 +455,13 @@ module ActionMCP
455
455
 
456
456
  invalidate_schema_cache
457
457
 
458
- collection_definition = { type: "array", items: { type: type } }
458
+ opts = schema_keywords(opts)
459
+ array_opts = opts.slice(*COLLECTION_ARRAY_KEYWORDS)
460
+ item_opts = opts.except(*COLLECTION_ARRAY_KEYWORDS)
461
+
462
+ collection_definition = { type: "array", items: { type: type, **item_opts } }
459
463
  collection_definition[:description] = description if description && !description.empty?
464
+ collection_definition.merge!(array_opts)
460
465
 
461
466
  self._schema_properties = _schema_properties.merge(prop_name.to_s => collection_definition)
462
467
  new_required = _required_properties.dup
@@ -479,9 +484,10 @@ module ActionMCP
479
484
  # Returns a hash representation of the tool definition including its JSON Schema.
480
485
  #
481
486
  # @return [Hash] The tool definition.
482
- def self.to_h(protocol_version: nil)
483
- schema = input_schema
484
- input_schemer
487
+ def self.to_h(protocol_version: nil, session: nil)
488
+ schema = input_schema(session: session)
489
+ # Compiling surfaces an invalid schema here instead of on the first call.
490
+ dynamic_schema? ? compile_input_schemer(schema) : input_schemer
485
491
 
486
492
  result = {
487
493
  name: tool_name,
@@ -600,21 +606,11 @@ module ActionMCP
600
606
  @response
601
607
  end
602
608
 
603
- def inspect
604
- attributes_hash = attributes.transform_values(&:inspect)
605
-
606
- response_info = if defined?(@response) && @response
607
- "response: #{@response.contents.size} content(s), isError: #{@response.is_error}"
608
- else
609
- "response: nil"
610
- end
611
-
612
- errors_info = errors.any? ? ", errors: #{errors.full_messages}" : ""
613
-
614
- "#<#{self.class.name} #{attributes_hash.map do |k, v|
615
- "#{k}: #{v.inspect}"
616
- end.join(', ')}, #{response_info}#{errors_info}>"
609
+ # Describes the collected response for #inspect.
610
+ def response_summary
611
+ "#{@response.contents.size} content(s), isError: #{@response.is_error}"
617
612
  end
613
+ private :response_summary
618
614
 
619
615
  # Override render to collect Content objects and support structured content
620
616
  def render(structured: nil, **args)
@@ -689,7 +685,7 @@ module ActionMCP
689
685
  else
690
686
  attributes.compact.merge(@_provided_additional_attributes.deep_stringify_keys)
691
687
  end
692
- schema_errors = SchemaValidator.validate(self.class.input_schemer, validation_input)
688
+ schema_errors = SchemaValidator.validate(self.class.input_schemer(session: session), validation_input)
693
689
  SchemaValidator.error_messages(schema_errors).each { |message| errors.add(:base, message) }
694
690
  @_alias_conflicts.each { |message| errors.add(:base, message) }
695
691
  end