mcp_authorization 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9adb27c3a4074869c90737b393772a425931683c8b8128864525902e7283aed6
-  data.tar.gz: 1d0e2d793b46ff13952142d3e3a21b0a0f6008039e184446506cf90b9e5a1083
+  metadata.gz: 9042f13cf2b294336b81ade0d8f97c31179a6483dde8c73c2258a7459227c7c4
+  data.tar.gz: 8be4296941e757f985bdab130472aa3f7f1bda837eae5d3b8d924078e9f27bb9
 SHA512:
-  metadata.gz: 1b46015ca220581022647d667f1d86809c83e433ef5cd2ea500d8b81a2fc2eb9a58346746b74c0a3dbe78209f51728e0b7b2593f5dc7e9fd7663c2fb19638df9
-  data.tar.gz: ec9e5d04a5a5d749a995f73026d05bd003e4ab2421fc97d872d67af07bf4fd3f909d1aaa77053c6aca644ffbbbaf89257fc77774bf0800d648ebaf0cb3d428ae
+  metadata.gz: f167384e7a8b591bb76e05677ed8f99998bcb253144f509046cb4c46e57170ef8348350b3d926a04620011e4982d91de354e41be4c01e39f08acdcec06b893ff
+  data.tar.gz: c283b35338579177226136f6fb66d778e982e9748e5d946e8ec0232134149aeaa3571033133923b5caf7c497aba14d9b2798a3c5f784c2dc50a22cdcb7e907a4

data/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.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
+- **Generic predicate tags.** Any `@tag(:value)` annotation not in the known constraint list becomes a predicate filter: the compiler calls `server_context.tag_name?(value)` at schema compile time. If the predicate returns false, the field/variant is excluded from the JSON Schema. This makes the gem infinitely extensible — define `feature?`, `tier?`, `beta?`, or any predicate on your server context without gem changes.
+- Backward-compat fallback for `@requires`: if the server context lacks a `requires?` method, the compiler falls back to `server_context.current_user.can?(:flag)` directly. No deploy-ordering constraint.
+- Error isolation: exceptions from individual predicates are rescued and logged. A single broken predicate no longer crashes the entire `tools/list` response.
+- Development-mode warning with DidYouMean suggestion when a predicate method is not found on the server context (e.g., `@feture(:x)` warns "Did you mean @feature?").
+
+### Changed
+- `@requires` is now handled through the generic predicate path. The `tags[:requires]` key is removed; `@requires(:flag)` is stored only in `tags[:predicates]` like any other predicate.
+- `predicate_excluded?` replaces the three hardcoded `current_user.can?` filter lines in `compile_tagged_record`, `compile_tagged_union`, and `filter_call_signature`.
+- Configuration docs updated to describe the predicate protocol on server context objects.
+
+### Migration notes
+- Consumers using `OpenStruct` as server context continue to work — `@requires` falls back to `current_user.can?`. To use `@feature` or custom predicates, define the corresponding `?` methods on your server context.
+- If you read `tags[:requires]` from parsed tag hashes (unlikely outside the gem), switch to `tags[:predicates].find { |p| p[:name] == "requires" }`.
+
 ## [0.2.1] - 2026-05-13
 
 ### Fixed

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
@@ -429,13 +434,52 @@ Tag any field in a `#:` annotation or `@rbs type` record to add JSON Schema cons
 | `@read_only()` | `readOnly: true` | Read-only field |
 | `@write_only()` | `writeOnly: true` | Write-only field |
 
-**Authorization:**
+**Authorization & predicate filters:**
 
 | Tag | Purpose |
 |---|---|
-| `@requires(:flag)` | Field/variant excluded when `can?(:flag)` is false |
+| `@requires(:flag)` | Field/variant excluded when `server_context.requires?(:flag)` returns false. Legacy fallback: if `requires?` is not defined, falls back to `current_user.can?(:flag)`. |
+| `@feature(:flag)` | Field/variant excluded when `server_context.feature?(:flag)` returns false (account-level feature flags) |
 | `@depends_on(:field)` | Emits `dependentRequired` — field only required when parent field is present |
 
+Any `@tag(:value)` not in the known constraint list above is a **generic predicate filter**. At schema compile time, the gem calls `server_context.tag_name?(value)` — if it returns false, the field is excluded. If `server_context` doesn't respond to the method, the predicate is skipped (permissive).
+
+This makes the gem infinitely extensible. Define any predicate on your server context:
+
+```ruby
+# In your app's server context:
+def requires?(flag) = current_user.can?(flag.to_sym)
+def feature?(flag) = current_account.feature_enabled?(flag.to_s)
+def tier?(name) = current_account.plan_tier?(name.to_s)
+def beta?(flag) = current_account.beta_enrolled?(flag.to_s)
+
+# In your handler:
+#: (?status: "active" | "inactive" | "unlisted" @feature(:opening_status_v2)) -> output
+#: (?force: bool @requires(:admin) @tier(:enterprise)) -> output
+```
+
+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/configuration.rb

