mcp_authorization 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79a43a7ab018242f92e8f0448f73ae5acbae410ebd7397868ec52553490a15ec
-  data.tar.gz: 2f41f4e5cfc4a923b26636551f25facf94c2c902be106ea19235a0c46b68dae6
+  metadata.gz: dbd953dcd628ffaf2d42d3bfa024ed6e6ab5a0b8a1089be84f8505a7158aaf20
+  data.tar.gz: e510d9b492abbdbc4acb091a0a802dea803b97434923673b16711215de918d38
 SHA512:
-  metadata.gz: 07fc7850bfa4960c00aee35f3543e907d5b1037ffe4b45a46b247e002d3d9a8271d4a7070746c031a2cd03d498a93a496bf1a74c998f17c1023fe361f416e27b
-  data.tar.gz: f83d36ff6ff7b43fffad639f8e81790a20c450959fe1cadb5d009ff39dee41464199e9d636ad1e1048d32e053eba84b4239d915e9837fcde11a495eb48361642
+  metadata.gz: 71272e773f2cba13d99a1b44fb94ad53e1de079627a5546432d39bb0de0c166a047edd95ab60e43072f91c008121b16ad7bdb3548b01ebde5ffee80305323ada
+  data.tar.gz: 9e06ca547f65de3b44de14e2538b54ff24d53db6b686faf63195dd1490a88d6d20ba831f28cc69eb0ea14fd266150fe9121380a073df39279ffbdceeb443c0e0

data/CHANGELOG.md

