mcp_authorization 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d09c532c9c775775e5b5dbea5d44df18cb9a693212641fff9b86621101806e4a
-  data.tar.gz: 18c5e6cc485efd2e73265e22d4ab037f3b21d32f72c377285794a644c8d4a225
+  metadata.gz: b1dabd038e65fbf04f01e9ae27d109e8734ae78b4db4baeaa6d20200291a3899
+  data.tar.gz: 0250e2902b73117cfe4447f6036783e4a49613ee4626a407560a82bd19bf25ef
 SHA512:
-  metadata.gz: 27959d3f62484456e2e6978f51cef90d8879584a978c4f4937e52fa599451c01ad41cfea2cb79607726ab2dcba166f50917c46b0bc0057639d1fba5aa4b4a249
-  data.tar.gz: cbdc8f8187594e942afc039248a8f8db638325b33f257972d85e5d8cbb62ec8d64f6e9f57b8e1ca022f9e1cbae1f7a0d590fa3cb5ea5784ad9cb87e20072e20a
+  metadata.gz: fbdfb8c28047b39373227ece236670dfc6df6ee34a32ca36f77d6b49f3e31ba7859d82a4c998ff505534ca3e55611f506d7b20a976cd0095a54ce03bc2377a66
+  data.tar.gz: 6ba9ec325debe3564cca6f8b5fdbee732aab893e1dc744d261fbac53db22772b619b764c1a4d9bb9baff59961d5352b334a9c56e171fda8c44da8e4a5d052a79

