actionmcp 0.110.2 → 0.111.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f18a19a33b307301a158d77b9fb5bfede2a9dfa9f3d316be439db3f58b313b6b
-  data.tar.gz: 5623ce4489efa81032fac7c1a9baad1a6ebe27b74593d6a25b022143f2d40d0c
+  metadata.gz: c0047ad57f7f03ccd09f3ebfc05f865412bd4731c5e918b0e7886a37c9a708e1
+  data.tar.gz: c85e5ffc964b2bc2587a12b669cd5e754feff1e8266fc0abf50fa0e3a40e2b15
 SHA512:
-  metadata.gz: fe04793ecfdad4d4c90041d3834b52fdf0956b152c51a4c5a866380bba60d327c560c427962eaac2259c6087a22daa7d97244adc75a5f7e7099ae0a37ec44fbf
-  data.tar.gz: 75ece96abe7f14658da802e3b295cb085bd7c736e900a7339f42c91b65c1ddd2422e10c650bac99121201ccd1b3abaaa0a39c2ad4665bafc5f7748493ce45a5c
+  metadata.gz: a8d4f3f7f47d9ac6031ebb925aa7ef59bb4e42ce7b2273ca768e431b13860d32887db55a1599ca6fe5991d39f5339347827fef12ef78e4a96ea0dfa1671ec864
+  data.tar.gz: 45ce27835f49e3f1068ec69e76c1c9f0d54fe5c13be1cabce94993490647d282b098fed63410953e10835227d980b6ae4450b12fd65915dcf176f422c5b97c33

data/lib/action_mcp/apps.rb

@@ -1,20 +1,37 @@
 # frozen_string_literal: true
 
 module ActionMCP