@@ -4,6 +4,63 @@ All notable changes to this gem are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] - 2026-05-26
+
+### Changed (BREAKING)
+- **Prefix optional marker (`?key:`) is now honored consistently across all three RBS parsers.**
+
+  The three sibling parsers handled optional-field markers inconsistently:
+  - `parse_call_params` — accepted only prefix `?key:`
+  - `compile_tagged_record` — accepted only suffix `key?:`, silently treated prefix `?key:` as required
+  - `parse_record_type` — recognized neither form, silently treated all fields as required
+
+  The README documents prefix as canonical ("Prefix a param with `?` to mark it optional"), so handlers that followed the docs got unexpectedly-required fields in their compiled schemas.
+
+  **Effect on consumers:** any field declared with prefix `?key:` in a `# @rbs type input = { ... }` record, a nested/aliased record (`# @rbs type foo = { ?bar: ... }`), or an inline record inside a `#:` signature is now correctly marked optional in the JSON Schema (omitted from `required`). For a consuming monolith with ~616 such fields, the schema's `required` array shrinks accordingly and clients (e.g. LLMs producing tool calls) will no longer treat these fields as mandatory.
+
+  **If you relied on the buggy behavior** (prefix marker silently making the field required), declare the field with no marker (`key:`) to keep it required, or enforce presence inside `#call`.
+
+### Deprecated
+- **Suffix optional marker (`key?:`) is deprecated; will be removed in 0.6.0.** Suffix `key?:` continues to work in 0.5.0 (record types, call signatures, and nested aliased records) but now emits a single `Kernel#warn` per use with `category: :deprecated`. Silence with `Warning[:deprecated] = false` or `ruby -W:no-deprecated`. The warning embeds the handler's source-file path because the annotation is parsed as static text — the offending file is not on the Ruby call stack when the warning is emitted, so `uplevel:` cannot surface it.
+
+### Added
+- `RbsSchemaCompiler.parse_field_name(raw, source_file: nil)` — internal helper that turns a raw field-name token (everything before the `:`) into `[clean_name, optional?]`. Single source of truth for the three parsers. Raises `ArgumentError` on malformed input (empty, bare `"?"`, double-marked `"?key?"`, `"??key"`, `"key??"`). Tolerates whitespace around the marker (`" ? key"` → `["key", true]`).
+
+### Fixed
+- `parse_record_type` now recognizes optional markers at all. Previously, nested aliased record types like `# @rbs type foo = { ?bar: ... }` produced schemas where every field landed in `required` regardless of the marker. Caught only because the same bug existed in the sibling parsers under different shapes, hiding the test gap.
+
+### Migration notes
+- **No code changes required.** Suffix `key?:` annotations keep parsing; you'll see a deprecation warning per call site on first cache build of each handler. Migrate to prefix `?key:` at your own pace before 0.6.0.
+- If you've been relying on prefix `?key:` being silently treated as required (the buggy behavior), audit your schemas: declared-optional fields that the handler still requires must be enforced inside `#call`, not by the schema.
+- The README example in the records section was updated to use prefix `?count: Integer` to match the documented canonical form.
+
+### Notes
+- The `fountain/monolith` consumer (gem's primary downstream) has a separate migration PR tracking the suffix→prefix rewrite for ~616 affected fields, including `sig/shared/option_bank_result.rbs` and friends. That work is out of scope for this gem release and will land in the monolith repo once it bumps the `mcp_authorization` gem to 0.5.0+.
+
+## [0.4.0] - 2026-05-21
+
+### Added
+- **Tool-level generic predicate gates.** `Tool` subclasses can now declare any number of `gate :predicate_name, :value` calls in addition to `authorization :perm`. The gate is evaluated at request time by calling `server_context.{predicate_name}?(value)`; if any gate returns false, the tool is hidden from `tools/list` and rejected from `tools/call`. This is the tool-level counterpart of the field-level `@predicate(:value)` system introduced in 0.3.0 — same semantics, same fail-open + error-isolation behavior, same backward-compat fallback for `gate :requires`.
+
+  ```ruby
+  class BulkSendSmsTool < McpAuthorization::Tool
+    authorization :communications  # RBAC permission (existing behavior preserved)
+    gate :feature, :sms            # hide tool unless current_account.sms_enabled?
+    gate :requires, :super_user    # extra check beyond authorization
+  end
+  ```
+
+- `McpAuthorization::Diagnostics` module — shared helper for the development-mode "Did you mean?" warning previously duplicated between field-level (`@predicate`) and tool-level (`gate`) sites. Single Levenshtein implementation, single warning phrasing per call site (`gate :feture, :sms` warns "Did you mean gate :feature?", `@feture(:sms)` warns "Did you mean @feature?").
+
+### Changed
+- **`authorization` migrated to the generic gate pipeline.** `authorization :perm` is now a convenience alias for `gate :requires, :perm`. The legacy dual-path in `Tool.permitted?` (one branch for `_permission`, another for gates) is gone; there is one pipeline now. Mirrors the field-level migration done in 0.3.0 (#12), where `@requires` was migrated through the same generic predicate pipeline rather than carrying its own special-cased branch. `_permission` remains exposed as before for introspection.
+- `permitted?(nil_context)` now denies when gates are declared (previously crashed). A nil context reaching `permitted?` is a programmer error; fail-closed avoids silently exposing the tool.
+
+### Migration notes
+- No breaking changes for end users. Tools that use `authorization :perm` continue to work exactly as before — the only difference is the internal pipeline.
+- If you read `tool_class._permission` for introspection, it still returns the declared symbol.
+- Existing field-level `@requires`/`@feature` semantics are unchanged.
+
 ## [0.3.0] - 2026-05-14
 
 ### Added

data/README.md

@@ -10,11 +10,11 @@ The gem gives you three independent controls over what each user sees:
 
 | Layer | Mechanism | Effect |
 |---|---|---|
-| **Tool visibility** | `authorization :manage_workflows` on the tool class | Tool hidden entirely from users who lack the flag |
-| **Input fields** | `@requires(:backward_routing)` on a param in `#:` annotation | Field excluded from the input schema *and* stripped from inbound params at call time |
-| **Output variants** | `@requires(:backward_routing)` on a variant in `@rbs type output` | Variant excluded from the `oneOf` *and* fields projected out of the handler's return value before it crosses the wire |
+| **Tool visibility** | `authorization :manage_workflows` (RBAC) or `gate :feature, :sms` (any predicate) on the tool class | Tool hidden entirely from users who fail any check |
+| **Input fields** | `@requires(:backward_routing)` or `@feature(:sms)` on a param in `#:` annotation | Field excluded from the input schema *and* stripped from inbound params at call time |
+| **Output variants** | `@requires(:backward_routing)` or `@feature(:sms)` on a variant in `@rbs type output` | Variant excluded from the `oneOf` *and* fields projected out of the handler's return value before it crosses the wire |
 
-All three go through the same predicate: `current_user.can?(:symbol)`. The symbol can represent a permission, a feature flag, a plan tier, an A/B bucket -- whatever your app puts behind it.
+Tool-level `authorization :perm` is RBAC (calls `current_user.can?`). Tool-level `gate :predicate, :value` and the field-level annotations are generic — any predicate name works, as long as the server context implements `{predicate}?(value)`. See [Generic predicate tags](#generic-predicate-tags) below.
 
 ### Enforcement, not just shaping
 
@@ -287,7 +287,9 @@ Shared types define **shapes**. Authorization (`@requires`) stays on the handler
 ```ruby
 class MyTool < McpAuthorization::Tool
   tool_name "my_tool"
-  authorization :some_flag        # tool hidden when can?(:some_flag) is false
+  authorization :some_flag        # RBAC: hidden unless current_user.can?(:some_flag)
+  gate :feature, :order_tracking  # any predicate: hidden unless server_context.feature?(:order_tracking)
+  gate :tier, :enterprise         # multiple gates AND together
   tags "recruiting", "operations" # which domains this tool appears in
   read_only!                      # MCP annotation hints
   dynamic_contract MyService      # handler class
@@ -297,7 +299,8 @@ end
 | Method | Purpose |
 |---|---|
 | `tool_name "name"` | MCP tool name |
-| `authorization :sym` | Tool-level visibility gate. Omit for public tools. |
+| `authorization :sym` | Tool-level RBAC visibility gate. Convenience alias for `gate :requires, :sym` — routes through the generic gate pipeline and falls back to `current_user.can?(:sym)` when the server context lacks a `requires?` method. Omit for public tools. |
+| `gate :predicate, :value` | Tool-level generic predicate gate. Calls `server_context.{predicate}?(value)`. Repeat for AND. Fail-open when the predicate method is missing (warning logged in dev). |
 | `tags "domain1", ...` | Domain(s) this tool appears under. Defaults to `["default"]`. |
 | `dynamic_contract HandlerClass` | Handler providing description, schemas, and execution |
 | `read_only!` | Annotation: tool only reads data |
@@ -307,6 +310,8 @@ end
 | `open_world!` | Annotation: tool may access external services |
 | `closed_world!` | Annotation: tool stays within the system |
 
+`authorization :perm` is just a convenience for `gate :requires, :perm` — internally there is one gate pipeline, not two. Multiple `gate` declarations AND together with `authorization`: the tool is shown only when every check passes. This makes tool-level gating symmetric with the field-level annotations (`@requires`, `@feature`, any custom predicate).
+
 Tools self-register when loaded. Put them anywhere under `tool_paths` (default: `app/mcp/`).
 
 ## Contract validation
@@ -375,9 +380,9 @@ The `@rbs type` comments compile to JSON Schema:
 # @rbs type result = {
 #   success: bool,
 #   message: String,
-#   count?: Integer
+#   ?count: Integer
 # }
-# (count? is optional -- excluded from "required")
+# (?count is optional -- excluded from "required")
 
 # Arrays
 # @rbs type items = Array[String]
@@ -455,6 +460,26 @@ def beta?(flag) = current_account.beta_enrolled?(flag.to_s)
 
 Multiple predicates on the same field are AND-ed — all must pass for the field to appear.
 
+### Tool-level gates
+
+The same predicate vocabulary is available at the **tool wrapper** level via `gate :predicate, :value`:
+
+```ruby
+class BulkSendSmsTool < McpAuthorization::Tool
+  authorization :communications  # RBAC permission
+  gate :feature, :sms            # hide tool unless account has SMS configured
+  gate :requires, :super_user    # extra RBAC check beyond authorization
+end
+```
+
+`gate` is the tool-level counterpart of `@predicate(:value)` on a field. Semantics:
+
+- Calls `server_context.{predicate_name}?(value)` at request time.
+- All gates AND together with `authorization`. The tool is shown only when every check passes.
+- Fail-open when the predicate method is missing on the server context (warning logged in development).
+- `gate :requires, :perm` falls back to `current_user.can?(:perm)` when the context lacks a `requires?` method (matching the field-level backward-compat path).
+- Exceptions raised by a predicate are rescued and logged — a broken predicate never crashes `tools/list`.
+
 **Niche:**
 
 | Tag | JSON Schema |

data/lib/mcp_authorization/diagnostics.rb

@@ -0,0 +1,84 @@
+module McpAuthorization
+  # Shared diagnostic helpers used by both the field-level
+  # +RbsSchemaCompiler#predicate_excluded?+ and the tool-level
+  # +Tool#gates_pass?+ paths.
+  #
+  # Lives in its own module so the two predicate sites — field-level
+  # (compile time) and tool-level (request time) — share a single
+  # "Did you mean?" warning implementation. Avoids two copies of
+  # Levenshtein drifting.
+  module Diagnostics
+    module_function
+
+    # Emit a development-mode warning when a predicate method is not
+    # found on the server context. Helps catch typos like
+    # +@feture(:x)+ or +gate :feture, :sms+.
+    #
+    # @param name [String, Symbol] The predicate name attempted (e.g. +"feature"+ or +:gate+).
+    # @param server_context [Object] The context the predicate was looked up on.
+    # @param site [Symbol] +:field+ or +:tool+ — controls the suggestion phrasing.
+    # @return [void]
+    #: (String | Symbol, untyped, Symbol) -> void
+    def warn_unknown_predicate(name, server_context, site:)
+      return unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
+
+      str = name.to_s
+      available = server_context.class.public_instance_methods(true)
+        .select { |m| m.to_s.end_with?("?") }
+        .map { |m| m.to_s.chomp("?") }
+      best = available.min_by { |a| levenshtein(a, str) }
+      suggestion = best && levenshtein(best, str) <= 3 ? best : nil
+
+      hint =
+        case site
+        when :tool  then suggestion ? " Did you mean gate :#{suggestion}?" : ""
+        when :field then suggestion ? " Did you mean @#{suggestion}?" : ""
+        else             suggestion ? " Did you mean #{suggestion}?" : ""
+        end
+
+      surface =
+        case site
+        when :tool  then "Gate predicate"
+        when :field then "Predicate"
+        else             "Predicate"
+        end
+
+      fallthrough =
+        case site
+        when :tool  then "Tool will be shown to all users."
+        when :field then "Field will be shown to all users."
+        else             ""
+        end
+
+      Rails.logger&.warn(
+        "[McpAuthorization] #{surface} '#{str}?' not found on #{server_context.class}.#{hint} #{fallthrough}".strip
+      )
+    end
+
+    # Minimal Levenshtein distance for typo suggestions.
+    #
+    # Iterative two-row implementation — O(m*n) time, O(m) extra space.
+    # Used only in development for "Did you mean?" suggestions, so the
+    # naive version is fine.
+    #
+    # @param a [String]
+    # @param b [String]
+    # @return [Integer]
+    #: (String, String) -> Integer
+    def levenshtein(a, b)
+      m, n = a.length, b.length
+      d = Array.new(m + 1) { |i| i }
+      (1..n).each do |j|
+        prev = d[0]
+        d[0] = j
+        (1..m).each do |i|
+          cost = a[i - 1] == b[j - 1] ? 0 : 1
+          temp = d[i]
+          d[i] = [d[i] + 1, d[i - 1] + 1, prev + cost].min
+          prev = temp
+        end
+      end
+      d[m]
+    end
+  end
+end

data/lib/mcp_authorization/rbs_schema_compiler.rb

@@ -1,3 +1,5 @@
+require_relative "diagnostics"
+
 module McpAuthorization
   # Compiles RBS-style type annotations in Ruby source files into JSON Schema,
   # with per-request filtering based on +@requires+ permission tags.
@@ -56,7 +58,7 @@ module McpAuthorization
         cached = cache_for(handler_class)
 
         schema = if cached[:raw_input]&.dig(:kind) == :record
-          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context)
+          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context, source_file: cached[:source_file])
         else
           build_input_schema(
             filter_call_signature(cached[:call_params], cached[:type_map], server_context)
@@ -204,7 +206,7 @@ module McpAuthorization
         cached = cache_for(handler_class)
 
         schema = if cached[:raw_input]&.dig(:kind) == :record
-          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context)
+          compile_tagged_record(cached[:raw_input][:body], cached[:type_map], server_context, source_file: cached[:source_file])
         else
           build_input_schema(
             filter_call_signature(cached[:call_params], cached[:type_map], server_context)
@@ -427,6 +429,93 @@ module McpAuthorization
         [type_str, tags]
       end
 
+      # Parse a field-name token (the part before +:+ in a record entry or
+      # call signature parameter) into its clean name and an optional flag.
+      #
+      # Recognizes both forms:
+      # - Prefix (RBS canonical, per README):     +?name:+ -> ["name", true]
+      # - Suffix (legacy, deprecated for 0.6.0):  +name?:+ -> ["name", true]
+      # - Unmarked:                                +name:+  -> ["name", false]
+      #
+      # The suffix form was historically accepted by parts of this gem
+      # but is not standard RBS. Recognizing it consistently across all
+      # three parsers (this method's callers) preserves backward
+      # compatibility while a single +Kernel#warn+ with
+      # +category: :deprecated+ steers consumers toward the prefix form.
+      # Users can silence via +Warning[:deprecated] = false+ or
+      # +-W:no-deprecated+ — the standard Ruby mechanisms.
+      #
+      # Raises +ArgumentError+ on malformed tokens. The helper produces
+      # three distinct error messages — categories grouped by which
+      # branch raises:
+      # - empty, whitespace-only, or nil input -> "empty field name"
+      # - double-marked optional after stripping (e.g. +"?key?"+) ->
+      #   "is double-marked optional"
+      # - any other shape that does not reduce to a bare +\w+
+      #   identifier (e.g. +"?"+, +"??key"+, +"key??"+, or tokens with
+      #   non-word characters) -> "invalid field name token"
+      #
+      # Whitespace adjacent to the marker is tolerated:
+      # +" ? key"+ -> ["key", true]. (Note: the three production call
+      # sites never produce such a token — their regexes don't permit
+      # internal whitespace — so this tolerance only matters if the
+      # helper is invoked directly.)
+      #
+      # @param raw [String] Token before the +:+ separator.
+      # @param source_file [String, nil] Path included in the deprecation
+      #   warning so consumers can locate the offending annotation. The
+      #   handler source file is read as text during parsing, so it is
+      #   not on the Ruby call stack — embedding the path in the message
+      #   is the only way to make the warning actionable.
+      # @return [Array(String, Boolean)] +[clean_name, optional?]+.
+      #: (String, ?source_file: String?) -> [String, bool]
+      def parse_field_name(raw, source_file: nil)
+        raise ArgumentError, "empty field name" if raw.nil? || raw.to_s.strip.empty?
+
+        trimmed = raw.to_s.strip
+        prefix = trimmed.start_with?("?")
+        suffix = trimmed.end_with?("?")
+
+        bare = trimmed
+        bare = bare.sub(/\A\?/, "").strip if prefix
+        bare = bare.sub(/\?\z/, "").strip if suffix
+
+        unless bare.match?(/\A\w+\z/)
+          raise ArgumentError, "invalid field name token: #{raw.inspect}"
+        end
+
+        if prefix && suffix
+          raise ArgumentError,
+            "field #{bare.inspect} is double-marked optional (both ?prefix and suffix?); pick one"
+        end
+
+        warn_deprecated_suffix_marker(bare, source_file) if suffix
+
+        [bare, prefix || suffix]
+      end
+
+      # Emit a deprecation warning for the legacy suffix optional marker
+      # (+key?:+). Uses +Kernel#warn+ with +category: :deprecated+ so
+      # silencing follows the standard Ruby mechanism
+      # (+Warning[:deprecated] = false+, +-W:no-deprecated+) and not a
+      # gem-specific env var.
+      #
+      # The source file path is embedded in the message because the
+      # handler annotation is parsed as static text — the offending file
+      # is not on the Ruby call stack at warn time, so +uplevel:+ cannot
+      # surface it. Embedding the path keeps the warning actionable for
+      # consumers grepping for the field name.
+      #: (String, String?) -> void
+      def warn_deprecated_suffix_marker(name, source_file)
+        location = source_file ? " (in #{source_file})" : ""
+        Kernel.warn(
+          "[mcp_authorization] Deprecated optional marker syntax: " \
+          "`#{name}?:`#{location}. Use prefix form `?#{name}:` instead. " \
+          "The suffix form will be removed in 0.6.0.",
+          category: :deprecated
+        )
+      end
+
       # Coerce a default value string from an annotation into its Ruby type.
       # Handles booleans, nil/null, integers, floats, and bare strings.
       #
@@ -540,14 +629,14 @@ module McpAuthorization
 
         # Build type map: shared imports first, then handler's own types override
         imported = load_imports(content)
-        local = parse_type_aliases(content)
+        local = parse_type_aliases(content, source_file: source_file)
         type_map = imported.merge(local)
 
         {
           type_map: type_map,
           raw_input: find_raw_type_body(content, "input"),
           raw_output: find_raw_type_body(content, "output"),
-          call_params: parse_call_params(content),
+          call_params: parse_call_params(content, source_file: source_file),
           source_file: source_file
         }
       end
@@ -602,35 +691,12 @@ module McpAuthorization
       end
 
       # Emit a development-mode warning when a predicate method is not
-      # found on the server_context. Helps catch typos like @feture(:x).
+      # found on the server_context. Delegates to the shared diagnostic
+      # helper so the field-level (+@predicate+) and tool-level (+gate+)
+      # warning shapes stay in sync.
       #: (String, untyped) -> void
       def warn_unknown_predicate(name, server_context)
-        return unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
-
-        available = server_context.class.public_instance_methods(true)
-          .select { |m| m.to_s.end_with?("?") }
-          .map { |m| m.to_s.chomp("?") }
-        best = available.min_by { |a| levenshtein(a, name) }
-        hint = best && levenshtein(best, name) <= 3 ? " Did you mean @#{best}?" : ""
-        Rails.logger&.warn("[McpAuthorization] Predicate '#{name}?' not found on #{server_context.class}.#{hint} Field will be shown to all users.")
-      end
-
-      # Minimal Levenshtein distance for typo suggestions.
-      #: (String, String) -> Integer
-      def levenshtein(a, b)
-        m, n = a.length, b.length
-        d = Array.new(m + 1) { |i| i }
-        (1..n).each do |j|
-          prev = d[0]
-          d[0] = j
-          (1..m).each do |i|
-            cost = a[i - 1] == b[j - 1] ? 0 : 1
-            temp = d[i]
-            d[i] = [d[i] + 1, d[i - 1] + 1, prev + cost].min
-            prev = temp
-          end
-        end
-        d[m]
+        McpAuthorization::Diagnostics.warn_unknown_predicate(name, server_context, site: :field)
       end
 
       # Compile a record-style input type (+# @rbs type input = { ... }+)
@@ -643,24 +709,23 @@ module McpAuthorization
       # @param type_map [Hash] Resolved type definitions for +$ref+ lookups.
       # @param server_context [Object] Per-request context.
       # @return [Hash] JSON Schema object with +properties+, +required+, etc.
-      #: (String, Hash[String, Hash[Symbol, untyped]], untyped) -> Hash[Symbol, untyped]
-      def compile_tagged_record(raw_body, type_map, server_context)
+      #: (String, Hash[String, Hash[Symbol, untyped]], untyped, ?source_file: String?) -> Hash[Symbol, untyped]
+      def compile_tagged_record(raw_body, type_map, server_context, source_file: nil)
         properties = {}
         required = []
         dependent_required = {}
 
         inner = raw_body.strip.sub(/\A\{/, "").sub(/\}\z/, "").strip
 
-        inner.scan(/(\w+\??)\s*:\s*([^,}]+)/) do |match|
+        inner.scan(/(\??\w+\??)\s*:\s*([^,}]+)/) do |match|
           key, type_str = match[0].to_s, match[1].to_s
           type_str, tags = extract_tags(type_str.strip)
 
           next if predicate_excluded?(tags, server_context)
 
