vector_mcp 0.1.0 → 0.2.0

data/lib/vector_mcp/session.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "sampling/request"
+require_relative "sampling/result"
+require_relative "errors"
+
 module VectorMCP
   # Represents the state of a single client-server connection session in MCP.
   # It tracks initialization status, and negotiated capabilities between the client and server.
@@ -10,21 +14,23 @@ module VectorMCP
   # @attr_reader client_info [Hash, nil] Information about the client, received during initialization.
   # @attr_reader client_capabilities [Hash, nil] Capabilities supported by the client, received during initialization.
   class Session
-    attr_reader :server_info, :server_capabilities, :protocol_version, :client_info, :client_capabilities
+    attr_reader :server_info, :server_capabilities, :protocol_version, :client_info, :client_capabilities, :server, :transport, :id
+    attr_accessor :data # For user-defined session-specific storage
 
     # Initializes a new session.
     #
-    # @param server_info [Hash] Hash containing server information (e.g., name, version).
-    # @param server_capabilities [Hash] Hash describing server capabilities.
-    # @param protocol_version [String] The protocol version the server adheres to.
-    def initialize(server_info:, server_capabilities:, protocol_version:)
-      @server_info = server_info
-      @server_capabilities = server_capabilities
-      @protocol_version = protocol_version
-
-      @initialized = false
+    # @param server [VectorMCP::Server] The server instance managing this session.
+    # @param transport [VectorMCP::Transport::Base, nil] The transport handling this session. Required for sampling.
+    # @param id [String] A unique identifier for this session (e.g., from transport layer).
+    def initialize(server, transport = nil, id: SecureRandom.uuid)
+      @server = server
+      @transport = transport # Store the transport for sending requests
+      @id = id
+      @initialized_state = :pending # :pending, :succeeded, :failed
       @client_info = nil
       @client_capabilities = nil
+      @data = {} # Initialize user data hash
+      @logger = server.logger
     end
 
     # Marks the session as initialized using parameters from the client's `initialize` request.
@@ -33,35 +39,106 @@ module VectorMCP
     #   Expected keys include "protocolVersion", "clientInfo", and "capabilities".
     # @return [Hash] A hash suitable for the server's `initialize` response result.
     def initialize!(params)
-      client_protocol_version = params["protocolVersion"]
+      raise InitializationError, "Session already initialized or initialization attempt in progress." unless @initialized_state == :pending
 
-      if client_protocol_version != @protocol_version
-        # raise VectorMCP::ProtocolError.new("Unsupported protocol version: #{client_protocol_version}", code: -32603)
-        VectorMCP.logger.warn("Client requested protocol version '#{client_protocol_version}', server using '#{@protocol_version}'")
-      end
+      # TODO: More robust validation of params against MCP spec for initialize request
+      params["protocolVersion"]
+      client_capabilities_raw = params["capabilities"]
+      client_info_raw = params["clientInfo"]
+
+      # For now, we mostly care about clientInfo and capabilities for the session object.
+      # Protocol version matching is more of a server/transport concern at a lower level if strict checks are needed.
+      @client_info = client_info_raw.transform_keys(&:to_sym) if client_info_raw.is_a?(Hash)
+      @client_capabilities = client_capabilities_raw.transform_keys(&:to_sym) if client_capabilities_raw.is_a?(Hash)
 
-      @client_info = params["clientInfo"] || {}
-      @client_capabilities = params["capabilities"] || {}
-      @initialized = true
+      @initialized_state = :succeeded
+      @logger.info("[Session #{@id}] Initialized successfully. Client: #{@client_info&.dig(:name)}")
 
-      # Return the initialize result (will be sent by transport)
       {
-        protocolVersion: @protocol_version,
-        serverInfo: @server_info,
-        capabilities: @server_capabilities
+        protocolVersion: @server.protocol_version,
+        serverInfo: @server.server_info,
+        capabilities: @server.server_capabilities
       }
