vector_mcp 0.3.3 → 0.4.0

data/lib/vector_mcp/transport/http_stream.rb

@@ -53,6 +53,16 @@ module VectorMCP
       DEFAULT_EVENT_RETENTION = 100 # Keep last 100 events for resumability
       DEFAULT_REQUEST_TIMEOUT = 30 # Default timeout for server-initiated requests
 
+      # Default allowed origins — restrict to localhost by default for security.
+      DEFAULT_ALLOWED_ORIGINS = %w[
+        http://localhost
+        https://localhost
+        http://127.0.0.1
+        https://127.0.0.1
+        http://[::1]
+        https://[::1]
+      ].freeze
+
       # Initializes a new HTTP Stream transport.
       #
       # @param server [VectorMCP::Server] The server instance that will handle messages
@@ -62,7 +72,8 @@ module VectorMCP
       # @option options [String] :path_prefix ("/mcp") The base path for HTTP endpoints
       # @option options [Integer] :session_timeout (300) Session timeout in seconds
       # @option options [Integer] :event_retention (100) Number of events to retain for resumability
-      # @option options [Array<String>] :allowed_origins (["*"]) List of allowed origins for CORS. Use ["*"] to allow all origins.
+      # @option options [Array<String>] :allowed_origins Allowed origins for CORS validation.
+      #   Defaults to localhost origins only. Pass ["*"] to allow all origins (NOT recommended for production).
       def initialize(server, options = {})
         @server = server
         @logger = server.logger
@@ -95,13 +106,29 @@ module VectorMCP
         start_time = Time.now
         path = env["PATH_INFO"]
         method = env["REQUEST_METHOD"]
+        transport_context = build_transport_context(env, method, path, start_time)
+
+        logger.debug { "Processing HTTP request #{method} #{path}" }
 
-        # Processing HTTP request
+        transport_context = execute_transport_hooks(:before_request, transport_context)
+        raise transport_context.error if transport_context.error?
+        return transport_context.result if transport_context.result
 
         response = route_request(path, method, env)
+        transport_context.result = response
+        transport_context = execute_transport_hooks(:after_response, transport_context)
+        raise transport_context.error if transport_context.error?
+
+        response = transport_context.result || response
         log_request_completion(method, path, start_time, response[0])
         response
       rescue StandardError => e
+        if transport_context
+          transport_context.error = e
+          transport_context = execute_transport_hooks(:on_transport_error, transport_context)
+          return transport_context.result if transport_context.result
+        end
+
         handle_request_error(method, path, e)
       end
 
@@ -133,16 +160,6 @@ module VectorMCP
         @stream_handler.send_message_to_session(session, message)
       end
 
-      # Broadcasts a notification to all active sessions.
-      #
-      # @param method [String] The notification method name
-      # @param params [Hash, Array, nil] The notification parameters
-      # @return [Integer] Number of sessions the notification was sent to
-      def broadcast_notification(method, params = nil)
-        message = build_notification(method, params)
-        @session_manager.broadcast_message(message)
-      end
-
       # Sends a server-initiated JSON-RPC request compatible with Session expectations.
       # This method will block until a response is received or the timeout is reached.
       # For HTTP transport, this requires finding an appropriate session with streaming connection.
@@ -307,10 +324,26 @@ module VectorMCP
       # @param env [Hash] The Rack environment
       # @return [Array] Rack response triplet
       def route_request(path, method, env)
+        return route_mounted_request(path, method, env) if @mounted
+
+        # Standalone mode: unchanged behavior
         return handle_health_check if path == "/"
         return not_found_response unless path == @path_prefix
 
