@dereekb/dbx-cli 13.13.0 → 13.15.0

package/firebase-api-manifest/main.js

@@ -162,6 +162,7 @@ import { join as join2 } from "node:path";
 // packages/dbx-cli/manifest-extract/src/lib/extract-crud.ts
 import { Node as Node2, Project as Project2 } from "ts-morph";
 var SUPPORTED_VERBS = /* @__PURE__ */ new Set(["create", "read", "update", "delete", "query", "invoke"]);
+var DBX_MODEL_API_MCP_RESULT_MARKER = "dbxModelApiMcpResult";
 function extractCrudEntries(source) {
   const project = new Project2({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true });
   const sourceFile = project.createSourceFile(source.name, source.text, { overwrite: true });
@@ -215,7 +216,7 @@ function extractCrudEntries(source) {
             if (!verbValueNode) {
               continue;
             }
-            collectVerbEntries({ modelName, verb, valueNode: verbValueNode, entries, fallbackDescription: readJsDocSummary(verbMember), resolveTypeDocs });
+            collectVerbEntries({ modelName, verb, valueNode: verbValueNode, entries, fallbackDescription: readJsDocSummary(verbMember), fallbackMcpResultTypeName: readJsDocTagValue(verbMember, DBX_MODEL_API_MCP_RESULT_MARKER), resolveTypeDocs });
           }
         }
       }
@@ -234,6 +235,8 @@ function extractCrudEntries(source) {
         const tuple = valueNode ? readTupleParamsResult(valueNode) : void 0;
         const paramsDocs = resolveTypeDocs(tuple?.params);
         const resultDocs = resolveTypeDocs(tuple?.result);
+        const mcpResultTypeName = readJsDocTagValue(member, DBX_MODEL_API_MCP_RESULT_MARKER);
+        const mcpResultDocs = resolveTypeDocs(mcpResultTypeName);
         entries.push({
           model: key,
           verb: "standalone",
@@ -246,7 +249,10 @@ function extractCrudEntries(source) {
           paramsFields: paramsDocs?.fields,
           paramsHasApiParamsTag: paramsDocs?.hasApiParamsTag,
           resultTypeDescription: resultDocs?.typeDescription,
-          resultFields: resultDocs?.fields
+          resultFields: resultDocs?.fields,
+          mcpResultTypeName,
+          mcpResultTypeDescription: mcpResultDocs?.typeDescription,
+          mcpResultFields: mcpResultDocs?.fields
         });
       }
     }
