@dereekb/firebase-server 13.17.0 → 13.18.0

package/mcp/package.json

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

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

@@ -19,6 +19,66 @@ export declare const DEFAULT_MCP_SERVER_NAME = "dbx-firebase-server-mcp";
  * handshake. Apps may override this via {@link McpModuleConfig.serverInstructions}.
  */
 export declare const 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}.
+ */
+export declare const 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}.
+ */
+export declare const DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH = 250;
+/**
+ * Default required-ness of the auto-injected reason parameter. See
+ * {@link McpReasonParameterConfig.required}.
+ */
+export declare const 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}.
+ */
+export declare const DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION = "A brief human-readable reason (\u2264250 chars) explaining why this tool is being called. Recorded for analytics/audit only; not part of the operation.";
+/**
+ * Configuration for the auto-injected `reason` parameter the MCP server adds to every advertised
+ * tool's input schema.
+ *
+ * When enabled (the default), the server augments each tool's `inputSchema` with a `reason` string
+ * property — a short human-readable justification for the call, surfaced to the model and recorded on
+ * the per-call analytics event. The field is stripped from the JSON body before the args are
+ * dispatched to the underlying handler, so call-model handlers never receive it.
+ *
+ * Supplied to {@link McpModuleConfig.reasonParameter} as a full object (to tune individual fields), or
+ * as a boolean shorthand (`true` = defaults on, `false` = disabled).
+ */
+export interface McpReasonParameterConfig {
+    /**
+     * Whether the reason parameter is injected at all. Defaults to `true`. Set `false` to disable
+     * (equivalent to `reasonParameter: false`).
+     */
+    readonly enabled?: boolean;
+    /**
+     * Whether the parameter is marked `required` in the advertised input schema. Defaults to
+     * {@link DEFAULT_MCP_REASON_PARAMETER_REQUIRED}.
+     */
+    readonly required?: boolean;
+    /**
+     * Maximum character length advertised (`maxLength`) and enforced server-side (the forwarded value is
+     * clamped). Defaults to {@link DEFAULT_MCP_REASON_PARAMETER_MAX_LENGTH}.
+     */
+    readonly maxLength?: number;
+    /**
+     * Description advertised for the parameter on each tool's input schema. Defaults to
+     * {@link DEFAULT_MCP_REASON_PARAMETER_DESCRIPTION}.
+     */
+    readonly description?: string;
+    /**
+     * Name of the injected parameter. Defaults to {@link DEFAULT_MCP_REASON_PARAMETER_NAME} (`'reason'`).
+     * Rename to avoid colliding with a handler that legitimately consumes a `reason` input field.
+     */
+    readonly parameterName?: string;
+}
 /**
  * Configuration for the firebase-server/mcp module.
  *
@@ -102,6 +162,17 @@ export declare abstract class McpModuleConfig {
      * ` (read-only)` so the client surface reflects the mode.
      */
     readonly readOnly?: boolean;
+    /**
+     * 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}.
+     */
+    readonly reasonParameter?: McpReasonParameterConfig | boolean;
 }
 /**
  * Signature for the optional role reader the MCP module uses when evaluating

package/mcp/src/lib/service/analytics/mcp.analytics.handler.d.ts

@@ -58,9 +58,16 @@ export interface McpAnalyticsEvent {
      */
     readonly readOnly?: Maybe<boolean>;
     /**
-     * The raw tool arguments passed to the call.
+     * The raw tool arguments passed to the call, with the auto-injected reason parameter already
+     * stripped (so it never appears twice — once here and once on {@link reason}).
      */
     readonly args?: Maybe<Record<string, unknown>>;
+    /**
+     * The auto-injected, human-readable reason the caller supplied for this tool call, clamped to the
+     * configured max length. `undefined` when the reason parameter is disabled, absent, or the tool
+     * declares its own field of the same name. Recorded for analytics/audit only.
+     */
+    readonly reason?: Maybe<string>;
     /**
      * Custom key-value properties. Reserved for future use.
      */

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

@@ -1,5 +1,6 @@
 export * from './analytics';
 export * from './mcp.manifest';
