@dereekb/firebase-server 13.11.18 → 13.12.0

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

@@ -0,0 +1,235 @@
+import { type Maybe } from '@dereekb/util';
+import { type ModelApiDetailsResult, type OnCallModelFunctionApiDetails, type FirebaseServerAuthData, type McpToolDetailsBuilder } from '@dereekb/firebase-server';
+import { type Request } from 'express';
+import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type McpManifestToolEntry } from './mcp.manifest';
+import { type McpToolFilterMetadata } from './mcp.visibility';
+/**
+ * Frozen wire-shape entry returned on `tools/list`.
+ *
+ * Built once at boot per tool and reused for every request when no
+ * {@link McpToolDefinition.toolDetailsBuilder} is configured. Tools that opt in
+ * to dynamic details produce a fresh wire entry per request.
+ */
+export interface McpToolListEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: object;
+    readonly outputSchema?: object;
+}
+/**
+ * A single MCP tool definition generated from one (modelType, callType, specifier) triple.
+ */
+export interface McpToolDefinition {
+    /**
+     * Tool name advertised on `tools/list`.
+     *
+     * Format: `<modelType>-<callType>` for default (`_`) specifiers,
+     * `<modelType>-<callType>-<specifier>` for non-default specifiers.
+     *
+     * @example 'guestbook-create'
+     * @example 'profile-update-username'
+     * @example 'storageFile-invoke-recomputeChecksums'
+     */
+    readonly name: string;
+    /**
+     * Human-readable description surfaced to MCP clients.
+     *
+     * Resolved from the build-time MCP manifest entry when present; otherwise auto-generated.
+     */
+    readonly description: string;
+    /**
+     * JSON Schema for the tool input.
+     *
+     * Resolved in order: manifest entry's `inputSchema` (when a manifest is supplied) > handler's
+     * `inputType.toJsonSchema()` > `undefined`. `undefined` means the tool is skipped during
+     * registration; the gap is logged so it's visible.
+     */
+    readonly inputSchema?: object;
+    /**
+     * JSON Schema for the tool output, when the manifest provides one. The wire `tools/list`
+     * response only includes this when the pinned MCP SDK type allows it.
+     */
+    readonly outputSchema?: object;
+    /**
+     * The original handler-level API details. Carries response formatters, analytics
+     * config, etc. — the controller resolves Tier 1/2/3 response shape from this.
+     *
+     * `undefined` for statically-registered tools that don't go through the callModel chain.
+     */
+    readonly details?: OnCallModelFunctionApiDetails;
+    /**
+     * The dispatch coordinates extracted from the position in the call model tree.
+     * The controller uses these to build the `OnCallTypedModelParams` envelope at call time.
+     *
+     * For statically-registered tools the coordinates are synthetic (they identify the tool to
+     * dynamic visibility predicates) but {@link staticHandler} runs instead of the callModel chain.
+     */
+    readonly dispatch: McpToolDispatchTarget;
+    /**
+     * When present, the per-request controller calls this handler directly instead of going
+     * through the callModel dispatch chain. Used for built-in MCP tools (e.g. `model-get`) that
+     * read from the Firebase model surface without a corresponding `callModel` handler.
+     */
+    readonly staticHandler?: McpStaticToolHandler;
+    /**
+     * Precomputed boot-time filter metadata consumed by the per-request `tools/list` filter.
+     */
+    readonly filterMetadata: McpToolFilterMetadata;
+    /**
+     * The frozen `tools/list` wire entry for this tool, computed once at boot from the
+     * static description / inputSchema / outputSchema. The factory returns this verbatim
+     * when {@link toolDetailsBuilder} is `undefined`, avoiding a per-request allocation.
+     */
+    readonly staticWireEntry: McpToolListEntry;
+    /**
+     * The handler's per-request builder, hoisted from `details.mcp.toolDetails` once at
+     * boot so the request hot path doesn't dereference through the details tree.
+     *
+     * `undefined` for tools that did not opt in (the common case) and for statically
+     * registered tools.
+     */
+    readonly toolDetailsBuilder?: McpToolDetailsBuilder;
+}
+/**
+ * Per-request handler for a statically-registered MCP tool.
+ *
+ * Receives the raw tool arguments and the MCP request context (auth + raw request); returns the
+ * MCP `CallToolResult` envelope verbatim. The factory wraps the call in a try/catch so handlers
+ * may surface user-visible errors by throwing.
+ */
+export type McpStaticToolHandler = (args: Record<string, unknown>, ctx: McpStaticToolHandlerContext) => Promise<CallToolResult>;
+/**
+ * Request-scoped context passed to {@link McpStaticToolHandler} implementations.
+ *
+ * Identical in shape to `McpRequestContext` but redeclared here so the tool generator does not
+ * depend on the server factory module (the dependency goes the other way).
+ */
+export interface McpStaticToolHandlerContext {
+    readonly auth?: FirebaseServerAuthData;
+    readonly rawRequest: Request;
+}
+/**
+ * The (call, modelType, specifier) coordinate that resolves a generated MCP tool
+ * back to a single dispatch target on the underlying callModel chain.
+ */
+export interface McpToolDispatchTarget {
+    readonly call: string;
+    readonly modelType: string;
+    /**
+     * `undefined` when the handler isn't behind a specifier (default `_` entry on a
+     * non-specifier model type).
+     */
+    readonly specifier?: string;
+}
+/**
+ * Options forwarded to {@link JsonSchemaRef.toJsonSchema}.
+ *
+ * Wraps the ArkType-specific fallback handlers so consumers can opt out of the
+ * default predicate / `undefinedAsClearable` behavior if their schema lib needs
+ * different options.
+ */
+export interface JsonSchemaGenerationOptions {
+    readonly [option: string]: unknown;
+}
+/**
+ * Default `toJsonSchema()` options.
+ *
+ * ArkType throws on predicate definitions and on `undefined` fields by default;
+ * these fallback handlers downgrade those errors so a partial schema is emitted
+ * for tools that mostly fit JSON Schema. The `unit` fallback covers `clearable(t)`
+ * from `@dereekb/model` (which expands to `t | undefined` and surfaces as an ArkType
+ * `unit: undefined` schema node).
+ */
+export declare const DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS: JsonSchemaGenerationOptions;
+/**
+ * Reason a tool was skipped during generation.
+ */
+export type McpToolGenerationSkipReason = 'missing_input_type' | 'schema_generation_failed';
+/**
+ * One tool that was skipped during generation.
+ */
+export interface McpToolGenerationSkip {
+    readonly toolName: string;
+    readonly reason: McpToolGenerationSkipReason;
+    readonly dispatch: McpToolDispatchTarget;
+    readonly error?: Error;
+}
+/**
+ * Aggregated output of {@link generateMcpToolDefinitions}.
+ */
+export interface McpToolGenerationResult {
+    /**
+     * Tools that may be visible on `tools/list`, subject to the per-request filter.
+     * Excludes anything classified as `'never'` visible at boot.
+     */
+    readonly tools: ReadonlyArray<McpToolDefinition>;
+    /**
+     * Tools whose `visibility` was classified as `'never'` at boot.
+     * Partitioned out so the per-request loop never touches them.
+     */
+    readonly neverVisibleTools: ReadonlyArray<McpToolDefinition>;
+    /**
+     * Tools that could not be generated (no inputType, or `toJsonSchema()` threw).
+     * Surfaced so the caller can log them at startup.
+     */
+    readonly skipped: ReadonlyArray<McpToolGenerationSkip>;
+}
+interface BuildStaticWireEntryInput {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema?: object;
+    readonly outputSchema?: object;
+}
+/**
+ * Builds the frozen wire-shape entry used by the per-request `tools/list` hot path.
+ *
+ * Tools without an `inputSchema` default to `{ type: 'object' }` to match the runtime
+ * behaviour the factory used before the precompute optimisation existed.
+ *
+ * @param input - The tool name, description, and optional input/output schemas used to assemble the wire entry.
+ * @returns A frozen wire entry safe to share across requests.
+ */
+export declare function buildStaticWireEntry(input: BuildStaticWireEntryInput): McpToolListEntry;
+/**
+ * The default specifier key used when a handler is not behind a specifier router.
+ */
+export declare const DEFAULT_SPECIFIER_KEY = "_";
+/**
+ * Builds the MCP tool name for a (modelType, callType, specifier) triple.
+ *
+ * Apps can override the auto-generated name by setting
+ * {@link OnCallModelFunctionApiDetails.mcp.name} on the handler.
+ *
+ * @param modelType - The Firestore model type (e.g., `storageFile`).
+ * @param callType - The call type (e.g., `invoke`).
+ * @param specifier - The specifier key, or `_` / undefined for the default entry.
+ * @returns The hyphen-joined tool name advertised on `tools/list`.
+ */
+export declare function buildMcpToolName(modelType: string, callType: string, specifier?: Maybe<string>): string;
+/**
+ * Builds the default description used when no build-time MCP manifest
+ * entry is available for the (modelType, callType, specifier) tuple.
+ *
+ * @param modelType - The Firestore model type segment used in the generated description.
+ * @param callType - The call type segment used in the generated description.
+ * @param specifier - The specifier segment, or `_` / undefined for the default entry.
+ * @returns A human-readable fallback description for the tool.
+ */
+export declare function buildDefaultMcpToolDescription(modelType: string, callType: string, specifier?: Maybe<string>): string;
+/**
+ * Generates MCP tool definitions from a model-first API details tree.
+ *
+ * Walks each (modelType, callType, specifier) triple in the tree, calls
+ * `inputType.toJsonSchema(options)` for the schema, and applies any handler-level
+ * MCP `name` override. Descriptions and input/output schemas are pulled from the
+ * build-time manifest when supplied. Tools without an `inputType` are skipped and
+ * reported so callers can log the gap at startup.
+ *
+ * @param apiDetails - The model-first API details tree returned by `getModelApiDetails(callModelFn)`.
+ * @param options - Optional schema generation options forwarded to `toJsonSchema()`. Defaults to {@link DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS}.
+ * @param manifest - Optional build-time manifest map; supplies overrides for descriptions and input/output schemas keyed by {@link mcpManifestKey}.
+ * @returns The list of generated tool definitions plus any skip reports.
+ */
+export declare function generateMcpToolDefinitions(apiDetails: ModelApiDetailsResult, options?: JsonSchemaGenerationOptions, manifest?: ReadonlyMap<string, McpManifestToolEntry>): McpToolGenerationResult;
+export {};

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

