mcp_authorization 0.5.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6b7e3511b7790b3da9c74c48f4df83c87adc11a875fc0e822c153c33b6a72e9
-  data.tar.gz: c00c25c116df33f17126a8b45105db079e8180c9b4b2895f1e50db0131fb9dfe
+  metadata.gz: 63bcf798beee003e44d7894f8e2e80177a6ddb1e7357b68507a74464c2665ce6
+  data.tar.gz: 047560ce4c65b3b960f7c66904ca48c70b513e90510d7714edbd93996c39f919
 SHA512:
-  metadata.gz: 2784b842b815610bf06752607b26332568076ce84b675dbc902e1ea0a858eac18e1e41d3b8cce812bce64b95f76266885fb6b43c4388742ac89e861d9d4f4639
-  data.tar.gz: 5fcb42dac47e116c9223c23aabc5c76884e756c06c2b8dc1ace1be6014fbd44560746458f54890653e597aaa4152bdb2e881c6b32d5ec1fba7f957e86939a2ed
+  metadata.gz: 41b2c6a57ffeda77b7c74e2d2a849da6653d6678f78e9a76b9dec0cdaef5059b4ea00449063c57254e526c9cf6ebc780a7f43b59bfefeb57fabcc12e2f966842
+  data.tar.gz: 7dc31d4854025087e495bc9963ee46079a35f3cc6cc6fcbd3a904b00383017e6f68b7718db51a49fb78585657d86158e637fcbd5a182a72b1ad6d09ec83f362e

