@dereekb/firebase-server 13.36.0 → 13.38.0

package/mcp/index.esm.js

@@ -1,21 +1,20 @@
-import { Injectable, Inject, Optional, Logger, Post, Req, Res, Controller, Get } from '@nestjs/common';
+import { Injectable, Inject, Optional, Logger, Post, Req, Res, Get, Delete, Controller, HttpStatus } from '@nestjs/common';
 import { existsSync, readFileSync } from 'node:fs';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { McpServer, isLegacyRequest, isJsonContentType, createMcpHandler } from '@modelcontextprotocol/server';
 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 { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { toWebRequest, toNodeHandler, NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 
 function _class_call_check$5(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function _define_property$9(obj, key, value) {
+function _define_property$a(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -86,7 +85,7 @@ function _define_property$9(obj, key, value) {
      * discovery document. Claude custom-connector reads this to discover the OIDC issuer.
      *
      * @example 'https://api.example.com/oidc'
-     */ _define_property$9(this, "oidcIssuer", void 0);
+     */ _define_property$a(this, "oidcIssuer", void 0);
     /**
      * The canonical resource URL of the MCP endpoint.
      *
@@ -94,17 +93,18 @@ function _define_property$9(obj, key, value) {
      * and used as the audience the access token's `aud` claim should match.
      *
      * @example 'https://api.example.com/mcp'
-     */ _define_property$9(this, "mcpUrl", void 0);
+     */ _define_property$a(this, "mcpUrl", void 0);
     /**
      * Optional filter applied to the OIDC provider's scope list when building the
      * protected-resource discovery document's `scopes_supported` (RFC 9728 §2).
      *
      * The base list is pulled automatically from the OIDC provider config via the
-     * injected {@link OidcProviderConfigService.scopesSupported} (i.e.
-     * `Object.keys(providerConfig.claims)`), so the MCP resource advertises exactly
-     * the scopes the issuer supports without the app restating them. Provide this
-     * only to narrow that set — it receives every scope the provider issues and
-     * returns the subset to advertise. When unset, all of them are advertised.
+     * injected {@link OidcProviderConfigService.clientRequestableScopesSupported}, so
+     * the MCP resource advertises the scopes the issuer grants an arbitrary client
+     * without the app restating them. Scopes only an admin-assigned provider profile
+     * unlocks are already excluded — requesting one is fatal at the consent unlock
+     * gate. Provide this only to narrow the set further; it returns the subset to
+     * advertise. When unset, the whole base list is advertised.
      *
      * Advertising these matters because dynamic-registration MCP clients (the Claude
      * Code CLI) read `scopes_supported` to decide which scopes to request on the
@@ -112,19 +112,19 @@ function _define_property$9(obj, key, value) {
      * the OIDC provider nothing to grant and ending the interaction in `access_denied`.
      *
      * @example (allScopes) => allScopes.filter((scope) => scope === 'openid' || scope.startsWith('model.'))
-     */ _define_property$9(this, "scopesSupported", void 0);
+     */ _define_property$a(this, "scopesSupported", void 0);
     /**
      * Optional name advertised on the MCP `initialize` handshake. Defaults to
      * {@link DEFAULT_MCP_SERVER_NAME}.
-     */ _define_property$9(this, "serverName", void 0);
+     */ _define_property$a(this, "serverName", void 0);
     /**
      * Optional version advertised on the MCP `initialize` handshake.
-     */ _define_property$9(this, "serverVersion", void 0);
+     */ _define_property$a(this, "serverVersion", void 0);
     /**
      * Optional override for the `instructions` string passed to `new McpServer(...)` and
      * advertised on the JSON-RPC `initialize` handshake. Defaults to
      * {@link DEFAULT_MCP_SERVER_INSTRUCTIONS}.
-     */ _define_property$9(this, "serverInstructions", void 0);
+     */ _define_property$a(this, "serverInstructions", void 0);
     /**
      * Absolute path to a pre-rendered MCP manifest JSON file produced by
      * `dbx-cli-generate-mcp-manifest`. When set, the runtime reads it once at
@@ -134,7 +134,7 @@ function _define_property$9(obj, key, value) {
      * Optional. When unset or the file is missing, the runtime falls back to
      * today's behavior (auto-generated descriptions, ArkType-derived input
      * schemas, no output schemas) and emits a single boot warning.
-     */ _define_property$9(this, "mcpManifestPath", void 0);
+     */ _define_property$a(this, "mcpManifestPath", void 0);
     /**
      * Absolute path to a pre-rendered route manifest JSON file produced by
      * `dbx-cli-generate-route-manifest`. When set, the runtime reads it once at
@@ -144,7 +144,7 @@ function _define_property$9(obj, key, value) {
      * Optional. When unset or the file is missing, the runtime skips registering
      * `url-models` and emits a single boot warning when the path was set but
      * unreadable.
-     */ _define_property$9(this, "mcpRouteManifestPath", void 0);
+     */ _define_property$a(this, "mcpRouteManifestPath", void 0);
     /**
      * When `true`, the MCP server only advertises tools whose effective read-only classification is `true`.
      *
@@ -154,7 +154,7 @@ function _define_property$9(obj, key, value) {
      *
      * The advertised `serverName` on the JSON-RPC `initialize` handshake is suffixed with
      * ` (read-only)` so the client surface reflects the mode.
-     */ _define_property$9(this, "readOnly", void 0);
+     */ _define_property$a(this, "readOnly", void 0);
     /**
      * Controls the auto-injected `reason` parameter added to every advertised tool's input schema.
      *
@@ -164,7 +164,7 @@ function _define_property$9(obj, key, value) {
      * When enabled, every advertised tool's `inputSchema` carries a required `reason` string the model
      * 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);
+     */ _define_property$a(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
@@ -174,17 +174,20 @@ function _define_property$9(obj, key, value) {
      *
      * 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);
+     */ _define_property$a(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);
+     */ _define_property$a(this, "modelRequiredScopes", void 0);
 };
 /**
  * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
  */ var MCP_AUTH_ROLE_READER = 'MCP_AUTH_ROLE_READER';
+/**
+ * NestJS injection token for the optional {@link McpModelRolesTargetUidPredicate} provider.
+ */ var MCP_MODEL_ROLES_TARGET_UID_PREDICATE = 'MCP_MODEL_ROLES_TARGET_UID_PREDICATE';
 
 function _type_of$5(obj) {
     "@swc/helpers - typeof";
@@ -214,7 +217,7 @@ function _array_like_to_array$b(arr, len) {
 function _array_without_holes$8(arr) {
     if (Array.isArray(arr)) return _array_like_to_array$b(arr);
 }
-function _define_property$8(obj, key, value) {
+function _define_property$9(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -233,7 +236,7 @@ function _iterable_to_array$8(iter) {
 function _non_iterable_spread$8() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _object_spread$6(target) {
+function _object_spread$7(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
         var ownKeys = Object.keys(source);
@@ -243,7 +246,7 @@ function _object_spread$6(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$8(target, key, source[key]);
+            _define_property$9(target, key, source[key]);
         });
     }
     return target;
@@ -353,9 +356,9 @@ function _unsupported_iterable_to_array$b(o, minLen) {
         var _base_type;
         var base = (typeof inputSchema === "undefined" ? "undefined" : _type_of$4(inputSchema)) === 'object' && inputSchema != null ? inputSchema : {};
         var existingProperties = _type_of$4(base.properties) === 'object' && base.properties != null ? base.properties : {};
-        var next = _object_spread_props$3(_object_spread$6({}, base), {
+        var next = _object_spread_props$3(_object_spread$7({}, base), {
             type: (_base_type = base.type) !== null && _base_type !== void 0 ? _base_type : 'object',
-            properties: _object_spread_props$3(_object_spread$6({}, existingProperties), _define_property$8({}, resolved.parameterName, {
+            properties: _object_spread_props$3(_object_spread$7({}, existingProperties), _define_property$9({}, resolved.parameterName, {
                 type: 'string',
                 maxLength: resolved.maxLength,
                 description: resolved.description
@@ -389,7 +392,7 @@ function _unsupported_iterable_to_array$b(o, minLen) {
     var result;
     if (resolved.enabled && !toolDeclaresOwnReason && Object.prototype.hasOwnProperty.call(args, resolved.parameterName)) {
         var rawValue = args[resolved.parameterName];
-        var nextArgs = _object_spread$6({}, args);
+        var nextArgs = _object_spread$7({}, args);
         delete nextArgs[resolved.parameterName];
         var stringValue = rawValue == null ? '' : String(rawValue);
         var clamped = stringValue.length > resolved.maxLength ? stringValue.slice(0, resolved.maxLength) : stringValue;
@@ -744,7 +747,7 @@ function scoreCandidates(states, pathname) {
     });
 }
 
-function asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, key, arg) {
+function asyncGeneratorStep$7(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
         var value = info.value;
@@ -758,16 +761,16 @@ function asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, key, arg) {
         Promise.resolve(value).then(_next, _throw);
     }
 }
-function _async_to_generator$6(fn) {
+function _async_to_generator$7(fn) {
     return function() {
         var self = this, args = arguments;
         return new Promise(function(resolve, reject) {
             var gen = fn.apply(self, args);
             function _next(value) {
-                asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, "next", value);
+                asyncGeneratorStep$7(gen, resolve, reject, _next, _throw, "next", value);
             }
             function _throw(err) {
-                asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, "throw", err);
+                asyncGeneratorStep$7(gen, resolve, reject, _next, _throw, "throw", err);
             }
             _next(undefined);
         });
@@ -781,7 +784,7 @@ function _instanceof$1(left, right) {
         return left instanceof right;
     }
 }
-function _ts_generator$6(thisArg, body) {
+function _ts_generator$7(thisArg, body) {
     var f, y, t, _ = {
         label: 0,
         sent: function() {
@@ -909,9 +912,9 @@ function _ts_generator$6(thisArg, body) {
  * @param details - The handler-level API details (carries the mapper + Tier 2/3 formatters).
  * @returns The MCP tool response content.
  */ function formatMcpToolResponse(result, params, details) {
-    return _async_to_generator$6(function() {
+    return _async_to_generator$7(function() {
         var mcp, value, _tmp, context, response, summary;
-        return _ts_generator$6(this, function(_state) {
+        return _ts_generator$7(this, function(_state) {
             switch(_state.label){
                 case 0:
                     mcp = details === null || details === void 0 ? void 0 : details.mcp;
@@ -1771,7 +1774,7 @@ function _array_like_to_array$8(arr, len) {
 function _array_without_holes$7(arr) {
     if (Array.isArray(arr)) return _array_like_to_array$8(arr);
 }
-function asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, key, arg) {
+function asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
         var value = info.value;
@@ -1785,16 +1788,16 @@ function asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, key, arg) {
         Promise.resolve(value).then(_next, _throw);
     }
 }
-function _async_to_generator$5(fn) {
+function _async_to_generator$6(fn) {
     return function() {
         var self = this, args = arguments;
         return new Promise(function(resolve, reject) {
             var gen = fn.apply(self, args);
             function _next(value) {
-                asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, "next", value);
+                asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, "next", value);
             }
             function _throw(err) {
-                asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, "throw", err);
+                asyncGeneratorStep$6(gen, resolve, reject, _next, _throw, "throw", err);
             }
             _next(undefined);
         });
@@ -1817,7 +1820,7 @@ function _unsupported_iterable_to_array$8(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$8(o, minLen);
 }
-function _ts_generator$5(thisArg, body) {
+function _ts_generator$6(thisArg, body) {
     var f, y, t, _ = {
         label: 0,
         sent: function() {
@@ -1978,55 +1981,564 @@ function _ts_generator$5(thisArg, body) {
 }
 // MARK: Handler
 function modelGetToolHandler(args, ctx, deps) {
+    return _async_to_generator$6(function() {
+        var result, input, identity, resolvedKeys, merged, error;
+        return _ts_generator$6(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    _state.trys.push([
+                        0,
+                        2,
+                        ,
+                        3
+                    ]);
+                    input = parseModelGetInput(args);
+                    identity = deps.resolveIdentity(input.modelType, ctx.auth);
+                    if (identity == null) {
+                        throw new Error("Unknown modelType: ".concat(input.modelType));
+                    }
+                    resolvedKeys = resolveKeys$1(input.keys, identity);
+                    return [
+                        4,
+                        readInChunks$1({
+                            modelType: input.modelType,
+                            keys: resolvedKeys,
+                            auth: ctx.auth,
+                            readDocuments: deps.readDocuments
+                        })
+                    ];
+                case 1:
+                    merged = _state.sent();
+                    result = {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(merged)
+                            }
+                        ],
+                        structuredContent: merged
+                    };
+                    return [
+                        3,
+                        3
+                    ];
+                case 2:
+                    error = _state.sent();
+                    result = formatMcpToolErrorResponse(error);
+                    return [
+                        3,
+                        3
+                    ];
+                case 3:
+                    return [
+                        2,
+                        result
+                    ];
+            }
+        });
+    })();
+}
+function parseModelGetInput(args) {
+    var modelType = args['modelType'];
+    var keys = args['keys'];
+    if (typeof modelType !== 'string' || modelType.length === 0) {
+        throw new Error('model-get: "modelType" is required and must be a non-empty string.');
+    }
+    if (!Array.isArray(keys) || keys.length === 0) {
+        throw new Error('model-get: "keys" is required and must be a non-empty array.');
+    }
+    var normalizedKeys = keys.map(function(value, index) {
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error("model-get: keys[".concat(index, "] must be a non-empty string."));
+        }
+        return value;
+    });
+    return {
+        modelType: modelType,
+        keys: normalizedKeys
+    };
+}
+function resolveKeys$1(keys, identity) {
+    var isRoot = identity.type === 'root';
+    var resolved = [];
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = keys[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var value = _step.value;
+            if (value.includes('/')) {
+                resolved.push(value);
+            } else if (isRoot) {
+                resolved.push("".concat(identity.collectionName, "/").concat(value));
+            } else {
+                throw new Error('model-get: modelType "'.concat(identity.modelType, '" is a subcollection; bare ids are not allowed. Provide full keys (e.g. "parentPrefix/parentId/').concat(identity.collectionName, "/").concat(value, '").'));
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return resolved;
+}
+function readInChunks$1(input) {
+    return _async_to_generator$6(function() {
+        var modelType, keys, auth, readDocuments, merged, offset, _merged_results, _merged_errors, batch, partial;
+        return _ts_generator$6(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    modelType = input.modelType, keys = input.keys, auth = input.auth, readDocuments = input.readDocuments;
+                    merged = {
+                        results: [],
+                        errors: []
+                    };
+                    offset = 0;
+                    _state.label = 1;
+                case 1:
+                    if (!(offset < keys.length)) return [
+                        3,
+                        4
+                    ];
+                    batch = keys.slice(offset, offset + MCP_MODEL_GET_BATCH_SIZE);
+                    return [
+                        4,
+                        readDocuments(modelType, batch, auth)
+                    ];
+                case 2:
+                    partial = _state.sent();
+                    (_merged_results = merged.results).push.apply(_merged_results, _to_consumable_array$7(partial.results));
+                    (_merged_errors = merged.errors).push.apply(_merged_errors, _to_consumable_array$7(partial.errors));
+                    _state.label = 3;
+                case 3:
+                    offset += MCP_MODEL_GET_BATCH_SIZE;
+                    return [
+                        3,
+                        1
+                    ];
+                case 4:
+                    return [
+                        2,
+                        merged
+                    ];
+            }
+        });
+    })();
+}
+// MARK: Schemas
+var MODEL_GET_INPUT_SCHEMA = {
+    type: 'object',
+    required: [
+        'modelType',
+        'keys'
+    ],
+    properties: {
+        modelType: {
+            type: 'string',
+            minLength: 1,
+            description: 'Firestore model type to fetch (e.g. "guestbook", "profile").'
+        },
+        keys: {
+            type: 'array',
+            minItems: 1,
+            description: 'Full keys ("prefix/id") or bare ids (root models only).',
+            items: {
+                type: 'string',
+                minLength: 1
+            }
+        }
+    },
+    additionalProperties: false
+};
+var MODEL_GET_OUTPUT_SCHEMA = {
+    type: 'object',
+    required: [
+        'results',
+        'errors'
+    ],
+    properties: {
+        results: {
+            type: 'array',
+            description: 'Per-key successful reads.',
+            items: {
+                type: 'object',
+                required: [
+                    'key',
+                    'data'
+                ],
+                properties: {
+                    key: {
+                        type: 'string'
+                    },
+                    data: {}
+                }
+            }
+        },
+        errors: {
+            type: 'array',
+            description: 'Per-key failures (not-found, forbidden, etc.).',
+            items: {
+                type: 'object',
+                required: [
+                    'key',
+                    'message'
+                ],
+                properties: {
+                    key: {
+                        type: 'string'
+                    },
+                    message: {
+                        type: 'string'
+                    },
+                    code: {
+                        type: 'string'
+                    }
+                }
+            }
+        }
+    }
+};
+
+function asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator$5(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep$5(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _define_property$8(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _object_spread$6(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property$8(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function _ts_generator$5(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+// MARK: Constants
+/**
+ * Reserved tool name for the built-in `model-roles` static tool.
+ */ var MODEL_ROLES_TOOL_NAME = 'model-roles';
+/**
+ * Synthetic call type used in the tool's dispatch identity. Distinct from `model-get`'s `get` so
+ * visibility predicates can target the two independently.
+ */ var MODEL_ROLES_DISPATCH_CALL = 'roles';
+/**
+ * Synthetic model type used in the tool's dispatch identity. Mirrors {@link MODEL_GET_DISPATCH_MODEL_TYPE}
+ * — the tool isn't bound to one model type, so the literal "model" stands in.
+ */ var MODEL_ROLES_DISPATCH_MODEL_TYPE = 'model';
+/**
+ * Maximum number of keys accepted per `model-roles` call. Role resolution runs the model's real
+ * permission delegate per key (which may itself read parent documents), so this is deliberately
+ * lower than the `model-get` batch size.
+ */ var MCP_MODEL_ROLES_MAX_KEYS = 25;
+// MARK: Factory
+/**
+ * Builds the built-in `model-roles` MCP tool definition.
+ *
+ * Answers "what is this user actually allowed to do with this document?" by running the same
+ * `roleMapForModel()` delegate the permission-checked read/write paths use, and returning the
+ * resolved roles instead of consuming them. Because the model's real delegate runs, derived and
+ * cascading roles appear exactly as the API grants them — there is no second implementation of the
+ * rules to drift.
+ *
+ * Two things it disambiguates that a plain read cannot:
+ * - **Missing vs. forbidden.** A key that resolves to a missing document returns
+ *   `exists: false, roles: []` rather than an error, so "the document is not there" reads
+ *   differently from "it is there and you have no access" (`exists: true, roles: []`).
+ * - **Full access.** Admin short-circuits that grant the full-access marker come back as
+ *   `fullAccess: true` rather than as an opaque enumerated set.
+ *
+ * By default roles are resolved for the calling user. Passing `uid` resolves them for another user
+ * and is gated behind {@link CreateModelRolesToolDeps.canTargetOtherUids}.
+ *
+ * @param deps - Role-map reader, identity resolver, and the target-uid authorization predicate.
+ * @returns A statically-registered {@link McpToolDefinition} ready to be appended to the MCP
+ *   server factory's tool registry.
+ */ function createModelRolesTool(deps) {
+    var handler = function handler(args, ctx) {
+        return modelRolesToolHandler(args, ctx, deps);
+    };
+    var name = MODEL_ROLES_TOOL_NAME;
+    var description = 'Resolve which roles the current user (or, with "uid", another user) is granted on one or more model keys — the same permission computation the API runs, returned instead of enforced. Use to answer "why was this forbidden?" and to tell a missing document (exists:false) apart from one you cannot access (exists:true, roles:[]). Admin full-access short-circuits report fullAccess:true. Targeting another uid requires elevated access.';
+    return buildStaticToolDefinition({
+        name: name,
+        description: description,
+        inputSchema: MODEL_ROLES_INPUT_SCHEMA,
+        outputSchema: MODEL_ROLES_OUTPUT_SCHEMA,
+        dispatch: {
+            call: MODEL_ROLES_DISPATCH_CALL,
+            modelType: MODEL_ROLES_DISPATCH_MODEL_TYPE
+        },
+        staticHandler: handler,
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
+}
+// MARK: Handler
+function modelRolesToolHandler(args, ctx, deps) {
     return _async_to_generator$5(function() {
-        var result, input, identity, resolvedKeys, merged, error;
+        var result, input, identity, targetUid, keys, resolved, error;
         return _ts_generator$5(this, function(_state) {
             switch(_state.label){
                 case 0:
                     _state.trys.push([
                         0,
-                        2,
+                        3,
                         ,
-                        3
+                        4
                     ]);
-                    input = parseModelGetInput(args);
+                    input = parseModelRolesInput(args);
                     identity = deps.resolveIdentity(input.modelType, ctx.auth);
                     if (identity == null) {
                         throw new Error("Unknown modelType: ".concat(input.modelType));
                     }
-                    resolvedKeys = resolveKeys(input.keys, identity);
                     return [
                         4,
-                        readInChunks$1({
-                            modelType: input.modelType,
-                            keys: resolvedKeys,
+                        resolveTargetUid({
+                            requestedUid: input.uid,
                             auth: ctx.auth,
-                            readDocuments: deps.readDocuments
+                            canTargetOtherUids: deps.canTargetOtherUids
                         })
                     ];
                 case 1:
-                    merged = _state.sent();
+                    targetUid = _state.sent();
+                    keys = resolveKeys(input.keys, identity);
+                    return [
+                        4,
+                        deps.readRoleMaps(_object_spread$6({
+                            modelType: input.modelType,
+                            keys: keys,
+                            auth: ctx.auth
+                        }, targetUid == null ? {} : {
+                            targetUid: targetUid
+                        }))
+                    ];
+                case 2:
+                    resolved = _state.sent();
                     result = {
                         content: [
                             {
                                 type: 'text',
-                                text: JSON.stringify(merged)
+                                text: JSON.stringify(resolved)
                             }
                         ],
-                        structuredContent: merged
+                        structuredContent: resolved
                     };
                     return [
                         3,
-                        3
+                        4
                     ];
-                case 2:
+                case 3:
                     error = _state.sent();
                     result = formatMcpToolErrorResponse(error);
+                    return [
+                        3,
+                        4
+                    ];
+                case 4:
+                    return [
+                        2,
+                        result
+                    ];
+            }
+        });
+    })();
+}
+/**
+ * Resolves the effective target uid for a call, enforcing the elevated-access gate.
+ *
+ * Requesting your own uid is always allowed and is treated as no target at all, so a caller that
+ * passes their own uid never trips the predicate.
+ *
+ * @param input - The requested uid, the caller's auth, and the authorization predicate.
+ * @returns The uid to resolve as, or `undefined` to resolve as the caller.
+ * @throws {Error} When another user's uid is requested and the predicate denies (or is absent).
+ */ function resolveTargetUid(input) {
+    return _async_to_generator$5(function() {
+        var requestedUid, auth, canTargetOtherUids, result, allowed, _tmp;
+        return _ts_generator$5(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    requestedUid = input.requestedUid, auth = input.auth, canTargetOtherUids = input.canTargetOtherUids;
+                    if (!(requestedUid != null && requestedUid !== (auth === null || auth === void 0 ? void 0 : auth.uid))) return [
+                        3,
+                        4
+                    ];
+                    if (!(canTargetOtherUids == null)) return [
+                        3,
+                        1
+                    ];
+                    _tmp = false;
                     return [
                         3,
                         3
                     ];
+                case 1:
+                    return [
+                        4,
+                        canTargetOtherUids(auth)
+                    ];
+                case 2:
+                    _tmp = _state.sent();
+                    _state.label = 3;
                 case 3:
+                    allowed = _tmp;
+                    if (!allowed) {
+                        throw new Error("model-roles: resolving roles for another user's uid requires elevated access.");
+                    }
+                    result = requestedUid;
+                    _state.label = 4;
+                case 4:
                     return [
                         2,
                         result
@@ -2035,25 +2547,34 @@ function modelGetToolHandler(args, ctx, deps) {
         });
     })();
 }
-function parseModelGetInput(args) {
-    var modelType = args.modelType;
-    var keys = args.keys;
+function parseModelRolesInput(args) {
+    var modelType = args['modelType'];
+    var keys = args['keys'];
+    var uid = args['uid'];
     if (typeof modelType !== 'string' || modelType.length === 0) {
-        throw new Error('model-get: "modelType" is required and must be a non-empty string.');
+        throw new Error('model-roles: "modelType" is required and must be a non-empty string.');
     }
     if (!Array.isArray(keys) || keys.length === 0) {
-        throw new Error('model-get: "keys" is required and must be a non-empty array.');
+        throw new Error('model-roles: "keys" is required and must be a non-empty array.');
+    }
+    if (keys.length > MCP_MODEL_ROLES_MAX_KEYS) {
+        throw new Error("model-roles: at most ".concat(MCP_MODEL_ROLES_MAX_KEYS, " keys may be resolved per call (received ").concat(keys.length, ")."));
+    }
+    if (uid !== undefined && (typeof uid !== 'string' || uid.length === 0)) {
+        throw new Error('model-roles: "uid" must be a non-empty string when provided.');
     }
     var normalizedKeys = keys.map(function(value, index) {
         if (typeof value !== 'string' || value.length === 0) {
-            throw new Error("model-get: keys[".concat(index, "] must be a non-empty string."));
+            throw new Error("model-roles: keys[".concat(index, "] must be a non-empty string."));
         }
         return value;
     });
-    return {
+    return _object_spread$6({
         modelType: modelType,
         keys: normalizedKeys
-    };
+    }, uid === undefined ? {} : {
+        uid: uid
+    });
 }
 function resolveKeys(keys, identity) {
     var isRoot = identity.type === 'root';
@@ -2067,7 +2588,7 @@ function resolveKeys(keys, identity) {
             } else if (isRoot) {
                 resolved.push("".concat(identity.collectionName, "/").concat(value));
             } else {
-                throw new Error('model-get: modelType "'.concat(identity.modelType, '" is a subcollection; bare ids are not allowed. Provide full keys (e.g. "parentPrefix/parentId/').concat(identity.collectionName, "/").concat(value, '").'));
+                throw new Error('model-roles: modelType "'.concat(identity.modelType, '" is a subcollection; bare ids are not allowed. Provide full keys (e.g. "parentPrefix/parentId/').concat(identity.collectionName, "/").concat(value, '").'));
             }
         }
     } catch (err) {
@@ -2086,51 +2607,8 @@ function resolveKeys(keys, identity) {
     }
     return resolved;
 }
-function readInChunks$1(input) {
-    return _async_to_generator$5(function() {
-        var modelType, keys, auth, readDocuments, merged, offset, _merged_results, _merged_errors, batch, partial;
-        return _ts_generator$5(this, function(_state) {
-            switch(_state.label){
-                case 0:
-                    modelType = input.modelType, keys = input.keys, auth = input.auth, readDocuments = input.readDocuments;
-                    merged = {
-                        results: [],
-                        errors: []
-                    };
-                    offset = 0;
-                    _state.label = 1;
-                case 1:
-                    if (!(offset < keys.length)) return [
-                        3,
-                        4
-                    ];
-                    batch = keys.slice(offset, offset + MCP_MODEL_GET_BATCH_SIZE);
-                    return [
-                        4,
-                        readDocuments(modelType, batch, auth)
-                    ];
-                case 2:
-                    partial = _state.sent();
-                    (_merged_results = merged.results).push.apply(_merged_results, _to_consumable_array$7(partial.results));
-                    (_merged_errors = merged.errors).push.apply(_merged_errors, _to_consumable_array$7(partial.errors));
-                    _state.label = 3;
-                case 3:
-                    offset += MCP_MODEL_GET_BATCH_SIZE;
-                    return [
-                        3,
-                        1
-                    ];
-                case 4:
-                    return [
-                        2,
-                        merged
-                    ];
-            }
-        });
-    })();
-}
 // MARK: Schemas
-var MODEL_GET_INPUT_SCHEMA = {
+var MODEL_ROLES_INPUT_SCHEMA = {
     type: 'object',
     required: [
         'modelType',
@@ -2140,47 +2618,78 @@ var MODEL_GET_INPUT_SCHEMA = {
         modelType: {
             type: 'string',
             minLength: 1,
-            description: 'Firestore model type to fetch (e.g. "guestbook", "profile").'
+            description: 'Firestore model type to resolve roles on (e.g. "guestbook", "profile").'
         },
         keys: {
             type: 'array',
             minItems: 1,
+            maxItems: MCP_MODEL_ROLES_MAX_KEYS,
             description: 'Full keys ("prefix/id") or bare ids (root models only).',
             items: {
                 type: 'string',
                 minLength: 1
             }
+        },
+        uid: {
+            type: 'string',
+            minLength: 1,
+            description: 'Resolve roles as this user instead of the caller. Requires elevated access; passing your own uid is always allowed.'
         }
     },
     additionalProperties: false
 };
-var MODEL_GET_OUTPUT_SCHEMA = {
+var MODEL_ROLES_OUTPUT_SCHEMA = {
     type: 'object',
     required: [
+        'targeted',
         'results',
         'errors'
     ],
     properties: {
+        uid: {
+            type: 'string',
+            description: 'The uid the roles were resolved for.'
+        },
+        targeted: {
+            type: 'boolean',
+            description: 'True when the roles were resolved for a user other than the caller.'
+        },
         results: {
             type: 'array',
-            description: 'Per-key successful reads.',
+            description: 'Per-key resolved permission state.',
             items: {
                 type: 'object',
                 required: [
                     'key',
-                    'data'
+                    'exists',
+                    'fullAccess',
+                    'roles'
                 ],
                 properties: {
                     key: {
                         type: 'string'
                     },
-                    data: {}
+                    exists: {
+                        type: 'boolean',
+                        description: 'Whether the document exists. Roles are only computed for documents that exist.'
+                    },
+                    fullAccess: {
+                        type: 'boolean',
+                        description: 'True when the full-access marker was granted; every role is implicitly held and "roles" is empty.'
+                    },
+                    roles: {
+                        type: 'array',
+                        items: {
+                            type: 'string'
+                        },
+                        description: 'Granted role names, sorted.'
+                    }
                 }
             }
         },
         errors: {
             type: 'array',
-            description: 'Per-key failures (not-found, forbidden, etc.).',
+            description: 'Per-key failures. A missing document is NOT an error — it appears in results with exists:false.',
             items: {
                 type: 'object',
                 required: [
@@ -2938,7 +3447,7 @@ var MODEL_ROW_SCHEMA = {
     }
 };
 // MCP's `tools/list` validator requires `outputSchema.type === 'object'` at the root
-// (see @modelcontextprotocol/sdk Zod schema), so the variants are expressed via a top-level
+// (see the MCP SDK's `ToolSchema`), so the variants are expressed via a top-level
 // object whose nested `oneOf` discriminates by the `mode` literal.
 var MODEL_INFO_OUTPUT_SCHEMA = {
     type: 'object',
@@ -3740,7 +4249,7 @@ function whoamiToolHandler(args, ctx, deps) {
 }
 // Coerces the `detail` input into a WhoamiDetailLevel, defaulting unknown or absent values to `summary`.
 function parseDetailLevel(args) {
-    var value = args.detail;
+    var value = args['detail'];
     return value === 'claims' || value === 'full' ? value : 'summary';
 }
 function buildResult(output, text) {
@@ -4335,30 +4844,30 @@ function urlModelsToolHandler(args, ctx, deps) {
     })();
 }
 function parseUrlModelsInput(args) {
-    var url = args.url;
+    var url = args['url'];
     if (typeof url !== 'string' || url.length === 0) {
         throw new Error('url-models: "url" is required and must be a non-empty string.');
     }
-    var keysOnly = args.keysOnly === true;
-    var load = args.load === true;
+    var keysOnly = args['keysOnly'] === true;
+    var load = args['load'] === true;
     if (keysOnly && load) {
         throw new Error('url-models: "keysOnly" and "load" cannot be combined — "keysOnly" returns keys without loading documents.');
     }
     var models;
-    if (args.models !== undefined) {
-        if (!Array.isArray(args.models) || args.models.some(function(m) {
+    if (args['models'] !== undefined) {
+        if (!Array.isArray(args['models']) || args['models'].some(function(m) {
             return typeof m !== 'string';
         })) {
             throw new Error('url-models: "models" must be an array of model-type strings.');
         }
-        models = args.models;
+        models = args['models'];
     }
     var currentUserUid;
-    if (args.currentUserUid !== undefined) {
-        if (typeof args.currentUserUid !== 'string' || args.currentUserUid.length === 0) {
+    if (args['currentUserUid'] !== undefined) {
+        if (typeof args['currentUserUid'] !== 'string' || args['currentUserUid'].length === 0) {
             throw new Error('url-models: "currentUserUid" must be a non-empty string.');
         }
-        currentUserUid = args.currentUserUid;
+        currentUserUid = args['currentUserUid'];
     }
     return _object_spread$2(_object_spread_props$1(_object_spread$2({
         url: url
@@ -5306,19 +5815,19 @@ function batchExecuteToolHandler(args, ctx, deps) {
 // MARK: Input parsing
 function parseBatchExecuteInput(args) {
     var _args_format, _args_maxParallel;
-    var uploadPath = args.uploadPath;
+    var uploadPath = args['uploadPath'];
     if (typeof uploadPath !== 'string' || uploadPath.length === 0) {
         throw new Error('batch-execute: "uploadPath" is required and must be a non-empty string.');
     }
-    var bucketId = args.bucketId;
+    var bucketId = args['bucketId'];
     if (bucketId != null && (typeof bucketId !== 'string' || bucketId.length === 0)) {
         throw new Error('batch-execute: "bucketId" must be a non-empty string when provided.');
     }
-    var format = (_args_format = args.format) !== null && _args_format !== void 0 ? _args_format : 'ndjson';
+    var format = (_args_format = args['format']) !== null && _args_format !== void 0 ? _args_format : 'ndjson';
     if (format !== 'json' && format !== 'ndjson') {
         throw new Error('batch-execute: "format" must be "json" or "ndjson".');
     }
-    var maxParallel = (_args_maxParallel = args.maxParallel) !== null && _args_maxParallel !== void 0 ? _args_maxParallel : DEFAULT_BATCH_EXECUTE_MAX_PARALLEL;
+    var maxParallel = (_args_maxParallel = args['maxParallel']) !== null && _args_maxParallel !== void 0 ? _args_maxParallel : DEFAULT_BATCH_EXECUTE_MAX_PARALLEL;
     if (typeof maxParallel !== 'number' || !Number.isInteger(maxParallel) || maxParallel < 1) {
         throw new Error('batch-execute: "maxParallel" must be a positive integer.');
     }
@@ -5327,8 +5836,8 @@ function parseBatchExecuteInput(args) {
         bucketId: bucketId !== null && bucketId !== void 0 ? bucketId : undefined,
         format: format,
         maxParallel: maxParallel,
-        stopOnError: args.stopOnError === true,
-        deleteUploadOnSuccess: args.deleteUploadOnSuccess !== false
+        stopOnError: args['stopOnError'] === true,
+        deleteUploadOnSuccess: args['deleteUploadOnSuccess'] !== false
     };
 }
 function readOperationsFile(input) {
@@ -5409,9 +5918,9 @@ function validateOperation(value, index) {
         throw new Error("batch-execute: operation[".concat(index, "] must be an object."));
     }
     var candidate = value;
-    var modelType = candidate.modelType;
-    var call = candidate.call;
-    var specifier = candidate.specifier;
+    var modelType = candidate['modelType'];
+    var call = candidate['call'];
+    var specifier = candidate['specifier'];
     if (typeof modelType !== 'string' || modelType.length === 0) {
         throw new Error("batch-execute: operation[".concat(index, '] is missing a non-empty "modelType".'));
     }
@@ -5425,7 +5934,7 @@ function validateOperation(value, index) {
         call: call,
         modelType: modelType,
         specifier: specifier !== null && specifier !== void 0 ? specifier : undefined,
-        data: candidate.data
+        data: candidate['data']
     };
 }
 function collectPreflightErrors(operations, authorizeOperation) {
@@ -6053,17 +6562,19 @@ var McpServerFactoryService_1;
  * Injectable factory that builds {@link McpServer} instances pre-wired to the
  * call model dispatch chain.
  *
- * The factory is invoked per Streamable HTTP request — `@modelcontextprotocol/sdk`
- * recommends a fresh `McpServer` + transport pair per stateless JSON-RPC request,
- * which sidesteps session bookkeeping for the common Claude-connector case.
+ * The factory is invoked per Streamable HTTP request. That is the shape the MCP
+ * SDK's 2026-07-28 entry (`createMcpHandler`) requires — it builds a fresh server
+ * per request and has no session concept at all — and it is equally what the SDK
+ * recommends for stateless 2025-era serving, so one factory backs both eras.
  */ var McpServerFactoryService = McpServerFactoryService_1 = /*#__PURE__*/ function() {
-    function McpServerFactoryService(mcpConfig, dispatchService, modelApiGetService, roleReader, analyticsService, storageService) {
+    function McpServerFactoryService(mcpConfig, dispatchService, modelApiGetService, roleReader, analyticsService, storageService, modelRolesTargetUidPredicate) {
         _class_call_check$3(this, McpServerFactoryService);
         _define_property$3(this, "mcpConfig", void 0);
         _define_property$3(this, "dispatchService", void 0);
         _define_property$3(this, "modelApiGetService", void 0);
         _define_property$3(this, "roleReader", void 0);
         _define_property$3(this, "storageService", void 0);
+        _define_property$3(this, "modelRolesTargetUidPredicate", void 0);
         _define_property$3(this, "_logger", new Logger(McpServerFactoryService_1.name));
         _define_property$3(this, "_cachedTools", void 0);
         _define_property$3(this, "_cachedStaticTools", void 0);
@@ -6083,6 +6594,7 @@ var McpServerFactoryService_1;
         this.modelApiGetService = modelApiGetService;
         this.roleReader = roleReader;
         this.storageService = storageService;
+        this.modelRolesTargetUidPredicate = modelRolesTargetUidPredicate;
         this._analyticsService = analyticsService !== null && analyticsService !== void 0 ? analyticsService : noopMcpAnalyticsService();
     }
     _create_class$3(McpServerFactoryService, [
@@ -6133,7 +6645,7 @@ var McpServerFactoryService_1;
                         batchTool
                     ]);
                 }
-                server.server.setRequestHandler(ListToolsRequestSchema, function() {
+                server.server.setRequestHandler('tools/list', function() {
                     return _async_to_generator$2(function() {
                         var _this;
                         return _ts_generator$2(this, function(_state) {
@@ -6141,6 +6653,10 @@ var McpServerFactoryService_1;
                             return [
                                 2,
                                 {
+                                    // McpToolListEntry types its schemas as opaque `object`: they are read from a manifest file
+                                    // or produced by arktype's JSON Schema export, so the `type: 'object'` root the SDK's wire
+                                    // type mandates holds at runtime but cannot be proven statically. Every schema reaching here
+                                    // either came from arktypeToJsonSchemaForExport or defaulted to `{ type: 'object' }`.
                                     tools: listedTools.map(function(tool) {
                                         return _this._buildToolListEntry(tool, ctx, scopes);
                                     })
@@ -6149,7 +6665,7 @@ var McpServerFactoryService_1;
                         });
                     }).call(_this);
                 });
-                server.server.setRequestHandler(CallToolRequestSchema, function(request) {
+                server.server.setRequestHandler('tools/call', function(request) {
                     return _async_to_generator$2(function() {
                         return _ts_generator$2(this, function(_state) {
                             return [
@@ -6349,6 +6865,14 @@ var McpServerFactoryService_1;
                             resolveIdentity: function resolveIdentity(modelType, auth) {
                                 return getService.getModelIdentity(modelType, auth);
                             }
+                        }), createModelRolesTool({
+                            readRoleMaps: function readRoleMaps(params) {
+                                return getService.readRoleMaps(params);
+                            },
+                            resolveIdentity: function resolveIdentity(modelType, auth) {
+                                return getService.getModelIdentity(modelType, auth);
+                            },
+                            canTargetOtherUids: this.modelRolesTargetUidPredicate
                         }));
                         // `url-models` reuses the model-get read/identity path, so it is only offered when the get
                         // service is wired AND a route manifest with at least one state was loaded.
@@ -7102,7 +7626,9 @@ McpServerFactoryService = McpServerFactoryService_1 = __decorate([
     __param(4, Optional()),
     __param(4, Inject(MCP_ANALYTICS_SERVICE)),
     __param(5, Optional()),
-    __param(5, Inject(FirebaseServerStorageService))
+    __param(5, Inject(FirebaseServerStorageService)),
+    __param(6, Optional()),
+    __param(6, Inject(MCP_MODEL_ROLES_TARGET_UID_PREDICATE))
 ], McpServerFactoryService);
 
 function asyncGeneratorStep$1(gen, resolve, reject, _next, _throw, key, arg) {
@@ -7234,29 +7760,168 @@ function _ts_generator$1(thisArg, body) {
     }
 }
 /**
- * Handles a single Streamable HTTP JSON-RPC request against the supplied MCP server.
+ * Handles a single Streamable HTTP JSON-RPC request, building a fresh MCP server for it.
+ *
+ * Both protocol eras are served, each by its own leg:
  *
- * Each call creates a fresh `StreamableHTTPServerTransport` in stateless mode — the
- * transport binds the server, processes one request, and is discarded. Stateless
- * mode is adequate for Claude custom-connector usage and avoids the bookkeeping
- * cost of session-tracked transports for the common case.
+ * - **2026-07-28 (modern)** — `createMcpHandler`, which is per-request and stateless by
+ *   construction: there is no `Mcp-Session-Id` and no transport bookkeeping.
+ * - **2025-era (legacy)** — a `NodeStreamableHTTPServerTransport` in stateless mode, which is
+ *   byte-for-byte what this endpoint served before the SDK v2 upgrade.
+ *
+ * The legacy leg is wired by hand (the SDK's documented `isLegacyRequest` composition) rather
+ * than left to `createMcpHandler`'s built-in `legacy: 'stateless'` fallback, because that
+ * fallback builds its transport with `sessionIdGenerator` alone and therefore answers in
+ * `text/event-stream`. See {@link handleLegacyMcpRequest} for why that framing is not viable
+ * here.
  *
  * The caller is expected to have already validated the bearer token (via the
  * OIDC bearer middleware) before this function runs.
  *
  * @param req - The Express request carrying the JSON-RPC body.
  * @param res - The Express response.
+ * @param buildServer - Factory producing the MCP server that backs this request.
+ */ function handleStreamableHttpMcpRequest(req, res, buildServer) {
+    return _async_to_generator$1(function() {
+        var probe;
+        return _ts_generator$1(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    // Hand-wired compositions must reject non-JSON POST bodies themselves — neither the modern
+                    // entry's routing nor the legacy transport does it on our behalf once we classify up front.
+                    if (!isJsonContentType(req.headers['content-type'])) {
+                        res.status(415).json({
+                            statusCode: 415,
+                            message: 'Unsupported Media Type'
+                        });
+                        return [
+                            2
+                        ];
+                    }
+                    return [
+                        4,
+                        toWebRequest(req, req.body)
+                    ];
+                case 1:
+                    probe = _state.sent();
+                    return [
+                        4,
+                        isLegacyRequest(probe)
+                    ];
+                case 2:
+                    if (!_state.sent()) return [
+                        3,
+                        4
+                    ];
+                    return [
+                        4,
+                        handleLegacyMcpRequest(req, res, buildServer())
+                    ];
+                case 3:
+                    _state.sent();
+                    return [
+                        3,
+                        6
+                    ];
+                case 4:
+                    return [
+                        4,
+                        handleModernMcpRequest(req, res, buildServer)
+                    ];
+                case 5:
+                    _state.sent();
+                    _state.label = 6;
+                case 6:
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+/**
+ * Serves one 2026-07-28 request through `createMcpHandler`.
+ *
+ * `legacy: 'reject'` keeps this leg modern-only — 2025-era traffic never reaches it, having
+ * already been routed to {@link handleLegacyMcpRequest}.
+ *
+ * `responseMode: 'json'` is the modern-leg equivalent of the legacy transport's
+ * `enableJsonResponse`, keeping the endpoint on a single `application/json` body. Safe here
+ * because no tool handler emits mid-call notifications, which are the only thing `'json'` drops.
+ *
+ * @param req - The Express request carrying the JSON-RPC body.
+ * @param res - The Express response.
+ * @param buildServer - Factory producing the MCP server that backs this request.
+ */ function handleModernMcpRequest(req, res, buildServer) {
+    return _async_to_generator$1(function() {
+        var handler;
+        return _ts_generator$1(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    handler = createMcpHandler(buildServer, {
+                        legacy: 'reject',
+                        responseMode: 'json'
+                    });
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        ,
+                        3,
+                        5
+                    ]);
+                    return [
+                        4,
+                        toNodeHandler(handler)(req, res, req.body)
+                    ];
+                case 2:
+                    _state.sent();
+                    return [
+                        3,
+                        5
+                    ];
+                case 3:
+                    return [
+                        4,
+                        handler.close()
+                    ];
+                case 4:
+                    _state.sent();
+                    return [
+                        7
+                    ];
+                case 5:
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+}
+/**
+ * Serves one 2025-era request through a stateless `NodeStreamableHTTPServerTransport`.
+ *
+ * `sessionIdGenerator: undefined` selects stateless mode: the transport binds the server,
+ * processes one request, and is discarded.
+ *
+ * `enableJsonResponse: true` replies with a single `application/json` body instead of framing it
+ * as `text/event-stream`. Stateless mode answers exactly one JSON-RPC message per request and the
+ * controller only implements POST (there is no standalone SSE stream to keep open), so SSE framing
+ * adds nothing while making the endpoint fragile behind proxies that buffer or rewrite streamed
+ * responses — the failure that originally pushed the demo app off its dev proxy.
+ *
+ * @param req - The Express request carrying the JSON-RPC body.
+ * @param res - The Express response.
  * @param server - The MCP server instance to back the transport.
- * @param server.connect - The MCP server's connect method that binds the transport before request handling.
- */ function handleStreamableHttpMcpRequest(req, res, server) {
+ */ function handleLegacyMcpRequest(req, res, server) {
     return _async_to_generator$1(function() {
         var transport;
         return _ts_generator$1(this, function(_state) {
             switch(_state.label){
                 case 0:
-                    // sessionIdGenerator: undefined → stateless mode.
-                    transport = new StreamableHTTPServerTransport({
-                        sessionIdGenerator: undefined
+                    transport = new NodeStreamableHTTPServerTransport({
+                        sessionIdGenerator: undefined,
+                        enableJsonResponse: true
                     });
                     res.on('close', function() {
                         void transport.close();
@@ -7448,9 +8113,11 @@ var McpController_1;
  * which must include `'/mcp'` in its `protectedPaths`. By the time the request reaches
  * this controller, `req.auth` is populated with the authenticated user's data.
  *
- * Each request gets a fresh transport + MCP server pair (stateless mode), which is
- * adequate for Claude custom-connector style usage. A session-tracked variant can
- * be layered on later if streaming tool output becomes a requirement.
+ * Each request gets a fresh MCP server (stateless mode), which is adequate for Claude
+ * custom-connector style usage. Both protocol eras are served — 2026-07-28 through the
+ * SDK's per-request `createMcpHandler` entry, and 2025-era through a stateless Streamable
+ * HTTP transport. A session-tracked variant can be layered on later if streaming tool
+ * output becomes a requirement.
  */ var McpController = McpController_1 = /*#__PURE__*/ function() {
     function McpController(factory) {
         _class_call_check$2(this, McpController);
@@ -7463,15 +8130,12 @@ var McpController_1;
             key: "handleMcpRequest",
             value: function handleMcpRequest(req, res) {
                 return _async_to_generator(function() {
-                    var auth, server, error;
+                    var _this, auth, error;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
+                                _this = this;
                                 auth = req.auth;
-                                server = this.factory.createServer({
-                                    auth: auth,
-                                    rawRequest: req
-                                });
                                 _state.label = 1;
                             case 1:
                                 _state.trys.push([
@@ -7482,7 +8146,12 @@ var McpController_1;
                                 ]);
                                 return [
                                     4,
-                                    handleStreamableHttpMcpRequest(req, res, server)
+                                    handleStreamableHttpMcpRequest(req, res, function() {
+                                        return _this.factory.createServer({
+                                            auth: auth,
+                                            rawRequest: req
+                                        });
+                                    })
                                 ];
                             case 2:
                                 _state.sent();
@@ -7511,6 +8180,45 @@ var McpController_1;
                     });
                 }).call(this);
             }
+        },
+        {
+            /**
+     * Rejects the Streamable HTTP transport's optional `GET` method, which opens a standalone SSE
+     * stream. Not applicable in stateless mode. Separate from {@link handleUnsupportedDelete} because
+     * NestJS binds one HTTP method per handler — stacking route decorators would silently drop one.
+     *
+     * @param res - The Express response to write the rejection to.
+     */ key: "handleUnsupportedGet",
+            value: function handleUnsupportedGet(res) {
+                this._rejectUnsupportedMethod(res);
+            }
+        },
+        {
+            /**
+     * Rejects the Streamable HTTP transport's optional `DELETE` method, which tears down a session.
+     * Not applicable in stateless mode — no session is ever issued.
+     *
+     * @param res - The Express response to write the rejection to.
+     */ key: "handleUnsupportedDelete",
+            value: function handleUnsupportedDelete(res) {
+                this._rejectUnsupportedMethod(res);
+            }
+        },
+        {
+            /**
+     * Answers with a spec-conformant `405 Method Not Allowed` + `Allow` header. Without these
+     * handlers NestJS answers `404`, which some clients treat as a hard failure rather than
+     * "the server doesn't offer this".
+     *
+     * @param res - The Express response to write the rejection to.
+     */ key: "_rejectUnsupportedMethod",
+            value: function _rejectUnsupportedMethod(res) {
+                res.setHeader('Allow', 'POST');
+                res.status(HttpStatus.METHOD_NOT_ALLOWED).json({
+                    statusCode: HttpStatus.METHOD_NOT_ALLOWED,
+                    message: 'Method Not Allowed'
+                });
+            }
         }
     ]);
     return McpController;
@@ -7520,6 +8228,14 @@ __decorate([
     __param(0, Req()),
     __param(1, Res())
 ], McpController.prototype, "handleMcpRequest", null);
+__decorate([
+    Get(),
+    __param(0, Res())
+], McpController.prototype, "handleUnsupportedGet", null);
+__decorate([
+    Delete(),
+    __param(0, Res())
+], McpController.prototype, "handleUnsupportedDelete", null);
 McpController = McpController_1 = __decorate([
     Controller('mcp'),
     __param(0, Inject(McpServerFactoryService))
@@ -7605,6 +8321,13 @@ function _unsupported_iterable_to_array$2(o, minLen) {
  * URIs must live at the host root. Apps need to exclude `.well-known/{*path}`
  * from any global API route prefix (see `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`
  * in `firebase-server/oidc` for the corresponding OIDC excludes).
+ *
+ * Because the document must be reachable at the origin root, the MCP endpoint has to be
+ * exposed through a host that serves the app at `/` — Firebase Hosting, or the hosting
+ * emulator in development. Pointing a client straight at the Functions emulator origin
+ * (`http://localhost:<port>/<project>/<region>/<function>/mcp`) breaks discovery: that
+ * runtime only routes `/<project>/<region>/<function>/…`, so nothing answers at the root
+ * and a client that has not yet seen a 401 challenge cannot find the issuer.
  */ var McpWellKnownController = /*#__PURE__*/ function() {
     function McpWellKnownController(mcpConfig, oidcProviderConfigService) {
         _class_call_check$1(this, McpWellKnownController);
@@ -7615,12 +8338,26 @@ function _unsupported_iterable_to_array$2(o, minLen) {
     }
     _create_class$1(McpWellKnownController, [
         {
-            key: "getProtectedResourceMetadata",
+            /**
+     * Serves both RFC 9728 discovery URLs — the primary form (§3.1), which inserts the resource's
+     * path after the well-known prefix (`/.well-known/oauth-protected-resource/mcp`), and the bare
+     * form (`/.well-known/oauth-protected-resource`) that clients probe as a fallback.
+     *
+     * The document is identical either way; the resource identity comes from
+     * {@link McpModuleConfig.mcpUrl}, not from the request path. Serving the primary form means
+     * discovery succeeds on a client's first probe rather than depending on it implementing the
+     * fallback.
+     *
+     * @returns The protected-resource metadata document.
+     */ key: "getProtectedResourceMetadata",
             value: function getProtectedResourceMetadata() {
                 var _this_mcpConfig = this.mcpConfig, mcpUrl = _this_mcpConfig.mcpUrl, oidcIssuer = _this_mcpConfig.oidcIssuer, scopesFilter = _this_mcpConfig.scopesSupported;
-                // Base scope list is the OIDC provider's own `scopes_supported`, so the resource
-                // advertises exactly what the issuer grants; the optional filter narrows it.
-                var providerScopes = this.oidcProviderConfigService.scopesSupported;
+                // Base scope list is what the issuer grants an arbitrary client, NOT its full
+                // `scopes_supported`: a dynamic-registration client copies this list verbatim onto
+                // `/authorize`, and a provider-profile-gated scope in it would be hard-rejected at the
+                // consent unlock gate (`access_denied`) for every client lacking that profile assignment.
+                // The optional filter narrows the list further.
+                var providerScopes = this.oidcProviderConfigService.clientRequestableScopesSupported;
                 var scopes = scopesFilter ? scopesFilter(providerScopes) : providerScopes;
                 return _object_spread({
                     resource: mcpUrl,
@@ -7636,7 +8373,10 @@ function _unsupported_iterable_to_array$2(o, minLen) {
     return McpWellKnownController;
 }();
 __decorate([
-    Get('oauth-protected-resource')
+    Get([
+        'oauth-protected-resource',
+        'oauth-protected-resource/{*path}'
+    ])
 ], McpWellKnownController.prototype, "getProtectedResourceMetadata", null);
 McpWellKnownController = __decorate([
     Controller('.well-known'),
@@ -7946,4 +8686,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-export { BATCH_EXECUTE_DISPATCH_CALL, BATCH_EXECUTE_DISPATCH_MODEL_TYPE, BATCH_EXECUTE_TOOL_NAME, DEFAULT_BATCH_EXECUTE_MAX_PARALLEL, DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, DEFAULT_MCP_ANALYTICS_EVENT_NAME, DEFAULT_MCP_PATH, DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION, DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH, DEFAULT_MCP_REASON_PARAMETER_NAME, DEFAULT_MCP_REASON_PARAMETER_REQUIRED, DEFAULT_MCP_SERVER_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_SPECIFIER_KEY, DEFAULT_VOID_MCP_SUCCESS_VALUE, ENUM_INFO_DISPATCH_CALL, ENUM_INFO_DISPATCH_MODEL_TYPE, ENUM_INFO_TOOL_NAME, ENUM_TABLE_SCHEMA, FIREBASE_SERVER_MCP_ANALYTICS_CONFIG, FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerMcpAnalyticsService, MAX_BATCH_EXECUTE_FILE_BYTES, MAX_BATCH_EXECUTE_OPERATIONS, MCP_ANALYTICS_SERVICE, MCP_AUTH_ROLE_READER, MCP_CALL_TYPE_ABBREVIATIONS, MCP_MANIFEST_VERSION, MCP_MODEL_GET_BATCH_SIZE, MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAME_WARN_LENGTH, MCP_WRITE_TOOL_DESCRIPTION_PREFIX, MODEL_DECODE_DISPATCH_CALL, MODEL_DECODE_DISPATCH_MODEL_TYPE, MODEL_DECODE_TOOL_NAME, MODEL_GET_DISPATCH_CALL, MODEL_GET_DISPATCH_MODEL_TYPE, MODEL_GET_TOOL_NAME, MODEL_INFO_DISPATCH_CALL, MODEL_INFO_DISPATCH_MODEL_TYPE, MODEL_INFO_GROUPS_HINT, MODEL_INFO_TOOL_NAME, MODEL_INFO_UNGROUPED_LABEL, McpAnalyticsService, McpController, McpModuleConfig, McpServerFactoryService, McpWellKnownController, ROUTE_MANIFEST_VERSION, URL_MODELS_DISPATCH_CALL, URL_MODELS_DISPATCH_MODEL_TYPE, URL_MODELS_TOOL_NAME, abbreviateMcpCallType, appMcpAnalyticsModuleMetadata, applyMcpReasonParameterToSchema, applyWriteMarker, batchOperationCoordKey, buildDefaultMcpToolDescription, buildDisambiguatedMcpToolName, buildMcpToolName, buildStaticToolDefinition, buildStaticWireEntry, classifyVisibility, createBatchExecuteTool, createEnumInfoTool, createModelDecodeTool, createModelGetTool, createModelInfoTool, createUrlModelsTool, decodeFirestoreModelKey, extractMcpReasonFromArgs, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, matchRouteManifestUrl, mcpManifestKey, mcpModuleMetadata, mcpSchemaDeclaresProperty, noopMcpAnalyticsService, parseUrlModelsPathname, readUrlModelsImpersonationUid, resolveEffectiveReadOnly, resolveEnumInfoOutput, resolveMcpReasonParameterConfig, resolveMcpToolAnnotations, resolveRequiredScope, validateMcpToolName };
+export { BATCH_EXECUTE_DISPATCH_CALL, BATCH_EXECUTE_DISPATCH_MODEL_TYPE, BATCH_EXECUTE_TOOL_NAME, DEFAULT_BATCH_EXECUTE_MAX_PARALLEL, DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, DEFAULT_MCP_ANALYTICS_EVENT_NAME, DEFAULT_MCP_PATH, DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION, DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH, DEFAULT_MCP_REASON_PARAMETER_NAME, DEFAULT_MCP_REASON_PARAMETER_REQUIRED, DEFAULT_MCP_SERVER_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_SPECIFIER_KEY, DEFAULT_VOID_MCP_SUCCESS_VALUE, ENUM_INFO_DISPATCH_CALL, ENUM_INFO_DISPATCH_MODEL_TYPE, ENUM_INFO_TOOL_NAME, ENUM_TABLE_SCHEMA, FIREBASE_SERVER_MCP_ANALYTICS_CONFIG, FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerMcpAnalyticsService, MAX_BATCH_EXECUTE_FILE_BYTES, MAX_BATCH_EXECUTE_OPERATIONS, MCP_ANALYTICS_SERVICE, MCP_AUTH_ROLE_READER, MCP_CALL_TYPE_ABBREVIATIONS, MCP_MANIFEST_VERSION, MCP_MODEL_GET_BATCH_SIZE, MCP_MODEL_ROLES_MAX_KEYS, MCP_MODEL_ROLES_TARGET_UID_PREDICATE, MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAME_WARN_LENGTH, MCP_WRITE_TOOL_DESCRIPTION_PREFIX, MODEL_DECODE_DISPATCH_CALL, MODEL_DECODE_DISPATCH_MODEL_TYPE, MODEL_DECODE_TOOL_NAME, MODEL_GET_DISPATCH_CALL, MODEL_GET_DISPATCH_MODEL_TYPE, MODEL_GET_TOOL_NAME, MODEL_INFO_DISPATCH_CALL, MODEL_INFO_DISPATCH_MODEL_TYPE, MODEL_INFO_GROUPS_HINT, MODEL_INFO_TOOL_NAME, MODEL_INFO_UNGROUPED_LABEL, MODEL_ROLES_DISPATCH_CALL, MODEL_ROLES_DISPATCH_MODEL_TYPE, MODEL_ROLES_TOOL_NAME, McpAnalyticsService, McpController, McpModuleConfig, McpServerFactoryService, McpWellKnownController, ROUTE_MANIFEST_VERSION, URL_MODELS_DISPATCH_CALL, URL_MODELS_DISPATCH_MODEL_TYPE, URL_MODELS_TOOL_NAME, abbreviateMcpCallType, appMcpAnalyticsModuleMetadata, applyMcpReasonParameterToSchema, applyWriteMarker, batchOperationCoordKey, buildDefaultMcpToolDescription, buildDisambiguatedMcpToolName, buildMcpToolName, buildStaticToolDefinition, buildStaticWireEntry, classifyVisibility, createBatchExecuteTool, createEnumInfoTool, createModelDecodeTool, createModelGetTool, createModelInfoTool, createModelRolesTool, createUrlModelsTool, decodeFirestoreModelKey, extractMcpReasonFromArgs, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, matchRouteManifestUrl, mcpManifestKey, mcpModuleMetadata, mcpSchemaDeclaresProperty, noopMcpAnalyticsService, parseUrlModelsPathname, readUrlModelsImpersonationUid, resolveEffectiveReadOnly, resolveEnumInfoOutput, resolveMcpReasonParameterConfig, resolveMcpToolAnnotations, resolveRequiredScope, validateMcpToolName };