data/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.7.0] - 2026-07-21
+
+Declarative tool grouping: a domain can present its tools as a small set of
+summarized category facades instead of a flat list, with per-tool schemas
+deferred out of the selection prompt. Opt-in and per-domain — domains not
+configured via `facet_domain` behave exactly as before. (#30)
+
+### Added
+- **`category :name` tool DSL.** A tool declares the group it belongs to when its domain is faceted; ignored in flat domains. An optional `summary:` kwarg serves single-tool groups; the central registry wins on conflict.
+
+- **`config.facet_domain :admin, group_by: :category`** — present a domain as grouped facades. `tools/list` returns one facade per group the caller has at least one permitted tool in (e.g. `orders_tools`), each with a routing-only description: the group summary plus RBAC-filtered one-liners of the tools the caller may actually invoke. Groups with zero permitted tools are hidden entirely, so a facade never advertises an empty `enum` (which fails JSON Schema draft-04 validation and can fail the whole `tools/list`).
+
+- **`config.categories { summary :orders, "..." }`** — one summary line per group, used as the facade description's lead.
+
+- **`facet_domain(..., facade_suffix:)`** — override the token appended to a category to form its facade tool name. Defaults to `"tools"` (`orders_tools`); e.g. `facade_suffix: "hire"` exposes `orders_hire`. Must be a lowercase identifier fragment (`[a-z0-9_]`). The suffix is folded into the tools/list cache digest, so changing it invalidates cached listings.
+
+- **Deferred-schema strategy** per domain via `schema_strategy:`. The facade `inputSchema` is always a flat object (`tool_name` enum + permissive `arguments`): an LLM tool `input_schema` must have an object root — Anthropic and OpenAI reject `oneOf`/`allOf`/`anyOf` at the top level — and hosts forward a facade's `inputSchema` straight to the model, so a correlated inline shape (each `tool_name` tied to its argument schema) is not expressible and is not offered. `:vendor_extension` (default) carries the per-tool schemas on the facade's `_meta` (key `"tool-input-schemas"`) — the MCP-sanctioned extension channel that SDKs preserve and that is never forwarded to the model as `input_schema` — for a client that wants to expand the facade. `:lazy` carries names only; argument shapes are enforced at dispatch. In both strategies the per-tool schemas are compiled per caller, so permission-gated fields never appear in a facade a caller receives.
+
+- **Facade dispatch through the real call path.** A `tools/call` on a facade names the inner tool (`tool_name`) and its `arguments`. Dispatch checks the name against the set advertised to *this* caller, re-resolves the tool via `ToolRegistry.tool_class_for` — which re-runs `permitted?`, so gating is enforced even against a stale advertised set — and delegates to the tool's materialized `call`. Input filtering, output filtering, and `NotAuthorizedError` behave exactly as in a direct call, because it is the same code.
+
+- **Argument coercion against the target tool's schema.** MCP clients frequently serialize nested objects as JSON strings; the facade's generic `arguments: object` contract cannot know which fields to parse. Both the `arguments` blob itself and any top-level value whose *target* schema type is an object or array are JSON-parsed before dispatch, then stripped by the target's `filter_input` as usual.
+
+- **`uncategorized:` mode** — a tool without a `category` in a faceted domain lands in an `uncategorized` fallback group by default; `uncategorized: :error` raises instead for servers that want CI-enforced completeness. A facade name that collides with a real registered tool raises `FacadeNameCollisionError` rather than shadowing the tool.
+
+- **`ToolRegistry.facades_for(domain:, server_context:)` / `facade_for(domain:, name:, server_context:)`** — the facade analogues of `tool_classes_for` / `tool_class_for`. `McpController` routes `tools/list` on a faceted domain to facades and resolves facade names on `tools/call` (direct tool names still resolve, so a client that learned a real tool name keeps working).
+
+### Changed
+- **The `tools/list` cache defs digest now folds in facet configuration.** Each tool's `category`, every `facet_domain` setting, and every group summary participate in the digest, so toggling grouping, switching schema strategy, or rewording a summary invalidates cached listings the same way a gate or handler-source change does.
+
+## [0.6.2] - 2026-07-01
+
+### Fixed
+- **A record field whose type is an inline string-literal union with a single field-level tag was misclassified as a per-member-tagged union.** `compile_tagged_record` routes a field into `compile_tagged_union` (which gates each `|`-separated member individually, e.g. `stage: a @feature(x) | b @feature(y)`) whenever `tagged_union_field?` sees an `@` anywhere in the type string plus more than one `|`-separated part. A plain literal union with one *field-level* tag trailing the whole thing — `logic: "AND" | "OR" @desc(...)` — matches that same heuristic even though the tag applies to the field, not an individual member. Misrouting sends each bare literal (`"AND"`, `"OR"`) through `resolve_type`, which only resolves *named alias references*; each literal fell back to `{type: "object"}`, producing `{type: "object", oneOf: [{type: "object"}, {type: "object"}]}` instead of `{type: "string", enum: ["AND", "OR"]}`. `tagged_union_field?` and `tagged_array_union_inner` now require at least one *non-final* `|`-separated member to carry a tag before treating a field as per-member-gated — every genuine per-member-tagged union in this codebase tags each gated member individually, so a tag trailing only the last member is never sufficient on its own. Field-level tags on inline literal unions now fall through to the normal RBS-library path (`visit_rbs_union`), which already resolved them correctly.
+
 ## [0.6.1] - 2026-07-01
 
 ### Fixed

data/README.md

@@ -360,6 +360,71 @@ Tag a tool with multiple domains to make it available in each:
 tags "operator", "recruiting"
 ```
 
+## Tool grouping (facades)
+
+As a domain grows into the hundreds of tools, a flat `tools/list` spends the
+selection prompt on call-time schemas instead of routing signal. A domain can
+opt into **grouped facades**: one tool per category, with a routing-only
+description and per-tool schemas deferred out of the listing.
+
+```ruby
+class ListOrdersTool < McpAuthorization::Tool
+  tags "admin"
+  category :orders                    # the group this tool belongs to
+  dynamic_contract OrderHandlers::List
+end
+
+McpAuthorization.configure do |config|
+  config.facet_domain :admin, group_by: :category
+
+  config.categories do
+    summary :orders,  "Create, inspect, and update orders and their line items."
+    summary :billing, "Invoices, payments, refunds, and billing profiles."
+  end
+end
+```
+
+`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
+inner tool and its arguments:
+
+```json
+{ "name": "orders_tools",
+  "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.
+
+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
+have an object root — Anthropic and OpenAI reject `oneOf`/`allOf`/`anyOf` at the
+top level — and hosts routinely forward a facade's `inputSchema` straight to the
+model. A correlated inline shape (each `tool_name` tied to its own argument
+schema) would need a root combinator, so it is not offered. `schema_strategy:`
+therefore only chooses where the per-tool schemas go:
+
+- `:vendor_extension` (default) — the per-tool schemas are carried on the
+  facade's `_meta` (key `"tool-input-schemas"`). `_meta` is the MCP-sanctioned
+  extension channel: SDKs preserve it and it is never forwarded to the model as
+  the tool `input_schema`, so the schemas stay available in-band for a client
+  that wants to expand the facade, without touching `inputSchema`.
+- `:lazy` — names and one-liners only; argument shapes are enforced at dispatch
+  by the target tool's own `filter_input`.
+
+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`.
+
+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.
+
 ## RBS type syntax
 
 The `@rbs type` comments compile to JSON Schema:

data/app/controllers/mcp_authorization/mcp_controller.rb

@@ -2,6 +2,13 @@ module McpAuthorization
   class McpController < ActionController::Base
     skip_forgery_protection
 
+    # Response header stamped on every cached tools/list path so hosts can log
+    # cache behavior: "hit" (served from the store), "miss" (compiled cold and
+    # stored), or "bypass" (compiled but not cached — cache had no key for this
+    # request, e.g. the domain's decision vocabulary isn't learned yet, or the
+    # response wasn't a cacheable result).
+    TOOLS_LIST_CACHE_HEADER = "X-MCP-Tools-List-Cache" #: String
+
     # POST/GET/DELETE /mcp/:domain
     #: () -> void
     def handle
@@ -48,6 +55,7 @@ module McpAuthorization
 
       key = McpAuthorization::Cache.tools_list_key(domain: domain, server_context: server_context)
       if key && (cached = McpAuthorization::Cache.store.get(key))
+        response.set_header(TOOLS_LIST_CACHE_HEADER, "hit")
         return render json: tools_list_envelope(cached)
       end
 
@@ -63,11 +71,17 @@ module McpAuthorization
       end
       result = parsed && parsed["result"]
       unless result
+        response.set_header(TOOLS_LIST_CACHE_HEADER, "bypass")
         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
+      if store_key
+        McpAuthorization::Cache.store.set(store_key, result, ttl: McpAuthorization::Cache.ttl)
+        response.set_header(TOOLS_LIST_CACHE_HEADER, "miss")
+      else
+        response.set_header(TOOLS_LIST_CACHE_HEADER, "bypass")
+      end
       render json: tools_list_envelope(result), status: status
     end
 
@@ -96,11 +110,7 @@ module McpAuthorization
         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)
