otto 2.9.0 → 2.11.0

data/lib/otto/mcp/protocol.rb

@@ -4,11 +4,47 @@
 
 require 'json'
 require_relative 'registry'
+require_relative 'errors'
 
 class Otto
   module MCP
-    # MCP protocol handler providing Model Context Protocol functionality
+    # MCP protocol handler providing Model Context Protocol functionality.
+    #
+    # == JSON-RPC error code to HTTP status mapping
+    #
+    #   Code     Meaning                 HTTP
+    #   -32700   Parse error             400
+    #   -32600   Invalid Request         400
+    #   -32601   Method not found        400
+    #   -32602   Invalid params          400
+    #   -32001   Resource not found      404
+    #   -32002   Tool not found          404
+    #   -32603   Internal error          500
+    #   -32099..-32000  server errors    500
+    #
+    # Protocol-level faults (a malformed or unsupported payload against a valid
+    # endpoint) are 400, including method-not-found: 404 there would conflate a
+    # bad payload with "no such route", which the MCP endpoint handler already
+    # returns when MCP is disabled. 404 is reserved for a well-formed request
+    # naming an entity that is not registered, and 500 for handler execution
+    # faults. Handler exception messages are logged, never returned: -32603
+    # responses carry a fixed message.
     class Protocol
+      # @see Protocol for the rationale behind this mapping.
+      ERROR_STATUS_MAP = {
+        -32_700 => 400, # Parse error
+        -32_600 => 400, # Invalid Request
+        -32_601 => 400, # Method not found
+        -32_602 => 400, # Invalid params
+        -32_001 => 404, # Resource not found
+        -32_002 => 404, # Tool not found
+        -32_603 => 500, # Internal error
+      }.freeze
+
+      # Implementation-defined server error range; anything unmapped inside it
+      # is an execution fault.
+      SERVER_ERROR_RANGE = (-32_099..-32_000)
+
       attr_reader :registry
 
       def initialize(otto_instance)
@@ -89,7 +125,15 @@ class Otto
 
         return error_response(data['id'], -32_602, 'Invalid params', 'Missing uri parameter') unless uri
 
-        resource = @registry.read_resource(uri)
+        begin
+          resource = @registry.read_resource(uri)
+        rescue StandardError => e
+          # Detail stays in the log: handler exceptions (Errno::*, constant
+          # resolution) can carry absolute paths and internals.
+          Otto.logger.error "[MCP] Resource read error for #{uri}: #{e.class}: #{e.message}"
+          return error_response(data['id'], -32_603, 'Internal error', 'Resource read failed')
+        end
+
         if resource
           success_response(data['id'], resource)
         else
@@ -112,9 +156,11 @@ class Otto
         begin
           result = @registry.call_tool(name, arguments, env)
           success_response(data['id'], result)
+        rescue Otto::MCP::ToolNotFoundError => e
+          error_response(data['id'], -32_002, 'Tool not found', e.message)
         rescue StandardError => e
-          Otto.logger.error "[MCP] Tool call error: #{e.message}"
-          error_response(data['id'], -32_603, 'Internal error', e.message)
+          Otto.logger.error "[MCP] Tool call error for #{name}: #{e.class}: #{e.message}"
+          error_response(data['id'], -32_603, 'Internal error', 'Tool execution failed')
         end
       end
 
@@ -138,24 +184,8 @@ class Otto
           error: error,
                              })
 
-        # Map JSON-RPC error codes to appropriate HTTP status codes
-        http_status = case code
-                      when -32_700..-32_600 # Parse error, Invalid Request, Method not found
-                        400
-                      when -32_603, -32_000..-32_099 # Internal error and all server error range (-32000..-32099)
-                        500
-                      when -32_001         # Resource not found
-                        404
-                      when -32_002         # Tool not found
-                        404
-                      when -32_601         # Method not found
-                        404
-                      when -32_602         # Invalid params
-                        400
-                      else
-                        # Default client error for unknown non-server codes; treat server-range as 500
-                        (-32_099..-32_000).cover?(code) ? 500 : 400
-                      end
+        # Map JSON-RPC error codes to HTTP status codes (see ERROR_STATUS_MAP).
+        http_status = ERROR_STATUS_MAP[code] || (SERVER_ERROR_RANGE.cover?(code) ? 500 : 400)
 
         [http_status, { 'content-type' => 'application/json' }, [body]]
       end

