vector_mcp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eb7e5435a5b8e67c4bd570c25432b86b0e791e24c5225ee398f693867030d9a
-  data.tar.gz: 9e0a8dce81c39d4912136a0985cff18b7c4bb30e5bc361d19bc81530183d53ac
+  metadata.gz: 11a17ca5149213858f5ec62dc28a7216cd97103e1cb066a86b96d01cbef808e6
+  data.tar.gz: c99bcbc2a611c20432b2c401760512cf545e0cfb5329bd74c76c61c806c2c491
 SHA512:
-  metadata.gz: c46edbc723ece6fc4d6f8658a4ea40f97a5e80a675d187d7a58d60fffcdfb0bf1ba3b9c57e1e2f142520a280196aa97635a1ef747316c0111d4097e15006d363
-  data.tar.gz: f67637b1bdbb0fb86ce500b315382ae93a5caa18ea6c8da2f6e563b8c81208f17840fb753cce92eae11b672961a0c9a628d65d11c7eb723affb35e6c9ba27c0d
+  metadata.gz: 065f397ce2448a4cea13944462b009cd511043e9a3afd85d52641cc8f05607f59d8e0ea0653f1822385f2b95def8e7ddee1bd5117db54430717c6bb20196a958
+  data.tar.gz: a04b7cd10db5c24f9ab51fb8d4758396675fc24411530ce6a9033629fb66bd0e9974579ffb113c1401d0fe82f4e949073ca1b45d6b899c6502112781e3a5daa4

data/README.md

@@ -21,7 +21,7 @@ This library allows you to easily create MCP servers that expose your applicatio
 *   **Sampling:** Server-initiated LLM requests with configurable capabilities (streaming, tool calls, images, token limits).
 *   **Transport:**
     *   **Stdio (stable):** Simple transport using standard input/output, ideal for process-based servers.
-    *   **SSE (work-in-progress):** Server-Sent Events support is under active development and currently unavailable.
+    *   **SSE (stable):** Server-Sent Events over HTTP, enabling web-based MCP clients and browser integration.
 
 ## Installation
 
@@ -33,7 +33,6 @@ gem 'vector_mcp'
 gem install vector_mcp
 ```
 
-> ⚠️  **Note:** SSE transport is not yet supported in the released gem.
 
 ## Quick Start
 
@@ -91,6 +90,71 @@ Or use a script:
 } | ruby my_server.rb | jq
 ```
 
+### HTTP/SSE Transport
+
+For web-based clients and browser integration, use the SSE transport:
+
+```ruby
+require 'vector_mcp'
+
+server = VectorMCP.new(
+  name: 'My HTTP Server',
+  version: '1.0.0'
+)
+
+# Register tools, resources, prompts...
+server.register_tool(
+  name: 'echo',
+  description: 'Returns the input message',
+  input_schema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message']
+  }
+) { |args| args['message'] }
+
+# Start HTTP server with SSE transport
+server.run(transport: :sse, options: { port: 8080, host: 'localhost' })
+```
+
+The server provides two HTTP endpoints:
+
+*   **SSE Stream:** `GET /sse` - Establishes server-sent events connection
+*   **Messages:** `POST /message?session_id=<id>` - Sends JSON-RPC requests
+
+**Client Integration:**
+
+```javascript
+// Connect to SSE stream
+const eventSource = new EventSource('http://localhost:8080/sse');
+
+eventSource.addEventListener('endpoint', (event) => {
+  const data = JSON.parse(event.data);
+  const messageUrl = data.uri; // POST endpoint for this session
+  
+  // Send MCP initialization
+  fetch(messageUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: { 
+        protocolVersion: '2024-11-05', 
+        capabilities: {},
+        clientInfo: { name: 'WebClient', version: '1.0' }
+      }
+    })
+  });
+});
+
+eventSource.addEventListener('message', (event) => {
+  const response = JSON.parse(event.data);
+  console.log('MCP Response:', response);
+});
+```
+
 ## Core Usage
 
 ### Creating a Server
