actionmcp 0.111.0 → 0.200.0

data/lib/action_mcp/renderable.rb

@@ -21,9 +21,9 @@ module ActionMCP
     #   render(text: "Hello, world!")
     #
     def render(text: nil, audio: nil, image: nil, resource: nil, mime_type: nil, blob: nil)
-      if resource && mime_type
+      if !resource.nil?
         Content::Resource.new(resource, mime_type, text: text, blob: blob, annotations: nil)
-      elsif text
+      elsif !text.nil?
         Content::Text.new(text, annotations: nil)
       elsif audio && mime_type
         Content::Audio.new(audio, mime_type, annotations: nil)
@@ -37,7 +37,7 @@ module ActionMCP
     # Renders a resource link for Model Context Protocol responses.
     #
     # @param uri [String] The URI of the resource
-    # @param name [String, nil] Optional name for the resource
+    # @param name [String] Name for the resource
     # @param description [String, nil] Optional description
     # @param mime_type [String, nil] Optional MIME type
     # @param annotations [Hash, nil] Optional annotations
@@ -47,7 +47,7 @@ module ActionMCP
     # @example Render a resource link
     #   render_resource_link(uri: "file:///path/to/file.txt", name: "Example File")
     #
-    def render_resource_link(uri:, name: nil, description: nil, mime_type: nil, annotations: nil)
+    def render_resource_link(uri:, name:, description: nil, mime_type: nil, annotations: nil)
       Content::ResourceLink.new(uri, name: name, description: description,
                                      mime_type: mime_type, annotations: annotations)
     end

data/lib/action_mcp/resource.rb

@@ -15,23 +15,26 @@ module ActionMCP
     # @param annotations [Hash, nil] Optional annotations
     # @param meta [Hash, #to_hash, #to_h, nil] Optional extension metadata. Emitted on the wire as `_meta`.
     def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil, meta: nil)
+      raise ArgumentError, "uri must be a non-empty string" unless uri.is_a?(String) && uri.present?
+      raise ArgumentError, "name must be a non-empty string" unless name.is_a?(String) && name.present?
+
+      { title: title, description: description, mime_type: mime_type }.each do |field, value|
+        raise ArgumentError, "#{field} must be a string or nil" unless value.nil? || value.is_a?(String)
+      end
+      unless size.nil? || (size.is_a?(Integer) && size >= 0)
+        raise ArgumentError, "size must be a non-negative integer or nil"
+      end
+
       @uri = uri
       @name = name
       @title = title
       @description = description
       @mime_type = mime_type
       @size = size
-      @annotations = annotations
-      @meta =
-        if meta.nil?
-          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
+      @annotations = annotations.nil? ? nil : Content::Validation.copy_object!(annotations, "annotations")
+      Content::Validation.validate_annotations!(@annotations)
+      @meta = meta.nil? ? nil : Content::Validation.copy_object!(meta, "meta")
+      to_h
       freeze
     end
 
@@ -47,6 +50,7 @@ module ActionMCP
       hash[:size] = size if size
       hash[:annotations] = annotations if annotations
       hash[:_meta] = meta if meta && !meta.empty?
+      Content::Validation.validate_resource!(hash)
       hash
     end
 

data/lib/action_mcp/resource_template.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "active_model"
+require "addressable/template"
+require "addressable/uri"
 
 module ActionMCP
   class ResourceTemplate
@@ -13,7 +15,7 @@ module ActionMCP
 
     # Track all registered templates
     @registered_templates = []
-    attr_reader :execution_context
+    attr_reader :execution_context, :resolved_uri
 
     # Delegate to class-level DSL values so instances see template metadata.
     delegate :description, :uri_template, :mime_type, to: :class
@@ -51,9 +53,8 @@ module ActionMCP
         @required_parameters ||= []
       end
 
-      # Cache compiled regex patterns for URI matching to avoid recompilation
-      def uri_regex_cache
-        @uri_regex_cache ||= {}
+      def addressable_template_cache
+        @addressable_template_cache ||= {}
       end
 
       def parameter(name, description:, required: false, **options)