-        # Validate origin for security (MCP specification requirement)
+        validate_and_dispatch(method, env)
+      end
+
+      # Routes requests when mounted inside another Rack app (e.g., Rails).
+      # PATH_INFO is relative to the mount point: "/" = MCP endpoint, "/health" = health check.
+      def route_mounted_request(path, method, env)
+        return handle_health_check if path == "/health"
+        return not_found_response unless ["", "/"].include?(path)
+
+        validate_and_dispatch(method, env)
+      end
+
+      # Validates origin and dispatches to the appropriate handler by HTTP method.
+      def validate_and_dispatch(method, env)
         return forbidden_response("Origin not allowed") unless valid_origin?(env)
 
         case method
@@ -330,28 +363,87 @@ module VectorMCP
       # @param env [Hash] The Rack environment
       # @return [Array] Rack response triplet
       def handle_post_request(env)
-        session_id = extract_session_id(env)
-        session = @session_manager.get_or_create_session(session_id, env)
+        unless valid_post_accept?(env)
+          logger.warn { "POST request with unsupported Accept header: #{env["HTTP_ACCEPT"]}" }
+          return not_acceptable_response("Not Acceptable: POST requires Accept: application/json")
+        end
 
+        session_id = extract_session_id(env)
         request_body = read_request_body(env)
-        message = parse_json_message(request_body)
+        parsed = parse_json_message(request_body)
 
-        # Check if this is a response to a server-initiated request
+        # MCP spec: POST body MUST be a single JSON-RPC message, not a batch array
+        if parsed.is_a?(Array)
+          return json_error_response(nil, -32_600, "Invalid Request",
+                                     { details: "Batch requests are not supported. Send a single JSON-RPC message per POST." })
+        end
+
+        session = resolve_session_for_post(session_id, parsed, env)
+        return session if session.is_a?(Array) # Rack error response
+
+        # Validate MCP-Protocol-Version header (skip for initialize requests)
+        is_initialize = parsed.is_a?(Hash) && parsed["method"] == "initialize"
+        unless is_initialize
+          version_error = validate_protocol_version_header(env)
+          return version_error if version_error
+        end
+
+        handle_single_request(parsed, session, env)
+      rescue JSON::ParserError => e
+        json_error_response(nil, -32_700, "Parse error", { details: e.message })
+      end
+
+      # Handles a single JSON-RPC message from a POST request.
+      #
+      # @param message [Hash] Parsed JSON-RPC message
+      # @param session [Session] The resolved session
+      # @param env [Hash] The Rack environment
+      # @return [Array] Rack response triplet
+      def handle_single_request(message, session, env)
         if outgoing_response?(message)
           handle_outgoing_response(message)
-          # For responses, return 202 Accepted with no body
           return [202, { "Mcp-Session-Id" => session.id }, []]
         end
 
-        result = @server.handle_message(message, session.context, session.id)
+        # Notifications: has method, no id -> 202 Accepted with no body (MCP spec requirement)
+        if message["method"] && !message.key?("id")
+          @server.handle_message(message, session.context, session.id)
+          return [202, { "Mcp-Session-Id" => session.id }, []]
+        end
 
-        # Set session ID header in response
-        headers = { "Mcp-Session-Id" => session.id }
-        json_rpc_response(result, message["id"], headers)
+        result = @server.handle_message(message, session.context, session.id)
+        build_rpc_response(env, result, message["id"], session.id)
       rescue VectorMCP::ProtocolError => e
