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
@@ -0,0 +1,28 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "active_support/callbacks"
4
+
5
+ module ActionMCP
6
+ # Builds a concern that defines one callback chain plus its
7
+ # before_<event>, after_<event> and around_<event> class macros.
8
+ module LifecycleCallbacks
9
+ def self.for(event)
10
+ Module.new do
11
+ extend ActiveSupport::Concern
12
+ include ActiveSupport::Callbacks
13
+
14
+ included do
15
+ define_callbacks event, skip_after_callbacks_if_terminated: true
16
+ end
17
+
18
+ class_methods do
19
+ %i[before after around].each do |kind|
20
+ define_method(:"#{kind}_#{event}") do |*filters, &blk|
21
+ set_callback(event, kind, *filters, &blk)
22
+ end
23
+ end
24
+ end
25
+ end
26
+ end
27
+ end
28
+ end
@@ -118,16 +118,7 @@ module ActionMCP
118
118
  end
119
119
 
120
120
  # Format the metric
121
- formatter = formatters&.dig(key)
122
- formatted_value = if formatter.respond_to?(:call)
123
- formatter.call(value)
124
- elsif value.is_a?(Float)
125
- format("%.1fms", value)
126
- else
127
- value.to_s
128
- end
129
-
130
- formatted_metric = "#{key}: #{formatted_value}"
121
+ formatted_metric = format_metric(key, value)
131
122
 
132
123
  # Add to appropriate group (or "other")
133
124
  if group
@@ -145,18 +136,21 @@ module ActionMCP
145
136
  end.compact.join(" | ")
146
137
  else
147
138
  # No grouping, just format all metrics
148
- custom_metrics.map do |key, value|
149
- formatter = formatters&.dig(key)
150
- formatted_value = if formatter.respond_to?(:call)
151
- formatter.call(value)
152
- elsif value.is_a?(Float)
153
- format("%.1fms", value)
154
- else
155
- value.to_s
156
- end
157
- "#{key}: #{formatted_value}"
158
- end.join(" | ")
139
+ custom_metrics.map { |key, value| format_metric(key, value) }.join(" | ")
140
+ end
141
+ end
142
+
143
+ # "key: value", using a registered formatter, milliseconds for floats, or to_s.
144
+ def self.format_metric(key, value)
145
+ formatter = formatters&.dig(key)
146
+ formatted_value = if formatter.respond_to?(:call)
147
+ formatter.call(value)
148
+ elsif value.is_a?(Float)
149
+ format("%.1fms", value)
150
+ else
151
+ value.to_s
159
152
  end
153
+ "#{key}: #{formatted_value}"
160
154
  end
161
155
 
162
156
  # Register a custom formatter for a specific metric
@@ -27,10 +27,7 @@ module ActionMCP
27
27
  schema["description"] = description if description
28
28
  schema.merge!(options) if options.any?
29
29
 
30
- @properties[name.to_s] = schema
31
- @required << name.to_s if required
32
-
33
- name.to_s
30
+ add_property(name, schema, required)
34
31
  end
35
32
 
36
33
  # Define a string property
@@ -44,14 +41,7 @@ module ActionMCP
44
41
  schema["minLength"] = min_length if min_length
45
42
  schema["maxLength"] = max_length if max_length
46
43
 
47
- if name
48
- @properties[name.to_s] = schema
49
- @required << name.to_s if required
50
- name.to_s
51
- else
52
- # Return schema for use in array items or other contexts
53
- schema
54
- end
44
+ add_property(name, schema, required)
55
45
  end
56
46
 
57
47
  # Define a number property
@@ -63,10 +53,7 @@ module ActionMCP
63
53
  schema["maximum"] = maximum if maximum
64
54
  schema["default"] = default if default
65
55
 
66
- @properties[name.to_s] = schema
67
- @required << name.to_s if required
68
-
69
- name.to_s
56
+ add_property(name, schema, required)
70
57
  end
71
58
 
72
59
  # Define a boolean property
@@ -75,10 +62,7 @@ module ActionMCP
75
62
  schema["description"] = description if description
76
63
  schema["default"] = default unless default.nil?
77
64
 
78
- @properties[name.to_s] = schema
79
- @required << name.to_s if required
80
-
81
- name.to_s
65
+ add_property(name, schema, required)
82
66
  end
83
67
 
84
68
  # Define an array property
@@ -122,9 +106,7 @@ module ActionMCP
122
106
  schema["items"] = { "type" => "string" }
123
107
  end
124
108
 
125
- @properties[name.to_s] = schema
126
-
127
- name.to_s
109
+ add_property(name, schema, false)
128
110
  end
129
111
 
130
112
  # Define an object property
@@ -150,14 +132,7 @@ module ActionMCP
150
132
  # Add additionalProperties if specified