@@ -129,46 +130,62 @@ module ActionMCP
       def meta_with_ui(meta = nil)
         supplied_meta = coerce_meta(meta)
         ui_meta = @ui_meta&.any? ? { ui: @ui_meta } : {}
+        combined = ui_meta.deep_merge(supplied_meta)
 
-        return nil if ui_meta.empty? && supplied_meta.empty?
-        return supplied_meta if ui_meta.empty?
-        return ui_meta if supplied_meta.empty?
+        return nil if combined.empty?
 
-        ui_meta.deep_merge(supplied_meta)
+        ui_present, combined_ui = metadata_value(combined, :ui)
+        validate_ui_metadata!(combined_ui) if ui_present
+        combined
       end
 
       private
 
       def validate_ui_metadata!(data)
-        validate_ui_csp_origins!(data[:csp] || data["csp"])
-        validate_ui_permissions!(data[:permissions] || data["permissions"])
+        raise ArgumentError, "ui metadata must be a hash" unless data.is_a?(Hash)
+
+        validate_ui_keys!(data, Apps::UI_META_KEYS, "metadata")
+        csp_present, csp = metadata_value(data, :csp)
+        permissions_present, permissions = metadata_value(data, :permissions)
+        domain_present, domain = metadata_value(data, :domain)
+        border_present, border = metadata_value(data, :prefersBorder)
+
+        validate_ui_csp_origins!(csp) if csp_present
+        validate_ui_permissions!(permissions) if permissions_present
+        if domain_present && !domain.is_a?(String)
+          raise ArgumentError, "ui domain must be a string, got: #{domain.inspect}"
+        end
+        if border_present && border != true && border != false
+          raise ArgumentError, "ui prefersBorder must be true or false, got: #{border.inspect}"
+        end
       end
 
       def validate_ui_csp_origins!(csp)
-        return unless csp.is_a?(Hash)
+        raise ArgumentError, "ui csp must be a hash" unless csp.is_a?(Hash)
 
+        validate_ui_keys!(csp, Apps::CSP_KEYS, "csp")
         Apps::CSP_KEYS.each do |key|
           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)
+          metadata_values(csp, key).each do |origins|
+            unless origins.is_a?(Array)
+              raise ArgumentError, "ui csp #{key} must be an array, got: #{origins.inspect}"
+            end
 
-            raise ArgumentError,
-                  "ui csp #{key} entries must be #{scheme_message} origins, got: #{origin.inspect}"
+            origins.each do |origin|
+              next if origin.is_a?(String) && pattern.match?(origin)
+
+              raise ArgumentError,
+                    "ui csp #{key} entries must be #{scheme_message} origins, got: #{origin.inspect}"
+            end
           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
+        validate_ui_keys!(permissions, Apps::PERMISSION_KEYS, "permissions")
 
         permissions.each do |key, value|
           next if value.respond_to?(:to_hash)
@@ -194,6 +211,30 @@ module ActionMCP
         coerced
       end
 
+      def metadata_value(data, key)
+        return [ true, data[key] ] if data.key?(key)
+        return [ true, data[key.to_s] ] if data.key?(key.to_s)
+
+        [ false, nil ]
+      end
+
+      def metadata_values(data, key)
+        values = []
+        values << data[key] if data.key?(key)
+        values << data[key.to_s] if data.key?(key.to_s)
+        values
+      end
+
+      def validate_ui_keys!(data, allowed_keys, label)
+        invalid = data.keys.reject do |key|
+          key.respond_to?(:to_sym) && allowed_keys.include?(key.to_sym)
+        end
+        return if invalid.empty?
+
+        raise ArgumentError,
+              "ui #{label} keys must be #{allowed_keys.join('/')}, got: #{invalid.inspect}"
+      end
+
       public
 
       def to_h
@@ -282,84 +323,41 @@ module ActionMCP
         params = extract_params_from_uri(uri_string)
         return new if params.nil? # Return invalid template for bad URI
 