@@ -0,0 +1,99 @@
+import { type Maybe } from '@dereekb/util';
+import { type CallModelOidcScope } from '@dereekb/firebase';
+import { type McpToolVisibility, type McpVisibilityContext, type McpVisibilityRule } from '@dereekb/firebase-server';
+/**
+ * Normalized classification of a {@link McpToolVisibility} value computed at boot.
+ *
+ * `'always'` keeps the tool (subject to scope/readOnly filters).
+ * `'never'` drops the tool from `tools/list` entirely — partitioned at boot so the per-request loop skips it.
+ * `'declarative'` carries a {@link McpVisibilityRule} checked per request without invoking user code.
+ * `'dynamic'` carries the original predicate; invoked per request inside try/catch.
+ */
+export type McpToolVisibilityKind = 'always' | 'never' | 'declarative' | 'dynamic';
+/**
+ * Boot-time classification result for one tool's `visibility` field.
+ *
+ * Discriminated by {@link McpToolVisibilityKind} so consumers can narrow `rule` /
+ * `visibilityFn` presence without optional-chain assertions.
+ */
+export type ClassifiedMcpToolVisibility = ClassifiedMcpToolVisibilityAlways | ClassifiedMcpToolVisibilityNever | ClassifiedMcpToolVisibilityDeclarative | ClassifiedMcpToolVisibilityDynamic;
+export interface ClassifiedMcpToolVisibilityAlways {
+    readonly visibilityKind: 'always';
+}
+export interface ClassifiedMcpToolVisibilityNever {
+    readonly visibilityKind: 'never';
+}
+export interface ClassifiedMcpToolVisibilityDeclarative {
+    readonly visibilityKind: 'declarative';
+    readonly rule: McpVisibilityRule;
+}
+export interface ClassifiedMcpToolVisibilityDynamic {
+    readonly visibilityKind: 'dynamic';
+    readonly visibilityFn: (context: McpVisibilityContext) => boolean;
+}
+/**
+ * Per-tool boot-time filter metadata. The per-request loop reads these fields directly.
+ *
+ * Discriminated by {@link McpToolVisibilityKind} so the request loop narrows to the
+ * exact variant carrying `rule` or `visibilityFn` without optional-chain assertions.
+ */
+export type McpToolFilterMetadata = McpToolFilterMetadataAlways | McpToolFilterMetadataNever | McpToolFilterMetadataDeclarative | McpToolFilterMetadataDynamic;
+interface McpToolFilterMetadataBase {
+    /**
+     * OIDC scope required to invoke this tool. Precomputed from the dispatch call type.
+     * `undefined` for non-CRUD call types (apps gate those via their own preAssert if needed).
+     */
+    readonly requiredScope?: CallModelOidcScope;
+    /**
+     * Effective read-only classification used by the module-level `readOnly` filter.
+     *
+     * Explicit handler `mcp.readOnly` wins. Otherwise inferred from the call type:
+     * `read`/`query` → true; `create`/`update`/`delete` → false; anything else → undefined.
+     * Unknown counts as a write for fail-safe filtering.
+     */
+    readonly effectiveReadOnly?: boolean;
+}
+export interface McpToolFilterMetadataAlways extends McpToolFilterMetadataBase {
+    readonly visibilityKind: 'always';
+}
+export interface McpToolFilterMetadataNever extends McpToolFilterMetadataBase {
+    readonly visibilityKind: 'never';
+}
+export interface McpToolFilterMetadataDeclarative extends McpToolFilterMetadataBase {
+    readonly visibilityKind: 'declarative';
+    readonly rule: McpVisibilityRule;
+}
+export interface McpToolFilterMetadataDynamic extends McpToolFilterMetadataBase {
+    readonly visibilityKind: 'dynamic';
+    readonly visibilityFn: (context: McpVisibilityContext) => boolean;
+}
+/**
+ * Classifies a {@link McpToolVisibility} value into its normalized boot-time form.
+ *
+ * Defaults `undefined` to `'always'` so handlers without a visibility field stay visible.
+ *
+ * @param visibility - The raw visibility value from the handler's `mcp.visibility` field.
+ * @returns The discriminated classification used by the per-request filter loop.
+ */
+export declare function classifyVisibility(visibility?: McpToolVisibility): ClassifiedMcpToolVisibility;
+/**
+ * Resolves the effective read-only classification for a handler.
+ *
+ * Explicit handler override wins. Otherwise infers from the call type. Returns
+ * `undefined` when neither source provides a definite classification.
+ *
+ * @param explicitReadOnly - The handler's explicit `mcp.readOnly` value, if any.
+ * @param callType - The dispatch call type used to infer read-only when no override is present.
+ * @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;
+/**
+ * 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
+ * `@dereekb/firebase` directly.
+ *
+ * @param callType - The dispatch call type to map to a CRUD OIDC scope.
+ * @returns The required scope for this call type, or `undefined` when no scope is enforced.
+ */
+export declare function resolveRequiredScope(callType: string): Maybe<CallModelOidcScope>;
+export {};