-        json_error_response(e.request_id, e.code, e.message, e.details)
-      rescue JSON::ParserError => e
-        json_error_response(nil, -32_700, "Parse error", { details: e.message })
+        build_protocol_error_response(env, e, session_id: session.id)
+      end
+
+      # Resolves or creates the session for a POST request following MCP spec rules:
+      # - session_id present and known  → return existing session (updating request context)
+      # - session_id present but unknown/expired → 404 Not Found
+      # - no session_id + initialize request → create new session
+      # - no session_id + other request → 400 Bad Request
+      #
+      # @param session_id [String, nil] Client-supplied Mcp-Session-Id header value
+      # @param message [Hash] Parsed JSON-RPC message
+      # @param env [Hash] Rack environment
+      # @return [Session, Array] Session object or Rack error response triplet
+      def resolve_session_for_post(session_id, message, env)
+        is_initialize = message.is_a?(Hash) && message["method"] == "initialize"
+
+        if session_id
+          session = @session_manager.get_session(session_id)
+          return not_found_response("Unknown or expired session") unless session
+
+          if env
+            request_context = VectorMCP::RequestContext.from_rack_env(env, "http_stream")
+            session.context.request_context = request_context
+          end
+          session
+        elsif is_initialize
+          @session_manager.create_session(nil, env)
+        else
+          bad_request_response("Missing Mcp-Session-Id header")
+        end
       end
 
       # Handles GET requests (SSE streaming)
@@ -359,12 +451,20 @@ module VectorMCP
       # @param env [Hash] The Rack environment
       # @return [Array] Rack response triplet
       def handle_get_request(env)
+        unless valid_get_accept?(env)
+          logger.warn { "GET request with unsupported Accept header: #{env["HTTP_ACCEPT"]}" }
+          return not_acceptable_response("Not Acceptable: GET requires Accept: text/event-stream")
+        end
+
         session_id = extract_session_id(env)
         return bad_request_response("Missing Mcp-Session-Id header") unless session_id
 
         session = @session_manager.get_or_create_session(session_id, env)
         return not_found_response unless session
 
+        version_error = validate_protocol_version_header(env)
+        return version_error if version_error
+
         @stream_handler.handle_streaming_request(env, session)
       end
 
@@ -376,6 +476,9 @@ module VectorMCP
         session_id = extract_session_id(env)
         return bad_request_response("Missing Mcp-Session-Id header") unless session_id
 
+        version_error = validate_protocol_version_header(env)
+        return version_error if version_error
+
         success = @session_manager.terminate_session(session_id)
         if success
           [204, {}, []]
@@ -469,8 +572,85 @@ module VectorMCP
         [400, { "Content-Type" => "application/json" }, [response.to_json]]
       end
 
-      def not_found_response
-        [404, { "Content-Type" => "text/plain" }, ["Not Found"]]
+      def build_rpc_response(env, result, request_id, session_id)
+        headers = { "Mcp-Session-Id" => session_id }
+        if client_accepts_sse?(env)
+          sse_rpc_response(result, request_id, headers, session_id: session_id)
+        else
+          json_rpc_response(result, request_id, headers)
+        end
+      end
+
+      def build_protocol_error_response(env, error, session_id: nil)
+        if client_accepts_sse?(env)
+          sse_error_response(error.request_id, error.code, error.message, error.details, session_id: session_id)
+        else
+          json_error_response(error.request_id, error.code, error.message, error.details)
+        end
+      end
+
+      def client_accepts_sse?(env)
+        accept = env["HTTP_ACCEPT"] || ""
+        accept.include?("text/event-stream")
+      end
+
+      def format_sse_event(data, type, event_id, retry_ms: nil)
+        lines = []
+        lines << "id: #{event_id}" if event_id
+        lines << "event: #{type}" if type
+        lines << "retry: #{retry_ms}" if retry_ms
+        lines << "data: #{data}"
+        lines << ""
+        "#{lines.join("\n")}\n"
+      end
+
+      def sse_rpc_response(result, request_id, headers = {}, session_id: nil)
+        response = { jsonrpc: "2.0", id: request_id, result: result }
+        event_data = response.to_json
+        stream_id = generate_sse_stream_id(session_id, :post)
+
+        # Priming event per MCP spec: event ID + empty data field
+        prime_event_id = @event_store.store_event("", nil, session_id: session_id, stream_id: stream_id)
+        prime_event = "id: #{prime_event_id}\ndata:\n\n"
+
+        # Actual response event
+        event_id = @event_store.store_event(event_data, "message", session_id: session_id, stream_id: stream_id)
+        sse_event = format_sse_event(event_data, "message", event_id)
+
+        response_headers = {
+          "Content-Type" => "text/event-stream",
+          "Cache-Control" => "no-cache",
+          "Connection" => "keep-alive",
+          "X-Accel-Buffering" => "no"
+        }.merge(headers)
+
+        [200, response_headers, [prime_event, sse_event]]
+      end
+
+      def sse_error_response(id, code, err_message, data = nil, session_id: nil)
+        error_obj = { code: code, message: err_message }
+        error_obj[:data] = data if data
+        response = { jsonrpc: "2.0", id: id, error: error_obj }
+        event_data = response.to_json
+        stream_id = generate_sse_stream_id(session_id, :post)
+
+        # Priming event per MCP spec
+        prime_event_id = @event_store.store_event("", nil, session_id: session_id, stream_id: stream_id)
+        prime_event = "id: #{prime_event_id}\ndata:\n\n"
+
+        event_id = @event_store.store_event(event_data, "message", session_id: session_id, stream_id: stream_id)
+        sse_event = format_sse_event(event_data, "message", event_id)
+
+        response_headers = {
+          "Content-Type" => "text/event-stream",
+          "Cache-Control" => "no-cache"
+        }
+
+        [200, response_headers, [prime_event, sse_event]]
+      end
+
+      def not_found_response(message = "Not Found")
+        [404, { "Content-Type" => "text/plain" }, [message]]
       end
 
       def bad_request_response(message = "Bad Request")
