@dereekb/firebase-server 13.12.1 → 13.12.3

package/mcp/index.cjs.js

@@ -12,12 +12,12 @@ var model = require('@dereekb/model');
 var firebase = require('@dereekb/firebase');
 var streamableHttp_js = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
 
-function _class_call_check$3(instance, Constructor) {
+function _class_call_check$5(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function _define_property$6(obj, key, value) {
+function _define_property$7(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -43,6 +43,10 @@ function _define_property$6(obj, key, value) {
  * Apps may override this via {@link McpModuleConfig.serverName} to identify their
  * deployment (e.g., `demo-api-mcp`, `hellosubs-api-mcp`).
  */ var 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}.
+ */ var DEFAULT_MCP_SERVER_INSTRUCTIONS = 'A set of call-model tools generated automatically.';
 /**
  * Configuration for the firebase-server/mcp module.
  *
@@ -59,7 +63,7 @@ function _define_property$6(obj, key, value) {
  * The OAuth bearer middleware that authenticates `/mcp` is configured on
  * {@link OidcModuleConfig.protectedPaths} — that's outside this config's scope.
  */ var McpModuleConfig = function McpModuleConfig() {
-    _class_call_check$3(this, McpModuleConfig);
+    _class_call_check$5(this, McpModuleConfig);
     /**
      * The canonical issuer URL of the OIDC provider that gates this MCP endpoint.
      *
@@ -67,7 +71,7 @@ function _define_property$6(obj, key, value) {
      * discovery document. Claude custom-connector reads this to discover the OIDC issuer.
      *
      * @example 'https://api.example.com/oidc'
-     */ _define_property$6(this, "oidcIssuer", void 0);
+     */ _define_property$7(this, "oidcIssuer", void 0);
     /**
      * The canonical resource URL of the MCP endpoint.
      *
@@ -75,14 +79,19 @@ function _define_property$6(obj, key, value) {
      * and used as the audience the access token's `aud` claim should match.
      *
      * @example 'https://api.example.com/mcp'
-     */ _define_property$6(this, "mcpUrl", void 0);
+     */ _define_property$7(this, "mcpUrl", void 0);
     /**
      * Optional name advertised on the MCP `initialize` handshake. Defaults to
      * {@link DEFAULT_MCP_SERVER_NAME}.
-     */ _define_property$6(this, "serverName", void 0);
+     */ _define_property$7(this, "serverName", void 0);
     /**
      * Optional version advertised on the MCP `initialize` handshake.
-     */ _define_property$6(this, "serverVersion", void 0);
+     */ _define_property$7(this, "serverVersion", void 0);
+    /**
+     * 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}.
+     */ _define_property$7(this, "serverInstructions", void 0);
     /**
      * 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
@@ -92,7 +101,7 @@ function _define_property$6(obj, key, value) {
      * Optional. When unset or the file is missing, the runtime falls back to
      * today's behavior (auto-generated descriptions, ArkType-derived input
      * schemas, no output schemas) and emits a single boot warning.
-     */ _define_property$6(this, "mcpManifestPath", void 0);
+     */ _define_property$7(this, "mcpManifestPath", void 0);
     /**
      * When `true`, the MCP server only advertises tools whose effective read-only classification is `true`.
      *
@@ -102,19 +111,19 @@ function _define_property$6(obj, key, value) {
      *
      * The advertised `serverName` on the JSON-RPC `initialize` handshake is suffixed with
      * ` (read-only)` so the client surface reflects the mode.
-     */ _define_property$6(this, "readOnly", void 0);
+     */ _define_property$7(this, "readOnly", void 0);
 };
 /**
  * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
  */ var MCP_AUTH_ROLE_READER = 'MCP_AUTH_ROLE_READER';
 
-function _type_of$1(obj) {
+function _type_of$2(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
 function __decorate(decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if ((typeof Reflect === "undefined" ? "undefined" : _type_of$1(Reflect)) === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    if ((typeof Reflect === "undefined" ? "undefined" : _type_of$2(Reflect)) === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
@@ -128,6 +137,39 @@ typeof SuppressedError === "function" ? SuppressedError : function(error, suppre
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+function _class_call_check$4(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+/**
+ * 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}.
+ */ var McpAnalyticsService = function McpAnalyticsService() {
+    _class_call_check$4(this, McpAnalyticsService);
+};
+/**
+ * Injection token for the MCP analytics service.
+ * Apps provide this in their MCP module to enable analytics in the MCP dispatch chain.
+ */ var MCP_ANALYTICS_SERVICE = 'MCP_ANALYTICS_SERVICE';
+/**
+ * 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__
+ */ function noopMcpAnalyticsService() {
+    return {
+        handleMcpAnalyticsEvent: function handleMcpAnalyticsEvent() {
+            return undefined;
+        }
+    };
+}
+
 /**
  * Version stamp embedded in the build-time MCP manifest JSON. Runtime loaders
  * refuse manifests whose `version` does not match this constant.
@@ -315,7 +357,7 @@ function stringifyResult(result) {
     return firebase.callModelOidcScopeForCallType(callType);
 }
 
-function _array_like_to_array$4(arr, len) {
+function _array_like_to_array$6(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
@@ -351,19 +393,19 @@ function _non_iterable_rest$2() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 function _sliced_to_array$2(arr, i) {
-    return _array_with_holes$2(arr) || _iterable_to_array_limit$2(arr, i) || _unsupported_iterable_to_array$4(arr, i) || _non_iterable_rest$2();
+    return _array_with_holes$2(arr) || _iterable_to_array_limit$2(arr, i) || _unsupported_iterable_to_array$6(arr, i) || _non_iterable_rest$2();
 }
-function _type_of(obj) {
+function _type_of$1(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
-function _unsupported_iterable_to_array$4(o, minLen) {
+function _unsupported_iterable_to_array$6(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$4(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$6(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$4(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$6(o, minLen);
 }
 /**
  * Default `toJsonSchema()` options.
@@ -630,7 +672,7 @@ function resolveInputSchema(context) {
     var result;
     try {
         var exported = model.arktypeToJsonSchemaForExport(handlerDetails.inputType);
-        if (exported && (typeof exported === "undefined" ? "undefined" : _type_of(exported)) === 'object') {
+        if (exported && (typeof exported === "undefined" ? "undefined" : _type_of$1(exported)) === 'object') {
             result = exported;
         } else {
             // arktypeToJsonSchemaForExport returned a non-object (shouldn't happen for object schemas).
@@ -649,13 +691,13 @@ function resolveInputSchema(context) {
     return result;
 }
 
-function _array_like_to_array$3(arr, len) {
+function _array_like_to_array$5(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes$3(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$3(arr);
+function _array_without_holes$5(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$5(arr);
 }
 function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
     try {
@@ -686,22 +728,22 @@ function _async_to_generator$3(fn) {
         });
     };
 }
-function _iterable_to_array$3(iter) {
+function _iterable_to_array$5(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread$3() {
+function _non_iterable_spread$5() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _to_consumable_array$3(arr) {
-    return _array_without_holes$3(arr) || _iterable_to_array$3(arr) || _unsupported_iterable_to_array$3(arr) || _non_iterable_spread$3();
+function _to_consumable_array$5(arr) {
+    return _array_without_holes$5(arr) || _iterable_to_array$5(arr) || _unsupported_iterable_to_array$5(arr) || _non_iterable_spread$5();
 }
-function _unsupported_iterable_to_array$3(o, minLen) {
+function _unsupported_iterable_to_array$5(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$3(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$5(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$3(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$5(o, minLen);
 }
 function _ts_generator$3(thisArg, body) {
     var f, y, t, _ = {
@@ -1006,8 +1048,8 @@ function readInChunks(input) {
                     ];
                 case 2:
                     partial = _state.sent();
-                    (_merged_results = merged.results).push.apply(_merged_results, _to_consumable_array$3(partial.results));
-                    (_merged_errors = merged.errors).push.apply(_merged_errors, _to_consumable_array$3(partial.errors));
+                    (_merged_results = merged.results).push.apply(_merged_results, _to_consumable_array$5(partial.results));
+                    (_merged_errors = merged.errors).push.apply(_merged_errors, _to_consumable_array$5(partial.errors));
                     _state.label = 3;
                 case 3:
                     offset += MCP_MODEL_GET_BATCH_SIZE;
@@ -1098,7 +1140,15 @@ var MODEL_GET_OUTPUT_SCHEMA = {
     }
 };
 
-function _define_property$5(obj, key, value) {
+function _array_like_to_array$4(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes$4(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$4(arr);
+}
+function _define_property$6(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -1111,6 +1161,12 @@ function _define_property$5(obj, key, value) {
     }
     return obj;
 }
+function _iterable_to_array$4(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread$4() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
 function _object_spread$2(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
@@ -1121,11 +1177,41 @@ function _object_spread$2(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$5(target, key, source[key]);
+            _define_property$6(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
         });
     }
     return target;
 }
+function _to_consumable_array$4(arr) {
+    return _array_without_holes$4(arr) || _iterable_to_array$4(arr) || _unsupported_iterable_to_array$4(arr) || _non_iterable_spread$4();
+}
+function _unsupported_iterable_to_array$4(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$4(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$4(o, minLen);
+}
 // MARK: Constants
 /**
  * Reserved tool name for the built-in `model-info` static tool.
@@ -1138,13 +1224,27 @@ function _object_spread$2(target) {
  * 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".
  */ var MODEL_INFO_DISPATCH_MODEL_TYPE = 'model';
+/**
+ * Group label applied to manifest entries that declare no `modelGroup`. Keeps the `groups` mode
+ * total reconcilable with the catalog size (sum of group counts always equals `totalModels`).
+ */ var MODEL_INFO_UNGROUPED_LABEL = '(ungrouped)';
+/**
+ * Hint string surfaced alongside the default `groups` response so callers know how to drill in.
+ */ var MODEL_INFO_GROUPS_HINT = 'Pass `model` for one/many models, `modelGroup` for a group, or `all:true` for the full catalog.';
 // MARK: Factory
 /**
  * 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.
+ * Modes (selected by input):
+ * - No args: returns model groups + counts (`mode: 'groups'`) — the cheap default for browsing.
+ * - `model` (string): returns the full entry for one model (`mode: 'single'`).
+ * - `model` (string array): returns full detail per match (`mode: 'multiple'`); misses land in `notFound`.
+ * - `modelGroup`: returns the summary list of that group's models (`mode: 'list'`).
+ * - `all: true`: returns the full catalog summary (`mode: 'list'`).
+ * - `fields`: forces (`true`) or suppresses (`false`) full persisted-field detail in list/multiple modes.
+ *
+ * Each `model` query matches by `modelType`, `identityConst`, or `collectionPrefix`. When several
+ * params are supplied, precedence is `model` > `modelGroup` > `all` > the default `groups` view.
  *
  * Output is delivered as both stringified JSON in `content[0].text` and `structuredContent`
  * so MCP clients can consume either form.
@@ -1157,7 +1257,8 @@ function _object_spread$2(target) {
         return Promise.resolve(modelInfoToolHandler(args, ctx, deps));
     };
     var name = MODEL_INFO_TOOL_NAME;
-    var description = "Browse the Firestore model catalog (".concat(deps.manifest.length, " model").concat(deps.manifest.length === 1 ? '' : 's', "). Without `model`, returns a summary list of every model. With `model` (matched by modelType, identityConst, or collectionPrefix), returns the full entry with persisted fields.");
+    var count = deps.manifest.length;
+    var description = "Browse the Firestore model catalog (".concat(count, " model").concat(count === 1 ? '' : 's', "). No args returns model groups + counts (start here). ") + '`model` (a modelType/identityConst/collectionPrefix string, or an array of them) returns full detail per match — misses are reported in `notFound`. ' + '`modelGroup` returns the summary list for that group. `all:true` returns the full catalog summary. ' + '`fields` (boolean) forces or suppresses persisted-field detail in list/multiple modes.';
     return {
         name: name,
         description: description,
@@ -1188,7 +1289,7 @@ function modelInfoToolHandler(args, _ctx, deps) {
     var result;
     try {
         var input = parseModelInfoInput(args);
-        var output = input.model == null ? buildListOutput(deps.manifest) : buildSingleOutput(input.model, deps.manifest);
+        var output = resolveModelInfoOutput(input, deps.manifest);
         result = {
             content: [
                 {
@@ -1203,60 +1304,285 @@ function modelInfoToolHandler(args, _ctx, deps) {
     }
     return result;
 }
+function resolveModelInfoOutput(input, manifest) {
+    var output;
+    if (input.modelQueries != null) {
+        output = buildModelLookupOutput({
+            queries: input.modelQueries,
+            isArray: input.modelIsArray,
+            manifest: manifest,
+            fields: input.fields
+        });
+    } else if (input.modelGroup != null) {
+        output = buildGroupFilterOutput({
+            group: input.modelGroup,
+            manifest: manifest,
+            fields: input.fields
+        });
+    } else if (input.all) {
+        output = buildAllOutput(manifest, input.fields);
+    } else {
+        output = buildGroupsOutput(manifest);
+    }
+    return output;
+}
+// MARK: Input parsing
 function parseModelInfoInput(args) {
-    var raw = args['model'];
-    var model;
+    var modelQueries = parseModelArg(args['model']);
+    var modelGroup = parseModelGroupArg(args['modelGroup']);
+    var all = parseBooleanArg(args['all'], 'all');
+    var fields = parseBooleanArg(args['fields'], 'fields');
+    return _object_spread$2(_object_spread_props(_object_spread$2(_object_spread_props(_object_spread$2({}, modelQueries == null ? {} : {
+        modelQueries: modelQueries
+    }), {
+        modelIsArray: Array.isArray(args['model'])
+    }), modelGroup == null ? {} : {
+        modelGroup: modelGroup
+    }), {
+        all: all !== null && all !== void 0 ? all : false
+    }), fields == null ? {} : {
+        fields: fields
+    });
+}
+function parseModelArg(raw) {
+    var result;
     if (raw == null) {
-        model = undefined;
+        result = undefined;
     } else if (typeof raw === 'string') {
-        var trimmed = raw.trim();
-        if (trimmed.length === 0) {
-            throw new Error('model-info: "model" must be a non-empty string when provided.');
+        result = [
+            requireNonEmptyString(raw, 'model')
+        ];
+    } else if (Array.isArray(raw)) {
+        if (raw.length === 0) {
+            throw new Error('model-info: "model" array must contain at least one entry.');
         }
-        model = trimmed;
+        result = raw.map(function(value, index) {
+            return requireNonEmptyString(value, "model[".concat(index, "]"));
+        });
+    } else {
+        throw new TypeError('model-info: "model" must be a string or an array of strings when provided.');
+    }
+    return result;
+}
+function parseModelGroupArg(raw) {
+    var result;
+    if (raw == null) {
+        result = undefined;
+    } else if (typeof raw === 'string') {
+        result = requireNonEmptyString(raw, 'modelGroup');
     } else {
-        throw new TypeError('model-info: "model" must be a string when provided.');
+        throw new TypeError('model-info: "modelGroup" must be a string when provided.');
+    }
+    return result;
+}
+function parseBooleanArg(raw, label) {
+    var result;
+    if (raw == null) {
+        result = undefined;
+    } else if (typeof raw === 'boolean') {
+        result = raw;
+    } else {
+        throw new TypeError('model-info: "'.concat(label, '" must be a boolean when provided.'));
+    }
+    return result;
+}
+function requireNonEmptyString(value, label) {
+    if (typeof value !== 'string') {
+        throw new TypeError('model-info: "'.concat(label, '" must be a string.'));
     }
+    var trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error('model-info: "'.concat(label, '" must be a non-empty string.'));
+    }
+    return trimmed;
+}
+// MARK: Output builders
+function buildGroupsOutput(manifest) {
     return {
-        model: model
+        mode: 'groups',
+        groups: computeGroupCounts(manifest),
+        totalModels: manifest.length,
+        hint: MODEL_INFO_GROUPS_HINT
     };
 }
-function buildListOutput(manifest) {
-    var models = manifest.map(function(entry) {
-        var row = _object_spread$2({
-            modelType: entry.modelType,
-            modelName: entry.modelName,
-            identityConst: entry.identityConst,
-            collectionPrefix: entry.collectionPrefix,
-            sourcePackage: entry.sourcePackage,
-            fieldCount: entry.fields.length
-        }, entry.modelGroup == null ? {} : {
-            modelGroup: entry.modelGroup
-        }, entry.parentIdentityConst == null ? {} : {
-            parentIdentityConst: entry.parentIdentityConst
-        }, entry.description == null ? {} : {
-            description: entry.description
-        }, entry.read == null ? {} : {
-            read: entry.read
-        }, entry.serviceFactory == null ? {} : {
-            serviceFactoryExport: entry.serviceFactory.exportName
-        });
-        return row;
+function buildGroupFilterOutput(config) {
+    var group = config.group, manifest = config.manifest, fields = config.fields;
+    var detailed = fields !== null && fields !== void 0 ? fields : false;
+    var lower = group.toLowerCase();
+    var matches = manifest.filter(function(entry) {
+        var _entry_modelGroup;
+        return ((_entry_modelGroup = entry.modelGroup) === null || _entry_modelGroup === void 0 ? void 0 : _entry_modelGroup.toLowerCase()) === lower;
     });
+    var result;
+    if (matches.length === 0) {
+        throw new Error(buildUnknownGroupMessage(group, manifest));
+    } else {
+        var canonical = matches[0].modelGroup;
+        result = {
+            mode: 'list',
+            modelGroup: canonical,
+            models: matches.map(function(entry) {
+                return toModelRow(entry, detailed);
+            })
+        };
+    }
+    return result;
+}
+function buildAllOutput(manifest, fields) {
+    var detailed = fields !== null && fields !== void 0 ? fields : false;
     return {
         mode: 'list',
-        models: models
+        models: manifest.map(function(entry) {
+            return toModelRow(entry, detailed);
+        })
     };
 }
-function buildSingleOutput(query, manifest) {
-    var entry = findModelEntry(query, manifest);
-    if (entry == null) {
-        throw new Error('model-info: no model matches "'.concat(query, '". Call `model-info` without arguments to list available models.'));
+function buildModelLookupOutput(config) {
+    var queries = config.queries, isArray = config.isArray, manifest = config.manifest, fields = config.fields;
+    var detailed = fields !== null && fields !== void 0 ? fields : true;
+    var matched = [];
+    var notFound = [];
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = queries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var query = _step.value;
+            var entry = findModelEntry(query, manifest);
+            if (entry == null) {
+                notFound.push({
+                    query: query,
+                    message: buildModelNotFoundMessage(query, manifest)
+                });
+            } else {
+                matched.push(toModelRow(entry, detailed));
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
     }
-    return {
-        mode: 'single',
-        model: entry
-    };
+    var result;
+    if (isArray) {
+        result = notFound.length > 0 ? {
+            mode: 'multiple',
+            models: matched,
+            notFound: notFound
+        } : {
+            mode: 'multiple',
+            models: matched
+        };
+    } else if (matched.length > 0) {
+        result = {
+            mode: 'single',
+            model: matched[0]
+        };
+    } else {
+        throw new Error(notFound[0].message);
+    }
+    return result;
+}
+// MARK: Row + group helpers
+function toModelRow(entry, detailed) {
+    return detailed ? entry : toSummaryRow(entry);
+}
+function toSummaryRow(entry) {
+    return _object_spread$2({
+        modelType: entry.modelType,
+        modelName: entry.modelName,
+        identityConst: entry.identityConst,
+        collectionPrefix: entry.collectionPrefix,
+        sourcePackage: entry.sourcePackage,
+        fieldCount: entry.fields.length
+    }, entry.modelGroup == null ? {} : {
+        modelGroup: entry.modelGroup
+    }, entry.parentIdentityConst == null ? {} : {
+        parentIdentityConst: entry.parentIdentityConst
+    }, entry.description == null ? {} : {
+        description: entry.description
+    }, entry.read == null ? {} : {
+        read: entry.read
+    }, entry.serviceFactory == null ? {} : {
+        serviceFactoryExport: entry.serviceFactory.exportName
+    });
+}
+/**
+ * Counts models per `modelGroup`, bucketing entries without a group under
+ * {@link MODEL_INFO_UNGROUPED_LABEL}. Sorted by count descending, then group name ascending.
+ *
+ * @param manifest - Model manifest to summarize.
+ * @returns One {@link ModelInfoGroupCount} per group, ordered most-populous-first.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function computeGroupCounts(manifest) {
+    var grouped = util.makeValuesGroupMap(_to_consumable_array$4(manifest), function(entry) {
+        var _entry_modelGroup;
+        return (_entry_modelGroup = entry.modelGroup) !== null && _entry_modelGroup !== void 0 ? _entry_modelGroup : MODEL_INFO_UNGROUPED_LABEL;
+    });
+    var counts = [];
+    grouped.forEach(function(entries, group) {
+        counts.push({
+            modelGroup: group,
+            modelCount: entries.length
+        });
+    });
+    counts.sort(function(a, b) {
+        return b.modelCount - a.modelCount || a.modelGroup.localeCompare(b.modelGroup);
+    });
+    return counts;
+}
+function findGroupCount(query, manifest) {
+    var lower = query.toLowerCase();
+    var result;
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = computeGroupCounts(manifest)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var count = _step.value;
+            if (count.modelGroup.toLowerCase() === lower) {
+                result = count;
+                break;
+            }
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return result;
+}
+function buildModelNotFoundMessage(query, manifest) {
+    var groupMatch = findGroupCount(query, manifest);
+    var message;
+    if (groupMatch != null) {
+        var plural = groupMatch.modelCount === 1 ? '' : 's';
+        message = 'model-info: no exact match for "'.concat(query, '" — did you mean group:"').concat(groupMatch.modelGroup, '" (').concat(groupMatch.modelCount, " model").concat(plural, ')? Use modelGroup:"').concat(groupMatch.modelGroup, '", or all:true for everything.');
+    } else {
+        message = 'model-info: no exact match for "'.concat(query, '". Call `model-info` with no arguments to list groups, or pass all:true for the full catalog.');
+    }
+    return message;
+}
+function buildUnknownGroupMessage(group, manifest) {
+    var available = computeGroupCounts(manifest).map(function(count) {
+        return "".concat(count.modelGroup, " (").concat(count.modelCount, ")");
+    }).join(', ');
+    return 'model-info: no model group matches "'.concat(group, '". Available groups: ').concat(available || '(none)', ". Call `model-info` with no arguments to list groups.");
 }
 /**
  * Resolves a manifest entry by `modelType`, `identityConst`, or `collectionPrefix`.
@@ -1298,160 +1624,205 @@ var MODEL_INFO_INPUT_SCHEMA = {
     type: 'object',
     properties: {
         model: {
+            description: 'One model (string) or many (string array), each matched by modelType, identityConst, or collectionPrefix. A string → `mode:"single"`; an array → `mode:"multiple"`. Misses are reported in `notFound`.',
+            oneOf: [
+                {
+                    type: 'string',
+                    minLength: 1
+                },
+                {
+                    type: 'array',
+                    minItems: 1,
+                    items: {
+                        type: 'string',
+                        minLength: 1
+                    }
+                }
+            ]
+        },
+        modelGroup: {
             type: 'string',
             minLength: 1,
-            description: 'Model to inspect (modelType, identityConst, or collectionPrefix). Omit to list every model.'
+            description: 'Return the summary list of models in this group (`mode:"list"`). Matched case-insensitively.'
+        },
+        all: {
+            type: 'boolean',
+            description: 'Opt in to the full catalog summary (every model). Never the default — omit to get groups instead.'
+        },
+        fields: {
+            type: 'boolean',
+            description: 'Force (true) or suppress (false) full persisted-field detail. Defaults to summary rows for list mode and full entries for single/multiple modes.'
         }
     },
     additionalProperties: false
 };
+// Shared item schema for model-bearing rows. Required props cover the summary form; full entries
+// add `fields`, `sourceFile`, and `serviceFactory` (allowed as additional properties).
+var MODEL_ROW_SCHEMA = {
+    type: 'object',
+    required: [
+        'modelType',
+        'modelName',
+        'identityConst',
+        'collectionPrefix',
+        'sourcePackage'
+    ],
+    properties: {
+        modelType: {
+            type: 'string'
+        },
+        modelName: {
+            type: 'string'
+        },
+        modelGroup: {
+            type: 'string'
+        },
+        identityConst: {
+            type: 'string'
+        },
+        collectionPrefix: {
+            type: 'string'
+        },
+        parentIdentityConst: {
+            type: 'string'
+        },
+        sourcePackage: {
+            type: 'string'
+        },
+        sourceFile: {
+            type: 'string'
+        },
+        fieldCount: {
+            type: 'integer'
+        },
+        description: {
+            type: 'string'
+        },
+        read: {
+            type: 'string',
+            enum: [
+                'system',
+                'owner',
+                'admin-only',
+                'permissions'
+            ]
+        },
+        serviceFactoryExport: {
+            type: 'string'
+        },
+        fields: {
+            type: 'array',
+            items: {
+                type: 'object'
+            }
+        },
+        serviceFactory: {
+            type: 'object',
+            required: [
+                'exportName',
+                'sourceFile'
+            ],
+            properties: {
+                exportName: {
+                    type: 'string'
+                },
+                sourceFile: {
+                    type: 'string'
+                }
+            }
+        }
+    }
+};
 // MCP's `tools/list` validator requires `outputSchema.type === 'object'` at the root
-// (see @modelcontextprotocol/sdk Zod schema), so the list/single union is expressed via a
-// top-level object whose nested `oneOf` discriminates by the `mode` literal.
+// (see @modelcontextprotocol/sdk Zod schema), so the variants are expressed via a top-level
+// object whose nested `oneOf` discriminates by the `mode` literal.
 var MODEL_INFO_OUTPUT_SCHEMA = {
     type: 'object',
     required: [
         'mode'
     ],
-    description: 'Either lists every model in the manifest (when `model` is omitted) or returns a full entry for the requested model (when `model` is provided). The `mode` field discriminates the variant.',
+    description: 'Discriminated by `mode`: `groups` (default model groups + counts), `list` (summary/full list for `modelGroup` or `all`), `single` (one `model`), or `multiple` (a `model` array, with misses in `notFound`).',
     properties: {
         mode: {
             type: 'string',
             enum: [
+                'groups',
                 'list',
-                'single'
+                'single',
+                'multiple'
             ]
         },
-        models: {
+        groups: {
             type: 'array',
-            description: 'Present when `mode` is `"list"`. One summary entry per registered model.',
+            description: 'Present when `mode` is `"groups"`. One entry per model group.',
             items: {
                 type: 'object',
                 required: [
-                    'modelType',
-                    'modelName',
-                    'identityConst',
-                    'collectionPrefix',
-                    'sourcePackage',
-                    'fieldCount'
+                    'modelGroup',
+                    'modelCount'
                 ],
                 properties: {
-                    modelType: {
-                        type: 'string'
-                    },
-                    modelName: {
-                        type: 'string'
-                    },
                     modelGroup: {
                         type: 'string'
                     },
-                    identityConst: {
-                        type: 'string'
-                    },
-                    collectionPrefix: {
-                        type: 'string'
-                    },
-                    parentIdentityConst: {
-                        type: 'string'
-                    },
-                    sourcePackage: {
-                        type: 'string'
-                    },
-                    fieldCount: {
+                    modelCount: {
                         type: 'integer'
-                    },
-                    description: {
-                        type: 'string'
-                    },
-                    read: {
-                        type: 'string',
-                        enum: [
-                            'system',
-                            'owner',
-                            'admin-only',
-                            'permissions'
-                        ]
-                    },
-                    serviceFactoryExport: {
-                        type: 'string'
                     }
                 }
             }
         },
-        model: {
-            type: 'object',
-            description: 'Present when `mode` is `"single"`. The full manifest entry for the requested model.',
-            required: [
-                'modelType',
-                'modelName',
-                'identityConst',
-                'collectionPrefix',
-                'sourcePackage',
-                'sourceFile',
-                'fields'
-            ],
-            properties: {
-                modelType: {
-                    type: 'string'
-                },
-                modelName: {
-                    type: 'string'
-                },
-                modelGroup: {
-                    type: 'string'
-                },
-                identityConst: {
-                    type: 'string'
-                },
-                collectionPrefix: {
-                    type: 'string'
-                },
-                parentIdentityConst: {
-                    type: 'string'
-                },
-                description: {
-                    type: 'string'
-                },
-                sourcePackage: {
-                    type: 'string'
-                },
-                sourceFile: {
-                    type: 'string'
-                },
-                fields: {
-                    type: 'array',
-                    items: {
-                        type: 'object'
-                    }
-                },
-                read: {
-                    type: 'string',
-                    enum: [
-                        'system',
-                        'owner',
-                        'admin-only',
-                        'permissions'
-                    ]
-                },
-                serviceFactory: {
-                    type: 'object',
-                    required: [
-                        'exportName',
-                        'sourceFile'
-                    ],
-                    properties: {
-                        exportName: {
-                            type: 'string'
-                        },
-                        sourceFile: {
-                            type: 'string'
-                        }
+        totalModels: {
+            type: 'integer',
+            description: 'Present when `mode` is `"groups"`. Total models across all groups.'
+        },
+        hint: {
+            type: 'string',
+            description: 'Present when `mode` is `"groups"`. Guidance on how to drill into the catalog.'
+        },
+        models: {
+            type: 'array',
+            description: 'Present when `mode` is `"list"` or `"multiple"`. Summary rows by default; full entries when `fields` requests detail.',
+            items: MODEL_ROW_SCHEMA
+        },
+        modelGroup: {
+            type: 'string',
+            description: 'Present when `mode` is `"list"` from a `modelGroup` filter. The canonical group name.'
+        },
+        model: _object_spread_props(_object_spread$2({}, MODEL_ROW_SCHEMA), {
+            description: 'Present when `mode` is `"single"`. The matched model entry (full detail unless `fields:false`).'
+        }),
+        notFound: {
+            type: 'array',
+            description: 'Present when `mode` is `"multiple"` and one or more queries matched nothing.',
+            items: {
+                type: 'object',
+                required: [
+                    'query',
+                    'message'
+                ],
+                properties: {
+                    query: {
+                        type: 'string'
+                    },
+                    message: {
+                        type: 'string'
                     }
                 }
             }
         }
     },
     oneOf: [
+        {
+            required: [
+                'groups',
+                'totalModels'
+            ],
+            properties: {
+                mode: {
+                    const: 'groups'
+                }
+            }
+        },
         {
             required: [
                 'models'
@@ -1471,11 +1842,21 @@ var MODEL_INFO_OUTPUT_SCHEMA = {
                     const: 'single'
                 }
             }
+        },
+        {
+            required: [
+                'models'
+            ],
+            properties: {
+                mode: {
+                    const: 'multiple'
+                }
+            }
         }
     ]
 };
 
-function _define_property$4(obj, key, value) {
+function _define_property$5(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -1498,7 +1879,7 @@ function _object_spread$1(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$4(target, key, source[key]);
+            _define_property$5(target, key, source[key]);
         });
     }
     return target;
@@ -1734,7 +2115,7 @@ var MODEL_DECODE_OUTPUT_SCHEMA = {
     }
 };
 
-function _array_like_to_array$2(arr, len) {
+function _array_like_to_array$3(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
@@ -1742,10 +2123,10 @@ function _array_like_to_array$2(arr, len) {
 function _array_with_holes$1(arr) {
     if (Array.isArray(arr)) return arr;
 }
-function _array_without_holes$2(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$2(arr);
+function _array_without_holes$3(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$3(arr);
 }
-function _define_property$3(obj, key, value) {
+function _define_property$4(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -1758,7 +2139,7 @@ function _define_property$3(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$2(iter) {
+function _iterable_to_array$3(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
 function _iterable_to_array_limit$1(arr, i) {
@@ -1788,7 +2169,7 @@ function _iterable_to_array_limit$1(arr, i) {
 function _non_iterable_rest$1() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _non_iterable_spread$2() {
+function _non_iterable_spread$3() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 function _object_spread(target) {
@@ -1801,24 +2182,24 @@ function _object_spread(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$3(target, key, source[key]);
+            _define_property$4(target, key, source[key]);
         });
     }
     return target;
 }
 function _sliced_to_array$1(arr, i) {
-    return _array_with_holes$1(arr) || _iterable_to_array_limit$1(arr, i) || _unsupported_iterable_to_array$2(arr, i) || _non_iterable_rest$1();
+    return _array_with_holes$1(arr) || _iterable_to_array_limit$1(arr, i) || _unsupported_iterable_to_array$3(arr, i) || _non_iterable_rest$1();
 }
-function _to_consumable_array$2(arr) {
-    return _array_without_holes$2(arr) || _iterable_to_array$2(arr) || _unsupported_iterable_to_array$2(arr) || _non_iterable_spread$2();
+function _to_consumable_array$3(arr) {
+    return _array_without_holes$3(arr) || _iterable_to_array$3(arr) || _unsupported_iterable_to_array$3(arr) || _non_iterable_spread$3();
 }
-function _unsupported_iterable_to_array$2(o, minLen) {
+function _unsupported_iterable_to_array$3(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$2(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$3(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$2(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$3(o, minLen);
 }
 // MARK: Constants
 /**
@@ -1899,7 +2280,7 @@ function whoamiToolHandler(ctx, deps) {
         return key;
     });
     var roleSet = deps.roleReader == null ? new Set() : deps.roleReader(token);
-    var roles = _to_consumable_array$2(roleSet).sort(function(a, b) {
+    var roles = _to_consumable_array$3(roleSet).sort(function(a, b) {
         return a.localeCompare(b);
     });
     var claimsByKey = new Map();
@@ -2168,7 +2549,7 @@ var WHOAMI_OUTPUT_SCHEMA = {
     }
 };
 
-function _array_like_to_array$1(arr, len) {
+function _array_like_to_array$2(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
@@ -2176,8 +2557,8 @@ function _array_like_to_array$1(arr, len) {
 function _array_with_holes(arr) {
     if (Array.isArray(arr)) return arr;
 }
-function _array_without_holes$1(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$1(arr);
+function _array_without_holes$2(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$2(arr);
 }
 function asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, key, arg) {
     try {
@@ -2208,12 +2589,12 @@ function _async_to_generator$2(fn) {
         });
     };
 }
-function _class_call_check$2(instance, Constructor) {
+function _class_call_check$3(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function _defineProperties$2(target, props) {
+function _defineProperties$3(target, props) {
     for(var i = 0; i < props.length; i++){
         var descriptor = props[i];
         descriptor.enumerable = descriptor.enumerable || false;
@@ -2222,11 +2603,11 @@ function _defineProperties$2(target, props) {
         Object.defineProperty(target, descriptor.key, descriptor);
     }
 }
-function _create_class$2(Constructor, protoProps, staticProps) {
-    if (protoProps) _defineProperties$2(Constructor.prototype, protoProps);
+function _create_class$3(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties$3(Constructor.prototype, protoProps);
     return Constructor;
 }
-function _define_property$2(obj, key, value) {
+function _define_property$3(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -2239,7 +2620,7 @@ function _define_property$2(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array$1(iter) {
+function _iterable_to_array$2(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
 function _iterable_to_array_limit(arr, i) {
@@ -2269,22 +2650,22 @@ function _iterable_to_array_limit(arr, i) {
 function _non_iterable_rest() {
     throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _non_iterable_spread$1() {
+function _non_iterable_spread$2() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
 function _sliced_to_array(arr, i) {
-    return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array$1(arr, i) || _non_iterable_rest();
+    return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array$2(arr, i) || _non_iterable_rest();
 }
-function _to_consumable_array$1(arr) {
-    return _array_without_holes$1(arr) || _iterable_to_array$1(arr) || _unsupported_iterable_to_array$1(arr) || _non_iterable_spread$1();
+function _to_consumable_array$2(arr) {
+    return _array_without_holes$2(arr) || _iterable_to_array$2(arr) || _unsupported_iterable_to_array$2(arr) || _non_iterable_spread$2();
 }
-function _unsupported_iterable_to_array$1(o, minLen) {
+function _unsupported_iterable_to_array$2(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$1(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$2(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$1(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$2(o, minLen);
 }
 function _ts_generator$2(thisArg, body) {
     var f, y, t, _ = {
@@ -2394,27 +2775,29 @@ var McpServerFactoryService_1;
  * recommends a fresh `McpServer` + transport pair per stateless JSON-RPC request,
  * which sidesteps session bookkeeping for the common Claude-connector case.
  */ exports.McpServerFactoryService = McpServerFactoryService_1 = /*#__PURE__*/ function() {
-    function McpServerFactoryService(mcpConfig, dispatchService, modelApiGetService, roleReader) {
-        _class_call_check$2(this, McpServerFactoryService);
-        _define_property$2(this, "mcpConfig", void 0);
-        _define_property$2(this, "dispatchService", void 0);
-        _define_property$2(this, "modelApiGetService", void 0);
-        _define_property$2(this, "roleReader", void 0);
-        _define_property$2(this, "_logger", new common.Logger(McpServerFactoryService_1.name));
-        _define_property$2(this, "_cachedTools", void 0);
-        _define_property$2(this, "_cachedStaticTools", void 0);
-        _define_property$2(this, "_cachedManifest", void 0);
-        _define_property$2(this, "_cachedManifestModels", void 0);
-        _define_property$2(this, "_cachedManifestAuth", void 0);
-        _define_property$2(this, "_manifestLoaded", false);
-        _define_property$2(this, "_loggedSkips", false);
-        _define_property$2(this, "_warnedMissingRoleReader", false);
+    function McpServerFactoryService(mcpConfig, dispatchService, modelApiGetService, roleReader, analyticsService) {
+        _class_call_check$3(this, McpServerFactoryService);
+        _define_property$3(this, "mcpConfig", void 0);
+        _define_property$3(this, "dispatchService", void 0);
+        _define_property$3(this, "modelApiGetService", void 0);
+        _define_property$3(this, "roleReader", void 0);
+        _define_property$3(this, "_logger", new common.Logger(McpServerFactoryService_1.name));
+        _define_property$3(this, "_cachedTools", void 0);
+        _define_property$3(this, "_cachedStaticTools", void 0);
+        _define_property$3(this, "_cachedManifest", void 0);
+        _define_property$3(this, "_cachedManifestModels", void 0);
+        _define_property$3(this, "_cachedManifestAuth", void 0);
+        _define_property$3(this, "_manifestLoaded", false);
+        _define_property$3(this, "_loggedSkips", false);
+        _define_property$3(this, "_warnedMissingRoleReader", false);
+        _define_property$3(this, "_analyticsService", void 0);
         this.mcpConfig = mcpConfig;
         this.dispatchService = dispatchService;
         this.modelApiGetService = modelApiGetService;
         this.roleReader = roleReader;
+        this._analyticsService = analyticsService !== null && analyticsService !== void 0 ? analyticsService : noopMcpAnalyticsService();
     }
-    _create_class$2(McpServerFactoryService, [
+    _create_class$3(McpServerFactoryService, [
         {
             /**
      * Builds a configured MCP server with tool listing + dispatch handlers wired up.
@@ -2424,14 +2807,14 @@ var McpServerFactoryService_1;
      */ key: "createServer",
             value: function createServer(ctx) {
                 var _this = this;
-                var _this_mcpConfig_serverName, _this_mcpConfig_serverVersion;
+                var _this_mcpConfig_serverName, _this_mcpConfig_serverVersion, _this_mcpConfig_serverInstructions;
                 var baseServerName = (_this_mcpConfig_serverName = this.mcpConfig.serverName) !== null && _this_mcpConfig_serverName !== void 0 ? _this_mcpConfig_serverName : DEFAULT_MCP_SERVER_NAME;
                 var serverName = this.mcpConfig.readOnly === true ? "".concat(baseServerName, " (read-only)") : baseServerName;
                 var server = new mcp_js.McpServer({
                     name: serverName,
                     version: (_this_mcpConfig_serverVersion = this.mcpConfig.serverVersion) !== null && _this_mcpConfig_serverVersion !== void 0 ? _this_mcpConfig_serverVersion : '0.0.0'
                 }, {
-                    instructions: 'Model-bound RPC tools generated from the callModel _apiDetails tree.'
+                    instructions: (_this_mcpConfig_serverInstructions = this.mcpConfig.serverInstructions) !== null && _this_mcpConfig_serverInstructions !== void 0 ? _this_mcpConfig_serverInstructions : DEFAULT_MCP_SERVER_INSTRUCTIONS
                 });
                 server.server.registerCapabilities({
                     tools: {}
@@ -2440,7 +2823,7 @@ var McpServerFactoryService_1;
                 var staticTools = this._resolveStaticTools();
                 var scopes = this._resolveScopes(ctx);
                 var authRoles = this._resolveAuthRoles(ctx);
-                var combinedTools = _to_consumable_array$1(toolGeneration.tools).concat(_to_consumable_array$1(staticTools));
+                var combinedTools = _to_consumable_array$2(toolGeneration.tools).concat(_to_consumable_array$2(staticTools));
                 var visibleTools = this._filterToolsForRequest(combinedTools, {
                     ctx: ctx,
                     scopes: scopes,
@@ -2891,19 +3274,36 @@ var McpServerFactoryService_1;
         },
         {
             key: "_handleToolCall",
-            value: function _handleToolCall(request, definitionsByName, ctx) {
+            value: /**
+     * 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.
+     */ function _handleToolCall(request, definitionsByName, ctx) {
                 return _async_to_generator$2(function() {
-                    var _request_params_arguments, definition, args, response;
+                    var _request_params_arguments, _ctx_auth, toolName, definition, args, startedAt, outcome, isSuccessful, toolKind;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
-                                definition = definitionsByName.get(request.params.name);
+                                toolName = request.params.name;
+                                definition = definitionsByName.get(toolName);
                                 args = (_request_params_arguments = request.params.arguments) !== null && _request_params_arguments !== void 0 ? _request_params_arguments : {};
+                                startedAt = Date.now();
                                 if (!(definition == null)) return [
                                     3,
                                     1
                                 ];
-                                response = formatMcpToolErrorResponse(new Error("Unknown tool: ".concat(request.params.name)));
+                                outcome = {
+                                    response: formatMcpToolErrorResponse(new Error("Unknown tool: ".concat(toolName)))
+                                };
                                 return [
                                     3,
                                     5
@@ -2918,7 +3318,7 @@ var McpServerFactoryService_1;
                                     this._handleCallModelToolCall(definition, args, ctx)
                                 ];
                             case 2:
-                                response = _state.sent();
+                                outcome = _state.sent();
                                 return [
                                     3,
                                     5
@@ -2929,23 +3329,57 @@ var McpServerFactoryService_1;
                                     this._handleStaticToolCall(definition.staticHandler, args, ctx)
                                 ];
                             case 4:
-                                response = _state.sent();
+                                outcome = _state.sent();
                                 _state.label = 5;
                             case 5:
+                                isSuccessful = outcome.error == null && outcome.response.isError !== true;
+                                // Unknown tools never reached a handler; classify as 'static' since no callModel dispatch occurred.
+                                toolKind = definition != null && definition.staticHandler == null ? 'callModel' : 'static';
+                                this._emitMcpAnalytics({
+                                    event: toolName,
+                                    toolName: toolName,
+                                    toolKind: toolKind,
+                                    call: definition === null || definition === void 0 ? void 0 : definition.dispatch.call,
+                                    modelType: definition === null || definition === void 0 ? void 0 : definition.dispatch.modelType,
+                                    specifier: definition === null || definition === void 0 ? void 0 : definition.dispatch.specifier,
+                                    uid: (_ctx_auth = ctx.auth) === null || _ctx_auth === void 0 ? void 0 : _ctx_auth.uid,
+                                    auth: ctx.auth,
+                                    readOnly: this.mcpConfig.readOnly === true,
+                                    args: args,
+                                    isSuccessful: isSuccessful,
+                                    error: outcome.error,
+                                    durationMs: Date.now() - startedAt
+                                });
                                 return [
                                     2,
-                                    response
+                                    outcome.response
                                 ];
                         }
                     });
                 }).call(this);
             }
         },
+        {
+            /**
+     * 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.
+     */ key: "_emitMcpAnalytics",
+            value: function _emitMcpAnalytics(event) {
+                try {
+                    this._analyticsService.handleMcpAnalyticsEvent(event);
+                } catch (error) {
+                    this._logger.warn("MCP analytics handler threw for tool ".concat(event.toolName, "; ignoring: ").concat(error.message));
+                }
+            }
+        },
         {
             key: "_handleStaticToolCall",
             value: function _handleStaticToolCall(staticHandler, args, ctx) {
                 return _async_to_generator$2(function() {
-                    var response, error;
+                    var outcome, _tmp, error;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -2955,19 +3389,23 @@ var McpServerFactoryService_1;
                                     ,
                                     3
                                 ]);
+                                _tmp = {};
                                 return [
                                     4,
                                     staticHandler(args, ctx)
                                 ];
                             case 1:
-                                response = _state.sent();
+                                outcome = (_tmp.response = _state.sent(), _tmp);
                                 return [
                                     3,
                                     3
                                 ];
                             case 2:
                                 error = _state.sent();
-                                response = formatMcpToolErrorResponse(error);
+                                outcome = {
+                                    response: formatMcpToolErrorResponse(error),
+                                    error: error
+                                };
                                 return [
                                     3,
                                     3
@@ -2975,7 +3413,7 @@ var McpServerFactoryService_1;
                             case 3:
                                 return [
                                     2,
-                                    response
+                                    outcome
                                 ];
                         }
                     });
@@ -2986,7 +3424,7 @@ var McpServerFactoryService_1;
             key: "_handleCallModelToolCall",
             value: function _handleCallModelToolCall(definition, args, ctx) {
                 return _async_to_generator$2(function() {
-                    var params, response, result, error;
+                    var params, outcome, result, error;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -3010,14 +3448,19 @@ var McpServerFactoryService_1;
                                 ];
                             case 2:
                                 result = _state.sent();
-                                response = formatMcpToolResponse(result, params, definition.details);
+                                outcome = {
+                                    response: formatMcpToolResponse(result, params, definition.details)
+                                };
                                 return [
                                     3,
                                     4
                                 ];
                             case 3:
                                 error = _state.sent();
-                                response = formatMcpToolErrorResponse(error);
+                                outcome = {
+                                    response: formatMcpToolErrorResponse(error),
+                                    error: error
+                                };
                                 return [
                                     3,
                                     4
@@ -3025,7 +3468,7 @@ var McpServerFactoryService_1;
                             case 4:
                                 return [
                                     2,
-                                    response
+                                    outcome
                                 ];
                         }
                     });
@@ -3042,7 +3485,9 @@ exports.McpServerFactoryService = McpServerFactoryService_1 = __decorate([
     __param(2, common.Optional()),
     __param(2, common.Inject(firebaseServer.ModelApiGetService)),
     __param(3, common.Optional()),
-    __param(3, common.Inject(MCP_AUTH_ROLE_READER))
+    __param(3, common.Inject(MCP_AUTH_ROLE_READER)),
+    __param(4, common.Optional()),
+    __param(4, common.Inject(MCP_ANALYTICS_SERVICE))
 ], exports.McpServerFactoryService);
 
 function asyncGeneratorStep$1(gen, resolve, reject, _next, _throw, key, arg) {
@@ -3250,12 +3695,12 @@ function _async_to_generator(fn) {
         });
     };
 }
-function _class_call_check$1(instance, Constructor) {
+function _class_call_check$2(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function _defineProperties$1(target, props) {
+function _defineProperties$2(target, props) {
     for(var i = 0; i < props.length; i++){
         var descriptor = props[i];
         descriptor.enumerable = descriptor.enumerable || false;
@@ -3264,11 +3709,11 @@ function _defineProperties$1(target, props) {
         Object.defineProperty(target, descriptor.key, descriptor);
     }
 }
-function _create_class$1(Constructor, protoProps, staticProps) {
-    if (protoProps) _defineProperties$1(Constructor.prototype, protoProps);
+function _create_class$2(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties$2(Constructor.prototype, protoProps);
     return Constructor;
 }
-function _define_property$1(obj, key, value) {
+function _define_property$2(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -3393,12 +3838,12 @@ var McpController_1;
  * be layered on later if streaming tool output becomes a requirement.
  */ exports.McpController = McpController_1 = /*#__PURE__*/ function() {
     function McpController(factory) {
-        _class_call_check$1(this, McpController);
-        _define_property$1(this, "factory", void 0);
-        _define_property$1(this, "_logger", new common.Logger(McpController_1.name));
+        _class_call_check$2(this, McpController);
+        _define_property$2(this, "factory", void 0);
+        _define_property$2(this, "_logger", new common.Logger(McpController_1.name));
         this.factory = factory;
     }
-    _create_class$1(McpController, [
+    _create_class$2(McpController, [
         {
             key: "handleMcpRequest",
             value: function handleMcpRequest(req, res) {
@@ -3465,12 +3910,12 @@ exports.McpController = McpController_1 = __decorate([
     __param(0, common.Inject(exports.McpServerFactoryService))
 ], exports.McpController);
 
-function _class_call_check(instance, Constructor) {
+function _class_call_check$1(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function _defineProperties(target, props) {
+function _defineProperties$1(target, props) {
     for(var i = 0; i < props.length; i++){
         var descriptor = props[i];
         descriptor.enumerable = descriptor.enumerable || false;
@@ -3479,11 +3924,11 @@ function _defineProperties(target, props) {
         Object.defineProperty(target, descriptor.key, descriptor);
     }
 }
-function _create_class(Constructor, protoProps, staticProps) {
-    if (protoProps) _defineProperties(Constructor.prototype, protoProps);
+function _create_class$1(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties$1(Constructor.prototype, protoProps);
     return Constructor;
 }
-function _define_property(obj, key, value) {
+function _define_property$1(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -3507,11 +3952,11 @@ function _define_property(obj, key, value) {
  * in `firebase-server/oidc` for the corresponding OIDC excludes).
  */ exports.McpWellKnownController = /*#__PURE__*/ function() {
     function McpWellKnownController(mcpConfig) {
-        _class_call_check(this, McpWellKnownController);
-        _define_property(this, "mcpConfig", void 0);
+        _class_call_check$1(this, McpWellKnownController);
+        _define_property$1(this, "mcpConfig", void 0);
         this.mcpConfig = mcpConfig;
     }
-    _create_class(McpWellKnownController, [
+    _create_class$1(McpWellKnownController, [
         {
             key: "getProtectedResourceMetadata",
             value: function getProtectedResourceMetadata() {
@@ -3534,30 +3979,30 @@ exports.McpWellKnownController = __decorate([
     __param(0, common.Inject(McpModuleConfig))
 ], exports.McpWellKnownController);
 
-function _array_like_to_array(arr, len) {
+function _array_like_to_array$1(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array(arr);
+function _array_without_holes$1(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$1(arr);
 }
-function _iterable_to_array(iter) {
+function _iterable_to_array$1(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread() {
+function _non_iterable_spread$1() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _to_consumable_array(arr) {
-    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+function _to_consumable_array$1(arr) {
+    return _array_without_holes$1(arr) || _iterable_to_array$1(arr) || _unsupported_iterable_to_array$1(arr) || _non_iterable_spread$1();
 }
-function _unsupported_iterable_to_array(o, minLen) {
+function _unsupported_iterable_to_array$1(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$1(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$1(o, minLen);
 }
 /**
  * Routes the firebase-server/mcp module owns. Apps should exclude these from
@@ -3594,26 +4039,254 @@ function _unsupported_iterable_to_array(o, minLen) {
     return {
         imports: [
             dependencyModule
-        ].concat(_to_consumable_array(imports !== null && imports !== void 0 ? imports : [])),
+        ].concat(_to_consumable_array$1(imports !== null && imports !== void 0 ? imports : [])),
         controllers: [
             exports.McpController,
             exports.McpWellKnownController
         ],
         exports: [
             exports.McpServerFactoryService
-        ].concat(_to_consumable_array(exports$1 !== null && exports$1 !== void 0 ? exports$1 : [])),
+        ].concat(_to_consumable_array$1(exports$1 !== null && exports$1 !== void 0 ? exports$1 : [])),
         providers: [
             exports.McpServerFactoryService
-        ].concat(_to_consumable_array(providers !== null && providers !== void 0 ? providers : []))
+        ].concat(_to_consumable_array$1(providers !== null && providers !== void 0 ? providers : []))
+    };
+}
+
+/**
+ * Default analytics event name used by {@link FirebaseServerMcpAnalyticsService} when
+ * forwarding a completed MCP tool call to the downstream analytics pipeline.
+ */ var DEFAULT_MCP_ANALYTICS_EVENT_NAME = 'mcp-tool';
+/**
+ * NestJS injection token for the optional {@link FirebaseServerMcpAnalyticsConfig} provider.
+ *
+ * @example
+ * ```typescript
+ * @Module(appMcpAnalyticsModuleMetadata({ mcpAnalyticsConfig: { eventName: 'mcp-tool', logEvents: true } }))
+ * export class AppMcpAnalyticsModule {}
+ * ```
+ */ var FIREBASE_SERVER_MCP_ANALYTICS_CONFIG = 'FIREBASE_SERVER_MCP_ANALYTICS_CONFIG';
+
+function _assert_this_initialized(self) {
+    if (self === void 0) {
+        throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
+    }
+    return self;
+}
+function _call_super(_this, derived, args) {
+    derived = _get_prototype_of(derived);
+    return _possible_constructor_return(_this, _is_native_reflect_construct() ? Reflect.construct(derived, [], _get_prototype_of(_this).constructor) : derived.apply(_this, args));
+}
+function _class_call_check(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _defineProperties(target, props) {
+    for(var i = 0; i < props.length; i++){
+        var descriptor = props[i];
+        descriptor.enumerable = descriptor.enumerable || false;
+        descriptor.configurable = true;
+        if ("value" in descriptor) descriptor.writable = true;
+        Object.defineProperty(target, descriptor.key, descriptor);
+    }
+}
+function _create_class(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties(Constructor.prototype, protoProps);
+    return Constructor;
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _get_prototype_of(o) {
+    _get_prototype_of = Object.setPrototypeOf ? Object.getPrototypeOf : function getPrototypeOf(o) {
+        return o.__proto__ || Object.getPrototypeOf(o);
+    };
+    return _get_prototype_of(o);
+}
+function _inherits(subClass, superClass) {
+    if (typeof superClass !== "function" && superClass !== null) {
+        throw new TypeError("Super expression must either be null or a function");
+    }
+    subClass.prototype = Object.create(superClass && superClass.prototype, {
+        constructor: {
+            value: subClass,
+            writable: true,
+            configurable: true
+        }
+    });
+    if (superClass) _set_prototype_of(subClass, superClass);
+}
+function _possible_constructor_return(self, call) {
+    if (call && (_type_of(call) === "object" || typeof call === "function")) {
+        return call;
+    }
+    return _assert_this_initialized(self);
+}
+function _set_prototype_of(o, p) {
+    _set_prototype_of = Object.setPrototypeOf || function setPrototypeOf(o, p) {
+        o.__proto__ = p;
+        return o;
+    };
+    return _set_prototype_of(o, p);
+}
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _is_native_reflect_construct() {
+    try {
+        var result = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function() {}));
+    } catch (_) {}
+    return (_is_native_reflect_construct = function() {
+        return !!result;
+    })();
+}
+var FirebaseServerMcpAnalyticsService_1;
+/**
+ * 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.
+ */ exports.FirebaseServerMcpAnalyticsService = FirebaseServerMcpAnalyticsService_1 = /*#__PURE__*/ function(McpAnalyticsService) {
+    _inherits(FirebaseServerMcpAnalyticsService, McpAnalyticsService);
+    function FirebaseServerMcpAnalyticsService(analyticsService, config) {
+        _class_call_check(this, FirebaseServerMcpAnalyticsService);
+        var _this;
+        var _ref, _ref1;
+        _this = _call_super(this, FirebaseServerMcpAnalyticsService), _define_property(_this, "analyticsService", void 0), _define_property(_this, "_logger", new common.Logger(FirebaseServerMcpAnalyticsService_1.name)), _define_property(_this, "_eventName", void 0), _define_property(_this, "_logEvents", void 0);
+        _this.analyticsService = analyticsService;
+        _this._eventName = (_ref = config === null || config === void 0 ? void 0 : config.eventName) !== null && _ref !== void 0 ? _ref : DEFAULT_MCP_ANALYTICS_EVENT_NAME;
+        _this._logEvents = (_ref1 = config === null || config === void 0 ? void 0 : config.logEvents) !== null && _ref1 !== void 0 ? _ref1 : true;
+        return _this;
+    }
+    _create_class(FirebaseServerMcpAnalyticsService, [
+        {
+            key: "handleMcpAnalyticsEvent",
+            value: function handleMcpAnalyticsEvent(event) {
+                if (this._logEvents) {
+                    var uidSuffix = event.uid ? " uid=".concat(event.uid) : '';
+                    var durationSuffix = event.durationMs != null ? " (".concat(event.durationMs, "ms)") : '';
+                    var outcome = event.isSuccessful ? 'Succeeded' : 'Failed';
+                    this._logger.log("MCP ".concat(event.toolName, " [").concat(event.toolKind, "] ").concat(outcome).concat(uidSuffix).concat(durationSuffix));
+                }
+                if (this.analyticsService != null) {
+                    var _event_call, _event_modelType, _event_specifier;
+                    this.analyticsService.sendEventData(event.uid, this._eventName, {
+                        tool: event.toolName,
+                        toolKind: event.toolKind,
+                        call: (_event_call = event.call) !== null && _event_call !== void 0 ? _event_call : '',
+                        modelType: (_event_modelType = event.modelType) !== null && _event_modelType !== void 0 ? _event_modelType : '',
+                        specifier: (_event_specifier = event.specifier) !== null && _event_specifier !== void 0 ? _event_specifier : '',
+                        success: event.isSuccessful
+                    });
+                }
+            }
+        }
+    ]);
+    return FirebaseServerMcpAnalyticsService;
+}(McpAnalyticsService);
+exports.FirebaseServerMcpAnalyticsService = FirebaseServerMcpAnalyticsService_1 = __decorate([
+    common.Injectable(),
+    __param(0, common.Optional()),
+    __param(0, common.Inject(firebaseServer.FirebaseServerAnalyticsService)),
+    __param(1, common.Optional()),
+    __param(1, common.Inject(FIREBASE_SERVER_MCP_ANALYTICS_CONFIG))
+], exports.FirebaseServerMcpAnalyticsService);
+
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+/**
+ * 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 {}
+ * ```
+ */ function appMcpAnalyticsModuleMetadata() {
+    var config = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
+    var mcpAnalyticsConfig = config.mcpAnalyticsConfig, imports = config.imports, exports$1 = config.exports, providers = config.providers;
+    var configProviders = mcpAnalyticsConfig ? [
+        {
+            provide: FIREBASE_SERVER_MCP_ANALYTICS_CONFIG,
+            useValue: mcpAnalyticsConfig
+        }
+    ] : [];
+    return {
+        imports: _to_consumable_array(imports !== null && imports !== void 0 ? imports : []),
+        exports: [
+            MCP_ANALYTICS_SERVICE,
+            exports.FirebaseServerMcpAnalyticsService
+        ].concat(_to_consumable_array(exports$1 !== null && exports$1 !== void 0 ? exports$1 : [])),
+        providers: [
+            exports.FirebaseServerMcpAnalyticsService,
+            {
+                provide: MCP_ANALYTICS_SERVICE,
+                useExisting: exports.FirebaseServerMcpAnalyticsService
+            }
+        ].concat(_to_consumable_array(configProviders), _to_consumable_array(providers !== null && providers !== void 0 ? providers : []))
     };
 }
 
 exports.DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS = DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS;
+exports.DEFAULT_MCP_ANALYTICS_EVENT_NAME = DEFAULT_MCP_ANALYTICS_EVENT_NAME;
 exports.DEFAULT_MCP_PATH = DEFAULT_MCP_PATH;
+exports.DEFAULT_MCP_SERVER_INSTRUCTIONS = DEFAULT_MCP_SERVER_INSTRUCTIONS;
 exports.DEFAULT_MCP_SERVER_NAME = DEFAULT_MCP_SERVER_NAME;
 exports.DEFAULT_SPECIFIER_KEY = DEFAULT_SPECIFIER_KEY;
 exports.DEFAULT_VOID_MCP_SUCCESS_VALUE = DEFAULT_VOID_MCP_SUCCESS_VALUE;
+exports.FIREBASE_SERVER_MCP_ANALYTICS_CONFIG = FIREBASE_SERVER_MCP_ANALYTICS_CONFIG;
 exports.FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE = FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE;
+exports.MCP_ANALYTICS_SERVICE = MCP_ANALYTICS_SERVICE;
 exports.MCP_AUTH_ROLE_READER = MCP_AUTH_ROLE_READER;
 exports.MCP_MANIFEST_VERSION = MCP_MANIFEST_VERSION;
 exports.MCP_MODEL_GET_BATCH_SIZE = MCP_MODEL_GET_BATCH_SIZE;
@@ -3625,8 +4298,12 @@ exports.MODEL_GET_DISPATCH_MODEL_TYPE = MODEL_GET_DISPATCH_MODEL_TYPE;
 exports.MODEL_GET_TOOL_NAME = MODEL_GET_TOOL_NAME;
 exports.MODEL_INFO_DISPATCH_CALL = MODEL_INFO_DISPATCH_CALL;
 exports.MODEL_INFO_DISPATCH_MODEL_TYPE = MODEL_INFO_DISPATCH_MODEL_TYPE;
+exports.MODEL_INFO_GROUPS_HINT = MODEL_INFO_GROUPS_HINT;
 exports.MODEL_INFO_TOOL_NAME = MODEL_INFO_TOOL_NAME;
+exports.MODEL_INFO_UNGROUPED_LABEL = MODEL_INFO_UNGROUPED_LABEL;
+exports.McpAnalyticsService = McpAnalyticsService;
 exports.McpModuleConfig = McpModuleConfig;
+exports.appMcpAnalyticsModuleMetadata = appMcpAnalyticsModuleMetadata;
 exports.buildDefaultMcpToolDescription = buildDefaultMcpToolDescription;
 exports.buildMcpToolName = buildMcpToolName;
 exports.buildStaticWireEntry = buildStaticWireEntry;
@@ -3642,5 +4319,6 @@ exports.generateMcpToolDefinitions = generateMcpToolDefinitions;
 exports.handleStreamableHttpMcpRequest = handleStreamableHttpMcpRequest;
 exports.mcpManifestKey = mcpManifestKey;
 exports.mcpModuleMetadata = mcpModuleMetadata;
+exports.noopMcpAnalyticsService = noopMcpAnalyticsService;
 exports.resolveEffectiveReadOnly = resolveEffectiveReadOnly;
 exports.resolveRequiredScope = resolveRequiredScope;