mcp_authorization 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '058c192ec678d3ceb11d6ae5fed31c1025156a83d40cf12f7458054f50935682'
-  data.tar.gz: 00aee0863c22ead686543f40e8658a3a019711db84c8554c28bcac287bc51253
+  metadata.gz: 68b3436ab106d889c6ec4c889e9fef24235db5a5fcd64d840a0365fa3fa3b313
+  data.tar.gz: 36946f67a327d9f7ab7a2cea555fb35b16d12d0afab370bdfe80a9dc3b20f5db
 SHA512:
-  metadata.gz: aeeb0fa5ab4074654132516b58e0b649aa3eaf3012b3703e98cb9d519c440f39f5bc080bde6947f802a8169073dc03dc1ee2cdf6ffc91b77f520182c7741a143
-  data.tar.gz: 89d8566f176bb0c6cb53cc84ca933adb01e858df69caa320d9d480759b7479efd814f6392c25fe61ecfef891c6246b7fbc0c6a349ba9c6892a01f1370c9f6255
+  metadata.gz: 873fd4f953cfcf45d561b897da001d54155315a3f1add2fab2785b4abc11018af972c8aaeaf6b196031ecac8dad44e1ba52d33b0c945d63309beac0b2332c092
+  data.tar.gz: 8da192fdc1e11c65dc84bfbc0ec4c5ed80042279283c784bfa7d7fe55958ce11f216b10ec7b523aa3723b23e685ae3eac67e8f73f3e3466266c65916daeead12

data/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.8.0]
+
+A supported seam for tool classes the host generates at runtime instead of
+defining in a file under `tool_paths`. Additive and opt-in — a host that sets
+no producers behaves exactly as before. (#35)
+
+### Added
+- **`config.tool_producers`** — an array of callables that register generated tool classes. Invoked by `ToolRegistry.ensure_tools_loaded!` on the first read of a registry that has not finished loading, immediately after the `tool_paths` eager-load, and again after every `reset!`. Defaults to `[]`.
+
+  Registering generated tools previously had no supported hook, so hosts improvised one from a Rails boot callback — and both available callbacks are traps. Registering *before* the gem's own load tripped `ensure_tools_loaded!`'s old `return if @registered_tools&.any?` guard and silently suppressed every file-defined tool, leaving a near-empty `tools/list` in any environment that doesn't eager-load. Registering from `config.to_prepare` runs host code during `:run_prepare_callbacks`, which precedes `:eager_load!` and the railtie `after_initialize` that copies `config.i18n` onto `I18n` — so application code loaded there sees an empty `I18n.load_path`, and any class resolving a translation in its class body freezes `"Translation missing: …"` into its validators and option lists permanently, with the failures landing nowhere near MCP. Running producers from a registry read makes both unreachable by construction rather than by documentation.
+
+- **Boot-time registry population when the host eager-loads.** The Engine reads the registry from `after_initialize` when `config.eager_load` is on, so a malformed tool — or a producer that raises — fails the deploy rather than the first `tools/list`. Development and test stay lazy. `after_initialize` specifically: it is the earliest phase where the framework is guaranteed to be fully configured, `I18n` included.
+
+### Changed
+- **Loading completion is tracked separately from registry contents.** `ensure_tools_loaded!` previously short-circuited on `return if @registered_tools&.any?`, and `registered_tools` only triggered a load while the array was empty. That conflated "the registry has entries" with "loading finished", which is wrong as soon as loading can fail partway: `eager_load_tool_paths!` registers the file-defined tools *first*, so by the time a producer raises the array is already non-empty — as it also is when a producer registers 40 tools and raises on the 41st. Every later read then no-op'd, so a bad producer failed loudly exactly once and silently forever after, leaving a permanently incomplete surface and contradicting the documented "exceptions propagate" contract. A dedicated `@tools_loaded` flag, set only after every producer returns, replaces both guards; a raising producer is now retried on every read until it is fixed. Re-running is safe — `register` dedupes by identity and `eager_load_dir` is a no-op on an already-loaded directory.
+
+  Two consequences worth naming. A host that calls `register` directly before the first read no longer suppresses the `tool_paths` load — the silent-erasure hazard producers exist to remove is now unreachable from that direction too. And `reset!` clears the flag, so a reload still reloads.
+
+### Fixed
+- **`ensure_tools_loaded!` no longer raises on a partially-loaded Rails.** The autoloader pass guarded on the bare `Rails` constant and then called `Rails.root` / `Rails.autoloaders`. A process where `Rails` is defined but incomplete (or an unrelated module of that name) satisfied `defined?` and raised `NoMethodError`, taking `registered_tools` down with it — including for a host whose tools all come from producers and need no autoloader at all. It now probes for the methods it actually calls, matching the `defined?(Rails) && Rails.respond_to?(:env)` idiom already used in `Diagnostics`.
+
+### Internal
+- `ensure_tools_loaded!` is reentrant: a producer may read the registry (to inspect what is already registered, say) without recursing forever. The reentrancy guard is cleared in an `ensure`, so a raising producer does not wedge every later read.
+- The `tool_paths` eager-load moved into a private `eager_load_tool_paths!`, leaving `ensure_tools_loaded!` as the ordering contract it documents.
+
 ## [0.7.1]
 
 Follow-ups from the 0.7.0 review (onboardiq/mcp_authorization#31).

data/README.md

@@ -1,4 +1,5 @@
 # mcp_authorization
+[read it](https://fountain.engineering/mcp_authorization/)
 
 Rails engine for serving MCP tools with per-request schema discrimination compiled from RBS type annotations.
 
@@ -6,6 +7,10 @@ Add it to your Gemfile and your Rails app speaks [MCP](https://modelcontextproto
 
 > Looking for task-oriented "how do I X?" recipes rather than reference? See the **[Cookbook](COOKBOOK.md)**.
 
+<!-- site:skip -->
+> Prefer these docs as a browsable site, one section per page? **<https://fountain.engineering/mcp_authorization>** — built from these same files by [`site/collect.rb`](site/collect.rb).
+<!-- site:endskip -->
+
 ## Three layers of authorization
 
 The gem gives you three independent controls over what each user sees:
@@ -66,9 +71,22 @@ end
 | `mount_path` | `"/mcp"` | URL prefix for MCP endpoints |
 | `default_domain` | `"default"` | Domain when no `:domain` segment in path |
 | `tool_paths` | `["app/mcp"]` | Directories where tool classes live (relative to Rails.root) |
+| `tool_producers` | `[]` | Callables that register tool classes built at runtime — see [Generated tools](#generated-tools) |
 | `shared_type_paths` | `["sig/shared"]` | Directories where shared `.rbs` type files live |
 | `context_builder` | *required* | `(request) -> context` |
 | `cli_context_builder` | `nil` | `(domain:, role:) -> context` for rake tasks |
+| `strict_schema` | `false` | Emit stricter compiled schemas |
+| `tools_list_cache` | `nil` | `:memory`, `:redis`, or any object responding to `get`/`set` — see [Caching `tools/list`](#caching-toolslist) |
+| `tools_list_cache_ttl` | `3600` | Per-entry TTL in seconds |
+| `tools_list_cache_redis` | `nil` | Explicit Redis client for the `:redis` store |
+| `tools_list_cache_redis_url` | `nil` | Explicit Redis URL; falls back to `ENV["REDIS_URL"]`, then `Redis.new` |
+
+Two configuration **methods** (not attributes) turn a domain into grouped facades — see [Tool grouping](#tool-grouping-facades):
+
+| Method | Purpose |
+|---|---|
+| `facet_domain :domain, group_by: :category, ...` | Present this domain as one facade tool per category. Optional `schema_strategy:`, `uncategorized:`, `facade_suffix:`. |
+| `categories { summary :key, "text" }` | Declare one summary line per group, used as each facade description's lead. |
 
 ## The contract
 
@@ -293,6 +311,7 @@ class MyTool < McpAuthorization::Tool
   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
+  category :orders                # group this tool belongs to in a faceted domain
   read_only!                      # MCP annotation hints
   dynamic_contract MyService      # handler class
 end
@@ -304,6 +323,7 @@ end
 | `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"]`. |
+| `category :name` | Group this tool belongs to when its domain is faceted (see [Tool grouping](#tool-grouping-facades)). Ignored in flat domains. Optional `summary:` kwarg supplies the group summary for single-tool groups. |
 | `dynamic_contract HandlerClass` | Handler providing description, schemas, and execution |
 | `read_only!` | Annotation: tool only reads data |
 | `not_destructive!` | Annotation: tool does not destroy data |
@@ -316,6 +336,47 @@ end
 
 Tools self-register when loaded. Put them anywhere under `tool_paths` (default: `app/mcp/`).
 
+### Generated tools
+
+Some tools aren't worth writing by hand — one per controller action, one per row in a config table, one per endpoint in a family. For those, register a **producer**: a callable that mints the classes and registers them.
+
+```ruby
+McpAuthorization.configure do |config|
+  config.tool_producers << -> { MyApp::GeneratedTools.register_all! }
+end
+```
+
+Producers run from `ToolRegistry.ensure_tools_loaded!` — on the first read of an empty registry, immediately after `tool_paths` is eager-loaded, and again after every reload. Two properties follow from that, and both matter:
+
+- **Don't register from a Rails boot callback instead.** Generating tools usually means loading the code they derive from, and from `config.to_prepare` that happens during `:run_prepare_callbacks` — before `:eager_load!`, and before railties copy `config.i18n` onto `I18n`. Application code loaded that early sees an empty `I18n.load_path`, so any class resolving a translation in its class body freezes `"Translation missing: …"` into its validators and option lists for the life of the process. A producer sidesteps the ordering question entirely.
+- **Don't register before the registry loads its own tools.** Historically `ensure_tools_loaded!` skipped the `tool_paths` pass once the registry was non-empty, so registering first made every file-defined tool silently disappear from `tools/list`. Producers run *after* that pass, and completion is now tracked separately from "the registry has entries", so the ordering is not yours to get right.
+
+A producer must be **idempotent**. `register` dedupes by object identity, not by `tool_name`, so minting a fresh class on every call registers a second tool under the same name and leaves `find_tool` resolving an arbitrary one. Reuse the class while its inputs are unchanged. Exceptions propagate — a malformed generated tool fails the read rather than vanishing.
+
+When the host eager-loads (production), the engine reads the registry at `after_initialize`, so a producer that raises fails the deploy instead of the first `tools/list`. Development and test stay lazy.
+
+### Introspecting a tool class
+
+Every declaration is readable back off the class, which is what the registry, the facade builder, and the cache digest use:
+
+| Reader | Returns |
+|---|---|
+| `_permission` | The symbol passed to `authorization` |
+| `_gates` | `[{ name:, value: }, ...]` for every declared gate |
+| `_tags` | Declared domains |
+| `_category` | Declared category symbol, or `nil` |
+| `_category_summary` | Summary passed to `category(summary:)`, or `nil` |
+| `_contract_handler` | The handler class |
+
+`ToolRegistry` is the entry point for turning those declarations into MCP tools:
+
+| Registry method | Purpose |
+|---|---|
+| `tool_classes_for(domain:, server_context:)` | Every permitted tool in a domain (the `tools/list` path) |
+| `tool_class_for(domain:, name:, server_context:)` | One named tool, or `nil` (the `tools/call` path) |
+| `facades_for(domain:, server_context:)` | Facades for a faceted domain |
+| `facade_for(domain:, name:, server_context:)` | One facade by name |
+
 ## Contract validation
 
 If a handler is missing required methods or schema definitions, the gem raises an `ArgumentError` on first request with a full diagnostic:
@@ -384,6 +445,19 @@ McpAuthorization.configure do |config|
 end
 ```
 
+Grouping is opt-in and per-domain: a domain with no `facet_domain` behaves
+exactly as before, and `category` is inert there. `facet_domain` takes:
+
+| Option | Default | Description |
+|---|---|---|
+| `group_by:` | *required* | Grouping key. Only `:category` today; anything else raises `ArgumentError`. |
+| `schema_strategy:` | `:vendor_extension` | Where per-tool argument schemas go — `:vendor_extension` or `:lazy` (below). |
+| `uncategorized:` | `:fallback` | `:fallback` collects tools with no `category` into an `uncategorized` group; `:error` raises instead. |
+| `facade_suffix:` | `"tools"` | Token appended to a category to form the facade name (`orders_tools`). |
+
+For a group that holds a single tool, `category :orders, summary: "..."` saves a
+trip to the central registry. When both are declared, `config.categories` wins.
+
 `tools/list` for the domain then returns one facade per group the caller has
 at least one permitted tool in (`orders_tools`, `billing_tools`), each
 describing its tools with RBAC-filtered one-liners. Calling a facade names the
@@ -394,10 +468,40 @@ inner tool and its arguments:
   "arguments": { "tool_name": "update_order", "arguments": { "id": "o_1" } } }
 ```
 
-Dispatch resolves the real tool through its normal call path — authorization,
-gating, and schema filtering apply exactly as if the tool had been called
-directly, and JSON-string argument blobs are coerced against the *target*
-tool's schema.
+### Facade shape
+
+| Part | Value |
+|---|---|
+| Name | `"#{category}_#{facade_suffix}"` — default suffix `tools`, so `orders_tools` |
+| Description | Group summary, then one line per tool the caller may invoke: `- tool_name — first line of that tool's description for this caller` |
+| `inputSchema` | Flat object: `tool_name` (string enum of permitted tool names) + `arguments` (object). Both required. |
+| `_meta` | Under `:vendor_extension`, key `"tool-input-schemas"` — a map of tool name to that caller's compiled input schema |
+
+### Facade dispatch
+
+Dispatch resolves the real tool through its normal call path — there is no
+second code path, and therefore no second place for authorization to be wrong:
+
+1. **Advertised-set check.** `tool_name` must be in the set advertised to *this*
+   caller, else `ArgumentError` listing the valid names.
+2. **Re-resolution.** The tool is re-fetched via `ToolRegistry.tool_class_for`,
+   which re-runs `permitted?` — so a stale advertised set cached by a client
+   cannot get a caller into a tool they've lost access to. Failure raises
+   `NotAuthorizedError`.
+3. **Argument coercion.** MCP clients frequently serialize nested objects as JSON
+   strings, and the facade's generic `arguments: object` contract cannot know
+   which fields are structured. The `arguments` blob itself, and any top-level
+   value whose type in the *target's* compiled schema is `object` or `array`, are
+   JSON-parsed. Invalid JSON raises `ArgumentError` naming the field.
+4. **Delegation.** The target's materialized `call` runs, applying `filter_input`
+   and `filter_output` exactly as in a direct call.
+
+Direct tool names still resolve on `tools/call`, so a client that learned a
+real tool name before the domain was faceted keeps working.
+
+A `tools/call` build skips the `_meta` per-tool schema map (`for_dispatch: true`)
+— nothing on the call path reads it, and building it would recompile every tool
+in the group on every call.
 
 The facade `inputSchema` is always a flat object (a `tool_name` enum plus a
 permissive `arguments` object). It has to be: an LLM tool `input_schema` must
@@ -417,13 +521,31 @@ therefore only chooses where the per-tool schemas go:
 
 Uncategorized tools land in an `uncategorized` facade by default; pass
 `uncategorized: :error` to fail fast instead. Groups with zero permitted tools
-are hidden entirely, so a facade never advertises an empty `enum`.
+are hidden entirely, so a facade never advertises an empty `enum`. A facade
+name that collides with a real registered tool in the domain raises
+`FacadeBuilder::FacadeNameCollisionError` rather than shadowing that tool.
 
 Facade names are `#{category}_tools` by default. Override the suffix per domain
 with `facade_suffix:` — e.g. `config.facet_domain :admin, group_by: :category,
 facade_suffix: "hire"` exposes `orders_hire`, `billing_hire`. The suffix must be
 a lowercase identifier fragment (`[a-z0-9_]`) so the derived name stays a valid
-MCP tool name. See `docs/designs/tool-grouping-facades.md` for the full design.
+MCP tool name. See [the design doc](docs/designs/tool-grouping-facades.md) for
+the full rationale.
+
+Facet configuration participates in the [`tools/list` cache](#caching-toolslist)
+digest — each tool's `category`, every `facet_domain` setting, and every group
+summary — so toggling grouping or rewording a summary invalidates cached
+listings the same way a gate change does.
+
+### Facade errors
+
+| Error | Raised when |
+|---|---|
+| `FacadeBuilder::UncategorizedToolError` | A tool has no `category` in a domain faceted with `uncategorized: :error` |
+| `FacadeBuilder::FacadeNameCollisionError` | A derived facade name collides with a registered tool in the domain |
+| `ArgumentError` (config) | Invalid `group_by:`, `schema_strategy:`, `uncategorized:`, or `facade_suffix:` |
+| `ArgumentError` (dispatch) | `tool_name` not advertised, or a string argument that isn't valid JSON |
+| `NotAuthorizedError` | Re-resolution found the caller isn't permitted after all |
 
 ## RBS type syntax
 
@@ -458,6 +580,16 @@ The `@rbs type` comments compile to JSON Schema:
 # @rbs type input = { id: String, status: status }
 ```
 
+Every handler must declare `@rbs type output`. It may be a single record, a reference, or a union:
+
+```ruby
+# @rbs type output = { id: String }        # inline record
+# @rbs type output = applicant             # reference
+# @rbs type output = success | error       # union
+```
+
+When a type appears more than once in a compiled schema, it is hoisted into `$defs` and referenced with `$ref` rather than inlined repeatedly. This is automatic — nothing to declare.
+
 ### Constraint and annotation tags
 
 Tag any field in a `#:` annotation or `@rbs type` record to add JSON Schema constraints. Tags are written as `@tag(value)` after the type:
@@ -557,6 +689,17 @@ end
 
 The `@min` / `@max` tags are type-aware: on strings they emit `minLength`/`maxLength`, on numbers `minimum`/`maximum`, and on arrays `minItems`/`maxItems`.
 
+### Where tags may appear
+
+| Position | Effect |
+|---|---|
+| On a param in `#:` | Constrains or gates that input field |
+| On a field in an `@rbs type` record | Constrains or gates that output field |
+| On a member of an `@rbs type` union | Gates that whole output variant |
+| On an inline literal union member | Gates that individual member |
+
+A tag trailing a whole inline literal union applies to the **field**, not to the last member — the compiler distinguishes the two by whether any non-final member carries a tag.
+
 ### Multiline `#:` annotations
 
 The `#:` annotation above `def call` supports multiple lines. Each line starts with `#:`:
@@ -611,6 +754,70 @@ MCP clients can narrow on `success: const true` vs `success: const false` -- the
 
 Source files are parsed once at boot and cached in memory. Only `@requires` filtering runs per request (hash lookups and `can?` calls). In development, caches are cleared automatically on file change via the Rails reloader.
 
+Per-request work is also scoped to what the incoming JSON-RPC method actually needs, since per-tool schema compilation is the dominant cost of an MCP request:
+
+| Method | Tools materialized |
+|---|---|
+| `tools/list` | Every permitted tool in the domain |
+| `tools/call` | Only the invoked tool |
+| `initialize`, `notifications/initialized`, `ping`, GET stream probe | None |
+| Unrecognized shape (e.g. a batch with no top-level `method`) | Full domain, so routing stays correct |
+
+In a 140-tool domain that took a `tools/call` from ~2.6s to under 100ms and `notifications/initialized` from ~2s to ~1ms, with no change to `tools/list` output. What remains is the listing itself — which is cacheable (below) and, for very large domains, [groupable](#tool-grouping-facades).
+
+## Caching `tools/list`
+
+`tools/list` must materialize a per-user schema for every tool in a domain. That cost can be cached. Default is no caching, so nothing changes unless you opt in:
+
+```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
+```
+
+| Store | Behavior |
+|---|---|
+| `:memory` | Process-local, bounded LRU with per-entry TTL |
+| `:redis` | Shared across processes, JSON values, per-entry TTL |
+| custom object | Anything responding to `get`/`set` |
+| *(unset)* | `NullStore` — no caching |
+
+The Redis 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.
+
+### The key is a decision vector, not an identity
+
+```
+H(domain + tool_defs_digest + vocab_fingerprint + decision_vector)
+```
+
+The **decision vector** is the result of every gating decision the domain's compilation consults — `@requires` / `@feature` / `@tier` / custom predicates, tool-level `gate` and `authorization`, and `current_user.can?` / `default_for`. It never includes user or account identity.
+
+Two contexts that answer all of those identically produce identical schemas by construction, so they 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` (each tool's gates plus handler source, plus facet configuration) changes on deploy, auto-invalidating stale entries; the TTL bounds out-of-band staleness, such as a permission changed directly in the database.
+
+### Two ways to supply the vector
+
+**Automatic.** On the first (cold) compile the gem wraps the context in a `Cache::Recorder`, learns the domain's predicate vocabulary, then replays that vocabulary against the live context on later requests.
+
+**Explicit.** If the server context responds to `mcp_cache_fingerprint`, its return value is used verbatim as the decision component and the recorder is skipped:
+
+```ruby
+class ServerContext
+  def mcp_cache_fingerprint
+    [current_user.role, account.enabled_features.sort, account.plan_tier]
+  end
+end
+```
+
+Explicit wins when present. Reach for it when gating depends on something the recorder cannot observe, or when you would rather own the invalidation contract than infer it.
+
+### Operational notes
+
+- **Cache outages fail open** — a `get`/`set` error is logged and behaves as a miss, never breaking `tools/list`.
+- **Only successful listings are cached.** Error and unexpected responses render but are not stored.
+- **A hit still rebuilds the envelope** — the cached `result` is re-wrapped with the live JSON-RPC id.
+- **Development reloads clear it** (the reloader calls `Cache.reset!`), so an edited annotation shows up immediately.
+
 ## Development
 
 ### Live reload

data/lib/mcp_authorization/configuration.rb

@@ -50,6 +50,27 @@ module McpAuthorization
     #: Array[String]
     attr_accessor :tool_paths
 
+    # Callables that register tool classes the host generates at runtime,
+    # rather than defining in a file under +tool_paths+.
+    #
+    #   config.tool_producers << -> { MyApp::GeneratedTools.register_all! }
+    #
+    # Invoked by +ToolRegistry.ensure_tools_loaded!+ after the +tool_paths+
+    # eager-load, on the first read of an empty registry. Because a producer
+    # runs from a registry read rather than a Rails boot callback, it cannot
+    # execute before the framework is fully configured — see
+    # +ToolRegistry.ensure_tools_loaded!+ for why that matters.
+    #
+    # A producer must be idempotent: +register+ dedupes by object identity,
+    # not by +tool_name+, so minting a fresh class on every call registers a
+    # second tool under the same name and leaves +find_tool+ resolving an
+    # arbitrary one. Reuse the class while its inputs are unchanged.
+    #
+    # Exceptions propagate — a malformed generated tool fails the read rather
+    # than silently vanishing from the surface.
+    #: Array[^() -> void]
+    attr_accessor :tool_producers
+
     # Directories (relative to +Rails.root+) where shared +.rbs+ type
     # files live. Used by RbsSchemaCompiler to resolve +# @rbs import+.
     #: Array[String]
@@ -151,6 +172,7 @@ module McpAuthorization
       @server_name = "mcp-authorization"
       @server_version = "1.0.0"
       @tool_paths = %w[app/mcp]
+      @tool_producers = []
       @shared_type_paths = %w[sig/shared]
       @default_domain = "default"
       @mount_path = "/mcp"

data/lib/mcp_authorization/engine.rb

@@ -50,6 +50,23 @@ module McpAuthorization
       end
     end
 
+    # Populate the registry at boot when the host eager-loads (production), so
+    # a malformed tool — or a +tool_producers+ callable that raises — fails the
+    # deploy instead of the first +tools/list+.
+    #
+    # +after_initialize+ specifically: this read may load a large part of the
+    # host application, and it is the earliest phase where the framework is
+    # guaranteed to be fully configured — notably +I18n+, which railties only
+    # wire up in this same phase. Rails cannot have loaded this Engine before
+    # its own railties, so this block is always registered after theirs, and
+    # load hooks run in registration order.
+    #
+    # Development and test stay lazy: nothing loads until something reads the
+    # registry.
+    config.after_initialize do |app|
+      McpAuthorization::ToolRegistry.registered_tools if app.config.eager_load
+    end
+
     # Prepend MCP routes into the host app's router. Uses +prepend+ so the
     # MCP endpoint is available before any catch-all routes the host may
     # define. Supports both domain-scoped and bare paths.

data/lib/mcp_authorization/tool_registry.rb

@@ -24,22 +24,65 @@ module McpAuthorization
       end
 
       # All registered tool classes. Triggers eager loading on first access.
+      #
+      # Gated on "loading finished", not on "the array has entries" — see
+      # +ensure_tools_loaded!+ for why those must not be conflated.
       #: () -> Array[singleton(McpAuthorization::Tool)]
       def registered_tools
         tools = (@registered_tools ||= [])
-        ensure_tools_loaded! if tools.empty?
+        ensure_tools_loaded! unless @tools_loaded
         tools
       end
 
-      # Force-loads tool directories so tool classes self-register.
+      # Force-loads tool directories so tool classes self-register, then runs
+      # +config.tool_producers+ for tools the host generates at runtime.
+      #
+      # Deliberately lazy, and the ordering here is the contract:
+      #
+      # * *Producers run last*, inside this method, so a host cannot register a
+      #   generated tool ahead of the +tool_paths+ eager-load and suppress it.
+      #
+      # * *Producers run on a registry read, never from a boot callback.*
+      #   Generating tool classes means loading the code they derive from,
+      #   which in a Rails app pulls in a large share of the application. Doing
+      #   that from +config.to_prepare+ runs it during +:run_prepare_callbacks+,
+      #   which precedes +:eager_load!+ and +:finisher_hook+ — and +config.i18n+
+      #   is only copied onto +I18n+ from a railtie-level +after_initialize+.
+      #   Application code loaded that early sees an empty +I18n.load_path+, so
+      #   any class resolving a translation in its class body freezes
+      #   "Translation missing: ..." into validators and option lists
+      #   permanently. Deferring to first read sidesteps the whole ordering
+      #   question rather than asking each host to solve it.
+      #
+      # * *Producers re-run after +reset!+.* The Engine resets the registry on
+      #   every code reload; the next read repopulates it, producers included.
+      #
+      # +@tools_loaded+ tracks completion, and is set only after every producer
+      # has returned. It deliberately does NOT reuse "is +@registered_tools+
+      # non-empty?" as the signal, because a non-empty registry does not mean
+      # loading succeeded: +eager_load_tool_paths!+ registers the file-defined
+      # tools first, so by the time a producer raises the array is already
+      # populated — as it also is when a producer registers 40 tools and raises
+      # on the 41st. Guarding on that would make the failure loud exactly once
+      # and silent forever after, leaving a permanently incomplete surface. The
+      # contract is the opposite: a producer that raises fails *every* read until
+      # it is fixed. Re-running is safe — +register+ dedupes by identity and
+      # +eager_load_dir+ is a no-op on an already-loaded directory.
+      #
+      # The reentrancy guard lets a producer call back into the registry (to
+      # inspect what is already registered, say) without recursing forever.
       #: () -> void
       def ensure_tools_loaded!
-        return if @registered_tools&.any?
-        return unless defined?(Rails)
+        return if @tools_loaded
+        return if @loading_tools
 
-        McpAuthorization.config.tool_paths.each do |path|
-          full_path = Rails.root.join(path)
-          Rails.autoloaders.main.eager_load_dir(full_path) if File.directory?(full_path)
+        @loading_tools = true
+        begin
+          eager_load_tool_paths!
+          McpAuthorization.config.tool_producers.each(&:call)
+          @tools_loaded = true
+        ensure
+          @loading_tools = false
         end
       end
 
@@ -115,9 +158,30 @@ module McpAuthorization
       end
 
       # Clear the registry. Called by the Engine's reloader on code change.
+      # The next read reloads +tool_paths+ and re-runs +tool_producers+.
       #: () -> void
       def reset!
         @registered_tools = []
+        @loading_tools = false
+        @tools_loaded = false
+      end
+
+      private
+
+      # Probes for the methods actually called rather than the bare constant,
+      # matching Diagnostics' `defined?(Rails) && Rails.respond_to?(:env)`.
+      # A partially-loaded Rails (or an unrelated `Rails` module in a non-Rails
+      # process) satisfies `defined?` and then raises NoMethodError on `.root`,
+      # which would take `registered_tools` down with it — including for a host
+      # whose tools all come from `tool_producers` and need no autoloader.
+      #: () -> void
+      def eager_load_tool_paths!
+        return unless defined?(Rails) && Rails.respond_to?(:root) && Rails.respond_to?(:autoloaders)
+
+        McpAuthorization.config.tool_paths.each do |path|
+          full_path = Rails.root.join(path)
+          Rails.autoloaders.main.eager_load_dir(full_path) if File.directory?(full_path)
+        end
       end
     end
   end

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails