vector_mcp 0.1.0 → 0.2.0

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

data/lib/vector_mcp/server/capabilities.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  class Server
+    # Handles server capabilities and configuration
+    module Capabilities
+      # --- Server Information and Capabilities ---
+
+      # Provides basic information about the server.
+      # @return [Hash] Server name and version.
+      def server_info
+        { name: @name, version: @version }
+      end
+
+      # Returns the sampling configuration for this server.
+      # @return [Hash] The sampling configuration including capabilities and limits.
+      def sampling_config
+        @sampling_config[:config]
+      end
+
+      # Describes the capabilities of this server according to MCP specifications.
+      # @return [Hash] A capabilities object.
+      def server_capabilities
+        caps = {}
+        caps[:tools] = { listChanged: false } unless @tools.empty?
+        caps[:resources] = { subscribe: false, listChanged: false } unless @resources.empty?
+        caps[:prompts] = { listChanged: @prompts_list_changed } unless @prompts.empty?
+        caps[:roots] = { listChanged: true } unless @roots.empty?
+        caps[:sampling] = @sampling_config[:capabilities]
+        caps
+      end
+
+      # Resets the `prompts_list_changed` flag to false.
+      # @return [void]
+      def clear_prompts_list_changed
+        @prompts_list_changed = false
+        logger.debug("Prompts listChanged flag cleared.")
+      end
+
+      # Notifies connected clients that the list of available prompts has changed.
+      # @return [void]
+      def notify_prompts_list_changed
+        return unless transport && @prompts_list_changed
+
+        notification_method = "notifications/prompts/list_changed"
+        begin
+          if transport.respond_to?(:broadcast_notification)
+            logger.info("Broadcasting prompts list changed notification.")
+            transport.broadcast_notification(notification_method)
+          elsif transport.respond_to?(:send_notification)
+            logger.info("Sending prompts list changed notification (transport may broadcast or send to first client).")
+            transport.send_notification(notification_method)
+          else
+            logger.warn("Transport does not support sending notifications/prompts/list_changed.")
+          end
+        rescue StandardError => e
+          logger.error("Failed to send prompts list changed notification: #{e.class.name}: #{e.message}")
+        end
+      end
+
+      # Resets the `roots_list_changed` flag to false.
+      # @return [void]
+      def clear_roots_list_changed
+        @roots_list_changed = false
+        logger.debug("Roots listChanged flag cleared.")
+      end
+
+      # Notifies connected clients that the list of available roots has changed.
+      # @return [void]
+      def notify_roots_list_changed
+        return unless transport && @roots_list_changed
+
+        notification_method = "notifications/roots/list_changed"
+        begin
+          if transport.respond_to?(:broadcast_notification)
+            logger.info("Broadcasting roots list changed notification.")
+            transport.broadcast_notification(notification_method)
+          elsif transport.respond_to?(:send_notification)
+            logger.info("Sending roots list changed notification (transport may broadcast or send to first client).")
+            transport.send_notification(notification_method)
+          else
+            logger.warn("Transport does not support sending notifications/roots/list_changed.")
+          end
+        rescue StandardError => e
+          logger.error("Failed to send roots list changed notification: #{e.class.name}: #{e.message}")
+        end
+      end
+
+      # Registers a session as a subscriber to prompt list changes.
+      # @api private
+      def subscribe_prompts(session)
+        @prompt_subscribers << session unless @prompt_subscribers.include?(session)
+        logger.debug("Session subscribed to prompt list changes: #{session.object_id}")
+      end
+
+      private
+
+      # Configures sampling capabilities based on provided configuration.
+      # @api private
+      def configure_sampling_capabilities(config)
+        defaults = {
+          enabled: true,
+          methods: ["createMessage"],
+          supports_streaming: false,
+          supports_tool_calls: false,
+          supports_images: false,
+          max_tokens_limit: nil,
+          timeout_seconds: 30,
+          context_inclusion_methods: %w[none thisServer],
+          model_preferences_supported: true
+        }
+
+        resolved_config = defaults.merge(config.transform_keys(&:to_sym))
+        capabilities = build_sampling_capabilities_object(resolved_config)
+
+        {
+          config: resolved_config,
+          capabilities: capabilities
+        }
+      end
+
+      # Builds the complete sampling capabilities object.
+      # @api private
+      def build_sampling_capabilities_object(config)
+        return {} unless config[:enabled]
+
+        {
+          methods: config[:methods],
+          features: build_sampling_features(config),
+          limits: build_sampling_limits(config),
+          contextInclusion: config[:context_inclusion_methods]
+        }
+      end
+
+      # Builds the features section of sampling capabilities.
+      # @api private
+      def build_sampling_features(config)
+        features = {}
+        features[:streaming] = true if config[:supports_streaming]
+        features[:toolCalls] = true if config[:supports_tool_calls]
+        features[:images] = true if config[:supports_images]
+        features[:modelPreferences] = true if config[:model_preferences_supported]
+        features
+      end
+
+      # Builds the limits section of sampling capabilities.
+      # @api private
+      def build_sampling_limits(config)
+        limits = {}
+        limits[:maxTokens] = config[:max_tokens_limit] if config[:max_tokens_limit]
+        limits[:defaultTimeout] = config[:timeout_seconds] if config[:timeout_seconds]
+        limits
+      end
+    end
+  end
+end

