vector_mcp 0.1.0 → 0.3.0

data/lib/vector_mcp/definitions.rb

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

data/lib/vector_mcp/errors.rb

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

data/lib/vector_mcp/handlers/core.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "uri"
+require "json-schema"
 
 module VectorMCP
   module Handlers
@@ -46,6 +47,7 @@ module VectorMCP
       # @return [Hash] A hash containing the tool call result or an error indication.
       #   Example success: `{ isError: false, content: [{ type: "text", ... }] }`
       # @raise [VectorMCP::NotFoundError] if the requested tool is not found.
+      # @raise [VectorMCP::InvalidParamsError] if arguments validation fails.
       def self.call_tool(params, _session, server)
         tool_name = params["name"]
         arguments = params["arguments"] || {}
@@ -53,6 +55,9 @@ module VectorMCP
         tool = server.tools[tool_name]
         raise VectorMCP::NotFoundError.new("Not Found", details: "Tool not found: #{tool_name}") unless tool
 
+        # Validate arguments against the tool's input schema
+        validate_input_arguments!(tool_name, tool, arguments)
+
         # Let StandardError propagate to Server#handle_request
         result = tool.handler.call(arguments)
         {
@@ -115,6 +120,23 @@ module VectorMCP
         result
       end
 
+      # Handles the `roots/list` request.
+      # Returns the list of available roots and clears the `listChanged` flag.
+      #
+      # @param _params [Hash] The request parameters (ignored).
+      # @param _session [VectorMCP::Session] The current session (ignored).
+      # @param server [VectorMCP::Server] The server instance.
+      # @return [Hash] A hash containing an array of root definitions.
+      #   Example: `{ roots: [ { uri: "file:///path/to/dir", name: "My Project" } ] }`
+      def self.list_roots(_params, _session, server)
+        # Once the list is supplied, clear the listChanged flag
+        result = {
+          roots: server.roots.values.map(&:as_mcp_definition)
+        }
+        server.clear_roots_list_changed if server.respond_to?(:clear_roots_list_changed)
+        result
+      end
+
       # Handles the `prompts/subscribe` request (placeholder).
       # This implementation is a simple acknowledgement.
       #
@@ -284,6 +306,44 @@ module VectorMCP
         end
       end
       private_class_method :validate_prompt_response!
+
+      # Validates arguments provided for a tool against its input schema using json-schema.
+      # @api private
+      # @param tool_name [String] The name of the tool.
+      # @param tool [VectorMCP::Definitions::Tool] The tool definition.
+      # @param arguments [Hash] The arguments supplied by the client.
+      # @return [void]
+      # @raise [VectorMCP::InvalidParamsError] if arguments fail validation.
+      def self.validate_input_arguments!(tool_name, tool, arguments)
+        return unless tool.input_schema.is_a?(Hash)
+        return if tool.input_schema.empty?
+
+        validation_errors = JSON::Validator.fully_validate(tool.input_schema, arguments)
+        return if validation_errors.empty?
+
+        raise_tool_validation_error(tool_name, validation_errors)
+      rescue JSON::Schema::ValidationError => e
+        raise_tool_validation_error(tool_name, [e.message])
+      end
+
+      # Raises InvalidParamsError with formatted validation details.
+      # @api private
+      # @param tool_name [String] The name of the tool.
+      # @param validation_errors [Array<String>] The validation error messages.
+      # @return [void]
+      # @raise [VectorMCP::InvalidParamsError] Always raises with formatted details.
+      def self.raise_tool_validation_error(tool_name, validation_errors)
+        raise VectorMCP::InvalidParamsError.new(
+          "Invalid arguments for tool '#{tool_name}'",
+          details: {
+            tool: tool_name,
+            validation_errors: validation_errors,
+            message: validation_errors.join("; ")
+          }
+        )
+      end
+      private_class_method :validate_input_arguments!
+      private_class_method :raise_tool_validation_error
     end
   end
 end