-          optional = key.end_with?("?")
-          clean_key = key.delete_suffix("?")
+          clean_key, optional = parse_field_name(key, source_file: source_file)
 
-          schema = rbs_type_to_json_schema(type_str, type_map)
+          schema = rbs_type_to_json_schema(type_str, type_map, source_file: source_file)
           properties[clean_key.to_sym] = apply_tags(schema, tags, server_context: server_context)
           required << clean_key unless optional
 
@@ -849,7 +914,7 @@ module McpAuthorization
         resolved = {}
         aliases.each do |name, value|
           resolved[name] = if value.is_a?(String)
-            parse_record_type(value, resolved.merge(aliases_to_schemas(aliases, resolved)))
+            parse_record_type(value, resolved.merge(aliases_to_schemas(aliases, resolved)), source_file: path)
           else
             value
           end
@@ -933,8 +998,8 @@ module McpAuthorization
       #
       # @param content [String] Full source file contents.
       # @return [Hash{String => Hash}] Type name → resolved JSON Schema.
-      #: (String) -> Hash[String, Hash[Symbol, untyped]]
-      def parse_type_aliases(content)
+      #: (String, ?source_file: String?) -> Hash[String, Hash[Symbol, untyped]]
+      def parse_type_aliases(content, source_file: nil)
         return {} if content.empty?
 
         aliases = {}
