@databrainhq/mcp-server 0.3.0-rc.5 → 0.3.0-rc.7

package/README.md

@@ -319,7 +319,7 @@ Prompts are guided workflows your AI assistant can follow. Ask for them by name
 
 ## Tools Reference
 
-44 tools organized by category (plus 6 chart App tools on the opt-in `databrain-mcp-chart-apps` entry). Your AI assistant picks the right tools automatically. You do not need to call them directly.
+50 tools organized by category (plus 6 chart App tools on the opt-in `databrain-mcp-chart-apps` entry). 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`).
 
@@ -372,7 +372,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 |
 |------|-------------|
@@ -381,8 +381,29 @@ 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_readiness` | Read the server readiness number, verdict and open checks |
 
 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 six 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. Use `semantic_readiness` to read the server score and open checks.
+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>

package/dist/apps/server.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import {
   createChartAppServer
-} from "../chunk-4DYPD273.js";
-import "../chunk-5IQ7MVUH.js";
-import "../chunk-PRE4CGOV.js";
+} from "../chunk-DYFJ5GKQ.js";
+import "../chunk-JSYG7ULR.js";
+import "../chunk-ETXH5HTT.js";
 export {
   createChartAppServer
 };

package/dist/apps/stdio.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   loadConfig
-} from "../chunk-V64ZQINV.js";
+} from "../chunk-VSSGMPSL.js";
 import {
   createChartAppServer
-} from "../chunk-4DYPD273.js";
-import "../chunk-5IQ7MVUH.js";
-import "../chunk-PRE4CGOV.js";
+} from "../chunk-DYFJ5GKQ.js";
+import "../chunk-JSYG7ULR.js";
+import "../chunk-ETXH5HTT.js";
 
 // src/apps/stdio.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/{chunk-4DYPD273.js → chunk-DYFJ5GKQ.js}

@@ -22,13 +22,13 @@ import {
   saveDraftAsDashboard,
   viewSchema,
   workspacesForDatamart
-} from "./chunk-5IQ7MVUH.js";
+} from "./chunk-JSYG7ULR.js";
 import {
   DatabrainApiError,
   DatabrainClient,
   MCP_SERVER_VERSION,
   toolContext
-} from "./chunk-PRE4CGOV.js";
+} from "./chunk-ETXH5HTT.js";
 
 // src/apps/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -513,4 +513,4 @@ function createChartAppServer(config, backend) {
 export {
   createChartAppServer
 };
-//# sourceMappingURL=chunk-4DYPD273.js.map
+//# sourceMappingURL=chunk-DYFJ5GKQ.js.map

package/dist/{chunk-PRE4CGOV.js → chunk-ETXH5HTT.js}