+    rescue StandardError => e
+      @initialized_state = :failed
+      @logger.error("[Session #{@id}] Initialization failed: #{e.message}")
+      # Re-raise as an InitializationError if it's not already one of our ProtocolErrors
+      raise e if e.is_a?(ProtocolError)
+
+      raise InitializationError, "Initialization processing error: #{e.message}", details: { original_error: e.to_s }
     end
 
     # Checks if the session has been successfully initialized.
     #
     # @return [Boolean] True if the session is initialized, false otherwise.
     def initialized?
-      @initialized
+      @initialized_state == :succeeded
     end
 
     # Helper to check client capabilities later if needed
     # def supports?(capability_key)
     #   @client_capabilities.key?(capability_key.to_s)
     # end
+
+    # --- MCP Sampling Method ---
+
+    # Initiates an MCP sampling request to the client associated with this session.
+    # This is a blocking call that waits for the client's response.
+    #
+    # @param request_params [Hash] Parameters for the `sampling/createMessage` request.
+    #   See `VectorMCP::Sampling::Request` for expected structure (e.g., :messages, :max_tokens).
+    # @param timeout [Numeric, nil] Optional timeout in seconds for this specific request.
+    #   Defaults to the transport's default request timeout.
+    # @return [VectorMCP::Sampling::Result] The result of the sampling operation.
+    # @raise [VectorMCP::SamplingError] if the sampling request fails, is rejected, or times out.
+    # @raise [StandardError] if the session's transport does not support `send_request`.
+    def sample(request_params, timeout: nil)
+      validate_sampling_preconditions
+
+      sampling_req_obj = VectorMCP::Sampling::Request.new(request_params)
+      @logger.info("[Session #{@id}] Sending sampling/createMessage request to client.")
+
+      send_sampling_request(sampling_req_obj, timeout)
+    end
+
+    private
+
+    # Validates that sampling can be performed on this session.
+    # @api private
+    # @raise [StandardError, InitializationError] if preconditions are not met.
+    def validate_sampling_preconditions
+      unless @transport.respond_to?(:send_request)
+        raise StandardError, "Session's transport does not support sending requests (required for sampling)."
+      end
+
+      return if initialized?
+
+      @logger.warn("[Session #{@id}] Attempted to send sampling request on a non-initialized session.")
+      raise InitializationError, "Cannot send sampling request: session not initialized."
+    end
+
+    # Sends the sampling request and handles the response.
+    # @api private
+    # @param sampling_req_obj [VectorMCP::Sampling::Request] The sampling request object.
+    # @param timeout [Numeric, nil] Optional timeout for the request.
+    # @return [VectorMCP::Sampling::Result] The sampling result.
+    # @raise [VectorMCP::SamplingError] if the request fails.
+    def send_sampling_request(sampling_req_obj, timeout)
+      send_request_args = ["sampling/createMessage", sampling_req_obj.to_h]
+      send_request_kwargs = {}
+      send_request_kwargs[:timeout] = timeout if timeout
+
+      raw_result = @transport.send_request(*send_request_args, **send_request_kwargs)
+      VectorMCP::Sampling::Result.new(raw_result)
+    rescue ArgumentError => e
+      @logger.error("[Session #{@id}] Invalid parameters for sampling request or result: #{e.message}")
+      raise VectorMCP::SamplingError, "Invalid sampling parameters or malformed client response: #{e.message}", details: { original_error: e.to_s }
+    rescue VectorMCP::SamplingError => e
+      @logger.warn("[Session #{@id}] Sampling request failed: #{e.message}")
+      raise e
+    rescue StandardError => e
+      @logger.error("[Session #{@id}] Unexpected error during sampling: #{e.class.name}: #{e.message}")
+      raise VectorMCP::SamplingError, "An unexpected error occurred during sampling: #{e.message}", details: { original_error: e.to_s }
+    end
   end
 end

