@dereekb/firebase-server 13.16.0 → 13.18.0

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.16.0",
+  "version": "13.18.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.16.0",
-    "@dereekb/date": "13.16.0",
-    "@dereekb/firebase": "13.16.0",
-    "@dereekb/firebase-server": "13.16.0",
-    "@dereekb/firebase-server/oidc": "13.16.0",
-    "@dereekb/model": "13.16.0",
-    "@dereekb/nestjs": "13.16.0",
-    "@dereekb/rxjs": "13.16.0",
-    "@dereekb/util": "13.16.0",
-    "@dereekb/zoho": "13.16.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.
  *
@@ -80,6 +140,17 @@ export declare abstract class McpModuleConfig {
      * schemas, no output schemas) and emits a single boot warning.
      */
     readonly mcpManifestPath?: string;
+    /**
+     * 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
+     * boot and registers the built-in `url-models` tool, which decodes an app URL
+     * into the Firestore models its page renders.
+     *
+     * 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.
+     */
+    readonly mcpRouteManifestPath?: string;
     /**
      * When `true`, the MCP server only advertises tools whose effective read-only classification is `true`.
      *
@@ -91,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,7 @@
 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';
 export * from './mcp.tool-generator';
@@ -7,4 +9,6 @@ export * from './mcp.visibility';
 export * from './tools/mcp.tool.model-get';
 export * from './tools/mcp.tool.model-info';
 export * from './tools/mcp.tool.model-decode';
+export * from './tools/mcp.tool.enum-info';
+export * from './tools/mcp.tool.url-models';
 export * from './tools/mcp.tool.batch-execute';

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

@@ -82,6 +82,28 @@ export interface McpManifestModelEntry {
         readonly sourceFile: string;
     };
 }
+/**
+ * One enum value with its persisted literal and the leading JSDoc paragraph.
+ *
+ * Structural mirror of `@dereekb/dbx-cli`'s `CliModelEnumValue`. Lets the
+ * runtime `model-info` / `enum-info` tools decode raw persisted integer/string
+ * values (`s: 4`) back to human-readable names without dropping into source.
+ */
+export interface McpManifestEnumValue {
+    readonly name: string;
+    readonly value: number | string;
+    readonly description?: string;
+}
+/**
+ * One TypeScript enum referenced by some model field's `enumRef`.
+ *
+ * Structural mirror of `@dereekb/dbx-cli`'s `CliModelEnum`.
+ */
+export interface McpManifestEnum {
+    readonly name: string;
+    readonly values: readonly McpManifestEnumValue[];
+    readonly description?: string;
+}
 /**
  * One auth claim entry in the pre-rendered MCP manifest JSON.
  *
@@ -138,6 +160,10 @@ export interface McpManifestAuth {
  * manifests rendered before model catalog support landed), the runtime skips
  * registering those tools instead of failing the boot.
  *
+ * The optional `enums` map (keyed by enum name) carries the value→label tables
+ * `model-info` inlines and the `enum-info` static tool serves. Absent on legacy
+ * manifests; the runtime then skips registering `enum-info`.
+ *
  * The optional `auth` section drives the built-in `whoami` static tool.
  */
 export interface McpManifest {
@@ -147,6 +173,9 @@ export interface McpManifest {
         readonly [key: string]: McpManifestToolEntry | undefined;
     };
     readonly models?: readonly McpManifestModelEntry[];
+    readonly enums?: {
+        readonly [name: string]: McpManifestEnum;
+    };
     readonly auth?: McpManifestAuth;
 }
 /**

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.route-manifest.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Runtime mirror of the build-time route manifest schema + a ported URL matcher.
+ *
+ * Structural mirror of `@dereekb/dbx-cli`'s `route-manifest.ts` types and the
+ * pure `url-match.ts` matcher, so the firebase-server/mcp runtime can consume
+ * the generated `route.manifest.json` without taking a runtime dependency on
+ * the build-time CLI package. Both sides bump {@link ROUTE_MANIFEST_VERSION}
+ * together when the manifest shape changes.
+ */
+/**
+ * Version stamp embedded in `route.manifest.json`. Runtime loaders refuse
+ * manifests whose `version` does not match. Mirror in `@dereekb/dbx-cli`'s
+ * `ROUTE_MANIFEST_VERSION` — bump both together.
+ */
+export declare const ROUTE_MANIFEST_VERSION: 1;
+/**
+ * Whether a route-model entry resolves to a promoted id, a full key, or a
+ * keyless list. Mirror of `@dereekb/dbx-cli`'s `RouteModelKind`.
+ */
+export type RouteModelKind = 'id' | 'key' | 'list';
+/**
+ * One model an app page renders. Structural mirror of `@dereekb/dbx-cli`'s
+ * `RouteManifestModelEntry`.
+ */
+export interface RouteManifestModelEntry {
+    readonly modelType: string;
+    readonly kind: RouteModelKind;
+    readonly keyTemplate?: string;
+    readonly description?: string;
+    readonly from?: string;
+}
+/**
+ * One UIRouter state, inheritance pre-flattened into `models`. Structural mirror
+ * of `@dereekb/dbx-cli`'s `RouteManifestStateEntry`.
+ */
+export interface RouteManifestStateEntry {
+    readonly name: string;
+    readonly url?: string;
+    readonly fullUrl?: string;
+    readonly parentName?: string;
+    readonly paramKeys: readonly string[];
+    readonly urlParamKeys: readonly string[];
+    readonly component?: string;
+    readonly componentFile?: string;
+    readonly abstract?: boolean;
+    readonly redirectTo?: string;
+    readonly models: readonly RouteManifestModelEntry[];
+}
+/**
+ * The full `route.manifest.json` shape. Structural mirror of `@dereekb/dbx-cli`'s
+ * `RouteManifest`.
+ */
+export interface RouteManifest {
+    readonly version: typeof ROUTE_MANIFEST_VERSION;
+    readonly generatedAt: string;
+    readonly app: {
+        readonly name: string;
+        readonly baseUrl?: string;
+    };
+    readonly states: readonly RouteManifestStateEntry[];
+}
+/**
+ * A single resolved state match. `via` distinguishes a literal path match from
+ * a parameterised one; `params` carries the captured `:param` / `{param}`
+ * values (empty for literal matches).
+ */
+export interface RouteUrlMatch {
+    readonly kind: 'match';
+    readonly via: 'literal' | 'param';
+    readonly state: RouteManifestStateEntry;
+    readonly params: Readonly<Record<string, string>>;
+    readonly pathname: string;
+}
+/**
+ * More than one state matched at the same tier.
+ */
+export interface RouteUrlAmbiguous {
+    readonly kind: 'ambiguous';
+    readonly states: readonly RouteManifestStateEntry[];
+    readonly pathname: string;
+}
+/**
+ * No state matched; `candidates` holds the closest scored near-misses (top 5).
+ */
+export interface RouteUrlNone {
+    readonly kind: 'none';
+    readonly candidates: readonly RouteManifestStateEntry[];
+    readonly pathname: string;
+}
+export type RouteUrlMatchResult = RouteUrlMatch | RouteUrlAmbiguous | RouteUrlNone;
+/**
+ * Input to {@link matchRouteManifestUrl}.
+ */
+export interface MatchRouteManifestUrlInput {
+    readonly manifest: RouteManifest;
+    readonly url: string;
+}
+/**
+ * Extracts the normalized pathname from a full URL or a bare path. Strips the
+ * scheme/host/port, query string, and hash; collapses an empty path to `/` and
+ * trims a single trailing slash.
+ *
+ * @param url - A full URL (`https://app.example.co/worker/x/timesheets/list`) or bare path.
+ * @returns The normalized pathname.
+ *
+ * @example
+ * ```ts
+ * parseUrlModelsPathname('https://app.hellosubs.co/worker/abc/timesheets/list/'); // => '/worker/abc/timesheets/list'
+ * ```
+ */
+export declare function parseUrlModelsPathname(url: string): string;
+/**
+ * Matches a URL against the manifest's states, preferring a literal match over
+ * a parameterised one. A tie at either tier collapses to `ambiguous`; otherwise
+ * the closest near-misses are scored and returned in a `none` result.
+ *
+ * @param input - The manifest and the URL (or pathname) to resolve.
+ * @returns A discriminated match / ambiguous / none result.
+ */
+export declare function matchRouteManifestUrl(input: MatchRouteManifestUrlInput): RouteUrlMatchResult;

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