data/lib/otto/mcp/rate_limiting.rb

@@ -5,44 +5,152 @@
 require 'json'
 
 require_relative '../security/rate_limiting'
-
-begin
-  require 'rack/attack'
-rescue LoadError
-  # rack-attack is optional - graceful fallback
-end
+require_relative 'endpoint'
 
 class Otto
   module MCP
     # Rate limiter for MCP protocol endpoints
+    #
+    # Rack::Attack configuration is process-global and a throttle is keyed by
+    # name alone, so registering 'mcp_requests' for a second MCP app in the
+    # same process used to REPLACE the first app's throttle: the captured
+    # endpoint moved from /a to /b and /a stopped being rate limited. Each
+    # configured endpoint now gets its own throttle pair
+    # ('mcp_requests:/a', 'mcp_tool_calls:/a', ...) with its own limits, and
+    # every endpoint configured in the process is remembered in
+    # {.registered_endpoints} so the (single, global) throttled responder and
+    # log subscriber recognise all of them, not just the most recent.
+    #
+    # Known limitation: throttles are keyed by endpoint path, not by Otto
+    # instance. Two apps in one process that mount MCP on the SAME path (for
+    # example both on /_mcp behind a host or tenant dispatcher) share one
+    # throttle definition, so the limits configured last apply to both, and
+    # one set of per-client-IP counters. Use distinct endpoint paths per app.
     class RateLimiter < Otto::Security::RateLimiting
-      def self.configure_rack_attack!(config = {})
-        return unless defined?(Rack::Attack)
+      DEFAULT_HTTP_ENDPOINT = '/_mcp'
+
+      @endpoints       = Set.new
+      @endpoints_mutex = Mutex.new
+
+      class << self
+        # Every MCP endpoint configured via {.configure_rack_attack!} in this
+        # process, in configuration order.
+        # @return [Array<String>]
+        def registered_endpoints
+          @endpoints_mutex.synchronize { @endpoints.to_a }
+        end
+
+        # Forget every registered endpoint. Test isolation only: production
+        # configuration is additive for the life of the process, like
+        # Rack::Attack's own.
+        # @api private
+        def reset_endpoints!
+          @endpoints_mutex.synchronize { @endpoints.clear }
+        end
+
+        # @api private
+        def register_endpoint(endpoint)
+          return if endpoint.nil?
 
-        # Start with base configuration from general rate limiting
+          @endpoints_mutex.synchronize { @endpoints << endpoint }
+        end
+      end
+
+      def self.configure_rack_attack!(config = {})
+        # Start with base configuration from general rate limiting. The base
+        # configure_rack_attack! assigns the single Rack::Attack
+        # throttled_responder (dispatching to .throttled_response, overridden
+        # below) and calls .configure_logging (also overridden below), so this
+        # class registers no responder or subscriber of its own after super.
         super
 
-        # Add MCP-specific rules
+        register_endpoint(config[:mcp_http_endpoint])
         configure_mcp_rules(config)