data/lib/vector_mcp/transport/stdio.rb

@@ -4,6 +4,8 @@
 require "json"
 require_relative "../errors"
 require_relative "../util"
+require "securerandom" # For generating unique request IDs
+require "timeout"      # For request timeouts
 
 module VectorMCP
   module Transport
@@ -19,6 +21,9 @@ module VectorMCP
       # @return [Logger] The logger instance, shared with the server.
       attr_reader :logger
 
+      # Timeout for waiting for a response to a server-initiated request (in seconds)
+      DEFAULT_REQUEST_TIMEOUT = 30 # Configurable if needed
+
       # Initializes a new Stdio transport.
       #
       # @param server [VectorMCP::Server] The server instance that will handle messages.
@@ -29,6 +34,14 @@ module VectorMCP
         @output_mutex = Mutex.new
         @running = false
         @input_thread = nil
+        @shutdown_requested = false
+        @outgoing_request_responses = {} # To store responses for server-initiated requests
+        @outgoing_request_conditions = {} # ConditionVariables for server-initiated requests
+        @mutex = Mutex.new # To synchronize access to shared response data
+        @request_id_generator = Enumerator.new do |y|
+          i = 0
+          loop { y << "vecmcp_stdio_#{i += 1}_#{SecureRandom.hex(4)}" }
+        end
       end
 
       # Starts the stdio transport, listening for input and processing messages.
@@ -96,6 +109,30 @@ module VectorMCP
         write_message(notification)
       end
 
+      # Sends a server-initiated JSON-RPC request to the client and waits for a response.
+      # This is a blocking call.
+      #
+      # @param method [String] The request method name.
+      # @param params [Hash, Array, nil] The request parameters.
+      # @param timeout [Numeric] How long to wait for a response, in seconds.
+      # @return [Object] The result part of the client's response.
+      # @raise [VectorMCP::SamplingError, VectorMCP::SamplingTimeoutError] if the client returns an error or times out.
+      # @raise [ArgumentError] if method is blank.
+      def send_request(method, params = nil, timeout: DEFAULT_REQUEST_TIMEOUT)
+        raise ArgumentError, "Method cannot be blank" if method.to_s.strip.empty?
+
+        request_id = @request_id_generator.next
+        request_payload = { jsonrpc: "2.0", id: request_id, method: method }
+        request_payload[:params] = params if params
+
+        setup_request_tracking(request_id)
+        logger.debug "[Stdio Transport] Sending request ID #{request_id}: #{method}"
+        write_message(request_payload)
+
+        response = wait_for_response(request_id, method, timeout)
+        process_response(response, request_id, method)
+      end
+
       # Initiates an immediate shutdown of the transport.
       # Sets the running flag to false and attempts to kill the input reading thread.
       #
@@ -112,9 +149,8 @@ module VectorMCP
       # @api private
       # @param session [VectorMCP::Session] The session object for this connection.
       # @return [void]
+      # Constant identifier for stdio sessions
       def read_input_loop(session)
-        session_id = "stdio-session" # Constant identifier for stdio sessions
-
         while @running
           line = read_input_line
           if line.nil?
@@ -123,7 +159,7 @@ module VectorMCP
           end
           next if line.strip.empty?
 
-          handle_input_line(line, session, session_id)
+          handle_input_line(line, session)
         end
       end
 
@@ -141,18 +177,48 @@ module VectorMCP
       # @api private
       # @param line [String] The line of text read from stdin.
       # @param session [VectorMCP::Session] The current session.
-      # @param session_id [String] The identifier for this session.
       # @return [void]
-      def handle_input_line(line, session, session_id)
+      def handle_input_line(line, _session)
         message = parse_json(line)
         return if message.is_a?(Array) && message.empty? # Error handled in parse_json, indicated by empty array
 
