vector_mcp 0.1.0 → 0.2.0

data/lib/vector_mcp/definitions.rb

@@ -28,6 +28,51 @@ module VectorMCP
           inputSchema: input_schema # Expected to be a Hash representing JSON Schema
         }.compact # Remove nil values
       end
+
+      # Checks if this tool supports image inputs based on its input schema.
+      # @return [Boolean] True if the tool's input schema includes image properties.
+      def supports_image_input?
+        return false unless input_schema.is_a?(Hash)
+
+        properties = extract_schema_properties
+        properties.any? { |_prop, schema| image_property?(schema) }
+      end
+
+      private
+
+      # Extracts properties from the input schema, handling both string and symbol keys.
+      def extract_schema_properties
+        input_schema["properties"] || input_schema[:properties] || {}
+      end
+
+      # Checks if a property schema represents an image input.
+      def image_property?(schema)
+        return false unless schema.is_a?(Hash)
+
+        explicit_image_format?(schema) || base64_image_content?(schema)
+      end
+
+      # Checks if the schema explicitly declares image format.
+      def explicit_image_format?(schema)
+        schema["format"] == "image" || schema[:format] == "image"
+      end
+
+      # Checks if the schema represents base64-encoded image content.
+      def base64_image_content?(schema)
+        string_type_with_base64_encoding?(schema) && image_media_type?(schema)
+      end
+
+      # Checks if the schema is a string type with base64 encoding.
+      def string_type_with_base64_encoding?(schema)
+        (schema["type"] == "string" && schema["contentEncoding"] == "base64") ||
+          (schema[:type] == "string" && schema[:contentEncoding] == "base64")
+      end
+
+      # Checks if the schema has an image media type.
+      def image_media_type?(schema)
+        schema["contentMediaType"]&.start_with?("image/") ||
+          schema[:contentMediaType]&.start_with?("image/")
+      end
     end
 
     # Represents a resource (context or data) that can be provided to the AI model or user.
@@ -39,7 +84,7 @@ module VectorMCP
     # @!attribute description [rw] String
     #   A description of the resource content.
     # @!attribute mime_type [rw] String
-    #   The MIME type of the resource content (e.g., "text/plain", "application/json").
+    #   The MIME type of the resource content (e.g., "text/plain", "application/json", "image/jpeg").
     # @!attribute handler [rw] Proc
     #   A callable that returns the content of the resource. It may receive parameters from the request (e.g., for dynamic resources).
     Resource = Struct.new(:uri, :name, :description, :mime_type, :handler) do
@@ -53,6 +98,64 @@ module VectorMCP
           mimeType: mime_type
         }.compact
       end
+
+      # Checks if this resource represents an image.
+      # @return [Boolean] True if the resource's MIME type indicates an image.
+      def image_resource?
+        !!mime_type&.start_with?("image/")
+      end
+
+      # Class method to create an image resource from a file path.
+      # @param uri [String] The URI for the resource.
+      # @param file_path [String] Path to the image file.
+      # @param name [String] Human-readable name for the resource.
+      # @param description [String] Description of the resource.
+      # @return [Resource] A new Resource instance configured for the image file.
+      def self.from_image_file(uri:, file_path:, name: nil, description: nil)
+        raise ArgumentError, "Image file not found: #{file_path}" unless File.exist?(file_path)
+
+        # Auto-detect MIME type
+        require_relative "image_util"
+        image_data = File.binread(file_path)
+        detected_mime_type = VectorMCP::ImageUtil.detect_image_format(image_data)
+
+        raise ArgumentError, "Could not detect image format for file: #{file_path}" unless detected_mime_type
+
+        # Generate name and description if not provided
+        default_name = name || File.basename(file_path)
+        default_description = description || "Image file: #{file_path}"
+
+        handler = lambda do |_params|
+          VectorMCP::ImageUtil.file_to_mcp_image_content(file_path)
+        end
+
+        new(uri, default_name, default_description, detected_mime_type, handler)
+      end
+
+      # Class method to create an image resource from binary data.
+      # @param uri [String] The URI for the resource.
+      # @param image_data [String] Binary image data.
+      # @param name [String] Human-readable name for the resource.
+      # @param description [String] Description of the resource.
+      # @param mime_type [String, nil] MIME type (auto-detected if nil).
+      # @return [Resource] A new Resource instance configured for the image data.
+      def self.from_image_data(uri:, image_data:, name:, description: nil, mime_type: nil)
+        require_relative "image_util"
+
+        # Detect or validate MIME type
+        detected_mime_type = VectorMCP::ImageUtil.detect_image_format(image_data)
+        final_mime_type = mime_type || detected_mime_type
+
+        raise ArgumentError, "Could not determine MIME type for image data" unless final_mime_type
+
+        default_description = description || "Image resource: #{name}"
+
+        handler = lambda do |_params|
+          VectorMCP::ImageUtil.to_mcp_image_content(image_data, mime_type: final_mime_type)
+        end
+
+        new(uri, name, default_description, final_mime_type, handler)
+      end
     end
 
     # Represents a prompt or templated message workflow for users or AI models.
