otto 2.0.0.pre1 → 2.0.0.pre3

data/lib/otto/core/middleware_stack.rb

@@ -2,6 +2,8 @@
 
 # lib/otto/core/middleware_stack.rb
 
+require_relative 'freezable'
+
 class Otto
   module Core
     # Enhanced middleware stack management for Otto framework.
@@ -9,10 +11,18 @@ class Otto
     # and improved execution chain management.
     class MiddlewareStack
       include Enumerable
+      include Otto::Core::Freezable
 
       def initialize
         @stack = []
         @middleware_set = Set.new
+        @on_change_callback = nil
+      end
+
+      # Set a callback to be invoked when the middleware stack changes
+      # @param callback [Proc] A callable object (e.g., method or lambda)
+      def on_change(&callback)
+        @on_change_callback = callback
       end
 
       # Enhanced middleware registration with argument uniqueness and immutability check
@@ -33,8 +43,89 @@ class Otto
         entry = { middleware: middleware_class, args: args, options: options }
         @stack << entry
         @middleware_set.add(middleware_class)
-        # Invalidate memoized middleware list
-        @memoized_middleware_list = nil
+        # Notify of change
+        @on_change_callback&.call
+      end
+
+      # Add middleware with position hint for optimal ordering
+      #
+      # @param middleware_class [Class] Middleware class
+      # @param args [Array] Middleware arguments
+      # @param position [Symbol, nil] Position hint (:first, :last, or nil for append)
+      # @option options [Symbol] :position Position hint (:first or :last)
+      def add_with_position(middleware_class, *args, position: nil, **options)
+        raise FrozenError, 'Cannot modify frozen middleware stack' if frozen?
+
+        # Check for identical configuration
+        existing_entry = @stack.find do |entry|
+          entry[:middleware] == middleware_class &&
+            entry[:args] == args &&
+            entry[:options] == options
+        end
+
+        return if existing_entry
+
+        entry = { middleware: middleware_class, args: args, options: options }
+
+        case position
+        when :first
+          @stack.unshift(entry)
+        when :last
+          @stack << entry
+        else
+          @stack << entry  # Default append
+        end
+
+        @middleware_set.add(middleware_class)
+        # Notify of change
+        @on_change_callback&.call
+      end
+
+      # Validate MCP middleware ordering
+      #
+      # MCP middleware must be in security-optimal order:
+      # 1. RateLimitMiddleware (reject excessive requests early)
+      # 2. Auth middleware (validate credentials before parsing)
+      # 3. SchemaValidationMiddleware (expensive JSON schema validation last)
+      #
+      # @return [Array<String>] Warning messages if order is suboptimal
+      def validate_mcp_middleware_order
+        warnings = []
+
+        # PERFORMANCE NOTE: This implementation intentionally uses select + find_index
+        # rather than a single-pass approach. The filtered mcp_middlewares array is
+        # typically 0-3 items, making the performance difference unmeasurable.
+        # The current approach prioritizes readability over micro-optimization.
+        # Single-pass alternatives were considered but rejected as premature optimization.
+        mcp_middlewares = @stack.select do |entry|
+          [
+            Otto::MCP::RateLimitMiddleware,
+            Otto::MCP::Auth::TokenMiddleware,
+            Otto::MCP::SchemaValidationMiddleware,
+          ].include?(entry[:middleware])
+        end
+
+        return warnings if mcp_middlewares.size < 2
+
+        # Find positions
+        rate_limit_pos = mcp_middlewares.find_index { |e| e[:middleware] == Otto::MCP::RateLimitMiddleware }
+        auth_pos = mcp_middlewares.find_index { |e| e[:middleware] == Otto::MCP::Auth::TokenMiddleware }
+        validation_pos = mcp_middlewares.find_index { |e| e[:middleware] == Otto::MCP::SchemaValidationMiddleware }
+
+        # Check optimal order: rate_limit < auth < validation
+        if rate_limit_pos && auth_pos && rate_limit_pos > auth_pos
+          warnings << '[MCP Middleware] RateLimitMiddleware should come before TokenMiddleware for optimal performance'
+        end
+
+        if auth_pos && validation_pos && auth_pos > validation_pos
+          warnings << '[MCP Middleware] TokenMiddleware should come before SchemaValidationMiddleware for optimal performance'
+        end
+
+        if rate_limit_pos && validation_pos && rate_limit_pos > validation_pos
+          warnings << '[MCP Middleware] RateLimitMiddleware should come before SchemaValidationMiddleware for optimal performance'
+        end
+
+        warnings
       end
       alias use add
       alias << add