-        # Create new instance with the extracted parameters
-        new(params)
+        # Preserve the concrete URI requested by the client. The template URI
+        # may contain placeholders and must not leak into resource contents.
+        new(params).tap { |record| record.instance_variable_set(:@resolved_uri, uri_string) }
       end
 
       private
 
       # Extract parameters from a URI using the template pattern
       def extract_params_from_uri(uri_string)
-        # Check cache for compiled regex and param names
-        cache_entry = uri_regex_cache[@uri_template]
-
-        unless cache_entry
-          # Convert template parameters to named capture groups
-          regex_parts = []
-          current_pos = 0
-          param_names = []
-
-          # Find all template parameters like {param_name}
-          @uri_template.scan(/\{([^}]+)\}/) do |param_name|
-            param_names << param_name[0]
-
-            # Get the position of this parameter in the template
-            param_start = @uri_template.index("{#{param_name[0]}}", current_pos)
-
-            # Add the text before the parameter (escaped)
-            if param_start > current_pos
-              prefix = Regexp.escape(@uri_template[current_pos...param_start])
-              regex_parts << prefix
-            end
-
-            # Add the named capture group
-            regex_parts << "(?<#{param_name[0]}>[^/]+)"
-
-            # Update current position
-            current_pos = param_start + param_name[0].length + 2 # +2 for { and }
-          end
-
-          # Add any remaining text after the last parameter
-          if current_pos < @uri_template.length
-            suffix = Regexp.escape(@uri_template[current_pos..])
-            regex_parts << suffix
-          end
-
-          # Build the final regex and cache it
-          regex_pattern = regex_parts.join
-          regex = Regexp.new("^#{regex_pattern}$")
-          cache_entry = { regex: regex, param_names: param_names }
-          uri_regex_cache[@uri_template] = cache_entry
-        end
-
-        # Try to match the URI using cached regex
-        match_data = cache_entry[:regex].match(uri_string)
-        return nil unless match_data
-
-        # Extract named captures as parameters
-        params = {}
-        cache_entry[:param_names].each do |name|
-          params[name.to_sym] = match_data[name] if match_data[name]
-        end
-
-        params
+        extracted = compiled_uri_template(@uri_template).extract(uri_string)
+        extracted&.transform_keys(&:to_sym)
       end
 
       # Extract the schema and pattern from a URI template
       def parse_uri_template(template)
-        # Parse the URI template to get schema and pattern
-        # Format: schema://path/{param1}/{param2}...
-        if template =~ %r{^([^:]+)://(.+)$}
-          schema = ::Regexp.last_match(1)
-          pattern = ::Regexp.last_match(2)
-
-          # Replace parameter placeholders with generic markers to compare structure
-          normalized_pattern = pattern.gsub(/\{[^}]+\}/, "{param}")
-
-          return { schema: schema, pattern: normalized_pattern, original: template }
+        addressable_template = compiled_uri_template(template)
+        variables = addressable_template.variables.index_with.with_index do |_, index|
+          "action_mcp_parameter_#{index}"
         end
+        expanded = addressable_template.expand(variables).to_s
+        parsed_uri = Addressable::URI.parse(expanded)
+        raise ArgumentError, "Invalid URI template format: #{template}" if parsed_uri.scheme.blank?
+
+        normalized_pattern = expanded.delete_prefix("#{parsed_uri.scheme}:").delete_prefix("//")
+        variables.each_value { |marker| normalized_pattern.gsub!(marker, "{param}") }
+
+        { schema: parsed_uri.scheme, pattern: normalized_pattern, original: template }
+      rescue Addressable::URI::InvalidURIError,
+             Addressable::Template::InvalidTemplateValueError,
+             Addressable::Template::InvalidTemplateOperatorError => e
+        raise ArgumentError, "Invalid URI template format: #{template} (#{e.message})"
+      end
 
-        raise ArgumentError, "Invalid URI template format: #{template}"
+      def compiled_uri_template(template)
+        addressable_template_cache[template] ||= Addressable::Template.new(template)
       end
 
       # Validate that the URI template is unique