@@ -961,7 +1026,7 @@ module McpAuthorization
         resolved = {}
         aliases.each do |name, value|
           resolved[name] = if value.is_a?(String)
-            parse_record_type(value, resolved.merge(aliases_to_schemas(aliases, resolved)))
+            parse_record_type(value, resolved.merge(aliases_to_schemas(aliases, resolved)), source_file: source_file)
           else
             value
           end
@@ -982,8 +1047,8 @@ module McpAuthorization
       #
       # @param content [String] Full source file contents.
       # @return [Array<Hash>] Parameter descriptors.
-      #: (String) -> Array[Hash[Symbol, untyped]]
-      def parse_call_params(content)
+      #: (String, ?source_file: String?) -> Array[Hash[Symbol, untyped]]
+      def parse_call_params(content, source_file: nil)
         return [] if content.empty?
 
         lines = content.lines
@@ -1001,8 +1066,10 @@ module McpAuthorization
         if annotation =~ /\((.+)\)\s*->/m
           $1.to_s.split(",").each do |param|
             param = param.strip
-            next unless param =~ /\A(\?)?([\w]+):\s*(.+)\z/
-            opt, name, type = $1, $2.to_s, $3.to_s.strip
+            next unless param =~ /\A(\??\w+\??):\s*(.+)\z/
+            raw_key, type = $1.to_s, $2.to_s.strip
+
+            name, optional = parse_field_name(raw_key, source_file: source_file)
             next if name == "server_context"
 
             type, tags = extract_tags(type)
