otto 2.9.0 → 2.10.0

data/lib/otto/mcp/endpoint.rb

@@ -0,0 +1,41 @@
+# lib/otto/mcp/endpoint.rb
+#
+# frozen_string_literal: true
+
+require_relative '../utils'
+
+class Otto
+  # Model Context Protocol support.
+  module MCP
+    # Whether +path+ is the MCP endpoint +endpoint+: the one request the router
+    # dispatches to the MCP handler, and nothing else.
+    #
+    # The MCP route is a literal route. The router normalizes PATH_INFO with
+    # Otto::Utils.normalize_path and looks it up by exact equality, so it never
+    # dispatches a sibling path to the MCP handler. The throttles, the throttled
+    # responder, the log subscriber, the token middleware and the schema
+    # validator all used to classify by prefix (start_with?) instead: with MCP
+    # mounted at /a, every /admin request was counted by 'mcp_requests:/a' and
+    # could be answered with an MCP JSON-RPC 429, or a 401, for a path the MCP
+    # handler can never receive; with MCP at / that was every route in the app.
+    #
+    # Both sides go through the router's normalize_path, as LocalhostGuard does
+    # for the Caddy endpoint, so a trailing slash or percent-encoding on either
+    # side cannot make these guards and the router disagree about a request.
+    #
+    # Callers must pass PATH_INFO (Rack::Request#path_info), never
+    # Rack::Request#path, which prepends SCRIPT_NAME. The router matches on
+    # PATH_INFO alone, so when the host app mounts Otto under a prefix
+    # (`map '/api' { run otto }`) the endpoint /_mcp is dispatched for
+    # PATH_INFO=/_mcp while #path reads /api/_mcp and never matches.
+    #
+    # @param path [String, nil] raw PATH_INFO of the request
+    # @param endpoint [String, nil] configured MCP endpoint
+    # @return [Boolean]
+    def self.endpoint_path?(path, endpoint)
+      return false if endpoint.nil?
+
+      Otto::Utils.normalize_path(path) == Otto::Utils.normalize_path(endpoint)
+    end
+  end
+end

data/lib/otto/mcp/errors.rb

@@ -0,0 +1,15 @@
+# lib/otto/mcp/errors.rb
+#
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+class Otto
+  module MCP
+    # Raised by {Otto::MCP::Registry#call_tool} when the requested tool name is
+    # not registered. Distinct from a tool that exists but fails during
+    # execution: the former is a named-entity lookup failure (JSON-RPC -32002,
+    # HTTP 404), the latter an execution fault (-32603, HTTP 500).
+    class ToolNotFoundError < Otto::NotFoundError; end
+  end
+end

data/lib/otto/mcp/options.rb