@@ -411,9 +409,26 @@ module ActionMCP
           raise ArgumentError, "render_ui requires :text or :template"
         end
 
+      resource_uri = resolved_uri || self.class.uri_template
+      unless resource_uri.is_a?(String) && ActionMCP::Apps::URI_SCHEME.match?(resource_uri)
+        raise ArgumentError, "render_ui requires a concrete ui:// resource URI, got: #{resource_uri.inspect}"
+      end
+      if resolved_uri.nil? && resource_uri.match?(/\{[^}]+\}/)
+        raise ArgumentError, "render_ui cannot emit a parameterized URI template without a concrete request URI"
+      end
+
+      resource_mime_type = self.class.mime_type || ActionMCP::Apps::MIME_TYPE
+      unless resource_mime_type == ActionMCP::Apps::MIME_TYPE
+        raise ArgumentError,
+              "render_ui requires mime type #{ActionMCP::Apps::MIME_TYPE.inspect}, got: #{resource_mime_type.inspect}"
+      end
+      unless resolved.is_a?(String)
+        raise ArgumentError, "render_ui content must be a string, got: #{resolved.class}"
+      end
+
       ActionMCP::Content::Resource.new(
-        self.class.uri_template,
-        self.class.mime_type || ActionMCP::Apps::MIME_TYPE,
+        resource_uri,
+        resource_mime_type,
         text: resolved,
         meta: self.class.meta_with_ui(meta)
       )

data/lib/action_mcp/resource_templates_registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "addressable/template"
+
 module ActionMCP
   # Registry for managing resource templates.
   class ResourceTemplatesRegistry < RegistryBase
@@ -24,53 +26,22 @@ module ActionMCP
 
       # Find the most specific template for a given URI.
       # Uses registry-backed source (not ResourceTemplate.registered_templates class array).
-      def find_template_for_uri(uri)
-        parse_result = parse_uri(uri)
-        return nil unless parse_result
-
-        schema = parse_result[:schema]
-        path = parse_result[:path]
-        path_segments = path.split("/")
-
-        matching_templates = resource_templates.values.select do |template|
+      def find_template_for_uri(uri, templates: resource_templates.values)
+        matching_templates = templates.select do |template|
           next unless template.uri_template
 
-          # Parse the template
-          template_data = parse_uri_template(template.uri_template)
-          next unless template_data && template_data[:schema] == schema
-
-          # Split template into segments and check if structure matches
-          template_segments = template_data[:path].split("/")
-          next unless template_segments.length == path_segments.length
-
-          # Check if each segment matches (either static match or a parameter)
-          segments_match = true
-
-          template_segments.each_with_index do |template_segment, index|
-            path_segment = path_segments[index]
-
-            if template_segment.start_with?("{") && template_segment.end_with?("}")
-              # This is a parameter segment, it matches any value
-              next
-            elsif template_segment != path_segment
-              # Static segment doesn't match
-              segments_match = false
-              break
-            end
-          end
-
-          segments_match
+          compiled_template(template.uri_template).extract(uri)
+        rescue Addressable::URI::InvalidURIError,
+               Addressable::Template::InvalidTemplateValueError,
+               Addressable::Template::InvalidTemplateOperatorError
+          false
         end
 
         # If multiple templates match, select the most specific one
         # (the one with the most static segments)
         if matching_templates.size > 1
           matching_templates.max_by do |template|
-            template_data = parse_uri_template(template.uri_template)
-            template_segments = template_data[:path].split("/")
-
-            # Count static segments (not parameters)
-            template_segments.count { |segment| !segment.start_with?("{") }
+            template_specificity(template.uri_template)
           end
         elsif matching_templates.size == 1
           matching_templates.first
@@ -79,75 +50,38 @@ module ActionMCP
 
       # Check if a URI matches a specific template
       def uri_matches_template?(uri, template)