@@ -22,6 +22,20 @@ module McpAuthorization
   #   current_user.can?(:symbol)              # required — gates field/tool visibility
   #   current_user.default_for(:symbol)       # optional — populates @default_for tags
   #
+  # The context object itself can implement predicate methods for generic
+  # tag filtering. Any +@tag(:value)+ not in the known constraint list
+  # calls +context.tag?(value)+:
+  #
+  #   context.requires?(flag)                 # optional — for @requires, falls back to current_user.can?
+  #   context.feature?(flag)                  # optional — for @feature (account-level feature flags)
+  #   context.tier?(name)                     # optional — for @tier (plan-level gating)
+  #
+  # For public/anonymous MCP interfaces, supply a context with minimum-viable
+  # permissions rather than +current_user: nil+. A nil user causes +@requires+
+  # fields to be silently excluded (no user = no permissions).
+  #
+  # See RbsSchemaCompiler.predicate_excluded? for the full protocol.
+  #
   class Configuration
     # Server name reported in the MCP +initialize+ handshake.
     #: String

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.
@@ -339,7 +341,7 @@ module McpAuthorization
       # @return [Array(String, Hash)] +[clean_type, tags_hash]+
       #
       # Supported tags:
-      #   @requires(:symbol)      -> { requires: :symbol }
+      #   @requires(:symbol)      -> added to :predicates (calls server_context.requires?)
       #   @depends_on(:field)     -> { depends_on: "field" }
       #   @min(n)                 -> { min: n }
       #   @max(n)                 -> { max: n }
@@ -360,6 +362,14 @@ module McpAuthorization
       #   @closed() / @strict()   -> { closed: true }
       #   @media_type(type)       -> { media_type: "type" }
       #   @encoding(enc)          -> { encoding: "enc" }
+      #
+      # Any tag not listed above is treated as a **predicate filter**:
+      #   @feature(:flag)         -> added to predicates, calls server_context.feature?(:flag)
+      #   @tier(:enterprise)      -> added to predicates, calls server_context.tier?(:enterprise)
+      #   @custom(:value)         -> added to predicates, calls server_context.custom?(:value)
+      #
+      # Predicate filters exclude the field/variant from the schema when the
+      # predicate returns false. The server_context must respond to +tag_name?+.
       #: (String) -> [String, Hash[Symbol, untyped]]
       def extract_tags(type_str)
         tags = {}
@@ -370,7 +380,7 @@ module McpAuthorization
 
           case tag_name
           when "requires"
-            tags[:requires] = tag_value.delete_prefix(":").to_sym
+            (tags[:predicates] ||= []) << { name: "requires", value: tag_value.delete_prefix(":") }
           when "depends_on"
             tags[:depends_on] = tag_value.delete_prefix(":")
           when "min"
@@ -411,6 +421,8 @@ module McpAuthorization
             tags[:media_type] = tag_value
           when "encoding"
             tags[:encoding] = tag_value
+          else
+            (tags[:predicates] ||= []) << { name: tag_name, value: tag_value.delete_prefix(":") }
           end
         end
 
@@ -543,18 +555,72 @@ module McpAuthorization
       end
 
       # ---------------------------------------------------------------
-      # @requires filtering — the per-request compile phase
+      # Predicate filtering — the per-request compile phase
       # ---------------------------------------------------------------
 