@@ -478,7 +658,8 @@ module VectorMCP
       end
 
       def forbidden_response(message = "Forbidden")
-        [403, { "Content-Type" => "text/plain" }, [message]]
+        error = { jsonrpc: "2.0", error: { code: -32_600, message: message } }
+        [403, { "Content-Type" => "application/json" }, [error.to_json]]
       end
 
       def method_not_allowed_response(allowed_methods)
@@ -486,7 +667,46 @@ module VectorMCP
          ["Method Not Allowed"]]
       end
 
-      # Validates the Origin header for security
+      def not_acceptable_response(message = "Not Acceptable")
+        [406, { "Content-Type" => "text/plain" }, [message]]
+      end
+
+      # Validates the MCP-Protocol-Version header per spec.
+      # Returns nil if valid, or a 400 Rack response if unsupported.
+      def validate_protocol_version_header(env)
+        version = env["HTTP_MCP_PROTOCOL_VERSION"]
+        return nil if version.nil? # Backwards compatibility: assume 2025-03-26
+
+        unless VectorMCP::Server::SUPPORTED_PROTOCOL_VERSIONS.include?(version)
+          return bad_request_response("Unsupported MCP-Protocol-Version: #{version}")
+        end
+
+        nil
+      end
+
+      def valid_post_accept?(env)
+        accept = env["HTTP_ACCEPT"]
+        return true if accept.nil? || accept.strip.empty?
+        return true if accept.include?("*/*")
+
+        # MCP spec: client MUST include both application/json AND text/event-stream
+        accept.include?("application/json") && accept.include?("text/event-stream")
+      end
+
+      def valid_get_accept?(env)
+        accept = env["HTTP_ACCEPT"]
+        return true if accept.nil? || accept.strip.empty?
+
+        accept.include?("text/event-stream") || accept.include?("*/*")
+      end
+
+      # Validates the Origin header for security.
+      #
+      # Matches are checked both exactly and as prefix (so that
+      # +http://localhost+ in the allowed list matches +http://localhost:3000+).
+      #
+      # Requests without an Origin header are allowed through because they
+      # originate from non-browser contexts (curl, server-to-server, etc.).
       #
       # @param env [Hash] The Rack environment
       # @return [Boolean] True if origin is allowed, false otherwise
@@ -496,7 +716,9 @@ module VectorMCP
         origin = env["HTTP_ORIGIN"]
         return true if origin.nil? # Allow requests without Origin header (e.g., server-to-server)
 
