vector_mcp 0.1.0 → 0.3.0

data/lib/vector_mcp/image_util.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+require "base64"
+require "stringio"
+
+module VectorMCP
+  # Provides comprehensive image handling utilities for VectorMCP operations,
+  # including format detection, validation, encoding/decoding, and conversion
+  # to MCP-compliant image content format.
+  module ImageUtil
+    module_function
+
+    # Common image MIME types and their magic byte signatures
+    IMAGE_SIGNATURES = {
+      "image/jpeg" => [
+        [0xFF, 0xD8, 0xFF].pack("C*"),
+        [0xFF, 0xD8].pack("C*")
+      ],
+      "image/png" => [[0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A].pack("C*")],
+      "image/gif" => %w[
+        GIF87a
+        GIF89a
+      ],
+      "image/webp" => [
+        "WEBP"
+      ],
+      "image/bmp" => [
+        "BM"
+      ],
+      "image/tiff" => [
+        "II*\0",
+        "MM\0*"
+      ]
+    }.freeze
+
+    # Maximum image size in bytes (default: 10MB)
+    DEFAULT_MAX_SIZE = 10 * 1024 * 1024
+
+    # Detects the MIME type of image data based on magic bytes.
+    #
+    # @param data [String] The binary image data.
+    # @return [String, nil] The detected MIME type, or nil if not recognized.
+    #
+    # @example
+    #   VectorMCP::ImageUtil.detect_image_format(File.binread("image.jpg"))
+    #   # => "image/jpeg"
+    def detect_image_format(data)
+      return nil if data.nil? || data.empty?
+
+      # Ensure we have binary data (dup to avoid modifying frozen strings)
+      binary_data = data.dup.force_encoding(Encoding::ASCII_8BIT)
+
+      IMAGE_SIGNATURES.each do |mime_type, signatures|
+        signatures.each do |signature|
+          case mime_type
+          when "image/webp"
+            # WebP files start with RIFF then have WEBP at offset 8
+            return mime_type if binary_data.start_with?("RIFF") && binary_data[8, 4] == signature
+          else
+            return mime_type if binary_data.start_with?(signature)
+          end
+        end
+      end
+
+      nil
+    end
+
+    # Validates if the provided data is a valid image.
+    #
+    # @param data [String] The binary image data.
+    # @param max_size [Integer] Maximum allowed size in bytes.
+    # @param allowed_formats [Array<String>] Allowed MIME types.
+    # @return [Hash] Validation result with :valid, :mime_type, and :errors keys.
+    #
+    # @example
+    #   result = VectorMCP::ImageUtil.validate_image(image_data)
+    #   if result[:valid]
+    #     puts "Valid #{result[:mime_type]} image"
+    #   else
+    #     puts "Errors: #{result[:errors].join(', ')}"
+    #   end
+    def validate_image(data, max_size: DEFAULT_MAX_SIZE, allowed_formats: nil)
+      errors = []
+
+      if data.nil? || data.empty?
+        errors << "Image data is empty"
+        return { valid: false, mime_type: nil, errors: errors }
+      end
+
+      # Check file size
+      errors << "Image size (#{data.bytesize} bytes) exceeds maximum allowed size (#{max_size} bytes)" if data.bytesize > max_size
+
+      # Detect format
+      mime_type = detect_image_format(data)
+      if mime_type.nil?
+        errors << "Unrecognized or invalid image format"
+        return { valid: false, mime_type: nil, errors: errors }
+      end
+
+      # Check allowed formats
+      if allowed_formats && !allowed_formats.include?(mime_type)
+        errors << "Image format #{mime_type} is not allowed. Allowed formats: #{allowed_formats.join(", ")}"
+      end
+
+      {
+        valid: errors.empty?,
+        mime_type: mime_type,
+        size: data.bytesize,
+        errors: errors
+      }
+    end
+
+    # Encodes binary image data to base64 string.
+    #
+    # @param data [String] The binary image data.
+    # @return [String] Base64 encoded string.
+    #
+    # @example
+    #   encoded = VectorMCP::ImageUtil.encode_base64(File.binread("image.jpg"))
+    def encode_base64(data)
+      Base64.strict_encode64(data)
+    end
+
+    # Decodes base64 string to binary image data.
+    #
+    # @param base64_string [String] Base64 encoded image data.
+    # @return [String] Binary image data.
+    # @raise [ArgumentError] If base64 string is invalid.
+    #
+    # @example
+    #   data = VectorMCP::ImageUtil.decode_base64(encoded_string)
+    def decode_base64(base64_string)
+      Base64.strict_decode64(base64_string)
+    rescue ArgumentError => e
+      raise ArgumentError, "Invalid base64 encoding: #{e.message}"
+    end
+
+    # Converts image data to MCP-compliant image content format.
+    #
+    # @param data [String] Binary image data or base64 encoded string.
+    # @param mime_type [String, nil] MIME type (auto-detected if nil).
+    # @param validate [Boolean] Whether to validate the image data.
+    # @param max_size [Integer] Maximum allowed size for validation.
+    # @return [Hash] MCP image content hash with :type, :data, and :mimeType.
+    # @raise [ArgumentError] If validation fails.
+    #
+    # @example Convert binary image data
+    #   content = VectorMCP::ImageUtil.to_mcp_image_content(
+    #     File.binread("image.jpg")
+    #   )
+    #   # => { type: "image", data: "base64...", mimeType: "image/jpeg" }
+    #
+    # @example Convert base64 string with explicit MIME type
+    #   content = VectorMCP::ImageUtil.to_mcp_image_content(
+    #     base64_string,
+    #     mime_type: "image/png",
+    #     validate: false
+    #   )
+    def to_mcp_image_content(data, mime_type: nil, validate: true, max_size: DEFAULT_MAX_SIZE)
+      binary_data, base64_data = process_image_data(data)
+      detected_mime_type = validate_and_detect_format(binary_data, validate, max_size)
+      final_mime_type = determine_final_mime_type(mime_type, detected_mime_type)
+
+      {
+        type: "image",
+        data: base64_data,
+        mimeType: final_mime_type
+      }
+    end
+
+    # Processes input data to extract both binary and base64 representations.
+    # @api private
+    def process_image_data(data)
+      is_base64 = base64_string?(data)
+
+      if is_base64
+        # Decode to validate and detect format
+        begin
+          binary_data = decode_base64(data)
+          base64_data = data
+        rescue ArgumentError => e
+          raise ArgumentError, "Invalid base64 image data: #{e.message}"
+        end
+      else
+        # Assume binary data (dup to avoid modifying frozen strings)
+        binary_data = data.dup.force_encoding(Encoding::ASCII_8BIT)
+        base64_data = encode_base64(binary_data)
+      end
+
+      [binary_data, base64_data]
+    end
+
+    # Validates image data and detects MIME type if validation is enabled.
+    # @api private
+    def validate_and_detect_format(binary_data, validate, max_size)
+      if validate
+        validation = validate_image(binary_data, max_size: max_size)
+        raise ArgumentError, "Image validation failed: #{validation[:errors].join(", ")}" unless validation[:valid]
+
+        validation[:mime_type]
+      else
+        detect_image_format(binary_data)
+      end
+    end
+
+    # Determines the final MIME type to use, preferring explicit over detected.
+    # @api private
+    def determine_final_mime_type(explicit_mime_type, detected_mime_type)
+      final_mime_type = explicit_mime_type || detected_mime_type
+      raise ArgumentError, "Could not determine image MIME type" if final_mime_type.nil?
+
+      final_mime_type
+    end
+
+    # Converts file path to MCP-compliant image content.
+    #
+    # @param file_path [String] Path to the image file.
+    # @param validate [Boolean] Whether to validate the image.
+    # @param max_size [Integer] Maximum allowed size for validation.
+    # @return [Hash] MCP image content hash.
+    # @raise [ArgumentError] If file doesn't exist or validation fails.
+    #
+    # @example
+    #   content = VectorMCP::ImageUtil.file_to_mcp_image_content("./avatar.png")
+    def file_to_mcp_image_content(file_path, validate: true, max_size: DEFAULT_MAX_SIZE)
+      raise ArgumentError, "Image file not found: #{file_path}" unless File.exist?(file_path)
+
+      raise ArgumentError, "Image file not readable: #{file_path}" unless File.readable?(file_path)
+
+      binary_data = File.binread(file_path)
+      to_mcp_image_content(binary_data, validate: validate, max_size: max_size)
+    end
+
+    # Extracts image metadata from binary data.
+    #
+    # @param data [String] Binary image data.
+    # @return [Hash] Metadata hash with available information.
+    #
+    # @example
+    #   metadata = VectorMCP::ImageUtil.extract_metadata(image_data)
+    #   # => { mime_type: "image/jpeg", size: 102400, format: "JPEG" }
+    def extract_metadata(data)
+      return {} if data.nil? || data.empty?
+
+      mime_type = detect_image_format(data)
+      metadata = {
+        size: data.bytesize,
+        mime_type: mime_type
+      }
+
+      metadata[:format] = mime_type.split("/").last.upcase if mime_type
+
+      # Add basic dimension detection for common formats
+      metadata.merge!(extract_dimensions(data, mime_type))
+    end
+
+    # Checks if a string appears to be base64 encoded.
+    #
+    # @param string [String] The string to check.
+    # @return [Boolean] True if the string appears to be base64.
+    def base64_string?(string)
+      return false if string.nil? || string.empty?
+
+      # Base64 strings should only contain valid base64 characters
+      # and be properly padded with correct length
+      return false unless string.match?(%r{\A[A-Za-z0-9+/]*={0,2}\z})
+
+      # Allow both padded and unpadded base64, but require proper structure
+      # For unpadded base64, length should be at least 4 and not result in invalid decoding
+      if string.include?("=")
+        # Padded base64 must be multiple of 4
+        (string.length % 4).zero?
+      else
+        # Unpadded base64 - try to decode to see if it's valid
+        return false if string.length < 4
+
+        begin
+          # Add padding and try to decode
+          padded = string + ("=" * (4 - (string.length % 4)) % 4)
+          Base64.strict_decode64(padded)
+          true
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+
+    # Extracts basic image dimensions for common formats.
+    # This is a simplified implementation; for production use,
+    # consider using a proper image library like MiniMagick or ImageMagick.
+    #
+    # @param data [String] Binary image data.
+    # @param mime_type [String] Detected MIME type.
+    # @return [Hash] Hash containing width/height if detectable.
+    def extract_dimensions(data, mime_type)
+      case mime_type
+      when "image/png"
+        extract_png_dimensions(data)
+      when "image/jpeg"
+        extract_jpeg_dimensions(data)
+      when "image/gif"
+        extract_gif_dimensions(data)
+      else
+        {}
+      end
+    rescue StandardError
+      {} # Return empty hash if dimension extraction fails
+    end
+
+    private
+
+    # Extracts PNG dimensions from IHDR chunk.
+    def extract_png_dimensions(data)
+      return {} unless data.length > 24
+
+      # PNG IHDR chunk starts at byte 16 and contains width/height
+      width = data[16, 4].unpack1("N")
+      height = data[20, 4].unpack1("N")
+
+      { width: width, height: height }
+    end
+
+    # Extracts JPEG dimensions from SOF marker.
+    def extract_jpeg_dimensions(data)
+      # Simple JPEG dimension extraction
+      # Look for SOF0 (Start of Frame) marker
+      offset = 2
+      while offset < data.length - 8
+        marker = data[offset, 2].unpack1("n")
+        length = data[offset + 2, 2].unpack1("n")
+
+        # SOF0 marker (0xFFC0)
+        if marker == 0xFFC0
+          height = data[offset + 5, 2].unpack1("n")
+          width = data[offset + 7, 2].unpack1("n")
+          return { width: width, height: height }
+        end
+
+        offset += 2 + length
+      end
+
+      {}
+    end
+
+    # Extracts GIF dimensions from header.
+    def extract_gif_dimensions(data)
+      return {} unless data.length > 10
+
+      # GIF dimensions are at bytes 6-9
+      width = data[6, 2].unpack1("v")  # Little-endian
+      height = data[8, 2].unpack1("v") # Little-endian
+
+      { width: width, height: height }
+    end
+
+    module_function :extract_dimensions, :extract_png_dimensions, :extract_jpeg_dimensions, :extract_gif_dimensions
+  end
+end