-  # Constants for the MCP Apps extension (ext-apps, SEP-1865, draft 2026-01-26).
-  # See: https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx
+  # Constants and helpers for the MCP Apps extension (ext-apps, SEP-1865,
+  # stable 2026-01-26).
+  # See: https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
   module Apps
     EXTENSION_KEY = "io.modelcontextprotocol/ui"
     VISIBILITY_VALUES = %w[model app].freeze
     URI_SCHEME = %r{\Aui://\S+\z}
     MIME_TYPE = MimeTypes::APP_HTML
+    EXTENSION_SETTINGS = { mimeTypes: [ MIME_TYPE ] }.freeze
 
     # `_meta.ui.csp` directive keys per ext-apps spec.
     CSP_KEYS = %i[connectDomains resourceDomains frameDomains baseUriDomains].freeze
+    PERMISSION_KEYS = %i[camera microphone geolocation clipboardWrite].freeze
 
-    # Accepts http/https origins only. Wildcard subdomain (`https://*.example.com`),
-    # ports, and paths are allowed. WebSocket origins (ws://, wss://) are not
-    # accepted by ActionMCP — declare them via `ws://` over fetch if you must.
-    ORIGIN_PATTERN = %r{\Ahttps?://[^\s"'<>]+\z}
+    # The stable MCP Apps spec allows WebSocket endpoints for connect-src only.
+    CONNECT_ORIGIN_PATTERN = %r{\A(?:https?|wss?)://[^\s"'<>]+\z}
+    RESOURCE_ORIGIN_PATTERN = %r{\Ahttps?://[^\s"'<>]+\z}
+
+    module_function
+
+    def extension_settings
+      EXTENSION_SETTINGS.deep_dup
+    end
+
+    def client_supports?(client_capabilities)
+      settings = client_capabilities&.dig("extensions", EXTENSION_KEY) ||
+                 client_capabilities&.dig(:extensions, EXTENSION_KEY)
+      return false unless settings.is_a?(Hash)
+
+      mime_types = settings["mimeTypes"] || settings[:mimeTypes]
+      Array(mime_types).include?(MIME_TYPE)
+    end
   end
 end

data/lib/action_mcp/capability.rb

@@ -32,10 +32,12 @@ module ActionMCP
 
     delegate :session_data, to: :session, allow_nil: true
 
-    # Returns true when the connected client advertises the MCP Apps UI extension.
+    # Returns true when the connected client advertises the MCP Apps UI extension
+    # and supports ActionMCP's HTML app resource MIME type.
     def client_supports_ui?
-      !session&.client_capabilities&.dig("extensions", Apps::EXTENSION_KEY).nil?
+      Apps.client_supports?(session&.client_capabilities)
     end
+    alias client_supports_mcp_app? client_supports_ui?
 
     # use _capability_name or default_capability_name
     def self.capability_name

data/lib/action_mcp/configuration.rb

@@ -48,6 +48,8 @@ module ActionMCP
                   :tasks_result_strategy,
                   :tasks_result_timeout,
                   :tasks_result_poll_interval,
+                  # --- MCP Apps Extension Options ---
+                  :mcp_apps_enabled,
                   # --- Schema Validation Options ---
                   :validate_structured_content,
                   # --- Allowed identity keys for gateway ---
@@ -79,6 +81,9 @@ module ActionMCP
       @tasks_result_timeout = 30.seconds
       @tasks_result_poll_interval = 0.25
 
+      # MCP Apps extension defaults to explicit opt-in.
+      @mcp_apps_enabled = false
+
       # Pagination - nil means off. Set a number to enable with that page size.
       # Most MCP clients (including Claude Code) don't follow nextCursor yet.
       @pagination_page_size = nil
@@ -319,6 +324,11 @@ module ActionMCP
         capabilities[:tasks] = tasks_cap
       end
 
+      if @mcp_apps_enabled
+        capabilities[:extensions] ||= {}
+        capabilities[:extensions][Apps::EXTENSION_KEY] = Apps.extension_settings
+      end
+
       capabilities
     end
 
@@ -341,6 +351,7 @@ module ActionMCP
       @logging_enabled = options[:logging_enabled] unless options[:logging_enabled].nil?
       @logging_level = options[:logging_level] unless options[:logging_level].nil?
       @resources_subscribe = options[:resources_subscribe] unless options[:resources_subscribe].nil?
+      @mcp_apps_enabled = boolean_config_value(options[:mcp_apps_enabled]) unless options[:mcp_apps_enabled].nil?
     end
 
     def eager_load_if_needed
@@ -437,6 +448,8 @@ module ActionMCP
         self.tasks_result_poll_interval = config["tasks_result_poll_interval"]
       end
 
+      @mcp_apps_enabled = boolean_config_value(config["mcp_apps_enabled"]) if config.key?("mcp_apps_enabled")
+
       # Extract allowed origins for DNS rebinding protection
       if config["allowed_origins"]
         @allowed_origins = Array(config["allowed_origins"])
@@ -470,6 +483,17 @@ module ActionMCP
       duration
     end
 
+    def boolean_config_value(value)
+      case value
+      when true, false
+        value
+      when String
+        !%w[false 0 no off].include?(value.strip.downcase)
+      else
+        !!value
+      end
+    end
+
     def ensure_mcp_components_loaded
       # Only load if we haven't loaded yet - but in development, always reload
       return if @mcp_components_loaded && !Rails.env.development?

data/lib/action_mcp/resource_template.rb

@@ -121,26 +121,79 @@ module ActionMCP
       def ui(**data)
         raise ArgumentError, "ui metadata must not be empty" if data.empty?
 
-        validate_ui_csp_origins!(data[:csp])
+        validate_ui_metadata!(data)
         @ui_meta ||= {}
         @ui_meta = @ui_meta.deep_merge(data)
       end
 
+      def meta_with_ui(meta = nil)
+        supplied_meta = coerce_meta(meta)
+        ui_meta = @ui_meta&.any? ? { ui: @ui_meta } : {}
+
+        return nil if ui_meta.empty? && supplied_meta.empty?
+        return supplied_meta if ui_meta.empty?
+        return ui_meta if supplied_meta.empty?
+
+        ui_meta.deep_merge(supplied_meta)
+      end
+
       private
 
+      def validate_ui_metadata!(data)
+        validate_ui_csp_origins!(data[:csp] || data["csp"])
+        validate_ui_permissions!(data[:permissions] || data["permissions"])
+      end
+
       def validate_ui_csp_origins!(csp)
         return unless csp.is_a?(Hash)
 
         Apps::CSP_KEYS.each do |key|
-          Array(csp[key]).each do |origin|
-            next if origin.is_a?(String) && Apps::ORIGIN_PATTERN.match?(origin)
+          pattern = key == :connectDomains ? Apps::CONNECT_ORIGIN_PATTERN : Apps::RESOURCE_ORIGIN_PATTERN
+          scheme_message = key == :connectDomains ? "http(s):// or ws(s)://" : "http(s)://"
+          Array(csp[key] || csp[key.to_s]).each do |origin|
+            next if origin.is_a?(String) && pattern.match?(origin)
 
             raise ArgumentError,
-                  "ui csp #{key} entries must be http(s):// origins, got: #{origin.inspect}"
+                  "ui csp #{key} entries must be #{scheme_message} origins, got: #{origin.inspect}"
           end
         end
       end
 
+      def validate_ui_permissions!(permissions)
+        return unless permissions
+        raise ArgumentError, "ui permissions must be a hash" unless permissions.is_a?(Hash)
+
+        normalized_keys = permissions.keys.map(&:to_sym)
+        invalid = normalized_keys - Apps::PERMISSION_KEYS
+        if invalid.any?
+          raise ArgumentError,
+                "ui permissions keys must be #{Apps::PERMISSION_KEYS.join('/')}, got: #{invalid.inspect}"
+        end
+
+        permissions.each do |key, value|
+          next if value.respond_to?(:to_hash)
+
+          raise ArgumentError, "ui permissions #{key} value must be a hash, got: #{value.inspect}"
+        end
+      end
+
+      def coerce_meta(meta)
+        coerced =
+          if meta.nil?
+            {}
+          elsif meta.respond_to?(:to_hash)
+            meta.to_hash
+          elsif meta.respond_to?(:to_h)
+            meta.to_h
+          else
+            raise ArgumentError, "meta must respond to :to_hash or :to_h, got: #{meta.class}"
+          end
+
+        coerced = coerced.deep_dup
+        coerced[:ui] = coerced.delete("ui") if coerced.key?("ui") && !coerced.key?(:ui)
+        coerced
+      end
+
       public
 
       def to_h
@@ -153,8 +206,8 @@ module ActionMCP
           mimeType: @mime_type
         }.compact
 
-        # Add _meta if present
-        result[:_meta] = @_meta if @_meta&.any?
+        meta = meta_with_ui(@_meta)
+        result[:_meta] = meta if meta&.any?
 
         result
       end
@@ -201,7 +254,7 @@ module ActionMCP
           mime_type: mime_type || @mime_type,
           size: size,
           annotations: annotations,
-          meta: meta
+          meta: meta_with_ui(meta)
         )
       end
 
@@ -338,11 +391,13 @@ module ActionMCP
     #
     # @example
     #   render_ui(template: "mcp/ui/weather_dashboard")
-    def render_ui(text: nil, template: nil, layout: false, locals: {})
+    def render_ui(text: nil, template: nil, layout: false, locals: {}, meta: nil)
+      raise ArgumentError, "render_ui accepts either :text or :template, not both" if !text.nil? && !template.nil?
+
       resolved =
-        if text
+        if !text.nil?
           text
-        elsif template
+        elsif !template.nil?
           rendered = ActionMCP::MCPAppRenderer.render(template: template, layout: layout, locals: locals)
           if rendered.to_s.strip.empty?
             ActionMCP.logger.warn(
@@ -356,12 +411,11 @@ module ActionMCP
           raise ArgumentError, "render_ui requires :text or :template"
         end
 
-      ui = self.class.ui_meta
       ActionMCP::Content::Resource.new(
         self.class.uri_template,
         self.class.mime_type || ActionMCP::Apps::MIME_TYPE,
         text: resolved,
-        meta: (ui&.any? ? { ui: ui } : nil)
+        meta: self.class.meta_with_ui(meta)
       )
     end
 

data/lib/action_mcp/tool.rb

@@ -30,6 +30,7 @@ module ActionMCP
     class_attribute :_output_schema_builder, instance_accessor: false, default: nil
     class_attribute :_additional_properties, instance_accessor: false, default: nil
     class_attribute :_cached_schema_property_keys, instance_accessor: false, default: nil
+    class_attribute :_property_aliases, instance_accessor: false, default: {}
     class_attribute :_task_support, instance_accessor: false, default: :forbidden
     class_attribute :_resumable_steps_block, instance_accessor: false, default: nil
 
@@ -296,16 +297,46 @@ module ActionMCP
       def schema_property_keys
         return _cached_schema_property_keys if _cached_schema_property_keys
 
-        self._cached_schema_property_keys = _schema_properties.keys.map(&:to_s)
+        self._cached_schema_property_keys = (_schema_properties.keys + _property_aliases.keys).map(&:to_s)
         _cached_schema_property_keys
       end
 
-      # Clear cached keys when properties change - use metaprogramming to avoid duplication
-      [ :property, :collection ].each do |method_name|
-        define_method(method_name) do |prop_name, **opts|
-          invalidate_schema_cache
-          super(prop_name, **opts)
+      # Creates an alternate input name for an existing property.
+      #
+      # @example
+      #   property :thread_id, type: "string", required: true
+      #   alias_property :root_id, :thread_id
+      #
+      # Both `root_id` and `thread_id` are accepted when initializing the tool,
+      # and both readers resolve to the same ActiveModel attribute.
+      def alias_property(alias_name, property_name)
+        alias_key = alias_name.to_s
+        property_key = canonical_property_name(property_name)
+
+        unless _schema_properties.key?(property_key)
+          raise ArgumentError, "Cannot alias unknown property '#{property_name}'"
+        end
+
+        if alias_key == property_key
+          raise ArgumentError, "Cannot alias property '#{property_key}' to itself"
+        end
+
+        if _schema_properties.key?(alias_key)
+          raise ArgumentError, "Cannot alias '#{alias_key}' because it is already defined as a property"
+        end
+
+        existing_alias = _property_aliases[alias_key]
+        if existing_alias && existing_alias != property_key
+          raise ArgumentError, "Alias '#{alias_key}' already points to property '#{existing_alias}'"
         end
+
+        self._property_aliases = _property_aliases.merge(alias_key => property_key)
+        alias_attribute alias_key, property_key
+        invalidate_schema_cache
+      end
+
+      def canonical_property_name(name)
+        _property_aliases[name.to_s] || name.to_s
       end
 
       private
@@ -332,6 +363,12 @@ module ActionMCP
     # @param opts [Hash] Additional options for the JSON Schema.
     # @return [void]
     def self.property(prop_name, type: "string", description: nil, required: false, default: nil, **opts)
+      if _property_aliases.key?(prop_name.to_s)
+        raise ArgumentError, "Cannot define property '#{prop_name}' because it is already defined as an alias"
+      end
+
+      invalidate_schema_cache
+
       # Build the JSON Schema definition.
       prop_definition = { type: type }
       prop_definition[:description] = description if description && !description.empty?
@@ -365,6 +402,12 @@ module ActionMCP
     def self.collection(prop_name, type:, description: nil, required: false, default: [])
       raise ArgumentError, "Type is required for a collection" if type.nil?
 
+      if _property_aliases.key?(prop_name.to_s)
+        raise ArgumentError, "Cannot define collection '#{prop_name}' because it is already defined as an alias"
+      end
+
+      invalidate_schema_cache
+
       collection_definition = { type: "array", items: { type: type } }
       collection_definition[:description] = description if description && !description.empty?
 
@@ -443,6 +486,8 @@ module ActionMCP
 
     # Override initialize to validate parameters before ActiveModel conversion
     def initialize(attributes = {})
+      validate_property_alias_conflicts(attributes)
+
       # Separate additional properties from defined attributes if enabled
       if self.class.accepts_additional_properties?
         defined_keys = self.class.schema_property_keys
@@ -647,20 +692,43 @@ module ActionMCP
 
     private
 
+    def validate_property_alias_conflicts(attributes)
+      return unless attributes.is_a?(Hash)
+
+      seen_values = {}
+      seen_keys = {}
+
+      attributes.each do |key, value|
+        key_str = key.to_s
+        property_key = self.class.canonical_property_name(key_str)
+        next unless self.class._schema_properties.key?(property_key)
+
+        if seen_values.key?(property_key) && seen_keys[property_key] != key_str && seen_values[property_key] != value
+          raise ArgumentError,
+                "Conflicting values provided for aliased property '#{property_key}' " \
+                "via '#{seen_keys[property_key]}' and '#{key_str}'"
+        end
+
+        seen_values[property_key] = value
+        seen_keys[property_key] = key_str
+      end
+    end
+
     # Validates parameter types before ActiveModel conversion
     def validate_parameter_types(attributes)
       return unless attributes.is_a?(Hash)
 
       attributes.each do |key, value|
         key_str = key.to_s
-        property_schema = self.class._schema_properties[key_str]
+        property_key = self.class.canonical_property_name(key_str)
+        property_schema = self.class._schema_properties[property_key]
 
         next unless property_schema
 
         expected_type = property_schema[:type]
 
         # Skip validation if value is nil and property is not required
-        next if value.nil? && !self.class._required_properties.include?(key_str)
+        next if value.nil? && !self.class._required_properties.include?(property_key)
 
         # Validate based on expected JSON Schema type
         case expected_type

data/lib/action_mcp/version.rb

@@ -2,7 +2,7 @@
 
 require_relative "gem_version"
 module ActionMCP
-  VERSION = "0.110.2"
+  VERSION = "0.111.0"
 
   class << self
     alias version gem_version

data/lib/action_mcp.rb

@@ -42,7 +42,7 @@ module ActionMCP
   LATEST_VERSION = SUPPORTED_VERSIONS.first.freeze
   DEFAULT_PROTOCOL_VERSION = "2025-06-18" # Default to previous stable version for backwards compatibility
 
-  MIME_TYPE_APP_HTML = Apps::MIME_TYPE # MCP Apps UI resources (ext-apps, draft 2026-01-26)
+  MIME_TYPE_APP_HTML = Apps::MIME_TYPE # MCP Apps UI resources (ext-apps, stable 2026-01-26)
   class << self
     # Returns a Rack-compatible application for serving MCP requests
     # @return [#call] A Rack application that can be used with `run ActionMCP.server`

data/lib/generators/action_mcp/install/templates/mcp.yml

@@ -20,6 +20,10 @@ shared:
   #   - "Use this server to manage project tickets and workflows"
   #   - "Helpful for tracking bugs, features, and sprint planning"
 
+  # MCP Apps are an optional extension. Enable this to advertise
+  # io.modelcontextprotocol/ui with text/html;profile=mcp-app support.
+  # mcp_apps_enabled: true
+
   # MCP capability profiles
   profiles:
     primary:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: actionmcp
 version: !ruby/object:Gem::Version
-  version: 0.110.2
+  version: 0.111.0
 platform: ruby
 authors:
 - Abdelkader Boudih