@dereekb/firebase-server 13.15.0 → 13.17.0

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.15.0",
+  "version": "13.17.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.15.0",
-    "@dereekb/date": "13.15.0",
-    "@dereekb/firebase": "13.15.0",
-    "@dereekb/firebase-server": "13.15.0",
-    "@dereekb/firebase-server/oidc": "13.15.0",
-    "@dereekb/model": "13.15.0",
-    "@dereekb/nestjs": "13.15.0",
-    "@dereekb/rxjs": "13.15.0",
-    "@dereekb/util": "13.15.0",
-    "@dereekb/zoho": "13.15.0",
+    "@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",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",

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

@@ -80,6 +80,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`.
      *

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

@@ -1,5 +1,6 @@
 export * from './analytics';
 export * from './mcp.manifest';
+export * from './mcp.route-manifest';
 export * from './mcp.response-formatter';
 export * from './mcp.server.factory';
 export * from './mcp.tool-generator';
@@ -7,4 +8,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.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,7 +32,10 @@ export declare class McpServerFactoryService {
     private _cachedStaticTools;
     private _cachedManifest;
     private _cachedManifestModels;
+    private _cachedManifestEnums;
     private _cachedManifestAuth;
+    private _cachedRouteManifest;
+    private _routeManifestLoaded;
     private _manifestLoaded;
     private _loggedSkips;
     private _warnedMissingRoleReader;
@@ -129,6 +132,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;
     /**

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

@@ -2,7 +2,7 @@ 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 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,20 @@ 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;
 /**
  * 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

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

@@ -0,0 +1,70 @@
+import { type McpManifestEnum } from '../mcp.manifest';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `enum-info` static tool.
+ */
+export declare const ENUM_INFO_TOOL_NAME = "enum-info";
+/**
+ * Synthetic call type used in the tool's dispatch identity. Mirrors the `info` call shared with
+ * `model-info`.
+ */
+export declare const ENUM_INFO_DISPATCH_CALL = "info";
+/**
+ * Synthetic model type used in the tool's dispatch identity. Apps avoiding collisions should not
+ * register a real model literally named "enum".
+ */
+export declare const ENUM_INFO_DISPATCH_MODEL_TYPE = "enum";
+/**
+ * Constructor dependencies for {@link createEnumInfoTool}.
+ */
+export interface CreateEnumInfoToolDeps {
+    /**
+     * Frozen enum value tables keyed by enum name, sourced from the build-time manifest's `enums`
+     * block.
+     */
+    readonly enums: {
+        readonly [name: string]: McpManifestEnum;
+    };
+}
+/**
+ * Shape of the `enum-info` tool input.
+ */
+export interface EnumInfoToolInput {
+    /**
+     * One enum name (string) or several (string array), each matched exactly by declaration name.
+     */
+    readonly enum: string | ReadonlyArray<string>;
+}
+/**
+ * Output payload for the `enum-info` tool: the resolved value tables, with any unmatched names in
+ * `notFound`.
+ */
+export interface EnumInfoToolOutput {
+    readonly enums: ReadonlyArray<McpManifestEnum>;
+    readonly notFound?: ReadonlyArray<string>;
+}
+/**
+ * Builds the built-in `enum-info` MCP tool definition — the symmetric counterpart to `model-info`
+ * for raw enum decoding.
+ *
+ * Resolves each requested enum name against the manifest's `enums` block and returns the matching
+ * value→label tables; misses land in `notFound`. A bare string is treated as a one-element array.
+ *
+ * Output is delivered as both stringified JSON in `content[0].text` and `structuredContent` so MCP
+ * clients can consume either form.
+ *
+ * @param deps - The frozen enum value tables 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 createEnumInfoTool(deps: CreateEnumInfoToolDeps): McpToolDefinition;
+/**
+ * Resolves each requested enum name against the registered value tables.
+ *
+ * @param names - The requested enum declaration names.
+ * @param enums - The registered enum value tables keyed by name.
+ * @returns The matched tables, with any unmatched names in `notFound`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function resolveEnumInfoOutput(names: readonly string[], enums: CreateEnumInfoToolDeps['enums']): EnumInfoToolOutput;

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

@@ -1,4 +1,4 @@
-import { type McpManifestModelEntry } from '../mcp.manifest';
+import { type McpManifestEnum, type McpManifestModelEntry } from '../mcp.manifest';
 import { type McpToolDefinition } from '../mcp.tool-generator';
 /**
  * Reserved tool name for the built-in `model-info` static tool.
@@ -32,6 +32,15 @@ export interface CreateModelInfoToolDeps {
      * manifest JSON.
      */
     readonly manifest: readonly McpManifestModelEntry[];
+    /**
+     * Optional enum value tables, keyed by enum name, sourced from the build-time manifest's `enums`
+     * block. When present, the value→label table for every enum referenced (by `enumRef`) on a
+     * returned model's fields is attached as a top-level `enums` section — but only when full field
+     * detail is returned, so the default compact modes stay small.
+     */
+    readonly enums?: {
+        readonly [name: string]: McpManifestEnum;
+    };
 }
 /**
  * Public shape of the `model-info` tool input. Every field is optional; the combination selects
@@ -112,8 +121,12 @@ export interface ModelInfoNotFound {
  * - `list`: a summary (or, with `fields: true`, full) list — used by `modelGroup` and `all`.
  * - `single`: full detail for one `model` string.
  * - `multiple`: full detail per match for a `model` array, with misses in `notFound`.
+ *
+ * The orthogonal `enums` section is attached only when full field detail is returned and the
+ * returned models reference at least one enum present in the manifest — the default compact modes
+ * (`groups`, summary `list`) never carry it.
  */
-export type ModelInfoToolOutput = {
+export type ModelInfoToolOutput = ({
     readonly mode: 'groups';
     readonly groups: ReadonlyArray<ModelInfoGroupCount>;
     readonly totalModels: number;
@@ -129,6 +142,8 @@ export type ModelInfoToolOutput = {
     readonly mode: 'multiple';
     readonly models: ReadonlyArray<ModelInfoModelRow>;
     readonly notFound?: ReadonlyArray<ModelInfoNotFound>;
+}) & {
+    readonly enums?: ReadonlyArray<McpManifestEnum>;
 };
 /**
  * Builds the built-in `model-info` MCP tool definition.
@@ -162,3 +177,37 @@ export declare function createModelInfoTool(deps: CreateModelInfoToolDeps): McpT
  * @__NO_SIDE_EFFECTS__
  */
 export declare function findModelEntry(query: string, manifest: ReadonlyArray<McpManifestModelEntry>): McpManifestModelEntry | undefined;
+/**
+ * JSON-schema for one enum value→label table. Shared with the `enum-info` tool so both advertise the
+ * identical enum shape.
+ */
+export declare const ENUM_TABLE_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["name", "values"];
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly values: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["name", "value"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly value: {
+                        readonly type: readonly ["string", "number"];
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+};

package/mcp/src/lib/service/tools/mcp.tool.url-models.d.ts

@@ -0,0 +1,101 @@
+import { type FirestoreModelKey } from '@dereekb/firebase';
+import { type ModelAccessMultiReadResult } from '@dereekb/firebase-server';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+import { type RouteManifest, type RouteManifestModelEntry } from '../mcp.route-manifest';
+import { type McpModelGetReadDocuments, type McpModelGetResolveIdentity } from './mcp.tool.model-get';
+/**
+ * Reserved tool name for the built-in `url-models` static tool.
+ */
+export declare const URL_MODELS_TOOL_NAME = "url-models";
+/**
+ * Synthetic call type used in the tool's dispatch identity.
+ */
+export declare const URL_MODELS_DISPATCH_CALL = "url-models";
+/**
+ * Synthetic model type used in the tool's dispatch identity. The tool isn't
+ * bound to a real model (the `url` is its input), so we use the literal "route".
+ */
+export declare const URL_MODELS_DISPATCH_MODEL_TYPE = "route";
+/**
+ * Why a model binding could not be resolved into a concrete key.
+ */
+export type UrlModelUnresolvedReason = 'missing-param' | 'subcollection-requires-key-template' | 'unknown-model-type' | 'auth-required';
+/**
+ * One resolved model binding for a matched page.
+ */
+export interface ResolvedRouteModel {
+    readonly modelType: string;
+    readonly kind: RouteManifestModelEntry['kind'];
+    readonly keyTemplate?: string;
+    readonly description?: string;
+    readonly from?: string;
+    /**
+     * The concrete FirestoreModelKey, when the binding resolved (`id`/`key` kinds).
+     */
+    readonly key?: FirestoreModelKey;
+    /**
+     * Present when the binding could not be turned into a key.
+     */
+    readonly unresolved?: {
+        readonly reason: UrlModelUnresolvedReason;
+        readonly message: string;
+    };
+}
+/**
+ * Documents loaded for one model type (when `load` is requested).
+ */
+export interface UrlModelLoadedGroup {
+    readonly modelType: string;
+    readonly results: ModelAccessMultiReadResult['results'];
+    readonly errors: ModelAccessMultiReadResult['errors'];
+}
+/**
+ * Constructor dependencies for {@link createUrlModelsTool}.
+ */
+export interface CreateUrlModelsToolDeps {
+    /**
+     * The pre-rendered route manifest used to match URLs to states.
+     */
+    readonly routeManifest: RouteManifest;
+    /**
+     * Reads a batch of model documents (shared with `model-get`).
+     */
+    readonly readDocuments: McpModelGetReadDocuments;
+    /**
+     * Resolves a model type's registered identity so `id` key templates can be
+     * promoted to `<collectionName>/<id>` (shared with `model-get`).
+     */
+    readonly resolveIdentity: McpModelGetResolveIdentity;
+}
+/**
+ * Shape of the `url-models` tool input.
+ */
+export interface UrlModelsToolInput {
+    readonly url: string;
+    readonly models?: ReadonlyArray<string>;
+    readonly keysOnly?: boolean;
+    readonly load?: boolean;
+    /**
+     * Overrides the uid used to fill `{authUid}` placeholders when resolving model
+     * keys (defaults to the authenticated caller). Use to preview the models
+     * another user would see on a page. Does not affect the document-load path —
+     * `load` still reads via the calling user's permissions.
+     */
+    readonly currentUserUid?: string;
+}
+/**
+ * Builds the built-in `url-models` MCP tool definition.
+ *
+ * Matches a pasted app URL against the build-time route manifest and returns the
+ * Firestore models the page renders — model types plus concrete keys with the
+ * route params and `{authUid}` substituted. Optionally filtered to specific
+ * `models`, reduced to keys-only, or loaded via the same permission-checked read
+ * path as `model-get`.
+ *
+ * A URL that matches no state returns a structured `{ matched: null, candidates }`
+ * (not an error) so the caller can suggest near-misses.
+ *
+ * @param deps - The route manifest plus the shared read-documents / identity callbacks.
+ * @returns A statically-registered {@link McpToolDefinition}.
+ */
+export declare function createUrlModelsTool(deps: CreateUrlModelsToolDeps): McpToolDefinition;