@dereekb/firebase-server 13.12.1 → 13.12.2

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.12.1",
+  "version": "13.12.2",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.1",
-    "@dereekb/date": "13.12.1",
-    "@dereekb/firebase": "13.12.1",
-    "@dereekb/firebase-server": "13.12.1",
-    "@dereekb/firebase-server/oidc": "13.12.1",
-    "@dereekb/model": "13.12.1",
-    "@dereekb/nestjs": "13.12.1",
-    "@dereekb/rxjs": "13.12.1",
-    "@dereekb/util": "13.12.1",
-    "@dereekb/zoho": "13.12.1",
+    "@dereekb/analytics": "13.12.2",
+    "@dereekb/date": "13.12.2",
+    "@dereekb/firebase": "13.12.2",
+    "@dereekb/firebase-server": "13.12.2",
+    "@dereekb/firebase-server/oidc": "13.12.2",
+    "@dereekb/model": "13.12.2",
+    "@dereekb/nestjs": "13.12.2",
+    "@dereekb/rxjs": "13.12.2",
+    "@dereekb/util": "13.12.2",
+    "@dereekb/zoho": "13.12.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",

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

@@ -14,6 +14,11 @@ export declare const DEFAULT_MCP_PATH = "/mcp";
  * deployment (e.g., `demo-api-mcp`, `hellosubs-api-mcp`).
  */
 export declare const DEFAULT_MCP_SERVER_NAME = "dbx-firebase-server-mcp";
+/**
+ * Default `instructions` string advertised by the MCP server on the JSON-RPC `initialize`
+ * handshake. Apps may override this via {@link McpModuleConfig.serverInstructions}.
+ */
+export declare const DEFAULT_MCP_SERVER_INSTRUCTIONS = "A set of call-model tools generated automatically.";
 /**
  * Configuration for the firebase-server/mcp module.
  *
@@ -58,6 +63,12 @@ export declare abstract class McpModuleConfig {
      * Optional version advertised on the MCP `initialize` handshake.
      */
     readonly serverVersion?: string;
+    /**
+     * Optional override for the `instructions` string passed to `new McpServer(...)` and
+     * advertised on the JSON-RPC `initialize` handshake. Defaults to
+     * {@link DEFAULT_MCP_SERVER_INSTRUCTIONS}.
+     */
+    readonly serverInstructions?: string;
     /**
      * Absolute path to a pre-rendered MCP manifest JSON file produced by
      * `dbx-cli-generate-mcp-manifest`. When set, the runtime reads it once at

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

@@ -0,0 +1,4 @@
+export * from './mcp.analytics.config';
+export * from './mcp.analytics.handler';
+export * from './mcp.analytics.module';
+export * from './mcp.analytics.service';

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

@@ -0,0 +1,34 @@
+import { type InjectionToken } from '@nestjs/common';
+/**
+ * Default analytics event name used by {@link FirebaseServerMcpAnalyticsService} when
+ * forwarding a completed MCP tool call to the downstream analytics pipeline.
+ */
+export declare const DEFAULT_MCP_ANALYTICS_EVENT_NAME = "mcp-tool";
+/**
+ * Configuration for {@link FirebaseServerMcpAnalyticsService}.
+ *
+ * Apps provide this via {@link FIREBASE_SERVER_MCP_ANALYTICS_CONFIG} (typically through
+ * {@link appMcpAnalyticsModuleMetadata}) to tune how completed MCP tool calls are logged
+ * and forwarded.
+ */
+export interface FirebaseServerMcpAnalyticsConfig {
+    /**
+     * The analytics event name forwarded to the app's `FirebaseServerAnalyticsService`.
+     * Defaults to {@link DEFAULT_MCP_ANALYTICS_EVENT_NAME}.
+     */
+    readonly eventName?: string;
+    /**
+     * Whether to emit a per-call `Logger` line for each completed tool call. Defaults to `true`.
+     */
+    readonly logEvents?: boolean;
+}
+/**
+ * NestJS injection token for the optional {@link FirebaseServerMcpAnalyticsConfig} provider.
+ *
+ * @example
+ * ```typescript
+ * @Module(appMcpAnalyticsModuleMetadata({ mcpAnalyticsConfig: { eventName: 'mcp-tool', logEvents: true } }))
+ * export class AppMcpAnalyticsModule {}
+ * ```
+ */
+export declare const FIREBASE_SERVER_MCP_ANALYTICS_CONFIG: InjectionToken<FirebaseServerMcpAnalyticsConfig>;

package/mcp/src/lib/service/analytics/mcp.analytics.handler.d.ts

