@dereekb/firebase-server 13.12.9 → 13.14.0

package/mcp/index.esm.js

@@ -190,6 +190,35 @@ function _class_call_check$4(instance, Constructor) {
     return isDefault ? "".concat(modelType, ".").concat(call, "._") : "".concat(modelType, ".").concat(call, ".").concat(specifier);
 }
 
+function asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator$4(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep$4(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
 function _instanceof(left, right) {
     "@swc/helpers - instanceof";
     if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
@@ -198,6 +227,105 @@ function _instanceof(left, right) {
         return left instanceof right;
     }
 }
+function _ts_generator$4(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
 /**
  * Default structured value emitted by MCP when a handler returns `undefined`.
  *
@@ -210,46 +338,84 @@ function _instanceof(left, right) {
 /**
  * Resolves a dispatch result + handler API details into the MCP `CallToolResult` shape.
  *
+ * When `mcp.mapSuccessfulResult` is set, the raw result is first mapped (async-capable) to the value
+ * exposed via MCP; the tiers and the default path then operate on the mapped value. The tier
+ * callbacks receive `(value, context)` where `context` carries both the raw + mapped values + params.
+ *
  * Three-tier resolution as documented on {@link OnCallModelFunctionApiDetails.mcp}:
  *
  * - **Tier 3** — when `mcp.formatResponse` is set, its return value is used verbatim.
  * - **Tier 2** — when `mcp.summarizeResponse` is set, the summary string is wrapped into a
- *   single text content block with the raw `result` exposed as `structuredContent`.
- * - **Tier 1** — default: JSON-stringify `result` as a single text content block, also
- *   exposing the raw value as `structuredContent`.
+ *   single text content block with the (mapped) value exposed as `structuredContent`.
+ * - **Tier 1** — default: JSON-stringify the (mapped) value as a single text content block, also
+ *   exposing it as `structuredContent`.
  *
- * @param result - The handler's return value.
+ * @param result - The handler's raw return value.
  * @param params - The {@link OnCallTypedModelParams} that were dispatched.
- * @param details - The handler-level API details (carries Tier 2/3 formatters).
+ * @param details - The handler-level API details (carries the mapper + Tier 2/3 formatters).
  * @returns The MCP tool response content.
  */ function formatMcpToolResponse(result, params, details) {
-    var mcp = details === null || details === void 0 ? void 0 : details.mcp;
-    var response;
-    if (mcp === null || mcp === void 0 ? void 0 : mcp.formatResponse) {
-        response = mcp.formatResponse(result, params);
-    } else if (mcp === null || mcp === void 0 ? void 0 : mcp.summarizeResponse) {
-        var summary = mcp.summarizeResponse(result, params);
-        response = {
-            content: [
-                {
-                    type: 'text',
-                    text: summary
-                }
-            ],
-            structuredContent: result
-        };
-    } else {
-        response = {
-            content: [
-                {
-                    type: 'text',
-                    text: stringifyResult(result)
-                }
-            ],
-            structuredContent: result === undefined ? DEFAULT_VOID_MCP_SUCCESS_VALUE : result
-        };
-    }
-    return response;
+    return _async_to_generator$4(function() {
+        var mcp, value, _tmp, context, response, summary;
+        return _ts_generator$4(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    mcp = details === null || details === void 0 ? void 0 : details.mcp;
+                    if (!(mcp === null || mcp === void 0 ? void 0 : mcp.mapSuccessfulResult)) return [
+                        3,
+                        2
+                    ];
+                    return [
+                        4,
+                        mcp.mapSuccessfulResult(result, params)
+                    ];
+                case 1:
+                    _tmp = _state.sent();
+                    return [
+                        3,
+                        3
+                    ];
+                case 2:
+                    _tmp = result;
+                    _state.label = 3;
+                case 3:
+                    value = _tmp;
+                    context = {
+                        raw: result,
+                        value: value,
+                        params: params
+                    };
+                    if (mcp === null || mcp === void 0 ? void 0 : mcp.formatResponse) {
+                        response = mcp.formatResponse(value, context);
+                    } else if (mcp === null || mcp === void 0 ? void 0 : mcp.summarizeResponse) {
+                        summary = mcp.summarizeResponse(value, context);
+                        response = {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: summary
+                                }
+                            ],
+                            structuredContent: value
+                        };
+                    } else {
+                        response = {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: stringifyResult(value)
+                                }
+                            ],
+                            structuredContent: value === undefined ? DEFAULT_VOID_MCP_SUCCESS_VALUE : value
+                        };
+                    }
+                    return [
+                        2,
+                        response
+                    ];
+            }
+        });
+    })();
 }
 /**
  * Converts an error thrown from the dispatch chain into the MCP error response shape.
@@ -456,18 +622,124 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  * The default specifier key used when a handler is not behind a specifier router.
  */ var DEFAULT_SPECIFIER_KEY = '_';
 /**
- * Builds the MCP tool name for a (modelType, callType, specifier) triple.
+ * Soft limit for an MCP tool name. Names longer than this still register, but the generator
+ * surfaces a `name_length_warning` so the drift toward the hard cap is visible at boot / build.
+ */ var MCP_TOOL_NAME_WARN_LENGTH = 55;
+/**
+ * Hard limit for an MCP tool name. Remote MCP clients reject a `tools/list` payload that contains
+ * any tool whose `name` exceeds this (`FrontendRemoteMcpToolDefinition.name: String should have at
+ * most 64 characters`), which fails the whole connection. Names over this are not registered.
+ */ var MCP_TOOL_NAME_MAX_LENGTH = 64;
+/**
+ * Classifies a tool name's length against the soft/hard MCP name-length limits.
+ *
+ * Shared by the runtime generator and the build-time manifest renderer so both apply the
+ * same thresholds and never drift.
+ *
+ * @param name - The fully-resolved tool name (including any per-handler override).
+ * @returns The length classification — `error` over {@link MCP_TOOL_NAME_MAX_LENGTH}, `warn` over
+ *   {@link MCP_TOOL_NAME_WARN_LENGTH}, otherwise `ok`.
+ *
+ * @example
+ * ```ts
+ * validateMcpToolName('worker-create'); // { name: 'worker-create', length: 13, level: 'ok' }
+ * ```
+ */ function validateMcpToolName(name) {
+    var length = name.length;
+    var level = 'ok';
+    if (length > MCP_TOOL_NAME_MAX_LENGTH) {
+        level = 'error';
+    } else if (length > MCP_TOOL_NAME_WARN_LENGTH) {
+        level = 'warn';
+    }
+    return {
+        name: name,
+        length: length,
+        level: level
+    };
+}
+/**
+ * Builds the MCP tool name for a (modelSegment, callType, specifier) triple.
+ *
+ * The call-type segment is only emitted for the default (`_`) specifier, where it carries the
+ * meaning (`worker-create`, `worker-update`). Named specifiers drop it — the specifier already
+ * disambiguates (`worker-syncCheckHqEmployee`), which keeps names short and within the MCP
+ * 64-character cap. Apps can override the whole name per handler via
+ * {@link OnCallModelFunctionApiDetails.mcp.name}.
  *
- * Apps can override the auto-generated name by setting
- * {@link OnCallModelFunctionApiDetails.mcp.name} on the handler.
+ * This is the preferred (short) form. When two visible tools collide on it — two call types share a
+ * specifier once the call-type segment is dropped — the generator re-derives both names with
+ * {@link buildDisambiguatedMcpToolName} instead.
  *
- * @param modelType - The Firestore model type (e.g., `storageFile`).
+ * @param modelSegment - The model segment of the name. Defaults to the model type, but may be a
+ *   shorter per-model override (e.g. the collection prefix) resolved by the caller.
  * @param callType - The call type (e.g., `invoke`).
  * @param specifier - The specifier key, or `_` / undefined for the default entry.
  * @returns The hyphen-joined tool name advertised on `tools/list`.
- */ function buildMcpToolName(modelType, callType, specifier) {
+ *
+ * @example
+ * ```ts
+ * buildMcpToolName('worker', 'create'); // 'worker-create'
+ * buildMcpToolName('worker', 'update', 'syncCheckHqEmployee'); // 'worker-syncCheckHqEmployee'
+ * ```
+ */ function buildMcpToolName(modelSegment, callType, specifier) {
+    var isDefault = specifier == null || specifier === DEFAULT_SPECIFIER_KEY;
+    return isDefault ? "".concat(modelSegment, "-").concat(callType) : "".concat(modelSegment, "-").concat(specifier);
+}
+/**
+ * Single-character abbreviations for the standard CRUDQ + invoke call types, used to disambiguate
+ * colliding tool names without re-introducing the full call-type segment everywhere.
+ *
+ * @example
+ * ```ts
+ * MCP_CALL_TYPE_ABBREVIATIONS.update; // 'u'
+ * ```
+ */ var MCP_CALL_TYPE_ABBREVIATIONS = {
+    create: 'c',
+    read: 'r',
+    update: 'u',
+    delete: 'd',
+    query: 'q',
+    invoke: 'i'
+};
+/**
+ * Abbreviates a call type for use in a disambiguated tool name. Known CRUDQ + invoke types collapse
+ * to a single character; a custom call type is returned unchanged so the name stays unambiguous.
+ *
+ * @param callType - The call type / verb.
+ * @returns The single-character abbreviation, or the original string for a custom call type.
+ *
+ * @example
+ * ```ts
+ * abbreviateMcpCallType('update'); // 'u'
+ * abbreviateMcpCallType('recompute'); // 'recompute'
+ * ```
+ */ function abbreviateMcpCallType(callType) {
+    var _MCP_CALL_TYPE_ABBREVIATIONS_callType;
+    return (_MCP_CALL_TYPE_ABBREVIATIONS_callType = MCP_CALL_TYPE_ABBREVIATIONS[callType]) !== null && _MCP_CALL_TYPE_ABBREVIATIONS_callType !== void 0 ? _MCP_CALL_TYPE_ABBREVIATIONS_callType : callType;
+}
+/**
+ * Builds the disambiguated MCP tool name for a (modelSegment, callType, specifier) triple — the form
+ * used only when the preferred {@link buildMcpToolName} output collides with another visible tool.
+ *
+ * Named specifiers re-insert the call type, abbreviated, between the segment and specifier
+ * (`worker-u-syncCheckHqEmployee`); since the two colliding tools differ only by call type, their
+ * abbreviations differ and the names no longer clash. Default (`_`) specifiers already carry the
+ * full call type, so they are returned in their {@link buildMcpToolName} form unchanged.
+ *
+ * @param modelSegment - The model segment of the name (model type, or a per-model override).
+ * @param callType - The call type / verb.
+ * @param specifier - The specifier key, or `_` / undefined for the default entry.
+ * @returns The hyphen-joined disambiguated tool name.
+ *
+ * @example
+ * ```ts
+ * buildDisambiguatedMcpToolName('worker', 'update', 'syncCheckHqEmployee'); // 'worker-u-syncCheckHqEmployee'
+ * buildDisambiguatedMcpToolName('worker', 'create'); // 'worker-create'
+ * ```
+ */ function buildDisambiguatedMcpToolName(modelSegment, callType, specifier) {
     var isDefault = specifier == null || specifier === DEFAULT_SPECIFIER_KEY;
-    return isDefault ? "".concat(modelType, "-").concat(callType) : "".concat(modelType, "-").concat(callType, "-").concat(specifier);
+    return isDefault ? "".concat(modelSegment, "-").concat(callType) : "".concat(modelSegment, "-").concat(abbreviateMcpCallType(callType), "-").concat(specifier);
 }
 /**
  * Builds the default description used when no build-time MCP manifest
@@ -481,7 +753,6 @@ function _unsupported_iterable_to_array$6(o, minLen) {
     var isDefault = specifier == null || specifier === DEFAULT_SPECIFIER_KEY;
     return isDefault ? 'Performs the "'.concat(callType, '" call on the "').concat(modelType, '" model.') : 'Performs the "'.concat(callType, '" call on the "').concat(modelType, '" model with the "').concat(specifier, '" specifier.');
 }
-// MARK: Generation
 /**
  * Generates MCP tool definitions from a model-first API details tree.
  *
@@ -489,17 +760,78 @@ function _unsupported_iterable_to_array$6(o, minLen) {
  * `inputType.toJsonSchema(options)` for the schema, and applies any handler-level
  * MCP `name` override. Descriptions and input/output schemas are pulled from the
  * build-time manifest when supplied. Tools without an `inputType` are skipped and
- * reported so callers can log the gap at startup.
+ * reported so callers can log the gap at startup. Tools whose resolved name exceeds
+ * {@link MCP_TOOL_NAME_MAX_LENGTH} are skipped so the advertised `tools/list` stays valid.
+ *
+ * Generation runs in two passes so a name clash is known before any name is finalized: the first
+ * pass plans every candidate and counts how many visible auto-named tools share each preferred name;
+ * the second builds each tool, re-deriving the colliding ones with the abbreviated call type
+ * ({@link buildDisambiguatedMcpToolName}) so both survive instead of one shadowing the other. A
+ * residual collision that disambiguation cannot resolve (e.g. an `mcp.name` override matching an auto
+ * name) drops the later tool so the dispatch map stays unambiguous.
  *
  * @param apiDetails - The model-first API details tree returned by `getModelApiDetails(callModelFn)`.
  * @param options - Optional schema generation options forwarded to `toJsonSchema()`. Defaults to {@link DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS}.
- * @param manifest - Optional build-time manifest map; supplies overrides for descriptions and input/output schemas keyed by {@link mcpManifestKey}.
+ * @param context - Optional build-time context (manifest overrides + per-model name segments).
  * @returns The list of generated tool definitions plus any skip reports.
  */ function generateMcpToolDefinitions(apiDetails) {
-    var options = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, manifest = arguments.length > 2 ? arguments[2] : void 0;
+    var options = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, context = arguments.length > 2 ? arguments[2] : void 0;
     var tools = [];
     var neverVisibleTools = [];
     var skipped = [];
+    var warnings = [];
+    var seenNames = new Set();
+    var manifest = context === null || context === void 0 ? void 0 : context.manifest;
+    var naming = context === null || context === void 0 ? void 0 : context.naming;
+    var candidates = planMcpToolCandidates(apiDetails, naming);
+    var clashCounts = countVisibleAutoNameClashes(candidates);
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = candidates[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var candidate = _step.value;
+            buildToolFromCandidate({
+                candidate: candidate,
+                clashCounts: clashCounts,
+                options: options,
+                manifest: manifest,
+                seenNames: seenNames,
+                outTools: tools,
+                outNeverVisibleTools: neverVisibleTools,
+                outSkipped: skipped,
+                outWarnings: warnings
+            });
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return {
+        tools: tools,
+        neverVisibleTools: neverVisibleTools,
+        skipped: skipped,
+        warnings: warnings
+    };
+}
+/**
+ * First pass: walk the API tree and plan one {@link McpToolCandidate} per handler. No schema
+ * generation happens here — only the cheap naming + visibility classification needed to detect
+ * clashes before any name is finalized.
+ *
+ * @param apiDetails - The model-first API details tree.
+ * @param naming - Optional per-model name-segment overrides.
+ * @returns One candidate per non-null handler, in tree order.
+ */ function planMcpToolCandidates(apiDetails, naming) {
+    var candidates = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
         for(var _iterator = Object.entries(apiDetails.models)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
@@ -511,16 +843,53 @@ function _unsupported_iterable_to_array$6(o, minLen) {
                     if (callDetails == null) {
                         continue;
                     }
-                    generateToolsForModelCall({
-                        modelType: modelType,
-                        callType: callType,
-                        callDetails: callDetails,
-                        options: options,
-                        manifest: manifest,
-                        outTools: tools,
-                        outNeverVisibleTools: neverVisibleTools,
-                        outSkipped: skipped
-                    });
+                    var _iteratorNormalCompletion2 = true, _didIteratorError2 = false, _iteratorError2 = undefined;
+                    try {
+                        for(var _iterator2 = Object.entries(callDetails.specifiers)[Symbol.iterator](), _step2; !(_iteratorNormalCompletion2 = (_step2 = _iterator2.next()).done); _iteratorNormalCompletion2 = true){
+                            var _step_value2 = _sliced_to_array$2(_step2.value, 2), specifierKey = _step_value2[0], handlerDetails = _step_value2[1];
+                            var _ref;
+                            var _naming_modelSegments, _handlerDetails_mcp, _handlerDetails_mcp1;
+                            if (handlerDetails == null) {
+                                continue;
+                            }
+                            var specifier = callDetails.isSpecifier ? specifierKey : undefined;
+                            var dispatch = {
+                                call: callType,
+                                modelType: modelType,
+                                specifier: specifier
+                            };
+                            var modelSegment = (_ref = naming === null || naming === void 0 ? void 0 : (_naming_modelSegments = naming.modelSegments) === null || _naming_modelSegments === void 0 ? void 0 : _naming_modelSegments.get(modelType)) !== null && _ref !== void 0 ? _ref : modelType;
+                            var overrideName = (_handlerDetails_mcp = handlerDetails.mcp) === null || _handlerDetails_mcp === void 0 ? void 0 : _handlerDetails_mcp.name;
+                            var baseName = overrideName !== null && overrideName !== void 0 ? overrideName : buildMcpToolName(modelSegment, callType, specifier);
+                            var classified = classifyVisibility((_handlerDetails_mcp1 = handlerDetails.mcp) === null || _handlerDetails_mcp1 === void 0 ? void 0 : _handlerDetails_mcp1.visibility);
+                            var isVisible = classified.visibilityKind !== 'never';
+                            candidates.push({
+                                modelType: modelType,
+                                callType: callType,
+                                handlerDetails: handlerDetails,
+                                specifier: specifier,
+                                dispatch: dispatch,
+                                modelSegment: modelSegment,
+                                overrideName: overrideName,
+                                baseName: baseName,
+                                classified: classified,
+                                isVisible: isVisible
+                            });
+                        }
+                    } catch (err) {
+                        _didIteratorError2 = true;
+                        _iteratorError2 = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion2 && _iterator2.return != null) {
+                                _iterator2.return();
+                            }
+                        } finally{
+                            if (_didIteratorError2) {
+                                throw _iteratorError2;
+                            }
+                        }
+                    }
                 }
             } catch (err) {
                 _didIteratorError1 = true;
@@ -551,19 +920,24 @@ function _unsupported_iterable_to_array$6(o, minLen) {
             }
         }
     }
