@databrainhq/mcp-server 0.2.11 → 0.2.12

package/README.md

@@ -118,7 +118,7 @@ Running Databrain on your own infrastructure? Point the MCP server at your insta
       "command": "npx",
       "args": ["@databrainhq/mcp-server"],
       "env": {
-        "DATABRAIN_PAT": "<your-personal-access-token>",
+        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>",
         "DATABRAIN_API_URL": "https://api.your-databrain.example.com"
       }
     }
@@ -129,7 +129,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_PAT` (Settings → Personal Access Tokens) for per-user role checks and audit. Use `DATABRAIN_SERVICE_TOKEN` if you want the MCP server to act with full org-level privileges (no per-user audit).
+- 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.
 - 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.
 
@@ -139,7 +139,7 @@ Open your AI assistant and try any of these:
 
 > **"Set up a Databrain embed for my dashboard"**
 
-> **"Brand my embed to match our company colors"**
+> **"Brand my embed to match our colors"**
 
 > **"What was total revenue last month?"**
 
@@ -195,13 +195,21 @@ Each of your customers gets their own dashboard with row-level security.
 
 Add, remove, or modify widgets (metrics) on a specific customer's embed without opening the Databrain UI. Clone from a template widget, write a fresh SQL spec, or generate one from a prompt. End with a demo link to verify exactly what that customer will see — same URL the UI's "Share Demo Link" generates.
 
-> "Add the 'Calls per day' widget from the standard template to Acme's dashboard"
+> "Add the 'Calls per day' widget from the standard template to a client's dashboard"
 
-> "Generate a widget showing disqualification reasons for Acme and add it to their embed"
+> "Generate a widget showing disqualification reasons and add it to a client's embed"
 
-> "Remove the billing widget from Acme's dashboard but keep it for other customers"
+> "Remove the billing widget from one client's dashboard but keep it for other clients"
 
-> "Give me a demo link for Acme's dashboard so I can see what they'll see"
+> "Give me a demo link for a client's dashboard so I can see what they'll see"
+
+### Migrate validated SQL into metrics
+
+Turn warehouse-validated SQL into Databrain metrics with a production-safe flow: validate the target dashboard/datasource, produce a dry-run plan, then apply only after explicit confirmation.
+
+> "Validate this SQL as a new metric on my operations dashboard"
+
+> "Dry-run creating this converted query as a metric, then show me the exact apply plan"
 
 ### Enable self-serve analytics
 
@@ -221,17 +229,16 @@ Let end-users build their own metrics with drag-and-drop or AI-powered chat.
 
 ## Environment Variables
 
-At least one of `DATABRAIN_PAT`, `DATABRAIN_SERVICE_TOKEN`, or `DATABRAIN_API_TOKEN` must be set. PAT is preferred — it binds the MCP session to a specific user so role checks and audit logs work correctly.
+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.
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `DATABRAIN_PAT` | One of three† | — | Personal Access Token from Settings → Personal Access Tokens. Binds the MCP session to your Databrain user — actions are role-checked and audited under your account. **Preferred for sandboxed hosts** (Claude Desktop, ChatGPT Desktop) and headless/CI environments where local credential caching isn't reliable. |
-| `DATABRAIN_SERVICE_TOKEN` | One of three† | — | Org-level token from Settings → Service Tokens. Powers all discovery and setup operations. The `connect` tool can mint a PAT on top of this for per-user audit. |
-| `DATABRAIN_API_TOKEN` | One of three† | — | Per-data-app token. Created automatically during setup via `create_api_token`, or set manually if you already have one. |
+| `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_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`). |
 
-† At least one of these three credentials must be set. Token resolution priority: `DATABRAIN_PAT` > cached PAT (from `connect`) > `DATABRAIN_SERVICE_TOKEN` > `DATABRAIN_API_TOKEN`.
+† At least one of these two credentials must be set. Token resolution priority: `DATABRAIN_SERVICE_TOKEN` > `DATABRAIN_API_TOKEN`.
 
 ---
 
@@ -247,17 +254,18 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `brand-my-embed` | Customize colors, fonts, charts, card styling, responsive layout |
 | `query-data` | Query your data with natural language, manage the semantic layer |
 | `populate-semantic-layer` | Auto-generate table/column descriptions to enable natural language querying |
+| `sql-to-metric-migration` | Production-safe SQL-to-metric workflow: validate, dry-run, then apply with explicit confirmation |
 
 ---
 
 ## Tools Reference
 
-29 tools organized by category. Your AI assistant picks the right tools automatically — you don't need to call them directly.
+34 tools organized by category. Your AI assistant picks the right tools automatically — you don't need to call them directly.
 
-> **Note:** Infrastructure creation (datasources, datamarts, workspaces) is done in the **Databrain UI**. However, the **semantic layer** is populated via MCP tools (`get_semantic_layer`, `update_semantic_layer`) — the AI auto-generates descriptions from column names.
+> **Note:** Datasource and workspace creation happen outside MCP. Datamarts can be planned with `create_datamart` in `dry_run` mode and created only with `confirm: "APPLY_TO_PRODUCTION"`. The semantic layer is managed via MCP tools (`get_semantic_layer`, `update_semantic_layer`, `start_semantic_layer_generation`, `get_semantic_layer_generation_status`).
 
 <details>
-<summary><b>Infrastructure — Exploration</b> (4)</summary>
+<summary><b>Infrastructure — Exploration and setup</b> (6)</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -265,6 +273,8 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `discover_datasource_schema` | Inspect a datasource to see available tables and columns |
 | `list_datamarts` | List datamarts |
 | `list_workspaces` | List all workspaces (shows datamart/datasource connections) |
+| `sync_datasource` | Trigger datasource schema sync |
+| `create_datamart` | Dry-run or create a datamart from selected tables and relationships |
 </details>
 
 <details>
@@ -302,28 +312,41 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 </details>
 
 <details>
-<summary><b>Query & Semantic Layer</b> (3) — Ask questions and manage data documentation</summary>
+<summary><b>Query & Semantic Layer</b> (5) — Ask questions and manage data documentation</summary>
 
 | Tool | Description |
 |------|-------------|
 | `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 |
+| `get_semantic_layer_generation_status` | Check semantic-layer generation progress |
 </details>
 
 <details>
-<summary><b>Dashboards & Widgets</b> (6) — Discover dashboards and CRUD widgets on customer embeds</summary>
+<summary><b>Dashboards & Widgets</b> (8) — Discover dashboards and CRUD widgets on customer embeds</summary>
 
 | Tool | Description |
 |------|-------------|
 | `list_dashboards` | List dashboards (by data app, workspace, or globally) |
 | `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` |
 | `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.
+Production writes through `create_or_update_metric_from_query` default to `dry_run`; `apply` requires `confirm: "APPLY_TO_PRODUCTION"`.
+</details>
+
+<details>
+<summary><b>Scheduled Reports</b> (1)</summary>
+
+| 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 |
 </details>
 
 ---