@@ -141,7 +205,81 @@ server.register_tool(
 end
 ```
 
-- `input_schema`: A JSON Schema object describing the tool's expected arguments
+#### Automatic Input Validation
+
+VectorMCP automatically validates all tool arguments against their defined `input_schema` before executing the tool handler. This provides several security and reliability benefits:
+
+- **Type Safety**: Ensures arguments match expected types (string, number, boolean, etc.)
+- **Required Fields**: Validates that all required parameters are present
+- **Format Validation**: Supports JSON Schema constraints like patterns, enums, and ranges
+- **Security**: Prevents injection attacks and malformed input from reaching your tool logic
+- **Better Error Messages**: Provides clear validation errors to help clients fix their requests
+
+```ruby
+# Example with comprehensive validation
+server.register_tool(
+  name: "process_user_data",
+  description: "Processes user information with strict validation",
+  input_schema: {
+    type: "object",
+    properties: {
+      name: { 
+        type: "string", 
+        minLength: 1, 
+        maxLength: 100,
+        pattern: "^[a-zA-Z\\s]+$"
+      },
+      age: { 
+        type: "integer", 
+        minimum: 0, 
+        maximum: 150 
+      },
+      email: { 
+        type: "string", 
+        format: "email" 
+      },
+      role: { 
+        type: "string", 
+        enum: ["admin", "user", "guest"] 
+      },
+      preferences: {
+        type: "object",
+        properties: {
+          theme: { type: "string" },
+          notifications: { type: "boolean" }
+        },
+        additionalProperties: false
+      }
+    },
+    required: ["name", "email", "role"],
+    additionalProperties: false
+  }
+) do |args, session|
+  # At this point, you can trust that:
+  # - All required fields are present
+  # - Data types are correct
+  # - String lengths and number ranges are valid
+  # - Email format is valid
+  # - Role is one of the allowed values
+  
+  "Processing user: #{args['name']} (#{args['role']})"
+end
+```
+
+**What happens with invalid input:**
+- VectorMCP returns a JSON-RPC error response with code `-32602` (Invalid params)
+- The error message includes specific details about what validation failed
+- Your tool handler is never called with invalid data
+- Clients receive clear feedback on how to fix their requests
+
+**Backward Compatibility:**
+- Tools without `input_schema` continue to work normally
+- No validation is performed if `input_schema` is not provided
+- Existing tools are unaffected by this security enhancement
+
+#### Tool Registration Options
+
+- `input_schema`: A JSON Schema object describing the tool's expected arguments (recommended for security)
 - Return value is automatically converted to MCP content format:
   - String → `{type: 'text', text: '...'}`
   - Hash with proper MCP structure → used as-is

data/lib/vector_mcp/definitions.rb

@@ -230,6 +230,7 @@ module VectorMCP
       # 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
@@ -248,13 +249,14 @@ module VectorMCP
         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)
 
+        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.

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)
         {
@@ -301,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

data/lib/vector_mcp/server/registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json-schema"
+
 module VectorMCP
   class Server
     # Handles registration of tools, resources, prompts, and roots
@@ -19,6 +21,9 @@ module VectorMCP
         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
@@ -206,6 +211,25 @@ module VectorMCP
 
       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)

data/lib/vector_mcp/transport/sse/client_connection.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Transport
+    class SSE
+      # Manages individual client connection state for SSE transport.
+      # Each client connection has a unique session ID, message queue, and streaming thread.
+      class ClientConnection
+        attr_reader :session_id, :message_queue, :logger
+        attr_accessor :stream_thread, :stream_io
+
+        # Initializes a new client connection.
+        #
+        # @param session_id [String] Unique identifier for this client session
+        # @param logger [Logger] Logger instance for debugging and error reporting
+        def initialize(session_id, logger)
+          @session_id = session_id
+          @logger = logger
+          @message_queue = Queue.new
+          @stream_thread = nil
+          @stream_io = nil
+          @closed = false
+          @mutex = Mutex.new
+
+          logger.debug { "Client connection created: #{session_id}" }
+        end
+
+        # Checks if the connection is closed
+        #
+        # @return [Boolean] true if connection is closed
+        def closed?
+          @mutex.synchronize { @closed }
+        end
+
+        # Closes the client connection and cleans up resources.
+        # This method is thread-safe and can be called multiple times.
+        def close
+          @mutex.synchronize do
+            return if @closed
+
+            @closed = true
+            logger.debug { "Closing client connection: #{session_id}" }
+
+            # Close the message queue to signal streaming thread to stop
+            @message_queue.close if @message_queue.respond_to?(:close)
+
+            # Close the stream I/O if it exists
+            begin
+              @stream_io&.close
+            rescue StandardError => e
+              logger.warn { "Error closing stream I/O for #{session_id}: #{e.message}" }
+            end
+
+            # Stop the streaming thread
+            if @stream_thread&.alive?
+              @stream_thread.kill
+              @stream_thread.join(1) # Wait up to 1 second for clean shutdown
+            end
+
+            logger.debug { "Client connection closed: #{session_id}" }
+          end
+        end
+
+        # Enqueues a message to be sent to this client.
+        # This method is thread-safe.
+        #
+        # @param message [Hash] The JSON-RPC message to send
+        # @return [Boolean] true if message was enqueued successfully
+        def enqueue_message(message)
+          return false if closed?
+
+          begin
+            @message_queue.push(message)
+            logger.debug { "Message enqueued for client #{session_id}: #{message.inspect}" }
+            true
+          rescue ClosedQueueError
+            logger.warn { "Attempted to enqueue message to closed queue for client #{session_id}" }
+            false
+          rescue StandardError => e
+            logger.error { "Error enqueuing message for client #{session_id}: #{e.message}" }
+            false
+          end
+        end
+
+        # Dequeues the next message from the client's message queue.
+        # This method blocks until a message is available or the queue is closed.
+        #
+        # @return [Hash, nil] The next message, or nil if queue is closed
+        def dequeue_message
+          return nil if closed?
+
+          begin
+            @message_queue.pop
+          rescue ClosedQueueError
+            nil
+          rescue StandardError => e
+            logger.error { "Error dequeuing message for client #{session_id}: #{e.message}" }
+            nil
+          end
+        end
+
+        # Gets the current queue size
+        #
+        # @return [Integer] Number of messages waiting in the queue
+        def queue_size
+          @message_queue.size
+        rescue StandardError
+          0
+        end
+      end
+    end
+  end
+end

data/lib/vector_mcp/transport/sse/message_handler.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "json"
+
+module VectorMCP
+  module Transport
+    class SSE
+      # Handles JSON-RPC message processing for POST requests.
+      # Processes incoming messages and sends responses via SSE streams.
+      class MessageHandler
+        # Initializes a new message handler.
+        #
+        # @param server [VectorMCP::Server] The MCP server instance
+        # @param session [VectorMCP::Session] The server session
+        # @param logger [Logger] Logger instance for debugging
+        def initialize(server, session, logger)
+          @server = server
+          @session = session
+          @logger = logger
+        end
+
+        # Handles a POST message request from a client.
+        #
+        # @param env [Hash] Rack environment hash
+        # @param client_conn [ClientConnection] The client connection
+        # @return [Array] Rack response triplet
+        def handle_post_message(env, client_conn)
+          request_body = read_request_body(env)
+          return error_response(nil, -32_600, "Request body is empty") if request_body.nil? || request_body.empty?
+
+          message = parse_json_message(request_body, client_conn)
+          return message if message.is_a?(Array) # Error response
+
+          process_message(message, client_conn)
+        rescue VectorMCP::ProtocolError => e
+          @logger.error { "Protocol error for client #{client_conn.session_id}: #{e.message}" }
+          request_id = e.request_id || message&.dig("id")
+          enqueue_error_response(client_conn, request_id, e.code, e.message, e.details)
+          error_response(request_id, e.code, e.message, e.details)
+        rescue StandardError => e
+          @logger.error { "Unexpected error for client #{client_conn.session_id}: #{e.message}\n#{e.backtrace.join("\n")}" }
+          request_id = message&.dig("id")
+          enqueue_error_response(client_conn, request_id, -32_603, "Internal server error")
+          error_response(request_id, -32_603, "Internal server error")
+        end
+
+        private
+
+        # Reads the request body from the Rack environment.
+        #
+        # @param env [Hash] Rack environment
+        # @return [String, nil] Request body as string
+        def read_request_body(env)
+          input = env["rack.input"]
+          return nil unless input
+
+          body = input.read
+          input.rewind if input.respond_to?(:rewind)
+          body
+        end
+
+        # Parses JSON message from request body.
+        #
+        # @param body_str [String] JSON string from request body
+        # @param client_conn [ClientConnection] Client connection for error handling
+        # @return [Hash, Array] Parsed message or error response triplet
+        def parse_json_message(body_str, client_conn)
+          JSON.parse(body_str)
+        rescue JSON::ParserError => e
+          @logger.error { "JSON parse error for client #{client_conn.session_id}: #{e.message}" }
+          malformed_id = VectorMCP::Util.extract_id_from_invalid_json(body_str)
+          enqueue_error_response(client_conn, malformed_id, -32_700, "Parse error")
+          error_response(malformed_id, -32_700, "Parse error")
+        end
+
+        # Processes a valid JSON-RPC message.
+        #
+        # @param message [Hash] Parsed JSON-RPC message
+        # @param client_conn [ClientConnection] Client connection
+        # @return [Array] Rack response triplet
+        def process_message(message, client_conn)
+          # Handle the message through the server
+          response_data = @server.handle_message(message, @session, client_conn.session_id)
+
+          # If it's a request (has id), send response via SSE
+          if message["id"]
+            enqueue_success_response(client_conn, message["id"], response_data)
+          else
+            @logger.debug { "Processed notification for client #{client_conn.session_id}" }
+          end
+
+          # Always return 202 Accepted for valid POST messages
+          success_response(message["id"])
+        end
+
+        # Enqueues a successful response to the client's SSE stream.
+        #
+        # @param client_conn [ClientConnection] Client connection
+        # @param request_id [String, Integer] Original request ID
+        # @param result [Object] Response result data
+        def enqueue_success_response(client_conn, request_id, result)
+          response = {
+            jsonrpc: "2.0",
+            id: request_id,
+            result: result
+          }
+          StreamManager.enqueue_message(client_conn, response)
+        end
+
+        # Enqueues an error response to the client's SSE stream.
+        #
+        # @param client_conn [ClientConnection] Client connection
+        # @param request_id [String, Integer, nil] Original request ID
+        # @param code [Integer] Error code
+        # @param message [String] Error message
+        # @param data [Object, nil] Additional error data
+        def enqueue_error_response(client_conn, request_id, code, message, data = nil)
+          error_payload = { code: code, message: message }
+          error_payload[:data] = data if data
+
+          error_response = {
+            jsonrpc: "2.0",
+            id: request_id,
+            error: error_payload
+          }
+          StreamManager.enqueue_message(client_conn, error_response)
+        end
+
+        # Creates a successful HTTP response for the POST request.
+        #
+        # @param request_id [String, Integer, nil] Request ID
+        # @return [Array] Rack response triplet
+        def success_response(request_id)
+          body = { status: "accepted", id: request_id }.to_json
+          [202, { "Content-Type" => "application/json" }, [body]]
+        end
+
+        # Creates an error HTTP response for the POST request.
+        #
+        # @param id [String, Integer, nil] Request ID
+        # @param code [Integer] Error code
+        # @param message [String] Error message
+        # @param data [Object, nil] Additional error data
+        # @return [Array] Rack response triplet
+        def error_response(id, code, message, data = nil)
+          status = case code
+                   when -32_700, -32_600, -32_602 then 400 # Parse, Invalid Request, Invalid Params
+                   when -32_601, -32_001 then 404 # Method Not Found, Not Found
+                   else 500 # Internal Error, Server Error
+                   end
+
+          error_payload = { code: code, message: message }
+          error_payload[:data] = data if data
+
+          body = {
+            jsonrpc: "2.0",
+            id: id,
+            error: error_payload
+          }.to_json
+
+          [status, { "Content-Type" => "application/json" }, [body]]
+        end
+      end
+    end
+  end
+end

data/lib/vector_mcp/transport/sse/puma_config.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Transport
+    class SSE
+      # Configures Puma server for production-ready SSE transport.
+      # Handles server setup, threading, and resource management.
+      class PumaConfig
+        attr_reader :host, :port, :logger
+
+        # Initializes Puma configuration.
+        #
+        # @param host [String] Host to bind to
+        # @param port [Integer] Port to listen on
+        # @param logger [Logger] Logger instance
+        def initialize(host, port, logger)
+          @host = host
+          @port = port
+          @logger = logger
+        end
+
+        # Configures a Puma server instance.
+        #
+        # @param server [Puma::Server] The Puma server to configure
+        def configure(server)
+          server.add_tcp_listener(host, port)
+
+          # Configure threading for production use
+          configure_threading(server)
+
+          # Set up server options
+          configure_server_options(server)
+
+          logger.debug { "Puma server configured for #{host}:#{port}" }
+        end
+
+        private
+
+        # Configures threading parameters for optimal performance.
+        #
+        # @param server [Puma::Server] The Puma server
+        def configure_threading(server)
+          # Set thread pool size based on CPU cores and expected load
+          min_threads = 2
+          max_threads = [4, Etc.nprocessors * 2].max
+
+          # Puma 6.x does not expose min_threads= and max_threads= as public API.
+          # Thread pool sizing should be set via Puma DSL/config before server creation.
+          # For legacy compatibility, set if possible, otherwise log a warning.
+          if server.respond_to?(:min_threads=) && server.respond_to?(:max_threads=)
+            server.min_threads = min_threads
+            server.max_threads = max_threads
+            logger.debug { "Puma configured with #{min_threads}-#{max_threads} threads" }
+          else
+            logger.warn { "Puma::Server does not support direct thread pool sizing; set threads via Puma config DSL before server creation." }
+          end
+        end
+
+        # Configures server-specific options.
+        #
+        # @param server [Puma::Server] The Puma server
+        def configure_server_options(server)
+          # Set server-specific options for SSE handling
+          server.leak_stack_on_error = false if server.respond_to?(:leak_stack_on_error=)
+
+          # Configure timeouts appropriate for SSE connections
+          # SSE connections should be long-lived, so we set generous timeouts
+          if server.respond_to?(:first_data_timeout=)
+            server.first_data_timeout = 30 # 30 seconds to send first data
+          end
+
+          logger.debug { "Puma server options configured for SSE transport" }
+        end
+      end
+    end
+  end
+end