-    return {
-        tools: tools,
-        neverVisibleTools: neverVisibleTools,
-        skipped: skipped
-    };
+    return candidates;
 }
-function generateToolsForModelCall(context) {
+/**
+ * Counts how many visible, auto-named (no `mcp.name` override) candidates share each preferred name.
+ * Only these participate in clash detection — hidden tools never reach the wire, and overrides are
+ * explicit. A base name with a count over 1 is a clash that the build pass disambiguates.
+ *
+ * @param candidates - The planned candidates from {@link planMcpToolCandidates}.
+ * @returns A map of preferred name to the number of visible auto-named candidates producing it.
+ */ function countVisibleAutoNameClashes(candidates) {
+    var counts = new Map();
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = Object.entries(context.callDetails.specifiers)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var _step_value = _sliced_to_array$2(_step.value, 2), specifierKey = _step_value[0], handlerDetails = _step_value[1];
-            if (handlerDetails != null) {
-                generateToolForSpecifier(context, specifierKey, handlerDetails);
+        for(var _iterator = candidates[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var candidate = _step.value;
+            if (candidate.isVisible && candidate.overrideName == null) {
+                var _counts_get;
+                counts.set(candidate.baseName, ((_counts_get = counts.get(candidate.baseName)) !== null && _counts_get !== void 0 ? _counts_get : 0) + 1);
             }
         }
     } catch (err) {
@@ -580,20 +954,36 @@ function generateToolsForModelCall(context) {
             }
         }
     }
+    return counts;
 }
-function generateToolForSpecifier(context, specifierKey, handlerDetails) {
-    var _ref, _ref1, _resolveRequiredScope;
-    var _handlerDetails_mcp, _handlerDetails_mcp1, _handlerDetails_mcp2, _handlerDetails_mcp3;
-    var modelType = context.modelType, callType = context.callType, callDetails = context.callDetails, options = context.options, manifest = context.manifest, outTools = context.outTools, outNeverVisibleTools = context.outNeverVisibleTools, outSkipped = context.outSkipped;
-    var specifier = callDetails.isSpecifier ? specifierKey : undefined;
-    var dispatch = {
-        call: callType,
-        modelType: modelType,
-        specifier: specifier
-    };
-    var name = (_ref = (_handlerDetails_mcp = handlerDetails.mcp) === null || _handlerDetails_mcp === void 0 ? void 0 : _handlerDetails_mcp.name) !== null && _ref !== void 0 ? _ref : buildMcpToolName(modelType, callType, specifier);
+/**
+ * Second pass: turn one planned {@link McpToolCandidate} into a tool definition, resolving its final
+ * name (disambiguating a clash with the abbreviated call type), generating its schema, and routing it
+ * to the visible or never-visible bucket.
+ *
+ * @param context - The candidate plus the shared generation accumulators.
+ */ function buildToolFromCandidate(context) {
+    var _clashCounts_get, _ref, _resolveRequiredScope;
+    var _handlerDetails_mcp, _handlerDetails_mcp1;
+    var candidate = context.candidate, clashCounts = context.clashCounts, options = context.options, manifest = context.manifest, seenNames = context.seenNames, outTools = context.outTools, outNeverVisibleTools = context.outNeverVisibleTools, outSkipped = context.outSkipped, outWarnings = context.outWarnings;
+    var modelType = candidate.modelType, callType = candidate.callType, handlerDetails = candidate.handlerDetails, specifier = candidate.specifier, dispatch = candidate.dispatch, modelSegment = candidate.modelSegment, overrideName = candidate.overrideName, baseName = candidate.baseName, classified = candidate.classified, isVisible = candidate.isVisible;
+    // A visible auto-named tool whose preferred name is produced by more than one visible tool is
+    // re-derived with the abbreviated call type so both survive on the wire. Overrides and hidden tools
+    // keep their preferred name (overrides are explicit; hidden tools never reach the wire).
+    var needsDisambiguation = isVisible && overrideName == null && ((_clashCounts_get = clashCounts.get(baseName)) !== null && _clashCounts_get !== void 0 ? _clashCounts_get : 0) > 1;
+    var name = needsDisambiguation ? buildDisambiguatedMcpToolName(modelSegment, callType, specifier) : baseName;
+    var nameValidation = validateMcpToolName(name);
+    // A name over the hard cap would make remote clients reject the whole tools/list payload — never advertise it.
+    if (nameValidation.level === 'error') {
+        outSkipped.push({
+            toolName: name,
+            reason: 'name_too_long',
+            dispatch: dispatch
+        });
+        return;
+    }
     var manifestEntry = manifest === null || manifest === void 0 ? void 0 : manifest.get(mcpManifestKey(modelType, callType, specifier));
-    var description = (_ref1 = manifestEntry === null || manifestEntry === void 0 ? void 0 : manifestEntry.description) !== null && _ref1 !== void 0 ? _ref1 : buildDefaultMcpToolDescription(modelType, callType, specifier);
+    var description = (_ref = manifestEntry === null || manifestEntry === void 0 ? void 0 : manifestEntry.description) !== null && _ref !== void 0 ? _ref : buildDefaultMcpToolDescription(modelType, callType, specifier);
     var inputSchema = resolveInputSchema({
         handlerDetails: handlerDetails,
         manifestEntry: manifestEntry,
@@ -605,9 +995,28 @@ function generateToolForSpecifier(context, specifierKey, handlerDetails) {
     if (inputSchema == null) {
         return;
     }
-    var classified = classifyVisibility((_handlerDetails_mcp1 = handlerDetails.mcp) === null || _handlerDetails_mcp1 === void 0 ? void 0 : _handlerDetails_mcp1.visibility);
+    // Cross-check the handler's mapSuccessfulResult against the manifest's mapped-result signal. Only
+    // meaningful when a manifest is supplied (it carries the `.api.ts` annotation outcome).
+    if (manifest != null) {
+        var _handlerDetails_mcp2;
+        var hasMapper = ((_handlerDetails_mcp2 = handlerDetails.mcp) === null || _handlerDetails_mcp2 === void 0 ? void 0 : _handlerDetails_mcp2.mapSuccessfulResult) != null;
+        var manifestMapped = (manifestEntry === null || manifestEntry === void 0 ? void 0 : manifestEntry.mcpResultTypeName) != null;
+        if (hasMapper && !manifestMapped) {
+            outWarnings.push({
+                toolName: name,
+                reason: 'mapper_without_mapped_manifest',
+                dispatch: dispatch
+            });
+        } else if (!hasMapper && manifestMapped) {
+            outWarnings.push({
+                toolName: name,
+                reason: 'mapped_manifest_without_mapper',
+                dispatch: dispatch
+            });
+        }
+    }
     var requiredScope = (_resolveRequiredScope = resolveRequiredScope(callType)) !== null && _resolveRequiredScope !== void 0 ? _resolveRequiredScope : undefined;
-    var effectiveReadOnly = resolveEffectiveReadOnly((_handlerDetails_mcp2 = handlerDetails.mcp) === null || _handlerDetails_mcp2 === void 0 ? void 0 : _handlerDetails_mcp2.readOnly, callType);
+    var effectiveReadOnly = resolveEffectiveReadOnly((_handlerDetails_mcp = handlerDetails.mcp) === null || _handlerDetails_mcp === void 0 ? void 0 : _handlerDetails_mcp.readOnly, callType);
     var filterMetadata;
     if (classified.visibilityKind === 'declarative') {
         filterMetadata = {
@@ -630,6 +1039,21 @@ function generateToolForSpecifier(context, specifierKey, handlerDetails) {
             effectiveReadOnly: effectiveReadOnly
         };
     }
+    // Disambiguation has already separated the common dropped-call-type clash; this is the backstop for
+    // a residual collision it cannot resolve (an `mcp.name` override matching an auto name, or two model
+    // segments coinciding on the same call type) which would otherwise let one tool silently shadow the
+    // other in the per-request name→definition map. Hidden tools never reach the map, so skip the check.
+    if (isVisible) {
+        if (seenNames.has(name)) {
+            outSkipped.push({
+                toolName: name,
+                reason: 'duplicate_name',
+                dispatch: dispatch
+            });
+            return;
+        }
+        seenNames.add(name);
+    }
     var outputSchema = manifestEntry === null || manifestEntry === void 0 ? void 0 : manifestEntry.outputSchema;
     var staticWireEntry = buildStaticWireEntry({
         name: name,
@@ -646,12 +1070,12 @@ function generateToolForSpecifier(context, specifierKey, handlerDetails) {
         dispatch: dispatch,
         filterMetadata: filterMetadata,
         staticWireEntry: staticWireEntry,
-        toolDetailsBuilder: (_handlerDetails_mcp3 = handlerDetails.mcp) === null || _handlerDetails_mcp3 === void 0 ? void 0 : _handlerDetails_mcp3.toolDetails
+        toolDetailsBuilder: (_handlerDetails_mcp1 = handlerDetails.mcp) === null || _handlerDetails_mcp1 === void 0 ? void 0 : _handlerDetails_mcp1.toolDetails
     };
-    if (filterMetadata.visibilityKind === 'never') {
-        outNeverVisibleTools.push(definition);
-    } else {
+    if (isVisible) {
         outTools.push(definition);
+    } else {
+        outNeverVisibleTools.push(definition);
     }
 }
 function resolveInputSchema(context) {
@@ -2880,21 +3304,24 @@ var McpServerFactoryService_1;
                         result = {
                             tools: [],
                             neverVisibleTools: [],
-                            skipped: []
+                            skipped: [],
+                            warnings: []
                         };
                     } else {
-                        result = generateMcpToolDefinitions(apiDetails, undefined, manifest);
+                        result = generateMcpToolDefinitions(apiDetails, undefined, {
+                            manifest: manifest,
+                            naming: this._resolveToolNamingOptions()
+                        });
                     }
                     this._cachedTools = result;
                 }
-                if (!this._loggedSkips && result.skipped.length > 0) {
+                if (!this._loggedSkips && (result.skipped.length > 0 || result.warnings.length > 0)) {
                     this._loggedSkips = true;
                     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
                     try {
                         for(var _iterator = result.skipped[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
                             var skip = _step.value;
-                            var errorSuffix = skip.error ? ": ".concat(skip.error.message) : '';
-                            this._logger.warn("Skipped MCP tool ".concat(skip.toolName, " (").concat(skip.reason, ")").concat(errorSuffix));
+                            this._logSkip(skip);
                         }
                     } catch (err) {
                         _didIteratorError = true;
@@ -2910,6 +3337,107 @@ var McpServerFactoryService_1;
                             }
                         }
                     }
+                    var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+                    try {
+                        for(var _iterator1 = result.warnings[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+                            var warning = _step1.value;
+                            this._logger.warn(this._describeToolGenerationWarning(warning));
+                        }
+                    } catch (err) {
+                        _didIteratorError1 = true;
+                        _iteratorError1 = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                                _iterator1.return();
+                            }
+                        } finally{
+                            if (_didIteratorError1) {
+                                throw _iteratorError1;
+                            }
+                        }
+                    }
+                }
+                return result;
+            }
+        },
+        {
+            /**
+     * Builds the per-model tool-name segment overrides from the loaded manifest's `models` catalog.
+     *
+     * Sourcing the segments from the manifest (rather than runtime config) keeps the runtime in
+     * agreement with the build-time manifest validation, which reads the same `mcpToolNameSegment`.
+     *
+     * @returns Naming options carrying the segment map, or `undefined` when no model declares one.
+     */ key: "_resolveToolNamingOptions",
+            value: function _resolveToolNamingOptions() {
+                var models = this._cachedManifestModels;
+                var result;
+                if (models != null && models.length > 0) {
+                    var modelSegments = new Map();
+                    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        for(var _iterator = models[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            var model = _step.value;
+                            if (model.mcpToolNameSegment != null && model.mcpToolNameSegment.length > 0) {
+                                modelSegments.set(model.modelType, model.mcpToolNameSegment);
+                            }
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                    if (modelSegments.size > 0) {
+                        result = {
+                            modelSegments: modelSegments
+                        };
+                    }
+                }
+                return result;
+            }
+        },
+        {
+            /**
+     * Logs one skipped tool at the appropriate level: name-cap and collision skips are errors (they
+     * would otherwise break or shadow tools on the wire), the rest are warnings.
+     *
+     * @param skip - The skipped-tool report to log.
+     */ key: "_logSkip",
+            value: function _logSkip(skip) {
+                var errorSuffix = skip.error ? ": ".concat(skip.error.message) : '';
+                if (skip.reason === 'name_too_long') {
+                    this._logger.error("Dropped MCP tool ".concat(skip.toolName, " — its name is ").concat(skip.toolName.length, " chars, over the ").concat(MCP_TOOL_NAME_MAX_LENGTH, "-char limit. Shorten the model/specifier, hide it (mcp.visibility: false), or set an mcp.name override."));
+                } else if (skip.reason === 'duplicate_name') {
+                    this._logger.error("Dropped MCP tool ".concat(skip.toolName, " — another visible tool already resolved to this name. Give one an mcp.name override to disambiguate."));
+                } else {
+                    this._logger.warn("Skipped MCP tool ".concat(skip.toolName, " (").concat(skip.reason, ")").concat(errorSuffix));
+                }
+            }
+        },
+        {
+            /**
+     * Renders a human-readable boot-time warning for an MCP-result mapping inconsistency between a
+     * handler's `mapSuccessfulResult` and the build-time manifest.
+     *
+     * @param warning - The tool-generation warning to describe.
+     * @returns The log line to emit at startup.
+     */ key: "_describeToolGenerationWarning",
+            value: function _describeToolGenerationWarning(warning) {
+                var result;
+                if (warning.reason === 'mapper_without_mapped_manifest') {
+                    result = "MCP tool ".concat(warning.toolName, " declares mcp.mapSuccessfulResult but its manifest entry has no mapped result type — annotate the matching '.api.ts' leaf with '@dbxModelApiMcpResult <TypeName>' and regenerate the manifest so the advertised output schema matches the mapped result.");
+                } else {
+                    result = "MCP tool ".concat(warning.toolName, " has a '@dbxModelApiMcpResult' manifest annotation but its handler no longer declares mcp.mapSuccessfulResult — remove the stale annotation and regenerate the manifest, or restore the mapper.");
                 }
                 return result;
             }
@@ -3422,7 +3950,7 @@ var McpServerFactoryService_1;
             key: "_handleCallModelToolCall",
             value: function _handleCallModelToolCall(definition, args, ctx) {
                 return _async_to_generator$2(function() {
-                    var params, outcome, result, error;
+                    var params, outcome, result, _tmp, error;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -3436,9 +3964,9 @@ var McpServerFactoryService_1;
                             case 1:
                                 _state.trys.push([
                                     1,
-                                    3,
+                                    4,
                                     ,
-                                    4
+                                    5
                                 ]);
                                 return [
                                     4,
@@ -3446,14 +3974,18 @@ var McpServerFactoryService_1;
                                 ];
                             case 2:
                                 result = _state.sent();
-                                outcome = {
-                                    response: formatMcpToolResponse(result, params, definition.details)
-                                };
+                                _tmp = {};
                                 return [
-                                    3,
-                                    4
+                                    4,
+                                    formatMcpToolResponse(result, params, definition.details)
                                 ];
                             case 3:
+                                outcome = (_tmp.response = _state.sent(), _tmp);
+                                return [
+                                    3,
+                                    5
+                                ];
+                            case 4:
                                 error = _state.sent();
                                 outcome = {
                                     response: formatMcpToolErrorResponse(error),
@@ -3461,9 +3993,9 @@ var McpServerFactoryService_1;
                                 };
                                 return [
                                     3,
-                                    4
+                                    5
                                 ];
-                            case 4:
+                            case 5:
                                 return [
                                     2,
                                     outcome
@@ -4277,4 +4809,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-export { DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, DEFAULT_MCP_ANALYTICS_EVENT_NAME, DEFAULT_MCP_PATH, DEFAULT_MCP_SERVER_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_SPECIFIER_KEY, DEFAULT_VOID_MCP_SUCCESS_VALUE, FIREBASE_SERVER_MCP_ANALYTICS_CONFIG, FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerMcpAnalyticsService, MCP_ANALYTICS_SERVICE, MCP_AUTH_ROLE_READER, MCP_MANIFEST_VERSION, MCP_MODEL_GET_BATCH_SIZE, MODEL_DECODE_DISPATCH_CALL, MODEL_DECODE_DISPATCH_MODEL_TYPE, MODEL_DECODE_TOOL_NAME, MODEL_GET_DISPATCH_CALL, MODEL_GET_DISPATCH_MODEL_TYPE, MODEL_GET_TOOL_NAME, MODEL_INFO_DISPATCH_CALL, MODEL_INFO_DISPATCH_MODEL_TYPE, MODEL_INFO_GROUPS_HINT, MODEL_INFO_TOOL_NAME, MODEL_INFO_UNGROUPED_LABEL, McpAnalyticsService, McpController, McpModuleConfig, McpServerFactoryService, McpWellKnownController, appMcpAnalyticsModuleMetadata, buildDefaultMcpToolDescription, buildMcpToolName, buildStaticWireEntry, classifyVisibility, createModelDecodeTool, createModelGetTool, createModelInfoTool, decodeFirestoreModelKey, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, mcpManifestKey, mcpModuleMetadata, noopMcpAnalyticsService, resolveEffectiveReadOnly, resolveRequiredScope };
+export { DEFAULT_JSON_SCHEMA_GENERATION_OPTIONS, DEFAULT_MCP_ANALYTICS_EVENT_NAME, DEFAULT_MCP_PATH, DEFAULT_MCP_SERVER_INSTRUCTIONS, DEFAULT_MCP_SERVER_NAME, DEFAULT_SPECIFIER_KEY, DEFAULT_VOID_MCP_SUCCESS_VALUE, FIREBASE_SERVER_MCP_ANALYTICS_CONFIG, FIREBASE_SERVER_MCP_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerMcpAnalyticsService, MCP_ANALYTICS_SERVICE, MCP_AUTH_ROLE_READER, MCP_CALL_TYPE_ABBREVIATIONS, MCP_MANIFEST_VERSION, MCP_MODEL_GET_BATCH_SIZE, MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAME_WARN_LENGTH, MODEL_DECODE_DISPATCH_CALL, MODEL_DECODE_DISPATCH_MODEL_TYPE, MODEL_DECODE_TOOL_NAME, MODEL_GET_DISPATCH_CALL, MODEL_GET_DISPATCH_MODEL_TYPE, MODEL_GET_TOOL_NAME, MODEL_INFO_DISPATCH_CALL, MODEL_INFO_DISPATCH_MODEL_TYPE, MODEL_INFO_GROUPS_HINT, MODEL_INFO_TOOL_NAME, MODEL_INFO_UNGROUPED_LABEL, McpAnalyticsService, McpController, McpModuleConfig, McpServerFactoryService, McpWellKnownController, abbreviateMcpCallType, appMcpAnalyticsModuleMetadata, buildDefaultMcpToolDescription, buildDisambiguatedMcpToolName, buildMcpToolName, buildStaticWireEntry, classifyVisibility, createModelDecodeTool, createModelGetTool, createModelInfoTool, decodeFirestoreModelKey, findModelEntry, formatMcpToolErrorResponse, formatMcpToolResponse, generateMcpToolDefinitions, handleStreamableHttpMcpRequest, mcpManifestKey, mcpModuleMetadata, noopMcpAnalyticsService, resolveEffectiveReadOnly, resolveRequiredScope, validateMcpToolName };