@databrainhq/mcp-server 0.1.1-test → 0.2.1

package/README.md

@@ -1,71 +1,30 @@
 # @databrainhq/mcp-server
 
-MCP server for Databrain embedded analytics. Connect it to any AI assistant and say **"set up a Databrain embed"** — it walks you through the entire flow interactively.
+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.
 
----
+```
+"What was total revenue last month?"
+"Embed my sales dashboard in my React app"
+```
 
-## Quick Start
+Works with Claude, Cursor, Windsurf, and any MCP-compatible client.
 
-### Prerequisites
+---
 
-- Node.js 18+
-- Databrain Cloud account ([usedatabrain.com](https://usedatabrain.com))
-- Service token (Settings > Service Tokens in Databrain UI)
+## Setup (2 minutes)
 
-### 1. Get Your Service Token
+### 1. Get your Service Token
 
 1. Log in to [Databrain](https://usedatabrain.com)
-2. Go to **Settings > Service Tokens**
+2. Go to **Settings → Service Tokens**
 3. Create a new token and copy it
 
-### 2. Connect to Your AI Assistant
-
-Pick your client below. All configs use the same MCP server — just different config file locations.
-
----
-
-#### Claude Desktop
-
-File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
-
-```json
-{
-  "mcpServers": {
-    "databrain": {
-      "command": "npx",
-      "args": ["@databrainhq/mcp-server"],
-      "env": {
-        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>",
-        "DATABRAIN_API_URL": "https://api.usedatabrain.com"
-      }
-    }
-  }
-}
-```
-
-#### Claude Code (CLI)
+### 2. Add to your AI client
 
-```bash
-claude mcp add databrain -- npx @databrainhq/mcp-server
-```
-
-Then set your token in the environment:
-```bash
-export DATABRAIN_SERVICE_TOKEN="<your-service-token>"
-```
-
-Or add to your project's `.claude/settings.json`:
-```json
-{
-  "env": {
-    "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
-  }
-}
-```
-
-#### Cursor
+<details>
+<summary><b>Cursor</b></summary>
 
-File: `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global)
+Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
 
 ```json
 {
@@ -80,10 +39,12 @@ File: `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global)
   }
 }
 ```
+</details>
 
-#### Windsurf
+<details>
+<summary><b>Claude Desktop</b></summary>
 
-File: `~/.codeium/windsurf/mcp_config.json`
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
@@ -98,17 +59,26 @@ File: `~/.codeium/windsurf/mcp_config.json`
   }
 }
 ```
+</details>
 
-#### ChatGPT (via MCP bridge)
+<details>
+<summary><b>Claude Code (CLI)</b></summary>
 
-ChatGPT doesn't natively support MCP yet. Use an MCP-to-OpenAI bridge like [mcp-bridge](https://github.com/nicobailon/mcp-bridge) or [mcp-openai](https://github.com/AshDevFr/mcp-openai-proxy):
+```bash
+claude mcp add databrain -- npx @databrainhq/mcp-server
+```
 
+Set your token:
 ```bash
-# Example with mcp-bridge
-npx mcp-bridge --config mcp-config.json
+export DATABRAIN_SERVICE_TOKEN="<your-service-token>"
 ```
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
 
-`mcp-config.json`:
 ```json
 {
   "mcpServers": {
@@ -122,199 +92,269 @@ npx mcp-bridge --config mcp-config.json
   }
 }
 ```
+</details>
 
-#### Any MCP-Compatible Client
+<details>
+<summary><b>Any MCP-compatible client</b></summary>
 
-The server uses **stdio transport** by default. Any client that supports MCP stdio can connect:
+The server uses stdio transport. Set environment variables and run:
 
 ```bash
+export DATABRAIN_SERVICE_TOKEN="<your-service-token>"
 npx @databrainhq/mcp-server
 ```
+</details>
 
-Set environment variables before running:
-```bash
-export DATABRAIN_SERVICE_TOKEN="<your-service-token>"
-export DATABRAIN_API_URL="https://api.usedatabrain.com"  # optional, this is the default
-```
+### 3. Start talking
+
+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"**
+
+> **"What was total revenue last month?"**
+
+The assistant walks you through each step interactively — picking your data app, selecting a workspace and dashboard, creating the embed, and generating the frontend code.
 
 ---
 
-### 3. Start Using It
+## What you can ask
+
+### Query your data
+
+Ask questions in natural language — the AI converts them to SQL, runs the query, and returns results with a chart type suggestion.
+
+> "What was total revenue last month?"
+
+> "Show me the monthly revenue trend for the past year"
+
+> "Compare sales by region — break it down by quarter"
+
+No setup required beyond your service token. Use `list_datamarts` to see available data, and the AI handles the rest. Follow-up questions use conversation context for better accuracy.
+
+> "Now show only the top 5 regions"
+
+If results seem off, improve the **semantic layer** — the metadata that helps the AI understand your column names and relationships:
+
+> "Check the semantic layer quality for my orders datamart"
+
+> "Add descriptions and synonyms to improve query accuracy"
+
+### Embed a dashboard
+
+The most common flow. You have dashboards in the Databrain UI and want to embed them.
 
-Once connected, just tell your AI assistant:
+> "Embed my sales dashboard in my React app"
 
-> **"Set up a Databrain dashboard embed"**
+The assistant will: discover your data apps → ensure API token → select workspace → list dashboards → create embed → generate a guest token → give you framework-specific code.
 
-The assistant will use the `setup_embed_interactive` tool to walk you through:
-1. Discovering your data apps (confirms your choice even if there's only one)
-2. Checking/creating an API token
-3. Listing embeds and confirming which one to use
-4. Validating the pipeline with a test guest token
-5. Returning a ready-to-use config block with all IDs and env vars
+### Brand and theme
 
-No need to memorize tool names or API details — the orchestrator handles it.
+Customize colors, fonts, chart styles, responsive breakpoints, and card styling.
+
+> "Make my embed match our brand — primary color #4F46E5, dark mode, Inter font"
+
+> "Apply the corporate theme preset and hide the dashboard name"
+
+### Multi-tenant embeds
+
+Each of your customers gets their own dashboard with row-level security.
+
+> "Create per-client dashboard embeds for my SaaS app"
+
+### Enable self-serve analytics
+
+Let end-users build their own metrics with drag-and-drop or AI-powered chat.
+
+> "Enable metric creation on my embed with the visual builder"
+
+### Filters, localization, permissions
+
+> "Add a date range filter and a region dropdown to my dashboard"
+
+> "Set up French translations for my embed"
+
+> "Lock down the embed so users can only view, not edit"
 
 ---
 
 ## Environment Variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `DATABRAIN_SERVICE_TOKEN` | Yes* | Organization-level token for datasources, data apps, datamarts |
-| `DATABRAIN_API_TOKEN` | No | Data-app-scoped token for embeds, queries, guest tokens. Can be created via `create_api_token` tool |
-| `DATABRAIN_API_URL` | No | API base URL (default: `https://api.usedatabrain.com`) |
-
-*At least one of `DATABRAIN_SERVICE_TOKEN` or `DATABRAIN_API_TOKEN` is required.
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATABRAIN_SERVICE_TOKEN` | **Yes** | — | Org-level token from Settings → Service Tokens. Powers all discovery and setup operations. |
+| `DATABRAIN_API_TOKEN` | No | — | Per-data-app token. Created automatically during setup via `create_api_token`, or set manually if you already have one. |
+| `DATABRAIN_API_URL` | No | `https://api.usedatabrain.com` | API base URL. Only change this for self-hosted Databrain. |
 
 ---
 
-## What's Inside
+## Available Prompts
 
-### Orchestration
-- `setup_embed_interactive` — Interactive step-by-step embed setup. Confirms choices with the user, validates the pipeline, and returns a deterministic config block.
+Prompts are guided workflows your AI assistant can follow. Ask for them by name or describe what you want.
 
-### Tools (38 total)
+| Prompt | What it does |
+|--------|-------------|
+| `embed-existing-dashboard` | Embed a dashboard you've already built in the Databrain UI |
+| `embed-blank-dashboard` | Multi-tenant setup — each client gets their own dashboard |
+| `enable-metric-creation` | Let end-users build metrics (drag-and-drop or AI chat) |
+| `brand-my-embed` | Customize colors, fonts, charts, card styling, responsive layout |
+| `localize-embed` | Multi-language support, translations, calendar format |
+| `secure-my-embed` | Permissions, access controls, role-based guest tokens |
+| `setup-filters` | Dashboard filters — dropdowns, date ranges, server-side filters |
+| `manage-embeds` | List, compare, and review existing embed configurations |
+| `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 |
 
-<details>
-<summary>Infrastructure (3)</summary>
+---
 
-- `list_datasources` — List all connected datasources
-- `create_datasource` — Connect a new database (Postgres, Snowflake, BigQuery, MySQL, Redshift, and more)
-- `sync_datasource` — Trigger schema metadata sync after connecting a database
-</details>
+## Tools Reference
+
+24 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.
 
 <details>
-<summary>Data Apps & Tokens (6)</summary>
-
-- `create_data_app` — Create a logical container for embeds
-- `list_data_apps` — List data apps
-- `create_api_token` — Generate API token scoped to a data app
-- `list_api_tokens` — List API tokens for a data app
-- `rotate_api_token` — Rotate an API token (invalidates the old one)
-- `set_api_token` — Set an existing API token for the current session (no env var needed)
+<summary><b>Infrastructure — Exploration & Linking</b> (5)</summary>
+
+| Tool | Description |
+|------|-------------|
+| `list_datasources` | List connected datasources |
+| `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) |
+| `link_datamart_to_workspace` | Link a datamart to an existing workspace |
 </details>
 
 <details>
-<summary>Datamarts & Semantic Layer (4)</summary>
-
-- `list_datamarts` — List datamarts
-- `create_datamart` — Create a curated subset of tables for analytics
-- `get_semantic_layer_status` — Check semantic layer generation progress
-- `generate_semantic_layer` — Auto-generate semantic layer for AI chat mode
+<summary><b>Data Apps & Tokens</b> (5)</summary>
+
+| Tool | Description |
+|------|-------------|
+| `list_data_apps` | List data apps |
+| `create_data_app` | Create a new data app |
+| `list_api_tokens` | List API tokens for a data app |
+| `create_api_token` | Create and activate an API token |
+| `rotate_api_token` | Rotate an existing API token |
 </details>
 
 <details>
-<summary>Embed Management (7)</summary>
-
-- `create_embed` — Create embed config for a dashboard/metric
-- `list_embeds` — List embed configurations
-- `get_embed_details` — Get full embed details
-- `update_embed` — Update embed access settings, permissions, or theme
-- `delete_embed` — Delete an embed configuration
-- `rename_embed` — Rename an embed
-- `apply_embed_preset` — Apply theme/access presets (light/dark/corporate/minimal + view-only/power-user/export-only/ai-enabled)
+<summary><b>Embeds</b> (7) — Create, configure, and customize embedded dashboards</summary>
+
+| Tool | Description |
+|------|-------------|
+| `create_embed` | Create an embed (standard or multi-tenant with `clientId`) |
+| `list_embeds` | List embed configurations |
+| `get_embed_details` | Get full embed details by ID |
+| `update_embed` | Update embed config (raw patch) |
+| `customize_embed_theme` | Presets, colors, fonts, cards, chart appearance, responsive layout |
+| `configure_embed` | UI options, filters (string/date/number/SQL), i18n, translations |
+| `diagnose_embed_health` | Diagnose malformed embeds + validate runtime readiness |
 </details>
 
 <details>
-<summary>Customization (5)</summary>
+<summary><b>Frontend</b> (2) — Guest tokens and code generation</summary>
 
-- `customize_embed_theme` — Set colors, typography, card styling, dashboard layout, chart fonts, buttons, checkboxes, and more
-- `configure_chart_appearance` — Configure chart tooltip, legend, axes, labels, margins, and color palettes
-- `configure_embed_options` — Toggle ~30 display/permission flags (metric ops, layout, downloads, loaders, UI, custom messages)
-- `configure_filters` — Set up dashboard filters with defaults, date presets, SQL-based options, and visibility
-- `configure_internationalization` — Set language (12 supported), translations, calendar type, and custom messages
+| Tool | Description |
+|------|-------------|
+| `generate_guest_token` | Generate a frontend guest token (server-side) |
+| `generate_embed_code` | Generate integration code (React, Next.js, Vue, Angular, Svelte, vanilla JS) |
 </details>
 
 <details>
-<summary>Frontend Embedding (2)</summary>
+<summary><b>Query & Semantic Layer</b> (3) — Ask questions and manage data documentation</summary>
 
-- `generate_guest_token` — Generate frontend auth token with filters, theme overrides, permissions, and multi-datasource support
-- `generate_embed_code` — Generate framework-specific code (React, Next.js, Vue, Angular, Svelte, SolidJS, vanilla JS)
+| 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) |
 </details>
 
 <details>