data/lib/vector_mcp/sampling/request.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module VectorMCP
+  module Sampling
+    # Represents a sampling request to be sent to an MCP client.
+    # It validates the basic structure of the request.
+    class Request
+      attr_reader :messages, :model_preferences, :system_prompt,
+                  :include_context, :temperature, :max_tokens,
+                  :stop_sequences, :metadata
+
+      # Initializes a new Sampling::Request.
+      #
+      # @param params [Hash] The parameters for the sampling request.
+      #   - :messages [Array<Hash>] (Required) Conversation history. Each message:
+      #     - :role [String] (Required) "user" or "assistant".
+      #     - :content [Hash] (Required) Message content.
+      #       - :type [String] (Required) "text" or "image".
+      #       - :text [String] (Optional) Text content if type is "text".
+      #       - :data [String] (Optional) Base64 image data if type is "image".
+      #       - :mime_type [String] (Optional) Mime type if type is "image".
+      #   - :model_preferences [Hash] (Optional) Model selection preferences.
+      #   - :system_prompt [String] (Optional) System prompt.
+      #   - :include_context [String] (Optional) "none", "thisServer", "allServers".
+      #   - :temperature [Float] (Optional) Sampling temperature.
+      #   - :max_tokens [Integer] (Optional) Maximum tokens to generate.
+      #   - :stop_sequences [Array<String>] (Optional) Stop sequences.
+      #   - :metadata [Hash] (Optional) Provider-specific parameters.
+      # @raise [ArgumentError] if the basic structure is invalid.
+      def initialize(params = {})
+        params = params.transform_keys(&:to_sym) # Normalize keys
+
+        @messages = params[:messages]
+        @model_preferences = params[:model_preferences]
+        @system_prompt = params[:system_prompt]
+        @include_context = params[:include_context]
+        @temperature = params[:temperature]
+        @max_tokens = params[:max_tokens]
+        @stop_sequences = params[:stop_sequences]
+        @metadata = params[:metadata]
+
+        validate!
+      end
+
+      # Returns the request parameters as a hash, suitable for JSON serialization.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          messages: @messages,
+          modelPreferences: @model_preferences, # MCP uses camelCase
+          systemPrompt: @system_prompt,
+          includeContext: @include_context,
+          temperature: @temperature,
+          maxTokens: @max_tokens,
+          stopSequences: @stop_sequences,
+          metadata: @metadata
+        }.compact # Remove nil values
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "'messages' array is required" unless @messages.is_a?(Array) && !@messages.empty?
+
+        @messages.each_with_index do |msg, idx|
+          validate_message(msg, idx)
+        end
+
+        validate_optional_params
+      end
+
+      def validate_message(msg, idx)
+        raise ArgumentError, "Each message in 'messages' must be a Hash (at index #{idx})" unless msg.is_a?(Hash)
+
+        msg_role = extract_message_role(msg)
+        msg_content = extract_message_content(msg)
+
+        validate_message_role(msg_role, idx)
+        validate_message_content_structure(msg_content, idx)
+        validate_content_by_type(msg_content, idx)
+      end
+
+      def extract_message_role(msg)
+        msg[:role] || msg["role"]
+      end
+
+      def extract_message_content(msg)
+        msg[:content] || msg["content"]
+      end
+
+      def validate_message_role(role, idx)
+        raise ArgumentError, "Message role must be 'user' or 'assistant' (at index #{idx})" unless %w[user assistant].include?(role)
+      end
+
+      def validate_message_content_structure(content, idx)
+        raise ArgumentError, "Message content must be a Hash (at index #{idx})" unless content.is_a?(Hash)
+      end
+
+      def validate_content_by_type(content, idx)
+        content_type = content[:type] || content["type"]
+        raise ArgumentError, "Message content type must be 'text' or 'image' (at index #{idx})" unless %w[text image].include?(content_type)
+
+        case content_type
+        when "text"
+          validate_text_content(content, idx)
+        when "image"
+          validate_image_content(content, idx)
+        end
+      end
+
+      def validate_text_content(content, idx)
+        text_value = content[:text] || content["text"]
+        return unless text_value.to_s.empty?
+
+        raise ArgumentError, "Text content must not be empty if type is 'text' (at index #{idx})"
+      end
+
+      def validate_image_content(content, idx)
+        validate_image_data(content, idx)
+        validate_image_mime_type(content, idx)
+      end
+
+      def validate_image_data(content, idx)
+        data_value = content[:data] || content["data"]
+        return if data_value.is_a?(String) && !data_value.empty?
+
+        raise ArgumentError, "Image content 'data' (base64 string) is required if type is 'image' (at index #{idx})"
+      end
+
+      def validate_image_mime_type(content, idx)
+        mime_type_value = content[:mime_type] || content["mime_type"]
+        return if mime_type_value.is_a?(String) && !mime_type_value.empty?
+
+        raise ArgumentError, "Image content 'mime_type' is required if type is 'image' (at index #{idx})"
+      end
+
+      def validate_optional_params
+        validate_model_preferences
+        validate_system_prompt
+        validate_include_context
+        validate_temperature
+        validate_max_tokens
+        validate_stop_sequences
+        validate_metadata
+      end
+
+      def validate_model_preferences
+        return unless @model_preferences && !@model_preferences.is_a?(Hash)
+
+        raise ArgumentError, "'model_preferences' must be a Hash if provided"
+      end
+
+      def validate_system_prompt
+        return unless @system_prompt && !@system_prompt.is_a?(String)
+
+        raise ArgumentError, "'system_prompt' must be a String if provided"
+      end
+
+      def validate_include_context
+        return unless @include_context && !%w[none thisServer allServers].include?(@include_context)
+
+        raise ArgumentError, "'include_context' must be 'none', 'thisServer', or 'allServers' if provided"
+      end
+
+      def validate_temperature
+        return unless @temperature && !@temperature.is_a?(Numeric)
+
+        raise ArgumentError, "'temperature' must be a Numeric if provided"
+      end
+
+      def validate_max_tokens
+        return unless @max_tokens && !@max_tokens.is_a?(Integer)
+
+        raise ArgumentError, "'max_tokens' must be an Integer if provided"
+      end
+
+      def validate_stop_sequences
+        return unless @stop_sequences && !@stop_sequences.is_a?(Array)
+
+        raise ArgumentError, "'stop_sequences' must be an Array if provided"
+      end
+
+      def validate_metadata
+        return unless @metadata && !@metadata.is_a?(Hash)
+
+        raise ArgumentError, "'metadata' must be a Hash if provided"
+      end
+    end
+  end
+end