@@ -1010,7 +1077,7 @@ module McpAuthorization
             params << {
               name: name,
               type: type,
-              required: opt.nil? && !type.end_with?("?"),
+              required: !optional && !type.end_with?("?"),
               tags: tags
             }
           end
@@ -1042,20 +1109,19 @@ module McpAuthorization
       # @param body [String] Record body including surrounding braces.
       # @param type_map [Hash] Resolved types for reference lookups.
       # @return [Hash] JSON Schema object with +properties+ and +required+.
-      #: (String, ?Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]
-      def parse_record_type(body, type_map = {})
+      #: (String, ?Hash[String, Hash[Symbol, untyped]], ?source_file: String?) -> Hash[Symbol, untyped]
+      def parse_record_type(body, type_map = {}, source_file: nil)
         properties = {}
         required = []
 
         inner = body.strip.sub(/\A\{/, "").sub(/\}\z/, "").strip
 
-        inner.scan(/(\w+):\s*([^,}]+)/) do |match|
+        inner.scan(/(\??\w+\??)\s*:\s*([^,}]+)/) do |match|
           key, type_str = match[0].to_s, match[1].to_s
           type_str, tags = extract_tags(type_str.strip)
-          optional = key.end_with?("?")
-          clean_key = key.delete_suffix("?")
+          clean_key, optional = parse_field_name(key, source_file: source_file)
 
