vector_mcp 0.3.1 → 0.3.3

data/lib/vector_mcp/request_context.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  # Encapsulates request-specific data for MCP sessions.
+  # This provides a formal interface for transports to populate request context
+  # and for handlers to access request data without coupling to session internals.
+  #
+  # @attr_reader headers [Hash] HTTP headers from the request
+  # @attr_reader params [Hash] Query parameters from the request
+  # @attr_reader method [String, nil] HTTP method (GET, POST, etc.) or transport-specific method
+  # @attr_reader path [String, nil] Request path or transport-specific path
+  # @attr_reader transport_metadata [Hash] Transport-specific metadata
+  class RequestContext
+    attr_reader :headers, :params, :method, :path, :transport_metadata
+
+    # Initialize a new request context with the provided data.
+    #
+    # @param headers [Hash] HTTP headers from the request (default: {})
+    # @param params [Hash] Query parameters from the request (default: {})
+    # @param method [String, nil] HTTP method or transport-specific method (default: nil)
+    # @param path [String, nil] Request path or transport-specific path (default: nil)
+    # @param transport_metadata [Hash] Transport-specific metadata (default: {})
+    def initialize(headers: {}, params: {}, method: nil, path: nil, transport_metadata: {})
+      @headers = normalize_headers(headers).freeze
+      @params = normalize_params(params).freeze
+      @method = method&.to_s&.freeze
+      @path = path&.to_s&.freeze
+      @transport_metadata = normalize_metadata(transport_metadata).freeze
+    end
+
+    # Convert the request context to a hash representation.
+    # This is useful for serialization and debugging.
+    #
+    # @return [Hash] Hash representation of the request context
+    def to_h
+      {
+        headers: @headers,
+        params: @params,
+        method: @method,
+        path: @path,
+        transport_metadata: @transport_metadata
+      }
+    end
+
+    # Check if the request context has any headers.
+    #
+    # @return [Boolean] True if headers are present, false otherwise
+    def headers?
+      !@headers.empty?
+    end
+
+    # Check if the request context has any parameters.
+    #
+    # @return [Boolean] True if parameters are present, false otherwise
+    def params?
+      !@params.empty?
+    end
+
+    # Get a specific header value.
+    #
+    # @param name [String] The header name
+    # @return [String, nil] The header value or nil if not found
+    def header(name)
+      @headers[name.to_s]
+    end
+
+    # Get a specific parameter value.
+    #
+    # @param name [String] The parameter name
+    # @return [String, nil] The parameter value or nil if not found
+    def param(name)
+      @params[name.to_s]
+    end
+
+    # Get transport-specific metadata.
+    #
+    # @param key [String, Symbol] The metadata key
+    # @return [Object, nil] The metadata value or nil if not found
+    def metadata(key)
+      @transport_metadata[key.to_s]
+    end
+
+    # Check if this is an HTTP-based transport.
+    #
+    # @return [Boolean] True if method is an HTTP method and path is present
+    def http_transport?
+      return false unless @method && @path
+
+      # Check if method is an HTTP method
+      http_methods = %w[GET POST PUT DELETE HEAD OPTIONS PATCH TRACE CONNECT]
+      http_methods.include?(@method.upcase)
+    end
+
+    # Create a minimal request context for non-HTTP transports.
+    # This is useful for stdio and other command-line transports.
+    #
+    # @param transport_type [String] The transport type identifier
+    # @return [RequestContext] A minimal request context
+    def self.minimal(transport_type)
+      new(
+        headers: {},
+        params: {},
+        method: transport_type.to_s.upcase,
+        path: "/",
+        transport_metadata: { transport_type: transport_type.to_s }
+      )
+    end
+
+    # Create a request context from a Rack environment.
+    # This is a convenience method for HTTP-based transports.
+    #
+    # @param rack_env [Hash] The Rack environment hash
+    # @param transport_type [String] The transport type identifier
+    # @return [RequestContext] A request context populated from the Rack environment
+    def self.from_rack_env(rack_env, transport_type)
+      # Handle nil rack_env by returning a minimal context
+      return minimal(transport_type) if rack_env.nil?
+
+      new(
+        headers: VectorMCP::Util.extract_headers_from_rack_env(rack_env),
+        params: VectorMCP::Util.extract_params_from_rack_env(rack_env),
+        method: rack_env["REQUEST_METHOD"],
+        path: rack_env["PATH_INFO"],
+        transport_metadata: {
+          transport_type: transport_type.to_s,
+          remote_addr: rack_env["REMOTE_ADDR"],
+          user_agent: rack_env["HTTP_USER_AGENT"],
+          content_type: rack_env["CONTENT_TYPE"]
+        }
+      )
+    end
+
+    # String representation of the request context.
+    #
+    # @return [String] String representation for debugging
+    def to_s
+      "<RequestContext method=#{@method} path=#{@path} headers=#{@headers.keys.size} params=#{@params.keys.size}>"
+    end
+
+    # Detailed string representation for debugging.
+    #
+    # @return [String] Detailed string representation
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+        "method=#{@method.inspect} path=#{@path.inspect} " \
+        "headers=#{@headers.inspect} params=#{@params.inspect} " \
+        "transport_metadata=#{@transport_metadata.inspect}>"
+    end
+
+    private
+
+    # Normalize headers to ensure consistent format.
+    #
+    # @param headers [Hash] Raw headers hash
+    # @return [Hash] Normalized headers hash
+    def normalize_headers(headers)
+      return {} unless headers.is_a?(Hash)
+
+      headers.transform_keys(&:to_s).transform_values { |v| v.nil? ? "" : v.to_s }
+    end
+
+    # Normalize parameters to ensure consistent format.
+    #
+    # @param params [Hash] Raw parameters hash
+    # @return [Hash] Normalized parameters hash
+    def normalize_params(params)
+      return {} unless params.is_a?(Hash)
+
+      params.transform_keys(&:to_s).transform_values { |v| v.nil? ? "" : v.to_s }
+    end
+
+    # Normalize transport metadata to ensure consistent format.
+    #
+    # @param metadata [Hash] Raw metadata hash
+    # @return [Hash] Normalized metadata hash
+    def normalize_metadata(metadata)
+      return {} unless metadata.is_a?(Hash)
+
+      metadata.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/vector_mcp/sampling/result.rb