-        configure_mcp_responses
-        configure_mcp_logging
+      end
+
+      # Resolve the MCP endpoint a Rack::Attack throttle should match against.
+      #
+      # Rack::Attack is mounted by the hosting app OUTSIDE Otto and runs before
+      # every Otto middleware, including the proc that sets
+      # env['otto.mcp_http_endpoint'], so inside a throttle that env key is
+      # absent. The endpoint therefore has to arrive with the configuration
+      # (Server#apply_rate_limits publishes it as :mcp_http_endpoint). The env
+      # key is kept as a fallback for callers that run Rack::Attack inside
+      # Otto's own stack, and the documented default closes the chain.
+      #
+      # @param configured [String, nil] endpoint from the rate limiting config
+      # @param env [Hash] the request env
+      # @return [String]
+      def self.mcp_endpoint_for(configured, env)
+        configured || env['otto.mcp_http_endpoint'] || DEFAULT_HTTP_ENDPOINT
+      end
+
+      # Whether a request targets ANY MCP endpoint configured in this process.
+      #
+      # Used by the throttled responder and the log subscriber, which are
+      # global (the last configuration wins) and so cannot capture a single
+      # endpoint the way a per-endpoint throttle can. Consults the registry at
+      # call time, then the env key, then the default when nothing is
+      # configured at all. A request matches only the exact endpoint path the
+      # router would dispatch to the MCP handler (see Otto::MCP.endpoint_path?),
+      # never a sibling that merely shares the prefix.
+      #
+      # Compares PATH_INFO, not Rack::Request#path (SCRIPT_NAME + PATH_INFO):
+      # the router dispatches on PATH_INFO, so under `map '/api' { run otto }`
+      # the MCP request for an endpoint at /_mcp arrives as SCRIPT_NAME=/api,
+      # PATH_INFO=/_mcp and the full path /api/_mcp never equals the endpoint.
+      #
+      # @param request [Rack::Attack::Request, #path_info, #env]
+      # @return [Boolean]
+      def self.mcp_request?(request)
+        candidates = registered_endpoints
+        env_endpoint = request.env['otto.mcp_http_endpoint']
+        candidates << env_endpoint if env_endpoint
+        candidates << DEFAULT_HTTP_ENDPOINT if candidates.empty?
+
+        candidates.any? { |endpoint| Otto::MCP.endpoint_path?(request.path_info, endpoint) }
+      end
+
+      # Name of the Rack::Attack throttle for +rule+ on +endpoint+.
+      #
+      # The endpoint is part of the name so that two MCP apps in one process
+      # get independent throttles (and independent counters: Rack::Attack keys
+      # the cache by throttle name). Without a configured endpoint the bare
+      # rule name is used and the block resolves the endpoint per request.
+      #
+      # @param rule [String] 'mcp_requests' or 'mcp_tool_calls'
+      # @param endpoint [String, nil]
+      # @return [String]
+      def self.throttle_name(rule, endpoint)
+        endpoint ? "#{rule}:#{endpoint}" : rule
       end
 
       def self.configure_mcp_rules(config)
-        # MCP endpoint requests - 60 per minute by default
+        # Captured once, outside the blocks: they run per request, long after
+        # this configuration hash is gone.
+        configured_endpoint = config[:mcp_http_endpoint]
+
+        # MCP endpoint requests - 60 per minute by default. Only the exact
+        # endpoint path counts: the router dispatches the MCP route by literal
+        # match, so a prefix match here would let /admin traffic exhaust (and be
+        # refused by) the counter for an endpoint at /a. PATH_INFO, not #path:
+        # a mount prefix (SCRIPT_NAME) is invisible to the router and must be
+        # invisible here too, or a mounted Otto is never throttled.
         mcp_requests_limit = config[:mcp_requests_per_minute] || 60
 
-        Rack::Attack.throttle('mcp_requests', limit: mcp_requests_limit, period: 60) do |request|
-          endpoint = request.env['otto.mcp_http_endpoint'] || '/_mcp'
-          request.ip if request.path.start_with?(endpoint)
+        Rack::Attack.throttle(throttle_name('mcp_requests', configured_endpoint),
+                              limit: mcp_requests_limit, period: 60) do |request|
+          endpoint = mcp_endpoint_for(configured_endpoint, request.env)
+          request.ip if Otto::MCP.endpoint_path?(request.path_info, endpoint)
         end
 
         # Tool calls are more expensive - 20 per minute by default
         tool_calls_limit = config[:tool_calls_per_minute] || 20
 
-        Rack::Attack.throttle('mcp_tool_calls', limit: tool_calls_limit, period: 60) do |request|
-          endpoint = request.env['otto.mcp_http_endpoint'] || '/_mcp'
-          if request.path.start_with?(endpoint) && request.post?
+        Rack::Attack.throttle(throttle_name('mcp_tool_calls', configured_endpoint),
+                              limit: tool_calls_limit, period: 60) do |request|
+          endpoint = mcp_endpoint_for(configured_endpoint, request.env)
+          if Otto::MCP.endpoint_path?(request.path_info, endpoint) && request.post?
             begin
               body = request.body.read
               data = JSON.parse(body)
@@ -56,91 +164,59 @@ class Otto
         end
       end
 