@@ -76,6 +179,112 @@ module VectorMCP
           arguments: arguments # Expected to be an array of { name:, description:, required: } hashes
         }.compact
       end
+
+      # Checks if this prompt supports image arguments.
+      # @return [Boolean] True if any of the prompt arguments are configured for images.
+      def supports_image_arguments?
+        return false unless arguments.is_a?(Array)
+
+        arguments.any? do |arg|
+          arg.is_a?(Hash) && (
+            arg["type"] == "image" ||
+            arg[:type] == "image" ||
+            (arg["description"] || arg[:description])&.downcase&.include?("image")
+          )
+        end
+      end
+
+      # Class method to create an image-enabled prompt with common image argument patterns.
+      # @param name [String] The unique name of the prompt.
+      # @param description [String] A human-readable description.
+      # @param image_argument_name [String] Name of the image argument (default: "image").
+      # @param additional_arguments [Array<Hash>] Additional prompt arguments.
+      # @param handler [Proc] The prompt handler.
+      # @return [Prompt] A new Prompt instance configured for image input.
+      def self.with_image_support(name:, description:, image_argument_name: "image", additional_arguments: [], &handler)
+        image_arg = {
+          name: image_argument_name,
+          description: "Image file path or image data to include in the prompt",
+          required: false,
+          type: "image"
+        }
+
+        all_arguments = [image_arg] + additional_arguments
+
+        new(name, description, all_arguments, handler)
+      end
+    end
+
+    # Represents an MCP root definition.
+    # Roots define filesystem boundaries where servers can operate.
+    Root = Struct.new(:uri, :name) do
+      # Converts the root to its MCP definition hash.
+      # @return [Hash] A hash representing the root in MCP format.
+      def as_mcp_definition
+        {
+          uri: uri.to_s,
+          name: name
+        }.compact
+      end
+
+      # Validates that the root URI is properly formatted and secure.
+      # @return [Boolean] True if the root is valid.
+      # @raise [ArgumentError] If the root is invalid.
+      def validate!
+        # Validate URI format
+        parsed_uri = begin
+          URI(uri.to_s)
+        rescue URI::InvalidURIError
+          raise ArgumentError, "Invalid URI format: #{uri}"
+        end
+
+        # Currently, only file:// scheme is supported per MCP spec
+        raise ArgumentError, "Only file:// URIs are supported for roots, got: #{parsed_uri.scheme}://" unless parsed_uri.scheme == "file"
+
+        # Validate path exists and is a directory
+        path = parsed_uri.path
+        raise ArgumentError, "Root directory does not exist: #{path}" unless File.exist?(path)
+
+        raise ArgumentError, "Root path is not a directory: #{path}" unless File.directory?(path)
+
+        # Security check: ensure we can read the directory
+        raise ArgumentError, "Root directory is not readable: #{path}" unless File.readable?(path)
+
+        # Validate against path traversal attempts in the URI itself
+        raise ArgumentError, "Root path contains unsafe traversal patterns: #{path}" if path.include?("..") || path.include?("./")
+
+        true
+      end
+
+      # Class method to create a root from a local directory path.
+      # @param path [String] Local filesystem path to the directory.
+      # @param name [String] Human-readable name for the root.
+      # @return [Root] A new Root instance.
+      # @raise [ArgumentError] If the path is invalid or not accessible.
+      def self.from_path(path, name: nil)
+        # Expand path to get absolute path and resolve any relative components
+        expanded_path = File.expand_path(path)
+
+        # Create file:// URI
+        uri = "file://#{expanded_path}"
+
+        # Generate name if not provided
+        default_name = name || File.basename(expanded_path)
+
+        root = new(uri, default_name)
+        root.validate! # Ensure the root is valid
+        root
+      end
+
+      # Returns the filesystem path for file:// URIs.
+      # @return [String] The filesystem path.
+      # @raise [ArgumentError] If the URI is not a file:// scheme.
+      def path
+        parsed_uri = URI(uri.to_s)
+        raise ArgumentError, "Cannot get path for non-file URI: #{uri}" unless parsed_uri.scheme == "file"
+
+        parsed_uri.path
+      end
     end
   end
 end