+      # Returns true if any predicate tag on a field/variant evaluates to
+      # false, meaning the field should be excluded from the schema.
+      #
+      # For each predicate, calls +server_context.tag_name?(value)+.
+      # If the server_context doesn't respond to the method, the predicate
+      # is skipped (fail-open — unknown predicates don't block). This is
+      # intentional: predicates shape the schema for the LLM, they are not
+      # a security boundary. Hiding a field by accident (typo) is worse
+      # than showing one extra field. Runtime enforcement (+filter_input+)
+      # is the actual security layer.
+      #
+      # Special case: +@requires+ falls back to +current_user.can?+ when
+      # the server_context lacks a +requires?+ method, for backward
+      # compatibility with consumers that haven't migrated to predicates.
+      #
+      # Exceptions from individual predicates are rescued and logged so
+      # that a single broken predicate doesn't crash the entire tools/list.
+      #
+      # @param tags [Hash] Parsed tags from +extract_tags+.
+      # @param server_context [Object] Per-request context.
+      # @return [Boolean] true if the field should be excluded.
+      #: (Hash[Symbol, untyped], untyped) -> bool
+      def predicate_excluded?(tags, server_context)
+        return false unless tags[:predicates] && server_context
+        tags[:predicates].any? do |pred|
+          method = :"#{pred[:name]}?"
+          if server_context.respond_to?(method)
+            !server_context.public_send(method, pred[:value])
+          elsif pred[:name] == "requires" && server_context.respond_to?(:current_user)
+            # Backward compat: fall back to direct user permission check.
+            # Note: nil current_user → &.can? returns nil → !nil is true → field excluded.
+            # This is intentional: no user = no permissions = hide restricted fields.
+            !server_context.current_user&.can?(pred[:value].to_sym)
+          else
+            warn_unknown_predicate(pred[:name], server_context)
+            false # Fail-open: include the field
+          end
+        rescue => e
+          if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+            Rails.logger.error("[McpAuthorization] predicate #{pred[:name]}?(#{pred[:value]}) raised: #{e.message}")
+          end
+          false # Fail-open on error: include the field
+        end
+      end
+
+      # Emit a development-mode warning when a 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.
+      #: (String, untyped) -> void
+      def warn_unknown_predicate(name, server_context)
+        McpAuthorization::Diagnostics.warn_unknown_predicate(name, server_context, site: :field)
+      end
+
       # Compile a record-style input type (+# @rbs type input = { ... }+)
-      # with field-level +@requires+ filtering.
+      # with field-level predicate filtering.
       #
-      # Fields whose +@requires+ flag the current user lacks are silently
-      # omitted from the resulting JSON Schema, so the LLM never sees them.
+      # Fields whose predicate tags (e.g. +@requires+, +@feature+) evaluate
+      # to false are silently omitted from the resulting JSON Schema.
       #
       # @param raw_body [String] The raw record body, e.g. +"{name: String, force: bool @requires(:admin)}"+.
       # @param type_map [Hash] Resolved type definitions for +$ref+ lookups.
-      # @param server_context [Object] Per-request context with +current_user+.
+      # @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)
@@ -568,7 +634,7 @@ module McpAuthorization
           key, type_str = match[0].to_s, match[1].to_s
           type_str, tags = extract_tags(type_str.strip)
 
-          next if tags[:requires] && !server_context.current_user.can?(tags[:requires])
+          next if predicate_excluded?(tags, server_context)
 
           optional = key.end_with?("?")
           clean_key = key.delete_suffix("?")
@@ -590,10 +656,10 @@ module McpAuthorization
       end
 
       # Compile a union-style output type (+# @rbs type output = success | admin_detail @requires(:admin)+)
-      # with variant-level +@requires+ filtering.
+      # with variant-level predicate filtering.
       #
-      # Each union variant (separated by +|+) can carry its own +@requires+
-      # tag. Variants the user lacks permission for are dropped entirely.
+      # Each union variant (separated by +|+) can carry its own predicate
+      # tags. Variants whose predicates evaluate to false are dropped entirely.
       # If only one variant remains, it's returned directly (no +oneOf+
       # wrapper). If zero remain, a bare +{type: "object"}+ fallback is used.
       #
@@ -607,7 +673,7 @@ module McpAuthorization
 
         filtered = parts.filter_map do |part|
           part, tags = extract_tags(part)
-          next nil if tags[:requires] && !server_context.current_user.can?(tags[:requires])
+          next nil if predicate_excluded?(tags, server_context)
           resolve_type(part, type_map)
         end
 
@@ -618,7 +684,7 @@ module McpAuthorization
         end
       end
 
-      # Filter method-signature parameters by +@requires+ tags and build
+      # Filter method-signature parameters by predicate tags and build
       # the input JSON Schema. This is the path used when the handler defines
       # its schema via a +#:+ annotation above +def call+ rather than an
       # explicit +# @rbs type input = { ... }+.
@@ -634,9 +700,7 @@ module McpAuthorization
         dependent_required = {}
 
         call_params.each do |param|
-          if param[:tags][:requires] && server_context
-            next unless server_context.current_user.can?(param[:tags][:requires])
-          end
+          next if predicate_excluded?(param[:tags], server_context)
 
           schema = rbs_type_to_json_schema(param[:type], type_map)
           properties[param[:name].to_sym] = apply_tags(schema, param[:tags], server_context: server_context)

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.2.1"
+  VERSION = "0.4.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.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-05-26 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