@dereekb/firebase-server 13.28.0 → 13.30.0

package/mcp/index.cjs.js

@@ -4,12 +4,12 @@ var common = require('@nestjs/common');
 var node_fs = require('node:fs');
 var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
 var types_js = require('@modelcontextprotocol/sdk/types.js');
+var firebase = require('@dereekb/firebase');
 var oidc = require('@dereekb/firebase-server/oidc');
 var util = require('@dereekb/util');
 var firebaseServer = require('@dereekb/firebase-server');
 var node_util = require('node:util');
 var model = require('@dereekb/model');
-var firebase = require('@dereekb/firebase');
 var streamableHttp_js = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
 
 function _class_call_check$5(instance, Constructor) {
@@ -167,6 +167,22 @@ function _define_property$9(obj, key, value) {
      * fills with a short justification for the call. The value is forwarded to analytics and stripped
      * from the dispatched handler body. See {@link McpReasonParameterConfig}.
      */ _define_property$9(this, "reasonParameter", void 0);
+    /**
+     * Default OIDC scope group term required on EVERY `callModel` op, mirrored into MCP tool-list
+     * visibility, unless a finer term overrides it (a per-function `requiredScope`, then a
+     * {@link McpModuleConfig.modelRequiredScopes} entry). Threaded into the same
+     * `resolveEffectiveOidcScopeTerms` composition the server-side model-api scope gate
+     * (`assertModelApiOidcScope`) uses, so a tool is advertised only when the caller could actually invoke it.
+     *
+     * Set this to the SAME value passed to `ModelApiDispatchConfig.defaultRequiredScope` to
+     * keep tool visibility and enforcement in lockstep.
+     */ _define_property$9(this, "defaultRequiredScope", void 0);
+    /**
+     * Per-model OIDC scope group-term overrides, keyed by {@link FirestoreModelType}, mirrored into MCP
+     * tool-list visibility. Set this to the SAME value passed to
+     * `ModelApiDispatchConfig.modelRequiredScopes` so per-model / verb-keyed restrictions that
+     * confine a subset client apply identically to the advertised tool list.
+     */ _define_property$9(this, "modelRequiredScopes", void 0);
 };
 /**
  * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
@@ -1400,6 +1416,8 @@ function _unsupported_iterable_to_array$9(o, minLen) {
     var seenNames = new Set();
     var manifest = context === null || context === void 0 ? void 0 : context.manifest;
     var naming = context === null || context === void 0 ? void 0 : context.naming;
+    var defaultRequiredScope = context === null || context === void 0 ? void 0 : context.defaultRequiredScope;
+    var modelRequiredScopes = context === null || context === void 0 ? void 0 : context.modelRequiredScopes;
     var candidates = planMcpToolCandidates(apiDetails, naming);
     var clashCounts = countVisibleAutoNameClashes(candidates);
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
@@ -1411,6 +1429,8 @@ function _unsupported_iterable_to_array$9(o, minLen) {
                 clashCounts: clashCounts,
                 options: options,
                 manifest: manifest,
+                defaultRequiredScope: defaultRequiredScope,
+                modelRequiredScopes: modelRequiredScopes,
                 seenNames: seenNames,
                 outTools: tools,
                 outNeverVisibleTools: neverVisibleTools,
@@ -1580,9 +1600,9 @@ function _unsupported_iterable_to_array$9(o, minLen) {
  *
  * @param context - The candidate plus the shared generation accumulators.
  */ function buildToolFromCandidate(context) {
-    var _clashCounts_get, _ref, _resolveRequiredScope;
+    var _clashCounts_get, _ref;
     var _handlerDetails_mcp, _handlerDetails_mcp1;
-    var candidate = context.candidate, clashCounts = context.clashCounts, options = context.options, manifest = context.manifest, seenNames = context.seenNames, outTools = context.outTools, outNeverVisibleTools = context.outNeverVisibleTools, outSkipped = context.outSkipped, outWarnings = context.outWarnings;
+    var candidate = context.candidate, clashCounts = context.clashCounts, options = context.options, manifest = context.manifest, defaultRequiredScope = context.defaultRequiredScope, modelRequiredScopes = context.modelRequiredScopes, seenNames = context.seenNames, outTools = context.outTools, outNeverVisibleTools = context.outNeverVisibleTools, outSkipped = context.outSkipped, outWarnings = context.outWarnings;
     var modelType = candidate.modelType, callType = candidate.callType, handlerDetails = candidate.handlerDetails, specifier = candidate.specifier, dispatch = candidate.dispatch, modelSegment = candidate.modelSegment, overrideName = candidate.overrideName, baseName = candidate.baseName, classified = candidate.classified, isVisible = candidate.isVisible;
     // A visible auto-named tool whose preferred name is produced by more than one visible tool is
     // re-derived with the abbreviated call type so both survive on the wire. Overrides and hidden tools
@@ -1632,7 +1652,18 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             });
         }
     }