-      def self.configure_mcp_responses
-        # Override throttled responder to provide JSON-RPC formatted responses for MCP requests
-        Rack::Attack.throttled_responder = lambda do |request|
-          match_data = request.env['rack.attack.match_data']
-          now        = match_data[:epoch_time]
-
-          headers = {
-            'content-type' => 'application/json',
-            'retry-after' => (match_data[:period] - (now % match_data[:period])).to_s,
-          }
-
-          # Check if this is an MCP request
-          endpoint = request.env['otto.mcp_http_endpoint'] || '/_mcp'
-          if request.path.start_with?(endpoint)
-            # JSON-RPC error response for MCP
-            error_response = {
-              jsonrpc: '2.0',
-              id: nil,
-              error: {
-                code: -32_000,
-                message: 'Rate limit exceeded',
-                data: {
-                  retry_after: headers['retry-after'].to_i,
-                  limit: match_data[:limit],
-                  period: match_data[:period],
-                },
-              },
-            }
-            [429, headers, [JSON.generate(error_response)]]
-          else
-            # Use the general rate limiting response for non-MCP requests
-            # Route's response_type takes precedence over Accept header
-            route_def = request.env['otto.route_definition']
-            wants_json = (route_def&.response_type == 'json') ||
-                         request.env['HTTP_ACCEPT'].to_s.include?('application/json')
-
-            if wants_json
-              error_response = {
-                error: 'Rate limit exceeded',
-                message: 'Too many requests',
-                retry_after: headers['retry-after'].to_i,
-                limit: match_data[:limit],
-                period: match_data[:period],
-              }
-              [429, headers, [JSON.generate(error_response)]]
-            else
-              body                    = "Rate limit exceeded. Retry after #{headers['retry-after']} seconds."
-              headers['content-type'] = 'text/plain'
-              [429, headers, [body]]
-            end
-          end
-        end
+      # JSON-RPC formatted 429 for MCP requests; the general Otto response
+      # (route response_type, then Accept header) for everything else.
+      def self.throttled_response(request)
+        return super unless mcp_request?(request)
+
+        match_data = request.env['rack.attack.match_data']
+        headers    = throttle_headers(match_data)
+
+        error_response = {
+          jsonrpc: '2.0',
+          id: nil,
+          error: {
+            code: -32_000,
+            message: 'Rate limit exceeded',
+            data: {
+              retry_after: headers['retry-after'].to_i,
+              limit: match_data[:limit],
+              period: match_data[:period],
+            },
+          },
+        }
+        [429, headers, [JSON.generate(error_response)]]
       end
 
-      def self.configure_mcp_logging
+      # Keep one MCP-aware subscriber while allowing it to recognize every
+      # endpoint registered in this process.
+      def self.configure_logging
         return unless defined?(ActiveSupport::Notifications)
 
-        # Masked address only — see the note on the sibling subscriber in
-        # Otto::Security::RateLimiting.configure_rack_attack! (issue #219).
-        ActiveSupport::Notifications.subscribe('rack.attack') do |_name, _start, _finish, _request_id, payload|
-          req      = payload[:request]
-          endpoint = req.env['otto.mcp_http_endpoint'] || '/_mcp'
-          ip       = Otto::LoggingHelpers.privacy_safe_ip(req.env, req.ip)
-
-          if req.path.start_with?(endpoint)
-            Otto.logger.warn "[MCP] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
-          else
-            Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
-          end
+        ActiveSupport::Notifications.unsubscribe(@log_subscriber) if @log_subscriber
+        @log_subscriber = ActiveSupport::Notifications.subscribe('rack.attack') do |_name, _start, _finish, _request_id, payload|
+          log_throttled_request(payload)
         end
       end
+
+      # Masked address only — see the note on the base implementation in
+      # Otto::Security::RateLimiting (issue #219).
+      def self.log_throttled_request(payload)
+        req = payload[:request]
+        return super unless mcp_request?(req)
+
+        ip = Otto::LoggingHelpers.privacy_safe_ip(req.env, req.ip)
+        Otto.logger.warn "[MCP] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
+      end
     end
 
     # Middleware for applying rate limits to MCP protocol endpoints
     class RateLimitMiddleware < Otto::Security::RateLimitMiddleware
       def initialize(app, security_config = nil)