-          schema = rbs_type_to_json_schema(type_str, type_map)
+          schema = rbs_type_to_json_schema(type_str, type_map, source_file: source_file)
           properties[clean_key.to_sym] = apply_tags(schema, tags)
           required << clean_key unless optional
         end
@@ -1078,8 +1144,8 @@ module McpAuthorization
       # @param rbs_type [String] RBS type expression.
       # @param type_map [Hash] Resolved type definitions for named type lookups.
       # @return [Hash] JSON Schema hash.
-      #: (String, ?Hash[String, Hash[Symbol, untyped]]) -> Hash[Symbol, untyped]
-      def rbs_type_to_json_schema(rbs_type, type_map = {})
+      #: (String, ?Hash[String, Hash[Symbol, untyped]], ?source_file: String?) -> Hash[Symbol, untyped]
+      def rbs_type_to_json_schema(rbs_type, type_map = {}, source_file: nil)
         stripped = rbs_type.strip
         case stripped
         when "String"
@@ -1095,17 +1161,17 @@ module McpAuthorization
         when "false"
           { type: "boolean", const: false }
         when /\AArray\[(.+)\]\z/
-          { type: "array", items: rbs_type_to_json_schema($1.to_s, type_map) }
+          { type: "array", items: rbs_type_to_json_schema($1.to_s, type_map, source_file: source_file) }
         when /\A(\w+)\?\z/
