@databrainhq/mcp-server 0.2.7 → 0.2.9

package/dist/index.js

@@ -936,14 +936,192 @@ var asRecord2 = (v) => {
   if (!v || typeof v !== "object" || Array.isArray(v)) return null;
   return v;
 };
+var isActiveDatasource = (ds) => Boolean(ds.isAuthenticated) && !ds.isDisabled;
 var WidgetService = class {
-  constructor(widgetsApi, embedsApi, dataAppsApi, guestTokenService, discoveryService) {
+  constructor(widgetsApi, embedsApi, dataAppsApi, datasourcesApi, guestTokenService, discoveryService) {
     this.widgetsApi = widgetsApi;
     this.embedsApi = embedsApi;
     this.dataAppsApi = dataAppsApi;
+    this.datasourcesApi = datasourcesApi;
     this.guestTokenService = guestTokenService;
     this.discoveryService = discoveryService;
   }
+  /**
+   * 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
+   * tool so business users never have to name the data app when it's
+   * unambiguous.
+   */
+  async resolveDataAppName(provided, embedId) {
+    if (provided) return { ok: true, value: provided };
+    if (embedId) {
+      const ctx = await this.resolveEmbedContext(embedId);
+      if (ctx.dataAppName) return { ok: true, value: ctx.dataAppName };
+    }
+    const apps = await this.dataAppsApi.listDataApps();
+    const normalized = apps.map((a) => this.discoveryService.normalizeDataApp(a)).filter((a) => a.name && a.name !== "Unnamed Data App");
+    if (normalized.length === 1) return { ok: true, value: normalized[0].name };
+    if (normalized.length === 0) {
+      return {
+        ok: false,
+        error: "No data apps found in this workspace. Create one in the Databrain UI first."
+      };
+    }
+    return {
+      ok: false,
+      error: `Multiple data apps exist (${normalized.map((a) => `"${a.name}"`).join(", ")}). Pass \`dataAppName\` explicitly, or pass \`embedId\` to auto-resolve.`
+    };
+  }
+  /**
+   * Resolve a datasource for a widget. Priority:
+   *   1. Explicit integrationId + integrationName (fast path).
+   *   2. One of integrationId/integrationName supplied — look up the other.
+   *   3. Probe existing widgets on the embed for inherited datasource metadata.
+   *   4. Fall back to the sole active datasource in the workspace.
+   * On failure, returns a business-user-friendly error listing the available
+   * datasource names.
+   */
+  async resolveDatasource(guestToken, params) {
+    if (params.integrationId && params.integrationName) {
+      return {
+        ok: true,
+        value: {
+          integrationId: params.integrationId,
+          integrationName: params.integrationName
+        }
+      };
+    }
+    if (params.integrationId || params.integrationName) {
+      return this.completeFromDatasources({
+        integrationId: params.integrationId,
+        integrationName: params.integrationName
+      });
+    }
+    let embedProbe = null;
+    if (params.embedId) {
+      embedProbe = await this.probeDatasourceFromEmbed(
+        guestToken,
+        params.embedId,
+        params.clientId
+      );
+      if (embedProbe.kind === "ok") {
+        return { ok: true, value: embedProbe.value };
+      }
+    }
+    const datasources = await this.datasourcesApi.listDatasources();
+    const named = datasources.filter(isActiveDatasource).filter(
+      (ds) => typeof ds.name === "string" && ds.name.trim().length > 0
+    );
+    if (named.length === 1) {
+      const ds = named[0];
+      const id = ds._id || ds.id || "";
+      const name = ds.name;
+      if (id && name) {
+        return { ok: true, value: { integrationId: id, integrationName: name } };
+      }
+    }
+    if (named.length === 0) {
+      return {
+        ok: false,
+        error: "No datasources found in this workspace. Connect one in the Databrain UI first (technical setup)."
+      };
+    }
+    const nameList = named.map((d) => `"${d.name}"`).join(", ");
+    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.`;
+      } 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.`;
+      }
+    }
+    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.`
+    };
+  }
+  async completeFromDatasources(provided) {
+    const allDatasources = await this.datasourcesApi.listDatasources();
+    const datasources = allDatasources.filter(isActiveDatasource);
+    const matchPredicate = (ds) => {
+      const id2 = ds._id || ds.id || "";
+      const name2 = typeof ds.name === "string" ? ds.name : "";
+      if (provided.integrationId && id2 === provided.integrationId) return true;
+      if (provided.integrationName && name2.toLowerCase() === provided.integrationName.toLowerCase()) {
+        return true;
+      }
+      return false;
+    };
+    const target = datasources.find(matchPredicate);
+    if (!target) {
+      const available = datasources.filter((ds) => typeof ds.name === "string" && ds.name.trim().length > 0).map((ds) => `"${ds.name}"`).join(", ");
+      const inactiveMatch = allDatasources.find(
+        (ds) => !isActiveDatasource(ds) && matchPredicate(ds)
+      );
+      if (inactiveMatch) {
+        const reason = inactiveMatch.isDisabled ? "disabled" : "not authenticated";
+        return {
+          ok: false,
+          error: `Datasource "${inactiveMatch.name ?? provided.integrationName ?? provided.integrationId}" is ${reason}. Fix the connection in the Databrain UI, or pick another datasource. Active options: ${available || "(none)"}.`
+        };
+      }
+      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 : "";
+    if (!id || !name) {
+      return {
+        ok: false,
+        error: `Datasource match is missing id or name (id: "${id}", name: "${name}").`
+      };
+    }
+    return { ok: true, value: { integrationId: id, integrationName: name } };
+  }
+  async probeDatasourceFromEmbed(guestToken, embedId, clientId) {
+    const widgets = await this.widgetsApi.listWidgets(embedId, clientId);
+    const candidates = widgets.filter(
+      (w) => typeof w.metricId === "string" && w.metricId.length > 0
+    );
+    if (candidates.length === 0) return { kind: "no_widgets" };
+    const MAX_PROBES = 5;
+    const toProbe = candidates.slice(0, MAX_PROBES);
+    let fetchErrors = 0;
+    let datasourcesCache = null;
+    for (const widget of toProbe) {
+      let response;
+      try {
+        response = await this.widgetsApi.fetchEmbeddedMetric(
+          guestToken,
+          widget.metricId
+        );
+      } catch {
+        fetchErrors += 1;
+        continue;
+      }
+      const metric = response?.externalMetric;
+      if (!metric || typeof metric !== "object") continue;
+      const rec = metric;
+      const integrationId = typeof rec.companyIntegrationId === "string" && rec.companyIntegrationId ? rec.companyIntegrationId : null;
+      let integrationName = typeof rec.integrationName === "string" && rec.integrationName ? rec.integrationName : null;
+      if (integrationId && !integrationName) {
+        if (!datasourcesCache) {
+          datasourcesCache = await this.datasourcesApi.listDatasources();
+        }
+        const match = datasourcesCache.find((ds) => {
+          const id = ds._id || ds.id || "";
+          return id === integrationId;
+        });
+        if (match && typeof match.name === "string" && match.name) {
+          integrationName = match.name;
+        }
+      }
+      if (integrationId && integrationName) {
+        return { kind: "ok", value: { integrationId, integrationName } };
+      }
+    }
+    return { kind: "no_metric_fields", widgetsTried: toProbe.length, fetchErrors };
+  }
   async resolveEmbedContext(embedId) {
     const response = await this.embedsApi.getByEmbedId(embedId);
     const records = Array.isArray(response) ? response : response ? [response] : [];
@@ -1079,6 +1257,7 @@ function createServiceBundle(client) {
       widgetsApi,
       embedsApi,
       dataAppsApi,
+      datasourcesApi,
       guestTokenService,
       discoveryService
     )
@@ -4261,7 +4440,7 @@ 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.",
+    "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.",
     {
       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)"),
@@ -4272,8 +4451,8 @@ function registerAddWidget(server, client) {
       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(),
+      companyIntegrationId: z22.string().optional().describe("Datasource UUID override. Auto-resolved from `embedId` or sole active datasource; leave blank unless the user explicitly picked one by ID."),
+      integrationName: z22.string().optional().describe('Datasource display name (e.g. "Snowflake"). Use this when the user picks a datasource by name \u2014 the id is looked up automatically.'),
       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.")
     },
@@ -4281,20 +4460,19 @@ function registerAddWidget(server, client) {
     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 dataAppName = await services.widgetService.resolveDataAppName(
+          params.dataAppName,
+          params.embedId
+        );
+        if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
-          dataAppName,
+          dataAppName.value,
           [params.embedId]
         );
         let createBody;
@@ -4326,19 +4504,21 @@ function registerAddWidget(server, client) {
         } 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`."
-            );
-          }
+          const datasource = await services.widgetService.resolveDatasource(guestToken, {
+            embedId: params.embedId,
+            clientId: params.clientId,
+            integrationId: params.companyIntegrationId,
+            integrationName: params.integrationName
+          });
+          if (!datasource.ok) return toolError(datasource.error);
           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,