package/mcp/src/lib/service/tools/mcp.tool.model-decode.d.ts

@@ -0,0 +1,87 @@
+import { type McpManifestModelEntry } from '../mcp.manifest';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `model-decode` static tool.
+ */
+export declare const MODEL_DECODE_TOOL_NAME = "model-decode";
+/**
+ * Synthetic call type used in the tool's dispatch identity. Aligns with the dbx-cli `model-decode`
+ * command.
+ */
+export declare const MODEL_DECODE_DISPATCH_CALL = "decode";
+/**
+ * Synthetic model type used in the tool's dispatch identity. Mirrors the other built-in static
+ * tools (`model-get`, `model-info`); apps avoiding collisions should not register a real model
+ * literally named "model".
+ */
+export declare const MODEL_DECODE_DISPATCH_MODEL_TYPE = "model";
+/**
+ * Constructor dependencies for {@link createModelDecodeTool}.
+ */
+export interface CreateModelDecodeToolDeps {
+    /**
+     * Frozen catalog of Firestore models used to resolve segment prefixes.
+     */
+    readonly manifest: readonly McpManifestModelEntry[];
+}
+/**
+ * Shape of the `model-decode` tool input.
+ */
+export interface ModelDecodeToolInput {
+    readonly key: string;
+}
+/**
+ * One segment of a decoded Firestore key. `model*` fields are absent when the
+ * segment's `prefix` isn't in the manifest.
+ */
+export interface DecodedKeySegment {
+    readonly prefix: string;
+    readonly id: string;
+    readonly modelType?: string;
+    readonly modelName?: string;
+    readonly modelGroup?: string;
+    readonly identityConst?: string;
+    readonly parentIdentityConst?: string;
+    readonly sourcePackage?: string;
+    readonly sourceFile?: string;
+}
+/**
+ * Output payload for the `model-decode` tool.
+ */
+export interface ModelDecodeToolOutput {
+    readonly key: string;
+    readonly leaf: DecodedKeySegment;
+    readonly ancestors: ReadonlyArray<DecodedKeySegment>;
+    readonly unresolvedPrefixes: ReadonlyArray<string>;
+}
+/**
+ * Builds the built-in `model-decode` MCP tool definition.
+ *
+ * Mirrors dbx-cli's `model-decode <key>` command:
+ * - Splits the supplied Firestore key on `/`, walks `[prefix, id]` pairs, and resolves each prefix
+ *   against the manifest.
+ * - Supports subcollection paths (`parentPrefix/parentId/childPrefix/childId`).
+ *
+ * Output is delivered as both stringified JSON in `content[0].text` and `structuredContent` so
+ * MCP clients can consume either form.
+ *
+ * @param deps - The frozen model manifest loaded at boot from the MCP manifest JSON.
+ * @returns A statically-registered {@link McpToolDefinition} ready to be appended to the MCP
+ *   server factory's tool registry.
+ */
+export declare function createModelDecodeTool(deps: CreateModelDecodeToolDeps): McpToolDefinition;
+/**
+ * Splits `rawKey` on `/`, resolves each `[prefix, id]` pair against the manifest, and
+ * returns the leaf segment + ancestor chain.
+ *
+ * Mirrors the dbx-cli `decodeFirestoreModelKey` helper structurally; both implementations
+ * must stay in lockstep on segment count and resolution order.
+ *
+ * @param rawKey - The Firestore key string.
+ * @param manifest - The model manifest.
+ * @returns The decoded key with leaf, ancestors, and any unresolved prefixes.
+ * @throws {Error} When `rawKey` is empty or does not parse into an even number of `prefix/id` segments.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function decodeFirestoreModelKey(rawKey: string, manifest: ReadonlyArray<McpManifestModelEntry>): ModelDecodeToolOutput;

package/mcp/src/lib/service/tools/mcp.tool.model-get.d.ts

@@ -0,0 +1,81 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirestoreModelIdentity, type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
+import { type ModelAccessMultiReadResult, type FirebaseServerAuthData } from '@dereekb/firebase-server';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `model-get` static tool.
+ */
+export declare const MODEL_GET_TOOL_NAME = "model-get";
+/**
+ * Synthetic call type used in the tool's dispatch identity. Aligns with the dbx-cli `get`
+ * command and the `/api/model/:modelType/get` HTTP endpoint that backs it.
+ */
+export declare const MODEL_GET_DISPATCH_CALL = "get";
+/**
+ * Synthetic model type used in the tool's dispatch identity. The tool itself isn't bound to a
+ * specific model type (the `modelType` is part of its input), so we use the literal "model" as
+ * the identity. Apps avoiding collision should not register a real model literally named
+ * "model".
+ */
+export declare const MODEL_GET_DISPATCH_MODEL_TYPE = "model";
+/**
+ * Maximum number of keys per backend multi-read request. Matches
+ * `MAX_MODEL_ACCESS_MULTI_READ_KEYS` exported from `@dereekb/firebase-server`; mirrored as a
+ * local constant so the bundler doesn't have to follow the import chain just for one number.
+ */
+export declare const MCP_MODEL_GET_BATCH_SIZE = 50;
+/**
+ * Per-batch read function. Identical signature to {@link ModelApiGetService.readDocuments} so the
+ * service method can be passed directly.
+ */
+export type McpModelGetReadDocuments = (modelType: FirestoreModelType, keys: FirestoreModelKey[], auth: Maybe<FirebaseServerAuthData>) => Promise<ModelAccessMultiReadResult>;
+/**
+ * Lookup function that resolves a `modelType` to its registered {@link FirestoreModelIdentity}.
+ *
+ * Takes the request's auth so the wiring layer can build a real model context on first use
+ * (the underlying `getFirestoreCollection(context)` accessor is context-dependent). Returns
+ * `undefined` for unknown model types; the handler surfaces this as a user-visible error.
+ */
+export type McpModelGetResolveIdentity = (modelType: FirestoreModelType, auth: Maybe<FirebaseServerAuthData>) => Maybe<FirestoreModelIdentity>;
+/**
+ * Constructor dependencies for {@link createModelGetTool}.
+ */
+export interface CreateModelGetToolDeps {
+    /**
+     * Reads a batch of model documents. Provided as a callback so the unit tests can mock it
+     * without instantiating the Nest DI container.
+     */
+    readonly readDocuments: McpModelGetReadDocuments;
+    /**
+     * Resolves the registered identity for a model type so bare ids can be promoted into full
+     * `prefix/id` keys.
+     */
+    readonly resolveIdentity: McpModelGetResolveIdentity;
+}
+/**
+ * Shape of the `model-get` tool input.
+ */
+export interface ModelGetToolInput {
+    readonly modelType: string;
+    readonly keys: ReadonlyArray<string>;
+}
+/**
+ * Builds the built-in `model-get` MCP tool definition.
+ *
+ * Mirrors dbx-cli's `get` / `get-many` behavior:
+ * - Accepts an array of keys; values containing `/` are treated as full keys and passed verbatim
+ *   while bare ids are promoted to `${collectionName}/${id}` for root models.
+ * - Nested (subcollection) models reject bare ids since a parent path is required.
+ * - Auto-chunks at {@link MCP_MODEL_GET_BATCH_SIZE} keys per backend call, mirroring
+ *   `getMultipleModelsOverHttpChunked` on the CLI side.
+ *
+ * The handler returns the same `{ results, errors }` shape produced by
+ * `ModelApiGetService.readDocuments`, exposed via both the text content block and
+ * `structuredContent` so MCP clients can consume either form.
+ *
+ * @param deps - Read-documents and identity-resolver callbacks (typically wired to
+ *   `ModelApiGetService`).
+ * @returns A statically-registered {@link McpToolDefinition} ready to be appended to the MCP
+ *   server factory's tool registry.
+ */
+export declare function createModelGetTool(deps: CreateModelGetToolDeps): McpToolDefinition;