@@ -314,7 +320,7 @@ function isNullLiteralType(node) {
   return result;
 }
 function collectVerbEntries(input) {
-  const { modelName, verb, valueNode, entries, fallbackDescription, resolveTypeDocs } = input;
+  const { modelName, verb, valueNode, entries, fallbackDescription, fallbackMcpResultTypeName, resolveTypeDocs } = input;
   if (Node2.isTypeLiteral(valueNode)) {
     for (const specMember of valueNode.getMembers()) {
       if (!Node2.isPropertySignature(specMember)) {
@@ -325,6 +331,8 @@ function collectVerbEntries(input) {
       const leaf2 = leafNode ? readTupleParamsResult(leafNode) ?? readBareParams(leafNode) : void 0;
       const paramsDocs2 = resolveTypeDocs(leaf2?.params);
       const resultDocs2 = resolveTypeDocs(leaf2?.result);
+      const mcpResultTypeName = readJsDocTagValue(specMember, DBX_MODEL_API_MCP_RESULT_MARKER);
+      const mcpResultDocs2 = resolveTypeDocs(mcpResultTypeName);
       entries.push({
         model: modelName,
         verb,
@@ -337,7 +345,10 @@ function collectVerbEntries(input) {
         paramsFields: paramsDocs2?.fields,
         paramsHasApiParamsTag: paramsDocs2?.hasApiParamsTag,
         resultTypeDescription: resultDocs2?.typeDescription,
-        resultFields: resultDocs2?.fields
+        resultFields: resultDocs2?.fields,
+        mcpResultTypeName,
+        mcpResultTypeDescription: mcpResultDocs2?.typeDescription,
+        mcpResultFields: mcpResultDocs2?.fields
       });
     }
     return;
@@ -345,6 +356,7 @@ function collectVerbEntries(input) {
   const leaf = readTupleParamsResult(valueNode) ?? readBareParams(valueNode);
   const paramsDocs = resolveTypeDocs(leaf?.params);
   const resultDocs = resolveTypeDocs(leaf?.result);
+  const mcpResultDocs = resolveTypeDocs(fallbackMcpResultTypeName);
   entries.push({
     model: modelName,
     verb,
@@ -357,7 +369,10 @@ function collectVerbEntries(input) {
     paramsFields: paramsDocs?.fields,
     paramsHasApiParamsTag: paramsDocs?.hasApiParamsTag,
     resultTypeDescription: resultDocs?.typeDescription,
-    resultFields: resultDocs?.fields
+    resultFields: resultDocs?.fields,
+    mcpResultTypeName: fallbackMcpResultTypeName,
+    mcpResultTypeDescription: mcpResultDocs?.typeDescription,
+    mcpResultFields: mcpResultDocs?.fields
   });
 }
 function readTupleParamsResult(node) {
@@ -436,6 +451,20 @@ function hasJsDocFlag(node, tagName) {
   }
   return result;
 }
+function readJsDocTagValue(node, tagName) {
+  let result;
+  for (const doc of node.getJsDocs()) {
+    for (const tag of doc.getTags()) {
+      if (tag.getTagName() === tagName) {
+        const token = tag.getCommentText()?.trim().split(/\s+/)[0];
+        if (token) {
+          result = token;
+        }
+      }
+    }
+  }
+  return result;
+}
 function readJsDocSummary(node) {
   let result;
   const docs = node.getJsDocs();
@@ -453,7 +482,9 @@ function readJsDocSummary(node) {
 import { Node as Node3, Project as Project3 } from "ts-morph";
 var READ_LEVEL_VALUES = /* @__PURE__ */ new Set(["system", "owner", "admin-only", "permissions"]);
 var SERVICE_FACTORY_TAG = "dbxModelServiceFactory";
+var MCP_TOOL_NAME_SEGMENT_TAG = "dbxModelMcpToolNameSegment";
 var MODEL_TYPE_VALUE_PATTERN = /^[a-z][A-Za-z0-9_$]*$/;
+var TOOL_NAME_SEGMENT_PATTERN = /^[A-Za-z][A-Za-z0-9_$]*$/;
 var PASSTHROUGH_TYPE_WRAPPERS = /* @__PURE__ */ new Set(["Partial", "Required", "Readonly", "NonNullable", "MaybeMap", "Pick", "Omit"]);
 var IDENTITY_FN = "firestoreModelIdentity";
 var CONVERTER_FN_NAMES = ["snapshotConverterFunctions", "firestoreSubObject", "firestoreObjectArray"];
@@ -527,6 +558,7 @@ function buildInterface(decl) {
   const jsDocs = decl.getJsDocs();
   const hasDbxModelTag = jsDocsHaveTag(jsDocs, "dbxModel");
   const dbxModelRead = readDbxModelReadTag(jsDocs);
+  const mcpToolNameSegment = readMcpToolNameSegmentTag(jsDocs);
   const extendsNames = decl.getExtends().map(resolveExtendsName);
   const props = [];
   for (const prop of decl.getProperties()) {
@@ -550,9 +582,26 @@ function buildInterface(decl) {
     hasDbxModelTag,
     extendsNames,
     props,
-    ...dbxModelRead === void 0 ? {} : { dbxModelRead }
+    ...dbxModelRead === void 0 ? {} : { dbxModelRead },
+    ...mcpToolNameSegment === void 0 ? {} : { mcpToolNameSegment }
   };
 }
+function readMcpToolNameSegmentTag(jsDocs) {
+  let result;
+  for (const doc of jsDocs) {
+    for (const tag of doc.getTags()) {
+      if (tag.getTagName() !== MCP_TOOL_NAME_SEGMENT_TAG) continue;
+      if (result !== void 0) continue;
+      const raw = tag.getCommentText()?.trim();
+      if (raw === void 0 || raw.length === 0) continue;
+      const firstToken = raw.split(/\s+/)[0];
+      if (TOOL_NAME_SEGMENT_PATTERN.test(firstToken)) {
+        result = firstToken;
+      }
+    }
+  }
+  return result;
+}
 function readDbxModelReadTag(jsDocs) {
   let result;
   for (const doc of jsDocs) {
@@ -1050,6 +1099,7 @@ function buildEntryForIdentity(input) {
           sourcePackage: source.sourcePackage,
           sourceFile: source.sourceFile,
           fields,
+          ...iface.mcpToolNameSegment ? { mcpToolNameSegment: iface.mcpToolNameSegment } : {},
           ...iface.dbxModelRead ? { read: iface.dbxModelRead } : {},
           ...serviceFactory ? { serviceFactory } : {}
         };
@@ -1347,7 +1397,10 @@ function renderEntry({ entry, validatorName }) {
     entry.paramsTypeDescription ? `paramsTypeDescription: ${JSON.stringify(entry.paramsTypeDescription)}` : void 0,
     entry.paramsFields && entry.paramsFields.length > 0 ? `paramsFields: ${renderDocFields(entry.paramsFields)}` : void 0,
     entry.resultTypeDescription ? `resultTypeDescription: ${JSON.stringify(entry.resultTypeDescription)}` : void 0,
-    entry.resultFields && entry.resultFields.length > 0 ? `resultFields: ${renderDocFields(entry.resultFields)}` : void 0
+    entry.resultFields && entry.resultFields.length > 0 ? `resultFields: ${renderDocFields(entry.resultFields)}` : void 0,
+    entry.mcpResultTypeName ? `mcpResultTypeName: ${JSON.stringify(entry.mcpResultTypeName)}` : void 0,
+    entry.mcpResultTypeDescription ? `mcpResultTypeDescription: ${JSON.stringify(entry.mcpResultTypeDescription)}` : void 0,
+    entry.mcpResultFields && entry.mcpResultFields.length > 0 ? `mcpResultFields: ${renderDocFields(entry.mcpResultFields)}` : void 0
   ];
   return `  { ${fields.filter((v) => Boolean(v)).join(", ")} }`;
 }
@@ -1375,6 +1428,7 @@ function renderModelEntry(entry, emitConverters) {
     `sourcePackage: ${JSON.stringify(entry.sourcePackage)}`,
     `sourceFile: ${JSON.stringify(entry.sourceFile)}`,
     `fields: ${renderModelFields(entry.fields, emitConverters)}`,
+    entry.mcpToolNameSegment ? `mcpToolNameSegment: ${JSON.stringify(entry.mcpToolNameSegment)}` : void 0,
     entry.read ? `read: ${JSON.stringify(entry.read)}` : void 0,
     entry.serviceFactory ? `serviceFactory: { exportName: ${JSON.stringify(entry.serviceFactory.exportName)}, sourceFile: ${JSON.stringify(entry.serviceFactory.sourceFile)} }` : void 0
   ];
@@ -1487,6 +1541,10 @@ async function main() {
           console.warn(`[no-api-params-tag] ${pkg.packageName} \xB7 ${entry.model}/${entry.verb}${specPart} \u2192 ${entry.paramsTypeName} missing @dbxModelApiParams`);
         }
       }
+      if (entry.mcpResultTypeName && entry.mcpResultFields == null && entry.mcpResultTypeDescription == null) {
+        const specPart = entry.specifier ? "/" + entry.specifier : "";
+        console.warn(`[mcp-result-type-unresolved] ${pkg.packageName} \xB7 ${entry.model}/${entry.verb}${specPart} \u2192 @dbxModelApiMcpResult ${entry.mcpResultTypeName} not declared in the same .api.ts file`);
+      }
       collected.push(enriched);
     }
   }

package/firebase-api-manifest/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/dbx-cli-firebase-api-manifest",
-  "version": "13.13.0",
+  "version": "13.15.0",
   "private": true,
   "type": "module",
   "devDependencies": {
     "ts-morph": "^21.0.0"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.13.0",
-    "@dereekb/util": "13.13.0",
+    "@dereekb/dbx-cli": "13.15.0",
+    "@dereekb/util": "13.15.0",
     "prettier": "3.8.3"
   }
 }

package/generate-firestore-indexes/main.js

@@ -5,14 +5,14 @@ const require = __createRequire(import.meta.url);
 // packages/dbx-cli/generate-firestore-indexes/package.json
 var package_default = {
   name: "@dereekb/dbx-cli-generate-firestore-indexes",
-  version: "13.13.0",
+  version: "13.15.0",
   private: true,
   type: "module",
   devDependencies: {
     eslint: "10.4.0"
   },
   peerDependencies: {
-    "@dereekb/dbx-cli": "13.13.0"
+    "@dereekb/dbx-cli": "13.15.0"
   }
 };
 

package/generate-firestore-indexes/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/dbx-cli-generate-firestore-indexes",
-  "version": "13.13.0",
+  "version": "13.15.0",
   "private": true,
   "type": "module",
   "devDependencies": {
     "eslint": "10.4.0"
   },
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.13.0"
+    "@dereekb/dbx-cli": "13.15.0"
   }
 }

package/generate-mcp-manifest/main.js

@@ -79,6 +79,38 @@ function mcpManifestKey(modelType, call, specifier) {
   const isDefault = specifier == null || specifier === "_";
   return isDefault ? `${modelType}.${call}._` : `${modelType}.${call}.${specifier}`;
 }
+var DEFAULT_SPECIFIER_KEY = "_";
+var MCP_TOOL_NAME_WARN_LENGTH = 55;
+var MCP_TOOL_NAME_MAX_LENGTH = 64;
+function buildMcpToolName(modelSegment, callType, specifier) {
+  const isDefault = specifier == null || specifier === DEFAULT_SPECIFIER_KEY;
+  return isDefault ? `${modelSegment}-${callType}` : `${modelSegment}-${specifier}`;
+}
+function validateMcpToolName(name) {
+  const length = name.length;
+  let level = "ok";
+  if (length > MCP_TOOL_NAME_MAX_LENGTH) {
+    level = "error";
+  } else if (length > MCP_TOOL_NAME_WARN_LENGTH) {
+    level = "warn";
+  }
+  return { name, length, level };
+}
+var MCP_CALL_TYPE_ABBREVIATIONS = {
+  create: "c",
+  read: "r",
+  update: "u",
+  delete: "d",
+  query: "q",
+  invoke: "i"
+};
+function abbreviateMcpCallType(callType) {
+  return MCP_CALL_TYPE_ABBREVIATIONS[callType] ?? callType;
+}
+function buildDisambiguatedMcpToolName(modelSegment, callType, specifier) {
+  const isDefault = specifier == null || specifier === DEFAULT_SPECIFIER_KEY;
+  return isDefault ? `${modelSegment}-${callType}` : `${modelSegment}-${abbreviateMcpCallType(callType)}-${specifier}`;
+}
 
 // packages/dbx-cli/src/lib/mcp-scan/registry/auth-runtime.ts
 // @__NO_SIDE_EFFECTS__
@@ -980,22 +1012,56 @@ function toRelative(absolutePath, cwd) {
 // packages/dbx-cli/generate-mcp-manifest/src/generate-mcp-manifest/render.ts
 function renderMcpManifest(input, now = /* @__PURE__ */ new Date()) {
   const tools = {};
-  for (const entry of input.apiManifest) {
-    if (entry.verb === "standalone") {
-      continue;
+  const warnings = [];
+  const errors = [];
+  const seenNames = /* @__PURE__ */ new Map();
+  const segments = /* @__PURE__ */ new Map();
+  if (input.modelManifest != null) {
+    for (const model of input.modelManifest) {
+      if (model.mcpToolNameSegment != null && model.mcpToolNameSegment.length > 0) {
+        segments.set(model.modelType, model.mcpToolNameSegment);
+      }
     }
+  }
+  const toolEntries = input.apiManifest.filter((entry) => entry.verb !== "standalone");
+  const nameCounts = /* @__PURE__ */ new Map();
+  for (const entry of toolEntries) {
+    const segment = segments.get(entry.model) ?? entry.model;
+    const baseName = buildMcpToolName(segment, entry.verb, entry.specifier);
+    nameCounts.set(baseName, (nameCounts.get(baseName) ?? 0) + 1);
+  }
+  for (const entry of toolEntries) {
     const key = mcpManifestKey(entry.model, entry.verb, entry.specifier);
     tools[key] = buildToolEntry(entry);
+    const segment = segments.get(entry.model) ?? entry.model;
+    const baseName = buildMcpToolName(segment, entry.verb, entry.specifier);
+    const clashes = (nameCounts.get(baseName) ?? 0) > 1;
+    const toolName = clashes ? buildDisambiguatedMcpToolName(segment, entry.verb, entry.specifier) : baseName;
+    if (toolName !== baseName) {
+      warnings.push(`Tool name "${baseName}" is produced by more than one entry; re-derived as "${toolName}" (${key}) with the abbreviated call type to disambiguate.`);
+    }
+    const validation = validateMcpToolName(toolName);
+    if (validation.level === "error") {
+      errors.push(`Tool name "${toolName}" is ${validation.length} chars, over the ${MCP_TOOL_NAME_MAX_LENGTH}-char MCP cap (${key}). Shorten the model/specifier, set a per-model mcpToolNameSegment, or hide the tool.`);
+    } else if (validation.level === "warn") {
+      warnings.push(`Tool name "${toolName}" is ${validation.length} chars, over the ${MCP_TOOL_NAME_WARN_LENGTH}-char soft limit (${key}).`);
+    }
+    const priorKey = seenNames.get(toolName);
+    if (priorKey != null) {
+      warnings.push(`Tool name "${toolName}" is still produced by more than one entry (${priorKey} and ${key}) after disambiguation; one shadows the other unless hidden or renamed at runtime.`);
+    } else {
+      seenNames.set(toolName, key);
+    }
   }
   const models = input.modelManifest != null && input.modelManifest.length > 0 ? input.modelManifest.map(projectModelEntry) : void 0;
   const auth = input.auth == null ? void 0 : projectAuthSection(input.auth.registry, input.auth.app);
   const base = { version: MCP_MANIFEST_VERSION, generatedAt: now.toISOString(), tools };
-  const result = {
+  const manifest = {
     ...base,
     ...models == null ? {} : { models },
     ...auth == null ? {} : { auth }
   };
-  return result;
+  return { manifest, warnings, errors };
 }
 function projectAuthSection(registry, appSlug) {
   const primary = registry.findApp(appSlug);
@@ -1052,6 +1118,7 @@ function projectModelEntry(entry) {
     ...entry.modelGroup == null ? {} : { modelGroup: entry.modelGroup },
     ...entry.parentIdentityConst == null ? {} : { parentIdentityConst: entry.parentIdentityConst },
     ...entry.description == null ? {} : { description: entry.description },
+    ...entry.mcpToolNameSegment == null ? {} : { mcpToolNameSegment: entry.mcpToolNameSegment },
     ...entry.read == null ? {} : { read: entry.read },
     ...entry.serviceFactory == null ? {} : { serviceFactory: entry.serviceFactory }
   };
@@ -1079,6 +1146,7 @@ function buildToolEntry(entry) {
   if (description != null) result.description = description;
   if (inputSchema != null) result.inputSchema = inputSchema;
   if (outputSchema != null) result.outputSchema = outputSchema;
+  if (entry.mcpResultTypeName != null) result.mcpResultTypeName = entry.mcpResultTypeName;
   return result;
 }
 function buildDescription(entry) {
@@ -1102,18 +1170,20 @@ function buildInputSchema(entry) {
   return schema;
 }
 function buildOutputSchema(entry) {
-  const hasFields = entry.resultFields != null && entry.resultFields.length > 0;
-  const hasDescription = typeof entry.resultTypeDescription === "string" && entry.resultTypeDescription.length > 0;
+  const fields = entry.mcpResultFields != null && entry.mcpResultFields.length > 0 ? entry.mcpResultFields : entry.resultFields;
+  const description = typeof entry.mcpResultTypeDescription === "string" && entry.mcpResultTypeDescription.length > 0 ? entry.mcpResultTypeDescription : entry.resultTypeDescription;
+  const hasFields = fields != null && fields.length > 0;
+  const hasDescription = typeof description === "string" && description.length > 0;
   if (!hasFields && !hasDescription) {
     return void 0;
   }
   const schema = { type: "object" };
   if (hasDescription) {
-    schema["description"] = entry.resultTypeDescription;
+    schema["description"] = description;
   }
   if (hasFields) {
     const properties = {};
-    for (const field of entry.resultFields) {
+    for (const field of fields) {
       properties[field.name] = buildPropertyFromField(field);
     }
     schema["properties"] = properties;
@@ -1212,16 +1282,26 @@ Expected output of \`nx run <cli>:generate-api-manifest\`.`);
   }
   const loaded = await loadManifest(inputPath);
   const auth = await maybeLoadAuth(flags);
-  const rendered = renderMcpManifest({ ...loaded, ...auth == null ? {} : { auth } });
-  const serialized = `${JSON.stringify(rendered, null, 2)}
+  const { manifest, warnings, errors } = renderMcpManifest({ ...loaded, ...auth == null ? {} : { auth } });
+  for (const warning of warnings) {
+    console.error(`[generate-mcp-manifest] tool name warning: ${warning}`);
+  }
+  for (const error of errors) {
+    console.error(`[generate-mcp-manifest] tool name error: ${error}`);
+  }
+  if (errors.length > 0) {
+    console.error(`generate-mcp-manifest: ${errors.length} tool name(s) exceed the ${MCP_TOOL_NAME_MAX_LENGTH}-char MCP limit; not writing ${relative2(WORKSPACE_ROOT, outputPath)}.`);
+    process.exit(1);
+  }
+  const serialized = `${JSON.stringify(manifest, null, 2)}
 `;
   ensureOutputDir(dirname(outputPath));
   const tmpPath = `${outputPath}.tmp`;
   writeFileSync(tmpPath, serialized);
   renameSync(tmpPath, outputPath);
-  const modelCount = rendered.models?.length ?? 0;
-  const authCount = rendered.auth?.claims.length ?? 0;
-  console.log(`[wrote] ${relative2(WORKSPACE_ROOT, outputPath)} \u2014 ${Object.keys(rendered.tools).length} tools, ${modelCount} models, ${authCount} auth claims`);
+  const modelCount = manifest.models?.length ?? 0;
+  const authCount = manifest.auth?.claims.length ?? 0;
+  console.log(`[wrote] ${relative2(WORKSPACE_ROOT, outputPath)} \u2014 ${Object.keys(manifest.tools).length} tools, ${modelCount} models, ${authCount} auth claims`);
 }
 async function maybeLoadAuth(flags) {
   if (flags.app == null || flags.claimsInputs.length === 0) {

package/generate-mcp-manifest/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dereekb/dbx-cli-generate-mcp-manifest",
-  "version": "13.13.0",
+  "version": "13.15.0",
   "private": true,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/dbx-cli": "13.13.0",
-    "@dereekb/model": "13.13.0",
+    "@dereekb/dbx-cli": "13.15.0",
+    "@dereekb/model": "13.15.0",
     "arktype": "^2.2.0",
     "jiti": "2.6.1"
   }