151
133
  add_additional_properties_to_schema(schema, additional_properties)
152
134
 
153
- if name
154
- @properties[name.to_s] = schema
155
- @required << name.to_s if required
156
- name.to_s
157
- else
158
- # Return schema directly for use in array items
159
- schema
160
- end
135
+ add_property(name, schema, required)
161
136
  end
162
137
 
163
138
  # Set additionalProperties for the root schema
@@ -186,5 +161,17 @@ module ActionMCP
186
161
 
187
162
  schema
188
163
  end
164
+
165
+ private
166
+
167
+ # Registers a named property and returns its name; an unnamed schema is
168
+ # returned as-is so it can serve as array items.
169
+ def add_property(name, schema, required)
170
+ return schema unless name
171
+
172
+ @properties[name.to_s] = schema
173
+ @required << name.to_s if required
174
+ name.to_s
175
+ end
189
176
  end
190
177
  end
@@ -6,7 +6,6 @@ module ActionMCP
6
6
  include ActionMCP::Callbacks
7
7
  include ActionMCP::CurrentHelpers
8
8
  class_attribute :_argument_definitions, instance_accessor: false, default: []
9
- class_attribute :_meta, instance_accessor: false, default: {}
10
9
 
11
10
  # ---------------------------------------------------
12
11
  # Prompt Name
@@ -16,47 +15,18 @@ module ActionMCP
16
15
  # @param name [String, nil] The prompt name to set.
17
16
  # @return [String] The prompt name.
18
17
  def self.prompt_name(name = nil)
19
- if name
20
- self._capability_name = name
21
- re_register_if_needed
22
- name
23
- else
24
- _capability_name || default_prompt_name
25
- end
26
- end
27
-
28
- # Re-registers the prompt if it was already registered under a different name
29
- # @return [void]
30
- def self.re_register_if_needed
31
- return if abstract?
32
- return unless _registered_name # Not yet registered
33
-
34
- new_name = capability_name
35
- return if _registered_name == new_name # No change
36
-
37
- ActionMCP::PromptsRegistry.re_register(self, _registered_name)
38
- end
39
-
40
- private_class_method :re_register_if_needed
41
-
42
- # Returns the default prompt name based on the class name.
43
- #
44
- # @return [String] The default prompt name.
45
- def self.default_prompt_name
46
- return "" if name.nil?
47
-
48
- name.underscore.gsub("/", "__").sub(/_prompt$/, "")
18
+ name ? assign_capability_name(name) : capability_name
49
19
  end
50
20
 
51
21
  class << self
52
- alias default_capability_name default_prompt_name
22
+ alias default_prompt_name default_capability_name
53
23
 
54
24
  def type
55
25
  :prompt
56
26
  end
57
27
 
58
- def unregister_from_registry
59
- ActionMCP::PromptsRegistry.unregister(self) if ActionMCP::PromptsRegistry.store.values.include?(self)
28
+ def registry
29
+ ActionMCP::PromptsRegistry
60
30
  end
61
31
 
62
32
  # Hook called when a class inherits from Prompt
@@ -67,17 +37,6 @@ module ActionMCP
67
37
  ActiveSupport.run_load_hooks(:action_mcp_prompt, subclass)
68
38
  end
69
39
  end
70
-
71
- # Sets or retrieves the _meta field
72
- def meta(data = nil)
73
- if data
74
- raise ArgumentError, "_meta must be a hash" unless data.is_a?(Hash)
75
-
76
- self._meta = _meta.merge(data)
77
- else
78
- _meta
79
- end
80
- end
81
40
  end
82
41
 
83
42
  # ---------------------------------------------------
@@ -178,21 +137,11 @@ module ActionMCP
178
137
  @response # Return the response with collected messages
179
138
  end
180
139
 
181
- def inspect
182
- attributes_hash = attributes.transform_values(&:inspect)
183
-
184
- response_info = if defined?(@response) && @response
185
- "response: #{@response.messages.size} message(s)"
186
- else
187
- "response: nil"
188
- end
189
-
190
- errors_info = errors.any? ? ", errors: #{errors.full_messages}" : ""
191
-
192
- "#<#{self.class.name} #{attributes_hash.map do |k, v|
193
- "#{k}: #{v.inspect}"
194
- end.join(', ')}, #{response_info}#{errors_info}>"
140
+ # Describes the collected response for #inspect.
141
+ def response_summary
142
+ "#{@response.messages.size} message(s)"
195
143
  end
144
+ private :response_summary
196
145
 
197
146
  # Override render to collect messages
