@databrainhq/mcp-server 0.2.12 → 0.2.14

package/README.md

@@ -1,13 +1,13 @@
 # @databrainhq/mcp-server
 
-Add embedded analytics to your app using natural language. Connect this MCP server to any AI assistant and describe what you want — it handles the Databrain API for you.
+Add embedded analytics to your app using natural language. Connect this MCP server to any AI assistant and describe what you want — it handles the setup steps for you.
 
 ```
 "What was total revenue last month?"
 "Embed my sales dashboard in my React app"
 ```
 
-Works with Claude, Cursor, Windsurf, and any MCP-compatible client.
+Works with Codex, Claude, Cursor, Windsurf, and any MCP-compatible client.
 
 ---
 
@@ -23,6 +23,24 @@ Works with Claude, Cursor, Windsurf, and any MCP-compatible client.
 
 > **Self-hosted?** Also set `DATABRAIN_API_URL` in the `env` block — see [Self-hosted Databrain](#self-hosted-databrain) below.
 
+<details>
+<summary><b>Codex</b></summary>
+
+Add the MCP server with your service token:
+
+```bash
+codex mcp add databrain --env DATABRAIN_SERVICE_TOKEN=YOUR_SERVICE_TOKEN -- npx @databrainhq/mcp-server
+```
+
+Verify the server is configured:
+
+```bash
+codex mcp list
+```
+
+Start a new Codex session after adding the server.
+</details>
+
 <details>
 <summary><b>Cursor</b></summary>
 
@@ -119,7 +137,8 @@ Running Databrain on your own infrastructure? Point the MCP server at your insta
       "args": ["@databrainhq/mcp-server"],
       "env": {
         "DATABRAIN_SERVICE_TOKEN": "<your-service-token>",
-        "DATABRAIN_API_URL": "https://api.your-databrain.example.com"
+        "DATABRAIN_API_URL": "https://api.your-databrain.example.com",
+        "DATABRAIN_DEMO_DOMAIN": "https://demo.your-databrain.example.com"
       }
     }
   }
@@ -129,7 +148,7 @@ Running Databrain on your own infrastructure? Point the MCP server at your insta
 Checklist:
 - `DATABRAIN_API_URL` must be the **API origin** for your self-hosted instance (not the dashboard URL). Typically `https://api.<your-domain>`.
 - The token must be minted from that same self-hosted instance — tokens are not portable across instances.
-- Use `DATABRAIN_SERVICE_TOKEN` (Settings → Service Tokens) for org-level access. Per-user identity binding will arrive with the OAuth-based login flow now in development.
+- Use `DATABRAIN_SERVICE_TOKEN` (Settings → Service Tokens) for org-level access.
 - The MCP client process must be able to reach the URL (VPN, firewall, self-signed certs all apply here).
 - Scaffolded frontend code (React, Next.js, Vue, etc.) reads the same `DATABRAIN_API_URL` for server-side guest-token generation, so the variable flows through to your app.
 
@@ -229,11 +248,11 @@ Let end-users build their own metrics with drag-and-drop or AI-powered chat.
 
 ## Environment Variables
 
-At least one of `DATABRAIN_SERVICE_TOKEN` or `DATABRAIN_API_TOKEN` must be set. Per-user identity binding (OAuth-based login) is in active development — until it ships, sessions authenticate at the org / data-app level.
+At least one of `DATABRAIN_SERVICE_TOKEN` or `DATABRAIN_API_TOKEN` must be set. Use a service token for full setup and management flows; use an API token only when you are operating inside one data app.
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `DATABRAIN_SERVICE_TOKEN` | One of two† | — | Org-level token from Settings → Service Tokens. Powers all discovery and setup operations. Audit logs record actions as `actor=system` until per-user OAuth login ships. |
+| `DATABRAIN_SERVICE_TOKEN` | One of two† | — | Org-level token from Settings → Service Tokens. Powers discovery, setup, data app management, semantic layer, and production-safe datamart operations. |
 | `DATABRAIN_API_TOKEN` | One of two† | — | Per-data-app token. Created automatically during setup via `create_api_token`, or set manually if you already have one. Sufficient for embedding operations on a single data app. |
 | `DATABRAIN_API_URL` | **Required for self-hosted** | `https://api.usedatabrain.com` | API base URL. Set to your instance's API origin (e.g. `https://api.your-databrain.example.com`). |
 | `DATABRAIN_DEMO_DOMAIN` | Optional | `https://demo.usedatabrain.com` | Base host for `get_demo_link` URLs. Override for self-hosted instances or custom preview domains (e.g. `https://demo.your-databrain.example.com`). |
