@dereekb/firebase-server 13.14.0 → 13.16.0

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.14.0",
+  "version": "13.16.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.14.0",
-    "@dereekb/date": "13.14.0",
-    "@dereekb/firebase": "13.14.0",
-    "@dereekb/firebase-server": "13.14.0",
-    "@dereekb/firebase-server/oidc": "13.14.0",
-    "@dereekb/model": "13.14.0",
-    "@dereekb/nestjs": "13.14.0",
-    "@dereekb/rxjs": "13.14.0",
-    "@dereekb/util": "13.14.0",
-    "@dereekb/zoho": "13.14.0",
+    "@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",
     "@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.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.
      *
@@ -89,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/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;