-        response_data = server.handle_message(message, session, session_id)
-        send_response(message["id"], response_data) if message["id"] && response_data
-      rescue VectorMCP::ProtocolError => e
-        handle_protocol_error(e, message)
-      rescue StandardError => e
-        handle_unexpected_error(e, message)
+        return handle_outgoing_response(message) if outgoing_response?(message)
+
+        ensure_session_exists
+        handle_server_message(message)
+      end
+
+      # Checks if a message is a response to an outgoing request.
+      # @api private
+      # @param message [Hash] The parsed message.
+      # @return [Boolean] True if this is an outgoing response.
+      def outgoing_response?(message)
+        message["id"] && !message["method"] && (message.key?("result") || message.key?("error"))
+      end
+
+      # Ensures a global session exists for this stdio transport.
+      # @api private
+      # @return [VectorMCP::Session] The current session.
+      def ensure_session_exists
+        @ensure_session_exists ||= VectorMCP::Session.new(@server, self, id: "stdio_global_session")
+      end
+
+      # Handles a server message with proper error handling.
+      # @api private
+      # @param message [Hash] The parsed message.
+      # @return [void]
+      def handle_server_message(message)
+        session = ensure_session_exists
+        session_id = session.id
+
+        begin
+          result = @server.handle_message(message, session, session_id)
+          send_response(message["id"], result) if message["id"] && result
+        rescue VectorMCP::ProtocolError => e
+          handle_protocol_error(e, message)
+        rescue StandardError => e
+          handle_unexpected_error(e, message)
+        end
       end
 
       # --- Run helpers (private) ---
@@ -161,11 +227,7 @@ module VectorMCP
       # @api private
       # @return [VectorMCP::Session] The newly created session.
       def create_session
-        VectorMCP::Session.new(
-          server_info: server.server_info,
-          server_capabilities: server.server_capabilities,
-          protocol_version: server.protocol_version
-        )
+        VectorMCP::Session.new(@server, self)
       end
 
       # Launches the input reading loop in a new thread.
@@ -193,6 +255,30 @@ module VectorMCP
 
       # --- Input helpers (private) ---
 
+      # Handles responses to outgoing requests (like sampling requests).
+      # @api private
+      # @param message [Hash] The parsed response message.
+      # @return [void]
+      def handle_outgoing_response(message)
+        request_id = message["id"]
+        logger.debug "[Stdio Transport] Received response for outgoing request ID #{request_id}"
+
+        @mutex.synchronize do
+          # Store the response (convert keys to symbols for consistency)
+          response_data = deep_transform_keys(message, &:to_sym)
+          @outgoing_request_responses[request_id] = response_data
+
+          # Signal any thread waiting for this response
+          condition = @outgoing_request_conditions[request_id]
+          if condition
+            condition.signal
+            logger.debug "[Stdio Transport] Signaled condition for request ID #{request_id}"
+          else
+            logger.warn "[Stdio Transport] Received response for request ID #{request_id} but no thread is waiting"
+          end
+        end
+      end
+
       # Parses a line of text as JSON.
       # If parsing fails, sends a JSON-RPC ParseError and returns an empty array
       # to signal that the error has been handled.
@@ -234,6 +320,21 @@ module VectorMCP
         send_error(request_id, -32_603, "Internal error", { details: error.message })
       end
 
+      # Recursively transforms hash keys using the given block.
+      # @api private
+      # @param obj [Object] The object to transform (Hash, Array, or other).
+      # @return [Object] The transformed object.
+      def deep_transform_keys(obj, &block)
+        case obj
+        when Hash
+          obj.transform_keys(&block).transform_values { |v| deep_transform_keys(v, &block) }
+        when Array
+          obj.map { |v| deep_transform_keys(v, &block) }
+        else
+          obj
+        end
+      end
+
       # Writes a message hash to `$stdout` as a JSON string, followed by a newline.
       # Ensures the output is flushed. Handles EPIPE errors if stdout closes.
       # @api private
@@ -253,6 +354,63 @@ module VectorMCP
           shutdown # Initiate shutdown as we can no longer communicate
         end
       end
+
+      # Sets up tracking for an outgoing request.
+      # @api private
+      # @param request_id [String] The request ID to track.
+      # @return [void]
+      def setup_request_tracking(request_id)
+        condition = ConditionVariable.new
+        @mutex.synchronize do
+          @outgoing_request_conditions[request_id] = condition
+        end
+      end
+
+      # Waits for a response to an outgoing request.
+      # @api private
+      # @param request_id [String] The request ID to wait for.
+      # @param method [String] The request method name.
+      # @param timeout [Numeric] How long to wait.
+      # @return [Hash] The response data.
+      # @raise [VectorMCP::SamplingTimeoutError] if timeout occurs.
+      def wait_for_response(request_id, method, timeout)
+        condition = @outgoing_request_conditions[request_id]
+
+        @mutex.synchronize do
+          Timeout.timeout(timeout) do
+            condition.wait(@mutex) until @outgoing_request_responses.key?(request_id)
+            @outgoing_request_responses.delete(request_id)
+          end
+        rescue Timeout::Error
+          logger.warn "[Stdio Transport] Timeout waiting for response to request ID #{request_id} (#{method}) after #{timeout}s"
+          @outgoing_request_responses.delete(request_id)
+          @outgoing_request_conditions.delete(request_id)
+          raise VectorMCP::SamplingTimeoutError, "Timeout waiting for client response to '#{method}' request (ID: #{request_id})"
+        ensure
+          @outgoing_request_conditions.delete(request_id)
+        end
+      end
+
+      # Processes the response from an outgoing request.
+      # @api private
+      # @param response [Hash, nil] The response data.
+      # @param request_id [String] The request ID.
+      # @param method [String] The request method name.
+      # @return [Object] The result data.
+      # @raise [VectorMCP::SamplingError] if response contains an error or is nil.
+      def process_response(response, request_id, method)
+        if response.nil?
+          raise VectorMCP::SamplingError, "No response received for '#{method}' request (ID: #{request_id}) - this indicates a logic error."
+        end
+
+        if response.key?(:error)
+          err = response[:error]
+          logger.warn "[Stdio Transport] Client returned error for request ID #{request_id} (#{method}): #{err.inspect}"
+          raise VectorMCP::SamplingError, "Client returned an error for '#{method}' request (ID: #{request_id}): [#{err[:code]}] #{err[:message]}"
+        end
+
+        response[:result]
+      end
     end
   end
 end

data/lib/vector_mcp/util.rb

@@ -14,9 +14,10 @@ module VectorMCP
     # into the wire-format expected by the MCP spec.
     #
     # Keys present in each returned hash:
-    # * **:type**      – Currently always `"text"`; future protocol versions may add rich/binary types.
-    # * **:text**      – UTF-8 encoded payload.
-    # * **:mimeType**  – IANA media-type describing `:text` (`"text/plain"`, `"application/json"`, …).
+    # * **:type**      – `"text"` or `"image"`; automatic detection for binary data.
+    # * **:text**      – UTF-8 encoded payload (for text content).
+    # * **:data**      – Base64 encoded payload (for image content).
+    # * **:mimeType**  – IANA media-type describing the content.
     # * **:uri**       – _Optional._  Added downstream (e.g., by {Handlers::Core.read_resource}).
     #
     # The method **never** returns `nil` and **always** returns at least one element.
@@ -35,6 +36,10 @@ module VectorMCP
     # @example Complex object
     #   VectorMCP::Util.convert_to_mcp_content({foo: 1})
     #   # => [{type: "text", text: "{\"foo\":1}", mimeType: "application/json"}]
+    #
+    # @example Image file path
+    #   VectorMCP::Util.convert_to_mcp_content("image.jpg")
+    #   # => [{type: "image", data: "base64...", mimeType: "image/jpeg"}]
     def convert_to_mcp_content(input, mime_type: "text/plain")
       return string_content(input, mime_type) if input.is_a?(String)
       return hash_content(input)             if input.is_a?(Hash)