@@ -51,8 +142,8 @@ class Otto
 
         # Rebuild the set of unique middleware classes
         @middleware_set = Set.new(@stack.map { |entry| entry[:middleware] })
-        # Invalidate memoized middleware list
-        @memoized_middleware_list = nil
+        # Notify of change
+        @on_change_callback&.call
       end
 
       # Check if middleware is registered - now O(1) using Set
@@ -67,8 +158,8 @@ class Otto
 
         @stack.clear
         @middleware_set.clear
-        # Invalidate memoized middleware list
-        @memoized_middleware_list = nil
+        # Notify of change
+        @on_change_callback&.call
       end
 
       # Enumerable support
@@ -77,7 +168,7 @@ class Otto
       end
 
       # Build Rack application with middleware chain
-      def build_app(base_app, security_config = nil)
+      def wrap(base_app, security_config = nil)
         @stack.reduce(base_app) do |app, entry|
           middleware = entry[:middleware]
           args = entry[:args]
@@ -97,10 +188,9 @@ class Otto
         end
       end
 
-      # Cached middleware list to reduce array creation
+      # Returns list of middleware classes in order
       def middleware_list
-        # Memoize the result to avoid repeated array creation
-        @memoized_middleware_list ||= @stack.map { |entry| entry[:middleware] }
+        @stack.map { |entry| entry[:middleware] }
       end
 
       # Detailed introspection
@@ -135,6 +225,8 @@ class Otto
         @stack.reverse_each(&)
       end
 
+
+
       private
 
       def middleware_needs_config?(middleware_class)
@@ -144,12 +236,7 @@ class Otto
           Otto::Security::Middleware::CSRFMiddleware,
           Otto::Security::Middleware::ValidationMiddleware,
           Otto::Security::Middleware::RateLimitMiddleware,
-          Otto::Security::Authentication::AuthenticationMiddleware,
-          # Backward compatibility aliases
-          Otto::Security::CSRFMiddleware,
-          Otto::Security::ValidationMiddleware,
-          Otto::Security::RateLimitMiddleware,
-          Otto::Security::AuthenticationMiddleware,
+          Otto::Security::Middleware::IPPrivacyMiddleware,
         ].include?(middleware_class)
       end
     end

data/lib/otto/core/router.rb

@@ -12,7 +12,7 @@ class Otto
         path = File.expand_path(path)
         raise ArgumentError, "Bad path: #{path}" unless File.exist?(path)
 
-        raw = File.readlines(path).select { |line| line =~ /^\w/ }.collect { |line| line.strip }
+        raw = File.readlines(path).grep(/^\w/).collect(&:strip)
         raw.each do |entry|
           # Enhanced parsing: split only on first two whitespace boundaries
           # This preserves parameters in the definition part
@@ -25,13 +25,9 @@ class Otto
 
           # Check for MCP routes
           if Otto::MCP::RouteParser.is_mcp_route?(definition)
-            raise '[MCP] MCP server not enabled' unless @mcp_server
-
             handle_mcp_route(verb, path, definition)
             next
           elsif Otto::MCP::RouteParser.is_tool_route?(definition)
-            raise '[MCP] MCP server not enabled' unless @mcp_server
-
             handle_tool_route(verb, path, definition)
             next
           end
@@ -46,7 +42,8 @@ class Otto
           @routes_literal[route.verb]           ||= {}
           @routes_literal[route.verb][path_clean] = route
         rescue StandardError => e
-          Otto.logger.error "Bad route in #{path}: #{entry} (Error: #{e.message})"
+          Otto.logger.error "Error for route #{path}: #{e.message}"
+          Otto.logger.debug e.backtrace.join("\n") if Otto.debug
         end
         self
       end
@@ -54,7 +51,7 @@ class Otto
       def handle_request(env)
         locale             = determine_locale env
         env['rack.locale'] = locale
-        env['otto.locale_config'] = @locale_config if @locale_config
+        env['otto.locale_config'] = @locale_config.to_h if @locale_config
         @static_route    ||= Rack::Files.new(option[:public]) if option[:public] && safe_dir?(option[:public])
         path_info          = Rack::Utils.unescape(env['PATH_INFO'])
         path_info          = '/' if path_info.to_s.empty?
