@dereekb/firebase-server 13.13.0 → 13.15.0

package/mcp/package.json

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

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

@@ -7,3 +7,4 @@ 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.batch-execute';

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

@@ -18,6 +18,12 @@ export interface McpManifestToolEntry {
     readonly description?: string;
     readonly inputSchema?: object;
     readonly outputSchema?: object;
+    /**
+     * Name of the MCP-mapped result interface (from `@dbxModelApiMcpResult`) when the output schema was
+     * built from a mapped type. Used at boot to detect a `mapSuccessfulResult` handler whose `.api.ts`
+     * leaf was never annotated (the output schema would then describe the raw, un-mapped result).
+     */
+    readonly mcpResultTypeName?: string;
 }
 /**
  * One persisted field on a {@link McpManifestModelEntry}.
@@ -55,6 +61,13 @@ export interface McpManifestModelEntry {
     readonly sourcePackage: string;
     readonly sourceFile: string;
     readonly fields: readonly McpManifestModelField[];
+    /**
+     * Per-model override of the model segment used in generated MCP tool names (from
+     * `@dbxModelMcpToolNameSegment` on the model interface). When present it replaces the model type
+     * in tool names (e.g. the collection prefix), trading readability for shorter names. Absent when
+     * the model omits the tag — names then use the model type.
+     */
+    readonly mcpToolNameSegment?: string;
     /**
      * Read posture declared by `@dbxModelRead <level>` on the model interface (`system` /
      * `owner` / `admin-only` / `permissions`). Absent when the source model omits the tag.

package/mcp/src/lib/service/mcp.response-formatter.d.ts

@@ -13,20 +13,24 @@ export declare const DEFAULT_VOID_MCP_SUCCESS_VALUE: {
 /**
  * Resolves a dispatch result + handler API details into the MCP `CallToolResult` shape.
  *
+ * When `mcp.mapSuccessfulResult` is set, the raw result is first mapped (async-capable) to the value
+ * exposed via MCP; the tiers and the default path then operate on the mapped value. The tier
+ * callbacks receive `(value, context)` where `context` carries both the raw + mapped values + params.
+ *
  * Three-tier resolution as documented on {@link OnCallModelFunctionApiDetails.mcp}:
  *
  * - **Tier 3** — when `mcp.formatResponse` is set, its return value is used verbatim.
  * - **Tier 2** — when `mcp.summarizeResponse` is set, the summary string is wrapped into a
- *   single text content block with the raw `result` exposed as `structuredContent`.
- * - **Tier 1** — default: JSON-stringify `result` as a single text content block, also
- *   exposing the raw value as `structuredContent`.
+ *   single text content block with the (mapped) value exposed as `structuredContent`.
+ * - **Tier 1** — default: JSON-stringify the (mapped) value as a single text content block, also
+ *   exposing it as `structuredContent`.
  *
- * @param result - The handler's return value.
+ * @param result - The handler's raw return value.
  * @param params - The {@link OnCallTypedModelParams} that were dispatched.
- * @param details - The handler-level API details (carries Tier 2/3 formatters).
+ * @param details - The handler-level API details (carries the mapper + Tier 2/3 formatters).
  * @returns The MCP tool response content.
  */