@@ -19,12 +19,22 @@ module VectorMCP
       #     - 'data' [String] (Optional) Base64 image data if type is "image".
       #     - 'mimeType' [String] (Optional) Mime type if type is "image".
       def initialize(result_hash)
+        # Handle malformed or nil result_hash
+        raise ArgumentError, "Sampling result must be a Hash, got #{result_hash.class}: #{result_hash.inspect}" unless result_hash.is_a?(Hash)
+
         @raw_result = result_hash.transform_keys { |k| k.to_s.gsub(/(.)([A-Z])/, '\1_\2').downcase.to_sym }
 
         @model = @raw_result[:model]
         @stop_reason = @raw_result[:stop_reason]
         @role = @raw_result[:role]
-        @content = (@raw_result[:content] || {}).transform_keys(&:to_sym)
+
+        # Safe content processing for malformed responses
+        content_raw = @raw_result[:content]
+        @content = if content_raw.is_a?(Hash)
+                     content_raw.transform_keys(&:to_sym)
+                   else
+                     {}
+                   end
 
         validate!
       end

data/lib/vector_mcp/security/middleware.rb

@@ -133,35 +133,9 @@ module VectorMCP
       # @param env [Hash] the Rack environment
       # @return [Hash] extracted request data
       def extract_from_rack_env(env)