@@ -164,6 +161,8 @@ class Otto
       end
 
       def handle_mcp_route(verb, path, definition)
+        raise '[MCP] MCP server not enabled' unless @mcp_server
+
         route_info = Otto::MCP::RouteParser.parse_mcp_route(verb, path, definition)
         @mcp_server.register_mcp_route(route_info)
         Otto.logger.debug "[MCP] Registered resource route: #{definition}" if Otto.debug
@@ -172,6 +171,8 @@ class Otto
       end
 
       def handle_tool_route(verb, path, definition)
+        raise '[MCP] MCP server not enabled' unless @mcp_server
+
         route_info = Otto::MCP::RouteParser.parse_tool_route(verb, path, definition)
         @mcp_server.register_mcp_route(route_info)
         Otto.logger.debug "[MCP] Registered tool route: #{definition}" if Otto.debug

data/lib/otto/core.rb

@@ -0,0 +1,8 @@
+# lib/otto/core.rb
+
+require_relative 'core/router'
+require_relative 'core/file_safety'
+require_relative 'core/configuration'
+require_relative 'core/error_handler'
+require_relative 'core/uri_generator'
+require_relative 'core/middleware_stack'

data/lib/otto/env_keys.rb

@@ -0,0 +1,118 @@
+# lib/otto/env_keys.rb
+#
+# Central registry of all env['otto.*'] keys used throughout Otto framework.
+# This documentation helps prevent key conflicts and aids multi-app integration.
+#
+# DOCUMENTATION-ONLY MODULE: The constants defined here are intentionally NOT used
+# in the codebase. Otto uses string literals (e.g., env['otto.strategy_result'])
+# for readibility/simplicity. This module exists as reference documentation but
+# may be considered for future use if needed.
+#
+class Otto
+  # Rack environment keys used by Otto framework
+  #
+  # All Otto-specific keys are namespaced under 'otto.*' to avoid conflicts
+  # with other Rack middleware or applications.
+  module EnvKeys
+    # =========================================================================
+    # ROUTING & REQUEST FLOW
+    # =========================================================================
+
+    # Route definition parsed from routes file
+    # Type: Otto::RouteDefinition
+    # Set by: Otto::Core::Router#parse_routes
+    # Used by: AuthenticationMiddleware, RouteHandlers, LogicClassHandler
+    ROUTE_DEFINITION = 'otto.route_definition'
+
+    # Route-specific options parsed from route string
+    # Type: Hash (e.g., { response: 'json', csrf: 'exempt', auth: 'authenticated' })
+    # Set by: Otto::RouteDefinition#initialize
+    # Used by: CSRFMiddleware, RouteHandlers
+    ROUTE_OPTIONS = 'otto.route_options'
+
+    # =========================================================================
+    # AUTHENTICATION & AUTHORIZATION
+    # =========================================================================
+
+    # Authentication strategy result containing session/user state
+    # Type: Otto::Security::Authentication::StrategyResult
+    # Set by: RouteAuthWrapper (wraps all route handlers)
+    # Used by: RouteHandlers, LogicClasses, Controllers
+    # Guarantee: ALWAYS present - either authenticated or anonymous
+    # - Routes WITH auth requirement: Authenticated StrategyResult or 401/302
+    # - Routes WITHOUT auth requirement: Anonymous StrategyResult
+    STRATEGY_RESULT = 'otto.strategy_result'
+
+    # Authenticated user object (convenience accessor)
+    # Type: Hash, Custom User Object, or nil
+    # Set by: RouteAuthWrapper (from strategy_result.user)
+    # Used by: Controllers, RouteHandlers
+    # Note: nil for anonymous/unauthenticated requests
+    USER = 'otto.user'
+
+    # User-specific context (session, roles, permissions, etc.)
+    # Type: Hash
+    # Set by: RouteAuthWrapper (from strategy_result.user_context)
+    # Used by: Controllers, Analytics
+    # Note: Empty hash {} for anonymous requests
+    USER_CONTEXT = 'otto.user_context'
+
+    # =========================================================================
+    # SECURITY & CONFIGURATION
+    # =========================================================================
+
+    # Security configuration object
+    # Type: Otto::Security::Config
+    # Set by: Otto#initialize, SecurityConfig
+    # Used by: All security middleware (CSRF, Headers, Validation)
+    SECURITY_CONFIG = 'otto.security_config'
+
+    # =========================================================================
+    # LOCALIZATION (I18N)
+    # =========================================================================
+
+    # Resolved locale for current request
+    # Type: String (e.g., 'en', 'es', 'fr')
+    # Set by: LocaleMiddleware
+    # Used by: RouteHandlers, LogicClasses, Views
+    LOCALE = 'otto.locale'
+
+    # Locale configuration object
+    # Type: Otto::LocaleConfig
+    # Set by: LocaleMiddleware
+    # Used by: Locale resolution logic
+    LOCALE_CONFIG = 'otto.locale_config'
+
+    # Available locales for the application
+    # Type: Array<String>
+    # Set by: LocaleConfig
+    # Used by: Locale middleware, language switchers
+    AVAILABLE_LOCALES = 'otto.available_locales'
+
+    # Default/fallback locale
+    # Type: String
+    # Set by: LocaleConfig
+    # Used by: Locale middleware when resolution fails
+    DEFAULT_LOCALE = 'otto.default_locale'
+
+    # =========================================================================
+    # ERROR HANDLING
+    # =========================================================================
+
+    # Unique error ID for tracking/logging
+    # Type: String (hex format, e.g., '4ac47cb3a6d177ef')
+    # Set by: ErrorHandler, RouteHandlers
+    # Used by: Error responses, logging, support
+    ERROR_ID = 'otto.error_id'
+
+    # =========================================================================
+    # MCP (MODEL CONTEXT PROTOCOL)
+    # =========================================================================
+
+    # MCP HTTP endpoint path
+    # Type: String (default: '/_mcp')
+    # Set by: Otto::MCP::Server#enable!
+    # Used by: MCP middleware, SchemaValidationMiddleware
+    MCP_HTTP_ENDPOINT = 'otto.mcp_http_endpoint'
+  end
+end