-export declare function formatMcpToolResponse(result: unknown, params: OnCallTypedModelParams, details: OnCallModelFunctionApiDetails | undefined): McpToolResponseContent;
+export declare function formatMcpToolResponse(result: unknown, params: OnCallTypedModelParams, details: OnCallModelFunctionApiDetails | undefined): Promise<McpToolResponseContent>;
 /**
  * Converts an error thrown from the dispatch chain into the MCP error response shape.
  *

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

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Request } from 'express';
-import { ModelApiCallModelDispatchService, ModelApiGetService, type FirebaseServerAuthData } from '@dereekb/firebase-server';
+import { ModelApiCallModelDispatchService, ModelApiGetService, FirebaseServerStorageService, type FirebaseServerAuthData } from '@dereekb/firebase-server';
 import { McpModuleConfig, type McpAuthRoleReader } from '../mcp.config';
 import { type McpAnalyticsService } from './analytics/mcp.analytics.handler';
 /**
@@ -26,6 +26,7 @@ export declare class McpServerFactoryService {
     private readonly dispatchService;
     private readonly modelApiGetService?;
     private readonly roleReader?;
+    private readonly storageService?;
     private readonly _logger;
     private _cachedTools;
     private _cachedStaticTools;
@@ -36,7 +37,7 @@ export declare class McpServerFactoryService {
     private _loggedSkips;
     private _warnedMissingRoleReader;
     private readonly _analyticsService;
-    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined, analyticsService?: McpAnalyticsService);
+    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined, analyticsService?: McpAnalyticsService, storageService?: FirebaseServerStorageService | undefined);
     /**
      * Builds a configured MCP server with tool listing + dispatch handlers wired up.
      *
@@ -53,6 +54,30 @@ export declare class McpServerFactoryService {
      * @returns The cached or freshly-generated tool generation result.
      */
     private _resolveToolDefinitions;
+    /**
+     * Builds the per-model tool-name segment overrides from the loaded manifest's `models` catalog.
+     *
+     * Sourcing the segments from the manifest (rather than runtime config) keeps the runtime in
+     * agreement with the build-time manifest validation, which reads the same `mcpToolNameSegment`.
+     *
+     * @returns Naming options carrying the segment map, or `undefined` when no model declares one.
+     */
+    private _resolveToolNamingOptions;
+    /**
+     * Logs one skipped tool at the appropriate level: name-cap and collision skips are errors (they
+     * would otherwise break or shadow tools on the wire), the rest are warnings.
+     *
+     * @param skip - The skipped-tool report to log.
+     */
+    private _logSkip;
+    /**
+     * Renders a human-readable boot-time warning for an MCP-result mapping inconsistency between a
+     * handler's `mapSuccessfulResult` and the build-time manifest.
+     *
+     * @param warning - The tool-generation warning to describe.
+     * @returns The log line to emit at startup.
+     */
+    private _describeToolGenerationWarning;
     /**
      * Builds the list of statically-registered (non-callModel) MCP tools.
      *
@@ -65,6 +90,33 @@ export declare class McpServerFactoryService {
      * @returns The cached array of static tool definitions, filtered for collisions with generated tools.
      */
     private _resolveStaticTools;
+    /**
+     * Builds the per-request `batch-execute` tool, or `undefined` when it should not be offered.
+     *
+     * Unlike the cached static tools this is rebuilt per request, because it closes over the caller's
+     * resolved visible tool set: each batched operation is authorized against exactly the callModel
+     * tools this caller may invoke directly. Offered only when a storage service is wired (it reads
+     * the uploaded operations file), the caller is authenticated, and the server is not in read-only
+     * mode (the tool performs writes).
+     *
+     * @param ctx - The per-request context (auth, raw request) forwarded to dispatched operations.
+     * @param definitionsByName - The caller's visible tool definitions, keyed by name.
+     * @returns The batch tool definition, or `undefined` when unavailable for this request.
+     */
+    private _resolveBatchTool;
+    /**
+     * Authorizes a single batched operation against the caller's visible callModel tool coordinates.
+     *
+     * Re-applies the same gate the `tools/list` filter already enforced: an operation is allowed only
+     * when its `(call, modelType, specifier)` coordinate matches a tool this caller can see. This is
+     * the critical guard — `dispatchService.dispatch` bypasses the MCP visibility filter, so without
+     * this check a batch could reach scope-, role-, or read-only-gated handlers.
+     *
+     * @param operation - The operation to authorize.
+     * @param authorizedCoords - The set of dispatchable coordinate keys visible to this caller.
+     * @returns Whether the operation may be dispatched, with a reason when it may not.
+     */
+    private _authorizeBatchOperation;
     /**
      * Reads the pre-rendered MCP manifest JSON once, validates its version, and caches the
      * resulting `key → entry` map plus the optional `models` catalog for the process lifetime.

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

@@ -1,4 +1,5 @@
 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';
@@ -24,12 +25,14 @@ export interface McpToolDefinition {
     /**
      * Tool name advertised on `tools/list`.
      *
-     * Format: `<modelType>-<callType>` for default (`_`) specifiers,
-     * `<modelType>-<callType>-<specifier>` for non-default specifiers.
+     * Format: `<modelSegment>-<callType>` for default (`_`) specifiers; named specifiers drop the
+     * call-type segment (`<modelSegment>-<specifier>`) to stay short. When two visible tools would
+     * resolve to the same name, both are disambiguated with the abbreviated call type
+     * (`<modelSegment>-<abbrev>-<specifier>`); see {@link buildDisambiguatedMcpToolName}.
      *
      * @example 'guestbook-create'
-     * @example 'profile-update-username'
-     * @example 'storageFile-invoke-recomputeChecksums'
+     * @example 'profile-username'
+     * @example 'profile-u-username'
      */
     readonly name: string;
     /**
@@ -144,8 +147,15 @@ export interface JsonSchemaGenerationOptions {
 export declare const DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS: JsonSchemaGenerationOptions;
 /**
  * Reason a tool was skipped during generation.
+ *
+ * - `missing_input_type` — the handler has no `inputType` to build a schema from.
+ * - `schema_generation_failed` — `toJsonSchema()` threw for the handler's `inputType`.
+ * - `name_too_long` — the resolved name exceeds {@link MCP_TOOL_NAME_MAX_LENGTH}; advertising it
+ *   would make remote clients reject the whole `tools/list` payload, so it is dropped.
+ * - `duplicate_name` — another already-registered visible tool resolved to the same name (e.g. two
+ *   specifiers collide once the call-type segment is dropped); the later tool is dropped.
  */