@@ -297,9 +316,9 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `create_embed` | Create an embed (standard or multi-tenant with `clientId`) |
 | `list_embeds` | List embed configurations (includes `distinctClientIds` for multi-tenant client discovery) |
 | `get_embed_details` | Get full embed details by ID |
-| `update_embed` | Update embed config — access settings, options, filters, i18n (via `body` passthrough) |
+| `update_embed` | Update embed config — access settings, options, filters, i18n, and advanced embed options |
 | `customize_embed_theme` | Presets, colors, fonts, cards, chart appearance, responsive layout |
-| `get_demo_link` | Get a shareable demo URL for a `clientId` — same link the UI's "Share Demo Link" generates. Use to preview ops-built widgets without a test app |
+| `get_demo_link` | Get a shareable demo URL for a `clientId` — same link the UI's "Share Demo Link" generates |
 </details>
 
 <details>
@@ -319,7 +338,7 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `ask_question` | Ask a natural language question — gets converted to SQL, returns data + chart suggestion |
 | `get_semantic_layer` | Inspect semantic layer metadata (table/column descriptions, synonyms, completion score) |
 | `update_semantic_layer` | Improve semantic layer quality (add descriptions, synonyms, example questions) |
-| `start_semantic_layer_generation` | Start backend semantic-layer generation for a datamart |
+| `start_semantic_layer_generation` | Start semantic-layer generation for a datamart |
 | `get_semantic_layer_generation_status` | Check semantic-layer generation progress |
 </details>
 
@@ -332,12 +351,12 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `list_widgets` | List widgets on an embed for a specific client |
 | `validate_metric_spec` | Validate a SQL-backed metric target without saving |
 | `create_or_update_metric_from_query` | Dry-run or apply a SQL-backed metric create/update |
-| `add_widget` | Add a widget — clone from a template (`templateMetricId`), supply a full spec, or pass a raw body from `generate_widget` |
+| `add_widget` | Add a widget — clone from a template (`templateMetricId`), supply a metric configuration, or use a generated draft |
 | `update_widget` | Patch a widget's fields (name, query, chartOptions, isPublished, etc.) |
 | `remove_widget` | Per-client soft delete — hides the widget for one client only |
 | `generate_widget` | AI-generate a widget draft from a natural-language prompt. Returns a draft; pass to `add_widget` to persist |
 
-Widget mutation tools mint a guest token internally for `(clientId, dataAppName)`. Provide `embedId` + `clientId` — the tools resolve the rest.
+Provide `clientId` and `dashboardName`; include `workspaceName` only if dashboard names are ambiguous. The tools resolve the required resources automatically.
 Production writes through `create_or_update_metric_from_query` default to `dry_run`; `apply` requires `confirm: "APPLY_TO_PRODUCTION"`.
 </details>
 
@@ -346,7 +365,7 @@ Production writes through `create_or_update_metric_from_query` default to `dry_r
 
 | Tool | Description |
 |------|-------------|
-| `list_scheduled_reports` | List configured scheduled reports for a dashboard/client scope. Delivery history is not part of this MCP/API surface yet |
+| `list_scheduled_reports` | List configured scheduled reports for a dashboard/client scope |
 </details>
 
 ---
@@ -407,13 +426,11 @@ node --version  # Should be v18.0.0 or higher
 ## How it works
 
 ```