-    var requiredScope = (_resolveRequiredScope = resolveRequiredScope(callType)) !== null && _resolveRequiredScope !== void 0 ? _resolveRequiredScope : undefined;
+    // AND-of-ORs scope terms: the per-verb call-type scope (model.<call>) plus the effective group term,
+    // resolved by the same precedence the server model-api scope gate uses (per-function requiredScope > per-model
+    // requirement > module default) via the shared resolveEffectiveOidcScopeTerms — so tool visibility
+    // tracks callability. Empty when no term applies (a non-CRUD call type with no per-function/model/
+    // default term → no scope gate).
+    var requiredScopeTerms = firebase.resolveEffectiveOidcScopeTerms({
+        perVerbScope: resolveRequiredScope(callType),
+        requiredScope: handlerDetails.requiredScope,
+        modelRequirement: modelRequiredScopes === null || modelRequiredScopes === void 0 ? void 0 : modelRequiredScopes[modelType],
+        call: callType,
+        defaultRequiredScope: defaultRequiredScope
+    });
     var effectiveReadOnly = resolveEffectiveReadOnly((_handlerDetails_mcp = handlerDetails.mcp) === null || _handlerDetails_mcp === void 0 ? void 0 : _handlerDetails_mcp.readOnly, callType);
     var annotations = resolveMcpToolAnnotations(effectiveReadOnly);
     var description = applyWriteMarker(baseDescription, annotations);
