@databrainhq/mcp-server 0.3.0-rc.1 → 0.3.0-rc.10

package/README.md

@@ -13,13 +13,81 @@ Works with Codex, Claude, Cursor, Windsurf, and any MCP-compatible client.
 
 ## Setup (2 minutes)
 
-### 1. Get your Service Token
+There are two ways in. Pick one.
+
+| | Best for | You need |
+|---|---|---|
+| **A. Hosted connector** | Claude, ChatGPT, Cursor, VS Code, Claude Code | Your Databrain sign-in. Nothing to install. |
+| **B. Local server + service token** | Codex, Windsurf, any stdio client, self-hosted Databrain, CI | A service token in the MCP config |
+
+With A you act as yourself: calls run in the workspaces you approve, with your role in each, and the audit log shows your name. With B calls run as the organization (`actor=system`).
+
+### A. Hosted connector
+
+Server URL: **`https://mcp.usedatabrain.com/mcp`** (beta: `https://mcp.beta.usedatabrain.com/mcp`).
+Your AI app opens a Databrain sign-in page, you pick one or more workspaces (or "All workspaces I can access") and click Allow. No token to copy.
+
+When you approve more than one workspace, the AI names the workspace on each call (`workspace` or `workspaceName`); `whoami` lists the ones you approved. With "All workspaces I can access", workspaces you get later are included, and `create_workspace` can make a new one if your role allows it.
+
+The hosted connector includes chart and KPI MCP Apps. `ask_question` returns an inline tile, and `list_widgets` opens a chart chooser in compatible hosts. Both current `_meta.ui.resourceUri` and legacy `_meta['ui/resourceUri']` pointers are included; other hosts retain the text summary and structured data. Tile controls retain the answer's granted workspace. Saving requires `mcp:dashboards:write`, `mcp:query`, the live workspace role, and `APPLY_TO_PRODUCTION` confirmation. No new environment variable is needed, including on self-hosted installs.
+
+<details>
+<summary><b>Claude (claude.ai and Claude Desktop)</b></summary>
+
+Settings > Connectors > **Add custom connector**. Name `Databrain`, URL `https://mcp.usedatabrain.com/mcp`. Click **Connect** and sign in. Custom connectors need a paid Claude plan.
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add --transport http databrain https://mcp.usedatabrain.com/mcp
+```
+
+Then run `/mcp` in Claude Code, pick `databrain` and sign in.
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=databrain&config=eyJ1cmwiOiJodHRwczovL21jcC51c2VkYXRhYnJhaW4uY29tL21jcCJ9)
+
+Or add to `~/.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "databrain": { "url": "https://mcp.usedatabrain.com/mcp" } } }
+```
+
+Cursor signs you in with OAuth the first time a tool runs.
+</details>
+
+<details>
+<summary><b>VS Code (GitHub Copilot agent mode)</b></summary>
+
+[Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=databrain&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.usedatabrain.com%2Fmcp%22%7D), or:
+
+```bash
+code --add-mcp '{"name":"databrain","type":"http","url":"https://mcp.usedatabrain.com/mcp"}'
+```
+
+VS Code asks you to sign in to Databrain when the server starts.
+</details>
+
+<details>
+<summary><b>ChatGPT</b></summary>
+
+Once Databrain is in the ChatGPT directory, search for **Databrain** and connect. Until then, a workspace admin can add it as a custom MCP connection with the URL `https://mcp.usedatabrain.com/mcp` and OAuth ([OpenAI guide](https://developers.openai.com/api/docs/guides/custom-mcp-server)).
+</details>
+
+### B. Local server with a service token
+
+#### 1. Get your Service Token
 
 1. Log in to your Databrain instance (cloud or self-hosted)
 2. Go to **Settings → Service Tokens**
 3. Create a new token and copy it
 