data/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.6.0] - 2026-06-25
+
+Per-request work is now scoped to what each MCP method needs, and the
+remaining `tools/list` cost is cacheable.
+
+### Changed
+- **`McpController#handle` now materializes only the tools the incoming request needs.** Every request — `initialize`, `notifications/initialized`, `ping`, the GET stream probe, and `tools/call` — previously ran `ToolRegistry.tool_classes_for`, compiling a per-user schema for *every* tool in the domain before the transport even looked at the method. Per-tool schema compilation is the dominant cost of an MCP request, so a `tools/call` (which invokes exactly one tool) and lifecycle traffic (which needs none) paid the full-domain price for nothing. `handle` now routes by JSON-RPC method: `tools/list` materializes the whole domain (unchanged), `tools/call` materializes only the invoked tool, lifecycle methods and the non-POST probe materialize none, and any unrecognized shape (e.g. a JSON-RPC batch with no top-level `method`) falls back to the full domain so routing stays correct. In a 140-tool domain this took a `tools/call` from ~2.6s to <100ms and `notifications/initialized` from ~2s to ~1ms, with no change to `tools/list` output.
+
+### Added
+- **`ToolRegistry.tool_class_for(domain:, name:, server_context:)`** — returns the concrete `MCP::Tool` subclass for a single named tool within a domain (or `nil` when the tool is unknown in that domain or the current user is not permitted), materializing just that one tool instead of the whole domain. Complements `tool_classes_for`, which remains the path for `tools/list`.
+
+- **Opt-in caching for the `tools/list` response.** `tools/list` must materialize a per-user schema for every tool in a domain — the dominant cost of an MCP request now that `tools/call` compiles only the invoked tool (above). It can now be cached. Enable in the host initializer:
+
+  ```ruby
+  McpAuthorization.configure do |c|
+    c.tools_list_cache = :redis          # or :memory, or any object responding to get/set
+    c.tools_list_cache_ttl = 3600        # seconds (default)
+  end
+  ```
+
+  Default is no caching (`NullStore`), so behavior is unchanged unless opted in.
+
+- **Decision-vector cache key — correct under feature flags, shareable across identity.** The key is `H(domain + tool_defs_digest + vocab_fingerprint + decision_vector)`, never user/account identity. The decision vector is the result of every gating decision the domain's compilation consults — `@requires`/`@feature`/`@tier`/custom predicates, tool-level `gate`/`authorization`, and `current_user.can?` / `default_for`. Two contexts that answer all of them identically (same permissions, feature flags, tiers, defaults) share an entry; flip one feature flag and the vector — and the key — change, so an admin in a flag-on account never receives a flag-off account's tools. The `tool_defs_digest` (computed from each tool's gates + handler source) changes on deploy, auto-invalidating stale entries; the TTL bounds out-of-band staleness.
+
+- **Two ways to supply the decision vector.** Automatic: the gem learns a domain's predicate vocabulary by wrapping the context in a `Cache::Recorder` on the first (cold) compile, then replays that vocabulary against the live context on subsequent requests. Explicit: if the server context responds to `mcp_cache_fingerprint`, its return value is used verbatim as the decision component (the host folds in whatever shapes the schema). Explicit wins when present.
+
+- **Pluggable stores.** `Cache::NullStore` (default), `Cache::MemoryStore` (process-local, bounded LRU + per-entry TTL), and `Cache::RedisStore` (shared; JSON values; per-entry TTL). The Redis store's connection resolves from an explicit client (`tools_list_cache_redis`), then `tools_list_cache_redis_url`, then `ENV["REDIS_URL"]`, then a bare `Redis.new` — i.e. it defaults to the host's Rails redis config with no extra wiring. `redis` is an optional dependency, required lazily only when the Redis store is used. Cache outages fail open (a get/set error logs and behaves as a miss, never breaking `tools/list`).
+
+- **`McpController` serves `tools/list` through the cache** when enabled: a hit renders the cached `result` re-wrapped with the live JSON-RPC id; a miss compiles cold under a `Recorder`, learns the vocabulary, and stores the result. Error/unexpected responses are rendered but not cached. All other methods are unaffected.
+
+### Notes
+- The cache is cleared on code reload (the Engine reloader now also calls `Cache.reset!`), so development picks up tool/schema changes immediately.
+
+## [0.5.6] - 2026-06-08
+
+### Fixed
+- **Single-line and column-aligned `# @rbs type` record aliases are now collected.** A record alias written on one line — `# @rbs type ok = { a: String, b: Integer }` — was silently dropped: `collect_inline_aliases` truncated the body to a bare `{` and only a closing brace on a *following* line ever balanced it. Any union or field referencing such an alias resolved to the `{type: "object"}` fallback (no properties, no per-request gating), so the advertised schema and runtime projection both lost the type's shape. The opening-line body is now captured whole and stored immediately when its braces balance. Relatedly, the alias regex now tolerates arbitrary whitespace around `=`, so column-aligned blocks (`# @rbs type success     = { ... }`) parse instead of being skipped. Multi-line aliases are unaffected.
+
 ## [0.5.5] - 2026-06-04
 
 ### Fixed

data/README.md

@@ -4,6 +4,8 @@ Rails engine for serving MCP tools with per-request schema discrimination compil
 
 Add it to your Gemfile and your Rails app speaks [MCP](https://modelcontextprotocol.io). Write `@rbs type` comments in plain Ruby service classes, tag fields and variants with `@requires(:flag)`, and the gem compiles tailored JSON Schema per request. The type definitions are the authorization policy.
 
+> Looking for task-oriented "how do I X?" recipes rather than reference? See the **[Cookbook](COOKBOOK.md)**.
+
 ## Three layers of authorization
 
 The gem gives you three independent controls over what each user sees:

data/app/controllers/mcp_authorization/mcp_controller.rb

@@ -6,11 +6,22 @@ module McpAuthorization
     #: () -> void
     def handle
       server_context = build_server_context
-      tools = McpAuthorization::ToolRegistry.tool_classes_for(
-        domain: params[:domain],
-        server_context: server_context
-      )
 
+      if mcp_method == "tools/list" && McpAuthorization::Cache.enabled?
+        return render_cached_tools_list(server_context)
+      end
+
+      status, headers, body = run_transport(server_context, tools_for_request(server_context))
+      apply_headers(headers)
+      render json: body.first, status: status
+    end
+
+    private
+
+    # Build a stateless MCP server with the given tools + context and run the
+    # incoming request through the transport.
+    #: (untyped, Array[singleton(MCP::Tool)]) -> [Integer, Hash[String, String], Array[untyped]]
+    def run_transport(server_context, tools)
       server = MCP::Server.new(
         name: McpAuthorization.config.server_name,
         version: McpAuthorization.config.server_version,
@@ -19,13 +30,103 @@ module McpAuthorization
       )
       transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
       server.transport = transport
+      transport.handle_request(request)
+    end
 
-      status, headers, body = transport.handle_request(request)
+    #: (Hash[String, String]) -> void
+    def apply_headers(headers)
       headers.each { |k, v| response.set_header(k, v) }
-      render json: body.first, status: status
     end
 
-    private
+    # Serve tools/list from the configured cache, or compile it cold (observed
+    # by a Recorder so the cache key vocabulary is learned) and store it. The
+    # JSON-RPC envelope is rebuilt with the live request id, so the cached
+    # value is just the (id-independent) `result`.
+    #: (untyped) -> void
+    def render_cached_tools_list(server_context)
+      domain = params[:domain]
+
+      key = McpAuthorization::Cache.tools_list_key(domain: domain, server_context: server_context)
+      if key && (cached = McpAuthorization::Cache.store.get(key))
+        return render json: tools_list_envelope(cached)
+      end
+
+      effective_ctx, recorder = McpAuthorization::Cache.recording_context(server_context)
+      status, headers, body = run_transport(effective_ctx, all_tools(effective_ctx))
+      McpAuthorization::Cache.learn!(domain: domain, recorder: recorder)
+      apply_headers(headers)
+
+      parsed = begin
+        JSON.parse(body.first)
+      rescue StandardError
+        nil
+      end
+      result = parsed && parsed["result"]
+      unless result
+        return render json: body.first, status: status # error / unexpected shape — don't cache
+      end
+
+      store_key = McpAuthorization::Cache.tools_list_key(domain: domain, server_context: server_context)
+      McpAuthorization::Cache.store.set(store_key, result, ttl: McpAuthorization::Cache.ttl) if store_key
+      render json: tools_list_envelope(result), status: status
+    end
+
+    #: (untyped) -> String
+    def tools_list_envelope(result)
+      { jsonrpc: "2.0", id: mcp_request_id, result: result }.to_json
+    end
+
+    #: () -> untyped
+    def mcp_request_id
+      params[:id] || params.dig(:mcp, :id)
+    end
+
+    # Materialize only the tools the incoming JSON-RPC method needs. Compiling
+    # per-user schemas for every tool is the dominant cost of an MCP request, so
+    # a +tools/call+ compiles just the invoked tool and lifecycle methods
+    # (initialize, notifications/*, ping) and non-POST probes compile none.
+    # +tools/list+ — and any unrecognized shape such as a JSON-RPC batch —
+    # falls back to the full domain so routing stays correct.
+    #: (untyped) -> Array[singleton(MCP::Tool)]
+    def tools_for_request(server_context)
+      return [] if request.get?
+
+      case mcp_method
+      when "tools/list"
+        all_tools(server_context)
+      when "tools/call"
+        name = mcp_request_params[:name]
+        name ? Array(McpAuthorization::ToolRegistry.tool_class_for(
+          domain: params[:domain],
+          name: name,
+          server_context: server_context
+        )) : all_tools(server_context)
+      when "initialize", "ping", %r{\Anotifications/}
+        []
+      else
+        # Unknown or unreadable method (e.g. a JSON-RPC batch with no top-level
+        # method): materialize the full domain so multi-method requests route.
+        all_tools(server_context)
+      end
+    end
+
+    #: (untyped) -> Array[singleton(MCP::Tool)]
+    def all_tools(server_context)
+      McpAuthorization::ToolRegistry.tool_classes_for(
+        domain: params[:domain],
+        server_context: server_context
+      )
+    end
+
+    #: () -> untyped
+    def mcp_method
+      params[:method] || params.dig(:mcp, :method)
+    end
+
+    #: () -> untyped
+    def mcp_request_params
+      params[:params] || params.dig(:mcp, :params) || ActionController::Parameters.new
+    end
 
     #: () -> untyped
     def build_server_context

data/lib/mcp_authorization/cache/memory_store.rb

@@ -0,0 +1,62 @@
+require "monitor"
+
+module McpAuthorization
+  module Cache
+    # Process-local in-memory store with a bounded entry count and per-entry
+    # TTL. Each worker process warms its own copy — fine for the tools/list
+    # payload, which is identical across workers for a given decision vector.
+    # For cross-process/host sharing, use RedisStore.
+    class MemoryStore
+      include MonitorMixin
+
+      DEFAULT_MAX_ENTRIES = 512
+
+      #: (?max_entries: Integer) -> void
+      def initialize(max_entries: DEFAULT_MAX_ENTRIES)
+        super()
+        @max_entries = max_entries
+        @entries = {} #: Hash[String, [untyped, Float?]]  # key => [value, expires_at]
+      end
+
+      #: (String) -> untyped
+      def get(key)
+        synchronize do
+          entry = @entries[key]
+          return nil unless entry
+
+          value, expires_at = entry
+          if expires_at && monotonic > expires_at
+            @entries.delete(key)
+            return nil
+          end
+
+          # Mark as most-recently-used.
+          @entries.delete(key)
+          @entries[key] = entry
+          value
+        end
+      end
+
+      #: (String, untyped, ?ttl: Integer?) -> void
+      def set(key, value, ttl: nil)
+        synchronize do
+          @entries.delete(key)
+          @entries[key] = [value, ttl ? monotonic + ttl : nil]
+          @entries.shift while @entries.size > @max_entries # evict oldest (insertion order)
+        end
+      end
+
+      #: () -> void
+      def clear
+        synchronize { @entries.clear }
+      end
+
+      private
+
+      #: () -> Float
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/mcp_authorization/cache/null_store.rb

@@ -0,0 +1,20 @@
+module McpAuthorization
+  module Cache
+    # No-op store. The default — caching is opt-in. Every read misses, every
+    # write is discarded, so behavior is identical to a gem with no cache.
+    class NullStore
+      #: (String) -> nil
+      def get(_key)
+        nil
+      end
+
+      #: (String, untyped, ?ttl: Integer?) -> void
+      def set(_key, _value, ttl: nil)
+        nil
+      end
+
+      #: () -> void
+      def clear; end
+    end
+  end
+end

data/lib/mcp_authorization/cache/recorder.rb

@@ -0,0 +1,110 @@
+module McpAuthorization
+  module Cache
+    # A signature for one decision the compiler consulted on the server
+    # context: a predicate call (`feature?(:sms)`, `requires?(:admin)`, a
+    # custom `tier?(:enterprise)`), or a `current_user.can?` / `default_for`
+    # call. Identity is by (target, method, arg) so the same decision dedupes
+    # across tools; +arg+ is retained intact so replay calls the predicate
+    # with the original value, not a coerced one.
+    Signature = Struct.new(:target, :method, :arg) do
+      #: () -> String
+      def canonical
+        "#{target}\x1f#{method}\x1f#{arg.inspect}"
+      end
+
+      #: (untyped) -> bool
+      def eql?(other)
+        other.is_a?(Signature) && canonical == other.canonical
+      end
+
+      #: () -> Integer
+      def hash
+        canonical.hash
+      end
+    end
+
+    # Wraps a server context during a cold compile and records every gating
+    # decision the compiler reads — so the cache key can be rebuilt later from
+    # just those decisions. Two contexts that answer every recorded predicate
+    # identically (same permissions, feature flags, tiers, defaults) produce
+    # the same key and share a cache entry; flip one feature flag and the
+    # vector — and the key — change.
+    #
+    # Transparently delegates everything to the wrapped context. The compiler
+    # reaches the user via +current_user+, so that returns a RecorderUser to
+    # capture +can?+ and +default_for+.
+    class Recorder
+      #: untyped
+      attr_reader :__target
+
+      #: Array[Signature]
+      attr_reader :consulted
+
+      #: (untyped) -> void
+      def initialize(target)
+        @__target = target
+        @consulted = []
+        @__user = nil
+      end
+
+      #: () -> untyped
+      def current_user
+        user = @__target.current_user
+        return nil unless user
+
+        @__user ||= RecorderUser.new(user, @consulted)
+      end
+
+      #: (Symbol, ?bool) -> bool
+      def respond_to_missing?(name, include_private = false)
+        @__target.respond_to?(name, include_private)
+      end
+
+      #: (Symbol, *untyped) -> untyped
+      def method_missing(name, *args, &block)
+        result = @__target.public_send(name, *args, &block)
+        # Gating predicates are single-arg methods ending in "?"
+        # (feature?/requires?/tier?/<custom>?). Recording an incidental
+        # predicate is harmless — it just adds a deterministic dimension to
+        # the key — so we don't need a hardcoded allowlist.
+        if name.to_s.end_with?("?") && args.size == 1
+          @consulted << Signature.new(:context, name.to_s, args.first)
+        end
+        result
+      end
+    end
+
+    # Records +can?+ and +default_for+ on the wrapped user. +default_for+
+    # returns a value baked into the schema, so its result is part of the
+    # decision vector too, not just predicate booleans.
+    class RecorderUser
+      #: (untyped, Array[Signature]) -> void
+      def initialize(target, consulted)
+        @__target = target
+        @consulted = consulted
+      end
+
+      #: (untyped) -> untyped
+      def can?(flag)
+        @consulted << Signature.new(:user, "can?", flag)
+        @__target.can?(flag)
+      end
+
+      #: (untyped) -> untyped
+      def default_for(key)
+        @consulted << Signature.new(:user, "default_for", key)
+        @__target.default_for(key)
+      end
+
+      #: (Symbol, ?bool) -> bool
+      def respond_to_missing?(name, include_private = false)
+        @__target.respond_to?(name, include_private)
+      end
+
+      #: (Symbol, *untyped) -> untyped
+      def method_missing(name, *args, &block)
+        @__target.public_send(name, *args, &block)
+      end
+    end
+  end
+end

data/lib/mcp_authorization/cache/redis_store.rb

@@ -0,0 +1,102 @@
+require "json"
+
+module McpAuthorization
+  module Cache
+    # Redis-backed store — shared across workers and hosts. Values are stored
+    # as JSON (the tools/list result is plain JSON-serializable data), with a
+    # per-entry TTL via +SET ... EX+.
+    #
+    # Connection resolution (first match wins), so a Rails host gets the
+    # "Rails redis config" for free without passing anything:
+    #
+    #   1. an explicit client       — RedisStore.new(redis: $redis)
+    #   2. an explicit URL          — RedisStore.new(url: "redis://…")
+    #   3. ENV["REDIS_URL"]         — the conventional Rails/Heroku/Sidekiq var
+    #   4. Redis.new                — the redis gem's own default (ENV or localhost),
+    #                                 matching a bare `Redis.new` in the host
+    #
+    # The +redis+ gem is an optional dependency, required lazily here so hosts
+    # that don't use this store never need it.
+    class RedisStore
+      # Raised when :redis caching is requested but the redis gem is absent.
+      class RedisUnavailable < StandardError; end
+
+      NAMESPACE = "mcpauth".freeze
+
+      #: (?redis: untyped?, ?url: String?, ?namespace: String) -> void
+      def initialize(redis: nil, url: nil, namespace: NAMESPACE)
+        @redis = redis
+        @url = url
+        @namespace = namespace
+      end
+
+      #: (String) -> untyped
+      def get(key)
+        raw = client.get(namespaced(key))
+        raw && JSON.parse(raw)
+      rescue StandardError => e
+        log_error("get", e)
+        nil # never let a cache outage break tools/list
+      end
+
+      #: (String, untyped, ?ttl: Integer?) -> void
+      def set(key, value, ttl: nil)
+        payload = JSON.generate(value)
+        if ttl && ttl > 0
+          client.set(namespaced(key), payload, ex: ttl)
+        else
+          client.set(namespaced(key), payload)
+        end
+        nil
+      rescue StandardError => e
+        log_error("set", e)
+        nil
+      end
+
+      #: () -> void
+      def clear
+        cursor = "0"
+        loop do
+          cursor, keys = client.scan(cursor, match: namespaced("*"), count: 500)
+          client.del(*keys) unless keys.empty?
+          break if cursor == "0"
+        end
+      rescue StandardError => e
+        log_error("clear", e)
+      end
+
+      private
+
+      #: (String) -> String
+      def namespaced(key)
+        "#{@namespace}:#{key}"
+      end
+
+      #: () -> untyped
+      def client
+        @client ||= @redis || build_client
+      end
+
+      #: () -> untyped
+      def build_client
+        require "redis"
+        url = @url || ENV["REDIS_URL"]
+        url ? ::Redis.new(url: url) : ::Redis.new
+      rescue LoadError
+        raise RedisUnavailable, <<~MSG
+          McpAuthorization is configured to use the :redis tools/list cache,
+          but the `redis` gem is not available. Add `gem "redis"` to your
+          Gemfile, or pass an explicit client/store to
+          `config.tools_list_cache`.
+        MSG
+      end
+
+      #: (String, Exception) -> void
+      def log_error(op, error)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+        Rails.logger.error("[McpAuthorization] redis cache #{op} failed: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end

data/lib/mcp_authorization/cache.rb

@@ -0,0 +1,222 @@
+require "digest"
+require "json"
+require "monitor"
+require "set"
+
+require_relative "cache/null_store"
+require_relative "cache/memory_store"
+require_relative "cache/redis_store"
+require_relative "cache/recorder"
+
+module McpAuthorization
+  # Opt-in caching for the `tools/list` response — the one MCP method that must
+  # materialize a per-user schema for *every* tool in a domain, and the
+  # dominant cost of an MCP request once `tools/call` only compiles one tool
+  # (see McpController).
+  #
+  # The cache is keyed on the *decisions* the compiler makes, not on user or
+  # account identity, so it is both correct under feature flags and maximally
+  # shareable:
+  #
+  #   key = H(domain + tool_defs_digest + vocab_fingerprint + decision_vector)
+  #
+  # - tool_defs_digest   — changes when a tool's gates or handler source change
+  #                        (i.e. on deploy), auto-invalidating stale entries.
+  # - decision_vector    — the result of every gating predicate the domain's
+  #                        compilation consults, evaluated against this context.
+  #
+  # Two ways the decision vector is obtained:
+  #
+  # 1. Explicit (recommended for hosts that know their inputs): if the server
+  #    context responds to +mcp_cache_fingerprint+, its return value is used
+  #    verbatim as the decision component. The host is responsible for folding
+  #    in everything that shapes the schema (permission set, feature flags,
+  #    integrations, per-user defaults).
+  #
+  # 2. Automatic: otherwise the gem learns the vocabulary by wrapping the
+  #    context in a Recorder on the first (cold) compile of a domain, capturing
+  #    every predicate / can? / default_for it reads. Subsequent requests
+  #    rebuild the vector by replaying that vocabulary against the live context.
+  #
+  # Caching is off by default (NullStore). Enable in a Rails initializer:
+  #
+  #   McpAuthorization.configure do |c|
+  #     c.tools_list_cache = :redis        # or :memory, or a custom store
+  #     c.tools_list_cache_ttl = 3600
+  #   end
+  module Cache
+    @monitor = Monitor.new
+    @learned = {}      #: Hash[String, Array[Signature]]  # domain => learned signatures
+    @learned_flag = {} #: Hash[String, bool]              # domain => has been learned at all
+    @store = nil
+    @defs_digest = nil
+
+    class << self
+      # The resolved store. Memoized; rebuilt after +reset!+.
+      #: () -> untyped
+      def store
+        @monitor.synchronize { @store ||= resolve_store(McpAuthorization.config.tools_list_cache) }
+      end
+
+      #: () -> bool
+      def enabled?
+        !store.is_a?(NullStore)
+      end
+
+      #: () -> Integer
+      def ttl
+        McpAuthorization.config.tools_list_cache_ttl
+      end
+
+      # Returns [effective_context, recorder_or_nil]. When the host supplies an
+      # explicit fingerprint, no recorder is needed and the real context is
+      # used. Otherwise the context is wrapped so the cold compile is observed.
+      #: (untyped) -> [untyped, Recorder?]
+      def recording_context(server_context)
+        return [server_context, nil] if explicit_fingerprint(server_context)
+
+        recorder = Recorder.new(server_context)
+        [recorder, recorder]
+      end
+
+      # Merge a cold compile's consulted decisions into the domain vocabulary.
+      # No-op in explicit-fingerprint mode (recorder is nil).
+      #: (domain: String, recorder: Recorder?) -> void
+      def learn!(domain:, recorder:)
+        return if recorder.nil?
+
+        @monitor.synchronize do
+          existing = @learned[domain] ||= []
+          seen = existing.to_set
+          recorder.consulted.each { |sig| existing << sig unless seen.include?(sig) }
+          @learned_flag[domain] = true
+        end
+      end
+
+      # The cache key for this domain + context, or nil when the domain has not
+      # been learned yet (auto mode), which forces a cold compile.
+      #: (domain: String, server_context: untyped) -> String?
+      def tools_list_key(domain:, server_context:)
+        fp = explicit_fingerprint(server_context)
+        if fp
+          components = ["fp", domain, defs_digest, stable(fp)]
+          return digest_key(components)
+        end
+
+        vocab, learned = @monitor.synchronize { [(@learned[domain] || []).dup, @learned_flag[domain]] }
+        return nil unless learned
+
+        sorted = vocab.sort_by(&:canonical)
+        vector = sorted.map { |sig| [sig.canonical, stable(evaluate(sig, server_context))] }
+        fingerprint = Digest::SHA256.hexdigest(sorted.map(&:canonical).join("\n"))[0, 12]
+        digest_key(["v", domain, defs_digest, fingerprint, vector])
+      end
+
+      # Digest of every registered tool's gating + contract source. Changes on
+      # deploy (gate edits, handler source mtime), invalidating cached entries
+      # without an explicit bust. Memoized; cleared by +reset!+.
+      #: () -> String
+      def defs_digest
+        @monitor.synchronize do
+          @defs_digest ||= compute_defs_digest
+        end
+      end
+
+      # Clear memoized store, learned vocabulary, and the defs digest. Called by
+      # the Engine reloader so code changes in development take effect.
+      #: () -> void
+      def reset!
+        @monitor.synchronize do
+          @store = nil
+          @learned = {}
+          @learned_flag = {}
+          @defs_digest = nil
+        end
+      end
+
+      private
+
+      #: (untyped) -> untyped
+      def resolve_store(setting)
+        case setting
+        when nil, false then NullStore.new
+        when :memory then MemoryStore.new
+        when :redis
+          RedisStore.new(
+            redis: McpAuthorization.config.tools_list_cache_redis,
+            url: McpAuthorization.config.tools_list_cache_redis_url
+          )
+        else
+          setting # assume a store-like object (responds to get/set)
+        end
+      end
+
+      #: (untyped) -> untyped
+      def explicit_fingerprint(server_context)
+        return nil unless server_context.respond_to?(:mcp_cache_fingerprint)
+
+        server_context.mcp_cache_fingerprint
+      rescue StandardError
+        nil
+      end
+
+      #: (Signature, untyped) -> untyped
+      def evaluate(sig, server_context)
+        target = sig.target == :user ? server_context.current_user : server_context
+        return :__no_target if target.nil?
+
+        target.public_send(sig.method, sig.arg)
+      rescue StandardError
+        :__error
+      end
+
+      #: (Array[untyped]) -> String
+      def digest_key(components)
+        "tl:" + Digest::SHA256.hexdigest(JSON.generate(components))
+      end
+
+      # Coerce a value into a stable, JSON-safe form for the key. Symbols become
+      # strings; anything exotic falls back to its inspect string.
+      #: (untyped) -> untyped
+      def stable(value)
+        case value
+        when Symbol then value.to_s
+        when String, Integer, Float, true, false, nil then value
+        when Array then value.map { |v| stable(v) }
+        when Hash then value.sort_by { |k, _| k.to_s }.map { |k, v| [k.to_s, stable(v)] }
+        else value.inspect
+        end
+      end
+
+      #: () -> String
+      def compute_defs_digest
+        sigs = McpAuthorization::ToolRegistry.registered_tools.map do |tool_class|
+          handler = (tool_class._contract_handler rescue nil)
+          source = handler_source_mtime(handler)
+          [
+            tool_class.tool_name.to_s,
+            (tool_class._gates || []).map { |g| [g[:name].to_s, g[:value].to_s] },
+            handler&.name.to_s,
+            source
+          ]
+        end.sort_by(&:first)
+        Digest::SHA256.hexdigest(JSON.generate(sigs))[0, 16]
+      rescue StandardError
+        # If anything about introspection fails, fall back to a process-stable
+        # digest so caching still works within a boot (just not across deploys
+        # via the digest — TTL still bounds staleness).
+        defined?(McpAuthorization::VERSION) ? McpAuthorization::VERSION : "mcpauth"
+      end
+
+      #: (untyped) -> Integer
+      def handler_source_mtime(handler)
+        return 0 unless handler
+
+        file = McpAuthorization::RbsSchemaCompiler.send(:find_source_file, handler)
+        file && File.exist?(file) ? File.mtime(file).to_i : 0
+      rescue StandardError
+        0
+      end
+    end
+  end
+end

data/lib/mcp_authorization/configuration.rb

@@ -79,6 +79,34 @@ module McpAuthorization
     #: bool
     attr_accessor :strict_schema
 
+    # Cache for the +tools/list+ response. Opt-in; defaults to no caching.
+    # Accepts:
+    #   nil / false  — no caching (default)
+    #   :memory      — process-local MemoryStore
+    #   :redis       — shared RedisStore (connection resolved from
+    #                  +tools_list_cache_redis+ / +tools_list_cache_redis_url+ /
+    #                  ENV["REDIS_URL"] / a bare Redis.new — the Rails redis config)
+    #   <object>     — any store responding to +get+/+set+
+    # See McpAuthorization::Cache for the keying strategy.
+    #: untyped
+    attr_accessor :tools_list_cache
+
+    # TTL (seconds) for cached +tools/list+ entries. Bounds staleness from
+    # out-of-band changes (e.g. a feature flag toggled with no deploy); the
+    # deploy digest invalidates on tool/schema changes independently.
+    #: Integer
+    attr_accessor :tools_list_cache_ttl
+
+    # Optional explicit Redis client for the :redis store. When nil, the store
+    # resolves a connection from +tools_list_cache_redis_url+, then
+    # ENV["REDIS_URL"], then a bare +Redis.new+.
+    #: untyped
+    attr_accessor :tools_list_cache_redis
+
+    # Optional explicit Redis URL for the :redis store.
+    #: String?
+    attr_accessor :tools_list_cache_redis_url
+
     #: () -> void
     def initialize
       @server_name = "mcp-authorization"
@@ -90,6 +118,10 @@ module McpAuthorization
       @context_builder = nil
       @cli_context_builder = nil
       @strict_schema = false
+      @tools_list_cache = nil
+      @tools_list_cache_ttl = 3600
+      @tools_list_cache_redis = nil
+      @tools_list_cache_redis_url = nil
     end
   end
 end

data/lib/mcp_authorization/engine.rb

@@ -46,6 +46,7 @@ module McpAuthorization
       app.reloader.to_prepare do
         McpAuthorization::ToolRegistry.reset!
         McpAuthorization::RbsSchemaCompiler.reset_cache!
+        McpAuthorization::Cache.reset!
       end
     end
 

data/lib/mcp_authorization/rbs_schema_compiler.rb

@@ -1476,10 +1476,22 @@ module McpAuthorization
         current_body = +""
 
         content.each_line do |line|
-          if line =~ /# @rbs type (\w+) = \{/
+          if line =~ /#\s*@rbs type (\w+)\s*=\s*(\{.*)$/
+            # Start of a record alias. Capture the body from the first `{` to
+            # end of line (minus any trailing comment), so a record written on
+            # one line — `# @rbs type ok = { a: String }` — is captured whole
+            # rather than truncated to a bare `{` (which silently dropped the
+            # alias). If the braces already balance it's a single-line record;
+            # otherwise keep accumulating on the following lines. Whitespace
+            # around `=` is tolerated so column-aligned aliases still parse.
             current_name = $1.to_s
-            current_body = "{"
-          elsif line =~ /# @rbs type (\w+) = "([^"]+)"/
+            current_body = +strip_rbs_comment($2.to_s)
+            if brace_balanced?(current_body)
+              aliases[current_name] = current_body
+              current_name = nil
+              current_body = +""
+            end
+          elsif line =~ /#\s*@rbs type (\w+)\s*=\s*"([^"]+)"/
             aliases[$1.to_s] = parse_string_union($2.to_s, line, content)
           elsif current_name
             stripped = strip_rbs_comment(line.strip.sub(/^#\s*/, ""))

data/lib/mcp_authorization/tool_registry.rb

@@ -73,6 +73,23 @@ module McpAuthorization
         end
       end
 
+      # Concrete MCP::Tool subclass for a single named tool within a domain,
+      # or nil when the tool is unknown in that domain or the current user is
+      # not permitted to use it.
+      #
+      # Materializing a per-user schema is the dominant cost of handling an MCP
+      # request, so a +tools/call+ — which targets exactly one tool — should
+      # compile that one tool rather than the whole domain (what
+      # +tool_classes_for+ does for +tools/list+).
+      #: (domain: String, name: String, server_context: untyped) -> singleton(MCP::Tool)?
+      def tool_class_for(domain:, name:, server_context:)
+        tool_class = (tools_by_domain[domain] || []).find { |tc| tc.tool_name == name }
+        return nil unless tool_class
+        return nil unless tool_class.permitted?(server_context)
+
+        tool_class.materialize_for(server_context)
+      end
+
       # Look up a tool by its MCP tool name across all domains.
       #: (String) -> singleton(McpAuthorization::Tool)?
       def find_tool(name)

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.5.5"
+  VERSION = "0.6.0"
 end

data/lib/mcp_authorization.rb

@@ -6,6 +6,7 @@ require_relative "mcp_authorization/dsl"
 require_relative "mcp_authorization/rbs_schema_compiler"
 require_relative "mcp_authorization/tool_registry"
 require_relative "mcp_authorization/tool"
+require_relative "mcp_authorization/cache"
 require_relative "mcp_authorization/engine" if defined?(Rails)
 
 # MCP Authorization — schema-shaping authorization for MCP tool servers.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.6.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -94,6 +94,11 @@ files:
 - README.md
 - app/controllers/mcp_authorization/mcp_controller.rb
 - lib/mcp_authorization.rb
+- lib/mcp_authorization/cache.rb
+- lib/mcp_authorization/cache/memory_store.rb
+- lib/mcp_authorization/cache/null_store.rb
+- lib/mcp_authorization/cache/recorder.rb
+- lib/mcp_authorization/cache/redis_store.rb
 - lib/mcp_authorization/configuration.rb
 - lib/mcp_authorization/diagnostics.rb
 - lib/mcp_authorization/dsl.rb