@@ -0,0 +1,292 @@
+# lib/otto/mcp/options.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module MCP
+    # Normalization of MCP configuration options.
+    #
+    # Otto.new and Otto#enable_mcp! historically accepted different spellings
+    # of the same settings and the constructor dropped all but the endpoint
+    # (issue #258). Every path now funnels through {.normalize}.
+    #
+    # One vocabulary: the canonical keys, their +mcp_+-prefixed variants (the
+    # constructor needs a namespace inside an options hash that also
+    # configures the rest of Otto), and +tool_calls_per_minute+, which is the
+    # name the rate-limiting middleware itself uses. Bare generic names such
+    # as +endpoint+, +validation+ and +rate_limiting+ are NOT accepted:
+    # +rate_limiting:+ is Otto's own general rate-limiting option (a Hash),
+    # and the others were documented before #258 but never read.
+    #
+    # Two strictness rules, selected with the +scope+ argument:
+    #
+    # +:constructor+ (used by Otto.new / #configure_mcp)
+    #   The constructor forwards its ENTIRE options hash here, most of which
+    #   configures things other than MCP, so unrecognized keys are ignored.
+    #   Unknown +mcp_+-prefixed keys still fail loud, since such a key can
+    #   only have been meant for MCP.
+    #
+    # +:explicit+ (used by Otto#enable_mcp!)
+    #   The caller is configuring MCP and nothing else, so any unrecognized
+    #   key raises. That turns +enable_mcp!(auth_token: 'x')+ — a
+    #   singular-vs-plural typo that silently left the endpoint open — into a
+    #   boot failure.
+    #
+    # The +mcp_+-prefixed gating keys (+mcp_enabled+, +mcp_http+, +mcp_stdio+)
+    # decide *whether* MCP is enabled and are read by the constructor itself
+    # (Otto::Core::Configuration#configure_mcp) through {.gating_options}. The
+    # +:constructor+ scope tolerates them; the +:explicit+ scope rejects them,
+    # because +enable_mcp!(mcp_http: false)+ would otherwise be accepted and
+    # still mount the endpoint. Their values must be exactly +true+ or
+    # +false+: the constructor disables the endpoint on +mcp_http == false+,
+    # so a String +"false"+ (from +ENV.fetch+ or YAML) or +nil+ (from an
+    # unset +ENV[...]+) would otherwise mount it.
+    #
+    # Keys may be Strings or Symbols; they are symbolized before anything is
+    # read, so +"auth_tokens" => [...]+ configures authentication exactly like
+    # +auth_tokens:+. A String key and its Symbol twin are two spellings of one
+    # option and conflict when their values differ.
+    #
+    # Both scopes accept the canonical output of {.normalize}, so normalization
+    # is idempotent under either.
+    module Options
+      # Canonical MCP option keys and every accepted alias.
+      # @api private
+      OPTION_ALIASES = {
+                http_endpoint: %i[http_endpoint mcp_endpoint],
+                  auth_tokens: %i[auth_tokens mcp_auth_tokens],
+            enable_validation: %i[enable_validation mcp_validation],
+         enable_rate_limiting: %i[enable_rate_limiting mcp_rate_limiting],
+          requests_per_minute: %i[requests_per_minute mcp_requests_per_minute],
+             tools_per_minute: %i[tools_per_minute tool_calls_per_minute mcp_tool_calls_per_minute],
+        allow_unauthenticated: %i[allow_unauthenticated mcp_allow_unauthenticated],
+      }.freeze
+
+      # @api private
+      SCOPES = %i[constructor explicit].freeze
+
+      # Canonical defaults applied when no alias supplies a value.
+      # @api private
+      OPTION_DEFAULTS = {
+                http_endpoint: '/_mcp',
+                  auth_tokens: [].freeze,
+            enable_validation: true,
+         enable_rate_limiting: true,
+          requests_per_minute: 60,
+             tools_per_minute: 20,
+        allow_unauthenticated: false,
+      }.freeze
+
+      # +mcp_+-prefixed constructor keys that gate *whether* MCP is enabled
+      # rather than configure the server. Otto.new reads them itself, so the
+      # :constructor scope tolerates them (and never emits them). #enable_mcp!
+      # cannot honour them, so the :explicit scope rejects them.
+      # @api private
+      GATING_KEYS = %i[mcp_enabled mcp_http mcp_stdio].freeze
+
+      # Every key {.normalize} recognizes, per scope.
+      # @api private
+      RECOGNIZED_KEYS = {
+        constructor: (OPTION_ALIASES.values.flatten + GATING_KEYS).freeze,
+           explicit: OPTION_ALIASES.values.flatten.freeze,
+      }.freeze
+
+      # Normalize a constructor- or #enable_mcp!-style option hash into the
+      # single canonical shape consumed by {Otto::MCP::Server#enable!}.
+      #
+      # +scope+ is positional, not a keyword, so a brace-less hash at the call
+      # site (+normalize(auth_tokens: ['t'])+) binds to +opts+ as intended.
+      #
+      # @param opts [Hash] raw options; String and Symbol keys are equivalent
+      # @param scope [Symbol] :explicit (strict; the default) or :constructor
+      #   (permissive about non-MCP keys)
+      # @return [Hash] canonical hash with keys :http_endpoint, :auth_tokens,
+      #   :enable_validation, :enable_rate_limiting, :requests_per_minute,
+      #   :tools_per_minute, :allow_unauthenticated
+      # @raise [ArgumentError] on an unrecognized key, conflicting aliases or
+      #   String/Symbol spellings, values of the wrong type, or auth tokens
+      #   supplied but empty/blank
+      def self.normalize(opts = {}, scope = :explicit)
+        raise ArgumentError, "Unknown MCP option scope #{scope.inspect}; expected one of #{SCOPES.inspect}" unless SCOPES.include?(scope)
+
+        opts = symbolize_keys(opts.to_h)
+        reject_unrecognized_keys!(opts, scope)
+
+        canonical = OPTION_DEFAULTS.dup
+        OPTION_ALIASES.each do |key, key_aliases|
+          supplied = key_aliases.select { |a| opts.key?(a) }
+          next if supplied.empty?
+
+          values = supplied.map { |a| opts[a] }
+          raise_conflict!(key, supplied.map { |a| [a, opts[a]] }) if values.uniq.size > 1
+
+          canonical[key] = coerce_option(key, values.first)
+        end
+
+        canonical
+      end
+
+      # Read the constructor-only gating keys (+mcp_enabled+, +mcp_http+,
+      # +mcp_stdio+) with the same String/Symbol tolerance as {.normalize}.
+      #
+      # Otto.new decides *whether* to enable MCP from these before it
+      # normalizes the rest, and it used to read them as raw Symbol keys, so
+      # +Otto.new(nil, "mcp_enabled" => true)+ silently did nothing while the
+      # String-keyed +"auth_tokens"+ beside it was documented as accepted.
+      #
+      # Every gating value present must be exactly +true+ or +false+.
+      # #configure_mcp disables the HTTP endpoint only on +mcp_http == false+,
+      # so +mcp_http: ENV.fetch('MCP_HTTP', 'false')+ (a String, truthy) or
+      # +mcp_http: ENV['MCP_HTTP']+ with the variable unset (+nil+, not
+      # +false+) would each mount the endpoint the caller meant to disable.
+      # An explicit +nil+ is rejected rather than treated as absent for that
+      # reason, matching the other boolean options and +auth_tokens: nil+.
+      #
+      # @param opts [Hash, nil] raw constructor options
+      # @return [Hash{Symbol=>Boolean}] the gating keys present in +opts+
+      # @raise [ArgumentError] when a String key and its Symbol twin disagree,
+      #   or when a gating value is anything but +true+ or +false+ (including
+      #   the Strings +"true"+ / +"false"+, Integers and +nil+)
+      def self.gating_options(opts)
+        gating = symbolize_keys(opts.to_h).slice(*GATING_KEYS)
+        gating.each { |key, value| coerce_boolean!(key, value) }
+        gating
+      end
+
+      # Symbolize option keys once, so String-keyed options configure the
+      # server instead of passing the unrecognized-key guard (which already
+      # symbolized) and then being ignored by normalization — which is how
+      # +enable_mcp!("auth_tokens" => [...])+ served the endpoint without
+      # authentication.
+      #
+      # A String key and its Symbol twin are two spellings of one option: equal
+      # values collapse, differing values conflict. Keys that cannot be
+      # symbolized are kept as-is for the unrecognized-key guard.
+      # @api private
+      def self.symbolize_keys(opts)
+        seen = {} # symbolized key => [original spelling, value]
+        opts.each do |key, value|
+          sym = key.respond_to?(:to_sym) ? key.to_sym : key
+          raise_conflict!(sym, [seen[sym], [key, value]]) if seen.key?(sym) && seen[sym].last != value
+
+          seen[sym] = [key, value]
+        end
+
+        seen.transform_values(&:last)
+      end
+      private_class_method :symbolize_keys
+
+      # @api private
+      def self.raise_conflict!(key, spellings)
+        raise ArgumentError,
+              "Conflicting MCP options for #{key}: " \
+              "#{spellings.map { |spelling, value| "#{spelling.inspect}=#{value.inspect}" }.join(', ')}"
+      end
+      private_class_method :raise_conflict!
+
+      # Reject keys the given scope cannot accept.
+      #
+      # :explicit rejects anything unrecognized, including the constructor-only
+      # gating keys, which it explains by name. :constructor rejects only
+      # unrecognized +mcp_+-prefixed keys, because it is handed Otto's whole
+      # options hash and most keys legitimately belong to other subsystems.
+      # @api private
+      def self.reject_unrecognized_keys!(opts, scope)
+        recognized = RECOGNIZED_KEYS.fetch(scope)
+        unknown    = opts.keys.reject { |k| recognized.include?(k) }
+        unknown.select! { |k| k.to_s.start_with?('mcp_') } if scope == :constructor
+        return if unknown.empty?
+
+        message = "Unknown MCP option(s): #{unknown.map(&:inspect).join(', ')}. "
+        gating  = unknown & GATING_KEYS
+        unless gating.empty?
+          message += "#{gating.map(&:inspect).join(', ')} gate whether MCP is enabled and are " \
+                     'constructor-only: pass them to Otto.new. #enable_mcp! always enables the ' \
+                     'HTTP endpoint, so it cannot honour them. '
+        end
+
+        raise ArgumentError,
+              message + "Recognized MCP options (#{scope}): #{recognized.map(&:inspect).join(', ')}"
+      end
+      private_class_method :reject_unrecognized_keys!
+
+      # @api private
+      def self.coerce_option(key, value)
+        case key
+        when :auth_tokens
+          coerce_auth_tokens!(value)
+        when :enable_validation, :enable_rate_limiting, :allow_unauthenticated
+          coerce_boolean!(key, value)
+        when :requests_per_minute, :tools_per_minute
+          unless value.is_a?(Integer) && value.positive?
+            raise ArgumentError,
+                  "MCP #{key} must be a positive Integer, got #{value.inspect}"
+          end
+
+          value
+        when :http_endpoint
+          unless value.is_a?(String) && value.start_with?('/')
+            raise ArgumentError,
+                  "MCP http_endpoint must be a String path starting with '/', got #{value.inspect}"
+          end
+
+          value
+        else
+          value
+        end
+      end
+      private_class_method :coerce_option
+
+      # Coerce and validate the configured bearer tokens.
+      #
+      # A literal empty Array is the one accepted "no tokens" spelling: it is
+      # unambiguous, and it is what {.normalize} itself emits when the key is
+      # omitted, which keeps normalization idempotent. Every other empty shape
+      # (+nil+, +''+, +[nil]+, +['']+) raises, because those are what
+      # +auth_tokens: ENV['MCP_TOKEN']+ produces when the variable is unset —
+      # silently serving the endpoint to anyone.
+      # @api private
+      def self.coerce_auth_tokens!(value)
+        return [] if value.is_a?(Array) && value.empty?
+
+        tokens  = value.is_a?(String) ? [value] : Array(value)
+        invalid = tokens.grep_v(String)
+        unless invalid.empty?
+          raise ArgumentError,
+                "MCP auth_tokens must be Strings, got #{invalid.map(&:class).uniq.join(', ')}"
+        end
+
+        raise_empty_auth_tokens!(value) if tokens.empty?
+
+        blank = tokens.select { |token| token.strip.empty? }
+        unless blank.empty?
+          raise ArgumentError,
+                "MCP auth_tokens must not be blank, got #{blank.map(&:inspect).join(', ')}. " \
+                'A blank token cannot be presented by a client and would not protect the endpoint.'
+        end
+
+        tokens
+      end
+      private_class_method :coerce_auth_tokens!
+
+      # @api private
+      def self.raise_empty_auth_tokens!(value)
+        raise ArgumentError,
+              "MCP auth_tokens was supplied as #{value.inspect} but resolves to no tokens. " \
+              "This is what auth_tokens: ENV['MCP_TOKEN'] does when the variable is unset, " \
+              'and it would expose the MCP endpoint to any caller. Supply at least one token, ' \
+              'or omit auth_tokens entirely and pass allow_unauthenticated: true to serve the ' \
+              'endpoint without authentication on purpose.'
+      end
+      private_class_method :raise_empty_auth_tokens!
+
+      # @api private
+      def self.coerce_boolean!(key, value)
+        return value if [true, false].include?(value)
+
+        raise ArgumentError, "MCP #{key} must be true or false, got #{value.inspect}"
+      end
+      private_class_method :coerce_boolean!
+    end
+  end
+end

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