@@ -0,0 +1,100 @@
+import { type InjectionToken } from '@nestjs/common';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
+import { type FirebaseServerAuthData } from '@dereekb/firebase-server';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Structured analytics event emitted once per completed MCP tool invocation.
+ *
+ * Captures the full context of a single MCP tool invocation — the tool, its dispatch
+ * coordinates, the outcome (success vs. error and the thrown error), the authenticated
+ * caller, and the read-only mode.
+ *
+ * MCP-transport scoped and complementary to the model-handler `OnCallModelAnalyticsEvent`,
+ * which continues to fire inside the callModel dispatch chain for callModel-backed tools.
+ *
+ * Consumed by {@link McpAnalyticsService} implementations registered under {@link MCP_ANALYTICS_SERVICE}.
+ */
+export interface McpAnalyticsEvent {
+    /**
+     * The event identity — the dispatched tool name (e.g., `'guestbook-create'`).
+     */
+    readonly event: string;
+    /**
+     * Whether the tool call completed successfully. `false` when the resolved outcome carried a
+     * thrown error or the response was flagged `isError`.
+     */
+    readonly isSuccessful: boolean;
+    /**
+     * The dispatched tool name. Mirrors {@link event}, kept explicit for clarity at the consumer.
+     */
+    readonly toolName: string;
+    /**
+     * Whether the tool routes through the callModel dispatch chain or is a static built-in tool
+     * (e.g., `model-get`, `whoami`).
+     */
+    readonly toolKind: 'callModel' | 'static';
+    /**
+     * The CRUD operation type for callModel-backed tools (e.g., `'create'`, `'read'`).
+     */
+    readonly call?: Maybe<string>;
+    /**
+     * The model type for callModel-backed tools (e.g., `'guestbook'`).
+     */
+    readonly modelType?: Maybe<string>;
+    /**
+     * The operation specifier for variant handlers, when present.
+     */
+    readonly specifier?: Maybe<string>;
+    /**
+     * The Firebase Auth UID of the calling user, if authenticated.
+     */
+    readonly uid?: Maybe<FirebaseAuthUserId>;
+    /**
+     * The full MCP request auth context, if available.
+     */
+    readonly auth?: Maybe<FirebaseServerAuthData>;
+    /**
+     * Whether the MCP server is running in read-only mode.
+     */
+    readonly readOnly?: Maybe<boolean>;
+    /**
+     * The raw tool arguments passed to the call.
+     */
+    readonly args?: Maybe<Record<string, unknown>>;
+    /**
+     * Custom key-value properties. Reserved for future use.
+     */
+    readonly properties?: Maybe<Record<string, any>>;
+    /**
+     * The thrown error, when the call failed ({@link isSuccessful} is `false`).
+     */
+    readonly error?: Maybe<unknown>;
+    /**
+     * Wall-clock duration in milliseconds from dispatch start to completion.
+     */
+    readonly durationMs?: Maybe<number>;
+}
+/**
+ * Abstract analytics service that apps implement to process MCP analytics events.
+ *
+ * Analogous to {@link OnCallModelAnalyticsService} but scoped to the MCP transport.
+ * Apps extend this class and provide it via {@link MCP_ANALYTICS_SERVICE}.
+ */
+export declare abstract class McpAnalyticsService {
+    abstract handleMcpAnalyticsEvent(event: McpAnalyticsEvent): void;
+}
+/**
+ * Injection token for the MCP analytics service.
+ * Apps provide this in their MCP module to enable analytics in the MCP dispatch chain.
+ */
+export declare const MCP_ANALYTICS_SERVICE: InjectionToken<McpAnalyticsService>;
+/**
+ * Creates a no-op {@link McpAnalyticsService} that silently discards all events.
+ *
+ * Used as the default fallback by {@link McpServerFactoryService} when no analytics
+ * service is registered.
+ *
+ * @returns An {@link McpAnalyticsService} that discards all analytics events.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function noopMcpAnalyticsService(): McpAnalyticsService;

package/mcp/src/lib/service/analytics/mcp.analytics.module.d.ts

@@ -0,0 +1,35 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
+import { type FirebaseServerMcpAnalyticsConfig } from './mcp.analytics.config';
+/**
+ * Configuration for {@link appMcpAnalyticsModuleMetadata}.
+ */
+export interface AppMcpAnalyticsMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Optional {@link FirebaseServerMcpAnalyticsConfig} provided under
+     * {@link FIREBASE_SERVER_MCP_ANALYTICS_CONFIG}. When omitted, the service uses its defaults.
+     */
+    readonly mcpAnalyticsConfig?: Maybe<FirebaseServerMcpAnalyticsConfig>;
+}
+/**
+ * Generates NestJS module metadata that registers {@link FirebaseServerMcpAnalyticsService} as the
+ * MCP analytics consumer, aliased to {@link MCP_ANALYTICS_SERVICE}.
+ *
+ * Mirrors the convention used by `appAnalyticsModuleMetadata`. Unlike `mcpModuleMetadata`, this
+ * requires no dependency module — `FirebaseServerAnalyticsService` is resolved optionally and is
+ * expected to be supplied globally by the app's analytics module.
+ *
+ * Decorate a `@Global()` module with the result so the `MCP_ANALYTICS_SERVICE` token is visible to
+ * the `McpServerFactoryService` provided by the app's MCP module.
+ *
+ * @param config - Optional metadata + analytics config to merge in.
+ * @returns NestJS module metadata providing + exporting the MCP analytics service and token.
+ *
+ * @example
+ * ```typescript
+ * @Global()
+ * @Module(appMcpAnalyticsModuleMetadata())
+ * export class AppMcpAnalyticsModule {}
+ * ```
+ */
+export declare function appMcpAnalyticsModuleMetadata(config?: AppMcpAnalyticsMetadataConfig): ModuleMetadata;

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