-        uri_data = parse_uri(uri)
-        template_data = parse_uri_template(template.uri_template)
-
-        return false unless uri_data && template_data && uri_data[:schema] == template_data[:schema]
-
-        uri_segments = uri_data[:path].split("/")
-        template_segments = template_data[:path].split("/")
-
-        return false unless uri_segments.length == template_segments.length
-
-        # Check each segment
-        template_segments.each_with_index do |template_segment, index|
-          uri_segment = uri_segments[index]
-
-          # If template segment is a parameter, it matches anything
-          next if template_segment.start_with?("{") && template_segment.end_with?("}")
-
-          # Otherwise, segments must match exactly
-          return false if template_segment != uri_segment
-        end
-
-        true
+        !compiled_template(template.uri_template).extract(uri).nil?
+      rescue Addressable::URI::InvalidURIError,
+             Addressable::Template::InvalidTemplateValueError,
+             Addressable::Template::InvalidTemplateOperatorError
+        false
       end
 
       # Extract parameter values from a URI based on a template
       def extract_parameters(uri, template)
-        return {} unless uri_matches_template?(uri, template)
-
-        uri_data = parse_uri(uri)
-        template_data = parse_uri_template(template.uri_template)
-
-        uri_segments = uri_data[:path].split("/")
-        template_segments = template_data[:path].split("/")
-
-        # Extract parameters
-        params = {}
-        template_segments.each_with_index do |template_segment, index|
-          next unless template_segment.start_with?("{") && template_segment.end_with?("}")
-
-          # Extract parameter name without braces
-          param_name = template_segment[1...-1].to_sym
-          params[param_name] = uri_segments[index]
-        end
-
-        params
+        extracted = compiled_template(template.uri_template).extract(uri)
+        extracted ? extracted.transform_keys(&:to_sym) : {}
+      rescue Addressable::URI::InvalidURIError,
+             Addressable::Template::InvalidTemplateValueError,
+             Addressable::Template::InvalidTemplateOperatorError
+        {}
       end
 
       private
 
-      # Parse a concrete URI
-      def parse_uri(uri)
-        return unless uri =~ %r{^([^:]+)://(.+)$}
-
-        {
-          schema: ::Regexp.last_match(1),
-          path: ::Regexp.last_match(2),
-          original: uri
-        }
+      def compiled_template(pattern)
+        compiled_templates[pattern] ||= Addressable::Template.new(pattern)
       end
 
-      # Parse a URI template
-      def parse_uri_template(template)
-        return unless template =~ %r{^([^:]+)://(.+)$}
+      def compiled_templates
+        @compiled_templates ||= {}
+      end
 
-        {
-          schema: ::Regexp.last_match(1),
-          path: ::Regexp.last_match(2),
-          original: template
-        }
+      def template_specificity(pattern)
+        segments = pattern.split("/")
+        static_segments = segments.count { |segment| !segment.include?("{") }
+        literal_length = pattern.gsub(/\{[^}]*\}/, "").length
+        [ static_segments, literal_length ]
       end
     end
   end

data/lib/action_mcp/schema_validator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+
+module ActionMCP
+  module SchemaValidator
+    DEFAULT_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+
+    module_function
+
+    def compile(schema, context: "JSON Schema")
+      normalized_schema = normalize(schema)
+      schema_errors = JSONSchemer.validate_schema(normalized_schema).to_a
+
+      if schema_errors.any?
+        raise ArgumentError, "Invalid #{context}: #{error_messages(schema_errors).join(', ')}"
+      end
+
+      JSONSchemer.schema(normalized_schema)
+    rescue JSONSchemer::UnknownRef => e
+      raise ArgumentError, "Invalid #{context}: unknown schema dialect or reference #{e.message.inspect}"
+    end
+
+    def validate(schemer, value)
+      schemer.validate(normalize(value)).to_a
+    end
+
+    def error_messages(errors)
+      errors.filter_map { |error| error["error"] }.uniq
+    end
+
+    def normalize(value)
+      case value
+      when Hash
+        value.deep_stringify_keys
+      when Array
+        value.map { |item| normalize(item) }
+      else
+        value
+      end
+    end
+  end
+end