@@ -1641,20 +1672,20 @@ function _unsupported_iterable_to_array$9(o, minLen) {
         filterMetadata = {
             visibilityKind: 'declarative',
             rule: classified.rule,
-            requiredScope: requiredScope,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     } else if (classified.visibilityKind === 'dynamic') {
         filterMetadata = {
             visibilityKind: 'dynamic',
             visibilityFn: classified.visibilityFn,
-            requiredScope: requiredScope,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     } else {
         filterMetadata = {
             visibilityKind: classified.visibilityKind,
-            requiredScope: requiredScope,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     }
@@ -6157,7 +6188,9 @@ var McpServerFactoryService_1;
                     } else {
                         result = generateMcpToolDefinitions(apiDetails, undefined, {
                             manifest: manifest,
-                            naming: this._resolveToolNamingOptions()
+                            naming: this._resolveToolNamingOptions(),
+                            defaultRequiredScope: this.mcpConfig.defaultRequiredScope,
+                            modelRequiredScopes: this.mcpConfig.modelRequiredScopes
                         });
                     }
                     this._cachedTools = result;
@@ -6626,7 +6659,7 @@ var McpServerFactoryService_1;
      * Synthesizes the same `{ auth: { token } }` shape that `getOidcScopesFromRequest`
      * expects post-dispatch, so the upstream helper stays the single source of scope parsing.
      * Returns `undefined` for non-OIDC callers (no `oidcValidatedToken.scope`) — the filter
-     * loop treats that as "skip scope enforcement", matching `oidcCallModelScopePreAssert`.
+     * loop treats that as "skip scope enforcement", matching the model-api scope gate (`assertModelApiOidcScope`).
      *
      * @param ctx - The per-request context carrying the validated auth payload.
      * @returns The set of granted OIDC scopes, or `undefined` when scope enforcement should be skipped.
@@ -6670,7 +6703,7 @@ var McpServerFactoryService_1;
                     for(var _iterator = tools[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
                         var tool = _step.value;
                         var filterMetadata = tool.filterMetadata;
-                        if (scopes != null && filterMetadata.requiredScope != null && !scopes.has(filterMetadata.requiredScope)) {
+                        if (scopes != null && filterMetadata.requiredScopeTerms != null && !firebase.oidcScopeTermsSatisfied(filterMetadata.requiredScopeTerms, scopes)) {
                             continue;
                         }
                         if (readOnlyMode && filterMetadata.effectiveReadOnly !== true) {

package/mcp/index.esm.js

@@ -2,12 +2,12 @@ import { Injectable, Inject, Optional, Logger, Post, Req, Res, Controller, Get }
 import { existsSync, readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { callModelOidcScopeForCallType, resolveEffectiveOidcScopeTerms, inferKeyFromTwoWayFlatFirestoreModelKey, oidcScopeTermsSatisfied } from '@dereekb/firebase';
 import { getOidcScopesFromRequest, OidcProviderConfigService } from '@dereekb/firebase-server/oidc';
 import { makeValuesGroupMap, IMPERSONATION_URL_QUERY_PARAM, performAsyncTasks, authRolesSetHasRoles } from '@dereekb/util';
 import { ModelApiCallModelDispatchService, ModelApiGetService, FirebaseServerStorageService, FirebaseServerEnvService, FirebaseServerAnalyticsService } from '@dereekb/firebase-server';
 import { inspect } from 'node:util';
 import { arktypeToJsonSchemaForExport } from '@dereekb/model';
-import { callModelOidcScopeForCallType, inferKeyFromTwoWayFlatFirestoreModelKey } from '@dereekb/firebase';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
 function _class_call_check$5(instance, Constructor) {
@@ -165,6 +165,22 @@ function _define_property$9(obj, key, value) {
      * fills with a short justification for the call. The value is forwarded to analytics and stripped
      * from the dispatched handler body. See {@link McpReasonParameterConfig}.
      */ _define_property$9(this, "reasonParameter", void 0);
+    /**
+     * Default OIDC scope group term required on EVERY `callModel` op, mirrored into MCP tool-list
+     * visibility, unless a finer term overrides it (a per-function `requiredScope`, then a
+     * {@link McpModuleConfig.modelRequiredScopes} entry). Threaded into the same
+     * `resolveEffectiveOidcScopeTerms` composition the server-side model-api scope gate
+     * (`assertModelApiOidcScope`) uses, so a tool is advertised only when the caller could actually invoke it.
+     *
+     * Set this to the SAME value passed to `ModelApiDispatchConfig.defaultRequiredScope` to
+     * keep tool visibility and enforcement in lockstep.
+     */ _define_property$9(this, "defaultRequiredScope", void 0);
+    /**
+     * Per-model OIDC scope group-term overrides, keyed by {@link FirestoreModelType}, mirrored into MCP
+     * tool-list visibility. Set this to the SAME value passed to
+     * `ModelApiDispatchConfig.modelRequiredScopes` so per-model / verb-keyed restrictions that
+     * confine a subset client apply identically to the advertised tool list.
+     */ _define_property$9(this, "modelRequiredScopes", void 0);
 };
 /**
  * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
@@ -1398,6 +1414,8 @@ function _unsupported_iterable_to_array$9(o, minLen) {
     var seenNames = new Set();
     var manifest = context === null || context === void 0 ? void 0 : context.manifest;
     var naming = context === null || context === void 0 ? void 0 : context.naming;
+    var defaultRequiredScope = context === null || context === void 0 ? void 0 : context.defaultRequiredScope;
+    var modelRequiredScopes = context === null || context === void 0 ? void 0 : context.modelRequiredScopes;
     var candidates = planMcpToolCandidates(apiDetails, naming);
     var clashCounts = countVisibleAutoNameClashes(candidates);
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
@@ -1409,6 +1427,8 @@ function _unsupported_iterable_to_array$9(o, minLen) {
                 clashCounts: clashCounts,
                 options: options,
                 manifest: manifest,
+                defaultRequiredScope: defaultRequiredScope,
+                modelRequiredScopes: modelRequiredScopes,
                 seenNames: seenNames,
                 outTools: tools,
                 outNeverVisibleTools: neverVisibleTools,
@@ -1578,9 +1598,9 @@ function _unsupported_iterable_to_array$9(o, minLen) {
  *
  * @param context - The candidate plus the shared generation accumulators.
  */ function buildToolFromCandidate(context) {
-    var _clashCounts_get, _ref, _resolveRequiredScope;
+    var _clashCounts_get, _ref;
     var _handlerDetails_mcp, _handlerDetails_mcp1;
-    var candidate = context.candidate, clashCounts = context.clashCounts, options = context.options, manifest = context.manifest, seenNames = context.seenNames, outTools = context.outTools, outNeverVisibleTools = context.outNeverVisibleTools, outSkipped = context.outSkipped, outWarnings = context.outWarnings;
+    var candidate = context.candidate, clashCounts = context.clashCounts, options = context.options, manifest = context.manifest, defaultRequiredScope = context.defaultRequiredScope, modelRequiredScopes = context.modelRequiredScopes, seenNames = context.seenNames, outTools = context.outTools, outNeverVisibleTools = context.outNeverVisibleTools, outSkipped = context.outSkipped, outWarnings = context.outWarnings;
     var modelType = candidate.modelType, callType = candidate.callType, handlerDetails = candidate.handlerDetails, specifier = candidate.specifier, dispatch = candidate.dispatch, modelSegment = candidate.modelSegment, overrideName = candidate.overrideName, baseName = candidate.baseName, classified = candidate.classified, isVisible = candidate.isVisible;
     // A visible auto-named tool whose preferred name is produced by more than one visible tool is
     // re-derived with the abbreviated call type so both survive on the wire. Overrides and hidden tools
@@ -1630,7 +1650,18 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             });
         }
     }
-    var requiredScope = (_resolveRequiredScope = resolveRequiredScope(callType)) !== null && _resolveRequiredScope !== void 0 ? _resolveRequiredScope : undefined;
+    // AND-of-ORs scope terms: the per-verb call-type scope (model.<call>) plus the effective group term,
+    // resolved by the same precedence the server model-api scope gate uses (per-function requiredScope > per-model
+    // requirement > module default) via the shared resolveEffectiveOidcScopeTerms — so tool visibility
+    // tracks callability. Empty when no term applies (a non-CRUD call type with no per-function/model/
+    // default term → no scope gate).
+    var requiredScopeTerms = resolveEffectiveOidcScopeTerms({
+        perVerbScope: resolveRequiredScope(callType),
+        requiredScope: handlerDetails.requiredScope,
+        modelRequirement: modelRequiredScopes === null || modelRequiredScopes === void 0 ? void 0 : modelRequiredScopes[modelType],
+        call: callType,
+        defaultRequiredScope: defaultRequiredScope
+    });
     var effectiveReadOnly = resolveEffectiveReadOnly((_handlerDetails_mcp = handlerDetails.mcp) === null || _handlerDetails_mcp === void 0 ? void 0 : _handlerDetails_mcp.readOnly, callType);
     var annotations = resolveMcpToolAnnotations(effectiveReadOnly);
     var description = applyWriteMarker(baseDescription, annotations);
@@ -1639,20 +1670,20 @@ function _unsupported_iterable_to_array$9(o, minLen) {
         filterMetadata = {
             visibilityKind: 'declarative',
             rule: classified.rule,
-            requiredScope: requiredScope,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     } else if (classified.visibilityKind === 'dynamic') {
         filterMetadata = {
             visibilityKind: 'dynamic',
             visibilityFn: classified.visibilityFn,
-            requiredScope: requiredScope,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     } else {
         filterMetadata = {
             visibilityKind: classified.visibilityKind,
-            requiredScope: requiredScope,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     }
@@ -6155,7 +6186,9 @@ var McpServerFactoryService_1;
                     } else {
                         result = generateMcpToolDefinitions(apiDetails, undefined, {
                             manifest: manifest,
-                            naming: this._resolveToolNamingOptions()
+                            naming: this._resolveToolNamingOptions(),
+                            defaultRequiredScope: this.mcpConfig.defaultRequiredScope,
+                            modelRequiredScopes: this.mcpConfig.modelRequiredScopes
                         });
                     }
                     this._cachedTools = result;
@@ -6624,7 +6657,7 @@ var McpServerFactoryService_1;
      * Synthesizes the same `{ auth: { token } }` shape that `getOidcScopesFromRequest`
      * expects post-dispatch, so the upstream helper stays the single source of scope parsing.
      * Returns `undefined` for non-OIDC callers (no `oidcValidatedToken.scope`) — the filter
-     * loop treats that as "skip scope enforcement", matching `oidcCallModelScopePreAssert`.
+     * loop treats that as "skip scope enforcement", matching the model-api scope gate (`assertModelApiOidcScope`).
      *
      * @param ctx - The per-request context carrying the validated auth payload.
      * @returns The set of granted OIDC scopes, or `undefined` when scope enforcement should be skipped.
@@ -6668,7 +6701,7 @@ var McpServerFactoryService_1;
                     for(var _iterator = tools[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
                         var tool = _step.value;
                         var filterMetadata = tool.filterMetadata;
-                        if (scopes != null && filterMetadata.requiredScope != null && !scopes.has(filterMetadata.requiredScope)) {
+                        if (scopes != null && filterMetadata.requiredScopeTerms != null && !oidcScopeTermsSatisfied(filterMetadata.requiredScopeTerms, scopes)) {
                             continue;
                         }
                         if (readOnlyMode && filterMetadata.effectiveReadOnly !== true) {

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.28.0",
+  "version": "13.30.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.28.0",
-    "@dereekb/date": "13.28.0",
-    "@dereekb/firebase": "13.28.0",
-    "@dereekb/firebase-server": "13.28.0",
-    "@dereekb/firebase-server/oidc": "13.28.0",
-    "@dereekb/model": "13.28.0",
-    "@dereekb/nestjs": "13.28.0",
-    "@dereekb/rxjs": "13.28.0",
-    "@dereekb/util": "13.28.0",
-    "@dereekb/zoho": "13.28.0",
+    "@dereekb/analytics": "13.30.0",
+    "@dereekb/date": "13.30.0",
+    "@dereekb/firebase": "13.30.0",
+    "@dereekb/firebase-server": "13.30.0",
+    "@dereekb/firebase-server/oidc": "13.30.0",
+    "@dereekb/model": "13.30.0",
+    "@dereekb/nestjs": "13.30.0",
+    "@dereekb/rxjs": "13.30.0",
+    "@dereekb/util": "13.30.0",
+    "@dereekb/zoho": "13.30.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",

package/mcp/src/lib/mcp.config.d.ts

@@ -1,5 +1,5 @@
 import { type AuthClaims, type AuthRoleSet } from '@dereekb/util';
-import { type OidcScope } from '@dereekb/firebase';
+import { type FirestoreModelType, type OidcModelScopeRequirement, type OidcScope, type OidcScopeTerm } from '@dereekb/firebase';
 /**
  * Default path the MCP Streamable HTTP transport is mounted at.
  *
@@ -200,6 +200,24 @@ export declare abstract class McpModuleConfig {
      * from the dispatched handler body. See {@link McpReasonParameterConfig}.
      */
     readonly reasonParameter?: McpReasonParameterConfig | boolean;
+    /**
+     * Default OIDC scope group term required on EVERY `callModel` op, mirrored into MCP tool-list
+     * visibility, unless a finer term overrides it (a per-function `requiredScope`, then a
+     * {@link McpModuleConfig.modelRequiredScopes} entry). Threaded into the same
+     * `resolveEffectiveOidcScopeTerms` composition the server-side model-api scope gate
+     * (`assertModelApiOidcScope`) uses, so a tool is advertised only when the caller could actually invoke it.
+     *
+     * Set this to the SAME value passed to `ModelApiDispatchConfig.defaultRequiredScope` to
+     * keep tool visibility and enforcement in lockstep.
+     */
+    readonly defaultRequiredScope?: OidcScopeTerm;
+    /**
+     * Per-model OIDC scope group-term overrides, keyed by {@link FirestoreModelType}, mirrored into MCP
+     * tool-list visibility. Set this to the SAME value passed to
+     * `ModelApiDispatchConfig.modelRequiredScopes` so per-model / verb-keyed restrictions that
+     * confine a subset client apply identically to the advertised tool list.
+     */
+    readonly modelRequiredScopes?: Record<FirestoreModelType, OidcModelScopeRequirement>;
 }
 /**
  * Signature for the optional role reader the MCP module uses when evaluating

package/mcp/src/lib/service/mcp.server.factory.d.ts

@@ -152,7 +152,7 @@ export declare class McpServerFactoryService {
      * Synthesizes the same `{ auth: { token } }` shape that `getOidcScopesFromRequest`
      * expects post-dispatch, so the upstream helper stays the single source of scope parsing.
      * Returns `undefined` for non-OIDC callers (no `oidcValidatedToken.scope`) — the filter
-     * loop treats that as "skip scope enforcement", matching `oidcCallModelScopePreAssert`.
+     * loop treats that as "skip scope enforcement", matching the model-api scope gate (`assertModelApiOidcScope`).
      *
      * @param ctx - The per-request context carrying the validated auth payload.
      * @returns The set of granted OIDC scopes, or `undefined` when scope enforcement should be skipped.

package/mcp/src/lib/service/mcp.tool-generator.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type KnownOnCallFunctionType } from '@dereekb/firebase';
+import { type FirestoreModelType, type KnownOnCallFunctionType, type OidcModelScopeRequirement, type OidcScopeTerm } from '@dereekb/firebase';
 import { type ModelApiDetailsResult, type OnCallModelFunctionApiDetails, type FirebaseServerAuthData, type McpToolDetailsBuilder, type McpVisibilityRule } from '@dereekb/firebase-server';
 import { type Request } from 'express';
 import { type CallToolResult, type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
@@ -452,6 +452,17 @@ export interface GenerateMcpToolDefinitionsContext {
      * Per-model name segment overrides (e.g. collection prefixes).
      */
     readonly naming?: McpToolGenerationNamingOptions;
+    /**
+     * Default OIDC scope group term required on every op unless a finer term overrides it. Mirrors the
+     * model-api layer's `ModelApiDispatchConfig.defaultRequiredScope` so a tool is advertised only when
+     * the caller could invoke it.
+     */
+    readonly defaultRequiredScope?: OidcScopeTerm;
+    /**
+     * Per-model OIDC scope group-term overrides, keyed by {@link FirestoreModelType}. Mirrors the model-api
+     * layer's `ModelApiDispatchConfig.modelRequiredScopes` so per-model / verb-keyed restrictions apply to tool visibility.
+     */
+    readonly modelRequiredScopes?: Record<FirestoreModelType, OidcModelScopeRequirement>;
 }
 /**
  * Generates MCP tool definitions from a model-first API details tree.

package/mcp/src/lib/service/mcp.visibility.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type CallModelOidcScope } from '@dereekb/firebase';
+import { type CallModelOidcScope, type OidcScopeTerm } from '@dereekb/firebase';
 import { type McpToolVisibility, type McpVisibilityContext, type McpVisibilityRule } from '@dereekb/firebase-server';
 import { type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 /**
@@ -41,10 +41,15 @@ export interface ClassifiedMcpToolVisibilityDynamic {
 export type McpToolFilterMetadata = McpToolFilterMetadataAlways | McpToolFilterMetadataNever | McpToolFilterMetadataDeclarative | McpToolFilterMetadataDynamic;
 interface McpToolFilterMetadataBase {
     /**
-     * OIDC scope required to invoke this tool. Precomputed from the dispatch call type.
-     * `undefined` for non-CRUD call types (apps gate those via their own preAssert if needed).
+     * OIDC scope TERMS required to invoke this tool, evaluated AND-of-ORs — the caller must satisfy
+     * EVERY term, and an array term (OR-group) is satisfied by holding ANY member. Checked with the
+     * shared `oidcScopeTermsSatisfied` so tool-list visibility matches the server-side `callModel` gate
+     * exactly. Precomputed from the dispatch call type's per-verb scope (`model.<call>`) plus the
+     * effective group term (per-function `requiredScope` > per-model requirement > module default).
+     * Empty when no scope is enforced (a non-CRUD call type with no per-function/model/default term);
+     * apps gate custom verbs via their own preAssert.
      */
-    readonly requiredScope?: CallModelOidcScope;
+    readonly requiredScopeTerms?: readonly OidcScopeTerm[];
     /**
      * Effective read-only classification used by the module-level `readOnly` filter.
      *

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.28.0",
+  "version": "13.30.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.28.0",
-    "@dereekb/date": "13.28.0",
-    "@dereekb/firebase": "13.28.0",
-    "@dereekb/firebase-server": "13.28.0",
-    "@dereekb/model": "13.28.0",
-    "@dereekb/nestjs": "13.28.0",
-    "@dereekb/rxjs": "13.28.0",
-    "@dereekb/util": "13.28.0",
+    "@dereekb/analytics": "13.30.0",
+    "@dereekb/date": "13.30.0",
+    "@dereekb/firebase": "13.30.0",
+    "@dereekb/firebase-server": "13.30.0",
+    "@dereekb/model": "13.30.0",
+    "@dereekb/nestjs": "13.30.0",
+    "@dereekb/rxjs": "13.30.0",
+    "@dereekb/util": "13.30.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",