-### 2. Add to your AI client
+#### 2. Add to your AI client
 
 > **Self-hosted?** Also set `DATABRAIN_API_URL` in the `env` block — see [Self-hosted Databrain](#self-hosted-databrain) below.
 
@@ -280,6 +348,27 @@ At least one of `DATABRAIN_SERVICE_TOKEN` or `DATABRAIN_API_TOKEN` must be set.
 
 ---
 
+## Hosted (HTTPS) deployment
+
+`node dist/index.js --http` starts the same server as a hosted Streamable HTTP endpoint at `/mcp`. Callers authenticate with an OAuth bearer token on every request; the server never reads `DATABRAIN_SERVICE_TOKEN` or `DATABRAIN_API_TOKEN` in this mode. Full design notes are in [`specs/hosted-http.md`](specs/hosted-http.md).
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATABRAIN_HOSTED_PUBLIC_URL` | Yes | — | Exact public HTTPS URL of the endpoint, ending in `/mcp` (e.g. `https://mcp.usedatabrain.com/mcp`). Used for discovery metadata and audience checks. |
+| `DATABRAIN_HOSTED_ISSUER` | Yes | — | HTTPS origin of the trusted authorization server. Bearer tokens are verified against `<issuer>/oauth/principal`. |
+| `DATABRAIN_HOSTED_BIND` | No | `127.0.0.1` | Listener address. Set `0.0.0.0` in a container so the load balancer can reach it. |
+| `DATABRAIN_HOSTED_PORT` | No | `3144` | Listener port. |
+
+`GET /health` (or `HEAD`) returns `200 {"status":"ok"}` with no authentication. It is the only route that skips the Host check, so an ALB health check with the target IP:port as Host succeeds. Point the target group health check at `/health`.
+
+The `Dockerfile` at the repo root builds the hosted server from source: `docker build -t databrain-mcp-hosted .` then run it with the two required variables and `-p 3144:3144`.
+
+The load balancer **must forward the original `Host` header unchanged**. Requests to `/mcp` and the `/.well-known/oauth-protected-resource` metadata are answered only when Host matches the host of `DATABRAIN_HOSTED_PUBLIC_URL`; anything else gets `403 invalid_host`.
+
+**Current limits.** Without `DATABRAIN_HOSTED_ADAPTER_MODULE` (an absolute path to a trusted delegated adapter, see the spec), the default adapter verifies identity only. `whoami`, tool/resource/prompt discovery and OAuth verification work today; every data tool answers `503 delegated_backend_adapter_required` until that adapter is configured.
+
+---
+
 ## Available Prompts
 
 Prompts are guided workflows your AI assistant can follow. Ask for them by name or describe what you want.
@@ -298,9 +387,9 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 
 ## Tools Reference
 
-35 tools organized by category. Your AI assistant picks the right tools automatically — you don't need to call them directly.
+50 tools organized by category (plus 6 chart App tools on the hosted connector and the opt-in `databrain-mcp-chart-apps` entry, and `create_workspace` on the hosted connector: 57 hosted tools total). Your AI assistant picks the right tools automatically. You do not need to call them directly.
 
-> **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`).
+> **Note:** Datasource creation happens outside MCP. Workspace creation does too, except on the hosted connector: `create_workspace` works there when you granted "All workspaces I can access" and your role may create workspaces. 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 and setup</b> (6)</summary>
@@ -310,7 +399,8 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `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) |
+| `list_workspaces` | List all workspaces (shows datamart/datasource connections). Hosted: only the workspaces you granted |
+| `create_workspace` | Hosted connector only: create a workspace (needs an "All workspaces" grant and a role that may create one) |
 | `sync_datasource` | Trigger datasource schema sync |
 | `create_datamart` | Dry-run or create a datamart from selected tables and relationships |
 </details>
@@ -351,7 +441,7 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 </details>
 
 <details>
-<summary><b>Query & Semantic Layer</b> (5) — Ask questions and manage data documentation</summary>
+<summary><b>Query & Semantic Layer</b> (11): Ask questions and manage data documentation</summary>
 
 | Tool | Description |
 |------|-------------|
@@ -360,14 +450,37 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 | `update_semantic_layer` | Improve semantic layer quality (add descriptions, synonyms, example questions) |
 | `start_semantic_layer_generation` | Start semantic-layer generation for a datamart |
 | `get_semantic_layer_generation_status` | Check semantic-layer generation progress |