-        # Extract headers (HTTP_ prefixed in Rack env)
-        headers = {}
-        env.each do |key, value|
-          next unless key.start_with?("HTTP_")
-
-          # Convert HTTP_X_API_KEY to X-API-Key format
-          header_name = key[5..].split("_").map do |part|
-            case part.upcase
-            when "API" then "API" # Keep API in all caps
-            else part.capitalize
-            end
-          end.join("-")
-          headers[header_name] = value
-        end
-
-        # Add special headers
-        headers["Authorization"] = env["HTTP_AUTHORIZATION"] if env["HTTP_AUTHORIZATION"]
-        headers["Content-Type"] = env["CONTENT_TYPE"] if env["CONTENT_TYPE"]
-
-        # Extract query parameters
-        params = {}
-        if env["QUERY_STRING"]
-          require "uri"
-          params = URI.decode_www_form(env["QUERY_STRING"]).to_h
-        end
-
         {
-          headers: headers,
-          params: params,
+          headers: VectorMCP::Util.extract_headers_from_rack_env(env),
+          params: VectorMCP::Util.extract_params_from_rack_env(env),
           method: env["REQUEST_METHOD"],
           path: env["PATH_INFO"],
           rack_env: env

data/lib/vector_mcp/security/strategies/api_key.rb

@@ -96,36 +96,14 @@ module VectorMCP
         # @param env [Hash] the Rack environment
         # @return [Hash] normalized headers
         def extract_headers_from_rack_env(env)
-          headers = {}
-          env.each do |key, value|
-            next unless key.start_with?("HTTP_")
-
-            # Convert HTTP_X_API_KEY to X-API-Key format
-            header_name = key[5..].split("_").map do |part|
-              case part.upcase
-              when "API" then "API" # Keep API in all caps
-              else part.capitalize
-              end
-            end.join("-")
-            headers[header_name] = value
-          end
-
-          # Add special headers
-          headers["Authorization"] = env["HTTP_AUTHORIZATION"] if env["HTTP_AUTHORIZATION"]
-          headers["Content-Type"] = env["CONTENT_TYPE"] if env["CONTENT_TYPE"]
-          headers
+          VectorMCP::Util.extract_headers_from_rack_env(env)
         end
 
         # Extract params from Rack environment
         # @param env [Hash] the Rack environment
         # @return [Hash] normalized params
         def extract_params_from_rack_env(env)
-          params = {}
-          if env["QUERY_STRING"]
-            require "uri"
-            params = URI.decode_www_form(env["QUERY_STRING"]).to_h
-          end
-          params
+          VectorMCP::Util.extract_params_from_rack_env(env)
         end
 
         # Extract API key from headers

data/lib/vector_mcp/security/strategies/jwt_token.rb

@@ -51,8 +51,8 @@ module VectorMCP
               authenticated_at: Time.now,
               jwt_headers: headers
             }
-          rescue JWT::ExpiredSignature, JWT::InvalidIssuerError,
-                 JWT::DecodeError, StandardError
+          rescue JWT::ExpiredSignature, JWT::InvalidIssuerError, JWT::InvalidAudienceError,
+                 JWT::VerificationError, JWT::DecodeError, StandardError
             false # Token validation failed
           end
         end
@@ -96,7 +96,10 @@ module VectorMCP
           auth_header = headers["Authorization"] || headers["authorization"]
           return nil unless auth_header&.start_with?("Bearer ")
 
-          auth_header[7..] # Remove 'Bearer ' prefix
+          token = auth_header[7..] # Remove 'Bearer ' prefix
+          return nil if token.nil? || token.strip.empty?
+
+          token.strip
         end
 
         # Extract token from custom JWT header

data/lib/vector_mcp/server/capabilities.rb

@@ -34,7 +34,6 @@ module VectorMCP
       # @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.
@@ -45,10 +44,10 @@ module VectorMCP
         notification_method = "notifications/prompts/list_changed"
         begin
           if transport.respond_to?(:broadcast_notification)
-            logger.info("Broadcasting prompts list changed notification.")
+            logger.debug("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).")
+            logger.debug("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.")
@@ -62,7 +61,6 @@ module VectorMCP
       # @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.
@@ -73,10 +71,10 @@ module VectorMCP
         notification_method = "notifications/roots/list_changed"
         begin
           if transport.respond_to?(:broadcast_notification)
-            logger.info("Broadcasting roots list changed notification.")
+            logger.debug("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).")
+            logger.debug("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.")
@@ -90,7 +88,7 @@ module VectorMCP
       # @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}")
+        # Session subscribed to prompt list changes
       end
 
       private

data/lib/vector_mcp/server/message_handling.rb

@@ -21,10 +21,10 @@ module VectorMCP
         params = message["params"] || {}
 
         if id && method # Request