@@ -2,18 +2,20 @@
 
 // src/utils/errors.ts
 var DatabrainApiError = class extends Error {
-  constructor(status, code, message, details) {
+  constructor(status, code, message, details, serverHint, retryable) {
     super(message);
     this.status = status;
     this.code = code;
     this.details = details;
+    this.serverHint = serverHint;
+    this.retryable = retryable;
     this.name = "DatabrainApiError";
   }
   toToolResponse() {
     const parts = [`Error: ${this.message}`];
     const detailDump = this.formatDetails();
     if (detailDump) parts.push(detailDump);
-    const hint = this.hint();
+    const hint = this.serverHint ? `Hint: ${this.serverHint}` : this.hint();
     if (hint) parts.push(hint);
     return {
       content: [{ type: "text", text: parts.join("\n\n") }],
@@ -29,7 +31,7 @@ var DatabrainApiError = class extends Error {
   formatDetails() {
     if (this.status < 400 || this.status >= 500) return "";
     if (!this.details || typeof this.details !== "object") return "";
-    const skipKeys = /* @__PURE__ */ new Set(["message", "detail", "error", "code"]);
+    const skipKeys = /* @__PURE__ */ new Set(["message", "detail", "error", "code", "data", "hint", "retryable"]);
     const extra = {};
     for (const [k, v] of Object.entries(this.details)) {
       if (skipKeys.has(k)) continue;
@@ -44,6 +46,9 @@ var DatabrainApiError = class extends Error {
     }
   }
   hint() {
+    if (this.code === "UNAUTHORIZED_ORIGIN") {
+      return "Hint: The embed origin is not on the allowed domains list. Add the domain to the allowed domains in the Databrain settings; the token itself is fine.";
+    }
     if (this.status === 401 || this.status === 403) {
       if (this.code === "OAUTH_API_ERROR") {
         return "Hint: Check that the backend accepts the configured OAuth issuer and resource, and that the service principal has permission for this operation. Static fallback applies only to token acquisition failures.";
@@ -123,7 +128,7 @@ var logger = {
 // package.json
 var package_default = {
   name: "@databrainhq/mcp-server",
-  version: "0.3.0-rc.5",
+  version: "0.3.0-rc.7",
   description: "MCP server for Databrain embedded analytics - connect databases, create datamarts, configure embeds, and generate frontend code",
   type: "module",
   bin: {
@@ -163,6 +168,7 @@ var package_default = {
     esbuild: "0.27.3",
     fflate: "0.8.3",
     "posthog-node": "^5.21.2",
+    yaml: "^2.9.1",
     zod: "^3.24.0"
   },
   devDependencies: {
@@ -214,6 +220,29 @@ var TtlCache = class {
   }
 };
 
+// src/client/error-body.ts
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var str = (v) => typeof v === "string" && v.trim() ? v : void 0;
+var fromEnvelope = (v) => {
+  if (!isRecord(v)) return void 0;
+  const out = {
+    code: str(v.code),
+    message: str(v.message) ?? str(v.detail),
+    hint: str(v.hint),
+    retryable: typeof v.retryable === "boolean" ? v.retryable : void 0,
+    details: v.details
+  };
+  return out.code || out.message || out.hint ? out : void 0;
+};
+function parseErrorBody(body) {
+  if (!isRecord(body)) return {};
+  const nested = fromEnvelope(isRecord(body.data) ? body.data.error : void 0) ?? fromEnvelope(body.error) ?? fromEnvelope(body);
+  if (nested) {
+    return { ...nested, message: nested.message ?? str(body.error) };
+  }
+  return { message: str(body.error) };
+}
+
 // src/utils/tool-context.ts
 import { AsyncLocalStorage } from "async_hooks";
 var toolContext = new AsyncLocalStorage();
@@ -531,14 +560,17 @@ var DatabrainClient = class {
             parsed = JSON.parse(errorBody);
           } catch {
           }
-          const errorMsg = parsed.message || parsed.detail || (typeof parsed.error === "string" ? parsed.error : JSON.stringify(parsed.error)) || `API request failed with status ${response.status}`;
+          const envelope = parseErrorBody(parsed);
+          const errorMsg = envelope.message || `API request failed with status ${response.status}`;
           const error = new DatabrainApiError(
             response.status,
-            parsed.code || `HTTP_${response.status}`,
+            envelope.code || `HTTP_${response.status}`,
             errorMsg,
-            parsed
+            parsed,
+            envelope.hint,
+            envelope.retryable
           );
-          const isTransient = response.status === 429 || response.status >= 500 && !NON_TRANSIENT_PATTERNS.some((p) => errorMsg.includes(p));
+          const isTransient = envelope.retryable !== void 0 ? envelope.retryable && (response.status === 429 || response.status >= 500) : response.status === 429 || response.status >= 500 && !NON_TRANSIENT_PATTERNS.some((p) => errorMsg.includes(p));
           if (isTransient && attempt < MAX_RETRIES) {
             const delay = Math.min(1e3 * Math.pow(2, attempt - 1), 8e3);
             logger.warn(`Retrying in ${delay}ms (attempt ${attempt}/${MAX_RETRIES})`, {
@@ -669,7 +701,7 @@ var V2_OPTION_EXTRA_KEYS = {
 var TRANSLATION_KEYS = ["name", "description", "slots", "options"];
 var SLOT_TRANSLATION_KEYS = ["label", "description"];
 var OPTION_TRANSLATION_KEYS = ["label", "group", "choices"];
-var isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+var isRecord2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
 var isId = (value) => typeof value === "string" && ID_PATTERN.test(value) && !FORBIDDEN_IDS.includes(value);
 var isText = (value, max = MAX_TEXT) => typeof value === "string" && value.length > 0 && value.length <= max;
 var isTranslationText = (value) => typeof value === "string" && value.length <= MAX_TEXT;
@@ -704,7 +736,7 @@ var Collector = class {
   }
 };
 function validateSlot(c, value, path, v2) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     c.add("manifest.slot.invalid", path, "A slot must be an object.");
     return;
   }
@@ -734,7 +766,7 @@ function validateSlot(c, value, path, v2) {
   }
 }
 function validateOption(c, value, path, v2) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     c.add("manifest.option.invalid", path, "An option must be an object.");
     return;
   }
@@ -799,7 +831,7 @@ function validateOption(c, value, path, v2) {
     case "select": {
       const choices = value.choices;
       const choicesOk = Array.isArray(choices) && choices.length > 0 && choices.length <= MAX_CHOICES && choices.every(
-        (choice) => isRecord(choice) && Object.keys(choice).length === 2 && isId(choice.value) && isText(choice.label)
+        (choice) => isRecord2(choice) && Object.keys(choice).length === 2 && isId(choice.value) && isText(choice.label)
       ) && new Set(choices.map((choice) => choice.value)).size === choices.length;
       if (!choicesOk) {
         c.add("manifest.option.choices", `${path}/choices`, `choices is a list of 1 to ${MAX_CHOICES} distinct { value, label } pairs; a value follows the id rule.`);
@@ -821,7 +853,7 @@ function validateOption(c, value, path, v2) {
 }
 function validateTranslations(c, value, slots, options) {
   const path = "/translations";
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     c.add("manifest.translations.invalid", path, "translations is an object keyed by language code.");
     return;
   }
@@ -831,7 +863,7 @@ function validateTranslations(c, value, slots, options) {
       c.add("manifest.translations.language", langPath, `"${language}" is not a language code like "fr" or "pt-BR".`);
       continue;
     }
-    if (!isRecord(entry)) {
+    if (!isRecord2(entry)) {
       c.add("manifest.translations.invalid", langPath, "A translation is an object with optional name, description, slots and options.");
       continue;
     }
@@ -843,7 +875,7 @@ function validateTranslations(c, value, slots, options) {
     }
     if (Object.hasOwn(entry, "slots")) {
       const entrySlots = entry.slots;
-      if (!isRecord(entrySlots)) {
+      if (!isRecord2(entrySlots)) {
         c.add("manifest.translations.invalid", `${langPath}/slots`, "slots is an object keyed by slot id.");
       } else {
         for (const [slotId, slotEntry] of Object.entries(entrySlots)) {
@@ -852,7 +884,7 @@ function validateTranslations(c, value, slots, options) {
             c.add("manifest.translations.slot", slotPath, `"${slotId}" is not a slot id in this manifest.`);
             continue;
           }
-          if (!isRecord(slotEntry)) {
+          if (!isRecord2(slotEntry)) {
             c.add("manifest.translations.invalid", slotPath, "A slot translation is an object with optional label and description.");
             continue;
           }
@@ -867,7 +899,7 @@ function validateTranslations(c, value, slots, options) {
     }
     if (Object.hasOwn(entry, "options")) {
       const entryOptions = entry.options;
-      if (!isRecord(entryOptions)) {
+      if (!isRecord2(entryOptions)) {
         c.add("manifest.translations.invalid", `${langPath}/options`, "options is an object keyed by option id.");
       } else {
         for (const [optionId, optionEntry] of Object.entries(entryOptions)) {
@@ -877,7 +909,7 @@ function validateTranslations(c, value, slots, options) {
             c.add("manifest.translations.option", optionPath, `"${optionId}" is not an option id in this manifest.`);
             continue;
           }
-          if (!isRecord(optionEntry)) {
+          if (!isRecord2(optionEntry)) {
             c.add("manifest.translations.invalid", optionPath, "An option translation is an object with optional label, group and choices.");
             continue;
           }
@@ -889,7 +921,7 @@ function validateTranslations(c, value, slots, options) {
           }
           if (!Object.hasOwn(optionEntry, "choices")) continue;
           const choices = optionEntry.choices;
-          if (!isRecord(choices)) {
+          if (!isRecord2(choices)) {
             c.add("manifest.translations.invalid", `${optionPath}/choices`, "choices is an object keyed by choice value.");
             continue;
           }
@@ -908,7 +940,7 @@ function validateTranslations(c, value, slots, options) {
 }
 function validateManifest(value) {
   const c = new Collector();
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     c.add("manifest.invalid", "", "manifest.json must be a JSON object.");
     return c.problems;
   }
@@ -944,7 +976,7 @@ function validateManifest(value) {
     slots.forEach((slot, index) => validateSlot(c, slot, `/slots/${index}`, v2));
     const seen = /* @__PURE__ */ new Set();
     slots.forEach((slot, index) => {
-      if (!isRecord(slot) || typeof slot.id !== "string") return;
+      if (!isRecord2(slot) || typeof slot.id !== "string") return;
       if (seen.has(slot.id)) {
         c.add("manifest.slot.duplicate", `/slots/${index}/id`, `Slot id "${slot.id}" is used more than once.`);
       }
@@ -960,7 +992,7 @@ function validateManifest(value) {
     options.forEach((option, index) => validateOption(c, option, `/options/${index}`, v2));
     const seen = /* @__PURE__ */ new Set();
     options.forEach((option, index) => {
-      if (!isRecord(option) || typeof option.id !== "string") return;
+      if (!isRecord2(option) || typeof option.id !== "string") return;
       if (seen.has(option.id)) {
         c.add("manifest.option.duplicate", `/options/${index}/id`, `Option id "${option.id}" is used more than once.`);
       }
@@ -1012,7 +1044,7 @@ var manifestSchema = z2.object({
 });
 function sortKeys(value) {
   if (Array.isArray(value)) return value.map((item) => sortKeys(item));
-  if (isRecord(value)) {
+  if (isRecord2(value)) {
     const out = {};
     for (const key of Object.keys(value).sort()) out[key] = sortKeys(value[key]);
     return out;
@@ -1900,4 +1932,4 @@ export {
   apiProblems,
   planUpload
 };
-//# sourceMappingURL=chunk-PRE4CGOV.js.map
+//# sourceMappingURL=chunk-ETXH5HTT.js.map