+        name ? Array(resolve_tool(name, server_context)) : all_tools(server_context)
       when "initialize", "ping", %r{\Anotifications/}
         []
       else
@@ -110,12 +120,34 @@ module McpAuthorization
       end
     end
 
+    # The single tool a tools/call needs. In a faceted domain the name is
+    # usually a facade ("orders_tools"); direct tool names still resolve so
+    # a client that learned a real tool name keeps working. Facade names
+    # cannot shadow real tools — FacadeBuilder raises on collision.
+    #: (String, untyped) -> singleton(MCP::Tool)?
+    def resolve_tool(name, server_context)
+      domain = params[:domain]
+      if McpAuthorization.config.faceted?(domain)
+        facade = McpAuthorization::ToolRegistry.facade_for(
+          domain: domain, name: name, server_context: server_context
+        )
+        return facade if facade
+      end
+      McpAuthorization::ToolRegistry.tool_class_for(
+        domain: domain, name: name, server_context: server_context
+      )
+    end
+
+    # Every tool the domain presents: grouped facades when the domain is
+    # faceted (see Configuration#facet_domain), the flat list otherwise.
     #: (untyped) -> Array[singleton(MCP::Tool)]
     def all_tools(server_context)
-      McpAuthorization::ToolRegistry.tool_classes_for(
-        domain: params[:domain],
-        server_context: server_context
-      )
+      domain = params[:domain]
+      if McpAuthorization.config.faceted?(domain)
+        McpAuthorization::ToolRegistry.facades_for(domain: domain, server_context: server_context)
+      else
+        McpAuthorization::ToolRegistry.tool_classes_for(domain: domain, server_context: server_context)
+      end
     end
 
     #: () -> untyped

data/lib/mcp_authorization/cache.rb

@@ -197,10 +197,20 @@ module McpAuthorization
             tool_class.tool_name.to_s,
             (tool_class._gates || []).map { |g| [g[:name].to_s, g[:value].to_s] },
             handler&.name.to_s,
-            source
+            source,
+            tool_class._category.to_s
           ]
         end.sort_by(&:first)
