vector_mcp 0.1.0 → 0.3.0

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.3.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vector_mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sergio Bayona
@@ -10,75 +10,75 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: async
+  name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.23.0
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.23.0
+        version: '0.2'
 - !ruby/object:Gem::Dependency
-  name: async-container
+  name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '3.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '3.1'
 - !ruby/object:Gem::Dependency
-  name: async-http
+  name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.61'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.61'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
-  name: async-io
+  name: json-schema
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.36'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.36'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: falcon
+  name: puma
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.42'
+        version: '6.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.42'
+        version: '6.4'
 description: Server-side tools for implementing the Model Context Protocol in Ruby
   applications
 email:
@@ -97,9 +97,19 @@ files:
 - lib/vector_mcp/definitions.rb
 - lib/vector_mcp/errors.rb
 - lib/vector_mcp/handlers/core.rb
+- lib/vector_mcp/image_util.rb
+- lib/vector_mcp/sampling/request.rb
+- lib/vector_mcp/sampling/result.rb
 - lib/vector_mcp/server.rb
+- lib/vector_mcp/server/capabilities.rb
+- lib/vector_mcp/server/message_handling.rb
+- lib/vector_mcp/server/registry.rb
 - lib/vector_mcp/session.rb
 - lib/vector_mcp/transport/sse.rb
+- lib/vector_mcp/transport/sse/client_connection.rb
+- lib/vector_mcp/transport/sse/message_handler.rb
+- lib/vector_mcp/transport/sse/puma_config.rb
+- lib/vector_mcp/transport/sse/stream_manager.rb
 - lib/vector_mcp/transport/stdio.rb
 - lib/vector_mcp/util.rb
 - lib/vector_mcp/version.rb