+| `search_semantic_model` | Find relevant v2 entities and their related entities |
+| `get_semantic_entity` | Read one v2 entity by kind and name with the current content hash |
+| `propose_semantic_change` | Validate candidate YAML or a patch and return its plan without writing |
+| `apply_semantic_change` | Preview by default, or apply live with a reviewed hash and production confirmation |
+| `eval_semantic_model` | Run saved queries and optional questions and return pass rate and verdicts |
+
+Semantic-layer generation uses the datamart ID returned by `list_datamarts` and calls the service-token API. Pass `datamartId` directly when the ID is already known.
+
+For a v2 model, the five model tools use `datamartId` and the configured service credential. They never request a token from the user or mint a guest token. Hosted eval also requires `mcp:query`; hosted apply requires `mcp:datamarts:write` even for its dry run.
+
+1. Use `search_semantic_model` with `question` and optional `k` (default 10, maximum 100). If the server has no retrieval route, the tool pulls the model and ranks name, alias, synonyms and description, then includes adjacent entities. Hidden tables and columns are excluded from local search.
+2. Use `get_semantic_entity` with `kind` and an exact `name`. Column names use `table.column`. Kinds are `table`, `column`, `measure`, `metric`, `join`, `entity`, `glossary`, `saved_query`, `instruction` and `access_rule`.
+3. Use `propose_semantic_change` with exactly one of `source` (complete YAML), `yaml_patch`, or `change`. It returns the candidate source, validation errors, the server plan and `expected_content_hash`. Invalid source returns errors and no plan.
+4. Use `eval_semantic_model` with the proposed `source` and optional `questions`. Omitting source evaluates the stored model. The server returns pass rate and individual verdicts.
+5. Review the plan. Call `apply_semantic_change` with the exact returned `source` and `expected_content_hash`. Its `dry_run` defaults to true. A live apply requires `dry_run: false` and user supplied `confirm: "APPLY_TO_PRODUCTION"`. The assistant must never supply confirmation on its own. Explicit `expected_content_hash: null` selects the first apply only when no layer is stored. Apply changes the live model for all consumers.
+
+A YAML patch merges mappings and named lists by name, including tables and columns. Other lists replace the original list. An empty list clears a list. Null removes a field. For example, `yaml_patch: "tables:\n  - name: orders\n    description: Customer purchases\n"` changes that description and preserves other tables and fields. Patch output normalizes YAML formatting and does not preserve comments. Review the returned source.
+
+A structured change uses `{ "operation": "upsert", "kind": "column", "table": "orders", "name": "amount", "value": { "description": "Order total" } }`. Upsert merges fields. Use `operation: "remove"` without `value` to remove one named entity. The backend validates all resulting references.
+
+HTTP 409 conflicts and 422 validation or projection refusals return tool errors with the backend reason and details. A conflict requires a fresh proposal and review. Plan, eval and readiness need the corresponding backend routes; these tools return backend errors if those routes are absent.
+
 </details>
 
 <details>
-<summary><b>Dashboards & Widgets</b> (8) — Discover dashboards and CRUD widgets on customer embeds</summary>
+<summary><b>Dashboards & Widgets</b> (9) — Discover dashboards, picture them, and CRUD widgets on customer embeds</summary>
 
 | Tool | Description |
 |------|-------------|
 | `list_dashboards` | List dashboards (by data app, workspace, or globally) |
+| `dashboard_snapshot` | A PNG of a dashboard or one chart, light or dark, as the signed-in user sees it. Needs a Databrain sign-in (OAuth), not a service token |
 | `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 |
@@ -388,6 +501,38 @@ Production writes through `create_or_update_metric_from_query` default to `dry_r
 | `list_scheduled_reports` | List configured scheduled reports for a dashboard/client scope |
 </details>
 
+<details>
+<summary><b>Custom chart types</b> (5)</summary>
+
+| Tool | Description |
+|------|-------------|
+| `custom_chart_scaffold` | Return the files of a new chart project (manifest, chart.ts, css, icon, sample data, author guide). Nothing is written or persisted |
+| `custom_chart_validate` | Validate a manifest and bundle with the local rules and, when a service token is configured, the server rules. Never persists |
+| `custom_chart_upload` | Dry-run or upload a built bundle as a private chart (version 1) or a preview version; `publish: true` publishes in the same apply |
+| `list_custom_charts` | List the company's custom chart types with status and version ids |
+| `publish_custom_chart` | Dry-run or publish a version so every builder can use chart type `custom:<key>` |
+
+`custom_chart_upload` and `publish_custom_chart` default to `dry_run` and apply only with `confirm: "APPLY_TO_PRODUCTION"`. Hosted scopes: `mcp:custom-charts:read` and `mcp:custom-charts:write`. Build the bundle with the CLI below.
+</details>
+
+---
+
+## Custom chart CLI
+
+The package also installs a `databrain` binary for chart authors:
+
+```bash
+npx -p @databrainhq/mcp-server databrain custom-chart init my-chart
+cd my-chart                                  # read AGENTS.md, edit chart.ts
+databrain custom-chart validate              # manifest, icon, css
+databrain custom-chart build                 # writes dist/index.js, manifest.json, icon.svg, index.css, bundle.zip
+databrain custom-chart dev                   # local sandbox page on http://127.0.0.1:4174
+DATABRAIN_SERVICE_TOKEN=... databrain custom-chart upload            # build, server validate, plan, confirm, upload
+DATABRAIN_SERVICE_TOKEN=... databrain custom-chart upload --publish --yes
+```
+
+Problems print as `path  code  message` and the exit code is 1 when there is any. `upload` needs `DATABRAIN_SERVICE_TOKEN` and, on self-hosted instances, `DATABRAIN_API_URL`. The template's `AGENTS.md` is the full author guide: manifest reference, data shape, theme, interactions, troubleshooting.
+
 ---
 
 ## Built-in Knowledge