-          rbs_type_to_json_schema($1.to_s, type_map)
+          rbs_type_to_json_schema($1.to_s, type_map, source_file: source_file)
         when /\A\{/
-          parse_record_type(stripped, type_map)
+          parse_record_type(stripped, type_map, source_file: source_file)
         when /\|/
           parts = stripped.split("|").map(&:strip)
           if parts.all? { |p| p.start_with?('"') && p.end_with?('"') }
             { type: "string", enum: parts.map { |p| p.delete('"') } }
           else
-            { oneOf: parts.map { |p| rbs_type_to_json_schema(p, type_map) } }
+            { oneOf: parts.map { |p| rbs_type_to_json_schema(p, type_map, source_file: source_file) } }
           end
         else
           type_map[stripped] || { type: "string" }

data/lib/mcp_authorization/tool.rb

@@ -1,3 +1,5 @@
+require_relative "diagnostics"
+
 module McpAuthorization
   # Base class for MCP tools with schema-shaping authorization.
   #
@@ -10,13 +12,18 @@ module McpAuthorization
   #
   #   class Tools::ListOrders < McpAuthorization::Tool
   #     tool_name "list_orders"
-  #     authorization :view_orders
+  #     authorization :view_orders     # RBAC permission (legacy, still supported)
+  #     gate :feature, :order_tracking # generic predicate gate (any predicate name)
   #     tags "operator", "fulfillment"
   #     read_only!
   #
   #     dynamic_contract Handlers::ListOrders
   #   end
   #
+  # Both +authorization+ and any number of +gate+ declarations contribute to
+  # visibility — the tool is shown only when every check passes. See
+  # +permitted?+ for the resolution order.
+  #
   class Tool < MCP::Tool
     class NotAuthorizedError < StandardError; end
 
@@ -27,6 +34,9 @@ module McpAuthorization
       #: Array[String]?
       attr_reader :_tags
 
+      #: Array[Hash[Symbol, untyped]]?
+      attr_reader :_gates
+
       #: untyped
       attr_reader :_contract_handler
 
@@ -36,10 +46,23 @@ module McpAuthorization
         McpAuthorization::ToolRegistry.register(subclass)
       end
 
-      # Declare the permission flag required to see this tool.
+      # Declare the RBAC permission flag required to see this tool.
+      #
+      # Convenience alias for +gate :requires, permission+. The generic
+      # gate pipeline handles dispatch — calling
+      # +server_context.requires?(permission)+ when defined, otherwise
+      # falling back to +current_user.can?(permission)+. This mirrors the
+      # field-level migration done in 0.3.0 (#12): +@requires+ also went
+      # through the generic predicate pipeline rather than carrying its
+      # own special-cased branch.
+      #
+      # +_permission+ remains exposed for introspection — the value is
+      # written there as before — but the actual gating goes through the
+      # gate list at +permitted?+ time, just like every other check.
       #: (Symbol) -> void
       def authorization(permission)
         @_permission = permission
+        gate :requires, permission
       end
 
       # Declare which MCP domains this tool belongs to.
@@ -48,6 +71,30 @@ module McpAuthorization
         @_tags = list.flatten
       end
 
+      # Declare a generic predicate gate that must pass for this tool to be
+      # visible. The gate calls +server_context.{predicate}?(value)+ at
+      # request time. If the predicate returns false, the tool is hidden
+      # from +tools/list+ and rejected from +tools/call+.
+      #
+      # Mirrors the field-level +@predicate(:value)+ system: any predicate
+      # name works, as long as the +server_context+ implements
+      # +{predicate}?(value)+.
+      #
+      #   class BulkSendSmsTool < McpAuthorization::Tool
+      #     authorization :communications  # RBAC (existing)
+      #     gate :feature, :sms            # hide tool unless account has SMS configured
+      #     gate :requires, :super_user    # extra RBAC check beyond authorization
+      #   end
+      #
+      # Multiple +gate+ calls AND together — every gate must pass.
+      #
+      # @param predicate_name [Symbol] Predicate name; resolved to +{predicate_name}?+ on the context.
+      # @param value [Symbol, String] Argument passed to the predicate method.
+      #: (Symbol, untyped) -> void
+      def gate(predicate_name, value)
+        (@_gates ||= []) << { name: predicate_name.to_sym, value: value }
+      end
+
       # MCP annotation hint shorthands
       #: () -> void
       def read_only!;       merge_annotations(read_only_hint: true) end
@@ -94,10 +141,17 @@ module McpAuthorization
       end
 
       # Check whether the current user is allowed to see this tool.
+      #
+      # Evaluates every declared gate against the server context. A tool
+      # is permitted only when every gate passes. With no gates declared,
+      # the tool is unconditionally visible.
+      #
+      # +authorization :perm+ contributes a +gate :requires, :perm+
+      # internally, so it goes through the same pipeline as every other
+      # predicate. There is one code path for gating, not two.
       #: (untyped) -> bool
       def permitted?(server_context)
-        return true if _permission.nil?
-        server_context.current_user.can?(_permission)
+        gates_pass?(server_context)
       end
 
       # Build the full MCP tool definition hash for +tools/list+.
@@ -187,6 +241,57 @@ module McpAuthorization
 
       private
 
+      # Evaluate all declared +gate+ predicates against the server context.
+      # Returns true if every gate passes.
+      #
+      # No gates declared → permissive (tool is public). Gates declared
+      # but no server context → deny (a programmer error reaching this
+      # method should not silently expose the tool).
+      #
+      # Symmetric with field-level +RbsSchemaCompiler#predicate_excluded?+:
+      # - Unknown predicate (server_context does not implement +{name}?+):
+      #   fail-open per-gate (gate passes, tool shown). A warning is
+      #   logged in development environments.
+      # - +requires+ predicate without a +requires?+ method: backward-compat
+      #   fallback to +current_user.can?(value)+.
+      # - Predicate raises an exception: fail-open per-gate and log.
+      #: (untyped) -> bool
+      def gates_pass?(server_context)
+        return true if _gates.nil? || _gates.empty?
+        return false unless server_context # gates declared + nil context → deny
+        _gates.all? { |gate| evaluate_gate(gate, server_context) }
+      end
+
+      #: (Hash[Symbol, untyped], untyped) -> bool
+      def evaluate_gate(gate, server_context)
+        method = :"#{gate[:name]}?"
+        if server_context.respond_to?(method)
+          !!server_context.public_send(method, gate[:value])
+        elsif gate[:name] == :requires && server_context.respond_to?(:current_user)
+          # Backward compat: fall back to direct user permission check.
+          # Mirrors RbsSchemaCompiler#predicate_excluded? handling for the
+          # OpenStruct-style contexts that predate ServerContext.
+          !!server_context.current_user&.can?(gate[:value].to_sym)
+        else
+          warn_unknown_gate(gate[:name], server_context)
+          true # Fail-open: show the tool
+        end
+      rescue StandardError => e
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.error("[McpAuthorization] tool gate #{gate[:name]}?(#{gate[:value]}) raised: #{e.message}")
+        end
+        true # Fail-open on error: show the tool
+      end
+
+      # Emit a development-mode warning when a gate predicate method is not
+      # found on the server context. Delegates to the shared diagnostic
+      # helper so the field-level (+@predicate+) and tool-level (+gate+)
+      # warning shapes stay in sync.
+      #: (Symbol, untyped) -> void
+      def warn_unknown_gate(name, server_context)
+        McpAuthorization::Diagnostics.warn_unknown_predicate(name, server_context, site: :tool)
+      end
+
       #: (**untyped) -> void
       def merge_annotations(**new_hints)
         hints = (@_annotation_hints || {}).merge(new_hints)

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/mcp_authorization.rb

@@ -1,6 +1,7 @@
 require "mcp"
 require_relative "mcp_authorization/version"
 require_relative "mcp_authorization/configuration"
+require_relative "mcp_authorization/diagnostics"
 require_relative "mcp_authorization/dsl"
 require_relative "mcp_authorization/rbs_schema_compiler"
 require_relative "mcp_authorization/tool_registry"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -67,8 +67,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 description: Add MCP tool serving to any Rails app. Write @rbs type annotations with
-  @requires(:flag) tags and the gem compiles per-user JSON Schema automatically. Feature
-  flags, permissions, and plan tiers all work through a single can?(:symbol) predicate.
+  predicate tags (@requires, @feature, or custom) and the gem compiles per-user JSON
+  Schema automatically — filtering fields by permissions, feature flags, and plan
+  tiers at request time.
 email:
 executables: []
 extensions: []
@@ -80,6 +81,7 @@ files:
 - app/controllers/mcp_authorization/mcp_controller.rb
 - lib/mcp_authorization.rb
 - lib/mcp_authorization/configuration.rb
+- lib/mcp_authorization/diagnostics.rb
 - lib/mcp_authorization/dsl.rb
 - lib/mcp_authorization/engine.rb
 - lib/mcp_authorization/rbs_schema_compiler.rb