-        @allowed_origins.include?(origin)
+        @allowed_origins.any? do |allowed|
+          origin == allowed || origin.start_with?("#{allowed}:")
+        end
       end
 
       # Logging and error handling
@@ -510,6 +732,29 @@ module VectorMCP
         [500, { "Content-Type" => "text/plain" }, ["Internal Server Error"]]
       end
 
+      def build_transport_context(env, method, path, start_time)
+        request_context = VectorMCP::RequestContext.from_rack_env(env, "http_stream")
+
+        VectorMCP::Middleware::Context.new(
+          operation_type: :transport,
+          operation_name: "#{method} #{path}",
+          params: request_context.to_h,
+          session: nil,
+          server: @server,
+          metadata: {
+            start_time: start_time,
+            path: path,
+            method: method
+          }
+        )
+      end
+
+      def execute_transport_hooks(hook_type, context)
+        return context unless @server.respond_to?(:middleware_manager) && @server.middleware_manager
+
+        @server.middleware_manager.execute_hooks(hook_type, context)
+      end
+
       def handle_fatal_error(error)
         logger.fatal { "Fatal error in HttpStream transport: #{error.message}" }
         exit(1)
@@ -657,8 +902,8 @@ module VectorMCP
       #
       # @param obj [Object] The object to transform (Hash, Array, or other)
       # @return [Object] The transformed object
-      def deep_transform_keys(obj, &block)
-        transform_object_keys(obj, &block)
+      def deep_transform_keys(obj, &)
+        transform_object_keys(obj, &)
       end
 
       # Core transformation logic extracted for better maintainability
@@ -692,7 +937,18 @@ module VectorMCP
         @path_prefix = normalize_path_prefix(options[:path_prefix] || DEFAULT_PATH_PREFIX)
         @session_timeout = options[:session_timeout] || DEFAULT_SESSION_TIMEOUT
         @event_retention = options[:event_retention] || DEFAULT_EVENT_RETENTION
-        @allowed_origins = options[:allowed_origins] || ["*"]
+        @allowed_origins = options[:allowed_origins] || DEFAULT_ALLOWED_ORIGINS
+        @mounted = options.fetch(:mounted, false)
+
+        warn_on_permissive_origins if @allowed_origins.include?("*")
+      end
+
+      # Logs a security warning when wildcard origin is configured.
+      def warn_on_permissive_origins
+        logger.warn do
+          "[SECURITY] allowed_origins includes '*', which permits cross-origin requests from any website. " \
+            "This is not recommended for production. Specify explicit origins instead."
+        end
       end
 
       # Initialize core HTTP stream components
@@ -719,6 +975,11 @@ module VectorMCP
         @request_id_counter = Concurrent::AtomicFixnum.new(0)
       end
 
+      def generate_sse_stream_id(session_id, origin)
+        session_label = session_id || "anonymous"
+        "#{session_label}-#{origin}-#{SecureRandom.hex(4)}"
+      end
+
       # Generate a unique, thread-safe request ID for server-initiated requests
       #
       # @return [String] A unique request ID in format: vecmcp_http_{pid}_{random}_{counter}

data/lib/vector_mcp/version.rb

@@ -2,5 +2,5 @@
 
 module VectorMCP
   # The current version of the VectorMCP gem.
-  VERSION = "0.3.3"
+  VERSION = "0.4.0"
 end

data/lib/vector_mcp.rb

@@ -8,19 +8,19 @@ require_relative "vector_mcp/errors"
 require_relative "vector_mcp/definitions"
 require_relative "vector_mcp/session"
 require_relative "vector_mcp/util"
+require_relative "vector_mcp/log_filter"
 require_relative "vector_mcp/image_util"
 require_relative "vector_mcp/handlers/core"