data/lib/vector_mcp/sampling/result.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Sampling
+    # Represents the result of a sampling request returned by an MCP client.
+    class Result
+      attr_reader :raw_result, :model, :stop_reason, :role, :content
+
+      # Initializes a new Sampling::Result.
+      #
+      # @param result_hash [Hash] The raw hash returned by the client for a sampling request.
+      #   Expected keys (MCP spec uses camelCase, we symbolize and underscore internally):
+      #   - 'model' [String] (Required) Name of the model used.
+      #   - 'stopReason' [String] (Optional) Reason why generation stopped.
+      #   - 'role' [String] (Required) "user" or "assistant".
+      #   - 'content' [Hash] (Required) The generated content.
+      #     - 'type' [String] (Required) "text" or "image".
+      #     - 'text' [String] (Optional) Text content if type is "text".
+      #     - 'data' [String] (Optional) Base64 image data if type is "image".
+      #     - 'mimeType' [String] (Optional) Mime type if type is "image".
+      def initialize(result_hash)
+        @raw_result = result_hash.transform_keys { |k| k.to_s.gsub(/(.)([A-Z])/, '\1_\2').downcase.to_sym }
+
+        @model = @raw_result[:model]
+        @stop_reason = @raw_result[:stop_reason]
+        @role = @raw_result[:role]
+        @content = (@raw_result[:content] || {}).transform_keys(&:to_sym)
+
+        validate!
+      end
+
+      # @return [Boolean] True if the content type is 'text'.
+      def text?
+        @content[:type] == "text"
+      end
+
+      # @return [Boolean] True if the content type is 'image'.
+      def image?
+        @content[:type] == "image"
+      end
+
+      # @return [String, nil] The text content if type is 'text', otherwise nil.
+      def text_content
+        text? ? @content[:text] : nil
+      end
+
+      # @return [String, nil] The base64 encoded image data if type is 'image', otherwise nil.
+      def image_data
+        image? ? @content[:data] : nil
+      end
+
+      # @return [String, nil] The mime type of the image if type is 'image', otherwise nil.
+      def image_mime_type
+        image? ? @content[:mime_type] : nil
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "'model' is required in sampling result" if @model.to_s.empty?
+        raise ArgumentError, "'role' is required in sampling result and must be 'user' or 'assistant'" unless %w[user assistant].include?(@role)
+        raise ArgumentError, "'content' hash is required in sampling result" if @content.empty?
+
+        content_type = @content[:type]
+        raise ArgumentError, "Content 'type' must be 'text' or 'image' in sampling result" unless %w[text image].include?(content_type)
+
+        if content_type == "text" && @content[:text].to_s.empty?
+          # NOTE: Some models might return empty text, so we don't raise an error here but allow nil from text_content
+          # raise ArgumentError, "Content 'text' must not be empty if type is 'text'"
+        end
+
+        return unless content_type == "image"
+        raise ArgumentError, "Content 'data' (base64 string) is required if type is 'image'" if @content[:data].to_s.empty?
+        return unless @content[:mime_type].to_s.empty?
+
+        raise ArgumentError, "Content 'mime_type' is required if type is 'image'"
+      end
+    end
+  end
+end