-          logger.info("[#{session_id}] Request [#{id}]: #{method} with params: #{params.inspect}")
+          logger.debug("[#{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}")
+          logger.debug("[#{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
@@ -74,7 +74,9 @@ module VectorMCP
       # 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?
+        # Handle both direct VectorMCP::Session and BaseSessionManager::Session wrapper
+        actual_session = session.respond_to?(:context) ? session.context : session
+        return if actual_session.initialized?
 
         # Allow "initialize" even if not marked initialized yet by server
         return if method == "initialize"
@@ -113,7 +115,9 @@ module VectorMCP
       # Internal handler for JSON-RPC notifications.
       # @api private
       def handle_notification(method, params, session)
-        unless session.initialized? || method == "initialized"
+        # Handle both direct VectorMCP::Session and BaseSessionManager::Session wrapper
+        actual_session = session.respond_to?(:context) ? session.context : session
+        unless actual_session.initialized? || method == "initialized"
           logger.warn("Ignoring notification '#{method}' before session is initialized. Params: #{params.inspect}")
           return
         end
@@ -158,7 +162,9 @@ module VectorMCP
       # @api private
       def session_method(method_name)
         lambda do |params, session, _server|
-          session.public_send(method_name, params)
+          # Handle both direct VectorMCP::Session and BaseSessionManager::Session wrapper
+          actual_session = session.respond_to?(:context) ? session.context : session
+          actual_session.public_send(method_name, params)
         end
       end
     end

data/lib/vector_mcp/server.rb

@@ -19,6 +19,7 @@ require_relative "security/session_context"
 require_relative "security/strategies/api_key"
 require_relative "security/strategies/jwt_token"
 require_relative "security/strategies/custom"
+require_relative "middleware"
 
 module VectorMCP
   # The `Server` class is the central component for an MCP server implementation.
@@ -70,7 +71,7 @@ module VectorMCP
     PROTOCOL_VERSION = "2024-11-05"
 
     attr_reader :logger, :name, :version, :protocol_version, :tools, :resources, :prompts, :roots, :in_flight_requests,
-                :auth_manager, :authorization, :security_middleware
+                :auth_manager, :authorization, :security_middleware, :middleware_manager
     attr_accessor :transport
 
     # Initializes a new VectorMCP server.
@@ -98,8 +99,8 @@ module VectorMCP
       @name = name_pos || name || "UnnamedServer"
       @version = version
       @protocol_version = options[:protocol_version] || PROTOCOL_VERSION
-      @logger = VectorMCP.logger
-      @logger.level = options[:log_level] if options[:log_level]
+      @logger = VectorMCP.logger_for("server")
+      # NOTE: log level should be configured via VectorMCP.configure_logging instead
 
       @transport = nil
       @tools = {}
@@ -121,6 +122,9 @@ module VectorMCP
       @authorization = Security::Authorization.new
       @security_middleware = Security::Middleware.new(@auth_manager, @authorization)
 
+      # Initialize middleware manager
+      @middleware_manager = Middleware::Manager.new
+
       setup_default_handlers
 
       @logger.info("Server instance '#{@name}' v#{@version} (MCP Protocol: #{@protocol_version}, Gem: v#{VectorMCP::VERSION}) initialized.")
@@ -130,11 +134,12 @@ module VectorMCP
 
     # Runs the server using the specified transport mechanism.
     #
-    # @param transport [:stdio, :sse, VectorMCP::Transport::Base] The transport to use.
-    #   Can be a symbol (`:stdio`, `:sse`) or an initialized transport instance.
+    # @param transport [:stdio, :sse, :http_stream, VectorMCP::Transport::Base] The transport to use.
+    #   Can be a symbol (`:stdio`, `:sse`, `:http_stream`) or an initialized transport instance.
     #   If a symbol is provided, the method will instantiate the corresponding transport class.
-    #   If `:sse` is chosen, ensure `async` and `falcon` gems are available.
-    # @param options [Hash] Transport-specific options (e.g., `:host`, `:port` for SSE).
+    #   If `:sse` is chosen, it uses Puma as the HTTP server (deprecated).
+    #   If `:http_stream` is chosen, it uses the MCP-compliant streamable HTTP transport.
+    # @param options [Hash] Transport-specific options (e.g., `:host`, `:port` for HTTP transports).
     #   These are passed to the transport's constructor if a symbol is provided for `transport`.
     # @return [void]
     # @raise [ArgumentError] if an unsupported transport symbol is given.
@@ -146,11 +151,20 @@ module VectorMCP
                          when :sse
                            begin
                              require_relative "transport/sse"
+                             logger.warn("SSE transport is deprecated. Please use :http_stream instead.")
                              VectorMCP::Transport::SSE.new(self, **options)
                            rescue LoadError => e
-                             logger.fatal("SSE transport requires additional dependencies. Install the 'async' and 'falcon' gems.")
+                             logger.fatal("SSE transport requires additional dependencies.")
                              raise NotImplementedError, "SSE transport dependencies not available: #{e.message}"
                            end
+                         when :http_stream
+                           begin
+                             require_relative "transport/http_stream"
+                             VectorMCP::Transport::HttpStream.new(self, **options)
+                           rescue LoadError => e
+                             logger.fatal("HttpStream transport requires additional dependencies.")
+                             raise NotImplementedError, "HttpStream transport dependencies not available: #{e.message}"
+                           end
                          when VectorMCP::Transport::Base # Allow passing an initialized transport instance
                            transport.server = self if transport.respond_to?(:server=) && transport.server.nil? # Ensure server is set
                            transport
@@ -202,9 +216,9 @@ module VectorMCP
     # Enable authorization with optional policy configuration block
     # @param block [Proc] optional block for configuring authorization policies
     # @return [void]
-    def enable_authorization!(&)
+    def enable_authorization!(&block)
       @authorization.enable!
-      instance_eval(&) if block_given?
+      instance_eval(&block) if block_given?
       @logger.info("Authorization enabled")
     end
 
@@ -218,29 +232,29 @@ module VectorMCP
     # Add authorization policy for tools
     # @param block [Proc] policy block that receives (user, action, tool)
     # @return [void]
-    def authorize_tools(&)
-      @authorization.add_policy(:tool, &)
+    def authorize_tools(&block)
+      @authorization.add_policy(:tool, &block)
     end
 
     # Add authorization policy for resources
     # @param block [Proc] policy block that receives (user, action, resource)
     # @return [void]
-    def authorize_resources(&)
-      @authorization.add_policy(:resource, &)
+    def authorize_resources(&block)
+      @authorization.add_policy(:resource, &block)
     end
 
     # Add authorization policy for prompts
     # @param block [Proc] policy block that receives (user, action, prompt)
     # @return [void]
-    def authorize_prompts(&)
-      @authorization.add_policy(:prompt, &)
+    def authorize_prompts(&block)
+      @authorization.add_policy(:prompt, &block)
     end
 
     # Add authorization policy for roots
     # @param block [Proc] policy block that receives (user, action, root)
     # @return [void]
-    def authorize_roots(&)
-      @authorization.add_policy(:root, &)
+    def authorize_roots(&block)
+      @authorization.add_policy(:root, &block)
     end
 
     # Check if security features are enabled
@@ -255,6 +269,46 @@ module VectorMCP
       @security_middleware.security_status
     end
 
+    # --- Middleware Management ---
+
+    # Register middleware for specific hook types
+    # @param middleware_class [Class] Middleware class inheriting from VectorMCP::Middleware::Base
+    # @param hooks [Symbol, Array<Symbol>] Hook types to register for (e.g., :before_tool_call, [:before_tool_call, :after_tool_call])
+    # @param priority [Integer] Execution priority (lower numbers execute first, default: 100)
+    # @param conditions [Hash] Conditions for when middleware should run
+    # @option conditions [Array<String>] :only_operations Only run for these operations
+    # @option conditions [Array<String>] :except_operations Don't run for these operations
+    # @option conditions [Array<String>] :only_users Only run for these user IDs
+    # @option conditions [Array<String>] :except_users Don't run for these user IDs
+    # @option conditions [Boolean] :critical If true, errors in this middleware stop execution
+    # @example
+    #   server.use_middleware(MyMiddleware, :before_tool_call)
+    #   server.use_middleware(AuthMiddleware, [:before_request, :after_response], priority: 10)
+    #   server.use_middleware(LoggingMiddleware, :after_tool_call, conditions: { only_operations: ['important_tool'] })
+    def use_middleware(middleware_class, hooks, priority: Middleware::Hook::DEFAULT_PRIORITY, conditions: {})
+      @middleware_manager.register(middleware_class, hooks, priority: priority, conditions: conditions)
+      @logger.debug("Registered middleware: #{middleware_class.name}")
+    end
+
+    # Remove all middleware hooks for a specific class
+    # @param middleware_class [Class] Middleware class to remove
+    def remove_middleware(middleware_class)
+      @middleware_manager.unregister(middleware_class)
+      @logger.debug("Removed middleware: #{middleware_class.name}")
+    end
+
+    # Get middleware statistics
+    # @return [Hash] Statistics about registered middleware
+    def middleware_stats
+      @middleware_manager.stats
+    end
+
+    # Clear all middleware (useful for testing)
+    def clear_middleware!
+      @middleware_manager.clear!
+      @logger.debug("Cleared all middleware")
+    end
+
     private
 
     # Add API key authentication strategy
@@ -276,8 +330,8 @@ module VectorMCP
     # Add custom authentication strategy
     # @param handler [Proc] custom authentication handler block
     # @return [void]
-    def add_custom_auth(&)
-      strategy = Security::Strategies::Custom.new(&)
+    def add_custom_auth(&block)
+      strategy = Security::Strategies::Custom.new(&block)
       @auth_manager.add_strategy(:custom, strategy)
     end