+            companyIntegrationId: datasource.value.integrationId,
+            integrationName: datasource.value.integrationName,
             isPublished: params.isPublished ?? true,
             isCreatedByClient: false,
             externalDashboardIds: [{ externalDashboardId: ctx.externalDashboardId }]
@@ -4385,8 +4565,8 @@ function registerUpdateWidget(server, client) {
     {
       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."),
+      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."),
       set: z23.record(z23.unknown()).describe("Partial patch. Keys can include: name, query, chartOptions, description, isPublished, isLive, selectedGroupBy, drillDownSettings, limit, etc.")
     },
     WRITE_IDEMPOTENT,
@@ -4395,9 +4575,14 @@ 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 dataAppName = await services.widgetService.resolveDataAppName(
+          params.dataAppName,
+          params.embedId
+        );
+        if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
-          params.dataAppName,
+          dataAppName.value,
           params.embedId ? [params.embedId] : void 0
         );
         const result = await services.widgetsApi.updateMetric(guestToken, {
@@ -4439,15 +4624,20 @@ function registerRemoveWidget(server, client) {
     {
       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.")
+      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.")
     },
     DESTRUCTIVE,
     async (params) => {
       try {
+        const dataAppName = await services.widgetService.resolveDataAppName(
+          params.dataAppName,
+          params.embedId
+        );
+        if (!dataAppName.ok) return toolError(dataAppName.error);
         const guestToken = await services.widgetService.mintGuestToken(
           params.clientId,
-          params.dataAppName,
+          dataAppName.value,
           params.embedId ? [params.embedId] : void 0
         );
         const result = await services.widgetsApi.markArchived(guestToken, {
@@ -4493,8 +4683,7 @@ function registerGenerateWidget(server, client) {
     READ_ONLY,
     async (params) => {
       try {
-        const dataAppName = await resolveDataAppName(
-          services,
+        const dataAppName = await services.widgetService.resolveDataAppName(
           params.dataAppName,
           params.embedId
         );
@@ -4504,7 +4693,7 @@ function registerGenerateWidget(server, client) {
           dataAppName.value,
           params.embedId ? [params.embedId] : void 0
         );
-        const datasource = await resolveDatasource(services, guestToken, {
+        const datasource = await services.widgetService.resolveDatasource(guestToken, {
           embedId: params.embedId,
           clientId: params.clientId,
           integrationId: params.integrationId,
@@ -4545,177 +4734,6 @@ function registerGenerateWidget(server, client) {
     }
   );
 }
-function isActiveDatasource(ds) {
-  return Boolean(ds.isAuthenticated) && !ds.isDisabled;
-}
-async function resolveDataAppName(services, provided, embedId) {
-  if (provided) return { ok: true, value: provided };
-  if (embedId) {
-    const ctx = await services.widgetService.resolveEmbedContext(embedId);
-    if (ctx.dataAppName) return { ok: true, value: ctx.dataAppName };
-  }
-  const apps = await services.dataAppsApi.listDataApps();
-  const normalized = apps.map((a) => services.discoveryService.normalizeDataApp(a)).filter((a) => a.name && a.name !== "Unnamed Data App");
-  if (normalized.length === 1) return { ok: true, value: normalized[0].name };
-  if (normalized.length === 0) {
-    return {
-      ok: false,
-      error: "No data apps found in this workspace. Create one in the Databrain UI first."
-    };
-  }
-  return {
-    ok: false,
-    error: `Multiple data apps exist (${normalized.map((a) => `"${a.name}"`).join(", ")}). Pass \`dataAppName\` explicitly, or pass \`embedId\` to auto-resolve.`
-  };
-}
-async function resolveDatasource(services, guestToken, params) {
-  if (params.integrationId && params.integrationName) {
-    return {
-      ok: true,
-      value: {
-        integrationId: params.integrationId,
-        integrationName: params.integrationName
-      }
-    };
-  }
-  if (params.integrationId || params.integrationName) {
-    return completeFromDatasources(services, {
-      integrationId: params.integrationId,
-      integrationName: params.integrationName
-    });
-  }
-  let embedProbe = null;
-  if (params.embedId) {
-    embedProbe = await probeDatasourceFromEmbed(
-      services,
-      guestToken,
-      params.embedId,
-      params.clientId
-    );
-    if (embedProbe.kind === "ok") {
-      return {
-        ok: true,
-        value: {
-          integrationId: params.integrationId || embedProbe.value.integrationId,
-          integrationName: params.integrationName || embedProbe.value.integrationName
-        }
-      };
-    }
-  }
-  const datasources = await services.datasourcesApi.listDatasources();
-  const named = datasources.filter(isActiveDatasource).filter(
-    (ds) => typeof ds.name === "string" && ds.name.trim().length > 0
-  );
-  if (named.length === 1) {
-    const ds = named[0];
-    const id = ds._id || ds.id || "";
-    const name = ds.name;
-    if (id && name) {
-      return { ok: true, value: { integrationId: id, integrationName: name } };
-    }
-  }
-  if (named.length === 0) {
-    return {
-      ok: false,
-      error: "No datasources found in this workspace. Connect one in the Databrain UI first (technical setup)."
-    };
-  }
-  const nameList = named.map((d) => `"${d.name}"`).join(", ");
-  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.`;
-    } 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.`;
-    }
-  }
-  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.`
-  };
-}
-async function completeFromDatasources(services, provided) {
-  const allDatasources = await services.datasourcesApi.listDatasources();
-  const datasources = allDatasources.filter(isActiveDatasource);
-  const matchPredicate = (ds) => {
-    const id2 = ds._id || ds.id || "";
-    const name2 = typeof ds.name === "string" ? ds.name : "";
-    if (provided.integrationId && id2 === provided.integrationId) return true;
-    if (provided.integrationName && name2.toLowerCase() === provided.integrationName.toLowerCase()) {
-      return true;
-    }
-    return false;
-  };
-  const target = datasources.find(matchPredicate);
-  if (!target) {
-    const available = datasources.filter((ds) => typeof ds.name === "string" && ds.name.trim().length > 0).map((ds) => `"${ds.name}"`).join(", ");
-    const inactiveMatch = allDatasources.find(
-      (ds) => !isActiveDatasource(ds) && matchPredicate(ds)
-    );
-    if (inactiveMatch) {
-      const reason = inactiveMatch.isDisabled ? "disabled" : "not authenticated";
-      return {
-        ok: false,
-        error: `Datasource "${inactiveMatch.name ?? provided.integrationName ?? provided.integrationId}" is ${reason}. Fix the connection in the Databrain UI, or pick another datasource. Active options: ${available || "(none)"}.`
-      };
-    }
-    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 : "";
-  if (!id || !name) {
-    return {
-      ok: false,
-      error: `Datasource match is missing id or name (id: "${id}", name: "${name}").`
-    };
-  }
-  return { ok: true, value: { integrationId: id, integrationName: name } };
-}
-async function probeDatasourceFromEmbed(services, guestToken, embedId, clientId) {
-  const widgets = await services.widgetsApi.listWidgets(embedId, clientId);
-  const candidates = widgets.filter(
-    (w) => typeof w.metricId === "string" && w.metricId.length > 0
-  );
-  if (candidates.length === 0) return { kind: "no_widgets" };
-  const MAX_PROBES = 5;
-  const toProbe = candidates.slice(0, MAX_PROBES);
-  let fetchErrors = 0;
-  let datasourcesCache = null;
-  for (const widget of toProbe) {
-    let response;
-    try {
-      response = await services.widgetsApi.fetchEmbeddedMetric(
-        guestToken,
-        widget.metricId
-      );
-    } catch {
-      fetchErrors += 1;
-      continue;
-    }
-    const metric = response?.externalMetric;
-    if (!metric || typeof metric !== "object") continue;
-    const rec = metric;
-    const integrationId = typeof rec.companyIntegrationId === "string" && rec.companyIntegrationId ? rec.companyIntegrationId : null;
-    let integrationName = typeof rec.integrationName === "string" && rec.integrationName ? rec.integrationName : null;
-    if (integrationId && !integrationName) {
-      if (!datasourcesCache) {
-        datasourcesCache = await services.datasourcesApi.listDatasources();
-      }
-      const match = datasourcesCache.find((ds) => {
-        const id = ds._id || ds.id || "";
-        return id === integrationId;
-      });
-      if (match && typeof match.name === "string" && match.name) {
-        integrationName = match.name;
-      }
-    }
-    if (integrationId && integrationName) {
-      return { kind: "ok", value: { integrationId, integrationName } };
-    }
-  }
-  return { kind: "no_metric_fields", widgetsTried: toProbe.length, fetchErrors };
-}
 
 // src/tools/registry.ts
 function registerAllTools(server, client) {