vector_mcp 0.1.0 → 0.3.0

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

data/lib/vector_mcp/server/registry.rb

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require "json-schema"
+
+module VectorMCP
+  class Server
+    # Handles registration of tools, resources, prompts, and roots
+    module Registry
+      # --- Registration Methods ---
+
+      # Registers a new tool with the server.
+      #
+      # @param name [String, Symbol] The unique name for the tool.
+      # @param description [String] A human-readable description of the tool.
+      # @param input_schema [Hash] A JSON Schema object that precisely describes the
+      #   structure of the argument hash your tool expects.
+      # @yield [Hash] A block implementing the tool logic.
+      # @return [self] Returns the server instance so you can chain registrations.
+      # @raise [ArgumentError] If another tool with the same name is already registered.
+      def register_tool(name:, description:, input_schema:, &handler)
+        name_s = name.to_s
+        raise ArgumentError, "Tool '#{name_s}' already registered" if @tools[name_s]
+
+        # Validate schema format during registration
+        validate_schema_format!(input_schema) if input_schema
+
+        @tools[name_s] = VectorMCP::Definitions::Tool.new(name_s, description, input_schema, handler)
+        logger.debug("Registered tool: #{name_s}")
+        self
+      end
+
+      # Registers a new resource with the server.
+      #
+      # @param uri [String, URI] The unique URI for the resource.
+      # @param name [String] A human-readable name for the resource.
+      # @param description [String] A description of the resource.
+      # @param mime_type [String] The MIME type of the resource's content (default: "text/plain").
+      # @yield [Hash] A block that provides the resource's content.
+      # @return [self] The server instance, for chaining.
+      # @raise [ArgumentError] if a resource with the same URI is already registered.
+      def register_resource(uri:, name:, description:, mime_type: "text/plain", &handler)
+        uri_s = uri.to_s
+        raise ArgumentError, "Resource '#{uri_s}' already registered" if @resources[uri_s]
+
+        @resources[uri_s] = VectorMCP::Definitions::Resource.new(uri, name, description, mime_type, handler)
+        logger.debug("Registered resource: #{uri_s}")
+        self
+      end
+
+      # Registers a new prompt with the server.
+      #
+      # @param name [String, Symbol] The unique name for the prompt.
+      # @param description [String] A human-readable description of the prompt.
+      # @param arguments [Array<Hash>] An array defining the prompt's arguments.
+      # @yield [Hash] A block that generates the prompt.
+      # @return [self] The server instance, for chaining.
+      # @raise [ArgumentError] if a prompt with the same name is already registered.
+      def register_prompt(name:, description:, arguments: [], &handler)
+        name_s = name.to_s
+        raise ArgumentError, "Prompt '#{name_s}' already registered" if @prompts[name_s]
+
+        validate_prompt_arguments(arguments)
+        @prompts[name_s] = VectorMCP::Definitions::Prompt.new(name_s, description, arguments, handler)
+        @prompts_list_changed = true
+        notify_prompts_list_changed
+        logger.debug("Registered prompt: #{name_s}")
+        self
+      end
+
+      # Registers a new root with the server.
+      #
+      # @param uri [String, URI] The unique URI for the root (must be file:// scheme).
+      # @param name [String] A human-readable name for the root.
+      # @return [self] The server instance, for chaining.
+      # @raise [ArgumentError] if a root with the same URI is already registered.
+      def register_root(uri:, name:)
+        uri_s = uri.to_s
+        raise ArgumentError, "Root '#{uri_s}' already registered" if @roots[uri_s]
+
+        root = VectorMCP::Definitions::Root.new(uri, name)
+        root.validate! # This will raise ArgumentError if invalid
+
+        @roots[uri_s] = root
+        @roots_list_changed = true
+        notify_roots_list_changed
+        logger.debug("Registered root: #{uri_s} (#{name})")
+        self
+      end
+
+      # Helper method to register a root from a local directory path.
+      #
+      # @param path [String] Local filesystem path to the directory.
+      # @param name [String, nil] Human-readable name for the root.
+      # @return [self] The server instance, for chaining.
+      # @raise [ArgumentError] if the path is invalid or not accessible.
+      def register_root_from_path(path, name: nil)
+        root = VectorMCP::Definitions::Root.from_path(path, name: name)
+        register_root(uri: root.uri, name: root.name)
+      end
+
+      # Helper method to register an image resource from a file path.
+      #
+      # @param uri [String] Unique URI for the resource.
+      # @param file_path [String] Path to the image file.
+      # @param name [String, nil] Human-readable name (auto-generated if nil).
+      # @param description [String, nil] Description (auto-generated if nil).
+      # @return [VectorMCP::Definitions::Resource] The registered resource.
+      # @raise [ArgumentError] If the file doesn't exist or isn't a valid image.
+      def register_image_resource(uri:, file_path:, name: nil, description: nil)
+        resource = VectorMCP::Definitions::Resource.from_image_file(
+          uri: uri,
+          file_path: file_path,
+          name: name,
+          description: description
+        )
+
+        register_resource(
+          uri: resource.uri,
+          name: resource.name,
+          description: resource.description,
+          mime_type: resource.mime_type,
+          &resource.handler
+        )
+      end
+
+      # Helper method to register an image resource from binary data.
+      #
+      # @param uri [String] Unique URI for the resource.
+      # @param image_data [String] Binary image data.
+      # @param name [String] Human-readable name.
+      # @param description [String, nil] Description (auto-generated if nil).
+      # @param mime_type [String, nil] MIME type (auto-detected if nil).
+      # @return [VectorMCP::Definitions::Resource] The registered resource.
+      # @raise [ArgumentError] If the data isn't valid image data.
+      def register_image_resource_from_data(uri:, image_data:, name:, description: nil, mime_type: nil)
+        resource = VectorMCP::Definitions::Resource.from_image_data(
+          uri: uri,
+          image_data: image_data,
+          name: name,
+          description: description,
+          mime_type: mime_type
+        )
+
+        register_resource(
+          uri: resource.uri,
+          name: resource.name,
+          description: resource.description,
+          mime_type: resource.mime_type,
+          &resource.handler
+        )
+      end
+
+      # Helper method to register a tool that accepts image inputs.
+      #
+      # @param name [String] Unique name for the tool.
+      # @param description [String] Human-readable description.
+      # @param image_parameter [String] Name of the image parameter (default: "image").
+      # @param additional_parameters [Hash] Additional JSON Schema properties.
+      # @param required_parameters [Array<String>] List of required parameter names.
+      # @param block [Proc] The tool handler block.
+      # @return [VectorMCP::Definitions::Tool] The registered tool.
+      def register_image_tool(name:, description:, image_parameter: "image", additional_parameters: {}, required_parameters: [], &block)
+        # Build the input schema with image support
+        image_property = {
+          type: "string",
+          description: "Base64 encoded image data or file path to image",
+          contentEncoding: "base64",
+          contentMediaType: "image/*"
+        }
+
+        properties = { image_parameter => image_property }.merge(additional_parameters)
+
+        input_schema = {
+          type: "object",
+          properties: properties,
+          required: required_parameters
+        }
+
+        register_tool(
+          name: name,
+          description: description,
+          input_schema: input_schema,
+          &block
+        )
+      end
+
+      # Helper method to register a prompt that supports image arguments.
+      #
+      # @param name [String] Unique name for the prompt.
+      # @param description [String] Human-readable description.
+      # @param image_argument [String] Name of the image argument (default: "image").
+      # @param additional_arguments [Array<Hash>] Additional prompt arguments.
+      # @param block [Proc] The prompt handler block.
+      # @return [VectorMCP::Definitions::Prompt] The registered prompt.
+      def register_image_prompt(name:, description:, image_argument: "image", additional_arguments: [], &block)
+        prompt = VectorMCP::Definitions::Prompt.with_image_support(
+          name: name,
+          description: description,
+          image_argument_name: image_argument,
+          additional_arguments: additional_arguments,
+          &block
+        )
+
+        register_prompt(
+          name: prompt.name,
+          description: prompt.description,
+          arguments: prompt.arguments,
+          &prompt.handler
+        )
+      end
+
+      private
+
+      # Validates that the provided schema is a valid JSON Schema.
+      # @api private
+      # @param schema [Hash, nil] The JSON Schema to validate.
+      # @return [void]
+      # @raise [ArgumentError] if the schema is invalid.
+      def validate_schema_format!(schema)
+        return if schema.nil? || schema.empty?
+        return unless schema.is_a?(Hash)
+
+        # Use JSON::Validator to validate the schema format itself
+        validation_errors = JSON::Validator.fully_validate_schema(schema)
+
+        raise ArgumentError, "Invalid input_schema format: #{validation_errors.join("; ")}" unless validation_errors.empty?
+      rescue JSON::Schema::ValidationError => e
+        raise ArgumentError, "Invalid input_schema format: #{e.message}"
+      rescue JSON::Schema::SchemaError => e
+        raise ArgumentError, "Invalid input_schema structure: #{e.message}"
+      end
+
+      # Validates the structure of the `arguments` array provided to {#register_prompt}.
+      # @api private
+      def validate_prompt_arguments(argument_defs)
+        raise ArgumentError, "Prompt arguments definition must be an Array of Hashes." unless argument_defs.is_a?(Array)
+
+        argument_defs.each_with_index { |arg, idx| validate_single_prompt_argument(arg, idx) }
+      end
+
+      # Defines the keys allowed in a prompt argument definition hash.
+      ALLOWED_PROMPT_ARG_KEYS = %w[name description required type].freeze
+      private_constant :ALLOWED_PROMPT_ARG_KEYS
+
+      # Validates a single prompt argument definition hash.
+      # @api private
+      def validate_single_prompt_argument(arg, idx)
+        raise ArgumentError, "Prompt argument definition at index #{idx} must be a Hash. Found: #{arg.class}" unless arg.is_a?(Hash)
+
+        validate_prompt_arg_name!(arg, idx)
+        validate_prompt_arg_description!(arg, idx)
+        validate_prompt_arg_required_flag!(arg, idx)
+        validate_prompt_arg_type!(arg, idx)
+        validate_prompt_arg_unknown_keys!(arg, idx)
+      end
+
+      # Validates the :name key of a prompt argument definition.
+      # @api private
+      def validate_prompt_arg_name!(arg, idx)
+        name_val = arg[:name] || arg["name"]
+        raise ArgumentError, "Prompt argument at index #{idx} missing :name" if name_val.nil?
+        unless name_val.is_a?(String) || name_val.is_a?(Symbol)
+          raise ArgumentError, "Prompt argument :name at index #{idx} must be a String or Symbol. Found: #{name_val.class}"
+        end
+        raise ArgumentError, "Prompt argument :name at index #{idx} cannot be empty." if name_val.to_s.strip.empty?
+      end
+
+      # Validates the :description key of a prompt argument definition.
+      # @api private
+      def validate_prompt_arg_description!(arg, idx)
+        return unless arg.key?(:description) || arg.key?("description")
+
+        desc_val = arg[:description] || arg["description"]
+        return if desc_val.nil? || desc_val.is_a?(String)
+
+        raise ArgumentError, "Prompt argument :description at index #{idx} must be a String if provided. Found: #{desc_val.class}"
+      end
+
+      # Validates the :required key of a prompt argument definition.
+      # @api private
+      def validate_prompt_arg_required_flag!(arg, idx)
+        return unless arg.key?(:required) || arg.key?("required")
+
+        req_val = arg[:required] || arg["required"]
+        return if [true, false].include?(req_val)
+
+        raise ArgumentError, "Prompt argument :required at index #{idx} must be true or false if provided. Found: #{req_val.inspect}"
+      end
+
+      # Validates the :type key of a prompt argument definition.
+      # @api private
+      def validate_prompt_arg_type!(arg, idx)
+        return unless arg.key?(:type) || arg.key?("type")
+
+        type_val = arg[:type] || arg["type"]
+        return if type_val.nil? || type_val.is_a?(String)
+
+        raise ArgumentError, "Prompt argument :type at index #{idx} must be a String if provided (e.g., JSON schema type). Found: #{type_val.class}"
+      end
+
+      # Checks for any unknown keys in a prompt argument definition.
+      # @api private
+      def validate_prompt_arg_unknown_keys!(arg, idx)
+        unknown_keys = arg.transform_keys(&:to_s).keys - ALLOWED_PROMPT_ARG_KEYS
+        return if unknown_keys.empty?
+
+        raise ArgumentError,
+              "Prompt argument definition at index #{idx} contains unknown keys: #{unknown_keys.join(", ")}. " \
+              "Allowed: #{ALLOWED_PROMPT_ARG_KEYS.join(", ")}."
+      end
+    end
+  end
+end