-        Digest::SHA256.hexdigest(JSON.generate(sigs))[0, 16]
+        # Facet config and group summaries shape the tools/list of a faceted
+        # domain the same way a gate edit shapes a flat one — toggling
+        # grouping, switching schema strategy, or rewording a summary must
+        # invalidate cached listings.
+        config = McpAuthorization.config
+        facets = config.faceted_domains.sort.map do |domain, fc|
+          [domain, fc.sort_by { |k, _| k.to_s }.map { |k, v| [k.to_s, v.to_s] }]
+        end
+        summaries = config.category_summaries.sort_by { |k, _| k.to_s }.map { |k, v| [k.to_s, v] }
+        Digest::SHA256.hexdigest(JSON.generate([sigs, facets, summaries]))[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

data/lib/mcp_authorization/configuration.rb

@@ -107,6 +107,40 @@ module McpAuthorization
     #: String?
     attr_accessor :tools_list_cache_redis_url
 
+    # Per-domain facet (tool-grouping) configuration, keyed by domain name.
+    # Each value is a Hash: { group_by:, schema_strategy:, uncategorized:,
+    # facade_suffix: }.
+    # Populated by +facet_domain+; read by ToolRegistry / FacadeBuilder.
+    # See docs/designs/tool-grouping-facades.md.
+    #: Hash[String, Hash[Symbol, untyped]]
+    attr_reader :faceted_domains
+
+    # Group summaries keyed by category symbol. Populated by +categories+.
+    #: Hash[Symbol, String]
+    attr_reader :category_summaries
+
+    # Schema strategies FacadeBuilder knows how to emit.
+    # LLM tool `input_schema` must have an object root — Anthropic and OpenAI
+    # reject `oneOf`/`allOf`/`anyOf` at the top level — so both facade
+    # strategies keep a flat object root and differ only in where the per-tool
+    # schemas go: `:vendor_extension` carries them on the facade's `_meta`;
+    # `:lazy` omits them (enforced at dispatch). A correlated inline shape
+    # (tool_name → its argument schema) would require a root combinator and is
+    # therefore not offered.
+    SCHEMA_STRATEGIES = %i[vendor_extension lazy].freeze #: Array[Symbol]
+
+    # Behaviors for a tool in a faceted domain that declares no +category+.
+    UNCATEGORIZED_MODES = %i[fallback error].freeze #: Array[Symbol]
+
+    # Default suffix appended to a category to form its facade tool name
+    # (e.g. category +:orders+ → +orders_tools+). Overridable per domain via
+    # +facet_domain(..., facade_suffix:)+.
+    DEFAULT_FACADE_SUFFIX = "tools" #: String
+
+    # A facade suffix must be a bare identifier fragment so the derived facade
+    # name (+"#{category}_#{suffix}"+) stays a valid MCP tool name.
+    FACADE_SUFFIX_FORMAT = /\A[a-z0-9]+(?:_[a-z0-9]+)*\z/ #: Regexp
+
     #: () -> void
     def initialize
       @server_name = "mcp-authorization"
@@ -122,6 +156,101 @@ module McpAuthorization
       @tools_list_cache_ttl = 3600
       @tools_list_cache_redis = nil
       @tools_list_cache_redis_url = nil
+      @faceted_domains = {}
+      @category_summaries = {}
+    end
+
+    # Present a domain as grouped facade tools instead of a flat tool list.
+    #
+    #   config.facet_domain :admin, group_by: :category
+    #   config.facet_domain :admin, group_by: :category,
+    #                        schema_strategy: :lazy,
+    #                        uncategorized: :error
+    #
+    # +group_by+ is currently always +:category+ (the only grouping key the
+    # +category+ DSL provides); it is accepted explicitly so future grouping
+    # keys are an additive change rather than a behavior switch.
+    #
+    # +schema_strategy+ selects where the per-tool argument schemas go (the
+    # facade inputSchema is a flat object either way — see SCHEMA_STRATEGIES).
+    # +:vendor_extension+ (default) carries them on the facade's +_meta+;
+    # +:lazy+ omits them.
+    #
+    # +uncategorized+ controls what happens to a tool in this domain with no
+    # +category+: +:fallback+ (default) collects them into an +uncategorized+
+    # group; +:error+ raises at facade-build time.
+    #
+    # +facade_suffix+ is the token appended to a category to form its facade
+    # tool name — category +:orders+ → +orders_#{suffix}+. Defaults to
+    # +"tools"+ (+orders_tools+). Must be a lowercase identifier fragment
+    # (+[a-z0-9_]+) so the derived name stays a valid MCP tool name.
+    #: (Symbol | String, group_by: Symbol, ?schema_strategy: Symbol, ?uncategorized: Symbol, ?facade_suffix: String | Symbol) -> void
+    def facet_domain(domain, group_by:, schema_strategy: :vendor_extension, uncategorized: :fallback, facade_suffix: DEFAULT_FACADE_SUFFIX)
+      unless SCHEMA_STRATEGIES.include?(schema_strategy)
+        raise ArgumentError, "unknown schema_strategy #{schema_strategy.inspect}; " \
+          "expected one of #{SCHEMA_STRATEGIES.inspect}"
+      end
+      unless UNCATEGORIZED_MODES.include?(uncategorized)
+        raise ArgumentError, "unknown uncategorized mode #{uncategorized.inspect}; " \
+          "expected one of #{UNCATEGORIZED_MODES.inspect}"
+      end
+
+      suffix = facade_suffix.to_s
+      unless FACADE_SUFFIX_FORMAT.match?(suffix)
+        raise ArgumentError, "invalid facade_suffix #{facade_suffix.inspect}; " \
+          "expected a lowercase identifier fragment matching #{FACADE_SUFFIX_FORMAT.inspect}"
+      end
+
+      @faceted_domains[domain.to_s] = {
+        group_by: group_by.to_sym,
+        schema_strategy: schema_strategy,
+        uncategorized: uncategorized,
+        facade_suffix: suffix
+      }
+    end
+
+    # True when the given domain is presented as grouped facades.
+    #: (String) -> bool
+    def faceted?(domain)
+      @faceted_domains.key?(domain.to_s)
+    end
+
+    # Facet config Hash for a domain, or nil when the domain is not faceted.
+    #: (String) -> Hash[Symbol, untyped]?
+    def facet_config(domain)
+      @faceted_domains[domain.to_s]
+    end
+
+    # Declare one summary line per group. Evaluated in a small collector so
+    # the block reads declaratively:
+    #
+    #   config.categories do
+    #     summary :orders,  "Create, inspect, and update orders."
+    #     summary :billing, "Invoices, payments, refunds."
+    #   end
+    #: () { () -> void } -> void
+    def categories(&block)
+      collector = CategoryCollector.new(@category_summaries)
+      collector.instance_eval(&block)
+    end
+
+    # The group summary for a category, or nil when none was declared.
+    #: (Symbol) -> String?
+    def category_summary(category)
+      @category_summaries[category.to_sym]
+    end
+
+    # Collects +summary :key, "text"+ declarations into a shared hash.
+    class CategoryCollector
+      #: (Hash[Symbol, String]) -> void
+      def initialize(store)
+        @store = store
+      end
+
+      #: (Symbol | String, String) -> void
+      def summary(category, text)
+        @store[category.to_sym] = text
+      end
     end
   end
 end

data/lib/mcp_authorization/facade_builder.rb

@@ -0,0 +1,274 @@
+require "json"
+require "set"
+
+module McpAuthorization
+  # Builds grouped facade tools for a faceted domain.
+  #
+  # A facade is a per-request synthetic MCP::Tool subclass — one per
+  # non-empty category — whose description carries routing signal only
+  # (group summary + RBAC-filtered tool one-liners) and whose inputSchema
+  # defers per-tool argument schemas out of the selection prompt. A
+  # +tools/call+ on a facade names the inner tool (+tool_name+) and its
+  # +arguments+; dispatch resolves the real tool through
+  # ToolRegistry.tool_class_for — re-running +permitted?+ — and delegates
+  # to its materialized +call+, so authorization, gating, and input/output
+  # filtering apply exactly as if the tool had been called directly.
+  #
+  # Facades are never registered in ToolRegistry; they are produced on
+  # demand by +facades_for+. See docs/designs/tool-grouping-facades.md.
+  class FacadeBuilder
+    # A tool in a faceted domain declared no +category+ and the domain is
+    # configured with +uncategorized: :error+.
+    class UncategorizedToolError < StandardError; end
+
+    # A facade's derived name (e.g. "orders_tools") collides with a real
+    # registered tool name. Renaming the category is the fix.
+    class FacadeNameCollisionError < StandardError; end
+
+    # Fallback group for uncategorized tools (default mode).
+    FALLBACK_CATEGORY = :uncategorized #: Symbol
+
+    class << self
+      # All facades for a domain, one per non-empty group the caller has at
+      # least one permitted tool in. Empty groups produce no facade — which
+      # also guarantees no facade ever advertises an empty +enum+.
+      #: (domain: String, server_context: untyped) -> Array[singleton(MCP::Tool)]
+      def facades_for(domain:, server_context:)
+        config = McpAuthorization.config.facet_config(domain)
+        return [] unless config
+
+        group_tools(domain, server_context, config).map do |category, tools|
+          build_facade(domain, category, tools, server_context, config)
+        end
+      end
+
+      # A single facade by its tool name (e.g. "orders_tools"), or nil when
+      # the name matches no non-empty group for this caller. Used by
+      # +tools/call+ routing so one call doesn't build every facade.
+      #: (domain: String, name: String, server_context: untyped) -> singleton(MCP::Tool)?
+      def facade_for(domain:, name:, server_context:)
+        config = McpAuthorization.config.facet_config(domain)
+        return nil unless config
+
+        group_tools(domain, server_context, config).each do |category, tools|
+          return build_facade(domain, category, tools, server_context, config) if facade_name(category, config) == name
+        end
+        nil
+      end
+
+      # The MCP tool name a category's facade is exposed under. The suffix is
+      # per-domain (facet config +facade_suffix+, default +"tools"+): category
+      # +:orders+ → +orders_tools+ (or +orders_hire+, etc.).
+      #: (Symbol, Hash[Symbol, untyped]) -> String
+      def facade_name(category, config)
+        suffix = config[:facade_suffix] || Configuration::DEFAULT_FACADE_SUFFIX
+        "#{category}_#{suffix}"
+      end
+
+      private
+
+      # Partition the domain's tools into non-empty, RBAC-filtered groups.
+      # Ordering is deterministic (by category name) so listings are stable.
+      #: (String, untyped, Hash[Symbol, untyped]) -> Array[[Symbol, Array[singleton(McpAuthorization::Tool)]]]
+      def group_tools(domain, server_context, config)
+        candidates = McpAuthorization::ToolRegistry.tools_by_domain[domain] || []
+        permitted = candidates.select { |tc| tc.permitted?(server_context) }
+
+        groups = Hash.new { |h, k| h[k] = [] } #: Hash[Symbol, Array[singleton(McpAuthorization::Tool)]]
+        permitted.each do |tool_class|
+          category = tool_class._category
+          if category.nil?
+            if config[:uncategorized] == :error
+              raise UncategorizedToolError,
+                "#{tool_class} (tool #{tool_class.tool_name.inspect}) has no category, and domain " \
+                "#{domain.inspect} is faceted with uncategorized: :error. Declare `category :name` " \
+                "on the tool or switch the domain to uncategorized: :fallback."
+            end
+            category = FALLBACK_CATEGORY
+          end
+          groups[category] << tool_class
+        end
+
+        sorted = groups.sort_by { |category, _| category.to_s }
+        sorted.each { |category, _| check_name_collision!(domain, category, candidates, config) }
+        sorted
+      end
+
+      # A facade name shadowing a real tool would make that tool
+      # unreachable by name in this domain — fail loudly instead.
+      #: (String, Symbol, Array[singleton(McpAuthorization::Tool)], Hash[Symbol, untyped]) -> void
+      def check_name_collision!(domain, category, candidates, config)
+        name = facade_name(category, config)
+        collision = candidates.find { |tc| tc.tool_name == name }
+        return unless collision
+
+        raise FacadeNameCollisionError,
+          "facade name #{name.inspect} for category #{category.inspect} collides with registered " \
+          "tool #{collision} in domain #{domain.inspect}. Rename the category or the tool."
+      end
+
+      # Build the synthetic MCP::Tool subclass for one group, with this
+      # caller's description, schema, and dispatch baked in — the same
+      # materialization shape Tool.materialize_for uses for real tools.
+      #: (String, Symbol, Array[singleton(McpAuthorization::Tool)], untyped, Hash[Symbol, untyped]) -> singleton(MCP::Tool)
+      def build_facade(domain, category, tools, server_context, config)
+        name = facade_name(category, config)
+        desc = facade_description(category, tools, server_context)
+        strategy = config[:schema_strategy]
+        schema = facade_input_schema(tools, strategy)
+
+        # :vendor_extension ships the per-tool argument schemas out-of-band on
+        # the facade's `_meta` — the MCP-sanctioned extension channel — rather
+        # than as a non-standard key inside `inputSchema`. Client SDKs preserve
+        # `_meta` but strip (or, when strict, reject) unknown JSON Schema
+        # keywords, and `_meta` is never forwarded to the model as the tool's
+        # input_schema. So the listing stays valid for strict Zod clients and
+        # strict-mode LLM tool-calling while still carrying the schemas in-band
+        # for capable clients.
+        meta_payload = strategy == :vendor_extension ? { "tool-input-schemas" => child_schema_map(tools, server_context) } : nil
+
+        advertised = tools.map(&:tool_name).to_set
+        builder = self
+        ctx = server_context
+
+        Class.new(MCP::Tool) do
+          tool_name name
+          description desc
+          input_schema schema
+          meta(meta_payload) if meta_payload
+
+          define_singleton_method(:call) do |server_context: nil, **params|
+            builder.send(:dispatch, domain, advertised, params, server_context || ctx)
+          end
+        end
+      end
+
+      # Routing-only description: group summary + one line per tool the
+      # caller may invoke. No argument schemas — those are deferred into
+      # the inputSchema per the domain's schema strategy.
+      #: (Symbol, Array[singleton(McpAuthorization::Tool)], untyped) -> String
+      def facade_description(category, tools, server_context)
+        summary = McpAuthorization.config.category_summary(category) ||
+                  tools.filter_map(&:_category_summary).first ||
+                  "Tools in the #{category} group."
+
+        lines = tools.map do |tool_class|
+          one_liner = tool_class.dynamic_description(server_context: server_context)
+                                .to_s.lines.first.to_s.strip
+          "- #{tool_class.tool_name} — #{one_liner}"
+        end
+
+        <<~DESC.strip
+          #{summary}
+
+          Available tools (pass one as `tool_name`):
+          #{lines.join("\n")}
+        DESC
+      end
+
+      # The facade inputSchema for the configured strategy. All three keep
+      # per-tool schemas out of the description and advertise only tools the
+      # caller may invoke; they differ in where argument schemas live.
+      #: (Array[singleton(McpAuthorization::Tool)], untyped, Symbol) -> Hash[Symbol, untyped]
+      # The facade inputSchema is always a flat object — a `tool_name` enum plus
+      # a permissive `arguments` object, with NO top-level combinator. LLM tool
+      # `input_schema` must have an object root: Anthropic and OpenAI reject
+      # `oneOf`/`allOf`/`anyOf` at the top level ("input_schema does not support
+      # oneOf, allOf, or anyOf at the top level"), and hosts routinely forward a
+      # facade's inputSchema straight to the model. The per-tool argument
+      # schemas therefore cannot be correlated to `tool_name` inline; they ride
+      # on the facade's `_meta` (:vendor_extension, see build_facade) for a
+      # client to expand, or are omitted entirely (:lazy) and enforced at
+      # dispatch by the target tool's own filter_input.
+      def facade_input_schema(tools, strategy)
+        arguments_description =
+          if strategy == :vendor_extension
+            'Arguments for the chosen tool; per-tool schemas are in this tool\'s _meta under "tool-input-schemas".'
+          else # :lazy
+            "Arguments for the chosen tool."
+          end
+
+        {
+          type: "object",
+          properties: {
+            tool_name: { type: "string", enum: tools.map(&:tool_name) },
+            arguments: { type: "object", description: arguments_description }
+          },
+          required: %w[tool_name arguments]
+        }
+      end
+
+      # Per-tool compiled input schemas keyed by tool_name, filtered for this
+      # caller. Shipped on the facade's `_meta` by the :vendor_extension
+      # strategy so the argument shapes travel with the listing without a
+      # non-standard key inside `inputSchema`.
+      #: (Array[singleton(McpAuthorization::Tool)], untyped) -> Hash[String, untyped]
+      def child_schema_map(tools, server_context)
+        tools.each_with_object({}) do |tool_class, map|
+          map[tool_class.tool_name] = tool_class.dynamic_input_schema(server_context: server_context)
+        end
+      end
+
+      # Dispatch a facade call to the real tool.
+      #
+      # 1. tool_name must be in the set advertised to *this* caller.
+      # 2. tool_class_for re-runs permitted?, so gating is enforced at
+      #    dispatch even if the advertised set were stale.
+      # 3. Arguments are coerced against the *target* tool's schema
+      #    (JSON-string blobs parsed) before delegation; the target's own
+      #    materialized call then applies filter_input / filter_output —
+      #    the same code path as a direct call.
+      #: (String, Set[String], Hash[Symbol, untyped], untyped) -> untyped
+      def dispatch(domain, advertised, params, server_context)
+        tool_name = (params[:tool_name] || params["tool_name"]).to_s
+        unless advertised.include?(tool_name)
+          raise ArgumentError,
+            "unknown tool_name #{tool_name.inspect}; expected one of #{advertised.to_a.sort.inspect}"
+        end
+
+        candidates = McpAuthorization::ToolRegistry.tools_by_domain[domain] || []
+        original = candidates.find { |tc| tc.tool_name == tool_name }
+        target = McpAuthorization::ToolRegistry.tool_class_for(
+          domain: domain, name: tool_name, server_context: server_context
+        )
+        raise McpAuthorization::Tool::NotAuthorizedError unless original && target
+
+        arguments = coerce_arguments(original, params[:arguments] || params["arguments"], server_context)
+        target.call(server_context: server_context, **arguments)
+      end
+
+      # Coerce a facade's +arguments+ blob against the target tool's
+      # compiled input schema. MCP clients frequently serialize nested
+      # objects as JSON strings; the facade's own contract only knows
+      # `arguments: object`, so string blobs are parsed here — both the
+      # blob itself and any top-level value whose target type is an object
+      # or array. Unknown / permission-gated fields are then stripped by
+      # the target's filter_input as in a direct call.
+      #: (singleton(McpAuthorization::Tool), untyped, untyped) -> Hash[Symbol, untyped]
+      def coerce_arguments(tool_class, raw, server_context)
+        parsed = raw.is_a?(String) ? parse_json_blob(raw, "arguments") : raw
+        return {} unless parsed.is_a?(Hash)
+
+        schema = tool_class.dynamic_input_schema(server_context: server_context)
+        properties = schema.is_a?(Hash) ? (schema[:properties] || schema["properties"] || {}) : {}
+
+        parsed.each_with_object({}) do |(key, value), out|
+          sym = key.to_sym
+          expected = properties[sym] || properties[key.to_s] || {}
+          expected_type = expected[:type] || expected["type"]
+          if value.is_a?(String) && %w[object array].include?(expected_type.to_s)
+            value = parse_json_blob(value, sym)
+          end
+          out[sym] = value
+        end
+      end
+
+      #: (String, untyped) -> untyped
+      def parse_json_blob(string, field)
+        JSON.parse(string)
+      rescue JSON::ParserError => e
+        raise ArgumentError, "#{field} was sent as a string but is not valid JSON: #{e.message}"
+      end
+    end
+  end
+end

data/lib/mcp_authorization/rbs_schema_compiler.rb

@@ -1094,10 +1094,19 @@ module McpAuthorization
       # True when a record field's type is a multi-member union that carries a
       # predicate tag — i.e. per-member gating is intended. A `|` at bracket
       # depth 0 marks a real union (not one inside a nested generic/record).
+      #
+      # A tag trailing only the *final* member (e.g. a plain literal union
+      # with one field-level `@desc(...)`, as in `"AND" | "OR" @desc(...)`)
+      # is NOT per-member gating — every genuine per-member-tagged union in
+      # this codebase tags each gated member individually
+      # (`a @feature(x) | b @feature(y)`), so at least one *non-final*
+      # member must carry a tag before we route into compile_tagged_union.
+      # Otherwise the field falls through to the normal RBS-library path,
+      # which resolves inline literal unions correctly via visit_rbs_union.
       #: (String) -> bool
       def tagged_union_field?(type_str)
         return false unless type_str.include?("@")
-        split_at_depth_zero(type_str, "|").size > 1
+        per_member_tagged_union?(type_str, "|")
       end
 
       # If a field type is +Array[<multi-member tagged union>]+, return the inner
@@ -1111,7 +1120,18 @@ module McpAuthorization
         return nil unless m
 
         inner = m[1].to_s
-        split_at_depth_zero(inner, "|").size > 1 ? inner : nil
+        per_member_tagged_union?(inner, "|") ? inner : nil
+      end
+
+      # True when a `|`-separated type expression has more than one member
+      # AND at least one *non-final* member carries a predicate tag. See
+      # tagged_union_field? for why the final member alone doesn't count.
+      #: (String, String) -> bool
+      def per_member_tagged_union?(type_str, delimiter)
+        parts = split_at_depth_zero(type_str, delimiter)
+        return false unless parts.size > 1
+
+        parts[0..-2].any? { |part| part.include?("@") }
       end
 
       # Compile a union-style output type (+# @rbs type output = success | admin_detail @requires(:admin)+)

data/lib/mcp_authorization/tool.rb

@@ -37,6 +37,12 @@ module McpAuthorization
       #: Array[Hash[Symbol, untyped]]?
       attr_reader :_gates
 
+      #: Symbol?
+      attr_reader :_category
+
+      #: String?
+      attr_reader :_category_summary
+
       #: untyped
       attr_reader :_contract_handler
 
@@ -71,6 +77,22 @@ module McpAuthorization
         @_tags = list.flatten
       end
 
+      # Declare the group this tool belongs to when its domain is faceted
+      # (see Configuration#facet_domain). Ignored in flat domains.
+      #
+      #   class ListOrdersTool < McpAuthorization::Tool
+      #     tags "admin"
+      #     category :orders
+      #   end
+      #
+      # The optional +summary:+ is a convenience for single-tool groups; the
+      # central +config.categories+ registry wins on conflict.
+      #: (Symbol | String, ?summary: String?) -> void
+      def category(name, summary: nil)
+        @_category = name.to_sym
+        @_category_summary = summary
+      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

data/lib/mcp_authorization/tool_registry.rb

@@ -90,6 +90,24 @@ module McpAuthorization
         tool_class.materialize_for(server_context)
       end
 
+      # Grouped facade tools for a faceted domain — one synthetic MCP::Tool
+      # per non-empty category the caller has at least one permitted tool
+      # in. Returns [] for domains not configured via facet_domain.
+      # See FacadeBuilder and docs/designs/tool-grouping-facades.md.
+      #: (domain: String, server_context: untyped) -> Array[singleton(MCP::Tool)]
+      def facades_for(domain:, server_context:)
+        McpAuthorization::FacadeBuilder.facades_for(domain: domain, server_context: server_context)
+      end
+
+      # A single facade by name within a faceted domain, or nil when the
+      # domain is not faceted or the name matches no non-empty group for
+      # this caller. The facade analogue of tool_class_for — a tools/call
+      # targeting one facade should not build every facade in the domain.
+      #: (domain: String, name: String, server_context: untyped) -> singleton(MCP::Tool)?
+      def facade_for(domain:, name:, server_context:)
+        McpAuthorization::FacadeBuilder.facade_for(domain: domain, name: name, server_context: 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.6.1"
+  VERSION = "0.7.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/facade_builder"
 require_relative "mcp_authorization/cache"
 require_relative "mcp_authorization/engine" if defined?(Rails)
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -103,6 +103,7 @@ files:
 - lib/mcp_authorization/diagnostics.rb
 - lib/mcp_authorization/dsl.rb
 - lib/mcp_authorization/engine.rb
+- lib/mcp_authorization/facade_builder.rb
 - lib/mcp_authorization/rbs_schema_compiler.rb
 - lib/mcp_authorization/tool.rb
 - lib/mcp_authorization/tool_registry.rb