-        @app                    = app
-        @security_config        = security_config
-        @rate_limiter_available = defined?(Rack::Attack)
-
-        if @rate_limiter_available
-          configure_mcp_rate_limiting
-        else
-          Otto.logger.warn '[MCP] rack-attack not available - rate limiting disabled'
-        end
+        @app             = app
+        @security_config = security_config
+
+        configure_mcp_rate_limiting
       end
 
       private
@@ -149,11 +225,13 @@ class Otto
         # Get base configuration from security config
         base_config = @security_config&.rate_limiting_config || {}
 
-        # Add MCP-specific defaults
-        mcp_config = base_config.merge({
-                                         mcp_requests_per_minute: 60,
+        # MCP defaults, overridden by anything the security config carries
+        # (Server#apply_rate_limits publishes the configured limits and the
+        # endpoint there).
+        mcp_config = {
+          mcp_requests_per_minute: 60,
           tool_calls_per_minute: 20,
-                                       })
+        }.merge(base_config)
 
         RateLimiter.configure_rack_attack!(mcp_config)
       end

data/lib/otto/mcp/registry.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative '../security/constant_resolver'
+require_relative 'errors'
 
 class Otto
   module MCP
@@ -57,24 +58,23 @@ class Otto
         resource = @resources[uri]
         return nil unless resource
 
-        begin
-          content = resource[:handler].call
-          {
-            contents: [{
-              uri: uri,
-              mimeType: resource[:mimeType],
-              text: content.to_s,
-            }],
-          }
-        rescue StandardError => e
-          Otto.logger.error "[MCP] Resource read error for #{uri}: #{e.message}"
-          nil
-        end
+        # A handler that blows up propagates: it is an execution fault
+        # (-32603/500), not a missing resource (-32001/404). Returning nil
+        # here previously made the two indistinguishable to the protocol,
+        # which owns the logging (Protocol#handle_resources_read).
+        content = resource[:handler].call
+        {
+          contents: [{
+            uri: uri,
+            mimeType: resource[:mimeType],
+            text: content.to_s,
+          }],
+        }
       end
 
       def call_tool(name, arguments, env)
         tool = @tools[name]
-        raise "Tool not found: #{name}" unless tool
+        raise ToolNotFoundError, "Tool not found: #{name}" unless tool
 
         handler = tool[:handler]
         if handler.respond_to?(:call)

data/lib/otto/mcp/schema_validation.rb

@@ -4,11 +4,8 @@
 
 require 'json'
 
-begin
-  require 'json_schemer'
-rescue LoadError
-  # json_schemer is optional - graceful fallback
-end
+require_relative '../optional_dependency'
+require_relative 'endpoint'
 
 class Otto
   module MCP
@@ -16,14 +13,24 @@ class Otto
 
     # JSON Schema validator for MCP protocol requests
     class Validator
+      JSON_SCHEMER_REQUIREMENT = '~> 2.0'
+
+      def self.ensure_available!
+        Otto::OptionalDependency.require!(
+          'json_schemer',
+          JSON_SCHEMER_REQUIREMENT,
+          require_path: 'json_schemer',
+          feature: 'MCP JSON Schema validation',
+          alternative: 'Or pass `enable_validation: false` when enabling MCP.'
+        )
+      end
+
       def initialize
-        @schemas                = {}
-        @json_schemer_available = defined?(JSONSchemer)
+        self.class.ensure_available!
+        @schemas = {}
       end
 
       def validate_request(data)
-        return true unless @json_schemer_available
-
         schema            = mcp_request_schema
         validation_errors = schema.validate(data).to_a
 
@@ -36,7 +43,7 @@ class Otto
       end
 
       def validate_tool_arguments(tool_name, arguments, schema)
-        return true unless @json_schemer_available && schema
+        return true unless schema
 
         schemer           = JSONSchemer.schema(schema)
         validation_errors = schemer.validate(arguments).to_a
@@ -100,10 +107,11 @@ class Otto
 
       private
 
+      # Exact endpoint only, normalized as the router normalizes it (see
+      # Otto::MCP.endpoint_path?); sibling paths are never parsed or rejected.
       def mcp_endpoint?(env)
         endpoint = env['otto.mcp_http_endpoint'] || '/_mcp'
-        path     = env['PATH_INFO'].to_s
-        path.start_with?(endpoint)
+        Otto::MCP.endpoint_path?(env['PATH_INFO'], endpoint)
       end
 
       def validation_error_response(id, message)