package/dist/apps/server.d.ts

@@ -197,8 +197,8 @@ declare const pageSchema: z.ZodEffects<z.ZodObject<{
         drillId: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         value: string | number | boolean | null;
-        label: string;
         key: string;
+        label: string;
         x: number;
         y: number;
         width: number;
@@ -206,8 +206,8 @@ declare const pageSchema: z.ZodEffects<z.ZodObject<{
         drillId?: string | undefined;
     }, {
         value: string | number | boolean | null;
-        label: string;
         key: string;
+        label: string;
         x: number;
         y: number;
         width: number;
@@ -228,8 +228,8 @@ declare const pageSchema: z.ZodEffects<z.ZodObject<{
     rows: Record<string, string | number | boolean | null>[];
     points: {
         value: string | number | boolean | null;
-        label: string;
         key: string;
+        label: string;
         x: number;
         y: number;
         width: number;
@@ -251,8 +251,8 @@ declare const pageSchema: z.ZodEffects<z.ZodObject<{
     rows: Record<string, string | number | boolean | null>[];
     points: {
         value: string | number | boolean | null;
-        label: string;
         key: string;
+        label: string;
         x: number;
         y: number;
         width: number;
@@ -274,8 +274,8 @@ declare const pageSchema: z.ZodEffects<z.ZodObject<{
     rows: Record<string, string | number | boolean | null>[];
     points: {
         value: string | number | boolean | null;
-        label: string;
         key: string;
+        label: string;
         x: number;
         y: number;
         width: number;
@@ -297,8 +297,8 @@ declare const pageSchema: z.ZodEffects<z.ZodObject<{
     rows: Record<string, string | number | boolean | null>[];
     points: {
         value: string | number | boolean | null;
-        label: string;
         key: string;
+        label: string;
         x: number;
         y: number;
         width: number;

package/dist/apps/server.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import {
   createChartAppServer
-} from "../chunk-NDVW3ZSJ.js";
-import "../chunk-7DS7OLWP.js";
+} from "../chunk-N7X762VU.js";
+import "../chunk-5IGP6A6T.js";
+import "../chunk-ERTAKB2H.js";
+import "../chunk-OCBTNAAO.js";
 export {
   createChartAppServer
 };

package/dist/apps/stdio.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import {
   loadConfig
-} from "../chunk-RF3HTNO7.js";
+} from "../chunk-CUPL7CAN.js";
 import {
   createChartAppServer
-} from "../chunk-NDVW3ZSJ.js";
-import "../chunk-7DS7OLWP.js";
+} from "../chunk-N7X762VU.js";
+import "../chunk-5IGP6A6T.js";
+import "../chunk-ERTAKB2H.js";
+import "../chunk-OCBTNAAO.js";
 
 // src/apps/stdio.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/apps/stdio.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/apps/stdio.ts"],"sourcesContent":["import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { loadConfig } from '../utils/config.js';\nimport { createChartAppServer } from './server.js';\n\n// Separate opt-in command until the owners integrate both shared entrypoints.\nconst server = createChartAppServer(loadConfig());\nawait server.connect(new StdioServerTransport());\n"],"mappings":";;;;;;;;;;AAAA,SAAS,4BAA4B;AAKrC,IAAM,SAAS,qBAAqB,WAAW,CAAC;AAChD,MAAM,OAAO,QAAQ,IAAI,qBAAqB,CAAC;","names":[]}
+{"version":3,"sources":["../../src/apps/stdio.ts"],"sourcesContent":["import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { loadConfig } from '../utils/config.js';\nimport { createChartAppServer } from './server.js';\n\n// Separate opt-in command until the owners integrate both shared entrypoints.\nconst server = createChartAppServer(loadConfig());\nawait server.connect(new StdioServerTransport());\n"],"mappings":";;;;;;;;;;;;AAAA,SAAS,4BAA4B;AAKrC,IAAM,SAAS,qBAAqB,WAAW,CAAC;AAChD,MAAM,OAAO,QAAQ,IAAI,qBAAqB,CAAC;","names":[]}