data/lib/otto/helpers/base.rb

@@ -5,26 +5,7 @@
 class Otto
   # Base helper methods providing core functionality for Otto applications
   module BaseHelpers
-    # Build application path by joining path segments
-    #
-    # This method safely joins multiple path segments, handling
-    # duplicate slashes and ensuring proper path formatting.
-    # Includes the script name (mount point) as the first segment.
-    #
-    # @param paths [Array<String>] Path segments to join
-    # @return [String] Properly formatted path
-    #
-    # @example
-    #   app_path('api', 'v1', 'users')
-    #   # => "/myapp/api/v1/users"
-    #
-    # @example
-    #   app_path(['admin', 'settings'])
-    #   # => "/myapp/admin/settings"
-    def app_path(*paths)
-      paths = paths.flatten.compact
-      paths.unshift(env['SCRIPT_NAME']) if env['SCRIPT_NAME']
-      paths.join('/').gsub('//', '/')
-    end
+    # Keep only truly context-independent shared functionality here
+    # Methods requiring env access should be implemented in the specific helper modules
   end
 end

data/lib/otto/helpers/request.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 # lib/otto/helpers/request.rb
 
 require_relative 'base'
@@ -13,6 +11,86 @@ class Otto
       env['HTTP_USER_AGENT']
     end
 
