@databrainhq/mcp-server 0.2.16 → 0.2.17

package/dist/index.js

@@ -187,6 +187,10 @@ var logger = {
 // src/version.ts
 var MCP_SERVER_VERSION = "0.2.10";
 
+// src/utils/tool-context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var toolContext = new AsyncLocalStorage();
+
 // src/client/databrain-client.ts
 var MCP_USER_AGENT = `databrain-mcp-server/${MCP_SERVER_VERSION}`;
 var MAX_RETRIES = 3;
@@ -282,6 +286,13 @@ var DatabrainClient = class {
           "User-Agent": MCP_USER_AGENT,
           "X-Databrain-Client": MCP_USER_AGENT
         };
+        const ctx = toolContext.getStore();
+        if (ctx) {
+          headers["X-Databrain-MCP-Tool"] = ctx.tool;
+          headers["X-Databrain-MCP-Tool-Category"] = ctx.category;
+          headers["X-Databrain-MCP-Workflow-Intent"] = ctx.workflowIntent;
+          headers["X-Databrain-MCP-Input-Mode"] = ctx.inputMode;
+        }
         if (token) {
           if (options.auth === "none") {
             headers["x-plugin-token"] = token;
@@ -356,6 +367,68 @@ var DatabrainClient = class {
   }
 };
 
+// src/tools/tool-metadata.ts
+var DEFAULT_TOOL_META = {
+  category: "discovery",
+  workflowIntent: "other"
+};
+var TOOL_METADATA = {
+  // Identity / discovery
+  whoami: { category: "discovery", workflowIntent: "discovery" },
+  // Infrastructure / data setup
+  list_datasources: { category: "infrastructure", workflowIntent: "setup_data" },
+  discover_datasource_schema: { category: "infrastructure", workflowIntent: "setup_data" },
+  list_datamarts: { category: "infrastructure", workflowIntent: "setup_data" },
+  list_workspaces: { category: "infrastructure", workflowIntent: "setup_data" },
+  sync_datasource: { category: "infrastructure", workflowIntent: "setup_data" },
+  create_datamart: { category: "infrastructure", workflowIntent: "setup_data" },
+  // Embedding — data apps & tokens
+  list_data_apps: { category: "embedding", workflowIntent: "embed_dashboard" },
+  list_tenants: { category: "embedding", workflowIntent: "embed_dashboard" },
+  create_data_app: { category: "embedding", workflowIntent: "embed_dashboard" },
+  list_api_tokens: { category: "embedding", workflowIntent: "embed_dashboard" },
+  create_api_token: { category: "embedding", workflowIntent: "embed_dashboard" },
+  rotate_api_token: { category: "embedding", workflowIntent: "embed_dashboard" },
+  // Embedding — embed management
+  create_embed: { category: "embedding", workflowIntent: "embed_dashboard" },
+  list_embeds: { category: "embedding", workflowIntent: "embed_dashboard" },
+  get_embed_details: { category: "embedding", workflowIntent: "embed_dashboard" },
+  update_embed: { category: "embedding", workflowIntent: "embed_dashboard" },
+  customize_embed_theme: { category: "embedding", workflowIntent: "embed_dashboard" },
+  get_demo_link: { category: "embedding", workflowIntent: "embed_dashboard" },
+  // Embedding — frontend
+  generate_guest_token: { category: "embedding", workflowIntent: "embed_dashboard" },
+  generate_embed_code: { category: "embedding", workflowIntent: "embed_dashboard" },
+  // Embedding — customer dashboards & widgets
+  list_dashboards: { category: "embedding", workflowIntent: "embedded_widget" },
+  list_widgets: { category: "embedding", workflowIntent: "embedded_widget" },
+  add_widget: { category: "embedding", workflowIntent: "embedded_widget" },
+  update_widget: { category: "embedding", workflowIntent: "embedded_widget" },
+  remove_widget: { category: "embedding", workflowIntent: "embedded_widget" },
+  generate_widget: { category: "embedding", workflowIntent: "embedded_widget" },
+  validate_metric_spec: { category: "embedding", workflowIntent: "sql_to_embedded_metric" },
+  create_or_update_metric_from_query: {
+    category: "embedding",
+    workflowIntent: "sql_to_embedded_metric"
+  },
+  // Internal analytics
+  create_workspace_metric: {
+    category: "internal_analytics",
+    workflowIntent: "sql_to_workspace_metric"
+  },
+  ask_question: { category: "internal_analytics", workflowIntent: "query_data" },
+  // Semantic layer
+  get_semantic_layer: { category: "semantic_layer", workflowIntent: "query_data" },
+  update_semantic_layer: { category: "semantic_layer", workflowIntent: "query_data" },
+  start_semantic_layer_generation: { category: "semantic_layer", workflowIntent: "query_data" },
+  get_semantic_layer_generation_status: {
+    category: "semantic_layer",
+    workflowIntent: "query_data"
+  },
+  // Reports
+  list_scheduled_reports: { category: "reports", workflowIntent: "reports" }
+};
+
 // src/tools/data-app/list-data-apps.ts
 import { z as z2 } from "zod";
 
@@ -5868,7 +5941,7 @@ function registerCreateOrUpdateMetricFromQuery(server, client) {
   const services = createServiceBundle(client);
   server.tool(
     "create_or_update_metric_from_query",
-    "Create or update a production metric/widget from validated SQL. Defaults to dry-run; apply requires explicit confirmation.",
+    "[EMBEDDING] Create or update a production metric/widget on a customer dashboard from validated SQL. Requires clientId (multi-tenant embed). Defaults to dry-run; apply requires explicit confirmation.",
     {
       mode: modeSchema.describe("dry_run returns the plan only; apply executes after confirmation"),
       confirm: z30.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
@@ -6051,21 +6124,25 @@ var modeSchema2 = z31.enum(["dry_run", "apply"]).default("dry_run");
 function registerCreateWorkspaceMetric(server, client) {
   server.tool(
     "create_workspace_metric",
-    "Create a workspace-level metric from validated SQL using the org service token. Scoped to the workspace, unpublished, and NOT attached to any dashboard. Defaults to dry-run; apply requires explicit confirmation.",
+    "[INTERNAL ANALYTICS] Create or update a workspace-level metric from validated SQL (migrating your SQL into Databrain), not embedding. Pass an existing metricId to update in place \u2014 query and Dimensions/Measures re-hydrated, publish state preserved; omit to create. Workspace-scoped, unattached. Uses the org service token. Defaults to dry-run; apply needs confirmation.",
     {
       mode: modeSchema2.describe(
-        "dry_run validates the SQL only (no write); apply creates the metric after confirmation"
+        "dry_run validates the SQL only (no write); apply creates or updates the metric after confirmation"
       ),
       confirm: z31.string().optional().describe(`Required for apply: ${APPLY_TO_PRODUCTION_CONFIRMATION}`),
       workspaceName: z31.string().describe("Target workspace name"),
       name: z31.string().describe("Metric display name"),
       query: z31.string().describe("SQL query to validate and store"),
-      metricId: z31.string().optional().describe("Stable metric slug; generated from the name if omitted"),
+      metricId: z31.string().optional().describe(
+        "Stable metric slug. Pass an existing slug to UPDATE that metric in place. Omit to create \u2014 the slug is derived deterministically from the name (no random/uniqueness suffix), so re-running with the same name upserts the same metric rather than creating a duplicate."
+      ),
       description: z31.string().optional().describe("Metric description"),
       datasourceId: z31.string().optional().describe("Datasource UUID override; defaults to the workspace datasource"),
-      isPublished: z31.boolean().optional().describe("Publish after apply. Defaults to false for safety")
+      isPublished: z31.boolean().optional().describe(
+        "Publish after apply. Defaults to false. Applies to creates; on updates the existing publish state is preserved."
+      )
     },
-    WRITE_CREATE,
+    WRITE_IDEMPOTENT,
     async (params) => {
       try {
         const mode = params.mode || "dry_run";
@@ -6102,7 +6179,7 @@ function registerCreateWorkspaceMetric(server, client) {
               mode,
               safety: productionSafetyNote(params.workspaceName),
               result,
-              nextStep: isApply ? "Metric created unpublished and unattached. Publish/attach it to a dashboard as a separate step when ready." : 'Dry-run only \u2014 no metric written. Re-run with mode "apply" and confirm to create it.'
+              nextStep: isApply ? "Saved. If the metricId already existed it was UPDATED in place (query and Dimensions/Measures re-derived; publish state preserved); otherwise a new metric was CREATED, unpublished and unattached. Publish/attach it to a dashboard as a separate step when ready." : 'Dry-run only \u2014 no metric written; it validates the SQL and returns the output columns. Re-run with mode "apply" and confirm to create or update the metric.'
             },
             null,
             2
@@ -6341,7 +6418,30 @@ function registerWhoami(server, client) {
 }
 
 // src/tools/registry.ts
+function instrumentToolRegistration(server) {
+  const original = server.tool.bind(server);
+  server.tool = (...args) => {
+    const name = args[0];
+    const meta = TOOL_METADATA[name] ?? DEFAULT_TOOL_META;
+    const cbIndex = args.length - 1;
+    const cb = args[cbIndex];
+    if (typeof cb === "function") {
+      const handler = cb;
+      args[cbIndex] = (...handlerArgs) => toolContext.run(
+        {
+          tool: name,
+          category: meta.category,
+          workflowIntent: meta.workflowIntent,
+          inputMode: "tool_call"
+        },
+        () => handler(...handlerArgs)
+      );
+    }
+    return original(...args);
+  };
+}
 function registerAllTools(server, client) {
+  instrumentToolRegistration(server);
   registerWhoami(server, client);
   registerListDatasources(server, client);
   registerDiscoverDatasourceSchema(server, client);
@@ -9565,6 +9665,67 @@ list_scheduled_reports({ clientId, dashboardName, workspaceName })
 \`\`\`
 Clarify that this lists configured schedules only. Delivery success/failure history is not yet persisted in the MCP/API surface.`;
 
+// src/prompts/sql-to-workspace-metric.ts
+var sqlToWorkspaceMetricPrompt = `You are helping turn validated warehouse SQL into an INTERNAL Databrain metric \u2014 a workspace-level metric for the team's own analytics. This is NOT embedding: there is no customer, no clientId, and the metric is not attached to any dashboard.
+
+Use this flow when the user says things like "I have this SQL, make it a metric in Databrain", "migrate my query", "add an unpublished metric", or "update/fix the SQL on an existing workspace metric" \u2014 and they are not setting up a customer-facing embed. If the goal is a widget on a customer's embedded dashboard, use the sql-to-metric-migration prompt instead (that one requires a clientId).
+
+**Why this path**
+- \`create_workspace_metric\` is workspace-scoped, unpublished, and uses the org service token. No clientId.
+- It upserts on \`metricId\`: pass an existing metric's \`metricId\` to UPDATE it in place (the query and its Dimensions/Measures are re-derived; archived/draft and publish state are preserved); omit \`metricId\` to CREATE a new metric.
+- The metric is intentionally NOT attached to a dashboard \u2014 attaching/publishing is a separate step the user does later.
+
+**Critical safety rules**
+- Default to dry-run. Never apply on the first pass.
+- Applying requires the exact confirmation string: \`APPLY_TO_PRODUCTION\`.
+- Service-token mode means writes are attributed as system until OAuth ships. State that clearly before apply.
+- Keep \`isPublished: false\` unless the user explicitly asks to publish.
+
+**Minimum inputs**
+- \`workspaceName\`
+- \`name\`
+- \`query\`
+- Optional: \`description\`, \`datasourceId\` (defaults to the workspace datasource), \`metricId\` (a stable slug). **Omit \`metricId\` to create** (it's generated from the name). **To UPDATE an existing metric, pass its exact \`metricId\`** \u2014 carry that same value through BOTH the dry-run and apply calls, or the update won't target the existing metric. If the user is editing a metric and you don't know its \`metricId\`, ask them for the exact slug it was created with (there is no workspace-metric list tool).
+
+**Step 1 \u2014 Confirm the workspace and datasource**
+Call:
+\`\`\`
+list_workspaces
+discover_datasource_schema({ datasourceName })
+\`\`\`
+Confirm the target workspace and that the columns referenced by the SQL exist. This avoids the most common validation failure.
+
+**Step 2 \u2014 Dry-run (validate the SQL, no write)**
+Call:
+\`\`\`
+create_workspace_metric({
+  mode: "dry_run",
+  workspaceName,
+  name,
+  query,
+  description,
+  metricId, // include the existing metricId when UPDATING; omit to create
+  isPublished: false
+})
+\`\`\`
+The dry-run validates the SQL against the workspace datasource and returns the output columns \u2014 it does NOT report whether apply will create or update. Show the result and the output columns. Stop and ask the user to review.
+
+**Step 3 \u2014 Apply only after explicit confirmation**
+Only after the user approves, call:
+\`\`\`
+create_workspace_metric({
+  mode: "apply",
+  confirm: "APPLY_TO_PRODUCTION",
+  workspaceName,
+  name,
+  query,
+  description,
+  metricId, // pass the SAME metricId used in the dry-run when UPDATING
+  isPublished: false
+})
+\`\`\`
+Never invent the confirmation. Pass the same \`metricId\` you used in the dry-run so an update targets the intended metric. On create, the metric is unpublished and unattached; on update, the existing metric is rewritten in place. Either way its Dimensions/Measures are (re-)hydrated from the query, and archived/draft + publish state are preserved on update; tell the user they can publish/attach it to a dashboard as a separate step when ready.`;
+
 // src/prompts/registry.ts
 var prompts = [
   {
@@ -9601,6 +9762,11 @@ var prompts = [
     name: "sql-to-metric-migration",
     description: "Production-safe SQL-to-metric migration workflow: validate, dry-run, then apply with explicit confirmation.",
     content: sqlToMetricMigrationPrompt
+  },
+  {
+    name: "sql-to-workspace-metric",
+    description: "Internal analytics: turn validated SQL into an unpublished workspace metric (no clientId, not embedding). Validate, dry-run, then apply with confirmation.",
+    content: sqlToWorkspaceMetricPrompt
   }
 ];
 function registerAllPrompts(server) {
@@ -9637,18 +9803,23 @@ function createServer(config) {
     {
       name: "databrain",
       version: MCP_SERVER_VERSION,
-      description: "Databrain MCP Server \u2014 embed analytics dashboards and charts into your app. Supports embed setup, semantic-layer maintenance, production dry-run/apply metric creation, theming, filters, permissions, and guest token generation."
+      description: "Databrain MCP Server \u2014 build customer-facing embedded analytics AND run internal analytics on your own data. Supports embed setup, semantic-layer maintenance, natural-language querying, SQL\u2192metric creation (embedded production metrics and unpublished internal workspace metrics), theming, filters, permissions, and guest token generation."
     },
     {
       instructions: operatorBlurb + `Databrain uses two token types \u2014 never confuse them:
 \u2022 SERVICE TOKEN (DATABRAIN_SERVICE_TOKEN): org-level, pre-configured in MCP server config. Used for: list_datasources, discover_datasource_schema, sync_datasource, list_datamarts, create_datamart, list_workspaces, list_data_apps, list_tenants, create_data_app, list_api_tokens, create_api_token, rotate_api_token, list_dashboards (workspace scope), ask_question, get_semantic_layer, update_semantic_layer, start_semantic_layer_generation, get_semantic_layer_generation_status. ${serviceTokenStatus}
 \u2022 API TOKEN (per data app): scoped to one data app, used for embedding operations (list_embeds, get_embed_details, create_embed, update_embed, generate_guest_token), data-app scoped dashboard listing, widget CRUD/metric creation through guest-token APIs, and list_scheduled_reports. ${apiTokenStatus}
 
-4 core use cases \u2014 match the user's scenario to the right prompt:
+FIRST classify the request before calling tools \u2014 this avoids wasted turns:
+\u2022 (A) EMBEDDING: putting Databrain dashboards/charts in front of YOUR customers (data apps, embeds, guest tokens, per-customer dashboard widgets). Needs an API token and usually a clientId.
+\u2022 (B) INTERNAL ANALYTICS: exploring your own data or migrating SQL into your own Databrain metrics for internal use. Workspace-scoped, uses the service token, NO clientId. Creating an unpublished workspace metric (create_workspace_metric) lives here \u2014 it is NOT embedding.
+
+5 core use cases \u2014 match the user's scenario to the right prompt:
 1. Embed existing dashboard \u2192 prompt: embed-existing-dashboard (list_data_apps \u2192 create_api_token \u2192 list_dashboards \u2192 create_embed \u2192 generate_guest_token \u2192 generate_embed_code)
 2. Blank dashboard per client \u2192 prompt: embed-blank-dashboard (list_data_apps \u2192 list_datamarts \u2192 create_embed with clientId per client \u2192 generate_guest_token \u2192 generate_embed_code)
 3. Explore & query data \u2192 prompt: query-data (list_datamarts \u2192 get_semantic_layer \u2192 if empty, auto-generate descriptions with update_semantic_layer or use populate-semantic-layer prompt \u2192 ask_question)
-4. SQL-to-metric migration \u2192 prompt: sql-to-metric-migration (validate_metric_spec \u2192 create_or_update_metric_from_query dry_run \u2192 apply only with explicit production confirmation)
+4. SQL \u2192 embedded production metric on a customer dashboard (EMBEDDING, requires clientId) \u2192 prompt: sql-to-metric-migration (validate_metric_spec \u2192 create_or_update_metric_from_query dry_run \u2192 apply only with explicit production confirmation)
+5. SQL \u2192 unpublished workspace metric (INTERNAL ANALYTICS, no clientId, not attached to any dashboard) \u2192 prompt: sql-to-workspace-metric (discover_datasource_schema \u2192 create_workspace_metric dry_run \u2192 apply with explicit confirmation)
 
 Production safety: OAuth may not be available yet. In service-token mode, writes are actor=system. For create_datamart and create_or_update_metric_from_query, dry_run is the default. Apply requires confirm="APPLY_TO_PRODUCTION" after the user reviews the plan. Widget validation and mutation tools must verify the resolved embed is tenant-scoped for the requested clientId; if not, they must refuse to touch it as a likely production/data-app dashboard. Do not apply from a vague request.