-require_relative "vector_mcp/transport/stdio"
-# require_relative "vector_mcp/transport/sse" # Load on demand
 require_relative "vector_mcp/logger"
 require_relative "vector_mcp/middleware"
 require_relative "vector_mcp/server"
+require_relative "vector_mcp/tool"
 
 # The VectorMCP module provides a full-featured, opinionated Ruby implementation
 # of the **Model Context Protocol (MCP)**.  It gives developers everything needed
 # to spin up an MCP-compatible server—including:
 #
-# * **Transport adapters** (synchronous `stdio` or HTTP + SSE)
+# * **Transport adapters** (streamable HTTP)
 # * **High-level abstractions** for *tools*, *resources*, and *prompts*
 # * **JSON-RPC 2.0** message handling with sensible defaults and detailed
 #   error reporting helpers
@@ -39,11 +39,10 @@ require_relative "vector_mcp/server"
 #   input_schema: {type: "object", properties: {text: {type: "string"}}}
 # ) { |args| args["text"] }
 #
-# server.run # => starts the stdio transport and begins processing JSON-RPC messages
+# server.run # => starts the HTTP stream transport and begins processing JSON-RPC messages
 # ```
 #
-# For production you could instead pass an `SSE` transport instance to `run` in
-# order to serve multiple concurrent clients over HTTP.
+# The default HTTP stream transport supports multiple concurrent clients over HTTP.
 #
 module VectorMCP
   class << self
@@ -67,8 +66,8 @@ module VectorMCP
     # Any positional or keyword arguments are forwarded verbatim to the underlying
     # constructor, so refer to {VectorMCP::Server#initialize} for the full list of
     # accepted parameters.
-    def new(*args, **kwargs)
-      Server.new(*args, **kwargs)
+    def new(*, **)
+      Server.new(*, **)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vector_mcp
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Sergio Bayona
@@ -129,12 +129,14 @@ files:
 - lib/vector_mcp/errors.rb
 - lib/vector_mcp/handlers/core.rb
 - lib/vector_mcp/image_util.rb
+- lib/vector_mcp/log_filter.rb
 - lib/vector_mcp/logger.rb
 - lib/vector_mcp/middleware.rb
 - lib/vector_mcp/middleware/base.rb
 - lib/vector_mcp/middleware/context.rb
 - lib/vector_mcp/middleware/hook.rb
 - lib/vector_mcp/middleware/manager.rb
+- lib/vector_mcp/rails/tool.rb
 - lib/vector_mcp/request_context.rb
 - lib/vector_mcp/sampling/request.rb
 - lib/vector_mcp/sampling/result.rb
@@ -151,19 +153,12 @@ files:
 - lib/vector_mcp/server/message_handling.rb
 - lib/vector_mcp/server/registry.rb
 - lib/vector_mcp/session.rb
+- lib/vector_mcp/tool.rb
 - lib/vector_mcp/transport/base_session_manager.rb
 - lib/vector_mcp/transport/http_stream.rb
 - lib/vector_mcp/transport/http_stream/event_store.rb
 - lib/vector_mcp/transport/http_stream/session_manager.rb
 - lib/vector_mcp/transport/http_stream/stream_handler.rb
-- lib/vector_mcp/transport/sse.rb
-- lib/vector_mcp/transport/sse/client_connection.rb
-- lib/vector_mcp/transport/sse/message_handler.rb
-- lib/vector_mcp/transport/sse/puma_config.rb
-- lib/vector_mcp/transport/sse/stream_manager.rb
-- lib/vector_mcp/transport/sse_session_manager.rb
-- lib/vector_mcp/transport/stdio.rb
-- lib/vector_mcp/transport/stdio_session_manager.rb
 - lib/vector_mcp/util.rb
 - lib/vector_mcp/version.rb
 homepage: https://github.com/sergiobayona/vector_mcp
@@ -181,7 +176,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.6
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

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

@@ -1,113 +0,0 @@
-# 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