+    # NOTE: We do NOT override Rack::Request#ip
+    #
+    # IPPrivacyMiddleware masks both REMOTE_ADDR and X-Forwarded-For headers,
+    # so Rack's native ip resolution logic works correctly with masked values.
+    # This allows Rack to handle proxy scenarios (trusted proxies, header parsing)
+    # while still returning privacy-safe masked IPs.
+    #
+    # If you need the masked IP explicitly, use:
+    #   req.masked_ip  # => '192.168.1.0' or nil if privacy disabled
+    #
+    # If you need the geo country:
+    #   req.geo_country  # => 'US' or nil
+    #
+    # If you need the full privacy fingerprint:
+    #   req.redacted_fingerprint  # => RedactedFingerprint object or nil
+
+    # Get the privacy-safe fingerprint for this request
+    #
+    # Returns nil if IP privacy is disabled. The fingerprint contains
+    # anonymized request information suitable for logging and analytics.
+    #
+    # @return [Otto::Privacy::RedactedFingerprint, nil] Privacy-safe fingerprint
+    # @example
+    #   fingerprint = req.redacted_fingerprint
+    #   fingerprint.masked_ip    # => '192.168.1.0'
+    #   fingerprint.country      # => 'US'
+    def redacted_fingerprint
+      env['otto.redacted_fingerprint']
+    end
+
+    # Get the geo-location country code for the request
+    #
+    # Returns ISO 3166-1 alpha-2 country code or 'XX' for unknown.
+    # Only available when IP privacy is enabled (default).
+    #
+    # @return [String, nil] Country code or nil if privacy disabled
+    # @example
+    #   req.geo_country  # => 'US'
+    def geo_country
+      redacted_fingerprint&.country || env['otto.geo_country']
+    end
+
+    # Get anonymized user agent string
+    #
+    # Returns user agent with version numbers stripped for privacy.
+    # Only available when IP privacy is enabled (default).
+    #
+    # @return [String, nil] Anonymized user agent or nil
+    # @example
+    #   req.anonymized_user_agent
+    #   # => 'Mozilla/X.X (Windows NT X.X; Win64; x64) AppleWebKit/X.X'
+    def anonymized_user_agent
+      redacted_fingerprint&.anonymized_ua
+    end
+
+    # Get masked IP address
+    #
+    # Returns privacy-safe masked IP. When privacy is enabled (default),
+    # this returns the masked version. When disabled, returns original IP.
+    #
+    # @return [String, nil] Masked or original IP address
+    # @example
+    #   req.masked_ip  # => '192.168.1.0'
+    def masked_ip
+      env['otto.masked_ip'] || env['REMOTE_ADDR']
+    end
+
+    # Get hashed IP for session correlation
+    #
+    # Returns daily-rotating hash of the IP address, allowing session
+    # tracking without storing the original IP. Only available when
+    # IP privacy is enabled (default).
+    #
+    # @return [String, nil] Hexadecimal hash string or nil
+    # @example
+    #   req.hashed_ip  # => 'a3f8b2c4d5e6f7...'
+    def hashed_ip
+      redacted_fingerprint&.hashed_ip || env['otto.hashed_ip']
+    end
+
     def client_ipaddress
       remote_addr = env['REMOTE_ADDR']
 

data/lib/otto/helpers/response.rb

@@ -14,10 +14,10 @@ class Otto
     def send_secure_cookie(name, value, ttl, opts = {})
       # Default security options
       defaults = {
-        secure: true,
-        httponly: true,
+           secure: true,
+         httponly: true,
         same_site: :strict,
-        path: '/',
+             path: '/',
       }
 
       # Merge with provided options
@@ -152,5 +152,27 @@ class Otto
       headers['expires']       = 'Mon, 7 Nov 2011 00:00:00 UTC'
       headers['pragma']        = 'no-cache'
     end
+
+    # Build application path by joining path segments
+    #
+    # This method safely joins multiple path segments, handling
+    # duplicate slashes and ensuring proper path formatting.
+    # Includes the script name (mount point) as the first segment.
+    #
+    # @param paths [Array<String>] Path segments to join
+    # @return [String] Properly formatted path
+    #
+    # @example
+    #   app_path('api', 'v1', 'users')
+    #   # => "/myapp/api/v1/users"
+    #
+    # @example
+    #   app_path(['admin', 'settings'])
+    #   # => "/myapp/admin/settings"
+    def app_path(*paths)
+      paths = paths.flatten.compact
+      paths.unshift(request.env['SCRIPT_NAME']) if request.env['SCRIPT_NAME']
+      paths.join('/').gsub('//', '/')
+    end
   end
 end

data/lib/otto/helpers.rb

@@ -0,0 +1,4 @@
+# lib/otto/helpers.rb
+
+require_relative 'helpers/request'
+require_relative 'helpers/response'