@@ -45,11 +50,20 @@ module VectorMCP
 
     # --- Conversion helpers (exposed as module functions) ---
 
-    # Converts a String into an MCP text content item.
+    # Converts a String into an MCP content item.
+    # Intelligently detects if the string is binary image data, a file path to an image,
+    # or regular text content.
     # @param str [String] The string to convert.
     # @param mime_type [String] The MIME type for the content.
-    # @return [Array<Hash>] MCP content array with one text item.
+    # @return [Array<Hash>] MCP content array with one item.
     def string_content(str, mime_type)
+      # Check if this might be a file path to an image
+      return file_path_to_image_content(str) if looks_like_image_file_path?(str)
+
+      # Check if this is binary image data
+      return binary_image_to_content(str) if binary_image_data?(str)
+
+      # Default to text content
       [{ type: "text", text: str, mimeType: mime_type }]
     end
 
@@ -60,7 +74,12 @@ module VectorMCP
     # @return [Array<Hash>] MCP content array.
     def hash_content(hash)
       if hash[:type] || hash["type"] # Already in content format
-        [hash.transform_keys(&:to_sym)]
+        normalized = hash.transform_keys(&:to_sym)
+
+        # Validate and enhance image content if needed
+        return [validate_and_enhance_image_content(normalized)] if normalized[:type] == "image"
+
+        [normalized]
       else
         [{ type: "text", text: hash.to_json, mimeType: "application/json" }]
       end
@@ -73,14 +92,30 @@ module VectorMCP
     # @param mime_type [String] The default MIME type for child items if they need conversion.
     # @return [Array<Hash>] MCP content array.
     def array_content(arr, mime_type)
-      if arr.all? { |item| item.is_a?(Hash) && (item[:type] || item["type"]) }
-        arr.map { |item| item.transform_keys(&:to_sym) }
+      if all_content_items?(arr)
+        arr.map { |item| process_content_item(item) }
       else
-        # Recursively convert each item, preserving the original mime_type intent for non-structured children.
         arr.flat_map { |item| convert_to_mcp_content(item, mime_type: mime_type) }
       end
     end
 
+    # Checks if all array items are pre-formatted MCP content items.
+    # @param arr [Array] The array to check.
+    # @return [Boolean] True if all items have type fields.
+    def all_content_items?(arr)
+      arr.all? { |item| item.is_a?(Hash) && (item[:type] || item["type"]) }
+    end
+
+    # Processes a single content item, normalizing and validating as needed.
+    # @param item [Hash] The content item to process.
+    # @return [Hash] The processed content item.
+    def process_content_item(item)
+      normalized = item.transform_keys(&:to_sym)
+      return validate_and_enhance_image_content(normalized) if normalized[:type] == "image"
+
+      normalized
+    end
+
     # Fallback conversion for any other object type to an MCP text content item.
     # Converts the object to its string representation.
     # @param obj [Object] The object to convert.
@@ -90,7 +125,8 @@ module VectorMCP
       [{ type: "text", text: obj.to_s, mimeType: mime_type }]
     end
 
-    module_function :string_content, :hash_content, :array_content, :fallback_content
+    module_function :string_content, :hash_content, :array_content, :fallback_content,
+                    :all_content_items?, :process_content_item
 
     # Extracts an ID from a potentially malformed JSON string using regex.
     # This is a best-effort attempt, primarily for error reporting when full JSON parsing fails.
@@ -109,5 +145,94 @@ module VectorMCP
 
       nil
     end