+export * from './mcp.reason';
 export * from './mcp.route-manifest';
 export * from './mcp.response-formatter';
 export * from './mcp.server.factory';

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

@@ -0,0 +1,80 @@
+import { type Maybe } from '@dereekb/util';
+import { type McpReasonParameterConfig } from '../mcp.config';
+/**
+ * The fully-normalized form of {@link McpReasonParameterConfig}, with every field resolved to a
+ * concrete value via {@link resolveMcpReasonParameterConfig}.
+ */
+export interface ResolvedMcpReasonParameterConfig {
+    readonly enabled: boolean;
+    readonly required: boolean;
+    readonly maxLength: number;
+    readonly description: string;
+    readonly parameterName: string;
+}
+/**
+ * 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.
+ */
+export declare function resolveMcpReasonParameterConfig(config?: McpReasonParameterConfig | boolean): ResolvedMcpReasonParameterConfig;
+/**
+ * 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`.
+ */
+export declare function mcpSchemaDeclaresProperty(schema: object | undefined, name: string): boolean;
+/**
+ * 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.
+ */
+export declare function applyMcpReasonParameterToSchema(inputSchema: object, resolved: ResolvedMcpReasonParameterConfig): object;
+/**
+ * The result of extracting the reason value from a tool call's raw arguments.
+ */
+export interface ExtractedMcpReason {
+    /**
+     * The extracted, clamped reason string, or `undefined` when absent / disabled / handler-owned.
+     */
+    readonly reason: Maybe<string>;
+    /**
+     * The arguments to forward to the underlying handler — with the reason key removed when this module
+     * owns it, or the original args untouched otherwise.
+     */
+    readonly args: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+export declare function extractMcpReasonFromArgs(args: Record<string, unknown>, resolved: ResolvedMcpReasonParameterConfig, toolDeclaresOwnReason: boolean): ExtractedMcpReason;

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

@@ -39,6 +39,7 @@ export declare class McpServerFactoryService {
     private _manifestLoaded;
     private _loggedSkips;
     private _warnedMissingRoleReader;
+    private _resolvedReasonConfig?;
     private readonly _analyticsService;
     constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined, analyticsService?: McpAnalyticsService, storageService?: FirebaseServerStorageService | undefined);
     /**
@@ -169,12 +170,24 @@ export declare class McpServerFactoryService {
     private _filterToolsForRequest;
     private _passesVisibility;
     private _checkDeclarativeVisibility;
+    /**
+     * 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).
+     */
+    private _resolveReasonConfig;
     /**
      * 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

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

@@ -1,6 +1,6 @@
 import { type Maybe } from '@dereekb/util';
 import { type KnownOnCallFunctionType } from '@dereekb/firebase';
-import { type ModelApiDetailsResult, type OnCallModelFunctionApiDetails, type FirebaseServerAuthData, type McpToolDetailsBuilder } from '@dereekb/firebase-server';
+import { type ModelApiDetailsResult, type OnCallModelFunctionApiDetails, type FirebaseServerAuthData, type McpToolDetailsBuilder, type McpVisibilityRule } from '@dereekb/firebase-server';
 import { type Request } from 'express';
 import { type CallToolResult, type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { type McpManifestToolEntry } from './mcp.manifest';
@@ -262,6 +262,42 @@ export declare const MCP_WRITE_TOOL_DESCRIPTION_PREFIX = "[WRITE] ";
  * @returns The description, prefixed with the write marker when the tool mutates.
  */
 export declare function applyWriteMarker(description: string, annotations: ToolAnnotations): string;
+/**
+ * Input for {@link buildStaticToolDefinition}.
+ */
+export interface BuildStaticToolDefinitionInput {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: object;
+    readonly outputSchema?: object;
+    readonly dispatch: McpToolDispatchTarget;
+    readonly staticHandler: McpStaticToolHandler;
+    /**
+     * Read-only classification for this built-in tool. Drives both the advertised MCP annotations
+     * (`readOnlyHint` / `destructiveHint`) and the per-request module-level `readOnly` filter.
+     */
+    readonly effectiveReadOnly: boolean;
+    /**
+     * Declarative visibility rule checked per request. Defaults to `{}` (always visible) when omitted.
+     */
+    readonly rule?: McpVisibilityRule;
+}
+/**
+ * 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.
+ */
+export declare function buildStaticToolDefinition(input: BuildStaticToolDefinitionInput): McpToolDefinition;
 /**
  * The default specifier key used when a handler is not behind a specifier router.
  */

package/model/package.json

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

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.17.0",
+  "version": "13.18.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.17.0",
-    "@dereekb/date": "13.17.0",
-    "@dereekb/firebase": "13.17.0",
-    "@dereekb/firebase-server": "13.17.0",
-    "@dereekb/model": "13.17.0",
-    "@dereekb/nestjs": "13.17.0",
-    "@dereekb/rxjs": "13.17.0",
-    "@dereekb/util": "13.17.0",
-    "@dereekb/zoho": "13.17.0",
+    "@dereekb/analytics": "13.18.0",
+    "@dereekb/date": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/firebase-server": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/util": "13.18.0",
+    "@dereekb/zoho": "13.18.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.17.0",
+  "version": "13.18.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -57,15 +57,15 @@
   "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.17.0",
-    "@dereekb/date": "13.17.0",
-    "@dereekb/dbx-core": "13.17.0",
-    "@dereekb/firebase": "13.17.0",
-    "@dereekb/model": "13.17.0",
-    "@dereekb/nestjs": "13.17.0",
-    "@dereekb/rxjs": "13.17.0",
-    "@dereekb/util": "13.17.0",
-    "@dereekb/zoho": "13.17.0",
+    "@dereekb/analytics": "13.18.0",
+    "@dereekb/date": "13.18.0",
+    "@dereekb/dbx-core": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/util": "13.18.0",
+    "@dereekb/zoho": "13.18.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/sdk": "1.29.0",

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.17.0",
+  "version": "13.18.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.17.0",
-    "@dereekb/date": "13.17.0",
-    "@dereekb/firebase": "13.17.0",
-    "@dereekb/firebase-server": "13.17.0",
-    "@dereekb/firebase-server/oidc": "13.17.0",
-    "@dereekb/model": "13.17.0",
-    "@dereekb/nestjs": "13.17.0",
-    "@dereekb/rxjs": "13.17.0",
-    "@dereekb/util": "13.17.0",
+    "@dereekb/analytics": "13.18.0",
+    "@dereekb/date": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/firebase-server": "13.18.0",
+    "@dereekb/firebase-server/oidc": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/util": "13.18.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -23,7 +23,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.17.0"
+    "@dereekb/nestjs": "13.18.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.17.0",
+  "version": "13.18.0",
   "peerDependencies": {
-    "@dereekb/date": "13.17.0",
-    "@dereekb/firebase": "13.17.0",
-    "@dereekb/firebase-server": "13.17.0",
-    "@dereekb/model": "13.17.0",
-    "@dereekb/nestjs": "13.17.0",
-    "@dereekb/rxjs": "13.17.0",
-    "@dereekb/util": "13.17.0"
+    "@dereekb/date": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/firebase-server": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/util": "13.18.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.17.0",
+  "version": "13.18.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.17.0",
-    "@dereekb/date": "13.17.0",
-    "@dereekb/model": "13.17.0",
-    "@dereekb/nestjs": "13.17.0",
-    "@dereekb/rxjs": "13.17.0",
-    "@dereekb/firebase": "13.17.0",
-    "@dereekb/util": "13.17.0",
-    "@dereekb/zoho": "13.17.0"
+    "@dereekb/analytics": "13.18.0",
+    "@dereekb/date": "13.18.0",
+    "@dereekb/model": "13.18.0",
+    "@dereekb/nestjs": "13.18.0",
+    "@dereekb/rxjs": "13.18.0",
+    "@dereekb/firebase": "13.18.0",
+    "@dereekb/util": "13.18.0",
+    "@dereekb/zoho": "13.18.0"
   },
   "exports": {
     "./package.json": "./package.json",