@dereekb/firebase-server 13.17.0 → 13.18.0

package/mcp/index.cjs.js

@@ -17,7 +17,7 @@ function _class_call_check$5(instance, Constructor) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function _define_property$8(obj, key, value) {
+function _define_property$9(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -47,6 +47,23 @@ function _define_property$8(obj, key, value) {
  * Default `instructions` string advertised by the MCP server on the JSON-RPC `initialize`
  * handshake. Apps may override this via {@link McpModuleConfig.serverInstructions}.
  */ var DEFAULT_MCP_SERVER_INSTRUCTIONS = 'A set of call-model tools generated automatically.';
+/**
+ * Default name of the auto-injected reason parameter added to every advertised MCP tool's input
+ * schema. See {@link McpReasonParameterConfig.parameterName}.
+ */ var DEFAULT_MCP_REASON_PARAMETER_NAME = 'reason';
+/**
+ * Default maximum length (in characters) of the auto-injected reason parameter. Values longer than
+ * this are clamped server-side before being forwarded to analytics. See
+ * {@link McpReasonParameterConfig.maxLength}.
+ */ var DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH = 250;
+/**
+ * Default required-ness of the auto-injected reason parameter. See
+ * {@link McpReasonParameterConfig.required}.
+ */ var DEFAULT_MCP_REASON_PARAMETER_REQUIRED = true;
+/**
+ * Default description advertised for the auto-injected reason parameter on every tool's input schema.
+ * See {@link McpReasonParameterConfig.description}.
+ */ var DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION = 'A brief human-readable reason (≤250 chars) explaining why this tool is being called. Recorded for analytics/audit only; not part of the operation.';
 /**
  * Configuration for the firebase-server/mcp module.
  *
@@ -71,7 +88,7 @@ function _define_property$8(obj, key, value) {
      * discovery document. Claude custom-connector reads this to discover the OIDC issuer.
      *
      * @example 'https://api.example.com/oidc'
-     */ _define_property$8(this, "oidcIssuer", void 0);
+     */ _define_property$9(this, "oidcIssuer", void 0);
     /**
      * The canonical resource URL of the MCP endpoint.
      *
@@ -79,19 +96,19 @@ function _define_property$8(obj, key, value) {
      * and used as the audience the access token's `aud` claim should match.
      *
      * @example 'https://api.example.com/mcp'
-     */ _define_property$8(this, "mcpUrl", void 0);
+     */ _define_property$9(this, "mcpUrl", void 0);
     /**
      * Optional name advertised on the MCP `initialize` handshake. Defaults to
      * {@link DEFAULT_MCP_SERVER_NAME}.
-     */ _define_property$8(this, "serverName", void 0);
+     */ _define_property$9(this, "serverName", void 0);
     /**
      * Optional version advertised on the MCP `initialize` handshake.
-     */ _define_property$8(this, "serverVersion", void 0);
+     */ _define_property$9(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$8(this, "serverInstructions", void 0);
+     */ _define_property$9(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
@@ -101,7 +118,7 @@ function _define_property$8(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$8(this, "mcpManifestPath", void 0);
+     */ _define_property$9(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
@@ -111,7 +128,7 @@ function _define_property$8(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$8(this, "mcpRouteManifestPath", void 0);
+     */ _define_property$9(this, "mcpRouteManifestPath", void 0);
     /**
      * When `true`, the MCP server only advertises tools whose effective read-only classification is `true`.
      *
@@ -121,19 +138,29 @@ function _define_property$8(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$8(this, "readOnly", void 0);
+     */ _define_property$9(this, "readOnly", void 0);
+    /**
+     * Controls the auto-injected `reason` parameter added to every advertised tool's input schema.
+     *
+     * Enabled by default (unset / `true` = defaults on). Pass a {@link McpReasonParameterConfig} object
+     * to tune `required`, `maxLength`, `description`, or `parameterName`, or `false` to disable it.
+     *
+     * 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);
 };
 /**
  * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
  */ var MCP_AUTH_ROLE_READER = 'MCP_AUTH_ROLE_READER';
 
-function _type_of$4(obj) {
+function _type_of$5(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
 function __decorate(decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if ((typeof Reflect === "undefined" ? "undefined" : _type_of$4(Reflect)) === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    if ((typeof Reflect === "undefined" ? "undefined" : _type_of$5(Reflect)) === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
@@ -147,6 +174,206 @@ typeof SuppressedError === "function" ? SuppressedError : function(error, suppre
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+function _array_like_to_array$a(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes$7(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$a(arr);
+}
+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 _iterable_to_array$7(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread$7() {
+    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$5(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 ownKeys$3(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props$3(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys$3(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _to_consumable_array$7(arr) {
+    return _array_without_holes$7(arr) || _iterable_to_array$7(arr) || _unsupported_iterable_to_array$a(arr) || _non_iterable_spread$7();
+}
+function _type_of$4(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _unsupported_iterable_to_array$a(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$a(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    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$a(o, minLen);
+}
+/**
+ * Normalizes the app-supplied {@link McpModuleConfig.reasonParameter} value (object / boolean /
+ * undefined) into a fully-resolved {@link ResolvedMcpReasonParameterConfig} with the package defaults
+ * applied.
+ *
+ * - `undefined` / `true` → defaults, enabled.
+ * - `false` → defaults, but `enabled: false`.
+ * - object → per-field overrides on top of the defaults (`enabled` defaults to `true`).
+ *
+ * @param config - The raw config from {@link McpModuleConfig.reasonParameter}.
+ * @returns The resolved config with all defaults applied.
+ */ function resolveMcpReasonParameterConfig(config) {
+    var result;
+    if (config === false) {
+        result = {
+            enabled: false,
+            required: DEFAULT_MCP_REASON_PARAMETER_REQUIRED,
+            maxLength: DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH,
+            description: DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION,
+            parameterName: DEFAULT_MCP_REASON_PARAMETER_NAME
+        };
+    } else if (config == null || config === true) {
+        result = {
+            enabled: true,
+            required: DEFAULT_MCP_REASON_PARAMETER_REQUIRED,
+            maxLength: DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH,
+            description: DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION,
+            parameterName: DEFAULT_MCP_REASON_PARAMETER_NAME
+        };
+    } else {
+        var _config_enabled, _config_required, _config_maxLength, _config_description, _config_parameterName;
+        result = {
+            enabled: (_config_enabled = config.enabled) !== null && _config_enabled !== void 0 ? _config_enabled : true,
+            required: (_config_required = config.required) !== null && _config_required !== void 0 ? _config_required : DEFAULT_MCP_REASON_PARAMETER_REQUIRED,
+            maxLength: (_config_maxLength = config.maxLength) !== null && _config_maxLength !== void 0 ? _config_maxLength : DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH,
+            description: (_config_description = config.description) !== null && _config_description !== void 0 ? _config_description : DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION,
+            parameterName: (_config_parameterName = config.parameterName) !== null && _config_parameterName !== void 0 ? _config_parameterName : DEFAULT_MCP_REASON_PARAMETER_NAME
+        };
+    }
+    return result;
+}
+/**
+ * Returns `true` when the JSON schema already declares a property named `name` under `properties`.
+ *
+ * Used as the collision guard so a handler that legitimately consumes its own field of the same name
+ * is never double-declared (schema injection) or stripped (arg extraction).
+ *
+ * @param schema - The candidate JSON schema object (may be `undefined`).
+ * @param name - The property name to look for.
+ * @returns Whether the schema's `properties` already contains `name`.
+ */ function mcpSchemaDeclaresProperty(schema, name) {
+    var properties = schema === null || schema === void 0 ? void 0 : schema.properties;
+    return properties != null && (typeof properties === "undefined" ? "undefined" : _type_of$4(properties)) === 'object' && Object.prototype.hasOwnProperty.call(properties, name);
+}
+/**
+ * Returns a NEW JSON schema object with the reason parameter property merged into `properties` (and
+ * appended to `required` when configured). Never mutates the input — the static wire schemas are
+ * shared module-level constants reused across requests.
+ *
+ * Self-skips (returns the input schema unchanged) when the config is disabled or the schema already
+ * declares the parameter name. Defensive against a non-object / missing-`properties` input.
+ *
+ * @param inputSchema - The tool's resolved input schema.
+ * @param resolved - The resolved reason-parameter config.
+ * @returns A new schema carrying the reason property, or the original schema when skipped.
+ */ function applyMcpReasonParameterToSchema(inputSchema, resolved) {
+    var result = inputSchema;
+    if (resolved.enabled && !mcpSchemaDeclaresProperty(inputSchema, resolved.parameterName)) {
+        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$5({}, base), {
+            type: (_base_type = base.type) !== null && _base_type !== void 0 ? _base_type : 'object',
+            properties: _object_spread_props$3(_object_spread$5({}, existingProperties), _define_property$8({}, resolved.parameterName, {
+                type: 'string',
+                maxLength: resolved.maxLength,
+                description: resolved.description
+            }))
+        });
+        if (resolved.required) {
+            var existingRequired = Array.isArray(base.required) ? base.required : [];
+            next.required = existingRequired.includes(resolved.parameterName) ? _to_consumable_array$7(existingRequired) : _to_consumable_array$7(existingRequired).concat([
+                resolved.parameterName
+            ]);
+        }
+        result = next;
+    }
+    return result;
+}
+/**
+ * Splits the auto-injected reason value out of a tool call's raw arguments.
+ *
+ * When enabled and the tool did NOT declare its own field of the same name: shallow-copies the args,
+ * deletes the parameter key, and coerces + clamps the value to `maxLength` (the client is not trusted).
+ * An empty / absent value yields `reason: undefined`.
+ *
+ * Otherwise (disabled, or the handler legitimately owns the field) returns the args unchanged so a
+ * field the handler actually consumes is never stripped.
+ *
+ * @param args - The raw `tools/call` arguments.
+ * @param resolved - The resolved reason-parameter config.
+ * @param toolDeclaresOwnReason - Whether the tool's own input schema already declares the parameter.
+ * @returns The extracted reason plus the (possibly stripped) args to dispatch.
+ */ function extractMcpReasonFromArgs(args, resolved, toolDeclaresOwnReason) {
+    var result;
+    if (resolved.enabled && !toolDeclaresOwnReason && Object.prototype.hasOwnProperty.call(args, resolved.parameterName)) {
+        var rawValue = args[resolved.parameterName];
+        var nextArgs = _object_spread$5({}, args);
+        delete nextArgs[resolved.parameterName];
+        var stringValue = rawValue == null ? '' : String(rawValue);
+        var clamped = stringValue.length > resolved.maxLength ? stringValue.slice(0, resolved.maxLength) : stringValue;
+        result = {
+            reason: clamped.length > 0 ? clamped : undefined,
+            args: nextArgs
+        };
+    } else {
+        result = {
+            reason: undefined,
+            args: args
+        };
+    }
+    return result;
+}
+
 function _class_call_check$4(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
@@ -949,6 +1176,46 @@ function _unsupported_iterable_to_array$8(o, minLen) {
  */ function applyWriteMarker(description, annotations) {
     return annotations.readOnlyHint === false ? "".concat(MCP_WRITE_TOOL_DESCRIPTION_PREFIX).concat(description) : description;
 }
+/**
+ * Assembles a statically-registered {@link McpToolDefinition} with consistent MCP annotations.
+ *
+ * Built-in tools (e.g. `whoami`, `model-get`, `batch-execute`) don't flow through
+ * {@link buildToolFromCandidate}, so this is their analogous single source of truth: it derives the
+ * read/write annotations from {@link BuildStaticToolDefinitionInput.effectiveReadOnly} via
+ * {@link resolveMcpToolAnnotations}, applies the {@link MCP_WRITE_TOOL_DESCRIPTION_PREFIX} write
+ * marker to the description, then mirrors the annotations onto both the definition's `annotations`
+ * field and the frozen {@link McpToolDefinition.staticWireEntry}. Centralizing this guarantees no
+ * built-in tool reaches `tools/list` un-annotated (which would surface as an uncategorized "other"
+ * tool in clients that bucket by `readOnlyHint`).
+ *
+ * @param input - The tool identity, schemas, dispatch target, static handler, and read-only classification.
+ * @returns A statically-registered {@link McpToolDefinition} to append to the MCP server factory's tool registry.
+ */ function buildStaticToolDefinition(input) {
+    var name = input.name, inputSchema = input.inputSchema, outputSchema = input.outputSchema, dispatch = input.dispatch, staticHandler = input.staticHandler, effectiveReadOnly = input.effectiveReadOnly, rule = input.rule;
+    var annotations = resolveMcpToolAnnotations(effectiveReadOnly);
+    var description = applyWriteMarker(input.description, annotations);
+    return {
+        name: name,
+        description: description,
+        inputSchema: inputSchema,
+        outputSchema: outputSchema,
+        annotations: annotations,
+        dispatch: dispatch,
+        staticHandler: staticHandler,
+        filterMetadata: {
+            visibilityKind: 'declarative',
+            rule: rule !== null && rule !== void 0 ? rule : {},
+            effectiveReadOnly: effectiveReadOnly
+        },
+        staticWireEntry: buildStaticWireEntry({
+            name: name,
+            description: description,
+            inputSchema: inputSchema,
+            outputSchema: outputSchema,
+            annotations: annotations
+        })
+    };
+}
 // MARK: Naming
 /**
  * The default specifier key used when a handler is not behind a specifier router.
@@ -1646,7 +1913,7 @@ function _ts_generator$5(thisArg, body) {
     };
     var name = MODEL_GET_TOOL_NAME;
     var description = 'Fetch one or more Firestore model documents by key or bare id. Values containing `/` are treated as full keys; bare ids are auto-promoted to `<collectionName>/<id>` for root models. Subcollection models require full keys.';
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: MODEL_GET_INPUT_SCHEMA,
@@ -1656,20 +1923,11 @@ function _ts_generator$5(thisArg, body) {
             modelType: MODEL_GET_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: MODEL_GET_INPUT_SCHEMA,
-            outputSchema: MODEL_GET_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function modelGetToolHandler(args, ctx, deps) {
@@ -1940,7 +2198,7 @@ function _object_spread$4(target) {
     }
     return target;
 }
-function ownKeys$1(object, enumerableOnly) {
+function ownKeys$2(object, enumerableOnly) {
     var keys = Object.keys(object);
     if (Object.getOwnPropertySymbols) {
         var symbols = Object.getOwnPropertySymbols(object);
@@ -1948,12 +2206,12 @@ function ownKeys$1(object, enumerableOnly) {
     }
     return keys;
 }
-function _object_spread_props$1(target, source) {
+function _object_spread_props$2(target, source) {
     source = source != null ? source : {};
     if (Object.getOwnPropertyDescriptors) {
         Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
     } else {
-        ownKeys$1(Object(source)).forEach(function(key) {
+        ownKeys$2(Object(source)).forEach(function(key) {
             Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
         });
     }
@@ -2017,7 +2275,7 @@ function _unsupported_iterable_to_array$6(o, minLen) {
     var name = MODEL_INFO_TOOL_NAME;
     var count = deps.manifest.length;
     var description = "Browse the Firestore model catalog (".concat(count, " model").concat(count === 1 ? '' : 's', "). No args returns model groups + counts (start here). ") + '`model` (a modelType/identityConst/collectionPrefix string, or an array of them) returns full detail per match — misses are reported in `notFound`. ' + '`modelGroup` returns the summary list for that group. `all:true` returns the full catalog summary. ' + '`fields` (boolean) forces or suppresses persisted-field detail in list/multiple modes.';
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: MODEL_INFO_INPUT_SCHEMA,
@@ -2027,20 +2285,11 @@ function _unsupported_iterable_to_array$6(o, minLen) {
             modelType: MODEL_INFO_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: MODEL_INFO_INPUT_SCHEMA,
-            outputSchema: MODEL_INFO_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function modelInfoToolHandler(args, _ctx, deps) {
@@ -2144,7 +2393,7 @@ function resolveModelInfoOutput(input, manifest) {
             }
         }
         if (tables.length > 0) {
-            result = _object_spread_props$1(_object_spread$4({}, output), {
+            result = _object_spread_props$2(_object_spread$4({}, output), {
                 enums: tables
             });
         }
@@ -2198,7 +2447,7 @@ function parseModelInfoInput(args) {
     var modelGroup = parseModelGroupArg(args['modelGroup']);
     var all = parseBooleanArg(args['all'], 'all');
     var fields = parseBooleanArg(args['fields'], 'fields');
-    return _object_spread$4(_object_spread_props$1(_object_spread$4(_object_spread_props$1(_object_spread$4({}, modelQueries == null ? {} : {
+    return _object_spread$4(_object_spread_props$2(_object_spread$4(_object_spread_props$2(_object_spread$4({}, modelQueries == null ? {} : {
         modelQueries: modelQueries
     }), {
         modelIsArray: Array.isArray(args['model'])
@@ -2696,7 +2945,7 @@ var MODEL_INFO_OUTPUT_SCHEMA = {
             type: 'string',
             description: 'Present when `mode` is `"list"` from a `modelGroup` filter. The canonical group name.'
         },
-        model: _object_spread_props$1(_object_spread$4({}, MODEL_ROW_SCHEMA), {
+        model: _object_spread_props$2(_object_spread$4({}, MODEL_ROW_SCHEMA), {
             description: 'Present when `mode` is `"single"`. The matched model entry (full detail unless `fields:false`).'
         }),
         notFound: {
@@ -2831,7 +3080,7 @@ function _object_spread$3(target) {
     };
     var name = MODEL_DECODE_TOOL_NAME;
     var description = 'Decode a Firestore model key ("prefix/id", or subcollection path "parentPrefix/parentId/childPrefix/childId") into { leaf, ancestors, unresolvedPrefixes } using the registered manifest ('.concat(deps.manifest.length, " model").concat(deps.manifest.length === 1 ? '' : 's', ").");
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: MODEL_DECODE_INPUT_SCHEMA,
@@ -2841,20 +3090,11 @@ function _object_spread$3(target) {
             modelType: MODEL_DECODE_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: MODEL_DECODE_INPUT_SCHEMA,
-            outputSchema: MODEL_DECODE_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function modelDecodeToolHandler(args, _ctx, deps) {
@@ -3061,7 +3301,7 @@ var MODEL_DECODE_OUTPUT_SCHEMA = {
     var name = ENUM_INFO_TOOL_NAME;
     var count = Object.keys(deps.enums).length;
     var description = "Look up enum value→label tables by name (".concat(count, " enum").concat(count === 1 ? '' : 's', ' registered). Pass `enum` (a string or array of enum declaration names, e.g. "JobWorkerTimesheetState") to decode the raw persisted integer/string values a model field stores. Misses are reported in `notFound`.');
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: ENUM_INFO_INPUT_SCHEMA,
@@ -3071,20 +3311,11 @@ var MODEL_DECODE_OUTPUT_SCHEMA = {
             modelType: ENUM_INFO_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: ENUM_INFO_INPUT_SCHEMA,
-            outputSchema: ENUM_INFO_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function enumInfoToolHandler(args, _ctx, deps) {
@@ -3347,7 +3578,7 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     var name = WHOAMI_TOOL_NAME;
     var appLabel = (_ref = (_deps_auth_app = deps.auth.app) === null || _deps_auth_app === void 0 ? void 0 : _deps_auth_app.app) !== null && _ref !== void 0 ? _ref : 'this server';
     var description = "Reports the authenticated caller's uid, raw custom claims, and decoded role set for `".concat(appLabel, "`. Returns `authenticated: false` for anonymous callers. Claim descriptions are drawn from the build-time auth manifest; only keys actually present on the live token are detailed.");
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: WHOAMI_INPUT_SCHEMA,
@@ -3357,18 +3588,9 @@ function _unsupported_iterable_to_array$5(o, minLen) {
             modelType: WHOAMI_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {},
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: WHOAMI_INPUT_SCHEMA,
-            outputSchema: WHOAMI_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {}
+    });
 }
 // MARK: Handler
 function whoamiToolHandler(ctx, deps) {
@@ -3764,7 +3986,7 @@ function _object_spread$1(target) {
     }
     return target;
 }
-function ownKeys(object, enumerableOnly) {
+function ownKeys$1(object, enumerableOnly) {
     var keys = Object.keys(object);
     if (Object.getOwnPropertySymbols) {
         var symbols = Object.getOwnPropertySymbols(object);
@@ -3772,12 +3994,12 @@ function ownKeys(object, enumerableOnly) {
     }
     return keys;
 }
-function _object_spread_props(target, source) {
+function _object_spread_props$1(target, source) {
     source = source != null ? source : {};
     if (Object.getOwnPropertyDescriptors) {
         Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
     } else {
-        ownKeys(Object(source)).forEach(function(key) {
+        ownKeys$1(Object(source)).forEach(function(key) {
             Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
         });
     }
@@ -3931,7 +4153,7 @@ function _ts_generator$4(thisArg, body) {
     };
     var name = URL_MODELS_TOOL_NAME;
     var description = 'Decode an app URL (or path) into the Firestore models its page renders. Pass a URL like `https://app.example.co/worker/abc/timesheets/list`; the tool matches it against the build-time route manifest and returns each model type plus the concrete key (route params + `{authUid}` substituted). Use `models` to filter to specific types, `keysOnly` for just the resolved keys, or `load: true` to fetch the documents via the same permission-checked path as `model-get` (cannot combine `load` with `keysOnly`).';
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: URL_MODELS_INPUT_SCHEMA,
@@ -3941,20 +4163,11 @@ function _ts_generator$4(thisArg, body) {
             modelType: URL_MODELS_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: true
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: URL_MODELS_INPUT_SCHEMA,
-            outputSchema: URL_MODELS_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: true,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function urlModelsToolHandler(args, ctx, deps) {
@@ -4031,7 +4244,7 @@ function parseUrlModelsInput(args) {
         }
         currentUserUid = args.currentUserUid;
     }
-    return _object_spread$1(_object_spread_props(_object_spread$1({
+    return _object_spread$1(_object_spread_props$1(_object_spread$1({
         url: url
     }, models === undefined ? {} : {
         models: models
@@ -4811,7 +5024,7 @@ function _ts_generator$3(thisArg, body) {
     };
     var name = BATCH_EXECUTE_TOOL_NAME;
     var description = 'Execute a batch of MCP operations server-side from an uploaded JSON/NDJSON file, returning a success/failure summary. Each line/element is an operation `{ call, modelType, specifier?, data }` matching any other write tool you could call individually. Generate the file with a script and upload it instead of invoking a per-record tool many times. Every operation is authorized against your visible tools before any run; a forbidden or malformed operation aborts the whole batch with nothing executed.';
-    return {
+    return buildStaticToolDefinition({
         name: name,
         description: description,
         inputSchema: BATCH_EXECUTE_INPUT_SCHEMA,
@@ -4821,20 +5034,11 @@ function _ts_generator$3(thisArg, body) {
             modelType: BATCH_EXECUTE_DISPATCH_MODEL_TYPE
         },
         staticHandler: handler,
-        filterMetadata: {
-            visibilityKind: 'declarative',
-            rule: {
-                requireAuthenticated: true
-            },
-            effectiveReadOnly: false
-        },
-        staticWireEntry: buildStaticWireEntry({
-            name: name,
-            description: description,
-            inputSchema: BATCH_EXECUTE_INPUT_SCHEMA,
-            outputSchema: BATCH_EXECUTE_OUTPUT_SCHEMA
-        })
-    };
+        effectiveReadOnly: false,
+        rule: {
+            requireAuthenticated: true
+        }
+    });
 }
 // MARK: Handler
 function batchExecuteToolHandler(args, ctx, deps) {
@@ -5538,6 +5742,25 @@ function _object_spread(target) {
     }
     return target;
 }
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
 function _sliced_to_array(arr, i) {
     return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array$2(arr, i) || _non_iterable_rest();
 }
@@ -5683,6 +5906,7 @@ var McpServerFactoryService_1;
         _define_property$3(this, "_manifestLoaded", false);
         _define_property$3(this, "_loggedSkips", false);
         _define_property$3(this, "_warnedMissingRoleReader", false);
+        _define_property$3(this, "_resolvedReasonConfig", void 0);
         _define_property$3(this, "_analyticsService", void 0);
         this.mcpConfig = mcpConfig;
         this.dispatchService = dispatchService;
@@ -6385,11 +6609,32 @@ var McpServerFactoryService_1;
         },
         {
             /**
+     * Resolves the app's reason-parameter config once and caches it for the process lifetime.
+     *
+     * The underlying {@link McpModuleConfig.reasonParameter} value is fixed at boot, so the normalized
+     * form is safe to memoize and reuse across every `tools/list` and `tools/call`.
+     *
+     * @returns The resolved reason-parameter config (defaults applied).
+     */ key: "_resolveReasonConfig",
+            value: function _resolveReasonConfig() {
+                var result = this._resolvedReasonConfig;
+                if (result == null) {
+                    result = resolveMcpReasonParameterConfig(this.mcpConfig.reasonParameter);
+                    this._resolvedReasonConfig = result;
+                }
+                return result;
+            }
+        },
+        {
+            /**
      * Resolves the wire-shape `tools/list` entry for a single tool.
      *
      * Hot-path short-circuit: tools without a `toolDetailsBuilder` reuse the precomputed,
      * frozen {@link McpToolDefinition.staticWireEntry} verbatim — zero allocations per
-     * request for the common case.
+     * request for the common case. When the auto-injected reason parameter is enabled (the
+     * default), the entry is no longer returned frozen-verbatim: its `inputSchema` is wrapped
+     * with the reason property per request (`tools/list` is low-frequency, so the allocation is
+     * acceptable). Tools that already declare the parameter name are still reused verbatim.
      *
      * Tools that opted in to {@link McpToolDetailsBuilder} get a fresh wire entry built
      * from the builder's overrides. If the builder throws, the framework falls back to
@@ -6401,9 +6646,20 @@ var McpServerFactoryService_1;
      * @returns The wire-shape entry to emit for this tool on `tools/list`.
      */ key: "_buildToolListEntry",
             value: function _buildToolListEntry(tool, ctx, scopes) {
+                var reasonConfig = this._resolveReasonConfig();
                 var result;
                 if (tool.toolDetailsBuilder == null) {
                     result = tool.staticWireEntry;
+                    if (reasonConfig.enabled) {
+                        var reasoned = applyMcpReasonParameterToSchema(tool.staticWireEntry.inputSchema, reasonConfig);
+                        // applyMcpReasonParameterToSchema self-skips (returns the same reference) on collision, so the
+                        // frozen-verbatim hot path still holds for tools that already declare the parameter name.
+                        if (reasoned !== tool.staticWireEntry.inputSchema) {
+                            result = _object_spread_props(_object_spread({}, tool.staticWireEntry), {
+                                inputSchema: reasoned
+                            });
+                        }
+                    }
                 } else {
                     var description = tool.description;
                     var inputSchema = tool.inputSchema;
@@ -6424,12 +6680,16 @@ var McpServerFactoryService_1;
                     } catch (error) {
                         this._logger.warn("MCP tool ".concat(tool.name, " toolDetails builder threw; falling back to defaults: ").concat(error.message));
                     }
+                    var resolvedInputSchema = inputSchema !== null && inputSchema !== void 0 ? inputSchema : {
+                        type: 'object'
+                    };
+                    if (reasonConfig.enabled) {
+                        resolvedInputSchema = applyMcpReasonParameterToSchema(resolvedInputSchema, reasonConfig);
+                    }
                     var wire = {
                         name: tool.name,
                         description: description,
-                        inputSchema: inputSchema !== null && inputSchema !== void 0 ? inputSchema : {
-                            type: 'object'
-                        }
+                        inputSchema: resolvedInputSchema
                     };
                     if (tool.outputSchema != null) {
                         wire.outputSchema = tool.outputSchema;
@@ -6459,14 +6719,20 @@ var McpServerFactoryService_1;
      * @returns The MCP tool response.
      */ function _handleToolCall(request, definitionsByName, ctx) {
                 return _async_to_generator$2(function() {
-                    var _request_params_arguments, _ctx_auth, toolName, definition, args, startedAt, outcome, isSuccessful, toolKind;
+                    var _request_params_arguments, _ctx_auth, toolName, definition, rawArgs, startedAt, reasonConfig, declaresOwn, _extractMcpReasonFromArgs, reason, args, outcome, isSuccessful, toolKind;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
                                 toolName = request.params.name;
                                 definition = definitionsByName.get(toolName);
-                                args = (_request_params_arguments = request.params.arguments) !== null && _request_params_arguments !== void 0 ? _request_params_arguments : {};
+                                rawArgs = (_request_params_arguments = request.params.arguments) !== null && _request_params_arguments !== void 0 ? _request_params_arguments : {};
                                 startedAt = Date.now();
+                                // Split the auto-injected reason out of the args: forward it to analytics, but never let it reach
+                                // the underlying handler. Tools that declare their own field of the same name keep it (driven by
+                                // the tool's own resolved inputSchema, not the reason-augmented wire schema).
+                                reasonConfig = this._resolveReasonConfig();
+                                declaresOwn = mcpSchemaDeclaresProperty(definition === null || definition === void 0 ? void 0 : definition.inputSchema, reasonConfig.parameterName);
+                                _extractMcpReasonFromArgs = extractMcpReasonFromArgs(rawArgs, reasonConfig, declaresOwn), reason = _extractMcpReasonFromArgs.reason, args = _extractMcpReasonFromArgs.args;
                                 if (!(definition == null)) return [
                                     3,
                                     1
@@ -6516,6 +6782,7 @@ var McpServerFactoryService_1;
                                     auth: ctx.auth,
                                     readOnly: this.mcpConfig.readOnly === true,
                                     args: args,
+                                    reason: reason,
                                     isSuccessful: isSuccessful,
                                     error: outcome.error,
                                     durationMs: Date.now() - startedAt
@@ -7357,18 +7624,20 @@ var FirebaseServerMcpAnalyticsService_1;
                 if (this._logEvents) {
                     var uidSuffix = event.uid ? " uid=".concat(event.uid) : '';
                     var durationSuffix = event.durationMs == null ? '' : " (".concat(event.durationMs, "ms)");
+                    var reasonSuffix = event.reason ? ' reason="'.concat(event.reason, '"') : '';
                     var outcome = event.isSuccessful ? 'Succeeded' : 'Failed';
-                    this._logger.log("MCP ".concat(event.toolName, " [").concat(event.toolKind, "] ").concat(outcome).concat(uidSuffix).concat(durationSuffix));
+                    this._logger.log("MCP ".concat(event.toolName, " [").concat(event.toolKind, "] ").concat(outcome).concat(uidSuffix).concat(durationSuffix).concat(reasonSuffix));
                 }
                 if (this.analyticsService != null) {
-                    var _event_call, _event_modelType, _event_specifier;
+                    var _event_call, _event_modelType, _event_specifier, _event_reason;
                     this.analyticsService.sendEventData(event.uid, this._eventName, {
                         tool: event.toolName,
                         toolKind: event.toolKind,
                         call: (_event_call = event.call) !== null && _event_call !== void 0 ? _event_call : '',
                         modelType: (_event_modelType = event.modelType) !== null && _event_modelType !== void 0 ? _event_modelType : '',
                         specifier: (_event_specifier = event.specifier) !== null && _event_specifier !== void 0 ? _event_specifier : '',
-                        success: event.isSuccessful
+                        success: event.isSuccessful,
+                        reason: (_event_reason = event.reason) !== null && _event_reason !== void 0 ? _event_reason : ''
                     });
                 }
             }
@@ -7462,6 +7731,10 @@ exports.DEFAULT_BATCH_EXECUTE_MAX_PARALLEL = DEFAULT_BATCH_EXECUTE_MAX_PARALLEL;
 exports.DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS = DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS;
 exports.DEFAULT_MCP_ANALYTICS_EVENT_NAME = DEFAULT_MCP_ANALYTICS_EVENT_NAME;
 exports.DEFAULT_MCP_PATH = DEFAULT_MCP_PATH;
+exports.DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION = DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION;
+exports.DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH = DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH;
+exports.DEFAULT_MCP_REASON_PARAMETER_NAME = DEFAULT_MCP_REASON_PARAMETER_NAME;
+exports.DEFAULT_MCP_REASON_PARAMETER_REQUIRED = DEFAULT_MCP_REASON_PARAMETER_REQUIRED;
 exports.DEFAULT_MCP_SERVER_INSTRUCTIONS = DEFAULT_MCP_SERVER_INSTRUCTIONS;
 exports.DEFAULT_MCP_SERVER_NAME = DEFAULT_MCP_SERVER_NAME;
 exports.DEFAULT_SPECIFIER_KEY = DEFAULT_SPECIFIER_KEY;
@@ -7501,11 +7774,13 @@ exports.URL_MODELS_DISPATCH_MODEL_TYPE = URL_MODELS_DISPATCH_MODEL_TYPE;
 exports.URL_MODELS_TOOL_NAME = URL_MODELS_TOOL_NAME;
 exports.abbreviateMcpCallType = abbreviateMcpCallType;
 exports.appMcpAnalyticsModuleMetadata = appMcpAnalyticsModuleMetadata;
+exports.applyMcpReasonParameterToSchema = applyMcpReasonParameterToSchema;
 exports.applyWriteMarker = applyWriteMarker;
 exports.batchOperationCoordKey = batchOperationCoordKey;
 exports.buildDefaultMcpToolDescription = buildDefaultMcpToolDescription;
 exports.buildDisambiguatedMcpToolName = buildDisambiguatedMcpToolName;
 exports.buildMcpToolName = buildMcpToolName;
+exports.buildStaticToolDefinition = buildStaticToolDefinition;
 exports.buildStaticWireEntry = buildStaticWireEntry;
 exports.classifyVisibility = classifyVisibility;
 exports.createBatchExecuteTool = createBatchExecuteTool;
@@ -7515,6 +7790,7 @@ exports.createModelGetTool = createModelGetTool;
 exports.createModelInfoTool = createModelInfoTool;
 exports.createUrlModelsTool = createUrlModelsTool;
 exports.decodeFirestoreModelKey = decodeFirestoreModelKey;
+exports.extractMcpReasonFromArgs = extractMcpReasonFromArgs;
 exports.findModelEntry = findModelEntry;
 exports.formatMcpToolErrorResponse = formatMcpToolErrorResponse;
 exports.formatMcpToolResponse = formatMcpToolResponse;
@@ -7523,10 +7799,12 @@ exports.handleStreamableHttpMcpRequest = handleStreamableHttpMcpRequest;
 exports.matchRouteManifestUrl = matchRouteManifestUrl;
 exports.mcpManifestKey = mcpManifestKey;
 exports.mcpModuleMetadata = mcpModuleMetadata;
+exports.mcpSchemaDeclaresProperty = mcpSchemaDeclaresProperty;
 exports.noopMcpAnalyticsService = noopMcpAnalyticsService;
 exports.parseUrlModelsPathname = parseUrlModelsPathname;
 exports.resolveEffectiveReadOnly = resolveEffectiveReadOnly;
 exports.resolveEnumInfoOutput = resolveEnumInfoOutput;
+exports.resolveMcpReasonParameterConfig = resolveMcpReasonParameterConfig;
 exports.resolveMcpToolAnnotations = resolveMcpToolAnnotations;
 exports.resolveRequiredScope = resolveRequiredScope;
 exports.validateMcpToolName = validateMcpToolName;