data/lib/vector_mcp/server/message_handling.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  class Server
+    # Handles message processing and request/notification dispatching
+    module MessageHandling
+      # --- Message Handling Logic (primarily called by transports) ---
+
+      # Handles an incoming JSON-RPC message (request or notification).
+      # This is the main dispatch point for messages received by a transport.
+      #
+      # @param message [Hash] The parsed JSON-RPC message object.
+      # @param session [VectorMCP::Session] The client session associated with this message.
+      # @param session_id [String] A unique identifier for the underlying transport connection.
+      # @return [Object, nil] For requests, returns the result data to be sent in the JSON-RPC response.
+      #   For notifications, returns `nil`.
+      # @raise [VectorMCP::ProtocolError] if the message is invalid or an error occurs during handling.
+      def handle_message(message, session, session_id)
+        id = message["id"]
+        method = message["method"]
+        params = message["params"] || {}
+
+        if id && method # Request
+          logger.info("[#{session_id}] Request [#{id}]: #{method} with params: #{params.inspect}")
+          handle_request(id, method, params, session)
+        elsif method # Notification
+          logger.info("[#{session_id}] Notification: #{method} with params: #{params.inspect}")
+          handle_notification(method, params, session)
+          nil # Notifications do not have a return value to send back to client
+        elsif id # Invalid: Has ID but no method
+          logger.warn("[#{session_id}] Invalid message: Has ID [#{id}] but no method. #{message.inspect}")
+          raise VectorMCP::InvalidRequestError.new("Request object must include a 'method' member.", request_id: id)
+        else # Invalid: No ID and no method
+          logger.warn("[#{session_id}] Invalid message: Missing both 'id' and 'method'. #{message.inspect}")
+          raise VectorMCP::InvalidRequestError.new("Invalid message format", request_id: nil)
+        end
+      end
+
+      # --- Request/Notification Hook Methods ---
+
+      # Registers a handler for a specific JSON-RPC request method.
+      #
+      # @param method [String, Symbol] The method name (e.g., "my/customMethod").
+      # @yield [params, session, server] A block to handle the request.
+      # @return [self] The server instance.
+      def on_request(method, &handler)
+        @request_handlers[method.to_s] = handler
+        self
+      end
+
+      # Registers a handler for a specific JSON-RPC notification method.
+      #
+      # @param method [String, Symbol] The method name (e.g., "my/customNotification").
+      # @yield [params, session, server] A block to handle the notification.
+      # @return [self] The server instance.
+      def on_notification(method, &handler)
+        @notification_handlers[method.to_s] = handler
+        self
+      end
+
+      private
+
+      # Internal handler for JSON-RPC requests.
+      # @api private
+      def handle_request(id, method, params, session)
+        validate_session_initialization(id, method, params, session)
+
+        handler = @request_handlers[method]
+        raise VectorMCP::MethodNotFoundError.new(method, request_id: id) unless handler
+
+        execute_request_handler(id, method, params, session, handler)
+      end
+
+      # Validates that the session is properly initialized for the given request.
+      # @api private
+      def validate_session_initialization(id, method, _params, session)
+        return if session.initialized?
+
+        # Allow "initialize" even if not marked initialized yet by server
+        return if method == "initialize"
+
+        # For any other method, session must be initialized
+        raise VectorMCP::InitializationError.new("Session not initialized. Client must send 'initialize' first.", request_id: id)
+      end
+
+      # Executes the request handler with proper error handling and tracking.
+      # @api private
+      def execute_request_handler(id, method, params, session, handler)
+        @in_flight_requests[id] = { method: method, params: params, session: session, start_time: Time.now }
+        result = handler.call(params, session, self)
+        result
+      rescue VectorMCP::ProtocolError => e
+        # Ensure the request ID from the current context is on the error
+        e.request_id = id unless e.request_id && e.request_id == id
+        raise e # Re-raise with potentially updated request_id
+      rescue StandardError => e
+        handle_request_error(id, method, e)
+      ensure
+        @in_flight_requests.delete(id)
+      end
+
+      # Handles unexpected errors during request processing.
+      # @api private
+      def handle_request_error(id, method, error)
+        logger.error("Unhandled error during request '#{method}' (ID: #{id}): #{error.message}\nBacktrace: #{error.backtrace.join("\n  ")}")
+        raise VectorMCP::InternalError.new(
+          "Request handler failed unexpectedly",
+          request_id: id,
+          details: { method: method, error: "An internal error occurred" }
+        )
+      end
+
+      # Internal handler for JSON-RPC notifications.
+      # @api private
+      def handle_notification(method, params, session)
+        unless session.initialized? || method == "initialized"
+          logger.warn("Ignoring notification '#{method}' before session is initialized. Params: #{params.inspect}")
+          return
+        end
+
+        handler = @notification_handlers[method]
+        if handler
+          begin
+            handler.call(params, session, self)
+          rescue StandardError => e
+            logger.error("Error executing notification handler '#{method}': #{e.message}\nBacktrace (top 5):\n  #{e.backtrace.first(5).join("\n  ")}")
+            # Notifications must not generate a response, even on error.
+          end
+        else
+          logger.debug("No handler registered for notification: #{method}")
+        end
+      end
+
+      # Sets up default handlers for core MCP methods using {VectorMCP::Handlers::Core}.
+      # @api private
+      def setup_default_handlers
+        # Core Requests
+        on_request("initialize", &session_method(:initialize!))
+        on_request("ping", &Handlers::Core.method(:ping))
+        on_request("tools/list", &Handlers::Core.method(:list_tools))
+        on_request("tools/call", &Handlers::Core.method(:call_tool))
+        on_request("resources/list", &Handlers::Core.method(:list_resources))
+        on_request("resources/read", &Handlers::Core.method(:read_resource))
+        on_request("prompts/list", &Handlers::Core.method(:list_prompts))
+        on_request("prompts/get", &Handlers::Core.method(:get_prompt))
+        on_request("prompts/subscribe", &Handlers::Core.method(:subscribe_prompts))
+        on_request("roots/list", &Handlers::Core.method(:list_roots))
+
+        # Core Notifications
+        on_notification("initialized", &Handlers::Core.method(:initialized_notification))
+        # Standard cancel request names
+        %w[$/cancelRequest $/cancel notifications/cancelled].each do |cancel_method|
+          on_notification(cancel_method, &Handlers::Core.method(:cancel_request_notification))
+        end
+      end
+
+      # Helper to create a proc that calls a method on the session object.
+      # @api private
+      def session_method(method_name)
+        lambda do |params, session, _server|
+          session.public_send(method_name, params)
+        end
+      end
+    end
+  end
+end