198
147
  def render(**args)
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ActionMCP
4
+ module RequestMeta
5
+ def request_meta
6
+ params = execution_context.dig(:request, :params)
7
+ meta = params && (params[:_meta] || params["_meta"])
8
+ meta.is_a?(Hash) ? meta.with_indifferent_access : ActiveSupport::HashWithIndifferentAccess.new
9
+ end
10
+ end
11
+ end
@@ -1,156 +1,29 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require "active_support/callbacks"
4
- require "active_support/core_ext/module/attribute_accessors"
5
-
6
3
  module ActionMCP
7
4
  # = Action MCP Resource Template \Callbacks
8
5
  #
9
- # Action MCP Resource Template Callbacks provide hooks during the resource resolution lifecycle.
10
- # These callbacks allow you to trigger logic during the resource resolution process.
11
- # Available callbacks are:
6
+ # Hooks around the +resolve+ method of resource templates:
7
+ # <tt>before_resolve</tt>, <tt>around_resolve</tt> and <tt>after_resolve</tt>.
12
8
  #
13
- # * <tt>before_resolve</tt>
14
- # * <tt>around_resolve</tt>
15
- # * <tt>after_resolve</tt>
16
- module ResourceCallbacks
17
- extend ActiveSupport::Concern
18
- include ActiveSupport::Callbacks
19
-
20
- class << self
21
- include ActiveSupport::Callbacks
22
- define_callbacks :execute
23
- end
24
-
25
- included do
26
- define_callbacks :resolve, skip_after_callbacks_if_terminated: true
27
- end
28
-
29
- # These methods will be included into any Action MCP Resource Template object, adding
30
- # callbacks for the +resolve+ method.
31
- class_methods do
32
- # Defines a callback that will get called right before the
33
- # resource template's resolve method is executed.
34
- #
35
- # class OrdersTemplate < ApplicationMCPResTemplate
36
- # description "Access order information"
37
- # uri_template "ecommerce://customers/{customer_id}/orders/{order_id}"
38
- # mime_type "application/json"
39
- #
40
- # parameter :customer_id,
41
- # description: "Customer identifier",
42
- # required: true
43
- # parameter :order_id,
44
- # description: "Order identifier",
45
- # required: true
46
- #
47
- # before_resolve do |template|
48
- # Rails.logger.info("Starting to resolve order: #{template.order_id} for customer: #{template.customer_id}")
49
- # end
50
- #
51
- # def resolve
52
- # order = MockOrder.find_by(id: order_id)
53
- # return unless order
54
- #
55
- # ActionMCP::Resource.new(
56
- # uri: "ecommerce://orders/#{order_id}",
57
- # name: "Order #{order_id}",
58
- # description: "Order information for order #{order_id}",
59
- # mime_type: "application/json",
60
- # size: order.to_json.length
61
- # )
62
- # end
63
- # end
64
- #
65
- def before_resolve(*filters, &blk)
66
- set_callback(:resolve, :before, *filters, &blk)
67
- end
68
-
69
- # Defines a callback that will get called right after the
70
- # resource template's resolve method has finished.
71
- #
72
- # class OrdersTemplate < ApplicationMCPResTemplate
73
- # description "Access order information"
74
- # uri_template "ecommerce://customers/{customer_id}/orders/{order_id}"
75
- # mime_type "application/json"
76
- #
77
- # parameter :customer_id,
78
- # description: "Customer identifier",
79
- # required: true
80
- # parameter :order_id,
81
- # description: "Order identifier",
82
- # required: true
83
- #
84
- # after_resolve do |template|
85
- # Rails.logger.info("Finished resolving order resource for order: #{template.order_id}")
86
- # end
87
- #
88
- # def resolve
89
- # order = MockOrder.find_by(id: order_id)
90
- # return unless order
91
- #
92
- # ActionMCP::Resource.new(
93
- # uri: "ecommerce://orders/#{order_id}",
94
- # name: "Order #{order_id}",
95
- # description: "Order information for order #{order_id}",
96
- # mime_type: "application/json",
97
- # size: order.to_json.length
98
- # )
99
- # end
100
- # end
101
- #
102
- def after_resolve(*filters, &blk)
103
- set_callback(:resolve, :after, *filters, &blk)
104
- end
105
-
106
- # Defines a callback that will get called around the resource template's resolve method.
107
- #
108
- # class OrdersTemplate < ApplicationMCPResTemplate
109
- # description "Access order information"
110
- # uri_template "ecommerce://customers/{customer_id}/orders/{order_id}"
111
- # mime_type "application/json"
112
- #
113
- # parameter :customer_id,
114
- # description: "Customer identifier",
115
- # required: true
116
- # parameter :order_id,
117
- # description: "Order identifier",
118
- # required: true
119
- #
120
- # around_resolve do |template, block|
121
- # start_time = Time.current
122
- # Rails.logger.info("Starting resolution for order: #{template.order_id}")
123
- #
124
- # resource = block.call
125
- #
126
- # if resource
127
- # Rails.logger.info("Order #{template.order_id} resolved successfully in #{Time.current - start_time}s")
128
- # else
129
- # Rails.logger.info("Order #{template.order_id} not found")
130
- # end
131
- #
132
- # resource
133
- # end
134
- #
135
- # def resolve
136
- # order = MockOrder.find_by(id: order_id)
137
- # return unless order
138
- #
139
- # ActionMCP::Resource.new(
140
- # uri: "ecommerce://orders/#{order_id}",
141
- # name: "Order #{order_id}",
142
- # description: "Order information for order #{order_id}",
143
- # mime_type: "application/json",
144
- # size: order.to_json.length
145
- # )
146
- # end
147
- # end
148
- #
149
- # You can access the return value of the resolve method as shown above.
150
- #
151
- def around_resolve(*filters, &blk)
152
- set_callback(:resolve, :around, *filters, &blk)
153
- end
154
- end
155
- end
9
+ # class OrdersTemplate < ApplicationMCPResTemplate
10
+ # uri_template "ecommerce://customers/{customer_id}/orders/{order_id}"
11
+ #
12
+ # before_resolve do |template|
13
+ # Rails.logger.info("Resolving order #{template.order_id}")
14
+ # end
15
+ #
16
+ # around_resolve do |template, block|
17
+ # resource = block.call
18
+ # Rails.logger.info("Order #{template.order_id} not found") unless resource
19
+ # resource
20
+ # end
21
+ #
22
+ # after_resolve do |template|
23
+ # Rails.logger.info("Resolved order #{template.order_id}")
24
+ # end
25
+ # end
26
+ #
27
+ # The around callback receives the value returned by +resolve+.
28
+ ResourceCallbacks = LifecycleCallbacks.for(:resolve)
156
29
  end