-<summary>Data & Analytics (9)</summary>
-
-- `list_dashboards` — List dashboards
-- `list_metrics` — List metrics
-- `query_metric_data` — Fetch metric data
-- `get_dashboard_data` — Fetch all metrics in a dashboard
-- `ask_ai_pilot` — Natural language data questions
-- `download_metric_csv` — Export metric data as CSV
-- `list_scheduled_reports` — List scheduled email reports
-- `export_dashboard` — Export a dashboard as JSON
-- `import_dashboard` — Import a dashboard from JSON
+<summary><b>Discovery & Orchestration</b> (2)</summary>
+
+| Tool | Description |
+|------|-------------|
+| `list_dashboards` | List dashboards (by data app, workspace, or globally) |
+| `setup_embed_interactive` | Guided step-by-step flow for the full embed setup |
 </details>
 
-### Resources (9)
+---
 
-- `databrain://getting-started` — Entity model and onboarding guide
-- `databrain://api-reference` — API endpoint reference
-- `databrain://embedding-guide` — Framework-specific embedding instructions
-- `databrain://filter-reference` — Filter types and operators
-- `databrain://theme-reference` — Theme customization
-- `databrain://web-component-reference` — Web component props
-- `databrain://self-serve-reference` — Self-serve analytics settings
-- `databrain://semantic-layer-guide` — Semantic layer for AI chat
-- `databrain://multi-tenancy-guide` — Multi-tenant row-level security
+## Built-in Knowledge
 
