@databrainhq/mcp-server 0.2.9 → 0.2.10

package/dist/index.js

@@ -479,6 +479,14 @@ var DatasourcesApi = class {
       cacheTtlMs: 5 * 60 * 1e3
     });
   }
+  async resolveIdByName(datasourceName) {
+    try {
+      const schema = await this.getDatasourceSchema(datasourceName);
+      return schema?.datasourceId || null;
+    } catch {
+      return null;
+    }
+  }
 };
 
 // src/api/embeds-api.ts
@@ -691,6 +699,7 @@ var DiscoveryService = class {
     return {
       name: isNonEmptyString(dashboard.name) && dashboard.name || isNonEmptyString(dashboard.dashboardName) && dashboard.dashboardName || "Unnamed Dashboard",
       dashboardId: isNonEmptyString(dashboard.dashboardId) && dashboard.dashboardId || isNonEmptyString(dashboard.externalDashboardId) && dashboard.externalDashboardId || isNonEmptyString(dashboard._id) && dashboard._id || isNonEmptyString(dashboard.id) && dashboard.id || isNonEmptyString(dashboard.uid) && dashboard.uid || null,
+      externalDashboardId: isNonEmptyString(dashboard.externalDashboardId) && dashboard.externalDashboardId || null,
       workspaceName: isNonEmptyString(dashboard.workspaceName) && dashboard.workspaceName || isNonEmptyString(dashboard.workspace) && dashboard.workspace || isNonEmptyString(dashboard.workspaceId) && dashboard.workspaceId || null,
       metricCount: typeof dashboard.metricCount === "number" ? dashboard.metricCount : null
     };
@@ -703,6 +712,7 @@ var DiscoveryService = class {
       embedId: isNonEmptyString(embed.embedId) ? embed.embedId : null,
       internalId: isNonEmptyString(embed._id) && embed._id || isNonEmptyString(embed.id) && embed.id || null,
       dashboardId: metadata && isNonEmptyString(metadata.dashboardId) && metadata.dashboardId || isNonEmptyString(embed.dashboardId) && embed.dashboardId || null,
+      externalDashboardId: isNonEmptyString(embed.externalDashboardId) && embed.externalDashboardId || externalDashboard && isNonEmptyString(externalDashboard.externalDashboardId) && externalDashboard.externalDashboardId || metadata && isNonEmptyString(metadata.externalDashboardId) && metadata.externalDashboardId || null,
       dataAppName: metadata && isNonEmptyString(metadata.dataAppName) && metadata.dataAppName || null,
       embedType: isNonEmptyString(embed.embedType) ? embed.embedType : null
     };
@@ -938,14 +948,135 @@ var asRecord2 = (v) => {
 };
 var isActiveDatasource = (ds) => Boolean(ds.isAuthenticated) && !ds.isDisabled;
 var WidgetService = class {
-  constructor(widgetsApi, embedsApi, dataAppsApi, datasourcesApi, guestTokenService, discoveryService) {
+  constructor(widgetsApi, embedsApi, dataAppsApi, datasourcesApi, dashboardsApi, guestTokenService, discoveryService) {
     this.widgetsApi = widgetsApi;
     this.embedsApi = embedsApi;
     this.dataAppsApi = dataAppsApi;
     this.datasourcesApi = datasourcesApi;
+    this.dashboardsApi = dashboardsApi;
     this.guestTokenService = guestTokenService;
     this.discoveryService = discoveryService;
   }
+  /**
+   * Resolve the target embedId from a non-technical dashboard name (optionally
+   * scoped to a workspace). This is the preferred entry point for CS/CX flows
+   * where the user only knows the dashboard + workspace, not the embedId or
+   * data app name. Returns a business-user-friendly error on ambiguity.
+   */
+  async resolveEmbedFromDashboard(dashboardName, workspaceName) {
+    const wsProvided = workspaceName && workspaceName.trim().length > 0 ? workspaceName.trim() : void 0;
+    let dashboards;
+    try {
+      dashboards = wsProvided ? await this.dashboardsApi.listDashboardsForWorkspace(wsProvided) : await this.dashboardsApi.listDashboardsAcrossWorkspaces();
+    } catch (err) {
+      return {
+        ok: false,
+        error: `Could not list dashboards: ${err.message}`
+      };
+    }
+    const normalized = dashboards.map(
+      (d) => this.discoveryService.normalizeDashboard(d)
+    );
+    const target = dashboardName.trim().toLowerCase();
+    const matches = normalized.filter(
+      (d) => d.name.trim().toLowerCase() === target
+    );
+    if (matches.length === 0) {
+      const available = normalized.filter((d) => d.name && d.name !== "Unnamed Dashboard").map(
+        (d) => d.workspaceName ? `"${d.name}" (workspace: ${d.workspaceName})` : `"${d.name}"`
+      ).join(", ");
+      return {
+        ok: false,
+        error: `No dashboard named "${dashboardName}"${wsProvided ? ` in workspace "${wsProvided}"` : ""}. ` + (available ? `Available dashboards: ${available}. Ask the user to pick by dashboard name.` : "No dashboards exist in this organization.")
+      };
+    }
+    if (matches.length > 1) {
+      const workspaces = matches.map((d) => d.workspaceName || "(unknown workspace)").join(", ");
+      return {
+        ok: false,
+        error: `Dashboard name "${dashboardName}" is ambiguous \u2014 it exists in multiple workspaces (${workspaces}). Ask the user which workspace and retry with \`workspaceName\`.`
+      };
+    }
+    const dashboard = matches[0];
+    if (!dashboard.dashboardId) {
+      return {
+        ok: false,
+        error: `Dashboard "${dashboard.name}" has no ID. This is unexpected \u2014 ask the user to verify the dashboard in the Databrain UI.`
+      };
+    }
+    let embeds;
+    try {
+      embeds = await this.embedsApi.listEmbeds();
+    } catch (err) {
+      return {
+        ok: false,
+        error: `Could not list embeds: ${err.message}`
+      };
+    }
+    const dashboardIds = new Set(
+      [dashboard.dashboardId, dashboard.externalDashboardId].filter(
+        (v) => typeof v === "string" && v.length > 0
+      )
+    );
+    const embedMatches = embeds.map((e) => ({ raw: e, n: this.discoveryService.normalizeEmbed(e) })).filter((x) => {
+      if (!x.n.embedId) return false;
+      const embedIds = [x.n.dashboardId, x.n.externalDashboardId].filter(
+        (v) => typeof v === "string" && v.length > 0
+      );
+      return embedIds.some((id) => dashboardIds.has(id));
+    });
+    if (embedMatches.length === 0) {
+      return {
+        ok: false,
+        error: `Dashboard "${dashboard.name}" has no embed configured. An embed must be created in the Databrain UI before widgets can be managed for customers.`
+      };
+    }
+    if (embedMatches.length > 1) {
+      const names = embedMatches.map((x) => `"${x.n.name}"`).join(", ");
+      return {
+        ok: false,
+        error: `Dashboard "${dashboard.name}" has multiple embeds (${names}). Ask the user which embed name they want to customize.`
+      };
+    }
+    return {
+      ok: true,
+      value: {
+        embedId: embedMatches[0].n.embedId,
+        dashboardName: dashboard.name,
+        workspaceName: dashboard.workspaceName
+      }
+    };
+  }
+  /**
+   * Normalize widget-tool input: callers may supply `embedId` directly (legacy
+   * / technical callers) or `dashboardName` + optional `workspaceName`
+   * (non-technical CS/CX flow). Returns a single embedId and the resolved
+   * dashboard info if lookup happened. Pass `required: true` to enforce that
+   * the user named a target dashboard (recommended for CS/CX flows).
+   */
+  async resolveEmbedId(params) {
+    if (params.embedId && params.embedId.trim().length > 0) {
+      return { ok: true, value: { embedId: params.embedId.trim() } };
+    }
+    if (params.dashboardName && params.dashboardName.trim().length > 0) {
+      const res = await this.resolveEmbedFromDashboard(
+        params.dashboardName,
+        params.workspaceName
+      );
+      if (!res.ok) return res;
+      return {
+        ok: true,
+        value: { embedId: res.value.embedId, resolvedFrom: res.value }
+      };
+    }
+    if (params.required) {
+      return {
+        ok: false,
+        error: "Missing dashboard. Ask the user which dashboard to customize (by name) and optionally which workspace, then pass `dashboardName` (and `workspaceName` if needed). Technical callers may pass `embedId` directly."
+      };
+    }
+    return { ok: true, value: { embedId: null } };
+  }
   /**
    * Resolve the data app name from either a caller override, an embed's
    * metadata, or the sole data app in the workspace. Used by every widget
@@ -1014,8 +1145,8 @@ var WidgetService = class {
     );
     if (named.length === 1) {
       const ds = named[0];
-      const id = ds._id || ds.id || "";
       const name = ds.name;
+      const id = ds._id || ds.id || await this.datasourcesApi.resolveIdByName(name) || "";
       if (id && name) {
         return { ok: true, value: { integrationId: id, integrationName: name } };
       }
@@ -1030,14 +1161,17 @@ var WidgetService = class {
     let embedReason = "";
     if (params.embedId && embedProbe) {
       if (embedProbe.kind === "no_widgets") {
-        embedReason = ` Embed "${params.embedId}" has no widgets for clientId "${params.clientId}" to inherit from, so the datasource can't be auto-detected.`;
+        embedReason = ` This dashboard has no widgets for client "${params.clientId}" yet, so there's no existing widget to inherit the datasource from.`;
       } else if (embedProbe.kind === "no_metric_fields") {
-        embedReason = ` Checked ${embedProbe.widgetsTried} widget(s) on embed "${params.embedId}"` + (embedProbe.fetchErrors > 0 ? ` (${embedProbe.fetchErrors} could not be fetched)` : "") + `, but none had datasource metadata to inherit from.`;
+        embedReason = ` Checked ${embedProbe.widgetsTried} existing widget(s) on this dashboard` + (embedProbe.fetchErrors > 0 ? ` (${embedProbe.fetchErrors} could not be fetched)` : "") + `, but none had datasource metadata to inherit from.`;
       }
     }
     return {
       ok: false,
-      error: `Could not auto-resolve a datasource.${embedReason} Ask the user which datasource this widget should query \u2014 available options: ${nameList}. Then retry with \`integrationName: "<chosen name>"\` (no other fields needed). Technical callers can pass \`integrationId\` instead \u2014 see \`list_datasources\` for UUIDs.`
+      error: `Could not auto-detect the datasource for this dashboard.${embedReason} STOP and ASK the user to choose one of these two options:
+  (1) Pick an existing chart to copy from \u2014 call \`list_widgets\` and present the widgets by name, then retry via \`add_widget\` with \`templateMetricId\` (datasource inherited automatically). This is the recommended path for non-technical users.
+  (2) Pick a datasource by name from: ${nameList}. Retry with \`integrationName: "<chosen name>"\`. Only use this if the user already knows their datasource.
+Do not guess between the two \u2014 wait for the user to choose.`
     };
   }
   async completeFromDatasources(provided) {
@@ -1068,12 +1202,12 @@ var WidgetService = class {
       const hint = provided.integrationId ? `No active datasource matches integrationId "${provided.integrationId}". Available datasources: ${available || "(none)"}.` : `No active datasource matches integrationName "${provided.integrationName}". Available datasources: ${available || "(none)"}. Match is case-insensitive \u2014 double-check the name with the user.`;
       return { ok: false, error: hint };
     }
-    const id = target._id || target.id || "";
     const name = typeof target.name === "string" ? target.name : "";
+    const id = target._id || target.id || (name ? await this.datasourcesApi.resolveIdByName(name) : null) || "";
     if (!id || !name) {
       return {
         ok: false,
-        error: `Datasource match is missing id or name (id: "${id}", name: "${name}").`
+        error: `Could not resolve datasource "${name || provided.integrationName || provided.integrationId}" to a UUID. The datasource list API does not return IDs; the schema lookup also failed \u2014 the datasource may need to be synced in the Databrain UI.`
       };
     }
     return { ok: true, value: { integrationId: id, integrationName: name } };
@@ -1258,6 +1392,7 @@ function createServiceBundle(client) {
       embedsApi,
       dataAppsApi,
       datasourcesApi,
+      dashboardsApi,
       guestTokenService,
       discoveryService
     )
@@ -1658,9 +1793,7 @@ function registerListDatasources(server, client) {
         return toolSuccess(JSON.stringify({
           count: active.length,
           datasources: active.map((ds) => ({
-            id: ds._id || ds.id || null,
-            name: ds.name,
-            type: ds.dbName || ds.datasourceType || "unknown"
+            name: ds.name
           })),
           inactive: inactive.length > 0 ? inactive.map((ds) => ({ name: ds.name })) : void 0
         }));
@@ -4396,29 +4529,41 @@ function registerListWidgets(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "list_widgets",
-    "List widgets (metrics) on a customer dashboard embed. Returns each widget's metricId, name, published state, and creator identifier.",
+    "List widgets on a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous). Returns each widget's externalMetricId (uuid, used for update/remove), metricId (slug), name, published state, and creator identifier.",
     {
-      embedId: z21.string().describe("Embed ID (customer dashboard instantiation)"),
-      clientId: z21.string().describe("Client/tenant identifier for this embed")
+      clientId: z21.string().describe("Client/tenant identifier for this dashboard"),
+      dashboardName: z21.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z21.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z21.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier.")
     },
     READ_ONLY,
     async (params) => {
       try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
         const widgets = await services.widgetsApi.listWidgets(
-          params.embedId,
+          embedId,
           params.clientId
         );
         if (!Array.isArray(widgets) || widgets.length === 0) {
           return toolSuccess(
-            `No widgets found on embed "${params.embedId}" for client "${params.clientId}".`
+            `No widgets found on dashboard "${embed.value.resolvedFrom?.dashboardName || embedId}" for client "${params.clientId}".`
           );
         }
         return toolSuccess(
           JSON.stringify({
             count: widgets.length,
-            embedId: params.embedId,
+            dashboardName: embed.value.resolvedFrom?.dashboardName || null,
+            embedId,
             clientId: params.clientId,
             widgets: widgets.map((w) => ({
+              externalMetricId: typeof w.externalMetricId === "string" && w.externalMetricId || typeof w.id === "string" && w.id || typeof w._id === "string" && w._id || null,
               metricId: w.metricId || null,
               name: w.name || null,
               isPublished: w.isPublished ?? null,
@@ -4440,11 +4585,13 @@ function registerAddWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "add_widget",
-    "Add a widget (metric) to a customer dashboard embed. Either clone via `templateMetricId` (recommended \u2014 inherits query, chartOptions, datasource), or supply a full spec (name + query + chartOptions). Datasource auto-resolves from the embed or sole active datasource; pass `integrationName` to override. Mints a guest token internally.",
+    "Add a widget to a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous). Cloning via `templateMetricId` is the recommended path \u2014 query, chart config, and datasource are all inherited. Data app and datasource auto-resolve; never ask the user for them.",
     {
-      embedId: z22.string().describe("Embed ID the widget will be added to"),
       clientId: z22.string().describe("Client/tenant identifier (widget is created in their scope)"),
-      dataAppName: z22.string().optional().describe("Data app name (required for guest token). Auto-resolved from embedId if omitted."),
+      dashboardName: z22.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z22.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z22.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z22.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
       templateMetricId: z22.string().optional().describe("Source widget metricId to clone from. Copies query, chartOptions, and datasource fields; caller can override via other params."),
       name: z22.string().optional().describe("Widget name (overrides template)"),
       metricId: z22.string().optional().describe("Unique slug for the new widget (auto-generated if omitted)"),
@@ -4459,21 +4606,29 @@ function registerAddWidget(server, client) {
     WRITE_CREATE,
     async (params) => {
       try {
-        const ctx = await services.widgetService.resolveEmbedContext(params.embedId);
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
+        const ctx = await services.widgetService.resolveEmbedContext(embedId);
         if (!ctx.externalDashboardId) {
           return toolError(
-            `Embed "${params.embedId}" has no externalDashboardId \u2014 cannot attach a widget. Verify via \`get_embed_details\`.`
+            `Dashboard "${params.dashboardName || embedId}" has no externalDashboardId \u2014 cannot attach a widget. Verify via \`get_embed_details\`.`
           );
         }
         const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
-          params.embedId
+          embedId
         );
         if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
           dataAppName.value,
-          [params.embedId]
+          [embedId]
         );
         let createBody;
         if (params.body) {
@@ -4505,7 +4660,7 @@ function registerAddWidget(server, client) {
           if (!params.name) return toolError("`name` is required when not cloning a template.");
           if (!params.query) return toolError("`query` is required when not cloning a template.");
           const datasource = await services.widgetService.resolveDatasource(guestToken, {
-            embedId: params.embedId,
+            embedId,
             clientId: params.clientId,
             integrationId: params.companyIntegrationId,
             integrationName: params.integrationName
@@ -4542,7 +4697,7 @@ ${JSON.stringify(createBody, null, 2).slice(0, 3e3)}`
 - externalMetricId: \`${newId}\`
 - metricId: \`${newMetricId}\`
 - name: \`${createBody.name}\`
-- embedId: \`${params.embedId}\`
+- dashboard: \`${embed.value.resolvedFrom?.dashboardName || embedId}\`
 - clientId: \`${params.clientId}\`
 
 Use \`list_widgets\` to verify, or \`update_widget\`/\`remove_widget\` to adjust.`
@@ -4561,12 +4716,14 @@ function registerUpdateWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "update_widget",
-    "Update a widget on a customer dashboard embed. Applies a partial patch to the externalMetrics row (name, query, chartOptions, isPublished, etc.). Mints a guest token internally.",
+    "Update a widget on a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous) + `externalMetricId` + `set`. Data app auto-resolves from the dashboard.",
     {
       externalMetricId: z23.string().describe("Internal uuid of the widget (externalMetrics.id). Not the user-facing metricId slug."),
       clientId: z23.string().describe("Client/tenant identifier"),
-      dataAppName: z23.string().optional().describe("Optional override. Auto-resolved from `embedId`, or from the sole data app when there is only one."),
-      embedId: z23.string().optional().describe("Optional \u2014 if provided, the guest token is scoped to just this embed and dataAppName is auto-resolved."),
+      dashboardName: z23.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z23.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z23.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z23.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank."),
       set: z23.record(z23.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
     },
     WRITE_IDEMPOTENT,
@@ -4575,15 +4732,22 @@ function registerUpdateWidget(server, client) {
         if (!params.set || Object.keys(params.set).length === 0) {
           return toolError("`set` must contain at least one field to update.");
         }
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
         const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
-          params.embedId
+          embedId || void 0
         );
         if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
           dataAppName.value,
-          params.embedId ? [params.embedId] : void 0
+          embedId ? [embedId] : void 0
         );
         const result = await services.widgetsApi.updateMetric(guestToken, {
           externalMetricId: params.externalMetricId,
@@ -4620,25 +4784,34 @@ function registerRemoveWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "remove_widget",
-    "Remove a widget from a customer dashboard embed. This is a per-client soft delete (writes to clientDeletedMetrics) \u2014 the widget stays on the template dashboard and on other customers' embeds.",
+    "Remove a widget from a customer dashboard. Non-technical flow: pass `clientId` + `dashboardName` (+ optional `workspaceName` if ambiguous) + `externalMetricId`. Per-client soft delete \u2014 the widget stays on the template dashboard and on other customers' dashboards.",
     {
       externalMetricId: z24.string().describe("Internal uuid of the widget (externalMetrics.id)"),
       clientId: z24.string().describe("Client/tenant identifier \u2014 the widget will be hidden for this client only"),
-      dataAppName: z24.string().optional().describe("Optional override. Auto-resolved from `embedId`, or from the sole data app when there is only one."),
-      embedId: z24.string().optional().describe("Optional \u2014 scopes the guest token to this embed and auto-resolves dataAppName.")
+      dashboardName: z24.string().optional().describe("Dashboard name (non-technical). Preferred input \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z24.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z24.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z24.string().optional().describe("Technical override. Auto-resolved from the dashboard; non-technical callers should leave this blank.")
     },
     DESTRUCTIVE,
     async (params) => {
       try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
         const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
-          params.embedId
+          embedId || void 0
         );
         if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
           dataAppName.value,
-          params.embedId ? [params.embedId] : void 0
+          embedId ? [embedId] : void 0
         );
         const result = await services.widgetsApi.markArchived(guestToken, {
           id: params.externalMetricId,
@@ -4671,30 +4844,40 @@ function registerGenerateWidget(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "generate_widget",
-    "AI-generate a widget draft from a natural-language prompt. Does NOT persist \u2014 returns a draft to review and pass to `add_widget`. Data app and datasource auto-resolve from `embedId` (preferred) or sole workspace defaults. On resolve failure, ask the user for the datasource by name and pass `integrationName`.",
+    "AI-generate a widget draft from a natural-language prompt. Does NOT persist \u2014 returns a draft to pass to `add_widget`. Non-technical flow: `clientId` + `dashboardName` (+ `workspaceName` if ambiguous); data app and datasource auto-resolve. Never ask the user for data app, datasource, or integration.",
     {
       clientId: z25.string().describe("Client/tenant identifier"),
       userInputs: z25.record(z25.unknown()).describe('Prompt + context object. Typical shape: { prompt: "calls per day over last 30 days", schema: {...}, examples: [...] }. Backend decides which keys it honors.'),
-      embedId: z25.string().optional().describe("Optional. When provided, data app and datasource are inherited from the embed's existing widgets \u2014 the preferred path for CS/CX flows."),
-      dataAppName: z25.string().optional().describe("Optional override. Auto-resolved from embedId, or from the sole data app when there is only one."),
-      integrationId: z25.string().optional().describe("Technical override \u2014 the datasource UUID. Most flows should leave this blank and rely on auto-resolution from `embedId`. If you must override, prefer `integrationName` (business-user friendly)."),
-      integrationName: z25.string().optional().describe('Datasource display name (e.g. "Snowflake", "demo datasource"). Use this when the user picks a datasource by name \u2014 the id is looked up automatically. Leave blank if `embedId` is provided (auto-resolved).')
+      dashboardName: z25.string().optional().describe("Dashboard name (non-technical). Preferred input for CS/CX flows \u2014 pass this with optional `workspaceName` instead of `embedId`."),
+      workspaceName: z25.string().optional().describe("Workspace name (non-technical). Only needed if `dashboardName` is ambiguous across workspaces."),
+      embedId: z25.string().optional().describe("Technical alternative to `dashboardName`. Pass only if you already have the embed identifier."),
+      dataAppName: z25.string().optional().describe("Technical override. Auto-resolved from the embed; non-technical callers should leave this blank."),
+      integrationId: z25.string().optional().describe("Technical override \u2014 the datasource UUID. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets."),
+      integrationName: z25.string().optional().describe("Technical override \u2014 datasource display name. Non-technical callers must leave this blank; the datasource is inherited from the dashboard's existing widgets.")
     },
     READ_ONLY,
     async (params) => {
       try {
+        const embed = await services.widgetService.resolveEmbedId({
+          embedId: params.embedId,
+          dashboardName: params.dashboardName,
+          workspaceName: params.workspaceName,
+          required: true
+        });
+        if (!embed.ok) return toolError(embed.error);
+        const embedId = embed.value.embedId;
         const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
-          params.embedId
+          embedId
         );
         if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
           dataAppName.value,
-          params.embedId ? [params.embedId] : void 0
+          [embedId]
         );
         const datasource = await services.widgetService.resolveDatasource(guestToken, {
-          embedId: params.embedId,
+          embedId,
           clientId: params.clientId,
           integrationId: params.integrationId,
           integrationName: params.integrationName
@@ -7764,75 +7947,85 @@ Suggest a sample question based on the tables you described and run it with \`as
 `;
 
 // src/prompts/customize-customer-dashboard.ts
-var customizeCustomerDashboardPrompt = `You are guiding widget CRUD on a specific customer's dashboard embed. This is the "tweak per customer" flow: add, modify, or remove individual widgets (metrics) on a customer's embedded dashboard without touching the template or other customers.
+var customizeCustomerDashboardPrompt = `You are guiding widget CRUD on a specific customer's dashboard. This is the "tweak per customer" flow for a non-technical CS/CX/support user: add, modify, or remove individual widgets for one customer without touching the template or other customers.
+
+**CRITICAL: This is an interactive, step-by-step guide. STOP after each step, show the user what you found, and wait for their input. Never batch multiple steps. Never assume the customer or dashboard.**
 
-**CRITICAL: This is an interactive, step-by-step guide. STOP after each step, show the user what you found, and wait for their input. Never batch multiple steps. Never assume the customer/embed.**
+**Minimum info the user needs to provide: \`clientId\` + \`dashboardName\`.** Everything else (data app, datasource, embed id, integration id) is auto-resolved. NEVER ask the user for any of those.
 
 **Key concepts (read before starting):**
-- **Embed** = a customer's instantiation of a dashboard. Identified by \`embedId\`. Each embed is scoped to one \`clientId\` (the customer/tenant).
-- **Widget** = a single visualization on a dashboard. Stored as \`externalMetrics\` internally. Has two ids: \`metricId\` (user-facing slug, shown in lists) and \`externalMetricId\` (internal uuid, used for updates/deletes).
-- **Per-client scope**: \`remove_widget\` is a per-client soft delete \u2014 it hides the widget for one client only. The widget stays on the template dashboard and on other customers' embeds.
-- **Guest tokens auto-minted**: \`add_widget\`, \`update_widget\`, \`remove_widget\`, and \`generate_widget\` all mint a guest token per call. You do not need to call \`generate_guest_token\` manually for widget operations.
+- **Dashboard** = the named analytics view the customer sees (e.g. "Demo Dashboard", "Airline Marketing"). This is what the user will name.
+- **Workspace** = an optional container grouping dashboards. Only ask for this if the dashboard name is ambiguous.
+- **Client/customer** = the tenant whose copy of the dashboard we're editing. Identified by \`clientId\`.
+- **Widget** = a single visualization on a dashboard. Has two ids: \`metricId\` (slug, shown in lists) and \`externalMetricId\` (uuid, used for update/remove).
+- **Per-client scope**: \`remove_widget\` is a per-client soft delete \u2014 the widget stays on the template dashboard and on other customers' copies.
+
+**Forbidden questions \u2014 DO NOT ASK the user for any of these:**
+- Data app name, \`dataAppName\`
+- Datasource name, \`integrationName\`, \`integrationId\`, \`companyIntegrationId\`
+- Embed id, \`embedId\`
+- External dashboard id, dashboard id, internal UUIDs
+
+If the user offers any of these proactively, accept and use them, but never prompt for them.
 
-**Step 1 \u2014 Identify the target embed**
+**Step 1 \u2014 Identify the customer and dashboard**
 STOP and ASK the user:
-- "Which customer/client are we customizing for?" (the \`clientId\`)
-- "Which embed/dashboard?" (the \`embedId\`)
+- "Which customer/client are we customizing for?" (capture as \`clientId\`)
+- "Which dashboard?" (capture as \`dashboardName\`)
 
-If the user only knows the customer name, call \`list_data_apps\` then \`list_embeds\` (filtered by \`dataAppName\`) and present the matching embeds. Do NOT proceed until you have both \`embedId\` and \`clientId\` confirmed.
+Only ask about workspace if the tool reports the dashboard name is ambiguous across workspaces.
 
 **Step 2 \u2014 Survey the current widgets**
-Call \`list_widgets({ embedId, clientId })\`.
-STOP and present the list: \`{metricId, name, isPublished, createdByUser}\` per widget.
-ASK: "What would you like to change? (add / modify / remove)" \u2014 or more specifically, "Which widgets should I add, update, or remove?"
+Call \`list_widgets({ clientId, dashboardName, workspaceName? })\`.
+STOP and present the list: \`{externalMetricId, metricId, name, isPublished, createdByUser}\` per widget. Keep the \`externalMetricId\` values from this response \u2014 you'll need them verbatim for update/remove. Show the user the human-readable names; the uuids are yours to reference internally.
+ASK: "What would you like to change? (add / modify / remove) \u2014 and which widgets?"
 
 **Step 3a \u2014 ADD a widget**
-This is a business-user flow. NEVER ask the user for a datasource, \`companyIntegrationId\`, \`integrationId\`, or raw SQL unless they explicitly say they want to write SQL. Prefer the two paths below in order.
+Business-user flow. NEVER ask for SQL, datasource, or chart config unless the user explicitly says they want to write raw SQL.
 
 1. **Clone an existing chart** (default \u2014 try this first):
-   - ASK: "Which existing chart should I copy from?" Call \`list_widgets\` on this embed, or on the template embed / another customer's embed, and present the widgets by name. Let the user pick by name.
-   - Call \`add_widget({ embedId, clientId, templateMetricId, name? })\` using the picked widget's \`metricId\`. The tool inherits the query, chart config, and datasource automatically.
+   - ASK: "Which existing chart should I copy from?" Call \`list_widgets\` and present the widgets by name. Let the user pick by name.
+   - Call \`add_widget({ clientId, dashboardName, workspaceName?, templateMetricId, name? })\` using the picked widget's \`metricId\`. Query, chart config, and datasource are inherited automatically.
 
 2. **Describe the chart in plain English** (AI generate \u2014 use if no suitable template exists):
    - ASK: "Describe the chart you want" (e.g., "calls per day over last 30 days").
-   - Call \`generate_widget({ embedId, clientId, userInputs: { prompt: "..." } })\` \u2014 data app and datasource auto-resolve from the embed's existing widgets. Do NOT ask the user for a datasource or data app.
-   - \`embedId\` is optional on \`generate_widget\` (the tool will fall back to the sole data app / sole datasource if absent), but pass it when you have one \u2014 resolution is more reliable.
-   - Review the returned \`draft\` with the user. If they approve, call \`add_widget({ embedId, clientId, body: <draft + externalDashboardIds> })\` to persist.
+   - Call \`generate_widget({ clientId, dashboardName, workspaceName?, userInputs: { prompt: "..." } })\`.
+   - Review the returned \`draft\` with the user. If they approve, call \`add_widget({ clientId, dashboardName, workspaceName?, body: <draft + externalDashboardIds> })\` to persist.
    - If they want changes, re-run \`generate_widget\` with a refined prompt.
-   - If \`generate_widget\` reports "Multiple data apps", pass \`embedId\` or \`dataAppName\`. If it reports "Could not auto-resolve a datasource", ASK the user which datasource to use by NAME (the error lists available options) and retry with \`integrationName: "<name>"\`. Never ask the user for \`integrationId\` or any UUID \u2014 \`integrationName\` alone is enough.
+   - If \`generate_widget\` reports "Could not auto-detect the datasource", STOP and ASK the user to choose: (a) pick an existing chart to copy from (recommended \u2014 call \`list_widgets\`, present widgets by name, then use \`add_widget\` with \`templateMetricId\`); or (b) pick a datasource by name from the list in the error (only if the user already knows it). Wait for the user's choice \u2014 do not guess.
 
 **Advanced \u2014 write SQL directly** (technical users only; ONLY if the user explicitly asks to write SQL):
-- ASK for: \`name\`, \`query\` (SQL), \`chartOptions\`, \`companyIntegrationId\` (use \`list_datasources\`).
-- Call \`add_widget({ embedId, clientId, name, query, chartOptions, companyIntegrationId, ... })\`.
+- ASK for: \`name\`, \`query\` (SQL), \`chartOptions\`.
+- Call \`add_widget({ clientId, dashboardName, name, query, chartOptions })\` \u2014 datasource still auto-resolves from the dashboard.
 
 Show the user the new widget's \`externalMetricId\` and \`metricId\` after each add.
 
 **Step 3b \u2014 UPDATE a widget**
 If the user wants to modify a widget, STOP and ASK:
-- Which widget? (look up its \`externalMetricId\` from Step 2 \u2014 remember, this is the uuid, NOT the \`metricId\` slug)
+- Which widget? (let the user pick by name, then look up the widget's \`externalMetricId\` from the Step 2 \`list_widgets\` response \u2014 this is the uuid, NOT the \`metricId\` slug. If you skipped Step 2, call \`list_widgets\` first to fetch it \u2014 never ask the user for a uuid.)
 - What to change? (name, query, chartOptions, isPublished, etc.)
 
-Call \`update_widget({ externalMetricId, clientId, dataAppName, set: {<partial patch>} })\`.
+Call \`update_widget({ externalMetricId, clientId, dashboardName, workspaceName?, set: {<partial patch>} })\`.
 Show the user the confirmation and list the changed fields.
 
 **Step 3c \u2014 REMOVE a widget**
 If the user wants to remove a widget, STOP and CONFIRM:
-- "This is a per-client soft delete. The widget will be hidden for \`<clientId>\` only \u2014 other customers and the template dashboard are unaffected. Proceed?"
+- "This is a per-customer soft delete. The widget will be hidden for \`<clientId>\` only \u2014 other customers and the template dashboard are unaffected. Proceed?"
 
-Wait for explicit confirmation before calling \`remove_widget({ externalMetricId, clientId, dataAppName })\`.
+Look up the widget's \`externalMetricId\` from the Step 2 \`list_widgets\` response (call it first if you skipped Step 2). Never ask the user for the uuid.
+Wait for explicit confirmation before calling \`remove_widget({ externalMetricId, clientId, dashboardName, workspaceName? })\`.
 
 **Step 4 \u2014 Verify**
-Call \`list_widgets({ embedId, clientId })\` again. Present the updated list and confirm the changes match what the user asked for.
+Call \`list_widgets({ clientId, dashboardName, workspaceName? })\` again. Present the updated list and confirm the changes match what the user asked for.
 
 **Step 5 \u2014 (Optional) regenerate guest token for live preview**
-If the user wants to see the changes in their running app:
-- Remind them: "Existing guest tokens carry the old embed config. Regenerate via \`generate_guest_token({ clientId, dataAppName })\` and reload the frontend to see the changes."
+If the user wants to see the changes in their running app, regenerate their guest token and reload. The MCP tools mint tokens internally for widget operations; a cached frontend token will not show the changes until refreshed.
 
 **Important rules:**
 - STOP after each step. Present results and wait for user input before proceeding.
-- Always pass \`externalMetricId\` (uuid) to \`update_widget\` / \`remove_widget\`, NOT the \`metricId\` slug. When in doubt, use \`list_widgets\` output \u2014 but note that \`list_widgets\` shows \`metricId\`, so you may need \`get_embed_details\` or context from \`add_widget\`'s response to find the uuid.
+- Always pass \`externalMetricId\` (uuid) to \`update_widget\` / \`remove_widget\`, NOT the \`metricId\` slug.
+- Never ask for data app, datasource, integration, or embed identifiers \u2014 they all auto-resolve from \`dashboardName\`.
 - Never batch add + update + remove without confirming each one.
-- If the customer-facing effect is not immediate (e.g., guest token cached), say so explicitly in your handoff message.
 
 After completion, suggest: \`brand-my-embed\` if they want to adjust theme, or \`manage-embeds\` if they want to tweak access settings / options.`;