@@ -32,10 +32,14 @@ export declare class McpServerFactoryService {
     private _cachedStaticTools;
     private _cachedManifest;
     private _cachedManifestModels;
+    private _cachedManifestEnums;
     private _cachedManifestAuth;
+    private _cachedRouteManifest;
+    private _routeManifestLoaded;
     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);
     /**
@@ -129,6 +133,17 @@ export declare class McpServerFactoryService {
      */
     private _resolveManifest;
     private _resetManifestCache;
+    /**
+     * Reads the pre-rendered route manifest JSON once, validates its version, and caches the result
+     * for the process lifetime. Drives whether the built-in `url-models` static tool is registered.
+     *
+     * Missing file or wrong version fall back to "no route manifest" with a single boot warning;
+     * the `url-models` tool is then simply not offered.
+     *
+     * @returns The cached route manifest, or `undefined` when none was loaded.
+     */
+    private _resolveRouteManifest;
+    private _parseRouteManifestFile;
     private _parseManifestFile;
     private _applyParsedManifest;
     /**
@@ -155,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,8 +1,8 @@
 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 } from '@modelcontextprotocol/sdk/types.js';
+import { type CallToolResult, type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { type McpManifestToolEntry } from './mcp.manifest';
 import { type McpToolFilterMetadata } from './mcp.visibility';
 /**
@@ -17,6 +17,12 @@ export interface McpToolListEntry {
     readonly description: string;
     readonly inputSchema: object;
     readonly outputSchema?: object;
+    /**
+     * Standard MCP read/write hints (`readOnlyHint`, `destructiveHint`) advertised to clients so a
+     * tool's mutating behaviour is machine-readable. Resolved at boot from the effective read-only
+     * classification; see {@link resolveMcpToolAnnotations}.
+     */
+    readonly annotations?: ToolAnnotations;
 }
 /**
  * A single MCP tool definition generated from one (modelType, callType, specifier) triple.
@@ -54,6 +60,12 @@ export interface McpToolDefinition {
      * response only includes this when the pinned MCP SDK type allows it.
      */
     readonly outputSchema?: object;