@@ -82,13 +82,9 @@ module ActionMCP
82
82
 
83
83
  # Override to_h to use -32002 for resource not found (consistent with send_resource_read)
84
84
  def to_h(_options = nil)
85
- if @is_error && @symbol.nil?
86
- { code: -32_002, message: @error_message, data: @error_data }
87
- elsif @is_error
88
- JSON_RPC::JsonRpcError.new(@symbol, message: @error_message, data: @error_data).to_h
89
- else
90
- build_success_hash
91
- end
85
+ return { code: -32_002, message: @error_message, data: @error_data } if @is_error && @symbol.nil?
86
+
87
+ super
92
88
  end
93
89
 
94
90
  # Implementation of build_success_hash for ResourceResponse
@@ -12,6 +12,7 @@ module ActionMCP
12
12
  include ResourceCallbacks
13
13
  include UriAmbiguityChecker
14
14
  include CurrentHelpers
15
+ include RequestMeta
15
16
 
16
17
  # Track all registered templates
17
18
  @registered_templates = []
@@ -0,0 +1,50 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ActionMCP
4
+ # Receiver for schema keywords given as procs. The proc runs through
5
+ # instance_exec, so it reads the session and the current user the same way
6
+ # a tool does:
7
+ #
8
+ # property :tool, type: "string", enum: -> { current_user.allowed_tools }
9
+ # collection :labels, type: "string", enum: -> { session_data["labels"] }
10
+ #
11
+ # session is nil when the schema is built outside a request (rake tasks).
12
+ # A proc that raises surfaces as ActionMCP::SchemaResolutionError.
13
+ class SchemaContext
14
+ include CurrentHelpers
15
+
16
+ attr_reader :session
17
+
18
+ def initialize(session = nil, owner = nil)
19
+ @session = session
20
+ @owner = owner
21
+ end
22
+
23
+ def session_data
24
+ session&.session_data
25
+ end
26
+
27
+ def resolve(value)
28
+ case value
29
+ when Hash then value.to_h { |key, nested| [ key, resolve(nested) ] }
30
+ when Array then value.map { |nested| resolve(nested) }
31
+ when Proc then resolve(evaluate(value))
32
+ else value.duplicable? ? value.dup : value
33
+ end
34
+ end
35
+
36
+ def evaluate(keyword_proc)
37
+ instance_exec(&keyword_proc)
38
+ rescue StandardError => e
39
+ raise SchemaResolutionError, "Schema keyword proc for #{@owner || 'a tool'} failed: #{e.class}: #{e.message}"
40
+ end
41
+
42
+ def self.dynamic?(value)
43
+ case value
44
+ when Hash then value.each_value.any? { |nested| dynamic?(nested) }
45
+ when Array then value.any? { |nested| dynamic?(nested) }
46
+ else value.is_a?(Proc)
47
+ end
48
+ end
49
+ end
50
+ end