@databrainhq/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,283 @@
+# @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.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- Databrain Cloud account ([usedatabrain.com](https://usedatabrain.com))
+- Service token (Settings > Service Tokens in Databrain UI)
+
+### 1. Get Your Service Token
+
+1. Log in to [Databrain](https://usedatabrain.com)
+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)
+
+```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
+
+File: `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global)
+
+```json
+{
+  "mcpServers": {
+    "databrain": {
+      "command": "npx",
+      "args": ["@databrainhq/mcp-server"],
+      "env": {
+        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
+      }
+    }
+  }
+}
+```
+
+#### Windsurf
+
+File: `~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "databrain": {
+      "command": "npx",
+      "args": ["@databrainhq/mcp-server"],
+      "env": {
+        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
+      }
+    }
+  }
+}
+```
+
+#### ChatGPT (via MCP bridge)
+
+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
+# Example with mcp-bridge
+npx mcp-bridge --config mcp-config.json
+```
+
+`mcp-config.json`:
+```json
+{
+  "mcpServers": {
+    "databrain": {
+      "command": "npx",
+      "args": ["@databrainhq/mcp-server"],
+      "env": {
+        "DATABRAIN_SERVICE_TOKEN": "<your-service-token>"
+      }
+    }
+  }
+}
+```
+
+#### Any MCP-Compatible Client
+
+The server uses **stdio transport** by default. Any client that supports MCP stdio can connect:
+
+```bash
+npx @databrainhq/mcp-server
+```
+
+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 Using It
+
+Once connected, just tell your AI assistant:
+
+> **"Set up a Databrain dashboard embed"**
+
+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
+
+No need to memorize tool names or API details — the orchestrator handles it.
+
+---
+
+## 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.
+
+---
+
+## What's Inside
+
+### Orchestration
+- `setup_embed_interactive` — Interactive step-by-step embed setup. Confirms choices with the user, validates the pipeline, and returns a deterministic config block.
+
+### Tools (28 total)
+
+<details>
+<summary>Infrastructure</summary>
+
+- `list_datasources` — List all connected datasources
+</details>
+
+<details>
+<summary>Data Apps & Tokens</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)
+</details>
+
+<details>
+<summary>Datamarts & Semantic Layer</summary>
+
+- `list_datamarts` — List datamarts
+- `get_semantic_layer_status` — Check semantic layer generation progress
+</details>
+
+<details>
+<summary>Embed Management</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)
+</details>
+
+<details>
+<summary>Frontend Embedding</summary>
+
+- `generate_guest_token` — Generate frontend auth token
+- `generate_embed_code` — Generate framework-specific code (React, Next.js, Vue, Angular, Svelte, SolidJS, vanilla JS)
+</details>
+
+<details>
+<summary>Data & Analytics</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
+</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
+
+### Prompts (1)
+
+- `explore-data` — Discover available data and dashboards in your workspace
+
+---
+
+## For AI/LLM Developers
+
+See [`docs/LLM_INSTRUCTIONS.md`](docs/LLM_INSTRUCTIONS.md) for detailed guidance on:
+- Tool chaining and dependency graph
+- Common workflows (embed, explore, theme, roles, export/import)
+- Error recovery patterns
+- Expected output formats
+- Security guardrails
+
+---
+
+## Development
+
+```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
+```
+
+### Testing with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector -- npx tsx src/index.ts
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }