@databrainhq/mcp-server 0.2.4 → 0.2.5

package/dist/index.js

@@ -206,8 +206,8 @@ var DatabrainClient = class {
         return cached;
       }
     }
-    const token = this.getToken(options.auth);
-    if (options.auth !== "none" && !token) {
+    const token = options.token ?? this.getToken(options.auth);
+    if (options.auth !== "none" && !options.token && !token) {
       if (options.auth === "service") {
         throw new DatabrainApiError(
           401,
@@ -236,7 +236,12 @@ var DatabrainClient = class {
           "X-Databrain-Client": MCP_USER_AGENT
         };
         if (token) {
-          headers["Authorization"] = `Bearer ${token}`;
+          if (options.auth === "none") {
+            headers["x-plugin-token"] = token;
+            headers["Origin"] = "https://mcp.usedatabrain.com";
+          } else {
+            headers["Authorization"] = `Bearer ${token}`;
+          }
         }
         const response = await fetch(url, {
           method: options.method,
@@ -585,6 +590,68 @@ var QueryApi = class {
   }
 };
 
+// src/api/widgets-api.ts
+var WidgetsApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async listWidgets(embedId, clientId) {
+    return this.client.request({
+      method: "GET",
+      path: "/api/v2/data-app/metrics",
+      auth: "api",
+      query: { embedId, clientId }
+    });
+  }
+  async createMetric(guestToken, body) {
+    return this.client.request({
+      method: "POST",
+      path: "/api/v2/dashboard/createMetric",
+      auth: "none",
+      token: guestToken,
+      body
+    });
+  }
+  async updateMetric(guestToken, body) {
+    return this.client.request({
+      method: "POST",
+      path: "/api/v2/dashboard/updateMetric",
+      auth: "none",
+      token: guestToken,
+      body
+    });
+  }
+  async markArchived(guestToken, body) {
+    return this.client.request({
+      method: "POST",
+      path: "/api/v2/dashboard/markArchived",
+      auth: "none",
+      token: guestToken,
+      body
+    });
+  }
+  async generateMetric(guestToken, body) {
+    return this.client.request({
+      method: "POST",
+      path: "/api/v2/dashboard/generateMetric",
+      auth: "none",
+      token: guestToken,
+      body,
+      timeoutMs: 12e4,
+      noRetryOnTimeout: true
+    });
+  }
+  async fetchEmbeddedMetric(guestToken, metricId) {
+    return this.client.request({
+      method: "GET",
+      path: "/api/v2/dashboard/embeddedMetric",
+      auth: "none",
+      token: guestToken,
+      query: { metricId }
+    });
+  }
+};
+
 // src/api/workspaces-api.ts
 var WorkspacesApi = class {
   constructor(client) {
@@ -863,6 +930,126 @@ var GuestTokenService = class {
   }
 };
 
+// src/services/widget-service.ts
+var isNonEmptyString3 = (v) => typeof v === "string" && v.trim().length > 0;
+var asRecord2 = (v) => {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  return v;
+};
+var WidgetService = class {
+  constructor(widgetsApi, embedsApi, dataAppsApi, guestTokenService, discoveryService) {
+    this.widgetsApi = widgetsApi;
+    this.embedsApi = embedsApi;
+    this.dataAppsApi = dataAppsApi;
+    this.guestTokenService = guestTokenService;
+    this.discoveryService = discoveryService;
+  }
+  async resolveEmbedContext(embedId) {
+    const response = await this.embedsApi.getByEmbedId(embedId);
+    const records = Array.isArray(response) ? response : response ? [response] : [];
+    const exact = records.find((r) => r && r.embedId === embedId) || records[0];
+    if (!exact) {
+      throw new Error(`Embed "${embedId}" not found. Run \`list_embeds\` to verify.`);
+    }
+    const metadata = asRecord2(exact.embedMetadata);
+    const externalDashboard = asRecord2(exact.externalDashboard);
+    const dataAppId = isNonEmptyString3(exact.dataAppId) ? exact.dataAppId : null;
+    const externalDashboardId = isNonEmptyString3(exact.externalDashboardId) && exact.externalDashboardId || (externalDashboard && isNonEmptyString3(externalDashboard.externalDashboardId) ? externalDashboard.externalDashboardId : null) || (metadata && isNonEmptyString3(metadata.externalDashboardId) ? metadata.externalDashboardId : null);
+    const dashboardId = isNonEmptyString3(exact.dashboardId) && exact.dashboardId || (metadata && isNonEmptyString3(metadata.dashboardId) ? metadata.dashboardId : null);
+    let dataAppName = metadata && isNonEmptyString3(metadata.dataAppName) ? metadata.dataAppName : null;
+    if (!dataAppName && dataAppId) {
+      try {
+        const apps = await this.dataAppsApi.listDataApps();
+        const match = apps.find((a) => {
+          const n = this.discoveryService.normalizeDataApp(a);
+          return n.dataAppId === dataAppId;
+        });
+        if (match) {
+          dataAppName = this.discoveryService.normalizeDataApp(match).name;
+        }
+      } catch {
+      }
+    }
+    return {
+      embedId,
+      dataAppId,
+      dataAppName,
+      externalDashboardId,
+      dashboardId
+    };
+  }
+  async mintGuestToken(clientId, dataAppName, allowedEmbeds) {
+    const { token } = await this.guestTokenService.generateToken({
+      clientId,
+      dataAppName,
+      ...allowedEmbeds && allowedEmbeds.length > 0 ? { allowedEmbeds } : {},
+      permissions: {
+        isDisableMetricCreation: false,
+        isEnableManageMetrics: true,
+        isEnableMetricUpdation: true,
+        isEnableArchiveMetrics: true
+      }
+    });
+    return token;
+  }
+  /**
+   * Build a create body by cloning a template metric. Fetches the full metric
+   * via the embeddedMetric endpoint and copies structural fields, then lets the
+   * caller override `name`/`metricId`/etc.
+   */
+  async buildCloneBody(guestToken, templateMetricId, overrides, externalDashboardId) {
+    const response = await this.widgetsApi.fetchEmbeddedMetric(
+      guestToken,
+      templateMetricId
+    );
+    const metric = asRecord2(response.externalMetric);
+    if (!metric) {
+      throw new Error(
+        `Template metric "${templateMetricId}" not found or could not be loaded. Response keys: ${Object.keys(
+          response || {}
+        ).join(", ")}. Error: ${JSON.stringify(response?.error ?? null)}`
+      );
+    }
+    const clone = {
+      // Required identity — caller must override or we derive.
+      name: overrides.name || (isNonEmptyString3(metric.name) ? `${metric.name} (copy)` : "Widget"),
+      metricId: overrides.metricId || `${isNonEmptyString3(metric.metricId) && metric.metricId || "widget"}-${Date.now()}`,
+      // Structural fields copied from template.
+      query: metric.query || void 0,
+      metricQuery: metric.metricQuery || void 0,
+      description: metric.description || "",
+      chartOptions: asRecord2(metric.chartOptions) || {},
+      companyId: metric.companyId || void 0,
+      companyIntegrationId: metric.companyIntegrationId || void 0,
+      integrationName: metric.integrationName || void 0,
+      outputColumns: metric.outputColumns || void 0,
+      inputFields: metric.inputFields,
+      isLive: metric.isLive ?? void 0,
+      timeGrain: metric.timeGrain || void 0,
+      selectedGroupBy: metric.selectedGroupBy,
+      isEnableGroupBy: metric.isEnableGroupBy ?? void 0,
+      datasetMetricSettings: metric.datasetMetricSettings,
+      groupBy: metric.groupBy,
+      drillDownSettings: metric.drillDownSettings,
+      limit: metric.limit ?? void 0,
+      // Dashboard attachment — always for the target embed's dashboard.
+      externalDashboardIds: [{ externalDashboardId }],
+      // Defaults that shouldn't be inherited from the template.
+      isCreatedByClient: false,
+      isPublished: true
+    };
+    for (const [key, value] of Object.entries(overrides)) {
+      if (value !== void 0) {
+        clone[key] = value;
+      }
+    }
+    if (!clone.externalDashboardIds || clone.externalDashboardIds.length === 0) {
+      clone.externalDashboardIds = [{ externalDashboardId }];
+    }
+    return clone;
+  }
+};
+
 // src/services/factory.ts
 function createServiceBundle(client) {
   const embedsApi = new EmbedsApi(client);
@@ -872,7 +1059,10 @@ function createServiceBundle(client) {
   const datasourcesApi = new DatasourcesApi(client);
   const guestTokenApi = new GuestTokenApi(client);
   const queryApi = new QueryApi(client);
+  const widgetsApi = new WidgetsApi(client);
   const workspacesApi = new WorkspacesApi(client);
+  const discoveryService = new DiscoveryService();
+  const guestTokenService = new GuestTokenService(guestTokenApi);
   return {
     embedsApi,
     dashboardsApi,
@@ -881,9 +1071,17 @@ function createServiceBundle(client) {
     datasourcesApi,
     workspacesApi,
     queryApi,
+    widgetsApi,
     embedService: new EmbedService(embedsApi, datamartsApi),
-    discoveryService: new DiscoveryService(),
-    guestTokenService: new GuestTokenService(guestTokenApi)
+    discoveryService,
+    guestTokenService,
+    widgetService: new WidgetService(
+      widgetsApi,
+      embedsApi,
+      dataAppsApi,
+      guestTokenService,
+      discoveryService
+    )
   };
 }
 
@@ -1281,6 +1479,7 @@ function registerListDatasources(server, client) {
         return toolSuccess(JSON.stringify({
           count: active.length,
           datasources: active.map((ds) => ({
+            id: ds.id,
             name: ds.name,
             type: ds.dbName || ds.datasourceType || "unknown"
           })),
@@ -4012,6 +4211,324 @@ You can now:
   );
 }
 
+// src/tools/widgets/list-widgets.ts
+import { z as z21 } from "zod";
+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.",
+    {
+      embedId: z21.string().describe("Embed ID (customer dashboard instantiation)"),
+      clientId: z21.string().describe("Client/tenant identifier for this embed")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const widgets = await services.widgetsApi.listWidgets(
+          params.embedId,
+          params.clientId
+        );
+        if (!Array.isArray(widgets) || widgets.length === 0) {
+          return toolSuccess(
+            `No widgets found on embed "${params.embedId}" for client "${params.clientId}".`
+          );
+        }
+        return toolSuccess(
+          JSON.stringify({
+            count: widgets.length,
+            embedId: params.embedId,
+            clientId: params.clientId,
+            widgets: widgets.map((w) => ({
+              metricId: w.metricId || null,
+              name: w.name || null,
+              isPublished: w.isPublished ?? null,
+              createdByUser: w.createdByUser || null
+            }))
+          })
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/add-widget.ts
+import { z as z22 } from "zod";
+function registerAddWidget(server, client) {
+  const services = createServiceBundle(client);
+  server.tool(
+    "add_widget",
+    "Add a widget (metric) to a customer dashboard embed. Either clone a template via `templateMetricId` (recommended \u2014 inherits query, chartOptions, datasource), or supply a full spec (name + query + chartOptions + companyIntegrationId). Mints a guest token for the clientId internally.",
+    {
+      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."),
+      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)"),
+      query: z22.string().optional().describe("SQL query body (overrides template)"),
+      chartOptions: z22.record(z22.unknown()).optional().describe("Chart config JSON (chart type, colors, legend, axes). Overrides template."),
+      description: z22.string().optional(),
+      companyIntegrationId: z22.string().optional().describe("Datasource ID. Required when not cloning a template."),
+      integrationName: z22.string().optional(),
+      isPublished: z22.boolean().optional().describe("Publish immediately (default true)"),
+      body: z22.record(z22.unknown()).optional().describe("Raw createMetric body passthrough. If provided, used as-is (after defaults). Overrides all other params.")
+    },
+    WRITE_CREATE,
+    async (params) => {
+      try {
+        const ctx = await services.widgetService.resolveEmbedContext(params.embedId);
+        const dataAppName = params.dataAppName || ctx.dataAppName;
+        if (!dataAppName) {
+          return toolError(
+            `Could not resolve dataAppName for embed "${params.embedId}". Pass \`dataAppName\` explicitly or verify the embed exists via \`list_embeds\`.`
+          );
+        }
+        if (!ctx.externalDashboardId) {
+          return toolError(
+            `Embed "${params.embedId}" has no externalDashboardId \u2014 cannot attach a widget. Verify via \`get_embed_details\`.`
+          );
+        }
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          dataAppName,
+          [params.embedId]
+        );
+        let createBody;
+        if (params.body) {
+          createBody = { ...params.body };
+          if (!createBody.externalDashboardIds || createBody.externalDashboardIds.length === 0) {
+            createBody.externalDashboardIds = [
+              { externalDashboardId: ctx.externalDashboardId }
+            ];
+          }
+        } else if (params.templateMetricId) {
+          const overrides = {};
+          if (params.name !== void 0) overrides.name = params.name;
+          if (params.metricId !== void 0) overrides.metricId = params.metricId;
+          if (params.query !== void 0) overrides.query = params.query;
+          if (params.chartOptions !== void 0) overrides.chartOptions = params.chartOptions;
+          if (params.description !== void 0) overrides.description = params.description;
+          if (params.companyIntegrationId !== void 0) {
+            overrides.companyIntegrationId = params.companyIntegrationId;
+          }
+          if (params.integrationName !== void 0) overrides.integrationName = params.integrationName;
+          if (params.isPublished !== void 0) overrides.isPublished = params.isPublished;
+          createBody = await services.widgetService.buildCloneBody(
+            guestToken,
+            params.templateMetricId,
+            overrides,
+            ctx.externalDashboardId
+          );
+        } else {
+          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.");
+          if (!params.companyIntegrationId) {
+            return toolError(
+              "`companyIntegrationId` is required when not cloning a template. Use `list_datasources` to find the datasource ID, or clone from an existing widget via `templateMetricId`."
+            );
+          }
+          createBody = {
+            name: params.name,
+            metricId: params.metricId || `widget-${Date.now()}`,
+            query: params.query,
+            chartOptions: params.chartOptions || {},
+            description: params.description || "",
+            companyIntegrationId: params.companyIntegrationId,
+            integrationName: params.integrationName,
+            isPublished: params.isPublished ?? true,
+            isCreatedByClient: false,
+            externalDashboardIds: [{ externalDashboardId: ctx.externalDashboardId }]
+          };
+        }
+        const result = await services.widgetsApi.createMetric(guestToken, createBody);
+        if (result.error) {
+          return toolError(
+            `Widget creation failed: ${stringify(result.error)}
+
+Request body sent:
+${JSON.stringify(createBody, null, 2).slice(0, 3e3)}`
+          );
+        }
+        const inserted = result.insert_externalMetrics_one;
+        const newId = inserted?.id || inserted?.metricId || "UNKNOWN_ID";
+        const newMetricId = inserted?.metricId || createBody.metricId;
+        return toolSuccess(
+          `Widget added successfully.
+
+- externalMetricId: \`${newId}\`
+- metricId: \`${newMetricId}\`
+- name: \`${createBody.name}\`
+- embedId: \`${params.embedId}\`
+- clientId: \`${params.clientId}\`
+
+Use \`list_widgets\` to verify, or \`update_widget\`/\`remove_widget\` to adjust.`
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/update-widget.ts
+import { z as z23 } from "zod";
+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.",
+    {
+      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().describe("Data app name the widget lives in (required to mint guest token)"),
+      embedId: z23.string().optional().describe("Optional \u2014 if provided, the guest token is scoped to just this embed."),
+      set: z23.record(z23.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
+    },
+    WRITE_IDEMPOTENT,
+    async (params) => {
+      try {
+        if (!params.set || Object.keys(params.set).length === 0) {
+          return toolError("`set` must contain at least one field to update.");
+        }
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          params.dataAppName,
+          params.embedId ? [params.embedId] : void 0
+        );
+        const result = await services.widgetsApi.updateMetric(guestToken, {
+          externalMetricId: params.externalMetricId,
+          set: params.set
+        });
+        if (result.error) {
+          return toolError(
+            `Widget update failed: ${stringify(result.error)}`
+          );
+        }
+        const updated = result.update_externalMetrics_by_pk;
+        const id = updated?.id || params.externalMetricId;
+        const metricId = updated?.metricId || null;
+        return toolSuccess(
+          `Widget updated successfully.
+
+- externalMetricId: \`${id}\`
+` + (metricId ? `- metricId: \`${metricId}\`
+` : "") + `- fields changed: ${Object.keys(params.set).join(", ")}
+
+Use \`list_widgets\` to verify.`
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/remove-widget.ts
+import { z as z24 } from "zod";
+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.",
+    {
+      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().describe("Data app name the widget lives in (required to mint guest token)"),
+      embedId: z24.string().optional().describe("Optional \u2014 scopes the guest token to this embed.")
+    },
+    DESTRUCTIVE,
+    async (params) => {
+      try {
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          params.dataAppName,
+          params.embedId ? [params.embedId] : void 0
+        );
+        const result = await services.widgetsApi.markArchived(guestToken, {
+          id: params.externalMetricId,
+          clientId: params.clientId
+        });
+        if (result.error) {
+          return toolError(
+            `Widget removal failed: ${stringify(result.error)}`
+          );
+        }
+        return toolSuccess(
+          `Widget removed for client "${params.clientId}".
+
+- externalMetricId: \`${params.externalMetricId}\`
+- clientId: \`${params.clientId}\`
+
+Note: this is a per-client soft delete. The widget remains available for other clients and on the source dashboard.`
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
+// src/tools/widgets/generate-widget.ts
+import { z as z25 } from "zod";
+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 (query, metadata) the caller can review and pass to `add_widget`. Mints a guest token internally.",
+    {
+      clientId: z25.string().describe("Client/tenant identifier"),
+      dataAppName: z25.string().describe("Data app name (required to mint guest token)"),
+      integrationId: z25.string().describe("Datasource ID to generate the widget against. Use `list_datasources` to find."),
+      integrationName: z25.string().describe("Datasource name (matches integrationId)"),
+      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 \u2014 scopes the guest token to this embed.")
+    },
+    READ_ONLY,
+    async (params) => {
+      try {
+        const guestToken = await services.widgetService.mintGuestToken(
+          params.clientId,
+          params.dataAppName,
+          params.embedId ? [params.embedId] : void 0
+        );
+        const result = await services.widgetsApi.generateMetric(guestToken, {
+          integrationId: params.integrationId,
+          integrationName: params.integrationName,
+          userInputs: params.userInputs
+        });
+        const resultRec = result;
+        if (resultRec.error) {
+          return toolError(
+            `Widget generation failed: ${stringify(resultRec.error)}`
+          );
+        }
+        return toolSuccess(
+          JSON.stringify({
+            message: "Draft generated. Review the `query` and `result` fields below, then pass to `add_widget` (using raw `body` passthrough) to persist.",
+            draft: {
+              query: resultRec.query ?? null,
+              result: resultRec.result ?? null,
+              metaData: resultRec.metaData ?? null,
+              timeTaken: resultRec.timeTaken ?? null,
+              error: resultRec.error ?? null
+            }
+          })
+        );
+      } catch (err) {
+        if (err instanceof DatabrainApiError) return err.toToolResponse();
+        return toolError(`Unexpected error: ${err.message}`);
+      }
+    }
+  );
+}
+
 // src/tools/registry.ts
 function registerAllTools(server, client) {
   registerListDatasources(server, client);
@@ -4035,6 +4552,11 @@ function registerAllTools(server, client) {
   registerAskQuestion(server, client);
   registerGetSemanticLayer(server, client);
   registerUpdateSemanticLayer(server, client);
+  registerListWidgets(server, client);
+  registerAddWidget(server, client);
+  registerUpdateWidget(server, client);
+  registerRemoveWidget(server, client);
+  registerGenerateWidget(server, client);
 }
 
 // src/resources/content/getting-started.ts
@@ -7035,6 +7557,77 @@ Suggest a sample question based on the tables you described and run it with \`as
 - For very large schemas (50+ tables), start with the most important tables and expand as needed
 `;
 
+// 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.
+
+**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.**
+
+**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.
+
+**Step 1 \u2014 Identify the target embed**
+STOP and ASK the user:
+- "Which customer/client are we customizing for?" (the \`clientId\`)
+- "Which embed/dashboard?" (the \`embedId\`)
+
+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.
+
+**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?"
+
+**Step 3a \u2014 ADD a widget**
+If the user wants to add a widget, STOP and ASK which sourcing mode:
+
+1. **Clone from template** (cheapest, most common):
+   - ASK for the source \`templateMetricId\` \u2014 or call \`list_widgets\` on the template embed / another customer's embed to help pick.
+   - Call \`add_widget({ embedId, clientId, templateMetricId, name? })\`. The tool inherits query, chartOptions, and datasource from the template.
+
+2. **Fresh spec** (SQL + chart config):
+   - ASK for: \`name\`, \`query\` (SQL), \`chartOptions\` (chart type + config), \`companyIntegrationId\` (datasource ID \u2014 use \`list_datasources\` if needed).
+   - Call \`add_widget({ embedId, clientId, name, query, chartOptions, companyIntegrationId, ... })\`.
+
+3. **AI generate** (NL prompt):
+   - ASK for a prompt describing the widget (e.g., "calls per day over last 30 days") and the \`integrationId\` / \`integrationName\` to query against.
+   - Call \`generate_widget({ clientId, dataAppName, integrationId, integrationName, userInputs: { prompt: "..." } })\`.
+   - Review the returned \`draft\` with the user. If they approve, call \`add_widget({ embedId, clientId, body: <draft + externalDashboardIds> })\` to persist.
+   - If they want changes, re-run \`generate_widget\` with a refined prompt.
+
+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)
+- What to change? (name, query, chartOptions, isPublished, etc.)
+
+Call \`update_widget({ externalMetricId, clientId, dataAppName, 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?"
+
+Wait for explicit confirmation before calling \`remove_widget({ externalMetricId, clientId, dataAppName })\`.
+
+**Step 4 \u2014 Verify**
+Call \`list_widgets({ embedId, clientId })\` 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."
+
+**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.
+- 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.`;
+
 // src/prompts/registry.ts
 var prompts = [
   {
@@ -7061,6 +7654,11 @@ var prompts = [
     name: "populate-semantic-layer",
     description: "Auto-generate and push table/column descriptions to enable natural language querying on a datamart",
     content: populateSemanticLayerPrompt
+  },
+  {
+    name: "customize-customer-dashboard",
+    description: "Add, modify, or remove widgets on a specific customer's dashboard embed. Per-client scope \u2014 changes only affect that customer.",
+    content: customizeCustomerDashboardPrompt
   }
 ];
 function registerAllPrompts(server) {