-Your AI Client ←→ MCP Server ←→ Databrain API
-    (Claude,         (this           (your data,
-     Cursor,        package)         dashboards,
-     etc.)                           embeds)
+Your AI Client                    MCP Server                  Databrain API
+(Codex, Claude, Cursor, etc.) ←→  (this package)       ←→     (your data, dashboards, embeds)
 ```
 
-The MCP server translates natural language requests into Databrain API calls. It manages authentication (service tokens, API tokens, guest tokens), validates inputs, and provides guided workflows so you don't need to learn the Databrain API directly.
+The MCP server translates natural language requests into Databrain actions. It manages authentication (service tokens, API tokens, guest tokens), validates inputs, and provides guided workflows so you don't need to learn the Databrain API directly.
 
 All tokens are managed automatically. You provide your service token once in the config — everything else is created and handled by the server during setup.
 

package/dist/index.js

@@ -646,7 +646,7 @@ var QueryApi = class {
   async startSemanticLayerGeneration(datamartId) {
     return this.client.request({
       method: "POST",
-      path: `/api/schema/datamart/${encodeURIComponent(datamartId)}/semantic-layer/auto-generate`,
+      path: `/schema/datamart/${encodeURIComponent(datamartId)}/semantic-layer/auto-generate`,
       auth: "service",
       invalidateCache: ["semantic_layer_"]
     });
@@ -654,7 +654,7 @@ var QueryApi = class {
   async getSemanticLayerGenerationStatus(datamartId) {
     return this.client.request({
       method: "GET",
-      path: `/api/schema/datamart/${encodeURIComponent(datamartId)}/semantic-layer/generation-status`,
+      path: `/schema/datamart/${encodeURIComponent(datamartId)}/semantic-layer/generation-status`,
       auth: "service"
     });
   }
@@ -4798,7 +4798,7 @@ var columnSchema2 = z22.object({
     "Identifier",
     "Number",
     "JSON"
-  ]).nullable().optional().describe('Semantic column type. Use "Identifier" for IDs/foreign keys, "Number" for numeric values, "String" for text. Omit for date columns.')
+  ]).nullable().optional().describe('Semantic column type. Use "Identifier" for IDs/foreign keys, "Number" for numeric values, "String" for text. Omit for date and boolean columns.')
 });
 var tableSchema2 = z22.object({
   name: z22.string().describe("Table name (must exist in the datamart)"),
@@ -4811,7 +4811,33 @@ var tableSchema2 = z22.object({
   ),
   columns: z22.array(columnSchema2).optional().describe("Column-level semantic definitions to update")
 });
-function normalizeTablesForApi(tables) {
+function columnKey(tableName, columnName) {
+  return `${tableName.toLowerCase()}\0${columnName.toLowerCase()}`;
+}
+function buildColumnDatatypeMap(semanticLayer) {
+  const datatypes = /* @__PURE__ */ new Map();
+  for (const table of semanticLayer.tables ?? []) {
+    for (const column of table.columns ?? []) {
+      if (column.datatype) {
+        datatypes.set(columnKey(table.name, column.name), column.datatype);
+      }
+    }
+  }
+  return datatypes;
+}
+function hasExplicitColumnType(tables) {
+  return tables?.some(
+    (table) => table.columns?.some(
+      (column) => column.columnType !== void 0 && column.columnType !== null
+    )
+  ) ?? false;
+}
+function shouldOmitColumnTypeForDatatype(datatype) {
+  if (!datatype) return false;
+  const normalized = datatype.trim().toLowerCase();
+  return normalized === "boolean" || normalized === "bool" || normalized === "date" || normalized.startsWith("date(") || normalized.startsWith("datetime") || normalized.startsWith("timestamp") || normalized === "time" || normalized.startsWith("time(") || normalized.startsWith("time ");
+}
+function normalizeTablesForApi(tables, datatypesByColumn) {
   if (!tables) return void 0;
   return tables.map((table) => {
     const normalized = { name: table.name };
@@ -4831,7 +4857,12 @@ function normalizeTablesForApi(tables) {
           normalizedColumn.miscellaneousInfo = column.miscellaneousInfo;
         }
         if (column.columnType !== void 0 && column.columnType !== null) {
-          normalizedColumn.columnType = column.columnType;
+          const datatype = datatypesByColumn?.get(
+            columnKey(table.name, column.name)
+          );
+          if (!shouldOmitColumnTypeForDatatype(datatype)) {
+            normalizedColumn.columnType = column.columnType;
+          }
         }
         return normalizedColumn;
       });
@@ -4874,7 +4905,10 @@ function registerUpdateSemanticLayer(server, client) {
         });
         if (resolution.kind !== "resolved") return resolution.response;
         const datamartName = resolution.name;
-        const tables = normalizeTablesForApi(params.tables);
+        const datatypesByColumn = hasExplicitColumnType(params.tables) ? buildColumnDatatypeMap(
+          await services.queryApi.getSemanticLayer(datamartName)
+        ) : void 0;
+        const tables = normalizeTablesForApi(params.tables, datatypesByColumn);
         await services.queryApi.updateSemanticLayer({
           datamartName,
           tables,
@@ -4911,10 +4945,108 @@ You can now:
 
 // src/tools/query/semantic-generation.ts
 import { z as z23 } from "zod";
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
 function datamartIdFrom(datamart) {
-  return typeof datamart.id === "string" && datamart.id || typeof datamart._id === "string" && datamart._id || typeof datamart.datamartId === "string" && datamart.datamartId || null;
+  return nonEmptyString(datamart.id) || nonEmptyString(datamart._id) || nonEmptyString(datamart.datamartId) || nonEmptyString(datamart.dataMartId) || null;
+}
+function nestedDatamartFromWorkspace(workspace) {
+  const nested = workspace.datamart;
+  return nested && typeof nested === "object" && !Array.isArray(nested) ? nested : null;
+}
+function workspaceDatamartIdFrom(workspace) {
+  const nested = nestedDatamartFromWorkspace(workspace);
+  return nonEmptyString(workspace.dataMartId) || nonEmptyString(workspace.datamartId) || (nested ? datamartIdFrom(nested) : null);
+}
+function workspaceDatamartNameFrom(workspace) {
+  const nested = nestedDatamartFromWorkspace(workspace);
+  return (nested ? nonEmptyString(nested.name) || nonEmptyString(nested.datamartName) : null) || nonEmptyString(workspace.datamartName) || null;
+}
+async function resolveDatamartFromWorkspace(params) {
+  const services = createServiceBundle(params.client);
+  const workspaces = await services.workspacesApi.listWorkspaces();
+  const resolution = resolveResource({
+    items: workspaces,
+    name: params.workspaceName,
+    getName: (ws) => ws.name,
+    formatItem: formatWorkspace,
+    resourceType: "workspace",
+    toolName: params.toolName
+  });
+  if (resolution.kind !== "resolved") return { ok: false, response: resolution.response };
+  const selected = resolution.selected;
+  const datamartId = workspaceDatamartIdFrom(selected);
+  const workspaceDatamartName = workspaceDatamartNameFrom(selected);
+  if (!datamartId) {
+    return {
+      ok: false,
+      response: toolError(
+        `Workspace "${resolution.name}" does not expose a linked dataMartId/datamart.id. Pass datamartId directly or choose a workspace linked to a datamart.`
+      )
+    };
+  }
+  if (params.datamartName && workspaceDatamartName && workspaceDatamartName.toLowerCase() !== params.datamartName.toLowerCase()) {
+    return {
+      ok: false,
+      response: toolError(
+        `Workspace "${resolution.name}" is linked to datamart "${workspaceDatamartName}", not "${params.datamartName}". Use the linked datamart name or choose another workspace.`
+      )
+    };
+  }
+  return {
+    ok: true,
+    datamartName: workspaceDatamartName || params.datamartName || datamartId,
+    datamartId,
+    workspaceName: resolution.name
+  };
+}
+async function findDatamartIdInLinkedWorkspaces(params) {
+  const services = createServiceBundle(params.client);
+  const workspaces = await services.workspacesApi.listWorkspaces();
+  const matches = workspaces.map((workspace) => {
+    const record = workspace;
+    return {
+      name: nonEmptyString(record.name),
+      datamartName: workspaceDatamartNameFrom(record),
+      datamartId: workspaceDatamartIdFrom(record)
+    };
+  }).filter(
+    (workspace) => workspace.datamartName?.toLowerCase() === params.datamartName.toLowerCase() && workspace.datamartId
+  );
+  const uniqueIds = [...new Set(matches.map((workspace) => workspace.datamartId))];
+  if (uniqueIds.length === 1 && uniqueIds[0]) {
+    return {
+      kind: "resolved",
+      datamartId: uniqueIds[0],
+      workspaceName: matches.find((workspace) => workspace.datamartId === uniqueIds[0])?.name || void 0
+    };
+  }
+  if (uniqueIds.length > 1) {
+    return {
+      kind: "ambiguous",
+      workspaceNames: matches.map((workspace) => workspace.name).filter((name) => !!name)
+    };
+  }
+  return { kind: "none" };
 }
 async function resolveDatamart(params) {
+  if (params.datamartId) {
+    return {
+      ok: true,
+      datamartName: params.datamartName || params.datamartId,
+      datamartId: params.datamartId,
+      workspaceName: params.workspaceName
+    };
+  }
+  if (params.workspaceName) {
+    return resolveDatamartFromWorkspace({
+      client: params.client,
+      workspaceName: params.workspaceName,
+      datamartName: params.datamartName,
+      toolName: params.toolName
+    });
+  }
   const services = createServiceBundle(params.client);
   const datamarts = await services.datamartsApi.listDatamarts();
   const resolution = resolveResource({
@@ -4928,10 +5060,30 @@ async function resolveDatamart(params) {
   if (resolution.kind !== "resolved") return { ok: false, response: resolution.response };
   const datamartId = datamartIdFrom(resolution.selected);
   if (!datamartId) {
+    const workspaceMatch = await findDatamartIdInLinkedWorkspaces({
+      client: params.client,
+      datamartName: resolution.name
+    });
+    if (workspaceMatch.kind === "resolved") {
+      return {
+        ok: true,
+        datamartName: resolution.name,
+        datamartId: workspaceMatch.datamartId,
+        workspaceName: workspaceMatch.workspaceName
+      };
+    }
+    if (workspaceMatch.kind === "ambiguous") {
+      return {
+        ok: false,
+        response: toolError(
+          `Datamart "${resolution.name}" is linked from multiple workspaces with different IDs. Call ${params.toolName} again with workspaceName. Matching workspaces: ${workspaceMatch.workspaceNames.join(", ")}`
+        )
+      };
+    }
     return {
       ok: false,
       response: toolError(
-        `Datamart "${resolution.name}" resolved by name but no id/_id/datamartId was returned. Use list_datamarts to verify the API response includes IDs.`
+        `Datamart "${resolution.name}" resolved by name but no id/_id/datamartId/dataMartId was returned and no linked workspace exposed its ID. Pass workspaceName for a workspace linked to this datamart, pass datamartId directly, or update the datamart list API to include IDs.`
       )
     };
   }
@@ -4947,14 +5099,18 @@ function registerStartSemanticLayerGeneration(server, client) {
     "start_semantic_layer_generation",
     "Start backend semantic-layer auto-generation for a datamart. Returns an async job id to poll.",
     {
-      datamartName: z23.string().optional().describe("Datamart name. Omit to list available datamarts")
+      datamartName: z23.string().optional().describe("Datamart name. Omit to list available datamarts"),
+      workspaceName: z23.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
+      datamartId: z23.string().optional().describe("Datamart UUID. Use only when already known.")
     },
     WRITE_CREATE,
     async (params) => {
       try {
         const resolved = await resolveDatamart({
           client,
+          datamartId: params.datamartId,
           datamartName: params.datamartName,
+          workspaceName: params.workspaceName,
           toolName: "start_semantic_layer_generation"
         });
         if (!resolved.ok) return resolved.response;
@@ -4966,8 +5122,9 @@ function registerStartSemanticLayerGeneration(server, client) {
             {
               datamartName: resolved.datamartName,
               datamartId: resolved.datamartId,
+              workspaceName: resolved.workspaceName,
               ...result,
-              nextStep: "Call get_semantic_layer_generation_status with the same datamartName until status is complete or failed."
+              nextStep: "Call get_semantic_layer_generation_status with the same datamartName or workspaceName until status is complete or failed."
             },
             null,
             2
@@ -4986,14 +5143,18 @@ function registerGetSemanticLayerGenerationStatus(server, client) {
     "get_semantic_layer_generation_status",
     "Get semantic-layer auto-generation job status for a datamart.",
     {
-      datamartName: z23.string().optional().describe("Datamart name. Omit to list available datamarts")
+      datamartName: z23.string().optional().describe("Datamart name. Omit to list available datamarts"),
+      workspaceName: z23.string().optional().describe("Workspace linked to the datamart. Use when datamartName resolution needs a dataMartId bridge."),
+      datamartId: z23.string().optional().describe("Datamart UUID. Use only when already known.")
     },
     READ_ONLY,
     async (params) => {
       try {
         const resolved = await resolveDatamart({
           client,
+          datamartId: params.datamartId,
           datamartName: params.datamartName,
+          workspaceName: params.workspaceName,
           toolName: "get_semantic_layer_generation_status"
         });
         if (!resolved.ok) return resolved.response;
@@ -5005,6 +5166,7 @@ function registerGetSemanticLayerGenerationStatus(server, client) {
             {
               datamartName: resolved.datamartName,
               datamartId: resolved.datamartId,
+              workspaceName: resolved.workspaceName,
               ...result
             },
             null,
@@ -8819,7 +8981,7 @@ Guidelines for generating descriptions:
 - **Table descriptions:** Explain what the table contains in 1-2 sentences. Example: \`orders\` \u2192 "Contains customer purchase orders with line items, totals, and fulfillment status."
 - **Column descriptions:** Explain the business meaning. Example: \`total_amount\` \u2192 "Total order value in the customer's local currency, including tax and shipping."
 - **Synonyms:** Add common alternative names users might say. Example: \`total_amount\` \u2192 ["revenue", "order total", "sales amount"]
-- **Column types:** Set semantic types when obvious: "Date", "Number", "Identifier", "Category", "Currency", "Email", "Name", etc.
+- **Column types:** Only use supported semantic types: "String", "Long String", "ENUM", "Mapper", "Range", "Expression", "Identifier", "Number", or "JSON". Omit \`columnType\` for date and boolean database columns.
 
 Ask the user if they want to review and refine the descriptions before applying, or if you should go ahead and apply them directly.