-export type McpToolGenerationSkipReason = 'missing_input_type' | 'schema_generation_failed';
+export type McpToolGenerationSkipReason = 'missing_input_type' | 'schema_generation_failed' | 'name_too_long' | 'duplicate_name';
 /**
  * One tool that was skipped during generation.
  */
@@ -155,6 +165,35 @@ export interface McpToolGenerationSkip {
     readonly dispatch: McpToolDispatchTarget;
     readonly error?: Error;
 }
+/**
+ * Reason a generated tool's handler and build-time manifest disagree about MCP result mapping.
+ *
+ * - `mapper_without_mapped_manifest` — the handler declares `mcp.mapSuccessfulResult` but the
+ *   manifest entry was not built from a mapped result type, i.e. the `.api.ts` leaf is missing its
+ *   `@dbxModelApiMcpResult <TypeName>` annotation, so the advertised output schema describes the raw
+ *   (un-mapped) result.
+ * - `mapped_manifest_without_mapper` — the manifest entry is annotated for a mapped result but the
+ *   handler no longer declares `mapSuccessfulResult` (stale annotation).
+ *
+ * Both are runtime↔manifest consistency checks the build-time manifest renderer cannot perform on
+ * its own (it has the `.api.ts` annotation but not the handler's wired `mapSuccessfulResult`), so the
+ * runtime keeps them. Purely build-time-detectable conditions are deliberately *not* warned here to
+ * keep the server boot quiet:
+ * - Name length over the soft limit is surfaced by the manifest renderer, not at runtime (the hard
+ *   cap is still enforced as a `name_too_long` skip).
+ * - A preferred name that collided with another visible tool is re-derived with the abbreviated call
+ *   type ({@link buildDisambiguatedMcpToolName}) **silently** at runtime; the manifest renderer flags it.
+ */
+export type McpToolGenerationWarningReason = 'mapper_without_mapped_manifest' | 'mapped_manifest_without_mapper';
+/**
+ * One generated tool whose handler / manifest MCP-result mapping is inconsistent. The tool is still
+ * generated; the warning is surfaced so the caller can log the drift at startup.
+ */
+export interface McpToolGenerationWarning {
+    readonly toolName: string;
+    readonly reason: McpToolGenerationWarningReason;
+    readonly dispatch: McpToolDispatchTarget;
+}
 /**
  * Aggregated output of {@link generateMcpToolDefinitions}.
  */