data/lib/otto/locale/config.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# lib/otto/locale/config.rb
+
+require_relative '../core/freezable'
+
+class Otto
+  module Locale
+    # Locale configuration for Otto applications
+    #
+    # This class manages locale-related settings including available locales
+    # and default locale selection.
+    #
+    # @example Basic usage
+    #   config = Otto::Locale::Config.new
+    #   config.available_locales = { 'en' => 'English', 'es' => 'Spanish' }
+    #   config.default_locale = 'en'
+    #
+    # @example With initialization
+    #   config = Otto::Locale::Config.new(
+    #     available_locales: { 'en' => 'English', 'fr' => 'French' },
+    #     default_locale: 'en'
+    #   )
+    class Config
+      include Otto::Core::Freezable
+
+      attr_accessor :available_locales, :default_locale
+
+      # Initialize locale configuration
+      #
+      # @param available_locales [Hash, nil] Hash of locale codes to names
+      # @param default_locale [String, nil] Default locale code
+      def initialize(available_locales: nil, default_locale: nil)
+        @available_locales = available_locales
+        @default_locale = default_locale
+      end
+
+      # Convert to hash for compatibility with existing code
+      #
+      # @return [Hash] Hash representation of configuration
+      def to_h
+        {
+          available_locales: @available_locales,
+          default_locale: @default_locale,
+        }.compact
+      end
+
+      # Check if locale configuration is present
+      #
+      # @return [Boolean] true if either available_locales or default_locale is set
+      def configured?
+        !@available_locales.nil? || !@default_locale.nil?
+      end
+    end
+  end
+end

data/lib/otto/mcp/{validation.rb → schema_validation.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# lib/otto/mcp/validation.rb
+# lib/otto/mcp/schema_validation.rb
 
 require 'json'
 
@@ -67,7 +67,8 @@ class Otto
     end
 
     # Middleware for validating MCP protocol requests using JSON schema
-    class ValidationMiddleware
+    # Validates JSON-RPC 2.0 structure and tool argument schemas
+    class SchemaValidationMiddleware
       def initialize(app, _security_config = nil)
         @app       = app
         @validator = Validator.new

data/lib/otto/mcp/server.rb

@@ -6,7 +6,7 @@ require_relative 'protocol'
 require_relative 'registry'
 require_relative 'route_parser'
 require_relative 'auth/token'
-require_relative 'validation'
+require_relative 'schema_validation'
 require_relative 'rate_limiting'
 
 class Otto
@@ -53,30 +53,43 @@ class Otto
       private
 
       def configure_middleware(_options)
-        # Configure middleware in security-optimal order:
-        # 1. Rate limiting (reject excessive requests early)
-        # 2. Authentication (validate credentials before parsing)
-        # 3. Validation (expensive JSON schema validation last)
+        # Configure middleware in security-optimal order using explicit positioning:
+        # 1. Rate limiting (reject excessive requests early) - position: :first
+        # 2. Authentication (validate credentials before parsing) - default append
+        # 3. Validation (expensive JSON schema validation last) - position: :last
 
-        # Configure rate limiting first
+        middleware = @otto_instance.instance_variable_get(:@middleware)
+
+        # Configure rate limiting first (explicit position for clarity)
         if @enable_rate_limiting
-          @otto_instance.use Otto::MCP::RateLimitMiddleware, @otto_instance.security_config
-          Otto.logger.debug '[MCP] Rate limiting enabled' if Otto.debug
+          middleware.add_with_position(
+            Otto::MCP::RateLimitMiddleware,
+            @otto_instance.security_config,
+            position: :first
+          )
+          Otto.logger.debug '[MCP] Rate limiting enabled (position: first)' if Otto.debug
         end
 
-        # Configure authentication second
+        # Configure authentication second (default append order)
         if @auth_tokens.any?
-          @auth                                   = Otto::MCP::Auth::TokenAuth.new(@auth_tokens)
+          @auth = Otto::MCP::Auth::TokenAuth.new(@auth_tokens)
           @otto_instance.security_config.mcp_auth = @auth
           @otto_instance.use Otto::MCP::Auth::TokenMiddleware
           Otto.logger.debug '[MCP] Token authentication enabled' if Otto.debug
         end
 
-        # Configure validation last (most expensive)
+        # Configure validation last (explicit position for clarity)
         return unless @enable_validation
 
-        @otto_instance.use Otto::MCP::ValidationMiddleware
-        Otto.logger.debug '[MCP] Request validation enabled' if Otto.debug
+        middleware.add_with_position(
+          Otto::MCP::SchemaValidationMiddleware,
+          position: :last
+        )
+        Otto.logger.debug '[MCP] Schema validation enabled (position: last)' if Otto.debug
+
+        # Validate middleware order (should pass with explicit positioning)
+        warnings = middleware.validate_mcp_middleware_order
+        warnings.each { |warning| Otto.logger.warn warning }
       end
 
       def add_mcp_endpoint_route