+
+    private
+
+    # Checks if a string looks like a file path to an image.
+    # @param str [String] The string to check.
+    # @return [Boolean] True if it looks like an image file path.
+    def looks_like_image_file_path?(str)
+      return false if str.nil? || str.empty? || str.length > 500
+
+      # Check for common image extensions
+      image_extensions = %w[.jpg .jpeg .png .gif .webp .bmp .tiff .tif .svg]
+      has_image_extension = image_extensions.any? { |ext| str.downcase.end_with?(ext) }
+
+      # Check if it looks like a file path (contains / or \ or ends with image extension)
+      looks_like_path = str.include?("/") || str.include?("\\") || has_image_extension
+
+      has_image_extension && looks_like_path
+    end
+
+    # Checks if a string contains binary image data.
+    # @param str [String] The string to check.
+    # @return [Boolean] True if it appears to be binary image data.
+    def binary_image_data?(str)
+      return false if str.nil? || str.empty?
+
+      # Check encoding first
+      encoding = str.encoding
+      is_binary = encoding == Encoding::ASCII_8BIT || !str.valid_encoding?
+
+      return false unless is_binary
+
+      # Use ImageUtil to detect if it's actually image data
+      require_relative "image_util"
+      !VectorMCP::ImageUtil.detect_image_format(str).nil?
+    rescue StandardError
+      false
+    end
+
+    # Converts a file path string to image content.
+    # @param file_path [String] Path to the image file.
+    # @return [Array<Hash>] MCP content array with image content.
+    def file_path_to_image_content(file_path)
+      require_relative "image_util"
+
+      begin
+        image_content = VectorMCP::ImageUtil.file_to_mcp_image_content(file_path)
+        [image_content]
+      rescue ArgumentError => e
+        # If image processing fails, fall back to text content with error message
+        [{ type: "text", text: "Error loading image '#{file_path}': #{e.message}", mimeType: "text/plain" }]
+      end
+    end
+
+    # Converts binary image data to MCP image content.
+    # @param binary_data [String] Binary image data.
+    # @return [Array<Hash>] MCP content array with image content.
+    def binary_image_to_content(binary_data)
+      require_relative "image_util"
+
+      begin
+        image_content = VectorMCP::ImageUtil.to_mcp_image_content(binary_data)
+        [image_content]
+      rescue ArgumentError
+        # If image processing fails, fall back to text content
+        [{ type: "text", text: binary_data.to_s, mimeType: "application/octet-stream" }]
+      end
+    end
+
+    # Validates and enhances existing image content hash.
+    # @param content [Hash] Existing image content hash.
+    # @return [Hash] Validated and enhanced image content.
+    def validate_and_enhance_image_content(content)
+      # Ensure required fields are present
+      raise ArgumentError, "Image content must have both :data and :mimeType fields" unless content[:data] && content[:mimeType]
+
+      # Validate the base64 data if possible
+      begin
+        require_relative "image_util"
+        VectorMCP::ImageUtil.decode_base64(content[:data])
+      rescue ArgumentError => e
+        raise ArgumentError, "Invalid base64 image data: #{e.message}"
+      end
+
+      content
+    end
+
+    module_function :looks_like_image_file_path?, :binary_image_data?,
+                    :file_path_to_image_content, :binary_image_to_content,
+                    :validate_and_enhance_image_content
   end
 end

data/lib/vector_mcp/version.rb

@@ -2,5 +2,5 @@
 
 module VectorMCP
   # The current version of the VectorMCP gem.
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/vector_mcp.rb

@@ -8,9 +8,10 @@ require_relative "vector_mcp/errors"
 require_relative "vector_mcp/definitions"
 require_relative "vector_mcp/session"
 require_relative "vector_mcp/util"
+require_relative "vector_mcp/image_util"
 require_relative "vector_mcp/handlers/core"
 require_relative "vector_mcp/transport/stdio"
-require_relative "vector_mcp/transport/sse"
+# require_relative "vector_mcp/transport/sse" # Load on demand to avoid async dependencies
 require_relative "vector_mcp/server"
 
 # The VectorMCP module provides a full-featured, opinionated Ruby implementation