+    /**
+     * Standard MCP read/write hints for this tool, mirrored onto {@link staticWireEntry} and the
+     * dynamic wire path so opt-in `toolDetails` handlers keep their annotations. Resolved at boot
+     * from the effective read-only classification; see {@link resolveMcpToolAnnotations}.
+     */
+    readonly annotations?: ToolAnnotations;
     /**
      * The original handler-level API details. Carries response formatters, analytics
      * config, etc. — the controller resolves Tier 1/2/3 response shape from this.
@@ -224,6 +236,7 @@ interface BuildStaticWireEntryInput {
     readonly description: string;
     readonly inputSchema?: object;
     readonly outputSchema?: object;
+    readonly annotations?: ToolAnnotations;
 }
 /**
  * Builds the frozen wire-shape entry used by the per-request `tools/list` hot path.
@@ -235,6 +248,56 @@ interface BuildStaticWireEntryInput {
  * @returns A frozen wire entry safe to share across requests.
  */
 export declare function buildStaticWireEntry(input: BuildStaticWireEntryInput): McpToolListEntry;
+/**
+ * Description prefix prepended to a mutating tool's description so MCP clients that don't render
+ * {@link ToolAnnotations} still surface the write signal in plain text.
+ */
+export declare const MCP_WRITE_TOOL_DESCRIPTION_PREFIX = "[WRITE] ";
+/**
+ * Prepends {@link MCP_WRITE_TOOL_DESCRIPTION_PREFIX} to a description when its annotations mark the
+ * tool as a write (`readOnlyHint === false`). Read-only tools are returned unchanged.
+ *
+ * @param description - The base tool description.
+ * @param annotations - The resolved MCP annotations for the tool.
+ * @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/mcp/src/lib/service/mcp.visibility.d.ts

@@ -1,6 +1,7 @@
 import { type Maybe } from '@dereekb/util';
 import { type CallModelOidcScope } from '@dereekb/firebase';
 import { type McpToolVisibility, type McpVisibilityContext, type McpVisibilityRule } from '@dereekb/firebase-server';
+import { type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 /**
  * Normalized classification of a {@link McpToolVisibility} value computed at boot.
  *
@@ -87,6 +88,22 @@ export declare function classifyVisibility(visibility?: McpToolVisibility): Clas
  * @returns The effective read-only flag, or `undefined` when neither source resolves a value.
  */
 export declare function resolveEffectiveReadOnly(explicitReadOnly: Maybe<boolean>, callType: string): boolean | undefined;
+/**
+ * Maps an effective read-only classification to the standard MCP {@link ToolAnnotations} hints
+ * advertised on `tools/list`.
+ *
+ * A definitively read-only tool advertises `{ readOnlyHint: true }`. Everything else — a known
+ * write (`false`) or an unclassified verb (`undefined`, e.g. `invoke`/custom) — fails safe to
+ * `{ readOnlyHint: false, destructiveHint: true }` so a client never mistakes an ambiguous tool
+ * for a safe read. `idempotentHint` / `openWorldHint` are intentionally left unset.
+ *
+ * Co-located with {@link resolveEffectiveReadOnly} / {@link READ_ONLY_BY_CALL_TYPE} so the
+ * read/write classification rules stay in one file.
+ *
+ * @param effectiveReadOnly - The resolved read-only classification from {@link resolveEffectiveReadOnly}.
+ * @returns The MCP annotations describing the tool's read/write behaviour.
+ */
+export declare function resolveMcpToolAnnotations(effectiveReadOnly: boolean | undefined): ToolAnnotations;
 /**
  * Resolves the OIDC scope required to invoke a given call type, or `undefined` for
  * non-CRUD calls. Thin re-export so the tool generator doesn't need to reach into