package/mcp/src/lib/service/tools/mcp.tool.model-info.d.ts

@@ -0,0 +1,84 @@
+import { type McpManifestModelEntry } from '../mcp.manifest';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `model-info` static tool.
+ */
+export declare const MODEL_INFO_TOOL_NAME = "model-info";
+/**
+ * Synthetic call type used in the tool's dispatch identity. Aligns with the dbx-cli `model-info`
+ * command.
+ */
+export declare const MODEL_INFO_DISPATCH_CALL = "info";
+/**
+ * Synthetic model type used in the tool's dispatch identity. Mirrors {@link MODEL_GET_DISPATCH_MODEL_TYPE};
+ * apps avoiding collisions should not register a real model literally named "model".
+ */
+export declare const MODEL_INFO_DISPATCH_MODEL_TYPE = "model";
+/**
+ * Constructor dependencies for {@link createModelInfoTool}.
+ */
+export interface CreateModelInfoToolDeps {
+    /**
+     * Frozen catalog of Firestore models exposed by the host app, sourced from the build-time
+     * manifest JSON.
+     */
+    readonly manifest: readonly McpManifestModelEntry[];
+}
+/**
+ * Shape of the `model-info` tool input. Omit `model` to list every model in the manifest.
+ */
+export interface ModelInfoToolInput {
+    readonly model?: string;
+}
+/**
+ * Summary row returned in list mode.
+ */
+export interface ModelInfoSummaryRow {
+    readonly modelType: string;
+    readonly modelName: string;
+    readonly modelGroup?: string;
+    readonly identityConst: string;
+    readonly collectionPrefix: string;
+    readonly parentIdentityConst?: string;
+    readonly sourcePackage: string;
+    readonly fieldCount: number;
+    readonly description?: string;
+    readonly read?: 'system' | 'owner' | 'admin-only' | 'permissions';
+    readonly serviceFactoryExport?: string;
+}
+/**
+ * Output payload for the `model-info` tool. `mode === 'list'` carries `models[]`;
+ * `mode === 'single'` carries the full `model` entry.
+ */
+export type ModelInfoToolOutput = {
+    readonly mode: 'list';
+    readonly models: ReadonlyArray<ModelInfoSummaryRow>;
+} | {
+    readonly mode: 'single';
+    readonly model: McpManifestModelEntry;
+};
+/**
+ * Builds the built-in `model-info` MCP tool definition.
+ *
+ * Mirrors dbx-cli's `model-info [model]` command:
+ * - Without a `model` arg: returns a summary list (modelType, modelName, prefix, group, identity, field count).
+ * - With a `model` arg: matches by `modelType`, `identityConst`, or `collectionPrefix` and returns the full entry.
+ *
+ * Output is delivered as both stringified JSON in `content[0].text` and `structuredContent`
+ * so MCP clients can consume either form.
+ *
+ * @param deps - The frozen model manifest loaded at boot from the MCP manifest JSON.
+ * @returns A statically-registered {@link McpToolDefinition} ready to be appended to the MCP
+ *   server factory's tool registry.
+ */
+export declare function createModelInfoTool(deps: CreateModelInfoToolDeps): McpToolDefinition;
+/**
+ * Resolves a manifest entry by `modelType`, `identityConst`, or `collectionPrefix`.
+ *
+ * @param query - Identifier to look up.
+ * @param manifest - Model manifest to search.
+ * @returns The matching entry or `undefined`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function findModelEntry(query: string, manifest: ReadonlyArray<McpManifestModelEntry>): McpManifestModelEntry | undefined;

package/mcp/src/lib/service/tools/mcp.tool.whoami.d.ts

@@ -0,0 +1,72 @@
+import { type McpAuthRoleReader } from '../../mcp.config';
+import { type McpManifestAuth } from '../mcp.manifest';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `whoami` static tool.
+ */
+export declare const WHOAMI_TOOL_NAME = "whoami";
+/**
+ * Synthetic call type used in the tool's dispatch identity. Matches the
+ * pattern set by `model-info` — `read` (not `info`) so the visibility
+ * classifier treats the tool as a read.
+ */
+export declare const WHOAMI_DISPATCH_CALL = "read";
+/**
+ * Synthetic model type used in the tool's dispatch identity.
+ */
+export declare const WHOAMI_DISPATCH_MODEL_TYPE = "auth";
+/**
+ * Constructor dependencies for {@link createWhoamiTool}.
+ */
+export interface CreateWhoamiToolDeps {
+    /**
+     * Auth section loaded from the pre-rendered MCP manifest JSON. Drives the
+     * description text plus the role-detail enrichment for claim keys present
+     * on the live token.
+     */
+    readonly auth: McpManifestAuth;
+    /**
+     * Optional role reader. When present, decodes the live token's claims into
+     * a {@link AuthRoleSet}; the resulting roles are returned alongside the
+     * claim details. When absent, `roles` is empty.
+     */
+    readonly roleReader?: McpAuthRoleReader;
+}
+/**
+ * One entry returned in `claimDetails`. Mirrors the `dbx_auth_list_app`
+ * formatter shape minus source paths.
+ */
+export interface WhoamiClaimDetail {
+    readonly key: string;
+    readonly interfaceName?: string;
+    readonly description: string;
+    readonly grantedRoles: readonly string[];
+    readonly inverse: boolean;
+    readonly tags: readonly string[];
+}
+/**
+ * Output payload for the `whoami` tool.
+ */
+export interface WhoamiToolOutput {
+    readonly authenticated: boolean;
+    readonly uid?: string;
+    readonly email?: string;
+    readonly emailVerified?: boolean;
+    readonly app?: string;
+    readonly claims: Readonly<Record<string, unknown>>;
+    readonly roles: readonly string[];
+    readonly claimDetails: readonly WhoamiClaimDetail[];
+    readonly unknownClaimKeys: readonly string[];
+}
+/**
+ * Builds the built-in `whoami` MCP tool definition. Returns the calling
+ * caller's `uid`, claims object, decoded role set, and rendered descriptions
+ * for every claim key actually present on the live token.
+ *
+ * Unauthenticated callers receive a structured `authenticated: false` result
+ * (no exception) so the tool can be used as a "do you see me?" probe.
+ *
+ * @param deps - The manifest's auth section + optional role reader.
+ * @returns A statically-registered {@link McpToolDefinition} to append to the MCP server factory's tool registry.
+ */
+export declare function createWhoamiTool(deps: CreateWhoamiToolDeps): McpToolDefinition;

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

@@ -0,0 +1 @@
+export * from './streamable-http.transport';