-### Prompts (12)
+The server includes 11 reference guides that your AI assistant can consult automatically:
 
-<details>
-<summary>Setup & Onboarding (4)</summary>
+| Resource | Content |
+|----------|---------|
+| Getting Started | Entity model, onboarding checklist, token types |
+| API Reference | All Databrain API endpoints |
+| Embedding Guide | Framework-specific code (React, Next.js, Vue, Angular, Svelte, vanilla JS) |
+| Theme Reference | Full theme schema — admin theme, component theme, chart appearance |
+| Web Component Reference | All `<dbn-dashboard>` and `<dbn-metric>` attributes |
+| Filter Reference | Filter types, operators, server-side filters |
+| Self-Serve Reference | Permission flags, metric creation modes |
+| Semantic Layer Guide | AI-powered metric creation setup |
+| Multi-Tenancy Guide | Row-level security, clientId patterns, tenant isolation |
+| Use Case Guides | Decision guide for choosing the right setup path |
+| Permission Schema | Embed accessSettings, guest token permissions, precedence rules |
 
-- `explore-data` — Discover available data and dashboards in your workspace
-- `setup-from-scratch` — Full guided setup: datasource → datamarts → dashboard → embed → frontend code
-- `setup-ai-chat` — Enable AI Pilot (natural language Q&A) on your embedded dashboard
-- `setup-multi-tenant` — Configure row-level security so each customer only sees their own data
-</details>
+---
 