@@ -0,0 +1,20 @@
+import { FirebaseServerAnalyticsService } from '@dereekb/firebase-server';
+import { McpAnalyticsService, type McpAnalyticsEvent } from './mcp.analytics.handler';
+import { type FirebaseServerMcpAnalyticsConfig } from './mcp.analytics.config';
+/**
+ * Reusable {@link McpAnalyticsService} that forwards each completed MCP tool call to the app's
+ * {@link FirebaseServerAnalyticsService}, so MCP-transport analytics feed the same downstream
+ * pipeline (e.g. Segment) as model analytics.
+ *
+ * Registered globally via {@link appMcpAnalyticsModuleMetadata}; tuned via
+ * {@link FirebaseServerMcpAnalyticsConfig}. When no analytics service is available the call is a
+ * no-op aside from the optional log line.
+ */
+export declare class FirebaseServerMcpAnalyticsService extends McpAnalyticsService {
+    private readonly analyticsService?;
+    private readonly _logger;
+    private readonly _eventName;
+    private readonly _logEvents;
+    constructor(analyticsService?: FirebaseServerAnalyticsService | undefined, config?: FirebaseServerMcpAnalyticsConfig);
+    handleMcpAnalyticsEvent(event: McpAnalyticsEvent): void;
+}

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

@@ -1,3 +1,4 @@
+export * from './analytics';
 export * from './mcp.manifest';
 export * from './mcp.response-formatter';
 export * from './mcp.server.factory';

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

@@ -2,6 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Request } from 'express';
 import { ModelApiCallModelDispatchService, ModelApiGetService, type FirebaseServerAuthData } from '@dereekb/firebase-server';
 import { McpModuleConfig, type McpAuthRoleReader } from '../mcp.config';
+import { type McpAnalyticsService } from './analytics/mcp.analytics.handler';
 /**
  * Optional per-request context passed when invoking the MCP server through a
  * Streamable HTTP transport. Carries the authenticated user (already extracted
@@ -34,7 +35,8 @@ export declare class McpServerFactoryService {
     private _manifestLoaded;
     private _loggedSkips;
     private _warnedMissingRoleReader;
-    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined);
+    private readonly _analyticsService;
+    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined, analyticsService?: McpAnalyticsService);
     /**
      * Builds a configured MCP server with tool listing + dispatch handlers wired up.
      *
@@ -118,7 +120,29 @@ export declare class McpServerFactoryService {
      * @returns The wire-shape entry to emit for this tool on `tools/list`.
      */
     private _buildToolListEntry;
+    /**
+     * Central dispatch point for every MCP tool call. Runs the underlying handler — callModel,
+     * static, or unknown-tool — then emits a single analytics event on completion so every call
+     * is tracked uniformly.
+     *
+     * Success vs error is decided by the resolved outcome: an outcome that carries a thrown
+     * error, or a response flagged `isError`, counts as a failure. The original thrown error
+     * (when present) is forwarded on the event.
+     *
+     * @param request - The `tools/call` request carrying the tool name and arguments.
+     * @param definitionsByName - The visible tool definitions keyed by name for this request.
+     * @param ctx - The per-request context (auth, raw request) forwarded to the handler.
+     * @returns The MCP tool response.
+     */
     private _handleToolCall;
+    /**
+     * Forwards an event to the registered {@link McpAnalyticsService}, swallowing any failure so
+     * a faulty analytics implementation can never break tool dispatch (fail-soft, matching the
+     * visibility-predicate guards above).
+     *
+     * @param event - The MCP analytics event to forward.
+     */
+    private _emitMcpAnalytics;
     private _handleStaticToolCall;
     private _handleCallModelToolCall;
 }