data/lib/vector_mcp/errors.rb

@@ -135,4 +135,43 @@ module VectorMCP
       super(message, code: -32_001, details: details, request_id: request_id)
     end
   end
+
+  # --- Sampling Specific Errors ---
+  # These are errors that can occur when a server initiates a `sampling/createMessage` request.
+
+  # Base class for sampling-related errors originating from client or transport during a server-initiated sample request.
+  class SamplingError < ProtocolError
+    # @param message [String] The error message.
+    # @param code [Integer] JSON-RPC error code (typically from client response, or server defined for timeouts etc).
+    # @param details [Object, nil] Optional additional error data from client or transport.
+    # @param request_id [String, Integer, nil] The ID of the `sampling/createMessage` request.
+    def initialize(message = "An error occurred during sampling.", code: -32_050, details: nil, request_id: nil)
+      # Using -32050 as a generic base for sampling errors from server's perspective.
+      # Specific errors from client might have different codes.
+      super
+    end
+  end
+
+  # Raised when a server-initiated sampling request times out waiting for a client response.
+  class SamplingTimeoutError < SamplingError
+    def initialize(message = "Timeout waiting for client response to sampling request.", details: nil, request_id: nil)
+      super(message, code: -32_051, details: details, request_id: request_id) # Server-defined code for this timeout
+    end
+  end
+
+  # Raised if the client explicitly rejects or denies the sampling request (e.g., user vetoed).
+  # This would typically correspond to a specific error response from the client.
+  class SamplingRejectedError < SamplingError
+    def initialize(message = "Client rejected the sampling request.", code: -32_052, details: nil, request_id: nil)
+      # This code might be overridden by the actual error code from the client if available.
+      super
+    end
+  end
+
+  # Placeholder for other specific sampling errors that might be defined based on client responses.
+  # class SpecificSamplingClientError < SamplingError
+  #   def initialize(message, client_code:, client_details:, request_id: nil)
+  #     super(message, code: client_code, details: client_details, request_id: request_id)
+  #   end
+  # end
 end

data/lib/vector_mcp/handlers/core.rb

@@ -115,6 +115,23 @@ module VectorMCP
         result
       end
 
+      # Handles the `roots/list` request.
+      # Returns the list of available roots and clears the `listChanged` flag.
+      #
+      # @param _params [Hash] The request parameters (ignored).
+      # @param _session [VectorMCP::Session] The current session (ignored).
+      # @param server [VectorMCP::Server] The server instance.
+      # @return [Hash] A hash containing an array of root definitions.
+      #   Example: `{ roots: [ { uri: "file:///path/to/dir", name: "My Project" } ] }`
+      def self.list_roots(_params, _session, server)
+        # Once the list is supplied, clear the listChanged flag
+        result = {
+          roots: server.roots.values.map(&:as_mcp_definition)
+        }
+        server.clear_roots_list_changed if server.respond_to?(:clear_roots_list_changed)
+        result
+      end
+
       # Handles the `prompts/subscribe` request (placeholder).
       # This implementation is a simple acknowledgement.
       #

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