-<details>
-<summary>Customization (4)</summary>
+## Troubleshooting
 
-- `brand-my-embed` — Customize colors, fonts, chart styles, and component theme
-- `localize-embed` — Set up multi-language support with translations and locale settings
-- `secure-my-embed` — Configure permissions, access controls, and role-based guest tokens
-- `setup-filters` — Configure dashboard filters: string, date, number, SQL-based, and server-side
-</details>
+### "MISSING_SERVICE_TOKEN" error
 
-<details>
-<summary>Operations & Troubleshooting (4)</summary>
+Your service token isn't set. Check that `DATABRAIN_SERVICE_TOKEN` is in your MCP config's `env` block and restart your AI client.
 
-- `diagnose-embed` — Troubleshoot a broken or misconfigured embed
-- `analyze-data` — Query metrics, export data, apply filters, and ask AI-powered questions
-- `manage-dashboards` — Export, import, and promote dashboards between environments
-- `manage-embeds` — List, compare, rename, delete embeds and rotate API tokens
-</details>
+### "MISSING_API_TOKEN" error
 
----
+This is normal during first-time setup. The assistant will automatically create one via `create_api_token`. If it persists, ask: *"Create an API token for my data app"*.
 
-## For AI/LLM Developers
+### No dashboards found
 
-See [`docs/LLM_INSTRUCTIONS.md`](docs/LLM_INSTRUCTIONS.md) for detailed guidance on:
-- Tool chaining and dependency graph
-- Common workflows (embed, explore, theme, filters, i18n, AI chat, roles, export/import)
-- Error recovery patterns
-- Expected output formats
-- Security guardrails
+This usually means no workspace was selected. Ask the assistant: *"List my workspaces and then show dashboards"*. Dashboards are scoped to workspaces.
 
----
+### Embed not rendering in frontend
+
+1. Check that the guest token is generated **server-side** (never expose API tokens in frontend code)
+2. Verify the embed ID and dashboard ID match
+3. Ask: *"Run a health check on my embed"* — this runs `diagnose_embed_health`
+
+### Theme changes not showing
+
+After updating theme or options, existing guest tokens still carry the old config. Regenerate your guest token or reload your app.
 
-## Development
+### Server won't start
 
+Make sure you have Node.js 18+ installed:
 ```bash
-npm install
-npm run build    # Build with tsup
-npm test         # Run tests with vitest
-npm run dev      # Run with tsx (development)
-npm run lint     # Type check
+node --version  # Should be v18.0.0 or higher
 ```
 
-### Testing with MCP Inspector
+---
+
+## How it works
 
-```bash
-npx @modelcontextprotocol/inspector -- npx tsx src/index.ts
 ```
+Your AI Client ←→ MCP Server ←→ Databrain API
+    (Claude,         (this           (your data,
+     Cursor,        package)         dashboards,
+     etc.)                           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.
+
+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.
+
+---
+
+## Links
+
+- [Databrain](https://usedatabrain.com) — Sign up and create dashboards
+- [Databrain Docs](https://docs.usedatabrain.com) — Full platform documentation
+- [MCP Protocol](https://modelcontextprotocol.io) — Learn about Model Context Protocol
 
 ---