@@ -174,6 +213,11 @@ export interface McpToolGenerationResult {
      * Surfaced so the caller can log them at startup.
      */
     readonly skipped: ReadonlyArray<McpToolGenerationSkip>;
+    /**
+     * Generated tools whose handler / manifest MCP-result mapping is inconsistent (only computed when a
+     * manifest is supplied). Surfaced so the caller can log the drift at startup.
+     */
+    readonly warnings: ReadonlyArray<McpToolGenerationWarning>;
 }
 interface BuildStaticWireEntryInput {
     readonly name: string;
@@ -196,17 +240,120 @@ export declare function buildStaticWireEntry(input: BuildStaticWireEntryInput):
  */
 export declare const DEFAULT_SPECIFIER_KEY = "_";
 /**
- * Builds the MCP tool name for a (modelType, callType, specifier) triple.
+ * Soft limit for an MCP tool name. Names longer than this still register, but the generator
+ * surfaces a `name_length_warning` so the drift toward the hard cap is visible at boot / build.
+ */
+export declare const MCP_TOOL_NAME_WARN_LENGTH = 55;
+/**
+ * Hard limit for an MCP tool name. Remote MCP clients reject a `tools/list` payload that contains
+ * any tool whose `name` exceeds this (`FrontendRemoteMcpToolDefinition.name: String should have at
+ * most 64 characters`), which fails the whole connection. Names over this are not registered.
+ */
+export declare const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/**
+ * Severity of a tool name's length relative to {@link MCP_TOOL_NAME_WARN_LENGTH} /
+ * {@link MCP_TOOL_NAME_MAX_LENGTH}.
+ *
+ * - `error` — over the hard cap; the tool must not be advertised.
+ * - `warn` — over the soft limit but within the hard cap; advertised, but flagged.
+ * - `ok` — within the soft limit.
+ */
+export type McpToolNameLengthLevel = 'ok' | 'warn' | 'error';
+/**
+ * The outcome of validating a tool name's length.
+ */
+export interface McpToolNameValidation {
+    readonly name: string;
+    readonly length: number;
+    readonly level: McpToolNameLengthLevel;
+}
+/**
+ * Classifies a tool name's length against the soft/hard MCP name-length limits.
+ *
+ * Shared by the runtime generator and the build-time manifest renderer so both apply the
+ * same thresholds and never drift.
+ *
+ * @param name - The fully-resolved tool name (including any per-handler override).
+ * @returns The length classification — `error` over {@link MCP_TOOL_NAME_MAX_LENGTH}, `warn` over
+ *   {@link MCP_TOOL_NAME_WARN_LENGTH}, otherwise `ok`.
+ *
+ * @example
+ * ```ts
+ * validateMcpToolName('worker-create'); // { name: 'worker-create', length: 13, level: 'ok' }
+ * ```
+ */
+export declare function validateMcpToolName(name: string): McpToolNameValidation;
+/**
+ * Builds the MCP tool name for a (modelSegment, callType, specifier) triple.
  *
- * Apps can override the auto-generated name by setting
- * {@link OnCallModelFunctionApiDetails.mcp.name} on the handler.
+ * The call-type segment is only emitted for the default (`_`) specifier, where it carries the
+ * meaning (`worker-create`, `worker-update`). Named specifiers drop it — the specifier already
+ * disambiguates (`worker-syncCheckHqEmployee`), which keeps names short and within the MCP
+ * 64-character cap. Apps can override the whole name per handler via
+ * {@link OnCallModelFunctionApiDetails.mcp.name}.
  *
- * @param modelType - The Firestore model type (e.g., `storageFile`).
+ * This is the preferred (short) form. When two visible tools collide on it — two call types share a
+ * specifier once the call-type segment is dropped — the generator re-derives both names with
+ * {@link buildDisambiguatedMcpToolName} instead.
+ *
+ * @param modelSegment - The model segment of the name. Defaults to the model type, but may be a
+ *   shorter per-model override (e.g. the collection prefix) resolved by the caller.
  * @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`.
+ *
+ * @example
+ * ```ts
+ * buildMcpToolName('worker', 'create'); // 'worker-create'
+ * buildMcpToolName('worker', 'update', 'syncCheckHqEmployee'); // 'worker-syncCheckHqEmployee'
+ * ```
+ */
+export declare function buildMcpToolName(modelSegment: string, callType: string, specifier?: Maybe<string>): string;
+/**
+ * Single-character abbreviations for the standard CRUDQ + invoke call types, used to disambiguate
+ * colliding tool names without re-introducing the full call-type segment everywhere.
+ *
+ * @example
+ * ```ts
+ * MCP_CALL_TYPE_ABBREVIATIONS.update; // 'u'
+ * ```
+ */
+export declare const MCP_CALL_TYPE_ABBREVIATIONS: Readonly<Record<KnownOnCallFunctionType, string>>;
+/**
+ * Abbreviates a call type for use in a disambiguated tool name. Known CRUDQ + invoke types collapse
+ * to a single character; a custom call type is returned unchanged so the name stays unambiguous.
+ *
+ * @param callType - The call type / verb.
+ * @returns The single-character abbreviation, or the original string for a custom call type.
+ *
+ * @example
+ * ```ts
+ * abbreviateMcpCallType('update'); // 'u'
+ * abbreviateMcpCallType('recompute'); // 'recompute'
+ * ```
+ */
+export declare function abbreviateMcpCallType(callType: string): string;
+/**
+ * Builds the disambiguated MCP tool name for a (modelSegment, callType, specifier) triple — the form
+ * used only when the preferred {@link buildMcpToolName} output collides with another visible tool.
+ *
+ * Named specifiers re-insert the call type, abbreviated, between the segment and specifier
+ * (`worker-u-syncCheckHqEmployee`); since the two colliding tools differ only by call type, their
+ * abbreviations differ and the names no longer clash. Default (`_`) specifiers already carry the
+ * full call type, so they are returned in their {@link buildMcpToolName} form unchanged.
+ *
+ * @param modelSegment - The model segment of the name (model type, or a per-model override).
+ * @param callType - The call type / verb.
+ * @param specifier - The specifier key, or `_` / undefined for the default entry.
+ * @returns The hyphen-joined disambiguated tool name.
+ *
+ * @example
+ * ```ts
+ * buildDisambiguatedMcpToolName('worker', 'update', 'syncCheckHqEmployee'); // 'worker-u-syncCheckHqEmployee'
+ * buildDisambiguatedMcpToolName('worker', 'create'); // 'worker-create'
+ * ```
  */
-export declare function buildMcpToolName(modelType: string, callType: string, specifier?: Maybe<string>): string;
+export declare function buildDisambiguatedMcpToolName(modelSegment: 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.
@@ -217,6 +364,32 @@ export declare function buildMcpToolName(modelType: string, callType: string, sp
  * @returns A human-readable fallback description for the tool.
  */
 export declare function buildDefaultMcpToolDescription(modelType: string, callType: string, specifier?: Maybe<string>): string;
+/**
+ * Optional naming inputs for {@link generateMcpToolDefinitions}.
+ */
+export interface McpToolGenerationNamingOptions {
+    /**
+     * Per-model override of the tool-name model segment, keyed by model type. When a model type is
+     * present, its segment (e.g. the collection prefix) replaces the model type in generated names;
+     * otherwise the model type is used.
+     */
+    readonly modelSegments?: ReadonlyMap<string, string>;
+}
+/**
+ * Optional build-time context for {@link generateMcpToolDefinitions}. Grouped into one object so the
+ * function stays at three parameters and new build-time inputs extend it rather than the arg list.
+ */
+export interface GenerateMcpToolDefinitionsContext {
+    /**
+     * Build-time manifest map supplying overrides for descriptions and input/output schemas, keyed by
+     * {@link mcpManifestKey}.
+     */
+    readonly manifest?: ReadonlyMap<string, McpManifestToolEntry>;
+    /**
+     * Per-model name segment overrides (e.g. collection prefixes).
+     */
+    readonly naming?: McpToolGenerationNamingOptions;
+}
 /**
  * Generates MCP tool definitions from a model-first API details tree.
  *
@@ -224,12 +397,20 @@ export declare function buildDefaultMcpToolDescription(modelType: string, callTy
  * `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.
+ * reported so callers can log the gap at startup. Tools whose resolved name exceeds
+ * {@link MCP_TOOL_NAME_MAX_LENGTH} are skipped so the advertised `tools/list` stays valid.
+ *
+ * Generation runs in two passes so a name clash is known before any name is finalized: the first
+ * pass plans every candidate and counts how many visible auto-named tools share each preferred name;
+ * the second builds each tool, re-deriving the colliding ones with the abbreviated call type
+ * ({@link buildDisambiguatedMcpToolName}) so both survive instead of one shadowing the other. A
+ * residual collision that disambiguation cannot resolve (e.g. an `mcp.name` override matching an auto
+ * name) drops the later tool so the dispatch map stays unambiguous.
  *
  * @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}.
+ * @param context - Optional build-time context (manifest overrides + per-model name segments).
  * @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 declare function generateMcpToolDefinitions(apiDetails: ModelApiDetailsResult, options?: JsonSchemaGenerationOptions, context?: GenerateMcpToolDefinitionsContext): McpToolGenerationResult;
 export {};

package/mcp/src/lib/service/tools/mcp.tool.batch-execute.d.ts

@@ -0,0 +1,151 @@
+import { type Request } from 'express';
+import { type StorageSlashPath, type StorageBucketId, type OnCallTypedModelParams } from '@dereekb/firebase';
+import { type FirebaseServerStorageService, type FirebaseServerAuthData } from '@dereekb/firebase-server';
+import { type Maybe } from '@dereekb/util';
+import { type McpToolDefinition, type McpToolDispatchTarget } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `batch-execute` static tool.
+ */
+export declare const BATCH_EXECUTE_TOOL_NAME = "batch-execute";
+/**
+ * Synthetic call type used in the tool's dispatch identity (analytics only — the tool re-dispatches
+ * to other callModel tools rather than resolving a `batch` call type of its own).
+ */
+export declare const BATCH_EXECUTE_DISPATCH_CALL = "batch";
+/**
+ * Synthetic model type used in the tool's dispatch identity. The tool isn't bound to a model type
+ * (each operation carries its own), so we use the literal "batch" as the identity. Apps avoiding
+ * collision should not register a real model literally named "batch".
+ */
+export declare const BATCH_EXECUTE_DISPATCH_MODEL_TYPE = "batch";
+/**
+ * Default per-operation concurrency when the caller does not specify `maxParallel`.
+ */
+export declare const DEFAULT_BATCH_EXECUTE_MAX_PARALLEL = 5;
+/**
+ * Hard upper bound on operations accepted in a single batch file, guarding against an
+ * accidentally enormous upload exhausting the function's memory/time budget.
+ */
+export declare const MAX_BATCH_EXECUTE_OPERATIONS = 1000;
+/**
+ * Maximum bytes read from the operations file. NDJSON of typical CRUD payloads stays well under
+ * this; an oversized file is rejected rather than streamed.
+ */
+export declare const MAX_BATCH_EXECUTE_FILE_BYTES: number;
+/**
+ * A single operation in the uploaded batch file — the same `(call, modelType, specifier?, data)`
+ * shape every other MCP tool ultimately dispatches.
+ */
+export type BatchExecuteOperation = OnCallTypedModelParams;
+/**
+ * Result of authorizing one operation against the caller's visible tool set.
+ *
+ * `allowed: false` carries a human-readable reason so the pre-flight error names exactly which
+ * operation is forbidden and why (unknown coordinate vs. hidden-for-this-caller).
+ */
+export type BatchOperationAuthorization = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+/**
+ * Dispatches one already-authorized operation through the callModel chain.
+ *
+ * Wired by the server factory to `ModelApiCallModelDispatchService.dispatch`, closing over the
+ * request's auth + raw request so each operation runs with the caller's identity and full
+ * per-handler param validation.
+ */
+export type BatchExecuteDispatchFn = (operation: OnCallTypedModelParams, auth: Maybe<FirebaseServerAuthData>, rawRequest: Request) => Promise<unknown>;
+/**
+ * Constructor dependencies for {@link createBatchExecuteTool}.
+ */
+export interface CreateBatchExecuteToolDeps {
+    /**
+     * Reads the uploaded operations file from storage.
+     */
+    readonly storageService: FirebaseServerStorageService;
+    /**
+     * Re-dispatches a single operation through the callModel chain.
+     */
+    readonly dispatch: BatchExecuteDispatchFn;
+    /**
+     * Authorizes one operation against the request's visible tool set. Provided by the factory so the
+     * check uses the same scope / role / read-only filtering already applied to `tools/list`.
+     */
+    readonly authorizeOperation: (operation: OnCallTypedModelParams) => BatchOperationAuthorization;
+    /**
+     * Overrides the maximum number of operations accepted per batch. Defaults to
+     * {@link MAX_BATCH_EXECUTE_OPERATIONS}.
+     */
+    readonly maxOperations?: number;
+}
+/**
+ * Shape of the `batch-execute` tool input.
+ */
+export interface BatchExecuteToolInput {
+    readonly uploadPath: StorageSlashPath;
+    readonly bucketId?: StorageBucketId;
+    readonly format: 'json' | 'ndjson';
+    readonly maxParallel: number;
+    readonly stopOnError: boolean;
+    readonly deleteUploadOnSuccess: boolean;
+}
+/**
+ * Per-operation failure entry in the batch summary, carrying the original file index so the caller
+ * can map a failure back to the line/element that produced it.
+ */
+export interface BatchExecuteErrorEntry {
+    readonly index: number;
+    readonly modelType: string;
+    readonly call?: string;
+    readonly specifier?: string;
+    readonly message: string;
+}
+/**
+ * Aggregate batch summary returned to the MCP client. Intentionally omits per-operation success
+ * payloads — only counts plus the failure list cross the wire, so 100 operations collapse to one
+ * compact result instead of 100 result blobs.
+ *
+ * `successCount + failureCount + skippedCount === total`. `skippedCount` is non-zero only when
+ * `stopOnError` halted the run before every operation was attempted.
+ */
+export interface BatchExecuteToolResult {
+    readonly total: number;
+    readonly successCount: number;
+    readonly failureCount: number;
+    readonly skippedCount: number;
+    readonly errors: ReadonlyArray<BatchExecuteErrorEntry>;
+    readonly uploadDeleted: boolean;
+}
+/**
+ * Builds the lookup key identifying a callModel dispatch coordinate. The factory indexes the
+ * caller's visible callModel tools by this key; the batch handler looks each operation up by the
+ * same key, so authorization reuses the exact tool set advertised on `tools/list`.
+ *
+ * @param dispatch - The `(call, modelType, specifier?)` coordinate to key.
+ * @returns A stable string key. Uses a NUL separator so segment values can't collide.
+ */
+export declare function batchOperationCoordKey(dispatch: Pick<McpToolDispatchTarget, 'call' | 'modelType' | 'specifier'>): string;
+/**
+ * Builds the built-in `batch-execute` MCP tool definition.
+ *
+ * The tool ingests an uploaded JSON / NDJSON file of `(call, modelType, specifier?, data)`
+ * operations and runs them server-side, returning a single success/failure summary. It exists so an
+ * agent can perform a bulk mutation (e.g. "update 200 workers") by *generating* the operations file
+ * with a script and uploading it — rather than emitting each payload as tool-call output and paying
+ * one model turn per record.
+ *
+ * Safety model:
+ * - Every operation is validated and authorized against the caller's visible tool set *before any
+ *   dispatch*. A malformed or forbidden operation aborts the whole batch with a pre-flight error and
+ *   nothing runs — `dispatch` would otherwise bypass the `tools/list` visibility filter.
+ * - Runtime failures are best-effort by default (collected into the summary); `stopOnError` halts at
+ *   the first failure (forcing sequential execution).
+ *
+ * @param deps - Storage reader, dispatch fn, and per-operation authorizer (typically wired in the
+ *   server factory to the request's visible tool set).
+ * @returns A statically-registered {@link McpToolDefinition} ready to be appended to the MCP server
+ *   factory's tool registry.
+ */
+export declare function createBatchExecuteTool(deps: CreateBatchExecuteToolDeps): McpToolDefinition;

package/model/package.json

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