package/model/package.json

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

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.12.1",
+  "version": "13.12.2",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.1",
-    "@dereekb/date": "13.12.1",
-    "@dereekb/firebase": "13.12.1",
-    "@dereekb/firebase-server": "13.12.1",
-    "@dereekb/model": "13.12.1",
-    "@dereekb/nestjs": "13.12.1",
-    "@dereekb/rxjs": "13.12.1",
-    "@dereekb/util": "13.12.1",
-    "@dereekb/zoho": "13.12.1",
+    "@dereekb/analytics": "13.12.2",
+    "@dereekb/date": "13.12.2",
+    "@dereekb/firebase": "13.12.2",
+    "@dereekb/firebase-server": "13.12.2",
+    "@dereekb/model": "13.12.2",
+    "@dereekb/nestjs": "13.12.2",
+    "@dereekb/rxjs": "13.12.2",
+    "@dereekb/util": "13.12.2",
+    "@dereekb/zoho": "13.12.2",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.12.1",
+  "version": "13.12.2",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -56,15 +56,15 @@
   "main": "./index.cjs.js",
   "types": "./src/index.d.ts",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.1",
-    "@dereekb/date": "13.12.1",
-    "@dereekb/dbx-core": "13.12.1",
-    "@dereekb/firebase": "13.12.1",
-    "@dereekb/model": "13.12.1",
-    "@dereekb/nestjs": "13.12.1",
-    "@dereekb/rxjs": "13.12.1",
-    "@dereekb/util": "13.12.1",
-    "@dereekb/zoho": "13.12.1",
+    "@dereekb/analytics": "13.12.2",
+    "@dereekb/date": "13.12.2",
+    "@dereekb/dbx-core": "13.12.2",
+    "@dereekb/firebase": "13.12.2",
+    "@dereekb/model": "13.12.2",
+    "@dereekb/nestjs": "13.12.2",
+    "@dereekb/rxjs": "13.12.2",
+    "@dereekb/util": "13.12.2",
+    "@dereekb/zoho": "13.12.2",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.12.1",
+  "version": "13.12.2",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.1",
-    "@dereekb/date": "13.12.1",
-    "@dereekb/firebase": "13.12.1",
-    "@dereekb/firebase-server": "13.12.1",
-    "@dereekb/firebase-server/oidc": "13.12.1",
-    "@dereekb/model": "13.12.1",
-    "@dereekb/nestjs": "13.12.1",
-    "@dereekb/rxjs": "13.12.1",
-    "@dereekb/util": "13.12.1",
+    "@dereekb/analytics": "13.12.2",
+    "@dereekb/date": "13.12.2",
+    "@dereekb/firebase": "13.12.2",
+    "@dereekb/firebase-server": "13.12.2",
+    "@dereekb/firebase-server/oidc": "13.12.2",
+    "@dereekb/model": "13.12.2",
+    "@dereekb/nestjs": "13.12.2",
+    "@dereekb/rxjs": "13.12.2",
+    "@dereekb/util": "13.12.2",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -23,7 +23,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.12.1"
+    "@dereekb/nestjs": "13.12.2"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.12.1",
+  "version": "13.12.2",
   "peerDependencies": {
-    "@dereekb/date": "13.12.1",
-    "@dereekb/firebase": "13.12.1",
-    "@dereekb/firebase-server": "13.12.1",
-    "@dereekb/model": "13.12.1",
-    "@dereekb/nestjs": "13.12.1",
-    "@dereekb/rxjs": "13.12.1",
-    "@dereekb/util": "13.12.1"
+    "@dereekb/date": "13.12.2",
+    "@dereekb/firebase": "13.12.2",
+    "@dereekb/firebase-server": "13.12.2",
+    "@dereekb/model": "13.12.2",
+    "@dereekb/nestjs": "13.12.2",
+    "@dereekb/rxjs": "13.12.2",
+    "@dereekb/util": "13.12.2"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.12.1",
+  "version": "13.12.2",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.1",
-    "@dereekb/date": "13.12.1",
-    "@dereekb/model": "13.12.1",
-    "@dereekb/nestjs": "13.12.1",
-    "@dereekb/rxjs": "13.12.1",
-    "@dereekb/firebase": "13.12.1",
-    "@dereekb/util": "13.12.1",
-    "@dereekb/zoho": "13.12.1"
+    "@dereekb/analytics": "13.12.2",
+    "@dereekb/date": "13.12.2",
+    "@dereekb/model": "13.12.2",
+    "@dereekb/nestjs": "13.12.2",
+    "@dereekb/rxjs": "13.12.2",
+    "@dereekb/firebase": "13.12.2",
+    "@dereekb/util": "13.12.2",
+    "@dereekb/zoho": "13.12.2"
   },
   "exports": {
     "./package.json": "./package.json",