Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

mcp-v2 integration branch (#81245)

bryan34ff3598e37d
diff --git a/.claude/agents/modules-backend-expert.md b/.claude/agents/modules-backend-expert.md
index 4389f068653..e6f29f6281a 100644
--- a/.claude/agents/modules-backend-expert.md
+++ b/.claude/agents/modules-backend-expert.md
@@ -81,7 +81,7 @@ Everything else in the module is **internal** and not allowed to be referenced f
`dev/src/dev/modularization_help.clj` — `potemkin-ns!` helper that generates `.core` re-export boilerplate from a target namespace.
-`dev/test/metabase/core/modules_test.clj` — runs on config changes; validates structure, team assignments, API and model boundaries.
+`test/metabase/core/modules_test.clj` — runs on config changes; validates structure, team assignments, API and model boundaries.
### API Design Inside a Module
@@ -119,7 +119,7 @@ When the linter complains, the answer is **always refactoring**, never suppressi
- `dev/src/dev/module_score.clj` — quality scoring
- `dev/src/dev/modularization_help.clj` — Potemkin re-export helper
- `dev/src/dev/model_boundary_config.clj` + `dev/src/dev/model_tracking.clj` — model-level enforcement
-- `dev/test/metabase/core/modules_test.clj` — config validation tests
+- `test/metabase/core/modules_test.clj` — config validation tests
- `src/metabase/core/init.clj` — OSS module init aggregation
- `enterprise/backend/src/metabase_enterprise/core/init.clj` — EE module init aggregation
- `src/metabase/models/resolution.clj` — `:model/X` keyword → namespace map
@@ -198,6 +198,6 @@ Use the `clojure-eval` skill (preferred) or `clj-nrepl-eval` to drive the dev to
(dev.module-score/scores (dev.module-score/deps) (dev.module-score/config))
```
-For tests of the config itself, use `./bin/mage project-tests modules`. After editing Clojure files, run `clj-paren-repair`. After editing `config.edn`, re-run the modules-test.
+For tests of the config itself, use `./bin/test-agent :only '[metabase.core.modules-test]'`. After editing Clojure files, run `clj-paren-repair`. After editing `config.edn`, re-run the modules-test.
**Update your agent memory** as you discover idioms: which modules use `:friends` and why, which models are most-imported (suggesting they belong in their own module), which settings are accessed cross-module via `(setting/get …)` instead of `:uses` deps, and which refactors the team is actively running.
diff --git a/.claude/skills/_shared/clojure-style-guide.md b/.claude/skills/_shared/clojure-style-guide.md
index afd97a05b56..fd6e302a674 100644
--- a/.claude/skills/_shared/clojure-style-guide.md
+++ b/.claude/skills/_shared/clojure-style-guide.md
@@ -304,13 +304,12 @@ Tag response Malli `:map` schemas with `{:closed true}` so the generated OpenAPI
**Linter Suppressions:**
-The right shape is a **reader-discard map** placed directly above the form being silenced, listing the
-rule keywords explicitly and including the required explanation:
+The right shape is a **reader-discard map** placed directly above the form being silenced, listing the rule keywords explicitly:
```clojure
-;; Loaded by name from the plugin registry.
-#_{:clj-kondo/ignore [:clojure-lsp/unused-public-var]}
-(defn plugin-entrypoint ...)
+#_{:clj-kondo/ignore [:metabase/validate-defendpoint-route-uses-kebab-case
+ :metabase/validate-defendpoint-has-response-schema]}
+(api.macros/defendpoint :post "/api_key" ...)
```
For a single require entry, hang it as metadata on that entry:
@@ -321,12 +320,7 @@ For a single require entry, hang it as metadata on that entry:
[metabase.query-processor.store :as qp.store])
```
-Use the map form, not the keyword form (`#_:clj-kondo/ignore`), so searches can identify the suppressed
-rules. Keep `:clj-kondo/ignore` as the map's first key; the ratchet scanner rejects other orderings.
-
-Fix the warning when possible. Adding a suppression is a last resort and requires approval. If one is
-necessary, add an explanatory `;;` comment directly above it or at the end of the same line. CI enforces
-these requirements with `./bin/mage kondo-ratchets`.
+Common Metabase-specific rules you'll see: `:metabase/modules`, `:metabase/validate-defendpoint-route-uses-kebab-case`, `:metabase/validate-defendpoint-has-response-schema`, `:metabase/prefer-with-dynamic-fn-redefs`, `:deprecated-namespace`, `:discouraged-namespace`. Don't use the keyword form (`#_:clj-kondo/ignore`); always the map form so it's grep-able by which rule(s) are suppressed.
**Configurable Options:**
diff --git a/.claude/skills/clojure-review/SKILL.md b/.claude/skills/clojure-review/SKILL.md
index 541fab8f0d5..805450e67e0 100644
--- a/.claude/skills/clojure-review/SKILL.md
+++ b/.claude/skills/clojure-review/SKILL.md
@@ -111,12 +111,7 @@ liability it usually is.
### Miscellaneous
- [ ] Example data is bird-themed when possible
-- [ ] Kondo suppressions use a reader-discard map, not `#_:clj-kondo/ignore`, with
- `:clj-kondo/ignore` as the first key
-- [ ] Each new suppression is approved and has a `;;` comment explaining why the warning cannot be fixed
-- [ ] Any ratchet budget increase is explained in the PR
-- [ ] PRs that remove ignores leave ratchet budgets unchanged; the shrink workflow records reductions on
- `master`
+- [ ] Kondo linter suppressions use proper format (not `#_:clj-kondo/ignore` keyword form)
## Pattern matching table
diff --git a/.claude/skills/clojure-write/SKILL.md b/.claude/skills/clojure-write/SKILL.md
index adaa1edb0e6..0760a2c7c25 100644
--- a/.claude/skills/clojure-write/SKILL.md
+++ b/.claude/skills/clojure-write/SKILL.md
@@ -123,12 +123,5 @@ breakage keeps happening, *that* is the signal a comment was warranted.
- Spaces on a line with nothing after it is not allowed
- After changing module boundaries (adding/removing/renaming a `src` namespace, a cross-module `require`
or `:model/X` reference, or a new module), run `./bin/mage fix-modules-config` to regenerate
- `.clj-kondo/config/modules/config.edn`, then run `./bin/mage project-tests modules`. The fixer is a no-op when
- nothing drifted; see "Module Boundaries" in the project `CLAUDE.md`.
-- Fix kondo warnings instead of suppressing them. Add a suppression only as a last resort, with approval
- and a `;;` comment explaining why it is necessary.
-- Do not lower budgets in `.clj-kondo/ratchets.edn` after removing ignores. The shrink workflow records
- reductions on `master`.
-- If `.clj-kondo/ratchets.edn` conflicts during a merge, rebase, or restack, run
- `./bin/merge-kondo-ratchets`. It preserves one-sided changes, chooses the policy that allows fewer
- suppressions when both sides change the same entry, and stops when the conflict needs a human decision.
+ `.clj-kondo/config/modules/config.edn` and keep `metabase.core.modules-test` green. No-op when nothing
+ drifted; see "Module Boundaries" in the project `CLAUDE.md`.
diff --git a/.claude/skills/emotion-migrate/SKILL.md b/.claude/skills/emotion-migrate/SKILL.md
index df0338ebf6f..67b459ec37b 100644
--- a/.claude/skills/emotion-migrate/SKILL.md
+++ b/.claude/skills/emotion-migrate/SKILL.md
@@ -171,7 +171,7 @@ Create `ComponentName.module.css` alongside the component file:
/* Use design system tokens — NEVER raw color/spacing values */
.root {
border: 1px solid var(--mb-color-border-neutral);
- border-radius: var(--mantine-radius-sm);
+ border-radius: var(--mantine-radius-md);
background-color: var(--mb-color-background_page-primary);
}
@@ -246,8 +246,7 @@ Remove the old styled file entirely. Remove all imports of it from other files.
**Spacing** (`p`, `px`, `py`, `pt`, `pb`, `pl`, `pr`, `m`, `mx`, `my`, `mt`, `mb`, `ml`, `mr`):
-- `"xxxs"` = 0.125rem, `"xxs"` = 0.25rem, `"xs"` = 0.375rem, `"sm"` = 0.5rem, `"md"` = 0.75rem, `"lg"` = 1rem, `"xl"` = 1.5rem, `"xxl"` = 2rem, `"xxxl"` = 2.5rem
-- Use numeric `0` for zero spacing.
+- `"xs"` = 4px, `"sm"` = 8px, `"md"` = 16px, `"lg"` = 24px, `"xl"` = 32px
- Custom: `rem(48)` for non-standard values (import `rem` from `metabase/ui`)
**Dimensions** (`w`, `h`, `maw`, `mah`, `miw`, `mih`):
@@ -290,16 +289,11 @@ Remove the old styled file entirely. Remove all imports of it from other files.
**Mantine spacing** — `var(--mantine-spacing-<size>)`:
-- `--mantine-spacing-xxxs` (0.125rem), `--mantine-spacing-xxs` (0.25rem), `--mantine-spacing-xs` (0.375rem), `--mantine-spacing-sm` (0.5rem), `--mantine-spacing-md` (0.75rem), `--mantine-spacing-lg` (1rem), `--mantine-spacing-xl` (1.5rem), `--mantine-spacing-xxl` (2rem), `--mantine-spacing-xxxl` (2.5rem)
+- `--mantine-spacing-xs` (4px), `--mantine-spacing-sm` (8px), `--mantine-spacing-md` (16px), `--mantine-spacing-lg` (24px), `--mantine-spacing-xl` (32px)
**Mantine radius** — `var(--mantine-radius-<size>)`:
-- `--mantine-radius-xxxs` (0.125rem), `--mantine-radius-xxs` (0.25rem), `--mantine-radius-xs` (0.375rem), `--mantine-radius-sm` (0.5rem), `--mantine-radius-md` (0.75rem), `--mantine-radius-lg` (1rem), `--mantine-radius-xl` (1.5rem)
-
-**Mantine shadows (elevation)** — `var(--mantine-shadow-<size>)`:
-
-- `--mantine-shadow-xs`, `--mantine-shadow-xs_outline`, `--mantine-shadow-sm`, `--mantine-shadow-sm_outline`, `--mantine-shadow-lg_outline`
-- Light and dark modes use different shadow values (defined in `frontend/src/metabase/ui/theme.ts`)
+- `--mantine-radius-xs` (4px), `--mantine-radius-sm` (6px), `--mantine-radius-md` (8px), `--mantine-radius-xl` (40px)
**Mantine font sizes** — `var(--mantine-font-size-<size>)`:
@@ -319,36 +313,24 @@ When migrating, **never carry over hardcoded `rem`/`px` values** from the origin
**Spacing** — snap to the nearest Mantine spacing token:
-| Hardcoded value | Nearest token | Style prop | CSS variable |
-| --------------------------------- | ------------- | ---------- | ------------------------------- |
-| `0` (0px) | — | `0` | `0` |
-| `0.125rem` (2px) | **xxxs** | `"xxxs"` | `var(--mantine-spacing-xxxs)` |
-| `0.2rem` (3.2px), `0.25rem` (4px) | **xxs** | `"xxs"` | `var(--mantine-spacing-xxs)` |
-| `0.375rem` (6px) | **xs** | `"xs"` | `var(--mantine-spacing-xs)` |
-| `0.5rem` (8px) | **sm** | `"sm"` | `var(--mantine-spacing-sm)` |
-| `0.75rem` (12px) | **md** | `"md"` | `var(--mantine-spacing-md)` |
-| `1rem` (16px) | **lg** | `"lg"` | `var(--mantine-spacing-lg)` |
-| `1.5rem` (24px) | **xl** | `"xl"` | `var(--mantine-spacing-xl)` |
-| `2rem` (32px) | **xxl** | `"xxl"` | `var(--mantine-spacing-xxl)` |
-| `2.5rem` (40px) | **xxxl** | `"xxxl"` | `var(--mantine-spacing-xxxl)` |
-
-Values between steps: keep the literal (e.g. `rem(10)`), don't round to a token.
+| Hardcoded value | Nearest token | Style prop | CSS variable |
+| --------------------------------- | ------------- | ------------ | ------------------------------ |
+| `0.125rem` (2px) | `2px` | `2` (number) | `2px` (keep literal, no token) |
+| `0.2rem` (3.2px), `0.25rem` (4px) | **xs** (4px) | `"xs"` | `var(--mantine-spacing-xs)` |
+| `0.5rem` (8px) | **sm** (8px) | `"sm"` | `var(--mantine-spacing-sm)` |
+| `0.75rem` (12px) | between sm/md | `rem(12)` | `0.75rem` (no exact token) |
+| `1rem` (16px) | **md** (16px) | `"md"` | `var(--mantine-spacing-md)` |
+| `1.5rem` (24px) | **lg** (24px) | `"lg"` | `var(--mantine-spacing-lg)` |
+| `2rem` (32px) | **xl** (32px) | `"xl"` | `var(--mantine-spacing-xl)` |
**Border radius** — snap to the nearest Mantine radius token:
-| Hardcoded value | Nearest token | CSS variable |
-| ---------------- | ------------- | ----------------------------- |
-| `0` (0px) | — | `0` |
-| `0.125rem` (2px) | **xxxs** | `var(--mantine-radius-xxxs)` |
-| `0.25rem` (4px) | **xxs** | `var(--mantine-radius-xxs)` |
-| `0.375rem` (6px) | **xs** | `var(--mantine-radius-xs)` |
-| `0.5rem` (8px) | **sm** | `var(--mantine-radius-sm)` |
-| `0.75rem` (12px) | **md** | `var(--mantine-radius-md)` |
-| `1rem` (16px) | **lg** | `var(--mantine-radius-lg)` |
-| `1.5rem` (24px) | **xl** | `var(--mantine-radius-xl)` |
-
-Fully-round pills/badges (radius ≥ half the element height): keep a literal
-such as `9999px`.
+| Hardcoded value | Nearest token | CSS variable |
+| ---------------- | ----------------------------- | -------------------------- |
+| `0.25rem` (4px) | **xs** (4px) | `var(--mantine-radius-xs)` |
+| `0.375rem` (6px) | **sm** (6px) | `var(--mantine-radius-sm)` |
+| `0.5rem` (8px) | **md** (8px) | `var(--mantine-radius-md)` |
+| `1rem`+ (16px+) | **xl** (40px) or keep literal | `var(--mantine-radius-xl)` |
**Font sizes** — snap to the nearest Mantine font size token:
diff --git a/.claude/skills/metabase-ui-component-from-figma/SKILL.md b/.claude/skills/metabase-ui-component-from-figma/SKILL.md
index ce426c6c4f6..16d2fbb52a3 100644
--- a/.claude/skills/metabase-ui-component-from-figma/SKILL.md
+++ b/.claude/skills/metabase-ui-component-from-figma/SKILL.md
@@ -31,11 +31,6 @@ Phases 1, 2, 5 and 6 are shared. The middle two differ in **order**: update mode
- **The component's intended API** — variants, sizes, and states the design system supports for this component. This defines the axes of your showcase (Phase 3).
3. Decide the mode (see **Two modes** above): search for an existing component — in `metabase/ui` or as a legacy component elsewhere. Found → **update**; nothing equivalent anywhere → **create**. Confirm with the user when unsure.
4. **Verify a Figma desktop MCP is connected before doing the work** — this skill depends on it for exact tokens in Phase 4 (and styling can't proceed accurately without it). Do a quick read against the issue's node (e.g. `get_metadata`/`get_variable_defs`); if it errors with "nothing selected" or the server isn't connected, prompt the user to enable it (Switch to Dev Mode → MCP section in the right sidebar) and select the relevant layer before continuing.
-5. **Figma Desktop MCP environments only:** open the issue's exact page with [`figma-open`](./figma-open) before MCP reads. Do not run this helper when Desktop MCP is unavailable.
- ```bash
- .claude/skills/metabase-ui-component-from-figma/figma-open "<figma-url-with-node-id>"
- ```
- A URL with `node-id` needs no token. Bare page-name and `--list` lookups require an already-configured `FIGMA_TOKEN`.
## Phase 2 — Understand the component
@@ -210,7 +205,7 @@ Per `docs/developers-guide/frontend.md` ("Colors"): every color must be a **sema
The same discipline applies to **dimensional** values — radius, spacing/padding/gap, elevation/shadow, and typography (font size, line-height, weight). Prefer the codebase's existing scale variable over a literal: `--mantine-radius-*`, `--mantine-spacing-*`, `--mantine-shadow-*`, and the Mantine font tokens.
-But Figma's scales don't always line up with the codebase's. When a Figma value **has no matching step** in the corresponding scale — e.g. Figma `radius/md = 16px` while `--mantine-radius-md` is `0.75rem`, or a Figma spacing step that has no Mantine equivalent — **don't silently bake in a literal.** Flag it to the user the same way you flag primitive colors: name the property, the Figma value, and the nearest codebase token, so it can be resolved with design / the scale owners (align the value, or add a scale step). Only fall back to a literal if the user confirms it's an accepted one-off, and leave a short comment in the code explaining why. The codebase scales are defined in `frontend/src/metabase/ui/theme.ts` (`SPACING_SCALE`, `RADIUS_SCALE`, `LIGHT_SHADOWS`/`DARK_SHADOWS`).
+But Figma's scales don't always line up with the codebase's. When a Figma value **has no matching step** in the corresponding scale — e.g. Figma `radius/md = 12px` while `--mantine-radius-md` is `8px`, or a Figma `xxxs` spacing step with no Mantine equivalent — **don't silently bake in a literal.** Flag it to the user the same way you flag primitive colors: name the property, the Figma value, and the nearest codebase token, so it can be resolved with design / the scale owners (align the value, or add a scale step). Only fall back to a literal if the user confirms it's an accepted one-off, and leave a short comment in the code explaining why.
### Mantine implementation notes (reference)
@@ -245,6 +240,5 @@ Only after sign-off:
- [ ] Storybook showcase matrix built from the component's full state space (theme excluded — global toggle drives light/dark), single panel, hover/pressed forced via `storybook-addon-pseudo-states`, controls scoped per story; lint + type-check pass. (Update mode: built before styling, **component styles untouched**. Create mode: built after the component is implemented in Phase 4.)
- [ ] Figma desktop MCP available; exact tokens extracted and mapped to semantic `--mb-color-*` (NO `color-mix`, NO primitives) and to existing scale vars for radius/spacing/elevation/type — any color *or* dimensional value with no matching token/scale step flagged to the user, not baked in as a literal.
- [ ] Component styled; stylelint + eslint(+CSS modules) + type-check pass.
-- [ ] Loki coverage registered: `storiesFilter` matches exact story display names; targeted `loki update` generated references; reference PNGs and Playwright screenshots visually inspected; targeted `loki test` passes; `.loki/reference/*.png` included in the commit.
- [ ] Iterated with the user until satisfied.
- [ ] Committed (when asked); call sites migrated/verified (update) or export wired (create); findings doc handed back.
diff --git a/.claude/skills/metabase-ui-component-from-figma/figma-open b/.claude/skills/metabase-ui-component-from-figma/figma-open
deleted file mode 100755
index b544a0b48c0..00000000000
--- a/.claude/skills/metabase-ui-component-from-figma/figma-open
+++ /dev/null
@@ -1,68 +0,0 @@
-#!/usr/bin/env bash
-# figma-open — open a Figma file (or a specific page) in the Figma desktop app
-#
-# Usage:
-# figma-open <url-or-file-key> open the file
-# figma-open <url-or-file-key> <node-id> open at a node/page id (e.g. 12-3 or 12:3)
-# figma-open <url-or-file-key> --list list pages with their ids
-# figma-open <url-or-file-key> "Page name" open a page by name
-#
-# Page lookup by name/--list needs a Figma personal access token:
-# export FIGMA_TOKEN=figd_... or put it in ~/.config/figma/token
-set -euo pipefail
-
-arg="${1:-}"
-[[ -n "$arg" ]] || { awk 'NR==1 && /^#!/ {next} /^#/ {sub(/^# ?/,""); print; next} {exit}' "$0"; exit 1; }
-
-token="${FIGMA_TOKEN:-}"
-[[ -f "$HOME/.config/figma/token" ]] && token="$(<"$HOME/.config/figma/token")"
-
-# Extract the file key from any Figma URL form, or use the arg as a bare key.
-key="$arg"
-case "$arg" in
- *figma.com*|figma://*)
- key="$(printf '%s' "$arg" | sed -E 's#https?://([a-z]+\.)?figma\.com##; s#^([a-z0-9-]+\.)?figma\.com##; s#^figma://##; s#^/?(file|design|proto|board)/##; s#^/##; s#/.*##; s#\?.*##')"
- ;;
-esac
-
-req="${2:-}"
-
-# If no page arg was given but the URL carries a node-id, use it.
-url_node="$(printf '%s' "$arg" | sed -nE 's/.*[?&]node-id=([0-9]+([-:][0-9]+)*).*/\1/p')"
-
-open_fig() { # $1 = optional node id
- if [[ -n "${1:-}" ]]; then
- open "figma://file/${key}?node-id=${1//:/-}"
- else
- open "figma://file/${key}"
- fi
-}
-
-# No page requested — open the file (or the node the URL points at).
-[[ -z "$req" ]] && { open_fig "${url_node:-}"; exit 0; }
-
-# Explicit node id (page ids work: pages are top-level nodes).
-if [[ "$req" =~ ^[0-9]+[:-][0-9]+$ ]]; then
- open_fig "$req"
- exit 0
-fi
-
-# Everything else needs the REST API.
-[[ -n "$token" ]] || { echo "error: page lookup needs FIGMA_TOKEN (env or ~/.config/figma/token)" >&2; exit 1; }
-
-pages_json="$(curl -sf -H "X-Figma-Token: ${token}" "https://api.figma.com/v1/files/${key}?depth=1")" \
- || { echo "error: could not fetch file ${key} (bad key, no access, or bad token)" >&2; exit 1; }
-
-if [[ "$req" == "--list" || "$req" == "-l" ]]; then
- printf '%s\n' "$pages_json" | jq -r '.document.children[] | "\(.id // .guid)\t\(.name)"' | column -t -s $'\t'
- exit 0
-fi
-
-# Page by name (case-insensitive, exact match first, then substring).
-node_id="$(printf '%s' "$pages_json" | jq -r --arg n "$req" \
- 'first(.document.children[] | select((.name // "") | ascii_downcase == ($n | ascii_downcase)) | .id // .guid) //
- first(.document.children[] | select((.name // "") | ascii_downcase | contains($n | ascii_downcase)) | .id // .guid) //
- empty')"
-
-[[ -n "$node_id" ]] || { echo "error: no page matching \"$req\" in file ${key}" >&2; exit 1; }
-open_fig "$node_id"
diff --git a/.clj-kondo/config.edn b/.clj-kondo/config.edn
index 810a47aaa7f..f20da2e2e18 100644
--- a/.clj-kondo/config.edn
+++ b/.clj-kondo/config.edn
@@ -185,6 +185,12 @@
dev.kondo-ratchet/fix!
metabase.ai-tracing.core/record!
metabase.api.macros.defendpoint.tools-manifest/assert-optional-fields-nullable!
+ ;; MCP v2 tool tests: call-tool! dispatches a tool with no shared mutable state across tests
+ metabase.mcp.v2.tools.alert-test/call-tool!
+ metabase.mcp.v2.tools.definitions-test/call-tool!
+ metabase.mcp.v2.tools.metric-test/call-tool!
+ ;; the `!` is for the throw (a teaching error), not a mutation; no shared mutable state
+ metabase.mcp.v2.tools.browse/validate-args-for-action!
metabase.channel.core/send!
metabase.channel.render.pdf/draw-too-large!
metabase.channel.render.pdf/draw-no-results!
@@ -218,7 +224,9 @@
;; Safe in tests, where we typically use a private, temporary index per thread.
metabase.search.core/reindex!
metabase.util/run-count!
- next.jdbc/execute!}}
+ next.jdbc/execute!
+ ;; pure validator: parses a keyword and throws on a bad one, touches no state
+ metabase.mcp.v2.tools.question/check-semantic-type!}}
:metabase/i-like-making-cams-eyes-bleed-with-horrifically-long-tests
{:level :warning
@@ -491,6 +499,7 @@
metabase.driver.sql-jdbc.connection/with-connection-spec-for-testing-connection clojure.core/let
metabase.driver.sql-jdbc.execute.diagnostic/capturing-diagnostic-info clojure.core/fn
metabase.driver-api.core/defsetting hooks.metabase.settings.models.setting/defsetting
+ metabase.mcp.v2.registry/deftool clojure.core/defn
metabase.models.json-migration/def-json-migration clj-kondo.lint-as/def-catch-all
metabase.models.util.spec-update/define-spec clojure.core/def
metabase.notification.test-util/with-card-notification clojure.core/let
@@ -673,6 +682,7 @@
metabase.lib.test-util.macros/mbql-query hooks.metabase.test.data/mbql-query
metabase.lib.test-util.macros/mbql-5-query hooks.metabase.test.data/mbql-query
metabase.lib.test-util.macros/with-testing-against-standard-queries hooks.metabase.lib.test-util.macros/with-testing-against-standard-queries
+ metabase.mcp.v2.tools.parameters-test/with-fixtures hooks.common/with-one-binding
metabase.metrics.api-dimension-test/with-seeded-metric hooks.common/with-one-binding
metabase.model-persistence.api-test/with-persistence-setup! hooks.common/with-one-top-level-binding
metabase.model-persistence.api-test/with-setup! hooks.common/with-one-top-level-binding
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index 12928979ab2..b412460a0de 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -437,7 +437,7 @@
bookmarks
{:team "UX West"
- :api #{metabase.bookmarks.api}
+ :api #{metabase.bookmarks.api metabase.bookmarks.db}
:uses #{api
app-db
collections
@@ -570,7 +570,8 @@
collections
{:team "UX West"
- :api #{metabase.collections.core
+ :api #{metabase.collections.children
+ metabase.collections.core
metabase.collections.curation
metabase.collections.init
metabase.collections.models.collection
@@ -581,12 +582,20 @@
app-db
audit-app
events
+ lib.be
lib.schema
models
+ notification
permissions
premium-features
+ queries
remote-sync
+ request
+ revisions
search
+ tracing
+ transforms
+ upload
util
util.config}
:model-exports #{:model/Collection}
@@ -612,33 +621,17 @@
:api #{metabase.collections-rest.api}
:uses #{api
api.eid-translation
- app-db
collections
documents
events
- lib.be
lib.schema
models
- notification
permissions
premium-features
queries
request
- revisions
- tracing
- transforms
- upload
util}
- :model-imports #{:model/Card
- :model/Collection
- :model/Dashboard
- :model/Document
- :model/Exploration
- :model/NativeQuerySnippet
- :model/Pulse
- :model/Table
- :model/Timeline
- :model/Transform}}
+ :model-imports #{:model/Card :model/Collection}}
comments
{:team "UX West"
@@ -731,8 +724,10 @@
metabase.dashboards.models.dashboard-card
metabase.dashboards.models.dashboard-tab
metabase.dashboards.schema
- metabase.dashboards.settings}
- :uses #{api
+ metabase.dashboards.settings
+ metabase.dashboards.write}
+ :uses #{analytics
+ api
app-db
audit-app
collections
@@ -744,6 +739,7 @@
parameters
permissions
public-sharing
+ pulse
queries
query-permissions
query-processor
@@ -762,6 +758,7 @@
:model/Collection
:model/DashboardBookmark
:model/ModerationReview
+ :model/ParameterCard
:model/Pulse
:model/PulseCard
:model/Revision
@@ -778,7 +775,6 @@
app-db
channel
collections
- collections.rest
dashboards
embedding
events
@@ -864,6 +860,7 @@
:model-imports #{:model/Card
:model/Collection
:model/Dashboard
+ :model/Database
:model/Table
:model/User}}
@@ -1270,28 +1267,66 @@
mcp
{:team "Metabot"
:module-exports #{mcp.oauth-server}
- :api #{metabase.mcp.api
- metabase.mcp.callback-api
+ :api #{metabase.mcp.callback-api
metabase.mcp.core
metabase.mcp.init
- metabase.mcp.usage}
+ metabase.mcp.usage
+ metabase.mcp.v2.api}
:model-exports #{:model/McpSessionLog :model/McpToolCallLog}
- :uses #{ai-tracing
+ :uses #{activity-feed
+ ai-tracing
api
+ api.eid-translation
app-db
+ bookmarks
+ channel
+ collections
+ comments
+ dashboards
+ documents
+ lib
+ lib.be
+ lib.metadata
lib.schema
mcp.oauth-server
metabot
metabot.agent-api
metabot.llm
+ metrics
+ models
+ notification
+ parameters
+ permissions
premium-features
+ pulse
+ queries
+ query-processor
request
server
session
settings
system
+ task
+ transforms
+ users
util
- util.config}}
+ util.config
+ warehouses.schema}
+ :model-imports #{:model/Card
+ :model/Collection
+ :model/Dashboard
+ :model/Database
+ :model/Document
+ :model/Field
+ :model/Measure
+ :model/NativeQuerySnippet
+ :model/Notification
+ :model/Pulse
+ :model/Segment
+ :model/Table
+ :model/Transform
+ :model/TransformTag
+ :model/User}}
mcp.oauth-server
{:team "UX West"
@@ -1342,10 +1377,13 @@
metabase.metabot.persistence
metabase.metabot.schema
metabase.metabot.schema.v2
+ metabase.metabot.scope
metabase.metabot.self
metabase.metabot.settings
metabase.metabot.tools
- metabase.metabot.tools.entity-details}
+ metabase.metabot.tools.construct
+ metabase.metabot.tools.entity-details
+ metabase.metabot.tools.search}
:module-exports #{metabot.agent-api
metabot.llm
metabot.slackbot}
@@ -1425,7 +1463,9 @@
:ns-prefix "metabase.agent-api"
:api #{metabase.agent-api.api
metabase.agent-api.init
+ metabase.agent-api.query-guards
metabase.agent-api.schema
+ metabase.agent-api.settings
metabase.agent-api.usage}
:uses #{ai-tracing
api
@@ -1632,6 +1672,7 @@
notification
{:team "Gadget"
:api #{metabase.notification.api
+ metabase.notification.card
metabase.notification.core
metabase.notification.init
metabase.notification.models
@@ -1702,6 +1743,7 @@
metabase.parameters.field
metabase.parameters.field-values
metabase.parameters.init
+ metabase.parameters.mapping-targets
metabase.parameters.params
metabase.parameters.schema
metabase.parameters.shared}
@@ -1867,6 +1909,7 @@
pulse
{:team "Gadget"
:api #{metabase.pulse.api
+ metabase.pulse.broken-subscriptions
metabase.pulse.core
metabase.pulse.init}
:uses #{api
@@ -3083,7 +3126,10 @@
search
sync.analyze
util
- warehouses}
+ util.classloader
+ util.config
+ warehouses
+ enterprise/permissions}
:model-exports #{:model/Dimension
:model/Field
:model/FieldUserSettings
diff --git a/.clj-kondo/ratchets.edn b/.clj-kondo/ratchets.edn
index a61c44fd4ac..6d33bd50417 100644
--- a/.clj-kondo/ratchets.edn
+++ b/.clj-kondo/ratchets.edn
@@ -25,7 +25,7 @@
:metabase/disallow-hardcoded-driver-names-in-tests 34
:metabase/discourage-millis-duration 1
:metabase/i-like-making-cams-eyes-bleed-with-horrifically-long-tests 13
- :metabase/modules 23
+ :metabase/modules 24
:metabase/namespace-name 4
:metabase/prefer-with-dynamic-fn-redefs 28
:metabase/test-helpers-use-non-thread-safe-functions 18
diff --git a/enterprise/backend/test/metabase_enterprise/mcp/usage_test.clj b/enterprise/backend/test/metabase_enterprise/mcp/usage_test.clj
index 4ce44824779..c3b964f1e74 100644
--- a/enterprise/backend/test/metabase_enterprise/mcp/usage_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/mcp/usage_test.clj
@@ -5,8 +5,9 @@
:none`); PII is gated by `analytics-pii-retention-enabled` (itself `:audit-app`-gated)."
(:require
[clojure.test :refer [deftest is testing use-fixtures]]
- [metabase.mcp.tools :as mcp.tools]
[metabase.mcp.usage :as usage]
+ [metabase.mcp.v2.registry :as v2.registry]
+ [metabase.mcp.v2.test-util]
[metabase.test :as mt]
[metabase.test.data.users :as test.users]
[metabase.test.fixtures :as fixtures]
@@ -264,21 +265,30 @@
;;; ---------------------------------------- call-tool instrumentation --------------------------------------
-(deftest ^:parallel call-tool-records-error-when-handler-throws-test
- (testing "a handler that throws (rather than returning error content) still records an error row,
- then the exception is rethrown so the client still sees the failure"
+;; Not ^:parallel: `register-tool!` mutates the shared tool registry.
+(deftest call-tool-records-error-when-handler-throws-test
+ (testing "a v2 tool handler that throws still records an error row, and the client sees a
+ (redacted) error rather than a silent success"
(mt/with-premium-features #{:audit-app}
- (let [sid (str "throw-session-" (mt/random-name))
- tool (str "boom-" (mt/random-name))]
+ ;; A tool name unique to this run. Driving the real `test_echo` would make the select read a sibling
+ ;; ^:parallel test's row, and the cleanup would then delete every test_echo row in the app DB — the rest
+ ;; of this ns isolates by a unique column value for exactly that reason.
+ (let [sid (str "throw-session-" (mt/random-name))
+ tool-name (str "throwing-" (mt/random-name))]
(try
- (mt/with-dynamic-fn-redefs [mcp.tools/dispatch-tool-call
- (fn [& _] (throw (ex-info "kaboom" {})))]
- (is (thrown-with-msg? clojure.lang.ExceptionInfo #"kaboom"
- (mcp.tools/call-tool #{} sid tool {}))))
- (let [row (t2/select-one :model/McpToolCallLog :tool_name tool)]
+ (v2.registry/register-tool! {:name tool-name
+ :scope "agent:content:read"
+ :description "throws on purpose"
+ :args [:map]
+ :handler (fn [_ _] (throw (ex-info "kaboom" {})))})
+ (let [{:keys [result error]} (v2.registry/call-tool #{"agent:content:read"} sid tool-name {})]
+ (is (or error (:isError result)) "the client sees an error result"))
+ (let [row (t2/select-one :model/McpToolCallLog :tool_name tool-name)]
(is (some? row) "an error row is recorded even though the handler threw")
(is (= "error" (:status row))))
- (finally (cleanup-calls! :tool_name tool)))))))
+ (finally
+ (swap! @#'v2.registry/tools* dissoc tool-name)
+ (cleanup-calls! :tool_name tool-name)))))))
;;; --------------------------------------------- Feature gating --------------------------------------------
@@ -355,12 +365,11 @@
(test.users/username->token :crowberto)
:post "mcp"
{:request-options {:headers {"mcp-session-id" sid}}}
- (jsonrpc "tools/call" {:name "read_resource"
- :arguments {:uris ["metabase://databases"]}} 2))]
+ (jsonrpc "tools/call" {:name "test_echo" :arguments {}} 2))]
(testing "successful tools/call writes a success row with identity denormalized on it"
(is (= 200 (:status call-resp)))
(is (false? (boolean (get-in call-resp [:body :result :isError]))))
- (let [row (t2/select-one :model/McpToolCallLog :tool_name "read_resource" :client_version ver)]
+ (let [row (t2/select-one :model/McpToolCallLog :tool_name "test_echo" :client_version ver)]
(is (some? row))
(is (= "success" (:status row)))
(is (= crowberto (:user_id row)))
@@ -374,17 +383,24 @@
:post "mcp"
{:request-options {:headers {"mcp-session-id" sid}}}
(jsonrpc "tools/call" {:name "no_such_tool" :arguments {}} 3))]
- (is (true? (boolean (get-in err-resp [:body :result :isError]))))
+ ;; The bare alias now serves v2, whose registry rejects an unknown tool before dispatch:
+ ;; that is `{:error ...}`, not a handler result carrying `:isError`.
+ (is (boolean (or (get-in err-resp [:body :error])
+ (get-in err-resp [:body :result :isError]))))
(let [row (t2/select-one :model/McpToolCallLog :tool_name "no_such_tool" :client_version ver)]
(is (some? row))
(is (= "error" (:status row)))
;; unknown tool -> JSON-RPC "method not found"; error_code is non-PII, always recorded
(is (= -32601 (:error_code row))))))
- (testing "DELETE stamps ended_at on the session row"
- (client/client-full-response (test.users/username->token :crowberto)
- :delete "mcp"
- {:request-options {:headers {"mcp-session-id" sid}}})
- (is (some? (:ended_at (t2/select-one :model/McpSessionLog :id sid)))))
+ (testing "DELETE is refused: v2 does not support client-initiated termination"
+ ;; v1 tore the session down here and stamped `ended_at` on the way out. The v2 transport
+ ;; answers 405 instead, so nothing on this path ends the session row. `record-mcp-session-end!`
+ ;; is now callerless -- tracked separately rather than wired up here, since choosing where a
+ ;; v2 session ends is a design question, not a test fix.
+ (is (= 405 (:status (client/client-full-response
+ (test.users/username->token :crowberto)
+ :delete "mcp"
+ {:request-options {:headers {"mcp-session-id" sid}}})))))
(finally
(cleanup-calls! :client_version ver)
(cleanup! sid))))))
diff --git a/enterprise/backend/test/metabase_enterprise/mcp/v2/redaction_sandbox_test.clj b/enterprise/backend/test/metabase_enterprise/mcp/v2/redaction_sandbox_test.clj
new file mode 100644
index 00000000000..71f3f762ce6
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/mcp/v2/redaction_sandbox_test.clj
@@ -0,0 +1,89 @@
+(ns metabase-enterprise.mcp.v2.redaction-sandbox-test
+ "The v2 read paths whose redaction only has teeth where a sandbox exists: the sandboxed-caller
+ branch of [[metabase.mcp.v2.redaction/redact-notification]], and the fingerprint strip in
+ `get_content`'s `fields` include. In OSS `sandboxed-or-impersonated-user?` is always false and no
+ table is row-restricted, so neither branch can be driven there; the rules that hold in OSS too are
+ pinned in `metabase.mcp.v2.redaction-test` and `metabase.mcp.v2.tools.content-test`."
+ (:require
+ [clojure.test :refer [deftest is testing]]
+ [metabase-enterprise.test :as met]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.redaction :as redaction]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.tools.content :as tools.content]
+ [metabase.metabot.metadata-perms :as metadata-perms]
+ [metabase.test :as mt]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+;; `deftool` registers on load, so the tool namespace has to be required for `call-tool` to find it.
+(comment tools.content/keep-me)
+
+(defn- user-recipient
+ [user-id]
+ {:type :notification-recipient/user :user_id user-id :user {:id user-id :tenant_id nil}})
+
+(deftest sandboxed-caller-sees-only-itself-among-user-recipients-test
+ (testing "a sandboxed caller sees only itself among user recipients; raw-value recipients survive"
+ (met/with-gtaps! {:gtaps {:venues {}}}
+ (let [rasta-id (mt/user->id :rasta)
+ notification {:id 3
+ ;; outside the payload-strip set, so only the per-recipient filters run
+ :payload_type :notification/testing
+ :handlers [{:id 10
+ :channel_type :channel/email
+ :recipients [(user-recipient rasta-id)
+ (user-recipient (mt/user->id :lucky))
+ {:type :notification-recipient/raw-value
+ :details {:value "[email protected]"}}]}]}
+ kept (mt/with-test-user :rasta
+ (->> (redaction/redact-notification notification) :handlers first :recipients))]
+ (is (= [rasta-id nil] (mapv :user_id kept))
+ "the other user is hidden; the caller and the raw address remain")))))
+
+(defn- fingerprinted-columns
+ "Names of the columns in a `fields` include payload that still carry a `:fingerprint`."
+ [row]
+ (into #{} (comp (filter :fingerprint) (map :name)) (:result_metadata row)))
+
+(defn- get-content-fields
+ "`get_content` on `card-id` with the `fields` include, as the current test user."
+ [card-id]
+ (let [{:keys [result error]} (registry/call-tool nil "test-session" "get_content"
+ {:items [{:type "question" :id card-id}]
+ :include ["fields"]})]
+ (when error
+ (throw (ex-info (str "get_content rejected: " (:message error)) {:error error})))
+ (first (:results (json/decode+kw (-> result :content first :text))))))
+
+(deftest sandboxed-caller-does-not-receive-fingerprints-test
+ (testing "a fingerprint is computed over every row of its table — `:min`/`:max` are individual cell
+ values and `:distinct-count` counts them all — so a caller whose rows are narrowed by a
+ sandbox must not receive one. Without the strip, a sandbox showing 10 of 100 rows still
+ reports statistics over all 100."
+ (met/with-gtaps-for-user! :rasta
+ {:gtaps {:venues {:remappings {:cat [:dimension [:field (mt/id :venues :category_id) nil]]}}}
+ :attributes {"cat" "50"}}
+ ;; The card is created inside the fixture so its stored `result_metadata` carries the
+ ;; sandboxed database's table ids — the ones `row-restricted-table-ids` answers about.
+ (let [mp (mt/metadata-provider)]
+ (mt/with-temp [:model/Card {card-id :id} {:type :question
+ :creator_id (mt/user->id :crowberto)
+ :dataset_query (lib/query mp (lib.metadata/table mp (mt/id :venues)))}]
+ (testing "unsandboxed, the fingerprints are present — otherwise this test could pass vacuously"
+ (mt/with-test-user :crowberto
+ (is (seq (fingerprinted-columns (get-content-fields card-id)))
+ "an admin with no row restriction still sees fingerprints")))
+ (mt/with-test-user :rasta
+ (testing "precondition: the sandbox really does narrow rasta's rows on VENUES"
+ (is (contains? (metadata-perms/row-restricted-table-ids #{(mt/id :venues)})
+ (mt/id :venues))
+ "if this fails the strip has nothing to key off and the rest is vacuous"))
+ (let [row (get-content-fields card-id)]
+ (is (nil? (:error row)) "the read still succeeds — this redacts, it does not refuse")
+ (is (seq (:result_metadata row)) "column metadata is still returned")
+ (is (= #{} (fingerprinted-columns row))
+ (str "no column may carry a :fingerprint for a sandboxed caller; got "
+ (pr-str (fingerprinted-columns row)))))))))))
diff --git a/enterprise/backend/test/metabase_enterprise/mcp/v2/tools/browse_sandbox_test.clj b/enterprise/backend/test/metabase_enterprise/mcp/v2/tools/browse_sandbox_test.clj
new file mode 100644
index 00000000000..5bc0e011c9f
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/mcp/v2/tools/browse_sandbox_test.clj
@@ -0,0 +1,83 @@
+(ns metabase-enterprise.mcp.v2.tools.browse-sandbox-test
+ "Row-restriction tests for `browse_data`'s `get_fields` action. Fingerprints are computed at sync
+ time over every row of the table, so they must not reach a user whose row access is narrowed."
+ ;; A gtap `:query` is persisted as a card's legacy `dataset_query`, so building these in Lib would
+ ;; only round-trip back through `lib.convert/->legacy-MBQL`.
+ {:clj-kondo/config '{:linters {:deprecated-var {:exclude {metabase.test.data/mbql-query {:namespaces [metabase-enterprise.mcp.v2.tools.browse-sandbox-test]}}}}}}
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase-enterprise.test :as met]
+ [metabase.mcp.v2.tools.browse :as tools.browse]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(defn- get-fields
+ [args]
+ (let [text (-> (tools.browse/browse-data args {}) :content first :text)]
+ (json/decode+kw (first (str/split-lines text)))))
+
+(defn- field-named
+ [envelope field-name]
+ (->> (:tables envelope) (mapcat :fields) (filter #(= field-name (:name %))) first))
+
+(deftest ^:synchronized sandboxed-get-fields-withholds-fingerprint-test
+ (testing "a row-sandboxed user gets no fingerprint — it is computed over rows they cannot see"
+ (met/with-gtaps! {:gtaps {:venues {:query (mt/mbql-query venues {:filter [:= $price 1]})}}
+ :attributes {}}
+ (let [envelope (get-fields {:action "get_fields"
+ :table_ids [(mt/id :venues)]
+ :response_format "detailed"})
+ price (field-named envelope "PRICE")
+ name-col (field-named envelope "NAME")]
+ (testing "PRICE — sandbox-narrowed :values survive, the whole-table :fingerprint does not"
+ (is (some? price))
+ (is (= [[1]] (:values price)))
+ (is (nil? (:fingerprint price))))
+ (testing "NAME — withheld too, since :global :distinct-count leaks whole-table cardinality"
+ (is (some? name-col))
+ (is (nil? (:fingerprint name-col))))))))
+
+(deftest ^:synchronized sandboxed-get-fields-withholds-temporal-fingerprint-test
+ (testing ":earliest/:latest are literal timestamps from hidden rows"
+ (met/with-gtaps! {:gtaps {:checkins {:query (mt/mbql-query checkins {:filter [:= $venue_id 1]})}}
+ :attributes {}}
+ (let [envelope (get-fields {:action "get_fields"
+ :table_ids [(mt/id :checkins)]
+ :response_format "detailed"})
+ date-col (field-named envelope "DATE")]
+ (is (some? date-col))
+ (is (nil? (:fingerprint date-col)))))))
+
+(deftest ^:synchronized sandboxed-get-fields-withholds-fingerprint-projection-test
+ (testing "an explicit `fields` projection cannot route around the withholding"
+ (met/with-gtaps! {:gtaps {:venues {:query (mt/mbql-query venues {:filter [:= $price 1]})}}
+ :attributes {}}
+ (let [envelope (get-fields {:action "get_fields"
+ :table_ids [(mt/id :venues)]
+ :fields ["fields.name" "fields.fingerprint"]})
+ price (field-named envelope "PRICE")]
+ (is (some? price))
+ (is (nil? (:fingerprint price)))))))
+
+(deftest ^:synchronized unrestricted-get-fields-keeps-fingerprint-test
+ (testing "control: a user whose row access is not narrowed still gets the full detailed projection"
+ (mt/with-test-user :crowberto
+ (let [envelope (get-fields {:action "get_fields"
+ :table_ids [(mt/id :venues) (mt/id :checkins)]
+ :response_format "detailed"})
+ price (field-named envelope "PRICE")
+ date-col (field-named envelope "DATE")]
+ (testing "numeric fingerprint statistics are present"
+ (is (some? (-> price :fingerprint :type :type/Number :max))))
+ (testing "temporal fingerprint statistics are present"
+ (is (some? (-> date-col :fingerprint :type :type/DateTime :earliest))))
+ (testing "the other detailed keys are untouched"
+ (is (some? (:effective_type price)))
+ (is (some? (:has_field_values price)))
+ (is (some? (:database_type price))))))))
diff --git a/enterprise/backend/test/metabase_enterprise/mcp/v2/tools/run_saved_question_sandbox_test.clj b/enterprise/backend/test/metabase_enterprise/mcp/v2/tools/run_saved_question_sandbox_test.clj
new file mode 100644
index 00000000000..9dccf1e71b2
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/mcp/v2/tools/run_saved_question_sandbox_test.clj
@@ -0,0 +1,88 @@
+(ns metabase-enterprise.mcp.v2.tools.run-saved-question-sandbox-test
+ "Sandboxing interaction for the v2 `run_saved_question` tool. The tool binds
+ [[metabase.query-processor.card/*allow-arbitrary-mbql-parameters*]] true so a saved
+ question's declared MBQL filter-widget parameters run; sandboxing is query-processor
+ middleware that is orthogonal to that flag, and a parameter can only AND a filter onto the
+ query, never remove the sandbox's own filter. This pins that: a sandboxed user cannot use a
+ dimension parameter to reach rows outside their sandbox. Lives in enterprise because GTAPs do."
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer [deftest is testing use-fixtures]]
+ [metabase-enterprise.test :as met]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.registry :as registry]
+ ;; registers the run_saved_question tool for the call-tool seam below
+ [metabase.mcp.v2.tools.query]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(defn- widget-only-products-query
+ "The GTAP query: PRODUCTS restricted to CATEGORY = \"Widget\", so a sandboxed user never sees
+ any other category through this table."
+ []
+ (let [mp (mt/metadata-provider)
+ table (lib.metadata/table mp (mt/id :products))
+ cat (lib.metadata/field mp (mt/id :products :category))]
+ (lib/filter (lib/query mp table) (lib/= cat "Widget"))))
+
+(defn- products-card-with-category-param
+ "A plain MBQL question over PRODUCTS with a declared filter-widget parameter targeting the
+ CATEGORY field."
+ [card-name]
+ (let [mp (mt/metadata-provider)]
+ {:name card-name
+ :dataset_query (lib/query mp (lib.metadata/table mp (mt/id :products)))
+ :parameters [{:id "p1"
+ :slug "cat_dim"
+ :name "Category"
+ :type :string/=
+ :target [:dimension [:field (mt/id :products :category) nil]]}]}))
+
+(defn- response-text
+ "A dispatch outcome's text block, or a registry-level rejection's message."
+ [{:keys [result error]}]
+ (if error (:message error) (-> result :content first :text)))
+
+(defn- dispatch-error?
+ "Whether a dispatch outcome is an error, at either layer: a registry-level rejection
+ (`{:error …}`, from a scope denial or an args-schema failure) or `:isError` tool content."
+ [{:keys [result error]}]
+ (boolean (or error (:isError result))))
+
+(defn- categories
+ "The distinct CATEGORY values in a successful tool result's rows."
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info (str "Tool call errored: " (response-text outcome)) {:outcome outcome})))
+ (let [[payload] (str/split (response-text outcome) #"\n" 2)
+ {:keys [cols rows]} (json/decode+kw payload)
+ idx (first (keep-indexed #(when (= "CATEGORY" (:name %2)) %1) cols))]
+ (set (map #(nth % idx) rows))))
+
+(defn- run-saved-question [card-id parameters]
+ (registry/call-tool nil (str (random-uuid)) "run_saved_question"
+ (cond-> {:id card-id :row_limit 2000}
+ parameters (assoc :parameters parameters))))
+
+(deftest sandboxed-mbql-parameter-cannot-escape-sandbox-test
+ (testing "an MBQL dimension parameter runs within the sandbox and cannot reach rows outside it"
+ (met/with-gtaps! {:gtaps {:products {:query (widget-only-products-query)}}}
+ (mt/with-temp [:model/Card {card-id :id} (products-card-with-category-param "rsq sandbox")]
+ (testing "with no parameter the sandboxed user sees only their permitted category"
+ (let [cats (categories (run-saved-question card-id nil))]
+ (is (= #{"Widget"} cats)
+ "the sandbox filter must apply through the tool path")))
+ (testing "a parameter selecting the permitted category still returns rows"
+ (is (= #{"Widget"} (categories (run-saved-question card-id [{:id "cat_dim" :value ["Widget"]}])))))
+ (testing "a parameter selecting a category outside the sandbox returns nothing, never those rows"
+ (let [result (run-saved-question card-id [{:id "cat_dim" :value ["Gadget"]}])
+ cats (categories result)]
+ (is (empty? cats)
+ "sandbox (Widget) AND parameter (Gadget) is empty — the parameter cannot widen access")
+ (is (not (contains? cats "Gadget")))))))))
diff --git a/enterprise/backend/test/metabase_enterprise/mcp/v_mcp_tool_calls_test.clj b/enterprise/backend/test/metabase_enterprise/mcp/v_mcp_tool_calls_test.clj
index 3082f5acf45..63154cf5055 100644
--- a/enterprise/backend/test/metabase_enterprise/mcp/v_mcp_tool_calls_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/mcp/v_mcp_tool_calls_test.clj
@@ -64,8 +64,9 @@
row))))))
;; Guard the hand-maintained error_code -> error_type coupling. These pairs must stay in sync with
-;; the CASE in the v_mcp_tool_calls view SQL and the error-code-* constants in metabase.mcp.tools; a
-;; drift on either side breaks this test rather than silently mislabeling errors.
+;; the CASE in the v_mcp_tool_calls view SQL and the error-code-* constants in
+;; metabase.mcp.v2.common; a drift on either side breaks this test rather than silently
+;; mislabeling errors.
(def ^:private error-code->type
{-32600 "Invalid request"
-32601 "Method not found"
diff --git a/enterprise/backend/test/metabase_enterprise/metabot/tools/semantic_search_test.clj b/enterprise/backend/test/metabase_enterprise/metabot/tools/semantic_search_test.clj
index 50b6bd4663c..0f7f54d18a0 100644
--- a/enterprise/backend/test/metabase_enterprise/metabot/tools/semantic_search_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/metabot/tools/semantic_search_test.clj
@@ -26,7 +26,8 @@
`(do ~@body (with-semantic-search-if-available! ~mock-embeddings ~@body)))
(deftest search-test
- ;; Fully mocked: each sub-test redefs search-core/search, so no engine or index runs. active-engines is
+ ;; Fully mocked: each sub-test redefs search-core/ranked-results (and search-results passes through, set
+ ;; up below), so no engine or index runs. active-engines is
;; pinned to include semantic so search/search takes the two-engine fusion branch (term queries via the
;; fallback engine, semantic queries via semantic), regardless of whether this instance has pgvector.
(mt/with-additional-premium-features #{:content-verification}
@@ -45,26 +46,30 @@
:verified true}]
(with-redefs [perms/impersonated-user? (fn [] false)
perms/sandboxed-user? (fn [] false)
- search.engine/active-engines (constantly [:search.engine/semantic :search.engine/appdb])]
+ search.engine/active-engines (constantly [:search.engine/semantic :search.engine/appdb])
+ ;; The per-query search now runs through ranked-results (each sub-test mocks that).
+ ;; search-results — the one-time hydrate step — is a passthrough so the mocked ranked
+ ;; records reach postprocess-search-result unchanged.
+ search-core/search-results (fn [_ctx _model-set ranked] {:data (vec ranked)})]
(testing "search returns postprocessed results for term queries"
- (with-redefs [search-core/search (fn [_] {:data [order-table]})]
+ (with-redefs [search-core/ranked-results (fn [_] [order-table])]
(let [args {:term-queries ["orders"]
:entity-types ["table"]}
results (search/search args)
expected [(#'search/postprocess-search-result order-table)]]
(is (= expected results)))))
(testing "search returns postprocessed results for semantic queries"
- (with-redefs [search-core/search (fn [_] {:data [dashboard]})]
+ (with-redefs [search-core/ranked-results (fn [_] [dashboard])]
(let [args {:semantic-queries ["sales metrics"]
:entity-types ["dashboard"]}
results (search/search args)
expected [(#'search/postprocess-search-result dashboard)]]
(is (= expected results)))))
(testing "search combines term and semantic queries using RRF"
- (with-redefs [search-core/search (fn [context]
- (if (= (:search-string context) "orders")
- {:data [order-table]}
- {:data [dashboard]}))]
+ (with-redefs [search-core/ranked-results (fn [context]
+ (if (= (:search-string context) "orders")
+ [order-table]
+ [dashboard]))]
(let [args {:term-queries ["orders"]
:semantic-queries ["sales"]
:entity-types ["table" "dashboard"]}
@@ -78,10 +83,10 @@
;; Pass terms through uncombined: Postgres appdb would OR them into one string,
;; which breaks the per-query mock keying below. Keeps this deterministic on any app-db.
search.engine/disjunction (fn [_ terms] terms)
- search-core/search (fn [context]
- (if (= (:search-string context) "orders")
- {:data [order-table]}
- {:data [dashboard]}))]
+ search-core/ranked-results (fn [context]
+ (if (= (:search-string context) "orders")
+ [order-table]
+ [dashboard]))]
(let [args {:term-queries ["orders"]
:semantic-queries ["sales"]
:entity-types ["table" "dashboard"]}
@@ -91,8 +96,8 @@
(is (some #(= (:id %) 1) results))
(is (some #(= (:id %) 2) results)))))
(testing "search applies RRF to overlapping results"
- (with-redefs [search-core/search (fn [_]
- {:data [order-table dashboard]})]
+ (with-redefs [search-core/ranked-results (fn [_]
+ [order-table dashboard])]
(let [args {:term-queries ["orders" "sales"]
:entity-types ["table" "dashboard"]}
results (search/search args)]
@@ -101,7 +106,7 @@
(is (some #(= (:id %) 1) results))
(is (some #(= (:id %) 2) results)))))
(testing "search handles empty results"
- (with-redefs [search-core/search (fn [_] {:data []})]
+ (with-redefs [search-core/ranked-results (fn [_] [])]
(let [args {:term-queries ["nonexistent"]
:entity-types ["table"]}
results (search/search args)]
@@ -112,10 +117,10 @@
(with-redefs [metabot.db/metabot-by-entity-id (fn [entity-id]
(is (= "test-bot" entity-id) "Should look up the Metabot")
metabot)
- search-core/search (fn [context]
- ;; use_verified_content now drives the curated filter, not :verified
- (is (true? (:curated? context)))
- {:data [dashboard]})]
+ search-core/ranked-results (fn [context]
+ ;; use_verified_content now drives the curated filter, not :verified
+ (is (true? (:curated? context)))
+ [dashboard])]
(let [results (search/search {:term-queries ["test"]
:metabot-id "test-bot"
:entity-types ["dashboard"]})]
diff --git a/frontend/src/metabase-types/api/metabot.ts b/frontend/src/metabase-types/api/metabot.ts
index 2e3de29fca8..4eb10a99378 100644
--- a/frontend/src/metabase-types/api/metabot.ts
+++ b/frontend/src/metabase-types/api/metabot.ts
@@ -1,3 +1,5 @@
+import type { EnterpriseSettings } from "./settings";
+
import type {
CardDisplayType,
CardId,
@@ -14,6 +16,8 @@ import type {
SuggestedTransform,
Transform,
UnsavedCard,
+ User,
+ UserPermissions,
} from ".";
export type MetabotFeedbackType =
@@ -297,6 +301,37 @@ export type SubmitMcpAppsFeedbackRequest = {
payload: McpAppsFeedback;
};
+/**
+ * The current-user projection `GET /api/embed-mcp/bootstrap` returns.
+ *
+ * Deliberately much narrower than `User`: the iframe's UI credential is minted from an
+ * MCP token that may hold nothing but `agent:query:run`, so it must not be able to read
+ * the full profile. Adding a field here means adding it to `::bootstrap-user` in
+ * `metabase.mcp.callback-api`, which is where that decision belongs.
+ */
+export type McpAppsBootstrapUser = Pick<
+ User,
+ | "id"
+ | "locale"
+ | "is_superuser"
+ | "is_data_analyst"
+ | "is_qbnewb"
+ | "tenant_id"
+ | "personal_collection_id"
+> & {
+ permissions: Pick<
+ UserPermissions,
+ "can_create_queries" | "can_create_native_queries"
+ >;
+};
+
+export type McpAppsBootstrapResponse = {
+ user: McpAppsBootstrapUser;
+
+ /** The settings a non-admin authenticated user may read, whoever the credential belongs to. */
+ settings: EnterpriseSettings;
+};
+
/* Metabot v3 - Entity Types */
export type MetabotId = number;
diff --git a/frontend/src/metabase-types/api/mocks/metabot.ts b/frontend/src/metabase-types/api/mocks/metabot.ts
index bf0a98aaea5..73bf9428e5d 100644
--- a/frontend/src/metabase-types/api/mocks/metabot.ts
+++ b/frontend/src/metabase-types/api/mocks/metabot.ts
@@ -1,11 +1,18 @@
+import _ from "underscore";
+
import {
AIToolKey,
+ type McpAppsBootstrapResponse,
+ type McpAppsBootstrapUser,
type MetabotConversation,
type MetabotGroupPermission,
type MetabotInfo,
type UserMetabotPermissions,
type UserMetabotPermissionsResponse,
} from "../metabot";
+import type { EnterpriseSettingKey, EnterpriseSettings } from "../settings";
+
+import { createMockSettings } from "./settings";
export const createMockMetabotInfo = (
opts?: Partial<MetabotInfo>,
@@ -75,3 +82,158 @@ export const createMockMetabotGroupPermissions = (
perm_value: permValue,
}));
};
+
+/**
+ * The setting keys `GET /api/embed-mcp/bootstrap` returns, out of those
+ * {@link createMockSettings} defines: the `:public`, `:authenticated` and
+ * `:admin-write-authed-read` settings a non-admin authenticated user may read.
+ * Everything else — SMTP and SSO configuration, LLM keys, Slack tokens — is
+ * `:admin`, `:internal` or `:settings-manager`, and the endpoint drops it.
+ */
+export const MCP_APPS_BOOTSTRAP_SETTING_KEYS = [
+ "admin-email",
+ "agent-api-enabled?",
+ "ai-features-enabled?",
+ "airgap-enabled",
+ "allowed-iframe-hosts",
+ "analytics-uuid",
+ "anon-tracking-enabled",
+ "application-colors",
+ "application-favicon-url",
+ "application-font",
+ "application-font-files",
+ "application-name",
+ "available-fonts",
+ "available-locales",
+ "available-timezones",
+ "bug-reporting-enabled",
+ "cloud-gateway-ips",
+ "csp-img-allowed-hosts",
+ "csp-img-enabled",
+ "custom-formatting",
+ "custom-geojson",
+ "custom-homepage",
+ "custom-homepage-dashboard",
+ "custom-viz-plugin-dev-mode-enabled",
+ "development-mode?",
+ "email-configured?",
+ "embedded-metabot-enabled?",
+ "embedding-app-origin",
+ "embedding-app-origins-interactive",
+ "embedding-app-origins-sdk",
+ "enable-embedding",
+ "enable-embedding-interactive",
+ "enable-embedding-sdk",
+ "enable-embedding-simple",
+ "enable-embedding-static",
+ "enable-nested-queries",
+ "enable-password-login",
+ "enable-pivoted-exports",
+ "enable-public-sharing",
+ "enable-sandboxes?",
+ "enable-xrays",
+ "example-dashboard-id",
+ "expand-bookmarks-in-nav",
+ "expand-browse-in-nav",
+ "google-auth-client-id",
+ "google-auth-enabled",
+ "has-sample-database?",
+ "has-user-setup",
+ "help-link",
+ "help-link-custom-destination",
+ "hide-embed-branding?",
+ "instance-creation",
+ "is-hosted?",
+ "last-used-native-database-id",
+ "ldap-configured?",
+ "ldap-enabled",
+ "llm-anthropic-api-key-configured?",
+ "loading-message",
+ "map-tile-server-url",
+ "mcp-enabled?",
+ "metabot-enabled?",
+ "metabot-icon",
+ "metabot-name",
+ "metabot-show-illustrations",
+ "metaplow-tracking-enabled",
+ "metaplow-url",
+ "mfa-enforcement",
+ "native-query-autocomplete-match-style",
+ "non-table-chart-generated",
+ "notebook-native-preview-sidebar-width",
+ "oidc-login-providers",
+ "other-sso-enabled?",
+ "password-complexity",
+ "persisted-models-enabled",
+ "read-only-mode",
+ "redirect-all-requests-to-https",
+ "report-timezone-long",
+ "report-timezone-short",
+ "sdk-iframe-embed-setup-settings",
+ "search-engine",
+ "search-typeahead-enabled",
+ "session-cookies",
+ "setup-token",
+ "show-google-sheets-integration",
+ "show-homepage-data",
+ "show-homepage-pin-message",
+ "show-homepage-xrays",
+ "show-metabase-links",
+ "show-metabot",
+ "site-locale",
+ "site-url",
+ "site-uuid",
+ "snowplow-enabled",
+ "snowplow-url",
+ "start-of-week",
+ "token-features",
+ "tracing-enabled",
+ "transforms-enabled",
+ "transforms-meter-locked",
+ "transforms-setup-complete",
+ "trial-banner-dismissal-timestamp",
+ "uploads-settings",
+ "use-tenants",
+ "user-visibility",
+ "version-info-last-checked",
+] as const satisfies readonly EnterpriseSettingKey[];
+
+export const createMockMcpAppsBootstrapUser = (
+ opts?: Partial<McpAppsBootstrapUser>,
+): McpAppsBootstrapUser => ({
+ id: 1,
+ locale: null,
+ is_superuser: false,
+ is_data_analyst: false,
+ is_qbnewb: false,
+ tenant_id: null,
+ personal_collection_id: 1,
+ permissions: {
+ can_create_queries: true,
+ can_create_native_queries: true,
+ },
+ ...opts,
+});
+
+export const createMockMcpAppsBootstrapSettings = (
+ opts?: Partial<EnterpriseSettings>,
+): EnterpriseSettings => {
+ const projected = _.pick(
+ createMockSettings(opts),
+ ...MCP_APPS_BOOTSTRAP_SETTING_KEYS,
+ );
+
+ // The endpoint answers a visibility-filtered subset while the client types the
+ // payload as the whole `EnterpriseSettings`. Reproducing that gap is the point of
+ // this fixture: a component that reads a setting the projection drops has to fail
+ // here rather than read a value only the mock provides.
+ return projected as EnterpriseSettings;
+};
+
+export const createMockMcpAppsBootstrapResponse = (
+ opts?: Partial<McpAppsBootstrapResponse>,
+): McpAppsBootstrapResponse => ({
+ user: createMockMcpAppsBootstrapUser(),
+ settings: createMockMcpAppsBootstrapSettings(),
+ ...opts,
+});
diff --git a/frontend/src/metabase/embedding/mcp/McpQuestionView.unit.spec.tsx b/frontend/src/metabase/embedding/mcp/McpQuestionView.unit.spec.tsx
new file mode 100644
index 00000000000..2108f170fc7
--- /dev/null
+++ b/frontend/src/metabase/embedding/mcp/McpQuestionView.unit.spec.tsx
@@ -0,0 +1,170 @@
+import {
+ setupAlertsEndpoints,
+ setupCardEndpoints,
+ setupCardQueryEndpoints,
+ setupCardQueryMetadataEndpoint,
+ setupCurrentUserEndpoint,
+ setupDatabaseEndpoints,
+ setupPropertiesEndpoints,
+ setupSettingsEndpoints,
+} from "__support__/server-mocks";
+import { createMockEmbedState, createMockState } from "__support__/state";
+import {
+ mockGetBoundingClientRect,
+ screen,
+ waitFor,
+ within,
+} from "__support__/ui";
+import { SdkQuestion } from "embedding-sdk-bundle/components/public/SdkQuestion";
+import { renderWithSDKProviders } from "embedding-sdk-bundle/test/__support__/ui";
+import { createMockSdkConfig } from "embedding-sdk-bundle/test/mocks/config";
+import {
+ createMockLoginStatusState,
+ createMockSdkState,
+} from "embedding-sdk-bundle/test/mocks/state";
+import MetabaseSettings from "metabase/utils/settings";
+import type { User } from "metabase-types/api";
+import {
+ createMockCard,
+ createMockCardQueryMetadata,
+ createMockDataset,
+ createMockDatasetData,
+ createMockDatetimeColumn,
+ createMockMcpAppsBootstrapResponse,
+ createMockMcpAppsBootstrapSettings,
+ createMockNumericColumn,
+ createMockTokenFeatures,
+} from "metabase-types/api/mocks";
+import {
+ ORDERS,
+ ORDERS_ID,
+ SAMPLE_DB_ID,
+ createSampleDatabase,
+} from "metabase-types/api/mocks/presets";
+
+import { McpQuestionView } from "./McpQuestionView";
+
+const TEST_DATABASE = createSampleDatabase();
+
+const TEST_CARD = createMockCard({
+ name: "Orders over time",
+ display: "table",
+ dataset_query: {
+ type: "query",
+ database: SAMPLE_DB_ID,
+ query: {
+ "source-table": ORDERS_ID,
+ aggregation: [["count"]],
+ breakout: [["field", ORDERS.CREATED_AT, { "temporal-unit": "quarter" }]],
+ },
+ },
+});
+
+const QUERY_RESULT = createMockDataset({
+ data: createMockDatasetData({
+ cols: [
+ createMockDatetimeColumn({
+ name: "CREATED_AT",
+ display_name: "Created At",
+ source: "breakout",
+ unit: "quarter",
+ }),
+ createMockNumericColumn({
+ name: "count",
+ display_name: "Count",
+ source: "aggregation",
+ }),
+ ],
+ rows: [["2024-01-01T00:00:00Z", 26000]],
+ }),
+});
+
+/**
+ * What `GET /api/embed-mcp/bootstrap` answers, not what a logged-in browser session
+ * sees: a seven-field user projection and the visibility-filtered settings map. The
+ * SDK token feature is switched on because the MCP iframe mounts SDK components and
+ * `renderWithSDKProviders` only defaults it in when the caller seeds no settings.
+ */
+const BOOTSTRAP = createMockMcpAppsBootstrapResponse({
+ settings: createMockMcpAppsBootstrapSettings({
+ "enable-embedding-sdk": true,
+ "token-features": createMockTokenFeatures({ embedding_sdk: true }),
+ }),
+});
+
+function setup() {
+ const { user, settings } = BOOTSTRAP;
+
+ // Reproduces the widening `useMcpUserAndSettingsFetch` does when it seeds the cache: at
+ // runtime the store holds a `User` carrying only these fields.
+ const currentUser = user as User;
+
+ setupCurrentUserEndpoint(currentUser);
+ setupSettingsEndpoints([]);
+ setupPropertiesEndpoints(settings);
+ setupCardEndpoints(TEST_CARD);
+ setupCardQueryMetadataEndpoint(
+ TEST_CARD,
+ createMockCardQueryMetadata({ databases: [TEST_DATABASE] }),
+ );
+ setupDatabaseEndpoints(TEST_DATABASE);
+ setupAlertsEndpoints(TEST_CARD, []);
+ setupCardQueryEndpoints(TEST_CARD, QUERY_RESULT);
+
+ // Not `mockSettings`: it re-expands through `createMockSettings`, restoring the admin-only
+ // settings the projection drops and hiding the regression this spec guards.
+ MetabaseSettings.setAll(settings);
+
+ const state = createMockState({
+ currentUser,
+ settings: { values: settings, loading: false },
+ sdk: createMockSdkState({
+ initStatus: createMockLoginStatusState({ status: "success" }),
+ }),
+ embed: createMockEmbedState(),
+ });
+
+ renderWithSDKProviders(
+ <SdkQuestion
+ questionId={TEST_CARD.id}
+ isSaveEnabled={false}
+ withEditorButton={false}
+ withChartTypeSelector={false}
+ >
+ <McpQuestionView queryKey="test-query" safeAreaPaddingTop={0} />
+ </SdkQuestion>,
+ {
+ componentProviderProps: { authConfig: createMockSdkConfig() },
+ storeInitialState: state,
+ },
+ );
+}
+
+describe("McpQuestionView with the MCP Apps bootstrap projection (GHY-4400)", () => {
+ beforeEach(() => {
+ mockGetBoundingClientRect({ width: 800, height: 400 });
+ });
+
+ it("renders the visualization when the store holds only the bootstrap user and settings", async () => {
+ setup();
+
+ const visualization = await screen.findByTestId("query-visualization-root");
+
+ expect(
+ await within(visualization).findByText("26,000"),
+ ).toBeInTheDocument();
+ expect(within(visualization).getByText("Created At")).toBeInTheDocument();
+ });
+
+ it("renders the question title and the time controls, not an error state", async () => {
+ setup();
+
+ expect(await screen.findByText("Count by Created At")).toBeInTheDocument();
+ expect(screen.getByTestId("query-explorer-bar")).toBeInTheDocument();
+
+ await waitFor(() => {
+ expect(screen.queryByText(/gone wrong/i)).not.toBeInTheDocument();
+ });
+ expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+ });
+});
diff --git a/frontend/src/metabase/embedding/mcp/McpUiAppRoute.tsx b/frontend/src/metabase/embedding/mcp/McpUiAppRoute.tsx
index 1aa4477ed79..45f35705adc 100644
--- a/frontend/src/metabase/embedding/mcp/McpUiAppRoute.tsx
+++ b/frontend/src/metabase/embedding/mcp/McpUiAppRoute.tsx
@@ -11,7 +11,7 @@ import type { ResolvedColorScheme } from "metabase/utils/color-scheme";
import { McpCardFooter } from "./McpCardFooter";
import { McpFeedbackArea } from "./McpFeedbackArea";
import { MCP_CONTENT_HEIGHT, McpQuestionView } from "./McpQuestionView";
-import { getMcpDeserializedCard } from "./McpUiAppRoute.utils";
+import { getMcpDeserializedQuery } from "./McpUiAppRoute.utils";
import { useHandleMcpDrillThrough } from "./hooks/useHandleMcpDrillThrough";
import { type McpAppState, useMcpApp } from "./hooks/useMcpApp";
import { useMcpFeedback } from "./hooks/useMcpFeedback";
@@ -32,6 +32,7 @@ interface McpUiAppRouteContentProps {
mcpSessionId: string;
prompt: McpAppState["prompt"];
query: McpAppState["query"];
+ queryError: McpAppState["queryError"];
uiCredential: string;
}
@@ -59,6 +60,7 @@ export function McpUiAppRoute() {
uiCredential,
prompt,
query,
+ queryError,
} = useMcpApp();
const scheme: ResolvedColorScheme =
@@ -94,6 +96,7 @@ export function McpUiAppRoute() {
mcpSessionId={mcpSessionId}
prompt={prompt}
query={query}
+ queryError={queryError}
uiCredential={uiCredential}
/>
</ComponentProvider>
@@ -108,6 +111,7 @@ function McpUiAppRouteContent({
mcpSessionId,
prompt,
query,
+ queryError,
uiCredential,
}: McpUiAppRouteContentProps) {
const isHosted = useSetting("is-hosted?");
@@ -119,18 +123,19 @@ function McpUiAppRouteContent({
mcpSessionId,
});
- const deserializedCard = useMemo(() => {
+ const deserializedQuery = useMemo(() => {
if (!query) {
return null;
}
- return getMcpDeserializedCard(query);
+ return getMcpDeserializedQuery(query);
}, [query]);
const { isSettingsReady, userAndSettingsFetchError } =
useMcpUserAndSettingsFetch({
instanceUrl,
uiCredential,
+ mcpSessionId,
store,
});
@@ -139,16 +144,16 @@ function McpUiAppRouteContent({
hostContext &&
isSettingsReady &&
uiCredential &&
- deserializedCard
+ deserializedQuery
);
useEffect(() => {
// Remove the loading indicator on the HTML page once the app is ready or
// when initialization fails and the route can render its own error.
- if (isReady || hostError || userAndSettingsFetchError) {
+ if (isReady || hostError || userAndSettingsFetchError || queryError) {
document.getElementById("mcp-loading")?.remove();
}
- }, [hostError, isReady, userAndSettingsFetchError]);
+ }, [hostError, isReady, queryError, userAndSettingsFetchError]);
const height = `calc(${MCP_CONTENT_HEIGHT} + ${FOOTER_HEIGHT})`;
@@ -222,9 +227,10 @@ function McpUiAppRouteContent({
};
const renderQuestionCardView = () =>
- deserializedCard && (
+ deserializedQuery && (
<SdkQuestion
- deserializedCard={deserializedCard}
+ deserializedCard={deserializedQuery.card}
+ initialSqlParameters={deserializedQuery.initialSqlParameters}
isSaveEnabled={false}
// we should never show query builder in chat interfaces
withEditorButton={false}
@@ -244,6 +250,12 @@ function McpUiAppRouteContent({
return <SdkError message={userAndSettingsFetchError} />;
}
+ // A handle that will not resolve has no card to render. Without this the
+ // route would sit on the loading indicator forever.
+ if (queryError) {
+ return <SdkError message={queryError} />;
+ }
+
if (!isReady) {
return null;
}
diff --git a/frontend/src/metabase/embedding/mcp/McpUiAppRoute.utils.ts b/frontend/src/metabase/embedding/mcp/McpUiAppRoute.utils.ts
index dca3bb50914..bb2cd9b4b57 100644
--- a/frontend/src/metabase/embedding/mcp/McpUiAppRoute.utils.ts
+++ b/frontend/src/metabase/embedding/mcp/McpUiAppRoute.utils.ts
@@ -1,3 +1,4 @@
+import type { SqlParameterValues } from "embedding-sdk-bundle/types/question";
import { b64_to_utf8 } from "metabase/utils/encoding";
import type { SeriesCard, VisualizationSettings } from "metabase-types/api";
@@ -6,14 +7,56 @@ export const MCP_APP_VISUALIZATION_SETTINGS: VisualizationSettings = {
"graph.y_axis.labels_enabled": false,
};
-export function getMcpDeserializedCard(query: string): SeriesCard | null {
+export interface McpDeserializedQuery {
+ card: SeriesCard;
+ initialSqlParameters: SqlParameterValues;
+}
+
+/**
+ * Split a base64 MCP query handle into the card to render and the template-tag
+ * values to run it with. Returns null when the payload is not decodable JSON.
+ */
+export function getMcpDeserializedQuery(
+ query: string,
+): McpDeserializedQuery | null {
try {
+ // `execute_sql` mints a payload wider than a dataset query: the values bound to `{{tag}}`
+ // placeholders ride alongside it under `parameters`, because the backend's
+ // `prepare-for-serialization` strips `:parameters` from the query itself as runtime-only.
+ const { parameters, ...datasetQuery } = JSON.parse(b64_to_utf8(query));
+
return {
- display: "table",
- dataset_query: JSON.parse(b64_to_utf8(query)),
- visualization_settings: MCP_APP_VISUALIZATION_SETTINGS,
+ card: {
+ display: "table",
+ dataset_query: datasetQuery,
+ visualization_settings: MCP_APP_VISUALIZATION_SETTINGS,
+ },
+ initialSqlParameters: getInitialSqlParameters(parameters),
};
} catch {
return null;
}
}
+
+/**
+ * Key each bound value by its template-tag name, the form `initialSqlParameters` takes.
+ * The parameters are matched to the question's own template-tag parameters by slug, so
+ * putting them on the card instead would not work: they carry no `id`, and a card-level
+ * `parameters` array short-circuits the tag-derived one it needs to be matched against.
+ */
+function getInitialSqlParameters(parameters: unknown): SqlParameterValues {
+ if (!Array.isArray(parameters)) {
+ return {};
+ }
+
+ return Object.fromEntries(
+ parameters.flatMap((parameter) => {
+ const [, tag] = parameter?.target ?? [];
+ const [tagType, tagName] = tag ?? [];
+
+ return tagType === "template-tag" && typeof tagName === "string"
+ ? [[tagName, parameter.value]]
+ : [];
+ }),
+ );
+}
diff --git a/frontend/src/metabase/embedding/mcp/McpUiAppRoute.utils.unit.spec.ts b/frontend/src/metabase/embedding/mcp/McpUiAppRoute.utils.unit.spec.ts
index 84fc94dc3b3..e3f8adfbf52 100644
--- a/frontend/src/metabase/embedding/mcp/McpUiAppRoute.utils.unit.spec.ts
+++ b/frontend/src/metabase/embedding/mcp/McpUiAppRoute.utils.unit.spec.ts
@@ -1,13 +1,48 @@
+import { createMockMetadata } from "__support__/metadata";
+import { getParameterValuesByIdFromQueryParams } from "metabase/parameters/utils/parameter-parsing";
import { utf8_to_b64 } from "metabase/utils/encoding";
+import Question from "metabase-lib/v1/Question";
+import { getCardUiParameters } from "metabase-lib/v1/parameters/utils/cards";
+import { normalizeParameters } from "metabase-lib/v1/parameters/utils/parameter-values";
-import { getMcpDeserializedCard } from "./McpUiAppRoute.utils";
+import { getMcpDeserializedQuery } from "./McpUiAppRoute.utils";
-describe("getMcpDeserializedCard", () => {
+// The exact payload `execute_sql` mints, captured from `lib/prepare-for-serialization` in the REPL:
+// MBQL 5 (`stages`, not a legacy `dataset_query`), `template-tags` as an array rather than a map,
+// and `parameters` re-attached at the top level because serialization strips them from the query.
+const NATIVE_QUERY = {
+ "lib/type": "mbql/query",
+ stages: [
+ {
+ "lib/type": "mbql.stage/native",
+ "template-tags": [
+ {
+ type: "text",
+ name: "cat",
+ id: "1f8cda0e-e8ae-4d63-ae5c-896d3bf4bc59",
+ "display-name": "Cat",
+ },
+ ],
+ native: "SELECT {{cat}} AS cat",
+ },
+ ],
+ database: 29001,
+};
+
+const BOUND_PARAMETERS = [
+ {
+ type: "text",
+ target: ["variable", ["template-tag", "cat"]],
+ value: "meow",
+ },
+];
+
+describe("getMcpDeserializedQuery", () => {
it("hides axis labels for MCP App ad-hoc charts", () => {
const datasetQuery = { database: 1, type: "query", query: {} };
const query = utf8_to_b64(JSON.stringify(datasetQuery));
- expect(getMcpDeserializedCard(query)).toEqual(
+ expect(getMcpDeserializedQuery(query)?.card).toEqual(
expect.objectContaining({
display: "table",
dataset_query: datasetQuery,
@@ -19,7 +54,116 @@ describe("getMcpDeserializedCard", () => {
);
});
+ it("returns bound template-tag values keyed by tag name", () => {
+ const query = utf8_to_b64(
+ JSON.stringify({
+ ...NATIVE_QUERY,
+ parameters: BOUND_PARAMETERS,
+ }),
+ );
+
+ expect(getMcpDeserializedQuery(query)?.initialSqlParameters).toEqual({
+ cat: "meow",
+ });
+ });
+
+ it("keeps parameters out of dataset_query", () => {
+ // `execute_sql` re-attaches `:parameters` to the serialized query, so a handle is wider than a
+ // dataset query. Leaving them nested there loses the values twice over: the card's own
+ // parameters win when the run payload is assembled, and nothing reads a `parameters` key inside
+ // `dataset_query` — so the native query would run with `{{cat}}` unbound.
+ const query = utf8_to_b64(
+ JSON.stringify({
+ ...NATIVE_QUERY,
+ parameters: BOUND_PARAMETERS,
+ }),
+ );
+
+ expect(getMcpDeserializedQuery(query)?.card.dataset_query).toEqual(
+ NATIVE_QUERY,
+ );
+ });
+
+ it("returns no template-tag values for a query that carries none", () => {
+ const datasetQuery = { database: 1, type: "query", query: {} };
+ const query = utf8_to_b64(JSON.stringify(datasetQuery));
+
+ expect(getMcpDeserializedQuery(query)?.initialSqlParameters).toEqual({});
+ });
+
+ it("skips parameters that do not target a template tag", () => {
+ const query = utf8_to_b64(
+ JSON.stringify({
+ ...NATIVE_QUERY,
+ parameters: [{ type: "category", value: "Gizmo", target: null }],
+ }),
+ );
+
+ expect(getMcpDeserializedQuery(query)?.initialSqlParameters).toEqual({});
+ });
+
it("returns null for invalid query params", () => {
- expect(getMcpDeserializedCard("not-json")).toBeNull();
+ expect(getMcpDeserializedQuery("not-json")).toBeNull();
+ });
+
+ // The load-bearing one. The two above only prove the payload was split; this proves the split
+ // halves rejoin: the card's own parameters are derived from its template tags, and
+ // `initialSqlParameters` is matched against them by slug. If the value doesn't land here, the
+ // embed runs `{{cat}}` unbound no matter how clean the split.
+ //
+ // Matches against `question.parameters()` through `getParameterValuesByIdFromQueryParams`
+ // directly, rather than through `getParameterValuesForQuestion`, which is what that helper
+ // delegates to — it keeps the test off a signature that is currently in flux upstream while
+ // exercising the same semantics.
+ it("binds the value to the card's template-tag parameter", () => {
+ const deserialized = getMcpDeserializedQuery(
+ utf8_to_b64(
+ JSON.stringify({ ...NATIVE_QUERY, parameters: BOUND_PARAMETERS }),
+ ),
+ );
+ const card = deserialized!.card;
+ const metadata = createMockMetadata({});
+
+ const uiParameters = getCardUiParameters(card, metadata);
+ expect(uiParameters.map((parameter) => parameter.slug)).toEqual(["cat"]);
+
+ const parameterValues = getParameterValuesByIdFromQueryParams(
+ new Question(card, metadata).parameters(),
+ deserialized!.initialSqlParameters,
+ );
+ // Array-wrapped by widget normalization: `normalizeParameterValue` wraps every string- and
+ // number-typed parameter the same way on the path to the request, so this is the shape a
+ // filter widget produces too, not an MCP quirk.
+ expect(Object.values(parameterValues)).toEqual([["meow"]]);
+ });
+
+ // The whole chain, mirroring `loadQuestionSdk`: build the question from the card, apply template
+ // tag parameters, derive values from `initialSqlParameters`, set them, then assemble the request
+ // parameters exactly as `runQuestionQuery` does. This is the payload the QP receives — if the
+ // bound value is missing here, the embed reports `missing required parameters`.
+ it("sends the bound value in the request parameters", () => {
+ const deserialized = getMcpDeserializedQuery(
+ utf8_to_b64(
+ JSON.stringify({ ...NATIVE_QUERY, parameters: BOUND_PARAMETERS }),
+ ),
+ );
+ const card = deserialized!.card;
+ const metadata = createMockMetadata({});
+
+ let question = new Question(card, metadata).applyTemplateTagParameters();
+ question = question.setParameterValues(
+ getParameterValuesByIdFromQueryParams(
+ question.parameters(),
+ deserialized!.initialSqlParameters,
+ ),
+ );
+
+ const requestParameters = normalizeParameters(question.parameters());
+ expect(requestParameters).toEqual([
+ expect.objectContaining({
+ value: ["meow"],
+ target: ["variable", ["template-tag", "cat"]],
+ }),
+ ]);
});
});
diff --git a/frontend/src/metabase/embedding/mcp/api.ts b/frontend/src/metabase/embedding/mcp/api.ts
index e80ee0205dd..e6487a4a2a9 100644
--- a/frontend/src/metabase/embedding/mcp/api.ts
+++ b/frontend/src/metabase/embedding/mcp/api.ts
@@ -1,7 +1,10 @@
/* eslint-disable metabase/no-literal-metabase-strings */
import { EMBEDDING_SDK_CONFIG } from "metabase/embedding-sdk/config";
-import type { SubmitMcpAppsFeedbackRequest } from "metabase-types/api";
+import type {
+ McpAppsBootstrapResponse,
+ SubmitMcpAppsFeedbackRequest,
+} from "metabase-types/api";
type StoreDrillQueryRequest = {
instanceUrl: string;
@@ -19,6 +22,45 @@ type SubmitMcpFeedbackPayload = SubmitMcpAppsFeedbackRequest & {
uiCredential: string;
};
+type McpBootstrapRequest = {
+ instanceUrl: string;
+ uiCredential: string;
+ mcpSessionId: string;
+};
+
+/**
+ * Fetches the user and settings the iframe needs to mount.
+ *
+ * The UI credential authenticates this endpoint and nothing on the general REST API,
+ * so a failure here is the whole app's auth story. The status rides along on the error
+ * so the caller can tell "credential rejected" from "MCP is switched off".
+ */
+export async function fetchMcpBootstrap({
+ instanceUrl,
+ uiCredential,
+ mcpSessionId,
+}: McpBootstrapRequest): Promise<McpAppsBootstrapResponse> {
+ const response = await fetch(`${instanceUrl}/api/embed-mcp/bootstrap`, {
+ method: "GET",
+ headers: {
+ "X-Metabase-Client": EMBEDDING_SDK_CONFIG.metabaseClientRequestHeader,
+ "X-Metabase-Mcp-Ui-Auth": uiCredential,
+ "Mcp-Session-Id": mcpSessionId,
+ },
+ });
+
+ if (!response.ok) {
+ throw Object.assign(
+ new Error(
+ `fetchMcpBootstrap failed: ${response.status} ${response.statusText}`,
+ ),
+ { status: response.status },
+ );
+ }
+
+ return response.json();
+}
+
/**
* Stores the drill-through's query on the server and returns a handle UUID
* that the iframe threads into the agent message so `render_drill_through`
@@ -52,6 +94,60 @@ export async function storeDrillQuery({
return response.json();
}
+type FetchQueryByHandleRequest = {
+ instanceUrl: string;
+ uiCredential: string;
+ mcpSessionId: string;
+ queryHandle: string;
+};
+
+type FetchQueryByHandleResponse = {
+ query: string;
+ prompt: string | null;
+};
+
+/**
+ * Exchanges a query handle for the base64-encoded query it stands for.
+ *
+ * The v2 MCP tools return only a handle, so the query never enters the model's
+ * context; the iframe resolves it here with the scoped UI credential it was
+ * rendered with. The lookup is user-scoped and the credential is accepted only
+ * on the MCP UI request surface, so a handle on its own is not a bearer
+ * credential.
+ *
+ * We cannot use RTK Query here as we are not in Metabase's React tree.
+ */
+export async function fetchQueryByHandle({
+ instanceUrl,
+ uiCredential,
+ mcpSessionId,
+ queryHandle,
+}: FetchQueryByHandleRequest): Promise<FetchQueryByHandleResponse> {
+ const response = await fetch(
+ `${instanceUrl}/api/embed-mcp/queries/${encodeURIComponent(queryHandle)}`,
+ {
+ headers: {
+ "X-Metabase-Client": EMBEDDING_SDK_CONFIG.metabaseClientRequestHeader,
+ "X-Metabase-Mcp-Ui-Auth": uiCredential,
+ "Mcp-Session-Id": mcpSessionId,
+ },
+ },
+ );
+
+ if (!response.ok) {
+ // `status` carries the reason the iframe shows the user — an expired handle
+ // and an unreachable instance need different messages.
+ throw Object.assign(
+ new Error(
+ `fetchQueryByHandle failed: ${response.status} ${response.statusText}`,
+ ),
+ { status: response.status },
+ );
+ }
+
+ return response.json();
+}
+
export async function submitMcpFeedback({
instanceUrl,
uiCredential,
diff --git a/frontend/src/metabase/embedding/mcp/api.unit.spec.ts b/frontend/src/metabase/embedding/mcp/api.unit.spec.ts
new file mode 100644
index 00000000000..8f0955378da
--- /dev/null
+++ b/frontend/src/metabase/embedding/mcp/api.unit.spec.ts
@@ -0,0 +1,37 @@
+import fetchMock from "fetch-mock";
+
+import { fetchMcpBootstrap } from "./api";
+
+const INSTANCE_URL = "http://localhost:3000";
+const BOOTSTRAP_URL = `${INSTANCE_URL}/api/embed-mcp/bootstrap`;
+
+const OPTIONS = {
+ instanceUrl: INSTANCE_URL,
+ uiCredential: "credential-1",
+ mcpSessionId: "session-1",
+};
+
+const sentHeader = (name: string) => {
+ const [call] = fetchMock.callHistory.calls();
+ return new Headers(call.options.headers).get(name);
+};
+
+describe("fetchMcpBootstrap", () => {
+ it("authenticates with the UI credential and the MCP session it was minted for", async () => {
+ const body = { user: { id: 1 }, settings: { "site-locale": "en" } };
+ fetchMock.get(BOOTSTRAP_URL, body);
+
+ await expect(fetchMcpBootstrap(OPTIONS)).resolves.toEqual(body);
+
+ expect(sentHeader("x-metabase-mcp-ui-auth")).toBe("credential-1");
+ expect(sentHeader("mcp-session-id")).toBe("session-1");
+ });
+
+ it("carries the status on the error so a rejected credential is not reported as a network failure", async () => {
+ fetchMock.get(BOOTSTRAP_URL, 401);
+
+ await expect(fetchMcpBootstrap(OPTIONS)).rejects.toMatchObject({
+ status: 401,
+ });
+ });
+});
diff --git a/frontend/src/metabase/embedding/mcp/auth/useMcpUiAuth.ts b/frontend/src/metabase/embedding/mcp/auth/useMcpUiAuth.ts
index 7f6a4d6dc22..fb5001ac282 100644
--- a/frontend/src/metabase/embedding/mcp/auth/useMcpUiAuth.ts
+++ b/frontend/src/metabase/embedding/mcp/auth/useMcpUiAuth.ts
@@ -11,7 +11,10 @@ import { installMcpUiCredential, refreshMcpUiAuth } from "./mcpUiAuth";
type UseMcpUiAuthOptions = {
app: App | null;
refreshKey: number;
- onAuthenticated: () => void;
+ onAuthenticated: (auth: {
+ uiCredential: string;
+ mcpSessionId: string;
+ }) => void;
};
export function useMcpUiAuth({
@@ -90,7 +93,12 @@ export function useMcpUiAuth({
setError(null);
authenticatedUntilRef.current = expiresAt;
- onAuthenticated();
+ // Passed through rather than read from state: the consumer resolves a
+ // query handle here, and the state setters above have not committed yet.
+ onAuthenticated({
+ uiCredential: auth.credential,
+ mcpSessionId: auth.sessionId,
+ });
scheduleCredentialExpiry();
scheduleRefresh(UI_CREDENTIAL_REFRESH_INTERVAL_MS);
diff --git a/frontend/src/metabase/embedding/mcp/hooks/useMcpApp.tsx b/frontend/src/metabase/embedding/mcp/hooks/useMcpApp.tsx
index 46c8ed1e654..b3636d700ca 100644
--- a/frontend/src/metabase/embedding/mcp/hooks/useMcpApp.tsx
+++ b/frontend/src/metabase/embedding/mcp/hooks/useMcpApp.tsx
@@ -8,7 +8,12 @@ import {
} from "@modelcontextprotocol/ext-apps/react";
import { useCallback, useEffect, useRef, useState } from "react";
+import { fetchQueryByHandle } from "../api";
import { useMcpUiAuth } from "../auth";
+import {
+ getMcpQueryFetchErrorMessage,
+ getMcpQueryFetchErrorType,
+} from "../utils/getMcpQueryFetchError";
export interface McpAppState {
query: string | null;
@@ -23,15 +28,41 @@ export interface McpAppState {
*/
prompt: string | null;
+ queryError: string | null;
+
hostContext: McpUiHostContext | null;
app: App | null;
}
-type VisualizeQueryToolResult = {
- query?: string;
+/**
+ * What `visualize_query` and `render_drill_through` put in `structuredContent`. The query itself
+ * never rides here — the tools pass a handle and the iframe exchanges it over the callback API, so
+ * the query stays out of the model's context.
+ */
+type VisualizeQueryToolPayload = {
+ query_handle?: string;
prompt?: string;
};
+/** `structuredContent` is untyped on the wire, so narrow it by checking rather than by asserting. */
+function toToolPayload(structuredContent: unknown): VisualizeQueryToolPayload {
+ if (typeof structuredContent !== "object" || structuredContent === null) {
+ return {};
+ }
+
+ // Safe after the guard above: widening a known object to an index signature, so every field
+ // read below still has to prove its own type rather than being asserted into one.
+ const { query_handle: queryHandle, prompt } = structuredContent as Record<
+ string,
+ unknown
+ >;
+
+ return {
+ query_handle: typeof queryHandle === "string" ? queryHandle : undefined,
+ prompt: typeof prompt === "string" ? prompt : undefined,
+ };
+}
+
function applyHostContext(ctx: McpUiHostContext) {
if (ctx.theme) {
applyDocumentTheme(ctx.theme);
@@ -49,10 +80,14 @@ function applyHostContext(ctx: McpUiHostContext) {
export function useMcpApp(): McpAppState {
const [query, setQuery] = useState<string | null>(null);
const [toolResultVersion, setToolResultVersion] = useState(0);
- const pendingToolResultRef = useRef<VisualizeQueryToolResult | null>(null);
+ const pendingToolResultRef = useRef<VisualizeQueryToolPayload | null>(null);
const [prompt, setPrompt] = useState<string | null>(null);
+ const [queryError, setQueryError] = useState<string | null>(null);
const [hostContext, setHostContext] = useState<McpUiHostContext | null>(null);
+ /** The handle whose resolution is still wanted; older ones are discarded. */
+ const pendingQueryHandleRef = useRef<string | null>(null);
+
// `app` is stable across re-renders
const { app } = useApp({
appInfo: { name: "metabase-visualize-query", version: "1.0.0" },
@@ -66,13 +101,10 @@ export function useMcpApp(): McpAppState {
};
app.ontoolresult = (params) => {
- const { query, prompt } =
- // Unjustified type cast. FIXME
- (params.structuredContent as VisualizeQueryToolResult | undefined) ??
- {};
+ const result = toToolPayload(params.structuredContent);
- if (query) {
- pendingToolResultRef.current = { query, prompt };
+ if (result.query_handle) {
+ pendingToolResultRef.current = result;
setToolResultVersion((version) => version + 1);
}
@@ -80,16 +112,64 @@ export function useMcpApp(): McpAppState {
},
});
- const handleAuthenticated = useCallback(() => {
- const toolResult = pendingToolResultRef.current;
+ /**
+ * Runs once the UI credential exists, because resolving a handle needs it.
+ * The credential is refreshed on a timer, so this can fire more than once for
+ * the same payload; resolution is keyed on the handle so a repeat is harmless.
+ */
+ const handleAuthenticated = useCallback(
+ (auth: { uiCredential: string; mcpSessionId: string }) => {
+ const toolResult = pendingToolResultRef.current;
- if (!toolResult?.query) {
- return;
- }
+ if (!toolResult) {
+ return;
+ }
+
+ const { query_handle: queryHandle, prompt } = toolResult;
- setQuery(toolResult.query);
- setPrompt(toolResult.prompt ?? null);
- }, []);
+ // A stale failure left standing would render over a query that has since loaded.
+ setQueryError(null);
+
+ if (!queryHandle) {
+ return;
+ }
+
+ pendingQueryHandleRef.current = queryHandle;
+
+ const { instanceUrl = "" } = window.metabaseConfig ?? {};
+
+ (async () => {
+ try {
+ const resolved = await fetchQueryByHandle({
+ instanceUrl,
+ uiCredential: auth.uiCredential,
+ mcpSessionId: auth.mcpSessionId,
+ queryHandle,
+ });
+
+ // Two resolutions can be in flight at once (a credential refresh
+ // re-runs this). Drop this one if a newer payload has arrived, rather
+ // than overwriting it with older results.
+ if (pendingQueryHandleRef.current !== queryHandle) {
+ return;
+ }
+
+ setQuery(resolved.query);
+ setPrompt(resolved.prompt ?? prompt ?? null);
+ } catch (error) {
+ if (pendingQueryHandleRef.current !== queryHandle) {
+ return;
+ }
+
+ console.error("Error resolving MCP query handle", error);
+ setQueryError(
+ getMcpQueryFetchErrorMessage(getMcpQueryFetchErrorType(error)),
+ );
+ }
+ })();
+ },
+ [],
+ );
const {
uiCredential,
@@ -116,6 +196,7 @@ export function useMcpApp(): McpAppState {
return {
query,
prompt,
+ queryError,
uiCredential,
mcpSessionId,
hostError: authError,
diff --git a/frontend/src/metabase/embedding/mcp/hooks/useMcpApp.unit.spec.tsx b/frontend/src/metabase/embedding/mcp/hooks/useMcpApp.unit.spec.tsx
index d841176d868..65aba627d7f 100644
--- a/frontend/src/metabase/embedding/mcp/hooks/useMcpApp.unit.spec.tsx
+++ b/frontend/src/metabase/embedding/mcp/hooks/useMcpApp.unit.spec.tsx
@@ -19,14 +19,25 @@ interface TestMcpApp {
ontoolresult: (params: McpUiToolResultNotification["params"]) => void;
}
+// `visualize_query` and `render_drill_through` put a handle in `structuredContent` and nothing
+// else, so every fixture here is handle-shaped. The queries below are what the callback API
+// resolves those handles to — see `resolveHandles`.
+const QUERY_HANDLE = "11111111-1111-4111-8111-111111111111";
+const NEXT_QUERY_HANDLE = "22222222-2222-4222-8222-222222222222";
+
const QUERY_RESULT: McpUiToolResultNotification["params"] = {
content: [],
- structuredContent: { query: "encoded-query" },
+ structuredContent: { query_handle: QUERY_HANDLE },
};
const NEXT_QUERY_RESULT: McpUiToolResultNotification["params"] = {
content: [],
- structuredContent: { query: "next-encoded-query" },
+ structuredContent: { query_handle: NEXT_QUERY_HANDLE },
+};
+
+const HANDLE_RESULT: McpUiToolResultNotification["params"] = {
+ content: [],
+ structuredContent: { query_handle: "0f2a1c33-4b5e-4a6f-8c7d-9e0a1b2c3d4e" },
};
const createAuthResult = (
@@ -64,6 +75,24 @@ const setup = (overrides: Partial<TestMcpApp> = {}) => {
return { app, ...renderHook(() => useMcpApp()) };
};
+const mockFetchQueryByHandle = jest.fn();
+
+/** Default callback-API behaviour: each fixture handle resolves to its own query. */
+const resolveHandles = () =>
+ mockFetchQueryByHandle.mockImplementation(
+ ({ queryHandle }: { queryHandle: string }) =>
+ Promise.resolve({
+ query:
+ queryHandle === NEXT_QUERY_HANDLE
+ ? "next-encoded-query"
+ : "encoded-query",
+ }),
+ );
+
+jest.mock("../api", () => ({
+ fetchQueryByHandle: (...args: unknown[]) => mockFetchQueryByHandle(...args),
+}));
+
jest.mock("@modelcontextprotocol/ext-apps/react", () => ({
applyDocumentTheme: jest.fn(),
applyHostFonts: jest.fn(),
@@ -77,6 +106,11 @@ describe("useMcpApp", () => {
jest.restoreAllMocks();
mockUseApp.mockReset();
+ mockFetchQueryByHandle.mockReset();
+ });
+
+ beforeEach(() => {
+ resolveHandles();
});
it("gets auth from the server tool instead of the visualization result", async () => {
@@ -383,4 +417,62 @@ describe("useMcpApp", () => {
expect(result.current.uiCredential).toBe("");
expect(result.current.mcpSessionId).toBe("");
});
+
+ // The v2 tools emit `{query_handle}` and nothing else.
+ describe("v2 query_handle payloads", () => {
+ it("resolves a handle into a query once the credential exists", async () => {
+ mockFetchQueryByHandle.mockResolvedValue({
+ query: "resolved-encoded-query",
+ prompt: "show me orders",
+ });
+
+ const { app, result } = setup({
+ callServerTool: jest.fn().mockResolvedValue(createAuthResult()),
+ getHostCapabilities: jest.fn(() => ({ serverTools: {} })),
+ });
+
+ act(() => {
+ app.ontoolresult(HANDLE_RESULT);
+ });
+
+ await waitFor(() => {
+ expect(result.current.query).toBe("resolved-encoded-query");
+ });
+
+ expect(result.current.prompt).toBe("show me orders");
+ expect(result.current.queryError).toBeNull();
+
+ // Resolved with the credential from this refresh, not from React state,
+ // which has not committed at the time the callback fires.
+ expect(mockFetchQueryByHandle).toHaveBeenCalledWith(
+ expect.objectContaining({
+ queryHandle: "0f2a1c33-4b5e-4a6f-8c7d-9e0a1b2c3d4e",
+ uiCredential: "refreshed-credential",
+ mcpSessionId: "mcp-session-id",
+ }),
+ );
+ });
+
+ it("surfaces an error instead of spinning forever when a handle will not resolve", async () => {
+ mockFetchQueryByHandle.mockRejectedValue(
+ Object.assign(new Error("gone"), { status: 404 }),
+ );
+ jest.spyOn(console, "error").mockImplementation(() => {});
+
+ const { app, result } = setup({
+ callServerTool: jest.fn().mockResolvedValue(createAuthResult()),
+ getHostCapabilities: jest.fn(() => ({ serverTools: {} })),
+ });
+
+ act(() => {
+ app.ontoolresult(HANDLE_RESULT);
+ });
+
+ await waitFor(() => {
+ expect(result.current.queryError).toMatch(/expired/i);
+ });
+
+ expect(result.current.query).toBeNull();
+ });
+ });
});
diff --git a/frontend/src/metabase/embedding/mcp/hooks/useMcpUserAndSettingsFetch.ts b/frontend/src/metabase/embedding/mcp/hooks/useMcpUserAndSettingsFetch.ts
index 68a598ac1c8..65ea94ff56a 100644
--- a/frontend/src/metabase/embedding/mcp/hooks/useMcpUserAndSettingsFetch.ts
+++ b/frontend/src/metabase/embedding/mcp/hooks/useMcpUserAndSettingsFetch.ts
@@ -1,9 +1,12 @@
import { useEffect, useState } from "react";
import type { SdkStore } from "embedding-sdk-bundle/store/types";
-import { refetchCurrentUser } from "metabase/current-user";
-import { refetchSiteSettings } from "metabase/settings";
+import { currentUserApi, loadCurrentUser } from "metabase/current-user";
+import { settingsApi } from "metabase/settings";
+import MetabaseSettings from "metabase/utils/settings";
+import type { User } from "metabase-types/api";
+import { fetchMcpBootstrap } from "../api";
import {
type McpAppsUserAndSettingsFetchErrorType,
getMcpAppsUserAndSettingsFetchErrorMessage,
@@ -13,6 +16,7 @@ import {
interface UseMcpUserAndSettingsFetchOptions {
instanceUrl: string;
uiCredential: string;
+ mcpSessionId: string;
store: SdkStore;
}
@@ -24,15 +28,15 @@ interface UseMcpUserAndSettingsFetchResult {
export function useMcpUserAndSettingsFetch({
instanceUrl,
uiCredential,
+ mcpSessionId,
store,
}: UseMcpUserAndSettingsFetchOptions): UseMcpUserAndSettingsFetchResult {
const [isSettingsReady, setIsSettingsReady] = useState(false);
const [fetchError, setFetchError] = useState<string | null>(null);
- // The OSS no-op initAuth never loads user or settings. Do it ourselves so
- // selectors like getTokenFeature has populated settings.
- // We also no-op the EE auth flow (auth.ts) when in MCP Apps route.
+ // The OSS no-op initAuth never loads user or settings, and we no-op the EE auth
+ // flow (auth.ts) on the MCP Apps route, so the app has to seed them itself.
useEffect(() => {
if (isSettingsReady) {
return;
@@ -48,7 +52,7 @@ export function useMcpUserAndSettingsFetch({
setIsSettingsReady(false);
setFetchError(null);
- if (!uiCredential) {
+ if (!uiCredential || !mcpSessionId) {
return;
}
@@ -57,17 +61,54 @@ export function useMcpUserAndSettingsFetch({
return;
}
- // `unwrap` both so an auth/network failure lands in the catch below
- // instead of silently reporting ready.
- await Promise.all([
- store.dispatch(refetchCurrentUser()).unwrap(),
- store.dispatch(refetchSiteSettings()).unwrap(),
- ]);
+ const { user, settings } = await fetchMcpBootstrap({
+ instanceUrl,
+ uiCredential,
+ mcpSessionId,
+ });
if (!isMounted) {
return;
}
+ // Seed the caches the shared components read from, rather than letting them
+ // fetch `/api/user/current` and `/api/session/properties` on demand: the UI
+ // credential deliberately does not authenticate the general REST API.
+
+ // The cache is typed as the full `User`, but the bootstrap projection is narrower
+ // on purpose — that narrowing is what the endpoint exists for. Fields the iframe
+ // does not render read back as `undefined`; the `metabase/current-user` selectors
+ // all access them optionally, so a component that needs one has to add it to
+ // `McpAppsBootstrapUser` and to `::bootstrap-user` on the server.
+ const currentUser = user as User;
+
+ store.dispatch(
+ currentUserApi.util.upsertQueryData(
+ "getCurrentUser",
+ undefined,
+ currentUser,
+ ),
+ );
+ store.dispatch(
+ settingsApi.util.upsertQueryData(
+ "getSessionProperties",
+ undefined,
+ settings,
+ ),
+ );
+ // Subscribe so RTK doesn't evict the seeded entries — it drops entries with no
+ // subscribers when they are invalidated. Neither call refetches; both are fulfilled.
+ //
+ // That subscription is also the one way this design breaks: an invalidation would
+ // refetch, and both requests fail here — `current-user` 401s, and `session-properties`,
+ // mounted without `+auth`, answers anonymously and silently drops the authenticated
+ // settings. Nothing in the iframe's tree dispatches a mutation today; the first one
+ // added has to reckon with this.
+ store.dispatch(loadCurrentUser());
+ store.dispatch(settingsApi.endpoints.getSessionProperties.initiate());
+ // Consumers outside the store and React tree (i18n, theming, dom helpers).
+ MetabaseSettings.setAll(settings);
+
setIsSettingsReady(true);
} catch (error) {
console.error("Error initializing MCP app", error);
@@ -83,7 +124,7 @@ export function useMcpUserAndSettingsFetch({
return () => {
isMounted = false;
};
- }, [instanceUrl, isSettingsReady, uiCredential, store]);
+ }, [instanceUrl, isSettingsReady, uiCredential, mcpSessionId, store]);
return { isSettingsReady, userAndSettingsFetchError: fetchError };
}
diff --git a/frontend/src/metabase/embedding/mcp/hooks/useMcpUserAndSettingsFetch.unit.spec.ts b/frontend/src/metabase/embedding/mcp/hooks/useMcpUserAndSettingsFetch.unit.spec.ts
index b44cdf71d27..7fd6862df79 100644
--- a/frontend/src/metabase/embedding/mcp/hooks/useMcpUserAndSettingsFetch.unit.spec.ts
+++ b/frontend/src/metabase/embedding/mcp/hooks/useMcpUserAndSettingsFetch.unit.spec.ts
@@ -1,43 +1,151 @@
import { renderHook, waitFor } from "@testing-library/react";
import type { SdkStore } from "embedding-sdk-bundle/store/types";
+import { currentUserApi } from "metabase/current-user";
+import { settingsApi } from "metabase/settings";
+import MetabaseSettings from "metabase/utils/settings";
+import { createMockMcpAppsBootstrapResponse } from "metabase-types/api/mocks";
+
+import { fetchMcpBootstrap } from "../api";
import { useMcpUserAndSettingsFetch } from "./useMcpUserAndSettingsFetch";
+jest.mock("../api", () => ({
+ fetchMcpBootstrap: jest.fn(),
+}));
+
jest.mock("metabase/current-user", () => ({
- refetchCurrentUser: jest.fn(() => ({ type: "refetch-current-user" })),
+ currentUserApi: {
+ util: {
+ upsertQueryData: jest.fn(() => ({ type: "upsert-current-user" })),
+ },
+ },
+ loadCurrentUser: jest.fn(() => ({ type: "load-current-user" })),
}));
jest.mock("metabase/settings", () => ({
- refetchSiteSettings: jest.fn(() => ({ type: "refetch-site-settings" })),
+ settingsApi: {
+ util: {
+ upsertQueryData: jest.fn(() => ({ type: "upsert-session-properties" })),
+ },
+ endpoints: {
+ getSessionProperties: {
+ initiate: jest.fn(() => ({ type: "initiate-session-properties" })),
+ },
+ },
+ },
}));
+jest.mock("metabase/utils/settings", () => ({
+ __esModule: true,
+ default: { setAll: jest.fn() },
+}));
+
+// The real payload rather than a stand-in, so the assertions pin the seeded cache to the
+// endpoint's actual projection.
+const BOOTSTRAP = createMockMcpAppsBootstrapResponse();
+
+const OPTIONS = {
+ instanceUrl: "http://localhost:3000",
+ uiCredential: "credential-1",
+ mcpSessionId: "session-1",
+};
+
+const setup = () => {
+ const dispatch = jest.fn();
+ // The hook only uses dispatch
+ const store = { dispatch } as unknown as SdkStore;
+
+ const { result, rerender } = renderHook(
+ (props: { uiCredential: string }) =>
+ useMcpUserAndSettingsFetch({ ...OPTIONS, ...props, store }),
+ { initialProps: { uiCredential: OPTIONS.uiCredential } },
+ );
+
+ return { dispatch, result, rerender };
+};
+
describe("useMcpUserAndSettingsFetch", () => {
- it("keeps settings ready state even when the ui credential changes", async () => {
- const unwrap = jest.fn().mockResolvedValue(undefined);
- const dispatch = jest.fn(() => ({ unwrap }));
-
- // The hook only uses dispatch
- const store = { dispatch } as unknown as SdkStore;
-
- const { result, rerender } = renderHook(
- ({ uiCredential }) =>
- useMcpUserAndSettingsFetch({
- instanceUrl: "http://localhost:3000",
- store,
- uiCredential,
- }),
- { initialProps: { uiCredential: "credential-1" } },
+ beforeEach(() => {
+ jest.mocked(fetchMcpBootstrap).mockResolvedValue(BOOTSTRAP);
+ });
+
+ afterEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it("seeds the user and settings caches from the MCP bootstrap endpoint", async () => {
+ const { dispatch, result } = setup();
+
+ await waitFor(() => {
+ expect(result.current.isSettingsReady).toBe(true);
+ });
+
+ expect(fetchMcpBootstrap).toHaveBeenCalledWith(OPTIONS);
+ expect(dispatch.mock.calls.flat()).toEqual([
+ { type: "upsert-current-user" },
+ { type: "upsert-session-properties" },
+ { type: "load-current-user" },
+ { type: "initiate-session-properties" },
+ ]);
+ });
+
+ it("seeds the caches with the bootstrap payload verbatim, narrow user projection included", async () => {
+ const { result } = setup();
+
+ await waitFor(() => {
+ expect(result.current.isSettingsReady).toBe(true);
+ });
+
+ expect(currentUserApi.util.upsertQueryData).toHaveBeenCalledWith(
+ "getCurrentUser",
+ undefined,
+ BOOTSTRAP.user,
+ );
+ expect(settingsApi.util.upsertQueryData).toHaveBeenCalledWith(
+ "getSessionProperties",
+ undefined,
+ BOOTSTRAP.settings,
);
+ });
+
+ it("publishes the settings to consumers that live outside the store", async () => {
+ const { result } = setup();
await waitFor(() => {
expect(result.current.isSettingsReady).toBe(true);
});
- expect(dispatch).toHaveBeenCalledTimes(2);
+ expect(MetabaseSettings.setAll).toHaveBeenCalledWith(BOOTSTRAP.settings);
+ });
+
+ it("keeps settings ready state even when the ui credential changes", async () => {
+ const { dispatch, result, rerender } = setup();
+
+ await waitFor(() => {
+ expect(result.current.isSettingsReady).toBe(true);
+ });
rerender({ uiCredential: "credential-2" });
+
expect(result.current.isSettingsReady).toBe(true);
- expect(dispatch).toHaveBeenCalledTimes(2);
+ expect(fetchMcpBootstrap).toHaveBeenCalledTimes(1);
+ expect(dispatch).toHaveBeenCalledTimes(4);
+ });
+
+ it("reports a rejected credential as an auth failure", async () => {
+ jest
+ .mocked(fetchMcpBootstrap)
+ .mockRejectedValue(Object.assign(new Error("nope"), { status: 401 }));
+ jest.spyOn(console, "error").mockImplementation(() => {});
+
+ const { result } = setup();
+
+ await waitFor(() => {
+ expect(result.current.userAndSettingsFetchError).toMatch(
+ /Authentication failed/,
+ );
+ });
+ expect(result.current.isSettingsReady).toBe(false);
});
});
diff --git a/frontend/src/metabase/embedding/mcp/utils/captureDefaultDisplay.ts b/frontend/src/metabase/embedding/mcp/utils/captureDefaultDisplay.ts
index 8db61617fca..a3c01258ef2 100644
--- a/frontend/src/metabase/embedding/mcp/utils/captureDefaultDisplay.ts
+++ b/frontend/src/metabase/embedding/mcp/utils/captureDefaultDisplay.ts
@@ -50,7 +50,7 @@ export function captureDefaultDisplay({
// Ad-hoc questions in MCP Apps initializes as `table`.
// Replace that placeholder when default display actually loads.
- // see `getMcpDeserializedCard` in `embedding/mcp/McpUiAppRoute.utils.ts`
+ // see `getMcpDeserializedQuery` in `embedding/mcp/McpUiAppRoute.utils.ts`
const shouldReplaceTablePlaceholder =
previousDefaultDisplay === "table" && currentDisplay !== "table";
diff --git a/frontend/src/metabase/embedding/mcp/utils/getMcpAppsUserAndSettingsFetchError.ts b/frontend/src/metabase/embedding/mcp/utils/getMcpAppsUserAndSettingsFetchError.ts
index 385935ef086..4e4f36e5b05 100644
--- a/frontend/src/metabase/embedding/mcp/utils/getMcpAppsUserAndSettingsFetchError.ts
+++ b/frontend/src/metabase/embedding/mcp/utils/getMcpAppsUserAndSettingsFetchError.ts
@@ -12,7 +12,11 @@ export function getMcpAppsUserAndSettingsFetchErrorType(
return "network";
}
- if ("status" in error && error.status === 401) {
+ // 401: the credential was rejected. 404: it was minted for an MCP session that has
+ // since expired or does not match the one the iframe is holding. Both are fixed by
+ // asking the client to render the visualization again. A 403 means MCP is switched
+ // off instance-wide, which the "network" message covers.
+ if ("status" in error && (error.status === 401 || error.status === 404)) {
return "auth";
}
diff --git a/frontend/src/metabase/embedding/mcp/utils/getMcpAppsUserAndSettingsFetchError.unit.spec.ts b/frontend/src/metabase/embedding/mcp/utils/getMcpAppsUserAndSettingsFetchError.unit.spec.ts
index c3ee9c68db5..62e846c08df 100644
--- a/frontend/src/metabase/embedding/mcp/utils/getMcpAppsUserAndSettingsFetchError.unit.spec.ts
+++ b/frontend/src/metabase/embedding/mcp/utils/getMcpAppsUserAndSettingsFetchError.unit.spec.ts
@@ -10,6 +10,24 @@ describe("getMcpAppsUserAndSettingsFetchErrorType", () => {
).toBe("auth");
});
+ it("returns auth when the bootstrap session is expired or mismatched", () => {
+ expect(
+ getMcpAppsUserAndSettingsFetchErrorType({
+ status: 404,
+ data: "Invalid or expired session",
+ }),
+ ).toBe("auth");
+ });
+
+ it("returns network when MCP is disabled instance-wide", () => {
+ expect(
+ getMcpAppsUserAndSettingsFetchErrorType({
+ status: 403,
+ data: "MCP server is not enabled.",
+ }),
+ ).toBe("network");
+ });
+
it("returns network for non-auth current user or settings API errors", () => {
expect(
getMcpAppsUserAndSettingsFetchErrorType({
diff --git a/frontend/src/metabase/embedding/mcp/utils/getMcpQueryFetchError.ts b/frontend/src/metabase/embedding/mcp/utils/getMcpQueryFetchError.ts
new file mode 100644
index 00000000000..f96737a1e73
--- /dev/null
+++ b/frontend/src/metabase/embedding/mcp/utils/getMcpQueryFetchError.ts
@@ -0,0 +1,47 @@
+/* eslint-disable metabase/no-literal-metabase-strings */
+
+import { match } from "ts-pattern";
+import { t } from "ttag";
+
+export type McpQueryFetchErrorType = "auth" | "expired" | "network";
+
+export function getMcpQueryFetchErrorType(
+ error: unknown,
+): McpQueryFetchErrorType {
+ if (!error || typeof error !== "object" || !("status" in error)) {
+ return "network";
+ }
+
+ if (error.status === 401 || error.status === 403) {
+ return "auth";
+ }
+
+ // The handle store is user-scoped and reaped, so a 404 is an expired handle
+ // rather than a missing endpoint.
+ if (error.status === 404) {
+ return "expired";
+ }
+
+ return "network";
+}
+
+export const getMcpQueryFetchErrorMessage = (
+ type: McpQueryFetchErrorType,
+): string =>
+ match(type)
+ .with(
+ "auth",
+ () =>
+ t`Authentication failed. Try signing out and signing back in, then ask your MCP client to show this again.`,
+ )
+ .with(
+ "expired",
+ () =>
+ t`This visualization has expired. Ask your MCP client to run the query again.`,
+ )
+ .with(
+ "network",
+ () =>
+ t`Could not load this visualization. Make sure Metabase is reachable, then ask your MCP client to show this again.`,
+ )
+ .exhaustive();
diff --git a/frontend/src/metabase/embedding/mcp/utils/getMcpQueryFetchError.unit.spec.ts b/frontend/src/metabase/embedding/mcp/utils/getMcpQueryFetchError.unit.spec.ts
new file mode 100644
index 00000000000..302844bffb5
--- /dev/null
+++ b/frontend/src/metabase/embedding/mcp/utils/getMcpQueryFetchError.unit.spec.ts
@@ -0,0 +1,22 @@
+import { getMcpQueryFetchErrorType } from "./getMcpQueryFetchError";
+
+describe("getMcpQueryFetchErrorType (GHY-4157)", () => {
+ it("returns expired for a handle the store no longer has", () => {
+ expect(getMcpQueryFetchErrorType({ status: 404 })).toBe("expired");
+ });
+
+ it("returns auth for a reaped or mismatched embedding session", () => {
+ expect(getMcpQueryFetchErrorType({ status: 401 })).toBe("auth");
+ expect(getMcpQueryFetchErrorType({ status: 403 })).toBe("auth");
+ });
+
+ it("returns network for server errors", () => {
+ expect(getMcpQueryFetchErrorType({ status: 500 })).toBe("network");
+ });
+
+ it("returns network for unreadable CORS or network failures", () => {
+ expect(getMcpQueryFetchErrorType(new TypeError("Failed to fetch"))).toBe(
+ "network",
+ );
+ });
+});
diff --git a/mage/src/mage/modules.clj b/mage/src/mage/modules.clj
index 179d0875b2d..2dcd27274c3 100644
--- a/mage/src/mage/modules.clj
+++ b/mage/src/mage/modules.clj
@@ -138,6 +138,7 @@
sso.auth-identity
auth-provider
batch-processing
+ bookmarks
channel
util.classloader
collections
diff --git a/resources/mcp/v2/skills/dashboard-filters/SKILL.md b/resources/mcp/v2/skills/dashboard-filters/SKILL.md
new file mode 100644
index 00000000000..53ba2725d8d
--- /dev/null
+++ b/resources/mcp/v2/skills/dashboard-filters/SKILL.md
@@ -0,0 +1,75 @@
+---
+name: dashboard-filters
+description: Dashboard parameters via dashboard_write — add_parameter types and value sources, the wire_parameter target grammar (target_field vs target_tag vs raw target), autowire, linked filters, inline parameters, tab visibility. Read before your first add_parameter or wire_parameter. Triggers — "add a filter to this dashboard", "wire a filter to these cards", "make a filter cascade", "filter dropdown values", "why isn't my filter showing / doing anything".
+---
+
+# Dashboard filters
+
+A filter is **a parameter plus a wire per card**: `add_parameter` creates the widget, and it filters nothing until `wire_parameter` connects it to a card — the most common "my filter does nothing" cause. Both are `dashboard_write` ops in one atomic call:
+
+```
+dashboard_write {"method": "update", "id": 40,
+ "ops": [{"op": "add_parameter", "parameter_id": "category", "name": "Category",
+ "type": "string/=", "sectionId": "string"},
+ {"op": "wire_parameter", "parameter_id": "category", "dashcard_id": 7,
+ "target_field": 18, "autowire": true}]}
+```
+
+`parameter_id` is a short slug you choose and reuse in later ops; the server derives the URL slug from `name`. `get_content` on the dashboard lists each parameter's id, type, and wired dashcard ids.
+
+## Parameter types
+
+`type`, closed vocabulary: `string/=` `string/!=` `string/contains` `string/does-not-contain` `string/starts-with` `string/ends-with`; `number/=` `number/!=` `number/between` `number/>=` `number/<=`; `date/all-options` (fullest) `date/single` `date/range` `date/relative` `date/month-year` `date/quarter-year`; `category`, `id`, `boolean/=`, `temporal-unit`, `location/city|state|zip_code|country`. `sectionId` groups the widget in the editor: `"string"`, `"number"`, `"date"`, `"id"`, `"location"`, `"temporal-unit"`.
+
+Other `add_parameter`/`update_parameter` fields: `default` (scalar, or array for multi-select), `required` (only with a `default` — without one viewers are blocked until they pick), `isMultiSelect`, `temporal_units` (for `temporal-unit`), `values_query_type` (`"list"` dropdown / `"search"` box / `"none"` free text), `values_source_type` + `values_source_config`, `filteringParameters`. To unset a default or link, name it in `clear` (`"clear": ["default", "filteringParameters"]`) — a null reads as omitted.
+
+## Wire targets
+
+| Situation | Pass |
+|---|---|
+| Card exposes the column (MBQL card, or a native field-filter tag bound to that field) | `target_field: <field id>` — the usual choice; the server derives the mapping from the card's query |
+| Native-SQL card, by tag name | `target_tag: "<tag name>"` — the server reads the tag's type (field filter vs variable) and emits the right mapping. Read tag names from the card's `template_tags` via `get_content`; a wrong name's error lists what exists |
+| `{{placeholder}}` in a text, heading, or iframe card's own content | `target: ["text-tag", "<name>"]` — the name must appear as `{{name}}` in that card |
+| Neither fits (advanced) | `target: ["dimension", ["template-tag", "category"]]` — the raw clause; hand-built targets are where wiring bugs live |
+
+`autowire: true` (with `target_field`) also maps every other card exposing the same field, silently skipping those that don't; the named `dashcard_id` must expose it or the op fails. A target resolving to nothing on the card is rejected at compile time, on `validate_only` and real saves alike.
+
+`unwire_parameter` disconnects one card (`dashcard_id`) or all (omit it). `remove_parameter` deletes the widget plus its mappings and linked-filter references.
+
+## Value sources
+
+Omit `values_source_type` for live distinct values from the wired column — usually right. Or:
+
+- Fixed list: `"values_source_type": "static-list", "values_source_config": {"values": ["active", "churned", "trial"]}`
+- From a card: `"values_source_type": "card", "values_source_config": {"card_id": 42, "value_field": ["field", 18, null]}`
+
+Preview: `get_parameter_values {"target": "dashboard", "id": 40, "parameter_id": "category"}` — also takes `query` (search) and `constraints` (other filters' selections, chain filtering).
+
+## Linked (cascading) filters
+
+A child (City) shows only values consistent with a parent (State) when the child's `filteringParameters` lists the parent's id:
+
+```
+{"op": "update_parameter", "parameter_id": "city", "filteringParameters": ["state"]}
+```
+
+Two hard constraints: linked filters read **table-metadata foreign keys only** — joins inside a saved question or model don't count; and a linked child is **incompatible with a `static-list` or `card` source** (a custom source overrides the cascade) — leave it live.
+
+## Placement and visibility
+
+- Parameters live in the header. `move_parameter` with `index` reorders; with `dashcard_id` it renders the widget **on that card** (inline). `add_card`'s `inline_parameters` does this at add time.
+- **Tabs:** a header filter appears on a tab only where it is wired to a card on *that* tab — a filter that "won't show" is usually wired only to another tab's cards.
+- A `temporal-unit` parameter binds only to a datetime column in the card query's **last** stage — after a time-bucketed summary it can't attach.
+
+## Don't
+
+- Don't add a parameter without wiring it — the widget renders and filters nothing.
+- Don't set `required: true` without a `default` — viewers are blocked until they pick a value.
+- Don't link a child filter that has a static-list/card source, or across a question/model join — the cascade silently doesn't apply.
+- Don't pass null to clear a default or link — it reads as omitted; use `clear`.
+- Don't hand-build a raw `target` when `target_field` or `target_tag` fits.
+- Don't report a default or link as set from the write response — read it back.
+
+## To confirm
+
+`get_content {"type": "dashboard", "id": 40, "include": ["parameters"]}` — the write response is a skeleton without `default`, `filteringParameters`, or value-source config; read them back before reporting a default or link as set. Dropdown contents: `get_parameter_values`.
diff --git a/resources/mcp/v2/skills/dashboard-layout/SKILL.md b/resources/mcp/v2/skills/dashboard-layout/SKILL.md
new file mode 100644
index 00000000000..c5afeff060f
--- /dev/null
+++ b/resources/mcp/v2/skills/dashboard-layout/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: dashboard-layout
+description: Dashboard layout with dashboard_write ops — the 24-column grid, per-display default sizes, explicit position vs autoplace, the KPI-row pattern, headings and text cards, tabs and the every-card-needs-a-tab rule. Triggers — "build a dashboard from these cards", "the dashboard is squished into half the width", "arrange the cards", "add a tab", "make a KPI row".
+---
+
+# Dashboard layout
+
+Ordered `dashboard_write` ops apply as one atomic save — batch a whole rearrangement in one `ops` list. New dashcards and tabs get **negative ids you choose** (`-1, -2, …`), referenced by later ops in the same call; the server assigns real ids on save. `validate_only: true` returns the resulting layout without writing.
+
+## The grid is 24 columns — not 12
+
+A dashcard is `{row, col, size_x, size_y}`: `col` 0-indexed, `row` grows downward, `col + size_x ≤ 24`. **Full width is `size_x: 24`.** A layout authored on a 12-column assumption crams everything into the left half — if no card crosses column 12, double every width.
+
+Omit `position` to autoplace (below/beside existing cards) and `size` for the display's default — right when appending a card or two. Compose whole layouts with explicit `position` + `size`; place a band wholly explicitly or let it all autoplace, never mixed. Sanity-check: rows fill to 24, at least one card ends at `col + size_x = 24`.
+
+Default sizes (w×h): `scalar`/`smartscalar` 6×3 · `pie` 12×8 · `table`/`pivot` 12×9 · `waterfall` 14×6 · `sankey` 16×10 · `iframe` 12×8 · `heading` 24×1 · `text` 12×3 · `link` 8×1 · `action` 4×1 · other charts 12×6.
+
+## The standard shape: KPI row, chart halves, full-width table
+
+```
+dashboard_write {"method": "create", "name": "Revenue overview",
+ "ops": [
+ {"op": "add_heading", "id": -1, "text": "Key numbers", "position": {"row": 0, "col": 0}},
+ {"op": "add_card", "id": -2, "card_id": 101, "position": {"row": 1, "col": 0}, "size": {"size_x": 6, "size_y": 3}},
+ {"op": "add_card", "id": -3, "card_id": 102, "position": {"row": 1, "col": 6}, "size": {"size_x": 6, "size_y": 3}},
+ {"op": "add_card", "id": -4, "card_id": 103, "position": {"row": 1, "col": 12}, "size": {"size_x": 6, "size_y": 3}},
+ {"op": "add_card", "id": -5, "card_id": 104, "position": {"row": 1, "col": 18}, "size": {"size_x": 6, "size_y": 3}},
+ {"op": "add_card", "id": -6, "card_id": 105, "position": {"row": 4, "col": 0}, "size": {"size_x": 12, "size_y": 6}},
+ {"op": "add_card", "id": -7, "card_id": 106, "position": {"row": 4, "col": 12}, "size": {"size_x": 12, "size_y": 6}},
+ {"op": "add_card", "id": -8, "card_id": 107, "position": {"row": 10, "col": 0}, "size": {"size_x": 24, "size_y": 9}}]}
+```
+
+## Structure and prose
+
+- `add_heading` — full-width section label (plain text, 24×1); one per band.
+- `add_text` — markdown card for explanations and captions.
+- `add_link` (URL or Metabase entity), `add_iframe` — external content.
+- `add_action` — button running a saved action (`action_id`; optional `label`, `display`: `"button"`/`"form"`).
+- `duplicate_card` copies a dashcard with its settings; `replace_card` swaps the card behind a slot, keeping the slot.
+
+## Editing an existing layout
+
+`move` (new `position` and/or `tab`), `resize` (`size`), `remove`, addressed by dashcard id from `get_content`. Layout keys never ride `patch_dashcard` (content merges only) — `move`/`resize`/`replace_card`/`set_series` own row, col, size, tab, card_id, series.
+
+## Tabs
+
+```
+"ops": [{"op": "add_tab", "id": -1, "name": "Overview"},
+ {"op": "add_tab", "id": -2, "name": "Details"},
+ {"op": "add_card", "id": -3, "card_id": 101, "tab": -1},
+ {"op": "move", "dashcard_id": 7, "tab": -2}]
+```
+
+- Existing cards are adopted automatically only when the save ends with exactly **one** tab; adding two or more in one call leaves them orphaned — `move` them onto a tab in the same call.
+- **With more than one tab, every card must have a tab** (`tab` on each add op, or `move`); the save rejects orphans by id.
+- `rename_tab`, `move_tab` (reorder), `duplicate_tab` (copies the tab and its cards), `remove_tab` (deletes its cards too).
+- A header filter appears on a tab only where it is wired to a card on that tab — `learn("dashboard-filters")`.
+
+## Don't
+
+- Don't author 12-column widths — the dashboard fills half the screen, with no error.
+- Don't mix explicit positions and autoplace within one band — the band misaligns.
+- Don't spread a rearrangement over several calls — each autoplaces against a half-built layout.
+
+## To confirm
+
+`get_content {"type": "dashboard", "id": 40, "include": ["layout"]}` returns every dashcard's tab, position, and size — check bands fill to 24 and every card has a tab. `validate_only: true` previews the same without saving.
diff --git a/resources/mcp/v2/skills/documents/SKILL.md b/resources/mcp/v2/skills/documents/SKILL.md
new file mode 100644
index 00000000000..808c6fdd6bc
--- /dev/null
+++ b/resources/mcp/v2/skills/documents/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: documents
+description: The Metabase-flavored Markdown grammar for document_write — the CommonMark subset, {% card %} embeds, {% entity %} links, ::: layout containers (flex / supporting / resize) and nesting rules, surgical `edits` and their limits, card clones, comments. Triggers — "create a document / report", "put prose beside a chart", "embed a question in a document", "edit a document", "document comments".
+---
+
+# Documents
+
+A document is a rich-text page mixing prose with embedded saved questions. `document_write` takes **Metabase-flavored Markdown**: CommonMark plus tokens. Charts must exist first (`question_write`), embedded by id.
+
+```
+document_write {"method": "create", "name": "Weekly report",
+ "content_markdown": "# Weekly report\n\nOrders trended up this week.\n\n{% card id=118 %}\n"}
+```
+
+**CommonMark subset:** headings, paragraphs, bold/italic/inline code, links (bare URLs autolink), lists, blockquotes, fenced code, horizontal rules, images. **No tables, strikethrough, or task lists** — the editor has no nodes for them; show tabular data by embedding a table-display question.
+
+## Tokens
+
+- **Card embed** (block, own line): `{% card id=118 %}` or `{% card id=118 name="Revenue by region" %}` (`name` overrides the title). The id must be a saved question you can read; an unresolvable id fails the write. Height is assigned for you.
+- **Entity link** (inline chip): `{% entity id="42" model="dashboard" %}` — id quoted; `model` ∈ `card`, `dataset`, `metric`, `dashboard`, `collection`, `table`, `database`, `document` (`user` parses but renders without a working link).
+
+## Layout containers (`:::` fences)
+
+`::: <name> {attrs}` on its own line opens a container; a bare `:::` closes the **innermost** open one (never `::: end`) — every opener needs its own closer, in order.
+
+- `::: flex {columns=[60,40]}` — a row of 1–3 cells (percent widths); a cell is a card embed or a `::: supporting` block. Never nest `flex` in `flex`.
+- `::: supporting` — a prose cell (paragraphs, headings, lists) inside a flex row.
+- `::: resize {height=442 minHeight=280}` — wraps exactly one card embed or flex row to pin its pixel height.
+
+Prose beside a chart:
+
+```markdown
+::: flex {columns=[60,40]}
+::: supporting
+### What happened
+Revenue climbed through the quarter, led by the Gadget category.
+:::
+{% card id=118 %}
+:::
+```
+
+(First `:::` closes `supporting`, last closes `flex`.) To pin the row's height, wrap it in `::: resize {height=400}` … `:::`.
+
+## Card clones
+
+A card the document doesn't already own is **cloned into it** on write and its id rewritten in the stored body — the markdown stored is not the markdown you sent, so always take the returned `content_markdown` as current, and edit against that, never your own earlier text. The clone is what renders: to change an embedded chart (display, settings, query), `question_write` the **clone id** shown in `content_markdown`; the master card does nothing for the document. E.g. you embedded 148, the body now reads `{% card id=155 %}` — `question_write {"method": "update", "id": 155, "display": "row"}` changes the document, updating 148 does not.
+
+## Updating
+
+Pass `id` and exactly **one** of:
+
+- `edits: [{old_str, new_str, replace_all?}]` — the default. Each `old_str` must match the **current server-side** markdown exactly once: 0 matches = the document changed since you read it (copy from the returned `content_markdown`); >1 = extend the snippet or set `replace_all: true`. Blocks keep their ids, so comment anchors survive.
+- `content_markdown` — full rewrite; every block is re-created, so **every comment thread on the body is orphaned** (listed in the response's `orphaned_comment_threads`). Only for restructuring; tell the user first.
+- `edits: []` — metadata only (`name`, `collection_id`, `collection_position`, `archived`), body untouched.
+
+Writes are last-write-wins; a stale `old_str` failing to match is the only staleness signal.
+
+**What `edits` can do:** `new_str` is plain text, stored literally — `**bold**`, `` `code` ``, `- item`, `## Heading`, fences, and `{% card %}` inside it appear as those characters, not formatting. A blank line (`\n\n`) does split a paragraph. So edits cover rewording any paragraph, heading, or list item, and adding a plain paragraph; a new heading, bullet, code block, embed, or container needs `content_markdown`.
+
+Add a paragraph — extend the end of the block before it:
+
+```
+"edits": [{"old_str": "led by the Gadget category.",
+ "new_str": "led by the Gadget category.\n\nGizmos were flat for the third quarter running."}]
+```
+
+Edit one bullet — match its text only, never the `- ` marker (a marker in `new_str` is escaped and merges two items into one):
+
+```
+"edits": [{"old_str": "Churn fell to 4%", "new_str": "Churn fell to 3.8%"}]
+```
+
+## Comments
+
+`get_content {"type": "document", "id": 12, "include": ["comments"]}` returns threads grouped by anchored block, each with `anchor: {start, end, text}` — the exact character slice of the returned `content_markdown` — and `thread` messages (`id`, `creator`, `text`, `is_resolved`, `created_at`). A thread whose block was rewritten or deleted appears under `orphaned_comments`: the discussion still exists but points at no text, and only the UI can re-anchor it. MCP can read comments but not reply, resolve, or re-anchor — tell the user when a thread needs that.
+
+## Don't
+
+- Don't `question_write` the master card to change an embedded chart — a no-op for the document; edit the clone id.
+- Don't put Markdown in `new_str` expecting formatting — stored as literal characters, no error.
+- Don't include the `- ` marker in a bullet edit — it merges two items into one.
+- Don't full-rewrite for a small change — every comment thread is orphaned, irreversibly.
+- Don't write tables, strikethrough, or task lists — no document representation.
+
+## To confirm
+
+`get_content {"type": "document", "id": 12}` returns the stored `content_markdown` (clone ids included); add `"include": ["layout"]` for the block outline, `["comments"]` for anchors. Rendering in the editor has no API check.
diff --git a/resources/mcp/v2/skills/native-parameters/SKILL.md b/resources/mcp/v2/skills/native-parameters/SKILL.md
new file mode 100644
index 00000000000..b4632a4e632
--- /dev/null
+++ b/resources/mcp/v2/skills/native-parameters/SKILL.md
@@ -0,0 +1,97 @@
+---
+name: native-parameters
+description: Template tags for native SQL questions written through question_write's `native` — tag kinds, field-filter vs raw-variable, the template_tags shape, widget types, [[ ]] optional blocks, wiring tags to dashboards. Read before first passing template_tags. Triggers — "add a filter widget to my SQL", "parameterize this query", "field filter", "why does my variable return no rows", "wire a dashboard filter to a SQL card".
+---
+
+# Native SQL parameters (template tags)
+
+Prefer MBQL (`execute_query` + `question_write` `query`, validated server-side). Use `native` only for what MBQL can't express (engine-specific functions, CTEs, window functions) or when the user asks for SQL: a raw-SQL card can't take a dashboard filter until that filter is a template tag, while an MBQL card wires as-is.
+
+```
+question_write {"method": "create", "name": "Orders by status",
+ "native": {"database_id": 1,
+ "sql": "SELECT status, count(*) FROM orders WHERE {{category}} AND total > {{min_total}} GROUP BY status",
+ "template_tags": {
+ "category": {"type": "dimension", "field_id": 18, "widget_type": "string/=", "display_name": "Category"},
+ "min_total": {"type": "number", "display_name": "Minimum total", "default": 0}}}}
+```
+
+Every `{{name}}` in the SQL is a tag. The server extracts them; `template_tags` configures them, keyed by the exact case-sensitive name — naming a tag absent from the SQL is an error. Never supply tag ids (the server mints them). Unconfigured tags are plain text variables.
+
+## Field filter vs raw variable
+
+Default to a **field filter** (`"type": "dimension"`) whenever the tag filters a real table column.
+
+- **Field filter** — binds a column (`field_id`), gets a smart widget (`widget_type`: dropdown, date picker). Write it **bare**, `WHERE {{category}}`; Metabase expands it (`category IN (...)`, `BETWEEN` for dates). `WHERE category = {{category}}` breaks the expansion — the most common native bug.
+- **Raw variable** (`text` | `number` | `date` | `boolean`) — literal splice, you write the operator: `WHERE total > {{min_total}}`, `LIMIT {{n}}`. Plain input box.
+- A field filter needs a real, connected column — not an expression, aggregate, or subquery/CTE column (use a raw variable) — and **the real table name: never alias the filtered table**. The expansion emits `orders.status`; under `FROM orders o` that name is out of scope and the card errors at run time, on dashboards too. Keep `FROM orders`, or qualify `FROM public.orders`.
+
+```sql
+SELECT count(*) FROM orders WHERE {{status}} -- works
+SELECT count(*) FROM orders o WHERE {{status}} -- fails: orders.status is hidden by the alias
+```
+
+- **Empty values** — a field filter with no value compiles to `1 = 1`; a raw variable with no value outside `[[ ]]` fails with "missing required parameters" even without `required`. Give every main-clause raw variable a `default` or wrap its clause in `[[ ]]`. A boolean's `default: false` reads as no default: pass it on every run, or use `[[ ]]`.
+- **`temporal-unit`** tag (`field_id` of a datetime column) — the viewer picks the bucket (day/week/month).
+
+## Tag shape
+
+```
+"tag_name": {"type": "dimension" | "temporal-unit" | "text" | "number" | "date" | "boolean",
+ "field_id": <numeric id or 21-char entity_id>, // required for dimension / temporal-unit
+ "widget_type": "string/=", // required for dimension
+ "display_name": "Label", // optional
+ "required": true, // optional; blocks the run until a value is given
+ "default": "Gadget"} // optional
+```
+
+Field ids: `browse_data {"action": "get_fields", "table_ids": [<table id>]}`. `widget_type` by column type:
+
+| Column type | widget_type |
+|---|---|
+| Text | `string/=` `string/!=` `string/contains` `string/does-not-contain` `string/starts-with` `string/ends-with` `category` |
+| Number | `number/=` `number/!=` `number/between` `number/>=` `number/<=` |
+| Date/datetime | `date/all-options` (fullest picker) `date/single` `date/range` `date/relative` `date/month-year` `date/quarter-year` |
+| Boolean | `boolean/=` |
+| PK/FK | `id` |
+| Location semantic type | `location/city` `location/state` `location/zip_code` `location/country` |
+
+Round-trip: `get_content` returns `template_tags` in the stored shape (`display-name`, `widget-type`, a `dimension` ref); `question_write` accepts it back verbatim. Don't author that shape or hand-mint ids — `field_id` is the write dialect.
+
+## Optional blocks `[[ ... ]]`
+
+Wrap any clause that should drop when its value is empty, keyword included: `WHERE true [[AND {{category}}]] [[AND total > {{min_total}}]]`. One nesting level; several optional `AND` blocks need a real `WHERE` first. A `required` tag or one with a `default` always has a value, so its clause never drops. `[[ ]]` doesn't fix a case/type mismatch: `WHERE plan = {{p}}` returns zero rows on a case-sensitive engine when the value's case is off.
+
+## Snippet and card references
+
+- `{{#42}}` (or `{{#42-slug}}`) inlines card 42 as a subquery: `SELECT * FROM {{#42}}`, `WITH x AS {{#42}} …`. It runs with its own saved defaults; its parameters can't be set from the parent.
+- Its columns are the card's result columns. MBQL aggregations get machine names (`count`, `avg`, then `avg_2`) that collide with SQL keywords — quote them: `SELECT cs."avg", cs."count" FROM {{#42}} cs`. Run the card once to see the exact names.
+- `{{snippet: Name}}` splices an existing shared snippet (find via `search` or `get_content` type `snippet`).
+- Neither takes a value or wires to a dashboard parameter; nothing to configure in `template_tags` (entries `get_content` returns for them round-trip and are ignored).
+
+## Running and wiring
+
+**Run** — `run_saved_question` takes `{id | slug, value}` pairs (from `get_content`'s `parameters`); an equality field filter takes an array even for one value:
+
+```
+run_saved_question {"id": 522, "parameters": [{"slug": "category", "value": ["Gadget"]},
+ {"slug": "min_total", "value": 100}]}
+```
+
+Date values use Metabase's date grammar, never a SQL fragment: `"2026-01-05"`, `"2026-01-01~2026-03-31"`, `"2026-01"`, `"past30days"`, `"thisyear"`.
+
+**Wire** — `wire_parameter` with `target_tag`; the server derives the mapping from the tag type, so field filters and variables wire identically. The parameter `type` must fit the tag's widget_type (same vocabulary). Dashboard side: `learn("dashboard-filters")`.
+
+```
+dashboard_write {"method": "update", "id": 40,
+ "ops": [{"op": "add_parameter", "parameter_id": "category", "name": "Category", "type": "string/=", "sectionId": "string"},
+ {"op": "wire_parameter", "parameter_id": "category", "dashcard_id": 7, "target_tag": "category"}]}
+```
+
+**Ad hoc** — `execute_sql` binds `{{tag}}` values via `template_tag_values` as prepared-statement parameters: plain variables only; field filters exist only on saved questions. Single read statement — no DDL or `;`-chains.
+
+## Don't
+
+- Don't wrap a field filter in an operator, alias its table, or bind it to a non-column.
+- Don't omit `widget_type` on a dimension tag or `field_id` on a dimension/temporal-unit tag.
+- Don't leave a main-clause raw variable without a `default` or `[[ ]]`; don't trust `default: false`.
diff --git a/resources/mcp/v2/skills/query-dialect/SKILL.md b/resources/mcp/v2/skills/query-dialect/SKILL.md
new file mode 100644
index 00000000000..d46243e98c7
--- /dev/null
+++ b/resources/mcp/v2/skills/query-dialect/SKILL.md
@@ -0,0 +1,135 @@
+---
+name: query-dialect
+description: The query dialect execute_query and question_write's `query` accept — numeric table/field ids, clause shape, filters, aggregation, breakouts, joins, expressions, multi-stage queries, saved-card sources. Read before authoring any non-trivial query, or on a shape / unknown-id rejection. Triggers — "write an MBQL query", "aggregate and group by", "join two tables", "filter then re-aggregate", "month-over-month", "query a saved question or model".
+---
+
+# The query dialect
+
+**MBQL or SQL?** MBQL (`execute_query`) for anything that will sit on a filtered dashboard, anything with a date/category/FK filter, every plain aggregate, breakout, or join — MBQL cards wire to dashboard filters as-is; a raw-SQL card must be rewritten with template tags first. SQL (`execute_sql`) for window functions, CTEs, set operations, engine-specific functions, or when the user asks for SQL. Unsure: start in MBQL — the server validates it and names what didn't resolve.
+
+Everything — tables, columns, saved questions, models, metrics, measures, segments — is named by **numeric id**, copied from `browse_data` (`list_tables`, `get_fields`), `search`, or `get_content`; never invented. A wrong name errors loudly; a wrong id that exists resolves to the wrong column *silently*. `get_content`'s `definition` include returns this same shape, so a read definition can be edited and sent back.
+
+Loop: author → `execute_query` `validate_only: true` (shape + ids, mints a `query_handle`, runs nothing) → execute → `question_write` with that `query_handle` (saves exactly what ran).
+
+## Shape
+
+`{"lib/type": "mbql/query", "database": <db id>, "stages": [...]}`. `execute_query` infers `database` from the first stage; `question_write`'s inline `query` requires it — include it.
+
+```json
+{"lib/type": "mbql/query",
+ "database": 1,
+ "stages": [{"lib/type": "mbql.stage/mbql",
+ "source-table": 5,
+ "aggregation": [["count", {}]],
+ "breakout": [["field", {"temporal-unit": "month"}, 42]]}]}
+```
+
+- First stage only: `source-table` (table id) **or** `source-card` (card id), exactly one; later stages read the previous stage's output.
+- Optional stage keys: `filters`, `aggregation`, `breakout`, `expressions`, `fields`, `joins`, `order-by`, `limit`.
+
+## Two rules
+
+1. **Every clause is `["op", {}, ...args]`** — options map at position 1 even when empty: `["count", {}]`, never `["count"]`. (Repaired server-side, but write it so your query matches later reads.) Never put a stage key (`aggregation`, `filters`, …) at a clause head — clauses go inside those arrays.
+2. **A field ref is `["field", {}, <numeric id>]`.** In a later stage, reference a previous stage's column by its **machine name**: `["field", {}, "count"]`. An aggregation's output name is the bare function (`count`, `sum`, `avg`; a second `sum` is `sum_2`) unless its options set `"name"`; a breakout keeps the field's machine name even when bucketed. Never a display label ("Max of Total").
+
+Field options: `temporal-unit` (`"day"`, `"week"`, `"month"`, `"quarter"`, `"year"`, …), `binning` (`{"strategy": "num-bins", "num-bins": 10}` for histograms), `join-alias` (required on every explicitly-joined ref), `source-field` (implicit-FK disambiguation, a field id). Don't breakout the same field twice in one stage (bucketed and raw).
+
+## Filters, aggregation, order-by
+
+`filters` entries are ANDed; nest `["or", {}, …]` for OR.
+
+```json
+"filters": [[">", {}, ["field", {}, 40], 100],
+ ["=", {}, ["field", {}, 61], "Gadget"]],
+"aggregation": [["sum", {"name": "revenue"}, ["field", {}, 40]]],
+"order-by": [["desc", {}, ["aggregation", {}, 0]]]
+```
+
+- `order-by`: `["asc"|"desc", {}, ref]`. A same-stage aggregation is `["aggregation", {}, <0-based index>]` — **never** `["field", {}, "count"]` in the stage that computes it (validates, then fails or misresolves at execution); name refs to aggregations are for the next stage.
+- `HAVING` (filter on an aggregation) goes in a next stage, by output name (below).
+- Relative dates: `["time-interval", {}, <field>, -30, "day"]`, `["time-interval", {}, <field>, "current", "month"]`. An explicit year or date range is an **absolute** `between`, not relative.
+- Multi-value: `["in", {}, <field>, "a", "b"]` / `["not-in", …]`.
+- Date arithmetic: `["datetime-diff", {}, a, b, "day"]`, never `-`.
+- Full catalog: `learn("query-dialect", "operators")`.
+
+## Expressions
+
+```json
+"expressions": {"Subtotal": ["+", {}, ["field", {}, 40], ["field", {}, 44]]},
+"aggregation": [["sum", {}, ["expression", {}, "Subtotal"]]]
+```
+
+## Joins
+
+**Implicit FK join** — reference the related table's field directly; with exactly one FK path the server fills in the join (`browse_data` `get_fields` marks FK columns and targets — check before assuming a column lives on the current table):
+
+```json
+{"lib/type": "mbql.stage/mbql",
+ "source-table": 5,
+ "aggregation": [["count", {}]],
+ "breakout": [["field", {}, 61]]}
+```
+
+Ambiguous FK → add `{"source-field": <FK field id on the source table>}` to the ref. No FK path → explicit join:
+
+```json
+"joins": [{"alias": "Products",
+ "strategy": "left-join",
+ "stages": [{"lib/type": "mbql.stage/mbql", "source-table": 8}],
+ "conditions": [["=", {},
+ ["field", {}, 43],
+ ["field", {"join-alias": "Products"}, 60]]]}],
+"breakout": [["field", {"join-alias": "Products"}, 61]]
+```
+
+`strategy`: `left-join` (default) / `right-join` / `inner-join` / `full-join`. **Every** joined-column ref carries `{"join-alias": "<alias>"}`, in conditions and downstream. Conditions accept only `=`, `!=`, `<`, `<=`, `>`, `>=`.
+
+## Multi-stage
+
+Filter on an aggregation's result in the next stage, by output name:
+
+```json
+"stages": [
+ {"lib/type": "mbql.stage/mbql",
+ "source-table": 5,
+ "aggregation": [["count", {}]],
+ "breakout": [["field", {}, 43]]},
+ {"lib/type": "mbql.stage/mbql",
+ "filters": [[">", {}, ["field", {}, "count"], 10]],
+ "order-by": [["desc", {}, ["field", {}, "count"]]]}
+]
+```
+
+Window: `offset` sits in `aggregation` and reads another breakout row — month-over-month is `["offset", {"name": "prev_month"}, ["sum", {}, <field>], -1]` against a monthly breakout.
+
+## Saved questions and models as sources
+
+`source-card` takes the card's numeric id — never `card__<id>`, URI refs, or entity_ids — and its columns go by output name. The card must be in the same database as the rest of the query. Never fall back to native `{{#id}}` SQL.
+
+```json
+{"lib/type": "mbql/query",
+ "database": 1,
+ "stages": [{"lib/type": "mbql.stage/mbql",
+ "source-card": 137,
+ "filters": [[">", {}, ["field", {}, "total"], 100]],
+ "limit": 50}]}
+```
+
+## Metrics, measures, segments
+
+By numeric id, on a stage whose `source-table` is their base table: metric `"aggregation": [["metric", {}, 42]]`; measure `"aggregation": [["measure", {}, 7]]`; segment `"filters": [["segment", {}, 3]]`. `browse_data` `get_fields` lists each table's with ids. To compose on top of one, `get_content` `include: ["definition"]` returns its clauses in this dialect to inline and extend.
+
+A metric's or measure's output column is named for the aggregation inside its definition (`sum`, `count`, `avg`), not for the metric or measure — set `"name"` in its options slot (`["measure", {"name": "revenue"}, 7]`) to name it for a later stage.
+
+## Translating the request
+
+- "only / where / for X" is a **filter**; "by / per / for each / over time" is a **breakout**.
+- Apply every stated constraint; add no analysis the user didn't ask for.
+
+## Don't
+
+- Don't guess ids — a wrong id that exists resolves to the wrong column with no error.
+- Don't order by a same-stage aggregation by name (`["field", {}, "count"]`) — `["aggregation", {}, <index>]`; name refs are for the next stage.
+- Don't omit the `{}` options slot — the server repairs it, so your query stops matching later reads.
+- Don't reference a previous stage's column by display label ("Max of Total") — machine name only.
+- Don't turn "only / where X" into a breakout, or drop a stated constraint once the aggregation is in place.
diff --git a/resources/mcp/v2/skills/query-dialect/references/operators.md b/resources/mcp/v2/skills/query-dialect/references/operators.md
new file mode 100644
index 00000000000..97f963b433e
--- /dev/null
+++ b/resources/mcp/v2/skills/query-dialect/references/operators.md
@@ -0,0 +1,106 @@
+# Operator catalog
+
+Every operator for `execute_query` / `question_write` queries; structure rules (options at position 1, numeric-id refs) are in the skill body. `<field>` abbreviates `["field", {}, <numeric field id>]` (or a string-name ref against a previous stage).
+
+## Filters
+
+Boolean:
+- `["and", {}, <pred>, <pred>, ...]` / `["or", {}, <pred>, <pred>, ...]` — min 2 args.
+- `["not", {}, <pred>]`
+
+Equality / membership (variadic):
+- `["=", {}, <a>, <b>, ...]` / `["!=", {}, <a>, <b>, ...]`
+- `["in", {}, <expr>, <v1>, <v2>, ...]` / `["not-in", …]` — canonical for multi-value categorical filters.
+
+Comparison:
+- `["<", {}, <a>, <b>]` / `["<=", …]` / `[">", …]` / `[">=", …]`
+- `["between", {}, <expr>, <min>, <max>]` — inclusive.
+- `["inside", {}, <lat-expr>, <lon-expr>, <lat-max>, <lon-min>, <lat-min>, <lon-max>]` — geographic bounding box.
+
+Null / empty:
+- `["is-null", {}, <expr>]` / `["not-null", {}, <expr>]`
+- `["is-empty", {}, <expr>]` / `["not-empty", {}, <expr>]` — NULL-or-`""` for strings.
+
+String match (options may carry `{"case-sensitive": false}`):
+- `["contains", {}, <str>, <substring>]` / `["does-not-contain", …]`
+- `["starts-with", {}, <str>, <prefix>]` / `["ends-with", {}, <str>, <suffix>]`
+
+Temporal:
+- `["time-interval", {}, <temporal>, <n | "current" | "last" | "next">, "<unit>"]` — relative window; options may set `{"include-current": true}`.
+- `["during", {}, <temporal>, "<iso-date-or-datetime>", "<unit>"]` — value within the bucket containing the literal.
+- `["relative-time-interval", {}, <temporal>, <value>, "<bucket>", <offset-value>, "<offset-bucket>"]` — window offset from now.
+- Absolute ranges: `["between", {}, <temporal>, "2024-01-01", "2024-12-31"]`.
+
+Named reference:
+- `["segment", {}, <numeric segment id>]` — a saved segment; its table must be the stage's source.
+
+## Aggregations
+
+- `["count", {}]` — all rows; optional 3rd slot `<expr>` counts non-NULL.
+- `["sum", {}, <num>]` / `["avg", {}, <num>]` / `["min", {}, <orderable>]` / `["max", {}, <orderable>]`
+- `["median", {}, <num>]` / `["percentile", {}, <num>, <0..1>]`
+- `["distinct", {}, <expr>]` — count of distinct values.
+- `["cum-count", {}]` / `["cum-sum", {}, <num>]` — running totals.
+- `["stddev", {}, <num>]` / `["var", {}, <num>]`
+- `["count-where", {}, <bool-pred>]` / `["sum-where", {}, <num>, <bool-pred>]` / `["distinct-where", {}, <expr>, <bool-pred>]`
+- `["share", {}, <bool-pred>]` — fraction of rows where the predicate holds, 0–1.
+- `["metric", {}, <numeric card id>]` / `["measure", {}, <numeric measure id>]` — saved definitions; base table must be the stage's source.
+- `["offset", {}, <expr>, <n>]` — window function: the value `<n>` rows back (negative) or ahead. Valid **only** inside `aggregation` or `order-by`, never in `expressions` or a filter.
+
+Name the output in options — `["sum", {"name": "revenue", "display-name": "Revenue"}, <field>]`; later stages and visualization settings reference that `name`.
+
+## Order-by
+
+- `["asc", {}, <ref>]` / `["desc", {}, <ref>]` — wraps a field ref or `["aggregation", {}, <0-based index>]`.
+
+## Expressions
+
+Arithmetic / math:
+- `["+", {}, <a>, <b>, ...]` / `["-", …]` / `["*", …]` / `["/", …]` (division always returns float)
+- `["abs", {}, <num>]`, `["ceil", …]`, `["floor", …]`, `["round", …]`
+- `["power", {}, <base>, <exp>]`, `["sqrt", {}, <num>]`, `["exp", …]`, `["log", …]`
+- `["integer", {}, <num-or-str>]` / `["float", {}, <str>]` / `["text", {}, <expr>]`
+
+String:
+- `["concat", {}, <a>, <b>, ...]`
+- `["substring", {}, <str>, <start (1-based)>, <length?>]`
+- `["replace", {}, <str>, <find>, <replacement>]`
+- `["regex-match-first", {}, <str>, <regex>]`
+- `["split-part", {}, <str>, <delimiter>, <position>]`
+- `["length", {}, <str>]`, `["trim", …]`, `["ltrim", …]`, `["rtrim", …]`, `["upper", …]`, `["lower", …]`
+- `["host", {}, <url>]`, `["domain", …]`, `["subdomain", …]`, `["path", …]`
+- `["month-name", {}, <int>]`, `["quarter-name", {}, <int>]`, `["day-name", {}, <int>]`
+
+Conditional:
+- `["case", {}, [[<pred1>, <val1>], [<pred2>, <val2>], ...], <default?>]` — alias `if`.
+- `["coalesce", {}, <a>, <b>, ...]` — first non-null.
+
+Temporal:
+- `["datetime-add", {}, <temporal>, <n>, "<unit>"]` / `["datetime-subtract", …]`
+- `["datetime-diff", {}, <left>, <right>, "<unit>"]` — unit ∈ `second minute hour day week month quarter year`; the only supported date subtraction.
+- `["interval", {}, <n>, "<unit>"]`
+- `["get-year", {}, <t>]`, `["get-quarter", …]`, `["get-month", …]`, `["get-day", …]`, `["get-hour", …]`, `["get-minute", …]`, `["get-second", …]`
+- `["get-week", {}, <t>, "<mode?>"]` / `["get-day-of-week", {}, <t>, "<mode?>"]` — mode `"iso"` / `"us"` / `"instance"`.
+- `["temporal-extract", {}, <t>, "<unit>"]`
+- `["convert-timezone", {}, <t>, "<target-tz>", "<source-tz?>"]`
+- `["relative-datetime", {}, <n>, "<unit>"]` (or `["relative-datetime", {}, "current"]`) / `["absolute-datetime", {}, "<iso>", "<unit?>"]`
+- `["date", {}, <expr>]` / `["datetime", {}, <expr>]` / `["time", {}, <expr>]`
+- `["now", {}]` / `["today", {}]`
+
+Extracted quarter/month/week values are **numbers** (`1`–`4` for quarters), never strings like `"Q1"`.
+
+## Field options
+
+Temporal bucketing — `{"temporal-unit": "..."}` on a field ref:
+- Truncation: `day`, `week`, `month`, `quarter`, `year`, plus `minute`, `hour`, `second`, `millisecond` for times.
+- Extraction (integer-returning): `day-of-week`, `day-of-month`, `day-of-year`, `week-of-year`, `month-of-year`, `quarter-of-year`, `year-of-era`, `hour-of-day`, `minute-of-hour`, `second-of-minute`.
+- `default` — let the system pick.
+
+Binning — `{"binning": {...}}` on a numeric/coordinate field ref in a breakout:
+- `{"strategy": "num-bins", "num-bins": 10}` — fixed count of equal-width bins.
+- `{"strategy": "bin-width", "bin-width": 5}` — fixed width.
+- `{"strategy": "default"}` — Metabase chooses.
+
+## Canonical spellings
+
+Near-misses are auto-corrected, but write the canonical name so later reads match: `count-where` (not `count-if`), `var` (not `variance`), `stddev` (not `stddev-pop`), `distinct` (not `count-distinct`), `get-day-of-week` (not `dayofweek`), `get-hour`/`get-month`/`get-quarter` (not `hour-of-day` etc. as operators), `datetime-diff` (not `temporal-diff`), `relative-datetime` (not `relative-date`). Clause heads are lowercase and hyphenated, never underscored or camelCase.
diff --git a/resources/mcp/v2/skills/transforms/SKILL.md b/resources/mcp/v2/skills/transforms/SKILL.md
new file mode 100644
index 00000000000..30bce3d2405
--- /dev/null
+++ b/resources/mcp/v2/skills/transforms/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: transforms
+description: Authoring transforms with transform_write — the query source (definition vs query_handle), the target table and what patching it renames, why the target database is never yours to choose, the two shapes the tool refuses (python, incremental), tags and folders. Read before your first transform_write. Triggers — "make a transform", "materialize this query into a table", "build a table other questions can query", "rename a transform's output table", "why won't it let me edit this transform".
+---
+
+# Transforms
+
+A transform is a saved query Metabase **runs to materialize its results into a real warehouse table**, which questions, other transforms, and anything reaching the database then query like any table. (A model is resolved at read time; a transform is a table that exists between runs.)
+
+```
+transform_write {"method": "create", "name": "Daily revenue",
+ "query_handle": "qh_…",
+ "target": {"name": "daily_revenue", "schema": "analytics"}}
+```
+
+## Query source — exactly one of `query_handle` | `definition`
+
+Preferred: author and run with `execute_query` (or `execute_sql` for native — fine here), then pass the returned `query_handle`; it saves exactly what ran. The alternative, inline `definition`, is the transform's **source map**, not a bare query — the shape `get_content`'s `"definition"` include returns, so read-modify-write round-trips; the inner query is the `execute_query` dialect (`learn("query-dialect")`), numeric ids:
+
+```
+"definition": {"type": "query", "query": {"lib/type": "mbql/query", "stages": [...]}}
+```
+
+A bare query in `definition` is the common miss (older transforms stored it that way) and a teaching error.
+
+## Target table
+
+`target` is `{name, schema?}` — the table the transform writes, **recreated in full on every run**.
+
+- `schema` is required on databases that have schemas.
+- On update `target` is **patched, not replaced**: passing only `name` renames the output table and keeps the schema — the supported rename.
+- A new transform whose target table **already exists is refused** — it creates its table, never adopts one. Pick another name or schema.
+- Never set `target.database`: the target follows the database the query reads; naming another is an error.
+- `target.type` is always `"table"`; incremental types are configured in Metabase.
+
+## Refused, not degraded
+
+Two shapes are rejected outright, because rewriting them would silently change how the transform loads: **Python transforms** (an update that would rewrite one is refused) and **incremental loading** — checkpoint (`definition.source-incremental-strategy`) and append/merge (`target.target-incremental-strategy`). Configure those in Metabase; the *query* of an incremental transform is still editable here as long as those keys stay out.
+
+`transform_write` only authors: no run (saving doesn't execute), no archive, no delete (transforms have no trash — remove in Metabase). `get_content` on a transform reports source type, target, and latest run.
+
+## Folders, tags, permissions
+
+- `collection_id` files it in a transform folder; omit for the top of the transforms tree.
+- Transform folders are their own hierarchy — make one with `collection_write(method: "create", namespace: "transforms")`, and browse them with `browse_collection(namespace: "transforms")`.
+- `tag_ids` — **jobs select transforms by tag**, so tags are how a transform gets scheduled. Replaced wholesale: pass the full set, or `[]` to clear.
+- Needs transforms permission on the source database plus the transforms feature, enforced exactly as the REST API and UI enforce them.
+
+## Don't
+
+- Don't expect saving to run the transform — nothing executes until a job does.
+- Don't pass a partial `tag_ids` — the list is replaced wholesale and the rest are dropped.
+- Don't pass a partial `target` expecting a replacement — it is patched, so the old schema stays.
+- Don't rely on rows surviving between runs — the table is recreated in full each time.
diff --git a/resources/mcp/v2/skills/visualization-settings/SKILL.md b/resources/mcp/v2/skills/visualization-settings/SKILL.md
new file mode 100644
index 00000000000..42866995027
--- /dev/null
+++ b/resources/mcp/v2/skills/visualization-settings/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: visualization-settings
+description: Choosing a card's `display` and authoring `visualization_settings` for question_write and patch_dashcard — which chart fits which data shape, the output-column-name rule, minimum keys per chart family, map regions, the column_settings JSON-string-key footgun. Triggers — "make this a bar/line/pie chart", "what chart should I use", "format as currency", "the card renders as a table instead of a chart", "conditional formatting", "region map".
+---
+
+# Visualization: pick the chart, then set it
+
+Two fields, set through `question_write` and mergeable per dashcard via `dashboard_write`'s `patch_dashcard`:
+
+- **`display`** — `table`, `bar`, `line`, `area`, `row`, `pie`, `scalar`, `smartscalar`, `combo`, `pivot`, `funnel`, `map`, `scatter`, `waterfall`, `progress`, `gauge`, `sankey`. Nothing else: an unknown value (`bargraph`, `histogram`, `number`) is accepted and renders nothing; `scalar` **is** the Number viz.
+- **`visualization_settings`** — a map keyed per display (`graph.*`, `pie.*`, `table.*`, …). **Nothing validates it**: unknown or wrong-display keys are stored and ignored; a wrong binding renders blank or falls back to a table. Feedback is read-back, not errors.
+
+## Step 1 — display by data shape
+
+- **Single number** → `scalar`; `smartscalar` for change vs previous period (needs a time breakout); `gauge`/`progress` for value vs target.
+- **Measure across categories** → `bar`; `row` (horizontal) for long or many labels.
+- **Trend** → `line`; `area` for stacked composition over time; `combo` for two related measures on unlike scales (never unrelated ones). Never `scalar`/`pie` for a trend.
+- **Part-to-whole** → `pie`, ≤5 slices only; beyond that a sorted `bar`/`row`.
+- **Distribution** → `bar` histogram (bin the field — `learn("query-dialect")`, binning).
+- **Correlation** → `scatter` (third measure → bubble size).
+- **Contributions to a total** → `waterfall`; **stage drop-off** → `funnel`; **flow between nodes** → `sankey`.
+- **Geographic** → `map` (region/choropleth, or pin/grid from lat+long).
+- **Precise values, many columns, nothing fits** → `table`; `pivot` for a two-dimension cross-tab.
+
+## Step 2 — bind output columns
+
+**Every binding key takes output column-name strings, never field ids** — the names the query produces: a `count` aggregation is `count`, a breakout its field's name, a named aggregation its `name` option, a second `sum` in a stage `sum_2`. Empty `{}` is valid for a simple aggregate (auto-bound); set keys to pin or override:
+
+```json
+{"display": "bar",
+ "visualization_settings": {"graph.dimensions": ["CATEGORY"], "graph.metrics": ["count"]}}
+```
+
+- `bar`/`line`/`area`/`combo`/`row`/`scatter`: `graph.dimensions` (x; a 2nd entry = series breakout), `graph.metrics` (y). Stacked: `"stackable.stack_type": "stacked"` (`"normalized"` = 100%).
+- `pie`: `{"pie.dimension": "CATEGORY", "pie.metric": "count"}`
+- `scalar`: `{"scalar.field": "count"}` (only with >1 column)
+- `funnel`: `{"funnel.dimension": "STAGE", "funnel.metric": "count"}`
+- `map` region: `{"map.type": "region", "map.region": "us_states", "map.dimension": "STATE", "map.metric": "count"}`. `map.region`: `"us_states"` (dimension values = 2-letter state codes or state names, `"CA"`/`"California"`), `"world_countries"` (2-letter ISO codes or country names, `"US"`/`"United States"`), or an admin-added custom-GeoJSON key. Pin/grid: `"map.type": "pin"` + `map.latitude_column` + `map.longitude_column`.
+- `sankey`: `{"sankey.source": "FROM", "sankey.target": "TO", "sankey.value": "count"}`
+- `waterfall`: exactly one dimension + one metric.
+- `table`: always renders; `table.columns` (`[{"name": …, "enabled": …}]`) orders and hides columns.
+
+## `column_settings`: JSON-string keys
+
+Per-column formatting keys are **JSON-encoded arrays passed as strings**, inner quotes escaped — never an object key:
+
+```json
+"visualization_settings": {
+ "column_settings": {
+ "[\"name\",\"TOTAL\"]": {"number_style": "currency", "currency": "USD", "decimals": 2},
+ "[\"name\",\"CREATED_AT\"]": {"date_style": "MMMM D, YYYY"}}}
+```
+
+Always author `["name", "<output column>"]`. A `["ref", ["field", id, opts]]` key appears in read-back — don't author it; when editing such a card keep those keys verbatim.
+
+## Escape hatch and catalog
+
+For anything intricate — combo charts, conditional formatting, pivot splits, click behavior — read a UI-built card with the look you want (`get_content {"items": [{"type": "question", "id": <id>}], "include": ["visualization_settings"]}`) and reuse its `visualization_settings` verbatim; the server produced it, so it's valid for that display. Every key with values and defaults, `series_settings`, conditional formatting, pivot splits, dashcard click behavior: `learn("visualization-settings", "settings")`.
+
+## Don't
+
+- Don't invent display values — accepted, renders nothing.
+- Don't put field ids in `graph.dimensions` / `pie.metric` / `scalar.field` — output column names only, or the chart renders blank.
+- Don't write a `column_settings` key as an object, or author the `["ref", …]` form — ignored.
+- Don't pick `pie` for >5 slices, `combo` for unrelated metrics, or `scalar`/`pie` for a trend — renders, misleads.
+- Don't report a chart as rendering from the write response — its `visualization_settings` echo is what got stored, not proof anything draws.
+
+## To confirm
+
+`get_content {"items": [{"type": "question", "id": <id>}], "include": ["visualization_settings"]}` returns `visualization_settings` as stored (alongside `display`, which every question read carries) — proof the settings saved, not that the chart renders. `question_write` also echoes `visualization_settings` in its response, so a write you just made needs no second call. `fields: ["visualization_settings"]` reads the blob alone; a card with nothing stored returns `{}`. Rendering (a region whose values don't match, a binding to a missing column) has no API check: call it unverified unless the user has viewed the card.
diff --git a/resources/mcp/v2/skills/visualization-settings/references/settings.md b/resources/mcp/v2/skills/visualization-settings/references/settings.md
new file mode 100644
index 00000000000..effde96d97c
--- /dev/null
+++ b/resources/mcp/v2/skills/visualization-settings/references/settings.md
@@ -0,0 +1,153 @@
+# visualization_settings — per-chart key reference
+
+Authorable keys per `display`, the data shape each chart suits, and the minimum to render. Set keys only to override defaults — empty `{}` works for a simple aggregate. Column-naming keys take **output column-name strings**; `column_settings` keys are escaped JSON strings: `"[\"name\",\"TOTAL\"]"`.
+
+Saved-card settings ride `question_write`'s `visualization_settings`; dashcard overrides and everything marked *dashcards only* merge in via `dashboard_write`'s `patch_dashcard`, whose `visualization_settings` patch merges key by key.
+
+## Cartesian — `bar`, `line`, `area`, `combo`, `scatter`, `waterfall`, `row`
+
+`bar`/`line`/`area`/`combo` share one key set (combo defaults the first series to a line, the rest to bars). Most allow up to 2 dimensions and unlimited metrics; **waterfall is 1 dimension + 1 metric**.
+
+Data binding:
+
+| Key | Type | Notes |
+|---|---|---|
+| `graph.dimensions` | string[] | X-axis. Index 0 = x-axis; a 2nd entry = series breakout. |
+| `graph.metrics` | string[] | Y-axis metric column(s). |
+| `graph.series_order` | object[] | Per-series order/visibility `{key, name, color, enabled}` (breakout only). |
+
+Stacking: `stackable.stack_type` — `null`, `"stacked"`, `"normalized"` (100%; incompatible with a `log` y-scale).
+
+Goal & trend: `graph.show_goal` (bool), `graph.goal_value` (number), `graph.goal_label` (string), `graph.show_trendline` (bool).
+
+Data labels: `graph.show_values` (bool), `graph.label_value_frequency` (`"fit"`/`"all"`), `graph.show_stack_values` (`"total"`/`"series"`/`"all"`, stacked bars), `graph.label_value_formatting` (`"auto"`/`"compact"`/`"full"`).
+
+Axes: `graph.x_axis.scale` (`"timeseries"` `"linear"` `"pow"` `"log"` `"histogram"` `"ordinal"`), `graph.y_axis.scale` (`"linear"` `"pow"` `"log"`), `graph.x_axis.axis_enabled` (`true`/`false`/`"compact"`/`"rotate-45"`/`"rotate-90"`), `graph.y_axis.axis_enabled` (bool), `graph.y_axis.auto_range` (bool) with `graph.y_axis.min`/`.max`, `graph.y_axis.unpin_from_zero` (bool), `graph.y_axis.auto_split` (bool), `graph.x_axis.title_text` / `graph.y_axis.title_text`.
+
+Tooltip: `graph.tooltip_columns` (string[] — extra columns on hover).
+
+Extras: `scatter.bubble` (numeric column name → bubble size). Waterfall: `waterfall.increase_color`, `waterfall.decrease_color`, `waterfall.show_total` (bool), `waterfall.total_color`. Row charts: `graph.dimensions` is the y-axis (categories), x-scale `"ordinal"` only.
+
+## Part-to-whole & single value
+
+**pie** — required `pie.dimension` (string, or array for up to 3 concentric rings), `pie.metric`. Optional: `pie.show_legend`, `pie.show_total`, `pie.show_labels`, `pie.percent_visibility` (`"off"`/`"legend"`/`"inside"`/`"both"`), `pie.decimal_places`, `pie.slice_threshold` (min % before grouping into "Other", default 2.5).
+
+**funnel** — required `funnel.dimension` (stage), `funnel.metric` (value). Optional: `funnel.type` (`"funnel"`/`"bar"`), `funnel.rows` (`[{key, name, enabled}]` step order).
+
+**gauge** — `gauge.segments`: `[{min, max, color?, label?}]` (min/max required per segment).
+
+**progress** — `progress.value` (column, only if >1 numeric), `progress.goal` (number or column name), `progress.color`.
+
+**scalar** — `scalar.field` (only if >1 column), `scalar.segments` (`[{min, max, color, label}]` thresholds). Number formatting is per-column in `column_settings`, not here.
+
+**smartscalar** — needs one value grouped by a single time field. `scalar.field`, `scalar.switch_positive_negative`, `scalar.compact_primary_number`, and `scalar.comparisons` (up to 3): `{id, type}` with type `"previousPeriod"` | `"previousValue"` | `"periodsAgo"` (+`value`) | `"staticNumber"` (+`value`,`label`) | `"anotherColumn"` (+`column`,`label`).
+
+## Tabular, geographic & flow
+
+**table** — always renders. `table.columns` (`[{name, enabled}]` order + visibility), `table.column_formatting` (below), `table.pivot` (bool; in-table pivot of 2 dims + 1 metric) with `table.pivot_column`/`table.cell_column`, `table.pagination`, `table.row_index`, `table.freeze_columns` + `table.freeze_columns_count`, `table.freeze_rows` + `table.freeze_rows_count`.
+
+Conditional formatting — `table.column_formatting` is a list of rules:
+
+```json
+[{"columns": ["TOTAL"], "type": "single", "operator": ">", "value": 100,
+ "color": "#84BB4C", "highlight_row": false},
+ {"columns": ["RATING"], "type": "range", "colors": ["#ED6E6E", "#F9CF48", "#84BB4C"],
+ "min_type": "custom", "min_value": 1, "max_type": "custom", "max_value": 5}]
+```
+
+`single` operators: `=` `!=` `<` `>` `<=` `>=` `is-null` `not-null` `contains` `does-not-contain` `starts-with` `ends-with` `is-true` `is-false`. `range` `min_type`/`max_type`: `"custom"`, `"all"`, or null.
+
+**pivot** — needs an aggregated query built in the query builder (not native). `pivot_table.column_split`: `{"rows": [...names], "columns": [...names], "values": [...names]}`; `pivot.show_row_totals`, `pivot.show_column_totals`, `pivot.condense_duplicate_totals` (bools); `pivot_table.column_formatting` (as table's). Per-column under `column_settings`: `pivot_table.column_sort_order` (`"ascending"`/`"descending"`), `pivot_table.column_show_totals` (bool).
+
+**map** — `map.type`: `"region"` (choropleth), `"pin"`, `"grid"`. Region: `map.region` (`"us_states"`, `"world_countries"`, or a custom-geojson key), `map.dimension`, `map.metric`, `map.colors`. Pin/grid: `map.latitude_column`, `map.longitude_column`, `map.metric_column`, `map.pin_type` (`"tiles"`/`"markers"`/`"grid"`/`"heat"`), `map.heat.radius`/`.blur`/`.min-opacity`/`.max-zoom`.
+
+**sankey** — `sankey.source`, `sankey.target`, `sankey.value` (column names; distinct source/target, acyclic, ≤150 nodes); `sankey.node_align` (`"left"`/`"right"`/`"justify"`), `sankey.show_edge_labels` (bool), `sankey.label_value_formatting` (`"auto"`/`"compact"`/`"full"`), `sankey.edge_color` (`"gray"`/`"source"`/`"target"`).
+
+## `column_settings` — per-column formatting
+
+Keyed by the JSON-string form of `["name", "<output column>"]`. Applies to table, pie, cartesian charts, and scalar.
+
+| Key | Values | Applies to |
+|---|---|---|
+| `column_title` | string — header override | all |
+| `text_align` | `"left"` `"right"` `"middle"` | table |
+| `view_as` | null (text), `"link"`, `"email_link"`, `"image"`, `"auto"` | table |
+| `link_text` / `link_url` | strings; `{{COLUMN}}` interpolates row values | table |
+| `show_mini_bar` | bool — inline bar in the cell | number |
+| `text_wrapping` | bool | string |
+| `number_style` | `"decimal"` `"currency"` `"percent"` `"scientific"` | number |
+| `currency` / `currency_style` / `currency_in_header` | ISO code; `"symbol"` `"narrowSymbol"` `"code"` `"name"`; bool | currency |
+| `number_separators` | `".,"` `", "` `",."` `"."` `".’"` | number |
+| `decimals` / `scale` / `prefix` / `suffix` | number, multiply factor, affixes | number |
+| `date_style` | moment.js format, e.g. `"MMMM D, YYYY"` | date |
+| `date_separator` / `date_abbreviate` | `"/"` `"-"` `"."`; bool | date |
+| `time_enabled` / `time_style` | null `"minutes"` `"seconds"` `"milliseconds"`; e.g. `"h:mm A"` | date+time |
+| `click_behavior` | object — **dashcards only** (below) | all |
+
+## `series_settings` — per-series styling (cartesian)
+
+Keyed by series name: the metric column's name (single series) or the breakout value (broken-out).
+
+| Key | Values |
+|---|---|
+| `title` | series label |
+| `color` | hex color |
+| `display` | `"line"` `"area"` `"bar"` — per-series type (combo) |
+| `line.interpolate` | `"linear"` `"cardinal"` `"step-after"` |
+| `line.style` / `line.size` | `"solid"` `"dashed"` `"dotted"`; `"S"` `"M"` `"L"` |
+| `line.marker_enabled` | null (auto) / bool |
+| `line.missing` | `"zero"` `"none"` `"interpolate"` |
+| `axis` | null (auto) / `"left"` / `"right"` |
+| `show_series_values` / `show_series_trendline` | bool |
+
+```json
+"series_settings": {"revenue": {"display": "line", "color": "#509EE3", "axis": "left"}}
+```
+
+## Click behavior — dashcards only
+
+Lives on a **dashcard** via `patch_dashcard` — whole-card at top-level `visualization_settings.click_behavior`, or per column under `column_settings[<key>].click_behavior` — never on a saved card. `type`: `"actionMenu"` (default drill menu), `"crossfilter"` (clicked value feeds a dashboard parameter), `"link"`. Keys are camelCase. A native-SQL card supports only crossfilter and link (no drill-through).
+
+Crossfilter — the driver chart emits the value; wire the same parameter onto follower cards normally (the driver stays unwired to it):
+
+```
+dashboard_write {"method": "update", "id": 40,
+ "ops": [{"op": "patch_dashcard", "dashcard_id": 7,
+ "patch": {"visualization_settings": {
+ "click_behavior": {
+ "type": "crossfilter",
+ "parameterMapping": {
+ "category": {"id": "category",
+ "source": {"type": "column", "id": "CATEGORY", "name": "Category"},
+ "target": {"type": "parameter", "id": "category"}}}}}}}]}
+```
+
+Link — `linkType` `"dashboard"` / `"question"` (`targetId` = target's numeric id, optional `parameterMapping`) or `"url"` (`linkTemplate`; `{{column}}` = clicked row value, `{{filter:param}}` = a dashboard parameter's value):
+
+```json
+// per column, under column_settings["[\"name\",\"campaign_name\"]"]: open dashboard 13 with its "campaign" filter set
+"click_behavior": {
+ "type": "link", "linkType": "dashboard", "targetId": 13,
+ "parameterMapping": {
+ "campaign": {"id": "campaign",
+ "source": {"type": "column", "id": "campaign_name", "name": "campaign_name"},
+ "target": {"type": "parameter", "id": "campaign"}}}}
+
+// whole card: any click opens question 42
+"click_behavior": {"type": "link", "linkType": "question", "targetId": 42}
+
+// url template, whole card or per column
+"click_behavior": {"type": "link", "linkType": "url", "linkTemplate": "https://app/campaigns/{{campaign_id}}"}
+```
+
+`parameterMapping` keys, `id`, and `target.id` are the **target** dashboard's parameter ids (`get_content` on it lists them); `source.id` is an output column of **this** card (a native card's SQL alias); one entry per filter passed. For anything else (a `question` target with mapped filters, full drill setups) build it once in the UI and copy the dashcard's settings via `get_content`.
+
+## Virtual dashcards
+
+Text/heading/link/iframe tiles are created with their own ops (`add_text`, `add_heading`, `add_link`, `add_iframe`) — never author their `virtual_card` settings by hand. A text, heading, or iframe card's content may carry `{{param}}` placeholders, bound to a dashboard parameter with a raw text-tag target — the name must appear as `{{region}}` in the card's own text or embed:
+
+```
+dashboard_write {"method": "update", "id": 40,
+ "ops": [{"op": "wire_parameter", "parameter_id": "region", "dashcard_id": 7,
+ "target": ["text-tag", "region"]}]}
+```
diff --git a/resources/migrations/064/20260909_retire_mcp_v1_oauth_scopes.yaml b/resources/migrations/064/20260909_retire_mcp_v1_oauth_scopes.yaml
new file mode 100644
index 00000000000..a297333c30c
--- /dev/null
+++ b/resources/migrations/064/20260909_retire_mcp_v1_oauth_scopes.yaml
@@ -0,0 +1,27 @@
+## MCP v1 retirement (GHY-4343). `/api/metabase-mcp` now serves the v2 tool surface, whose tools gate
+## on six coarse scopes. Clients connected to v0.60–v0.63 hold tokens carrying the per-entity agent
+## scopes instead; no legacy scope satisfies any v2 scope, so those clients get HTTP 200 with an empty
+## tools list and no error. The refresh grant can only narrow, so it never self-heals.
+##
+## Two data-only changesets: widen every dynamically registered client's scope snapshot so a
+## re-authorization validates, then revoke the legacy-shaped tokens so the client actually
+## re-authenticates rather than refreshing. Both are idempotent.
+
+databaseChangeLog:
+ - changeSet:
+ id: v64.2026-09-09T12:00:00
+ author: bryanmaass
+ comment: Widen dynamic OAuth client scope snapshots with the MCP v2 scopes
+ changes:
+ - customChange:
+ class: metabase.app_db.custom_migrations.WidenDynamicOAuthClientScopesForMcpV2
+ rollback: []
+
+ - changeSet:
+ id: v64.2026-09-09T12:00:01
+ author: bryanmaass
+ comment: Revoke OAuth tokens carrying only pre-MCP-v2 scopes
+ changes:
+ - customChange:
+ class: metabase.app_db.custom_migrations.RevokeLegacyMcpOAuthTokens
+ rollback: []
diff --git a/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/h2-mcp_tool_calls.sql b/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/h2-mcp_tool_calls.sql
index 056ff34b52a..53da7253b44 100644
--- a/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/h2-mcp_tool_calls.sql
+++ b/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/h2-mcp_tool_calls.sql
@@ -7,7 +7,7 @@ SELECT
t.tool_name,
t.status,
-- NOTE: keep these CASE branches in sync with the error-code-* constants in
- -- src/metabase/mcp/tools.clj (the enum-<->-CASE sync footgun).
+ -- src/metabase/mcp/v2/common.clj (the enum-<->-CASE sync footgun).
CASE t.error_code
WHEN -32600 THEN 'Invalid request'
WHEN -32601 THEN 'Method not found'
diff --git a/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/mysql-mcp_tool_calls.sql b/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/mysql-mcp_tool_calls.sql
index 2daa87388c8..fb6f8f73147 100644
--- a/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/mysql-mcp_tool_calls.sql
+++ b/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/mysql-mcp_tool_calls.sql
@@ -7,7 +7,7 @@ SELECT
t.tool_name,
t.status,
-- NOTE: keep these CASE branches in sync with the error-code-* constants in
- -- src/metabase/mcp/tools.clj (the enum-<->-CASE sync footgun).
+ -- src/metabase/mcp/v2/common.clj (the enum-<->-CASE sync footgun).
CASE t.error_code
WHEN -32600 THEN 'Invalid request'
WHEN -32601 THEN 'Method not found'
diff --git a/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/postgres-mcp_tool_calls.sql b/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/postgres-mcp_tool_calls.sql
index 056ff34b52a..53da7253b44 100644
--- a/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/postgres-mcp_tool_calls.sql
+++ b/resources/migrations/instance_analytics_views/mcp_tool_calls/v1/postgres-mcp_tool_calls.sql
@@ -7,7 +7,7 @@ SELECT
t.tool_name,
t.status,
-- NOTE: keep these CASE branches in sync with the error-code-* constants in
- -- src/metabase/mcp/tools.clj (the enum-<->-CASE sync footgun).
+ -- src/metabase/mcp/v2/common.clj (the enum-<->-CASE sync footgun).
CASE t.error_code
WHEN -32600 THEN 'Invalid request'
WHEN -32601 THEN 'Method not found'
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.clj
index 31b36b65543..269d04c2662 100644
--- a/src/metabase/agent_api/api.clj
+++ b/src/metabase/agent_api/api.clj
@@ -27,6 +27,7 @@
[metabase.lib.schema.common :as lib.schema.common]
[metabase.metabot.core :as metabot]
[metabase.metabot.tools.construct :as metabot-construct]
+ [metabase.metabot.tools.recovery-hints :as recovery-hints]
[metabase.metabot.tools.resources :as metabot-resources]
[metabase.metabot.tools.search :as metabot-search]
[metabase.metabot.util :as metabot.u]
@@ -239,7 +240,9 @@
table, ambiguous FK, etc.); we let those propagate so [[api.macros/defendpoint]] surfaces
them with the appropriate 4xx status code instead of a 500."
[body]
- (-> (metabot-construct/execute-representations-query (:query body))
+ (-> (metabot-construct/execute-representations-query
+ (:query body)
+ {:recovery-hint recovery-hints/recovery-hint})
(get-in [:structured-output :query])))
(defn- evaluate-external-query-for-execution
@@ -1393,13 +1396,13 @@
(let [tab-id (target-tab-id tab_id)]
(insert-new-dashcard! state dashboard-id tab-id
(autoplaced-position (on-tab (:placed @state) tab-id) :heading nil)
- {:visualization_settings (dashboard-card/virtual-card-settings "heading" text)}))
+ {:visualization_settings (dashboard-card/virtual-card-settings "heading" {:text text})}))
"add_text"
(let [tab-id (target-tab-id tab_id)]
(insert-new-dashcard! state dashboard-id tab-id
(autoplaced-position (on-tab (:placed @state) tab-id) :text display_size)
- {:visualization_settings (dashboard-card/virtual-card-settings "text" text)}))
+ {:visualization_settings (dashboard-card/virtual-card-settings "text" {:text text})}))
"update_text"
(let [existing (api/check-404
diff --git a/src/metabase/agent_api/query_guards.clj b/src/metabase/agent_api/query_guards.clj
index 40d2b905606..a36cad22afb 100644
--- a/src/metabase/agent_api/query_guards.clj
+++ b/src/metabase/agent_api/query_guards.clj
@@ -11,19 +11,20 @@
copy: native detection raw-scans the payload instead of normalize-then-inspect, so a payload
too malformed to normalize now fails closed instead of falling through to shape validation.
- [[check-mcp-ui-native-query!]] is the odd one out: it is written to guard the ordinary QP endpoints,
- which the MCP Apps iframe reaches with a credential that the endpoint scope middleware cannot narrow.
- It shares the native detection but refuses raw SQL on scope rather than banning it outright. It is
- NOT yet wired into any endpoint — the `:mcp-ui-credential` it keys on, and the scopes claim it spends,
- only exist once the v2 core's session rework lands (the next PR in this stack). It is extracted and
- unit-tested here so that slice can wire it in without also authoring it; until then it is dormant."
+ [[check-mcp-ui-native-query!]] is the odd one out: it guards the ordinary QP endpoints, which the
+ MCP Apps iframe reaches with a credential that the endpoint scope middleware cannot narrow. It
+ shares the native detection but refuses raw SQL on scope rather than banning it outright. It is
+ mounted on the whole `/api/dataset` route tree via [[+refuse-unscoped-native-sql]], keyed on the
+ `:mcp-ui-credential` the session middleware attaches and the scopes claim the v2 session rework
+ put on it."
(:require
[clojure.string :as str]
[metabase.agent-api.settings :as agent-api.settings]
[metabase.api.common :as api]
[metabase.api.macros.scope :as scope]
[metabase.metabot.scope :as metabot.scope]
- [metabase.util :as u]))
+ [metabase.util :as u]
+ [metabase.util.json :as json]))
(set! *warn-on-reflection* true)
@@ -79,6 +80,16 @@
payload still reaches the query processor as a native stage and must trip the guard."
#{"query" "source-query"})
+(defn- try-decode-json
+ "`s` parsed as JSON, or nil when it does not parse.
+
+ Only used to look INSIDE a structural edge that arrived as a string; a parse failure is not an error here,
+ it just means the value is not a query fragment and the caller falls back to its usual scan."
+ [s]
+ (try
+ (json/decode s true)
+ (catch Exception _ nil)))
+
(defn native-query?
"True if `query-map` (a decoded, client-reachable query) contains native SQL along its
query-nesting structure — legacy top-level `:type :native`, a legacy nested `:source-query`'s
@@ -117,14 +128,33 @@
(cond
(nil? node) false
(sequential? node) (boolean (some scan-map node))
+ ;; Decoded for the same reason as the map edge below, and kept symmetric with it deliberately:
+ ;; no edge accepts a JSON string here today, so if one ever does its contents must not become
+ ;; the one shape the scan cannot see.
+ (string? node) (let [decoded (try-decode-json node)]
+ (if (sequential? decoded)
+ (boolean (some scan-map decoded))
+ (deep-scan node)))
:else (deep-scan node)))
- ;; `:query`/`:source-query`: normally a nested stage/query map. A malformed non-map value
- ;; is deep-scanned.
+ ;; `:query`/`:source-query`: normally a nested stage/query map. A JSON STRING is decoded first —
+ ;; `POST /api/dataset/:export-format` accepts `query` that way for `<form>`-submit back-compat and
+ ;; decodes it in Malli, which runs AFTER this guard, so the guard is handed the raw string. Without
+ ;; decoding, a string edge falls to `deep-scan`, which finds no marker inside text. Anything that is
+ ;; not a map and not JSON-decodable to one is deep-scanned as before.
+ ;;
+ ;; This reaches a JSON body. A genuinely `<form>`-encoded submit — the shape that back-compat is
+ ;; actually about — leaves `(:body request)` a stream, not a map, so nothing structural is visible
+ ;; and the scan passes. That route is off the credential's allowlist, so it is unreachable today;
+ ;; adding it would mean reading `[:params :query]` alongside the body.
(scan-map-edge [node]
(cond
- (nil? node) false
- (map? node) (scan-map node)
- :else (deep-scan node)))
+ (nil? node) false
+ (map? node) (scan-map node)
+ (string? node) (let [decoded (try-decode-json node)]
+ (if (map? decoded)
+ (scan-map decoded)
+ (deep-scan node)))
+ :else (deep-scan node)))
;; Fail-closed fallback for a malformed sub-tree: match a marker anywhere within it.
(deep-scan [node]
(boolean (some native-marker? (tree-seq coll? seq node))))]
@@ -167,22 +197,16 @@
(defn check-mcp-ui-native-query!
"Throw a 403 if `request` is authenticated by an MCP Apps UI credential that may not run `query` as raw SQL.
- NOT yet wired into any endpoint. The `:mcp-ui-credential` request key it dispatches on is attached by
- the v2 core's session rework (the next PR in this stack); until that lands no request carries it, so this
- guard is a no-op wherever it might be called. It is authored and unit-tested here so the session-rework
- slice can drop it into the QP endpoint path without also having to write it. When wiring it in, add it to
- the QP-endpoint request flow for the routes on the MCP-UI credential's allowlist (the `/api/dataset*`
- surface), and delete this paragraph.
+ Mounted on the `/api/dataset` route tree by [[+refuse-unscoped-native-sql]].
- The iframe's credential is stamped `::scope/unrestricted` on purpose — none of the routes on its allowlist declare
- a `:scope`, so a narrower stamp would 403 the iframe at bootstrap. That makes the endpoint scope middleware unable
- to stop a credential lifted out of the resource HTML from POSTing native SQL to the query endpoints. The minting
- session's real scopes are meant to ride along on the credential and be spent here: raw SQL needs an SQL-execution
- scope (`agent:sql:run`, or v1's concrete `agent:sql:execute`) and the `mcp-execute-sql-enabled` kill switch.
+ The query endpoints declare no `:scope` of their own, so the endpoint scope middleware cannot tell a native
+ query apart from any other one: [[metabase.mcp.ui-surface/request-surface]] charges the whole `/api/dataset`
+ tree a single `agent:query:run`, which a credential lifted out of the resource HTML holds. Raw SQL costs
+ more, and that difference is spent here: it needs an SQL-execution scope (`agent:sql:run`, or v1's concrete
+ `agent:sql:execute`) off the credential's signed claim, and the `mcp-execute-sql-enabled` kill switch.
- Sequencing: credentials only start carrying a scopes claim with the v2 core's session rework (the
- next PR in this stack). Until then — and for any credential minted before that deploy — the claim
- is absent and a native query over a UI credential fails closed, which the test suite codifies.
+ A credential whose claim is simply absent fails closed: a rolling deploy can hand this node one minted before
+ the claim existed.
Native is refused rather than banned because `execute_sql` handles legitimately hold raw SQL and are visualizable
by design. Non-native queries, and requests authenticated any other way, pass straight through."
@@ -207,6 +231,30 @@
"with the mcp-execute-sql-enabled setting.")
{:status-code 403}))))))
+(defn +refuse-unscoped-native-sql
+ "Ring middleware applying [[check-mcp-ui-native-query!]] to a route tree, reading the query from the request
+ body.
+
+ It rides the route rather than the endpoints because the endpoints cannot reach it: `agent-api` already
+ `:uses` `query-processor`, so a call from inside `metabase.query-processor.api` would close a module cycle.
+ `api-routes` is `:uses :any` and is where the two modules legitimately meet.
+
+ Applying it to the whole `/api/dataset` tree rather than to the two executing routes is deliberate: the
+ guard is keyed on `:mcp-ui-credential`, which the session middleware attaches only for the routes on the
+ credential's own allowlist, so every other route short-circuits before the body is read. That also means a
+ `/api/dataset` route later added to the allowlist is covered the day it is added — a route added ELSEWHERE
+ is not, because this middleware wraps only that tree — which is why the scan decodes a
+ JSON-string `query` edge rather than assuming the already-decoded shape: `/api/dataset/:export-format`
+ takes one, this middleware runs ahead of Malli's `:decode/api`, and that route is off the allowlist only
+ for now."
+ [handler]
+ (fn [request respond raise]
+ (try
+ (check-mcp-ui-native-query! request (:body request))
+ (handler request respond raise)
+ (catch Throwable e
+ (raise e)))))
+
(defn check-token-query-permissions!
"Re-validate the current user's permissions on a stored or client-supplied query.
diff --git a/src/metabase/agent_lib/representations.clj b/src/metabase/agent_lib/representations.clj
index 6269940dbaa..53f8df3e808 100644
--- a/src/metabase/agent_lib/representations.clj
+++ b/src/metabase/agent_lib/representations.clj
@@ -28,6 +28,7 @@
[malli.core :as mc]
[malli.transform :as mtx]
[metabase.lib.schema :as lib.schema]
+ [metabase.models.serialization.resolve :as serdes.resolve]
[metabase.util.i18n :refer [tru]]
[metabase.util.malli.humanize :as mu.humanize]
[metabase.util.malli.registry :as mr]))
@@ -179,6 +180,13 @@
(non-blank-string? (nth x 0))
(options-map? (nth x 1))))
+(defn- numeric-id-when-allowed?
+ "A numeric id in a source slot, valid only on a surface that accepts numeric ids (checked at
+ validation time via [[metabase.models.serialization.resolve/*numeric-ids-allowed?*]], so the
+ same schema serves both surfaces)."
+ [x]
+ (and (pos-int? x) serdes.resolve/*numeric-ids-allowed?*))
+
(def ^:private registry
{::table-fk [:and vector?
[:fn {:error/message "table FK must be [db-name, schema-or-null, table-name]"}
@@ -207,8 +215,14 @@
::stage [:map
{:closed false}
["lib/type" [:= "mbql.stage/mbql"]]
- ["source-table" {:optional true} [:ref ::table-fk]]
- ["source-card" {:optional true} :string]
+ ["source-table" {:optional true}
+ [:or [:ref ::table-fk]
+ [:fn {:error/message "numeric table ids are accepted on numeric-id surfaces only"}
+ numeric-id-when-allowed?]]]
+ ["source-card" {:optional true}
+ [:or :string
+ [:fn {:error/message "numeric card ids are accepted on numeric-id surfaces only"}
+ numeric-id-when-allowed?]]]
["joins" {:optional true} [:sequential [:ref ::join]]]
["filters" {:optional true} [:sequential [:ref ::clause]]]
["aggregation" {:optional true} [:sequential [:ref ::clause]]]
diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.clj
index 729640fb0bd..8556a2cd1e4 100644
--- a/src/metabase/agent_lib/representations/repair.clj
+++ b/src/metabase/agent_lib/representations/repair.clj
@@ -1868,9 +1868,10 @@
;;; ============================================================
(defn- field-clause?
- "A repaired field clause of shape `[\"field\" <opts-map> <portable-fk-vector>]`. We require the
- opts map to be a real map and the portable FK to be a vector of >= 4 elements (DB, SCHEMA,
- TABLE, FIELD, …)."
+ "A repaired field clause of shape `[\"field\" <opts-map> <target>]` whose target names a
+ concrete column. We require the opts map to be a real map and the target to be either a
+ portable FK vector of >= 4 elements (DB, SCHEMA, TABLE, FIELD, …) or — on a surface that
+ accepts numeric ids — a numeric field id."
[v]
(and (vector? v)
(not (map-entry? v))
@@ -1878,7 +1879,8 @@
(= "field" (nth v 0))
(map? (nth v 1))
(let [fk (nth v 2)]
- (and (vector? fk) (>= (count fk) 4)))))
+ (or (and (vector? fk) (>= (count fk) 4))
+ (and (pos-int? fk) resolve/*numeric-ids-allowed?*)))))
(defn- try-resolve-source-table-id
"Resolve the stage's `source-table` portable FK to a numeric id. Returns nil on any failure
@@ -1887,17 +1889,23 @@
surface with a better message."
[import-resolver source-table-fk]
(try
- (when (and import-resolver (vector? source-table-fk) (= 3 (count source-table-fk)))
+ (cond
+ (and (pos-int? source-table-fk) resolve/*numeric-ids-allowed?*)
+ source-table-fk
+
+ (and import-resolver (vector? source-table-fk) (= 3 (count source-table-fk)))
(resolve/import-table-fk import-resolver source-table-fk))
(catch Exception _ nil)))
(defn- try-resolve-field-target-table-id
- "Resolve the target-table-id of a portable field FK, by looking up the field and following its
- `:table-id`. Walks JSON-unfolded parent chains via the resolver's `import-field-fk`. Returns
- nil on failure."
+ "Resolve the target-table-id of a field target — a portable field FK or a numeric field id —
+ by looking up the field and following its `:table-id`. Walks JSON-unfolded parent chains via
+ the resolver's `import-field-fk`. Returns nil on failure."
[mp import-resolver field-fk]
(try
- (when-let [fid (resolve/import-field-fk import-resolver field-fk)]
+ (when-let [fid (if (pos-int? field-fk)
+ field-fk
+ (resolve/import-field-fk import-resolver field-fk))]
(:table-id (lib.metadata.protocols/field mp fid)))
(catch Exception _ nil)))
@@ -1956,10 +1964,17 @@
(let [candidates (get outbound-fks-by-target target-table-id)]
(case (count candidates)
0 (let [src-name (display-source-table mp source-table-id)
- tbl-name (nth fk 2)]
- (throw (ex-info (tru "Field {0} is on table {1}, which has no foreign key from the source table {2}, so it cannot be reached implicitly. To group or filter by a column from that table, add an explicit `joins:` entry and reference the field using the join alias. If you are aggregating a metric that relates to that table (metrics can join tables that have no foreign key), read that metric dimensions resource `metabase://metric/<metric_id>/dimensions` which lists the exact join clause to paste into `joins:` and the columns it unlocks. Otherwise use a field from the source table."
+ ;; MBQL 5 can carry `fk` as a numeric id rather than a `[db schema table field]`
+ ;; vector. For the portable form the vector already carries the table's own
+ ;; name; for the numeric form we name the table by its bare id rather than
+ ;; reading it back off the metadata provider (a plain id, not `pr-str`, which
+ ;; would render `"42"` and read as a table literally named 42).
+ tbl-name (if (vector? fk)
+ (pr-str (nth fk 2))
+ (str target-table-id))]
+ (throw (ex-info (tru "Field {0} is on table {1}, which has no foreign key from the source table {2}, so it cannot be reached implicitly. To group or filter by a column from that table, add an explicit `joins:` entry and reference the field using the join alias. If you are aggregating a metric that relates to that table (metrics can join tables that have no foreign key), its dimensions list the exact join clause to paste into `joins:` and the columns it unlocks. Otherwise use a field from the source table."
(display-portable fk)
- (pr-str tbl-name)
+ tbl-name
(pr-str src-name))
{:status-code 400
:error :no-fk-path
@@ -1975,10 +1990,11 @@
;; Deliberately do NOT enumerate the candidate FK columns: the metadata provider
;; is un-sandboxed and any leaked `[db schema table field]` path could surface
;; bridge-table column names the caller is not permitted to see (`:agent-error?`
- ;; relays the message verbatim to the user). The LLM can recover by reading the
- ;; source table's fields with `read_resource` to inspect available foreign-key columns.
+ ;; relays the message verbatim to the user). The LLM can recover by listing the
+ ;; source table's fields with the surface's own discovery tool to inspect the
+ ;; available foreign-key columns.
(let [src-name (display-source-table mp source-table-id)]
- (throw (ex-info (tru "Field {0} can be reached from {1} via {2} foreign keys. Specify the `source-field` option on the field clause to disambiguate; call `read_resource` with `metabase://table/<numeric id>/fields` for the source table to list the available foreign-key columns."
+ (throw (ex-info (tru "Field {0} can be reached from {1} via {2} foreign keys. Specify the `source-field` option on the field clause to disambiguate."
(display-portable fk)
(pr-str src-name)
(count candidates))
@@ -2653,30 +2669,33 @@
(defn- numeric-field-id-error!
"Detect any `[field, <opts>, <id>]` clause whose third slot is an integer (the sexp /
- legacy-MBQL numeric field-id form). repr requires a portable FK in the third slot:
- either a vector `[<db>, <schema>, <table>, <column>]` (resolved against the metadata
- provider) OR a string column name (cross-stage reference). lib's schema rejects bare
- numeric ids, but the error is a generic shape mismatch; this detector gives an
- LLM-actionable explanation pointing at the portable-FK syntax.
+ legacy-MBQL numeric field-id form). On the portable-only surface repr requires a portable FK
+ in the third slot: either a vector `[<db>, <schema>, <table>, <column>]` (resolved against the
+ metadata provider) OR a string column name (cross-stage reference). Such a clause fails
+ downstream anyway, but as a generic shape mismatch; this detector gives an LLM-actionable
+ explanation pointing at the portable-FK syntax instead.
Carried over from the sexp pipeline's
- `validate/operators.clj/validate-operator-specific!` `field` branch."
+ `validate/operators.clj/validate-operator-specific!` `field` branch. A no-op on surfaces
+ that accept numeric field ids (see [[metabase.models.serialization.resolve/*numeric-ids-allowed?*]])."
[form]
- (walk/postwalk
- (fn [node]
- (when (and (vector? node)
- (not (map-entry? node))
- (= 3 (count node))
- (= "field" (nth node 0))
- (map? (nth node 1))
- (integer? (nth node 2)))
- (throw (ex-info
- (tru "`field` clause needs a portable FK in its third slot, not a numeric id. Use a vector `[<database>, <schema>, <table>, <column>]` (resolved against the metadata provider) or a string column-name (for cross-stage references).")
- {:agent-error? true
- :error :numeric-field-id
- :clause node})))
- node)
- form))
+ (when-not resolve/*numeric-ids-allowed?*
+ (walk/postwalk
+ (fn [node]
+ (when (and (vector? node)
+ (not (map-entry? node))
+ (= 3 (count node))
+ (= "field" (nth node 0))
+ (map? (nth node 1))
+ (integer? (nth node 2)))
+ (throw (ex-info
+ (tru "`field` clause needs a portable FK in its third slot, not a numeric id. Use a vector `[<database>, <schema>, <table>, <column>]` (resolved against the metadata provider) or a string column-name (for cross-stage references).")
+ {:agent-error? true
+ :error :numeric-field-id
+ :clause node})))
+ node)
+ form))
+ form)
;;; ----- friendly-errors pipeline driver -----------------------------------------------
diff --git a/src/metabase/api/macros/scope.clj b/src/metabase/api/macros/scope.clj
index 720c8c629f1..0a224c07483 100644
--- a/src/metabase/api/macros/scope.clj
+++ b/src/metabase/api/macros/scope.clj
@@ -12,7 +12,15 @@
The `::unrestricted` keyword is used as a sentinel in `:token-scopes` to indicate an unrestricted token
(session auth or unscoped JWT). Unlike `\"*\"` which is a valid wildcard scope that could appear in a
- JWT claim, this keyword can never be confused with an externally-supplied scope string."
+ JWT claim, this keyword can never be confused with an externally-supplied scope string.
+
+ `::mcp-ui` is a second such sentinel, for the MCP Apps iframe credential. It is deliberately NOT
+ `::unrestricted`: the credential authenticates a narrow, purpose-limited surface, and stamping it
+ unrestricted meant that anything which reached an endpoint outside that surface arrived with full
+ privilege. Carrying `::mcp-ui` instead makes the default failure closed — it satisfies no endpoint's
+ declared `:scope`, and `ensure-scopes-checked` refuses it on endpoints that declare none — so such a
+ request is rejected rather than served. Being a keyword, it can never be requested, granted, or named on
+ a consent screen."
(:require
[metabase.api-scope.core :as api-scope]
[metabase.config.core :as config]
@@ -37,7 +45,19 @@
On success, sets `:token-scopes-checked` on the request so that downstream [[ensure-scopes-checked]]
middleware knows scope enforcement already happened. This allows `enforce-scope` to be applied at the
- namespace level while individual endpoints use `ensure-scopes-checked` as a safety net."
+ namespace level while individual endpoints use `ensure-scopes-checked` as a safety net.
+
+ Also passes an MCP Apps UI credential (`::mcp-ui`) whose request is already `:token-scopes-checked`.
+ That credential is not an OAuth token and an endpoint's declared `:scope` is not the vocabulary that
+ confines it: [[metabase.mcp.ui-surface/request-surface]] is, and it is strictly narrower — a handful of
+ routes, each priced in the MCP scope the minting session had to hold. The stamp is set only when that
+ gate passes, so honouring it here defers to a route-specific decision that already happened rather than
+ waiving one. Without this, declaring a `:scope` on any route of that surface silently 403s the iframe
+ while every other caller is unaffected, and the iframe just stops rendering.
+
+ Deliberately conditioned on `::mcp-ui` rather than on the stamp alone. `enforce-scope` sets the stamp
+ itself on success, so trusting it unconditionally would make every per-endpoint `:scope` a no-op
+ underneath a namespace-level `enforce-scope`."
[required-scope]
;; Dev-time warning only — fires at middleware construction (load time), not per-request.
;; The middleware is returned regardless; this just surfaces unregistered scopes early.
@@ -48,6 +68,8 @@
(let [token-scopes (:token-scopes request)]
(if (or (nil? token-scopes)
(contains? token-scopes ::unrestricted)
+ (and (contains? token-scopes ::mcp-ui)
+ (:token-scopes-checked request))
(scope-satisfied? token-scopes required-scope))
(handler (cond-> request
token-scopes (assoc :token-scopes-checked true))
diff --git a/src/metabase/api_routes/routes.clj b/src/metabase/api_routes/routes.clj
index 6af97827aa4..3f79cb98c30 100644
--- a/src/metabase/api_routes/routes.clj
+++ b/src/metabase/api_routes/routes.clj
@@ -4,6 +4,7 @@
[metabase.actions-rest.api]
[metabase.activity-feed.api]
[metabase.agent-api.api]
+ [metabase.agent-api.query-guards :as agent-api.query-guards]
[metabase.ai-tracing.api]
[metabase.analytics.api]
[metabase.analytics.api.proxy]
@@ -37,8 +38,8 @@
[metabase.llm.api]
[metabase.logger.api]
[metabase.login-history.api]
- [metabase.mcp.api]
[metabase.mcp.callback-api]
+ [metabase.mcp.v2.api]
[metabase.measures.api]
[metabase.metabot.api]
[metabase.metrics.api]
@@ -105,8 +106,8 @@
metabase.indexes-rest.api/keep-me
metabase.logger.api/keep-me
metabase.login-history.api/keep-me
- metabase.mcp.api/keep-me
metabase.mcp.callback-api/keep-me
+ metabase.mcp.v2.api/keep-me
metabase.oauth-server.api.admin/keep-me
metabase.osi.ai-context.api/keep-me
metabase.measures.api/keep-me
@@ -189,7 +190,14 @@
"/dashboard" (+auth 'metabase.dashboards-rest.api)
"/data-studio" (+auth metabase.data-studio.api/routes)
"/database" (+auth 'metabase.warehouses-rest.api)
- "/dataset" (+auth 'metabase.query-processor.api)
+ ;; The MCP Apps iframe credential is accepted for `/dataset` and is stamped unrestricted, so the endpoint
+ ;; scope middleware cannot hold the `agent:sql:run` line here — the guard is what stops a credential lifted
+ ;; out of the resource HTML from POSTing raw SQL. The spec-generation wrapper keeps the guard transparent
+ ;; to [[metabase.api.open-api/open-api-spec]] — a bare middleware fn here fails openapi.json generation
+ ;; for the whole /api tree.
+ "/dataset" (+auth ((routes.common/wrap-middleware-for-open-api-spec-generation
+ agent-api.query-guards/+refuse-unscoped-native-sql)
+ (api.macros/ns-handler 'metabase.query-processor.api)))
"/docs" (metabase.api.docs/make-routes #'routes)
"/document" (+auth metabase.documents.api/routes)
"/eid-translation" (+auth 'metabase.eid-translation.api)
@@ -211,10 +219,10 @@
"/logger" (+auth 'metabase.logger.api)
"/login-history" (+auth 'metabase.login-history.api)
;; `/mcp` is a legacy alias of the canonical `/metabase-mcp` below, kept for back-compat with
- ;; existing clients. See [[metabase.mcp.api/endpoint-paths]].
- "/mcp" (metabase.mcp.api/+mcp-enabled metabase.mcp.api/handler)
+ ;; existing clients. See [[metabase.mcp.paths/endpoint-paths]].
+ "/mcp" (metabase.mcp.v2.api/+mcp-enabled metabase.mcp.v2.api/handler)
"/measure" (+auth 'metabase.measures.api)
- "/metabase-mcp" (metabase.mcp.api/+mcp-enabled metabase.mcp.api/handler)
+ "/metabase-mcp" (metabase.mcp.v2.api/+mcp-enabled metabase.mcp.v2.api/handler)
"/metabot" metabase.metabot.api/routes
"/metric" (+auth 'metabase.metrics.api)
"/model-index" (+auth 'metabase.indexed-entities.api)
diff --git a/src/metabase/app_db/custom_migrations.clj b/src/metabase/app_db/custom_migrations.clj
index 36a4d2acf6f..224b44e84cd 100644
--- a/src/metabase/app_db/custom_migrations.clj
+++ b/src/metabase/app_db/custom_migrations.clj
@@ -2259,3 +2259,79 @@
(t2/query {:update :setting
:set {:value_with_aad (encryption/maybe-encrypt plain {:aad (mdb.setting/setting-aad "example-dashboard-id")})}
:where [:= :key "example-dashboard-id"]}))))
+
+;;; MCP v1 retirement (GHY-4343): `/api/metabase-mcp` now serves the v2 tool surface, which gates every
+;;; tool on one of six coarse scopes. Clients connected to v0.60–v0.63 hold OAuth tokens carrying the
+;;; per-entity agent scopes instead, and no legacy scope satisfies any v2 scope, so `list-tools` filters
+;;; the whole surface away: HTTP 200, an empty tools list, nothing logged. It does not self-heal — the
+;;; refresh grant copies the original scope forward and can only narrow — so a refreshing client stays
+;;; in the zero-tools state indefinitely.
+;;;
+;;; The scope strings are literals rather than a read of `metabase.mcp.paths/v2-surface-scopes`: a
+;;; migration's behaviour must be frozen against later edits to that vector.
+
+(def ^:private ^:no-doc mcp-v2-scopes
+ ["agent:content:read"
+ "agent:content:write"
+ "agent:query:run"
+ "agent:sql:run"
+ "agent:delivery:write"
+ "agent:resource:read"])
+
+;; `agent:resource:read` is excluded: it gates only a resource, so a token holding it alone still
+;; resolves zero *tools*, which is the state this migration exists to end.
+(def ^:private ^:no-doc mcp-v2-tool-scopes
+ (set (remove #{"agent:resource:read"} mcp-v2-scopes)))
+
+(defn- legacy-mcp-scopes?
+ "True when `scopes` looks like a token minted against the pre-v2 scope set: it satisfies no v2 tool
+ and carries at least one scope outside the six. The second half is what keeps this off tokens that
+ are already v2-shaped (or empty), so re-running the migration revokes nothing new."
+ [scopes]
+ (let [scopes (set (filter string? scopes))]
+ (and (not (some mcp-v2-tool-scopes scopes))
+ (boolean (some (complement (set mcp-v2-scopes)) scopes)))))
+
+(defn- json-array-out
+ "Parse a JSON-array column into a vector, tolerating a row that is already a collection. Returns nil
+ for anything that isn't an array — including unparseable JSON — so a malformed row is skipped
+ rather than rewritten."
+ [v]
+ (let [parsed (cond
+ (string? v) (try (json/decode v) (catch Exception _ nil))
+ (coll? v) v)]
+ (when (sequential? parsed)
+ (vec parsed))))
+
+(define-migration WidenDynamicOAuthClientScopesForMcpV2
+ ;; Step 1 of 2 — raise the ceiling. Dynamically registered clients snapshot the scope set that
+ ;; existed when they registered, and `validate-scope` rejects any requested scope absent from that
+ ;; snapshot. Without this a user who re-authorizes is answered `400 invalid_request`, rendered raw
+ ;; in the browser tab, because `/oauth/authorize` validates before narrowing. Widening the snapshot
+ ;; grants nothing on its own: consent still happens per-authorization.
+ (run! (fn [{:keys [id scopes]}]
+ (when-let [existing (json-array-out scopes)]
+ (let [widened (into existing (remove (set existing)) mcp-v2-scopes)]
+ (when-not (= widened existing)
+ (t2/query {:update :oauth_client
+ :set {:scopes (json/encode widened)}
+ :where [:= :id id]})))))
+ (t2/reducible-query {:select [:id :scopes]
+ :from [:oauth_client]
+ :where [:= :registration_type "dynamic"]})))
+
+(define-migration RevokeLegacyMcpOAuthTokens
+ ;; Step 2 of 2 — force one re-authentication. Both tables must be stamped: leaving the refresh token
+ ;; alive means the client silently refreshes into another legacy-scoped access token instead of
+ ;; re-authenticating. Once both are revoked the next request gets the existing `invalid_token` 401
+ ;; with the discovery challenge — the RFC 6750 path every MCP client already handles.
+ (doseq [table [:oauth_access_token :oauth_refresh_token]]
+ (run! (fn [{:keys [id scope]}]
+ (when (some-> (json-array-out scope) legacy-mcp-scopes?)
+ (t2/query {:update table
+ :set {:revoked_at :%now}
+ :where [:= :id id]})))
+ ;; Already-revoked rows are skipped, which is also what makes this safe to re-run.
+ (t2/reducible-query {:select [:id :scope]
+ :from [table]
+ :where [:= :revoked_at nil]}))))
diff --git a/src/metabase/bookmarks/api.clj b/src/metabase/bookmarks/api.clj
index dc1dd380ed5..93e85829840 100644
--- a/src/metabase/bookmarks/api.clj
+++ b/src/metabase/bookmarks/api.clj
@@ -30,30 +30,6 @@
"document" :model/Document
"exploration" :model/Exploration})
-(defn- bookmark-exists? [model id user-id]
- (case model
- "card" (bookmarks.db/card-bookmark-exists? id user-id)
- "dashboard" (bookmarks.db/dashboard-bookmark-exists? id user-id)
- "collection" (bookmarks.db/collection-bookmark-exists? id user-id)
- "document" (bookmarks.db/document-bookmark-exists? id user-id)
- "exploration" (bookmarks.db/exploration-bookmark-exists? id user-id)))
-
-(defn- insert-bookmark! [model id user-id]
- (case model
- "card" (bookmarks.db/insert-card-bookmark! id user-id)
- "dashboard" (bookmarks.db/insert-dashboard-bookmark! id user-id)
- "collection" (bookmarks.db/insert-collection-bookmark! id user-id)
- "document" (bookmarks.db/insert-document-bookmark! id user-id)
- "exploration" (bookmarks.db/insert-exploration-bookmark! id user-id)))
-
-(defn- delete-bookmark! [model id user-id]
- (case model
- "card" (bookmarks.db/delete-card-bookmark! id user-id)
- "dashboard" (bookmarks.db/delete-dashboard-bookmark! id user-id)
- "collection" (bookmarks.db/delete-collection-bookmark! id user-id)
- "document" (bookmarks.db/delete-document-bookmark! id user-id)
- "exploration" (bookmarks.db/delete-exploration-bookmark! id user-id)))
-
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
;;
@@ -75,9 +51,9 @@
[:model Models]
[:id ms/PositiveInt]]]
(api/read-check (item-model model) id)
- (api/check (not (bookmark-exists? model id api/*current-user-id*))
+ (api/check (not (bookmarks.db/bookmark-exists? model id api/*current-user-id*))
[400 "Bookmark already exists"])
- (insert-bookmark! model id api/*current-user-id*))
+ (bookmarks.db/insert-bookmark! model id api/*current-user-id*))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -89,7 +65,7 @@
[:model Models]
[:id ms/PositiveInt]]]
;; todo: allow admins to include an optional user id to delete for so they can delete other's bookmarks.
- (delete-bookmark! model id api/*current-user-id*)
+ (bookmarks.db/delete-bookmark! model id api/*current-user-id*)
api/generic-204-no-content)
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
diff --git a/src/metabase/bookmarks/db.clj b/src/metabase/bookmarks/db.clj
index 12b1a71bac4..2cbd9a24992 100644
--- a/src/metabase/bookmarks/db.clj
+++ b/src/metabase/bookmarks/db.clj
@@ -1,6 +1,6 @@
(ns metabase.bookmarks.db
- "Application database queries for the bookmarks module. Every function here is a direct Toucan 2 call with no
- additional logic, so no other namespace in the module runs a query itself (model definitions still use `toucan2.core`)."
+ "Application database queries for the bookmarks module, plus a thin (model, id, user-id) dispatch tier over them,
+ so no other namespace in the module runs a query itself (model definitions still use `toucan2.core`)."
(:require
[malli.util :as mut]
[metabase.app-db.core :as mdb]
@@ -106,6 +106,53 @@
user-id :- ::lib.schema.id/user]
(t2/delete! :model/ExplorationBookmark :exploration_id exploration-id :user_id user-id))
+;;; Generic (model, id, user-id) tier. The REST API and the MCP `bookmark_content` tool both take the
+;;; model as a runtime string, so they dispatch here rather than naming a per-model fn at the call site.
+
+(defn- unknown-bookmark-model!
+ "Throws a consistent error for a `model` string none of the generic (model, id, user-id) fns recognize."
+ [model]
+ (throw (ex-info (str "Unknown bookmarkable model: " (pr-str model)) {:model model})))
+
+(defn bookmark-exists?
+ "Whether the User with `user-id` has a bookmark on (`model`, `id`). `model` is a bookmarkable model string.
+ Throws for an unrecognized `model`."
+ [model id user-id]
+ (case model
+ "card" (card-bookmark-exists? id user-id)
+ "dashboard" (dashboard-bookmark-exists? id user-id)
+ "collection" (collection-bookmark-exists? id user-id)
+ "document" (document-bookmark-exists? id user-id)
+ "exploration" (exploration-bookmark-exists? id user-id)
+ (unknown-bookmark-model! model)))
+
+(def ^:private model->bookmark-model+item-key
+ {"card" [:model/CardBookmark :card_id]
+ "dashboard" [:model/DashboardBookmark :dashboard_id]
+ "collection" [:model/CollectionBookmark :collection_id]
+ "document" [:model/DocumentBookmark :document_id]
+ "exploration" [:model/ExplorationBookmark :exploration_id]})
+
+(defn insert-bookmark!
+ "Give `user-id` a bookmark on (`model`, `id`) and return it - the existing one when there already is one.
+ Does not read-check the item; callers do. Throws for an unrecognized `model`."
+ [model id user-id]
+ (let [[bookmark-model item-key] (or (model->bookmark-model+item-key model) (unknown-bookmark-model! model))]
+ ;; select-or-insert! rather than insert!: concurrent callers both get the state they asked for instead of
+ ;; one losing to the (user_id, item) unique constraint.
+ (mdb/select-or-insert! bookmark-model {item-key id :user_id user-id} (constantly {}))))
+
+(defn delete-bookmark!
+ "Delete `user-id`'s bookmark on (`model`, `id`). No-op when there is none. Throws for an unrecognized `model`."
+ [model id user-id]
+ (case model
+ "card" (delete-card-bookmark! id user-id)
+ "dashboard" (delete-dashboard-bookmark! id user-id)
+ "collection" (delete-collection-bookmark! id user-id)
+ "document" (delete-document-bookmark! id user-id)
+ "exploration" (delete-exploration-bookmark! id user-id)
+ (unknown-bookmark-model! model)))
+
(mu/defn delete-bookmark-orderings-for-user!
"Delete the BookmarkOrderings of the User with `user-id`."
[user-id :- ::lib.schema.id/user]
diff --git a/src/metabase/collections/children.clj b/src/metabase/collections/children.clj
new file mode 100644
index 00000000000..a52090e4e11
--- /dev/null
+++ b/src/metabase/collections/children.clj
@@ -0,0 +1,1211 @@
+(ns metabase.collections.children
+ "Fetching the child items of a Collection (or the Root Collection) — the domain logic behind
+ the `/api/collection/:id/items`, `/api/collection/root/items`, and `/api/collection/tree`
+ REST endpoints, callable directly by non-REST consumers such as the MCP tools.
+
+ [[collection-children]] unions one query per child model (cards, dashboards, collections,
+ snippets, transforms, …), permission-filtered and sorted server-side; paging rides
+ [[metabase.request.core/limit]]/[[metabase.request.core/offset]] (bind them with
+ [[metabase.request.core/with-limit-and-offset]] outside a REST request). [[select-collections]]
+ and [[shallow-tree-from-collection-id]] serve the collection-tree views.
+
+ Callers that page over `:document` rows should scope
+ [[metabase.documents.core/with-content-gate-cache]] around the [[collection-children]] call:
+ the `:can_write` hydration on each document row adjudicates that document's content gate, and
+ the cache keeps that to once per document. The binding can't live here — `documents` already
+ depends on `collections`, so requiring it back would be circular."
+ (:require
+ [clojure.string :as str]
+ [honey.sql.helpers :as sql.helpers]
+ [medley.core :as m]
+ [metabase.api.common :as api]
+ [metabase.app-db.core :as mdb]
+ [metabase.collections.db :as collections.db]
+ [metabase.collections.models.collection :as collection]
+ [metabase.collections.util :as collections.util]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.models.interface :as mi]
+ [metabase.permissions.core :as perms]
+ [metabase.premium-features.core :as premium-features :refer [defenterprise]]
+ [metabase.queries.core :as queries]
+ [metabase.request.core :as request]
+ [metabase.revisions.core :as revisions]
+ [metabase.tracing.core :as tracing]
+ [metabase.transforms.feature-gating :as transforms.gating]
+ [metabase.transforms.util :as transforms.u]
+ [metabase.upload.core :as upload]
+ [metabase.util :as u]
+ [metabase.util.honey-sql-2 :as h2x]
+ [metabase.util.malli :as mu]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(defn- location-from-collection-id-clause
+ "Clause to restrict which collections are being selected based off collection-id. If collection-id is nil,
+ then restrict to the children and the grandchildren of the root collection. If collection-id is an an integer,
+ then restrict to that collection's parents and children."
+ [collection-id]
+ (if collection-id
+ [:and
+ [:like :location (str "%/" collection-id "/%")]
+ [:not [:like :location (str "%/" collection-id "/%/%/%")]]]
+ [:not [:like :location "/%/%/"]]))
+
+(defn- remove-other-users-personal-subcollections
+ [user-id collections]
+ (let [personal-ids (set (collections.db/other-users-personal-collection-ids user-id))
+ personal-descendant? (fn [collection]
+ (let [first-parent-collection-id (-> collection
+ :location
+ collection/location-path->ids
+ first)]
+ (personal-ids first-parent-collection-id)))]
+ (remove personal-descendant? collections)))
+
+(defn select-collections
+ "Select collections based off certain parameters. If `shallow` is true, we select only the requested collection (or
+ the root, if `collection-id` is `nil`) and its immediate children, to avoid reading the entire collection tree when it
+ is not necessary.
+
+ For archived, we can either include only archived items (when archived is truthy) or exclude archived items (when
+ archived is falsey).
+
+ The Trash Collection itself (the container for archived items) is *always* included.
+
+ This will select only collections where `personal_owner_id` is not `nil`.
+
+ To include library collections and their descendants, pass in `include-library?` as `true`.
+ By default, library-type collections are excluded. "
+ [{:keys [archived exclude-other-user-collections namespaces shallow collection-id personal-only include-library?]}]
+ (cond->>
+ (collections.db/collections-matching
+ {:where [:and
+ (case archived
+ nil nil
+ false [:and
+ [:not= :id (collection/trash-collection-id)]
+ [:not :archived]]
+ true [:or
+ [:= :id (collection/trash-collection-id)]
+ :archived])
+ (when shallow
+ (location-from-collection-id-clause collection-id))
+ (when personal-only
+ [:!= :personal_owner_id nil])
+ (when exclude-other-user-collections
+ [:or [:= :personal_owner_id nil] [:= :personal_owner_id api/*current-user-id*]])
+ (when-not include-library?
+ [:or [:= nil :type]
+ [:not-in :type [collection/library-collection-type
+ collection/library-data-collection-type
+ collection/library-metrics-collection-type]]])
+ [:or
+ (when (contains? namespaces nil)
+ [:= :namespace nil])
+ (when (seq namespaces)
+ [:in :namespace namespaces])]
+ (collection/visible-collection-filter-clause
+ :id
+ {:include-archived-items (if archived
+ :only
+ :exclude)
+ :include-trash-collection? true
+ :permission-level :read
+ :archive-operation-id nil})]
+ ;; Order NULL collection types first so that audit collections are last
+ :order-by [[[[:case [:= :authority_level "official"] 0 :else 1]] :asc]
+ [[[:case
+ [:= :type nil] 0
+ [:= :type collection/trash-collection-type] 1
+ :else 2]] :asc]
+ [:%lower.name :asc]]})
+ exclude-other-user-collections
+ (remove-other-users-personal-subcollections api/*current-user-id*)))
+
+(defn prep-collection-for-export
+ "Given a collection, tweaks it to be ready for returning to the FE.
+
+ These same functions were called in several places in this namespace, so they're combined here to keep it DRY."
+ [coll]
+ (-> coll
+ collection/personal-collection-with-ui-details
+ collection/maybe-localize-tenant-collection-name
+ collection/maybe-mark-collection-as-library-root))
+
+(defn shallow-tree-from-collection-id
+ "Returns only a shallow Collection in the provided collection-id, e.g.
+
+ location: /1/
+ ```
+ [{:name \"A\"
+ :location \"/1/\"
+ :children 1}
+ ...
+ {:name \"H\"
+ :location \"/1/\"}]
+
+ If the collection-id is nil, then we default to the root collection.
+ ```"
+ [colls]
+ (->> colls
+ (map prep-collection-for-export)
+ (collection/collections->tree nil)
+ (map (fn [coll] (update coll :children #(boolean (seq %)))))))
+
+(def ^:private valid-model-param-values
+ "Valid values for the `?model=` param accepted by the collection-items endpoints.
+ `no_models` is for nilling out the set because a nil model set is actually the total model set"
+ #{"card" ; SavedQuestion
+ "dataset" ; Model. TODO : update this
+ "document"
+ "exploration"
+ "metric"
+ "collection"
+ "dashboard"
+ "pulse" ; I think the only kinds of Pulses we still have are Alerts?
+ "snippet"
+ "no_models"
+ "timeline"
+ "table"
+ "transform"
+ "measure"})
+
+(def ^:private ModelString
+ (into [:enum] valid-model-param-values))
+
+(def Models
+ "This is basically a union type. [[api.macros/defendpoint]] splits the string if it only gets one."
+ [:vector {:decode/string (fn [x] (cond (vector? x) x x [x]))} ModelString])
+
+(def valid-pinned-state-values
+ "Valid values for the `?pinned-state=` param accepted by endpoints in this namespace."
+ #{"all" "is_pinned" "is_not_pinned"})
+
+(def valid-sort-columns
+ "Valid values for the `?sort-column=` param accepted by the collection-items endpoints."
+ #{"name" "last_edited_at" "last_edited_by" "model" "description"})
+(def valid-sort-directions
+ "Valid values for the `?sort-direction=` param accepted by the collection-items endpoints."
+ #{"asc" "desc"})
+(defn normalize-sort-choice
+ "Normalize a sort param string to the keyword form [[collection-children]] expects."
+ [w]
+ (when w (keyword (str/replace w #"_" "-"))))
+
+(def CollectionType
+ "Collection types that the root/items endpoint can filter on"
+ [:enum "remote-synced"])
+
+(def CollectionChildrenOptions
+ "The `options` map accepted by [[collection-children]] and [[collection-filter-metadata]]."
+ [:map
+ [:show-dashboard-questions? :boolean]
+ [:show-exploration-documents? {:optional true} [:maybe :boolean]]
+ [:collection-type {:optional true} [:maybe CollectionType]]
+ [:archived? :boolean]
+ [:include-library? {:optional true} [:maybe :boolean]]
+ [:pinned-state {:optional true} [:maybe (into [:enum] (map keyword) valid-pinned-state-values)]]
+ ;; when specified, only return results of this type.
+ [:models {:optional true} [:maybe [:set (into [:enum] (map keyword) valid-model-param-values)]]]
+ ;; when set, restrict results to items created by this user id; models without a creator
+ ;; column (see [[creator-filterable-models]]) return nothing.
+ [:created-by-id {:optional true} [:maybe pos-int?]]
+ [:search-text {:optional true} [:maybe :string]]
+ [:sort-info {:optional true} [:maybe [:map
+ [:sort-column (into [:enum {:error/message "sort-columns"}]
+ (map normalize-sort-choice)
+ valid-sort-columns)]
+ [:sort-direction (into [:enum {:error/message "sort-direction"}]
+ (map normalize-sort-choice)
+ valid-sort-directions)]
+ [:official-collections-first? {:optional true} :boolean]]]]])
+
+(def ^:private creator-filterable-models
+ "Child models carrying a `creator_id` a `:created-by-id` option can restrict on. When that
+ option is set, models absent here return nothing."
+ #{:card :dataset :metric :dashboard :document})
+
+(defmulti ^:private collection-children-query
+ "Query that will fetch the 'children' of a `collection`, for different types of objects. Possible options are listed
+ in the [[CollectionChildrenOptions]] schema above.
+
+ NOTES:
+
+ * `collection` will be either a CollectionInstance, or the Root Collection special placeholder object, so do not use
+ `u/the-id` on it! Use `:id`, which will return `nil` for the Root Collection, which is exactly what we want.
+
+ * These queries will be combined into a union-all query. You do not need to put all of the columns into the query,
+ any you don't select will be added in the correct position so the union will work (see `all-select-columns` for more
+ details)."
+ {:arglists '([model collection options])}
+ (fn [model _ _] (keyword model)))
+
+;;; TODO -- in Postgres and H2 at least I think we could just do `true` or `false` here... not sure about MySQL.
+
+(def ^:private always-true-hsql-expr
+ "A Honey SQL expression that is always true.
+
+ 1 = 1"
+ [:= [:inline 1] [:inline 1]])
+
+(def ^:private always-false-hsql-expr
+ "A Honey SQL expression that is never true.
+
+ 1 = 2"
+ [:= [:inline 1] [:inline 2]])
+
+(defn- search-text-clause
+ "Match every token in `search-text` against an item's name or last editor's first or last name."
+ [search-text]
+ (when-not (str/blank? search-text)
+ (when-let [tokens (->> (str/split (u/lower-case-en (str/trim search-text)) #"\s+")
+ (filter seq)
+ not-empty)]
+ (into [:and]
+ (for [token tokens
+ :let [pattern (h2x/like-substring token)]]
+ [:or
+ [:like [:lower :name] pattern]
+ [:like [:lower :last_edit_first_name] pattern]
+ [:like [:lower :last_edit_last_name] pattern]])))))
+
+(defn- pinned-state->clause
+ ([pinned-state]
+ (pinned-state->clause pinned-state :collection_position))
+ ([pinned-state col]
+ (case pinned-state
+ :all always-true-hsql-expr
+ :is_pinned [:<> col nil]
+ :is_not_pinned [:= col nil]
+ always-true-hsql-expr)))
+
+(defn- poison-when-pinned-clause
+ "Poison a query to return no results when filtering to pinned items. Use for items that do not have a notion of
+ pinning so that no results return when asking for pinned items."
+ [pinned-state]
+ (if (= pinned-state :is_pinned)
+ always-false-hsql-expr
+ always-true-hsql-expr))
+
+(defmulti ^:private post-process-collection-children
+ {:arglists '([model options collection rows])}
+ (fn [model _ _ _]
+ (keyword model)))
+
+(defmethod ^:private post-process-collection-children :default
+ [_ _ _ rows]
+ rows)
+
+(defmethod ^:private post-process-collection-children :document
+ [_ _ collection rows]
+ (map #(dissoc % :exploration_id)
+ (t2/hydrate (for [document rows]
+ (-> (t2/instance :model/Document document)
+ (assoc :location (or (when collection
+ (collection/children-location collection))
+ "/"))
+ (dissoc :namespace)
+ (update :archived api/bit->boolean)
+ (update :archived_directly api/bit->boolean)))
+ :can_write :can_restore :can_delete :is_remote_synced :collection_namespace)))
+
+(defmethod collection-children-query :document
+ [_ collection {:keys [archived? pinned-state created-by-id show-exploration-documents?]}]
+ (-> {:select [:document.id
+ :document.name
+ :document.collection_id
+ :document.collection_position
+ :document.archived
+ :document.archived_directly
+ :document.exploration_id
+ [:u.id :last_edit_user]
+ [:u.email :last_edit_email]
+ [:u.first_name :last_edit_first_name]
+ [:u.last_name :last_edit_last_name]
+ [:r.timestamp :last_edit_timestamp]
+ [(h2x/literal "document") :model]]
+ :from [[:document :document]]
+ :left-join [[:revision :r] [:and
+ [:= :r.model_id :document.id]
+ [:= :r.most_recent true]
+ [:= :r.model (h2x/literal "Document")]]
+ [:core_user :u] [:= :u.id :r.user_id]]
+ :where [:and
+ (collection/visible-collection-filter-clause :document.collection_id {:cte-name :visible_collection_ids})
+ (if (collection/is-trash? collection)
+ [:= :document.archived_directly true]
+ [:and
+ [:= :document.collection_id (:id collection)]
+ [:= :document.archived_directly false]])
+ (when created-by-id
+ [:= :document.creator_id created-by-id])
+ [:= :document.archived (boolean archived?)]
+ ;; Hide exploration-attached documents - similar to Dashboard Questions, they're not visible in the
+ ;; collection, but only through the Exploration they're in. Callers that want them (e.g. the
+ ;; Trash view, embedding SDK) pass show-exploration-documents? to opt in.
+ (when-not show-exploration-documents?
+ [:= :document.exploration_id nil])]}
+ (sql.helpers/where (pinned-state->clause pinned-state :document.collection_position))))
+
+(defmethod ^:private post-process-collection-children :exploration
+ [_ _ collection rows]
+ (t2/hydrate (for [exploration rows]
+ (-> (t2/instance :model/Exploration exploration)
+ (assoc :location (or (when collection
+ (collection/children-location collection))
+ "/"))
+ (update :archived api/bit->boolean)
+ (update :archived_directly api/bit->boolean)))
+ :can_write :can_restore :can_delete))
+
+(def ^:private exploration-recent-edits-subquery
+ ;; Per-exploration latest edit, unioning the Exploration's own metadata revisions with
+ ;; revisions of its Summary Document. `rn = 1` picks the winner.
+ ;; The Exploration row is mostly inert post-creation; the meat of editing happens in
+ ;; the attached Document, so "Last edited" must reflect both sources.
+ ^:allow-subquery
+ {:select [:exploration_id
+ :timestamp
+ :user_id
+ [[:over [[:row_number] ^:allow-subquery {:partition-by [:exploration_id]
+ :order-by [[:timestamp :desc]]}]] :rn]]
+ :from [[^:allow-subquery {:union-all
+ [^:allow-subquery
+ {:select [[:r.model_id :exploration_id]
+ [:r.timestamp :timestamp]
+ [:r.user_id :user_id]]
+ :from [[:revision :r]]
+ :where [:and
+ [:= :r.model (h2x/literal "Exploration")]
+ [:= :r.most_recent true]]}
+ ^:allow-subquery
+ {:select [[:d.exploration_id :exploration_id]
+ [:r.timestamp :timestamp]
+ [:r.user_id :user_id]]
+ :from [[:revision :r]]
+ :join [[:document :d] [:= :d.id :r.model_id]]
+ :where [:and
+ [:= :r.model (h2x/literal "Document")]
+ [:= :r.most_recent true]
+ [:not= :d.exploration_id nil]]}]}
+ :all_edits]]})
+
+(defmethod collection-children-query :exploration
+ [_ collection {:keys [archived? pinned-state]}]
+ (-> {:select [:exploration.id
+ :exploration.name
+ :exploration.description
+ :exploration.entity_id
+ :exploration.collection_id
+ :exploration.collection_position
+ :exploration.archived
+ :exploration.archived_directly
+ [:u.id :last_edit_user]
+ [:u.email :last_edit_email]
+ [:u.first_name :last_edit_first_name]
+ [:u.last_name :last_edit_last_name]
+ [:ere.timestamp :last_edit_timestamp]
+ [(h2x/literal "exploration") :model]]
+ :from [[:exploration :exploration]]
+ :left-join [[exploration-recent-edits-subquery :ere]
+ [:and
+ [:= :ere.exploration_id :exploration.id]
+ [:= :ere.rn [:inline 1]]]
+ [:core_user :u] [:= :u.id :ere.user_id]]
+ :where [:and
+ (collection/visible-collection-filter-clause :exploration.collection_id {:cte-name :visible_collection_ids})
+ (if (collection/is-trash? collection)
+ [:= :exploration.archived_directly true]
+ [:and
+ [:= :exploration.collection_id (:id collection)]
+ [:= :exploration.archived_directly false]])
+ [:= :exploration.archived (boolean archived?)]]}
+ (sql.helpers/where (pinned-state->clause pinned-state :exploration.collection_position))))
+
+(defmethod collection-children-query :pulse
+ [_ collection {:keys [archived? pinned-state]}]
+ (-> {:select-distinct [:p.id
+ :p.name
+ :p.entity_id
+ :p.collection_position
+ :p.collection_id
+ [(h2x/literal "pulse") :model]]
+ :from [[:pulse :p]]
+ :left-join [[:pulse_card :pc] [:= :p.id :pc.pulse_id]]
+ :where [:and
+ [:= :p.collection_id (:id collection)]
+ [:= :p.archived (boolean archived?)]
+ ;; exclude alerts
+ [:= :p.alert_condition nil]
+ ;; exclude dashboard subscriptions
+ [:= :p.dashboard_id nil]]}
+ (sql.helpers/where (pinned-state->clause pinned-state :p.collection_position))))
+
+(defmethod post-process-collection-children :pulse
+ [_ _ _ rows]
+ (for [row rows]
+ (dissoc row
+ :description :display :authority_level :moderated_status :icon :personal_owner_id :namespace
+ :collection_preview :dataset_query :table_id :query_type :is_upload :collection_namespace)))
+
+(defenterprise snippets-collection-children-query
+ "Collection children query for snippets on OSS. Returns all snippets regardless of collection, because snippet
+ collections are an EE feature."
+ metabase-enterprise.snippet-collections.api.native-query-snippet
+ [_collection {:keys [archived?]}]
+ {:select [:id :name :entity_id [(h2x/literal "snippet") :model]]
+ :from [[:native_query_snippet :nqs]]
+ :where [:= :archived (boolean archived?)]})
+
+(defmethod collection-children-query :snippet
+ [_model collection options]
+ (snippets-collection-children-query collection options))
+
+(defmethod collection-children-query :timeline
+ [_ collection {:keys [archived? pinned-state]}]
+ {:select [:id :collection_id :name [(h2x/literal "timeline") :model] :description :entity_id :icon]
+ :from [[:timeline :timeline]]
+ :where [:and
+ (poison-when-pinned-clause pinned-state)
+ [:= :collection_id (:id collection)]
+ [:= :archived (boolean archived?)]]})
+
+(defmethod collection-children-query :transform
+ [_model collection {:keys [pinned-state]}]
+ (let [enabled-types (transforms.u/enabled-source-types-for-user)]
+ {:select [:id :collection_id :name [(h2x/literal "transform") :model] :description :entity_id]
+ :from [[:transform :transform]]
+ :where [:and
+ (poison-when-pinned-clause pinned-state)
+ [:= :collection_id (:id collection)]
+ (if (seq enabled-types)
+ [:in :source_type enabled-types]
+ [:=
+ [:inline 0]
+ [:inline 1]])]}))
+
+(defmethod post-process-collection-children :timeline
+ [_ _options _collection rows]
+ (for [row rows]
+ (dissoc row
+ :description :display :collection_position :authority_level :moderated_status
+ :collection_preview :dataset_query :table_id :query_type :is_upload :namespace)))
+
+(defmethod post-process-collection-children :snippet
+ [_ _options _collection rows]
+ (for [row rows]
+ (-> (dissoc row
+ :description :collection_position :display :authority_level
+ :moderated_status :icon :personal_owner_id :collection_preview
+ :dataset_query :table_id :query_type :is_upload :namespace)
+ (assoc :collection_namespace "snippets"))))
+
+(defn- card-query [card-type collection {:keys [archived? pinned-state show-dashboard-questions? created-by-id]}]
+ (-> {:select (cond->
+ [:c.id :c.name :c.description :c.entity_id :c.collection_position :c.display :c.collection_preview
+ :dashboard_id
+ :last_used_at
+ :c.collection_id
+ :c.archived_directly
+ :c.archived
+ :c.dataset_query
+ [(h2x/literal (case card-type
+ :model "dataset"
+ :metric "metric"
+ "card"))
+ :model]
+ [:u.id :last_edit_user]
+ [:u.email :last_edit_email]
+ [:u.first_name :last_edit_first_name]
+ [:u.last_name :last_edit_last_name]
+ [:r.timestamp :last_edit_timestamp]
+ [:mr.status :moderated_status]]
+ (#{:question :model} card-type)
+ (conj :c.database_id))
+ :from [[:report_card :c]]
+ :left-join [[:revision :r] [:and
+ [:= :r.model_id :c.id]
+ [:= :r.most_recent true]
+ [:= :r.model (h2x/literal "Card")]]
+ [:moderation_review :mr] [:and
+ [:= :mr.moderated_item_id :c.id]
+ [:= :mr.most_recent true]
+ [:= :mr.moderated_item_type (h2x/literal "card")]]
+ [:core_user :u] [:= :u.id :r.user_id]]
+ :where [:and
+ (collection/visible-collection-filter-clause :c.collection_id {:cte-name :visible_collection_ids})
+ (if (collection/is-trash? collection)
+ [:= :c.archived_directly true]
+ [:and
+ [:= :c.collection_id (:id collection)]
+ [:= :c.archived_directly false]])
+ (when-not show-dashboard-questions?
+ [:= :c.dashboard_id nil])
+ [:= :c.document_id nil]
+ (when created-by-id
+ [:= :c.creator_id created-by-id])
+ [:= :c.archived (boolean archived?)]
+ (case card-type
+ :model
+ [:= :c.type (h2x/literal "model")]
+
+ :metric
+ [:= :c.type (h2x/literal "metric")]
+
+ [:= :c.type (h2x/literal "question")])]}
+ (cond-> (= :model card-type)
+ (-> (sql.helpers/select :c.table_id :t.is_upload :c.query_type)
+ (sql.helpers/left-join [:metabase_table :t] [:= :t.id :c.table_id])))
+ (sql.helpers/where (pinned-state->clause pinned-state))))
+
+(defmethod collection-children-query :dataset
+ [_ collection options]
+ (card-query :model collection options))
+
+(defmethod collection-children-query :metric
+ [_ collection options]
+ (card-query :metric collection options))
+
+(defmethod collection-children-query :card
+ [_ collection options]
+ (card-query :question collection options))
+
+(defn- post-process-card-row [row]
+ (-> (t2/instance :model/Card row)
+ ;; `card-query` filters `[:= :c.document_id nil]` unconditionally, so every row here is known
+ ;; not to belong to a Document. Say so on the instance: `mi/can-write?` consults `document_id`
+ ;; (a Document-scoped Card is gated by its Document), and an instance that merely *omits* the
+ ;; column makes it resolve one from the primary key instead — one extra query per row, on a
+ ;; listing that renders a full page of them. Stamping it rather than selecting it keeps the
+ ;; column out of `all-select-columns`, which every model's union arm would otherwise have to
+ ;; pad, and out of the response body.
+ (assoc :document_id nil)
+ (update :dataset_query (:out lib-be/transform-query))
+ (update :collection_preview api/bit->boolean)
+ (update :archived api/bit->boolean)
+ (update :archived_directly api/bit->boolean)))
+
+(defn- post-process-card-row-after-hydrate [row]
+ (-> (dissoc row :authority_level :icon :personal_owner_id :dataset_query :table_id :query_type :is_upload :namespace
+ ;; internal-only: stamped in `post-process-card-row` for the permission check
+ :document_id)
+ (update :dashboard #(when % (select-keys % [:id :name :moderation_status])))
+ (assoc :fully_parameterized (queries/fully-parameterized? row))))
+
+(defn- post-process-card-like
+ [{:keys [hydrate-based-on-upload]} rows]
+ (let [hydration [:can_write
+ :can_restore
+ :can_delete
+ :dashboard_count
+ :is_remote_synced
+ :collection_namespace
+ [:dashboard :moderation_status]]]
+ (as-> (map post-process-card-row rows) $
+ (apply t2/hydrate $ hydration)
+ (cond-> $
+ hydrate-based-on-upload upload/model-hydrate-based-on-upload)
+ (map post-process-card-row-after-hydrate $))))
+
+(defmethod post-process-collection-children :card
+ [_ options _ rows]
+ (post-process-card-like options rows))
+
+(defmethod post-process-collection-children :metric
+ [_ options _ rows]
+ (post-process-card-like options rows))
+
+(defmethod post-process-collection-children :dataset
+ [_ options _ rows]
+ (post-process-card-like (assoc options :hydrate-based-on-upload true) rows))
+
+(defn- dashboard-query [collection {:keys [archived? pinned-state created-by-id]}]
+ (-> {:select [:d.id :d.name :d.description :d.entity_id :d.collection_position
+ [:last_viewed_at :last_used_at]
+ :d.collection_id
+ :d.archived_directly
+ [(h2x/literal "dashboard") :model]
+ [:u.id :last_edit_user]
+ :d.archived
+ [:u.email :last_edit_email]
+ [:u.first_name :last_edit_first_name]
+ [:u.last_name :last_edit_last_name]
+ [:r.timestamp :last_edit_timestamp]
+ [:mr.status :moderated_status]]
+ :from [[:report_dashboard :d]]
+ :left-join [[:moderation_review :mr] [:and
+ [:= :mr.moderated_item_id :d.id]
+ [:= :mr.most_recent true]
+ [:= :mr.moderated_item_type (h2x/literal "dashboard")]]
+ [:revision :r] [:and
+ [:= :r.model_id :d.id]
+ [:= :r.most_recent true]
+ [:= :r.model (h2x/literal "Dashboard")]]
+ [:core_user :u] [:= :u.id :r.user_id]]
+ :where [:and
+ (collection/visible-collection-filter-clause :d.collection_id {:cte-name :visible_collection_ids})
+ (if (collection/is-trash? collection)
+ [:= :d.archived_directly true]
+ [:and
+ [:= :d.collection_id (:id collection)]
+ [:not= :d.archived_directly true]])
+ (when created-by-id
+ [:= :d.creator_id created-by-id])
+ [:= :d.archived (boolean archived?)]]}
+ (sql.helpers/where (pinned-state->clause pinned-state))))
+
+(defmethod collection-children-query :dashboard
+ [_ collection options]
+ (dashboard-query collection options))
+
+(defn- post-process-dashboard [parent-collection dashboard]
+ (-> (t2/instance :model/Dashboard dashboard)
+ (assoc :location (or (when parent-collection
+ (collection/children-location parent-collection))
+ "/"))
+ (assoc :is_tenant_dashboard (collection/shared-tenant-collection? parent-collection))
+ (update :archived api/bit->boolean)
+ (update :archived_directly api/bit->boolean)
+ (t2/hydrate :can_write :can_restore :can_delete :is_remote_synced :collection_namespace)
+ (dissoc :display :authority_level :icon :personal_owner_id :collection_preview
+ :dataset_query :table_id :query_type :is_upload)))
+
+(defmethod post-process-collection-children :dashboard
+ [_ _options parent-collection rows]
+ (->> rows
+ collections.util/annotate-dashboards
+ (map (partial post-process-dashboard parent-collection))))
+
+(defenterprise snippets-collection-filter-clause
+ "Clause to filter out snippet collections from the collection query on OSS instances, and instances without the
+ snippet-collections. EE implementation returns `nil`, so as to not filter out snippet collections."
+ metabase-enterprise.snippet-collections.api.native-query-snippet
+ []
+ [:or
+ [:= :namespace nil]
+ [:not= :namespace (u/qualified-name "snippets")]])
+
+(defn- collection-query
+ [collection {:keys [archived? collection-namespace pinned-state collection-type include-library?]}]
+ (-> (assoc
+ (collection/effective-children-query
+ collection
+ {:cte-name :visible_collection_ids}
+ [:and
+ (when collection-type
+ (if (= collection-type "remote-synced")
+ [:= :is_remote_synced true]
+ [:= :type collection-type]))
+ (when-not include-library?
+ [:or [:= nil :type]
+ [:not [:in :type [collection/library-collection-type
+ collection/library-metrics-collection-type
+ collection/library-data-collection-type]]]])
+ (if archived?
+ [:or
+ [:= :archived true]
+ [:= :id (collection/trash-collection-id)]]
+ [:and [:= :archived false] [:not= :id (collection/trash-collection-id)]])]
+ (perms/namespace-clause :namespace (u/qualified-name collection-namespace) (collection/is-trash? collection))
+ ;; never show tenant-specific root collections as children of another collection
+ [:or
+ [:= :type nil]
+ [:not= :type collection/tenant-specific-root-collection-type]]
+ (snippets-collection-filter-clause))
+ ;; We get from the effective-children-query a normal set of columns selected:
+ ;; want to make it fit the others to make UNION ALL work
+ :select [:id
+ [:id :collection_id]
+ :archived
+ :name
+ :description
+ :entity_id
+ :personal_owner_id
+ :location
+ :archived_directly
+ :namespace
+ ;; selected as `type` for compatibility with collection fns that expect it
+ :type
+ [[:case [:= :is_remote_synced nil] [:inline false] :else :is_remote_synced] :is_remote_synced]
+ ;; selected as `collection_type` for fast sorting on "when it's a collection, type"
+ [:type :collection_type]
+ [(h2x/literal "collection") :model]
+ :authority_level])
+ ;; the nil indicates that collections are never pinned.
+ (sql.helpers/where (pinned-state->clause pinned-state nil))))
+
+(defmethod collection-children-query :collection
+ [_ collection options]
+ (collection-query collection options))
+
+(defmethod collection-children-query :table
+ [_ collection {:keys [archived? pinned-state]}]
+ (let [user-info {:user-id api/*current-user-id*
+ :is-superuser? api/*is-superuser?*}
+ published-clause (perms/published-table-visible-clause :t.id user-info)
+ queryable-clause (cond-> [:or
+ [:in :t.id (perms/visible-table-filter-select
+ :id
+ user-info
+ {:perms/view-data :unrestricted
+ :perms/create-queries :query-builder})]]
+ published-clause (conj [:and
+ [:in :t.id (perms/visible-table-filter-select
+ :id
+ user-info
+ {:perms/view-data :unrestricted})]
+ published-clause]))]
+ {:select [:t.id
+ [:t.id :table_id]
+ [:t.display_name :name]
+ :t.description
+ :t.collection_id
+ [:t.db_id :database_id]
+ [[:!= :t.archived_at nil] :archived]
+ [(h2x/literal "table") :model]]
+ :from [[:metabase_table :t]]
+ :where [:and
+ [:= :t.is_published true]
+ (poison-when-pinned-clause pinned-state)
+ (collection/visible-collection-filter-clause :t.collection_id {:cte-name :visible_collection_ids})
+ queryable-clause
+ [:= :t.collection_id (:id collection)]
+ (if archived?
+ [:!= :t.archived_at nil]
+ [:= :t.archived_at nil])]}))
+
+(defn- annotate-collections
+ [parent-coll colls {:keys [show-dashboard-questions?]}]
+ (let [descendant-collections (collection/descendants-flat parent-coll nil
+ (collection/visible-collection-filter-clause
+ :id
+ {:include-archived-items :all}))
+
+ descendant-collection-ids (mapv u/the-id descendant-collections)
+
+ child-type->coll-id-set
+ (reduce (fn [acc {collection-id :collection_id, card-type :type, :as _card}]
+ (update acc (case (keyword card-type)
+ :model :dataset
+ :metric :metric
+ :card) conj collection-id))
+ {:dataset #{}
+ :metric #{}
+ :card #{}}
+ (when (seq descendant-collection-ids)
+ (collections.db/unarchived-card-collection-types-in-reducible
+ descendant-collection-ids
+ (not show-dashboard-questions?))))
+
+ ;; Tables in collections are an EE feature (library)
+ collections-containing-tables
+ (if (premium-features/has-feature? :library)
+ (->> (when (seq descendant-collection-ids)
+ (collections.db/published-table-collection-ids-in descendant-collection-ids))
+ (map :collection_id)
+ (into #{}))
+ #{})
+
+ collections-containing-transforms
+ (if (seq (transforms.gating/enabled-source-types))
+ (->> (when (seq descendant-collection-ids)
+ (collections.db/transform-collection-ids-in descendant-collection-ids (transforms.gating/enabled-source-types)))
+ (map :collection_id)
+ (into #{}))
+ #{})
+
+ collections-containing-dashboards
+ (->> (when (seq descendant-collection-ids)
+ (collections.db/unarchived-dashboard-collection-ids-in descendant-collection-ids))
+ (map :collection_id)
+ (into #{}))
+
+ ;; the set of collections that contain collections (in terms of *effective* location)
+ collections-containing-collections
+ (->> (t2/hydrate descendant-collections :effective_parent :is_remote_synced)
+ (reduce (fn [accu {:keys [effective_parent] :as _coll}]
+ (let [parent-id (:id effective_parent)]
+ (conj accu parent-id)))
+ #{}))
+
+ child-type->coll-id-set
+ (merge child-type->coll-id-set
+ {:table collections-containing-tables
+ :collection collections-containing-collections
+ :dashboard collections-containing-dashboards
+ :transform collections-containing-transforms})
+
+ ;; why are we calling `annotate-collections` on all descendants, when we only need the collections in `colls`
+ ;; to be annotated? Because `annotate-collections` works by looping through the collections it's passed and
+ ;; using them to figure out the ancestors of a given collection. This could use a refactor - probably the
+ ;; caller of `annotate-collections` could be generating both `child-type->parent-ids` and
+ ;; `child-type->ancestor-ids`.
+ coll-id->annotated (m/index-by :id (collection/annotate-collections child-type->coll-id-set descendant-collections))]
+ (for [coll colls]
+ (merge coll (select-keys (coll-id->annotated (:id coll)) [:here :below])))))
+
+(defmethod post-process-collection-children :collection
+ [_ options parent-collection rows]
+ (letfn [(update-personal-collection [{:keys [personal_owner_id] :as row}]
+ (if personal_owner_id
+ ;; when fetching root collection, we might have personal collection
+ (assoc row :name (collection/user->personal-collection-name (:personal_owner_id row) :user))
+ (dissoc row :personal_owner_id)))]
+ (for [row (annotate-collections parent-collection rows options)]
+ (let [type-value (:type row)]
+ (-> (t2/instance :model/Collection row)
+ collection/maybe-localize-system-collection-name
+ collection/maybe-localize-tenant-collection-name
+ collection/maybe-mark-collection-as-library-root
+ (update :archived api/bit->boolean)
+ (update :is_remote_synced api/bit->boolean)
+ (t2/hydrate :can_write :effective_location :can_restore :can_delete :is_shared_tenant_collection)
+ (dissoc :collection_position :display :moderated_status :icon
+ :collection_preview :dataset_query :table_id :query_type :is_upload)
+ (assoc :type type-value)
+ update-personal-collection)))))
+
+(defmethod post-process-collection-children :table
+ [_ {:keys [models]} _collection rows]
+ (let [tables (map #(-> (t2/instance :model/Table %)
+ (update :archived api/bit->boolean)) rows)]
+ (if (contains? models :measure)
+ (t2/hydrate tables :measures)
+ tables)))
+
+;;; TODO -- consider whether this function belongs here or in [[metabase.revisions.models.revision.last-edit]]
+(mu/defn- coalesce-edit-info :- revisions/MaybeAnnotated
+ "Hoist all of the last edit information into a map under the key :last-edit-info. Considers this information present
+ if `:last_edit_user` is not nil."
+ [row]
+ (letfn [(select-as [original k->k']
+ (reduce (fn [m [k k']] (assoc m k' (get original k)))
+ {}
+ k->k'))]
+ (let [mapping {:last_edit_user :id
+ :last_edit_last_name :last_name
+ :last_edit_first_name :first_name
+ :last_edit_email :email
+ :last_edit_timestamp :timestamp}]
+ (cond-> (apply dissoc row (keys mapping))
+ ;; don't use contains as they all have the key, we care about a value present
+ (:last_edit_user row) (assoc :last-edit-info (select-as row mapping))))))
+
+(defn- remove-unwanted-keys [{:keys [model] :as row}]
+ (cond-> (dissoc row :model_ranking :archived_directly :total_count :collection_type)
+ (not= model "collection") (dissoc :type)))
+
+(defn- model-name->toucan-model [model-name]
+ (case (keyword model-name)
+ :collection :model/Collection
+ :card :model/Card
+ :dataset :model/Card
+ :metric :model/Card
+ :dashboard :model/Dashboard
+ :document :model/Document
+ :exploration :model/Exploration
+ :pulse :model/Pulse
+ :snippet :model/NativeQuerySnippet
+ :table :model/Table
+ :timeline :model/Timeline
+ :transform :model/Transform))
+
+(defn post-process-rows
+ "Post process any data. Have a chance to process all of the same type at once using
+ `post-process-collection-children`. Must respect the order passed in."
+ [options collection rows]
+ (->> (map-indexed (fn [i row] (vary-meta row assoc ::index i)) rows) ;; keep db sort order
+ (group-by :model)
+ (into []
+ (comp (map (fn [[model rows]]
+ (post-process-collection-children (keyword model) options collection rows)))
+ cat
+ (map coalesce-edit-info)))
+ (map remove-unwanted-keys)
+ ;; the collection these are presented "in" is the ID of the collection we're getting `/items` on.
+ (map #(assoc % :collection_id (:id collection)))
+ (sort-by (comp ::index meta))))
+
+(defn- select-name
+ "Takes a honeysql select column and returns a keyword of which column it is.
+
+ eg:
+ (select-name :id) -> :id
+ (select-name [(literal \"card\") :model]) -> :model
+ (select-name :p.id) -> :id"
+ [x]
+ (if (vector? x)
+ (recur (second x))
+ (-> x name (str/split #"\.") peek keyword)))
+
+(def ^:private all-select-columns
+ "All columns that need to be present for the union-all. Generated with the comment form below. Non-text columns that
+ are optional (not id, but last_edit_user for example) must have a type so that the union-all can unify the nil with
+ the correct column type."
+ [:id :name :description :entity_id :display [:collection_preview :boolean] :dataset_query
+ :collection_id
+ [:dashboard_id :integer]
+ [:archived_directly :boolean]
+ :model :collection_position :authority_level [:personal_owner_id :integer] :location
+ :last_edit_email :last_edit_first_name :last_edit_last_name :moderated_status :icon
+ [:last_edit_user :integer] [:last_edit_timestamp :timestamp] [:database_id :integer]
+ :collection_type :type [:archived :boolean] [:last_used_at :timestamp] [:is_remote_synced :boolean] :namespace
+ ;; for determining whether a model is based on a csv-uploaded table
+ [:table_id :integer] [:is_upload :boolean] :query_type])
+
+(defn- add-missing-columns
+ "Ensures that all necessary columns are in the select-columns collection, adding `[nil :column]` as necessary."
+ [select-columns necessary-columns]
+ (let [columns (m/index-by select-name select-columns)]
+ (map (fn [col]
+ (let [[col-name type'] (u/one-or-many col)]
+ (get columns col-name (if (and type' (= (mdb/db-type) :postgres))
+ [(h2x/cast type' nil) col-name]
+ [nil col-name]))))
+ necessary-columns)))
+
+(defn- add-model-ranking
+ [select-clause model]
+ (let [rankings {:dashboard 1
+ :pulse 2
+ :dataset 3
+ :metric 4
+ :card 5
+ :snippet 6
+ :collection 7
+ :timeline 8}]
+ (conj select-clause [[:inline (get rankings model 100)]
+ :model_ranking])))
+
+(comment
+ ;; generate the set of columns across all child queries. Remember to add type info if not a text column
+ (into []
+ (comp cat (map select-name) (distinct))
+ (for [model [:card :metric :dataset :dashboard :snippet :pulse :collection :timeline]]
+ (:select (collection-children-query model {:id 1 :location "/"} nil)))))
+
+(defn- official-collections-first-sort-clause [{:keys [official-collections-first?]}]
+ (when official-collections-first?
+ [:authority_level :asc :nulls-last]))
+
+(def ^:private normal-collections-first-sort-clause
+ [:type :asc :nulls-first])
+
+(defn children-sort-clause
+ "Given the client side sort-info, return sort clause to effect this. `db-type` is necessary due to complications from
+ treatment of nulls in the different app db types."
+ [sort-info db-type]
+ (into []
+ (comp cat
+ (remove nil?))
+ [[(official-collections-first-sort-clause sort-info)]
+ [normal-collections-first-sort-clause]
+ (case ((juxt :sort-column :sort-direction) sort-info)
+ [nil nil] [[:%lower.name :asc]]
+ [:name :asc] [[:%lower.name :asc]]
+ [:name :desc] [[:%lower.name :desc]]
+ [:last-edited-at :asc] [(if (= db-type :mysql)
+ [:%isnull.last_edit_timestamp]
+ [:last_edit_timestamp :nulls-last])
+ [:last_edit_timestamp :asc]
+ [:%lower.name :asc]]
+ [:last-edited-at :desc] [(case db-type
+ :mysql [:%isnull.last_edit_timestamp]
+ :postgres [:last_edit_timestamp :desc-nulls-last]
+ :h2 nil)
+ [:last_edit_timestamp :desc]
+ [:%lower.name :asc]]
+ [:last-edited-by :asc] [(if (= db-type :mysql)
+ [:%isnull.last_edit_last_name]
+ [:last_edit_last_name :nulls-last])
+ [:last_edit_last_name :asc]
+ (if (= db-type :mysql)
+ [:%isnull.last_edit_first_name]
+ [:last_edit_first_name :nulls-last])
+ [:last_edit_first_name :asc]
+ [:%lower.name :asc]]
+ [:last-edited-by :desc] [(case db-type
+ :mysql [:%isnull.last_edit_last_name]
+ :postgres [:last_edit_last_name :desc-nulls-last]
+ :h2 nil)
+ [:last_edit_last_name :desc]
+ (case db-type
+ :mysql [:%isnull.last_edit_first_name]
+ :postgres [:last_edit_last_name :desc-nulls-last]
+ :h2 nil)
+ [:last_edit_first_name :desc]
+ [:%lower.name :asc]]
+ [:model :asc] [[:model_ranking :asc] [:%lower.name :asc]]
+ [:model :desc] [[:model_ranking :desc] [:%lower.name :asc]]
+ [:description :asc] [[:%lower.description :asc :nulls-last] [:%lower.name :asc]]
+ [:description :desc] [[:%lower.description :desc :nulls-last] [:%lower.name :asc]])
+ ;; add a fallback sort order so paging is still deterministic even if collection have the same name or
+ ;; whatever
+ [[:id :asc]]]))
+
+(defn- total-count
+ "The size of the whole result set `rows` is a page of, read off the `total_count` window column.
+
+ A page past the end of the result set comes back empty and so carries no window column; in that case read the count
+ off the first row of the same query without its pagination."
+ [rows rows-query offset]
+ (or (some-> rows first :total_count)
+ (when (pos? (or offset 0))
+ (some-> (collections.db/collection-children-rows (assoc rows-query :limit 1)) first :total_count))
+ 0))
+
+(defn- collection-children*
+ [collection models {:keys [sort-info archived? search-text] :as options}]
+ (let [sql-order (children-sort-clause sort-info (mdb/db-type))
+ models (sort (map keyword models))
+ queries (for [model models
+ :let [query (collection-children-query model collection options)
+ select-clause-type (some
+ (fn [k]
+ (when (get query k)
+ k))
+ [:select :select-distinct])]]
+ (-> query
+ (update select-clause-type add-missing-columns all-select-columns)
+ (update select-clause-type add-model-ranking model)))
+ viz-config {:include-archived-items :all
+ :archive-operation-id nil
+ :permission-level (if archived? :write :read)
+ :include-trash-collection? archived?}
+ search-clause (search-text-clause search-text)
+ rows-query (cond-> {:with [[:visible_collection_ids (collection/visible-collection-query viz-config)]]
+ :select [:* [[:over [[:count :*] ^:allow-subquery {} :total_count]]]]
+ :from [[^:allow-subquery {:union-all queries} :dummy_alias]]
+ :order-by sql-order}
+ search-clause
+ (sql.helpers/where search-clause))
+ limit (request/limit)
+ offset (request/offset)
+ count-only? (= limit 0)
+ ;; We didn't implement collection pagination for snippets namespace for root/items
+ ;; Rip out the limit for now and put it back in when we want it. A count-only request still
+ ;; needs a LIMIT so it doesn't fetch the whole snippets table just to read :total_count.
+ limit-query (if (or
+ (nil? limit)
+ (nil? offset)
+ (and (= (:collection-namespace options) "snippets")
+ (not count-only?)))
+ rows-query
+ (assoc rows-query
+ ;; If limit is 0, we still execute the query with a limit of 1 so that we fetch a
+ ;; :total_count
+ :limit (if count-only? 1 limit)
+ :offset offset))
+ rows (tracing/with-span :db-app "db-app.collection-items-query" {:collection/id (:id collection)}
+ (collections.db/collection-children-rows limit-query))
+ res {:total (total-count rows rows-query offset)
+ :data (if count-only?
+ []
+ (tracing/with-span :db-app "db-app.collection-items-post-process" {:collection/id (:id collection)}
+ (post-process-rows options collection rows)))
+ :models models}
+ limit-res (assoc res
+ :limit (request/limit)
+ :offset (request/offset))]
+ (if (= (:collection-namespace options) "snippets")
+ res
+ limit-res)))
+
+(defn- valid-collection-models
+ "Return every item model that can appear in `collection-namespace`."
+ [collection-namespace]
+ (for [model-kw (cond-> [:collection :dataset :metric :card :dashboard :pulse :snippet :timeline :document :exploration :transform]
+ ;; Tables in collections are an EE feature (library)
+ (premium-features/has-feature? :library) (conj :table))
+ :let [toucan-model (model-name->toucan-model model-kw)
+ allowed-namespaces (collection/allowed-namespaces toucan-model)]
+ :when (or (= model-kw :collection)
+ (contains? allowed-namespaces (keyword collection-namespace)))]
+ model-kw))
+
+(mu/defn collection-children
+ "Fetch a sequence of 'child' objects belonging to a Collection, filtered using `options`."
+ [{collection-namespace :namespace, :as collection} :- collection/CollectionWithLocationAndIDOrRoot
+ {:keys [models created-by-id], :as options} :- CollectionChildrenOptions]
+ (let [valid-models (for [model-kw (cond-> [:collection :dataset :metric :card :dashboard :pulse :snippet :timeline :document :exploration :transform]
+ ;; Tables in collections are an EE feature (library)
+ (premium-features/has-feature? :library) (conj :table))
+ ;; only fetch models that are specified by the `model` param; or everything if it's empty
+ :when (or (empty? models) (contains? models model-kw))
+ ;; a creator filter drops models that don't index a creator
+ :when (or (nil? created-by-id) (contains? creator-filterable-models model-kw))
+ :let [toucan-model (model-name->toucan-model model-kw)
+ allowed-namespaces (collection/allowed-namespaces toucan-model)]
+ :when (or (= model-kw :collection)
+ (contains? allowed-namespaces (keyword collection-namespace)))]
+ model-kw)]
+ (if (seq valid-models)
+ (collection-children* collection valid-models (assoc options :collection-namespace collection-namespace))
+ {:total 0
+ :data []
+ :limit (request/limit)
+ :offset (request/offset)
+ :models valid-models})))
+
+(defn filterable-models
+ "The models that can appear as a filterable item of `collection`. Snippets are never included: they are not a
+ filterable type. When present, `restrict-models` limits the set."
+ [collection restrict-models]
+ (cond->> (remove #{:snippet} (valid-collection-models (:namespace collection)))
+ (seq restrict-models) (filter restrict-models)))
+
+(mu/defn collection-filter-metadata :- [:map
+ [:available_models [:sequential :string]]]
+ "Return the models that have at least one visible item in `collection`. Respect the requested scope and visibility,
+ but ignore model and search filters. When present, `restrict-models` limits the candidate models. Snippets are never
+ reported: they are not a filterable type."
+ [collection :- collection/CollectionWithLocationAndIDOrRoot
+ restrict-models :- [:maybe [:set :keyword]]
+ {:keys [archived?] :as options} :- CollectionChildrenOptions]
+ (let [candidates (filterable-models collection restrict-models)
+ options (-> options
+ (dissoc :models :search-text)
+ (assoc :collection-namespace (:namespace collection)))]
+ ;; This result is independent of search and model filters. Requesting it with every filter update
+ ;; repeats the same EXISTS probes; a separately cached request could avoid that work.
+ (if (empty? candidates)
+ {:available_models []}
+ (let [viz-config {:include-archived-items :all
+ :archive-operation-id nil
+ :permission-level (if archived? :write :read)
+ :include-trash-collection? archived?}
+ row (first
+ (collections.db/collection-filter-metadata-rows
+ {:with [[:visible_collection_ids (collection/visible-collection-query viz-config)]]
+ :select (vec
+ (for [model candidates]
+ [[:exists (collection-children-query model collection options)] model]))}))]
+ {:available_models
+ (->> candidates
+ (keep (fn [model]
+ (when (api/bit->boolean (get row model))
+ (name model))))
+ sort
+ vec)}))))
+
+(defn visible-model-kwds
+ "If you pass in explicitly keywords that you can't see, you can't see them.
+ But there is an exception for the collections,
+ because you might not be able to see the top-level collections
+ but be able to see, children of those invisible top-level collections."
+ [root-collection model-set]
+ (if (mi/can-read? root-collection)
+ model-set
+ (if (or (empty? model-set) (contains? model-set :collection))
+ #{:collection}
+ #{:no_models})))
+
+(def namespaces-holding-non-collection-types
+ "We can't really *know* what namespace something with a `nil` `collection_id` is in, unless it's one of the special
+ types that can only live in one namespace.
+
+ If you're looking in the root collection of one of these namespaces, we'll allow you to list any type of model.
+
+ Otherwise, we'll just show you collections."
+ #{nil "snippets" "transforms"})
diff --git a/src/metabase/collections/core.clj b/src/metabase/collections/core.clj
index d0503827020..cea50b3858f 100644
--- a/src/metabase/collections/core.clj
+++ b/src/metabase/collections/core.clj
@@ -3,17 +3,21 @@
(:require
[metabase.collections.create]
[metabase.collections.models.collection]
+ [metabase.collections.update]
[metabase.collections.util]
[potemkin :as p]))
(comment
metabase.collections.create/keep-me
metabase.collections.models.collection/keep-me
+ metabase.collections.update/keep-me
metabase.collections.util/keep-me)
(p/import-vars
[metabase.collections.create
create-collection!]
+ [metabase.collections.update
+ update-collection!]
[metabase.collections.models.collection
archive-or-unarchive-collection!
has-remote-synced-collection?
diff --git a/src/metabase/collections/db.clj b/src/metabase/collections/db.clj
index 6e8ff29c22f..2972058b2cb 100644
--- a/src/metabase/collections/db.clj
+++ b/src/metabase/collections/db.clj
@@ -4,6 +4,7 @@
and transactions."
(:require
[malli.util :as mut]
+ [metabase.app-db.core :as app-db]
[metabase.collections.schema :as collections.schema]
[metabase.lib.schema.id :as lib.schema.id]
[metabase.models.serialization :as serdes]
@@ -84,8 +85,13 @@
[collection-id :- ::lib.schema.id/collection]
(t2/select-one-fn :location :model/Collection :id collection-id))
+(defn collection-location-columns
+ "The location, id, and type of the Collection with `collection-id`, or nil."
+ [collection-id]
+ (t2/select-one [:model/Collection :location :id :type] :id collection-id))
+
(mu/defn root-collection-type-by-id
- "The type of the top-level ::collections.schema/collection with `collection-id`, or nil if it is not top-level."
+ "The type of the top-level Collection with `collection-id`, or nil if it is not top-level."
[collection-id :- ::lib.schema.id/collection]
(t2/select-one-fn :type :model/Collection :id collection-id :location "/"))
@@ -269,7 +275,20 @@
[user-ids :- [:set ::lib.schema.id/user]]
(t2/select-fn->pk :personal_owner_id :model/Collection :personal_owner_id [:in user-ids]))
-;;; ---------------------------------------------- ::collections.schema/collection writes ----------------------------------------------
+(defn other-users-personal-collection-ids
+ "The IDs of the personal Collections owned by Users other than `user-id`."
+ [user-id]
+ (t2/select-fn-set :id :model/Collection
+ {:where [:and [:!= :personal_owner_id nil] [:!= :personal_owner_id user-id]]}))
+
+(defn collections-matching
+ "The Collections matching the Honey SQL `query` map. The caller builds the whole query because it needs clause
+ builders like `visible-collection-filter-clause`, which live in `metabase.collections.models.collection` and so
+ can't be called from here without a require cycle (that namespace already requires this one)."
+ [query]
+ (t2/select :model/Collection query))
+
+;;; ---------------------------------------------- Collection writes ----------------------------------------------
(mu/defn insert-collection!
"Insert `collection` and return the new instance."
@@ -437,8 +456,13 @@
(t2/select-pks-set :model/Dashboard
{:where [:and [:= :collection_id collection-id] (when skip-archived? [:not :archived])]}))
+(defn cards-in-collection
+ "The Cards in the Collection with `collection-id`."
+ [collection-id]
+ (t2/select :model/Card :collection_id collection-id))
+
(mu/defn card-ids-in-collection
- "The IDs of the Cards in the ::collections.schema/collection with `collection-id`, excluding archived ones when `skip-archived?` and
+ "The IDs of the Cards in the Collection with `collection-id`, excluding archived ones when `skip-archived?` and
excluding Cards materialized by an exploration Summary."
[collection-id :- [:maybe ::lib.schema.id/collection]
skip-archived? :- [:maybe :boolean]]
@@ -509,6 +533,61 @@
[:= :report_dashboardcard.card_id :report_card.id]
[:= :report_dashboardcard.dashboard_id :report_card.dashboard_id]]}]]}))
+(defn unarchived-card-collection-types-in-reducible
+ "A reducible of the distinct Collection ID and type of the unarchived Cards in the Collections with
+ `collection-ids`, leaving out dashboard questions when `exclude-dashboard-questions?`."
+ [collection-ids exclude-dashboard-questions?]
+ (t2/reducible-query {:select-distinct [:collection_id :type]
+ :from [:report_card]
+ :where [:and
+ (when exclude-dashboard-questions?
+ [:= :dashboard_id nil])
+ [:= :archived false]
+ [:in :collection_id collection-ids]]}))
+
+(defn published-table-collection-ids-in
+ "The distinct `:collection_id`s of the published, unarchived Tables in the Collections with `collection-ids`."
+ [collection-ids]
+ (t2/query {:select-distinct [:collection_id]
+ :from :metabase_table
+ :where [:and
+ [:= :is_published true]
+ [:= :archived_at nil]
+ [:in :collection_id collection-ids]]}))
+
+(defn transform-collection-ids-in
+ "The distinct `:collection_id`s of the Transforms with one of `source-types` in the Collections with
+ `collection-ids`."
+ [collection-ids source-types]
+ (t2/query {:select-distinct [:collection_id]
+ :from :transform
+ :where [:and
+ [:in :collection_id collection-ids]
+ [:in :source_type source-types]]}))
+
+(defn unarchived-dashboard-collection-ids-in
+ "The distinct `:collection_id`s of the unarchived Dashboards in the Collections with `collection-ids`."
+ [collection-ids]
+ (t2/query {:select-distinct [:collection_id]
+ :from :report_dashboard
+ :where [:and
+ [:= :archived false]
+ [:in :collection_id collection-ids]]}))
+
+(defn collection-children-rows
+ "The rows matching the collection-children Honey SQL `query`, built by `metabase.collections.children` from the
+ per-model item queries for a Collection's paginated child listing. Follows the same exception as
+ `metabase.search.db` for spec-driven Honey SQL that can't be reduced to plain-data parameters."
+ [query]
+ (app-db/query query))
+
+(defn collection-filter-metadata-rows
+ "The rows matching the collection-filter-metadata Honey SQL `query`, built by `metabase.collections.children` to
+ probe which item models have at least one visible child in a Collection. Follows the same exception as
+ `metabase.search.db` for spec-driven Honey SQL that can't be reduced to plain-data parameters."
+ [query]
+ (app-db/query query))
+
;;; ------------------------------------------------ Permissions ------------------------------------------------
(mu/defn user-has-root-collection-permission?
diff --git a/src/metabase/collections/update.clj b/src/metabase/collections/update.clj
new file mode 100644
index 00000000000..efea475395f
--- /dev/null
+++ b/src/metabase/collections/update.clj
@@ -0,0 +1,123 @@
+(ns metabase.collections.update
+ "Update-collection business logic, shared between the REST endpoint
+ (`metabase.collections-rest.api`) and other callers like the MCP `collection_write` tool.
+ Lives in the `collections` module so non-REST consumers can use it without crossing the
+ module-linter's non-rest -> rest barrier, mirroring `metabase.collections.create`."
+ (:require
+ [metabase.api.common :as api]
+ [metabase.collections.db :as collections.db]
+ [metabase.collections.models.collection :as collection]
+ [metabase.events.core :as events]
+ ;; `metabase.notification.card`, not `notification.core`: `core` pulls the payload/send chain,
+ ;; which reaches `queries.core` -> `queries.models.card` -> `collections.core` and so cycles
+ ;; back into this module. `notification.card` requires only events, the notification models,
+ ;; and toucan.
+ [metabase.notification.card :as notification.card]
+ [metabase.permissions.core :as perms]
+ [metabase.premium-features.core :as premium-features]
+ [metabase.util :as u]
+ [metabase.util.i18n :refer [tru]]
+ [metabase.util.malli :as mu]
+ [metabase.util.malli.schema :as ms]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(def UpdateCollectionArguments
+ "The arguments to an update-collection call — what the public API surface accepts. Absent keys
+ are left alone; `:archived` and `:parent_id` are acted on only when present, so a caller that
+ wants the REST endpoint's \"omitted means unarchived\" semantics has to supply that default
+ itself."
+ [:map
+ [:name {:optional true} [:maybe ms/NonBlankString]]
+ [:description {:optional true} [:maybe ms/NonBlankString]]
+ [:archived {:optional true} [:maybe :boolean]]
+ [:parent_id {:optional true} [:maybe ms/PositiveInt]]
+ [:authority_level {:optional true} [:maybe collection/AuthorityLevel]]])
+
+(defn- maybe-send-archived-notifications!
+ "When a collection is archived, all of it's cards are also marked as archived, but this is down in the model layer
+ which will not cause the archive notification code to fire. This will delete the relevant alerts and notify the
+ users just as if they had be archived individually via the card API."
+ [& {:keys [collection-before-update collection-updates actor]}]
+ (when (api/column-will-change? :archived collection-before-update collection-updates)
+ (doseq [card (collections.db/cards-in-collection (u/the-id collection-before-update))]
+ (notification.card/delete-card-notifications-and-notify! :event/card-update.notification-deleted.card-archived actor card))))
+
+(defn- move-collection!
+ "If `collection-updates` specifies that we should *move* a Collection, do appropriate permissions checks and move it
+ (and its descendants)."
+ [collection-before-update collection-updates]
+ ;; sanity check: a [new] parent_id update specified in the request?
+ (when (contains? collection-updates :parent_id)
+ (let [orig-location (:location collection-before-update)
+ new-parent-id (:parent_id collection-updates)
+ new-parent (if new-parent-id
+ (collections.db/collection-location-columns new-parent-id)
+ collection/root-collection)
+ new-location (collection/children-location new-parent)]
+ ;; check and make sure we're actually supposed to be moving something
+ (when (not= orig-location new-location)
+ ;; Check that we have write perms on the new parent collection
+ (api/write-check new-parent)
+ ;; ok, make sure we have perms to do this operation
+ (api/check-403
+ (perms/set-has-full-permissions-for-set? @api/*current-user-permissions-set*
+ (collection/perms-for-moving collection-before-update new-parent)))
+ (api/check
+ (not (collection/shared-tenant-collection? new-parent)))
+ ;; ok, we're good to move!
+ (collection/move-collection! collection-before-update new-location
+ (collection/moving-into-remote-synced? (collection/location-path->parent-id orig-location)
+ new-parent-id))))))
+
+(defn- archive-collection!
+ "If `collection-updates` specifies that we should archive a collection, do the appropriate permissions checks and
+ then move it to the trash."
+ [collection-before-update collection-updates]
+ ;; sanity check
+ (when (api/column-will-change? :archived collection-before-update collection-updates)
+ (collection/archive-or-unarchive-collection!
+ collection-before-update
+ (select-keys collection-updates [:parent_id :archived]))
+ (maybe-send-archived-notifications! {:collection-before-update collection-before-update
+ :collection-updates collection-updates
+ :actor @api/*current-user*})))
+
+(defn- move-or-archive-collection-if-needed!
+ "If `collection-updates` specifies that we should either move or archive the collection (archiving means 'moving to
+ the trash' so it makes sense to deal with them together), do the appropriate permissions checks and changes."
+ [collection-before-update collection-updates]
+ (condp #(api/column-will-change? %1 collection-before-update %2) collection-updates
+ :archived (archive-collection! collection-before-update collection-updates)
+ :parent_id (move-collection! collection-before-update collection-updates)
+ :no-op))
+
+(mu/defn update-collection!
+ "Modify the collection with `id`, including archiving or unarchiving it, or moving it. Write-checks the collection,
+ gates `authority_level` behind superuser plus the Official Collections feature, applies the plain column updates,
+ then moves or archives as `collection-updates` asks, and publishes the update and touch events. Returns the updated
+ collection. The single source of truth for collection updates; REST and agent callers both go through here."
+ [id :- ms/PositiveInt
+ collection-updates :- UpdateCollectionArguments]
+ ;; do we have perms to edit this Collection?
+ (let [collection-before-update (t2/hydrate (api/write-check :model/Collection id) :parent_id)]
+ ;; tenant-specific-root-collection collections cannot be updated
+ (api/check-400
+ (not= (:type collection-before-update) collection/tenant-specific-root-collection-type))
+ ;; if authority_level is changing, make sure we're allowed to do that
+ (when (and (contains? collection-updates :authority_level)
+ (not= (keyword (:authority_level collection-updates))
+ (:authority_level collection-before-update)))
+ (premium-features/assert-has-feature :official-collections (tru "Official Collections"))
+ (api/check-403 api/*is-superuser?*))
+ ;; ok, go ahead and update it! Only update keys that were specified in the request. But not `parent_id` since
+ ;; that's not actually a property of Collection, and since we handle moving a Collection separately below.
+ (let [updates (u/select-keys-when collection-updates :present [:name :description :authority_level])]
+ (when (seq updates)
+ (collections.db/update-collection! id updates)))
+ ;; if we're trying to move or archive the Collection, go ahead and do that
+ (move-or-archive-collection-if-needed! collection-before-update collection-updates)
+ (u/prog1 (collections.db/collection id)
+ (events/publish-event! :event/collection-update {:object <> :user-id api/*current-user-id*})
+ (events/publish-event! :event/collection-touch {:collection-id id :user-id api/*current-user-id*}))))
diff --git a/src/metabase/collections_rest/api.clj b/src/metabase/collections_rest/api.clj
index 3688f8ec418..152b303c05b 100644
--- a/src/metabase/collections_rest/api.clj
+++ b/src/metabase/collections_rest/api.clj
@@ -7,30 +7,23 @@
[malli.core :as mc]
[malli.transform :as mtx]
[malli.util]
- [medley.core :as m]
[metabase.api.common :as api]
[metabase.api.macros :as api.macros]
- [metabase.collections-rest.children-query :as children-query]
[metabase.collections-rest.db :as collections-rest.db]
+ [metabase.collections.children :as collections.children]
[metabase.collections.core :as collections]
[metabase.collections.models.collection :as collection]
[metabase.collections.models.collection.root :as collection.root]
[metabase.documents.core :as documents]
[metabase.eid-translation.core :as eid-translation]
[metabase.events.core :as events]
- [metabase.lib-be.core :as lib-be]
[metabase.models.interface :as mi]
- [metabase.notification.core :as notification]
[metabase.permissions.core :as perms]
[metabase.premium-features.core :as premium-features]
[metabase.queries.core :as queries]
[metabase.request.core :as request]
- [metabase.revisions.core :as revisions]
- [metabase.tracing.core :as tracing]
- [metabase.transforms.feature-gating :as transforms.gating]
- [metabase.upload.core :as upload]
[metabase.util :as u]
- [metabase.util.i18n :as i18n :refer [tru]]
+ [metabase.util.i18n :as i18n]
[metabase.util.malli :as mu]
[metabase.util.malli.registry :as mr]
[metabase.util.malli.schema :as ms]
@@ -66,47 +59,6 @@
[:name [:or :string i18n/LocalizedString]]
[:children {:optional true} [:or :boolean [:sequential [:ref ::CollectionTreeNode]]]]])
-(mr/def ::ItemsResponse
- "A page of a Collection's items. `:available_models` is present only when the request asked for it, and
- `:limit`/`:offset` are dropped entirely in the `snippets` namespace, which is not paginated."
- [:map
- [:total ms/IntGreaterThanOrEqualToZero]
- [:data [:sequential :map]]
- [:models [:maybe [:sequential :any]]]
- [:limit {:optional true} [:maybe ms/IntGreaterThanOrEqualToZero]]
- [:offset {:optional true} [:maybe ms/IntGreaterThanOrEqualToZero]]
- [:available_models {:optional true} [:sequential :any]]])
-
-(defn- remove-other-users-personal-subcollections
- [user-id collections]
- (let [personal-ids (set (collections-rest.db/other-users-personal-collection-ids user-id))
- personal-descendant? (fn [collection]
- (let [first-parent-collection-id (-> collection
- :location
- collection/location-path->ids
- first)]
- (personal-ids first-parent-collection-id)))]
- (remove personal-descendant? collections)))
-
-(defn- select-collections
- "Select collections based off certain parameters. If `shallow` is true, we select only the requested collection (or
- the root, if `collection-id` is `nil`) and its immediate children, to avoid reading the entire collection tree when it
- is not necessary.
-
- For archived, we can either include only archived items (when archived is truthy) or exclude archived items (when
- archived is falsey).
-
- The Trash Collection itself (the container for archived items) is *always* included.
-
- This will select only collections where `personal_owner_id` is not `nil`.
-
- To include library collections and their descendants, pass in `include-library?` as `true`.
- By default, library-type collections are excluded. "
- [{:keys [exclude-other-user-collections] :as options}]
- (cond->> (collections-rest.db/collections-for-listing options api/*current-user-id*)
- exclude-other-user-collections
- (remove-other-users-personal-subcollections api/*current-user-id*)))
-
(api.macros/defendpoint :get "/" :- [:sequential ::Collection]
"Fetch a list of all Collections that the current user has read permissions for (`:can_write` is returned as an
additional property of each Collection so you can tell which of these you have write permissions for.)
@@ -125,16 +77,16 @@
[:namespace {:optional true} [:maybe ms/NonBlankString]]
[:personal-only {:default false} [:maybe ms/BooleanValue]]]]
(as->
- (select-collections {:archived (boolean archived)
- :exclude-other-user-collections exclude-other-user-collections
- :namespaces (cond
- namespace [namespace]
- (premium-features/enable-audit-app?) #{"analytics" nil}
- :else
- #{nil})
- :shallow false
- :personal-only personal-only
- :include-library? true}) collections
+ (collections.children/select-collections {:archived (boolean archived)
+ :exclude-other-user-collections exclude-other-user-collections
+ :namespaces (cond
+ namespace [namespace]
+ (premium-features/enable-audit-app?) #{"analytics" nil}
+ :else
+ #{nil})
+ :shallow false
+ :personal-only personal-only
+ :include-library? true}) collections
;; include Root Collection at beginning or results if archived or personal-only isn't `true`
(if (or archived personal-only)
collections
@@ -152,36 +104,6 @@
collection/personal-collections-with-ui-details
collection/maybe-localize-tenant-collection-names)))
-(defn- prep-collection-for-export
- "Given a collection, tweaks it to be ready for returning to the FE.
-
- These same functions were called in several places in this namespace, so they're combined here to keep it DRY."
- [coll]
- (-> coll
- collection/personal-collection-with-ui-details
- collection/maybe-localize-tenant-collection-name
- collection/maybe-mark-collection-as-library-root))
-
-(defn- shallow-tree-from-collection-id
- "Returns only a shallow Collection in the provided collection-id, e.g.
-
- location: /1/
- ```
- [{:name \"A\"
- :location \"/1/\"
- :children 1}
- ...
- {:name \"H\"
- :location \"/1/\"}]
-
- If the collection-id is nil, then we default to the root collection.
- ```"
- [colls]
- (->> colls
- (map prep-collection-for-export)
- (collection/collections->tree nil)
- (map (fn [coll] (update coll :children #(boolean (seq %)))))))
-
(api.macros/defendpoint :get "/tree" :- [:sequential ::CollectionTreeNode]
"Similar to `GET /`, but returns Collections in a tree structure, e.g.
@@ -232,15 +154,15 @@
(seq namespaces) (into #{} (map not-empty namespaces))
(premium-features/enable-audit-app?) #{nil "analytics"}
:else #{nil})
- collections (-> (select-collections {:archived archived
- :exclude-other-user-collections exclude-other-user-collections
- :namespaces namespaces
- :shallow shallow
- :collection-id collection-id
- :include-library? include-library})
+ collections (-> (collections.children/select-collections {:archived archived
+ :exclude-other-user-collections exclude-other-user-collections
+ :namespaces namespaces
+ :shallow shallow
+ :collection-id collection-id
+ :include-library? include-library})
(t2/hydrate :can_write))]
(if shallow
- (shallow-tree-from-collection-id collections)
+ (collections.children/shallow-tree-from-collection-id collections)
(let [collection-type-ids (merge (reduce (fn [acc {collection-id :collection_id, card-type :type, :as _card}]
(update acc (case (keyword card-type)
:model :dataset
@@ -255,391 +177,21 @@
{:table (->> (collections-rest.db/published-table-collection-ids)
(map :collection_id)
(into #{}))}))
- collections-with-details (map prep-collection-for-export collections)]
+ collections-with-details (map collections.children/prep-collection-for-export collections)]
(collection/collections->tree collection-type-ids collections-with-details)))))
;;; --------------------------------- Fetching a single Collection & its 'children' ----------------------------------
-(def ^:private ModelString
- (into [:enum] children-query/valid-model-param-values))
-
-(def ^:private Models
- "This is basically a union type. [[api.macros/defendpoint]] splits the string if it only gets one."
- [:vector {:decode/string (fn [x] (cond (vector? x) x x [x]))} ModelString])
-
-(defmulti ^:private post-process-collection-children
- {:arglists '([model options collection rows])}
- (fn [model _ _ _]
- (keyword model)))
-
-(defmethod ^:private post-process-collection-children :default
- [_ _ _ rows]
- rows)
-
-(defmethod ^:private post-process-collection-children :document
- [_ _ collection rows]
- (documents/with-content-gate-cache
- (map #(dissoc % :exploration_id)
- (t2/hydrate (for [document rows]
- (-> (t2/instance :model/Document document)
- (assoc :location (or (when collection
- (collection/children-location collection))
- "/"))
- (dissoc :namespace)
- (update :archived api/bit->boolean)
- (update :archived_directly api/bit->boolean))) :can_write :can_restore :can_delete :is_remote_synced :collection_namespace))))
-
-(defmethod ^:private post-process-collection-children :exploration
- [_ _ collection rows]
- (t2/hydrate (for [exploration rows]
- (-> (t2/instance :model/Exploration exploration)
- (assoc :location (or (when collection
- (collection/children-location collection))
- "/"))
- (update :archived api/bit->boolean)
- (update :archived_directly api/bit->boolean))) :can_write :can_restore :can_delete))
-
-(defmethod post-process-collection-children :pulse
- [_ _ _ rows]
- (for [row rows]
- (dissoc row
- :description :display :authority_level :moderated_status :icon :personal_owner_id :namespace
- :collection_preview :dataset_query :table_id :query_type :is_upload :collection_namespace)))
-
-(defmethod post-process-collection-children :timeline
- [_ _options _collection rows]
- (for [row rows]
- (dissoc row
- :description :display :collection_position :authority_level :moderated_status
- :collection_preview :dataset_query :table_id :query_type :is_upload :namespace)))
-
-(defmethod post-process-collection-children :snippet
- [_ _options _collection rows]
- (for [row rows]
- (-> (dissoc row
- :description :collection_position :display :authority_level
- :moderated_status :icon :personal_owner_id :collection_preview
- :dataset_query :table_id :query_type :is_upload :namespace)
- (assoc :collection_namespace "snippets"))))
-
-(defn- post-process-card-row [row]
- (-> (t2/instance :model/Card row)
- ;; `card-query` filters `[:= :c.document_id nil]` unconditionally, so every row here is known
- ;; not to belong to a Document. Say so on the instance: `mi/can-write?` consults `document_id`
- ;; (a Document-scoped Card is gated by its Document), and an instance that merely *omits* the
- ;; column makes it resolve one from the primary key instead — one extra query per row, on a
- ;; listing that renders a full page of them. Stamping it rather than selecting it keeps the
- ;; column out of `all-select-columns`, which every model's union arm would otherwise have to
- ;; pad, and out of the response body.
- (assoc :document_id nil)
- (update :dataset_query (:out lib-be/transform-query))
- (update :collection_preview api/bit->boolean)
- (update :archived api/bit->boolean)
- (update :archived_directly api/bit->boolean)))
-
-(defn- post-process-card-row-after-hydrate [row]
- (-> (dissoc row :authority_level :icon :personal_owner_id :dataset_query :table_id :query_type :is_upload :namespace
- ;; internal-only: stamped in `post-process-card-row` for the permission check
- :document_id)
- (update :dashboard #(when % (select-keys % [:id :name :moderation_status])))
- (assoc :fully_parameterized (queries/fully-parameterized? row))))
-
-(defn- post-process-card-like
- [{:keys [hydrate-based-on-upload]} rows]
- (let [hydration [:can_write
- :can_restore
- :can_delete
- :dashboard_count
- :is_remote_synced
- :collection_namespace
- [:dashboard :moderation_status]]]
- (as-> (map post-process-card-row rows) $
- (apply t2/hydrate $ hydration)
- (cond-> $
- hydrate-based-on-upload upload/model-hydrate-based-on-upload)
- (map post-process-card-row-after-hydrate $))))
-
-(defmethod post-process-collection-children :card
- [_ options _ rows]
- (post-process-card-like options rows))
-
-(defmethod post-process-collection-children :metric
- [_ options _ rows]
- (post-process-card-like options rows))
-
-(defmethod post-process-collection-children :dataset
- [_ options _ rows]
- (post-process-card-like (assoc options :hydrate-based-on-upload true) rows))
-
-(defn- post-process-dashboard [parent-collection dashboard]
- (-> (t2/instance :model/Dashboard dashboard)
- (assoc :location (or (when parent-collection
- (collection/children-location parent-collection))
- "/"))
- (assoc :is_tenant_dashboard (collection/shared-tenant-collection? parent-collection))
- (update :archived api/bit->boolean)
- (update :archived_directly api/bit->boolean)
- (t2/hydrate :can_write :can_restore :can_delete :is_remote_synced :collection_namespace)
- (dissoc :display :authority_level :icon :personal_owner_id :collection_preview
- :dataset_query :table_id :query_type :is_upload)))
-
-(defmethod post-process-collection-children :dashboard
- [_ _options parent-collection rows]
- (->> rows
- collections/annotate-dashboards
- (map (partial post-process-dashboard parent-collection))))
-
-(defn- annotate-collections
- [parent-coll colls {:keys [show-dashboard-questions?]}]
- (let [descendant-collections (collection/descendants-flat parent-coll nil
- (collection/visible-collection-filter-clause
- :id
- {:include-archived-items :all}))
-
- descendant-collection-ids (mapv u/the-id descendant-collections)
-
- child-type->coll-id-set
- (reduce (fn [acc {collection-id :collection_id, card-type :type, :as _card}]
- (update acc (case (keyword card-type)
- :model :dataset
- :metric :metric
- :card) conj collection-id))
- {:dataset #{}
- :metric #{}
- :card #{}}
- (when (seq descendant-collection-ids)
- (collections-rest.db/unarchived-card-collection-types-in-reducible
- descendant-collection-ids
- (not show-dashboard-questions?))))
-
- ;; Tables in collections are an EE feature (library)
- collections-containing-tables
- (if (premium-features/has-feature? :library)
- (->> (when (seq descendant-collection-ids)
- (collections-rest.db/published-table-collection-ids-in descendant-collection-ids))
- (map :collection_id)
- (into #{}))
- #{})
-
- collections-containing-transforms
- (if (seq (transforms.gating/enabled-source-types))
- (->> (when (seq descendant-collection-ids)
- (collections-rest.db/transform-collection-ids-in descendant-collection-ids (transforms.gating/enabled-source-types)))
- (map :collection_id)
- (into #{}))
- #{})
-
- collections-containing-dashboards
- (->> (when (seq descendant-collection-ids)
- (collections-rest.db/unarchived-dashboard-collection-ids-in descendant-collection-ids))
- (map :collection_id)
- (into #{}))
-
- ;; the set of collections that contain collections (in terms of *effective* location)
- collections-containing-collections
- (->> (t2/hydrate descendant-collections :effective_parent :is_remote_synced)
- (reduce (fn [accu {:keys [effective_parent] :as _coll}]
- (let [parent-id (:id effective_parent)]
- (conj accu parent-id)))
- #{}))
-
- child-type->coll-id-set
- (merge child-type->coll-id-set
- {:table collections-containing-tables
- :collection collections-containing-collections
- :dashboard collections-containing-dashboards
- :transform collections-containing-transforms})
-
- ;; why are we calling `annotate-collections` on all descendants, when we only need the collections in `colls`
- ;; to be annotated? Because `annotate-collections` works by looping through the collections it's passed and
- ;; using them to figure out the ancestors of a given collection. This could use a refactor - probably the
- ;; caller of `annotate-collections` could be generating both `child-type->parent-ids` and
- ;; `child-type->ancestor-ids`.
- coll-id->annotated (m/index-by :id (collection/annotate-collections child-type->coll-id-set descendant-collections))]
- (for [coll colls]
- (merge coll (select-keys (coll-id->annotated (:id coll)) [:here :below])))))
-
-(defmethod post-process-collection-children :collection
- [_ options parent-collection rows]
- (letfn [(update-personal-collection [{:keys [personal_owner_id] :as row}]
- (if personal_owner_id
- ;; when fetching root collection, we might have personal collection
- (assoc row :name (collection/user->personal-collection-name (:personal_owner_id row) :user))
- (dissoc row :personal_owner_id)))]
- (for [row (annotate-collections parent-collection rows options)]
- (let [type-value (:type row)]
- (-> (t2/instance :model/Collection row)
- collection/maybe-localize-system-collection-name
- collection/maybe-localize-tenant-collection-name
- collection/maybe-mark-collection-as-library-root
- (update :archived api/bit->boolean)
- (update :is_remote_synced api/bit->boolean)
- (t2/hydrate :can_write :effective_location :can_restore :can_delete :is_shared_tenant_collection)
- (dissoc :collection_position :display :moderated_status :icon
- :collection_preview :dataset_query :table_id :query_type :is_upload)
- (assoc :type type-value)
- update-personal-collection)))))
-
-(defmethod post-process-collection-children :table
- [_ {:keys [models]} _collection rows]
- (let [tables (map #(-> (t2/instance :model/Table %)
- (update :archived api/bit->boolean)) rows)]
- (if (contains? models :measure)
- (t2/hydrate tables :measures)
- tables)))
-
-;;; TODO -- consider whether this function belongs here or in [[metabase.revisions.models.revision.last-edit]]
-(mu/defn- coalesce-edit-info :- revisions/MaybeAnnotated
- "Hoist all of the last edit information into a map under the key :last-edit-info. Considers this information present
- if `:last_edit_user` is not nil."
- [row]
- (letfn [(select-as [original k->k']
- (reduce (fn [m [k k']] (assoc m k' (get original k)))
- {}
- k->k'))]
- (let [mapping {:last_edit_user :id
- :last_edit_last_name :last_name
- :last_edit_first_name :first_name
- :last_edit_email :email
- :last_edit_timestamp :timestamp}]
- (cond-> (apply dissoc row (keys mapping))
- ;; don't use contains as they all have the key, we care about a value present
- (:last_edit_user row) (assoc :last-edit-info (select-as row mapping))))))
-
-(defn- remove-unwanted-keys [{:keys [model] :as row}]
- (cond-> (dissoc row :model_ranking :archived_directly :total_count :collection_type)
- (not= model "collection") (dissoc :type)))
-
-(defn- model-name->toucan-model [model-name]
- (case (keyword model-name)
- :collection :model/Collection
- :card :model/Card
- :dataset :model/Card
- :metric :model/Card
- :dashboard :model/Dashboard
- :document :model/Document
- :exploration :model/Exploration
- :pulse :model/Pulse
- :snippet :model/NativeQuerySnippet
- :table :model/Table
- :timeline :model/Timeline
- :transform :model/Transform))
-
-(defn post-process-rows
- "Post process any data. Have a chance to process all of the same type at once using
- `post-process-collection-children`. Must respect the order passed in."
- [options collection rows]
- (->> (map-indexed (fn [i row] (vary-meta row assoc ::index i)) rows) ;; keep db sort order
- (group-by :model)
- (into []
- (comp (map (fn [[model rows]]
- (post-process-collection-children (keyword model) options collection rows)))
- cat
- (map coalesce-edit-info)))
- (map remove-unwanted-keys)
- ;; the collection these are presented "in" is the ID of the collection we're getting `/items` on.
- (map #(assoc % :collection_id (:id collection)))
- (sort-by (comp ::index meta))))
-
-(defn- total-count
- "The size of the whole result set `rows` is a page of, read off the `total_count` window column.
-
- A page past the end of the result set comes back empty and so carries no window column; in that case read the count
- off the first row of the same query without its pagination."
- [rows collection models options offset]
- (or (some-> rows first :total_count)
- (when (pos? (or offset 0))
- (some-> (collections-rest.db/collection-children-rows collection models options {:limit 1}) first :total_count))
- 0))
-
-(defn- collection-children*
- [collection models options]
- (let [models (sort (map keyword models))
- limit (request/limit)
- offset (request/offset)
- ;; A limit of 0 asks for the count alone rather than for a page.
- count-only? (= limit 0)
- ;; We didn't implement collection pagination for snippets namespace for root/items
- ;; Rip out the limit for now and put it back in when we want it.
- page (when-not (or (nil? limit)
- (nil? offset)
- (and (= (:collection-namespace options) "snippets")
- (not count-only?)))
- ;; If limit is 0, we still execute the query with a limit of 1 so that we fetch a :total_count
- {:limit (if count-only? 1 limit)
- :offset offset})
- rows (tracing/with-span :db-app "db-app.collection-items-query" {:collection/id (:id collection)}
- (collections-rest.db/collection-children-rows collection models options page))
- res {:total (total-count rows collection models options offset)
- :data (if count-only?
- []
- (tracing/with-span :db-app "db-app.collection-items-post-process" {:collection/id (:id collection)}
- (post-process-rows options collection rows)))
- :models models}
- limit-res (assoc res
- :limit (request/limit)
- :offset (request/offset))]
- (if (= (:collection-namespace options) "snippets")
- res
- limit-res)))
-
-(defn- valid-collection-models
- "Return every item model that can appear in `collection-namespace`."
- [collection-namespace]
- (for [model-kw (cond-> [:collection :dataset :metric :card :dashboard :pulse :snippet :timeline :document :exploration :transform]
- ;; Tables in collections are an EE feature (library)
- (premium-features/has-feature? :library) (conj :table))
- :let [toucan-model (model-name->toucan-model model-kw)
- allowed-namespaces (collection/allowed-namespaces toucan-model)]
- :when (or (= model-kw :collection)
- (contains? allowed-namespaces (keyword collection-namespace)))]
- model-kw))
-
-(mu/defn collection-children
- "Fetch a sequence of 'child' objects belonging to a Collection, filtered using `options`."
- [{collection-namespace :namespace, :as collection} :- collection/CollectionWithLocationAndIDOrRoot
- {:keys [models], :as options} :- children-query/CollectionChildrenOptions]
- (let [valid-models (cond->> (valid-collection-models collection-namespace)
- (seq models) (filter models))]
- (if (seq valid-models)
- (collection-children* collection valid-models (assoc options :collection-namespace collection-namespace))
- {:total 0
- :data []
- :limit (request/limit)
- :offset (request/offset)
- :models valid-models})))
-
-(defn- filterable-models
- "The models that can appear as a filterable item of `collection`. Snippets are never included: they are not a
- filterable type. When present, `restrict-models` limits the set."
- [collection restrict-models]
- (cond->> (remove #{:snippet} (valid-collection-models (:namespace collection)))
- (seq restrict-models) (filter restrict-models)))
-
-(mu/defn- collection-filter-metadata :- [:map
- [:available_models [:sequential :string]]]
- "Return the models that have at least one visible item in `collection`. Respect the requested scope and visibility,
- but ignore model and search filters. When present, `restrict-models` limits the candidate models. Snippets are never
- reported: they are not a filterable type."
- [collection :- collection/CollectionWithLocationAndIDOrRoot
- restrict-models :- [:maybe [:set :keyword]]
- options :- children-query/CollectionChildrenOptions]
- (let [candidates (filterable-models collection restrict-models)
- options (-> options
- (dissoc :models :search-text)
- (assoc :collection-namespace (:namespace collection)))]
- ;; This result is independent of search and model filters. Requesting it with every filter update
- ;; repeats the same EXISTS probes; a separately cached request could avoid that work.
- (if (empty? candidates)
- {:available_models []}
- (let [row (first (collections-rest.db/collection-filter-metadata-rows collection (vec candidates) options))]
- {:available_models
- (->> candidates
- (keep (fn [model]
- (when (api/bit->boolean (get row model))
- (name model))))
- sort
- vec)}))))
+(mr/def ::ItemsResponse
+ "A page of a Collection's items. `:available_models` is present only when the request asked for it, and
+ `:limit`/`:offset` are dropped entirely in the `snippets` namespace, which is not paginated."
+ [:map
+ [:total ms/IntGreaterThanOrEqualToZero]
+ [:data [:sequential :map]]
+ [:models [:maybe [:sequential :any]]]
+ [:limit {:optional true} [:maybe ms/IntGreaterThanOrEqualToZero]]
+ [:offset {:optional true} [:maybe ms/IntGreaterThanOrEqualToZero]]
+ [:available_models {:optional true} [:sequential :any]]])
(mr/def ::ItemsMetadata
[:map
@@ -655,23 +207,29 @@
never reported -- a snippet -- is never counted either."
[collection :- collection/CollectionWithLocationAndIDOrRoot
restrict-models :- [:maybe [:set :keyword]]
- options :- children-query/CollectionChildrenOptions]
+ options :- collections.children/CollectionChildrenOptions]
(let [options (dissoc options :models :search-text)
- models (set (filterable-models collection restrict-models))]
- (assoc (collection-filter-metadata collection restrict-models options)
+ models (set (collections.children/filterable-models collection restrict-models))]
+ (assoc (collections.children/collection-filter-metadata collection restrict-models options)
;; An empty model set means "nothing to count"; `collection-children` would read it as "no restriction".
:total_items (if (empty? models)
0
(request/with-limit-and-offset 0 0
- (:total (collection-children collection (assoc options :models models))))))))
+ (:total (collections.children/collection-children collection (assoc options :models models))))))))
(mu/defn- collection-detail
"Add a standard set of details to `collection`, including things like `effective_location`.
Works for either a normal Collection or the Root Collection."
[collection :- collection/CollectionWithLocationAndIDOrRoot]
(-> collection
- prep-collection-for-export
- (t2/hydrate :parent_id :effective_location [:effective_ancestors :can_write] :can_write :is_personal :can_restore :can_delete)))
+ collections.children/prep-collection-for-export
+ (t2/hydrate :parent_id
+ :effective_location
+ [:effective_ancestors :can_write]
+ :can_write
+ :is_personal
+ :can_restore
+ :can_delete)))
(api.macros/defendpoint :get "/trash" :- ::Collection
"Fetch the trash collection, as in `/api/collection/:trash-id`"
@@ -795,27 +353,6 @@
(api/read-check)
(dissoc ::collection.root/is-root?)))
-(defn- visible-model-kwds
- "If you pass in explicitly keywords that you can't see, you can't see them.
- But there is an exception for the collections,
- because you might not be able to see the top-level collections
- but be able to see, children of those invisible top-level collections."
- [root-collection model-set]
- (if (mi/can-read? root-collection)
- model-set
- (if (or (empty? model-set) (contains? model-set :collection))
- #{:collection}
- #{:no_models})))
-
-(def ^:private namespaces-holding-non-collection-types
- "We can't really *know* what namespace something with a `nil` `collection_id` is in, unless it's one of the special
- types that can only live in one namespace.
-
- If you're looking in the root collection of one of these namespaces, we'll allow you to list any type of model.
-
- Otherwise, we'll just show you collections."
- #{nil "snippets" "transforms"})
-
(api.macros/defendpoint :get "/root/items" :- ::ItemsResponse
"Fetch objects that the current user should see at their root level. As mentioned elsewhere, the 'Root' Collection
doesn't actually exist as a row in the application DB: it's simply a virtual Collection where things with no
@@ -840,28 +377,27 @@
changed, that should too."
[_route-params
{:keys [models archived namespace pinned-state sort-column sort-direction official-collections-first
- include-library collection-type
- show-dashboard-questions show-exploration-documents
- q include-available-models]} :- [:map {:closed true}
- [:models {:optional true} [:maybe Models]]
- [:collection-type {:optional true} children-query/CollectionType]
- [:archived {:default false} [:maybe ms/BooleanValue]]
- [:namespace {:optional true} [:maybe ms/NonBlankString]]
- [:include-library {:default false} [:maybe ms/BooleanValue]]
- [:pinned-state {:optional true} [:maybe (into [:enum] children-query/valid-pinned-state-values)]]
- [:sort-column {:optional true} [:maybe (into [:enum] children-query/valid-sort-columns)]]
- [:sort-direction {:optional true} [:maybe (into [:enum] children-query/valid-sort-directions)]]
- [:official-collections-first {:optional true} [:maybe ms/MaybeBooleanValue]]
- [:show-dashboard-questions {:optional true} [:maybe ms/MaybeBooleanValue]]
- [:show-exploration-documents {:optional true} [:maybe ms/MaybeBooleanValue]]
- [:q {:optional true} [:maybe :string]]
- [:include-available-models {:default false} [:maybe ms/BooleanValue]]]]
+ include-library collection-type show-dashboard-questions
+ q include-available-models show-exploration-documents]} :- [:map {:closed true}
+ [:models {:optional true} [:maybe collections.children/Models]]
+ [:collection-type {:optional true} collections.children/CollectionType]
+ [:archived {:default false} [:maybe ms/BooleanValue]]
+ [:namespace {:optional true} [:maybe ms/NonBlankString]]
+ [:include-library {:default false} [:maybe ms/BooleanValue]]
+ [:pinned-state {:optional true} [:maybe (into [:enum] collections.children/valid-pinned-state-values)]]
+ [:sort-column {:optional true} [:maybe (into [:enum] collections.children/valid-sort-columns)]]
+ [:sort-direction {:optional true} [:maybe (into [:enum] collections.children/valid-sort-directions)]]
+ [:official-collections-first {:optional true} [:maybe ms/MaybeBooleanValue]]
+ [:show-dashboard-questions {:optional true} [:maybe ms/MaybeBooleanValue]]
+ [:q {:optional true} [:maybe :string]]
+ [:include-available-models {:default false} [:maybe ms/BooleanValue]]
+ [:show-exploration-documents {:optional true} [:maybe ms/MaybeBooleanValue]]]]
;; Return collection contents, including Collections that have an effective location of being in the Root
;; Collection for the Current User.
(let [root-collection (assoc collection/root-collection :namespace namespace)
model-set (set (map keyword (u/one-or-many models)))
- model-kwds (visible-model-kwds root-collection model-set)
- restrict-models (when (or (not (contains? namespaces-holding-non-collection-types namespace))
+ model-kwds (collections.children/visible-model-kwds root-collection model-set)
+ restrict-models (when (or (not (contains? collections.children/namespaces-holding-non-collection-types namespace))
(not (mi/can-read? root-collection)))
#{:collection})
options {:archived? (boolean archived)
@@ -869,19 +405,23 @@
:show-exploration-documents? (boolean show-exploration-documents)
:collection-type collection-type
:include-library? include-library
- :models (if-not (contains? namespaces-holding-non-collection-types namespace)
+ :models (if-not (contains? collections.children/namespaces-holding-non-collection-types namespace)
#{:collection}
model-kwds)
:pinned-state (keyword pinned-state)
:search-text q
- :sort-info {:sort-column (or (some-> sort-column children-query/normalize-sort-choice) :name)
- :sort-direction (or (some-> sort-direction children-query/normalize-sort-choice) :asc)
+ :sort-info {:sort-column (or (some-> sort-column collections.children/normalize-sort-choice) :name)
+ :sort-direction (or (some-> sort-direction collections.children/normalize-sort-choice) :asc)
;; default to sorting official collections first, but provide the option not to
:official-collections-first? (or (nil? official-collections-first)
(boolean official-collections-first))}}]
- (cond-> (collection-children root-collection options)
- include-available-models
- (merge (collection-filter-metadata root-collection restrict-models options)))))
+ ;; scope the document content-gate cache over the listing: each document row's hydration
+ ;; adjudicates the gate, and the cache keeps that to once per document (see
+ ;; `post-process-collection-children :document` in `metabase.collections.children`)
+ (documents/with-content-gate-cache
+ (cond-> (collections.children/collection-children root-collection options)
+ include-available-models
+ (merge (collections.children/collection-filter-metadata root-collection restrict-models options))))))
(api.macros/defendpoint :get "/root/items/metadata" :- ::ItemsMetadata
"Metadata about the Root Collection's items list: the models with at least one visible item plus the item count.
@@ -890,17 +430,17 @@
[_route-params
{:keys [models archived namespace pinned-state collection-type include-library
show-dashboard-questions show-exploration-documents]} :- [:map {:closed true}
- [:models {:optional true} [:maybe Models]]
+ [:models {:optional true} [:maybe collections.children/Models]]
[:archived {:default false} [:maybe ms/BooleanValue]]
[:namespace {:optional true} [:maybe ms/NonBlankString]]
- [:pinned-state {:optional true} [:maybe (into [:enum] children-query/valid-pinned-state-values)]]
- [:collection-type {:optional true} children-query/CollectionType]
+ [:pinned-state {:optional true} [:maybe (into [:enum] collections.children/valid-pinned-state-values)]]
+ [:collection-type {:optional true} collections.children/CollectionType]
[:include-library {:default false} [:maybe ms/BooleanValue]]
[:show-dashboard-questions {:default false} [:maybe ms/BooleanValue]]
[:show-exploration-documents {:default false} [:maybe ms/BooleanValue]]]]
(let [root-collection (assoc collection/root-collection :namespace namespace)
model-set (set (map keyword (u/one-or-many models)))
- restrict-models (visible-model-kwds root-collection model-set)]
+ restrict-models (collections.children/visible-model-kwds root-collection model-set)]
(collection-items-metadata root-collection restrict-models
{:archived? (boolean archived)
:show-dashboard-questions? (boolean show-dashboard-questions)
@@ -932,64 +472,9 @@
[:authority_level {:optional true} [:maybe collection/AuthorityLevel]]]]
(collections/create-collection! body))
-(defn- maybe-send-archived-notifications!
- "When a collection is archived, all of it's cards are also marked as archived, but this is down in the model layer
- which will not cause the archive notification code to fire. This will delete the relevant alerts and notify the
- users just as if they had be archived individually via the card API."
- [& {:keys [collection-before-update collection-updates actor]}]
- (when (api/column-will-change? :archived collection-before-update collection-updates)
- (doseq [card (collections-rest.db/cards-in-collection (u/the-id collection-before-update))]
- (notification/delete-card-notifications-and-notify! :event/card-update.notification-deleted.card-archived actor card))))
-
-(defn- move-collection!
- "If input the `PUT /api/collection/:id` endpoint (`collection-updates`) specify that we should *move* a Collection, do
- appropriate permissions checks and move it (and its descendants)."
- [collection-before-update collection-updates]
- ;; sanity check: a [new] parent_id update specified in the PUT request?
- (when (contains? collection-updates :parent_id)
- (let [orig-location (:location collection-before-update)
- new-parent-id (:parent_id collection-updates)
- new-parent (if new-parent-id
- (collections-rest.db/collection-location-columns new-parent-id)
- collection/root-collection)
- new-location (collection/children-location new-parent)]
- ;; check and make sure we're actually supposed to be moving something
- (when (not= orig-location new-location)
- ;; Check that we have write perms on the new parent collection
- (api/write-check new-parent)
- ;; ok, make sure we have perms to do this operation
- (api/check-403
- (perms/set-has-full-permissions-for-set? @api/*current-user-permissions-set*
- (collection/perms-for-moving collection-before-update new-parent)))
- (api/check
- (not (collection/shared-tenant-collection? new-parent)))
- ;; ok, we're good to move!
- (collection/move-collection! collection-before-update new-location
- (collection/moving-into-remote-synced? (collection/location-path->parent-id orig-location)
- new-parent-id))))))
-
-(defn- archive-collection!
- "If input to the `PUT /api/collection/:id` endpoint specifies that we should archive a collection, do the appropriate
- permissions checks and then move it to the trash."
- [collection-before-update collection-updates]
- ;; sanity check
- (when (api/column-will-change? :archived collection-before-update collection-updates)
- (collection/archive-or-unarchive-collection!
- collection-before-update
- (select-keys collection-updates [:parent_id :archived]))
- (maybe-send-archived-notifications! {:collection-before-update collection-before-update
- :collection-updates collection-updates
- :actor @api/*current-user*})))
-
-(defn- move-or-archive-collection-if-needed!
- "If input to the `PUT /api/collection/:id` endpoint (`collection-updates`) specifies that we should either move or
- archive the collection (archiving means 'moving to the trash' so it makes sense to deal with them together), do the
- appropriate permissions checks and changes."
- [collection-before-update collection-updates]
- (condp #(api/column-will-change? %1 collection-before-update %2) collection-updates
- :archived (archive-collection! collection-before-update collection-updates)
- :parent_id (move-collection! collection-before-update collection-updates)
- :no-op))
+;; Update-collection business logic lives in `metabase.collections.update` so that non-REST
+;; callers (the MCP `collection_write` tool) run the identical permission checks and move/archive
+;; handling.
;;; ------------------------------------------------ GRAPH ENDPOINTS -------------------------------------------------
@@ -1102,34 +587,13 @@
[{:keys [id]} :- [:map {:closed true}
[:id ms/PositiveInt]]
_query-params
- {authority-level :authority_level, :as collection-updates} :- [:map {:closed true}
- [:name {:optional true} [:maybe ms/NonBlankString]]
- [:description {:optional true} [:maybe ms/NonBlankString]]
- [:archived {:default false} [:maybe ms/BooleanValue]]
- [:parent_id {:optional true} [:maybe ms/PositiveInt]]
- [:authority_level {:optional true} [:maybe collection/AuthorityLevel]]]]
- ;; do we have perms to edit this Collection?
- (let [collection-before-update (t2/hydrate (api/write-check :model/Collection id) :parent_id)]
- ;; tenant-specific-root-collection collections cannot be updated
- (api/check-400
- (not= (:type collection-before-update) collection/tenant-specific-root-collection-type))
- ;; if authority_level is changing, make sure we're allowed to do that
- (when (and (contains? collection-updates :authority_level)
- (not= (keyword authority-level) (:authority_level collection-before-update)))
- (premium-features/assert-has-feature :official-collections (tru "Official Collections"))
- (api/check-403 api/*is-superuser?*))
- ;; ok, go ahead and update it! Only update keys that were specified in the `body`. But not `parent_id` since
- ;; that's not actually a property of Collection, and since we handle moving a Collection separately below.
- (let [updates (u/select-keys-when collection-updates :present [:name :description :authority_level])]
- (when (seq updates)
- (collections-rest.db/update-collection! id updates)))
- ;; if we're trying to move or archive the Collection, go ahead and do that
- (move-or-archive-collection-if-needed! collection-before-update collection-updates)
- (let [updated-collection (collections-rest.db/collection id)]
- (events/publish-event! :event/collection-update {:object updated-collection :user-id api/*current-user-id*})
- (events/publish-event! :event/collection-touch {:collection-id id :user-id api/*current-user-id*})))
- ;; finally, return the updated object
- (collection-detail (collections-rest.db/collection id)))
+ collection-updates :- [:map {:closed true}
+ [:name {:optional true} [:maybe ms/NonBlankString]]
+ [:description {:optional true} [:maybe ms/NonBlankString]]
+ [:archived {:default false} [:maybe ms/BooleanValue]]
+ [:parent_id {:optional true} [:maybe ms/PositiveInt]]
+ [:authority_level {:optional true} [:maybe collection/AuthorityLevel]]]]
+ (collection-detail (collections/update-collection! id collection-updates)))
;; Returns the number of Collection rows deleted, which `t2/delete!` hands back -- 1 whenever the checks above pass.
(api.macros/defendpoint :delete "/:id" :- ms/IntGreaterThanOrEqualToZero
@@ -1172,11 +636,11 @@
{:keys [models archived pinned-state sort-column sort-direction official-collections-first
show-dashboard-questions show-exploration-documents
q include-available-models]} :- [:map {:closed true}
- [:models {:optional true} [:maybe Models]]
+ [:models {:optional true} [:maybe collections.children/Models]]
[:archived {:default false} [:maybe ms/BooleanValue]]
- [:pinned-state {:optional true} [:maybe (into [:enum] children-query/valid-pinned-state-values)]]
- [:sort-column {:optional true} [:maybe (into [:enum] children-query/valid-sort-columns)]]
- [:sort-direction {:optional true} [:maybe (into [:enum] children-query/valid-sort-directions)]]
+ [:pinned-state {:optional true} [:maybe (into [:enum] collections.children/valid-pinned-state-values)]]
+ [:sort-column {:optional true} [:maybe (into [:enum] collections.children/valid-sort-columns)]]
+ [:sort-direction {:optional true} [:maybe (into [:enum] collections.children/valid-sort-directions)]]
[:official-collections-first {:optional true} [:maybe ms/MaybeBooleanValue]]
[:show-dashboard-questions {:default false} [:maybe ms/BooleanValue]]
[:show-exploration-documents {:default false} [:maybe ms/BooleanValue]]
@@ -1192,16 +656,17 @@
:archived? (or archived (:archived collection) (collection/is-trash? collection))
:pinned-state (keyword pinned-state)
:search-text q
- :sort-info {:sort-column (or (some-> sort-column children-query/normalize-sort-choice) :name)
- :sort-direction (or (some-> sort-direction children-query/normalize-sort-choice) :asc)
+ :sort-info {:sort-column (or (some-> sort-column collections.children/normalize-sort-choice) :name)
+ :sort-direction (or (some-> sort-direction collections.children/normalize-sort-choice) :asc)
;; default to sorting official collections first, except for the trash.
:official-collections-first? (if (and (nil? official-collections-first)
(not (collection/is-trash? collection)))
true
(boolean official-collections-first))}}
- children (cond-> (collection-children collection options)
- include-available-models
- (merge (collection-filter-metadata collection nil options)))]
+ children (documents/with-content-gate-cache
+ (cond-> (collections.children/collection-children collection options)
+ include-available-models
+ (merge (collections.children/collection-filter-metadata collection nil options))))]
(events/publish-event! :event/collection-read {:object collection :user-id api/*current-user-id*})
children))
@@ -1214,9 +679,9 @@
[:id [:or ms/PositiveInt ms/NanoIdString]]]
{:keys [models archived pinned-state
show-dashboard-questions show-exploration-documents]} :- [:map {:closed true}
- [:models {:optional true} [:maybe Models]]
+ [:models {:optional true} [:maybe collections.children/Models]]
[:archived {:default false} [:maybe ms/BooleanValue]]
- [:pinned-state {:optional true} [:maybe (into [:enum] children-query/valid-pinned-state-values)]]
+ [:pinned-state {:optional true} [:maybe (into [:enum] collections.children/valid-pinned-state-values)]]
[:show-dashboard-questions {:default false} [:maybe ms/BooleanValue]]
[:show-exploration-documents {:default false} [:maybe ms/BooleanValue]]]]
(let [resolved-id (eid-translation/->id-or-404 :collection id)
diff --git a/src/metabase/collections_rest/children_query.clj b/src/metabase/collections_rest/children_query.clj
deleted file mode 100644
index b9374211410..00000000000
--- a/src/metabase/collections_rest/children_query.clj
+++ /dev/null
@@ -1,656 +0,0 @@
-(ns metabase.collections-rest.children-query
- "Builds the Honey SQL that lists the children of a Collection (`/api/collection/:id/items` and `/root/items`): one
- query per item model, combined with `UNION ALL` and paginated with a `total_count` window. `metabase.collections-rest.db`
- runs the queries built here, so this namespace must not require it."
- (:require
- [clojure.string :as str]
- [honey.sql.helpers :as sql.helpers]
- [medley.core :as m]
- [metabase.api.common :as api]
- [metabase.app-db.core :as mdb]
- [metabase.collections.models.collection :as collection]
- [metabase.permissions.core :as perms]
- [metabase.premium-features.core :refer [defenterprise]]
- [metabase.transforms.util :as transforms.u]
- [metabase.util :as u]
- [metabase.util.honey-sql-2 :as h2x]))
-
-(set! *warn-on-reflection* true)
-
-(def valid-model-param-values
- "Valid values for the `?model=` param accepted by endpoints in this namespace.
- `no_models` is for nilling out the set because a nil model set is actually the total model set"
- #{"card" ; SavedQuestion
- "dataset" ; Model. TODO : update this
- "document"
- "exploration"
- "metric"
- "collection"
- "dashboard"
- "pulse" ; I think the only kinds of Pulses we still have are Alerts?
- "snippet"
- "no_models"
- "timeline"
- "table"
- "transform"
- "measure"})
-
-(def valid-pinned-state-values
- "Valid values for the `?pinned-state` param accepted by endpoints in this namespace."
- #{"all" "is_pinned" "is_not_pinned"})
-
-(def valid-sort-columns
- "Valid values for the `?sort-column` param accepted by endpoints in this module."
- #{"name" "last_edited_at" "last_edited_by" "model" "description"})
-(def valid-sort-directions
- "Valid values for the `?sort-direction` param accepted by endpoints in this module."
- #{"asc" "desc"})
-(defn normalize-sort-choice
- "The keyword for a `?sort-column`/`?sort-direction` param value, e.g. `\"last_edited_at\"` -> `:last-edited-at`."
- [w]
- (when w (keyword (str/replace w #"_" "-"))))
-
-(def CollectionType
- "Collection types that the root/items endpoint can filter on"
- [:enum "remote-synced"])
-
-(def CollectionChildrenOptions
- "The options that select and order the children of a Collection (see [[children-rows-query]])."
- [:map
- [:show-dashboard-questions? :boolean]
- [:show-exploration-documents? :boolean]
- [:collection-type {:optional true} [:maybe CollectionType]]
- [:archived? :boolean]
- [:include-library? {:optional true} [:maybe :boolean]]
- [:pinned-state {:optional true} [:maybe (into [:enum] (map keyword) valid-pinned-state-values)]]
- ;; when specified, only return results of this type.
- [:models {:optional true} [:maybe [:set (into [:enum] (map keyword) valid-model-param-values)]]]
- [:search-text {:optional true} [:maybe :string]]
- [:sort-info {:optional true} [:maybe [:map
- [:sort-column (into [:enum {:error/message "sort-columns"}]
- (map normalize-sort-choice)
- valid-sort-columns)]
- [:sort-direction (into [:enum {:error/message "sort-direction"}]
- (map normalize-sort-choice)
- valid-sort-directions)]
- [:official-collections-first? {:optional true} :boolean]]]]])
-
-(defmulti ^:private collection-children-query
- "Query that will fetch the 'children' of a `collection`, for different types of objects. Possible options are listed
- in the [[CollectionChildrenOptions]] schema above.
-
- NOTES:
-
- * `collection` will be either a CollectionInstance, or the Root Collection special placeholder object, so do not use
- `u/the-id` on it! Use `:id`, which will return `nil` for the Root Collection, which is exactly what we want.
-
- * These queries will be combined into a union-all query. You do not need to put all of the columns into the query,
- any you don't select will be added in the correct position so the union will work (see `all-select-columns` for more
- details)."
- {:arglists '([model collection options])}
- (fn [model _ _] (keyword model)))
-
-;;; TODO -- in Postgres and H2 at least I think we could just do `true` or `false` here... not sure about MySQL.
-
-(def ^:private always-true-hsql-expr
- "A Honey SQL expression that is always true.
-
- 1 = 1"
- [:= [:inline 1] [:inline 1]])
-
-(def ^:private always-false-hsql-expr
- "A Honey SQL expression that is never true.
-
- 1 = 2"
- [:= [:inline 1] [:inline 2]])
-
-(defn- search-text-clause
- "Match every token in `search-text` against an item's name or last editor's first or last name."
- [search-text]
- (when-not (str/blank? search-text)
- (when-let [tokens (->> (str/split (u/lower-case-en (str/trim search-text)) #"\s+")
- (filter seq)
- not-empty)]
- (into [:and]
- (for [token tokens
- :let [pattern (h2x/like-substring token)]]
- [:or
- [:like [:lower :name] pattern]
- [:like [:lower :last_edit_first_name] pattern]
- [:like [:lower :last_edit_last_name] pattern]])))))
-
-(defn- pinned-state->clause
- ([pinned-state]
- (pinned-state->clause pinned-state :collection_position))
- ([pinned-state col]
- (case pinned-state
- :all always-true-hsql-expr
- :is_pinned [:<> col nil]
- :is_not_pinned [:= col nil]
- always-true-hsql-expr)))
-
-(defn- poison-when-pinned-clause
- "Poison a query to return no results when filtering to pinned items. Use for items that do not have a notion of
- pinning so that no results return when asking for pinned items."
- [pinned-state]
- (if (= pinned-state :is_pinned)
- always-false-hsql-expr
- always-true-hsql-expr))
-
-(defmethod collection-children-query :document
- [_ collection {:keys [archived? pinned-state show-exploration-documents?]}]
- (-> {:select [:document.id
- :document.name
- :document.collection_id
- :document.collection_position
- :document.archived
- :document.archived_directly
- :document.exploration_id
- [:u.id :last_edit_user]
- [:u.email :last_edit_email]
- [:u.first_name :last_edit_first_name]
- [:u.last_name :last_edit_last_name]
- [:r.timestamp :last_edit_timestamp]
- [(h2x/literal "document") :model]]
- :from [[:document :document]]
- :left-join [[:revision :r] [:and
- [:= :r.model_id :document.id]
- [:= :r.most_recent true]
- [:= :r.model (h2x/literal "Document")]]
- [:core_user :u] [:= :u.id :r.user_id]]
- :where [:and
- (collection/visible-collection-filter-clause :document.collection_id {:cte-name :visible_collection_ids})
- (if (collection/is-trash? collection)
- [:= :document.archived_directly true]
- [:and
- [:= :document.collection_id (:id collection)]
- [:= :document.archived_directly false]])
- [:= :document.archived (boolean archived?)]
- ;; Hide exploration-attached documents - similar to Dashboard Questions, they're not visible in the
- ;; collection, but only through the Exploration they're in. Callers that want them (e.g. the
- ;; Trash view, embedding SDK) pass show-exploration-documents? to opt in.
- (when-not show-exploration-documents?
- [:= :document.exploration_id nil])]}
- (sql.helpers/where (pinned-state->clause pinned-state :document.collection_position))))
-
-(def ^:private exploration-recent-edits-subquery
- ;; Per-exploration latest edit, unioning the Exploration's own metadata revisions with
- ;; revisions of its Summary Document. `rn = 1` picks the winner.
- ;; The Exploration row is mostly inert post-creation; the meat of editing happens in
- ;; the attached Document, so "Last edited" must reflect both sources.
- ^:allow-subquery
- {:select [:exploration_id
- :timestamp
- :user_id
- [[:over [[:row_number] ^:allow-subquery {:partition-by [:exploration_id]
- :order-by [[:timestamp :desc]]}]] :rn]]
- :from [[^:allow-subquery {:union-all
- [^:allow-subquery
- {:select [[:r.model_id :exploration_id]
- [:r.timestamp :timestamp]
- [:r.user_id :user_id]]
- :from [[:revision :r]]
- :where [:and
- [:= :r.model (h2x/literal "Exploration")]
- [:= :r.most_recent true]]}
- ^:allow-subquery
- {:select [[:d.exploration_id :exploration_id]
- [:r.timestamp :timestamp]
- [:r.user_id :user_id]]
- :from [[:revision :r]]
- :join [[:document :d] [:= :d.id :r.model_id]]
- :where [:and
- [:= :r.model (h2x/literal "Document")]
- [:= :r.most_recent true]
- [:not= :d.exploration_id nil]]}]}
- :all_edits]]})
-
-(defmethod collection-children-query :exploration
- [_ collection {:keys [archived? pinned-state]}]
- (-> {:select [:exploration.id
- :exploration.name
- :exploration.description
- :exploration.entity_id
- :exploration.collection_id
- :exploration.collection_position
- :exploration.archived
- :exploration.archived_directly
- [:u.id :last_edit_user]
- [:u.email :last_edit_email]
- [:u.first_name :last_edit_first_name]
- [:u.last_name :last_edit_last_name]
- [:ere.timestamp :last_edit_timestamp]
- [(h2x/literal "exploration") :model]]
- :from [[:exploration :exploration]]
- :left-join [[exploration-recent-edits-subquery :ere]
- [:and
- [:= :ere.exploration_id :exploration.id]
- [:= :ere.rn [:inline 1]]]
- [:core_user :u] [:= :u.id :ere.user_id]]
- :where [:and
- (collection/visible-collection-filter-clause :exploration.collection_id {:cte-name :visible_collection_ids})
- (if (collection/is-trash? collection)
- [:= :exploration.archived_directly true]
- [:and
- [:= :exploration.collection_id (:id collection)]
- [:= :exploration.archived_directly false]])
- [:= :exploration.archived (boolean archived?)]]}
- (sql.helpers/where (pinned-state->clause pinned-state :exploration.collection_position))))
-
-(defmethod collection-children-query :pulse
- [_ collection {:keys [archived? pinned-state]}]
- (-> {:select-distinct [:p.id
- :p.name
- :p.entity_id
- :p.collection_position
- :p.collection_id
- [(h2x/literal "pulse") :model]]
- :from [[:pulse :p]]
- :left-join [[:pulse_card :pc] [:= :p.id :pc.pulse_id]]
- :where [:and
- [:= :p.collection_id (:id collection)]
- [:= :p.archived (boolean archived?)]
- ;; exclude alerts
- [:= :p.alert_condition nil]
- ;; exclude dashboard subscriptions
- [:= :p.dashboard_id nil]]}
- (sql.helpers/where (pinned-state->clause pinned-state :p.collection_position))))
-
-(defenterprise snippets-collection-children-query
- "Collection children query for snippets on OSS. Returns all snippets regardless of collection, because snippet
- collections are an EE feature."
- metabase-enterprise.snippet-collections.api.native-query-snippet
- [_collection {:keys [archived?]}]
- {:select [:id :name :entity_id [(h2x/literal "snippet") :model]]
- :from [[:native_query_snippet :nqs]]
- :where [:= :archived (boolean archived?)]})
-
-(defmethod collection-children-query :snippet
- [_model collection options]
- (snippets-collection-children-query collection options))
-
-(defmethod collection-children-query :timeline
- [_ collection {:keys [archived? pinned-state]}]
- {:select [:id :collection_id :name [(h2x/literal "timeline") :model] :description :entity_id :icon]
- :from [[:timeline :timeline]]
- :where [:and
- (poison-when-pinned-clause pinned-state)
- [:= :collection_id (:id collection)]
- [:= :archived (boolean archived?)]]})
-
-(defmethod collection-children-query :transform
- [_model collection {:keys [pinned-state]}]
- (let [enabled-types (transforms.u/enabled-source-types-for-user)]
- {:select [:id :collection_id :name [(h2x/literal "transform") :model] :description :entity_id]
- :from [[:transform :transform]]
- :where [:and
- (poison-when-pinned-clause pinned-state)
- [:= :collection_id (:id collection)]
- (if (seq enabled-types)
- [:in :source_type enabled-types]
- [:=
- [:inline 0]
- [:inline 1]])]}))
-
-(defn- card-query [card-type collection {:keys [archived? pinned-state show-dashboard-questions?]}]
- (-> {:select (cond->
- [:c.id :c.name :c.description :c.entity_id :c.collection_position :c.display :c.collection_preview
- :dashboard_id
- :last_used_at
- :c.collection_id
- :c.archived_directly
- :c.archived
- :c.dataset_query
- [(h2x/literal (case card-type
- :model "dataset"
- :metric "metric"
- "card"))
- :model]
- [:u.id :last_edit_user]
- [:u.email :last_edit_email]
- [:u.first_name :last_edit_first_name]
- [:u.last_name :last_edit_last_name]
- [:r.timestamp :last_edit_timestamp]
- [:mr.status :moderated_status]]
- (#{:question :model} card-type)
- (conj :c.database_id))
- :from [[:report_card :c]]
- :left-join [[:revision :r] [:and
- [:= :r.model_id :c.id]
- [:= :r.most_recent true]
- [:= :r.model (h2x/literal "Card")]]
- [:moderation_review :mr] [:and
- [:= :mr.moderated_item_id :c.id]
- [:= :mr.most_recent true]
- [:= :mr.moderated_item_type (h2x/literal "card")]]
- [:core_user :u] [:= :u.id :r.user_id]]
- :where [:and
- (collection/visible-collection-filter-clause :c.collection_id {:cte-name :visible_collection_ids})
- (if (collection/is-trash? collection)
- [:= :c.archived_directly true]
- [:and
- [:= :c.collection_id (:id collection)]
- [:= :c.archived_directly false]])
- (when-not show-dashboard-questions?
- [:= :c.dashboard_id nil])
- [:= :c.document_id nil]
- [:= :c.archived (boolean archived?)]
- (case card-type
- :model
- [:= :c.type (h2x/literal "model")]
-
- :metric
- [:= :c.type (h2x/literal "metric")]
-
- [:= :c.type (h2x/literal "question")])]}
- (cond-> (= :model card-type)
- (-> (sql.helpers/select :c.table_id :t.is_upload :c.query_type)
- (sql.helpers/left-join [:metabase_table :t] [:= :t.id :c.table_id])))
- (sql.helpers/where (pinned-state->clause pinned-state))))
-
-(defmethod collection-children-query :dataset
- [_ collection options]
- (card-query :model collection options))
-
-(defmethod collection-children-query :metric
- [_ collection options]
- (card-query :metric collection options))
-
-(defmethod collection-children-query :card
- [_ collection options]
- (card-query :question collection options))
-
-(defn- dashboard-query [collection {:keys [archived? pinned-state]}]
- (-> {:select [:d.id :d.name :d.description :d.entity_id :d.collection_position
- [:last_viewed_at :last_used_at]
- :d.collection_id
- :d.archived_directly
- [(h2x/literal "dashboard") :model]
- [:u.id :last_edit_user]
- :d.archived
- [:u.email :last_edit_email]
- [:u.first_name :last_edit_first_name]
- [:u.last_name :last_edit_last_name]
- [:r.timestamp :last_edit_timestamp]
- [:mr.status :moderated_status]]
- :from [[:report_dashboard :d]]
- :left-join [[:moderation_review :mr] [:and
- [:= :mr.moderated_item_id :d.id]
- [:= :mr.most_recent true]
- [:= :mr.moderated_item_type (h2x/literal "dashboard")]]
- [:revision :r] [:and
- [:= :r.model_id :d.id]
- [:= :r.most_recent true]
- [:= :r.model (h2x/literal "Dashboard")]]
- [:core_user :u] [:= :u.id :r.user_id]]
- :where [:and
- (collection/visible-collection-filter-clause :d.collection_id {:cte-name :visible_collection_ids})
- (if (collection/is-trash? collection)
- [:= :d.archived_directly true]
- [:and
- [:= :d.collection_id (:id collection)]
- [:not= :d.archived_directly true]])
- [:= :d.archived (boolean archived?)]]}
- (sql.helpers/where (pinned-state->clause pinned-state))))
-
-(defmethod collection-children-query :dashboard
- [_ collection options]
- (dashboard-query collection options))
-
-(defenterprise snippets-collection-filter-clause
- "Clause to filter out snippet collections from the collection query on OSS instances, and instances without the
- snippet-collections. EE implementation returns `nil`, so as to not filter out snippet collections."
- metabase-enterprise.snippet-collections.api.native-query-snippet
- []
- [:or
- [:= :namespace nil]
- [:not= :namespace (u/qualified-name "snippets")]])
-
-(defn- collection-query
- [collection {:keys [archived? collection-namespace pinned-state collection-type include-library?]}]
- (-> (assoc
- (collection/effective-children-query
- collection
- {:cte-name :visible_collection_ids}
- [:and
- (when collection-type
- (if (= collection-type "remote-synced")
- [:= :is_remote_synced true]
- [:= :type collection-type]))
- (when-not include-library?
- [:or [:= nil :type]
- [:not [:in :type [collection/library-collection-type
- collection/library-metrics-collection-type
- collection/library-data-collection-type]]]])
- (if archived?
- [:or
- [:= :archived true]
- [:= :id (collection/trash-collection-id)]]
- [:and [:= :archived false] [:not= :id (collection/trash-collection-id)]])]
- (perms/namespace-clause :namespace (u/qualified-name collection-namespace) (collection/is-trash? collection))
- ;; never show tenant-specific root collections as children of another collection
- [:or
- [:= :type nil]
- [:not= :type collection/tenant-specific-root-collection-type]]
- (snippets-collection-filter-clause))
- ;; We get from the effective-children-query a normal set of columns selected:
- ;; want to make it fit the others to make UNION ALL work
- :select [:id
- [:id :collection_id]
- :archived
- :name
- :description
- :entity_id
- :personal_owner_id
- :location
- :archived_directly
- :namespace
- ;; selected as `type` for compatibility with collection fns that expect it
- :type
- [[:case [:= :is_remote_synced nil] [:inline false] :else :is_remote_synced] :is_remote_synced]
- ;; selected as `collection_type` for fast sorting on "when it's a collection, type"
- [:type :collection_type]
- [(h2x/literal "collection") :model]
- :authority_level])
- ;; the nil indicates that collections are never pinned.
- (sql.helpers/where (pinned-state->clause pinned-state nil))))
-
-(defmethod collection-children-query :collection
- [_ collection options]
- (collection-query collection options))
-
-(defmethod collection-children-query :table
- [_ collection {:keys [archived? pinned-state]}]
- (let [user-info {:user-id api/*current-user-id*
- :is-superuser? api/*is-superuser?*}
- published-clause (perms/published-table-visible-clause :t.id user-info)
- queryable-clause (cond-> [:or
- [:in :t.id (perms/visible-table-filter-select
- :id
- user-info
- {:perms/view-data :unrestricted
- :perms/create-queries :query-builder})]]
- published-clause (conj [:and
- [:in :t.id (perms/visible-table-filter-select
- :id
- user-info
- {:perms/view-data :unrestricted})]
- published-clause]))]
- {:select [:t.id
- [:t.id :table_id]
- [:t.display_name :name]
- :t.description
- :t.collection_id
- [:t.db_id :database_id]
- [[:!= :t.archived_at nil] :archived]
- [(h2x/literal "table") :model]]
- :from [[:metabase_table :t]]
- :where [:and
- [:= :t.is_published true]
- (poison-when-pinned-clause pinned-state)
- (collection/visible-collection-filter-clause :t.collection_id {:cte-name :visible_collection_ids})
- queryable-clause
- [:= :t.collection_id (:id collection)]
- (if archived?
- [:!= :t.archived_at nil]
- [:= :t.archived_at nil])]}))
-
-(defn- select-name
- "Takes a honeysql select column and returns a keyword of which column it is.
-
- eg:
- (select-name :id) -> :id
- (select-name [(literal \"card\") :model]) -> :model
- (select-name :p.id) -> :id"
- [x]
- (if (vector? x)
- (recur (second x))
- (-> x name (str/split #"\.") peek keyword)))
-
-(def ^:private all-select-columns
- "All columns that need to be present for the union-all. Generated with the comment form below. Non-text columns that
- are optional (not id, but last_edit_user for example) must have a type so that the union-all can unify the nil with
- the correct column type."
- [:id :name :description :entity_id :display [:collection_preview :boolean] :dataset_query
- :collection_id
- [:dashboard_id :integer]
- [:archived_directly :boolean]
- :model :collection_position :authority_level [:personal_owner_id :integer] :location
- :last_edit_email :last_edit_first_name :last_edit_last_name :moderated_status :icon
- [:last_edit_user :integer] [:last_edit_timestamp :timestamp] [:database_id :integer]
- :collection_type :type [:archived :boolean] [:last_used_at :timestamp] [:is_remote_synced :boolean] :namespace
- ;; for determining whether a model is based on a csv-uploaded table
- [:table_id :integer] [:is_upload :boolean] :query_type])
-
-(defn- add-missing-columns
- "Ensures that all necessary columns are in the select-columns collection, adding `[nil :column]` as necessary."
- [select-columns necessary-columns]
- (let [columns (m/index-by select-name select-columns)]
- (map (fn [col]
- (let [[col-name type'] (u/one-or-many col)]
- (get columns col-name (if (and type' (= (mdb/db-type) :postgres))
- [(h2x/cast type' nil) col-name]
- [nil col-name]))))
- necessary-columns)))
-
-(defn- add-model-ranking
- [select-clause model]
- (let [rankings {:dashboard 1
- :pulse 2
- :dataset 3
- :metric 4
- :card 5
- :snippet 6
- :collection 7
- :timeline 8}]
- (conj select-clause [[:inline (get rankings model 100)]
- :model_ranking])))
-
-(comment
- ;; generate the set of columns across all child queries. Remember to add type info if not a text column
- (into []
- (comp cat (map select-name) (distinct))
- (for [model [:card :metric :dataset :dashboard :snippet :pulse :collection :timeline]]
- (:select (collection-children-query model {:id 1 :location "/"} nil)))))
-
-(defn- official-collections-first-sort-clause [{:keys [official-collections-first?]}]
- (when official-collections-first?
- [:authority_level :asc :nulls-last]))
-
-(def ^:private normal-collections-first-sort-clause
- [:type :asc :nulls-first])
-
-(defn children-sort-clause
- "Given the client side sort-info, return sort clause to effect this. `db-type` is necessary due to complications from
- treatment of nulls in the different app db types."
- [sort-info db-type]
- (into []
- (comp cat
- (remove nil?))
- [[(official-collections-first-sort-clause sort-info)]
- [normal-collections-first-sort-clause]
- (case ((juxt :sort-column :sort-direction) sort-info)
- [nil nil] [[:%lower.name :asc]]
- [:name :asc] [[:%lower.name :asc]]
- [:name :desc] [[:%lower.name :desc]]
- [:last-edited-at :asc] [(if (= db-type :mysql)
- [:%isnull.last_edit_timestamp]
- [:last_edit_timestamp :nulls-last])
- [:last_edit_timestamp :asc]
- [:%lower.name :asc]]
- [:last-edited-at :desc] [(case db-type
- :mysql [:%isnull.last_edit_timestamp]
- :postgres [:last_edit_timestamp :desc-nulls-last]
- :h2 nil)
- [:last_edit_timestamp :desc]
- [:%lower.name :asc]]
- [:last-edited-by :asc] [(if (= db-type :mysql)
- [:%isnull.last_edit_last_name]
- [:last_edit_last_name :nulls-last])
- [:last_edit_last_name :asc]
- (if (= db-type :mysql)
- [:%isnull.last_edit_first_name]
- [:last_edit_first_name :nulls-last])
- [:last_edit_first_name :asc]
- [:%lower.name :asc]]
- [:last-edited-by :desc] [(case db-type
- :mysql [:%isnull.last_edit_last_name]
- :postgres [:last_edit_last_name :desc-nulls-last]
- :h2 nil)
- [:last_edit_last_name :desc]
- (case db-type
- :mysql [:%isnull.last_edit_first_name]
- :postgres [:last_edit_last_name :desc-nulls-last]
- :h2 nil)
- [:last_edit_first_name :desc]
- [:%lower.name :asc]]
- [:model :asc] [[:model_ranking :asc] [:%lower.name :asc]]
- [:model :desc] [[:model_ranking :desc] [:%lower.name :asc]]
- [:description :asc] [[:%lower.description :asc :nulls-last] [:%lower.name :asc]]
- [:description :desc] [[:%lower.description :desc :nulls-last] [:%lower.name :asc]])
- ;; add a fallback sort order so paging is still deterministic even if collection have the same name or
- ;; whatever
- [[:id :asc]]]))
-
-(defn- visible-collections-config
- "The visibility config of the `visible_collection_ids` CTE: archived listings need write access to the items."
- [{:keys [archived?]}]
- {:include-archived-items :all
- :archive-operation-id nil
- :permission-level (if archived? :write :read)
- :include-trash-collection? archived?})
-
-(defn children-rows-query
- "The query listing the children of `collection` for the item `models` (keywords, in the order to union them),
- filtered and ordered by `options` (see [[CollectionChildrenOptions]]). Every row carries the size of the whole
- result set as `total_count`. `page` is `nil` for the whole result set, or a map with `:limit` and optionally
- `:offset`."
- [collection models {:keys [sort-info search-text] :as options} page]
- (let [sql-order (children-sort-clause sort-info (mdb/db-type))
- queries (for [model models
- :let [query (collection-children-query model collection options)
- select-clause-type (some
- (fn [k]
- (when (get query k)
- k))
- [:select :select-distinct])]]
- (-> query
- (update select-clause-type add-missing-columns all-select-columns)
- (update select-clause-type add-model-ranking model)))
- search-clause (search-text-clause search-text)]
- (cond-> {:with [[:visible_collection_ids (collection/visible-collection-query (visible-collections-config options))]]
- :select [:* [[:over [[:count :*] ^:allow-subquery {} :total_count]]]]
- :from [[^:allow-subquery {:union-all queries} :dummy_alias]]
- :order-by sql-order}
- search-clause (sql.helpers/where search-clause)
- (:limit page) (assoc :limit (:limit page))
- (:offset page) (assoc :offset (:offset page)))))
-
-(defn filter-metadata-query
- "The single-row query whose columns say, for each of the item `models`, whether `collection` has at least one visible
- child of that model under `options`."
- [collection models options]
- {:with [[:visible_collection_ids (collection/visible-collection-query (visible-collections-config options))]]
- :select (vec
- (for [model models]
- [[:exists (collection-children-query model collection options)] model]))})
diff --git a/src/metabase/collections_rest/db.clj b/src/metabase/collections_rest/db.clj
index 9fc21b087ef..b0c0626cff0 100644
--- a/src/metabase/collections_rest/db.clj
+++ b/src/metabase/collections_rest/db.clj
@@ -2,112 +2,20 @@
"Application database queries for the collections REST module. Every function here is a direct Toucan 2 call with no
additional logic, so the rest of the module only touches `toucan2.core` for hydration."
(:require
- [malli.util :as mut]
- [metabase.app-db.core :as app-db]
- [metabase.collections-rest.children-query :as children-query]
- [metabase.collections.models.collection :as collection]
- [metabase.collections.schema :as collections.schema]
[metabase.lib.schema.id :as lib.schema.id]
[metabase.util.malli :as mu]
- [metabase.util.malli.schema :as ms]
[toucan2.core :as t2]))
-(mu/defn other-users-personal-collection-ids
- "The ids of the personal Collections owned by Users other than `user-id`."
- [user-id :- ::lib.schema.id/user]
- (t2/select-fn-set :id :model/Collection
- {:where [:and [:!= :personal_owner_id nil] [:!= :personal_owner_id user-id]]}))
-
-(defn- location-from-collection-id-clause
- "Clause to restrict which collections are being selected based off collection-id. If collection-id is nil,
- then restrict to the children and the grandchildren of the root collection. If collection-id is an an integer,
- then restrict to that collection's parents and children."
- [collection-id]
- (if collection-id
- [:and
- [:like :location (str "%/" collection-id "/%")]
- [:not [:like :location (str "%/" collection-id "/%/%/%")]]]
- [:not [:like :location "/%/%/"]]))
-
-(mu/defn collections-for-listing
- "The Collections the User with `current-user-id` can read, for the listing endpoint: archived or unarchived ones
- (`archived`), only those around `collection-id` when `shallow`, only personal ones when `personal-only`, only the
- user's own personal ones when `exclude-other-user-collections`, library ones only when `include-library?`, and
- those in `namespaces`; official and non-trash Collections first, then by name."
- [{:keys [archived exclude-other-user-collections namespaces shallow collection-id personal-only include-library?]}
- :- [:map {:closed true}
- [:archived {:optional true} [:maybe :boolean]]
- [:exclude-other-user-collections {:optional true} [:maybe :boolean]]
- [:namespaces {:optional true} [:maybe [:or [:set [:maybe :string]] [:sequential [:maybe :string]]]]]
- [:shallow {:optional true} [:maybe :boolean]]
- [:collection-id {:optional true} [:maybe ::lib.schema.id/collection]]
- [:personal-only {:optional true} [:maybe :boolean]]
- [:include-library? {:optional true} [:maybe :boolean]]
- [:permissions-set {:optional true} [:maybe [:set :string]]]]
- current-user-id :- ::lib.schema.id/user]
- (t2/select :model/Collection
- {:where [:and
- (case archived
- nil nil
- false [:and
- [:not= :id (collection/trash-collection-id)]
- [:not :archived]]
- true [:or
- [:= :id (collection/trash-collection-id)]
- :archived])
- (when shallow
- (location-from-collection-id-clause collection-id))
- (when personal-only
- [:!= :personal_owner_id nil])
- (when exclude-other-user-collections
- [:or [:= :personal_owner_id nil] [:= :personal_owner_id current-user-id]])
- (when-not include-library?
- [:or [:= nil :type]
- [:not-in :type [collection/library-collection-type
- collection/library-data-collection-type
- collection/library-metrics-collection-type]]])
- [:or
- (when (contains? namespaces nil)
- [:= :namespace nil])
- (when (seq namespaces)
- [:in :namespace namespaces])]
- (collection/visible-collection-filter-clause
- :id
- {:include-archived-items (if archived
- :only
- :exclude)
- :include-trash-collection? true
- :permission-level :read
- :archive-operation-id nil})]
- ;; Order NULL collection types first so that audit collections are last
- :order-by [[[[:case [:= :authority_level "official"] 0 :else 1]] :asc]
- [[[:case
- [:= :type nil] 0
- [:= :type collection/trash-collection-type] 1
- :else 2]] :asc]
- [:%lower.name :asc]]}))
-
(mu/defn collection
"The Collection with `id`, or nil."
[id :- [:maybe ::lib.schema.id/collection]]
(t2/select-one :model/Collection :id id))
-(mu/defn collection-location-columns
- "The location, id, and type of the Collection with `id`, or nil."
- [id :- ::lib.schema.id/collection]
- (t2/select-one [:model/Collection :location :id :type] :id id))
-
(mu/defn directly-archived-descendant-collections
"The directly archived Collections whose location starts with `location-prefix`."
[location-prefix :- :string]
(t2/select :model/Collection :location [:like (str location-prefix "%")] :archived_directly true))
-(mu/defn update-collection!
- "Apply `changes` to the Collection with `id`."
- [id :- ::lib.schema.id/collection
- changes :- (mut/select-keys ::collections.schema/collection.update [:name :description :authority_level])]
- (t2/update! :model/Collection id changes))
-
(mu/defn delete-collection!
"Delete the Collection with `id`."
[id :- ::lib.schema.id/collection]
@@ -120,19 +28,6 @@
:from [:report_card]
:where [:= :archived false]}))
-(mu/defn unarchived-card-collection-types-in-reducible
- "A reducible of the distinct Collection id and type of the unarchived Cards in the Collections with
- `collection-ids`, leaving out dashboard questions when `exclude-dashboard-questions?`."
- [collection-ids :- [:sequential ::lib.schema.id/collection]
- exclude-dashboard-questions? :- :boolean]
- (t2/reducible-query {:select-distinct [:collection_id :type]
- :from [:report_card]
- :where [:and
- (when exclude-dashboard-questions?
- [:= :dashboard_id nil])
- [:= :archived false]
- [:in :collection_id collection-ids]]}))
-
(mu/defn published-table-collection-ids
"The distinct `:collection_id`s of the published, unarchived Tables."
[]
@@ -142,36 +37,6 @@
[:= :is_published true]
[:= :archived_at nil]]}))
-(mu/defn published-table-collection-ids-in
- "The distinct `:collection_id`s of the published, unarchived Tables in the Collections with `collection-ids`."
- [collection-ids :- [:sequential ::lib.schema.id/collection]]
- (t2/query {:select-distinct [:collection_id]
- :from :metabase_table
- :where [:and
- [:= :is_published true]
- [:= :archived_at nil]
- [:in :collection_id collection-ids]]}))
-
-(mu/defn transform-collection-ids-in
- "The distinct `:collection_id`s of the Transforms with one of `source-types` in the Collections with
- `collection-ids`."
- [collection-ids :- [:sequential ::lib.schema.id/collection]
- source-types :- [:set :string]]
- (t2/query {:select-distinct [:collection_id]
- :from :transform
- :where [:and
- [:in :collection_id collection-ids]
- [:in :source_type source-types]]}))
-
-(mu/defn unarchived-dashboard-collection-ids-in
- "The distinct `:collection_id`s of the unarchived Dashboards in the Collections with `collection-ids`."
- [collection-ids :- [:sequential ::lib.schema.id/collection]]
- (t2/query {:select-distinct [:collection_id]
- :from :report_dashboard
- :where [:and
- [:= :archived false]
- [:in :collection_id collection-ids]]}))
-
(mu/defn top-level-cards-in-collection
"The Cards in the Collection with `collection-id` that belong to no Dashboard, newest first."
[collection-id :- [:maybe ::lib.schema.id/collection]]
@@ -179,28 +44,3 @@
[:= :collection_id collection-id]
[:= :dashboard_id nil]]
:order-by [[:id :desc]]}))
-
-(mu/defn cards-in-collection
- "The Cards in the Collection with `collection-id`."
- [collection-id :- ::lib.schema.id/collection]
- (t2/select :model/Card :collection_id collection-id))
-
-(mu/defn collection-children-rows
- "The children of `collection` for the item `models` (keywords), filtered and ordered by `options` (see
- `metabase.collections-rest.children-query/CollectionChildrenOptions`), every row carrying the whole result set's
- size as `total_count`; `page` is nil for every row, or a map with `:limit` and optionally `:offset`."
- [collection :- collection/CollectionWithLocationAndIDOrRoot
- models :- [:sequential :keyword]
- options :- children-query/CollectionChildrenOptions
- page :- [:maybe [:map {:closed true}
- [:limit ms/IntGreaterThanOrEqualToZero]
- [:offset {:optional true} ms/IntGreaterThanOrEqualToZero]]]]
- (app-db/query (children-query/children-rows-query collection models options page)))
-
-(mu/defn collection-filter-metadata-rows
- "The single row saying, for each of the item `models` (keywords), whether `collection` has at least one visible child
- of that model under `options`."
- [collection :- collection/CollectionWithLocationAndIDOrRoot
- models :- [:sequential :keyword]
- options :- children-query/CollectionChildrenOptions]
- (app-db/query (children-query/filter-metadata-query collection models options)))
diff --git a/src/metabase/comments/core.clj b/src/metabase/comments/core.clj
index 964509df197..281bfcaa9b5 100644
--- a/src/metabase/comments/core.clj
+++ b/src/metabase/comments/core.clj
@@ -1,12 +1,18 @@
(ns metabase.comments.core
"Public surface of the `comments` module."
(:require
+ [metabase.comments.api]
[metabase.comments.models.comment]
[potemkin :as p]))
(comment
+ metabase.comments.api/keep-me
metabase.comments.models.comment/keep-me)
(p/import-vars
+ [metabase.comments.api
+ notify-comment-id!]
[metabase.comments.models.comment
+ child-target-ids-for-document
+ comments-for-document
register-context-gate!])
diff --git a/src/metabase/comments/db.clj b/src/metabase/comments/db.clj
index 89ec0f8d42c..55aef5f3cd9 100644
--- a/src/metabase/comments/db.clj
+++ b/src/metabase/comments/db.clj
@@ -24,6 +24,27 @@
[:= :target_id target-id]]
:order-by [[:created_at :asc]]}))
+(defn document-comments
+ "The Comments on the document with `document-id`, oldest first, ties broken on `:id`.
+
+ Distinct from [[comments-for-target]], which leaves ties undetermined."
+ [document-id]
+ (t2/select :model/Comment
+ :target_type "document"
+ :target_id document-id
+ {:order-by [[:created_at :asc] [:id :asc]]}))
+
+(defn document-child-target-counts
+ "Rows of `:child_target_id` and `:comment_count` for the document with `document-id`, counting only
+ live comments and skipping threads with no child target."
+ [document-id]
+ (t2/select [:model/Comment :child_target_id [:%count.id :comment_count]]
+ :target_type "document"
+ :target_id document-id
+ :child_target_id [:not= nil]
+ :deleted_at nil
+ {:group-by [:child_target_id]}))
+
(mu/defn active-user-ids
"The ids among `user-ids` of active Users, or nil."
[user-ids :- [:sequential ::lib.schema.id/user]]
diff --git a/src/metabase/comments/models/comment.clj b/src/metabase/comments/models/comment.clj
index 171fa88bc46..ba913485ddc 100644
--- a/src/metabase/comments/models/comment.clj
+++ b/src/metabase/comments/models/comment.clj
@@ -132,3 +132,39 @@
(when (pos-int? entity-id)
entity-id))))
(tree-seq :content :content content)))
+
+(defn comments-for-document
+ "A document's comments, oldest first, with `:creator` hydrated. Deleted comments are dropped —
+ except one that still has replies, which stays with its `:content` scrubbed to `{}` so the
+ replies' `:parent_comment_id` keeps something to anchor to, the same deleted-comment rule
+ `GET /api/comment` applies. Read access to the document is the caller's job to check first —
+ the same check-the-target-once pattern the comments REST endpoint uses.
+
+ Matches the endpoint on that scrub rule only; it is not the endpoint's whole response. Reactions
+ are not hydrated (they read `api/*current-user-id*`, which a non-request caller has not bound),
+ and the ordering breaks ties on `:id` where the endpoint leaves them undetermined."
+ [document-id]
+ (let [comments (comments.db/document-comments document-id)
+ has-replies? (into #{} (map :parent_comment_id) comments)]
+ (-> (into []
+ ;; `content_html` is the deprecated pre-render of `:content`. Nothing clears it on
+ ;; delete, so scrubbing `:content` alone would leave a deleted comment's body
+ ;; readable in the column beside it, and nothing rewrites it on edit, so even a live
+ ;; comment's copy can contradict `:content`. The endpoint drops it from every comment
+ ;; (`render-comments`); so do we.
+ (comp (keep (fn [comment]
+ (cond
+ (not (:deleted_at comment)) comment
+ (has-replies? (:id comment)) (assoc comment :content {})
+ :else nil)))
+ (map #(dissoc % :content_html)))
+ comments)
+ (t2/hydrate :creator))))
+
+(defn child-target-ids-for-document
+ "Distinct non-nil `child_target_id` values (with a live comment count each) for a document's
+ comment threads. Read access to the document is the caller's job to check first — the same
+ check-the-target-once pattern the comments REST endpoint uses."
+ [document-id]
+ (->> (comments.db/document-child-target-counts document-id)
+ (mapv #(select-keys % [:child_target_id :comment_count]))))
diff --git a/src/metabase/dashboards/db.clj b/src/metabase/dashboards/db.clj
index b14e15f9726..26463a001ec 100644
--- a/src/metabase/dashboards/db.clj
+++ b/src/metabase/dashboards/db.clj
@@ -25,9 +25,14 @@
(t2/insert-returning-instance! :model/Dashboard row))
(mu/defn update-dashboard!
- "Apply `changes` to the Dashboard with `dashboard-id`, returning the number updated."
+ "Apply `changes` to the Dashboard with `dashboard-id`, returning the number updated.
+
+ Takes the whole `::dashboard.update` — \"what an update (or insert) of a Dashboard accepts\" — the same
+ schema [[insert-dashboard!]] takes. It was narrowed to `[:parameters]` when the only caller wrote nothing
+ else; `metabase.dashboards.write/update-dashboard!` writes the full attribute set (`:name`, `:description`,
+ `:archived`, `:collection_id`, `:cache_ttl`, ...), and a narrowed schema refuses every one of them."
[dashboard-id :- ::lib.schema.id/dashboard
- changes :- (mut/select-keys ::dashboards.schema/dashboard.update [:parameters])]
+ changes :- ::dashboards.schema/dashboard.update]
(t2/update! :model/Dashboard dashboard-id changes))
(mu/defn delete-dashboard-revisions!
@@ -132,6 +137,20 @@
[row :- ::queries.schema/card.update]
(t2/insert-returning-instance! :model/Card row))
+(defn dashboard-question-exists?
+ "Does the Dashboard with `dashboard-id` hold an unarchived Card saved inside it?"
+ [dashboard-id]
+ (t2/exists? :model/Card :dashboard_id dashboard-id :archived false))
+
+(defn card-internal-to-other-dashboard?
+ "Is any Card among `card-ids` saved inside a dashboard other than the one with `dashboard-id`?"
+ [dashboard-id card-ids]
+ (t2/exists? :model/Card
+ {:where [:and
+ [:not= :dashboard_id dashboard-id]
+ [:not= :dashboard_id nil]
+ [:in :id card-ids]]}))
+
(mu/defn dashcard-serdes-columns
"The id, Card, Action, parameter mappings, and visualization settings of the DashboardCards of the Dashboard with
`dashboard-id`."
@@ -215,6 +234,45 @@
(mut/select-keys ::dashboards.schema/dashboard-card-series.update [:dashboardcard_id :card_id :position])]]
(t2/insert! :model/DashboardCardSeries rows))
+(defn parameter-card-card-ids
+ "The Card ids referenced by the ParameterCards of the Dashboard with `dashboard-id`."
+ [dashboard-id]
+ (t2/select-fn-vec :card_id :model/ParameterCard
+ :parameterized_object_type "dashboard"
+ :parameterized_object_id dashboard-id))
+
+(defn dashcard-card-ids
+ "The Card ids of the DashboardCards of the Dashboard with `dashboard-id`."
+ [dashboard-id]
+ (t2/select-fn-vec :card_id :model/DashboardCard :dashboard_id dashboard-id))
+
+(defn dashcard-series-card-ids
+ "The Card ids of the DashboardCardSeries of the Dashboard with `dashboard-id`."
+ [dashboard-id]
+ (t2/select-fn-vec :card_id :model/DashboardCardSeries
+ {:where [:in :dashboardcard_id
+ ^:allow-subquery {:select [:id]
+ :from [(t2/table-name :model/DashboardCard)]
+ :where [:= :dashboard_id dashboard-id]}]}))
+
+(defn dashcard-action-ids
+ "The Action ids of the DashboardCards of the Dashboard with `dashboard-id`."
+ [dashboard-id]
+ (t2/select-fn-vec :action_id :model/DashboardCard :dashboard_id dashboard-id))
+
+(defn dashcard-parameter-mappings
+ "A map of DashboardCard id to parameter mappings for the DashboardCards of the Dashboard with `dashboard-id`."
+ [dashboard-id]
+ (t2/select-pk->fn :parameter_mappings :model/DashboardCard :dashboard_id dashboard-id))
+
+(defn dashcard-card-ids-by-dashcard-id
+ "A map of DashboardCard id to Card id for the DashboardCards with `dashcard-ids` on the Dashboard with
+ `dashboard-id`."
+ [dashboard-id dashcard-ids]
+ (t2/select-pk->fn :card_id :model/DashboardCard
+ :dashboard_id dashboard-id
+ :id [:in dashcard-ids]))
+
;;; ----------------------------------------------- Link cards ----------------------------------------------------
(mu/defn ensure-integer-link-card-id
diff --git a/src/metabase/dashboards/models/dashboard_card.clj b/src/metabase/dashboards/models/dashboard_card.clj
index 26fb504af46..189f7eaffa7 100644
--- a/src/metabase/dashboards/models/dashboard_card.clj
+++ b/src/metabase/dashboards/models/dashboard_card.clj
@@ -111,15 +111,16 @@
(defn virtual-card-settings
"`visualization_settings` for a virtual dashcard — a dashcard with no backing card, such as a text
- card or heading. `display` is the virtual display type as a string (\"text\", \"heading\", ...).
- Mirrors the shape the frontend saves; see `createVirtualCard` in
- frontend/src/metabase/common/utils/dashboard.ts."
- [display text]
- (cond-> {:virtual_card {:name nil
- :display display
- :visualization_settings {}
- :archived false}
- :text text}
+ card, heading, link, or iframe. `display` is the virtual display type as a string (\"text\",
+ \"heading\", \"link\", \"iframe\", ...); `extras` (e.g. `{:text \"...\"}`, `{:link {:url \"...\"}}`)
+ is merged in on top of the `:virtual_card` wrapper. Mirrors the shape the frontend saves; see
+ `createVirtualCard` in frontend/src/metabase/common/utils/dashboard.ts."
+ [display extras]
+ (cond-> (merge {:virtual_card {:name nil
+ :display display
+ :visualization_settings {}
+ :archived false}}
+ extras)
;; headings render without a card background, matching the frontend default
(= display "heading") (assoc :dashcard.background false)))
diff --git a/src/metabase/dashboards/write.clj b/src/metabase/dashboards/write.clj
new file mode 100644
index 00000000000..1ecbf09c4a6
--- /dev/null
+++ b/src/metabase/dashboards/write.clj
@@ -0,0 +1,621 @@
+(ns metabase.dashboards.write
+ "Permission-checked create/update operations for Dashboards, shared by the REST API and other callers.
+
+ These functions return the saved Dashboard row; response-shaping concerns such as hydration and
+ `:last-edit-info` belong to the callers."
+ (:require
+ [clojure.set :as set]
+ [medley.core :as m]
+ [metabase.analytics.core :as analytics]
+ [metabase.api.common :as api]
+ [metabase.collections.core :as collections]
+ [metabase.collections.models.collection :as collection]
+ [metabase.dashboards.db :as dashboards.db]
+ [metabase.dashboards.models.dashboard :as dashboard]
+ [metabase.dashboards.models.dashboard-card :as dashboard-card]
+ [metabase.dashboards.models.dashboard-tab :as dashboard-tab]
+ [metabase.embedding.validation :as embedding.validation]
+ [metabase.events.core :as events]
+ [metabase.lib.schema.id :as lib.schema.id]
+ [metabase.models.interface :as mi]
+ [metabase.parameters.core :as parameters]
+ [metabase.parameters.params :as params]
+ [metabase.parameters.schema :as parameters.schema]
+ [metabase.pulse.broken-subscriptions :as pulse.broken-subscriptions]
+ [metabase.queries.core :as queries]
+ [metabase.query-permissions.core :as query-perms]
+ [metabase.util :as u]
+ [metabase.util.i18n :refer [tru]]
+ [metabase.util.malli :as mu]
+ [metabase.util.malli.schema :as ms]
+ [steffan-westcott.clj-otel.api.trace.span :as span]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(defn- dashcard-card-ids [dashcard]
+ (concat (when-let [card-id (:card_id dashcard)]
+ [card-id])
+ (keep :id (:series dashcard))))
+
+(defn- references
+ [{:keys [dashcards parameters]}]
+ {:cards (into (set (queries/values-source-card-ids parameters))
+ (comp (mapcat dashcard-card-ids) (filter pos-int?))
+ dashcards)
+ :actions (into #{} (keep :action_id) dashcards)})
+
+(defn- stored-references
+ [dashboard-id]
+ {:cards (into (set (dashboards.db/parameter-card-card-ids dashboard-id))
+ (concat (dashboards.db/dashcard-card-ids dashboard-id)
+ (dashboards.db/dashcard-series-card-ids dashboard-id)))
+ :actions (set (dashboards.db/dashcard-action-ids dashboard-id))})
+
+(def ^:private no-references {:cards #{} :actions #{}})
+
+(defn- check-new-references
+ "Read-check every card and action the incoming `dashboard` newly references, relative to `stored`.
+ Lives here rather than at the REST boundary so every writer — MCP's dashboard_write included —
+ gets the check."
+ [stored dashboard]
+ (let [new-references (references dashboard)]
+ (doseq [card-id (set/difference (:cards new-references) (:cards stored))]
+ (api/read-check :model/Card card-id))
+ (doseq [action-id (set/difference (:actions new-references) (:actions stored))]
+ (api/read-check :model/Action action-id))))
+
+(mu/defn create-dashboard! :- :map
+ "Create a Dashboard owned by the current user and return the saved row. `:width` and
+ `:auto_apply_filters` fall back to the column defaults when omitted or nil.
+ Requires create permission on `:collection_id` (nil = root). Publishes `:event/dashboard-create`."
+ [{:keys [name description parameters cache_ttl collection_id collection_position
+ width auto_apply_filters]}
+ :- [:map
+ [:name ms/NonBlankString]
+ [:parameters {:optional true} [:maybe ::parameters.schema/parameters]]
+ [:description {:optional true} [:maybe :string]]
+ [:cache_ttl {:optional true} [:maybe ms/PositiveInt]]
+ [:collection_id {:optional true} [:maybe ms/PositiveInt]]
+ [:collection_position {:optional true} [:maybe ms/PositiveInt]]
+ [:width {:optional true} [:maybe [:enum "fixed" "full"]]]
+ [:auto_apply_filters {:optional true} [:maybe :boolean]]]]
+ ;; if we're trying to save the new dashboard in a Collection make sure we have permissions to do that
+ (api/create-check :model/Dashboard {:collection_id collection_id})
+ (check-new-references no-references {:parameters parameters})
+ (let [dashboard-data (cond-> {:name name
+ :description description
+ :parameters (or parameters [])
+ :creator_id api/*current-user-id*
+ :cache_ttl cache_ttl
+ :collection_id collection_id
+ :collection_position collection_position}
+ ;; both columns are NOT NULL with defaults, so only set them when asked
+ (some? width) (assoc :width width)
+ (some? auto_apply_filters) (assoc :auto_apply_filters auto_apply_filters))
+ dash (t2/with-transaction [_conn]
+ ;; Adding a new dashboard at `collection_position` could cause other dashboards in this
+ ;; collection to change position, check that and fix up if needed
+ (api/maybe-reconcile-collection-position! dashboard-data)
+ ;; Ok, now save the Dashboard
+ (dashboards.db/insert-dashboard! dashboard-data))]
+ (events/publish-event! :event/dashboard-create {:object dash :user-id api/*current-user-id*})
+ (analytics/track-event! :snowplow/dashboard
+ {:event :dashboard-created
+ :dashboard-id (u/the-id dash)})
+ dash))
+
+(defn- check-allowed-to-change-embedding
+ "You must be a superuser to change the value of `enable_embedding`, `embedding_type` or `embedding_params`. Embedding must be
+ enabled."
+ [dash-before-update dash-updates]
+ (when (or (api/column-will-change? :enable_embedding dash-before-update dash-updates)
+ (api/column-will-change? :embedding_type dash-before-update dash-updates)
+ (api/column-will-change? :embedding_params dash-before-update dash-updates))
+ (embedding.validation/check-embedding-enabled)
+ (api/check-superuser)))
+
+(mu/defn- param-target->field-id :- [:maybe ::lib.schema.id/field]
+ [target query]
+ (params/param-target->field-id target {:dataset_query query}))
+
+;; TODO -- should we only check *new* or *modified* mappings?
+(mu/defn- check-parameter-mapping-permissions
+ "Starting in 0.41.0, you must have *data* permissions in order to add or modify a DashboardCard parameter mapping."
+ {:added "0.41.0"}
+ ;; `:dashcard-id`/`:card-id` are stamped on by the callers below before the check runs, and #82196 closed
+ ;; `::parameter-mapping`, so they have to be declared or every mapping write is refused. Kept identical to
+ ;; the REST copy in `metabase.dashboards-rest.api`, which this function is a fork of.
+ [parameter-mappings :- [:sequential [:merge
+ ::parameters.schema/parameter-mapping
+ [:map {:closed true}
+ [:dashcard-id {:optional true} [:maybe ms/PositiveInt]]
+ [:card-id {:optional true} [:maybe ms/PositiveInt]]]]]]
+ (when (seq parameter-mappings)
+ (let [card-ids (into #{} (keep :card-id) parameter-mappings)
+ card-id->query (when (seq card-ids)
+ (dashboards.db/card-queries card-ids))
+ field-ids (into []
+ (keep (fn [{:keys [target card-id]}]
+ (when target
+ (let [query (when card-id
+ (or (card-id->query card-id)
+ (throw (ex-info (tru "Card {0} does not exist or does not have a valid query."
+ card-id)
+ {:status-code 404
+ :card-id card-id}))))]
+ (param-target->field-id target query)))))
+ parameter-mappings)]
+ (query-perms/check-parameter-field-permissions field-ids))))
+
+(defn- existing-parameter-mappings
+ "Returns a map of DashboardCard ID -> parameter mappings for a Dashboard of the form
+
+ {<dashboard-card-id> #{{:target [:dimension [:field 1000 nil]]
+ :parameter_id \"abcdef\"}}}"
+ [dashboard-id]
+ (m/map-vals (fn [mappings]
+ (into #{} (map #(select-keys % [:target :parameter_id])) mappings))
+ (dashboards.db/dashcard-parameter-mappings dashboard-id)))
+
+(defn- check-updated-parameter-mapping-permissions
+ "In 0.41.0+ you now require data permissions for the Table in question to add or modify Dashboard parameter mappings.
+ Check that the current user has the appropriate permissions. Don't check any parameter mappings that already exist
+ for this Dashboard -- only check permissions for new or modified ones."
+ [dashboard-id dashcards]
+ (let [dashcard-id->existing-mappings (existing-parameter-mappings dashboard-id)
+ existing-mapping? (fn [dashcard-id mapping]
+ (let [mapping (parameters/normalize-parameter-mapping mapping)
+ existing-mappings (get dashcard-id->existing-mappings dashcard-id)]
+ (contains? existing-mappings (select-keys mapping [:target :parameter_id]))))
+ new-mappings (for [{mappings :parameter_mappings, dashcard-id :id} dashcards
+ mapping mappings
+ :when (not (existing-mapping? dashcard-id mapping))]
+ (assoc mapping :dashcard-id dashcard-id))
+ ;; need to add the appropriate `:card-id` for all the new mappings we're going to check.
+ dashcard-id->card-id (when (seq new-mappings)
+ (dashboards.db/dashcard-card-ids-by-dashcard-id
+ dashboard-id
+ (set (map :dashcard-id new-mappings))))
+ new-mappings (for [{:keys [dashcard-id], :as mapping} new-mappings]
+ (assoc mapping :card-id (get dashcard-id->card-id dashcard-id)))]
+ (check-parameter-mapping-permissions new-mappings)))
+
+(defn- create-dashcards!
+ [dashboard dashcards]
+ (doseq [card-id (into #{} (comp (mapcat dashcard-card-ids) (filter pos-int?)) dashcards)]
+ (api/check-not-archived (dashboards.db/card card-id)))
+ (check-parameter-mapping-permissions (for [{:keys [card_id parameter_mappings]} dashcards
+ mapping parameter_mappings]
+ (assoc mapping :card-id card_id)))
+ (api/check-500 (dashboard/add-dashcards! dashboard dashcards)))
+
+(defn- update-dashcards! [dashboard dashcards]
+ (check-updated-parameter-mapping-permissions (:id dashboard) dashcards)
+ ;; transform the dashcard data to the format of the DashboardCard model
+ ;; so update-dashcards! can compare them with existing dashcards
+ (dashboard/update-dashcards! dashboard (map dashboard-card/from-parsed-json dashcards))
+ dashcards)
+
+(defn- delete-dashcards! [dashcard-ids]
+ (let [dashboard-cards (dashboards.db/dashcards-by-ids dashcard-ids)]
+ (dashboard-card/delete-dashboard-cards! dashcard-ids)
+ dashboard-cards))
+
+(defn- assert-dashcards-are-not-internal-to-other-dashboards
+ "Reject `new-dashcards` that newly reference a question internal to another dashboard. Card ids the
+ dashboard already references (as a dashcard's card or series, per `existing-dashboard`'s hydrated
+ `:dashcards`) are grandfathered so that pre-existing associations never block saving the dashboard
+ (UXW-4870)."
+ [existing-dashboard new-dashcards]
+ (let [grandfathered-ids (into #{} (mapcat dashcard-card-ids) (:dashcards existing-dashboard))]
+ (when-let [card-ids (seq (remove grandfathered-ids (mapcat dashcard-card-ids new-dashcards)))]
+ (api/check-400 (not (dashboards.db/card-internal-to-other-dashboard?
+ (u/the-id existing-dashboard)
+ (set card-ids)))))))
+
+(defn- do-update-dashcards!
+ [dashboard current-cards new-cards]
+ (let [{:keys [to-create to-update to-delete]} (u/row-diff current-cards new-cards)]
+ (dashboard/archive-or-unarchive-internal-dashboard-questions! (:id dashboard) new-cards)
+ ;; Check both created and updated dashcards: a "Replace" keeps the dashcard id and only swaps
+ ;; card_id, so it lands in `to-update`, not `to-create` (UXW-4731). Card ids the dashboard already
+ ;; references are grandfathered, so pre-existing foreign internal cards don't block saving (UXW-4870).
+ (assert-dashcards-are-not-internal-to-other-dashboards dashboard (concat to-create to-update))
+ (when (seq to-update)
+ (update-dashcards! dashboard to-update))
+ {:deleted-dashcards (when (seq to-delete)
+ (delete-dashcards! (map :id to-delete)))
+ :created-dashcards (when (seq to-create)
+ (create-dashcards! dashboard to-create))}))
+
+(def UpdatedDashboardCard
+ "Schema for one dashcard in a dashboard update payload. A negative `:id` marks a dashcard to
+ create; positive ids name existing rows, and rows absent from the payload are deleted."
+ [:map
+ [:id int?]
+ [:size_x ms/PositiveInt]
+ [:size_y ms/PositiveInt]
+ [:row ms/IntGreaterThanOrEqualToZero]
+ [:col ms/IntGreaterThanOrEqualToZero]
+ [:card_id {:optional true} [:maybe ms/PositiveInt]]
+ [:action_id {:optional true} [:maybe ms/PositiveInt]]
+ [:dashboard_tab_id {:optional true} [:maybe int?]]
+ [:parameter_mappings {:optional true} [:maybe [:ref ::parameters.schema/parameter-mappings]]]
+ [:visualization_settings {:optional true} [:maybe ms/VisualizationSettings]]
+ [:inline_parameters {:optional true} [:maybe [:sequential ms/NonBlankString]]]
+ [:series {:optional true} [:maybe [:sequential [:map [:id ms/PositiveInt]]]]]])
+
+(def UpdatedDashboardTab
+ "Schema for one tab in a dashboard update payload. A negative `:id` marks a tab to create;
+ positive ids name existing rows, and rows absent from the payload are deleted."
+ [:map
+ [:id ms/Int]
+ [:name ms/NonBlankString]
+ ;; tab order -- `metabase.dashboards.models.dashboard-tab/do-update-tabs!` writes it alongside `:name`
+ [:position {:optional true} ms/IntGreaterThanOrEqualToZero]])
+
+(defn- track-dashcard-and-tab-events!
+ [{dashboard-id :id :as dashboard}
+ {:keys [created-dashcards deleted-dashcards
+ created-tab-ids deleted-tab-ids total-num-tabs]}]
+ ;; Dashcard events
+ (when (seq deleted-dashcards)
+ (events/publish-event! :event/dashboard-remove-cards
+ {:object dashboard :user-id api/*current-user-id* :dashcards deleted-dashcards}))
+ (when (seq created-dashcards)
+ (events/publish-event! :event/dashboard-add-cards
+ {:object dashboard :user-id api/*current-user-id* :dashcards created-dashcards})
+ (doseq [{:keys [card_id]} created-dashcards
+ :when (pos-int? card_id)]
+ (analytics/track-event! :snowplow/dashboard
+ {:event :question-added-to-dashboard
+ :dashboard-id dashboard-id
+ :question-id card_id})))
+ ;; Tabs events
+ (when (seq deleted-tab-ids)
+ (analytics/track-event! :snowplow/dashboard
+ {:event :dashboard-tab-deleted
+ :dashboard-id dashboard-id
+ :num-tabs (count deleted-tab-ids)
+ :total-num-tabs total-num-tabs}))
+ (when (seq created-tab-ids)
+ (analytics/track-event! :snowplow/dashboard
+ {:event :dashboard-tab-created
+ :dashboard-id dashboard-id
+ :num-tabs (count created-tab-ids)
+ :total-num-tabs total-num-tabs})))
+
+(defn update-dashboard!
+ "Update the Dashboard with `id` and return the saved row. `dash-updates` may carry
+ dashboard attributes plus `:dashcards` and `:tabs`, which fully replace the current layout — entries
+ with negative ids are created, missing entries are deleted. Requires write permission on the dashboard;
+ runs in one transaction. Publishes `:event/dashboard-update` and may notify owners of broken subscriptions."
+ [id {:keys [dashcards tabs parameters] :as dash-updates}]
+ (span/with-span!
+ {:name "update-dashboard"
+ :attributes {:dashboard/id id}}
+ (check-new-references (stored-references id) dash-updates)
+ (let [current-dash (api/write-check :model/Dashboard id)
+ ;; If there are parameters in the update, we want the old params so that we can do a check to see if any of
+ ;; the notifications were broken by the update.
+ {original-params :resolved-params} (when parameters
+ (t2/hydrate
+ (dashboards.db/dashboard id)
+ [:dashcards :card]
+ :resolved-params))
+ changes-stats (atom nil)
+ ;; tabs are always sent in production as well when dashcards are updated, but there are lots of
+ ;; tests that exclude it. so this only checks for dashcards
+ update-dashcards-and-tabs? (contains? dash-updates :dashcards)
+ dash-updates (api/updates-with-archived-directly current-dash dash-updates)]
+ (collection/check-allowed-to-change-collection current-dash dash-updates)
+ (check-allowed-to-change-embedding current-dash dash-updates)
+ (api/check-500
+ (do
+ (t2/with-transaction [_conn]
+ ;; If the dashboard has an updated position, or if the dashboard is moving to a new collection, we might need to
+ ;; adjust the collection position of other dashboards in the collection
+ (api/maybe-reconcile-collection-position! current-dash dash-updates)
+ (when-let [updates (not-empty
+ (u/select-keys-when
+ dash-updates
+ :present #{:description :position :width :collection_id :collection_position :cache_ttl :archived_directly :embedding_type}
+ :non-nil #{:name :parameters :caveats :points_of_interest :show_in_getting_started :enable_embedding
+ :embedding_params :archived :auto_apply_filters}))]
+ (dashboard/cascade-card-state-from-dashboard-update! current-dash dash-updates)
+ (dashboards.db/update-dashboard! id updates)
+ (when (contains? updates :collection_id)
+ (events/publish-event! :event/collection-touch {:collection-id id :user-id api/*current-user-id*}))
+ ;; Handle broken subscriptions, if any, when parameters changed
+ (when parameters
+ (pulse.broken-subscriptions/handle-broken-subscriptions! id original-params)))
+ (when update-dashcards-and-tabs?
+ (when (not (false? (:archived false)))
+ (api/check-not-archived current-dash))
+ (let [{current-dashcards :dashcards
+ current-tabs :tabs
+ :as hydrated-current-dash} (t2/hydrate current-dash [:dashcards :series :card] :tabs)
+ new-tabs (map-indexed (fn [idx tab] (assoc tab :position idx)) tabs)
+ dashcards (if (= 1 (count new-tabs))
+ (let [single-tab-id (-> new-tabs first :id)]
+ (mapv #(if (nil? (:dashboard_tab_id %))
+ (assoc % :dashboard_tab_id single-tab-id)
+ %)
+ dashcards))
+ dashcards)
+ _ (when (and (seq new-tabs)
+ (not (every? #(some? (:dashboard_tab_id %)) dashcards)))
+ (throw (ex-info (tru "This dashboard has tab, makes sure every card has a tab")
+ {:status-code 400})))
+ {:keys [old->new-tab-id
+ deleted-tab-ids]
+ :as tabs-changes-stats} (dashboard-tab/do-update-tabs! (:id current-dash) current-tabs new-tabs)
+ deleted-tab-ids (set deleted-tab-ids)
+ current-dashcards (remove (fn [dashcard]
+ (contains? deleted-tab-ids (:dashboard_tab_id dashcard)))
+ current-dashcards)
+ new-dashcards (cond->> dashcards
+ ;; fixup the temporary tab ids with the real ones
+ (seq old->new-tab-id)
+ (map (fn [card]
+ (if-let [real-tab-id (get old->new-tab-id (:dashboard_tab_id card))]
+ (assoc card :dashboard_tab_id real-tab-id)
+ card))))
+ dashcards-changes-stats (do-update-dashcards! hydrated-current-dash current-dashcards new-dashcards)]
+ (reset! changes-stats
+ (merge
+ (select-keys tabs-changes-stats [:created-tab-ids :deleted-tab-ids :total-num-tabs])
+ (select-keys dashcards-changes-stats [:created-dashcards :deleted-dashcards])))))
+ (collections/check-for-remote-sync-update current-dash))
+ true))
+ (let [dashboard (dashboards.db/dashboard id)]
+ ;; skip publishing the event if it's just a change in its collection position
+ (when-not (= #{:collection_position}
+ (set (keys dash-updates)))
+ (events/publish-event! :event/dashboard-update {:object dashboard :user-id api/*current-user-id*}))
+ (track-dashcard-and-tab-events! dashboard @changes-stats)
+ dashboard))))
+
+(def DashUpdates
+ "Schema for the `dash-updates` argument to [[update-dashboard!]]: dashboard attributes plus the
+ optional `:dashcards`/`:tabs` full-replacement layout."
+ [:map
+ [:name {:optional true} [:maybe ms/NonBlankString]]
+ [:description {:optional true} [:maybe :string]]
+ [:caveats {:optional true} [:maybe :string]]
+ [:points_of_interest {:optional true} [:maybe :string]]
+ [:show_in_getting_started {:optional true} [:maybe :boolean]]
+ [:enable_embedding {:optional true} [:maybe :boolean]]
+ [:embedding_type {:optional true} [:maybe :string]]
+ [:embedding_params {:optional true} [:maybe ms/EmbeddingParams]]
+ [:parameters {:optional true} [:maybe ::parameters.schema/parameters]]
+ [:position {:optional true} [:maybe ms/PositiveInt]]
+ [:width {:optional true} [:enum "fixed" "full"]]
+ [:archived {:optional true} [:maybe :boolean]]
+ [:collection_id {:optional true} [:maybe ms/PositiveInt]]
+ [:collection_position {:optional true} [:maybe ms/PositiveInt]]
+ [:cache_ttl {:optional true} [:maybe ms/PositiveInt]]
+ [:auto_apply_filters {:optional true} [:maybe :boolean]]
+ [:dashcards {:optional true} [:maybe (ms/maps-with-unique-key [:sequential UpdatedDashboardCard] :id)]]
+ [:tabs {:optional true} [:maybe (ms/maps-with-unique-key [:sequential UpdatedDashboardTab] :id)]]])
+
+;;; ---------------------------------------------------- Copying -------------------------------------------------------
+
+(mu/defn- cards-to-copy :- [:map
+ [:discard [:sequential :any]]
+ [:copy [:map-of ms/PositiveInt :any]]
+ [:reference [:map-of ms/PositiveInt :any]]]
+ "Returns a map of which cards we need to copy, which cards we need to reference, and which are not to be copied. The
+ `:copy` and `:reference` keys are maps from id to card. The `:discard` key is a vector of cards left out because
+ the caller cannot read them (or their series' base card), or because they are archived; a card discarded for
+ unreadability is reduced to `{:id id}`.
+
+ If we're making a deep copy, we copy all cards that we have necessary permissions on. Otherwise, we copy Dashboard
+ Questions (questions stored 'in' the dashboard rather than a collection) and reference the rest (assuming
+ permissions)."
+ [deep-copy? :- ms/MaybeBooleanValue
+ dashcards :- [:sequential :any]]
+ (let [card->cards (fn [{:keys [card series]}] (into [card] series))
+ readable? (fn [card] (and (mi/model card) (mi/can-read? card)))
+ card->decision (fn [parent-card card]
+ (cond
+ (or
+ (not (readable? parent-card))
+ (not (readable? card))
+ (:archived card))
+ :discard
+
+ (or (:dashboard_id card)
+ (and deep-copy? (not= :model (:type card))))
+ :copy
+
+ :else :reference))
+ ;; `:discard` rides out on the copy response as `:uncopied`, so a card kept out because the
+ ;; caller cannot read it must not be returned in full.
+ redact (fn [card] (if (readable? card) card (select-keys card [:id])))
+ split-cards (fn [{:keys [card] :as db-card}]
+ (let [cards (card->cards db-card)]
+ (-> (group-by (partial card->decision card) cards)
+ (m/update-existing :discard #(mapv redact %)))))]
+ (reduce (fn [acc db-card]
+ (let [{:keys [discard copy reference]} (split-cards db-card)]
+ (-> acc
+ (update :reference merge (m/index-by :id reference))
+ (update :copy merge (m/index-by :id copy))
+ (update :discard concat discard))))
+ {:reference {}
+ :copy {}
+ :discard []}
+ (filter :card_id dashcards))))
+
+(defn- maybe-duplicate-cards
+ "Takes a dashboard id, and duplicates the cards both on the dashboard's cards and dashcardseries as necessary.
+
+ Returns `{:copied {old-card-id duplicated-card} :referenced {old-card-id card} :discarded [card]}` so that the new
+ dashboard can adjust accordingly. `:discarded` carries [[cards-to-copy]]'s redaction.
+
+ If `deep-copy?` is `false`, doesn't copy any cards *except* for Dashboard Questions, which must be copied."
+ [deep-copy? new-dashboard old-dashboard dest-coll-id]
+ (let [same-collection? (= (:collection_id old-dashboard) dest-coll-id)
+ {:keys [copy discard reference]} (cards-to-copy deep-copy? (:dashcards old-dashboard))]
+ {:copied (into {} (for [[id to-copy] copy]
+ [id (queries/create-card!
+ (cond-> to-copy
+ true (assoc :collection_id dest-coll-id)
+ same-collection? (update :name #(str % " - " (tru "Duplicate")))
+ (:dashboard_id to-copy) (assoc :dashboard_id (u/the-id new-dashboard)))
+ @api/*current-user*
+ ;; creating cards from a transaction. wait until tx complete to signal event
+ true
+ ;; do not autoplace these cards. we will create the dashboard cards ourselves.
+ false)]))
+ :discarded discard
+ :referenced reference}))
+
+(defn- duplicate-tabs
+ [new-dashboard existing-tabs]
+ (let [new-tab-ids (dashboards.db/insert-dashboard-tabs!
+ (for [tab existing-tabs]
+ (-> tab
+ (assoc :dashboard_id (:id new-dashboard))
+ (dissoc :id :entity_id :created_at :updated_at))))]
+ (zipmap (map :id existing-tabs) new-tab-ids)))
+
+(defn- update-colvalmap-setting
+ "Visualizer dashcards have unique visualization settings which embed column id remapping metadata
+ This function iterates through the `:columnValueMapping` viz setting and updates referenced card ids
+
+ col->val-source can look like:
+ {:COLUMN_2 [{:sourceId 'card:<OLD_CARD_ID>', :originalName 'sum', :name 'COLUMN_2'}], ...}"
+ [col->val-source id->new-card]
+ (let [update-cvm-item (fn [item]
+ (if-let [source-id (:sourceId item)]
+ (if-let [[_ card-id] (and (string? source-id)
+ (re-find #"^card:(\d+)$" source-id))]
+ (if-let [new-card (get id->new-card (Long/parseLong card-id))]
+ (assoc item :sourceId (str "card:" (:id new-card)))
+ item)
+ item)
+ item))
+ update-cvm (fn [cvm]
+ (when (map? cvm)
+ (update-vals cvm #(mapv update-cvm-item %))))]
+ (update-cvm col->val-source)))
+
+(defn update-cards-for-copy
+ "Update dashcards in a dashboard for copying.
+ If the dashboard has tabs, fix up the tab ids in dashcards to point to the new tabs.
+ Then if shallow copy, return the cards. If deep copy, replace ids with id from the newly-copied cards.
+ A dashcard whose card was neither copied nor referenced is omitted — [[cards-to-copy]] discarded it as unreadable
+ or archived."
+ [dashcards id->new-card id->referenced-card id->new-tab-id]
+ (let [dashcards (if (seq id->new-tab-id)
+ (map #(assoc % :dashboard_tab_id (id->new-tab-id (:dashboard_tab_id %)))
+ dashcards)
+ dashcards)]
+ (keep (fn [dashboard-card]
+ (cond
+ (:action_id dashboard-card)
+ nil
+
+ (some-> dashboard-card :visualization_settings :virtual_card :display #{"iframe"})
+ dashboard-card
+
+ ;; text cards need no manipulation
+ (some-> dashboard-card :visualization_settings :virtual_card :display #{"text" "heading"})
+ dashboard-card
+
+ ;; referenced cards need no manipulation
+ (get id->referenced-card (:card_id dashboard-card))
+ dashboard-card
+
+ ;; if we didn't duplicate, it doesn't go in the dashboard
+ (not (get id->new-card (:card_id dashboard-card)))
+ nil
+
+ :else
+ (let [new-id (fn [id]
+ (-> id id->new-card :id))]
+ (-> dashboard-card
+ (update :card_id new-id)
+ (assoc :card (-> dashboard-card :card_id id->new-card))
+ (m/update-existing :parameter_mappings
+ (fn [pms]
+ (keep (fn [pm]
+ (m/update-existing pm :card_id new-id))
+ pms)))
+ (m/update-existing :series
+ (fn [series]
+ (keep (fn [card]
+ (when-let [id' (new-id (:id card))]
+ (assoc card :id id')))
+ series)))
+ (m/update-existing-in [:visualization_settings :visualization :columnValuesMapping]
+ update-colvalmap-setting id->new-card)))))
+ dashcards)))
+
+(defn contains-dashboard-questions?
+ "Does the dashboard with `id` hold any live questions saved inside it? Such a dashboard cannot be
+ shallow-copied — the questions would have nowhere to live."
+ [id]
+ (dashboards.db/dashboard-question-exists? id))
+
+(defn copy-dashboard!
+ "Copy the dashboard with `from-dashboard-id` into `:collection_id` (nil = root) and return the saved
+ row, carrying `:uncopied` when permissions kept some cards out of the copy. `copy-opts` may override
+ `:name`/`:description` and set `:collection_position`; `:is_deep_copy` also duplicates the dashboard's
+ questions, which is mandatory when it holds Dashboard Questions.
+
+ Requires read permission on the source and create permission on the destination collection. Publishes
+ `:event/dashboard-create` and `:event/card-create` for each duplicated card."
+ [from-dashboard-id {:keys [name description collection_id collection_position is_deep_copy]}]
+ ;; if we're trying to save the new dashboard in a Collection make sure we have permissions to do that
+ (api/create-check :model/Dashboard {:collection_id collection_id})
+ (api/check-400 (not (and (not is_deep_copy)
+ (contains-dashboard-questions? from-dashboard-id)))
+ (tru "You cannot do a shallow copy of this dashboard because it contains Dashboard Questions."))
+ (let [existing-dashboard (-> (api/read-check :model/Dashboard from-dashboard-id)
+ (t2/hydrate [:dashcards :card :series] :tabs))
+ dashboard-data {:name (or name (:name existing-dashboard))
+ :description (or description (:description existing-dashboard))
+ :parameters (or (:parameters existing-dashboard) [])
+ :creator_id api/*current-user-id*
+ :collection_id collection_id
+ :collection_position collection_position
+ :width (:width existing-dashboard)}
+ new-cards (atom nil)
+ dashboard (t2/with-transaction [_conn]
+ ;; Adding a new dashboard at `collection_position` could cause other dashboards in this
+ ;; collection to change position, check that and fix up if needed
+ (api/maybe-reconcile-collection-position! dashboard-data)
+ ;; Ok, now save the Dashboard
+ (let [dash (dashboards.db/insert-dashboard! dashboard-data)
+ {id->new-card :copied
+ id->referenced-card :referenced
+ uncopied :discarded}
+ (maybe-duplicate-cards is_deep_copy dash existing-dashboard collection_id)
+
+ id->new-tab-id (when-let [existing-tabs (seq (:tabs existing-dashboard))]
+ (duplicate-tabs dash existing-tabs))]
+ (reset! new-cards (vals id->new-card))
+ (when-let [dashcards (seq (update-cards-for-copy (:dashcards existing-dashboard)
+ id->new-card
+ id->referenced-card
+ id->new-tab-id))]
+ (api/check-500 (dashboard/add-dashcards! dash dashcards)))
+ (u/prog1 (cond-> dash
+ (seq uncopied)
+ (assoc :uncopied uncopied))
+ (when (collections/moving-into-remote-synced? (:collection_id existing-dashboard)
+ collection_id)
+ (collections/check-non-remote-synced-dependencies <>)))))]
+ (analytics/track-event! :snowplow/dashboard
+ {:event :dashboard-created
+ :dashboard-id (u/the-id dashboard)})
+ ;; must signal event outside of tx so cards are visible from other threads
+ (when-let [newly-created-cards (seq @new-cards)]
+ (doseq [card newly-created-cards]
+ (events/publish-event! :event/card-create {:object card :user-id api/*current-user-id*})))
+ (events/publish-event! :event/dashboard-create {:object dashboard :user-id api/*current-user-id*})
+ dashboard))
diff --git a/src/metabase/dashboards_rest/api.clj b/src/metabase/dashboards_rest/api.clj
index faa7865c553..582c8f68f07 100644
--- a/src/metabase/dashboards_rest/api.clj
+++ b/src/metabase/dashboards_rest/api.clj
@@ -12,7 +12,7 @@
[metabase.api.macros :as api.macros]
[metabase.channel.email.messages :as messages]
[metabase.channel.render.core :as channel.render]
- [metabase.collections-rest.api :as api.collection]
+ [metabase.collections.children :as collections.children]
[metabase.collections.core :as collections]
[metabase.collections.models.collection :as collection]
[metabase.collections.models.collection.root :as collection.root]
@@ -716,9 +716,9 @@
(let [dashboard (api/read-check :model/Dashboard id)
cards (dashboards-rest.db/dashboard-item-cards id (request/paged?) (request/limit) (request/offset))]
{:total (count cards)
- :data (api.collection/post-process-rows {}
- (dashboards-rest.db/collection (:collection_id dashboard))
- cards)
+ :data (collections.children/post-process-rows {}
+ (dashboards-rest.db/collection (:collection_id dashboard))
+ cards)
:limit (request/limit)
:offset (request/offset)
:models (if (seq cards) ["card"] [])}))
diff --git a/src/metabase/documents/api/document.clj b/src/metabase/documents/api/document.clj
index a38fe4b9408..be8b7b8c77a 100644
--- a/src/metabase/documents/api/document.clj
+++ b/src/metabase/documents/api/document.clj
@@ -10,14 +10,9 @@
[metabase.documents.prose-mirror :as prose-mirror]
[metabase.documents.schema :as documents.schema]
[metabase.events.core :as events]
- [metabase.lib-be.schema :as lib-be.schema]
[metabase.models.interface :as mi]
- [metabase.parameters.params :as params]
[metabase.parameters.schema :as parameters.schema]
[metabase.public-sharing.validation :as public-sharing.validation]
- [metabase.queries.core :as card]
- [metabase.queries.schema :as queries.schema]
- [metabase.query-permissions.core :as query-perms]
[metabase.query-processor.api :as api.dataset]
[metabase.query-processor.card :as qp.card]
[metabase.util :as u]
@@ -26,27 +21,12 @@
[metabase.util.malli.schema :as ms]
[toucan2.core :as t2]))
-(def ^:private CardCreateSchema
- "Schema for creating a new card - simplified version to avoid circular dependencies"
- [:map {:closed true}
- [:name ms/NonBlankString]
- [:dataset_query ::lib-be.schema/maybe-legacy-query]
- [:entity_id {:optional true} [:maybe ms/NonBlankString]]
- [:parameters {:optional true} [:maybe ::parameters.schema/parameters]]
- [:parameter_mappings {:optional true} [:maybe ::parameters.schema/parameter-mappings]]
- [:description {:optional true} [:maybe ms/NonBlankString]]
- [:display ms/NonBlankString]
- [:visualization_settings ms/VisualizationSettings]
- [:result_metadata {:optional true} [:maybe ::queries.schema/card.result-metadata]]
- [:cache_ttl {:optional true} [:maybe ms/PositiveInt]]])
-
(defn- cards-to-create-schema
"Request schema for the `cards` map: placeholder id -> new card.
- The strict `[:map-of key-schema CardCreateSchema]` can't be the request schema directly. Request decoding strips
- `:map-of` entries that don't match their schema, so an unusable card would be quietly dropped and the document
- saved without it. Decoding therefore sees a permissive `[:map-of :int :any]` — enough to turn the JSON string keys
- into ints — and the `:fn` re-checks the strict shape afterwards, so a bad card is a 400."
+ Plain `:map-of` can't be the request schema directly — request decoding silently strips entries that don't match,
+ so an unusable card would vanish and the document would save without it. Decoding each key and value explicitly
+ turns a bad card into a 400 instead."
[key-schema]
[:schema
{:decode/normalize (fn [cards]
@@ -54,8 +34,9 @@
(map? cards)
(-> (update-keys #(api.macros/decode-and-validate-params
:body key-schema (cond-> % (keyword? %) u/qualified-name)))
- (update-vals #(api.macros/decode-and-validate-params :body CardCreateSchema %)))))}
- [:map-of key-schema CardCreateSchema]])
+ (update-vals #(api.macros/decode-and-validate-params
+ :body m.document/CardCreateSchema %)))))}
+ [:map-of key-schema m.document/CardCreateSchema]])
(def ^:private DocumentCreateOptions
[:map {:closed true}
@@ -74,140 +55,6 @@
[:cards {:optional true} [:maybe (cards-to-create-schema :int)]]
[:archived {:optional true} [:maybe :boolean]]])
-(defn- create-card!
- "The single choke point every document card-creation path (create, update, copy) funnels through. Runs the same
- checks `POST /api/card` runs before saving: create access to the target collection, run permission on the query,
- read access to any card the parameters draw values from, and query permission on the fields the parameter targets
- name."
- [{query :dataset_query :as card} creator]
- (api/create-check :model/Card {:collection_id (:collection_id card)})
- (query-perms/check-run-permissions-for-query (dissoc query :query-permissions/perms))
- (card/check-parameter-source-card-permissions (:parameters card))
- (query-perms/check-parameter-field-permissions
- (into []
- (keep #(some-> % :target (params/param-target->field-id {:dataset_query query})))
- (:parameters card)))
- (card/create-card! (assoc card :type :question :dashboard_id nil) creator))
-
-(defn- clone-card!
- "Saves a copy of an existing card the user can already read, e.g. when embedding it into a document.
-
- Still checks create access to the target collection, but unlike [[create-card!]] deliberately skips the authoring
- checks (run permission on the query, parameter source-card and parameter field permissions): the query and
- parameters come from an existing card row the caller passed a read check on rather than from the request, so the
- user is not authoring anything -- they may be able to view (and run) the source card without having permission to
- write such a query themselves, e.g. a native card when they lack native query editing perms (UXW-5037). Running the
- clone is still gated by the usual runtime permission checks, the same ones that gate running the source card."
- [card creator]
- (api/create-check :model/Card {:collection_id (:collection_id card)})
- (card/create-card! (assoc card :type :question :dashboard_id nil) creator))
-
-(mu/defn- update-cards-in-ast :- [:map [:document :any]
- [:content_type :string]]
-
- [document :- [:map
- [:document :any]
- [:content_type :string]]
- card-id-map :- [:maybe [:map-of :int ms/PositiveInt]]]
- (cond-> document
- (map? document)
- (prose-mirror/update-ast (fn match-card-to-update [{:keys [type attrs]}]
- (and (= type prose-mirror/card-embed-type)
- (contains? card-id-map (get attrs "id"))))
- (fn update-card-id [embed]
- (update-in embed [:attrs "id"] card-id-map)))))
-
-(mu/defn- create-cards-for-document! :- [:map-of ms/NegativeInt ms/PositiveInt]
- "Creates cards for a document from the cards map.
- Returns a mapping from the original negative integer keys to the newly created card IDs.
-
- Args:
- - cards-to-create: Map of negative-int -> CardCreateSchema data
- - document-id: ID of the document these cards belong to
- - document-collection-id: Collection ID of the document (for inheritance)
- - creator: User creating the cards
-
- Returns:
- - Map of negative-int -> actual-card-id"
- [cards-to-create :- [:map-of [:int {:max -1}] CardCreateSchema]
- document-id :- ms/PositiveInt
- document-collection-id :- [:or :nil ms/PositiveInt]
- creator :- [:map [:id ms/PositiveInt]]]
- (when (seq cards-to-create)
- (reduce-kv
- (fn [result-map original-key card-data]
- (let [;; Merge document info into card data
- ;; Cards inherit document's collection_id if not explicitly specified
- merged-card-data (-> card-data
- (assoc :document_id document-id)
- (cond-> (nil? (:collection_id card-data))
- (assoc :collection_id document-collection-id)))
- ;; Create the card using the queries core function
- new-card (create-card! merged-card-data creator)]
- (assoc result-map original-key (:id new-card))))
- {}
- cards-to-create)))
-
-(mu/defn- clone-cards-in-document! :- [:map-of ms/PositiveInt ms/PositiveInt]
- "Finds all cards in the document that are not associated with the document and clones the cards.
-
- Args:
- - document: the document model to clone cards within
-
- Returns:
- - map of old-card-id -> cloned-card-id"
- [{:keys [id collection_id] :as document}]
- (let [card-ids (prose-mirror/collect-ast document #(when (and (= prose-mirror/card-embed-type (:type %))
- (pos-int? (get-in % [:attrs "id"])))
- (get-in % [:attrs "id"])))
- to-clone (when (seq card-ids)
- (documents.db/cards-not-in-document card-ids id))]
- (m.document/with-content-gate-cache
- (reduce (fn [accum card]
- (api/read-check card)
- (assoc accum
- (:id card)
- (:id (clone-card! (assoc card :document_id id :collection_id collection_id)
- @api/*current-user*))))
- {}
- to-clone))))
-
-(defn- hydrate-document
- "Fetch a document by id along with the derived fields the API returns. Does *not* check permissions or
- publish a read event, so it is safe to use on write paths (PUT/POST) where recording a view would be
- both semantically wrong and an extra, avoidable round-trip."
- [id]
- (t2/hydrate (documents.db/document id) :creator :can_write :can_delete :can_restore :is_remote_synced))
-
-(defn get-document
- "Get document by id, checking that it exists and the current user can read it, and recording a view.
- Pass `:log-view? false` to skip publishing the `:event/document-read` view event."
- [id & {:keys [log-view?] :or {log-view? true}}]
- (u/prog1 (api/check-404 (api/read-check (hydrate-document id)))
- (when log-view?
- (events/publish-event! :event/document-read
- {:object-id id
- :user-id api/*current-user-id*}))))
-
-(defn- draft-stored-result-pairings
- "From the incoming document AST and a draft→new card-id map, collect distinct
- `[new-card-id stored-result-id]` pairs for draft embeds that carry a `stored_result_id`.
-
- Only negative keys from `card-id-map` are considered (the draft-created set); clone
- remappings are irrelevant here."
- [document content-type draft-card-id-map]
- (when (and (seq draft-card-id-map) document)
- (->> (prose-mirror/collect-ast
- {:document document :content_type content-type}
- (fn [{:keys [type attrs]}]
- (when (and (= prose-mirror/card-embed-type type)
- (contains? draft-card-id-map (get attrs "id"))
- (get attrs "stored_result_id"))
- [(get draft-card-id-map (get attrs "id"))
- (get attrs "stored_result_id")])))
- distinct
- vec)))
-
(defn add-card-to-document!
"Insert an embed for the already-created card with `card-id` into the prose-mirror ast of the
document with `document-id` and persist it. `position` is a 0-based index among the document's
@@ -228,7 +75,7 @@
(:is_placeholder document) (assoc :is_placeholder false))]
(documents.db/update-document! document-id updates)
(collections/check-for-remote-sync-update document)))
- (get-document document-id :log-view? false))
+ (m.document/get-document document-id :log-view? false))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -252,38 +99,9 @@
"Create a new `Document`."
[_route-params
_query-params
- {:keys [name document collection_id collection_position cards]} :- DocumentCreateOptions]
+ {:keys [collection_id] :as body} :- DocumentCreateOptions]
(api/create-check :model/Document {:collection_id collection_id})
- (let [created-document (t2/with-transaction [_conn]
- (when collection_position
- (api/maybe-reconcile-collection-position! {:collection_id collection_id
- :collection_position collection_position}))
- (let [document-id (documents.db/insert-document! {:name name
- :collection_id collection_id
- :collection_position collection_position
- :document document
- :content_type prose-mirror/prose-mirror-content-type
- :creator_id api/*current-user-id*})
- cards-to-update-in-ast (merge (clone-cards-in-document! {:id document-id
- :collection_id collection_id
- :document document
- :content_type prose-mirror/prose-mirror-content-type})
- (when-not (empty? cards)
- (create-cards-for-document! cards document-id collection_id @api/*current-user*)))]
- (when (seq cards-to-update-in-ast)
- (documents.db/update-document! document-id
- (update-cards-in-ast
- {:document document
- :content_type prose-mirror/prose-mirror-content-type}
- cards-to-update-in-ast)))
- (u/prog1 (get-document document-id)
- (when (collections/remote-synced-collection? (:collection_id <>))
- (collections/check-non-remote-synced-dependencies <>)))))]
- ;; Publish event after successful creation
- (events/publish-event! :event/document-create
- {:object created-document
- :user-id api/*current-user-id*})
- created-document))
+ (m.document/create-document! body))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -292,8 +110,8 @@
(api.macros/defendpoint :get "/:document-id"
"Returns an existing Document by ID."
[{:keys [document-id]} :- [:map {:closed true} [:document-id ms/PositiveInt]]]
- ;; `get-document` already does the 404 + read-check internally;
- (get-document document-id))
+ ;; `m.document/get-document` already does the 404 and read check internally.
+ (m.document/get-document document-id))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -304,60 +122,16 @@
[{:keys [document-id]} :- [:map {:closed true}
[:document-id ms/PositiveInt]]
_query-params
- {:keys [name document collection_id collection_position cards] :as body} :- DocumentUpdateOptions]
- ;; Use a lightweight fetch for the guard: we only need the raw row for the archived/permission/collection-move
- ;; checks below. Calling `get-document` here would hydrate display fields we don't use and record a *view* of
- ;; the document on every save.
+ {:keys [collection_id] :as body} :- DocumentUpdateOptions]
+ ;; Use a lightweight fetch for the guard: we only need the raw row for the archived, permission, and collection-move
+ ;; checks below. Calling `m.document/get-document` here would hydrate unused display fields and record a view.
(let [existing-document (api/check-404 (documents.db/document document-id))]
(when-not (contains? body :archived)
(api/check-not-archived existing-document))
(api/write-check existing-document)
(when (api/column-will-change? :collection_id existing-document body)
(m.document/validate-collection-move-permissions (:collection_id existing-document) collection_id))
- ;; Handle archiving logic
- (let [document-updates (dissoc (api/updates-with-archived-directly existing-document body) :cards)]
- (t2/with-transaction [_conn]
- (when collection_position
- (api/maybe-reconcile-collection-position! existing-document {:collection_id (if (contains? body :collection_id)
- collection_id
- (:collection_id existing-document))
- :collection_position collection_position}))
- (let [card-id-map (when document
- (merge
- (clone-cards-in-document! (assoc existing-document :document document))
- (when-not (empty? cards)
- (create-cards-for-document! cards document-id collection_id @api/*current-user*))))
- draft-card-id-map (into {} (filter (comp neg? key) card-id-map))
- pairings (draft-stored-result-pairings document
- (:content_type existing-document)
- draft-card-id-map)]
- (documents.db/update-document! document-id
- (cond-> document-updates
- document (merge (update-cards-in-ast
- {:document document
- :content_type (:content_type existing-document)}
- card-id-map))
- name (assoc :name name)
- (contains? body :collection_id) (assoc :collection_id collection_id)
- ;; First body save clears the auto-created Summary placeholder flag.
- (and (:is_placeholder existing-document)
- (contains? body :document))
- (assoc :is_placeholder false)))
- (when (seq pairings)
- (card/carry-pairings-for-document! document-id pairings)))
- (collections/check-for-remote-sync-update existing-document))
- ;; `hydrate-document` (not `get-document`): the write already passed `write-check`, and a save is not a view,
- ;; so we neither re-check read perms nor publish a read event for the returned instance.
- (let [updated-document (hydrate-document document-id)]
- ;; Publish appropriate events
- (if (:archived document-updates)
- (events/publish-event! :event/document-delete
- {:object updated-document
- :user-id api/*current-user-id*})
- (events/publish-event! :event/document-update
- {:object updated-document
- :user-id api/*current-user-id*}))
- updated-document))))
+ (m.document/update-document! existing-document body)))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -398,12 +172,12 @@
;; collection the caller cannot read. Read-check each card before copying, mirroring
;; `clone-cards-in-document!`.
(api/read-check card)
- (let [new-card (clone-card! (-> card
- (dissoc :id :entity_id :created_at :updated_at :creator_id
- :public_uuid :made_public_by_id :cache_invalidated_at)
- (assoc :document_id new-document-id
- :collection_id new-collection-id))
- @api/*current-user*)]
+ (let [new-card (m.document/clone-card! (-> card
+ (dissoc :id :entity_id :created_at :updated_at :creator_id
+ :public_uuid :made_public_by_id :cache_invalidated_at)
+ (assoc :document_id new-document-id
+ :collection_id new-collection-id))
+ @api/*current-user*)]
(when (or (:archived card) (:archived_directly card))
(documents.db/update-card! (:id new-card)
{:archived (boolean (:archived card))
@@ -412,15 +186,14 @@
{}
cards-to-copy)))
-(api.macros/defendpoint :post "/:from-document-id/copy" :- [:map [:id ::documents.schema/document.id]]
- "Copy a Document."
- [{:keys [from-document-id]} :- [:map {:closed true}
- [:from-document-id ms/PositiveInt]]
- _query-params
- {:keys [name collection_id collection_position]} :- [:map {:closed true}
- [:name {:optional true} [:maybe ms/NonBlankString]]
- [:collection_id {:optional true} [:maybe ms/PositiveInt]]
- [:collection_position {:optional true} [:maybe ms/PositiveInt]]]]
+(defn copy-document!
+ "Copy the document with `from-document-id` into `:collection_id` (nil = root), along with the
+ questions saved inside it, and return the new document. `copy-opts` may override `:name` and set
+ `:collection_position`.
+
+ Requires read permission on the source and create permission on the destination collection.
+ Publishes `:event/document-create`."
+ [from-document-id {:keys [name collection_id collection_position]}]
(api/create-check :model/Document {:collection_id collection_id})
(let [existing-document (api/check-404
(api/read-check
@@ -438,11 +211,11 @@
card-id-map (copy-cards-for-document! from-document-id new-document-id collection_id)]
(when (seq card-id-map)
(documents.db/update-document! new-document-id
- (update-cards-in-ast
+ (m.document/update-cards-in-ast
{:document (:document existing-document)
:content_type (:content_type existing-document)}
card-id-map)))
- (u/prog1 (get-document new-document-id)
+ (u/prog1 (m.document/get-document new-document-id)
(when (collections/remote-synced-collection? collection_id)
(collections/check-non-remote-synced-dependencies <>)))))]
(events/publish-event! :event/document-create
@@ -450,6 +223,19 @@
:user-id api/*current-user-id*})
new-document))
+(api.macros/defendpoint :post "/:from-document-id/copy" :- [:map [:id ::documents.schema/document.id]]
+ "Copy a Document."
+ [{:keys [from-document-id]} :- [:map {:closed true}
+ [:from-document-id ms/PositiveInt]]
+ _query-params
+ {:keys [name collection_id collection_position]} :- [:map {:closed true}
+ [:name {:optional true} [:maybe ms/NonBlankString]]
+ [:collection_id {:optional true} [:maybe ms/PositiveInt]]
+ [:collection_position {:optional true} [:maybe ms/PositiveInt]]]]
+ (copy-document! from-document-id {:name name
+ :collection_id collection_id
+ :collection_position collection_position}))
+
;;; ----------------------------------------------- Sharing is Caring ------------------------------------------------
(api.macros/defendpoint :post "/:document-id/public-link" :- [:map [:uuid ms/UUIDString]]
diff --git a/src/metabase/documents/core.clj b/src/metabase/documents/core.clj
index 975388dab6f..2ffc8b3bcd7 100644
--- a/src/metabase/documents/core.clj
+++ b/src/metabase/documents/core.clj
@@ -1,6 +1,7 @@
(ns metabase.documents.core
(:require
[metabase.documents.api.document]
+ [metabase.documents.markdown]
[metabase.documents.models.document]
[metabase.documents.prose-mirror]
[metabase.documents.recent-views]
@@ -8,6 +9,7 @@
(comment
metabase.documents.api.document/keep-me
+ metabase.documents.markdown/keep-me
metabase.documents.models.document/keep-me
metabase.documents.prose-mirror/keep-me
metabase.documents.recent-views/keep-me)
@@ -15,9 +17,21 @@
(p/import-vars
[metabase.documents.api.document
add-card-to-document!
- get-document]
+ copy-document!]
+ [metabase.documents.markdown
+ contains-table?
+ escape-text
+ parse
+ serialize
+ splice]
[metabase.documents.models.document
+ clone-cards-in-document!
+ create-document!
+ DocumentName
+ get-document
register-doc-content-visibility-fn!
+ update-document!
+ validate-collection-move-permissions
with-content-gate-cache]
[metabase.documents.prose-mirror
insert-card-embed
diff --git a/src/metabase/documents/markdown.clj b/src/metabase/documents/markdown.clj
new file mode 100644
index 00000000000..85fd3e29bc1
--- /dev/null
+++ b/src/metabase/documents/markdown.clj
@@ -0,0 +1,1459 @@
+(ns metabase.documents.markdown
+ "Convert between Metabase-flavored Markdown and the ProseMirror-JSON AST stored in a
+ Document's `:document` column.
+
+ Metabase-flavored Markdown is CommonMark (as parsed by flexmark — core spec plus bare-URL
+ autolinking; no tables, strikethrough, or task lists, since the document editor's ProseMirror
+ schema has no nodes for them) extended with a token vocabulary:
+
+ Leaf tokens — the text forms the editor's own nodes emit via `renderText`:
+
+ {% card id=118 name=\"Revenue by region\" %} ; block-level cardEmbed (name optional)
+ {% entity id=\"42\" model=\"dashboard\" %} ; inline smartLink (id quoted, per the editor)
+
+ Container tokens — Pandoc-fenced-div-style fences for the layout wrappers, which have no
+ client-side text form. `::: <name> {attr=val ...}` on its own line opens a container, a bare
+ `:::` line closes the innermost open one:
+
+ ::: resize {height=442 minHeight=280}
+ ::: flex {columns=[60,40]}
+ ::: supporting
+ A paragraph of supporting text.
+ :::
+ {% card id=118 name=\"Revenue by region\" %}
+ :::
+ :::
+
+ This grammar is jointly versioned with the Tiptap node specs under
+ `frontend/src/metabase/rich_text_editing/tiptap/extensions/` — a frontend change to
+ `flexContainer`/`resizeNode`/`supportingText` attrs or content models must update this
+ namespace in lockstep; nothing enforces the correspondence automatically.
+
+ `parse` emits the AST in the editor's own normal form: every attribute the schema declares
+ is present, marks are in schema rank order, and childless nodes carry no `:content`. The
+ document editor compares the JSON it reads against the JSON it would write to decide whether
+ a document has unsaved changes, so an AST that merely means the same thing is not enough —
+ it has to be byte-identical to what ProseMirror produces. The one attribute out of reach is
+ the `class` on a link mark, whose default is a CSS-module class name minted by the frontend
+ build: a document containing a Markdown link opens with the editor reporting a change.
+
+ Known lossy edges: strikethrough/underline marks serialize as plain text (no CommonMark
+ form the parser could round-trip); a GFM pipe table degrades to one paragraph, its rows kept
+ on their own lines by hard breaks — the line structure is as much of a grid as a schema with
+ no table node can hold, and the Markdown written back ends each row with the `\\` those hard
+ breaks serialize as; a `[text][ref]` link becomes an ordinary link mark and loses the
+ definition's optional title, while a definition no link consumed stays as the prose line it
+ was written as rather than rendering to nothing (an image reference consumes nothing, an image
+ having no node here either); a smartLink whose `model` this grammar has no token for
+ degrades to its label as prose, and a card embed whose `name` contains a `{%`/`%}` delimiter
+ keeps its embed but loses the name (neither is expressible in a token); an inline
+ `{% entity %}` typed literally into prose is indistinguishable from a real token and
+ round-trips into one — a line-leading `{% card %}` does not, since it is escaped so that
+ serializing prose can never manufacture an embed; a paragraph's leading
+ indentation is not preserved (four or more columns would read back as an indented code
+ block, so it collapses to at most three spaces, which CommonMark itself absorbs);
+ boundary whitespace inside a bold/italic run moves outside the mark; spaces in link
+ hrefs percent-encode to `%20`; and a CR or CRLF inside a text node normalizes to a newline,
+ which re-parses as a space, since the parser ends a line on it either way — inside code block
+ content it normalizes too, staying a newline there, because CommonMark gives a fence no way to
+ carry a bare CR.
+
+ This namespace takes and returns plain data and touches no database. A `{% entity %}` token
+ parses to a smartLink carrying only its `entityId`/`model`, with `label`/`href` left at their
+ defaults; resolving those means reading the referenced row, which is a permission decision, so
+ it belongs to the caller (the MCP document tool, in a later slice). Keeping it there also keeps
+ the `documents` module clear of a dependency on `permissions`, which would drag every documents
+ change into the driver test suite."
+ (:require
+ [clojure.string :as str]
+ [metabase.documents.prose-mirror :as prose-mirror]
+ [metabase.util.log :as log])
+ (:import
+ (com.vladsch.flexmark.ast AutoLink BlockQuote BulletList Code Emphasis FencedCodeBlock
+ HardLineBreak Heading HtmlBlock HtmlCommentBlock HtmlEntity HtmlInline
+ IndentedCodeBlock Link LinkRef MailLink OrderedList Paragraph
+ Reference SoftLineBreak StrongEmphasis Text TextBase ThematicBreak)
+ (com.vladsch.flexmark.ext.autolink AutolinkExtension)
+ (com.vladsch.flexmark.parser Parser)
+ (com.vladsch.flexmark.util.ast Block Document Node)
+ (com.vladsch.flexmark.util.data MutableDataSet)))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------ Vocabulary ----------------------------------------------------
+
+;; The node types that carry a `:_id` attr — paragraph, heading, codeBlock, bulletList,
+;; orderedList, blockquote, supportingText, cardEmbed — are the ones whose Tiptap extension
+;; spreads `createIdAttribute`. Comments anchor to these ids, so they are the units of the
+;; source map; `parse` mints one wherever it builds such a node.
+
+(def ^:private transient-types
+ "UI-session-scoped scratch nodes (in-progress AI generation); dropped from the Markdown
+ projection entirely — no token, no span."
+ #{"metabot" "metabot-mention"})
+
+(def ^:private container-types
+ #{"resizeNode" "flexContainer" "supportingText"})
+
+(def ^:private resize-node-default-height 442)
+(def ^:private resize-node-default-min-height 280)
+
+(def ^:private line-ending-re
+ "The line endings the Markdown parser breaks a line on: CRLF, CR, LF (CommonMark 2.2). Prose
+ reaching the serializer is an arbitrary stored string, so it can hold any of them, and every
+ line the parser will see has to go through [[escape-line-start]] — a CR the serializer treats
+ as ordinary text is a line the parser reads as a fresh one, free to open a block.
+
+ The scanner splits on this too, and must: `clojure.string/split-lines` breaks on `\\r?\\n` and
+ leaves a lone CR inside the line it returns. flexmark would end the line there, so the two
+ disagree about where lines begin — and a `{% card %}` the author fenced as code lands on a
+ scanner line that no longer looks like a fence, promoting it to a real embed."
+ #"\r\n|\r|\n")
+
+(def ^:private max-nesting-depth
+ "How deep a parse tree may get before parsing refuses the input. Conversion recurses once per
+ level — `scan-segments` per container fence, `convert-block`/`convert-inline` per block and
+ inline node — so unbounded input depth is a stack overflow, and an 8KB body is enough to reach
+ one.
+
+ This counts tree levels, not visually nested blocks, and inline nodes are levels too: `> > hi`
+ is four deep (two quotes, a paragraph, a text node), so the allowance in blockquotes or list
+ levels is somewhat lower than the number itself. It is a safety bound, not a contract — no real
+ document comes near it, since the layout content model bottoms out at three
+ (`resize` > `flex` > `supporting`) and prose nested past a handful of levels is already
+ unreadable. The stack gives out somewhere around 2000 and the app DB's own JSON nesting limit
+ refuses to store a body past roughly 600, so this sits well clear of both."
+ 100)
+
+(defn- mint-id
+ []
+ (str (random-uuid)))
+
+(defn- teaching-error
+ [msg]
+ (ex-info msg {:status-code 400}))
+
+;;; ------------------------------------------------ Smart links ---------------------------------------------------
+
+;; The `{% entity %}` vocabulary is the key set of
+;; [[metabase.documents.prose-mirror/smart-link-model->db-model]]. Only membership is read here —
+;; which row a model denotes, and whether the caller may see it, belongs to whoever resolves the
+;; link, so this namespace still never touches the database. Parsing and serializing consult the
+;; same keys, so a model the grammar can't express stays literal text in both directions.
+
+;;; ------------------------------------------------ Token grammar -------------------------------------------------
+
+(def ^:private fence-open-re
+ #"[ \t]{0,3}:::[ \t]*(resize|flex|supporting)[ \t]*(?:\{([^}]*)\})?[ \t]*")
+
+(def ^:private fence-close-re
+ #"[ \t]{0,3}:::[ \t]*")
+
+;; Token regexes are written to match in linear time with no backtracking over alternation
+;; loops — a lazy loop over an alternation recurses per character in the JVM regex engine,
+;; and a StackOverflowError from a long unclosed token would bypass every Exception handler.
+;; The card regex is greedy to the line's last `%}`; bodies containing another token
+;; delimiter are rejected after the match instead of via backtracking.
+
+(def ^:private card-token-line-re
+ #"[ \t]{0,3}\{%\s*card\s+(.*)%\}[ \t]*")
+
+(def ^:private entity-token-re
+ #"\{%\s*entity\s+([^%{}]{0,500})%\}")
+
+(def ^:private attr-pair-re
+ #"([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(\"[^\"\\]*(?:\\.[^\"\\]*)*\"|\[[^\]]*\]|[^\s\"\[]+)")
+
+(def ^:private max-token-attrs-length 2000)
+
+(defn- parse-scalar
+ [^String s]
+ (cond
+ (re-matches #"-?\d{1,18}" s) (Long/parseLong s)
+ (re-matches #"-?\d{1,18}\.\d+" s) (Double/parseDouble s)
+ :else s))
+
+(defn- parse-attr-value
+ [^String v]
+ (cond
+ (and (str/starts-with? v "\"") (str/ends-with? v "\"") (>= (count v) 2))
+ (-> (subs v 1 (dec (count v)))
+ (str/replace #"\\([\"\\])" "$1"))
+
+ (and (str/starts-with? v "[") (str/ends-with? v "]"))
+ (let [inner (str/trim (subs v 1 (dec (count v))))]
+ (if (str/blank? inner)
+ []
+ (mapv (comp parse-scalar str/trim) (str/split inner #","))))
+
+ :else
+ (parse-scalar v)))
+
+(defn- parse-token-attrs
+ [attrs-str]
+ (let [attrs-str (or attrs-str "")]
+ (when (> (count attrs-str) max-token-attrs-length)
+ (throw (teaching-error (format "Token attributes exceed %d characters — shorten the token."
+ max-token-attrs-length))))
+ (into {}
+ (for [[_ k v] (re-seq attr-pair-re attrs-str)]
+ [(keyword k) (parse-attr-value v)]))))
+
+;;; ------------------------------------------------ Parse: block scan ---------------------------------------------
+
+;; Segments are the line-level pre-parse: container fences and block card tokens are ours,
+;; everything between them accumulates into chunks handed to flexmark.
+;; {:kind :markdown :text "..."}
+;; {:kind :card :attrs {...}}
+;; {:kind :container :name "flex" :attrs {...} :children [segment ...]}
+
+(defn- flush-markdown
+ [segments md-lines]
+ (let [text (str/join "\n" md-lines)]
+ (cond-> segments
+ (not (str/blank? text)) (conj {:kind :markdown :text text}))))
+
+(defn- card-attrs
+ [attrs-str]
+ (let [{:keys [id name] :as attrs} (parse-token-attrs attrs-str)]
+ (when-not (pos-int? id)
+ (throw (teaching-error (format "Invalid card token {%% card %s %%} — expected {%% card id=<int> %%} or {%% card id=<int> name=\"…\" %%}."
+ attrs-str))))
+ (when-let [unknown (seq (remove #{:id :name} (keys attrs)))]
+ (throw (teaching-error (format "Unknown card token attribute(s) %s — a card token takes id and an optional name."
+ (str/join ", " (map clojure.core/name unknown))))))
+ {:id id :name (when (string? name) name)}))
+
+(defn- card-token-line-body
+ "The attr text of a line that is exactly one `{% card … %}` token, else nil. The greedy
+ regex captures to the line's last `%}`, so a body containing another token delimiter means
+ the line isn't a single card token."
+ ^String [^String line]
+ (when-let [[_ body] (re-matches card-token-line-re line)]
+ (let [body (str/trim body)]
+ (when-not (or (str/includes? body "{%") (str/includes? body "%}"))
+ body))))
+
+(def ^:private code-fence-re
+ ;; A fence may open on a list item's marker line (`- ```clj`). Without the marker branch the
+ ;; scanner never enters the code state for such a block, and the item's content lines -- which
+ ;; sit at 2-3 columns, inside this regex's indent budget -- get read as structure, manufacturing
+ ;; a card embed or closing a container early out of what CommonMark calls code.
+ #"[ \t]{0,3}(?:(?:[-+*]|\d{1,9}[.)])[ \t]{1,4})?(`{3,}|~{3,})(.*)")
+
+(defn- code-fence-open
+ "The fence descriptor `{:ch :len}` a line opens, or nil. A backtick fence's info string
+ cannot contain a backtick (CommonMark 4.5)."
+ [^String line]
+ (when-let [[_ fence info] (re-matches code-fence-re line)]
+ (when-not (and (str/starts-with? fence "`") (str/includes? info "`"))
+ {:ch (first fence) :len (count fence)})))
+
+(def ^:private code-fence-close-re
+ ;; A fence opened behind a list marker closes at the item's content indent, which sits past the
+ ;; 3 columns a top-level fence is limited to. Allowing more leading space here only ever ends a
+ ;; block the opener already began, so it cannot make non-code text look like structure.
+ #"[ \t]{0,13}(`{3,}|~{3,})[ \t]*")
+
+(defn- code-fence-close?
+ [^String line {:keys [ch len]}]
+ (boolean
+ (when-let [[_ fence] (re-matches code-fence-close-re line)]
+ (and (= ch (first fence)) (>= (count fence) (long len))))))
+
+(defn- indented-code-line?
+ "Whether CommonMark reads `line` as indented code, i.e. its content starts at column 4 or later.
+
+ The token and fence regexes bound their indent with `[ \\t]{0,3}`, which counts a tab as one
+ character. A tab advances to the next 4-column tab stop (CommonMark 2.2), so `\\t{% card id=1 %}`
+ is a one-character indent to those regexes and a code block to flexmark — the scanner promotes to
+ structure exactly what the parser reads as content. Measuring in columns is what makes the two
+ agree, and doing it here covers every token type at once."
+ [^String line]
+ (loop [idx (long 0) col (long 0)]
+ (if (>= idx (.length line))
+ ;; Ran out of line while still counting indent: the line is blank. A blank line separates
+ ;; blocks rather than opening a code block, however wide its whitespace is — so the column
+ ;; test belongs on the first non-whitespace character, not on entry to each iteration.
+ false
+ (let [c (.charAt line idx)]
+ (cond
+ (= c \space) (recur (inc idx) (inc col))
+ (= c \tab) (recur (inc idx) (long (+ col (- 4 (mod col 4)))))
+ :else (>= col 4))))))
+
+(defn- scan-segments
+ "Scan `lines` from index `i` into segments. `open-fence` names the container fence being
+ filled, or nil at the top level, and `depth` how many fences are open above this one — bounded,
+ because each open fence costs a stack frame and the content-model check that would reject absurd
+ nesting does not run until the whole scan has already returned. Lines inside a fenced code block
+ are opaque: token syntax there is content, not structure. Returns [segments next-index]."
+ [lines i open-fence depth]
+ (when (> (long depth) max-nesting-depth)
+ (throw (teaching-error (format "Layout containers are nested more than %d deep — flatten the layout."
+ max-nesting-depth))))
+ (loop [i i
+ md-lines []
+ segments []
+ code-fence nil]
+ (if (>= i (count lines))
+ (if open-fence
+ (throw (teaching-error (format "Unclosed ::: %s container — add a closing ::: line." open-fence)))
+ [(flush-markdown segments md-lines) i])
+ (let [^String line (nth lines i)]
+ (cond
+ code-fence
+ (recur (inc i) (conj md-lines line) segments
+ (when-not (code-fence-close? line code-fence) code-fence))
+
+ ;; Indented code is content, not structure — flexmark will read this line as a code
+ ;; block, so no token or fence on it may be promoted. Sits below the `code-fence` arm
+ ;; because a line inside an already-open fence is opaque whatever its indent.
+ (indented-code-line? line)
+ (recur (inc i) (conj md-lines line) segments nil)
+
+ (code-fence-open line)
+ (recur (inc i) (conj md-lines line) segments (code-fence-open line))
+
+ (re-matches fence-open-re line)
+ (let [[_ fence-name attrs-str] (re-matches fence-open-re line)
+ [children next-i] (scan-segments lines (inc i) fence-name (inc (long depth)))]
+ (recur next-i
+ []
+ (conj (flush-markdown segments md-lines)
+ {:kind :container :name fence-name :attrs (parse-token-attrs attrs-str)
+ :children children})
+ nil))
+
+ (re-matches fence-close-re line)
+ (if open-fence
+ [(flush-markdown segments md-lines) (inc i)]
+ ;; A stray ::: outside any container is plain text.
+ (recur (inc i) (conj md-lines line) segments nil))
+
+ (card-token-line-body line)
+ (recur (inc i)
+ []
+ (conj (flush-markdown segments md-lines)
+ {:kind :card :attrs (card-attrs (card-token-line-body line))})
+ nil)
+
+ :else
+ (recur (inc i) (conj md-lines line) segments nil))))))
+
+;;; ------------------------------------------------ Parse: flexmark -> AST ----------------------------------------
+
+(def ^:private ^Parser flexmark-parser
+ (let [options (.. (MutableDataSet.)
+ (set Parser/EXTENSIONS [(AutolinkExtension/create)]))]
+ (.build (Parser/builder options))))
+
+(defn- fm-children
+ [^Node node]
+ (seq (iterator-seq (.iterator (.getChildren node)))))
+
+(defn- unescape-md
+ ^String [^String s]
+ (str/replace s #"\\(\p{Punct})" "$1"))
+
+(def ^:private mark-rank
+ "ProseMirror sorts a text node's marks by their schema rank when it loads a document
+ (`Mark.setFrom`), so marks emitted in any other order describe a different AST than the one
+ the editor hands back on the next save. The ranks are the document editor's schema
+ registration order — link outranks the rest because the Link extension declares a higher
+ extension priority."
+ (zipmap ["link" "bold" "code" "italic" "strike" "underline"] (range)))
+
+(defn- text-node
+ [s marks]
+ (cond-> {:type "text" :text s}
+ (seq marks) (assoc :marks (vec (sort-by #(mark-rank (:type %) (count mark-rank)) marks)))))
+
+(defn- mark
+ ([type] {:type type})
+ ([type attrs] {:type type :attrs attrs}))
+
+(def ^:private link-mark-defaults
+ "The `target`/`rel` defaults the editor's Link extension applies to every link mark. Its
+ `class` attribute is a build-time CSS-module name and is deliberately left off — it can only
+ be filled in by the client."
+ {"target" "_blank" "rel" "noopener noreferrer nofollow"})
+
+(defn- link-mark
+ [href]
+ (mark "link" (assoc link-mark-defaults "href" href)))
+
+(defn- with-content
+ "Attach `content` to `node`, omitting the key when there is nothing to attach — ProseMirror's
+ own `toJSON` drops `content` on a childless node."
+ [node content]
+ (cond-> node
+ (seq content) (assoc :content (vec content))))
+
+(def ^:private table-delimiter-row-re
+ "A line made of nothing but pipes, dashes, colons and spaces. Recognizing a GFM delimiter row by
+ its alphabet rather than by cell structure keeps the match linear and has no false negatives —
+ every real delimiter row is drawn from exactly these characters."
+ #"[ \t]*[-:|][-:| \t]*")
+
+(defn- table-delimiter-row?
+ "True when `line` is the `|---|:--:|` row that makes the line above it a table header. Both a pipe
+ and a dash are required, so a setext underline or a thematic break is never one."
+ [^String line]
+ (and (str/includes? line "|")
+ (str/includes? line "-")
+ (boolean (re-matches table-delimiter-row-re line))))
+
+(defn- inline-lines
+ "The source text of each line of a paragraph's inline children, split at soft line breaks. Built
+ from the leaf nodes rather than the paragraph's own chars because a block's chars carry the line
+ prefixes of any enclosing blockquote or list item, and an inline node never spans one."
+ [nodes]
+ ;; Chunks are collected per line and joined once at the end: appending to the accumulated line
+ ;; string directly is quadratic in the node count, and a paragraph is one line unless a soft
+ ;; break says otherwise — a megabyte of `*a* *a* …` prose would pin a core for minutes.
+ (->> nodes
+ (reduce (fn [lines ^Node node]
+ (if (instance? SoftLineBreak node)
+ (conj lines [])
+ (update lines (dec (count lines)) conj (str (.getChars node)))))
+ [[]])
+ (mapv str/join)))
+
+(defn- table-paragraph?
+ "True when a paragraph holds a GFM pipe table: a row containing a pipe, followed by a delimiter
+ row. The editor's schema has no table node, so a table is prose whatever happens here — but a
+ paragraph joins its lines with a space, which runs the entire grid onto one line, and the line
+ structure is the only part of a table this schema can still carry."
+ [nodes]
+ (->> (inline-lines nodes)
+ (partition 2 1)
+ (some (fn [[header delimiter]]
+ (and (str/includes? header "|") (table-delimiter-row? delimiter))))
+ boolean))
+
+(defn contains-table?
+ "Returns true when `markdown-string` contains a GFM pipe table outside a code block."
+ [markdown-string]
+ (letfn [(node-table? [node]
+ (and (instance? Paragraph node)
+ (table-paragraph? (fm-children node))))
+ (segment-table? [{:keys [kind text children]}]
+ (case kind
+ :markdown (let [root (.parse flexmark-parser ^String text)]
+ (boolean (some node-table? (tree-seq #(seq (fm-children %)) fm-children root))))
+ :container (boolean (some segment-table? children))
+ false))]
+ (let [[segments _] (scan-segments (str/split-lines (or markdown-string "")) 0 nil 0)]
+ (boolean (some segment-table? segments)))))
+
+(defn- reference-link-url
+ "The URL a `[text][ref]` link resolves to, or nil when nothing in the document defines `ref`. The
+ definition is a block of its own that carries no ProseMirror node, so this lookup is the only way
+ the URL reaches the AST."
+ [^LinkRef node]
+ (when (.isDefined node)
+ (when-let [^Reference ref (.getReferenceNode node ^Document (.getDocument node))]
+ (unescape-md (str (.getUrl ref))))))
+
+(defn- convert-inline
+ "Convert one flexmark inline node to a seq of ProseMirror inline nodes, with `marks`
+ accumulated from enclosing emphasis/link nodes. `hard-breaks?` renders a soft line break as a
+ `hardBreak` instead of the space CommonMark gives it — the table case, where the line structure
+ is the content."
+ [node marks hard-breaks?]
+ (letfn [(children-with [extra-mark]
+ (mapcat #(convert-inline % (conj marks extra-mark) hard-breaks?) (fm-children node)))]
+ (condp instance? node
+ Text [(text-node (unescape-md (str (.getChars ^Node node))) marks)]
+ StrongEmphasis (children-with (mark "bold"))
+ Emphasis (children-with (mark "italic"))
+ ;; CommonMark strips one space of padding from a code span that has it on both sides
+ ;; (the escape hatch for content with edge backticks); flexmark's getText keeps it.
+ Code [(text-node (let [s (str (.getText ^Code node))]
+ (if (and (str/starts-with? s " ") (str/ends-with? s " ")
+ (not (str/blank? s)) (> (count s) 1))
+ (subs s 1 (dec (count s)))
+ s))
+ (conj marks (mark "code")))]
+ ;; flexmark keeps backslash escapes in the destination it reports.
+ Link (mapcat #(convert-inline % (conj marks (link-mark (unescape-md (str (.getUrl ^Link node))))) hard-breaks?)
+ (fm-children node))
+ ;; A reference link is the same link mark as an inline one, resolved through the definition
+ ;; block. An undefined reference is not a link at all — CommonMark leaves it as literal text.
+ LinkRef (if-let [url (reference-link-url node)]
+ (mapcat #(convert-inline % (conj marks (link-mark url)) hard-breaks?) (fm-children node))
+ [(text-node (str (.getChars ^Node node)) marks)])
+ AutoLink [(text-node (str (.getText ^AutoLink node))
+ (conj marks (link-mark (str (.getUrl ^AutoLink node)))))]
+ MailLink [(text-node (str (.getText ^MailLink node))
+ (conj marks (link-mark (str "mailto:" (.getText ^MailLink node)))))]
+ SoftLineBreak (if hard-breaks? [{:type "hardBreak"}] [(text-node " " marks)])
+ HardLineBreak [{:type "hardBreak"}]
+ HtmlEntity [(text-node (str (.getChars ^Node node)) marks)]
+ HtmlInline [(text-node (str (.getChars ^Node node)) marks)]
+ ;; AutolinkExtension wraps a text run containing a bare URL in a TextBase around
+ ;; [Text AutoLink Text] children.
+ TextBase (into [] (mapcat #(convert-inline % marks hard-breaks?)) (fm-children node))
+ ;; Anything without a ProseMirror counterpart (images, …) keeps its source text.
+ [(text-node (str (.getChars ^Node node)) marks)])))
+
+(defn- merge-adjacent-text
+ [inlines]
+ (reduce (fn [acc {:keys [type text marks] :as node}]
+ (let [prev (peek acc)]
+ (if (and prev
+ (= type "text") (= (:type prev) "text")
+ (= marks (:marks prev)))
+ (conj (pop acc) (assoc prev :text (str (:text prev) text)))
+ (conj acc node))))
+ []
+ inlines))
+
+(defn- entity-token->smart-link
+ "Parse the attrs of one `{% entity %}` token match. Returns a smartLink node, or nil when
+ the token is malformed / references an unknown model (left as literal text)."
+ [attrs-str]
+ (let [{:keys [id model]} (parse-token-attrs attrs-str)
+ id (if (string? id) (parse-scalar id) id)]
+ (when (and (pos-int? id) (contains? prose-mirror/smart-link-model->db-model model))
+ {:type "smartLink"
+ :attrs {"entityId" id "model" model "label" nil "href" "/"}})))
+
+(defn- split-entity-tokens
+ [{:keys [text marks] :as node}]
+ (let [m (re-matcher entity-token-re text)]
+ (loop [out [] last-end 0]
+ (if (.find m)
+ (if-let [link (entity-token->smart-link (.group m 1))]
+ (recur (cond-> out
+ (< last-end (.start m)) (conj (text-node (subs text last-end (.start m)) marks))
+ true (conj link))
+ (.end m))
+ (recur out last-end))
+ (if (zero? last-end)
+ [node]
+ (cond-> out
+ (< last-end (count text)) (conj (text-node (subs text last-end) marks))))))))
+
+(defn- expand-entity-tokens
+ [inlines]
+ (into []
+ (mapcat (fn [{:keys [type text marks] :as node}]
+ (if (and (= type "text")
+ (str/includes? (or text "") "{%")
+ (not-any? #(= "code" (:type %)) marks))
+ (split-entity-tokens node)
+ [node])))
+ inlines))
+
+(defn- convert-inlines
+ [nodes hard-breaks?]
+ (-> (into [] (mapcat #(convert-inline % [] hard-breaks?)) nodes)
+ merge-adjacent-text
+ expand-entity-tokens
+ (->> (remove #(and (= "text" (:type %)) (= "" (:text %))))
+ (into []))))
+
+(declare convert-blocks)
+
+(defn- container-block
+ "`node` with `content` attached, as the one-element seq a `convert-block` branch returns — or an
+ empty one when the conversion produced no children. A container with no children is a document
+ the editor's content model rejects and cannot load, so a container whose children all convert to
+ nothing (an HTML comment block, a bullet with nothing after it) is dropped rather than emitted
+ empty. Nothing visible goes with it: what it held was already nothing to show."
+ [node content]
+ (when (seq content)
+ [(assoc node :content (vec content))]))
+
+(defn- convert-list-item
+ [item]
+ (container-block {:type "listItem"} (convert-blocks (fm-children item))))
+
+(defn- code-block-text
+ ^String [^Block node]
+ (str/replace (str (.getContentChars node)) #"\n\z" ""))
+
+(defn- code-block-node
+ [node language]
+ (with-content {:type "codeBlock"
+ :attrs {"language" language "_id" (mint-id)}}
+ (let [text (code-block-text node)]
+ (when-not (= text "") [{:type "text" :text text}]))))
+
+(defn- convert-block
+ [node]
+ (condp instance? node
+ Paragraph (let [children (fm-children node)]
+ [(with-content {:type "paragraph"
+ :attrs {"_id" (mint-id)}}
+ (convert-inlines children (table-paragraph? children)))])
+ ;; A heading is one line however it was written, so its lines join with a space even when a
+ ;; setext underline let it hold more than one.
+ Heading [(with-content {:type "heading"
+ :attrs {"level" (.getLevel ^Heading node) "_id" (mint-id)}}
+ (convert-inlines (fm-children node) false))]
+ BulletList (container-block {:type "bulletList"
+ :attrs {"_id" (mint-id)}}
+ (mapcat convert-list-item (fm-children node)))
+ OrderedList (container-block {:type "orderedList"
+ :attrs {"start" (.getStartNumber ^OrderedList node) "type" nil "_id" (mint-id)}}
+ (mapcat convert-list-item (fm-children node)))
+ BlockQuote (container-block {:type "blockquote"
+ :attrs {"_id" (mint-id)}}
+ (convert-blocks (fm-children node)))
+ FencedCodeBlock [(code-block-node node (not-empty (first (str/split (str (.getInfo ^FencedCodeBlock node)) #"\s+"))))]
+ IndentedCodeBlock [(code-block-node node nil)]
+ ThematicBreak [{:type "horizontalRule"}]
+ HtmlBlock [{:type "paragraph"
+ :attrs {"_id" (mint-id)}
+ :content [{:type "text" :text (str/trimr (str (.getChars ^Node node)))}]}]
+ ;; A comment renders nowhere, so it carries no node — a container left with only comments in it
+ ;; is dropped by [[container-block]] rather than emitted with nothing inside.
+ HtmlCommentBlock []
+ ;; A definition still in the tree is one [[unlink-consumed-references!]] found no link for, so
+ ;; its URL reaches the document only as the prose it was written as.
+ Reference [{:type "paragraph"
+ :attrs {"_id" (mint-id)}
+ :content [{:type "text" :text (str/trimr (str (.getChars ^Node node)))}]}]
+ ;; Anything unrecognized flattens to its converted children.
+ (convert-blocks (fm-children node))))
+
+(defn- convert-blocks
+ [nodes]
+ (into [] (mapcat convert-block) nodes))
+
+(defn- check-nesting-depth!
+ "Refuse a flexmark tree nested past [[max-nesting-depth]] before converting it. flexmark itself
+ builds deep trees happily — 8000 nested blockquotes parse fine — and it is
+ `convert-block`/`convert-inline`, one frame per level, that then runs out of stack. Checking the
+ tree instead of threading a depth argument through four mutually recursive converters keeps the
+ bound in one place.
+
+ The walk holds its own stack: measuring depth recursively would overflow on exactly the trees
+ this exists to reject."
+ [root]
+ (loop [stack [[root 0]]]
+ (when (seq stack)
+ (let [[^Node node depth] (peek stack)]
+ (when (> (long depth) max-nesting-depth)
+ (throw (teaching-error (format "Markdown is nested more than %d levels deep — flatten it."
+ max-nesting-depth))))
+ (recur (into (pop stack)
+ (map #(vector % (inc (long depth))))
+ (fm-children node)))))))
+
+(defn- unlink-consumed-references!
+ "Drop from `root` every top-level link reference definition that a `[text][ref]` link resolved
+ through: the URL is on the link mark now, and leaving the definition would put it in the document
+ a second time as prose. What stays is the definitions nothing consumed, whose URL exists nowhere
+ else. Mutating the tree keeps the used/unused split out of every converter's arguments; the tree
+ belongs to this call and is discarded right after.
+
+ Only definitions parented by the document go — a consumed one leaves at least the block holding
+ its link behind, whereas a definition inside a blockquote or a list item can be that container's
+ only child, and unlinking it there would take the whole container out of the document."
+ [^Node root]
+ (doseq [node (vec (iterator-seq (.iterator (.getDescendants root))))
+ :when (instance? LinkRef node)]
+ (when-let [^Node ref (.getReferenceNode ^LinkRef node ^Document (.getDocument ^Node node))]
+ (when (instance? Document (.getParent ref))
+ (.unlink ref)))))
+
+(defn- markdown-chunk->nodes
+ [text]
+ (let [root (.parse flexmark-parser ^String text)]
+ (check-nesting-depth! root)
+ (unlink-consumed-references! root)
+ (-> root fm-children convert-blocks)))
+
+;;; ------------------------------------------------ Parse: containers ---------------------------------------------
+
+(defn- content-model-error
+ [container-type]
+ (teaching-error
+ (case container-type
+ "resizeNode" "A ::: resize container must wrap exactly one ::: flex container or {% card %} embed."
+ "flexContainer" "A ::: flex container must hold 1-3 columns, each a ::: supporting block or a {% card %} embed."
+ "supportingText" "A ::: supporting block can only hold prose blocks (paragraphs, headings, lists, blockquotes, code blocks).")))
+
+(defn- validate-container-content!
+ [container-type children]
+ (let [types (map :type children)
+ ok? (case container-type
+ "resizeNode" (and (= 1 (count children))
+ (contains? #{"flexContainer" "cardEmbed"} (first types)))
+ "flexContainer" (and (<= 1 (count children) 3)
+ (every? #{"supportingText" "cardEmbed"} types))
+ "supportingText" (and (seq children)
+ (every? #{"paragraph" "heading" "bulletList" "orderedList" "blockquote" "codeBlock"}
+ types)))]
+ (when-not ok?
+ (throw (content-model-error container-type)))))
+
+(defn- check-known-attrs!
+ [fence-name attrs allowed]
+ (when-let [unknown (seq (remove allowed (keys attrs)))]
+ (throw (teaching-error (format "Unknown ::: %s attribute(s) %s — allowed: %s."
+ fence-name
+ (str/join ", " (map name unknown))
+ (str/join ", " (map name (sort allowed))))))))
+
+(declare segment->nodes)
+
+(defn- container-node
+ [{:keys [name attrs children]}]
+ (let [child-nodes (into [] (mapcat segment->nodes) children)]
+ (case name
+ "supporting"
+ (do (check-known-attrs! name attrs #{})
+ (validate-container-content! "supportingText" child-nodes)
+ {:type "supportingText" :attrs {"_id" (mint-id)} :content child-nodes})
+
+ "flex"
+ (do (check-known-attrs! name attrs #{:columns})
+ (validate-container-content! "flexContainer" child-nodes)
+ (let [columns (:columns attrs)]
+ (when (and (some? columns) (not (and (vector? columns) (every? number? columns))))
+ (throw (teaching-error "::: flex columns must be a numeric array, e.g. {columns=[60,40]}.")))
+ {:type "flexContainer"
+ :attrs {"columnWidths" columns}
+ :content child-nodes}))
+
+ "resize"
+ (do (check-known-attrs! name attrs #{:height :minHeight})
+ (validate-container-content! "resizeNode" child-nodes)
+ (doseq [k [:height :minHeight]]
+ (when-let [v (get attrs k)]
+ (when-not (number? v)
+ (throw (teaching-error (format "::: resize %s must be a number." (clojure.core/name k)))))))
+ {:type "resizeNode"
+ :attrs {"height" (get attrs :height resize-node-default-height)
+ "minHeight" (get attrs :minHeight resize-node-default-min-height)}
+ :content child-nodes}))))
+
+(defn- segment->nodes
+ [{:keys [kind] :as segment}]
+ (case kind
+ :markdown (markdown-chunk->nodes (:text segment))
+ :card [{:type "cardEmbed"
+ :attrs {"id" (get-in segment [:attrs :id])
+ "name" (get-in segment [:attrs :name])
+ "_id" (mint-id)}}]
+ :container [(container-node segment)]))
+
+(defn- parse-content
+ [markdown-string]
+ ;; Splits on [[line-ending-re]], not `str/split-lines`, so the scanner and flexmark agree on
+ ;; where every line begins — see that var for what a lone CR otherwise does to token opacity.
+ (let [lines (str/split (or markdown-string "") line-ending-re -1)
+ [segments _] (scan-segments lines 0 nil 0)]
+ (into [] (mapcat segment->nodes) segments)))
+
+(defn- wrap-loose-embeds
+ "Give every top-level `cardEmbed`/`flexContainer` its `resizeNode` wrapper. A chart's height
+ lives on that wrapper and nowhere else — everything inside it is `height: 100%` — so an embed
+ sitting directly in the document body renders collapsed to nothing. The editor's own
+ insertion paths (`wrapCardEmbed` in
+ `frontend/src/metabase/rich_text_editing/tiptap/extensions/shared/layout.ts`, and every drop
+ handler) hold the same invariant, which is why an explicit `::: resize` fence is optional in
+ the Markdown. Applies at document level only: inside a `::: resize` or `::: flex` the wrapper
+ is either already there or forbidden by the container's content model."
+ [content]
+ (mapv (fn [{:keys [type] :as node}]
+ (if (#{"cardEmbed" "flexContainer"} type)
+ {:type "resizeNode"
+ :attrs {"height" resize-node-default-height
+ "minHeight" resize-node-default-min-height}
+ :content [node]}
+ node))
+ content))
+
+(defn- ensure-trailing-paragraph
+ "A document's last block is always a paragraph. The editor's `trailingNode` plugin appends an
+ empty one the moment a document whose last block is anything else is loaded (see
+ `@tiptap/extensions`, configured through `CustomStarterKit`), so a document stored without one
+ is rewritten on open and shows up as unsaved changes nobody made. Also floors an empty
+ document to a single paragraph, which `doc`'s `block+` content model requires."
+ [content]
+ (cond-> content
+ (not= "paragraph" (:type (peek content)))
+ (conj {:type "paragraph" :attrs {"_id" (mint-id)}})))
+
+(defn parse
+ "Metabase-flavored Markdown string -> ProseMirror AST map, i.e. the value that goes in a
+ Document's `:document` column: `{:type \"doc\" :content [...]}`. Mints a fresh `:_id` on
+ every node type that carries one, wraps a bare top-level card embed or flex container in
+ the `resizeNode` that gives it a height, and closes the body with a paragraph. Malformed
+ structure (unclosed fences, invalid container content, bad card tokens, nesting past
+ [[max-nesting-depth]]) throws a 400 `ex-info` whose message names the fix. A `{% entity %}`
+ token parses to a smartLink with `label`/`href` left at their defaults — resolving them is the
+ caller's job (see the namespace docstring)."
+ [markdown-string]
+ (try
+ {:type "doc"
+ :content (-> (parse-content markdown-string) wrap-loose-embeds ensure-trailing-paragraph)}
+ ;; [[check-nesting-depth!]] catches deep structure that flexmark hands back, but flexmark can
+ ;; also run out of stack inside its own inline parser (a long `***…` delimiter run does it)
+ ;; before there is a tree to measure. Left alone that escapes as an Error, slipping past the
+ ;; `catch Exception` that sanitizes tool failures and surfacing as an unhandled 500. Safe to
+ ;; convert here because parsing is pure — nothing is half-written when the stack unwinds.
+ (catch StackOverflowError _
+ (throw (teaching-error "Markdown is nested too deeply to parse — flatten it.")))))
+
+;;; ------------------------------------------------ Serialize: inline ---------------------------------------------
+
+(defn- escape-inline
+ ^String [^String s]
+ (str/replace s #"([\\*_`\[\]])" "\\\\$1"))
+
+(defn- escape-line-start
+ "Escape a leading character that would otherwise start a block construct — a CommonMark one
+ (heading, list, blockquote, fence, thematic break, HTML block), a `:::` container fence, or a
+ `{% card %}` block token — when this paragraph line is re-parsed. Prose is the one place an arbitrary
+ stored string reaches the output verbatim, so this is what keeps a text node that merely
+ *looks* like markup from becoming markup on the next parse. Leading indentation of four or
+ more columns (or any tab) would read as an indented code block, so it collapses to three
+ spaces.
+
+ Both patterns are DOTALL: a line can still hold a separator the parser reads as ordinary text
+ (NEL, LINE SEPARATOR, PARAGRAPH SEPARATOR — routine in prose pasted from a PDF or a word
+ processor), and a bare `.` excludes exactly those, which would drop everything past one."
+ ^String [^String line]
+ (let [[_ ws body] (re-matches #"(?s)([ \t]*)(.*)" line)
+ ws (if (or (str/includes? ws "\t") (>= (count ws) 4)) " " ws)]
+ (cond
+ ;; `card-token-line-body` is the same predicate the scanner uses, so a line is escaped
+ ;; exactly when it would otherwise be read as a card embed — never more, never less.
+ (or (re-find #"^(#{1,6}([ \t]|$)|>|<|[-+]([ \t]|$)|:::|~~~|=+[ \t]*$|-+[ \t]*$)" body)
+ (card-token-line-body body))
+ (str ws "\\" body)
+
+ (re-find #"^\d{1,9}[.)]([ \t]|$)" body)
+ (let [[_ digits delim tail] (re-matches #"(?s)(\d{1,9})([.)])(.*)" body)]
+ (str ws digits "\\" delim tail))
+
+ :else (str ws body))))
+
+(defn- escape-block-starts
+ "Escape every line of `s` against being re-read as a block construct, normalizing the parser's
+ line endings to `\\n` on the way out."
+ ^String [^String s]
+ (str/join "\n" (map escape-line-start (str/split s line-ending-re -1))))
+
+(defn escape-text
+ "Escape `s` so that, spliced into Markdown source and re-parsed, it round-trips back to the same
+ literal text wherever it lands — inline or at the start of a line. [[splice]] treats its
+ replacement as Markdown *source* (that is how it inserts a heading or a card embed), so a caller
+ that means literal text — `document_write`'s `edits` — must escape it first, or a replacement
+ like `*` reopens the block as a list. Escapes inline emphasis/link/code characters on every line,
+ then any leading character that would open a block construct; over-escaping a character that was
+ not actually in a special position is inert (CommonMark renders `\\#` as `#`)."
+ ^String [^String s]
+ (str/join "\n" (map (comp escape-line-start escape-inline) (str/split s line-ending-re -1))))
+
+(defn- code-span
+ "Wrap `s` in a backtick run longer than any run it contains, space-padded when the content
+ has edge backticks or symmetric edge spaces (CommonMark strips one pad space from each
+ side on parse)."
+ ^String [^String s]
+ (let [longest (transduce (map count) max 0 (re-seq #"`+" s))
+ delim (apply str (repeat (inc longest) "`"))
+ pad (when (or (str/starts-with? s "`") (str/ends-with? s "`")
+ (and (str/starts-with? s " ") (str/ends-with? s " ") (not (str/blank? s))))
+ " ")]
+ (str delim pad s pad delim)))
+
+(defn- split-boundary-whitespace
+ "[leading-ws core trailing-ws] of `s` — emphasis delimiters must hug non-whitespace."
+ [^String s]
+ (let [len (count s)
+ start (loop [i 0]
+ (if (and (< i len) (Character/isWhitespace (.charAt s i)))
+ (recur (inc i))
+ i))
+ end (loop [i len]
+ (if (and (> i start) (Character/isWhitespace (.charAt s (dec i))))
+ (recur (dec i))
+ i))]
+ [(subs s 0 start) (subs s start end) (subs s end)]))
+
+(defn- link-destination
+ "A bare CommonMark link destination for `href`: parens and backslashes are
+ backslash-escaped (undone by the parser's unescape), whitespace is percent-encoded —
+ flexmark accepts neither raw nor angle-bracketed spaces in a destination."
+ ^String [href]
+ (-> (str href)
+ (str/replace "\\" "\\\\")
+ (str/replace "(" "\\(")
+ (str/replace ")" "\\)")
+ (str/replace "<" "\\<")
+ (str/replace ">" "\\>")
+ (str/replace " " "%20")
+ (str/replace "\t" "%09")
+ (str/replace "\r" "%0D")
+ (str/replace "\n" "%0A")))
+
+(defn- has-mark?
+ [marks type]
+ (boolean (some #(= type (:type %)) marks)))
+
+(defn- mark-attrs
+ [marks type]
+ (some #(when (= type (:type %)) (:attrs %)) marks))
+
+(defn- attr-num
+ "Coerce a node attribute that must serialize as a number. REST accepts `[:document :any]`,
+ so stored attrs can be strings; numeric-looking strings coerce, anything else is a
+ teaching error rather than a ClassCastException."
+ [node-type attr v]
+ (let [v (if (and (string? v) (re-matches #"-?\d{1,18}(\.\d+)?" v))
+ (parse-scalar v)
+ v)]
+ (if (number? v)
+ v
+ (throw (teaching-error (format "Cannot serialize %s node: attribute %s is %s, expected a number."
+ node-type (name attr) (pr-str v)))))))
+
+(defn- attr-pos-long
+ [node-type attr v]
+ ;; Range-check before coercing: `(long 1.0E19)` throws a raw IllegalArgumentException, which
+ ;; would escape as a 500 instead of the teaching error this value deserves.
+ (let [n (attr-num node-type attr v)
+ l (when (<= 1 n Long/MAX_VALUE) (long n))]
+ (when-not (and l (== n l))
+ (throw (teaching-error (format "Cannot serialize %s node: attribute %s is %s, expected a positive integer."
+ node-type (name attr) (pr-str v)))))
+ l))
+
+(defn- entity-token
+ "The `{% entity %}` token for a smartLink node's attrs, or nil when `model` isn't one this
+ grammar can express — the mirror of [[entity-token->smart-link]], which likewise declines an
+ unknown model rather than inventing a node. Interpolating `model` unescaped is safe precisely
+ because membership is checked first: no key of [[prose-mirror/smart-link-model->db-model]]
+ contains a quote,
+ a newline, or a token delimiter."
+ ^String [{:strs [entityId model]}]
+ (when (contains? prose-mirror/smart-link-model->db-model model)
+ (format "{%% entity id=\"%d\" model=\"%s\" %%}" (attr-pos-long "smartLink" :entityId entityId) model)))
+
+(defn- escape-card-name
+ "The `name=\"…\"` value for a card token, or nil when the name can't be carried in one. A token
+ delimiter is unescapable here: [[card-token-line-body]] rejects a line whose body contains one
+ with a plain substring test, so a backslash wouldn't save it and the whole embed would degrade
+ to prose. The name is a cached display label, so dropping just the name keeps the embed and its
+ card id intact."
+ ^String [^String card-name]
+ (when-not (re-find #"\{%|%\}" card-name)
+ (-> card-name
+ (str/replace "\\" "\\\\")
+ (str/replace "\"" "\\\"")
+ (str/replace #"\R" " "))))
+
+(defn- card-token
+ ^String [{:strs [id name]}]
+ (let [id (attr-pos-long "cardEmbed" :id id)
+ named (when (and (string? name) (not (str/blank? name)))
+ (escape-card-name name))]
+ (if named
+ (format "{%% card id=%d name=\"%s\" %%}" id named)
+ (format "{%% card id=%d %%}" id))))
+
+(defn- marked-text
+ "One text node's Markdown. Emphasis delimiters cannot touch whitespace (CommonMark
+ flanking), so boundary whitespace moves outside them; whole-whitespace text drops its
+ emphasis. Code content keeps its whitespace — [[code-span]] pads instead."
+ ^String [{:keys [text marks]}]
+ (let [text (or text "")
+ code? (has-mark? marks "code")
+ italic? (has-mark? marks "italic")
+ bold? (has-mark? marks "bold")
+ [lead core trail] (if (and (or italic? bold?) (not code?))
+ (split-boundary-whitespace text)
+ ["" text ""])
+ body (if (= core "")
+ (escape-inline text)
+ (let [s (if code? (code-span core) (escape-inline core))
+ s (cond-> s
+ italic? (as-> t (str "*" t "*"))
+ bold? (as-> t (str "**" t "**")))]
+ (str lead s trail)))]
+ (if-let [{:strs [href]} (mark-attrs marks "link")]
+ (str "[" body "](" (link-destination href) ")")
+ body)))
+
+(defn- inline->markdown
+ (^String [node]
+ (inline->markdown node nil))
+ (^String [{:keys [type attrs] :as node} {:keys [hard-break] :or {hard-break "\\\n"}}]
+ (case type
+ "text" (marked-text node)
+ "hardBreak" hard-break
+ ;; A model this grammar has no token for — a link type the frontend added, or a corrupted
+ ;; attr — degrades to its cached label as prose. Failing instead would take the whole
+ ;; document body down over one node, and parse already treats an unknown model as text.
+ "smartLink" (or (entity-token attrs)
+ (do (log/warnf "no entity token for smartLink model %s; serializing its label as text"
+ (pr-str (get attrs "model")))
+ (escape-inline (str (get attrs "label")))))
+ "metabot-mention" ""
+ (throw (ex-info (format "Cannot serialize unknown inline node type %s to Markdown." (pr-str type))
+ {:status-code 400 :node-type type})))))
+
+(defn- inlines->markdown
+ (^String [content]
+ (inlines->markdown content nil))
+ (^String [content opts]
+ (apply str (map #(inline->markdown % opts) content))))
+
+;;; ------------------------------------------------ Serialize: blocks ---------------------------------------------
+
+;; ctx is {:sb StringBuilder, :spans volatile-vector-or-nil, :record? bool}. Emission returns
+;; an extent {:node …, :start …, :end …, :children …} per block: char offsets into the buffer,
+;; end exclusive. :children extents are kept only for container nodes, whose fenced content is
+;; emitted verbatim — the recursion path `splice` may descend. Blockquote and list content is
+;; re-rendered with line prefixes, so descendant offsets there would be meaningless: those
+;; subtrees are rendered through a fresh non-recording context and get no nested extents.
+
+(declare emit-blocks!)
+
+(defn- render-blocks
+ ^String [nodes]
+ (let [sb (StringBuilder.)]
+ (emit-blocks! {:sb sb :spans nil :record? false} nodes)
+ (.toString sb)))
+
+;; Both prefixers split on [[line-ending-re]], not on `\n`. The body they are handed can hold a
+;; line ending they didn't put there: code block content is emitted raw, being the one text the
+;; serializer must not escape. A line the parser starts that the prefixer didn't prefix escapes the
+;; blockquote or list entirely — for a code block that puts the closing fence outside the prefix,
+;; where it re-opens as a new block instead of closing the old one.
+
+(defn- prefix-quote
+ ^String [^String s]
+ (->> (str/split s line-ending-re -1)
+ (map #(if (str/blank? %) ">" (str "> " %)))
+ (str/join "\n")))
+
+(defn- prefix-list-item
+ ^String [^String marker ^String body]
+ (let [indent (apply str (repeat (count marker) " "))
+ lines (str/split body line-ending-re -1)]
+ (str marker
+ (first lines)
+ (when (next lines)
+ (str "\n" (str/join "\n" (map #(if (str/blank? %) "" (str indent %)) (rest lines))))))))
+
+(defn- format-number
+ ^String [n]
+ (let [d (double n)]
+ ;; The long-range check keeps `(long d)` from throwing on an integral double a long can't
+ ;; hold (e.g. 1.0E19); such a value serializes in its double notation instead.
+ (if (and (== d (Math/rint d))
+ (<= Long/MIN_VALUE d Long/MAX_VALUE))
+ (str (long d))
+ (str d))))
+
+(defn- code-fence-for
+ ^String [^String text]
+ (let [longest (transduce (map count) max 0 (re-seq #"`+" text))]
+ (apply str (repeat (max 3 (inc longest)) "`"))))
+
+(defn- tilde-fence-for
+ ^String [^String text]
+ (let [longest (transduce (map count) max 0 (re-seq #"~+" text))]
+ (apply str (repeat (max 3 (inc longest)) "~"))))
+
+(defn- resize-fence
+ ^String [{:strs [height minHeight]}]
+ (format "::: resize {height=%s minHeight=%s}"
+ (format-number (attr-num "resizeNode" :height (or height resize-node-default-height)))
+ (format-number (attr-num "resizeNode" :minHeight (or minHeight resize-node-default-min-height)))))
+
+(defn- flex-fence
+ ^String [{:strs [columnWidths]}]
+ (if (seq columnWidths)
+ (format "::: flex {columns=[%s]}"
+ (str/join "," (map #(format-number (attr-num "flexContainer" :columnWidths %)) columnWidths)))
+ "::: flex"))
+
+(defn- block-body
+ "The Markdown text of a leaf (non-container) block node, or nil when the node type is not a
+ leaf block handled inline here."
+ [{:keys [type attrs content] :as _node}]
+ (case type
+ "paragraph" (escape-block-starts (inlines->markdown content))
+ ;; A heading is a single ATX line: hard breaks render as spaces, and a trailing hash run
+ ;; is escaped so re-parsing doesn't strip it as a closing sequence.
+ "heading" (str (apply str (repeat (max 1 (long (attr-num "heading" :level (or (get attrs "level") 1)))) "#"))
+ " "
+ ;; Newlines collapse before the trailing-hash escape: an ATX heading is
+ ;; one line, so a literal newline in a text node would otherwise let the
+ ;; rest of the run open a new block on re-parse.
+ (-> (inlines->markdown content {:hard-break " "})
+ (str/replace #"\R" " ")
+ (str/replace #"(^|[ \t])(#+[ \t]*)$" "$1\\\\$2")))
+ ;; The language rides the fence line, so a value that would break the line out of being a
+ ;; fence re-opens the code content to the parser — the token-opacity guarantee dies with the
+ ;; fence. A backtick fence's info string may not contain a backtick (CommonMark), but a tilde
+ ;; fence's may (and a tilde fence's info string is exactly where a parsed `:language` picks
+ ;; one up), so such a language re-serializes behind a tilde fence; a newline can't ride any
+ ;; fence line, so it collapses to a space, as a card name's does.
+ "codeBlock" (let [text (apply str (map :text content))
+ language (str/replace (str (or (get attrs "language") "")) #"\R" " ")
+ fence (if (str/includes? language "`")
+ (tilde-fence-for text)
+ (code-fence-for text))]
+ (str fence language "\n"
+ (when-not (= text "") (str text "\n"))
+ fence))
+ "blockquote" (prefix-quote (render-blocks content))
+ "bulletList" (->> content
+ (map #(prefix-list-item "- " (render-blocks (:content %))))
+ (str/join "\n"))
+ "orderedList" (let [start (long (attr-num "orderedList" :start (or (get attrs "start") 1)))]
+ (->> content
+ (map-indexed (fn [i item]
+ (prefix-list-item (str (+ start i) ". ")
+ (render-blocks (:content item)))))
+ (str/join "\n")))
+ "horizontalRule" "---"
+ "cardEmbed" (card-token attrs)
+ nil))
+
+(defn- record-span!
+ [{:keys [spans record?]} node start end]
+ (when (and record? spans)
+ (when-let [id (get-in node [:attrs "_id"])]
+ (vswap! spans conj {:node-id id :start start :end end}))))
+
+(defn- emit-block!
+ "Append `node`'s Markdown to the buffer; returns its extent."
+ [{:keys [^StringBuilder sb] :as ctx} {:keys [type attrs content] :as node}]
+ (let [start (.length sb)
+ child-extents
+ (if (container-types type)
+ (do (.append sb ^String (case type
+ "resizeNode" (resize-fence attrs)
+ "flexContainer" (flex-fence attrs)
+ "supportingText" "::: supporting"))
+ (.append sb "\n")
+ (let [extents (emit-blocks! ctx content)]
+ (.append sb "\n:::")
+ extents))
+ (if-let [body (block-body node)]
+ (do (.append sb ^String body) nil)
+ (throw (ex-info (format "Cannot serialize unknown block node type %s to Markdown." (pr-str type))
+ {:status-code 400 :node-type type}))))
+ end (.length sb)]
+ (record-span! ctx node start end)
+ {:node node :start start :end end :children child-extents}))
+
+(def ^:private list-block-types #{"bulletList" "orderedList"})
+
+(defn- emit-blocks!
+ "Append `nodes` (block siblings) separated by blank lines; returns their extents, index-aligned
+ with `nodes`. Adjacent lists of the same type additionally get an HTML-comment separator (a
+ blank line alone would merge them into one list on re-parse; the comment drops out of the
+ parsed AST). Transient metabot nodes emit nothing and get an empty extent at their position."
+ [{:keys [^StringBuilder sb] :as ctx} nodes]
+ (loop [nodes (seq nodes), prev-type nil, extents []]
+ (if-not nodes
+ extents
+ (let [{:keys [type] :as node} (first nodes)]
+ (if (transient-types type)
+ (recur (next nodes) prev-type
+ (conj extents {:node node :start (.length sb) :end (.length sb) :children nil}))
+ (do (when prev-type
+ (.append sb ^String (if (and (= prev-type type) (list-block-types type))
+ "\n\n<!-- -->\n\n"
+ "\n\n")))
+ (recur (next nodes) type (conj extents (emit-block! ctx node)))))))))
+
+(defn- serialize*
+ [ast]
+ (let [sb (StringBuilder.)
+ spans (volatile! [])
+ extents (emit-blocks! {:sb sb :spans spans :record? true} (:content ast))]
+ {:markdown (.toString sb)
+ :spans (vec (sort-by (juxt :start (comp - :end)) @spans))
+ :extents extents}))
+
+(defn serialize
+ "ProseMirror AST -> `{:markdown string, :spans [{:node-id string, :start int, :end int} …]}`.
+ `:spans` covers every node carrying an `:_id` whose text appears verbatim in `:markdown`
+ (blocks nested inside blockquotes/lists are re-rendered with line prefixes and get no span of
+ their own — their text falls inside the span of the nearest enclosing block that has one, which
+ is not necessarily a top-level one), in document order; offsets are character indexes,
+ end exclusive. Deterministic: the same AST always serializes to the same string, which is
+ what makes untouched-node reuse in [[splice]] well-defined. Transient metabot nodes are
+ skipped entirely — no token, no span.
+
+ The namespaced `::extents`/`::ast` keys are a fast path for [[splice]]: when handed the
+ serialization of the very AST being spliced, it reuses these instead of re-serializing."
+ [ast]
+ (let [{:keys [markdown spans extents]} (serialize* ast)]
+ {:markdown markdown
+ :spans spans
+ ::markdown markdown
+ ::extents extents
+ ::ast ast}))
+
+;;; --------------------------------------------- Node reconciliation ----------------------------------------------
+
+(def ^:private convertible-block-types
+ "Block types the editor turns into one another in place. Tiptap's input rules, `setNode` and
+ the list toggles rewrite the node while keeping its attrs, so typing `## ` in front of a
+ paragraph leaves the block's `:_id` — and any comment anchored to it — intact. Reconciliation
+ treats a change within this set as the same block; every other type matches only its own kind,
+ so a comment on a chart can never migrate onto prose."
+ #{"paragraph" "heading" "blockquote" "bulletList" "orderedList" "codeBlock"})
+
+(def ^:private block-content-types
+ "Node types whose `:content` holds block nodes rather than inline content. Reconciliation
+ recurses through these to reach nested ids: a paragraph inside a blockquote or a list item is
+ an anchor target in its own right."
+ #{"blockquote" "listItem" "bulletList" "orderedList" "supportingText" "flexContainer" "resizeNode"})
+
+(defn- node-key
+ "Content-identity key for a block: its type plus its canonical Markdown. Equal keys mean the
+ two nodes are byte-identical in the projection, which is what makes a block the edit didn't
+ touch recognisable wherever it moved to. A `listItem` has no standalone rendering — its marker
+ belongs to the parent list — so it is keyed by its children's text."
+ [{:keys [type content] :as node}]
+ [type (render-blocks (if (= "listItem" type) content [node]))])
+
+(defn- lcs-pairs
+ "Index pairs `[i j]` of a longest common subsequence of `a` and `b`, ascending. Ties resolve
+ toward advancing `a`, making the alignment a pure function of the two vectors."
+ [a b]
+ (let [n (count a)
+ m (count b)
+ ;; dp[i][j] = length of the LCS of a[i:] and b[j:]; row n and column m are the zero base.
+ dp (reduce (fn [dp i]
+ (assoc dp i
+ (reduce (fn [row j]
+ (assoc row j
+ (if (= (nth a i) (nth b j))
+ (inc (long (get-in dp [(inc i) (inc j)])))
+ (max (long (get-in dp [(inc i) j]))
+ (long (get row (inc j)))))))
+ (vec (repeat (inc m) 0))
+ (range (dec m) -1 -1))))
+ (vec (repeat (inc n) (vec (repeat (inc m) 0))))
+ (range (dec n) -1 -1))]
+ (loop [i 0, j 0, acc []]
+ (cond
+ (or (= i n) (= j m))
+ acc
+
+ (= (nth a i) (nth b j))
+ (recur (inc i) (inc j) (conj acc [i j]))
+
+ (>= (long (get-in dp [(inc i) j])) (long (get-in dp [i (inc j)])))
+ (recur (inc i) j acc)
+
+ :else
+ (recur i (inc j) acc)))))
+
+(defn- align
+ "Pairs `[old-index new-index]` matching `old-nodes` to `new-nodes`. Blocks the edit left alone
+ match on content wherever they moved; the runs between those anchors pair up head-first, which
+ is how ProseMirror resolves the ambiguous cases — a split leaves the id on the first of the two
+ halves, a merge keeps the head block's id and drops the tail's."
+ [old-nodes new-nodes]
+ (let [anchors (lcs-pairs (mapv node-key old-nodes) (mapv node-key new-nodes))]
+ (loop [oi 0, ni 0, anchors (seq anchors), acc []]
+ (let [[ao an] (first anchors)
+ o-stop (or ao (count old-nodes))
+ n-stop (or an (count new-nodes))
+ acc (into acc
+ (map (fn [k] [(+ oi k) (+ ni k)]))
+ (range (min (- o-stop oi) (- n-stop ni))))]
+ (if anchors
+ (recur (inc (long ao)) (inc (long an)) (next anchors) (conj acc [ao an]))
+ acc)))))
+
+(defn- same-block?
+ [old new]
+ (let [ot (:type old)
+ nt (:type new)]
+ (or (= ot nt)
+ (and (convertible-block-types ot) (convertible-block-types nt)))))
+
+(defn- carry-id
+ [new-node old-node]
+ (let [id (get-in old-node [:attrs "_id"])]
+ (cond-> new-node
+ (and id (contains? (:attrs new-node) "_id")) (assoc-in [:attrs "_id"] id))))
+
+(defn- carry-attrs
+ "Carry the old node's attrs onto its re-parsed counterpart, with freshly parsed values winning.
+
+ A node's serialized text does not round-trip every attr it holds: a card token writes `id` and
+ `name`, so re-parsing one drops `stored_result_id`, `sort`, `chart_href`, `child_target_id`, and
+ `host_data`. `child_target_id` anchors comments and the rest is user-visible visualization state,
+ so a splice that re-parses a sibling it did not semantically change must not shed them.
+
+ Only same-type pairs merge. [[same-block?]] also pairs convertible types (a paragraph with a
+ bulletList), where the old attrs describe a different node shape -- a heading's `level` has no
+ meaning on the paragraph it became -- so those keep the id-only carry.
+
+ `:_id` goes the other way. Every other attr is parsed from the node's text, so a fresh value is
+ the edit's intent and has to win -- retargeting a card token to `id=1234` must not be undone by
+ the old `id=7`. But `:_id` is minted anew by [[parse]] on every node, never round-tripped, so a
+ fresh one is not intent, just a new identity. Letting it win would rename the block on every
+ splice and orphan the comments anchored to it, which is the guarantee [[reconcile-ids]] exists
+ to keep."
+ [new-node old-node]
+ (if (= (:type new-node) (:type old-node))
+ (-> new-node
+ (update :attrs #(merge (:attrs old-node) %))
+ (carry-id old-node))
+ (carry-id new-node old-node)))
+
+(defn- reconcile-ids
+ "Give freshly parsed `new-nodes` the `:_id`s of the `old-nodes` they replace, so a block whose
+ text an edit rewrote keeps the identity its comments anchor to — the same guarantee the editor
+ gives, where a node survives its own text changing. Follows [[align]]'s pairs and recurses
+ through nested block content. A new node with no counterpart keeps the id [[parse]] minted for
+ it, and an old id with no counterpart is dropped: that block is genuinely gone."
+ [old-nodes new-nodes]
+ (let [old (vec old-nodes)
+ new (vec new-nodes)]
+ (reduce (fn [acc [oi ni]]
+ (let [o (nth old oi)
+ n (nth acc ni)]
+ (if-not (same-block? o n)
+ acc
+ (assoc acc ni
+ (cond-> (carry-attrs n o)
+ ;; Both sides must hold block content. `convertible-block-types` lets a
+ ;; paragraph pair with a bulletList or blockquote, but a paragraph's
+ ;; `:content` is inline — recursing on the new node's type alone hands
+ ;; text nodes to [[node-key]], which can only render blocks.
+ (and (block-content-types (:type n))
+ (block-content-types (:type o))
+ (seq (:content n)))
+ (update :content #(reconcile-ids (:content o) %)))))))
+ new
+ (align old new))))
+
+;;; ------------------------------------------------ Splice --------------------------------------------------------
+
+(defn- touched-range
+ "Indexes [i j] of the extents overlapping [s e), or nil when the span falls entirely between
+ siblings. An insertion point (s = e) touching a block boundary belongs to that block."
+ [extents s e]
+ (if (= s e)
+ (when-let [i (first (keep-indexed (fn [i {:keys [start end]}]
+ (when (<= start s end) i))
+ extents))]
+ [i i])
+ (let [is (keep-indexed (fn [i {:keys [start end]}]
+ (when (if (= start end)
+ (and (< s start) (> e start))
+ (and (< s end) (> e start)))
+ i))
+ extents)]
+ (when (seq is)
+ [(first is) (last is)]))))
+
+(defn- insertion-index
+ [extents pos]
+ (or (first (keep-indexed (fn [i {:keys [start]}] (when (>= start pos) i)) extents))
+ (count extents)))
+
+(defn- validate-spliced!
+ [parent-type children]
+ (when (container-types parent-type)
+ (validate-container-content! parent-type children)))
+
+(defn- splice-level
+ "Splice [s e) -> `replacement` into the children `nodes` (extents index-aligned). Descends
+ into a single touched container when the span fits inside its children region; otherwise
+ re-parses the touched sibling run and reuses every other sibling untouched."
+ [nodes extents ^String markdown s e replacement parent-type]
+ (let [nodes (vec nodes)
+ [i j] (touched-range extents s e)]
+ (cond
+ (nil? i)
+ (if (= s e)
+ (let [idx (insertion-index extents s)
+ inserted (parse-content replacement)
+ result (into (into (subvec nodes 0 idx) inserted) (subvec nodes idx))]
+ (validate-spliced! parent-type result)
+ result)
+ ;; The span deletes separator text between two siblings: both get re-parsed together.
+ (let [idx (insertion-index extents e)
+ i (max 0 (dec idx))
+ j (min (dec (count nodes)) idx)]
+ (recur nodes extents markdown
+ (:start (nth extents i)) (:end (nth extents j))
+ (str (subs markdown (:start (nth extents i)) s)
+ replacement
+ (subs markdown e (:end (nth extents j))))
+ parent-type)))
+
+ ;; A single touched container whose children region contains the whole span: descend, so
+ ;; the edit re-parses the innermost siblings and everything else keeps its identity.
+ (and (= i j)
+ (container-types (:type (nth nodes i)))
+ (seq (:children (nth extents i)))
+ (>= s (:start (first (:children (nth extents i)))))
+ (<= e (:end (last (:children (nth extents i))))))
+ (let [node (nth nodes i)]
+ (assoc nodes i
+ (assoc node :content
+ (splice-level (:content node) (:children (nth extents i))
+ markdown s e replacement (:type node)))))
+
+ :else
+ ;; The edit span may spill past the touched blocks into separator whitespace on either
+ ;; side; widen the re-parsed region to cover it so the substring arithmetic stays valid.
+ (let [region-start (min s (:start (nth extents i)))
+ region-end (max e (:end (nth extents j)))
+ new-text (str (subs markdown region-start s)
+ replacement
+ (subs markdown e region-end))
+ new-nodes (reconcile-ids (subvec nodes i (inc j)) (parse-content new-text))
+ result (into (into (subvec nodes 0 i) new-nodes) (subvec nodes (inc j)))]
+ (validate-spliced! parent-type result)
+ result))))
+
+(defn splice
+ "`old-ast`, the `{:markdown :spans}` from a prior [[serialize]] call on `old-ast`, a character
+ span [start end) to replace, and the replacement text -> new AST.
+
+ Finds the minimal children array whose combined span contains [start end), recursing into
+ layout containers as needed. Every sibling whose own text doesn't overlap the span is reused
+ by identity from `old-ast` — same `:_id`, same attrs, same nested content. The overlapping
+ sibling(s) have their serialized text, with the edit applied, re-parsed, and
+ [[reconcile-ids]] then carries the old nodes' `:_id`s onto the parsed result, so editing a
+ block's text preserves the identity its comments anchor to. Throws a 400 `ex-info`
+ when `markdown` doesn't match `old-ast`'s serialization (a stale source map), when the span
+ is out of bounds, when the re-parsed result violates a container's content model, or when the
+ replacement nests too deeply to parse."
+ [old-ast {:keys [markdown] ::keys [extents ast] trusted-markdown ::markdown} start end replacement-text]
+ (let [{fresh-markdown :markdown extents :extents}
+ (if (and extents trusted-markdown (identical? ast old-ast))
+ {:markdown trusted-markdown :extents extents}
+ (serialize* old-ast))]
+ (when (not= fresh-markdown markdown)
+ (throw (teaching-error "The provided markdown doesn't match the document's current serialization — re-serialize and retry.")))
+ (when-not (and (int? start) (int? end) (<= 0 start end (count fresh-markdown)))
+ (throw (teaching-error (format "Invalid splice span [%s %s) for a %d-character document."
+ start end (count fresh-markdown)))))
+ (try
+ (assoc old-ast :content
+ (-> (splice-level (:content old-ast) extents fresh-markdown
+ start end (or replacement-text "") "doc")
+ wrap-loose-embeds
+ ensure-trailing-paragraph))
+ ;; The same backstop [[parse]] has, for the same reason: the re-parse of the edited region
+ ;; runs through flexmark, whose inline parser can blow the stack on a long delimiter run in
+ ;; the replacement text before there is a tree to measure. Splicing is pure, so nothing is
+ ;; half-written when the stack unwinds.
+ (catch StackOverflowError _
+ (throw (teaching-error "Markdown is nested too deeply to parse — flatten it."))))))
diff --git a/src/metabase/documents/models/document.clj b/src/metabase/documents/models/document.clj
index e183b10ea85..9e779be100b 100644
--- a/src/metabase/documents/models/document.clj
+++ b/src/metabase/documents/models/document.clj
@@ -2,13 +2,20 @@
(:require
[clojure.string :as str]
[metabase.api.common :as api]
+ [metabase.collections.core :as collections]
[metabase.collections.models.collection :as collection]
[metabase.documents.db :as documents.db]
[metabase.documents.prose-mirror :as prose-mirror]
[metabase.events.core :as events]
+ [metabase.lib-be.schema :as lib-be.schema]
[metabase.models.interface :as mi]
[metabase.models.serialization :as serdes]
+ [metabase.parameters.params :as params]
+ [metabase.parameters.schema :as parameters.schema]
[metabase.public-sharing.core :as public-sharing]
+ [metabase.queries.core :as card]
+ [metabase.queries.schema :as queries.schema]
+ [metabase.query-permissions.core :as query-perms]
[metabase.search.config :as search.config]
[metabase.search.spec :as search.spec]
[metabase.util :as u]
@@ -16,6 +23,7 @@
[metabase.util.json :as json]
[metabase.util.log :as log]
[metabase.util.malli :as mu]
+ [metabase.util.malli.schema :as ms]
[methodical.core :as methodical]
[toucan2.core :as t2]
[toucan2.instance :as t2.instance]))
@@ -147,6 +155,276 @@
(api/check-400 (documents.db/unarchived-collection-exists? new-collection-id))
(api/write-check :model/Collection new-collection-id)))
+;;; ------------------------------------------------ Write orchestration -------------------------------------------
+
+(def CardCreateSchema
+ "Schema for a card created inline with a document (the `cards` map on create/update). The
+ card fields are declared locally: the model layer doesn't depend on the REST card schema."
+ [:map {:closed true}
+ [:name ms/NonBlankString]
+ [:dataset_query ::lib-be.schema/maybe-legacy-query]
+ [:entity_id {:optional true} [:maybe ms/NonBlankString]]
+ [:parameters {:optional true} [:maybe ::parameters.schema/parameters]]
+ [:parameter_mappings {:optional true} [:maybe ::parameters.schema/parameter-mappings]]
+ [:description {:optional true} [:maybe ms/NonBlankString]]
+ [:display ms/NonBlankString]
+ [:visualization_settings ms/VisualizationSettings]
+ [:result_metadata {:optional true} [:maybe ::queries.schema/card.result-metadata]]
+ [:cache_ttl {:optional true} [:maybe ms/PositiveInt]]])
+
+(defn- create-card!
+ "The single choke point every document card-creation path (create, update, copy) funnels through. Runs the same
+ checks `POST /api/card` runs before saving: create access to the target collection, run permission on the query,
+ read access to any card the parameters draw values from, and query permission on the fields the parameter targets
+ name."
+ [{query :dataset_query :as card} creator]
+ (api/create-check :model/Card {:collection_id (:collection_id card)})
+ (query-perms/check-run-permissions-for-query (dissoc query :query-permissions/perms))
+ (card/check-parameter-source-card-permissions (:parameters card))
+ (query-perms/check-parameter-field-permissions
+ (into []
+ (keep #(some-> % :target (params/param-target->field-id {:dataset_query query})))
+ (:parameters card)))
+ (card/create-card! (assoc card :type :question :dashboard_id nil) creator))
+
+(defn clone-card!
+ "Saves a copy of an existing card the user can already read, e.g. when embedding it into a document.
+
+ Still checks create access to the target collection, but unlike [[create-card!]] deliberately skips the authoring
+ checks (run permission on the query, parameter source-card and parameter field permissions): the query and
+ parameters come from an existing card row the caller passed a read check on rather than from the request, so the
+ user is not authoring anything -- they may be able to view (and run) the source card without having permission to
+ write such a query themselves, e.g. a native card when they lack native query editing perms (UXW-5037). Running the
+ clone is still gated by the usual runtime permission checks, the same ones that gate running the source card."
+ [card creator]
+ (api/create-check :model/Card {:collection_id (:collection_id card)})
+ (card/create-card! (assoc card :type :question :dashboard_id nil) creator))
+
+(mu/defn update-cards-in-ast :- [:map [:document :any]
+ [:content_type :string]]
+ "Rewrite the card FK (`[:attrs \"id\"]`) of every cardEmbed node found in `card-id-map`.
+ Touches nothing else on the node — in particular a node's `:_id` never changes here."
+ [document :- [:map
+ [:document :any]
+ [:content_type :string]]
+ card-id-map :- [:maybe [:map-of :int ms/PositiveInt]]]
+ (cond-> document
+ (map? document)
+ (prose-mirror/update-ast (fn match-card-to-update [{:keys [type attrs]}]
+ (and (= type prose-mirror/card-embed-type)
+ (contains? card-id-map (get attrs "id"))))
+ (fn update-card-id [embed]
+ (update-in embed [:attrs "id"] card-id-map)))))
+
+(mu/defn- create-cards-for-document! :- [:map-of ms/NegativeInt ms/PositiveInt]
+ "Creates cards for a document from the cards map.
+ Returns a mapping from the original negative integer keys to the newly created card IDs.
+
+ Args:
+ - cards-to-create: Map of negative-int -> CardCreateSchema data
+ - document-id: ID of the document these cards belong to
+ - document-collection-id: Collection ID of the document (for inheritance)
+ - creator: User creating the cards
+
+ Returns:
+ - Map of negative-int -> actual-card-id"
+ [cards-to-create :- [:map-of [:int {:max -1}] CardCreateSchema]
+ document-id :- ms/PositiveInt
+ document-collection-id :- [:or :nil ms/PositiveInt]
+ creator :- [:map [:id ms/PositiveInt]]]
+ (when (seq cards-to-create)
+ (reduce-kv
+ (fn [result-map original-key card-data]
+ (let [;; Merge document info into card data
+ ;; Cards inherit document's collection_id if not explicitly specified
+ merged-card-data (-> card-data
+ (assoc :document_id document-id)
+ (cond-> (nil? (:collection_id card-data))
+ (assoc :collection_id document-collection-id)))
+ ;; Create the card using the queries core function
+ new-card (create-card! merged-card-data creator)]
+ (assoc result-map original-key (:id new-card))))
+ {}
+ cards-to-create)))
+
+(mu/defn clone-cards-in-document! :- [:map-of ms/PositiveInt ms/PositiveInt]
+ "Finds all cards in the document that are not associated with the document and clones the cards.
+
+ Args:
+ - document: the document model to clone cards within
+
+ Returns:
+ - map of old-card-id -> cloned-card-id"
+ [{:keys [id collection_id] :as document}]
+ (let [card-ids (prose-mirror/collect-ast document #(when (and (= prose-mirror/card-embed-type (:type %))
+ (pos-int? (get (:attrs %) "id")))
+ (get (:attrs %) "id")))
+ to-clone (when (seq card-ids)
+ (documents.db/cards-not-in-document card-ids id))]
+ (with-content-gate-cache
+ (reduce (fn [accum card]
+ (api/read-check card)
+ (assoc accum
+ (:id card)
+ (:id (clone-card! (assoc card :document_id id :collection_id collection_id)
+ @api/*current-user*))))
+ {}
+ to-clone))))
+
+(defn- hydrate-document
+ "Fetch a document by id along with the derived fields the API returns. Does *not* check permissions or
+ publish a read event, so it is safe to use on write paths (PUT/POST) where recording a view would be
+ both semantically wrong and an extra, avoidable round-trip."
+ [id]
+ (t2/hydrate (documents.db/document id) :creator :can_write :can_delete :can_restore :is_remote_synced))
+
+(defn get-document
+ "Get document by id checking if the current user has permission to access and if the document exists.
+ Pass `:log-view? false` to skip publishing the `:event/document-read` view event."
+ [id & {:keys [log-view?] :or {log-view? true}}]
+ (u/prog1 (api/check-404
+ (api/read-check
+ (hydrate-document id)))
+ (when log-view?
+ (events/publish-event! :event/document-read
+ {:object-id id
+ :user-id api/*current-user-id*}))))
+
+(defn- draft-stored-result-pairings
+ "From the incoming document AST and a draft→new card-id map, collect distinct
+ `[new-card-id stored-result-id]` pairs for draft embeds that carry a `stored_result_id`.
+
+ Only negative keys from `card-id-map` are considered (the draft-created set); clone
+ remappings are irrelevant here."
+ [document content-type draft-card-id-map]
+ (when (and (seq draft-card-id-map) document)
+ (->> (prose-mirror/collect-ast
+ {:document document :content_type content-type}
+ (fn [{:keys [type attrs]}]
+ (when (and (= prose-mirror/card-embed-type type)
+ (contains? draft-card-id-map (get attrs "id"))
+ (get attrs "stored_result_id"))
+ [(get draft-card-id-map (get attrs "id"))
+ (get attrs "stored_result_id")])))
+ distinct
+ vec)))
+
+(mu/defn create-document!
+ "Create a Document, clone any embedded cards the document doesn't own, publish
+ `:event/document-create`, and return the created document. Permission checks
+ (`api/create-check`) are the caller's job, run before this — the same split the REST
+ `POST /api/document/` handler uses."
+ [{:keys [name document collection_id collection_position cards]}
+ :- [:map
+ [:name DocumentName]
+ [:document :any]
+ [:collection_id {:optional true} [:maybe ms/PositiveInt]]
+ [:collection_position {:optional true} [:maybe ms/PositiveInt]]
+ [:cards {:optional true} [:maybe [:map-of [:int {:max -1}] CardCreateSchema]]]]]
+ (let [created-document (t2/with-transaction [_conn]
+ (when collection_position
+ (api/maybe-reconcile-collection-position! {:collection_id collection_id
+ :collection_position collection_position}))
+ (let [document-id (documents.db/insert-document! {:name name
+ :collection_id collection_id
+ :collection_position collection_position
+ :document document
+ :content_type prose-mirror/prose-mirror-content-type
+ :creator_id api/*current-user-id*})
+ cards-to-update-in-ast (merge (clone-cards-in-document! {:id document-id
+ :collection_id collection_id
+ :document document
+ :content_type prose-mirror/prose-mirror-content-type})
+ (when-not (empty? cards)
+ (create-cards-for-document! cards document-id collection_id @api/*current-user*)))]
+ (when (seq cards-to-update-in-ast)
+ (documents.db/update-document! document-id
+ (update-cards-in-ast
+ {:document document
+ :content_type prose-mirror/prose-mirror-content-type}
+ cards-to-update-in-ast)))
+ ;; `get-document`, so `:event/document-read` fires: the creator has to find the
+ ;; document they just made in their recents, and that row is written only by this
+ ;; event's handler. Creating is arguably not viewing — but the view count and
+ ;; `view_log` row it also writes are the cost of the recents entry until the two
+ ;; are decoupled; suppressing the event silently drops the document out of the
+ ;; command palette (UXW-1786).
+ ;;
+ ;; The read check inside it still has to run: `can-read?` on a Document is
+ ;; collection permissions *and* the content gate, and the gate adjudicates the
+ ;; warehouse data the body embeds, so a document the creator may not read must not
+ ;; come back rendered.
+ (u/prog1 (get-document document-id)
+ (when (collections/remote-synced-collection? (:collection_id <>))
+ (collections/check-non-remote-synced-dependencies <>)))))]
+ ;; Publish event after successful creation
+ (events/publish-event! :event/document-create
+ {:object created-document
+ :user-id api/*current-user-id*})
+ created-document))
+
+(mu/defn update-document!
+ "Apply `body` (any of `:name`, `:document`, `:collection_id`, `:collection_position`,
+ `:cards`, `:archived`) to `existing-document`, clone any newly-embedded cards the document
+ doesn't own, publish `:event/document-update` (or `:event/document-delete` when archiving),
+ and return the updated document. Permission checks (write-check, archived state,
+ collection-move) are the caller's job, run before this — the same split the REST
+ `PUT /api/document/:id` handler uses."
+ [existing-document :- [:map [:id ms/PositiveInt]]
+ {:keys [name document collection_id collection_position cards] :as body}
+ :- [:map
+ [:name {:optional true} DocumentName]
+ [:document {:optional true} :any]
+ [:collection_id {:optional true} [:maybe ms/PositiveInt]]
+ [:collection_position {:optional true} [:maybe ms/PositiveInt]]
+ ;; Any int key, matching the REST `DocumentUpdateOptions` this backs: with no `:document`
+ ;; in the body the map is ignored entirely, and [[create-cards-for-document!]] still holds
+ ;; the actually-consumed keys to negative ints.
+ [:cards {:optional true} [:maybe [:map-of :int CardCreateSchema]]]
+ [:archived {:optional true} [:maybe :boolean]]]]
+ (let [document-id (:id existing-document)
+ document-updates (dissoc (api/updates-with-archived-directly existing-document body) :cards)]
+ (t2/with-transaction [_conn]
+ (when collection_position
+ (api/maybe-reconcile-collection-position! existing-document {:collection_id (if (contains? body :collection_id)
+ collection_id
+ (:collection_id existing-document))
+ :collection_position collection_position}))
+ (let [card-id-map (when document
+ (merge
+ (clone-cards-in-document! (assoc existing-document :document document))
+ (when-not (empty? cards)
+ (create-cards-for-document! cards document-id collection_id @api/*current-user*))))
+ draft-card-id-map (into {} (filter (comp neg? key) card-id-map))
+ pairings (draft-stored-result-pairings document
+ (:content_type existing-document)
+ draft-card-id-map)]
+ (documents.db/update-document! document-id
+ (cond-> document-updates
+ document (merge (update-cards-in-ast
+ {:document document
+ :content_type (:content_type existing-document)}
+ card-id-map))
+ name (assoc :name name)
+ (contains? body :collection_id) (assoc :collection_id collection_id)
+ ;; First body save clears the auto-created Summary placeholder flag.
+ (and (:is_placeholder existing-document)
+ (contains? body :document))
+ (assoc :is_placeholder false)))
+ (when (seq pairings)
+ (card/carry-pairings-for-document! document-id pairings)))
+ (collections/check-for-remote-sync-update existing-document))
+ (let [updated-document (hydrate-document document-id)]
+ ;; Publish appropriate events
+ (if (:archived document-updates)
+ (events/publish-event! :event/document-delete
+ {:object updated-document
+ :user-id api/*current-user-id*})
+ (events/publish-event! :event/document-update
+ {:object updated-document
+ :user-id api/*current-user-id*}))
+ updated-document)))
+
(methodical/defmethod t2/batched-hydrate [:model/Document :creator]
"Hydrate the creator (user) of a document based on the creator_id."
[_model k documents]
diff --git a/src/metabase/documents/prose_mirror.clj b/src/metabase/documents/prose_mirror.clj
index 346a0983f60..071079b3fdd 100644
--- a/src/metabase/documents/prose_mirror.clj
+++ b/src/metabase/documents/prose_mirror.clj
@@ -77,6 +77,22 @@
"Type of a smart-link node"
"smartLink")
+(def smart-link-model->db-model
+ "The row each smartLink `model` denotes. One source for both halves of the smart-link round
+ trip: [[metabase.documents.markdown]] reads the keys, which are the `{% entity %}` grammar's
+ whole vocabulary, and whoever resolves a link's label/href reads the values. Kept here rather
+ than in either caller because a model present in one half and not the other parses into a link
+ whose label silently never resolves."
+ {"card" :model/Card
+ "dataset" :model/Card
+ "metric" :model/Card
+ "dashboard" :model/Dashboard
+ "collection" :model/Collection
+ "table" :model/Table
+ "database" :model/Database
+ "document" :model/Document
+ "user" :model/User})
+
(def prose-mirror-content-type
"The vendored 'mime-type' for documents saved using the prose-mirror ast."
"application/json+vnd.prose-mirror")
diff --git a/src/metabase/lib/schema/common.cljc b/src/metabase/lib/schema/common.cljc
index 23007890cea..a9831613619 100644
--- a/src/metabase/lib/schema/common.cljc
+++ b/src/metabase/lib/schema/common.cljc
@@ -368,7 +368,8 @@
[:metabase.driver.sql.query-processor/wrap-in-case {:optional true} :boolean]
[:metabase.driver.sql.parameters.substitution/compiling-field-filter? {:optional true} :boolean]
[:metabase.driver.sqlserver/optimized-bucketing? {:optional true} :boolean]
- [:metabase.driver.mongo.query-processor/join-local {:optional true} [:ref :metabase.lib.schema.join/alias]]]
+ [:metabase.driver.mongo.query-processor/join-local {:optional true} [:ref :metabase.lib.schema.join/alias]]
+ [:metabase.mcp.v2.query/keyset {:optional true} :boolean]]
(disallowed-keys
{:ident ":ident is deprecated and should not be included in options maps"})])
diff --git a/src/metabase/mcp/README.md b/src/metabase/mcp/README.md
index ce883a7397d..0c5b2296f5b 100644
--- a/src/metabase/mcp/README.md
+++ b/src/metabase/mcp/README.md
@@ -52,23 +52,13 @@ Browser-based sessions (cookie auth) are also supported and receive unrestricted
Access tokens are scoped to limit what tools a client can use:
-| Scope | Grants access to |
-| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `agent:search` | `search` |
-| `agent:resource:read` | `read_resource` (always granted to any authenticated caller; per-URI perm checks happen inside the dispatcher) |
-| `agent:query:construct` | `construct_query` |
-| `agent:query` | `query` |
-| `agent:query:execute` | `execute_query` |
-| `agent:sql:construct` | `construct_native_query` |
-| `agent:sql:execute` | `execute_sql` |
-| `agent:question:create` | `create_question` |
-| `agent:question:update` | `update_question` (also covers "move card to collection" and archiving) |
-| `agent:question:execute` | `execute_question` |
-| `agent:metric:create` | `create_metric` |
-| `agent:metric:update` | `update_metric` (also covers "move metric to collection" and archiving) |
-| `agent:dashboard:create` | `create_dashboard` |
-| `agent:dashboard:update` | `update_dashboard` (also covers archiving) |
-| `agent:collection:create` | `create_collection` |
+| Scope | Tools it grants |
+| ----- | --------------- |
+| `agent:content:read` | `browse_collection`, `browse_data`, `get_content`, `get_parameter_values`, `learn`, `search` |
+| `agent:content:write` | `bookmark_content`, `collection_write`, `dashboard_write`, `document_write`, `duplicate_content`, `measure_write`, `metric_write`, `question_write`, `segment_write`, `transform_write` |
+| `agent:delivery:write` | `alert_write`, `subscription_write` |
+| `agent:query:run` | `execute_query`, `refresh_ui_credential`, `render_drill_through`, `run_saved_question`, `visualize_query` |
+| `agent:sql:run` | `execute_sql` |
Wildcard patterns (e.g. `agent:*`) match any scope with that prefix.
@@ -82,57 +72,53 @@ By default our consent screen grants access to all scopes without the opportunit
## Available tools
-The MCP server exposes these tools, dynamically generated from the Agent API endpoint metadata:
-
-### Discovery + read
-
-| Tool | Description |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search` | Search for tables, metrics, cards, dashboards, and collections using keyword or natural-language queries. |
-| `read_resource` | Read one or more Metabase entities by `metabase://` URI. Covers database/schema/table/collection/question/dashboard/metric/transform navigation. Up to 5 URIs per call. |
-
-### Query construction + execution
-
-| Tool | Description |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `construct_query` | Construct a query against a table or metric. Accepts the user's original `prompt` when available. Returns an opaque `query_handle` for use with `execute_query` or `visualize_query`. |
-| `construct_native_query` | Construct a native (raw SQL) query for a database. Returns an opaque `query_handle` to feed `create_question` and save it. Does not execute the SQL; native handles are rejected by `execute_query`/`query` (use `execute_sql` to run raw SQL). |
-| `query` | Query a table or metric directly. Supports pagination via continuation tokens. |
-| `execute_query` | Execute a previously constructed query and return results with column metadata. |
-| `execute_sql` | Execute a raw SQL query against a database. Requires the user to have native-query permission on the target database. Can be disabled instance-wide via the `mcp-execute-sql-enabled` setting. |
-| `execute_question` | Run a saved question by id and return its rows + column metadata. Runs under the caller's permissions. Parameterized questions are not supported (returns an error). |
-
-### Write
-
-| Tool | Description |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `create_metric` | Save a query as a reusable metric. Accepts a `query_handle` from `construct_query`. The query needs one aggregation and at most one date grouping. |
-| `update_metric` | Update a saved metric. Patch semantics. Setting `collection_id` moves it; setting `archived: true` archives it — a reversible soft delete, used when asked to delete a metric. A replacement `query` must still be a valid metric. |
-| `create_question` | Save a query as a named question (card). Accepts a `query_handle` from `construct_query` (MBQL) or `construct_native_query` (native SQL). Saving native requires native-query DB permission. |
-| `update_question` | Update a saved question. Patch semantics. Setting `collection_id` moves the card. Setting `archived: true` archives it — a reversible soft delete, used when asked to delete a question. Replacing the query accepts a `construct_query` or `construct_native_query` handle. |
-| `create_dashboard` | Create a new dashboard, optionally populated with saved questions (auto-positioned on the grid). |
-| `update_dashboard` | Update a dashboard's metadata (name, description, collection, archived — a reversible soft delete, used when asked to delete a dashboard). |
-| `create_collection` | Create a new collection. Optionally nested under a `parent_collection_id`. |
+Generated from the v2 registry (`deftool`); every tool is gated by the single scope named here, and a
+token missing it neither sees the tool in `tools/list` nor may call it.
+
+| Tool | Scope | Description |
+| ---- | ----- | ----------- |
+| `alert_write` | `agent:delivery:write` | Create or update an alert: a notification sent on a schedule when a saved question's results meet a condition. |
+| `bookmark_content` | `agent:content:write` | Add or remove a bookmark on content for the calling user — the same starred/favorites list the Metabase sidebar shows. |
+| `browse_collection` | `agent:content:read` | Browse collections structurally — one uniform id over every partition: a numeric id, a 21-char entity_id, "root" (re-rooted per namespace), or "trash" (archived content, items mode only). |
+| `browse_data` | `agent:content:read` | Browse the data hierarchy: databases → schemas → tables → fields. |
+| `collection_write` | `agent:content:write` | Create, rename, move, archive, or restore a collection — the folders that hold questions, dashboards, models, and documents. |
+| `dashboard_write` | `agent:content:write` | Create or update a dashboard and edit its layout with ordered ops. |
+| `document_write` | `agent:content:write` | Create or update a document. |
+| `duplicate_content` | `agent:content:write` | Copy a question, dashboard, or document into a collection — cheaper and safer than reading the original and re-creating it, and it preserves everything the read projections leave out. |
+| `execute_query` | `agent:query:run` | Validate and execute a query, returning rows plus a query_handle. |
+| `execute_sql` | `agent:sql:run` | Execute a raw SQL string against a database, returning rows plus a query_handle. |
+| `get_content` | `agent:content:read` | Fetch content by {type, id} — the typed read for anything found via search or browse_collection. |
+| `get_parameter_values` | `agent:content:read` | Fetch the valid values for one filter on a dashboard or saved question, so you filter with real values instead of guessing. |
+| `learn` | `agent:content:read` | Read this server's task docs (skills) for the write dialects the schemas can't fully describe. |
+| `measure_write` | `agent:content:write` | Create or update a measure: a named, reusable MBQL aggregation attached to one table, referenced inside another query's aggregation as ["measure", id]. |
+| `metric_write` | `agent:content:write` | Create or update a metric: a saved, reusable aggregation that lives in a collection and can be queried on its own or referenced from other queries. |
+| `question_write` | `agent:content:write` | Create, update, or archive a saved question or model. |
+| `refresh_ui_credential` | `agent:query:run` | Refresh the scoped credential used by a Metabase MCP App. |
+| `render_drill_through` | `agent:query:run` | Render the drill-through visualization the user just navigated into. |
+| `run_saved_question` | `agent:query:run` | Run a saved question (card) by numeric id or entity_id, returning rows inline. |
+| `search` | `agent:content:read` | Find content across the Metabase instance by relevance. |
+| `segment_write` | `agent:content:write` | Create or update a segment: a named, reusable MBQL filter attached to one table, referenced from other queries' filters. |
+| `subscription_write` | `agent:delivery:write` | Create or update a dashboard subscription — scheduled delivery of a whole dashboard, e.g. |
+| `transform_write` | `agent:content:write` | Create or update a transform: a saved query that Metabase runs to materialize its results into a real table in your warehouse, which questions and other transforms can then query. |
+| `visualize_query` | `agent:query:run` | Visualize a query as an interactive chart or table, rendered inline in the conversation. |
Query results are limited to 200 rows per request. When more rows are available, the response includes a
`continuation_token` that can be passed back to fetch the next page.
-`read_resource` list responses cap at 25 items with `truncated` / `total` signals; drill into specific URIs to see
-more, or refine via `search`.
-
## Resources
The server exposes MCP [resources](https://modelcontextprotocol.io/specification/2025-03-26/server/resources) so
clients can fetch supplementary content by URI without inflating tool descriptions.
-| Resource URI | Description |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `metabase://docs/construct-query.md` | Program syntax for `construct_query` and `query`: sources, operations, operator forms, worked examples, pitfalls. |
+| Resource URI | Description |
+| ------------ | ----------- |
+| `ui://metabase/visualize-query.html` | The MCP Apps iframe shell `visualize_query` points a capable client at. |
+| `ui://metabase/render-drill-through.html` | The shell `render_drill_through` points at. |
+
+Skill packs are delivered through the `learn` tool rather than as resources.
-The `read_resource` **tool** (above) uses a separate URI scheme to navigate Metabase entities (`metabase://question/{id}`,
-`metabase://database/{id}/tables`, etc.). The two URI namespaces are independent: `metabase://docs/...` is for static
-reference content fetched via MCP `resources/read`, while `metabase://table/...` and friends are entity URIs passed
-to the `read_resource` tool.
+Entity navigation is done with the `get_content` and `browse_*` tools rather than a URI scheme; the `ui://`
+resources above exist only so a client that can render an iframe has something to mount.
## Supported JSON-RPC methods
@@ -153,16 +139,15 @@ Requests can be sent individually or as a JSON-RPC batch. The server responds wi
The implementation lives in these files:
-- **[`api.clj`](api.clj)** - The HTTP handler. Parses JSON-RPC requests, validates authentication and session headers,
- enforces origin checks (DNS rebinding protection), and dispatches to the appropriate method. Supports both JSON and
- SSE response formats.
+- **[`transport.clj`](transport.clj)** - The HTTP transport. Parses JSON-RPC requests, validates authentication and
+ session headers, enforces origin checks (DNS rebinding protection), and dispatches to the appropriate method.
+ Supports both JSON and SSE response formats.
-- **[`tools.clj`](tools.clj)** - Tool dispatch and manifest generation. Builds the tool list from Agent API endpoint
- metadata, checks scopes, and routes tool calls through synthetic Agent API requests.
+- **[`v2/api.clj`](v2/api.clj)** - The tool surface handler. Wires the transport to the v2 tool + resource registries
+ and defines method dispatch (`tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`).
-- **[`resources.clj`](resources.clj)** - MCP resource registry and handlers. Holds documentation resources (like
- the `construct_query` reference) keyed by URI, with scope-based access control on `resources/list` and
- `resources/read`.
+- **[`v2/registry.clj`](v2/registry.clj)** - The v2 tool registry. Tools self-register via `deftool`; the registry
+ checks scopes, validates arguments, dispatches calls, and records usage.
- **[`scope.clj`](scope.clj)** - Scope matching logic. Supports exact matches, wildcard patterns, and the
`::unrestricted` sentinel for session-based auth.
diff --git a/src/metabase/mcp/api.clj b/src/metabase/mcp/api.clj
deleted file mode 100644
index e7cf54b2ad5..00000000000
--- a/src/metabase/mcp/api.clj
+++ /dev/null
@@ -1,479 +0,0 @@
-(ns metabase.mcp.api
- "MCP (Model Context Protocol) Streamable HTTP transport handler.
- Exposes Metabase's agent tools via JSON-RPC 2.0 over each of the MCP endpoints."
- (:require
- [clojure.core.async :as a]
- [clojure.string :as str]
- [clojure.walk :as walk]
- [compojure.response :as compojure.response]
- [metabase.ai-tracing.core :as ait]
- [metabase.api.common :as api]
- [metabase.api.macros.scope :as scope]
- [metabase.api.open-api :as open-api]
- [metabase.mcp.core :as mcp]
- [metabase.mcp.resources :as mcp.resources]
- [metabase.mcp.session :as mcp.session]
- [metabase.mcp.tools :as mcp.tools]
- [metabase.mcp.usage :as mcp.usage]
- [metabase.mcp.validation :as mcp.validation]
- [metabase.oauth-server.core :as oauth-server]
- [metabase.request.core :as request]
- [metabase.server.middleware.security :as mw.security]
- [metabase.server.streaming-response :as streaming-response]
- [metabase.system.core :as system]
- [metabase.util :as u]
- [metabase.util.json :as json]
- [metabase.util.log :as log]
- [throttle.core :as throttle])
- (:import
- (java.io BufferedWriter OutputStreamWriter)
- (java.nio.charset StandardCharsets)))
-
-(set! *warn-on-reflection* true)
-
-;;; -------------------------------------------------- Auth --------------------------------------------------------
-
-(defn- validate-bearer-token
- "Look up and validate an OAuth bearer token. Returns `{:user-id <int> :scopes <set>}` on success, nil on failure.
- Delegates to the shared resolver so MCP and the core session middleware agree on token validity and scopes."
- [token-string]
- (oauth-server/resolve-access-token token-string))
-
-;;; ------------------------------------------------- JSON-RPC 2.0 --------------------------------------------------
-
-(def ^:private server-info
- {:name "metabase"
- :version "0.1.0"})
-
-(def ^:private protocol-version "2025-03-26")
-
-(defn- jsonrpc-response [id result]
- {:jsonrpc "2.0" :id id :result result})
-
-(defn- jsonrpc-error [id code message]
- {:jsonrpc "2.0" :id id :error {:code code :message message}})
-
-(defn- handle-initialize [id params]
- (when-let [client-info (:clientInfo params)]
- (log/infof "MCP client connected: %s %s" (:name client-info) (:version client-info)))
- (jsonrpc-response
- id
- {:protocolVersion protocol-version
- :capabilities {:tools {:listChanged true} :resources {}}
- :serverInfo server-info}))
-
-(defn- mcp-app-ui-capability?
- "Return true if initialize params advertise support for MCP Apps HTML resources."
- [params]
- ;; `json/decode+kw` preserves the slash in the JSON extension key `"io.modelcontextprotocol/ui"` as the
- ;; namespaced keyword `:io.modelcontextprotocol/ui`.
- (contains?
- (set (get-in params [:capabilities :extensions :io.modelcontextprotocol/ui :mimeTypes]))
- "text/html;profile=mcp-app"))
-
-(defn- handle-tools-list [id _params session-id token-scopes]
- (let [supports-mcp-ui? (mcp.session/supports-mcp-ui? session-id)]
- (jsonrpc-response id {:tools (mcp.tools/list-tools token-scopes {:supports-mcp-ui?
- supports-mcp-ui?})})))
-
-(defn- handle-tools-call [id params session-id token-scopes request-context]
- (let [tool-name (:name params)
- arguments (or (:arguments params) {})
- ;; RC clients carry their identity per-call in `_meta`; the recorder falls back to the
- ;; session's stored identity when it's absent. (`json/decode+kw` preserves the slash in
- ;; the extension key, so it's the namespaced keyword `:io.modelcontextprotocol/clientInfo`.)
- client-info (get-in params [:_meta :io.modelcontextprotocol/clientInfo])
- supports-mcp-ui? (mcp.session/supports-mcp-ui? session-id)]
- (jsonrpc-response id (mcp.tools/call-tool token-scopes
- session-id
- tool-name
- arguments
- {:supports-mcp-ui? supports-mcp-ui?
- :client-info client-info
- :request-context request-context}))))
-
-(defn- handle-resources-list [id _params token-scopes]
- (jsonrpc-response id (mcp.resources/list-resources token-scopes)))
-
-(defn- handle-resources-read [id params token-scopes]
- (let [uri (:uri params)]
- (if (or (not (string? uri)) (str/blank? uri))
- (jsonrpc-error id -32602 "Missing required parameter: uri")
- (let [result (mcp.resources/read-resource uri token-scopes {})]
- (case (:status result)
- (:not-found :scope-denied) (jsonrpc-error id -32602 "Resource not found")
- :ok (jsonrpc-response id {:contents (:contents result)}))))))
-
-(defn- handle-ping [id _params]
- (jsonrpc-response id {}))
-
-(defn- eval-session-override
- "An eval-session id the harness supplies via the `x-eval-session-id` header so it can name (and
- later fetch) the trace itself — the MCP analogue of metabot's `eval_session_id`. opencode negotiates
- the `Mcp-Session-Id` internally, so without this the harness can't know which `<uuid>.jsonl` to read.
-
- Validates through `ait/checked-session-id` — the mint-time boundary, and the single source of truth
- for the safe-id contract — and maps its throw on an unsafe/over-long id to nil, so a bad header falls
- back to the Mcp-Session-Id correlator rather than 500ing ahead of `dispatch-request`'s try/catch. The
- `when-let` guards the absent-header case, so we never reach `checked-session-id`'s nil -> fresh-uuid
- branch (which would invent a trace file the harness never named)."
- [request]
- (when-let [id (get-in request [:headers "x-eval-session-id"])]
- (try (ait/checked-session-id id) (catch Exception _ nil))))
-
-(defn- dispatch-method
- "Route a single JSON-RPC `method` to its handler, returning a response map or nil (notifications).
- A handler that throws is turned into a JSON-RPC internal error rather than propagating."
- [id method params session-id token-scopes request-context]
- (try
- (case method
- "notifications/initialized" nil
- "tools/list" (handle-tools-list id params session-id token-scopes)
- "tools/call" (handle-tools-call id params session-id token-scopes request-context)
- "resources/list" (handle-resources-list id params token-scopes)
- "resources/read" (handle-resources-read id params token-scopes)
- "ping" (handle-ping id params)
- (if id
- (jsonrpc-error id -32601 (str "Method not found: " method))
- nil))
- (catch Throwable e
- (log/error "Error dispatching JSON-RPC method" method (ex-message e))
- (jsonrpc-error id -32603 (or (ex-message e) "Internal error")))))
-
-(defn- dispatch-request
- "Dispatch a single JSON-RPC request. Returns a response map or nil for notifications."
- [{:keys [id method params] :as _msg} session-id token-scopes request-context eval-session-id]
- ;; Eval tracing (inert unless MB_AI_EVAL_CAPTURE): establish a session and open a per-request root
- ;; span; tool/resource/agent-api spans nest under it automatically. Key on the harness-supplied
- ;; `eval-session-id` when given (so it owns the trace file name), else the MCP session's UUID
- ;; correlator so an entire conversation's requests append to one `<uuid>.jsonl`. We key on the UUID
- ;; prefix (not the full `<uuid>.<base64>` id): it's stable across the conversation AND always
- ;; filesystem/URL-safe, whereas the full id can carry a base64 payload that `require-valid-session`
- ;; accepts but `safe-session-id-re` rejects (e.g. `=` padding) — passing that to `with-eval-session`
- ;; would throw out here, ahead of the try/catch.
- ;;
- ;; When BOTH are absent (a stateless / pre-initialize request with no header), this is nil and
- ;; `with-eval-session` mints a fresh uuid — so such requests get their own `<uuid>.jsonl` rather than
- ;; grouping. That's fine for the eval flow, which always supplies `eval-session-id`; the ungrouped
- ;; files are reaped by the appender's IdlePurgePolicy.
- (ait/with-eval-session (or eval-session-id (some-> session-id (str/split #"\.") first))
- (ait/eval-span (str "mcp." method) {:mcp/method method
- :mcp/request-id id
- :mcp/params params
- :mcp/user-id api/*current-user-id*
- :mcp/scopes token-scopes}
- (let [response (dispatch-method id method params session-id token-scopes request-context)]
- ;; record the materialized JSON-RPC result/error (the request's output)
- (when (ait/capture-active?)
- (ait/record! {:mcp/response
- (cond-> response
- (contains? response :result)
- (update :result mcp.resources/redact-ui-credential))}))
- response))))
-
-;;; ----------------------------------------------------- SSE ------------------------------------------------------
-
-(defn- accepts-sse?
- "Return true if the request's Accept header includes text/event-stream."
- [request]
- (some-> (get-in request [:headers "accept"])
- (str/includes? "text/event-stream")))
-
-(defn- sse-body
- "Format a sequence of JSON-RPC messages as SSE event text."
- [messages]
- (str/join (for [message messages]
- (str "event: message\ndata: " (json/encode message) "\n\n"))))
-
-;;; -------------------------------------------------- Responses ---------------------------------------------------
-
-(defn- json-response
- ([status body]
- (json-response status body nil))
- ([status body extra-headers]
- {:status status
- :headers (merge {"Content-Type" "application/json"} extra-headers)
- :body (json/encode body)}))
-
-(defn- sse-response
- "Return a plain Ring response with SSE-formatted body for POST requests."
- ([messages]
- (sse-response messages nil))
- ([messages extra-headers]
- {:status 200
- :headers (merge {"Content-Type" "text/event-stream"
- "Cache-Control" "no-cache"}
- extra-headers)
- :body (sse-body messages)}))
-
-;;; ------------------------------------------------- Validation --------------------------------------------------
-
-(defn- normalize-domain
- "Extract and lowercase the domain from a URL or Host-style header value.
- Bracketed IPv6 forms (`[::1]:3000`) and ports are handled correctly. Returns nil for unparsable input.
- Uses `try-parse-url` (the silent variant) — `Origin`/`Host` are client-controlled, so malformed inputs
- are expected and shouldn't spam the error logs."
- [url]
- (some-> url str mw.security/try-parse-url :domain u/lower-case-en))
-
-(defn- same-origin-host? [origin host]
- (let [origin-domain (normalize-domain origin)]
- (and (some? origin-domain) (= origin-domain (normalize-domain host)))))
-
-(defn- approved-mcp-origin? [origin]
- ;; Pre-lowercase both inputs so DNS hostname matching is case-insensitive (per RFC) and so mixed-case
- ;; schemes still match `try-parse-url`'s lowercase-only `https?|app|capacitor` regex.
- (boolean
- (or (mcp/sandbox-origin? origin)
- (when-let [approved-origins (not-empty (mcp/cors-origins))]
- (when-let [origin-url (mw.security/try-parse-url (u/lower-case-en origin))]
- (some (fn [approved-origin]
- (and (mw.security/approved-domain? (:domain origin-url) (:domain approved-origin))
- (mw.security/approved-protocol? (:protocol origin-url) (:protocol approved-origin))
- (mw.security/approved-port? (:port origin-url) (:port approved-origin))))
- (mw.security/parse-approved-origins (u/lower-case-en approved-origins))))))))
-
-(defn- validate-origin
- "Validate the Origin header to prevent DNS rebinding attacks (MCP spec requirement).
- Returns a 403 response if Origin is present and is neither same-host nor an explicitly configured
- MCP app origin. Non-browser clients that omit the Origin header are allowed through."
- [request]
- (when-let [origin (get-in request [:headers "origin"])]
- (let [host (get-in request [:headers "host"])]
- (when-not (or (same-origin-host? origin host)
- (approved-mcp-origin? origin))
- (json-response 403 (jsonrpc-error nil -32600 "Origin not allowed"))))))
-
-(defn- require-valid-session
- "Validate the Mcp-Session-Id header value. Checks UUID format and, when a
- `core_session` has been materialized, verifies it belongs to `user-id`."
- [user-id session-id]
- (cond
- (str/blank? session-id)
- {:error (json-response 400 (jsonrpc-error nil -32600 "Missing Mcp-Session-Id header"))}
-
- (not (mcp.session/valid-id? session-id))
- {:error (json-response 404 (jsonrpc-error nil -32600 "Invalid or expired session"))}
-
- (not (mcp.session/owned-by-user? session-id user-id))
- {:error (json-response 404 (jsonrpc-error nil -32600 "Invalid or expired session"))}
-
- :else
- {:session-id session-id}))
-
-;;; -------------------------------------------------- Handlers ---------------------------------------------------
-
-(defn- handle-post
- "Handle a POST request containing one or more JSON-RPC messages."
- [user-id request]
- (let [body (walk/keywordize-keys (:body request))
- session-id (get-in request [:headers "mcp-session-id"])
- eval-session-id (eval-session-override request)
- batch? (sequential? body)]
- (cond
- (nil? body)
- (json-response 400 (jsonrpc-error nil -32700 "Parse error: empty body"))
-
- (and (not (map? body)) (not batch?))
- (json-response 400 (jsonrpc-error nil -32600 "Invalid request: expected object or array"))
-
- ;; JSON-RPC 2.0: empty batch is invalid
- (and batch? (empty? body))
- (json-response 400 (jsonrpc-error nil -32600 "Invalid request: empty batch"))
-
- ;; MCP spec: "The initialize request MUST NOT be part of a JSON-RPC batch"
- (and batch? (some #(= "initialize" (:method %)) body))
- (json-response 400 (jsonrpc-error nil -32600 "initialize must not be batched"))
-
- ;; Initialize: create session and return response with session header
- (and (not batch?) (= "initialize" (:method body)))
- (let [params (:params body)
- supports-mcp-ui? (mcp-app-ui-capability? params)
- session-id (mcp.session/create! user-id {:supports-mcp-ui?
- supports-mcp-ui?})
- init-response (handle-initialize (:id body) params)]
- ;; Record the session row (EE-only, best-effort). Identity + PII are captured once
- ;; here, from the on-thread request, and never overwritten.
- (mcp.usage/record-mcp-session!
- {:session-id session-id
- :user-id user-id
- :tenant-id (some-> api/*current-user* deref :tenant_id)
- :client-info (:clientInfo params)
- :user-agent (get-in request [:headers "user-agent"])
- :ip-address (request/ip-address request)})
- (if (accepts-sse? request)
- (sse-response [init-response] {"Mcp-Session-Id" session-id})
- (json-response 200 init-response {"Mcp-Session-Id" session-id})))
-
- ;; All other requests require a valid session
- :else
- (let [{:keys [error]} (require-valid-session user-id session-id)]
- (if error
- error
- (let [messages (if batch? body [body])
- ;; Captured on-thread from the request so each tool-call row can denormalize IP/UA
- ;; (gated PII) alongside client identity — the view no longer joins the session.
- request-context {:user-agent (get-in request [:headers "user-agent"])
- :ip-address (request/ip-address request)}
- dispatch-msg (fn [msg]
- (dispatch-request msg session-id (:token-scopes request)
- request-context eval-session-id))
- responses (into [] (keep dispatch-msg) messages)]
- (cond
- (empty? responses)
- {:status 202 :headers {} :body ""}
-
- (accepts-sse? request)
- (sse-response responses)
-
- (and (not batch?) (= 1 (count responses)))
- (json-response 200 (first responses))
-
- :else
- (json-response 200 responses))))))))
-
-(def ^:private tools-list-changed-notification
- {:jsonrpc "2.0" :method "notifications/tools/list_changed"})
-
-(defn- handle-get
- "Handle a GET request for SSE stream (keepalive for server-initiated notifications).
- Polls the tool manifest hash on each keepalive tick — if the visible tool set has
- changed since the previous tick, emits an MCP `notifications/tools/list_changed`
- message so the client knows to refetch `tools/list`. Stateless: each connection
- tracks its own last-seen hash; no shared registry."
- [user-id request respond raise]
- (let [session-id (get-in request [:headers "mcp-session-id"])
- token-scopes (:token-scopes request)
- {:keys [error]} (require-valid-session user-id session-id)]
- (cond
- (some? error)
- (respond error)
-
- :else
- (let [resp (streaming-response/streaming-response
- {:content-type "text/event-stream"
- :headers {"Cache-Control" "no-cache"}
- :status 200}
- [os canceled-chan]
- (let [writer (BufferedWriter. (OutputStreamWriter. os StandardCharsets/UTF_8))]
- (loop [last-hash (mcp.tools/tools-hash token-scopes)]
- (when-not (a/poll! canceled-chan)
- (.write writer ": keepalive\n\n")
- (.flush writer)
- (Thread/sleep 30000)
- (let [current-hash (mcp.tools/tools-hash token-scopes)]
- (when (not= current-hash last-hash)
- (.write writer ^String (sse-body [tools-list-changed-notification]))
- (.flush writer))
- (recur current-hash))))))]
- (compojure.response/send* resp request respond raise)))))
-
-(defn- handle-delete
- "Handle a DELETE request to tear down a session."
- [user-id request]
- (let [session-id-header (get-in request [:headers "mcp-session-id"])
- {:keys [session-id error]} (require-valid-session user-id session-id-header)]
- (or error
- (do (mcp.session/delete! session-id user-id)
- ;; Stamp ended_at on the session row (EE-only, best-effort).
- (mcp.usage/record-mcp-session-end! session-id)
- {:status 200 :headers {"Content-Type" "application/json"} :body ""}))))
-
-;;; -------------------------------------------------- Throttling --------------------------------------------------
-
-;; MCP is auth-gated (session cookie or bearer token), so the risk is lower than the
-;; unauthenticated OAuth endpoints. The threshold is generous to accommodate users running
-;; multiple concurrent agents (e.g. 5 agents × 200 req/min). throttle/check counts every
-;; request (not just failures) which is correct here — we want to cap total throughput
-;; regardless of success to prevent resource exhaustion from a compromised token.
-(def ^:private one-minute-ms (* 60 1000))
-
-(def ^:private mcp-throttler
- (throttle/make-throttler :user-id :attempts-threshold 1000 :attempt-ttl-ms one-minute-ms))
-
-(defn- check-throttle
- "Returns a 429 JSON-RPC response if rate-limited, nil otherwise."
- [user-id]
- (try
- (throttle/check mcp-throttler user-id)
- nil
- (catch clojure.lang.ExceptionInfo e
- (let [message (ex-message e)
- retry-seconds (some->> message (re-find #"(\d+) seconds") second)]
- (cond-> (json-response 429 (jsonrpc-error nil -32000 message))
- retry-seconds (assoc-in [:headers "Retry-After"] retry-seconds))))))
-
-;;; ---------------------------------------------------- Handler ---------------------------------------------------
-
-;; Source of truth for the route aliases — keep in sync with the route-map in
-;; [[metabase.api-routes.routes]] and resource-metadata endpoints in [[metabase.oauth-server.api.metadata]].
-(def ^:private endpoint-paths
- "URL paths that serve the MCP endpoint, relative to site-url.
- `/api/metabase-mcp` is canonical (the advertised URL); `/api/mcp` is a legacy alias kept for
- back-compat with existing clients."
- #{"/api/metabase-mcp" "/api/mcp"})
-
-(defn- www-authenticate-discovery
- "Build the `WWW-Authenticate` header advertising OAuth discovery for the path the client hit.
- A client connecting via an alias is pointed at that same alias as the protected resource."
- [request]
- ;; Routing matches on the first path segment, so a trailing slash (e.g. `/api/metabase-mcp/`) still
- ;; reaches the handler — strip it so the alias is recognized rather than falling back to canonical.
- (let [uri (str/replace (:uri request) #"/+$" "")
- path (if (contains? endpoint-paths uri) uri "/api/metabase-mcp")]
- (str "Bearer realm=\"mcp\" resource_metadata=\"" (system/site-url) "/.well-known/oauth-protected-resource" path "\"")))
-
-(def +mcp-enabled
- "Wrap routes so they may only be accessed when the MCP server is enabled."
- mcp.validation/+mcp-enabled)
-
-(def ^{:arglists '([request respond raise])} handler
- "Ring async handler for the MCP endpoint.
- Uses JSON-RPC 2.0 over HTTP rather than REST, so the OpenAPI spec is empty."
- (open-api/handler-with-open-api-spec
- (fn [request respond raise]
- (let [origin-error (validate-origin request)
- bearer-token (oauth-server/extract-bearer-token request)
- session-auth api/*current-user-id*
- token-scopes (:token-scopes request)]
- (letfn [(dispatch [user-id token-scopes]
- (request/with-current-user user-id
- (if-let [throttle-err (check-throttle user-id)]
- (respond throttle-err)
- (try
- (let [request (assoc request :token-scopes token-scopes)]
- (cond
- (= :post (:request-method request))
- (respond (handle-post user-id request))
-
- (= :get (:request-method request))
- (handle-get user-id request respond raise)
-
- (= :delete (:request-method request))
- (respond (handle-delete user-id request))
-
- :else
- (respond (json-response 405 (jsonrpc-error nil -32600 "Method not allowed")))))
- (catch Throwable e
- (raise e))))))]
- (cond
- (some? origin-error)
- (respond origin-error)
-
- ;; Respect the scope set attached to an authenticated request. Sessions without one
- ;; retain unrestricted access.
- session-auth
- (dispatch session-auth (or token-scopes #{::scope/unrestricted}))
-
- ;; Bearer token auth — validate and extract scopes
- bearer-token
- (if-let [{:keys [user-id scopes]} (validate-bearer-token bearer-token)]
- (dispatch user-id scopes)
- (respond (json-response 401 (jsonrpc-error nil -32603 "Invalid bearer token")
- {"WWW-Authenticate" "Bearer error=\"invalid_token\""})))
-
- ;; No auth at all — return 401 with discovery
- :else
- (respond (json-response 401 (jsonrpc-error nil -32603 "Authentication required")
- {"WWW-Authenticate" (www-authenticate-discovery request)}))))))
- (constantly nil)))
diff --git a/src/metabase/mcp/callback_api.clj b/src/metabase/mcp/callback_api.clj
index e196234a02b..158c1073ccd 100644
--- a/src/metabase/mcp/callback_api.clj
+++ b/src/metabase/mcp/callback_api.clj
@@ -1,9 +1,13 @@
(ns metabase.mcp.callback-api
- "Iframe-callback endpoints for the embedded MCP UI. The MCP iframe POSTs here to
- stash query payloads server-side so the agent never has to carry them in the
- model context — it just receives a handle UUID it can pass to the corresponding
- MCP tool. Mounted as a sibling of `/api/metabase-mcp` so the JSON-RPC handler doesn't
- have to special-case non-protocol routes."
+ "Server-side endpoints for the embedded MCP UI, mounted at `/api/embed-mcp`. Two kinds of route live here:
+
+ - Iframe callbacks: the iframe POSTs query payloads here to stash them server-side so the agent never has to
+ carry them in the model context — it just receives a handle UUID it can pass to the corresponding MCP tool.
+ - Bootstrap: the projection of the user and settings the iframe needs to mount, so the UI credential never has
+ to authenticate the general `/api/user/current` and `/api/session/properties` endpoints.
+
+ Mounted as a sibling of `/api/metabase-mcp` so the JSON-RPC handler doesn't have to special-case non-protocol
+ routes."
(:require
[clojure.string :as str]
[metabase.api.common :as api]
@@ -12,8 +16,12 @@
[metabase.mcp.session :as mcp.session]
[metabase.mcp.validation :as mcp.validation]
[metabase.metabot.config :as metabot.config]
+ [metabase.permissions.core :as perms]
+ [metabase.settings.core :as setting]
[metabase.util.i18n :refer [tru]]
- [metabase.util.malli.schema :as ms]))
+ [metabase.util.malli.registry :as mr]
+ [metabase.util.malli.schema :as ms]
+ [toucan2.core :as t2]))
(defn- mcp-session-id-from-headers
[request]
@@ -35,6 +43,63 @@
(api/check (= credential-session-id session-id)
[404 (tru "Invalid or expired session")])))
+;;; ------------------------------------------------- Bootstrap --------------------------------------------------
+
+(def ^:private bootstrap-setting-visibilities
+ "Setting visibilities the iframe may read: exactly what a non-admin authenticated user sees, even when the
+ credential holder is an admin. The iframe renders one visualization and needs no admin-only setting, and a
+ credential minted from a narrow MCP scope must not widen into instance configuration."
+ #{:public :authenticated :admin-write-authed-read})
+
+(mr/def ::bootstrap-user
+ "The projection of the current user the MCP iframe may read. Closed on purpose: a field belongs here only when
+ something the iframe renders reads it, so widening the projection is a decision someone has to make in this file
+ rather than a side effect of the shared `GET /api/user/current` response growing.
+
+ Deliberately absent: `email`, `login_attributes`, `jwt_attributes`, `attributes`, `sso_source`, `group_ids` and
+ the advanced-permissions flags. Nothing in the visualization reads them, and they are what made the general
+ endpoint a scope-escalation target. The name fields are absent for the same reason: the iframe displays no
+ user, and `common_name` falls back to the email address when a user has neither first nor last name."
+ [:map {:closed true}
+ [:id ms/PositiveInt]
+ [:locale [:maybe :string]]
+ [:is_superuser :boolean]
+ [:is_data_analyst :boolean]
+ [:is_qbnewb :boolean]
+ ;; the holder's own tenant; `getIsTenantUser` on the client branches on it
+ [:tenant_id [:maybe ms/PositiveInt]]
+ [:personal_collection_id [:maybe ms/PositiveInt]]
+ [:permissions [:map {:closed true}
+ [:can_create_queries :boolean]
+ [:can_create_native_queries :boolean]]]])
+
+(defn- bootstrap-user
+ "The [[::bootstrap-user]] projection of the current user."
+ []
+ (let [user (api/check-404 @api/*current-user*)
+ {:keys [can-create-queries can-create-native-queries]}
+ (perms/query-creation-capabilities (:id user))]
+ (-> user
+ (t2/hydrate :personal_collection_id)
+ (select-keys [:id :locale :is_superuser :is_data_analyst :is_qbnewb
+ :tenant_id :personal_collection_id])
+ (assoc :permissions {:can_create_queries can-create-queries
+ :can_create_native_queries can-create-native-queries}))))
+
+(api.macros/defendpoint :get "/bootstrap" :- [:map {:closed true}
+ [:user ::bootstrap-user]
+ [:settings [:map-of :keyword :any]]]
+ "Everything the MCP Apps iframe needs to mount, so its UI credential never authenticates a general REST endpoint.
+ Replaces the iframe's calls to `GET /api/user/current` and `GET /api/session/properties`."
+ [_route-params
+ _query-params
+ _body
+ request]
+ (let [session-id (mcp-session-id-from-headers request)]
+ (check-session-header! session-id api/*current-user-id* request)
+ {:user (bootstrap-user)
+ :settings (setting/user-readable-values-map bootstrap-setting-visibilities)}))
+
(def ^:private feedback-text-max-length
10000)
@@ -64,6 +129,26 @@
(check-session-header! session-id api/*current-user-id* request)
{:handle (mcp.session/store-handle! session-id api/*current-user-id* encodedQuery)}))
+(api.macros/defendpoint :get "/queries/:handle" :- [:map
+ [:query ms/NonBlankString]
+ [:prompt [:maybe :string]]]
+ "Resolve a query handle to the base64-encoded MBQL the iframe should render.
+
+ This is how the v2 MCP Apps tools keep result data out of the model context: `visualize_query`
+ and `render_drill_through` return only a handle, and the iframe exchanges it here using the
+ scoped UI credential it was rendered with. The lookup is user-scoped (see
+ [[metabase.mcp.session/find-handle-row]]) and the credential is accepted only on the MCP UI
+ request surface, so a handle on its own is not a bearer credential."
+ [{:keys [handle]} :- [:map {:closed true} [:handle ms/UUIDString]]
+ _query-params
+ _body
+ request]
+ (let [session-id (mcp-session-id-from-headers request)]
+ (check-session-header! session-id api/*current-user-id* request)
+ (api/let-404 [{:keys [encoded_query prompt]}
+ (mcp.session/resolve-query-handle session-id api/*current-user-id* handle)]
+ {:query encoded_query :prompt prompt})))
+
(api.macros/defendpoint :post "/feedback" :- [:map
[:status [:= 204]]
[:body :nil]]
diff --git a/src/metabase/mcp/core.clj b/src/metabase/mcp/core.clj
index f73c1d1b368..ba060bddedd 100644
--- a/src/metabase/mcp/core.clj
+++ b/src/metabase/mcp/core.clj
@@ -4,12 +4,24 @@
(:require
[clojure.string :as str]
[metabase.api.macros :as api.macros]
- [metabase.mcp.resources :as mcp.resources]
+ [metabase.mcp.paths :as mcp.paths]
[metabase.mcp.session :as mcp.session]
- [metabase.mcp.settings :as mcp.settings]))
+ [metabase.mcp.settings :as mcp.settings]
+ [metabase.mcp.ui-surface :as mcp.ui-surface]))
(set! *warn-on-reflection* true)
+(defn mcp-canonical-path
+ "The advertised MCP URL path, relative to site-url (see [[metabase.mcp.paths/canonical-path]])."
+ []
+ mcp.paths/canonical-path)
+
+(defn mcp-endpoint-paths
+ "Every path serving MCP, canonical plus back-compat aliases
+ (see [[metabase.mcp.paths/endpoint-paths]])."
+ []
+ mcp.paths/endpoint-paths)
+
(defn cors-origins
"Returns space-separated CORS origins from both common and custom MCP client settings."
[]
@@ -25,6 +37,16 @@
[credential]
(mcp.session/resolve-ui-credential credential))
+(defn ui-credential-on-surface?
+ "Whether an MCP Apps UI credential may authenticate `method` + `uri` at all."
+ [method uri]
+ (mcp.ui-surface/on-surface? method uri))
+
+(defn ui-credential-scope-satisfied?
+ "Whether a UI credential with `claims` holds what `method` + `uri` costs."
+ [method uri claims]
+ (mcp.ui-surface/scope-satisfied? method uri claims))
+
(defn vscode-webview-enabled?
"Returns true if vscode/cursor is enabled in common MCP apps."
[]
@@ -40,10 +62,38 @@
false)))
(defn all-scopes
- "All supported OAuth scopes: those declared on agent-api endpoints via
- defendpoint metadata, plus scopes from MCP UI resources (e.g. visualize_query)."
+ "All supported OAuth scopes: those declared on agent-api endpoints via defendpoint metadata, the
+ scopes v2 tools gate on (registry), and the scopes v2 UI resources gate on (e.g. visualize_query).
+
+ DCR snapshots this set into a client's registered scopes when the client registers without naming any, and
+ the OAuth server's `validate-scope` then checks a requested scope against that per-client snapshot. So a
+ scope the v2 401 challenge asks for must be here, or a freshly registered client that follows the challenge
+ is answered \"Invalid scope\" instead of having its grant narrowed. A client registered before a scope was
+ added keeps its older snapshot until it re-registers."
+ []
+ (-> (sorted-set)
+ ;; agent-api scopes from defendpoint metadata
+ (into (comp (keep #(get-in % [:form :metadata :scope]))
+ (filter string?))
+ (vals (api.macros/ns-routes 'metabase.agent-api.api)))
+ ;; The v2 surface's scopes, read from the require-free leaf rather than from the registry. Deriving them
+ ;; from `v2.registry/registered-scopes` would report only the tools whose namespaces happen to be loaded,
+ ;; and reaching `v2.resources` from here puts `metabot.scope` (and `premium-features`) on the security
+ ;; middleware's load path — the cycle `metabase.mcp.paths`' docstring exists to prevent. The literal set
+ ;; already covers every scope the v2 tools and resources gate on, and
+ ;; `v2-surface-scopes-match-metabot-scope-test` keeps it in step.
+ (into mcp.paths/v2-surface-scopes)))
+
+(defn v2-scopes
+ "The scopes the v2 MCP surface itself gates on. Excludes the agent-API endpoint scopes
+ [[all-scopes]] also gathers — those belong to a different resource, and advertising them for v2 is
+ what puts per-entity scopes the v2 tools don't use on a v2 client's consent screen.
+
+ Read from the require-free literal in [[metabase.mcp.paths/v2-surface-scopes]] rather than from the
+ registries: `metabase.server.middleware.security` requires this namespace, so reaching
+ `mcp.v2.resources` from here would put `metabot.scope` (and `premium-features`) on the security
+ middleware's load path — the cycle `mcp.paths` exists to prevent. Deriving from the registry is also
+ load-order dependent, reporting only the tools whose namespaces happen to be loaded.
+ `v2-surface-scopes-match-metabot-scope-test` keeps the literal in step with what the tools gate on."
[]
- (into (mcp.resources/resource-scopes)
- (comp (keep #(get-in % [:form :metadata :scope]))
- (filter string?))
- (vals (api.macros/ns-routes 'metabase.agent-api.api))))
+ mcp.paths/v2-surface-scopes)
diff --git a/src/metabase/mcp/db.clj b/src/metabase/mcp/db.clj
index 3b33c0e4064..013ba17e3ea 100644
--- a/src/metabase/mcp/db.clj
+++ b/src/metabase/mcp/db.clj
@@ -1,6 +1,10 @@
(ns metabase.mcp.db
"Application database queries for the MCP module. Every function here is a direct Toucan 2 call with no
- additional logic, so no other namespace in the module runs a query itself (model definitions still use `toucan2.core`)."
+ additional logic, so no other namespace in the module runs a query itself (model definitions still use `toucan2.core`).
+
+ The one thing that does belong alongside a query is a guard on a value the query splices rather than binds
+ — see [[user-id->tenant-id]]. It lives here because here is the only place that knows the value reaches
+ HoneySQL."
(:require
[metabase.app-db.core :as app-db]
[metabase.lib.schema.id :as lib.schema.id]
@@ -10,15 +14,137 @@
[metabase.util.malli.schema :as ms]
[toucan2.core :as t2]))
+(defn select-one-by-id
+ "The `model` row with primary key `id`, or nil. `id` must already be an integer - ids arriving from an agent
+ are resolved to one before they reach here, so a string entity_id is a bug rather than a lookup."
+ [model id]
+ {:pre [(integer? id)]}
+ (t2/select-one model :id id))
+
+(defn select-by-ids
+ "The `model` rows whose primary keys are in `ids`. `ids` is expected non-empty — an empty `:in` is a SQL
+ error rather than an empty result, so callers guard it."
+ [model ids]
+ (t2/select model :id [:in ids]))
+
+(defn select-users-where
+ "The `:model/User` rows matching the HoneySQL `where` clause.
+
+ Takes an assembled clause rather than the values behind it: the clause encodes which users the caller is
+ allowed to resolve at all, which is a permission decision and belongs with the permission check."
+ [where]
+ (t2/select :model/User {:where where}))
+
+(defn table-by-id
+ "The Table with `table-id`, or nil. Unlike [[select-one-by-id]], a nil `table-id` is answered with nil
+ rather than refused — callers reach here with a column value, not with an id an agent supplied."
+ [table-id]
+ (t2/select-one :model/Table :id table-id))
+
+(defn field-types
+ "The `base_type` and `effective_type` of the Field with `field-id`, or nil."
+ [field-id]
+ (t2/select-one [:model/Field :base_type :effective_type] :id field-id))
+
+(defn nullable-fields-with-fingerprints
+ "The Fields among `field-ids` the warehouse declares nullable, carrying their `:fingerprint`.
+ `field-ids` is expected non-empty — an empty `:in` is a SQL error rather than an empty result,
+ so callers guard it."
+ [field-ids]
+ (t2/select [:model/Field :id :database_is_nullable :fingerprint]
+ :id [:in field-ids]
+ :database_is_nullable true))
+
+(defn active-user-exists?
+ "Whether an active User with `user-id` exists."
+ [user-id]
+ (t2/exists? :model/User :id user-id :is_active true))
+
+(defn dashboard-parameters
+ "The `parameters` of the Dashboard with `dashboard-id`, or nil."
+ [dashboard-id]
+ (t2/select-one-fn :parameters :model/Dashboard :id dashboard-id))
+
+(defn browsable-database
+ "The Database with `database-id` restricted by the HoneySQL `browsable-where` clause, or nil.
+
+ Takes an assembled clause rather than the values behind it, for the same reason
+ as [[select-users-where]]: which databases an agent may reach at all is a permission decision and
+ belongs with the permission check."
+ [database-id browsable-where]
+ (t2/select-one :model/Database :id database-id {:where browsable-where}))
+
+(defn browsable-databases
+ "The `columns` of the Databases matching the HoneySQL `browsable-where` clause, in name order. Naming the
+ columns keeps the `details`/`settings` blobs from being decrypted on every row."
+ [columns browsable-where]
+ (t2/select (into [:model/Database] columns)
+ {:where browsable-where
+ :order-by [[:%lower.name :asc]]}))
+
+(defn browsable-database-ids
+ "The subset of `database-ids` matching the HoneySQL `browsable-where` clause, as a set. `database-ids` is
+ expected non-empty — an empty `:in` is a SQL error rather than an empty result, so callers guard it."
+ [database-ids browsable-where]
+ (t2/select-pks-set :model/Database {:where [:and [:in :id database-ids] browsable-where]}))
+
+(defn unarchived-models-in-database
+ "The `columns` of the unarchived Models of the Database with `database-id`, in name order."
+ [columns database-id]
+ (t2/select columns :type :model :database_id database-id :archived false {:order-by [[:%lower.name :asc]]}))
+
+(defn active-tables-by-ids
+ "The active Tables with `table-ids`. `table-ids` is expected non-empty — an empty `:in` is a SQL error
+ rather than an empty result, so callers guard it."
+ [table-ids]
+ (t2/select :model/Table :id [:in table-ids] :active true))
+
+(defn active-visible-fields-for-tables
+ "The id, name, table id, and position of the active, non-hidden Fields of the Tables with `table-ids`, in
+ table position then id order. `table-ids` is expected non-empty — an empty `:in` is a SQL error rather than
+ an empty result, so callers guard it."
+ [table-ids]
+ (t2/select [:model/Field :id :name :table_id :position]
+ :table_id [:in table-ids]
+ :active true
+ :visibility_type [:not-in ["hidden" "sensitive" "retired"]]
+ {:order-by [[:position :asc] [:id :asc]]}))
+
+(defn collections-for-read-check
+ "The Collections with `ids`, carrying the columns [[metabase.models.interface/can-read?]] consults.
+ `:namespace` and `:type` are selected for that check, not for display."
+ [ids]
+ (t2/select [:model/Collection :id :name :namespace :type] :id [:in ids]))
+
+(defn collection-id->name+location
+ "Map of collection id -> `[name location]` for the Collections with `ids`."
+ [ids]
+ (t2/select-fn->fn :id (juxt :name :location)
+ [:model/Collection :id :name :location]
+ :id [:in ids]))
+
+(defn snippets-by-archived-state
+ "The NativeQuerySnippets in the given archived state, ordered by lower-cased name. Selects only the
+ returned columns plus `:collection_id`, which the caller's read check consults — never `:content`,
+ which holds the SQL body."
+ [archived?]
+ (t2/select [:model/NativeQuerySnippet :id :name :description :collection_id]
+ :archived (boolean archived?)
+ {:order-by [[:%lower.name :asc]]}))
+
(mu/defn insert-feedback!
"Insert the McpFeedback `row`, returning the number inserted."
[row :- ::mcp.schema/mcp-feedback.update]
(t2/insert! :model/McpFeedback row))
-(mu/defn session-user-id
- "The id of the User owning the `core_session` with `key-hashed`, or nil."
- [key-hashed :- :string]
- (t2/select-one-fn :user_id :core_session :key_hashed key-hashed))
+(defn session-user-ids
+ "The ids of every User owning a `core_session` with `key-hashed`.
+
+ A set rather than a single id: `key-hashed` derives from the client-supplied `Mcp-Session-Id`, so two users
+ can each materialize their own row under one id. Reading a single owner picks one of them arbitrarily and
+ locks the rest out of a session they already hold — see `metabase.mcp.session/owned-by-user?`."
+ [key-hashed]
+ (t2/select-fn-set :user_id :core_session :key_hashed key-hashed))
(mu/defn get-or-create-core-session!
"The `core_session` row for `key-hashed` and `user-id`, creating one with a freshly generated session id if none
@@ -53,6 +179,11 @@
[:= :mqh.id handle-id]
[:= :cs.user_id user-id]]}))
+(defn delete-query-handles-created-before!
+ "Delete every McpQueryHandle created before `cutoff`, returning the number deleted."
+ [cutoff]
+ (t2/delete! :model/McpQueryHandle {:where [:< :created_at cutoff]}))
+
(mu/defn delete-session-for-user!
"Delete the `core_session` with `key-hashed` if it belongs to the User with `user-id`."
[key-hashed :- :string
@@ -62,7 +193,80 @@
[:= :key_hashed key-hashed]
[:= :user_id user-id]]}))
-(mu/defn delete-query-handles-for-mcp-session!
- "Delete the McpQueryHandles of the MCP session `mcp-session-id`, returning the number deleted."
- [mcp-session-id :- :string]
- (t2/delete! :model/McpQueryHandle :mcp_session_id mcp-session-id))
+(defn delete-query-handles-for-user-session!
+ "Delete the McpQueryHandles of MCP session `mcp-session-id` that belong to the User with `user-id`, plus any
+ carrying no `core_session_id` at all. See `metabase.mcp.session/delete!` for why the scoping is needed.
+
+ The subquery is deliberate: resolving those session ids in a separate round trip leaves a window where a
+ concurrent teardown drops the session between the two statements."
+ [mcp-session-id key-hashed user-id]
+ (t2/query {:delete-from :mcp_query_handle
+ :where [:and
+ [:= :mcp_session_id mcp-session-id]
+ [:or
+ [:= :core_session_id nil]
+ [:in :core_session_id ^:allow-subquery {:select [:id]
+ :from [:core_session]
+ :where [:and
+ [:= :key_hashed key-hashed]
+ [:= :user_id user-id]]}]]]}))
+
+(defn hydrate-moderation-reviews
+ "`card` with `:moderation_reviews` hydrated, each review carrying its `:moderator_details`."
+ [card]
+ (t2/hydrate card [:moderation_reviews :moderator_details]))
+
+(defn notification-by-payload-type
+ "The Notification with `id` whose `payload_type` is `payload-type`, or nil."
+ [id payload-type]
+ (t2/select-one :model/Notification :id id :payload_type payload-type))
+
+(defn subscription-pulse-exists?
+ "Whether a Pulse with `pulse-id` exists and is a subscription — a nil `alert_condition` — rather than an alert."
+ [pulse-id]
+ (t2/exists? :model/Pulse :id pulse-id :alert_condition nil))
+
+(defn hydrate-notification
+ "`notification` with its payload, subscriptions, and handler channels and recipients hydrated.
+
+ Spelled out here rather than delegated to `metabase.notification.models/hydrate-notification`, whose
+ output schema rejects `payload_type: notification/dashboard` rows — readable on the MCP read path by
+ design."
+ [notification]
+ (t2/hydrate notification
+ :payload
+ :subscriptions
+ [:handlers :channel [:recipients :recipients-detail]]))
+
+(defn user-id->tenant-id
+ "Map of user id to `tenant_id` for `user-ids`, in one query. An empty collection asks nothing of the
+ database and answers `{}` — `[:in ()]` is not valid SQL.
+
+ Throws unless `user-ids` is a collection of integers. The ids are spliced into an `[:in …]` clause,
+ where HoneySQL reads some shapes as syntax rather than as values: a vector is a function call, so
+ `[:raw \"1) OR 1=1 --\"]` renders verbatim into the SQL and `[:inline x]` inlines a literal; a map is a
+ subquery; a keyword or symbol is an identifier. Those are the injection vectors, and they are refused
+ before any SQL is built. Numbers and strings are bound as parameters, so a string id is a plain bug
+ rather than a hole — refused all the same, because a silent no-match is a worse answer than a throw.
+ The offending values ride `ex-data` rather than the message, so nothing caller-controlled lands in a
+ log line.
+
+ `int?` rather than `Long` on purpose: `core_user.id` comes back from JDBC as an `Integer`, so a
+ Long-only check would pass its tests and refuse every real call."
+ [user-ids]
+ (when-not (coll? user-ids)
+ (throw (ex-info "MCP: user ids must be a collection of integers" {:user-ids user-ids})))
+ (when-let [invalid (seq (remove int? user-ids))]
+ (throw (ex-info "MCP: user ids must be a collection of integers" {:invalid (vec invalid)})))
+ (if (seq user-ids)
+ (t2/select-pk->fn :tenant_id :model/User :id [:in user-ids])
+ {}))
+
+(defn existing-transform-tag-ids
+ "The subset of `tag-ids` that name a real TransformTag, as a set. `ids` is expected non-empty — an
+ empty `:in` is a SQL error rather than an empty result, so callers guard it.
+
+ A set rather than the select's own return: `t2/select-fn-set` answers nil when nothing matches,
+ which is exactly the all-unknown case the caller is checking for."
+ [tag-ids]
+ (into #{} (t2/select-fn-set :id :model/TransformTag :id [:in tag-ids])))
diff --git a/src/metabase/mcp/init.clj b/src/metabase/mcp/init.clj
index 9033b8c340c..fcf83d519c6 100644
--- a/src/metabase/mcp/init.clj
+++ b/src/metabase/mcp/init.clj
@@ -1,4 +1,4 @@
(ns metabase.mcp.init
(:require
- [metabase.mcp.resources]
- [metabase.mcp.settings]))
+ [metabase.mcp.settings]
+ [metabase.mcp.task.mcp-query-handle-gc]))
diff --git a/src/metabase/mcp/llms-install.md b/src/metabase/mcp/llms-install.md
index 4931fe4b448..bcbc6eb2bbd 100644
--- a/src/metabase/mcp/llms-install.md
+++ b/src/metabase/mcp/llms-install.md
@@ -122,9 +122,7 @@ Metabase, so the user should log in with the account whose access they want the
## Step 5 — Verify the connection
-Once configured, the client should be able to list MCP tools provided by Metabase. The tools include `search`,
-`get_table`, `get_metric`, `construct_query`, `execute_query`, and `query`. If those appear in the client's tool
-list, the connection is working.
+Once configured, the client should be able to list MCP tools provided by Metabase. The tools include `search`, `browse_data`, `get_content`, `execute_query`, and `learn`. If those appear in the client's tool list, the connection is working. Clients that can render MCP Apps also see `visualize_query`; its absence elsewhere is expected and not a sign of a broken connection.
If the tool list is empty or the client reports an authentication error, re-check that:
diff --git a/src/metabase/mcp/paths.clj b/src/metabase/mcp/paths.clj
new file mode 100644
index 00000000000..4df04f5eb34
--- /dev/null
+++ b/src/metabase/mcp/paths.clj
@@ -0,0 +1,62 @@
+(ns metabase.mcp.paths
+ "The URL paths the MCP server is served under, relative to site-url.
+
+ Source of truth for the route aliases — keep in sync with the route map in
+ [[metabase.api-routes.routes]] and the resource-metadata endpoints in
+ [[metabase.oauth-server.api.metadata]] — and for the scope set the v2 surface accepts.
+
+ A leaf namespace, with NO requires, so both the handler and the OAuth server can read it without a
+ dependency cycle. That is load-bearing rather than tidy: `metabase.server.middleware.security` requires
+ `metabase.mcp.core`, so anything `mcp.core` reaches becomes part of the security middleware's load path —
+ pulling `metabot.scope` (and through it `premium-features`) in that way deadlocks namespace loading with a
+ methodical protocol error at web-server start. Keep this namespace dependency-free.")
+
+(set! *warn-on-reflection* true)
+
+(def canonical-path
+ "The advertised MCP URL. RFC 9728 metadata names `<site-url><this>` as the resource identifier,
+ and that is the string an RFC 8707 `resource` indicator is matched against."
+ "/api/metabase-mcp")
+
+(def endpoint-paths
+ "Every path that serves MCP: the canonical one, plus `/api/mcp`, which predates it and is kept for
+ back-compat with existing client configs. Both serve the same surface.
+
+ Three things are derived from this set and must not drift from it: the route table mounts exactly
+ these paths, `metabase.oauth-server.api.metadata` publishes one RFC 9728 document per path, and
+ `metabase.oauth-server.core/narrow-scope-to-resources` recognises an RFC 8707 `resource` indicator
+ only if it names one. A path that still serves traffic but has dropped out of this set fails
+ OPEN — the indicator matches nothing, so the grant is never narrowed to the MCP surface.
+
+ `/api/metabase-mcp/v2` was here while v2 shipped behind a flag. It was retired at the switchover,
+ along with its route entry and its metadata document."
+ #{canonical-path
+ "/api/mcp"})
+
+(def v2-surface-scopes
+ "Every OAuth scope the v2 MCP surface accepts, as an ordered vector — unlike [[endpoint-paths]] above, which
+ is a set. The order is the order the 401 challenge lists them in, and `contains?` on this would test an
+ index rather than a scope.
+
+ Three things must agree on these, and they are reached from different places, which is why they live in
+ this leaf rather than beside any one of them:
+
+ - the 401 `WWW-Authenticate` challenge, which tells an uninstructed client what to ask for
+ ([[metabase.mcp.v2.api/default-ask-scopes]]);
+ - what the OAuth server will actually grant — DCR snapshots [[metabase.mcp.core/all-scopes]] into each
+ newly registered client, and `validate-scope` checks requests against that per-client snapshot;
+ - what v2 tools and resources may gate on.
+
+ When the challenge drifted ahead of the grant, a client that followed it asked for exactly what it was told
+ and was answered \"Invalid scope\", so the connect failed outright instead of degrading to a narrower grant
+ (GHY-4226).
+
+ Spelled as literals rather than read from `metabot.scope` because requiring that namespace here would close
+ the load cycle described above; `v2-surface-scopes-match-metabot-scope-test` is what keeps them in step.
+ Scopes are never renamed — issued tokens carry literal strings — so this only ever grows."
+ ["agent:content:read"
+ "agent:content:write"
+ "agent:query:run"
+ "agent:sql:run"
+ "agent:delivery:write"
+ "agent:resource:read"])
diff --git a/src/metabase/mcp/resources.clj b/src/metabase/mcp/resources.clj
deleted file mode 100644
index a2ad92d0392..00000000000
--- a/src/metabase/mcp/resources.clj
+++ /dev/null
@@ -1,473 +0,0 @@
-(ns metabase.mcp.resources
- "MCP resource registry. Resources let clients fetch supplementary content (docs,
- reference material) and UI resources by URI without inflating tool descriptions.
-
- Each entry in the registry is a map with `:uri`, `:name`, `:description`,
- `:mimeType`, an optional `:scope`, and a `:render-fn` that returns the textual
- payload. For resources, `:scope` uses [[metabase.mcp.scope/public-or-matches?]]:
- nil means \"public\" (any authenticated caller), and a string is an MCP scope
- checked against the token scopes. This intentionally differs from tools, where
- nil scope is treated as internal-only."
- (:require
- [clojure.java.io :as io]
- [clojure.string :as str]
- [environ.core :as env]
- [metabase.api.common :as api]
- [metabase.api.macros.defendpoint.tools-manifest :as tools-manifest]
- [metabase.config.core :as config]
- [metabase.mcp.scope :as mcp.scope]
- [metabase.mcp.session :as mcp.session]
- [metabase.request.core :as request]
- [metabase.system.core :as system]
- [metabase.util.json :as json]
- [metabase.util.malli :as mu]
- [metabase.util.malli.schema :as ms]
- [stencil.core :as stencil])
- (:import
- (java.net URI)))
-
-(set! *warn-on-reflection* true)
-
-(def ^:private embed-mcp-template-path "frontend_client/embed-mcp.html")
-
-;; The built template is emitted by HtmlWebpackPlugin into resources/frontend_client/
-;; during the frontend build. Backend-only test runs (e.g. CI app-db tests) don't produce
-;; it, so tests install a minimal inline template via `with-fallback-template`.
-(def ^:private test-fallback-template
- (str "<!doctype html><html><head><base href=\"{{{instanceUrlRaw}}}/\"></head><body><script>"
- "window.metabaseConfig = {"
- "instanceUrl: {{{instanceUrl}}}"
- "};</script></body></html>"))
-
-;; An atom rather than a dynamic var because `resources/read` is invoked from the
-;; HTTP handler thread, which doesn't inherit thread-local bindings from the test
-;; thread that installs the fallback.
-(defonce ^:private fallback-template (atom nil))
-
-(defn do-with-fallback-template
- "Implementation detail of [[with-fallback-template]]."
- [thunk]
- (try
- (reset! fallback-template test-fallback-template)
- (thunk)
- (finally
- (reset! fallback-template nil))))
-
-(defmacro with-fallback-template
- "Test-only: install an inline Mustache fallback for the embed-mcp template for
- the duration of `body`. Backend-only test runs don't produce the built template,
- so tests that exercise `resources/read` need this."
- [& body]
- `(do-with-fallback-template (fn [] ~@body)))
-
-(defn render-embed-mcp-template
- "Render the embed-mcp.html Mustache template with the given vars map.
- Expected keys: :instanceUrl (JSON-encoded) and :instanceUrlRaw."
- [vars]
- (cond
- (io/resource embed-mcp-template-path)
- (stencil/render-file embed-mcp-template-path vars)
-
- ;; Backend-only tests install this stub when the frontend build is absent. A
- ;; real build must win so tests and shared REPL JVMs exercise production HTML.
- @fallback-template
- (stencil/render-string @fallback-template vars)
-
- :else
- (throw (ex-info (str "Missing MCP embed template: " embed-mcp-template-path
- ". Run the frontend build to produce it.")
- {:path embed-mcp-template-path}))))
-
-;; The registry holds two indexes:
-;; `:uri->resource` — URI is unique, one resource (iframe) per URI
-;; `:tools` — keyed by tool name, which is also unique. Multiple tools may
-;; target the same resource via :_meta.ui.resourceUri (the iframe
-;; doesn't care which tool delivered the payload).
-;; Both maps overwrite on re-registration so REPL reload is idempotent.
-(defonce ^:private registry
- (atom {:key->uri {}
- :uri->resource (sorted-map)
- :tools (sorted-map)}))
-
-(defn- chatgpt-client?
- "True when the in-flight request's User-Agent identifies the ChatGPT MCP/Apps
- client. ChatGPT empirically sends `openai-mcp/...`; Claude rejects
- `_meta.ui.domain` unless it's a Claude-issued subdomain, so we gate the field
- on this check."
- []
- (boolean (some-> (request/current-request)
- (get-in [:headers "user-agent"])
- (str/includes? "openai-mcp"))))
-
-(defn- site-origin
- "Origin (scheme://host[:port]) extracted from `site-url`, dropping any path segment.
- ChatGPT's MCP host treats `_meta.ui.domain` and the CSP domain lists as origins, so an instance
- hosted under a subpath would otherwise leak the path and fail validation. Returns nil when
- `site-url` is unset — callers degrade gracefully rather than NPE on a misconfigured instance."
- []
- (when-let [url (system/site-url)]
- (let [^URI uri (URI. url)
- scheme (.getScheme uri)
- host (.getHost uri)
- port (.getPort uri)]
- (cond-> (str scheme "://" host)
- (not (neg? port)) (str ":" port)))))
-
-(defn- resource-domains
- [url]
- (cond-> [url]
- config/is-dev? (conj (str "http://localhost:" (or (env/env :mb-frontend-dev-port) "8080")))))
-
-(defn- ui-meta
- "MCP `_meta.ui` block returned alongside UI resources.
- Hosts that render the resource in a sandboxed iframe (notably ChatGPT's MCP app surface) use this
- to pick a sandbox configuration:
-
- - `prefersBorder` — presentation hint asking the host to draw a frame border
- - `domain` — origin the iframe content is anchored at. ChatGPT-only:
- Claude validates this against its own namespace
- (`*.claudemcpcontent.com`) and rejects anything else,
- so we emit it only for ChatGPT (gated by [[chatgpt-client?]]).
- - `csp.baseUriDomains` — hosts the iframe may use in its document `<base>` tag
- (relative bundle assets resolve against the Metabase instance)
- - `csp.connectDomains` — hosts the iframe may XHR/fetch/WebSocket to
- (the embedded SDK calls back to this Metabase instance)
- - `csp.resourceDomains` — hosts the iframe may load scripts/styles/images from
- (the SDK bundle is served from this Metabase instance)
-
- `frameDomains` is intentionally omitted — we don't nest iframes inside the visualization, and leaving
- it out narrows the CSP for security review."
- [resource]
- (let [url (site-origin)]
- {:ui (cond-> {:csp {:baseUriDomains [url]
- :connectDomains [url]
- :resourceDomains (resource-domains url)}}
- (contains? resource :prefersBorder)
- (assoc :prefersBorder (:prefersBorder resource))
-
- (chatgpt-client?)
- (assoc :domain url))}))
-
-(mu/defn register-resource!
- "Register an MCP resource. Overwrites any existing entry with the same `:uri`."
- [resource :- [:map
- [:uri :string]
- [:name :string]
- [:description :string]
- [:render-fn fn?]
- [:mimeType {:optional true} :string]
- [:scope {:optional true} [:maybe :string]]]]
- (let [resource (update resource :mimeType #(or % "text/markdown"))]
- (swap! registry assoc-in [:uri->resource (:uri resource)] resource)
- resource))
-
-(mu/defn- register-ui-resource!
- [key :- :keyword
- uri :- :string
- scope :- :string
- resource :- [:map
- [:name :string]
- [:description :string]
- [:render-fn fn?]
- [:prefersBorder {:optional true} :boolean]]]
- (let [resource (-> (assoc resource :uri uri :scope scope :ui? true)
- (update :mimeType #(or % "text/html;profile=mcp-app")))]
- (swap! registry #(-> %
- (assoc-in [:key->uri key] uri)
- (assoc-in [:uri->resource uri] resource)))
- resource))
-
-(defn- malli->ui-input-schema
- "Convert a Malli schema for a UI-tool input into the published JSON Schema."
- [schema]
- (-> schema tools-manifest/malli->json-schema tools-manifest/strict-tool-input-schema))
-
-(defn- malli->ui-output-schema
- "Convert a Malli schema for a UI-tool output into the published JSON Schema.
- No strict transform — outputs aren't constrained by OpenAI's strict-tool rules."
- [schema]
- (tools-manifest/malli->json-schema schema))
-
-(mu/defn- register-ui-tool-for-resources!
- [resource-keys :- [:sequential :keyword]
- tool :- [:map
- [:name :string]
- [:description :string]
- [:inputSchema :any]
- [:outputSchema {:optional true} :any]
- [:annotations {:optional true} :map]
- [:visibility {:optional true} [:sequential [:enum "model" "app"]]]
- [:response-fn fn?]]]
- (let [resources (mapv (fn [resource-key]
- (if-let [uri (get-in @registry [:key->uri resource-key])]
- (get-in @registry [:uri->resource uri])
- (throw (ex-info "Unknown resource" {:resource-key resource-key}))))
- resource-keys)
- scopes (into #{} (map :scope) resources)
- ui-meta (cond-> {}
- (= 1 (count resources)) (assoc :resourceUri (:uri (first resources)))
- (:visibility tool) (assoc :visibility (:visibility tool)))
- tool (-> tool
- (dissoc :visibility)
- (update :inputSchema malli->ui-input-schema)
- (cond-> (:outputSchema tool) (update :outputSchema malli->ui-output-schema))
- (assoc :scope (if (= 1 (count scopes)) (first scopes) scopes)
- :required-extensions #{:mcp-app-ui}
- :_meta {:ui ui-meta}))]
- (swap! registry assoc-in [:tools (:name tool)] tool)
- tool))
-
-(defn- register-ui-tool!
- "Register a UI tool. `inputSchema` and `outputSchema` are Malli schemas (not JSON Schema)."
- [resource-key tool]
- (register-ui-tool-for-resources! [resource-key] tool))
-
-(defn resource-scopes
- "Return the distinct set of scopes registered across all UI resources."
- []
- (into (sorted-set) (keep :scope) (vals (:uri->resource @registry))))
-
-(defn list-ui-tools
- "Return the list of MCP tools corresponding to UI components."
- []
- (vals (:tools @registry)))
-
-(defn list-resources
- "Return the MCP `resources/list` payload, filtered by `token-scopes`."
- [token-scopes]
- {:resources (into []
- (comp (filter #(mcp.scope/public-or-matches? token-scopes (:scope %)))
- (map (fn [resource]
- (cond-> (select-keys resource [:uri :name :description :mimeType])
- (:ui? resource) (assoc :_meta (ui-meta resource))))))
- (vals (:uri->resource @registry)))})
-
-(def ^:private compatible-mcp-app-uri-pattern
- #"^ui://metabase/(visualize-query|render-drill-through)(?:-v2|\.[0-9a-f]+)?\.html$")
-
-(def ^:private mcp-app-name->resource-key
- {"visualize-query" :visualize-query
- "render-drill-through" :render-drill-through})
-
-(defn- resource-for-uri
- "Resolve current resource URIs exactly. Known MCP App URI variants resolve to
- the corresponding current resource. This compatibility step must ship before
- build-versioned URIs are advertised so rolling upgrades remain safe."
- [uri]
- (let [snapshot @registry]
- (or (get-in snapshot [:uri->resource uri])
- (when-let [[_ app-name] (re-matches compatible-mcp-app-uri-pattern uri)]
- (let [resource-key (get mcp-app-name->resource-key app-name)
- current-uri (get-in snapshot [:key->uri resource-key])]
- (some-> (get-in snapshot [:uri->resource current-uri])
- (assoc :uri uri)))))))
-
-(defn check-resource-access
- "Check whether `uri` exists and is accessible under `token-scopes`.
- Returns :ok, :not-found, or :scope-denied."
- [uri token-scopes]
- (if-let [{:keys [scope]} (resource-for-uri uri)]
- (if (mcp.scope/public-or-matches? token-scopes scope)
- :ok
- :scope-denied)
- :not-found))
-
-(defn read-resource
- "Read a registered resource by URI, gated by `token-scopes`. Returns one of
- `{:status :ok :contents [...]}`, `{:status :scope-denied}`, or
- `{:status :not-found}`. Resource resolution and scope enforcement use the same
- immutable registry snapshot, so aliases cannot bypass the scope check."
- [uri token-scopes opts]
- (if-let [{:keys [render-fn scope ui?] :as resource} (resource-for-uri uri)]
- (if (mcp.scope/public-or-matches? token-scopes scope)
- {:status :ok
- :contents [(cond-> (select-keys resource [:uri :mimeType])
- true (assoc :text (render-fn (assoc opts :resource-uri uri)))
- ui? (assoc :_meta (ui-meta resource)))]}
- {:status :scope-denied})
- {:status :not-found}))
-
-;;; -------------------------------------------------- Helpers ----------------------------------------------------
-
-(defn classpath-text-resource
- "Build a `:render-fn` that returns the contents of `path` on the classpath.
- Throws on registration if the file is missing, surfacing a clear error at boot
- rather than the first `resources/read` call."
- [path]
- (let [url (io/resource path)]
- (when-not url
- (throw (ex-info (str "Missing classpath resource: " path) {:path path})))
- (let [content (delay (slurp url :encoding "UTF-8"))]
- (fn [_opts] @content))))
-
-;;; ------------------------------------------------ Registrations ------------------------------------------------
-
-(register-resource!
- {:uri "metabase://docs/construct-query.md"
- :name "Construct Query Reference"
- :description (str "Format reference for `construct_query` and `query`: top-level / "
- "stage shape, field references, filter / aggregation / temporal "
- "operators, joins, expressions, multi-stage queries, worked examples, "
- "and common pitfalls.")
- :mimeType "text/markdown"
- :render-fn (classpath-text-resource "metabot/prompts/tools/construct_notebook_query.md")})
-
-(defn- visualize-query-render-fn
- "Shared render-fn for visualize_query and render_drill_through. Both expose the
- same iframe template; they only differ in URI so hosts that dedupe by URI
- (notably ChatGPT, which otherwise skips rendering a new iframe for a tool
- whose `_meta.ui.resourceUri` already has one mounted) treat them as distinct.
- `tag` is a per-URI marker embedded in the rendered HTML so the bytes hash
- differently — ChatGPT's asset CDN appears to dedupe by body hash, and without
- distinct bodies the second URI's asset is silently dropped and the widget 404s."
- [tag]
- (fn [{:keys [resource-uri]}]
- (let [site-url (system/site-url)]
- (str "<!-- metabase-mcp-asset: " tag " " resource-uri " -->\n"
- (render-embed-mcp-template
- {:instanceUrl (json/encode site-url)
- :instanceUrlRaw site-url})))))
-
-(register-ui-resource!
- :visualize-query
- "ui://metabase/visualize-query.html"
- "agent:viz:mcp-ui:query"
- {:name "Visualize Query"
- :description "Lightweight MCP Apps visualization for a query"
- :prefersBorder true
- :render-fn (visualize-query-render-fn "visualize-query")})
-
-(register-ui-resource!
- :render-drill-through
- "ui://metabase/render-drill-through.html"
- "agent:viz:mcp-ui:drill-through"
- {:name "Render Drill Through"
- :description "Lightweight MCP Apps visualization for a drill-through follow-up"
- :prefersBorder true
- :render-fn (visualize-query-render-fn "render-drill-through")})
-
-(defn- with-ui-credential
- [result session-id]
- (if (and session-id api/*current-user-id*)
- (assoc result :_meta {:com.metabase/mcp-apps
- {:credential (mcp.session/issue-ui-credential session-id api/*current-user-id*)
- :sessionId session-id}})
- {:content [{:type "text"
- :text "MCP UI credential refresh requires an authenticated MCP session."}]
- :isError true}))
-
-(defn redact-ui-credential
- "Remove the private MCP UI credential from a tool result before tracing it."
- [result]
- (cond-> result
- (map? (:_meta result)) (update :_meta dissoc :com.metabase/mcp-apps)))
-
-(register-ui-tool-for-resources!
- [:visualize-query :render-drill-through]
- {:name "refresh_ui_credential"
- :description "Refresh the scoped credential used by a Metabase MCP App."
- :inputSchema [:map]
- :annotations {:readOnlyHint true
- :destructiveHint false
- :idempotentHint true
- :openWorldHint false}
- :visibility ["app"]
- :response-fn (fn [_arguments {:keys [session-id]}]
- (with-ui-credential
- {:content [{:type "text" :text "MCP UI credential refreshed."}]}
- session-id))})
-
-(register-ui-tool!
- :visualize-query
- {:name "visualize_query"
- :description (str "Visualize a previously constructed query as an interactive chart or table. "
- "This renders a lightweight MCP Apps visualization, not the full Metabase "
- "query builder or standard Metabase UI. Do not tell the user to switch "
- "display types, use visualization settings, or use a Metabase panel, "
- "sidebar, or right-hand panel. "
- "Use this for prompts that ask to show, display, visualize, plot, chart, "
- "or present results, for example: `Show me customers in Metabase`, "
- "`Show me orders by month`, `Display revenue by region`, or "
- "`Visualize active users over time`. This renders the final answer in the UI. "
- "Do not call execute_query after visualize_query; showing the visualization "
- "is enough.")
- ;; Both fields are optional rather than expressing "at least one of" via a top-level `anyOf`.
- ;; This is because some MCP clients, e.g. the MCP inspector (mcpjam) rejects top-level combinators.
- ;; The response-fn enforces the at-least-one contract at runtime.
- :inputSchema
- [:map
- [:query {:optional true
- :description "Base64-encoded MBQL query (use query_handle instead when available)"}
- [:maybe ms/NonBlankString]]
- [:query_handle {:optional true
- :description "Handle returned by construct_query; preferred over raw query"}
- [:maybe ms/UUIDString]]]
- :outputSchema
- [:map
- [:query {:description "Base64-encoded MBQL query that the visualization is rendering."}
- :string]
- [:prompt {:optional true
- :description "User's original request, when stored alongside the handle."}
- [:maybe :string]]]
- :annotations {:readOnlyHint true
- :destructiveHint false
- :idempotentHint true
- :openWorldHint false}
- :response-fn (fn [arguments {:keys [session-id]}]
- (let [query (:query arguments)
- handle (:query_handle arguments)
- resolved (some->> handle (mcp.session/resolve-query-handle
- session-id api/*current-user-id*))
- encoded (or query (:encoded_query resolved))
- prompt (:prompt resolved)]
- (cond
- (and (nil? query) (nil? handle))
- {:content [{:type "text" :text "Provide either 'query' or 'query_handle'."}]
- :isError true}
-
- encoded
- {:content [{:type "text" :text (str "Visualizing query in the interactive UI. "
- "Do not call execute_query after this; "
- "the visualization is the final result.")}]
- ;; If visualize_query was called with a handle, use the stored prompt so the iframe can
- ;; include the user's original request when submitting visualization feedback.
- :structuredContent (cond-> {:query encoded}
- prompt (assoc :prompt prompt))}
-
- :else
- {:content [{:type "text" :text "Query handle not found. Try running construct_query again."}]
- :isError true})))})
-
-(register-ui-tool!
- :render-drill-through
- {:name "render_drill_through"
- :description (str "Render the drill-through visualization the user just navigated into. "
- "This renders a lightweight MCP Apps visualization, not the full Metabase "
- "query builder or standard Metabase UI. Do not tell the user to switch "
- "display types, use visualization settings, or use a Metabase panel, "
- "sidebar, or right-hand panel. "
- "Use this tool, not execute_query, when the user asks to show the result and "
- "their message includes a `handle` UUID. This is the exact follow-up for the "
- "phrase `Show me the result`. Do not execute the query yourself; pass the "
- "`handle` UUID as the `handle` argument.")
- :inputSchema
- [:map
- [:handle {:description "Handle UUID from the user's drill-through message."}
- ms/UUIDString]]
- :outputSchema
- [:map
- [:query {:description "Base64-encoded MBQL query bound to the drill-through handle."}
- :string]]
- :annotations {:readOnlyHint true
- :destructiveHint false
- :idempotentHint true
- :openWorldHint false}
- :response-fn (fn [arguments {:keys [session-id]}]
- (if-let [handle (:handle arguments)]
- (if-let [encoded (mcp.session/read-handle session-id api/*current-user-id* handle)]
- {:content [{:type "text" :text "Rendering drill-through visualization..."}]
- :structuredContent {:query encoded}}
- {:content [{:type "text" :text "No drill-through found for that handle."}]
- :isError true})
- {:content [{:type "text" :text "No drill-through found for that handle."}]
- :isError true}))})
diff --git a/src/metabase/mcp/server.json b/src/metabase/mcp/server.json
deleted file mode 100644
index 9364a825fe8..00000000000
--- a/src/metabase/mcp/server.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
- "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
- "name": "io.github.metabase/mcp",
- "title": "Metabase",
- "description": "Lets AI clients search, explore, query, and visualize data in a Metabase instance.",
- "version": "1.0.0",
- "websiteUrl": "https://www.metabase.com",
- "icons": [
- {
- "src": "https://www.metabase.com/images/logo.svg",
- "mimeType": "image/svg+xml",
- "sizes": ["any"]
- }
- ],
- "repository": {
- "url": "https://github.com/metabase/metabase",
- "source": "github",
- "subfolder": "src/metabase/mcp"
- },
- "remotes": [
- {
- "type": "streamable-http",
- "url": "https://{metabase_host}/api/metabase-mcp",
- "variables": {
- "metabase_host": {
- "description": "Your Metabase hostname, e.g. 'metabase.example.com'.",
- "isRequired": true
- }
- }
- }
- ]
-}
diff --git a/src/metabase/mcp/session.clj b/src/metabase/mcp/session.clj
index dc055654d3d..100c7da79ae 100644
--- a/src/metabase/mcp/session.clj
+++ b/src/metabase/mcp/session.clj
@@ -1,18 +1,18 @@
(ns metabase.mcp.session
"Lightweight MCP session management.
- An MCP session ID is just a random UUID handed out on `initialize` — no database
- row is created. Query handles may lazily materialize a `core_session` row, keyed
- by the hash of a deterministic value derived from the MCP session id.
+ An MCP session ID is just a random UUID handed out on `initialize` — no database row is created. Query handles may
+ lazily materialize a `core_session` row, keyed by the hash of a deterministic value derived from the MCP session id.
- The backing value is derived rather than reusing the MCP session id directly, so
- the correlation id on the wire remains distinct from any stored session material.
- Any webserver can recompute the same value without per-session plaintext at rest.
+ The backing value is derived rather than reusing the MCP session id directly, so the correlation id on the wire
+ remains distinct from any stored session material. Any webserver can recompute the same value without per-session
+ plaintext at rest.
- MCP sessions themselves do not expire. Any backing `core_session` has its own
- TTL and is re-created on demand for query-handle lifecycle management."
+ MCP sessions themselves do not expire. Any backing `core_session` has its own TTL and is re-created on demand for
+ query-handle lifecycle management."
(:require
[clojure.string :as str]
+ [metabase.api.macros.scope :as scope]
[metabase.mcp.db :as mcp.db]
[metabase.mcp.models.mcp-query-handle]
[metabase.mcp.settings :as mcp.settings]
@@ -39,19 +39,27 @@
(.init mac (SecretKeySpec. (.getBytes secret "UTF-8") "HmacSHA256"))
(.doFinal mac (.getBytes message "UTF-8"))))
-(defn derive-embedding-session-key
- "Deterministically derive the embedding session key for `mcp-session-id` from the
- instance-wide signing secret. See ns docstring for rationale.
+(defn- derive-embedding-session-key
+ "Deterministically derive the embedding session key for `mcp-session-id` from the instance-wide signing secret. See ns
+ docstring for rationale.
- The output is formatted as a UUID string because `metabase.server.middleware.session`
- rejects non-UUID session keys up-front. Specifically we emit a version-8 UUID
- (RFC 9562), which is the version reserved for \"custom / vendor-defined\"
- constructions — i.e. exactly our case: 128 bits produced by our own HMAC-SHA256
- derivation rather than by the standard v1/v3/v4/v5 algorithms. v4 would lie
- about randomness, v5 would lie about the hash algorithm; v8 is the only version
- that's actually honest here.
+ PRIVATE ON PURPOSE, and the privacy is load-bearing rather than stylistic. The derivation takes only the MCP
+ session id — which is client-supplied and unsigned — so two users presenting the same id derive the SAME key.
+ `core_session` lookups resolve a key by `key_hashed` alone, with no user filter and no ordering
+ ([[metabase.server.middleware.session]]), so whichever colliding row the DB returns first is who that key
+ authenticates as. Any public fn returning this plaintext is therefore an account-takeover primitive: a caller
+ who knows another user's session id gets a working session key for whoever else materialized a row under it.
- Trade-offs to be aware of:
+ Inside this namespace the value is only ever hashed. Keep it that way — a caller that needs the row should use
+ [[get-or-create-embedding-session!]], which returns the row and never the key.
+
+ The output is formatted as a UUID string because `metabase.server.middleware.session` rejects non-UUID session keys
+ up-front. Specifically we emit a version-8 UUID
+ (RFC 9562), which is the version reserved for \"custom / vendor-defined\" constructions: 128 bits produced by our
+ own HMAC-SHA256 derivation rather than by the standard v1/v3/v4/v5 algorithms. v4 would lie about randomness, v5
+ would lie about the hash algorithm; v8 is the only version that's actually honest here.
+
+ Trade-offs to be aware of:
- Masking the variant (2 bits) and version (4 bits) costs 6 bits of entropy, so
we end up with 122 bits of randomness — identical to `UUID/randomUUID`, and
plenty for the ~2^61 birthday bound the rest of the session model already
@@ -77,8 +85,8 @@
(str (UUID. high low))))
(def ^:private ui-credential-lifetime-seconds
- "Lifetime of an MCP Apps UI credential. The server sends the credential in
- private tool-result metadata."
+ "Lifetime of a rendered MCP Apps UI credential. This is deliberately short: the credential is delivered to an iframe
+ through a resource response."
300)
(defn- base64url-encode [^String value]
@@ -95,20 +103,67 @@
(hmac-sha256 (mcp.settings/unobfuscated-mcp-embedding-signing-secret)
(str "mcp-ui-v1." payload))))
+(defn- session-payload-signature
+ "HMAC over the encoded capability `payload` for `uuid`, base64url.
+
+ Bound to the uuid so a signature cannot be lifted from one session id onto another — the payload alone is
+ `{\"v\":1,\"ui\":true}` for every UI-capable session, so an unbound signature would be a reusable token
+ granting the capability to any correlator. Domain-separated from
+ [[ui-credential-signature]] so neither can be replayed as the other."
+ [^String uuid ^String payload]
+ (base64url-encode-bytes
+ (hmac-sha256 (mcp.settings/unobfuscated-mcp-embedding-signing-secret)
+ (str "mcp-session-v1." uuid "." payload))))
+
(declare valid-id?)
-(defn issue-ui-credential
- "Create a short-lived credential for the MCP Apps UI. It authenticates only
- the narrow server-side UI request surface, never as a core Metabase session."
- [session-id user-id]
+(defn- encode-token-scopes
+ "Serialize `token-scopes` into credential claims.
+
+ Named scope strings go in `:scp`; the `::scope/unrestricted` sentinel gets its own boolean claim `:unr`. They are
+ kept in separate claims deliberately: JSON has no keywords, so folding the sentinel into `:scp` would turn it into
+ a string that a granted scope could be equal to. Nothing that can appear in `:scp` can appear in `:unr`."
+ [token-scopes]
+ (cond-> {:scp (vec (sort (filter string? token-scopes)))}
+ (contains? token-scopes ::scope/unrestricted) (assoc :unr true)))
+
+(defn- decode-token-scopes
+ "Rebuild the scope set from credential `claims`, reversing [[encode-token-scopes]].
+
+ Absent claims read as the empty set rather than as unrestricted, so a credential minted by a node that predates
+ the claim fails closed for the five minutes it stays valid."
+ [{:keys [scp unr]}]
+ (cond-> (into #{} (filter string?) scp)
+ (true? unr) (conj ::scope/unrestricted)))
+
+(defn- sign-ui-credential
+ "Sign the standard credential claims plus `extra-claims` into a `<payload>.<signature>` string."
+ [session-id user-id extra-claims]
(let [payload (base64url-encode
- (json/encode {:v 1 :uid user-id :sid session-id
- :exp (+ (.getEpochSecond (Instant/now)) ui-credential-lifetime-seconds)}))]
+ (json/encode (merge {:v 1 :uid user-id :sid session-id
+ :exp (+ (.getEpochSecond (Instant/now)) ui-credential-lifetime-seconds)}
+ extra-claims)))]
(str payload "." (ui-credential-signature payload))))
+(defn issue-ui-credential
+ "Create a short-lived credential for the MCP Apps UI. It authenticates only the narrow server-side UI request surface,
+ never as a core Metabase session.
+
+ `token-scopes` is the minting MCP session's scope set. It rides along as a signed claim because it is the only
+ record of what the client was actually granted: the credential authenticates as `::scope/mcp-ui`, which
+ satisfies no endpoint's declared `:scope`. Both gates on the iframe's request surface spend this claim — see
+ [[metabase.mcp.ui-surface/request-surface]] and [[metabase.agent-api.query-guards/check-mcp-ui-native-query!]].
+
+ Passing the caller's real scopes is what subjects the credential to the native-SQL gate. (v1's frozen
+ surface used to mint claimless, gate-exempt `:legacy` credentials through a 2-arity of this fn; that shim
+ retired with v1.)"
+ [session-id user-id token-scopes]
+ (sign-ui-credential session-id user-id (encode-token-scopes token-scopes)))
+
(defn resolve-ui-credential
- "Validate a rendered MCP Apps UI credential and return its claims, or nil.
- Invalid and expired inputs intentionally have the same result and are never logged."
+ "Validate a rendered MCP Apps UI credential and return its claims, or nil. The claims carry `:token-scopes`, the
+ scope set the minting MCP session held.
+ Invalid and expired inputs intentionally have the same result and are never logged."
[credential]
(try
(let [[payload ^String signature & extra] (str/split (or credential "") #"\." -1)
@@ -120,7 +175,7 @@
(when (and (= v 1) (integer? uid) (string? sid) (integer? exp)
(valid-id? sid)
(> exp (.getEpochSecond (Instant/now))))
- claims))))
+ (assoc claims :token-scopes (decode-token-scopes claims))))))
(catch Exception _ nil)))
;;; -------------------------------------------------- Lifecycle --------------------------------------------------
@@ -144,38 +199,37 @@
(defn- encode-session-payload
"Encode a small JSON map for the second segment of `Mcp-Session-Id`.
- MCP initialize capabilities are client-advertised hints, not authorization state. We include them in the
- server-created session id so later requests can make the same tools/list decision on any Metabase webserver
- without an in-memory cache or a DB row just for session metadata."
+ MCP initialize capabilities are client-advertised hints, not authorization state. We include them in the
+ server-created session id so later requests can make the same tools/list decision on any Metabase webserver without
+ an in-memory cache or a DB row just for session metadata."
[payload]
- (-> (json/encode payload)
- (.getBytes StandardCharsets/UTF_8)
- (->> (.encodeToString (.withoutPadding (Base64/getUrlEncoder))))))
+ (base64url-encode (json/encode payload)))
(defn- decode-session-payload
"Decode the optional client-capability hint from an `Mcp-Session-Id`.
- Invalid payloads return nil so the whole session id can be treated as invalid by [[session-parts]]."
+ Invalid payloads return nil so the whole session id can be treated as invalid by [[session-parts]]."
[encoded]
(when-not (str/blank? encoded)
+ ;; The payload is client-supplied via the `Mcp-Session-Id` header, so a bad base64 body or
+ ;; non-JSON contents must read as an invalid session rather than propagate out of `valid-id?`.
(try
- (-> (Base64/getUrlDecoder)
- (.decode ^String encoded)
- (String. StandardCharsets/UTF_8)
- json/decode+kw)
+ (json/decode+kw (base64url-decode encoded))
(catch Exception _
nil))))
(defn- parse-session-payload
"Parse the optional base64url JSON capability segment.
- Plain UUID session ids are legacy ids issued before capability-aware tools/list and remain valid. Two-part ids
- with a known payload version must include a supported payload shape so malformed capability hints do not silently
- fall back to legacy behavior. Unknown payload versions remain valid but default to no UI capability, so rolling
- deploy version skew does not invalidate the whole session."
- [payload]
+ Plain UUID session ids are legacy ids issued before capability-aware tools/list and remain valid. Two-part ids with
+ a known payload version must include a supported payload shape so malformed capability hints do not silently fall
+ back to legacy behavior. Unknown payload versions remain valid but default to no UI capability, so rolling deploy
+ version skew does not invalidate the whole session."
+ [payload signed?]
(cond
(nil? payload)
+ ;; A bare uuid predates capability hints entirely. It claims nothing: reading it as "supports MCP Apps"
+ ;; would make signing pointless, since a caller could omit the payload and be believed anyway.
{:extended false}
(str/blank? payload)
@@ -197,7 +251,13 @@
known-version?
(mr/validate ::session-payload decoded-payload))
{:extended true
- :payload (select-keys decoded-payload [:ui])}
+ ;; The capability is believed only when the signature proves the SERVER minted this claim. An
+ ;; unsigned or tampered payload leaves the session usable — the id is a stateless correlator and
+ ;; any well-formed one works for its presenter — but claims nothing, so the gate it feeds fails
+ ;; closed rather than trusting a self-assertion.
+ :payload (if signed?
+ (select-keys decoded-payload [:ui])
+ {:ui false})}
;; During rolling deploys, a newer node may mint a capability payload version this node does not understand.
;; The payload is only a capability hint, so keep the session valid but fall back to no MCP Apps UI support.
@@ -210,37 +270,54 @@
(defn- session-parts
"Parse an MCP session id into a UUID correlator plus optional client-capability hint.
- New session ids have the form `<uuid>.<base64url-json>`, currently with payload `{\"v\":1,\"ui\":true}`.
- We keep the UUID as the first segment because existing MCP session behavior derives the embedding session key
- from this server-created id, while the JSON segment lets us remember initialize-time UI capability statelessly
- across multiple Metabase webservers."
+ New session ids have the form `<uuid>.<base64url-json>.<signature>`, currently with payload
+ `{\"v\":1,\"ui\":true}`. An id whose signature is absent or wrong is still a VALID session — it is a
+ stateless correlator and any well-formed one works for its presenter — but its capability claim is not
+ believed, so a client cannot self-assert MCP Apps support by forging a payload. We keep
+ the UUID as the first segment because existing MCP session behavior derives the embedding session key from this
+ server-created id, while the JSON segment lets us remember initialize-time UI capability statelessly across multiple
+ Metabase webservers."
[session-id]
(when (and (string? session-id)
(<= (count session-id) max-session-id-length))
- (let [[uuid payload :as parts] (str/split session-id #"\." -1)]
- (when (#{1 2} (count parts))
- (when-let [uuid (parse-uuid uuid)]
- (some-> (parse-session-payload payload)
- (assoc :uuid uuid)))))))
+ (let [[uuid payload signature :as parts] (str/split session-id #"\." -1)]
+ (when (#{1 2 3} (count parts))
+ (when-let [parsed-uuid (parse-uuid uuid)]
+ (let [signed? (boolean (and payload signature
+ (let [^String expected (session-payload-signature uuid payload)]
+ (MessageDigest/isEqual (.getBytes expected StandardCharsets/UTF_8)
+ (.getBytes ^String signature
+ StandardCharsets/UTF_8)))))]
+ (some-> (parse-session-payload payload signed?)
+ (assoc :uuid parsed-uuid))))))))
(defn- create-session-id
"Create a stateless MCP session id containing client capability hints.
- The server creates this id during initialize; clients only echo it back. The unsigned payload is intentionally
- limited to non-security-sensitive capability hints such as whether the client says it can render MCP Apps UI."
+ The server creates this id during initialize; clients only echo it back. The capability payload is SIGNED
+ (`<uuid>.<payload>.<signature>`) because `:required-extensions` gates on it: unsigned, it is a claim the
+ client makes about itself, and any caller could mint one asserting MCP Apps support it never advertised.
+ The id itself remains an opaque stateless correlator — see [[session-parts]] for why an unproven claim
+ downgrades the capability rather than rejecting the session."
[{:keys [supports-mcp-ui?]}]
- (let [session-id (str (UUID/randomUUID)
- "."
- (encode-session-payload {:v session-payload-version
- :ui (true? supports-mcp-ui?)}))]
- (assert (<= (count session-id) max-session-id-length)
- "MCP session id is too long")
+ (let [uuid (str (UUID/randomUUID))
+ payload (encode-session-payload {:v session-payload-version
+ :ui (true? supports-mcp-ui?)})
+ session-id (str uuid "." payload "." (session-payload-signature uuid payload))]
+ ;; Enforce the `mcp_query_handle.mcp_session_id` column width (254) at the mint site, not only on the read path
+ ;; ([[session-parts]]). A future payload field that pushed an id past the cap would otherwise mint fine and
+ ;; initialize a working session, then have every later request 404 "Invalid or expired session" once the
+ ;; over-long id failed the read-path length guard — a failure divorced in time and place from its cause. Failing
+ ;; here turns that into an immediate, legible error at creation. A thrown ex (not a bare `assert`, which
+ ;; `*assert*` can disable) keeps the guard live in every build.
+ (when (> (count session-id) max-session-id-length)
+ (throw (ex-info "MCP session id exceeds the persisted column width"
+ {:length (count session-id) :max max-session-id-length})))
session-id))
(defn valid-id?
"Return true if `session-id` has a UUID correlator (the format `create!` produces).
- Format check only — authentication is handled separately by cookie or bearer token,
- not by the session ID itself."
+ Format check only — authentication is handled separately by cookie or bearer token, not by the session ID itself."
[session-id]
(some? (session-parts session-id)))
@@ -252,30 +329,38 @@
(defn create!
"Create a new MCP session. Returns a session id string.
- No database row is written — the session is just an opaque correlator until
- a resource read materializes it into a `core_session`.
+ No database row is written — the session is just an opaque correlator until a resource read materializes it into a
+ `core_session`.
+
+ `user-id` is accepted but not persisted: since MCP sessions are currently stateless (no server-side token store), we
+ don't validate the user against future requests. This parameter exists so we can add durable, user-scoped sessions
+ in the future without changing the call-site contract.
- `user-id` is accepted but not persisted: since MCP sessions are currently
- stateless (no server-side token store), we don't validate the user against
- future requests. This parameter exists so we can add durable, user-scoped
- sessions in the future without changing the call-site contract."
+ The 1-arity is v1 compat (master's call-site shape, still used by the v1 callback tests); it goes
+ with the other v1 shims at retirement."
([user-id]
(create! user-id nil))
([_user-id metadata]
(create-session-id metadata)))
(defn supports-mcp-ui?
- "Return true if the client advertised MCP Apps UI support during initialize."
+ "Return true if the client PROVABLY advertised MCP Apps UI support during initialize.
+
+ Only a signed capability payload counts. This gates `:required-extensions`, so a claim the server cannot
+ verify has to read as absent: a plain UUID id — issued before capability hints existed — used to return
+ true here, which meant a caller could bypass the whole gate by simply omitting the payload. Both that and an
+ unsigned payload now fail closed."
[session-id]
- (when-let [{:keys [payload extended]} (session-parts session-id)]
- (if extended
- (true? (:ui payload))
- ;; Legacy plain UUID sessions were issued before capability-aware tools/list; keep old behavior for them.
- true)))
+ (boolean
+ (when-let [{:keys [payload extended]} (session-parts session-id)]
+ (and extended (true? (:ui payload))))))
-(defn- get-or-create-embedding-session!
+(defn get-or-create-embedding-session!
"Materialize and return the `core_session` row backing this MCP session.
- Idempotent — repeated calls collapse to the same row in the common case."
+ Idempotent — repeated calls collapse to the same row in the common case.
+
+ Returns the row, never the session key — see [[derive-embedding-session-key]] for why the plaintext must not
+ leave this namespace."
[session-id user-id]
(let [session-key (derive-embedding-session-key session-id)
key-hashed (session/hash-session-key session-key)]
@@ -292,20 +377,18 @@
;; auth layer, not here, and no constraint shape at this call site can fix it.
(mcp.db/get-or-create-core-session! key-hashed user-id)))
-(defn get-or-create-session-key!
- "Ensure a `core_session` exists for this MCP session and return its (plaintext)
- session key, HMAC-derived from the MCP session id."
- [session-id user-id]
- (get-or-create-embedding-session! session-id user-id)
- (derive-embedding-session-key session-id))
-
(defn owned-by-user?
- "Return true if no `core_session` has been materialized for this session yet
- (i.e. no ownership to violate), or if the existing row belongs to `user-id`."
+ "Return true if no `core_session` has been materialized for this session yet (i.e. no ownership to violate), or if
+ one of the materialized rows belongs to `user-id`."
[session-id user-id]
+ ;; `Mcp-Session-Id` is client-supplied and unsigned, so two users can present the same id and each materialize their
+ ;; own row before either check runs — the window spans requests, so no transaction here can close it. Matching the
+ ;; (key_hashed, user_id) scoping that `get-or-create-embedding-session!` and `delete!` already use makes that
+ ;; harmless: each user sees their own row instead of one arbitrarily shadowing the other. Reading the owner from
+ ;; key_hashed alone would pick one row of the set and lock every other user out of a session they already hold.
(let [key-hashed (session/hash-session-key (derive-embedding-session-key session-id))
- owner (mcp.db/session-user-id key-hashed)]
- (or (nil? owner) (= owner user-id))))
+ owners (mcp.db/session-user-ids key-hashed)]
+ (or (empty? owners) (contains? owners user-id))))
;;; -------------------------------------------- Query Handle Store -----------------------------------------------
;; DB-backed store for base64-encoded MBQL query payloads referenced by MCP tool
@@ -316,12 +399,12 @@
(defn store-handle!
"Insert a new handle row binding `encoded-query` to the calling user, and return the handle UUID.
- `mcp-session-id` is recorded so DELETE /api/metabase-mcp can sweep the session's handles, and so reads can log
- when a handle is resolved across sessions (see [[find-handle-row]]) — the read path itself is purely
- user-scoped, since handle UUIDs are globally unique.
+ `mcp-session-id` is recorded so DELETE /api/metabase-mcp can sweep the session's handles, and so reads can log when
+ a handle is resolved across sessions (see [[find-handle-row]]) — the read path itself is purely user-scoped, since
+ handle UUIDs are globally unique.
- `prompt` is optional, but should be supplied for construct_query handles so visualize_query can later
- return both the query and original user prompt to the MCP iframe for feedback submission."
+ `prompt` is optional, but should be supplied for construct_query handles so visualize_query can later return both
+ the query and original user prompt to the MCP iframe for feedback submission."
([mcp-session-id user-id encoded-query]
(store-handle! mcp-session-id user-id encoded-query nil))
([mcp-session-id user-id encoded-query prompt]
@@ -346,10 +429,9 @@
(defn- find-handle-row
"Look up the handle row by `handle-id`, scoped to `user-id`.
- Handle ids are globally unique UUIDs, so the join's `WHERE mqh.id = handle-id` returns at most one
- row by definition — no ordering or session-preference logic is needed. `mcp-session-id` is recorded
- on the row only so harnesses that rotate MCP sessions between calls (e.g. ChatGPT) can be logged as
- cross-session resolutions for telemetry."
+ Handle ids are globally unique UUIDs, so the join's `WHERE mqh.id = handle-id` returns at most one row by definition
+ — no ordering or session-preference logic is needed. `mcp-session-id` is recorded on the row only so harnesses that
+ rotate MCP sessions between calls (e.g. ChatGPT) can be logged as cross-session resolutions for telemetry."
[mcp-session-id user-id handle-id]
(when (and user-id (handle-id? handle-id))
;; Single round-trip: join `mcp_query_handle` to `core_session` and filter on
@@ -360,30 +442,44 @@
handle-id user-id))
row)))
+(defn resolve-query-handle
+ "Return {:encoded_query ... :prompt ...} for `handle-id` owned by `user-id`, or nil.
+ Lookup is user-scoped — see [[find-handle-row]] for how `mcp-session-id` is used."
+ [mcp-session-id user-id handle-id]
+ ;; Threading the ROW, not the session id: the lookup is user-scoped and needs only `user-id`, and
+ ;; `mcp-session-id` is used solely to log a cross-session resolution. Short-circuiting on a nil session id
+ ;; would refuse a handle its owner is entitled to.
+ (some-> (find-handle-row mcp-session-id user-id handle-id)
+ (select-keys [:encoded_query :prompt])))
+
(defn read-handle
"Return the encoded query for `handle-id` owned by `user-id`, or nil if no row exists.
- Lookup is user-scoped — see [[find-handle-row]] for how `mcp-session-id` is used."
- [mcp-session-id user-id handle-id]
- (:encoded_query (find-handle-row mcp-session-id user-id handle-id)))
+ Lookup is user-scoped — see [[find-handle-row]] for how `mcp-session-id` is used.
-(defn resolve-query-handle
- "Return {:encoded_query ... :prompt ...} for `handle-id` owned by `user-id`, or nil.
- Lookup is user-scoped — see [[find-handle-row]] for how `mcp-session-id` is used."
+ v1-compat: only the frozen v1 surface calls this; delete it with v1's retirement."
[mcp-session-id user-id handle-id]
- (when-let [row (find-handle-row mcp-session-id user-id handle-id)]
- (select-keys row [:encoded_query :prompt])))
+ (:encoded_query (find-handle-row mcp-session-id user-id handle-id)))
(defn delete!
- "Delete the `core_session` backing this MCP session (if one was ever created)
- and any associated query handles. Scoped to `user-id` so that one user cannot
- delete another user's session.
-
- Handles tied to a `core_session` are also reaped by the FK cascade when the
- session row goes; the explicit handle-delete here covers handles whose
- `core_session_id` was never set — e.g. handles for regular query payloads that
- aren't backed by an MCP iframe and so never materialize a `core_session`."
+ "Delete the `core_session` backing this MCP session (if one was ever created) and this user's query handles on it.
+ Every statement is scoped to `user-id`, so tearing down one user's session cannot touch another's.
+
+ That scoping is not belt-and-braces: `Mcp-Session-Id` is client-supplied and unsigned, so two users can hold
+ rows under one id and [[owned-by-user?]] admits both by design. Deleting handles by `mcp_session_id` alone
+ would therefore reap the other user's handles — rows the FK cascade would never have touched, since they hang
+ off *their* `core_session`.
+
+ Handles are deleted before the session row so they can still be scoped through it; the `ON DELETE CASCADE` that
+ follows is then a no-op for this user.
+
+ Rows with a NULL `core_session_id` ARE reaped, on session id alone. `store-handle!` always sets the column now,
+ but it is nullable and released code predating that left rows without it; scoping those through `core_session`
+ strands them forever, since `NULL IN (subquery)` never matches and nothing else sweeps the table. Reaping them
+ unscoped is safe precisely because they are unattributed: [[find-handle-row]] inner-joins `core_session`, so
+ such a row can never be read back by anyone. That makes it unreachable data rather than another user's working
+ handle — the opposite of the attributed rows, which stay scoped."
[session-id user-id]
(assert-session-id! session-id)
(let [key-hashed (session/hash-session-key (derive-embedding-session-key session-id))]
- (mcp.db/delete-session-for-user! key-hashed user-id)
- (mcp.db/delete-query-handles-for-mcp-session! session-id)))
+ (mcp.db/delete-query-handles-for-user-session! session-id key-hashed user-id)
+ (mcp.db/delete-session-for-user! key-hashed user-id)))
diff --git a/src/metabase/mcp/task/mcp_query_handle_gc.clj b/src/metabase/mcp/task/mcp_query_handle_gc.clj
new file mode 100644
index 00000000000..38a08b98342
--- /dev/null
+++ b/src/metabase/mcp/task/mcp_query_handle_gc.clj
@@ -0,0 +1,50 @@
+(ns metabase.mcp.task.mcp-query-handle-gc
+ "Scheduled task that deletes `mcp_query_handle` rows older than
+ [[metabase.mcp.settings/mcp-query-handle-ttl-hours]]. Handles tied to a live session are also
+ reaped by the `core_session` FK cascade and the explicit session delete; this task catches
+ handles whose sessions outlive the TTL, since every execute mints a handle and volume grows
+ much faster than sessions are torn down. Drill-through handles share the store and age out on
+ the same TTL."
+ (:require
+ [clojurewerkz.quartzite.jobs :as jobs]
+ [clojurewerkz.quartzite.schedule.cron :as cron]
+ [clojurewerkz.quartzite.triggers :as triggers]
+ [java-time.api :as t]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.models.mcp-query-handle]
+ [metabase.mcp.settings :as mcp.settings]
+ [metabase.task.core :as task]
+ [metabase.util.log :as log])
+ (:import
+ (org.quartz DisallowConcurrentExecution)))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private gc-job-key (jobs/key "metabase.task.mcp.query-handle-gc.job"))
+(def ^:private gc-trigger-key (triggers/key "metabase.task.mcp.query-handle-gc.trigger"))
+
+(defn- gc-expired-query-handles!
+ []
+ (let [ttl-hours (mcp.settings/mcp-query-handle-ttl-hours)
+ cutoff (t/minus (t/offset-date-time) (t/hours (long ttl-hours)))
+ deleted (mcp.db/delete-query-handles-created-before! cutoff)]
+ (log/infof "MCP query handle GC complete. Deleted %d handle(s) older than %d hours."
+ (or deleted 0) (long ttl-hours))))
+
+(task/defjob ^{DisallowConcurrentExecution true
+ :doc "Delete expired MCP query handles"}
+ McpQueryHandleGc [_ctx]
+ (gc-expired-query-handles!))
+
+(defmethod task/init! ::McpQueryHandleGc
+ [_]
+ (let [job (jobs/build
+ (jobs/of-type McpQueryHandleGc)
+ (jobs/with-identity gc-job-key))
+ trigger (triggers/build
+ (triggers/with-identity gc-trigger-key)
+ (triggers/start-now)
+ (triggers/with-schedule
+ ;; daily at 23:27:11 (offset from the MCP usage trimmer's 23:19:41)
+ (cron/cron-schedule "11 27 23 * * ?")))]
+ (task/schedule-task! job trigger)))
diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.clj
deleted file mode 100644
index b64b76cde32..00000000000
--- a/src/metabase/mcp/tools.clj
+++ /dev/null
@@ -1,585 +0,0 @@
-(ns metabase.mcp.tools
- "MCP tool dispatch. Generates tool definitions from defendpoint metadata and delegates
- tool calls to existing agent API endpoints."
- (:require
- [clojure.core.async :as a]
- [clojure.set :as set]
- [clojure.string :as str]
- [metabase.agent-api.api :as agent-api]
- [metabase.ai-tracing.core :as ait]
- [metabase.api.common :as api]
- [metabase.api.macros.defendpoint.tools-manifest :as tools-manifest]
- [metabase.config.core :as config]
- [metabase.mcp.resources :as mcp.resources]
- [metabase.mcp.scope :as mcp.scope]
- [metabase.mcp.session :as mcp.session]
- [metabase.mcp.usage :as mcp.usage]
- [metabase.server.streaming-response :as streaming-response]
- [metabase.util :as u]
- [metabase.util.json :as json]
- [metabase.util.log :as log]
- [metabase.util.malli.registry :as mr]
- [metabase.util.malli.schema :as ms])
- (:import
- (java.io ByteArrayOutputStream)
- (java.net URLEncoder)
- (metabase.server.streaming_response StreamingResponse)))
-
-(set! *warn-on-reflection* true)
-
-;;; ---------------------------- MCP schema overrides -------------------------------
-;;
-;; A few tools have an MCP-visible input or output shape that differs from the wire shape declared
-;; on the defendpoint. Owning the override here keeps `agent-api` ignorant of MCP: the endpoint
-;; describes its own wire schema, and this layer patches the manifest to publish the MCP-visible
-;; shape.
-
-;; Shared sub-shapes for the representations-shaped tools (`construct_query`, `query`).
-;;
-;; The wire schemas under `agent-api` describe the body as `{:query <::lib.schema/external-query>}`,
-;; and `::external-query` references `::lib.schema/query`, which carries `:optional` keys (notably
-;; `:lib/metadata`) that are not `[:maybe ...]`. The new `assert-optional-fields-nullable!` lint in
-;; `tools-manifest` walks every reachable map and fails on those — which is the right behaviour for
-;; tool inputs but not for the lib-internal query map we never want strict MCP clients to populate.
-;;
-;; The override here publishes a permissive `:query` field (an opaque JSON object) and conveys the
-;; real grammar through the tool description + `metabase://docs/construct-query.md`. Strict MCP
-;; clients (ChatGPT) get a clean JSON Schema (no `prefixItems` / `allOf`); the agent learns the
-;; actual MBQL 5 shape from the prompt.
-
-(def ^:private external-query-mcp-malli
- "MCP-visible shape for the `query` field of `construct_query` / `query`. Deliberately opaque:
- publishing the full `::lib.schema/external-query` recursively would pull in `::query`'s optional
- non-nullable `:lib/metadata` (which trips the manifest's strict-tool lint) and emit `prefixItems` /
- `allOf` JSON Schema constructs that strict MCP clients (ChatGPT) reject."
- [:map {:tool/description (str "A Metabase MBQL 5 query as a JSON object. See the "
- "`construct_notebook_query` tool for the format reference.")}])
-
-(def ^:private construct-query-mcp-input-malli
- "MCP-visible input for `construct_query`.
- Deliberately flatter than the wire schema — the MBQL 5 representations grammar is conveyed through
- the tool description and the construct-query.md MCP resource, not the schema."
- [:map
- [:query {:tool/description "Metabase MBQL 5 query."}
- external-query-mcp-malli]
- ;; Length bounds + description go on the inner `:string` so they end up on the JSON Schema branch
- ;; (and not as an `:allOf`, which ChatGPT's strict validator rejects).
- [:prompt {:optional true}
- [:maybe [:string {:min 1
- :max 10000
- :tool/description (str "The user's exact original message, when available. "
- "Pass it as-is without summarizing or rewriting.")}]]]])
-
-(def ^:private query-mcp-input-malli
- "MCP-visible input for `query`. The wire body is a `:multi` whose `:fresh` branch references
- `::lib.schema/external-query` — that pulls in `::query`'s `:optional` non-nullable
- `:lib/metadata` (and emits `prefixItems` / `allOf` JSON Schema constructs that strict MCP
- clients reject). This override publishes the same opaque-object `:query` field used by
- `construct_query`, plus the `:query_handle` and `:continuation_token` alternatives. The handle
- is swapped for the stored base64 `:query` by [[resolve-query-arg]] before dispatch."
- [:map
- [:query {:optional true
- :tool/description (str "Metabase MBQL 5 query. Use `query_handle` instead "
- "when you have one. Omit when paginating via "
- "`continuation_token`.")}
- [:maybe external-query-mcp-malli]]
- [:query_handle {:optional true
- :tool/description (str "Handle returned by construct_query — preferred over "
- "raw `query`.")}
- [:maybe ms/UUIDString]]
- [:continuation_token {:optional true
- :tool/description (str "Token returned by a previous `query` response — pass "
- "it back to fetch the next page. Mutually exclusive "
- "with `query`.")}
- [:maybe ms/NonBlankString]]])
-
-(def ^:private execute-query-mcp-input-malli
- "MCP-visible input for `execute_query`.
- The wire endpoint requires `:query`; the MCP tool also accepts `:query_handle`, resolved by
- [[resolve-query-arg]] before dispatch."
- [:map
- [:query {:optional true
- :tool/description "Base64-encoded MBQL query. Use `query_handle` instead when available."}
- [:maybe ms/NonBlankString]]
- [:query_handle {:optional true
- :tool/description "Handle returned by construct_query — preferred over raw `query`."}
- [:maybe ms/UUIDString]]])
-
-(def ^:private construct-query-mcp-output-malli
- "MCP-visible output of `construct_query`.
- The agent_api endpoint returns `{:query base64}`; the MCP body transform stores that and emits
- `{:query_handle}`."
- [:map
- [:query_handle
- {:tool/description (str "Opaque UUID handle for the stored query. "
- "Pass as `query_handle` to `execute_query` or `visualize_query`.")}
- ms/UUIDString]])
-
-(def ^:private mcp-input-overrides
- "tool-name → Malli schema. Replaces the manifest's derived `:inputSchema`."
- {"construct_query" construct-query-mcp-input-malli
- "query" query-mcp-input-malli
- "execute_query" execute-query-mcp-input-malli})
-
-(def ^:private mcp-output-overrides
- "tool-name → Malli schema. Replaces the manifest's derived `:outputSchema`.
- Both construct tools emit `{:query_handle}` via the body transform (see
- [[tools-storing-query-handle]]), so they share the same output schema."
- {"construct_query" construct-query-mcp-output-malli
- "construct_native_query" construct-query-mcp-output-malli})
-
-(defn- override->input-json-schema [malli tool-name]
- (tools-manifest/assert-optional-fields-nullable! malli tool-name)
- (-> malli tools-manifest/malli->json-schema tools-manifest/strict-tool-input-schema))
-
-(defn- apply-schema-overrides
- "Replace `:inputSchema`/`:outputSchema` on tools whose MCP-visible shape differs from the wire shape.
- The `overrides-cover-known-tools-test` test asserts every key here matches a real tool name; a
- misspelled or drifted key would otherwise silently no-op and leave the wire shape published."
- [tools]
- (mapv (fn [{tool-name :name :as tool}]
- (cond-> tool
- (mcp-input-overrides tool-name)
- (assoc :inputSchema (override->input-json-schema (mcp-input-overrides tool-name) tool-name))
-
- (mcp-output-overrides tool-name)
- (assoc :outputSchema (tools-manifest/malli->json-schema (mcp-output-overrides tool-name)))))
- tools))
-
-(defn- generate-manifest
- "Generate tools manifest from agent API endpoint metadata, then patch input/output schemas for tools
- whose MCP-visible shape differs from the wire shape."
- []
- (-> (tools-manifest/generate-tools-manifest
- {'metabase.agent-api.api "/api/agent"})
- (update :tools apply-schema-overrides)))
-
-(def ^:private manifest-delay
- (delay (generate-manifest)))
-
-(defn- manifest
- "Return the tools manifest. Cached in prod, recomputed each call in dev."
- []
- (if config/is-dev?
- (generate-manifest)
- @manifest-delay))
-
-(def ^:private extension-labels
- "Human-readable labels for required-extension keywords in tool-call error messages."
- {:mcp-app-ui "MCP Apps UI"})
-
-(defn- supported-extensions
- [{:keys [supports-mcp-ui?]}]
- (if supports-mcp-ui?
- #{:mcp-app-ui}
- #{}))
-
-(defn- missing-required-extensions
- [tool supported-extensions]
- (seq (set/difference (:required-extensions tool #{}) supported-extensions)))
-
-(defn- missing-extensions-error
- [tool-name missing-extensions]
- (let [extension-names (str/join ", " (map #(get extension-labels % (name %)) missing-extensions))]
- (str tool-name " requires a client that supports " extension-names ". "
- "Reconnect from a client that advertises text/html;profile=mcp-app.")))
-
-(defn list-tools
- "Return the tool definitions suitable for MCP `tools/list` responses.
- When `token-scopes` is provided, only tools whose scope matches are included."
- ([token-scopes]
- (list-tools token-scopes {:supports-mcp-ui? true}))
- ([token-scopes options]
- (let [{:keys [tools]} (manifest)
- supported (supported-extensions options)]
- (into []
- (comp (filter #(mcp.scope/matches? token-scopes (:scope %)))
- (remove #(missing-required-extensions % supported))
- (map (fn [tool]
- (select-keys tool [:name :title :description :inputSchema :outputSchema :annotations :_meta]))))
- (concat tools (mcp.resources/list-ui-tools))))))
-
-(defn- pad-left
- [^String s width]
- (if (>= (count s) width)
- s
- (str (apply str (repeat (- width (count s)) \0)) s)))
-
-(defn tools-hash
- "Return a stable hash of the tool list visible to `token-scopes`, formatted as
- an 8-character unsigned hex string. Used by the SSE keepalive loop to detect
- manifest changes and emit `notifications/tools/list_changed`. Hashes the JSON
- encoding of `[name inputSchema outputSchema]` per tool, sorted by name, so the
- result is determined purely by the wire-visible schema bytes — no reliance on
- Clojure's `hash` of map values (which can be unstable for non-data leaves
- like functions, and is order-sensitive for some collection types)."
- [token-scopes]
- (-> (->> (list-tools token-scopes)
- (map (juxt :name :inputSchema :outputSchema))
- (sort-by first)
- json/encode
- hash)
- (Integer/toUnsignedString 16)
- (pad-left 8)))
-
-(defn- build-tool-index
- "Build name->tool lookup from manifest tools."
- [tools]
- (into {} (map (juxt :name identity)) tools))
-
-(def ^:private tool-index-delay
- (delay (build-tool-index (:tools @manifest-delay))))
-
-(defn- tool-index
- "Lookup from tool name to its full manifest definition. Cached in prod, recomputed each call in dev."
- []
- (if config/is-dev?
- (build-tool-index (:tools (manifest)))
- @tool-index-delay))
-
-(defn- format-validation-detail
- "Flatten a defendpoint schema-error map — humanized by `malli.error`, whose leaves
- are vectors of message strings and whose intermediate nodes may be nested maps —
- into a compact `field: msg, msg; field: msg` rendering for MCP error text."
- [errors-map]
- (->> errors-map
- (map (fn [[k v]]
- (str (name k) ": "
- (cond
- (map? v) (format-validation-detail v)
- (sequential? v) (str/join ", " v)
- :else (str v)))))
- (str/join "; ")))
-
-(defn- extract-error-message
- "Pull the best human-readable string out of an agent-api error response. Agent-api
- returns `:specific-errors`/`:errors` for schema-validation 400s (see
- [[metabase.api.macros/decode-and-validate-params]]) and `:message`/`:error` for
- other failures — surfacing the validation detail turns \"Invalid body\" into an
- actionable message for MCP clients. String bodies (e.g. 404 \"Not found.\") are
- surfaced as the message rather than collapsed to a bare \"Agent API error: <status>\"."
- [response]
- (let [body (:body response)
- body-map (when (map? body) body)
- body-str (when (and (string? body) (not (str/blank? body))) body)
- {msg :message :keys [specific-errors errors error]} body-map
- detail (cond
- (seq specific-errors) (format-validation-detail specific-errors)
- (seq errors) (format-validation-detail errors))]
- (cond
- (and msg detail) (str msg " (" detail ")")
- detail detail
- msg msg
- error error
- body-str body-str
- :else (str "Agent API error: " (:status response)))))
-
-;;; ------------------------------------------- Query Handle Transforms -------------------------------------------
-
-(defn- resolve-query-arg
- "Resolve the query argument for tools that accept a handle.
- If :query_handle is present, look it up and replace with :query.
- If :query is itself a UUID (the LLM passed the handle in the wrong field), resolve
- it too (and log a warning).
- Returns updated arguments, or ::handle-not-found if the handle doesn't exist."
- [session-id tool-name arguments]
- (let [user-id api/*current-user-id*]
- (cond
- (:query_handle arguments)
- (if-let [{:keys [encoded_query]} (mcp.session/resolve-query-handle
- session-id user-id (:query_handle arguments))]
- (-> arguments (dissoc :query_handle) (assoc :query encoded_query))
- ::handle-not-found)
-
- (mcp.session/valid-id? (:query arguments))
- (do (log/warnf "MCP tool %s: agent passed a UUID handle in :query; resolving as :query_handle"
- tool-name)
- (if-let [{:keys [encoded_query]} (mcp.session/resolve-query-handle
- session-id user-id (:query arguments))]
- (assoc arguments :query encoded_query)
- ::handle-not-found))
-
- :else
- arguments)))
-
-(def ^:private construct-query-output-validator
- (mr/validator construct-query-mcp-output-malli))
-
-(defn- make-store-construct-query-result
- "Build a body-transform fn for the construct tools (`construct_query`, `construct_native_query`).
- The fn stores the base64 payload server-side under the calling user (with the current MCP session id
- recorded for cleanup) and returns {:query_handle uuid} instead of {:query base64}, so the LLM carries
- a short opaque UUID rather than the full base64 string.
- The optional prompt is stored with the handle for later feedback submission.
-
- The fn validates its emitted shape against `construct-query-mcp-output-malli` — the same schema the
- manifest publishes as the tool's outputSchema — keeping the published schema and the actual emitted
- body in lockstep."
- [session-id user-id]
- (fn [body]
- (if-let [encoded (:query body)]
- (let [handle (mcp.session/store-handle! session-id user-id encoded (:prompt body))
- new-body {:query_handle handle}]
- (when-not (construct-query-output-validator new-body)
- (throw (ex-info (str "construct_query body transform produced a shape that doesn't "
- "match the declared outputSchema")
- {:body new-body})))
- new-body)
- body)))
-
-;; Tools whose :query_handle is resolved by `resolve-query-arg` (it swaps the handle for the stored
-;; base64 :query) before the agent-api dispatch in `call-tool`. `visualize_query` also accepts a
-;; handle, but it's a UI tool that resolves the handle itself (see `metabase.mcp.resources`) and
-;; never reaches this dispatch path, so it's intentionally absent here.
-(def ^:private tools-accepting-query-handle
- #{"execute_query" "query" "create_question" "update_question" "create_metric" "update_metric"})
-
-;; Tools whose 200 body is `{:query base64}` and gets stored as a handle, returning `{:query_handle}`.
-;; `construct_query` (MBQL) and `construct_native_query` (native SQL) both follow this contract.
-(def ^:private tools-storing-query-handle
- #{"construct_query" "construct_native_query"})
-
-;;; ------------------------------------------------- Tool Dispatch -------------------------------------------------
-
-(defn- text-content
- "Wrap a value as an MCP tool-call result.
- Map/sequential values are surfaced as `structuredContent` — MCP spec requires this for any tool that
- declares an `outputSchema`.
- The `content` array carries a text serialization for clients that don't consume structuredContent."
- [v]
- (cond-> {:content [{:type "text" :text (if (string? v) v (json/encode v))}]}
- (or (map? v) (sequential? v)) (assoc :structuredContent v)))
-
-;; JSON-RPC error codes recorded as `mcp_tool_call_log.error_code` for failed tool calls.
-;; Kept in sync with the `error_code` -> `error_type` CASE in the v_mcp_tool_calls view SQL. The
-;; view also maps -32000 ("Server error") defensively (JSON-RPC reserves -32000..-32099), but the
-;; recorder never emits it, so there's no constant for it here.
-(def ^:private error-code-invalid-request -32600)
-(def ^:private error-code-method-not-found -32601)
-(def ^:private error-code-invalid-params -32602)
-(def ^:private error-code-internal -32603)
-
-(defn- error-content
- "Wrap an error message as MCP error content. The JSON-RPC `code` (default: internal error) is
- carried under a namespaced key for usage logging and stripped from the response before it
- reaches the client (see [[call-tool]])."
- ([message] (error-content message error-code-internal))
- ([message code] {:content [{:type "text" :text message}] :isError true ::error-code code}))
-
-(comment streaming-response/keep-me) ; ensure StreamingResponse class is loaded
-
-(defn- capture-streaming-response
- "Execute a StreamingResponse in-process by writing to a ByteArrayOutputStream,
- then parse the JSON output and return it as MCP text content.
-
- This buffers the full response in memory (~120KB for 200 rows), which is fine for
- the row limits we enforce."
- [^StreamingResponse response]
- (let [baos (ByteArrayOutputStream.)
- canceled-chan (a/promise-chan)
- f (.f response)]
- (f baos canceled-chan)
- (text-content (json/decode+kw (.toString baos "UTF-8")))))
-
-(defn- deliver-agent-api-response
- "Dispatch to agent API routes and deliver response to promise.
- For POST/PUT/PATCH requests, `params` is sent as the request body.
- For other methods (GET/DELETE), `params` is sent as parsed query params.
- Materializes StreamingResponse bodies in-process before delivering."
- [result method path token-scopes params]
- (agent-api/routes
- (cond-> {:request-method method
- :uri path
- :metabase-user-id api/*current-user-id*
- :token-scopes token-scopes
- ;; Marks this as MCP's synthetic in-process dispatch so the Agent API usage recorder
- ;; skips it — these calls are already counted in mcp_tool_call_log; recording them as
- ;; agent_api_call_log rows too would double-count.
- :agent-api-internal-request? true}
- ;; POST/PUT/PATCH carry params in the body; GET/DELETE carry them as query params.
- (and (seq params) (#{:post :put :patch} method)) (assoc :body params)
- (and (seq params) (not (#{:post :put :patch} method))) (assoc :query-params params))
- (fn [{resp-body :body :as response}]
- (deliver result (if (instance? StreamingResponse resp-body)
- (capture-streaming-response resp-body)
- response)))
- (fn [error]
- (let [{:keys [status-code] :as data} (ex-data error)]
- (deliver result {:status (or status-code 500)
- :body (merge (select-keys data [:errors :specific-errors])
- {:message (or (ex-message error) "Internal error")})})))))
-
-(defn- invoke-agent-api
- "Invoke an Agent API endpoint with a synthetic Ring request.
- Returns MCP content (text-content on success, error-content on failure).
- For POST/PUT/PATCH, `params` becomes the request body; otherwise (GET/DELETE)
- `params` becomes query-params.
-
- Propagates `token-scopes` from the original MCP request so that scope restrictions
- are preserved through the synthetic request.
-
- `body-transform-fn`, when provided, is applied to the 200 response body before
- wrapping with text-content. Used to post-process construct_query results."
- [method path token-scopes params & {:keys [body-transform-fn]}]
- (let [result (promise)]
- (deliver-agent-api-response result method path token-scopes params)
- (let [response (deref result 30000 {:status 504 :body {:message "Timeout"}})]
- (cond
- ;; Already materialized from a StreamingResponse
- (:content response)
- response
-
- (= 200 (:status response))
- (text-content (cond-> (:body response)
- body-transform-fn (body-transform-fn)))
-
- :else
- (error-content (extract-error-message response))))))
-
-(defn- interpolate-path
- "Replace `{param}` placeholders in `path` with values from `arguments`.
- Returns `[resolved-path remaining-args]` where remaining-args has path params removed."
- [path arguments]
- (let [params (re-seq #"\{([^}]+)\}" path)
- resolved (reduce (fn [p [placeholder k]]
- (let [v (get arguments (keyword k))]
- (when (nil? v)
- (throw (ex-info (str "Missing required path parameter: " k)
- {:parameter k :path path})))
- (str/replace p placeholder (URLEncoder/encode (str v) "UTF-8"))))
- path
- params)
- path-keys (set (map (comp keyword second) params))]
- [resolved (apply dissoc arguments path-keys)]))
-
-(defn- strip-api-prefix
- "Strip the `/api/agent` prefix from manifest paths, since `invoke-agent-api`
- calls `agent-api/routes` directly which expects `/v1/...` paths."
- [path]
- (str/replace-first path #"^/api/agent" ""))
-
-(defn- dispatch-via-agent-api
- "Generic dispatch for tools whose responseFormat is \"json\".
- Looks up method/path from the tool definition, interpolates path params,
- and calls `invoke-agent-api`. For POST/PUT/PATCH requests, remaining args are
- sent as the request body. For other methods (GET/DELETE), remaining args are
- sent as query params."
- [tool-def arguments token-scopes session-id]
- (let [{:keys [method path]} (:endpoint tool-def)
- tool-name (:name tool-def)
- method (keyword (u/lower-case-en method))
- [resolved-path
- remaining-args] (interpolate-path path arguments)
- api-path (strip-api-prefix resolved-path)
- body-transform-fn (when (tools-storing-query-handle tool-name)
- (make-store-construct-query-result
- session-id api/*current-user-id*))]
- (invoke-agent-api method api-path token-scopes remaining-args
- :body-transform-fn body-transform-fn)))
-
-;; --- Design note: centralized null-stripping at the MCP boundary --------------------------------
-;; The MCP inputSchema we publish makes every optional field required-and-nullable, because strict
-;; MCP clients (notably ChatGPT) cannot represent absent fields — they always send every property
-;; the schema declares, with `null` for the ones the agent doesn't want to populate. We strip
-;; those nulls here so each downstream tool handler can use ordinary Clojure idioms (destructure
-;; `:or` defaults, `(when foo …)`, etc.) and treat missing and null identically.
-;;
-;; The alternative is per-tool auditing: every endpoint handler would need to coerce nil into the
-;; right default, and every wire schema's dispatch logic would need to tolerate explicit nulls. We
-;; chose centralization because (a) it's the layer that creates the strict-validator artifact, and
-;; (b) the codex review found that `query`'s `:multi` dispatch on `:continuation_token` already
-;; mishandled a client-sent `null`, so per-tool handling is easy to miss.
-;;
-;; TRADE-OFF: as a consequence, a top-level `null` argument is indistinguishable from omitted at
-;; the MCP boundary. If we ever expose a tool whose semantics genuinely require `null` to mean
-;; something different from "missing" (e.g. \"clear this field\" semantics), it must either model
-;; the distinction with a sentinel value (`{:clear true}`) or do the bespoke handling before this
-;; normalization runs (e.g. as a pre-processing step inside `call-tool`).
-(defn- drop-nil-args
- "Strip nil-valued top-level keys from MCP tool arguments.
- Nested values are left alone — the strict-tool transform only rewrites top-level properties."
- [arguments]
- (when arguments
- (into {} (remove (comp nil? val)) arguments)))
-
-(defn- dispatch-tool-call
- "Resolve and invoke the handler for an MCP `tools/call`, returning MCP content on success
- or error content on failure. The instrumented [[call-tool]] wraps this."
- [token-scopes session-id tool-name arguments options]
- (let [arguments (drop-nil-args arguments)
- supported (supported-extensions options)]
- (if-let [ui-tool (some #(when (= tool-name (:name %)) %) (mcp.resources/list-ui-tools))]
- (if-not (mcp.scope/matches? token-scopes (:scope ui-tool))
- (error-content (str "Insufficient scope to call tool: " tool-name) error-code-invalid-request)
- (if-let [missing-extensions (missing-required-extensions ui-tool supported)]
- (error-content (missing-extensions-error tool-name missing-extensions) error-code-invalid-params)
- ((:response-fn ui-tool) arguments {:session-id session-id})))
- (if-let [tool-def (get (tool-index) tool-name)]
- (if-not (mcp.scope/matches? token-scopes (:scope tool-def))
- (error-content (str "Insufficient scope to call tool: " tool-name) error-code-invalid-request)
- (if-let [missing-extensions (missing-required-extensions tool-def supported)]
- (error-content (missing-extensions-error tool-name missing-extensions) error-code-invalid-params)
- (let [arguments (if (tools-accepting-query-handle tool-name)
- (resolve-query-arg session-id tool-name arguments)
- arguments)]
- (if (= arguments ::handle-not-found)
- (error-content "Query handle not found. The query may have expired — try running construct_query again." error-code-invalid-params)
- (try
- (dispatch-via-agent-api tool-def arguments token-scopes session-id)
- (catch Exception e
- (error-content (or (ex-message e) "Internal error") error-code-internal)))))))
- (error-content (str "Unknown tool: " tool-name) error-code-method-not-found)))))
-
-(defn call-tool
- "Dispatch an MCP `tools/call` request to the appropriate handler.
- `token-scopes` from the original MCP session are propagated to the synthetic
- agent-api request so that scope restrictions are enforced by the agent API's
- `defendpoint` middleware. UI tool response-fns receive `{:session-id session-id}`
- as opts in case a tool needs to scope reads to the calling MCP session.
- Returns MCP content on success, or error content on failure.
-
- Every call — including scope-denied, unknown-tool, and error outcomes — is recorded to
- `mcp_tool_call_log` (EE-only, best-effort) with its timing, success/error status, and on
- error the JSON-RPC `error_code` + `error_message` (the latter gated/truncated by the writer)."
- ([token-scopes session-id tool-name arguments]
- (call-tool token-scopes session-id tool-name arguments {:supports-mcp-ui? true}))
- ([token-scopes session-id tool-name arguments options]
- ;; Eval span (inert unless capturing) nesting under the MCP request span; records the tool
- ;; name + args, and the resulting content as output.
- (ait/with-tool-call {:ai/tool-name tool-name :ai/tool-args arguments}
- (let [start (System/nanoTime)
- record! (fn [status error-code error-message]
- (mcp.usage/record-mcp-tool-call!
- {:tool-name tool-name
- :user-id api/*current-user-id*
- :session-id session-id
- :status status
- :duration-ms (quot (- (System/nanoTime) start) 1000000)
- :error-code error-code
- :error-message error-message
- ;; Identity + PII are denormalized onto the row (the view no longer joins the
- ;; session): client from the call's `_meta`, tenant from the current user,
- ;; IP/UA from the request. The recorder falls back to the session row's stored
- ;; client when `_meta` carries none, and gates the PII columns.
- :client-info (:client-info options)
- :tenant-id (some-> api/*current-user* deref :tenant_id)
- :user-agent (get-in options [:request-context :user-agent])
- :ip-address (get-in options [:request-context :ip-address])}))]
- (try
- (let [result (dispatch-tool-call token-scopes session-id tool-name arguments options)
- error? (boolean (:isError result))]
- (record! (if error? "error" "success")
- (when error? (or (::error-code result) error-code-internal))
- (when error? (some-> result :content first :text)))
- ;; `::error-code` is an internal classification marker — never expose it to the client.
- (let [result (dissoc result ::error-code)]
- (when (ait/capture-active?)
- (ait/record! {:ai/tool-output (mcp.resources/redact-ui-credential result)}))
- result))
- (catch Throwable e
- ;; A handler that throws instead of returning error content (notably a UI tool
- ;; `:response-fn`, whose path isn't wrapped in `dispatch-tool-call`) would otherwise
- ;; skip instrumentation and under-report errors. Record the failure, then rethrow so the
- ;; transport layer still surfaces it to the client.
- (record! "error" error-code-internal (ex-message e))
- (throw e)))))))
diff --git a/src/metabase/mcp/transport.clj b/src/metabase/mcp/transport.clj
new file mode 100644
index 00000000000..84fd612364d
--- /dev/null
+++ b/src/metabase/mcp/transport.clj
@@ -0,0 +1,701 @@
+(ns metabase.mcp.transport
+ "MCP (Model Context Protocol) Streamable HTTP transport.
+
+ Owns everything transport-level: JSON-RPC 2.0 framing (single messages and batches), the `initialize` handshake and
+ session issuance, origin validation (DNS-rebinding protection), cookie/bearer auth resolution, per-user throttling,
+ SSE responses and the GET keepalive stream, and OAuth discovery hints on 401s."
+ (:require
+ [clojure.core.async :as a]
+ [clojure.string :as str]
+ [clojure.walk :as walk]
+ [compojure.response :as compojure.response]
+ [metabase.ai-tracing.core :as ait]
+ [metabase.api.common :as api]
+ [metabase.api.macros.scope :as scope]
+ [metabase.api.open-api :as open-api]
+ [metabase.mcp.core :as mcp]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.usage :as mcp.usage]
+ [metabase.mcp.v2.common :as v2.common]
+ [metabase.oauth-server.core :as oauth-server]
+ [metabase.request.core :as request]
+ [metabase.server.middleware.security :as mw.security]
+ [metabase.server.streaming-response :as streaming-response]
+ [metabase.system.core :as system]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.util.log :as log]
+ [throttle.core :as throttle])
+ (:import
+ (java.io BufferedWriter OutputStreamWriter Writer)
+ (java.nio.charset StandardCharsets)
+ (java.util.concurrent ExecutorService Executors)))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------- JSON-RPC 2.0 --------------------------------------------------
+
+(def ^:private server-info
+ {:name "metabase"
+ :version "0.1.0"})
+
+(def ^:private protocol-version "2025-03-26")
+
+(defn jsonrpc-response
+ "Wrap `result` as a JSON-RPC 2.0 success response for request `id`."
+ [id result]
+ {:jsonrpc "2.0" :id id :result result})
+
+(defn jsonrpc-error
+ "Build a JSON-RPC 2.0 error response for request `id`."
+ [id code message]
+ {:jsonrpc "2.0" :id id :error {:code code :message message}})
+
+(defn- handle-initialize
+ "Handle the MCP `initialize` method: log the connecting client and return the handshake result.
+
+ - `capabilities` is per-surface — a surface must only advertise the methods it dispatches.
+ - `instructions` rides the result as the MCP `instructions` field."
+ [id params capabilities instructions]
+ (when-let [client-info (:clientInfo params)]
+ (log/infof "MCP client connected: %s %s" (:name client-info) (:version client-info)))
+ (jsonrpc-response
+ id
+ (cond-> {:protocolVersion protocol-version
+ :capabilities capabilities
+ :serverInfo server-info}
+ instructions (assoc :instructions instructions))))
+
+(defn- mcp-app-ui-capability?
+ "Return true if initialize params advertise support for MCP Apps HTML resources."
+ [params]
+ ;; The wire key is the JSON string `"io.modelcontextprotocol/ui"`; keywordizing preserves the slash, so the lookup
+ ;; below is a namespaced keyword rather than the dotted `:io.modelcontextprotocol.ui` it might look like a typo for.
+ (contains?
+ (set (get-in params [:capabilities :extensions :io.modelcontextprotocol/ui :mimeTypes]))
+ "text/html;profile=mcp-app"))
+
+(defn- eval-session-override
+ "An eval-session id the harness supplies via the `x-eval-session-id` header so it can name (and later fetch) the trace
+ itself — the MCP analogue of metabot's `eval_session_id`. opencode negotiates the `Mcp-Session-Id` internally, so
+ without this the harness can't know which `<uuid>.jsonl` to read.
+
+ Validates through [[ait/checked-session-id]] — the mint-time boundary, and the single source of truth for the
+ safe-id contract — and maps its throw on an unsafe/over-long id to nil, so a bad header falls back to the
+ Mcp-Session-Id correlator rather than 500ing ahead of [[dispatch-request]]'s try/catch. The `when-let` guards the
+ absent-header case, so we never reach `checked-session-id`'s nil -> fresh-uuid branch (which would invent a trace
+ file the harness never named)."
+ [request]
+ (when-let [id (get-in request [:headers "x-eval-session-id"])]
+ (try (ait/checked-session-id id) (catch Exception _ nil))))
+
+(defn- redact-ui-credentials
+ "Strip minted MCP Apps UI credentials from a JSON-RPC response before it is recorded into an eval
+ trace. A `resources/read` of a UI shell embeds the freshly minted credential in the rendered HTML
+ (`uiCredential: \"…\"` via [[metabase.mcp.ui-resource/embed-render-fn]]); recording it verbatim
+ parks a live bearer authenticator in the trace file (and the superuser-readable ai-tracing API),
+ where it outlives its 5-minute window in backups and log shipping. v1 stripped its credential
+ channel before tracing the same way (`mcp.resources/redact-ui-credential`).
+
+ A `tools/call` result carries the credential in its private MCP Apps `_meta` block instead
+ (`refresh_ui_credential`); the registry strips that block from its own tool-output trace, and this
+ response-level trace must strip it too or the credential lands in the trace one frame up."
+ [response]
+ (letfn [(redact-text [s]
+ (cond-> s
+ (string? s) (str/replace #"uiCredential: \"[^\"]*\"" "uiCredential: \"[redacted]\"")))]
+ (cond-> response
+ (sequential? (get-in response [:result :contents]))
+ (update-in [:result :contents] (partial mapv #(update % :text redact-text)))
+
+ (map? (:result response))
+ (update :result v2.common/redact-mcp-apps-meta))))
+
+(defn- dispatch-request
+ "Dispatch a single JSON-RPC request through the surface's `dispatch-method-fn`.
+ Returns a response map or nil for notifications."
+ [dispatch-method-fn {:keys [id method params] :as _msg} session-id token-scopes request-context eval-session-id]
+ ;; Eval tracing (inert unless MB_AI_EVAL_CAPTURE): establish a session and open a per-request root
+ ;; span; tool/resource/agent-api spans nest under it automatically. Key on the harness-supplied
+ ;; `eval-session-id` when given (so it owns the trace file name), else the MCP session's UUID
+ ;; correlator so an entire conversation's requests append to one `<uuid>.jsonl`. We key on the UUID
+ ;; prefix (not the full `<uuid>.<base64>` id): it's stable across the conversation AND always
+ ;; filesystem/URL-safe, whereas the full id can carry a base64 payload that `require-valid-session`
+ ;; accepts but `safe-session-id-re` rejects (e.g. `=` padding) — passing that to `with-eval-session`
+ ;; would throw out here, ahead of the try/catch.
+ ;;
+ ;; When BOTH are absent (a stateless / pre-initialize request with no header), this is nil and
+ ;; `with-eval-session` mints a fresh uuid — so such requests get their own `<uuid>.jsonl` rather than
+ ;; grouping. That's fine for the eval flow, which always supplies `eval-session-id`; the ungrouped
+ ;; files are reaped by the appender's IdlePurgePolicy.
+ (ait/with-eval-session (or eval-session-id (some-> session-id (str/split #"\.") first))
+ (ait/eval-span (str "mcp." method) {:mcp/method method
+ :mcp/request-id id
+ :mcp/params params
+ :mcp/user-id api/*current-user-id*
+ :mcp/scopes token-scopes}
+ (let [response (try
+ (dispatch-method-fn id method params session-id token-scopes request-context)
+ (catch Throwable e
+ ;; Logged inside `caller-safe-error-message` (once). The sanitizer, not the raw message: handlers that answer with a
+ ;; JSON-RPC error (resources/read render-fns, tools/list) don't pass
+ ;; through `->mcp-error-content`, and a thrown Error (not Exception)
+ ;; skips even the tool-call sanitizer — either way an unvetted message
+ ;; may embed SQL, schema, or connection detail.
+ (jsonrpc-error id -32603 (v2.common/caller-safe-error-message e))))]
+ ;; record the materialized JSON-RPC result/error (the request's output)
+ (ait/record! {:mcp/response (redact-ui-credentials response)})
+ response))))
+
+;;; ----------------------------------------------------- SSE ------------------------------------------------------
+
+(defn- accepts-sse?
+ "Return true if the request's Accept header includes text/event-stream."
+ [request]
+ (some-> (get-in request [:headers "accept"])
+ (str/includes? "text/event-stream")))
+
+(defn- sse-body
+ "Format a sequence of JSON-RPC messages as SSE event text."
+ [messages]
+ (str/join (for [message messages]
+ (str "event: message\ndata: " (json/encode message) "\n\n"))))
+
+;;; -------------------------------------------------- Responses ---------------------------------------------------
+
+(defn- json-response
+ "Build a Ring response with a JSON-encoded `body`."
+ ([status body]
+ (json-response status body nil))
+ ([status body extra-headers]
+ {:status status
+ :headers (merge {"Content-Type" "application/json"} extra-headers)
+ :body (json/encode body)}))
+
+(defn- sse-response
+ "Return a plain Ring response with SSE-formatted body for POST requests."
+ ([messages]
+ (sse-response messages nil))
+ ([messages extra-headers]
+ {:status 200
+ :headers (merge {"Content-Type" "text/event-stream"
+ "Cache-Control" "no-cache"}
+ extra-headers)
+ :body (sse-body messages)}))
+
+;;; ------------------------------------------------- Validation --------------------------------------------------
+
+(defn- normalize-authority
+ "Extract `[domain port]` from a URL or Host-style header value, lowercasing the domain and leaving `port` as the
+ string the header carried (nil when it carried none). Bracketed IPv6 forms (`[::1]:3000`) are handled correctly.
+ Returns nil for unparsable input.
+ Uses [[mw.security/try-parse-url]] (the silent variant) — `Origin`/`Host` are client-controlled, so malformed inputs
+ are expected and shouldn't spam the error logs."
+ [url]
+ (when-let [{:keys [domain port]} (some-> url str mw.security/try-parse-url)]
+ [(u/lower-case-en domain) port]))
+
+(defn- same-origin-host?
+ "Is `origin` the same origin as the host the request was addressed to?
+
+ Compares domain AND port: an origin is a (scheme, domain, port) triple, so matching on the domain alone treats
+ every other app on the same hostname as same-origin. On a developer machine that is the whole threat model —
+ `localhost:9999` and `localhost:3000` are different origins, and a page on the former must not drive this server
+ with the user's cookies.
+
+ Two deliberate loosenesses:
+
+ - The ports are compared only when BOTH headers carry one. A reverse proxy can rewrite `Host` to add or drop a
+ port the browser's `Origin` does not carry, and a 403 on a legitimate deployment is worse than the residual
+ here: exploiting it requires occupying the scheme's DEFAULT port locally, which the dev servers this guard
+ is aimed at do not use.
+ - Scheme is not compared at all, because `Host` does not carry one. The request's own `:scheme` is not a
+ substitute — behind a TLS-terminating proxy it reads `:http` while the browser's `Origin` says `https` (cf.
+ #75110).
+
+ This is the FALLBACK comparison, used only when `site-url` gives us no instance origin to check against.
+ See [[validate-origin]]: two client-supplied headers cannot establish who the request was really for."
+ [origin host]
+ (let [[origin-domain origin-port] (normalize-authority origin)
+ [host-domain host-port] (normalize-authority host)]
+ (and (some? origin-domain)
+ (= origin-domain host-domain)
+ (or (nil? origin-port)
+ (nil? host-port)
+ (= origin-port host-port)))))
+
+(defn- approved-mcp-origin? [origin]
+ ;; Pre-lowercase both inputs so DNS hostname matching is case-insensitive (per RFC) and so mixed-case
+ ;; schemes still match `try-parse-url`'s lowercase-only `https?|app|capacitor` regex.
+ (boolean
+ (or (mcp/sandbox-origin? origin)
+ (when-let [approved-origins (not-empty (mcp/cors-origins))]
+ (when-let [origin-url (mw.security/try-parse-url (u/lower-case-en origin))]
+ (some (fn [approved-origin]
+ (and (mw.security/approved-domain? (:domain origin-url) (:domain approved-origin))
+ (mw.security/approved-protocol? (:protocol origin-url) (:protocol approved-origin))
+ (mw.security/approved-port? (:port origin-url) (:port approved-origin))))
+ (mw.security/parse-approved-origins (u/lower-case-en approved-origins))))))))
+
+(def ^:private default-ports
+ "Default port per scheme, so `https://h` and `https://h:443` are one origin, as the browser treats them."
+ {"http" "80" "https" "443"})
+
+(defn- canonical-origin
+ "`[protocol domain port]` for `origin-map` (the [[mw.security/try-parse-url]] shape), lowercased, with an
+ absent port replaced by its scheme's default. nil without a scheme: an `Origin` always carries one, and
+ comparing without it would let `http://` satisfy an `https://` instance."
+ [{:keys [protocol domain port]}]
+ (when (and protocol domain)
+ (let [protocol (u/lower-case-en protocol)]
+ [protocol (u/lower-case-en domain) (or port (get default-ports protocol))])))
+
+(defn- same-origin-as-instance?
+ "Is `origin` this instance's own origin, as `site-url` declares it?"
+ [origin instance-origin]
+ (= (canonical-origin (mw.security/try-parse-url (u/lower-case-en (str origin))))
+ (canonical-origin instance-origin)))
+
+(defn- validate-origin
+ "Validate the Origin header to prevent DNS rebinding attacks (MCP spec requirement).
+ Returns a 403 response if Origin is present and is neither this instance's own origin nor an explicitly
+ configured MCP app origin. Non-browser clients that omit the Origin header are allowed through.
+
+ The instance's origin comes from `site-url`, NOT from the request. Comparing `Origin` against `Host` — which
+ is what this did, and what v1 still does — cannot detect the attack it names: under DNS rebinding both
+ headers carry the attacker's own name (`evil.example`), so they match each other and the request is admitted.
+ `site-url` is the one origin on a request the client cannot influence.
+
+ When `site-url` is unset or unparsable there is no instance origin to check against, and the guard falls back
+ to the `Origin`/`Host` comparison. That is weaker, but a misconfigured instance degrading to the previous
+ behaviour beats 403ing its own browser clients."
+ [request]
+ (when-let [origin (get-in request [:headers "origin"])]
+ (when-not (or (approved-mcp-origin? origin)
+ (if-let [instance-origin (mw.security/site-origin)]
+ (same-origin-as-instance? origin instance-origin)
+ (same-origin-host? origin (get-in request [:headers "host"]))))
+ (json-response 403 (jsonrpc-error nil -32600 "Origin not allowed")))))
+
+(defn- require-valid-session
+ "Validate the Mcp-Session-Id header value. Checks UUID format and, when a
+ `core_session` has been materialized, verifies it belongs to `user-id`."
+ [user-id session-id]
+ (cond
+ (str/blank? session-id)
+ {:error (json-response 400 (jsonrpc-error nil -32600 "Missing Mcp-Session-Id header"))}
+
+ (not (mcp.session/valid-id? session-id))
+ {:error (json-response 404 (jsonrpc-error nil -32600 "Invalid or expired session"))}
+
+ (not (mcp.session/owned-by-user? session-id user-id))
+ {:error (json-response 404 (jsonrpc-error nil -32600 "Invalid or expired session"))}
+
+ :else
+ {:session-id session-id}))
+
+;;; -------------------------------------------------- Handlers ---------------------------------------------------
+
+(defn- handle-post
+ "Handle a POST request containing one or more JSON-RPC messages."
+ [{:keys [dispatch-method-fn capabilities instructions]} user-id request]
+ (let [body (walk/keywordize-keys (:body request))
+ session-id (get-in request [:headers "mcp-session-id"])
+ eval-session-id (eval-session-override request)
+ batch? (sequential? body)
+ valid-message? (fn [message]
+ (and (map? message)
+ (= "2.0" (:jsonrpc message))
+ (string? (:method message))))]
+ (cond
+ (nil? body)
+ (json-response 400 (jsonrpc-error nil -32700 "Parse error: empty body"))
+
+ (and (not batch?)
+ (or (not (valid-message? body))
+ (and (= "initialize" (:method body))
+ (not (contains? body :id)))))
+ (json-response 400 (jsonrpc-error nil -32600 "Invalid request"))
+
+ ;; JSON-RPC 2.0: empty batch is invalid
+ (and batch? (empty? body))
+ (json-response 400 (jsonrpc-error nil -32600 "Invalid request: empty batch"))
+
+ ;; MCP spec: "The initialize request MUST NOT be part of a JSON-RPC batch"
+ (and batch? (some #(and (valid-message? %) (= "initialize" (:method %))) body))
+ (json-response 400 (jsonrpc-error nil -32600 "initialize must not be batched"))
+
+ ;; Initialize: create session and return response with session header
+ (and (not batch?) (valid-message? body) (= "initialize" (:method body)))
+ (let [params (:params body)
+ supports-mcp-ui? (mcp-app-ui-capability? params)
+ session-id (mcp.session/create! user-id {:supports-mcp-ui?
+ supports-mcp-ui?})
+ init-response (handle-initialize (:id body) params capabilities instructions)]
+ ;; Record the session row (EE-only, best-effort). Identity + PII are captured once
+ ;; here, from the on-thread request, and never overwritten.
+ (mcp.usage/record-mcp-session!
+ {:session-id session-id
+ :user-id user-id
+ :tenant-id (some-> api/*current-user* deref :tenant_id)
+ :client-info (:clientInfo params)
+ :user-agent (get-in request [:headers "user-agent"])
+ :ip-address (request/ip-address request)})
+ (if (accepts-sse? request)
+ (sse-response [init-response] {"Mcp-Session-Id" session-id})
+ (json-response 200 init-response {"Mcp-Session-Id" session-id})))
+
+ ;; All other requests require a valid session
+ :else
+ (let [{:keys [error]} (require-valid-session user-id session-id)]
+ (if error
+ error
+ (let [messages (if batch? body [body])
+ ;; Captured on-thread from the request so each tool-call row can denormalize IP/UA
+ ;; (gated PII) alongside client identity — the view no longer joins the session.
+ request-context {:user-agent (get-in request [:headers "user-agent"])
+ :ip-address (request/ip-address request)}
+ ;; Validate each batch element independently (JSON-RPC 2.0 §6). A request must be an object with
+ ;; `jsonrpc: "2.0"` and a string `method`; anything else is Invalid Request. Without this check,
+ ;; non-object elements dispatch to a nil method and disappear through `keep`, while objects missing
+ ;; `method` become method-not-found responses. Invalid Request uses a null id because §5 reserves
+ ;; that value for requests whose ids cannot be established.
+ ;; A message carrying no `id` is a NOTIFICATION (§4.1) and gets no reply, whatever it
+ ;; dispatches to. It still executes — a notification is a request the client is not waiting on,
+ ;; not one to ignore — but its result is dropped rather than answered. Distinct from the
+ ;; malformed case above, which does reply with a null id: §5 reserves that for a message that
+ ;; could not be parsed, and using it for a well-formed notification invents a response to
+ ;; something nobody is listening for.
+ notification? (fn [msg] (and (map? msg) (not (contains? msg :id))))
+ handle-msg (fn [msg]
+ (cond
+ (not (valid-message? msg))
+ (jsonrpc-error nil -32600 "Invalid request")
+
+ :else
+ (let [response (dispatch-request dispatch-method-fn msg session-id
+ (:token-scopes request) request-context
+ eval-session-id)]
+ (when-not (notification? msg)
+ response))))
+ responses (into [] (keep handle-msg) messages)]
+ (cond
+ (empty? responses)
+ {:status 202 :headers {} :body ""}
+
+ (accepts-sse? request)
+ (sse-response responses)
+
+ (and (not batch?) (= 1 (count responses)))
+ (json-response 200 (first responses))
+
+ :else
+ (json-response 200 responses))))))))
+
+(def ^:private tools-list-changed-notification
+ {:jsonrpc "2.0" :method "notifications/tools/list_changed"})
+
+(def ^:private keepalive-interval-ms
+ "How often the GET stream emits an SSE comment. Clients drop an idle stream without periodic traffic, so this
+ cadence is a protocol obligation and not tunable downward for the sake of cancellation latency."
+ 30000)
+
+(defonce ^:private ^ExecutorService keepalive-executor
+ ;; A keepalive stream blocks for the life of the client's connection, not the life of a query. Running it on the
+ ;; shared streaming-response pool — a fixed pool of `mb-jetty-maxthreads`/50 threads that also serves query
+ ;; downloads — lets a handful of idle MCP sessions occupy every thread and stall exports instance-wide. Virtual
+ ;; threads have no such ceiling and cost nothing while parked.
+ (Executors/newThreadPerTaskExecutor (.. (Thread/ofVirtual) (name "mcp-keepalive-" 0) factory)))
+
+(defn- keepalive-loop!
+ "Emit SSE keepalive comments on `writer` every `interval-ms` until `canceled-chan` reports the client is gone.
+ Re-reads the tool manifest hash on each tick and emits `notifications/tools/list_changed` when it differs from the
+ previous tick, so the client knows to refetch `tools/list`. Returns nil once canceled."
+ [^Writer writer tools-hash-fn token-scopes canceled-chan interval-ms]
+ (loop [last-hash (tools-hash-fn token-scopes)]
+ (.write writer ": keepalive\n\n")
+ (.flush writer)
+ ;; Park on the cancellation channel instead of sleeping through the interval: the cancel loop notices a
+ ;; disconnected client within a second, and waiting on it releases this thread then rather than at the next tick.
+ (let [[_ port] (a/alts!! [canceled-chan (a/timeout interval-ms)])]
+ (when-not (= port canceled-chan)
+ (let [current-hash (tools-hash-fn token-scopes)]
+ (when (not= current-hash last-hash)
+ (.write writer ^String (sse-body [tools-list-changed-notification]))
+ (.flush writer))
+ (recur current-hash))))))
+
+(def ^:private max-concurrent-keepalive-streams
+ "How many GET keepalive streams one user may hold open at once.
+
+ Running the loop on virtual threads (see [[keepalive-executor]]) removed the only ceiling these streams had:
+ the fixed streaming pool refused work past its size, whereas a virtual thread costs nothing to park. A stream
+ is held for as long as the client keeps it and costs a single throttle attempt to open, so nothing else bounds
+ how many one credential can accumulate — and every one of them holds a connection.
+
+ The cap is per-user rather than global so a single caller cannot crowd everyone else off the surface. It is set
+ well above real use: a client opens one stream per MCP session, and the throttle's own sizing assumes a handful
+ of concurrent agents."
+ 25)
+
+(defonce ^:private keepalive-stream-counts
+ (atom {}))
+
+(def ^:private keepalive-cap-error
+ "The JSON-RPC error every keepalive refusal carries, whether it goes out as a 429 body or as an SSE frame on a
+ stream whose headers are already sent."
+ (jsonrpc-error nil -32000
+ (str "Too many concurrent MCP event streams open for this user "
+ "(limit " max-concurrent-keepalive-streams
+ "). Close an existing stream before opening another.")))
+
+(defn- at-keepalive-cap?
+ "Is `user-id` already holding [[max-concurrent-keepalive-streams]] running streams?
+
+ Read-only on purpose: `handle-get` decides whether to serve from this, but takes nothing. Only a stream that
+ is actually running holds a slot ([[acquire-keepalive-slot!]] is called from the body), so a connection that
+ dies during setup has nothing to leak. The cost is that two simultaneous connects can both read under the cap
+ and both proceed — over-admitting by a few is the right trade for a resource cap that must never wedge shut. A
+ connection that loses that race is refused by [[keepalive-stream-body!]] instead, on the stream itself."
+ [user-id]
+ (>= (get @keepalive-stream-counts user-id 0) max-concurrent-keepalive-streams))
+
+(defn- acquire-keepalive-slot!
+ "Take a keepalive slot for `user-id`, returning true when taken and false when they are already at
+ [[max-concurrent-keepalive-streams]]. Called from the stream body, not from the handler — see
+ [[at-keepalive-cap?]]."
+ [user-id]
+ (let [[old new] (swap-vals! keepalive-stream-counts
+ (fn [counts]
+ (cond-> counts
+ (< (get counts user-id 0) max-concurrent-keepalive-streams)
+ (update user-id (fnil inc 0)))))]
+ (not= (get old user-id 0) (get new user-id 0))))
+
+(defn- release-keepalive-slot!
+ "Return one of `user-id`'s keepalive slots. A user back at zero is dropped from the map rather than left as an
+ entry, so the map tracks live streams and not every user the process has ever served. Releasing more than was
+ acquired cannot drive the count negative — that would hand the user free slots on top of the cap."
+ [user-id]
+ (swap! keepalive-stream-counts
+ (fn [counts]
+ (let [remaining (dec (get counts user-id 0))]
+ (if (pos? remaining)
+ (assoc counts user-id remaining)
+ (dissoc counts user-id)))))
+ nil)
+
+(defn- keepalive-stream-body!
+ "Take `user-id`'s keepalive slot, run [[keepalive-loop!]], and return the slot however the loop ends —
+ normally, on client disconnect, or by throwing.
+
+ The slot is taken HERE rather than in the handler so that it exists only for a stream that is actually
+ running: streaming-response reports a setup failure by neither throwing out of `send*` nor calling `raise`
+ (its `Sendable` impl ignores `raise` entirely, and its own catch sends a 500 and closes its channels), so a
+ handler that took the slot up front could never learn to give it back, and the cap would wedge shut a
+ connection at a time.
+
+ A slot can be missing here even though `handle-get` read the user as under the cap: that read is advisory, so
+ racing connects can both pass it and one of them loses the slot. Refuse in band rather than by returning, since
+ status 200 and the SSE headers are already on the wire by the time the body runs."
+ [user-id ^Writer writer tools-hash-fn token-scopes canceled-chan interval-ms]
+ (if (acquire-keepalive-slot! user-id)
+ (try
+ (keepalive-loop! writer tools-hash-fn token-scopes canceled-chan interval-ms)
+ (finally
+ (release-keepalive-slot! user-id)))
+ (do
+ (.write writer ^String (sse-body [keepalive-cap-error]))
+ (.flush writer))))
+
+(defn- handle-get
+ "Handle a GET request for SSE stream (keepalive for server-initiated notifications).
+ Polls the tool manifest hash on each keepalive tick — if the visible tool set has
+ changed since the previous tick, emits an MCP `notifications/tools/list_changed`
+ message so the client knows to refetch `tools/list`. Stateless: each connection
+ tracks its own last-seen hash; no shared registry."
+ [tools-hash-fn user-id request respond raise]
+ (let [session-id (get-in request [:headers "mcp-session-id"])
+ token-scopes (:token-scopes request)
+ {:keys [error]} (require-valid-session user-id session-id)]
+ (cond
+ (some? error)
+ (respond error)
+
+ (at-keepalive-cap? user-id)
+ (respond (json-response 429 keepalive-cap-error))
+
+ :else
+ ;; No slot is taken here — `keepalive-stream-body!` takes and returns it, so a connection that dies
+ ;; during streaming-response setup leaves nothing behind.
+ (let [resp (streaming-response/streaming-response
+ {:content-type "text/event-stream"
+ :headers {"Cache-Control" "no-cache"}
+ :status 200
+ :executor keepalive-executor}
+ [os canceled-chan]
+ (keepalive-stream-body! user-id
+ (BufferedWriter. (OutputStreamWriter. os StandardCharsets/UTF_8))
+ tools-hash-fn token-scopes canceled-chan keepalive-interval-ms))]
+ (compojure.response/send* resp request respond raise)))))
+
+(defn- handle-delete
+ "Handle a DELETE request by validating the session, then reporting that client-initiated termination is unsupported."
+ [user-id request]
+ (let [session-id-header (get-in request [:headers "mcp-session-id"])
+ {:keys [error]} (require-valid-session user-id session-id-header)]
+ (or error
+ {:status 405 :headers {"Allow" "GET, POST"} :body ""})))
+
+;;; -------------------------------------------------- Throttling --------------------------------------------------
+
+;; MCP is auth-gated (session cookie or bearer token), so the risk is lower than the
+;; unauthenticated OAuth endpoints. The threshold is generous to accommodate users running
+;; multiple concurrent agents (e.g. 5 agents × 200 req/min). throttle/check records every
+;; attempt (not just failures) which is correct here — we want to cap total throughput
+;; regardless of success to prevent resource exhaustion from a compromised token.
+;; One throttler covers every surface built on THIS transport. During the v1 migration that is v2 only —
+;; v1 carries its own copy of this namespace and its own throttler, so a user's total MCP throughput is
+;; currently two caps, not one. That collapses to a single cap when v1's transport is deleted.
+;; The cap counts JSON-RPC *messages*, not HTTP requests: a POST can carry a batch, so charging
+;; one attempt per request would let a 1000-message batch cost a single attempt and defeat the cap
+;; (see [[check-throttle]]/[[jsonrpc-message-count]]).
+(def ^:private one-minute-ms (* 60 1000))
+
+(def ^:private mcp-throttler
+ (throttle/make-throttler :user-id :attempts-threshold 1000 :attempt-ttl-ms one-minute-ms))
+
+(defn- jsonrpc-message-count
+ "How many throttle attempts a request costs: the number of JSON-RPC messages it carries. A batch (array body) costs
+ one per element; any other request — a single message, or a malformed/empty body still worth one unit of work —
+ costs one. The body has already been parsed to Clojure data by the JSON middleware, so this reads it directly."
+ [request]
+ (let [body (:body request)]
+ (if (sequential? body)
+ (max 1 (count body))
+ 1)))
+
+(defn- check-throttle
+ "Charge `n` throttle attempts for `user-id` (one per JSON-RPC message in the request). Returns a 429 JSON-RPC
+ response if the cap is hit partway through, nil otherwise. Checking N up front means a batch is refused before any
+ of its messages run; `throttle/check` throws before recording the attempt, so a batch that trips on element k has
+ charged only the k-1 attempts before it."
+ [user-id n]
+ (try
+ (dotimes [_ n]
+ (throttle/check mcp-throttler user-id))
+ nil
+ (catch clojure.lang.ExceptionInfo e
+ (let [message (ex-message e)
+ retry-seconds (some->> message (re-find #"(\d+) seconds") second)]
+ (cond-> (json-response 429 (jsonrpc-error nil -32000 message))
+ retry-seconds (assoc-in [:headers "Retry-After"] retry-seconds))))))
+
+;;; ---------------------------------------------------- Handler ---------------------------------------------------
+
+(defn- www-authenticate-discovery
+ "Build the `WWW-Authenticate` header advertising OAuth discovery for the path the client hit.
+ A client connecting via an alias is pointed at that same alias as the protected resource;
+ any other path falls back to `default-path` (the surface's canonical URL).
+
+ `default-ask-scopes`, when non-empty, is emitted as the challenge's `scope` parameter."
+ [endpoint-paths default-path default-ask-scopes request]
+ ;; Routing matches on the first path segment, so a trailing slash (e.g. `/api/metabase-mcp/`) still
+ ;; reaches the handler — strip it so the alias is recognized rather than falling back to canonical.
+ (let [uri (str/replace (:uri request) #"/+$" "")
+ path (if (contains? endpoint-paths uri) uri default-path)]
+ ;; Comma-separated per RFC 7235's `#auth-param`. Both MCP SDKs currently pull each parameter
+ ;; with an unanchored per-field regex and would accept spaces, but every spec and vendor example
+ ;; uses commas and the stricter parsers proposed upstream would not.
+ (str "Bearer realm=\"mcp\", resource_metadata=\"" (system/site-url) "/.well-known/oauth-protected-resource" path "\""
+ ;; A client that reads this prefers it over the resource metadata's `scopes_supported`,
+ ;; which is what lets a surface ask for less than it accepts: the wider set stays
+ ;; advertised and requestable, this is only what an uninstructed client asks for.
+ (when (seq default-ask-scopes)
+ (str ", scope=\"" (str/join " " default-ask-scopes) "\"")))))
+
+(defn make-handler
+ "Build a Ring async handler for one MCP surface. Uses JSON-RPC 2.0 over HTTP rather than REST,
+ so the OpenAPI spec is empty.
+
+ Options:
+ - `:dispatch-method-fn` — `(fn [id method params session-id token-scopes request-context])`
+ returning a JSON-RPC response map, or nil for notifications. `initialize` is handled by the
+ transport itself and never reaches this fn.
+ - `:capabilities` — the server capabilities the `initialize` handshake advertises. Must match
+ what `:dispatch-method-fn` actually serves (e.g. advertise `:resources` only when the
+ surface dispatches `resources/*`).
+ - `:instructions` — optional string returned as the `initialize` result's `instructions`
+ field, surfaced to the model by clients that support it.
+ - `:tools-hash-fn` — `(fn [token-scopes])` returning a stable hash of the visible tool set,
+ polled by the GET/SSE keepalive to emit `notifications/tools/list_changed`.
+ - `:endpoint-paths` — the URL paths (relative to site-url) the 401 `WWW-Authenticate`
+ challenge matches the request URI against. NOT necessarily all served by this surface:
+ during the migration the set includes v1's paths — see [[metabase.mcp.paths/endpoint-paths]].
+ - `:default-path` — the canonical path advertised when the request URI matches no entry in
+ `:endpoint-paths`.
+ - `:default-ask-scopes` — optional scopes emitted as the `scope` parameter of the 401
+ `WWW-Authenticate` challenge, i.e. what a client that has not been told otherwise asks for.
+ Omit to let clients ask for everything the resource metadata advertises."
+ [{:keys [tools-hash-fn endpoint-paths default-path default-ask-scopes] :as opts}]
+ (open-api/handler-with-open-api-spec
+ (fn [request respond raise]
+ (let [origin-error (validate-origin request)
+ bearer-token (oauth-server/extract-bearer-token request)
+ session-auth api/*current-user-id*
+ token-scopes (:token-scopes request)]
+ (letfn [(dispatch [user-id token-scopes]
+ (request/with-current-user user-id
+ ;; Charge the throttle per JSON-RPC message, not per HTTP request, so a batch can't smuggle many
+ ;; messages past the per-minute cap on one attempt. GET/DELETE carry no batch and cost one.
+ (if-let [throttle-err (check-throttle user-id (jsonrpc-message-count request))]
+ (respond throttle-err)
+ (try
+ (let [request (assoc request :token-scopes token-scopes)]
+ (cond
+ (= :post (:request-method request))
+ (respond (handle-post opts user-id request))
+
+ (= :get (:request-method request))
+ (handle-get tools-hash-fn user-id request respond raise)
+
+ (= :delete (:request-method request))
+ (respond (handle-delete user-id request))
+
+ :else
+ (respond (json-response 405 (jsonrpc-error nil -32600 "Method not allowed")))))
+ (catch Throwable e
+ (raise e))))))]
+ (cond
+ (some? origin-error)
+ (respond origin-error)
+
+ ;; Respect the scope set attached to an authenticated request. Sessions without one
+ ;; retain unrestricted access.
+ session-auth
+ ;; An OAuth bearer request lands here too — the session middleware resolves the token and
+ ;; attaches `:token-scopes`, so this branch is not "cookie sessions only".
+ (dispatch session-auth (or token-scopes #{::scope/unrestricted}))
+
+ ;; A bearer token that reaches here did NOT authenticate upstream: the session middleware
+ ;; ([[metabase.server.middleware.session/current-user-info-for-oauth-token]]) resolves every *valid* bearer
+ ;; token — including checking `user.is_active` and running the granted scopes through the
+ ;; `oauth-token->token-scopes` trust hinge — and sets `*current-user-id*`, so an active user's token is
+ ;; served by the `session-auth` branch above. Landing here therefore means the token is unknown, expired,
+ ;; revoked, or names a DEACTIVATED user. We must not re-resolve and dispatch it: doing so bypassed the
+ ;; active-user check (a disabled user's token still authenticated) and the scope trust hinge (raw token
+ ;; scopes dispatched verbatim). Return the RFC 6750 `invalid_token` 401 and dispatch nothing.
+ bearer-token
+ ;; RFC 6750 `invalid_token`, still carrying the RFC 9728 discovery parameters: a client whose
+ ;; token expired re-discovers the protected-resource metadata from this 401 (MCP auth spec MUST).
+ (respond (json-response 401 (jsonrpc-error nil -32603 "Invalid bearer token")
+ {"WWW-Authenticate" (str (www-authenticate-discovery endpoint-paths default-path
+ default-ask-scopes request)
+ ", error=\"invalid_token\"")}))
+
+ ;; No auth at all — return 401 with discovery
+ :else
+ (respond (json-response 401 (jsonrpc-error nil -32603 "Authentication required")
+ {"WWW-Authenticate" (www-authenticate-discovery endpoint-paths default-path
+ default-ask-scopes request)}))))))
+ (constantly nil)))
diff --git a/src/metabase/mcp/ui_resource.clj b/src/metabase/mcp/ui_resource.clj
new file mode 100644
index 00000000000..29b15b97e7c
--- /dev/null
+++ b/src/metabase/mcp/ui_resource.clj
@@ -0,0 +1,187 @@
+(ns metabase.mcp.ui-resource
+ "Primitives for MCP Apps UI resources — the sandboxed iframe surface
+ [[metabase.mcp.v2.resources]] exposes: rendering the embed template and computing the
+ `_meta.ui` block hosts use to configure the iframe sandbox."
+ (:require
+ [clojure.java.io :as io]
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [environ.core :as env]
+ [metabase.config.core :as config]
+ [metabase.request.core :as request]
+ [metabase.system.core :as system]
+ [metabase.util.json :as json]
+ [stencil.core :as stencil])
+ (:import
+ (java.net URI)))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private embed-mcp-template-path "frontend_client/embed-mcp.html")
+
+;; The built template is emitted by HtmlWebpackPlugin into resources/frontend_client/
+;; during the frontend build. Backend-only test runs (e.g. CI app-db tests) don't produce
+;; it, so tests install a minimal inline template via `with-fallback-template`.
+(def ^:private test-fallback-template
+ (str "<!doctype html><html><head><base href=\"{{{instanceUrlRaw}}}/\"></head><body><script>"
+ "window.metabaseConfig = {"
+ "instanceUrl: {{{instanceUrl}}},"
+ "uiCredential: {{{uiCredential}}}"
+ "};</script></body></html>"))
+
+;; An atom rather than a dynamic var because `resources/read` is invoked from the
+;; HTTP handler thread, which doesn't inherit thread-local bindings from the test
+;; thread that installs the fallback.
+(defonce ^:private fallback-template (atom nil))
+
+(defn do-with-fallback-template
+ "Implementation detail of [[with-fallback-template]]."
+ [thunk]
+ (try
+ (reset! fallback-template test-fallback-template)
+ (thunk)
+ (finally
+ (reset! fallback-template nil))))
+
+(defmacro with-fallback-template
+ "Test-only: install an inline Mustache fallback for the embed-mcp template for
+ the duration of `body`. Backend-only test runs don't produce the built template,
+ so tests that exercise `resources/read` need this."
+ [& body]
+ `(do-with-fallback-template (fn [] ~@body)))
+
+(defn render-embed-mcp-template
+ "Render the embed-mcp.html Mustache template with the given vars map.
+ Expected keys: :instanceUrl (JSON-encoded), :instanceUrlRaw, :uiCredential (JSON-encoded or nil),
+ :mcpSessionId (JSON-encoded or nil). The production template has had no credential or session-id
+ placeholder since #81041 — the iframe fetches its credential through the `refresh_ui_credential`
+ tool — so those two keys only render into the test fallback template."
+ [vars]
+ (cond
+ (io/resource embed-mcp-template-path)
+ (stencil/render-file embed-mcp-template-path vars)
+
+ @fallback-template
+ (stencil/render-string @fallback-template vars)
+
+ :else
+ (throw (ex-info (str "Missing MCP embed template: " embed-mcp-template-path
+ ". Run the frontend build to produce it.")
+ {:path embed-mcp-template-path}))))
+
+(defn- chatgpt-client?
+ "True when the in-flight request's User-Agent identifies the ChatGPT MCP/Apps
+ client. ChatGPT empirically sends `openai-mcp/...`; Claude rejects
+ `_meta.ui.domain` unless it's a Claude-issued subdomain, so we gate the field
+ on this check."
+ []
+ (boolean (some-> (request/current-request)
+ (get-in [:headers "user-agent"])
+ (str/includes? "openai-mcp"))))
+
+(defn- site-origin
+ "Origin (scheme://host[:port]) extracted from `site-url`, dropping any path segment.
+ ChatGPT's MCP host treats `_meta.ui.domain` and the CSP domain lists as origins, so an instance
+ hosted under a subpath would otherwise leak the path and fail validation. Returns nil when
+ `site-url` is unset — callers degrade gracefully rather than NPE on a misconfigured instance."
+ []
+ (when-let [url (system/site-url)]
+ (let [^URI uri (URI. url)
+ scheme (.getScheme uri)
+ host (.getHost uri)
+ port (.getPort uri)]
+ (cond-> (str scheme "://" host)
+ (not (neg? port)) (str ":" port)))))
+
+(defn- resource-domains
+ [url]
+ (cond-> [url]
+ config/is-dev? (conj (str "http://localhost:" (or (env/env :mb-frontend-dev-port) "8080")))))
+
+(defn ui-meta
+ "MCP `_meta.ui` block returned alongside UI resources.
+ Hosts that render the resource in a sandboxed iframe (notably ChatGPT's MCP app surface) use this
+ to pick a sandbox configuration:
+
+ - `prefersBorder` — presentation hint asking the host to draw a frame border
+ - `domain` — origin the iframe content is anchored at. ChatGPT-only:
+ Claude validates this against its own namespace
+ (`*.claudemcpcontent.com`) and rejects anything else,
+ so we emit it only for ChatGPT (gated by [[chatgpt-client?]]).
+ - `csp.baseUriDomains` — hosts the iframe may use in its document `<base>` tag
+ (relative bundle assets resolve against the Metabase instance)
+ - `csp.connectDomains` — hosts the iframe may XHR/fetch/WebSocket to
+ (the embedded SDK calls back to this Metabase instance)
+ - `csp.resourceDomains` — hosts the iframe may load scripts/styles/images from
+ (the SDK bundle is served from this Metabase instance)
+
+ `frameDomains` is intentionally omitted — we don't nest iframes inside the visualization, and leaving
+ it out narrows the CSP for security review."
+ [resource]
+ (let [url (site-origin)]
+ {:ui (cond-> {:csp {:baseUriDomains [url]
+ :connectDomains [url]
+ :resourceDomains (resource-domains url)}}
+ (contains? resource :prefersBorder)
+ (assoc :prefersBorder (:prefersBorder resource))
+
+ (chatgpt-client?)
+ (assoc :domain url))}))
+
+;;; --------------------------------------------- Client extensions ------------------------------------------------
+
+(def ^:private extension-labels
+ "Human-readable labels for required-extension keywords in tool-call error messages."
+ {:mcp-app-ui "MCP Apps UI"})
+
+(def known-extensions
+ "Every client extension a tool may gate on. A tool requiring anything outside this set could never be
+ listed or called, since [[supported-extensions]] can only ever report these."
+ #{:mcp-app-ui})
+
+(defn supported-extensions
+ "The extension keywords the calling client advertised, from a tool-dispatch options map."
+ [{:keys [supports-mcp-ui?]}]
+ (if supports-mcp-ui?
+ #{:mcp-app-ui}
+ #{}))
+
+(defn missing-required-extensions
+ "The extensions `tool` requires that `supported-extensions` doesn't provide, or nil when the
+ client can render it. A tool with no `:required-extensions` is always renderable."
+ [tool supported-extensions]
+ (set/difference (:required-extensions tool #{}) supported-extensions))
+
+(defn missing-extensions-error
+ "Teaching message for a tool call the client can't render."
+ [tool-name missing-extensions]
+ (let [extension-names (str/join ", " (map #(get extension-labels % (name %)) missing-extensions))]
+ (str tool-name " requires a client that supports " extension-names ". "
+ "Reconnect from a client that advertises text/html;profile=mcp-app.")))
+
+(defn embed-render-fn
+ "Build a `:render-fn` that serves the MCP Apps iframe shell.
+
+ `tag` is a per-URI marker embedded in the rendered HTML so distinct URIs hash to distinct
+ bytes — ChatGPT's asset CDN appears to dedupe by body hash, and without distinct bodies the
+ second URI's asset is silently dropped and the widget 404s. (Its host also dedupes by
+ `_meta.ui.resourceUri`, which is why each UI tool gets its own URI in the first place.)
+
+ The returned fn takes the `resources/read` options map: `:ui-credential` (the scoped credential
+ the iframe authenticates with, as a delay — forcing it here is what mints one, so resources that
+ do not embed a credential never cause one to exist) and `:session-id` (the MCP session id it
+ echoes back on callbacks). Since #81041 the production template discards both — the iframe
+ fetches its credential through the `refresh_ui_credential` tool — so on a production shell read
+ the minted credential (HMAC-only, no DB row) is unused; the test fallback template still embeds
+ it, which is what the shell-credential tests exercise."
+ [tag]
+ (fn [opts]
+ (let [site-url (system/site-url)
+ ui-credential (force (:ui-credential opts))
+ session-id (:session-id opts)]
+ (str "<!-- metabase-mcp-asset: " tag " -->\n"
+ (render-embed-mcp-template
+ {:instanceUrl (json/encode site-url)
+ :instanceUrlRaw site-url
+ :uiCredential (when ui-credential (json/encode ui-credential))
+ :mcpSessionId (when session-id (json/encode session-id))})))))
diff --git a/src/metabase/mcp/ui_surface.clj b/src/metabase/mcp/ui_surface.clj
new file mode 100644
index 00000000000..c6c6e8c23d9
--- /dev/null
+++ b/src/metabase/mcp/ui_surface.clj
@@ -0,0 +1,74 @@
+(ns metabase.mcp.ui-surface
+ "The server-side API surface an MCP Apps UI credential may reach, and what each route on it costs.
+
+ A UI credential is deliberately not a general Metabase API credential. It is minted from an MCP session
+ whose token may hold nothing but `agent:query:run`, so what it reaches has to be decided here rather than
+ inherited from whatever the embedded app happens to call."
+ (:require
+ [metabase.api.macros.scope :as scope]
+ [metabase.metabot.scope :as metabot.scope]))
+
+(set! *warn-on-reflection* true)
+
+(def request-surface
+ "`[method uri]` -> the scope the minting MCP session must hold to use that route, or nil when holding a valid
+ credential is the whole requirement.
+
+ Two gates, not one. A route absent from the surface is not authenticated at all: the credential resolver
+ returns nil and the request falls through as anonymous. A route present on it is served only while the
+ credential's signed scope claim satisfies the value; otherwise the request is authenticated but not
+ scope-checked, and `ensure-scopes-checked` refuses it. Adding a route is therefore a decision about which
+ scope pays for it, and a route reached by mistake — a routing change, a new alias — fails closed.
+
+ `agent:query:run` is the scope that already bought the iframe: the v2 shell resources in
+ [[metabase.mcp.v2.resources]] declare it, so a client that can mount the iframe at all holds it."
+ {[:get "/api/embed-mcp/bootstrap"] nil
+ [:post "/api/embed-mcp/feedback"] nil
+ [:post "/api/embed-mcp/drills"] metabot.scope/agent-query-run
+ [:post "/api/dataset"] metabot.scope/agent-query-run
+ [:post "/api/dataset/pivot"] metabot.scope/agent-query-run
+ [:post "/api/dataset/query_metadata"] metabot.scope/agent-query-run
+ [:post "/api/dataset/parameter/remapping"] metabot.scope/agent-query-run})
+
+(def parameterized-request-surface
+ "The part of the surface whose uri carries a path parameter, and so cannot be written as a literal
+ `[method uri]` pair. Values mean what they do in [[request-surface]]: the scope the route costs, or nil.
+
+ Each regex must match the whole uri and pin every path segment it does not parameterize, so an entry
+ here stays exactly as narrow as a literal one."
+ {[:get #"/api/embed-mcp/queries/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"]
+ metabot.scope/agent-query-run})
+
+(defn- surface-entry
+ "The map entry for `method` + `uri` from either surface, or nil when the route is on neither.
+
+ The entry's value is what the route costs, so a free route is still an entry: nil from this fn means
+ off-surface, never free."
+ [method uri]
+ (or (find request-surface [method uri])
+ (some (fn [[[entry-method pattern] :as entry]]
+ (when (and (= entry-method method)
+ (re-matches pattern uri))
+ entry))
+ parameterized-request-surface)))
+
+(defn on-surface?
+ "Whether a UI credential may authenticate `method` + `uri` at all."
+ [method uri]
+ (some? (surface-entry method uri)))
+
+(defn scope-satisfied?
+ "Whether a credential with `claims` may be served `method` + `uri`.
+
+ Credentials minted before the scope claim existed decode to an empty scope set, so a rolling deploy
+ degrades a credential to the routes that cost no scope rather than to full access.
+
+ `::scope/unrestricted` in the claim satisfies every route, matching `enforce-scope` and
+ `ensure-scopes-checked` rather than making this table the one place the sentinel means less. It only
+ appears when the minting MCP session was itself unrestricted — a cookie-authenticated caller — so the
+ credential reaches nothing its holder could not already reach with their own session."
+ [method uri {:keys [token-scopes]}]
+ (when-let [entry (surface-entry method uri)]
+ (boolean (or (nil? (val entry))
+ (contains? token-scopes ::scope/unrestricted)
+ (scope/scope-satisfied? token-scopes (val entry))))))
diff --git a/src/metabase/mcp/v2/api.clj b/src/metabase/mcp/v2/api.clj
new file mode 100644
index 00000000000..2bc29dc76e6
--- /dev/null
+++ b/src/metabase/mcp/v2/api.clj
@@ -0,0 +1,153 @@
+(ns metabase.mcp.v2.api
+ "The MCP tool surface mounted on every path in
+ [[metabase.mcp.paths/endpoint-paths]]. [[metabase.mcp.transport]] supplies the JSON-RPC framing,
+ origin checks, cookie/bearer auth, session handling, and throttling; `tools/list` and
+ `tools/call` are driven by the [[metabase.mcp.v2.registry]]. Gated by
+ [[metabase.mcp.validation/+mcp-enabled]]."
+ (:require
+ [clojure.string :as str]
+ [metabase.api.common :as api]
+ [metabase.mcp.paths :as mcp.paths]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.transport :as transport]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resources :as v2.resources]
+ ;; Tool namespaces self-register via `deftool` when loaded. The core surface ships with the `learn`
+ ;; hello-world tool; each later PR adds its tool's require line here alongside the tool file.
+ [metabase.mcp.v2.tools.alert]
+ [metabase.mcp.v2.tools.bookmark]
+ [metabase.mcp.v2.tools.browse]
+ [metabase.mcp.v2.tools.collection]
+ [metabase.mcp.v2.tools.content]
+ [metabase.mcp.v2.tools.dashboard]
+ [metabase.mcp.v2.tools.definitions]
+ [metabase.mcp.v2.tools.document]
+ [metabase.mcp.v2.tools.duplicate]
+ [metabase.mcp.v2.tools.learn]
+ [metabase.mcp.v2.tools.metric]
+ [metabase.mcp.v2.tools.parameters]
+ [metabase.mcp.v2.tools.query]
+ [metabase.mcp.v2.tools.question]
+ [metabase.mcp.v2.tools.search]
+ [metabase.mcp.v2.tools.subscription]
+ [metabase.mcp.v2.tools.transform]
+ [metabase.mcp.v2.tools.ui-credential]
+ [metabase.mcp.v2.tools.visualize]
+ [metabase.mcp.validation :as mcp.validation]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------ Method dispatch -----------------------------------------------
+
+(defn- handle-tools-list [id _params session-id token-scopes]
+ (let [supports-mcp-ui? (mcp.session/supports-mcp-ui? session-id)]
+ (transport/jsonrpc-response id {:tools (registry/list-tools token-scopes
+ {:supports-mcp-ui? supports-mcp-ui?})})))
+
+(defn- handle-tools-call [id params session-id token-scopes request-context]
+ (let [tool-name (:name params)
+ arguments (or (:arguments params) {})
+ ;; RC clients carry their identity per-call in `_meta`; the usage recorder falls back to
+ ;; the session's stored identity when it's absent.
+ client-info (get-in params [:_meta :io.modelcontextprotocol/clientInfo])
+ supports-mcp-ui? (mcp.session/supports-mcp-ui? session-id)
+ {:keys [error result]}
+ (registry/call-tool token-scopes
+ session-id
+ tool-name
+ arguments
+ {:client-info client-info
+ :supports-mcp-ui? supports-mcp-ui?
+ :request-context request-context})]
+ (if-let [{:keys [code message]} error]
+ (transport/jsonrpc-error id code message)
+ (transport/jsonrpc-response id result))))
+
+(defn- handle-resources-list [id _params token-scopes]
+ (transport/jsonrpc-response id (v2.resources/list-resources token-scopes)))
+
+(defn- handle-resources-read [id params session-id token-scopes]
+ (let [uri (:uri params)]
+ (if (or (not (string? uri)) (str/blank? uri))
+ (transport/jsonrpc-error id -32602 "Missing required parameter: uri")
+ ;; The scoped credential the iframe authenticates with. Since #81041 the browser receives it
+ ;; through the `refresh_ui_credential` tool; the shell's render-fn still forces this delay for
+ ;; templates that embed it (the test fallback), and the production template discards it.
+ ;; Deliberately a delay: the URI has not been resolved yet, so minting eagerly would hand a live
+ ;; 5-minute authenticator to data resources that ignore it, and burn one on reads that turn out
+ ;; to be unknown or scope-denied. Only [[metabase.mcp.ui-resource/embed-render-fn]] forces it,
+ ;; and only after the scope gate has passed.
+ (let [user-id api/*current-user-id*
+ ui-credential (when user-id
+ (delay (mcp.session/issue-ui-credential session-id user-id token-scopes)))
+ result (v2.resources/read-resource uri token-scopes {:ui-credential ui-credential
+ :session-id session-id})]
+ (case (:status result)
+ ;; Collapsed so a scope-denied read can't be used to probe which resources exist.
+ (:not-found :scope-denied) (transport/jsonrpc-error id -32602 "Resource not found")
+ :ok (transport/jsonrpc-response id {:contents (:contents result)})
+ (transport/jsonrpc-error id -32603 (str "Unexpected resource status: " (:status result))))))))
+
+(defn- handle-ping [id _params]
+ (transport/jsonrpc-response id {}))
+
+(defn- dispatch-method
+ "Route a single JSON-RPC `method` to its handler, returning a response map or nil
+ (notifications). `resources/*` serves the MCP Apps iframe shells only; documentation and skill
+ resources land with the skills work. `prompts/*` is still unimplemented and falls through to
+ method-not-found. A handler that throws is turned into a JSON-RPC internal error by the
+ transport."
+ [id method params session-id token-scopes request-context]
+ (case method
+ "notifications/initialized" nil
+ "tools/list" (handle-tools-list id params session-id token-scopes)
+ "tools/call" (handle-tools-call id params session-id token-scopes request-context)
+ "resources/list" (handle-resources-list id params token-scopes)
+ "resources/read" (handle-resources-read id params session-id token-scopes)
+ "ping" (handle-ping id params)
+ (if id
+ (transport/jsonrpc-error id -32601 (str "Method not found: " method))
+ nil)))
+
+;;; ---------------------------------------------------- Handler ---------------------------------------------------
+
+(def +mcp-enabled
+ "Wrap routes so they may only be accessed when the MCP server is enabled."
+ mcp.validation/+mcp-enabled)
+
+(def ^:private server-instructions
+ "The `initialize` result's `instructions` — the only channel that reaches the model before any tool call, so it points
+ at the `learn` skills once, in three lines."
+ (str "This server ships task-shaped docs as skills. learn() lists the topics; learn(topic) returns one.\n"
+ "Before your first complex write — native template_tags, dashboard parameter wiring, an MBQL query, "
+ "visualization settings — read the matching skill unless it is already in context.\n"
+ "Teaching errors embed the relevant contract, so a failed call always names its fix."))
+
+(def ^:private default-ask-scopes
+ "What an uninstructed client is asked to request for this surface: everything the surface accepts.
+
+ A client asks once, at connect time, using this challenge — and `list-tools` filters by the scopes the resulting
+ token carries. Asking for less therefore does not degrade gracefully: it hides the write tools from `tools/list`
+ entirely, so the user sees a read-only Metabase with nothing telling them the rest exists or how to ask for it.
+ There is no in-product path from \"connected\" to \"can write\".
+
+ So the consent screen names the full surface and the user decides there, rather than the server deciding for them
+ by omission. This is not a widening of what the surface accepts — that set is unchanged, and `mb:full` and the
+ rest of the agent-API scopes remain refused (GHY-4226).
+
+ Read from [[metabase.mcp.paths/v2-surface-scopes]] rather than listed here, because the OAuth server has to
+ grant exactly this set: when the two drifted, a client that followed the challenge asked for scopes
+ `validate-scope` rejected and the connect failed with \"Invalid scope\"."
+ mcp.paths/v2-surface-scopes)
+
+(def ^{:arglists '([request respond raise])} handler
+ "Ring async handler for the MCP endpoint."
+ (transport/make-handler
+ {:dispatch-method-fn dispatch-method
+ ;; No :prompts — a surface must not advertise methods it answers with method-not-found.
+ :capabilities {:tools {:listChanged true} :resources {}}
+ :instructions server-instructions
+ :tools-hash-fn registry/tools-hash
+ :endpoint-paths mcp.paths/endpoint-paths
+ :default-path mcp.paths/canonical-path
+ :default-ask-scopes default-ask-scopes}))
diff --git a/src/metabase/mcp/v2/common.clj b/src/metabase/mcp/v2/common.clj
new file mode 100644
index 00000000000..41e9ebd9493
--- /dev/null
+++ b/src/metabase/mcp/v2/common.clj
@@ -0,0 +1,389 @@
+(ns metabase.mcp.v2.common
+ "The v2 MCP tools' shared response conventions: the MCP response channels, the teaching-error
+ taxonomy, and message-shaping helpers. Sibling namespaces own the other shared machinery as
+ their first consumers land it (`v2.resolve` for id resolution, `v2.write` for `_write`
+ dispatch, `v2.queries` for the query pipeline). Tool namespaces add domain logic only and
+ never re-derive these shapes.
+
+ Scope-binding rule: scopes are never renamed. Issued OAuth tokens carry literal strings (a
+ token holding `agent:question:create` satisfies no other name), so renaming one strands every
+ existing token. Add new leaf scopes for net-new capability; never rename."
+ (:require
+ [clojure.string :as str]
+ [metabase.channel.urls :as channel.urls]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.util.log :as log])
+ (:import
+ (org.apache.commons.text.similarity LevenshteinDistance)))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------ Response channels ---------------------------------------------
+
+;; JSON-RPC error codes recorded as `mcp_tool_call_log.error_code` for failed tool calls.
+(def error-code-invalid-request
+ "JSON-RPC -32600: request rejected before dispatch (e.g. insufficient scope)." -32600)
+(def error-code-method-not-found
+ "JSON-RPC -32601: unknown or disabled tool." -32601)
+(def error-code-invalid-params
+ "JSON-RPC -32602: invalid arguments, including teaching errors and not-found." -32602)
+(def error-code-internal
+ "JSON-RPC -32603: unexpected server-side failure." -32603)
+
+(defn error-content
+ "Wrap an error message as MCP error content. The JSON-RPC `code` (default: internal error) is
+ carried under the namespaced `::error-code` key for usage logging and stripped from the
+ response before it reaches the client (see the registry's call-tool)."
+ ([message] (error-content message error-code-internal))
+ ([message code] {:content [{:type "text" :text message}] :isError true ::error-code code}))
+
+(defn success-content
+ "Assemble the two MCP response channels deliberately. When `structuredContent` is present,
+ clients may hand the model that channel alone — the MCP spec defines the text block as the
+ backwards-compat serialization of `structuredContent`, so structured is the primary channel
+ whenever both exist, and a structured payload that is a subset of the text silently hides
+ the rest from the model. Tools therefore default to text-only (omit `structured`), with
+ `text` self-sufficient: everything the model needs to reason or make its next call. Pass
+ `structured` only when a concrete programmatic consumer reads it (e.g. an MCP Apps iframe),
+ and make it a faithful mirror of the text — never a subset, never the sole home of anything
+ the model needs."
+ ([text] (success-content text nil))
+ ([text structured]
+ (cond-> {:content [{:type "text" :text (if (string? text) text (json/encode text))}]}
+ (some? structured) (assoc :structuredContent structured))))
+
+(def mcp-apps-meta-key
+ "The `_meta` key MCP Apps credentials ride on, private to the host and never shown to the model.
+
+ Named here rather than inline because two places must agree on it: the tool that puts a credential there, and
+ the redaction that strips it before the result reaches an eval trace."
+ :com.metabase/mcp-apps)
+
+(defn redact-mcp-apps-meta
+ "`result` with the private MCP Apps `_meta` block removed.
+
+ A credential in a tool result is a live authenticator for the /api/dataset surface. Recording one verbatim
+ parks it in trace files and the superuser-readable ai-tracing API, where it outlives its five-minute window
+ in backups and log shipping. v1 strips the same channel before tracing
+ (`metabase.mcp.resources/redact-ui-credential`); the transport's HTML scrub covers `resources/read` bodies
+ and does not reach tool results."
+ [result]
+ (cond-> result
+ (map? (:_meta result)) (update :_meta dissoc mcp-apps-meta-key)))
+
+;;; ------------------------------------------------ Teaching errors -----------------------------------------------
+
+(defn throw-teaching-error
+ "Throw an `ex-info` whose message is a complete caller-facing sentence naming the fix.
+ Surfaced to the MCP client as `isError` content by [[->mcp-error-content]]."
+ ([msg] (throw-teaching-error msg nil))
+ ([msg data]
+ (throw (ex-info msg (merge {:status-code 400} data)))))
+
+(defn throw-not-found
+ "Throw the collapsed not-found teaching error. Deliberately identical for \"doesn't exist\"
+ and \"exists but not readable\", so responses never form an existence oracle across the
+ permission boundary."
+ [model id]
+ (throw (ex-info (format "%s %s not found — it may not exist, or you may not have access to it."
+ (name model) id)
+ {:status-code 404})))
+
+(defn- status-code->error-code
+ [status-code]
+ (cond
+ (contains? #{401 402 403 409} status-code) error-code-invalid-request
+ (contains? #{400 404} status-code) error-code-invalid-params
+ :else error-code-internal))
+
+(def ^:private client-error-status-codes
+ "Status codes that mark an exception as deliberately caller-facing — its message is safe to
+ return. Everything else is an internal failure whose message may embed SQL, schema, or
+ connection detail. 402 (missing premium feature) and 409 (conflict) are included because their
+ messages name the missing feature or clashing state — information the agent needs to recover."
+ #{400 401 402 403 404 409})
+
+(defn- caller-facing-error-code
+ "The JSON-RPC error code for `e` when it is deliberately caller-facing (an explicit
+ `::error-code` other than internal, or a client 4xx `:status-code` in `ex-data`), else nil."
+ [e]
+ (let [{::keys [error-code] :keys [status-code]} (ex-data e)]
+ (or (when (and error-code (not= error-code error-code-internal)) error-code)
+ (when (contains? client-error-status-codes status-code)
+ (status-code->error-code status-code)))))
+
+(def ^:private schema-failure-types
+ "The `metabase.util.malli.fn` failure types. These are server-side bugs, not caller mistakes, but a bug
+ with a name is a one-call diagnosis instead of a blind retry loop — see GHY-4502."
+ #{:metabase.util.malli.fn/invalid-input :metabase.util.malli.fn/invalid-output})
+
+(defn- schema-failure-message
+ "A caller-facing message for a `mu/defn` schema failure, or nil when `e` is not one.
+
+ Names the function either way. The humanization is included ONLY for `::invalid-input`, where it
+ describes the caller's own argument echoed back at them. An `::invalid-output` humanization
+ describes SERVER-produced data — `me/humanize` embeds offending values (\"disallowed key, got: 177\"),
+ so echoing one could hand the caller a row they have no right to read.
+
+ `:value` is never touched: it holds the whole argument or return value."
+ [e]
+ (let [{:keys [type fn-name humanized]} (ex-data e)]
+ (when (contains? schema-failure-types type)
+ (if (= type :metabase.util.malli.fn/invalid-input)
+ (format "Server-side schema check failed in `%s`: %s. This is a bug in Metabase, not something to retry — report it."
+ fn-name (pr-str humanized))
+ (format "Server-side schema check failed in `%s` (on its return value). This is a bug in Metabase, not something to retry — report it."
+ fn-name)))))
+
+(defn caller-safe-error-message
+ "The message of `e` when it is deliberately caller-facing, judged the same way as
+ [[->mcp-error-content]]; any other exception is logged server-side and reported to the client
+ as a generic \"Internal error\". This is the sanitizer for response paths that answer with a
+ JSON-RPC error rather than tool content — resource reads, list handlers, and the transport's
+ own catch-all."
+ [e]
+ (cond
+ (caller-facing-error-code e) (or (ex-message e) "Internal error")
+ (schema-failure-message e) (do
+ (log/error e "Schema check failed dispatching MCP v2 request")
+ (schema-failure-message e))
+ :else (do
+ (log/error e "Unhandled error dispatching MCP v2 request")
+ "Internal error")))
+
+(defn ->mcp-error-content
+ "Convert a caught exception into MCP error content, and the single point where an exception
+ message is judged safe to return. Only deliberately caller-facing errors surface their
+ message: an explicit `::error-code` (other than internal) or a client (4xx) `:status-code`
+ in `ex-data` — teaching errors, not-found, scope denials. Every other exception — incidental
+ `ex-info`s from libraries (whose messages may embed SQL or connection detail), 5xx
+ invariants, and non-`ex-info` failures like JDBC or NPE — becomes a generic internal error;
+ the real exception is logged server-side for debugging but never returned to the client."
+ [e]
+ (if-let [code (caller-facing-error-code e)]
+ (error-content (or (ex-message e) "Internal error") code)
+ (if-let [message (schema-failure-message e)]
+ (do
+ (log/error e "Schema check failed dispatching MCP v2 tool call")
+ (error-content message error-code-internal))
+ (do
+ (log/error e "Unhandled error dispatching MCP v2 tool call")
+ (error-content "Internal error" error-code-internal)))))
+
+;;; ------------------------------------------------ Message helpers ----------------------------------------------
+
+(defn ellipsize
+ "`s` truncated to `limit` characters, with an ellipsis marking the cut."
+ [s limit]
+ (let [s (str s)]
+ (if (> (count s) limit)
+ (str (subs s 0 limit) "…")
+ s)))
+
+(defn humanize-detail
+ "Flatten a [[malli.error/humanize]] explanation into one line of `path: expectation`.
+
+ Sequential positions are labelled `[i]` and satisfied entries dropped, so a failure inside a
+ multi-element collection names which element it is in; a run of plain strings is a single
+ value's alternative messages and joins without positions."
+ [errors]
+ (cond
+ (map? errors)
+ (str/join "; " (map (fn [[k v]] (str (u/qualified-name k) ": " (humanize-detail v))) errors))
+
+ (and (sequential? errors) (every? string? errors))
+ (str/join ", " errors)
+
+ (sequential? errors)
+ (str/join "; " (keep-indexed (fn [i v]
+ (when (some? v)
+ (format "[%d] %s" i (humanize-detail v))))
+ errors))
+
+ :else
+ (str errors)))
+
+;;; ------------------------------------------------ Response shaping ----------------------------------------------
+
+(def ^:private ^LevenshteinDistance levenshtein
+ (LevenshteinDistance/getDefaultInstance))
+
+(defn- nearest-paths
+ [^String path catalog]
+ (->> catalog
+ (sort-by #(.apply levenshtein path ^String %))
+ (take 3)))
+
+(defn- add-path
+ "Merge one path (a vector of segments) into the selection tree. `::all` marks a
+ whole-subtree selection; it absorbs any narrower path at the same node, in either
+ insertion order, so `[\"parameters\" \"parameters.name\"]` selects all of `parameters`."
+ [tree segs]
+ (cond
+ (= ::all tree) ::all
+ (empty? segs) ::all
+ :else (update tree (first segs) #(add-path (or % {}) (rest segs)))))
+
+(defn- paths->tree
+ [paths]
+ (reduce (fn [tree path] (add-path tree (str/split path #"\.")))
+ {}
+ paths))
+
+(defn- select-tree
+ [node tree]
+ (cond
+ (= ::all tree) node
+ ;; Arrays are item-relative: apply the selection to every item.
+ (sequential? node) (mapv #(select-tree % tree) node)
+ (map? node) (into {}
+ (keep (fn [[seg subtree]]
+ (let [k (keyword seg)]
+ (cond
+ (contains? node k) [k (select-tree (get node k) subtree)]
+ ;; A named leaf answers even when the compact projection
+ ;; dropped it as nil: `{"cache_ttl": null}` says "not set",
+ ;; where `{}` reads as "not a readable field". A deeper
+ ;; path stays dropped — answering `last_run.status` with
+ ;; `{"last_run": {"status": null}}` would claim a run.
+ (= ::all subtree) [k nil]))))
+ tree)
+ :else node))
+
+(defn- valid-path?
+ "A requested path is valid when it is a catalog entry or a segment-aligned prefix of one
+ (selecting a whole subtree)."
+ [path catalog]
+ (boolean (some #(or (= % path) (str/starts-with? % (str path "."))) catalog)))
+
+(defn select-fields
+ "Narrow `response-map` (the permission-filtered built response for one item of `type`,
+ never a raw model row) to the requested `fields` dot-paths. Paths are validated against
+ `type`'s catalog; an unknown path is a teaching error naming the nearest valid paths. A valid
+ path the row has no value for comes back as null, so the answer never reads as an unsupported
+ field. `fields` is mutually exclusive with `response_format` and `include` — the caller passes
+ what was present and combining them is a teaching error."
+ ([type response-map fields]
+ (select-fields type response-map fields nil))
+ ([type response-map fields {:keys [response-format include]}]
+ (when (or response-format include)
+ (throw-teaching-error "Use `fields` OR `response_format`/`include`, not both."))
+ (when (empty? fields)
+ (throw-teaching-error "`fields` must name at least one path."))
+ (let [catalog (or (projections/catalog type)
+ (throw-teaching-error (format "`fields` is not supported for type %s." (name type))))]
+ (doseq [path fields]
+ (when-not (valid-path? path catalog)
+ (throw-teaching-error (format "Unknown field path %s for type %s. Nearest valid paths: %s."
+ (pr-str path) (name type)
+ (str/join ", " (nearest-paths path catalog))))))
+ (select-tree response-map (paths->tree fields)))))
+
+(defn response-format
+ "Read `:response_format` from tool arguments: `:concise` (default) or `:detailed`; anything
+ else is a teaching error."
+ [args]
+ (case (get args :response_format)
+ (nil "concise") :concise
+ "detailed" :detailed
+ (throw-teaching-error (format "Invalid response_format %s — use \"concise\" or \"detailed\"."
+ (pr-str (get args :response_format))))))
+
+;;; ------------------------------------------------ List envelopes ------------------------------------------------
+
+(defn truncation-line
+ "The steering sentence appended to a truncated list response: names the narrowing `param` when
+ one narrows this list, and always the next offset. Returns nil when the page isn't truncated
+ (or `total` is unknown). `:returned` is the actual page size — the caller's ground truth, e.g.
+ `(count data)` — not derived arithmetically, since a post-fetch drop (a stale index hit, an
+ unreadable row) can leave a page shorter than `limit`/`total`/`offset` alone would predict.
+ `:total-floor?` marks `total` as a lower bound rather than an exact count — e.g. a search total
+ capped at the ranking limit — so the sentence reads \"at least N\"."
+ ;; A list with nothing to narrow by still has to say more exists — without a line the caller
+ ;; reads a truncated page as the whole set.
+ [{:keys [param offset limit total total-floor? returned]}]
+ (let [offset (or offset 0)]
+ (when (and total limit (< (+ offset limit) total))
+ (let [total-str (str (when total-floor? "at least ") total)
+ next (+ offset limit)]
+ (if param
+ (format "Returned %d of %s — narrow with `%s`, or continue with `offset: %d`."
+ returned total-str (name param) next)
+ (format "Returned %d of %s — continue with `offset: %d`."
+ returned total-str next))))))
+
+(defn- empty-page-line
+ "The steering sentence for a page that returned nothing while `total` says matches exist.
+ [[truncation-line]] only fires on arithmetic truncation, so an offset at or past the end — or a
+ page whose every row was dropped after the count — otherwise carries no line at all, and an
+ empty `data` reads as \"nothing matches\" rather than \"nothing *here*\". Nil when `total` is
+ unknown or genuinely zero: that envelope already says it."
+ [{:keys [offset total total-floor?]}]
+ (when (and total (pos? total))
+ (let [total-str (str (when total-floor? "at least ") total)]
+ (if (pos? (or offset 0))
+ (format "No results at offset %d — %s available; page back with a smaller `offset`."
+ offset total-str)
+ ;; offset 0 with a positive total: the matches were counted, then dropped downstream
+ ;; (a stale index hit, a row gone unreadable). Paging cannot help, so don't suggest it.
+ (format "Returned 0 of %s — the matches found are no longer readable or have been removed."
+ total-str)))))
+
+(defn list-envelope
+ "The literal list-response envelope `{:data … :returned … :total?}`. `total` is included
+ when known (offset pagination over the app db usually can count)."
+ ([data] (list-envelope data nil))
+ ([data total]
+ (cond-> {:data data :returned (count data)}
+ (some? total) (assoc :total total))))
+
+(defn list-content
+ "Build the MCP success content for a list response: the envelope (compact JSON) in the text
+ block, with a steering line appended. `data` is already the page; `opts` carries
+ `:offset`/`:limit`, an optional `:param` naming what narrows this list, and an optional
+ `:empty-hint` — the domain reason a genuinely empty result set (`total` 0) is empty, never an
+ override of a computed line. Text-only — list data never rides `structuredContent` by reflex."
+ [data total {:keys [empty-hint offset] :as opts}]
+ (let [envelope (list-envelope data total)
+ opts (assoc opts :total total :returned (count data))
+ ;; The two empty-page sentences answer different questions, so `:empty-hint` is gated on a
+ ;; zero total rather than merely losing a race with [[empty-page-line]]: telling someone who
+ ;; paged past the end "nothing is visible to you" would be factually false. The offset is
+ ;; part of that gate, not just the total: [[empty-page-line]] declines at `total` 0 for any
+ ;; offset, so without it a caller who paged past the end of an empty list still reads the
+ ;; hint as the reason.
+ line (if (empty? data)
+ (or (empty-page-line opts)
+ (when (and (= 0 total) (not (pos? (or offset 0)))) empty-hint))
+ (truncation-line opts))]
+ (success-content (cond-> (json/encode envelope)
+ line (str "\n" line)))))
+
+;;; ------------------------------------------------- Frontend URLs ------------------------------------------------
+
+(defn frontend-url
+ "Prefix a `channel.urls` relative `path` with the configured site URL, returning it relative
+ when site-url is unset so a tool never emits an absolute URL with an empty host. Always build
+ a tool's `:url` this way — `channel.urls`' own `*-url` fns interpolate site-url directly and
+ render `nil` as the literal string \"null\", which site-url is whenever it is unconfigured or
+ fails validation."
+ [path]
+ (let [base (channel.urls/site-url)]
+ (if (str/blank? base)
+ path
+ (str base path))))
+
+;;; ------------------------------------------------ Shared schemas ------------------------------------------------
+
+(def card-display-values
+ "Visualization types a card (or an MCP Apps visualization) can render as. `list` is the model list
+ view — one of the two displays the model editor offers, so a tool that omits it can neither build
+ a list-view model nor leave one alone when updating it."
+ ["table" "list" "bar" "line" "pie" "scatter" "area" "row" "combo" "pivot"
+ "scalar" "smartscalar" "gauge" "progress" "funnel" "map" "waterfall" "sankey"])
+
+(def card-display-enum
+ "[[card-display-values]] as an undescribed Malli enum."
+ (into [:enum] card-display-values))
diff --git a/src/metabase/mcp/v2/dashboard_ops.clj b/src/metabase/mcp/v2/dashboard_ops.clj
new file mode 100644
index 00000000000..10ffeedca52
--- /dev/null
+++ b/src/metabase/mcp/v2/dashboard_ops.clj
@@ -0,0 +1,724 @@
+(ns metabase.mcp.v2.dashboard-ops
+ "The pure core of the `dashboard_write` tool: fold an ordered list of editor operations over a
+ hydrated dashboard and return the payload
+ [[metabase.dashboards.write/update-dashboard!]] saves — `{:dashcards :tabs :parameters}`.
+
+ No I/O. Everything the ops need about cards, tables, or fields is resolved by the caller and
+ passed in, which is what lets `validate_only` reuse this untouched and lets the whole op
+ grammar be tested against plain maps.
+
+ New dashcards and tabs carry caller-supplied negative ids, the same temp-id convention the
+ frontend editor sends to `PUT /api/dashboard/:id`: `u/row-diff` treats them as creates, and
+ `do-update-tabs!` rewrites each dashcard's `dashboard_tab_id` once the real tab rows exist.
+
+ Op methods validate, then compose the row primitives in the State algebra section; those
+ primitives are the only code that touches the `:dashcards`/`:tabs`/`:parameters` vectors."
+ (:require
+ [clojure.string :as str]
+ [metabase.dashboards.autoplace :as autoplace]
+ [metabase.dashboards.models.dashboard-card :as dashboard-card]
+ [metabase.lib.core :as lib]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.skills :as skills]
+ [metabase.parameters.mapping-targets :as mapping-targets]
+ [metabase.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defn op-error!
+ "Throw a teaching error attributing `message` to the op at `idx` (0-based, as sent)."
+ [idx message]
+ (common/throw-teaching-error (format "op %d (%s" idx message)))
+
+;; No local size table: `autoplace`'s `[cards display-type]` arity already merges
+;; `dashboards.constants/default-card-size` with the per-display entry in `card-size-defaults`,
+;; which covers :heading (full-width × 1), :text, :link, :iframe, and :action. That table is kept
+;; in sync with the frontend grid; a second copy here would drift.
+
+;;; ------------------------------------------------- State --------------------------------------------------------
+
+(defn- init-state
+ "Working state for the fold: dashcards/tabs/parameters as vectors in save order, plus the
+ caller-supplied `{card-id card}` map. Card metadata rides in state rather than being fetched,
+ which is what keeps this namespace pure — it is needed for a new card's default size and,
+ later, for parameter wiring."
+ [current cards]
+ {:dashcards (vec (:dashcards current))
+ :tabs (vec (:tabs current))
+ :parameters (vec (:parameters current))
+ ::cards cards})
+
+(defn- card-display
+ "The display type keyword driving a new dashcard's default size; `:table` when the card is
+ unknown, which only affects the default and never correctness."
+ [state card-id]
+ (keyword (or (:display (get (::cards state) card-id)) "table")))
+
+;;; --------------------------------------------- State algebra ----------------------------------------------------
+
+;;; `coll` is one of the three collection keys — :dashcards, :tabs, :parameters — each a vector of
+;;; :id-keyed maps in save order. These primitives are the only functions that write those keys;
+;;; op methods validate, then compose them.
+
+(defn- find-row
+ "The row in `(get state coll)` whose `:id` is `id`, or nil."
+ [state coll id]
+ (first (filter #(= id (:id %)) (get state coll))))
+
+(defn- insert-row
+ "Append `row` to `(get state coll)`, preserving save order."
+ [state coll row]
+ (update state coll conj row))
+
+(defn- update-row
+ "Replace the row with `id` by `(f row)`; every other row and the order are untouched."
+ [state coll id f]
+ (update state coll (partial mapv #(if (= id (:id %)) (f %) %))))
+
+(defn- remove-row
+ "Drop the row with `id`, preserving the order of the rest."
+ [state coll id]
+ (update state coll (partial filterv #(not= id (:id %)))))
+
+(defn- move-row
+ "Move the row with `id` so it sits at `index` among the remaining rows; nil when `index` falls
+ outside `[0, count-after-removal]`."
+ [state coll id index]
+ (let [row (find-row state coll id)
+ rest* (filterv #(not= id (:id %)) (get state coll))]
+ (when (<= 0 index (count rest*))
+ (assoc state coll (vec (concat (subvec rest* 0 index) [row] (subvec rest* index)))))))
+
+(defn- map-rows
+ "Replace every row by `(f row)`, order preserved."
+ [state coll f]
+ (update state coll (partial mapv f)))
+
+(defn- check-new-id!
+ "A new dashcard or tab id must be negative and unused in this batch."
+ [state idx id kind]
+ (when-not (and (integer? id) (neg? id))
+ (op-error! idx (format "%s): `id` must be a negative integer — negative ids mark rows to create."
+ kind)))
+ (when (some #(= id (:id %)) (concat (:dashcards state) (:tabs state)))
+ (op-error! idx (format "%s): id %d is already used in this batch — give each new row its own negative id."
+ kind id))))
+
+(defn- resolve-dashcard!
+ "The existing dashcard `id` names, or a teaching error."
+ [state idx id]
+ (or (find-row state :dashcards id)
+ (op-error! idx (format "%s): no dashcard with id %s on this dashboard."
+ "dashcard_id" id))))
+
+(defn- check-tab-id!
+ "A dashcard's target tab must be one of this dashboard's tabs — including a tab added earlier in
+ this batch under its negative id. nil means no tab, which stays legal. `op-name` names the op in
+ the teaching error."
+ [state idx op-name tab-id]
+ (when (and (some? tab-id) (not (find-row state :tabs tab-id)))
+ (op-error! idx (format "%s): no tab with id %s on this dashboard." op-name tab-id))))
+
+;;; ---------------------------------------------- Placement -------------------------------------------------------
+
+(defn- placement
+ "The `{:row :col :size_x :size_y}` for a new dashcard of `display-type` (a keyword such as
+ `:table`, `:heading`, `:iframe`). Explicit `position`/`size` win; an omitted size comes from
+ the display type's default and an omitted position autoplaces against the cards already on
+ the target tab."
+ [state {:keys [position size]} tab-id display-type]
+ (let [siblings (filterv #(= tab-id (:dashboard_tab_id %)) (:dashcards state))
+ ;; The display's default size, from `dashboards.constants` via the 2-arity. Resolved
+ ;; against no siblings so it always yields a size — the search below can come up empty on
+ ;; a full tab, and the default size must not vanish with it.
+ default (autoplace/get-position-for-new-dashcard [] display-type)
+ size_x (or (:size_x size) (:size_x default))
+ size_y (or (:size_y size) (:size_y default))]
+ (if position
+ {:row (:row position) :col (:col position) :size_x size_x :size_y size_y}
+ ;; Re-run placement at the caller's size — the default-size slot may not fit it.
+ (let [placed (autoplace/get-position-for-new-dashcard
+ siblings size_x size_y autoplace/default-grid-width)]
+ (when-not placed
+ (common/throw-teaching-error
+ "No free space on this tab for another card — remove or resize something first."))
+ {:row (:row placed) :col (:col placed) :size_x size_x :size_y size_y}))))
+
+;;; ---------------------------------------------- Domain helpers --------------------------------------------------
+
+(defn- upsert-mapping
+ "Add or replace `dc`'s parameter mapping for `parameter-id`, pointing at `target`. `:card_id`
+ comes from the dashcard — nil for a virtual card, which is what a `[:text-tag …]` mapping stores."
+ [dc parameter-id target]
+ (update dc :parameter_mappings
+ (fn [ms]
+ (conj (filterv #(not= parameter-id (:parameter_id %)) (vec ms))
+ {:parameter_id parameter-id
+ :card_id (:card_id dc)
+ :target target}))))
+
+(defn- drop-mapping
+ "Remove `dc`'s parameter mapping for `parameter-id`. An absent, nil, or empty
+ `:parameter_mappings` is left exactly as it was — writing the key, or rewriting a legacy
+ nil as [], would make an untouched dashcard register as changed in `update-dashboard!`'s
+ row diff."
+ [dc parameter-id]
+ (cond-> dc
+ (seq (:parameter_mappings dc))
+ (update :parameter_mappings (partial filterv #(not= parameter-id (:parameter_id %))))))
+
+(defn- add-inline-parameter
+ "Place `parameter-id` inline on `dc`; adding an id already present is a no-op."
+ [dc parameter-id]
+ (update dc :inline_parameters
+ (fn [ps] (vec (distinct (conj (vec ps) parameter-id))))))
+
+(defn- drop-inline-parameter
+ "Remove `parameter-id` from `dc`'s inline placements. An absent, nil, or empty
+ `:inline_parameters` is left exactly as it was, for the same row-diff reason as
+ [[drop-mapping]]."
+ [dc parameter-id]
+ (cond-> dc
+ (seq (:inline_parameters dc))
+ (update :inline_parameters (partial filterv #(not= parameter-id %)))))
+
+(defn- clear-inline-parameters
+ "Drop every inline placement from `dc`, leaving the key absent. Exactly one dashcard may place a
+ given parameter: `cleanup-orphaned-inline-parameters!` deletes the parameter from the dashboard
+ as soon as any dashcard placing it is deleted, so a second claimant takes the first one's filter
+ down with it."
+ [dc]
+ (dissoc dc :inline_parameters))
+
+(defn- insert-dashcard
+ "Insert a new dashcard: check `(:id op)` is a fresh negative id, place it on
+ `(:dashboard_tab_id base)` — a tab on this dashboard — honoring `op`'s position/size with
+ `display`'s default size, and append `base` merged with the placement."
+ [state idx op base display]
+ (check-new-id! state idx (:id op) (:op op))
+ (check-tab-id! state idx (:op op) (:dashboard_tab_id base))
+ (insert-row state :dashcards
+ (merge base (placement state op (:dashboard_tab_id base) display))))
+
+;;; ------------------------------------------------- Ops ----------------------------------------------------------
+
+(defmulti ^:private apply-op
+ "Apply one op to the working state. Dispatches on the op's `:op` string."
+ {:arglists '([state idx op])}
+ (fn [_state _idx op] (:op op)))
+
+(defmethod apply-op :default
+ [_state idx op]
+ (op-error! idx (format "%s): unknown op — see the tool description for the supported list."
+ (pr-str (:op op)))))
+
+(defmethod apply-op "add_card"
+ [state idx {:keys [id card_id tab series inline_parameters] :as op}]
+ (insert-dashcard state idx op
+ (merge {:id id
+ :card_id card_id
+ :dashboard_tab_id tab
+ :parameter_mappings []}
+ (when (seq series) {:series (mapv (fn [cid] {:id cid}) series)})
+ (when (seq inline_parameters) {:inline_parameters (vec inline_parameters)}))
+ (card-display state card_id)))
+
+;;; ---------------------------------------------- Virtual dashcards -------------------------------------------------
+
+(defn- virtual-dashcard
+ "A dashcard with no backing card. `display` is the virtual display type and `extras` its
+ display-specific settings, both handed to [[dashboard-card/virtual-card-settings]] so this
+ compiler and the frontend agree on the shape."
+ [state idx op display extras]
+ (insert-dashcard state idx op
+ (merge {:id (:id op)
+ :dashboard_tab_id (:tab op)
+ :parameter_mappings []
+ :visualization_settings (dashboard-card/virtual-card-settings display extras)}
+ (when (seq (:inline_parameters op))
+ {:inline_parameters (vec (:inline_parameters op))}))
+ (keyword display)))
+
+(defmethod apply-op "add_text"
+ [state idx {:keys [markdown] :as op}]
+ (virtual-dashcard state idx op "text" {:text markdown}))
+
+(defmethod apply-op "add_heading"
+ [state idx {:keys [text] :as op}]
+ (virtual-dashcard state idx op "heading" {:text text}))
+
+(defmethod apply-op "add_link"
+ [state idx {:keys [url entity] :as op}]
+ (when (= (some? url) (some? entity))
+ (op-error! idx "add_link): pass exactly one of `url` or `entity`."))
+ (virtual-dashcard state idx op "link"
+ {:link (if url
+ {:url url}
+ {:entity {:model (:type entity) :id (:id entity)}})}))
+
+(defmethod apply-op "add_iframe"
+ [state idx {:keys [src] :as op}]
+ (virtual-dashcard state idx op "iframe" {:iframe src}))
+
+(defmethod apply-op "add_action"
+ [state idx {:keys [id action_id label display] :as op}]
+ (insert-dashcard state idx op
+ {:id id
+ :action_id action_id
+ :dashboard_tab_id (:tab op)
+ :parameter_mappings []
+ ;; the frontend keys off `:virtual_card` to recognize an action dashcard, so an
+ ;; action carries the same wrapper as the other card-less dashcards
+ :visualization_settings
+ (dashboard-card/virtual-card-settings
+ "action"
+ (cond-> {:actionDisplayType (or display "button")}
+ label (assoc "button.label" label)))}
+ :action))
+
+(defmethod apply-op "duplicate_card"
+ [state idx {:keys [id dashcard_id tab] :as op}]
+ ;; also checked inside insert-dashcard; the explicit call keeps a bad new id reported ahead of a
+ ;; bad source dashcard
+ (check-new-id! state idx id "duplicate_card")
+ (let [source (resolve-dashcard! state idx dashcard_id)
+ tab-id (if (contains? op :tab) tab (:dashboard_tab_id source))]
+ ;; The clone keeps its wiring but not the placement, so the filter stays on the card the user
+ ;; put it on. The editor instead mints a fresh copy of each inline parameter; this grammar has
+ ;; `add_parameter` + `move_parameter` for that, so cloning one implicitly would be an
+ ;; unrequested dashboard-level edit under an id the caller never chose.
+ (insert-dashcard state idx
+ (assoc op :size {:size_x (:size_x source) :size_y (:size_y source)})
+ (-> source
+ (dissoc :id :row :col :size_x :size_y :dashboard_tab_id
+ :created_at :updated_at :card :entity_id)
+ clear-inline-parameters
+ (merge {:id id :dashboard_tab_id tab-id}))
+ (card-display state (:card_id source)))))
+
+;;; ------------------------------------------------- Edit ops ------------------------------------------------------
+
+(def ^:private patch-rejected-keys
+ "Layout and identity keys `patch_dashcard` refuses, mapped to the op that owns them. A patch is a
+ content merge; silently dropping one would let a caller believe a move or replace took effect.
+ `:id` has no owning op — it is caught generically by the [[patchable-keys]] allowlist."
+ {:row "move"
+ :col "move"
+ :dashboard_tab_id "move"
+ :size_x "resize"
+ :size_y "resize"
+ :card_id "replace_card"
+ :action_id "replace_card"
+ :series "set_series"})
+
+(def ^:private patchable-keys
+ "The dashcard content keys a patch may carry. An existing dashcard's update allowlists these
+ anyway, but a new (negative-id) dashcard is inserted with an open schema, so an unlisted key
+ would reach the DB as a raw error — reject it here instead, symmetrically for both."
+ #{:visualization_settings :parameter_mappings :inline_parameters})
+
+(defmethod apply-op "replace_card"
+ [state idx {:keys [dashcard_id card_id]}]
+ (resolve-dashcard! state idx dashcard_id)
+ (update-row state :dashcards dashcard_id
+ ;; `:card` is the hydrated row of the card being replaced. Dropping it is what makes the dry
+ ;; run honest: the projection prefers `:card` over `:card_id`, so leaving the old one would
+ ;; report the replace as a no-op while the real save reads back the new card.
+ #(-> (assoc % :card_id card_id
+ :series []
+ :parameter_mappings []
+ :visualization_settings {})
+ (dissoc :card))))
+
+(defmethod apply-op "move"
+ [state idx {:keys [dashcard_id tab position] :as op}]
+ (let [dc (resolve-dashcard! state idx dashcard_id)
+ tab-id (if (contains? op :tab) tab (:dashboard_tab_id dc))]
+ (when (contains? op :tab)
+ (check-tab-id! state idx "move" tab))
+ (update-row state :dashcards dashcard_id
+ (fn [dc]
+ (merge dc
+ {:dashboard_tab_id tab-id}
+ (if position
+ {:row (:row position) :col (:col position)}
+ ;; autoplace against the other cards on the tab: the card being moved is
+ ;; not its own sibling, or the search can never return the slot it holds
+ (select-keys (placement (update state :dashcards
+ (partial filterv #(not= dashcard_id (:id %))))
+ {:size (select-keys dc [:size_x :size_y])}
+ tab-id
+ :table)
+ [:row :col])))))))
+
+(defmethod apply-op "resize"
+ [state idx {:keys [dashcard_id size]}]
+ (resolve-dashcard! state idx dashcard_id)
+ (update-row state :dashcards dashcard_id #(merge % (select-keys size [:size_x :size_y]))))
+
+(defmethod apply-op "remove"
+ [state idx {:keys [dashcard_id]}]
+ (resolve-dashcard! state idx dashcard_id)
+ (remove-row state :dashcards dashcard_id))
+
+(defmethod apply-op "set_series"
+ [state idx {:keys [dashcard_id card_ids]}]
+ (resolve-dashcard! state idx dashcard_id)
+ (update-row state :dashcards dashcard_id #(assoc % :series (mapv (fn [cid] {:id cid}) card_ids))))
+
+(defn- coerce-target
+ "Keywordize the clause heads of a raw JSON `target` — `[\"dimension\", [\"template-tag\", \"x\"]]`
+ arrives as strings throughout, and the mapping schema wants keyword heads. Only position 0 of each
+ nested vector is a head; every other element (tag names, column names, ids, options maps) is data
+ and passes through untouched."
+ [x]
+ (if (and (sequential? x) (string? (first x)))
+ (into [(keyword (first x))] (map coerce-target) (rest x))
+ x))
+
+(defmethod apply-op "patch_dashcard"
+ [state idx {:keys [dashcard_id patch]}]
+ (resolve-dashcard! state idx dashcard_id)
+ (doseq [k (keys patch)]
+ (cond
+ (contains? patch-rejected-keys k)
+ (op-error! idx (format "patch_dashcard): `%s` is not patchable — use the `%s` op."
+ (name k) (get patch-rejected-keys k)))
+
+ (not (contains? patchable-keys k))
+ (op-error! idx (format "patch_dashcard): `%s` is not a patchable property." (name k)))))
+ (update-row state :dashcards dashcard_id
+ (fn [dc]
+ (cond-> (merge dc (dissoc patch :visualization_settings))
+ (contains? patch :visualization_settings)
+ (update :visualization_settings merge (:visualization_settings patch))
+
+ ;; A patched mapping arrives as raw JSON, so its target's clause heads are strings
+ ;; ("dimension", "field") where the mapping schema wants keywords — the same coercion
+ ;; `wire_parameter` does. Without it every parameter_mappings patch, a key this op
+ ;; advertises as patchable, fails validation with "should be :dimension".
+ (contains? patch :parameter_mappings)
+ (update :parameter_mappings
+ (partial mapv #(cond-> % (:target %) (update :target (comp coerce-target vec)))))))))
+
+;;; -------------------------------------------------- Tab ops ------------------------------------------------------
+
+(defn- resolve-tab!
+ [state idx id]
+ (or (find-row state :tabs id)
+ (op-error! idx (format "tab_id): no tab with id %s on this dashboard." id))))
+
+(defn- next-temp-id
+ "A negative id not yet used by any dashcard or tab in the working state. Ops that clone a whole
+ tab mint ids for the copies rather than making the caller enumerate them."
+ [state]
+ (dec (reduce min 0 (map :id (concat (:dashcards state) (:tabs state))))))
+
+(defmethod apply-op "add_tab"
+ [state idx {:keys [id name]}]
+ (check-new-id! state idx id "add_tab")
+ (insert-row state :tabs {:id id :name name}))
+
+(defmethod apply-op "rename_tab"
+ [state idx {:keys [tab_id name]}]
+ (resolve-tab! state idx tab_id)
+ (update-row state :tabs tab_id #(assoc % :name name)))
+
+(defmethod apply-op "move_tab"
+ [state idx {:keys [tab_id index]}]
+ (resolve-tab! state idx tab_id)
+ (or (move-row state :tabs tab_id index)
+ (op-error! idx (format "move_tab): index %d is out of range — this dashboard has %d tabs."
+ index (count (:tabs state))))))
+
+(defmethod apply-op "duplicate_tab"
+ [state idx {:keys [id tab_id]}]
+ (check-new-id! state idx id "duplicate_tab")
+ (let [source (resolve-tab! state idx tab_id)
+ cards (filterv #(= tab_id (:dashboard_tab_id %)) (:dashcards state))
+ state (insert-row state :tabs {:id id :name (:name source)})]
+ (reduce (fn [st card]
+ (insert-row st :dashcards
+ (-> card
+ (dissoc :created_at :updated_at :card)
+ clear-inline-parameters
+ (assoc :id (next-temp-id st)
+ :dashboard_tab_id id))))
+ state
+ cards)))
+
+(defmethod apply-op "remove_tab"
+ [state idx {:keys [tab_id]}]
+ (resolve-tab! state idx tab_id)
+ (let [doomed (map :id (filter #(= tab_id (:dashboard_tab_id %)) (:dashcards state)))]
+ (reduce (fn [st dc-id] (remove-row st :dashcards dc-id))
+ (remove-row state :tabs tab_id)
+ doomed)))
+
+(defn- check-tab-coverage!
+ "`update-dashboard!` requires every dashcard to name a tab once a dashboard has more than one —
+ with exactly one tab it back-fills a nil `dashboard_tab_id` itself — and its own error is
+ opaque. Reject the 2+ tab case here, naming the offending cards."
+ [{:keys [tabs dashcards] :as state}]
+ (when (< 1 (count tabs))
+ (when-let [orphans (not-empty (filterv #(nil? (:dashboard_tab_id %)) dashcards))]
+ (common/throw-teaching-error
+ (format (str "This dashboard has tabs, so every card must belong to a tab: %s have none. "
+ "Pass `tab` on the add op, or use `move` with `tab` for cards already placed.")
+ (pr-str (mapv :id orphans))))))
+ state)
+
+;;; --------------------------------------------- Parameter ops -----------------------------------------------------
+
+(defn- resolve-parameter!
+ [state idx id]
+ (or (find-row state :parameters id)
+ (op-error! idx (format "parameter_id): no parameter with id %s on this dashboard." (pr-str id)))))
+
+(defn- card-for-dashcard
+ [state dashcard]
+ (get (::cards state) (:card_id dashcard)))
+
+(defn- assoc-slug
+ "Derive `:slug` from a parameter's name, as the editor's `setParameterName` does. Without it a
+ parameter this tool creates is not addressable by slug — embedding, public links, and URL param
+ sync all key on the slug — so a parameter that works in the editor would half-work here."
+ [param]
+ (cond-> param
+ (:name param) (assoc :slug (u/slugify (:name param)))))
+
+(defmethod apply-op "add_parameter"
+ [state idx {:keys [parameter_id] :as op}]
+ (when (find-row state :parameters parameter_id)
+ (op-error! idx (format "add_parameter): parameter %s already exists — use `update_parameter`."
+ (pr-str parameter_id))))
+ (insert-row state :parameters
+ (-> (dissoc op :op :parameter_id)
+ (assoc :id parameter_id)
+ assoc-slug)))
+
+(defmethod apply-op "update_parameter"
+ [state idx {:keys [parameter_id clear] :as op}]
+ (resolve-parameter! state idx parameter_id)
+ (let [cleared (map keyword clear)]
+ (doseq [field cleared
+ :when (contains? op field)]
+ (op-error! idx (format "update_parameter): `%s` is both set and cleared — pass one or the other."
+ (name field))))
+ (update-row state :parameters parameter_id
+ (fn [param]
+ ;; A parameter is a map, so clearing removes the key rather than setting it to
+ ;; nil — `merge` can only add, and a stored explicit null is not the same as an
+ ;; absent property to the REST shape.
+ (cond-> (apply dissoc
+ (merge param (dissoc op :op :parameter_id :clear))
+ cleared)
+ ;; only re-slug on a rename, so an unrelated edit can't rewrite the slug of a
+ ;; parameter created in the editor and break its existing URLs
+ (contains? op :name) assoc-slug)))))
+
+(defmethod apply-op "remove_parameter"
+ [state idx {:keys [parameter_id]}]
+ (resolve-parameter! state idx parameter_id)
+ (-> state
+ (remove-row :parameters parameter_id)
+ (map-rows :parameters
+ (fn [p]
+ (cond-> p
+ (contains? p :filteringParameters)
+ (update :filteringParameters (partial filterv #(not= parameter_id %))))))
+ (map-rows :dashcards
+ (fn [dc]
+ (-> dc
+ (drop-inline-parameter parameter_id)
+ (drop-mapping parameter_id))))))
+
+(defmethod apply-op "move_parameter"
+ [state idx {:keys [parameter_id index dashcard_id] :as op}]
+ (resolve-parameter! state idx parameter_id)
+ (when (and (contains? op :index) (contains? op :dashcard_id))
+ (op-error! idx "move_parameter): pass exactly one of `index` or `dashcard_id`."))
+ (cond
+ (contains? op :dashcard_id)
+ (do (resolve-dashcard! state idx dashcard_id)
+ (map-rows state :dashcards
+ (fn [dc]
+ (if (= dashcard_id (:id dc))
+ (add-inline-parameter dc parameter_id)
+ (drop-inline-parameter dc parameter_id)))))
+
+ (contains? op :index)
+ (or (move-row state :parameters parameter_id index)
+ (op-error! idx (format "move_parameter): index %d is out of range — this dashboard has %d parameters."
+ index (count (:parameters state)))))
+
+ :else
+ (op-error! idx "move_parameter): pass `index` to reorder the header, or `dashcard_id` to place it on a card.")))
+
+(defn- wire-one
+ "Add or replace `parameter`'s mapping on `dashcard`. Returns the dashcard unchanged when its card
+ exposes no target for `field-id`."
+ [state idx parameter dashcard field-id explicit?]
+ (let [card (card-for-dashcard state dashcard)
+ target (when card (mapping-targets/target-for-field card parameter field-id))]
+ (cond
+ target
+ (upsert-mapping dashcard (:id parameter) target)
+
+ explicit?
+ (op-error! idx (format (str "wire_parameter): dashcard %s does not expose field %s for parameter %s. "
+ "Read the dashboard with get_content to see each card's columns.")
+ (:id dashcard) field-id (pr-str (:id parameter))))
+
+ :else dashcard)))
+
+(defn- wire-card!
+ "The card behind the dashcard a wire op targets, or a teaching error — a virtual dashcard (text,
+ heading, link, iframe) has no query, so only a `[:text-tag …]` target (handled before this) can
+ wire it."
+ [state idx dashcard]
+ (or (card-for-dashcard state dashcard)
+ (op-error! idx (format (str "wire_parameter): dashcard %s has no card behind it — only a raw "
+ "`target` of [\"text-tag\", \"<name>\"] can wire a text, heading, "
+ "or iframe card's own {{placeholder}}.")
+ (:id dashcard)))))
+
+(defn- tag-target!
+ "The mapping target for `target_tag` on `dashcard`'s card — `[:dimension [:template-tag …]]` for a
+ field-filter or temporal-unit tag, `[:variable …]` for a raw variable, derived from the tag's actual
+ type so the caller never has to know the distinction. A tag that doesn't exist on the card, or that
+ can't back a parameter (snippet/card reference tags), is a teaching error naming the tags that do."
+ [state idx dashcard target-tag]
+ (let [card (wire-card! state idx dashcard)
+ tag-types (mapping-targets/template-tag-types card)
+ tag-type (get tag-types target-tag)]
+ (cond
+ (nil? tag-type)
+ (op-error! idx (format "wire_parameter): card %s has no template tag named %s.%s %s"
+ (:card_id dashcard) (pr-str target-tag)
+ (if (seq tag-types)
+ (str " Its tags: " (str/join ", " (sort (keys tag-types))) ".")
+ (str " It has no template tags — `target_tag` wires a native-SQL "
+ "card's tags; for an MBQL card pass `target_field`."))
+ skills/wire-target-grammar))
+
+ :else
+ (or (mapping-targets/target-for-tag target-tag tag-type)
+ (op-error! idx (format (str "wire_parameter): {{%s}} is a %s-reference tag — it splices SQL "
+ "text and cannot take a parameter value. Wireable tags on this "
+ "card: %s.")
+ target-tag (name tag-type)
+ (or (->> tag-types
+ (filter (fn [[nm t]] (mapping-targets/target-for-tag nm t)))
+ (map key)
+ sort
+ (str/join ", ")
+ not-empty)
+ "none")))))))
+
+(defn- text-tag-names
+ "The `{{tag}}` placeholder names a dashcard's own content carries — a text or heading card's
+ markdown, an iframe card's embed — which are what a `[:text-tag …]` target can bind. Empty for
+ every other dashcard."
+ [dashcard]
+ (let [vs (:visualization_settings dashcard)
+ source (case (u/qualified-name (get-in vs [:virtual_card :display] ""))
+ ("text" "heading") (:text vs)
+ "iframe" (:iframe vs)
+ nil)]
+ (if (string? source)
+ (into #{} (map :name) (lib/recognize-template-tags source))
+ #{})))
+
+(defn- check-text-tag-target!
+ "A `[:text-tag <name>]` target binds a `{{name}}` placeholder in a virtual dashcard's own
+ content, so it is validated against the dashcard, not a card — which text, heading, and iframe
+ dashcards don't have."
+ [idx dashcard [_ tag-name :as target]]
+ (let [names (text-tag-names dashcard)]
+ (when-not (contains? names tag-name)
+ (op-error! idx (format (str "wire_parameter): target %s resolves to nothing on dashcard %s — a "
+ "text-tag target binds a {{tag}} placeholder in a text, heading, or "
+ "iframe card's own content%s")
+ (pr-str target) (:id dashcard)
+ (if (seq names)
+ (str "; this card's placeholders: " (str/join ", " (sort names)) ".")
+ ", and this dashcard carries none."))))))
+
+(defn- checked-raw-target!
+ "Coerce a raw `target` clause and verify it resolves to something the dashcard actually exposes
+ for `parameter` — a wire whose target resolves to nothing saves cleanly and renders as
+ \"unknown field\", which no teaching error would ever catch. A `[:text-tag …]` target resolves
+ against the dashcard's own content; everything else against its card."
+ [state idx parameter dashcard target]
+ (let [target (coerce-target (vec target))]
+ (if (= :text-tag (first target))
+ (check-text-tag-target! idx dashcard target)
+ (let [card (wire-card! state idx dashcard)]
+ (when-not (mapping-targets/wireable-target? card parameter target)
+ (op-error! idx (format (str "wire_parameter): target %s resolves to nothing on card %s — the "
+ "card exposes no matching column or template tag for parameter "
+ "%s. Read the card with get_content to see its columns and "
+ "template tags. %s")
+ (pr-str target) (:card_id dashcard) (pr-str (:id parameter))
+ skills/wire-target-grammar)))))
+ target))
+
+(defn- wire-target
+ "Replace `parameter`'s mapping on the dashcard `dashcard-id` with `target`."
+ [state dashcard-id parameter-id target]
+ (update-row state :dashcards dashcard-id #(upsert-mapping % parameter-id target)))
+
+(defmethod apply-op "wire_parameter"
+ [state idx {:keys [parameter_id dashcard_id target_field target_tag target autowire]}]
+ (let [parameter (resolve-parameter! state idx parameter_id)
+ dashcard (resolve-dashcard! state idx dashcard_id)]
+ (cond
+ target
+ (wire-target state dashcard_id parameter_id
+ (checked-raw-target! state idx parameter dashcard target))
+
+ target_tag
+ (wire-target state dashcard_id parameter_id
+ (tag-target! state idx dashcard target_tag))
+
+ target_field
+ (let [state (update-row state :dashcards dashcard_id
+ #(wire-one state idx parameter % target_field true))]
+ (if autowire
+ (map-rows state :dashcards
+ #(if (= dashcard_id (:id %))
+ %
+ (wire-one state idx parameter % target_field false)))
+ state))
+
+ :else
+ (op-error! idx (str "wire_parameter): pass one of `target_field`, `target_tag`, or `target`. "
+ skills/wire-target-grammar)))))
+
+(defmethod apply-op "unwire_parameter"
+ [state idx {:keys [parameter_id dashcard_id] :as op}]
+ (resolve-parameter! state idx parameter_id)
+ (when (contains? op :dashcard_id)
+ (resolve-dashcard! state idx dashcard_id))
+ (map-rows state :dashcards
+ (fn [dc]
+ (if (or (not (contains? op :dashcard_id)) (= dashcard_id (:id dc)))
+ (drop-mapping dc parameter_id)
+ dc))))
+
+;;; ------------------------------------------------ Entry ---------------------------------------------------------
+
+(defn compile-ops
+ "Fold `ops` over `current` (a dashboard hydrated with `[:dashcards :series :card] :tabs`) and
+ return `{:dashcards :tabs :parameters}` — the full-replacement payload `update-dashboard!`
+ saves. New rows carry the caller's negative ids. `cards` maps every card id the ops may touch
+ to its card row; this namespace does no I/O, so the caller resolves that. Throws a teaching
+ error naming the op index on any invalid op."
+ ([current ops] (compile-ops current ops {}))
+ ([current ops cards]
+ (-> (reduce-kv (fn [state idx op] (apply-op state idx op))
+ (init-state current cards)
+ (vec ops))
+ check-tab-coverage!
+ (select-keys [:dashcards :tabs :parameters]))))
diff --git a/src/metabase/mcp/v2/projections.clj b/src/metabase/mcp/v2/projections.clj
new file mode 100644
index 00000000000..87957b86ec0
--- /dev/null
+++ b/src/metabase/mcp/v2/projections.clj
@@ -0,0 +1,431 @@
+(ns metabase.mcp.v2.projections
+ "Per-type concise/detailed response projections for v2 MCP read tools, plus the generated
+ per-type `fields` dot-path catalog.
+
+ A projection is a subset of the corresponding REST response — same property names, no
+ renames. Each tool task registers its own type here; this namespace seeds a few
+ representative types so the conventions layer is exercisable.
+
+ A projection takes an already-fetched, already-redacted row and returns its shape: pure, with
+ no app-DB access and no read of the current user. Hydration and the permission-dependent
+ redaction happen before the row gets here — see [[metabase.mcp.v2.redaction]].
+
+ The catalog is generated by walking the shape of a sample detailed response (rather than
+ hand-listed), so it cannot drift from the projection: dot-paths up to three segments deep,
+ item-relative inside arrays."
+ (:require
+ [clojure.string :as str]
+ [medley.core :as m]
+ [metabase.dashboards.models.dashboard :as dashboard]
+ [metabase.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defonce ^:private registry
+ (atom {}))
+
+;;; ------------------------------------------------ Catalog generation --------------------------------------------
+
+(def ^:private max-catalog-depth 3)
+
+(defn- sample-paths
+ [prefix node]
+ (cond
+ (= (count prefix) max-catalog-depth)
+ [(str/join "." prefix)]
+
+ (map? node)
+ (if (empty? node)
+ (when (seq prefix) [(str/join "." prefix)])
+ (mapcat (fn [[k v]] (sample-paths (conj prefix (name k)) v)) node))
+
+ ;; Arrays are item-relative: the path addresses fields of the items, the array itself
+ ;; contributes no segment.
+ (sequential? node)
+ (if-let [item (first (filter map? node))]
+ (sample-paths prefix item)
+ (when (seq prefix) [(str/join "." prefix)]))
+
+ :else
+ (when (seq prefix) [(str/join "." prefix)])))
+
+(defn paths-from-sample
+ "Return the vector of `fields` dot-paths derivable from `sample` (a built detailed response
+ map): every leaf up to three segments deep, item-relative inside arrays."
+ [sample]
+ (vec (sort (distinct (sample-paths [] sample)))))
+
+;;; ------------------------------------------------ Registry -------------------------------------------------------
+
+(defn register-projection!
+ "Register the projection entry for `type` (a keyword such as `:collection`). Overwrites any
+ existing entry, so re-evaluating a tool namespace in the REPL is idempotent.
+
+ `entry` keys:
+ - `:concise` / `:detailed` — `(fn [row] response-map)`, REST property names only
+ - `:sample` — a representative detailed row; the catalog is generated from
+ `(:detailed entry)` applied to it
+ - `:catalog` — explicit dot-path vector, only for types whose sample can't capture the
+ shape (prefer `:sample`)"
+ [type {:keys [concise detailed sample] :as entry
+ explicit-catalog :catalog}]
+ {:pre [(keyword? type) (fn? concise) (fn? detailed) (or sample explicit-catalog)]}
+ (let [resolved-catalog (or explicit-catalog (paths-from-sample (detailed sample)))]
+ (swap! registry assoc type (assoc entry :catalog resolved-catalog))
+ type))
+
+(defn register-key-projection!
+ "Register `type`'s concise/detailed projections as `select-keys` over the given key vectors —
+ the common case, replacing a hand-written `{:concise … :detailed … :sample …}` map. Options:
+
+ - `:detailed-keys` — keys for the detailed projection; defaults to `concise-keys`.
+ - `:compact?` — drop nil-valued keys from the projected row (default true). Pass false for rows
+ whose columns are always populated and where an explicit null is meaningful.
+ - `:sample` — a representative detailed row, overriding the auto `(zipmap detailed-keys \"x\")`
+ for types with nested (non-scalar) shapes the catalog must see."
+ [type concise-keys & {:keys [detailed-keys compact? sample] :or {compact? true}}]
+ (let [detailed-keys (or detailed-keys concise-keys)
+ project-fn (fn [ks]
+ (if compact?
+ #(m/remove-vals nil? (select-keys % ks))
+ #(select-keys % ks)))]
+ (register-projection!
+ type
+ {:concise (project-fn concise-keys)
+ :detailed (project-fn detailed-keys)
+ :sample (or sample (zipmap detailed-keys (repeat "x")))})))
+
+(def ^:private projection-formats
+ #{:concise :detailed})
+
+(defn project
+ "Apply `type`'s `fmt` (`:concise` | `:detailed`) projection to `row`. Throws when no projection is
+ registered for `type`, or when `fmt` is not a projection format."
+ [type fmt row]
+ (let [entry (get @registry type)]
+ (when-not entry
+ (throw (ex-info (str "No projection registered for type: " (name type))
+ {:status-code 500 :type type})))
+ (when-not (contains? projection-formats fmt)
+ (throw (ex-info (str "Unknown projection format: " (pr-str fmt)
+ ". Valid formats: " (str/join ", " (sort (map str projection-formats))))
+ {:status-code 500 :type type :fmt fmt})))
+ ((get entry fmt) row)))
+
+(defn catalog
+ "The `fields` dot-path catalog for `type`, or nil when the type is unregistered."
+ [type]
+ (get-in @registry [type :catalog]))
+
+(defn all-catalogs
+ "Map of registered type -> dot-path catalog, published as the `catalog://metabase/fields`
+ MCP resource (see [[metabase.mcp.v2.resources]])."
+ []
+ (into (sorted-map) (map (fn [[type entry]] [type (:catalog entry)])) @registry))
+
+;;; --------------------------------------------- Representative types ---------------------------------------------
+;; Field selection ported from the v1 presenters (metabase.metabot.tools.resources), but keeping
+;; the REST property names — v2 never renames (`db_id` stays `db_id`, no synthetic `uri`/`path`).
+
+(def ^:private collection-concise-keys
+ [:id :name :description :location :archived])
+
+(def ^:private collection-detailed-keys
+ (into collection-concise-keys
+ [:authority_level :personal_owner_id :namespace :entity_id :slug :created_at]))
+
+(register-key-projection! :collection collection-concise-keys
+ :detailed-keys collection-detailed-keys :compact? false)
+
+(def ^:private table-concise-keys
+ [:id :name :display_name :schema :db_id :description])
+
+(def ^:private table-detailed-keys
+ (into table-concise-keys
+ [:entity_type :view_count :active :field_order :is_upload :visibility_type
+ :initial_sync_status :created_at :updated_at]))
+
+(register-key-projection! :table table-concise-keys
+ :detailed-keys table-detailed-keys :compact? false)
+
+;; The one canonical card projection. Shared by browse_collection's model list and get_content's
+;; question/model reads — registered here (the namespace both load) so it has a single definition
+;; rather than one tool silently overwriting another's at load time. `query_summary`/`template_tags`
+;; are enrichments get_content computes; browse rows lack them and `compact` drops them.
+(def ^:private question-concise-keys
+ [:id :name :type :description :display :collection_id :collection_path :database_id :database_name
+ :table_id :source_card_id :archived :query_summary :template_tags :parameters])
+
+(def question-detailed-keys
+ "Keys of the `:question` detailed projection. All are Card columns except
+ [[question-enrichment-keys]], which `get_content` computes at read time."
+ (into question-concise-keys
+ [:entity_id :dashboard_id :query_type :collection_position :creator_id :cache_ttl
+ :visualization_settings :created_at :updated_at]))
+
+(def question-enrichment-keys
+ "Projection keys `get_content` computes at read time — not Card columns. Column-select paths
+ (`list_models`, browse rows) can't fetch them, so they drop these before selecting."
+ #{:query_summary :template_tags :collection_path :database_name})
+
+;; `visualization_settings` stays a scalar in the sample on purpose: its own keys are literal
+;; strings containing dots (`graph.dimensions`), so a dot-path into it could never address
+;; anything. The catalog offers the one whole-blob path.
+(register-key-projection!
+ :question question-concise-keys
+ :detailed-keys question-detailed-keys
+ :sample (-> (zipmap question-detailed-keys (repeat "x"))
+ (assoc :template_tags {}
+ :parameters [{:id "x" :name "x" :type "x" :target ["x"] :slug "x"}])))
+
+;; Shared by `document_write`'s echo and `get_content`'s document reads — registered here, the
+;; namespace both load, for the same reason as `:question` above: neither tool requires the other,
+;; so a registration owned by either would leave the other depending on `api.clj`'s require order.
+;; `:content_markdown_unavailable` stands in for `:content_markdown` when the stored body holds a
+;; block with no Markdown form. Exactly one of the pair is ever present, and the projection is
+;; compact, so the absent one drops out.
+(def ^:private document-concise-keys
+ [:id :name :collection_id :archived :content_markdown :content_markdown_unavailable])
+
+(def ^:private document-detailed-keys
+ (into document-concise-keys
+ [:entity_id :creator_id :created_at :updated_at]))
+
+(register-key-projection! :document document-concise-keys
+ :detailed-keys document-detailed-keys)
+
+;; Shared by `metric_write`'s echo and `get_content`'s metric reads, and registered here for the
+;; same reason. Owning it from either tool leaves the other reading a projection registered by a
+;; namespace it does not require, so both tools once carried their own copy of this and the winner
+;; was decided by `api.clj`'s require order.
+(def ^:private metric-concise-keys
+ [:id :name :type :description :collection_id :database_id :table_id :source_card_id
+ :archived :query_summary])
+
+(def ^:private metric-detailed-keys
+ (into metric-concise-keys
+ [:entity_id :display :creator_id :created_at :updated_at]))
+
+(register-key-projection! :metric metric-concise-keys
+ :detailed-keys metric-detailed-keys)
+
+;;; ----------------------------------------------- dashboard ------------------------------------------------------
+
+(defn- dashcard-kind
+ [{:keys [card_id action_id visualization_settings]}]
+ (cond
+ action_id "action"
+ card_id "card"
+ :else (or (some->> (get-in visualization_settings [:virtual_card :display]) name (str "virtual_"))
+ "virtual")))
+
+(defn- dashcard-card-ref
+ "The `{id, name}` card reference for a card-backed dashcard. A dashcard carrying no `:card` —
+ never hydrated, or redacted away as unreadable — collapses to `{id}` only, as the REST
+ dashboard response does."
+ [{:keys [card_id action_id card]}]
+ (when (and card_id (not action_id))
+ (if card
+ {:id (:id card) :name (:name card)}
+ {:id card_id})))
+
+(defn- dashcard-summary
+ [{:keys [visualization_settings] :as dc}]
+ (m/remove-vals
+ nil?
+ {:id (:id dc)
+ :kind (dashcard-kind dc)
+ :card (dashcard-card-ref dc)
+ ;; External link URLs only — a link card's stored entity snapshot may describe something
+ ;; this user can't read, so it never rides the summary.
+ :text (when-not (:card_id dc)
+ (or (:text visualization_settings)
+ (get-in visualization_settings [:link :url])))
+ :dashboard_tab_id (:dashboard_tab_id dc)
+ :row (:row dc)
+ :col (:col dc)
+ :size_x (:size_x dc)
+ :size_y (:size_y dc)
+ :series (not-empty
+ (mapv #(m/remove-vals nil? (select-keys % [:id :name])) (:series dc)))
+ :inline_parameters (not-empty (:inline_parameters dc))}))
+
+(defn- dashboard-parameters-summary
+ "One row per dashboard parameter: id, name, type, and the ids of the dashcards it is wired
+ to (via [[dashboard/dashboard->resolved-params]], the same resolution the QP uses)."
+ [dash]
+ (let [resolved (dashboard/dashboard->resolved-params dash)]
+ (mapv (fn [{param-id :id :as param}]
+ (m/remove-vals
+ nil?
+ {:id param-id
+ :name (:name param)
+ :type (:type param)
+ :dashcard_ids (not-empty
+ (vec (sort (distinct (keep (comp :id :dashcard)
+ (:mappings (get resolved (u/qualified-name param-id))))))))}))
+ (:parameters dash))))
+
+(defn dashboard-row
+ "The projection row for `dash`, a dashboard hydrated with `[:dashcards :series :card] :tabs` and
+ already redacted. Both the `:concise` and `:detailed` projections select from this shape."
+ [dash]
+ (-> (select-keys dash [:id :name :description :entity_id :collection_id :creator_id :archived
+ :created_at :updated_at :width :auto_apply_filters :cache_ttl
+ :collection_position])
+ (assoc :tabs (mapv #(select-keys % [:id :name]) (:tabs dash))
+ :parameters (dashboard-parameters-summary dash)
+ :dashcards (mapv dashcard-summary
+ (sort-by (juxt #(or (:row %) 0) #(or (:col %) 0)) (:dashcards dash))))))
+
+(def ^:private dashboard-concise-keys
+ [:id :name :description :tabs :parameters :dashcards])
+
+(def ^:private dashboard-detailed-keys
+ (into dashboard-concise-keys
+ [:entity_id :collection_id :creator_id :archived :created_at :updated_at :width
+ :auto_apply_filters :cache_ttl :collection_position]))
+
+(def ^:private dashboard-sample
+ (-> (zipmap dashboard-detailed-keys (repeat "x"))
+ (assoc :tabs [{:id 1 :name "x"}]
+ :parameters [{:id "x" :name "x" :type "x" :dashcard_ids [1]}]
+ :dashcards [{:id 1 :kind "x" :card {:id 1 :name "x"} :text "x" :dashboard_tab_id 1
+ :row 0 :col 0 :size_x 1 :size_y 1 :series [{:id 1 :name "x"}]
+ :inline_parameters ["x"]}])))
+
+(register-key-projection!
+ :dashboard dashboard-concise-keys
+ :detailed-keys dashboard-detailed-keys
+ :sample dashboard-sample)
+
+;;; ----------------------------------------------- notification ---------------------------------------------------
+
+(defn- notification-recipient-row
+ [recipient]
+ (m/remove-vals nil?
+ {:type (some-> (:type recipient) u/qualified-name)
+ :user_id (:user_id recipient)
+ :email (or (get-in recipient [:user :email])
+ (get-in recipient [:details :value]))
+ :permissions_group_id (:permissions_group_id recipient)}))
+
+(defn- notification-handler-rows
+ "Projected handler rows. Recipients are projected as given: redaction happens before the
+ projection, and a handler whose `:recipients` were removed projects without the key."
+ [handlers]
+ (mapv (fn [handler]
+ (m/remove-vals
+ nil?
+ {:id (:id handler)
+ :channel_type (some-> (:channel_type handler) u/qualified-name)
+ :channel_id (:channel_id handler)
+ :recipients (some->> (:recipients handler) (mapv notification-recipient-row))}))
+ handlers))
+
+(defn notification-row
+ "The projection row for `notification`, already hydrated and recipient-redacted. Both the
+ `:concise` and `:detailed` `:alert` projections select from this shape."
+ [notification]
+ (m/remove-vals
+ nil?
+ {:id (:id notification)
+ :payload_type (some-> (:payload_type notification) u/qualified-name)
+ :active (:active notification)
+ :creator_id (:creator_id notification)
+ :created_at (:created_at notification)
+ :updated_at (:updated_at notification)
+ :payload (not-empty
+ (m/remove-vals nil? (select-keys (:payload notification)
+ [:card_id :send_condition :send_once])))
+ :subscriptions (mapv #(m/remove-vals nil?
+ {:type (some-> (:type %) u/qualified-name)
+ :cron_schedule (:cron_schedule %)
+ :ui_display_type (some-> (:ui_display_type %) u/qualified-name)})
+ (:subscriptions notification))
+ :handlers (notification-handler-rows (:handlers notification))}))
+
+(def alert-concise-keys
+ "Keys of the `:alert` concise projection. Also selected by the notification-backed half of the
+ `:subscription` projection, whose rows are [[notification-row]] output too."
+ [:id :active :payload :subscriptions :handlers :creator_id])
+
+(def alert-detailed-keys
+ "Keys of the `:alert` detailed projection."
+ (into alert-concise-keys [:payload_type :created_at :updated_at]))
+
+(def alert-sample
+ "A representative detailed `:alert` row, for `fields` catalog generation."
+ (-> (zipmap alert-detailed-keys (repeat "x"))
+ (assoc :payload {:card_id 1 :send_condition "x" :send_once true}
+ :subscriptions [{:type "x" :cron_schedule "x" :ui_display_type "x"}]
+ :handlers [{:id 1 :channel_type "x" :channel_id 1
+ :recipients [{:type "x" :user_id 1 :email "x" :permissions_group_id 1}]}])))
+
+(register-key-projection! :alert alert-concise-keys
+ :detailed-keys alert-detailed-keys
+ :sample alert-sample)
+
+;;; ------------------------------------------------ subscription --------------------------------------------------
+
+(defn- compact
+ [m]
+ (m/remove-vals nil? m))
+
+(defn subscription-row
+ "The projection row for `pulse-row`, a Pulse already hydrated and redacted. Both `get_content`
+ and `subscription_write` return this shape."
+ [pulse-row]
+ (compact
+ (-> (select-keys pulse-row [:id :name :dashboard_id :skip_if_empty :parameters :collection_id
+ :entity_id :creator_id :archived :created_at :updated_at])
+ (assoc :channels (mapv (fn [channel]
+ (compact
+ (-> (select-keys channel [:id :channel_type :schedule_type
+ :schedule_hour :schedule_day
+ :schedule_frame :enabled :details])
+ ;; `details.emails` is where recipients who aren't Metabase
+ ;; users are stored; `:recipients` below already carries
+ ;; them as `{:email …}`. `mi/to-json` strips it for every
+ ;; REST consumer, but that encoder hook only fires on a
+ ;; Toucan instance and `select-keys` returns a plain map.
+ (m/dissoc-in [:details :emails])
+ (assoc :recipients
+ (some->> (:recipients channel)
+ (mapv #(compact (select-keys % [:id :email]))))))))
+ (:channels pulse-row))
+ :cards (some->> (:cards pulse-row)
+ (mapv #(compact (select-keys % [:id :name :include_csv :include_xls
+ :format_rows]))))))))
+
+(def ^:private subscription-pulse-concise-keys
+ [:id :name :dashboard_id :channels :cards :skip_if_empty :archived :creator_id])
+
+(def ^:private subscription-pulse-detailed-keys
+ (into subscription-pulse-concise-keys
+ [:entity_id :collection_id :parameters :created_at :updated_at]))
+
+(def ^:private subscription-sample
+ (-> (zipmap subscription-pulse-detailed-keys (repeat "x"))
+ (assoc :channels [{:id 1 :channel_type "x" :schedule_type "x" :schedule_hour 1
+ :schedule_day "x" :schedule_frame "x" :enabled true
+ :details {}
+ :recipients [{:id 1 :email "x"}]}]
+ :cards [{:id 1 :name "x" :include_csv true :include_xls true :format_rows true}]
+ :parameters [{:id "x" :name "x" :type "x"}])))
+
+(register-projection!
+ :subscription
+ {:concise (fn [row]
+ (if (:handlers row)
+ (compact (select-keys row alert-concise-keys))
+ (compact (select-keys row subscription-pulse-concise-keys))))
+ :detailed (fn [row]
+ (if (:handlers row)
+ (compact (select-keys row alert-detailed-keys))
+ (compact (select-keys row subscription-pulse-detailed-keys))))
+ :sample subscription-sample
+ ;; The projection dispatches on row shape (pulse-backed vs. notification-backed), so no single
+ ;; sample captures it — the `fields` catalog is the union of both shapes' detailed paths.
+ :catalog (vec (sort (distinct (concat (paths-from-sample subscription-sample)
+ (paths-from-sample alert-sample)))))})
diff --git a/src/metabase/mcp/v2/queries.clj b/src/metabase/mcp/v2/queries.clj
new file mode 100644
index 00000000000..bd2924817e9
--- /dev/null
+++ b/src/metabase/mcp/v2/queries.clj
@@ -0,0 +1,173 @@
+(ns metabase.mcp.v2.queries
+ "The v2 MCP tools' query machinery: the representations pipeline entry point (validate ->
+ repair -> resolve, in the numeric-id dialect with v2 recovery sentences), portable-dialect
+ resolution for `definition` arguments, and the query-handle store (mint/resolve, with the
+ fresh-query guards re-run on every read). Landed with its first consumer (`metric_write`);
+ the execute tools (query PR) add the minting call sites."
+ (:require
+ [metabase.agent-api.query-guards :as query-guards]
+ [metabase.agent-api.settings :as agent-api.settings]
+ [metabase.lib.core :as lib]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.recovery-hints :as v2.recovery-hints]
+ [metabase.metabot.tools.construct :as metabot.construct]
+ [metabase.models.serialization.resolve :as serdes.resolve]
+ [metabase.util :as u]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private max-schema-detail-length
+ "Character budget for the humanized schema explanation appended to a structural failure. A
+ deeply nested query explains in kilobytes; the leading paths are the ones worth fixing first,
+ and an unbounded dump would crowd out the rest of the agent's context."
+ 500)
+
+(defn- with-schema-detail
+ "`e` with its humanized schema explanation folded into the message, or unchanged when it carries
+ none. The representations pipeline computes the explanation and files it under `:humanized` but
+ states only the bare verdict, which leaves an agent nothing to edit; only structural validation
+ failures carry the key, so the dialect steering is always apt where it lands."
+ [^clojure.lang.ExceptionInfo e]
+ (if-let [humanized (:humanized (ex-data e))]
+ (ex-info (str (ex-message e)
+ " Invalid at " (common/ellipsize (common/humanize-detail humanized) max-schema-detail-length)
+ ". Fix the named paths, or call `learn` with \"query-dialect\" for the clause shapes.")
+ (ex-data e)
+ (ex-cause e))
+ e))
+
+(defn execute-representations-query
+ "Run the shared representations pipeline (validate → repair → resolve) as the MCP v2 surface —
+ the one entry point for v2 tools that accept an agent-authored MBQL query. Binds the numeric-id
+ dialect on, and supplies v2's recovery sentences so a resolution failure names `browse_data` /
+ `search` rather than v1's `read_resource` / `metabase://` URIs. A structural failure gains the
+ offending paths ([[with-schema-detail]]), which the pipeline computes but does not state."
+ [external-query]
+ (binding [serdes.resolve/*numeric-ids-allowed?* true]
+ (try
+ (metabot.construct/execute-representations-query
+ external-query
+ {:recovery-hint v2.recovery-hints/recovery-hint})
+ (catch clojure.lang.ExceptionInfo e
+ (throw (with-schema-detail e))))))
+
+;;; ------------------------------------------------ Portable queries ----------------------------------------------
+
+(defn portable-query?
+ "True when `query` is a full query whose first stage names its source the way the portable
+ external dialect does — an FK path `[db schema table]` or a card entity_id — rather than a
+ numeric id."
+ [query]
+ (let [stage (first (:stages query))]
+ (or (vector? (:source-table stage))
+ (string? (:source-card stage)))))
+
+(defn resolve-external-query
+ "Resolve a full query in the portable external dialect through the same pipeline `execute_query`
+ runs a fresh `query` through — repair, portable-FK resolution, and the runnable/editor gates —
+ and return the serialized MBQL 5 query. Resolution only: the pipeline does not execute.
+
+ The pipeline's own agent-facing failures become a teaching error about the `definition`
+ argument, ending in `hint` (a sentence naming the shapes the calling tool accepts); permission
+ failures and anything unrecognized pass through."
+ [external-query hint]
+ (try
+ ;; Through the v2 entry point, not the raw pipeline: a `definition` gets the same numeric-id
+ ;; dialect and the same v2 recovery sentences a fresh `execute_query` body would.
+ (-> (execute-representations-query external-query)
+ (get-in [:structured-output :query])
+ lib/prepare-for-serialization)
+ (catch clojure.lang.ExceptionInfo e
+ (if (:agent-error? (ex-data e))
+ (common/throw-teaching-error
+ (format "`definition` could not be resolved: %s %s" (common/ellipsize (ex-message e) 300) hint))
+ (throw e)))))
+
+;;; ------------------------------------------------ Query handles -------------------------------------------------
+
+(defn encode-serialized-query
+ "Base64-encode a serialized MBQL query map ([[metabase.lib.core/prepare-for-serialization]] output)
+ for storage in the query-handle store. The inverse of the decode step in [[resolve-query-handle!]]."
+ [serialized-query]
+ (-> serialized-query json/encode u/encode-base64))
+
+(defn mint-query-handle!
+ "Store `encoded-query` (base64 serialized MBQL, exactly what ran — see [[encode-serialized-query]])
+ under a fresh handle owned by `user-id`, with the user's original `prompt` alongside for the
+ visualization feedback flow. Returns the handle UUID string. Execute tools mint on every call,
+ including `validate_only`, so what the agent later saves or visualizes through the handle is
+ byte-identical to what ran."
+ ([mcp-session-id user-id encoded-query]
+ (mint-query-handle! mcp-session-id user-id encoded-query nil))
+ ([mcp-session-id user-id encoded-query prompt]
+ (mcp.session/store-handle! mcp-session-id user-id encoded-query prompt)))
+
+(defn- decode-stored-query
+ "Decode a stored handle's base64 query payload to a map, surfacing garbage as a teaching error
+ rather than a decode exception."
+ [encoded]
+ (let [decoded (try
+ (-> encoded u/decode-base64 json/decode+kw)
+ (catch Exception _ ::invalid))]
+ (if (map? decoded) ;; catch ::invalid and non-map values
+ decoded
+ (common/throw-teaching-error "Query handle contents are invalid — run the query again to get a fresh handle."))))
+
+(defn resolve-query-handle!
+ "Resolve `handle` for `user-id` and re-run the fresh-query guards on the stored query, so a
+ handle can never smuggle native SQL past the MBQL-scoped tools or grant access the caller has
+ since lost. Returns `{:query <decoded MBQL map> :prompt <string-or-nil>}`, or throws a teaching
+ error (unknown/expired handle, native query, malformed query, or missing permissions).
+
+ MBQL-path callers only: the MCP Apps UI tools read handles directly through
+ [[metabase.mcp.session/resolve-query-handle]] — a native/SQL handle is visualizable by design,
+ so the native-reject guard must never move into the store's read path."
+ [mcp-session-id user-id handle]
+ (let [{:keys [encoded_query prompt]}
+ (or (mcp.session/resolve-query-handle mcp-session-id user-id handle)
+ (common/throw-teaching-error "Query handle not found — it may have expired; run the query again."))
+ query (decode-stored-query encoded_query)]
+ (query-guards/reject-native-query! query)
+ (query-guards/validate-serialized-query! query)
+ (query-guards/check-token-query-permissions! query)
+ {:query query :prompt prompt}))
+
+(defn resolve-query-handle-for-save!
+ "Like [[resolve-query-handle!]] but for the save/write path: resolves `handle` for `user-id`,
+ re-runs the shape and permission guards, and — unlike the MBQL read path — DOES allow a native
+ query through. `execute_sql` mints handles specifically so their SQL can be saved; the
+ native-reject guard would otherwise make those handles unsaveable. Returns
+ `{:query <decoded map> :prompt <string-or-nil>}`, or throws a teaching error."
+ [mcp-session-id user-id handle]
+ (let [{:keys [encoded_query prompt]}
+ (or (mcp.session/resolve-query-handle mcp-session-id user-id handle)
+ (common/throw-teaching-error "Query handle not found — it may have expired; run the query again."))
+ query (decode-stored-query encoded_query)]
+ (query-guards/validate-serialized-query! query)
+ (query-guards/check-token-query-permissions! query)
+ {:query query :prompt prompt}))
+
+;;; ------------------------------------------------ Raw-SQL kill switch -------------------------------------------
+
+(defn check-execute-sql-enabled!
+ "Throw a 403 unless the instance-level `mcp-execute-sql-enabled` kill switch is on. `subject`
+ opens the refusal sentence, naming what the instance refused.
+
+ The gate covers every v2 path on which the AGENT AUTHORS the SQL — `execute_sql` itself, and
+ `question_write` / `transform_write` storing agent-authored native SQL — so a switch an admin
+ turned off is not reachable by a second route to the same capability.
+
+ It deliberately does not cover running SQL that already exists as a saved, permission-checked
+ artifact: `run_saved_question` executes a stored native card without consulting it, as does
+ `execute_query` over a `:source-card` naming one. That matches the setting's own scope —
+ \"Whether the MCP `execute_sql` tool is available\" — and the read check on the card is what
+ guards those. Turning the switch off removes the agent's ability to write SQL, not the
+ instance's ability to run questions it already has."
+ [subject]
+ (when-not (agent-api.settings/mcp-execute-sql-enabled)
+ (throw (ex-info (format (str "%s is disabled on this instance — an admin can re-enable it "
+ "with the mcp-execute-sql-enabled setting.")
+ subject)
+ {:status-code 403}))))
diff --git a/src/metabase/mcp/v2/query.clj b/src/metabase/mcp/v2/query.clj
new file mode 100644
index 00000000000..0355301304e
--- /dev/null
+++ b/src/metabase/mcp/v2/query.clj
@@ -0,0 +1,488 @@
+(ns metabase.mcp.v2.query
+ "Keyset cursors for the v2 query tools. A cursor is an ordinary query handle whose stored query
+ already embeds the page boundary — the same resolved query with a server-derived total order
+ and a keyset predicate past the last returned row — so paging is just another query on the
+ existing handle store: no page-state column, no content-addressing, no schema change."
+ (:require
+ [clojure.walk :as walk]
+ [metabase.agent-api.query-guards :as query-guards]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.util.log :as log]))
+
+(set! *warn-on-reflection* true)
+
+(defn- order-by-specs
+ "Map the last stage's order-bys onto positions in `ret-cols` as `[{:idx :dir} …]`, preserving
+ order. Returns nil when an order-by targets a column outside the projection — its boundary
+ value would be unreadable from the last returned row, so no gap-free cursor is possible."
+ [query ret-cols]
+ (reduce (fn [specs [dir _opts expr]]
+ (let [col (lib/find-matching-column query -1 expr ret-cols)
+ idx (if col (.indexOf ^java.util.List ret-cols col) -1)]
+ (if (neg? idx)
+ (reduced nil)
+ (conj specs {:idx idx :dir dir}))))
+ []
+ (lib/order-bys query)))
+
+(defn- pk-index
+ "Position in `ret-cols` of the source table's PK, when the query sources a table directly and
+ the PK is in the projection."
+ [resolved-query ret-cols]
+ (let [source-table (get-in resolved-query [:stages 0 :source-table])]
+ (when (int? source-table)
+ (some (fn [[i col]]
+ (when (and (= (:semantic-type col) :type/PK)
+ (= (:table-id col) source-table))
+ i))
+ (map-indexed vector ret-cols)))))
+
+(defn- explicit-join?
+ "True when `query-map` carries a non-empty `:joins` anywhere in its tree — a stage's own joins,
+ a join's sub-stages, and legacy `:source-query` nesting alike. A whole-tree scan because a
+ join at any depth can fan the result out, and the map may be MBQL 5 or a card's still-legacy
+ stored query."
+ [query-map]
+ (boolean (some (fn [node] (and (map? node) (seq (:joins node))))
+ (tree-seq coll? seq query-map))))
+
+(defn- source-card-ids
+ "Card ids `query-map` sources at any depth: MBQL 5 `:source-card`, plus the legacy
+ `:source-table \"card__<id>\"` spelling a card's own stored query may still use."
+ [query-map]
+ (let [legacy-id (fn [source-table]
+ (when (string? source-table)
+ (some-> (re-matches #"card__(\d+)" source-table) second parse-long)))]
+ (into #{}
+ (comp (filter map?)
+ (mapcat (juxt :source-card (comp legacy-id :source-table)))
+ (filter int?))
+ (tree-seq coll? seq query-map))))
+
+(defn- fan-out-join?
+ "True when the query — or any saved question it sources, transitively — carries an explicit
+ join. Join cardinality isn't knowable from metadata, so every join is assumed able to fan the
+ source table out 1:many. Implicit joins (`:source-field` field refs) resolve many:1 against
+ the target table's PK and cannot fan out, so they don't count. A sourced card whose stored
+ query can't be read counts as a fan-out: an unreadable source can't be shown join-free, and
+ the contract here is to refuse rather than page over an unproven shape."
+ [metadata-providerable resolved-query]
+ (loop [pending (list resolved-query), seen #{}]
+ (if-let [query-map (first pending)]
+ (or (explicit-join? query-map)
+ (let [ids (vec (remove seen (source-card-ids query-map)))
+ sourced (reduce (fn [acc id]
+ (if-let [stored (:dataset-query (lib.metadata/card metadata-providerable id))]
+ (conj acc stored)
+ (reduced nil)))
+ []
+ ids)]
+ (if sourced
+ (recur (into (rest pending) sourced) (into seen ids))
+ true)))
+ false)))
+
+(defn- passthrough-stage?
+ "True when stage `stage-number` cannot change row identity: no joins (a join can fan the rows
+ out) and no `:fields` (a re-projection can drop the very columns that made the tuple unique).
+ Filters, expressions and limits all preserve row identity and are fine."
+ [query stage-number]
+ (and (empty? (lib/joins query stage-number))
+ (nil? (:fields (lib/query-stage query stage-number)))))
+
+(defn- aggregation-derived-unique?
+ "True when the full projected tuple is unique per result row because an aggregating stage
+ produced those rows — they are distinct by breakout tuple, and an aggregated stage projects
+ every breakout — and every stage after it merely passes them through.
+
+ The look-back is load-bearing, not defensive: [[next-page-query]] carries an aggregated
+ query's keyset in an appended stage, so from page 2 on the LAST stage is that appended
+ pass-through, unaggregated and PK-less. A proof that only inspected the last stage would kill
+ the chain at page 2."
+ [query]
+ (loop [stage-number (dec (lib/stage-count query))]
+ (cond
+ (neg? stage-number) false
+ (or (seq (lib/aggregations query stage-number))
+ (seq (lib/breakouts query stage-number))) true
+ (passthrough-stage? query stage-number) (recur (dec stage-number))
+ :else false)))
+
+(defn- unique-key-specs
+ "Specs for a key proven unique per result row, or nil when no such proof exists. Two proofs:
+ the projected source-table PK (the fan-out guard in [[next-page-query]] is what upgrades its
+ metadata-level uniqueness to a row-level fact), or a full projected tuple an aggregation made
+ distinct.
+
+ Nil is the honest answer for an unaggregated projection that drops the PK — a `fields`
+ selection of non-unique columns, say. Its full tuple repeats, so no order over it is total
+ and the strictly-past-the-boundary keyset would skip every row tied with the boundary. There
+ is no gap-free cursor to mint; the caller is steered to narrow instead."
+ [resolved-query query ret-cols]
+ (if-let [pk-idx (pk-index resolved-query ret-cols)]
+ [{:idx pk-idx :dir :asc}]
+ (when (aggregation-derived-unique? query)
+ (mapv (fn [i] {:idx i :dir :asc}) (range (count ret-cols))))))
+
+(defn- tiebreaker-specs
+ "The unique key's columns that aren't already ordered — the deterministic tiebreakers to append
+ after the existing order-bys to make the row order total.
+
+ Three distinguishable answers, and both callers depend on telling them apart. Nil: no unique
+ key can be proven, so no total order exists and no cursor is possible ([[with-total-order]]
+ leaves the query alone; [[next-page-query]] refuses). Empty: the query's own order is already
+ total — the condition [[next-page-query]] mints on and the condition [[with-total-order]]
+ establishes. Non-empty: the tiebreakers that would establish it."
+ [resolved-query query ret-cols ordered-idxs]
+ (when-let [key-specs (unique-key-specs resolved-query query ret-cols)]
+ (into [] (remove (comp ordered-idxs :idx)) key-specs)))
+
+(defn- serialize-preserving-parameters
+ "`query` serialized, with `:parameters` carried over from `serialized-query`.
+
+ [[lib/prepare-for-serialization]] strips `:parameters` as runtime-only, but for an MBQL query
+ they are a real filter: the QP's parameter middleware ANDs them onto the query. Any rewrite that
+ round-trips through serialization must put them back, or the rewritten query asks a wider
+ question than the caller did. `execute_sql` re-attaches them the same way for the same reason."
+ [serialized-query query]
+ (cond-> (lib/prepare-for-serialization query)
+ (seq (:parameters serialized-query)) (assoc :parameters (:parameters serialized-query))))
+
+(defn- keyset-filter-clause
+ "Lexicographic strictly-past-the-boundary predicate over the key columns:
+ `(k₀ cmp v₀) OR (k₀ = v₀ AND k₁ cmp v₁) OR …`, where `cmp` is `>` for `:asc` keys and `<` for
+ `:desc`. `values` are the boundary row's values aligned with `specs`."
+ [target-cols specs values]
+ (let [cmp (fn [{:keys [idx dir]} v]
+ (if (= dir :desc)
+ (lib/< (nth target-cols idx) v)
+ (lib/> (nth target-cols idx) v)))
+ eq (fn [{:keys [idx]} v]
+ (lib/= (nth target-cols idx) v))
+ terms (map-indexed
+ (fn [i spec]
+ (let [eqs (map eq (take i specs) (take i values))]
+ (if (seq eqs)
+ (apply lib/and (concat eqs [(cmp spec (nth values i))]))
+ (cmp spec (nth values i)))))
+ specs)]
+ (if (= 1 (count terms))
+ (first terms)
+ (apply lib/or terms))))
+
+(def ^:private keyset-marker
+ "Option key stamped on a filter clause this namespace minted, so the next page can supersede its
+ predecessor instead of stacking a dead predicate beside it.
+
+ Superseding is sound, not merely tidy: every row the new predicate admits lies strictly past a
+ boundary row that itself satisfied the old one, so the new predicate implies the old and
+ dropping it cannot widen the result.
+
+ The marker rides in a clause's options map, and `metabase.lib.schema.common/::options` is
+ `:closed true` — so it has to be DECLARED there, alongside the keys Mongo, SQL Server and the
+ add-alias-info/add-remaps middleware stamp. An undeclared key is rejected, not tolerated:
+ `lib/filter` refuses the stamped clause outright, and because [[next-page-cursor!]] treats any
+ failure to build a cursor as \"this query cannot be paged\", the rejection surfaces as cursors
+ silently never being minted rather than as an error. `internal-keys-fixture-covers-the-schemas-test`
+ is what keeps the declaration and its serialization fixture in step."
+ ::keyset)
+
+(defn- minted-keyset?
+ [clause]
+ (and (vector? clause) (true? (get-in clause [1 keyset-marker]))))
+
+(defn- stage-without-minted-keysets
+ [stage]
+ (if-let [kept (not-empty (into [] (remove minted-keyset?) (:filters stage)))]
+ (assoc stage :filters kept)
+ (dissoc stage :filters)))
+
+(defn strip-caller-keyset-markers
+ "`serialized-query` with [[keyset-marker]] removed from every clause's options, everywhere in the
+ map.
+
+ The marker identifies a predicate *this namespace* minted, and two behaviours depend on that:
+ [[without-page-boundary]] drops marked filters from the query a handle stores, and
+ [[supersede-previous-keyset]] drops them from the query the next page runs. Neither is safe if a
+ caller can mint the mark itself — and it can, since a tool's `:query` is an open `[:map]` and a
+ namespaced option key rides through JSON decode and serialization untouched. A caller that
+ stamps its own filter gets that filter silently dropped from the saved handle and from every
+ later page, so the tool reports a narrow question while serving wide rows.
+
+ Run every caller-supplied query through this so only server-minted clauses can carry the mark."
+ [serialized-query]
+ (walk/postwalk (fn [x]
+ (if (and (map? x) (contains? x keyset-marker))
+ (dissoc x keyset-marker)
+ x))
+ serialized-query))
+
+(defn- supersede-previous-keyset
+ "`query`'s last stage with the keyset predicates this namespace minted removed, so the caller can
+ add the current page's in their place. Filters the caller wrote are untouched."
+ [query]
+ (lib/update-query-stage query -1 stage-without-minted-keysets))
+
+(defn without-page-boundary
+ "`serialized-query` with the keyset predicate this namespace minted stripped from its last stage,
+ or unchanged when it carries none.
+
+ A cursor page's stored query embeds the boundary it resumed from — that is how paging works —
+ but a boundary is a scroll position, not part of the question. A query handle is what a later
+ tool saves or visualizes, so mint it from this: saving page 3 of an orders listing should save
+ the orders question, never `orders WHERE id > 4171`. Paging is untouched, since the cursor
+ carries its own boundary.
+
+ Only predicates this namespace minted come off (see [[keyset-marker]]); a filter the caller
+ wrote is part of the question and stays. Works on the serialized map rather than a rehydrated
+ query, so cleaning a stored handle needs no metadata.
+
+ One mark of a cursor page it cannot undo: a query carrying its own `:limit` has that limit spent
+ down across pages, so a deep page's handle asks for the rows still owed rather than the count
+ the caller wrote. Recovering that would need state the handle store deliberately does not keep."
+ [serialized-query]
+ (let [stages (vec (:stages serialized-query))]
+ (if-let [stage (peek stages)]
+ (if (some minted-keyset? (:filters stage))
+ (assoc serialized-query :stages
+ (assoc stages (dec (count stages)) (stage-without-minted-keysets stage)))
+ serialized-query)
+ serialized-query)))
+
+(def ^:private exact-temporal-units
+ "Truncation units at or coarser than a second. A value truncated this far renders without
+ sub-second digits, so the emitted string parses back to exactly the value that was compared."
+ #{:second :minute :hour :day :week :month :quarter :year})
+
+(defn- lossy-boundary-col?
+ "True when `col`'s emitted row values can't be trusted to round-trip exactly into a comparison
+ literal. Raw datetime/time values are the offender: the row carries a formatted string
+ (millisecond precision at best, driver-dependent rendering), so a keyset predicate built from
+ it can re-include or skip boundary rows. Plain dates and bucket-truncated values render
+ exactly and are safe."
+ [col]
+ (and (isa? (:effective-type col) :type/Temporal)
+ (not (isa? (:effective-type col) :type/Date))
+ (not (contains? exact-temporal-units (:unit (lib/temporal-bucket col))))))
+
+(defn- nullable-key-cols?
+ "True when any column in `cols` can hold NULL — the condition that makes a keyset cursor lose rows.
+
+ A keyset predicate is built purely from comparisons (`k > v`, `k = v`), and under SQL's
+ three-valued logic every one of those is NULL — never true — for a row whose key column is NULL.
+ Such a row fails the next-page predicate and is never served, even though it sorted after the
+ boundary in the order that actually ran. The `(every? some? values)` guard on the boundary row
+ does not catch this: it fires only when a page boundary happens to land inside the NULL run,
+ while the rows lost are the whole run.
+
+ Refusing is the honest answer rather than a fix. Where the NULL block sorts is driver-dependent
+ (the SQL QP emits no explicit `NULLS FIRST`/`LAST`), and MBQL cannot express a null-aware
+ comparison, so there is no predicate this namespace could build that is correct on every driver.
+ This joins the remap and lossy-value checks in [[next-page-query]]: an unusable key means no
+ cursor, not a cursor with gaps.
+
+ Two signals, both read from the app DB because lib column metadata carries neither. A column is
+ unsafe only when it is BOTH declared nullable AND has been observed to hold NULLs
+ (`fingerprint.global.nil%`). Declared nullability alone is far too blunt to gate on — in a
+ typical warehouse only primary keys are NOT NULL, so refusing on it would cost the cursor for
+ nearly every query that orders by anything else, trading a silent-rows bug for a broad loss of
+ paging. The fingerprint is what distinguishes a column that merely permits NULLs from one that
+ actually contains them.
+
+ The fingerprint is a sync-time sample, so `nil% = 0.0` is strong evidence rather than proof: a
+ column that gains its first NULL after the last sync stays cursorable until the next one. That
+ residual is bounded by sync frequency and is the price of keeping paging usable at all.
+
+ Columns that are not plain field refs (expression and aggregation outputs) have no `:id`, so
+ nothing is known about them and they are treated as safe on the same reasoning — refusing on
+ every aggregate would disable the aggregated cursor path wholesale."
+ [cols]
+ (let [field-ids (into #{} (keep :id) cols)]
+ (boolean
+ (when (seq field-ids)
+ (->> (mcp.db/nullable-fields-with-fingerprints field-ids)
+ (some (fn [field]
+ (pos? (or (get-in (:fingerprint field) [:global :nil%]) 0)))))))))
+
+(defn- row-positions
+ "Positions in the result row of the query's projected columns, in projection order. The remap
+ middleware can inject display columns anywhere in the row (each marked `:remapped_from`);
+ dropping those must leave exactly the projection, verified 1:1 by name. Without the run's
+ `result-cols` the row must be exactly the projection. Nil when alignment can't be proven —
+ a misaligned read would build a wrong boundary, which is worse than no cursor."
+ [ret-cols result-cols last-row]
+ (let [positions (if result-cols
+ (into [] (keep-indexed (fn [i col] (when-not (:remapped_from col) i))) result-cols)
+ (vec (range (count ret-cols))))]
+ (when (and (= (count positions) (count ret-cols))
+ (every? #(< % (count last-row)) positions)
+ (if result-cols
+ (every? (fn [[ret-col pos]]
+ (= (:name ret-col) (:name (nth result-cols pos))))
+ (map vector ret-cols positions))
+ (= (count last-row) (count ret-cols))))
+ positions)))
+
+(defn- next-page-query
+ "The serialized next-page query for `resolved-query` given the truncated page's `last-row`
+ (and the run's `result-cols` metadata, used to locate the projected columns in the row), or
+ nil when no gap-free cursor can be built.
+
+ The page's keyset filter supersedes the previous page's rather than joining it: each is
+ stamped with [[keyset-marker]], and a stamped predicate on the target stage is dropped before
+ the new one goes on. Left to accumulate they would grow the stored query, the emitted `WHERE`,
+ and the warehouse's planning cost linearly with page depth, all of them dead — see
+ [[keyset-marker]] for why dropping them cannot change the result.
+
+ An unaggregated last stage takes the order and keyset filter in place — the filter applies
+ before the stage's own limit, so an embedded limit still yields exactly the next page. An
+ aggregated last stage takes them in an appended stage (an in-stage filter would apply
+ pre-aggregation); if that stage also carries its own limit the base set is cut before the
+ total order can pin it down, so no cursor.
+
+ Mints only for a query whose own order is already total — an empty [[tiebreaker-specs]]. A
+ page served under a partial order broke its ties however the engine happened to, and no
+ tiebreaker derived here can agree with an order that execution never ran under: around a
+ boundary inside a tie group the two disagree, dropping rows and repeating others.
+ [[with-total-order]] is what establishes the condition, by imposing the tiebreakers on the
+ execution itself; a query that reaches here without them gets no cursor.
+
+ A query that joins — directly, or through a saved question it sources — gets no cursor even
+ with the order imposed. A 1:many join repeats the source-table PK across result rows, so the
+ PK tiebreaker isn't unique per row and the order it makes isn't total after all; the
+ full-tuple fallback can't be trusted either, since fanned-out rows can be wholly identical.
+ A joined query is an explicit dead end rather than paging with silent gaps."
+ [resolved-query result-cols last-row]
+ (let [mp (lib-be/application-database-metadata-provider (:database resolved-query))]
+ (when-not (fan-out-join? mp resolved-query)
+ (let [query (lib/query mp resolved-query)
+ aggregated? (boolean (or (seq (lib/aggregations query))
+ (seq (lib/breakouts query))))]
+ (when-not (and aggregated? (lib/current-limit query))
+ (let [ret-cols (vec (lib/returned-columns query))
+ positions (when (and (seq ret-cols) (sequential? last-row))
+ (row-positions ret-cols result-cols last-row))]
+ (when positions
+ (when-let [specs (order-by-specs query ret-cols)]
+ (when (= [] (tiebreaker-specs resolved-query query ret-cols (into #{} (map :idx) specs)))
+ (let [;; read post-`js-int-to-string?`, so an integer past 2^53 arrives here as a
+ ;; string and goes into the predicate as one. It compiles numerically all the
+ ;; same: the QP's `wrap-value-literals` types the bare literal from the column
+ ;; and `auto-parse-filter-values` parses it, both above the driver layer.
+ ;; Pinned by `large-integer-boundary-paging-test`.
+ values (mapv #(nth last-row (nth positions (:idx %))) specs)
+ ;; a remapped column can't be a cursor key (the remap middleware rewrites an
+ ;; order-by on it to sort by the display value, so the executed order and the
+ ;; keyset predicate — which compares raw values — would disagree: a gap), and
+ ;; neither can a column whose boundary value doesn't round-trip exactly.
+ key-cols (mapv #(nth ret-cols (:idx %)) specs)
+ unsafe-key? (or (some (fn [col]
+ (or (:lib/external-remap col)
+ (:lib/internal-remap col)
+ (lossy-boundary-col? col)))
+ key-cols)
+ ;; a NULL in any key column makes every comparison term
+ ;; NULL, so the row is silently never served
+ (nullable-key-cols? key-cols))]
+ (when (and (seq specs) (not unsafe-key?) (every? some? values))
+ (let [base (if aggregated? (lib/append-stage query) query)
+ target-cols (if aggregated? (vec (lib/returned-columns base)) ret-cols)
+ ;; the unaggregated stage already carries the total order; the appended
+ ;; stage starts bare, so it is re-imposed there.
+ with-order (if aggregated?
+ (reduce (fn [q {:keys [idx dir]}]
+ (lib/order-by q (nth target-cols idx) dir))
+ base
+ specs)
+ base)]
+ (->> (-> with-order
+ supersede-previous-keyset
+ (lib/filter (-> (keyset-filter-clause target-cols specs values)
+ (assoc-in [1 keyset-marker] true))))
+ (serialize-preserving-parameters resolved-query))))))))))))))
+
+(defn with-total-order
+ "`serialized-query` with the tiebreakers that make its row order total appended to the last
+ stage's order-bys — the same total order [[next-page-cursor!]] seeks past, imposed on the
+ execution itself so the page that was served and the page that continues it agree on how ties
+ break. Run a query through this before executing it if it may later be paged: a cursor is
+ minted only for a query whose order is already total, so skipping this costs paging, never
+ correctness.
+
+ Returns the query unchanged when its order is already total, when no tiebreakers can be
+ derived (an order-by outside the projection, or a projection with no provable unique key —
+ see [[unique-key-specs]]), when a join makes them unsound anyway (see [[next-page-query]]), or
+ on any failure to rehydrate or manipulate the query. Idempotent: a second pass finds every
+ tiebreaker already ordered."
+ [serialized-query]
+ (or (when (and (map? serialized-query)
+ (pos-int? (:database serialized-query))
+ (sequential? (:stages serialized-query))
+ (seq (:stages serialized-query))
+ (not (query-guards/native-query? serialized-query)))
+ (try
+ (let [mp (lib-be/application-database-metadata-provider (:database serialized-query))]
+ (when-not (fan-out-join? mp serialized-query)
+ (let [query (lib/query mp serialized-query)
+ ret-cols (vec (lib/returned-columns query))]
+ (when-let [ordered (order-by-specs query ret-cols)]
+ (when-let [tiebreakers (seq (tiebreaker-specs serialized-query query ret-cols
+ (into #{} (map :idx) ordered)))]
+ (->> (reduce (fn [q {:keys [idx dir]}]
+ (lib/order-by q (nth ret-cols idx) dir))
+ query
+ tiebreakers)
+ (serialize-preserving-parameters serialized-query)))))))
+ (catch Exception e
+ (log/warn e "Failed to impose a total order on the query")
+ nil)))
+ serialized-query))
+
+(defn next-page-cursor!
+ "For a truncated MBQL page, build the next-page query (the same resolved query with a
+ server-derived total order appended and a keyset predicate past `last-row`), store it as an
+ ordinary handle, and return that handle's UUID for use as an opaque `next_cursor`.
+
+ `resolved-query` is the decoded serialized MBQL map that ran; `last-row` is the page's last
+ returned row. Opts:
+
+ - `:result-cols` — the run's `[:data :cols]` metadata. Pass it whenever available: the remap
+ middleware can inject display columns anywhere in the row, and without `result-cols` the
+ row must match the projection exactly or no cursor is minted.
+ - `:prompt` — the user's original prompt, carried onto the cursor handle for the
+ visualization feedback flow.
+
+ `resolved-query` must be what actually ran, and must have been run through
+ [[with-total-order]] first — the keyset seeks past the boundary in the query's own order, so
+ a page served under a partial order has no continuation to seek.
+
+ Returns nil whenever a gap-free cursor cannot be guaranteed: native SQL anywhere in the
+ tree, an order that isn't already total, an explicit join anywhere — directly or inside a
+ sourced saved question, or a sourced question whose stored query can't be read (a fan-out
+ defeats every tiebreaker — see [[next-page-query]]), an order-by outside the projection, a
+ row that can't be aligned with the projection, a nil boundary value, a key column that is
+ remapped, nullable in the warehouse (see [[nullable-key-cols?]]), or whose values don't
+ round-trip exactly (raw datetimes), a projection with no provable unique key — an unaggregated stage whose `:fields` drops the source-table PK, whose
+ repeating tuple no order can break ties on (see [[unique-key-specs]]) — an aggregated stage
+ carrying its own limit, or any failure to rehydrate or manipulate the query."
+ ([mcp-session-id user-id resolved-query last-row]
+ (next-page-cursor! mcp-session-id user-id resolved-query last-row nil))
+ ([mcp-session-id user-id resolved-query last-row {:keys [result-cols prompt]}]
+ (when (and (map? resolved-query)
+ (pos-int? (:database resolved-query))
+ (sequential? (:stages resolved-query))
+ (seq (:stages resolved-query))
+ (not (query-guards/native-query? resolved-query)))
+ (when-let [serialized (try
+ (next-page-query resolved-query result-cols last-row)
+ (catch Exception e
+ (log/warn e "Failed to build a next-page cursor query")
+ nil))]
+ (v2.queries/mint-query-handle! mcp-session-id
+ user-id
+ (v2.queries/encode-serialized-query serialized)
+ prompt)))))
diff --git a/src/metabase/mcp/v2/recipients.clj b/src/metabase/mcp/v2/recipients.clj
new file mode 100644
index 00000000000..5be92e7bc95
--- /dev/null
+++ b/src/metabase/mcp/v2/recipients.clj
@@ -0,0 +1,33 @@
+(ns metabase.mcp.v2.recipients
+ "The recipient vocabulary shared by the v2 MCP tools that deliver email — `alert_write` and
+ `subscription_write`. Both accept the same two shapes from an agent, a Metabase user id or a
+ bare email address, and must reject the same inputs; they differ only in how the accepted
+ recipient is stored (a notification recipient vs. a pulse channel recipient), which is why the
+ validation lives here and the shaping stays in each tool."
+ (:require
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(defn classify
+ "Classify one entry of a tool's `recipients` list as `[:user user-id]` or `[:email address]`.
+ Throws a teaching error for anything else, including an id no active user has — that one would
+ otherwise surface as a foreign key violation at insert time."
+ [recipient]
+ (cond
+ (int? recipient)
+ (do
+ (when-not (mcp.db/active-user-exists? recipient)
+ (common/throw-teaching-error
+ (format "No active user with id %d — pass a user id from the people list, or an email address."
+ recipient)))
+ [:user recipient])
+
+ (u/email? recipient)
+ [:email recipient]
+
+ :else
+ (common/throw-teaching-error
+ (format "Recipient %s is neither a user id nor an email address." (pr-str recipient)))))
diff --git a/src/metabase/mcp/v2/recovery_hints.clj b/src/metabase/mcp/v2/recovery_hints.clj
new file mode 100644
index 00000000000..ea35eee79dd
--- /dev/null
+++ b/src/metabase/mcp/v2/recovery_hints.clj
@@ -0,0 +1,81 @@
+(ns metabase.mcp.v2.recovery-hints
+ "The v2 surface's recovery sentences for the shared representations pipeline's agent errors.
+
+ The pipeline throws a bare statement of what went wrong plus structured `ex-data`; it does
+ not know which tools the caller has. This namespace turns that `ex-data` into the sentence
+ telling *this* surface's agent how to recover. The v2 query entry point must pass it to
+ `construct/execute-representations-query` as `:recovery-hint` — the same way the v1 entry
+ points pass [[metabase.metabot.tools.recovery-hints/recovery-hint]]. Until the v2 query slice
+ lands, this namespace has no production caller: nothing on the v2 surface reaches the shared
+ pipeline yet, so wiring it is that slice's responsibility, not an accomplished fact.
+
+ Keep every sentence inside v2's own vocabulary — `browse_data`, `search`, numeric ids. An
+ error key with no entry here yields no sentence, which is the intended failure mode: a
+ missing hint reads as terse, a wrong one sends the agent at a tool it does not have."
+ (:require
+ [metabase.util.i18n :refer [tru]]))
+
+(set! *warn-on-reflection* true)
+
+(defn- uri-hint
+ "The `source-table:`-took-a-URI sentence, which varies by what the URI pointed at."
+ [entity-type entity-id]
+ (case entity-type
+ ;; The `{}` options slot has to sit outside the format string — MessageFormat reads a brace
+ ;; as a placeholder, and `tru` rejects the escaped form as a skipped argument index.
+ "metric"
+ (str (tru "Metrics are aggregations, not sources. To use metric {0}, put its base table''s numeric id into `source-table:` (find it via `search` or `browse_data`) and reference the metric by its numeric id:"
+ (str entity-id))
+ " `aggregation: [[metric, {}, " entity-id "]]`.")
+
+ ("question" "model" "card")
+ (tru "To reference a saved question or model as a query source, put its bare numeric id into `source-card:` — not a URI: `\"source-card\": {0}`."
+ (str entity-id))
+
+ "table"
+ (tru "Use the bare numeric table id in `source-table:` — not a URI: `\"source-table\": {0}`."
+ (str entity-id))
+
+ (tru "`source-table:` accepts a numeric table id; `source-card:` accepts a saved-card numeric id.")))
+
+(defn recovery-hint
+ "The v2 recovery sentence for an agent error's `ex-data`, or nil when it has none."
+ [{:keys [error entity-type entity-id]}]
+ (case error
+ :uri-in-source-table
+ (uri-hint entity-type entity-id)
+
+ (:unknown-table :unknown-table-id)
+ ;; On the numeric-id surface both keys resolve the same way: list the tables and pick a
+ ;; numeric id. (v1 keeps them separate because a portable-FK miss and a numeric-id miss want
+ ;; different vocabulary; here both want the numeric id.)
+ (tru "Call `browse_data` with action \"list_tables\" to list available tables with their numeric ids, then use one as `source-table`.")
+
+ :ambiguous-table
+ (tru "Call `browse_data` with action \"list_tables\" for the database, then retry with the numeric table id — it is never ambiguous.")
+
+ (:unknown-field :unknown-field-id)
+ (tru "Call `browse_data` with action \"get_fields\" for the table to list its columns with their numeric ids.")
+
+ :ambiguous-fk
+ (tru "Call `browse_data` with action \"get_fields\" for the source table to list the available foreign-key columns.")
+
+ :no-fk-path
+ (tru "If a metric relates to that table, call `browse_data` with action \"get_fields\" for the table that owns the metric to read its dimensions, which give the exact `joins:` clause.")
+
+ (:unknown-card :unknown-card-id)
+ (tru "Find the question or model with `search` and put its bare numeric id into `source-card:`.")
+
+ (:unknown-measure :unknown-measure-id)
+ (tru "Call `browse_data` with action \"get_fields\" for the table that owns the measure and use the numeric id from its measures list.")
+
+ (:unknown-segment :unknown-segment-id)
+ (tru "Call `browse_data` with action \"get_fields\" for the table that owns the segment and use the numeric id from its segments list.")
+
+ :unknown-database
+ (tru "Use a numeric table id in `source-table:` (from `browse_data` action \"list_tables\"), which needs no database name at all.")
+
+ :missing-source-in-first-stage
+ (tru "`source-table:` takes a numeric table id; `source-card:` takes a saved-card numeric id.")
+
+ nil))
diff --git a/src/metabase/mcp/v2/redaction.clj b/src/metabase/mcp/v2/redaction.clj
new file mode 100644
index 00000000000..fb5b1821743
--- /dev/null
+++ b/src/metabase/mcp/v2/redaction.clj
@@ -0,0 +1,148 @@
+(ns metabase.mcp.v2.redaction
+ "The current-user half of the v2 MCP read shape: everything a tool must do to a row before
+ [[metabase.mcp.v2.projections]] reshapes it. Projections are pure, so the permission-dependent
+ work lives here — the app-DB hydration a redaction needs, and the redaction itself. Dashboards,
+ notification-backed rows (alerts, migrated subscriptions), and pulse-backed rows (dashboard
+ subscriptions) are all covered, on reads and on the rows writes read back.
+
+ Notification hydration is not exposed on its own: a hydrated row carries every recipient, so
+ handing one straight to a projection leaks them. [[hydrate-and-redact-notification]] is the way
+ in.
+
+ These read `metabase.api.common/*current-user*` (the dashboard side through the model read
+ checks) and so must be called as the requesting user; the projections they feed are pure."
+ (:require
+ [metabase.api.common :as api]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.models.interface :as mi]
+ [metabase.notification.models :as models.notification]
+ [metabase.permissions.core :as perms]
+ [metabase.pulse.core :as pulse]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------- dashboard ----------------------------------------------------
+
+(def ^:private card-describing-viz-keys
+ "`:visualization_settings` keys that describe the card rather than the grid slot: its author-written
+ title, the warehouse columns it displays and their labels, and click targets naming other entities.
+ Layout keys (sizing, container styling) describe the dashboard itself and survive redaction."
+ [:card.title :card.description :column_settings :series_settings :click_behavior])
+
+(defn- redact-dashcard
+ [dashcard]
+ (cond-> dashcard
+ ;; The projection reads an absent `:card` the same way it reads an unhydrated one — as an id
+ ;; with no name — so removing it is the whole redaction *for the projection*. The `layout`
+ ;; include reads this same dashcard directly, though, and `:visualization_settings` /
+ ;; `:parameter_mappings` are stored snapshots that describe the card: the title, the warehouse
+ ;; column names it renders, and the field ids its filters are wired to. Leaving them behind
+ ;; hands a caller who was just denied the card exactly what the denial withheld, so they go
+ ;; with it.
+ (not (some-> (:card dashcard) mi/can-read?))
+ ;; `:parameter_mappings` is emptied rather than removed: it is a required key on a DashboardCard,
+ ;; and `dashboard->resolved-params` — which the parameters summary runs over the same row — fails
+ ;; its schema when the key is absent.
+ (-> (dissoc :card)
+ (assoc :parameter_mappings []))
+
+ ;; Guarded on there being something to strip rather than on the key's presence: a dashcard read
+ ;; from the app db is a Toucan instance, where `update` on an absent key still writes it back as
+ ;; nil and the projection then reports a key the dashcard never had.
+ (and (not (some-> (:card dashcard) mi/can-read?))
+ (seq (:visualization_settings dashcard)))
+ (assoc :visualization_settings
+ (not-empty (apply dissoc (:visualization_settings dashcard) card-describing-viz-keys)))
+
+ (seq (:series dashcard))
+ (update :series (partial mapv #(cond-> % (not (mi/can-read? %)) (select-keys [:id]))))))
+
+(defn redact-dashboard
+ "`dash`, with its dashcards' `:card` and `:series` populated — by hydration on a saved dashboard,
+ by hand on a compiled one — and the cards the current user cannot read reduced to their ids, the
+ same collapse the REST dashboard response does."
+ [dash]
+ (update dash :dashcards (partial mapv redact-dashcard)))
+
+;;; ------------------------------------------------ notification --------------------------------------------------
+
+(defn- lookup-recipient-tenant-ids
+ "Map of user id to tenant id for the `recipients` whose `:user` hydration came back nil, in one
+ query. The `:recipients-detail` hydration deliberately attaches `:user` nil for a deactivated
+ user, whose tenant must then be looked up — otherwise a deactivated recipient reads as
+ tenantless and slips past (or is wrongly dropped by) the tenant filter."
+ [recipients]
+ (mcp.db/user-id->tenant-id (into #{} (comp (remove :user) (keep :user_id)) recipients)))
+
+(defn- recipient-tenant-id
+ "The tenant of a user recipient: read off the hydrated `:user` when present, else off
+ `id->tenant-id`, the batched lookup for recipients that have no `:user`."
+ [id->tenant-id recipient]
+ (if-some [user (:user recipient)]
+ (:tenant_id user)
+ (id->tenant-id (:user_id recipient))))
+
+(defn- visible-recipients
+ "`recipients` less the ones the current user may not see: sandboxed or impersonated callers see
+ only themselves among user recipients, and a caller who belongs to a tenant sees only user
+ recipients of that tenant. Same rule as `pulse/maybe-filter-pulses-recipients`: a tenantless
+ caller sees recipients unfiltered, as before tenants existed.
+
+ `id->tenant-id` is a delay over [[lookup-recipient-tenant-ids]] shared across the notification's
+ handlers, so the lookup costs one query for the whole notification and none at all for a caller
+ the tenant filter does not apply to."
+ [id->tenant-id recipients]
+ (let [caller-tenant-id (:tenant_id @api/*current-user*)]
+ (vec (cond->> recipients
+ (perms/sandboxed-or-impersonated-user?)
+ (filter #(or (nil? (:user_id %)) (= (:user_id %) api/*current-user-id*)))
+
+ (and (not api/*is-superuser?*) (some? caller-tenant-id))
+ (filter #(or (nil? (:user_id %))
+ (= (recipient-tenant-id @id->tenant-id %) caller-tenant-id)))))))
+
+(defn- payload-readable?
+ "Whether the current user may read the notification's payload.
+ [[models.notification/current-user-can-read-payload?]] has no `:notification/dashboard` clause
+ (its `case` throws on one), and a migrated dashboard row has no payload to check against: no
+ payload table stands behind `:payload_id`, and the `:payload` batched hydration only has a
+ `:notification/card` branch, so `:payload` hydrates nil. With no dashboard reachable, the check
+ is superuser — the one caller who can read every dashboard — mirroring how
+ `:notification/system-event` is handled there."
+ [notification]
+ (if (= :notification/dashboard (:payload_type notification))
+ (mi/superuser?)
+ (models.notification/current-user-can-read-payload? notification)))
+
+(defn redact-notification
+ "`notification`, hydrated, with handler recipients redacted for the current user the way
+ `/api/pulse` redacts them. A caller who can read the notification only as its creator or
+ recipient — not its payload — loses the recipient lists entirely; otherwise individual
+ recipients are filtered by [[visible-recipients]]."
+ [notification]
+ (let [strip? (and (#{:notification/card :notification/dashboard} (:payload_type notification))
+ (not (payload-readable? notification)))]
+ (update notification :handlers
+ (fn [handlers]
+ (let [id->tenant-id (delay (lookup-recipient-tenant-ids (mapcat :recipients handlers)))]
+ (mapv (fn [handler]
+ (if strip?
+ (dissoc handler :recipients)
+ (update handler :recipients (partial visible-recipients id->tenant-id))))
+ handlers))))))
+
+(defn hydrate-and-redact-notification
+ "`notification`, hydrated and recipient-redacted for the current user — the shape
+ [[metabase.mcp.v2.projections/notification-row]] takes."
+ [notification]
+ (redact-notification (mcp.db/hydrate-notification notification)))
+
+;;; --------------------------------------------------- pulse ------------------------------------------------------
+
+(defn redact-pulse
+ "`pulse-row` with recipients and sensitive metadata redacted for the current user exactly as
+ `/api/pulse` redacts them."
+ [pulse-row]
+ (-> pulse-row
+ pulse/maybe-filter-pulse-recipients
+ pulse/maybe-strip-sensitive-metadata))
diff --git a/src/metabase/mcp/v2/registry.clj b/src/metabase/mcp/v2/registry.clj
new file mode 100644
index 00000000000..da4f2977e82
--- /dev/null
+++ b/src/metabase/mcp/v2/registry.clj
@@ -0,0 +1,344 @@
+(ns metabase.mcp.v2.registry
+ "The v2 MCP tool registry. Tools are in-code registry entries declared with [[deftool]].
+ The v2 surface builds its own manifest and dispatch:
+
+ - `tools/list` ([[list-tools]]) filters by token scopes, the `mcp-v2-disabled-tools` CSV,
+ and the client extensions the caller advertised (a tool needing MCP Apps UI is hidden from
+ a client that can't render an iframe, rather than failing at call time);
+ - `tools/call` ([[call-tool]]) re-checks all three, validates arguments against the tool's
+ Malli schema with teaching errors, dispatches to the handler under the already-bound
+ current user, and logs every outcome through the shared usage path.
+
+ The three filters are not three boundaries. Scopes come from the verified token and the
+ disabled-tools CSV from instance settings, but the extension set is reconstructed from the
+ unsigned capability payload the client echoes back in its session id — a client can claim any
+ extension it likes, and never has to `initialize` to do so. Treat `:required-extensions` as a
+ client-declared hint that keeps a tool out of a list where it could not render, and put nothing
+ behind it that the tool's `:scope` does not already protect."
+ (:require
+ [clojure.string :as str]
+ [malli.error :as me]
+ [metabase.ai-tracing.core :as ait]
+ [metabase.api.common :as api]
+ [metabase.api.macros.defendpoint.tools-manifest :as tools-manifest]
+ [metabase.mcp.scope :as mcp.scope]
+ [metabase.mcp.settings :as mcp.settings]
+ [metabase.mcp.ui-resource :as mcp.ui-resource]
+ [metabase.mcp.usage :as mcp.usage]
+ [metabase.mcp.v2.common :as common]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.util.malli.registry :as mr]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------ Registration --------------------------------------------------
+
+(defonce ^:private tools*
+ (atom {}))
+
+;; Regenerating the manifest is slow. This atom stores a cache.
+(defonce ^:private manifest-cache
+ (atom nil))
+
+(defn register-tool!
+ "Register a v2 tool definition.
+
+ Does basic validation of arguments and throws when invalid."
+ [{tool-name :name :keys [scope description args handler] :as tool}]
+ (when (str/blank? tool-name)
+ (throw (ex-info "v2 MCP tool registered without a :name" {:tool tool})))
+ (doseq [[k v] {:scope scope :description description}]
+ (when-not (and (string? v) (not (str/blank? v)))
+ (throw (ex-info (format "v2 MCP tool %s registered without a %s string" tool-name k)
+ {:tool-name tool-name k v}))))
+ (when-not args
+ (throw (ex-info (format "v2 MCP tool %s registered without an :args Malli schema" tool-name)
+ {:tool-name tool-name})))
+ (when-not (ifn? handler)
+ (throw (ex-info (format "v2 MCP tool %s registered without a :handler fn" tool-name)
+ {:tool-name tool-name})))
+ ;; Dispatch gates on :required-extensions, so a misspelled key (:require-extensions,
+ ;; :requires-extension) would silently disable the gate — reject unknown keys loudly instead.
+ (when-let [unknown (seq (remove #{:name :scope :description :args :handler :annotations
+ :output-schema :required-extensions :title :_meta}
+ (keys tool)))]
+ (throw (ex-info (format "v2 MCP tool %s registered with unknown option(s) %s" tool-name (vec unknown))
+ {:tool-name tool-name :unknown-keys (vec unknown)})))
+ ;; Only the extensions a client can actually advertise are gateable: an unknown keyword is never in
+ ;; `ui-resource/supported-extensions`'s output, so the tool would be hidden from and refused to every
+ ;; client forever, with no error to say why.
+ (when (contains? tool :required-extensions)
+ (let [exts (:required-extensions tool)]
+ (when-not (and (set? exts) (every? keyword? exts))
+ (throw (ex-info (format "v2 MCP tool %s :required-extensions must be a set of keywords" tool-name)
+ {:tool-name tool-name :required-extensions exts})))
+ (when-let [unknown (seq (remove mcp.ui-resource/known-extensions exts))]
+ (throw (ex-info (format "v2 MCP tool %s requires unknown client extension(s) %s — no client can satisfy them"
+ tool-name (vec unknown))
+ {:tool-name tool-name :unknown-extensions (vec unknown)})))))
+ ;; Fail at load time (not first list) on a schema strict clients can't consume.
+ (tools-manifest/assert-optional-fields-nullable! args tool-name)
+ ;; The registry is keyed by public name, so a second definition claiming an existing name would
+ ;; silently shadow the first, with load order deciding which one `tools/call` reaches. Compared by the
+ ;; handler var's fully-qualified symbol, not by identity: reloading a tool namespace (REPL,
+ ;; tools.namespace refresh) mints a fresh var for the same name, which an identity check would reject.
+ (let [handler-sym (fn [h] (when (var? h) (symbol h)))]
+ (when-let [existing (get @tools* tool-name)]
+ (when-not (= (handler-sym (:handler existing)) (handler-sym handler))
+ (throw (ex-info (format "v2 MCP tool %s is already registered by a different handler" tool-name)
+ {:tool-name tool-name})))))
+ (swap! tools* assoc tool-name tool)
+ ;; flush cache to allow for repl/test redefinition.
+ (reset! manifest-cache nil)
+ tool-name)
+
+(defmacro deftool
+ "Define and register a v2 MCP tool.
+
+ (deftool echo
+ \"Echo the message back.\"
+ {:name \"echo\"
+ :scope metabot.scope/agent-content-read
+ :annotations {:readOnlyHint true}
+ :args [:map …]}
+ [arguments context]
+ …)
+
+ `description` is both the handler's docstring and the tool description published by tools/list.
+
+ Defines `handler-sym` via `defn` with two arguments:
+ - `arguments` - will be schema validated
+ - `context` - a map of
+ - `:session-id`
+ - `:token-scopes`
+ - `:client-info`
+ - `:request-context`
+
+ `opts` is a map of:
+ - `:name` - the mcp public-facing name of the tool
+ - `:scope` - the required scope for the tool
+ - `:annotations` - _optional_ - overrides for the default annotations
+ - `:args` - malli schema for the arguments, published as `inputSchema`
+ - `:output-schema` - _optional_ - malli schema for the structured output, published as `outputSchema`
+ - `:required-extensions` - _optional_ - set of client extensions (e.g. `:mcp-app-ui`) the tool
+ needs to render. Clients that don't advertise one don't see the tool listed and get a
+ teaching error if they call it anyway — but the advertisement is unauthenticated, so this is
+ a hint that spares incapable clients an unrenderable tool, not an authorization boundary.
+ `:scope` is the boundary; a tool gated only by an extension is a tool with no gate.
+ - `:title` - _optional_ - human-readable display name, published alongside `:name` for clients
+ that show one; without it clients fall back to the raw tool name
+ - `:_meta` - _optional_ - map published verbatim on the tool entry, carrying client-specific
+ hints outside the MCP tool schema (e.g. `{:ui {:visibility [\"app\"]}}` to mark a tool as one
+ the app calls for itself rather than one the model should choose)
+
+ Handlers return MCP content (see [[metabase.mcp.v2.common/success-content]]) or throw a teaching error."
+ [handler-sym description opts argv & body]
+ (assert (and (vector? argv)
+ (= 2 (count argv))))
+ `(do
+ (defn ~handler-sym ~description ~argv ~@body)
+ ;; Register the var (not the fn value) so re-evaluating the handler in the REPL — or
+ ;; redefining it in a test — takes effect without re-registering.
+ (register-tool! (assoc ~opts :description ~description :handler (var ~handler-sym)))))
+
+(defn registered-scopes
+ "The scopes from registered tools.
+
+ All scopes must also be registered via `defscope`."
+ []
+ (into #{}
+ (map :scope)
+ (vals @tools*)))
+
+;;; ------------------------------------------------ Manifest ------------------------------------------------------
+
+(def ^:private default-annotations
+ "`readOnlyHint`, `destructiveHint`, and `openWorldHint` are always present — some MCP clients
+ (e.g. the ChatGPT Apps SDK) reject tools that omit them. `openWorldHint` is false because
+ Metabase tools stay within the user's own instance."
+ {:readOnlyHint false
+ :destructiveHint false
+ :openWorldHint false})
+
+(defn- tool->manifest-entry
+ [{:keys [args annotations output-schema] :as tool}]
+ (cond-> (assoc tool
+ :inputSchema (-> args
+ tools-manifest/malli->json-schema
+ tools-manifest/strict-tool-input-schema)
+ :annotations (merge default-annotations annotations))
+ ;; No strict transform on outputs — that rewrite exists to satisfy OpenAI's strict-tool rules
+ ;; for arguments the model produces, and outputs aren't constrained by them.
+ output-schema (assoc :outputSchema (tools-manifest/malli->json-schema output-schema))))
+
+(defn- generate-manifest
+ []
+ (->> (vals @tools*)
+ (sort-by :name)
+ (mapv tool->manifest-entry)))
+
+(defn- manifest
+ "Cached manifest entries for all registered tools."
+ []
+ (or @manifest-cache
+ (reset! manifest-cache (generate-manifest))))
+
+(defn- disabled-tool-names
+ []
+ (set (mcp.settings/mcp-v2-disabled-tools)))
+
+(defn list-tools
+ "Return the tool definitions for the v2 MCP `tools/list` response, filtered by `token-scopes`,
+ the `mcp-v2-disabled-tools` setting, and the client extensions
+ `options` advertises (`:supports-mcp-ui?` — MCP Apps tools are hidden from clients that
+ can't render an iframe rather than failing at call time).
+
+ The 1-arity assumes full extension support: it backs [[tools-hash]], whose transport hook
+ sees only token scopes, so the hash must not depend on per-session capabilities."
+ ([token-scopes]
+ (list-tools token-scopes {:supports-mcp-ui? true}))
+ ([token-scopes options]
+ (let [disabled (disabled-tool-names)
+ supported (mcp.ui-resource/supported-extensions options)]
+ (into []
+ (comp
+ ;; no disabled tools
+ (filter #(not (contains? disabled (:name %))))
+ ;; has all required extensions
+ (filter #(empty? (mcp.ui-resource/missing-required-extensions % supported)))
+ ;; required scope is available
+ (filter #(mcp.scope/matches? token-scopes (:scope %)))
+ (map #(select-keys % [:name :title :description :inputSchema :outputSchema :annotations :_meta])))
+ (manifest)))))
+
+(defn tools-hash
+ "Stable 8-character hex hash of the tool list visible to `token-scopes`; polled by the
+ GET/SSE keepalive to emit `notifications/tools/list_changed` when the visible set changes
+ (scope changes, `mcp-v2-disabled-tools` edits, feature flips). Hashes the JSON encoding of
+ the wire-visible schema, so the result never depends on Clojure's `hash` of non-data leaves."
+ [token-scopes]
+ (format "%08x"
+ (hash (->> (list-tools token-scopes)
+ (map (juxt :name :inputSchema :outputSchema))
+ (sort-by first)
+ json/encode))))
+
+;;; ------------------------------------------------ Dispatch ------------------------------------------------------
+
+(defn- validation-error-message
+ "Validate `arguments` against the tool's Malli schema; returns a teaching-style message
+ string on failure, nil when valid."
+ [schema arguments]
+ (when-let [explanation ((mr/explainer schema) arguments)]
+ (str "Invalid arguments: " (common/humanize-detail (me/humanize explanation)))))
+
+(defn- insufficient-scope-message
+ "The scope-denial error text. Names the scope the tool requires and the ones the token holds — both are
+ in hand here, and a message that names only the tool leaves the caller with nothing to act on, against
+ the server's own `initialize` instructions promising that a failed call always names its fix.
+
+ `required` is a scope string or a set of alternatives ([[metabase.mcp.scope/matches?]] accepts either);
+ `token-scopes` may carry the `::api.scope/unrestricted` keyword alongside its strings, which is not a
+ scope a caller can request, so only strings are listed back."
+ [tool-name required token-scopes]
+ (let [held (sort (filter string? token-scopes))
+ needs (if (set? required)
+ (str "one of " (str/join ", " (sort required)))
+ (str required))]
+ (str "Insufficient scope to call tool: " tool-name ". Requires " needs "; "
+ (if (seq held)
+ (str "your token holds " (str/join ", " held) ".")
+ "your token holds no scopes."))))
+
+(defn- dispatch-tool-call
+ [token-scopes session-id tool-name arguments options]
+ (let [tool (get @tools* tool-name)
+ missing (mcp.ui-resource/missing-required-extensions
+ tool (mcp.ui-resource/supported-extensions options))]
+ (cond
+ ;; Disabled tools are absent from tools/list, so calling one is indistinguishable from
+ ;; calling a tool that never existed.
+ (or (nil? tool)
+ (contains? (disabled-tool-names) tool-name))
+ {:error {:code common/error-code-method-not-found :message (str "Unknown tool: " tool-name)}}
+
+ (not (map? (or arguments {})))
+ {:error {:code common/error-code-invalid-params :message "Invalid arguments: expected a JSON object."}}
+
+ (not (mcp.scope/matches? token-scopes (:scope tool)))
+ {:error {:code common/error-code-invalid-request
+ :message (insufficient-scope-message tool-name (:scope tool) token-scopes)}}
+
+ ;; A UI tool the client can't render is a caller error, not a hidden tool: unlike the
+ ;; scope/disabled cases it stays listed for capable clients, so name what's missing.
+ (seq missing)
+ {:error {:code common/error-code-invalid-params :message (mcp.ui-resource/missing-extensions-error tool-name missing)}}
+
+ :else
+ ;; Strict MCP clients (ChatGPT) send every declared property with `null` for the ones they
+ ;; don't populate; stripping top-level nils at the boundary lets handlers treat missing and
+ ;; null identically. Nested values are left alone.
+ (let [arguments (u/remove-nils (or arguments {}))]
+ (if-let [message (validation-error-message (:args tool) arguments)]
+ {:error {:code common/error-code-invalid-params :message message}}
+ (try
+ {:result ((:handler tool)
+ arguments
+ {:session-id session-id
+ :token-scopes token-scopes
+ :client-info (:client-info options)
+ :request-context (:request-context options)})}
+ ;; Every failure is sanitized in one place: only deliberately caller-facing errors
+ ;; surface their message; internal ones are logged and returned generically.
+ (catch Exception e
+ {:result (common/->mcp-error-content e)})))))))
+
+(defn call-tool
+ "Dispatch a v2 MCP `tools/call`. Returns `{:error {:code ... :message ...}}` when the registry rejects the request before dispatch, or `{:result mcp-content}` after handler execution. Only an executed handler can produce an MCP result carrying `:isError`.
+
+ Every call is recorded to `mcp_tool_call_log` (EE-only, best-effort) with its timing, success/error status, and on error the JSON-RPC `error_code` + `error_message` (the latter gated/truncated by the writer)."
+ ([token-scopes session-id tool-name arguments]
+ (call-tool token-scopes session-id tool-name arguments {}))
+ ([token-scopes session-id tool-name arguments options]
+ (ait/with-tool-call {:ai/tool-name tool-name :ai/tool-args arguments}
+ (let [start (System/nanoTime)
+ record! (fn [status error-code error-message]
+ (mcp.usage/record-mcp-tool-call!
+ {:tool-name tool-name
+ :user-id api/*current-user-id*
+ :session-id session-id
+ :status status
+ :duration-ms (quot (- (System/nanoTime) start) 1000000)
+ :error-code error-code
+ :error-message error-message
+ :client-info (:client-info options)
+ :tenant-id (some-> api/*current-user* deref :tenant_id)
+ :user-agent (get-in options [:request-context :user-agent])
+ :ip-address (get-in options [:request-context :ip-address])}))]
+ (try
+ (let [{:keys [error result] :as outcome}
+ (dispatch-tool-call token-scopes session-id tool-name arguments options)
+ result-error-code
+ (::common/error-code result)]
+ (if error
+ (record! "error" (:code error) (:message error))
+ (if (:isError result)
+ (record! "error"
+ (or result-error-code common/error-code-internal)
+ (some-> result :content first :text))
+ (record! "success" nil nil)))
+ ;; `::common/error-code` is an internal classification marker — never expose it to the client.
+ (if (contains? outcome :result)
+ (let [result (dissoc result ::common/error-code)]
+ ;; Trace the result WITHOUT the private MCP Apps block: it can carry a live UI credential, and a
+ ;; trace outlives the credential's five-minute window. The client still gets the full result.
+ (ait/record! {:ai/tool-output (common/redact-mcp-apps-meta result)})
+ (assoc outcome :result result))
+ outcome))
+ (catch Throwable e
+ ;; A handler that throws something the dispatch try doesn't convert would otherwise skip instrumentation
+ ;; and under-report errors. Record the failure, then rethrow so the transport layer still surfaces it to
+ ;; the client.
+ (record! "error" common/error-code-internal (ex-message e))
+ (throw e)))))))
diff --git a/src/metabase/mcp/v2/resolve.clj b/src/metabase/mcp/v2/resolve.clj
new file mode 100644
index 00000000000..0e0f8a2234e
--- /dev/null
+++ b/src/metabase/mcp/v2/resolve.clj
@@ -0,0 +1,174 @@
+(ns metabase.mcp.v2.resolve
+ "Id resolution for v2 MCP tools: numeric-or-entity_id translation and the read-check pairing
+ that collapses \"doesn't exist\" and \"exists but not readable\" into one not-found error.
+ Landed with its first consumers: the entity-id machinery with `bookmark_content`, collection
+ resolution with `collection_write`."
+ (:require
+ [clojure.string :as str]
+ [metabase.api.common :as api]
+ [metabase.collections.models.collection :as collection]
+ [metabase.eid-translation.core :as eid-translation]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.models.interface :as mi]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private entity-id-re
+ "NanoID shape used by `entity_id` columns."
+ #"^[A-Za-z0-9_-]{21}$")
+
+(defn entity-id?
+ "Is `x` a 21-character entity_id string?"
+ [x]
+ (boolean (and (string? x) (re-matches entity-id-re x))))
+
+(def ^:private numeric-id-re
+ "Digits with no leading zero and no sign — the exact rendering of a numeric id."
+ #"^[1-9][0-9]*$")
+
+(defn normalize-id
+ "Coerce an id argument a client sent as a JSON string (`\"16211\"`) to the integer it names;
+ return `x` unchanged for every other value, including entity_ids and the `\"root\"`/`\"trash\"`
+ sentinels.
+
+ GHY-4498: some MCP clients serialize every value of an `anyOf [integer, string]` param as a
+ string, and the model has no way to force the JSON type, so a numeric id would otherwise be
+ unreachable from those clients. Digit runs too large for a `long` stay strings and fail
+ validation like any other non-id."
+ [x]
+ (if (and (string? x) (re-matches numeric-id-re x))
+ (or (parse-long x) x)
+ x))
+
+(defn resolve-id-or-404
+ "Resolve a numeric id or 21-char entity_id to the numeric id for `model`. Throws the
+ collapsed not-found error when an entity_id doesn't resolve, and a teaching error for any
+ other shape.
+
+ This is translation only — it must always be followed by the object's read check. Prefer
+ [[resolve-and-read]], which enforces that pairing."
+ [model id-or-eid]
+ (let [id-or-eid (normalize-id id-or-eid)]
+ (cond
+ (int? id-or-eid)
+ id-or-eid
+
+ (entity-id? id-or-eid)
+ (try
+ (eid-translation/->id-or-404 model id-or-eid)
+ (catch clojure.lang.ExceptionInfo e
+ (if (= 404 (:status-code (ex-data e)))
+ (common/throw-not-found model id-or-eid)
+ (throw e))))
+
+ :else
+ ;; Name a retry that works: the obvious reading of "pass a numeric id" is to send the same
+ ;; number again, which fails identically.
+ (common/throw-teaching-error
+ (format "Invalid id %s — pass the positive numeric id, or the 21-character entity_id from a search or list result."
+ (pr-str id-or-eid))))))
+
+(defn resolve-and-read-with
+ "Resolve `id-or-eid` for `model`, then return the object from `read-check-fn`, which must
+ enforce at least what the corresponding REST endpoint enforces. \"Doesn't exist\" and
+ \"exists but not readable\" collapse into the same not-found error, so the response never
+ leaks existence across the permission boundary.
+
+ Reach for [[resolve-and-read]] first; use this only when the read genuinely differs (a
+ module fetch fn that runs its own checks, a write check, an extra existence predicate)."
+ [model id-or-eid read-check-fn]
+ (let [id (resolve-id-or-404 model id-or-eid)]
+ (try
+ (let [result (read-check-fn id)]
+ (if (nil? result)
+ (common/throw-not-found model id-or-eid)
+ result))
+ (catch clojure.lang.ExceptionInfo e
+ (if (contains? #{403 404} (:status-code (ex-data e)))
+ (common/throw-not-found model id-or-eid)
+ (throw e))))))
+
+(defn resolve-and-read
+ "Resolve `id-or-eid` for `model` and return the row from behind its `api/read-check` — what
+ nearly every read needs, with the same not-found collapse as [[resolve-and-read-with]]."
+ [model id-or-eid]
+ (resolve-and-read-with model id-or-eid
+ (fn [id] (api/read-check (mcp.db/select-one-by-id model id)))))
+
+(defn resolve-collection-id
+ "Resolve a `collection_id`/`parent_id` argument. `nil` and `\"root\"` mean the root
+ collection and resolve to nil without a DB translation; `\"trash\"` resolves to
+ `:trash-collection-id` when the caller allows it (the tool passes the id from the
+ collections module) and is a teaching error otherwise.
+
+ Anything else must name a collection the caller can read: \"doesn't exist\" and \"exists but not
+ readable\" collapse into the same not-found error, so the argument never reports the existence of
+ a collection the caller cannot see. That read also keeps an id for no collection at all from
+ travelling into the write, where it fails a `mu/defn` schema or a permission check and reaches
+ the caller as the sanitized \"Internal error\". Write permission stays the caller's job."
+ ([id-or-sentinel] (resolve-collection-id id-or-sentinel nil))
+ ([id-or-sentinel {:keys [trash-collection-id]}]
+ (cond
+ (or (nil? id-or-sentinel) (= "root" id-or-sentinel))
+ nil
+
+ (= "trash" id-or-sentinel)
+ (or trash-collection-id
+ (common/throw-teaching-error "\"trash\" is not a valid collection here — pass a collection id, entity_id, or \"root\"."))
+
+ :else
+ (:id (resolve-and-read :model/Collection id-or-sentinel)))))
+
+(defn resolve-collection-id-or-personal
+ "Like [[resolve-collection-id]], but an absent argument means the caller's personal collection
+ instead of the root collection. Explicit `\"root\"` still resolves to the root collection, so
+ callers keep a way to ask for it. Arguments arrive with top-level nils stripped at the
+ registry boundary, so a nil here is always an omitted argument rather than an explicit null.
+
+ For create paths only. On update an absent collection argument must leave content where it is,
+ so update paths guard [[resolve-collection-id]] with `contains?` instead.
+
+ API-key users have no personal collection; that nil is a teaching error here rather than a
+ silent write into the root collection."
+ [id-or-sentinel]
+ (if (some? id-or-sentinel)
+ (resolve-collection-id id-or-sentinel)
+ (or (:id (collection/user->personal-collection api/*current-user-id*))
+ (common/throw-teaching-error
+ (str "The current user has no personal collection. Pass an explicit collection_id "
+ "(or \"root\" for the root collection) instead.")))))
+
+;;; --------------------------------------------- Collection paths -------------------------------------------------
+
+(defn- location->ids
+ [location]
+ (when location
+ (mapv parse-long (re-seq #"\d+" location))))
+
+(defn- readable-id->name
+ "Map of collection id -> name for the given ids, omitting collections the current user cannot
+ read. `:namespace` and `:type` are selected because [[mi/can-read?]] consults them."
+ [ids]
+ (when (seq ids)
+ (into {}
+ (comp (filter mi/can-read?)
+ (map (juxt :id :name)))
+ (mcp.db/collections-for-read-check ids))))
+
+(defn collection-path
+ "The display path of the collection with `collection-id` — ancestor names joined with `/`, ending
+ in the collection's own name — or nil for a root item (`collection-id` nil) or a collection the
+ caller cannot read.
+
+ Ancestors the caller cannot read are omitted rather than failing the path, matching the
+ breadcrumb semantics of [[metabase.collections.models.collection/effective-ancestors]]: for
+ A > B > C where B is unreadable, the path reads \"A/C\".
+
+ Two reads per call, so it suits a single item or a small batch; `search` walks whole result
+ pages and batches the same lookups itself rather than calling this per row."
+ [collection-id]
+ (when collection-id
+ (when-let [[cname location] (get (mcp.db/collection-id->name+location #{collection-id}) collection-id)]
+ (let [ancestors (readable-id->name (set (location->ids location)))]
+ (str/join "/" (concat (keep ancestors (location->ids location)) [cname]))))))
diff --git a/src/metabase/mcp/v2/resources.clj b/src/metabase/mcp/v2/resources.clj
new file mode 100644
index 00000000000..3a45ad95935
--- /dev/null
+++ b/src/metabase/mcp/v2/resources.clj
@@ -0,0 +1,130 @@
+(ns metabase.mcp.v2.resources
+ "The v2 MCP resource registry.
+
+ Contains the `ui://` iframe shells behind the MCP Apps tools (`visualize_query`, `render_drill_through`)
+ and the fields-catalog data resource. Documentation/skill resources land with the skills work.
+
+ Every resource carries a required `:scope` and is matched with [[metabase.mcp.scope/matches?]], the same
+ all-or-nothing gate v2 tools use. There are deliberately no public resources, so there is no looser gate to
+ accidentally ship one through.
+
+ Rendering and the `_meta.ui` sandbox block come from [[metabase.mcp.ui-resource]]."
+ (:require
+ [metabase.mcp.scope :as mcp.scope]
+ [metabase.mcp.ui-resource :as mcp.ui-resource]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.util.json :as json]
+ [metabase.util.malli :as mu]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private ui-mime-type "text/html;profile=mcp-app")
+
+;; Keyed by URI, which is unique per resource. Overwrites on re-registration so REPL reload is idempotent.
+(defonce ^:private resources*
+ (atom (sorted-map)))
+
+(mu/defn register-resource!
+ "Register a v2 MCP data resource, returning its URI. Overwrites any existing entry with the
+ same `:uri`. `:render-fn` produces the resource text at read time, so the content is always
+ current rather than a snapshot from registration."
+ [resource :- [:map
+ [:uri :string]
+ [:name :string]
+ [:description :string]
+ [:mimeType :string]
+ [:scope :string]
+ [:render-fn fn?]]]
+ (swap! resources* assoc (:uri resource) resource)
+ (:uri resource))
+
+(mu/defn register-ui-resource!
+ "Register a v2 MCP Apps UI resource, returning its URI. Overwrites any existing entry with the
+ same `:uri`."
+ [resource :- [:map
+ [:uri :string]
+ [:name :string]
+ [:description :string]
+ [:scope :string]
+ [:render-fn fn?]
+ [:prefersBorder {:optional true} :boolean]]]
+ (swap! resources* assoc (:uri resource) (assoc resource :mimeType ui-mime-type :ui? true))
+ (:uri resource))
+
+(defn resource-scope
+ "The scope guarding `uri`, or nil when no such resource is registered. UI tools read this so a
+ tool and the resource it renders can never drift onto different scopes."
+ [uri]
+ (get-in @resources* [uri :scope]))
+
+(defn resource-scopes
+ "The distinct scope strings across all registered v2 resources."
+ []
+ (into (sorted-set) (keep :scope) (vals @resources*)))
+
+(defn list-resources
+ "The MCP `resources/list` payload, filtered by `token-scopes`."
+ [token-scopes]
+ {:resources (into []
+ (comp (filter #(mcp.scope/matches? token-scopes (:scope %)))
+ (map (fn [resource]
+ (cond-> (select-keys resource [:uri :name :description :mimeType])
+ (:ui? resource) (assoc :_meta (mcp.ui-resource/ui-meta resource))))))
+ (vals @resources*))})
+
+(defn read-resource
+ "Read a registered resource by URI, gated by `token-scopes`. Returns one of
+ `{:status :ok :contents [...]}`, `{:status :scope-denied}`, or `{:status :not-found}`. The
+ single registry lookup keeps the gate atomic with the render, so callers cannot bypass the
+ scope check.
+
+ `opts` is threaded to the `:render-fn` — see [[metabase.mcp.ui-resource/embed-render-fn]]."
+ [uri token-scopes opts]
+ (if-let [{:keys [render-fn scope] :as resource} (get @resources* uri)]
+ (if (mcp.scope/matches? token-scopes scope)
+ {:status :ok
+ :contents [(cond-> (-> (select-keys resource [:uri :mimeType])
+ (assoc :text (render-fn opts)))
+ (:ui? resource) (assoc :_meta (mcp.ui-resource/ui-meta resource)))]}
+ {:status :scope-denied})
+ {:status :not-found}))
+
+;;; ------------------------------------------------ Registrations -------------------------------------------------
+
+;; Two URIs rather than one shared shell: hosts dedupe mounted iframes by `_meta.ui.resourceUri`,
+;; so a drill-through that reused the visualize URI would silently not render. See
+;; [[metabase.mcp.ui-resource/embed-render-fn]] for the matching body-hash concern.
+
+(def visualize-query-uri
+ "URI of the iframe shell `visualize_query` renders into."
+ (register-ui-resource!
+ {:uri "ui://metabase/visualize-query.html"
+ :name "Visualize Query"
+ :description "Lightweight MCP Apps visualization for a query"
+ :scope metabot.scope/agent-query-run
+ :prefersBorder true
+ :render-fn (mcp.ui-resource/embed-render-fn "visualize-query")}))
+
+(def render-drill-through-uri
+ "URI of the iframe shell `render_drill_through` renders into."
+ (register-ui-resource!
+ {:uri "ui://metabase/render-drill-through.html"
+ :name "Render Drill Through"
+ :description "Lightweight MCP Apps visualization for a drill-through follow-up"
+ :scope metabot.scope/agent-query-run
+ :prefersBorder true
+ :render-fn (mcp.ui-resource/embed-render-fn "render-drill-through")}))
+
+(def fields-catalog-uri
+ "URI of the fields catalog: content type -> the dot-paths its `fields` argument accepts.
+ Rendered at read time because tool namespaces register their projections at load time.
+ The scheme is `catalog://`, NOT `metabase://` — that was v1's resource scheme, and the leak
+ test bans it from anything an agent can read so nothing steers one at v1 affordances."
+ (register-resource!
+ {:uri "catalog://metabase/fields"
+ :name "Fields Catalog"
+ :description "The dot-paths each content type supports in `fields` arguments (e.g. get_content), keyed by type."
+ :mimeType "application/json"
+ :scope metabot.scope/agent-resource-read
+ :render-fn (fn [_opts] (json/encode (projections/all-catalogs)))}))
diff --git a/src/metabase/mcp/v2/skills.clj b/src/metabase/mcp/v2/skills.clj
new file mode 100644
index 00000000000..97031518c1c
--- /dev/null
+++ b/src/metabase/mcp/v2/skills.clj
@@ -0,0 +1,123 @@
+(ns metabase.mcp.v2.skills
+ "The skill packs behind the v2 `learn` tool, plus the doc snippets teaching errors embed.
+
+ A pack is a directory on the classpath under `mcp/v2/skills/<pack>/`: a `SKILL.md` (the whole
+ document a `learn(topic)` call returns — one indivisible unit, no windowing) and optional
+ `references/<name>.md` files it points at. Every file is resolved at namespace load, so a
+ missing file fails at startup rather than on the first fetch; the slurp itself is delayed.
+
+ Packs carry the knowledge tool descriptions cannot: shapes the input schemas don't fully
+ type (template tags, visualization settings), the MBQL query dialect, and conventions
+ (dashboard grids, parameter wiring). Tool descriptions point here with trigger-conditioned
+ sentences, and teaching errors embed the short contract snippets defined at the bottom of
+ this namespace — so a miss recovers within one round trip even when no pack was read."
+ (:require
+ [clojure.java.io :as io]
+ [clojure.string :as str]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private skills-root "mcp/v2/skills")
+
+(defn- classpath-file
+ "A delay over the contents of `path` under the skills root. Throws at namespace load when the
+ file is missing from the classpath."
+ [path]
+ (let [full (str skills-root "/" path)
+ url (io/resource full)]
+ (when-not url
+ (throw (ex-info (str "Missing MCP skill pack file on classpath: resources/" full)
+ {:path full})))
+ (delay (slurp url :encoding "UTF-8"))))
+
+(def packs
+ "The pack catalog, in the order `learn()` lists it. `:description` doubles as the catalog line
+ and must say when to read the pack, not just what it is."
+ [{:name "query-dialect"
+ :description "The query dialect for execute_query and question_write's `query`: numeric-id refs, clause grammar, joins, expressions, multi-stage queries. Read before any non-trivial query. Reference `operators`: every filter/aggregation/expression operator."
+ :references ["operators"]}
+ {:name "native-parameters"
+ :description "Template tags for native SQL (question_write's `native`): tag kinds, field filter vs raw variable, the template_tags shape, widget types, [[ ]] optional blocks. Read before first passing template_tags."
+ :references []}
+ {:name "dashboard-filters"
+ :description "Dashboard parameters: add_parameter types, wire_parameter target grammar, autowire, linked filters, value sources, inline parameters. Read before your first add_parameter or wire_parameter."
+ :references []}
+ {:name "dashboard-layout"
+ :description "The 24-column grid: per-display default sizes, explicit placement vs autoplace, the KPI-row pattern, tabs and the every-card-needs-a-tab rule."
+ :references []}
+ {:name "documents"
+ :description "document_write's Markdown grammar: the CommonMark subset, {% card %} embeds, {% entity %} links, ::: layout containers, how `edits` behave."
+ :references []}
+ {:name "transforms"
+ :description "transform_write: materializing a query into a real warehouse table — definition vs query_handle, the target table and what patching it renames, the shapes it refuses (python, incremental), tags and folders. Read before your first transform_write."
+ :references []}
+ {:name "visualization-settings"
+ :description "Choosing a card's display and visualization_settings: which chart fits which data, the output-column-name rule, minimum settings per chart family. Reference `settings`: the per-chart key catalog incl. column_settings, series_settings, click behavior."
+ :references ["settings"]}])
+
+(def ^:private content
+ "pack name -> {:skill <delay> :references {ref-name <delay>}} — resolved (and thus existence-
+ checked) at load."
+ (into {}
+ (map (fn [{pack-name :name :keys [references]}]
+ [pack-name
+ {:skill (classpath-file (str pack-name "/SKILL.md"))
+ :references (into {}
+ (map (fn [ref-name]
+ [ref-name (classpath-file (str pack-name "/references/" ref-name ".md"))]))
+ references)}]))
+ packs))
+
+(defn topics
+ "The pack names, in catalog order."
+ []
+ (mapv :name packs))
+
+(defn catalog-text
+ "The `learn()` response: one line per pack — name, description, reference names."
+ []
+ (str "Topics — fetch one with learn(topic); a reference with learn(topic, reference):\n\n"
+ (str/join "\n"
+ (for [{pack-name :name :keys [description references]} packs]
+ (str "- " pack-name " — " description
+ (when (seq references)
+ (str " [references: " (str/join ", " references) "]")))))))
+
+(defn skill-text
+ "`topic`'s whole SKILL.md, with a footer naming its references, or nil for an unknown topic."
+ [topic]
+ (when-let [{:keys [skill references]} (get content topic)]
+ (cond-> @skill
+ (seq references)
+ (str "\n\n---\nReferences for this topic — fetch with learn(\"" topic "\", \"<name>\"): "
+ (str/join ", " (keys references)) "."))))
+
+(defn reference-text
+ "The reference file `reference` of pack `topic`, or nil when either is unknown."
+ [topic reference]
+ (some-> (get-in content [topic :references reference]) deref))
+
+(defn reference-names
+ "The reference names of `topic`, or nil for an unknown topic."
+ [topic]
+ (when-let [{:keys [references]} (get content topic)]
+ (vec (keys references))))
+
+;;; --------------------------------------------- Teaching-error snippets ------------------------------------------
+;;; Short contract blocks embedded into teaching errors at the boundaries the packs document, so a
+;;; failed call carries the spec itself and recovery never needs a second round trip.
+
+(def template-tag-contract
+ "The question_write template_tags contract, embedded in tag-shape teaching errors."
+ (str "template_tags is a map keyed by {{tag}} name; each entry:\n"
+ " field filter: {\"type\": \"dimension\", \"field_id\": <numeric id or entity_id>, \"widget_type\": \"string/=\" | \"number/=\" | \"date/all-options\" | …, \"display_name\"?, \"required\"?, \"default\"?}\n"
+ " raw variable: {\"type\": \"text\" | \"number\" | \"date\" | \"boolean\", \"display_name\"?, \"required\"?, \"default\"?}\n"
+ " time grouping: {\"type\": \"temporal-unit\", \"field_id\": <numeric id or entity_id>}\n"
+ "Write a field filter BARE in the SQL (WHERE {{tag}}, never col = {{tag}}); a raw variable is a literal you wrap yourself (WHERE total > {{tag}}). "
+ "get_content's template_tags are accepted back verbatim; snippet/card reference entries are ignored (the SQL configures them). Full doc: learn(\"native-parameters\")."))
+
+(def wire-target-grammar
+ "The wire_parameter target grammar, embedded in wiring teaching errors."
+ (str "wire_parameter takes exactly one of: `target_field` (numeric field id — MBQL cards and native field-filter tags; the server derives the mapping), "
+ "`target_tag` (a tag name on a native card; the server derives dimension vs variable from the tag's type), "
+ "or raw `target` (advanced, e.g. [\"dimension\", [\"template-tag\", \"category\"]]; [\"text-tag\", \"name\"] binds a {{name}} placeholder in a text/heading/iframe card's own content). Full doc: learn(\"dashboard-filters\")."))
diff --git a/src/metabase/mcp/v2/tools/alert.clj b/src/metabase/mcp/v2/tools/alert.clj
new file mode 100644
index 00000000000..2e7abefb96c
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/alert.clj
@@ -0,0 +1,455 @@
+(ns metabase.mcp.v2.tools.alert
+ "The v2 MCP `alert_write` tool: condition-triggered notifications on a saved question, backed by
+ the notification API's `notification/card` payload. The tool's own work is translating the
+ agent-facing vocabulary into the notification shape — a ScheduleMap compiled to cron (agents
+ never author cron), a channel plus recipients compiled to one handler, a condition compiled to
+ `send_condition`/`send_once` — and then handing the assembled notification to the same
+ create/update fns the REST endpoints call, so permission enforcement is inherited.
+
+ Update is a patch, but the notification update spec is not: it deletes the subscription and
+ handler rows a body omits. So every update reads the stored notification first and writes it
+ back whole, with only the caller's fields replaced."
+ (:require
+ [clojure.string :as str]
+ [medley.core :as m]
+ [metabase.api.common :as api]
+ [metabase.channel.email.messages :as messages]
+ [metabase.channel.settings :as channel.settings]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.scope :as mcp.scope]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.recipients :as mcp.recipients]
+ [metabase.mcp.v2.redaction :as redaction]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.models.interface :as mi]
+ [metabase.notification.api :as notification.api]
+ [metabase.util :as u]
+ [metabase.util.cron :as u.cron]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+;;; -------------------------------------------------- schedule ----------------------------------------------------
+
+(def ^:private schedule-fields-used
+ "The schedule fields [[metabase.util.cron/schedule-map->cron-string]] reads, per schedule type.
+ Anything outside its type's set the compiler drops on the floor."
+ {"hourly" #{:schedule_minute}
+ "daily" #{:schedule_hour}
+ "weekly" #{:schedule_hour :schedule_day}
+ "monthly" #{:schedule_hour :schedule_frame :schedule_day}})
+
+(def ^:private schedule-field-advice
+ "What to do instead, per field a schedule type doesn't read."
+ {:schedule_minute "only an hourly schedule sends at a minute past the hour"
+ :schedule_hour "an hourly schedule sends every hour — use \"daily\", \"weekly\", or \"monthly\" to send at one hour"
+ :schedule_day "use \"weekly\", or \"monthly\" with schedule_frame \"first\" or \"last\", to send on a weekday"
+ :schedule_frame "only a monthly schedule sends on a frame of the month"})
+
+(defn- check-ignored-schedule-fields!
+ "Reject a schedule field the caller's `schedule_type` doesn't read. The cron compiler drops such
+ a field silently, so the alert would send on a schedule nobody asked for while the call reports
+ success — `{hourly, schedule_hour 9}` fires 24 times a day, not once at nine. Only a
+ non-nil value counts: the strict-client transform lists every property as required and spells
+ \"no value\" as null, so a filled-in null is an omission, not a request."
+ [{:keys [schedule_type] :as schedule}]
+ (let [used (get schedule-fields-used schedule_type #{})
+ ignored (->> (keys schedule-field-advice)
+ (filter #(some? (get schedule %)))
+ (remove used)
+ sort
+ first)]
+ (when ignored
+ (common/throw-teaching-error
+ (format "A %s schedule doesn't use %s, so it would be ignored — %s."
+ schedule_type (name ignored) (schedule-field-advice ignored))))))
+
+(defn- check-schedule!
+ "Reject a schedule the cron compiler would mis-encode: one missing a field its type needs, or one
+ carrying a field its type doesn't read. The util would otherwise fill an omitted hour with
+ midnight and drop the surplus fields, silently picking a send time the caller never asked for,
+ and fail the other shapes as an opaque error. Kept in step with `subscription_write`'s check of
+ the same vocabulary, so an agent that has learned one tool's schedule has learned the other's."
+ [{:keys [schedule_type schedule_hour schedule_day schedule_frame] :as schedule}]
+ (letfn [(require! [v field explanation]
+ (when (nil? v)
+ (common/throw-teaching-error
+ (format "A %s schedule needs %s — %s." schedule_type field explanation))))]
+ (case schedule_type
+ "hourly" nil
+ "daily" (require! schedule_hour "schedule_hour" "the hour of the day to send, 0-23")
+ "weekly" (do (require! schedule_hour "schedule_hour" "the hour of the day to send, 0-23")
+ (require! schedule_day "schedule_day" "the day of the week, e.g. \"mon\""))
+ "monthly" (do (require! schedule_hour "schedule_hour" "the hour of the day to send, 0-23")
+ (require! schedule_frame "schedule_frame" "\"first\", \"mid\", or \"last\"")
+ (when (and (= "mid" schedule_frame) schedule_day)
+ (common/throw-teaching-error
+ (str "A monthly schedule with schedule_frame \"mid\" sends on the 15th, so it cannot also "
+ "take a schedule_day — drop schedule_day, or use frame \"first\" or \"last\" to send "
+ "on a particular weekday."))))))
+ (check-ignored-schedule-fields! schedule))
+
+(defn- schedule->cron
+ "Compile a ScheduleMap to the cron string the notification API stores, once
+ [[check-schedule!]] has ruled out the shapes the util can't express."
+ [schedule]
+ (check-schedule! schedule)
+ (try
+ (u.cron/schedule-map->cron-string schedule)
+ (catch Exception _
+ (common/throw-teaching-error
+ (format "Metabase can't schedule %s — check schedule_type against the other schedule fields."
+ (pr-str schedule))))))
+
+(defn- cron-subscription
+ [schedule]
+ [{:type :notification-subscription/cron
+ :cron_schedule (schedule->cron schedule)
+ ;; The alert was authored through the schedule picker's vocabulary, so mark it as such: the
+ ;; product's alert modal then edits it in the picker rather than as a raw cron string.
+ :ui_display_type :cron/builder}])
+
+;;; -------------------------------------------------- condition ---------------------------------------------------
+
+(def ^:private goal-conditions #{"goal_above" "goal_below"})
+
+(defn- check-goal-line!
+ "A goal condition compares results to the question's goal line; without one the notification
+ backend can only fail at send time, silently. Reject it here instead, mirroring
+ [[metabase.util.ui-logic/find-goal-value]]'s reading of where a goal lives per display.
+
+ The FE alert modal gates on `graph.show_goal` instead, and toggling the goal line on persists
+ no `graph.goal_value` (the rendered 0 is a render-time default) — so a chart can draw a goal
+ line the send path can't read, and `goal-met?` throws on the nil. Until FE and BE agree, this
+ check follows the send path (goal_value) and words the show_goal-without-value case as the
+ missing number it is. It also refuses multi-series charts, which the modal doesn't offer:
+ `graph-column-index` compares against whichever series is listed first."
+ [card]
+ (let [viz (:visualization_settings card)]
+ (case (keyword (:display card))
+ (:area :bar :line)
+ (cond
+ (nil? (:graph.goal_value viz))
+ (common/throw-teaching-error
+ (if (:graph.show_goal viz)
+ (format (str "Question %d shows a goal line but has no goal value saved, so alerts can't compare "
+ "against it — edit the chart's goal line settings and enter a goal number, or use "
+ "the \"has_result\" condition.")
+ (:id card))
+ (format (str "Question %d has no goal line, so a \"goal_above\"/\"goal_below\" alert can never fire — "
+ "set a goal on the chart, or use the \"has_result\" condition.")
+ (:id card))))
+
+ (< 1 (count (:graph.metrics viz)))
+ (common/throw-teaching-error
+ (format (str "Question %d plots more than one series, so a goal alert has no single value to compare "
+ "against the goal — use the \"has_result\" condition, or edit the chart down to one series.")
+ (:id card))))
+
+ :progress
+ nil
+
+ (common/throw-teaching-error
+ (format (str "Question %d is displayed as a %s, which has no goal line — \"goal_above\"/\"goal_below\" "
+ "alerts need a line, area, bar, or progress chart. Use the \"has_result\" condition instead.")
+ (:id card) (u/qualified-name (:display card)))))))
+
+;;; --------------------------------------------------- handlers ---------------------------------------------------
+
+(defn- email-recipient
+ "One email-handler recipient: an integer is a Metabase user, a string is a bare email address."
+ [recipient]
+ (let [[kind value] (mcp.recipients/classify recipient)]
+ (case kind
+ :user {:type :notification-recipient/user :user_id value}
+ :email {:type :notification-recipient/raw-value :details {:value value}})))
+
+(defn- slack-recipient
+ "The single raw-value recipient a slack handler carries: the channel's display name plus its
+ Slack id, resolved from the cached channel list the product's channel picker also reads."
+ [slack-channel]
+ (when-not (channel.settings/slack-configured?)
+ (common/throw-teaching-error
+ "Slack is not configured — ask an admin to set up Slack in Metabase settings, or use channel \"email\"."))
+ (let [channel (or (channel.settings/find-cached-slack-channel-or-username slack-channel)
+ (common/throw-teaching-error
+ (format "No Slack channel or user named %s — pass a channel name like \"#data-team\"."
+ (pr-str slack-channel))))]
+ {:type :notification-recipient/raw-value
+ :details {:value (:display-name channel) :channel_id (:id channel)}}))
+
+(defn- build-handler
+ "The one handler an alert delivers through. `existing` is the alert's stored handler (nil at
+ create). When the channel type is unchanged the new handler is built *onto* the stored row, so
+ editing recipients patches that handler rather than deleting and recreating it; switching
+ channels drops the old row instead."
+ [{:keys [channel slack_channel recipients]} existing]
+ (let [existing-type (some-> (:channel_type existing) u/qualified-name)
+ channel-type (or channel
+ (some-> existing-type (str/replace #"^channel/" ""))
+ "email")
+ base (if (= (str "channel/" channel-type) existing-type) existing {})]
+ ;; Guard the *stored* channel rather than the requested one. Replacing a handler alert_write
+ ;; doesn't manage — an http webhook, say — drops that delivery silently, so an explicit
+ ;; `channel` must not be able to talk its way past this guard by naming a type we do manage.
+ (when (and existing-type (not (#{"channel/email" "channel/slack"} existing-type)))
+ (common/throw-teaching-error
+ (format (str "This alert delivers over %s, which alert_write doesn't manage — edit it in Metabase, "
+ "or leave channel, slack_channel, and recipients out to keep it as it is.")
+ existing-type)))
+ ;; An empty list reads as "clear the recipients", which the cond below would silently answer
+ ;; with the caller (at create) or the stored list (at update).
+ (when (and recipients (empty? recipients))
+ (common/throw-teaching-error
+ (str "`recipients` can't be empty — an alert with nobody to send to would never reach anyone. "
+ "Pass at least one user id or email address, or leave recipients out: a new alert then "
+ "goes to you, and an existing one keeps the recipients it has.")))
+ (case channel-type
+ "slack"
+ (do
+ (when (seq recipients)
+ (common/throw-teaching-error
+ "A Slack alert posts to a channel, so it takes slack_channel rather than recipients."))
+ (assoc base
+ :channel_type :channel/slack
+ :recipients (cond
+ slack_channel [(slack-recipient slack_channel)]
+ (seq (:recipients base)) (:recipients base)
+ :else (common/throw-teaching-error
+ "`slack_channel` is required when channel is \"slack\"."))))
+
+ "email"
+ (do
+ (when slack_channel
+ (common/throw-teaching-error
+ "`slack_channel` only applies to a Slack alert — pass channel \"slack\" to post there, or drop slack_channel to keep delivering by email."))
+ (assoc base
+ :channel_type :channel/email
+ :recipients (cond
+ (seq recipients) (mapv email-recipient recipients)
+ (seq (:recipients base)) (:recipients base)
+ :else [{:type :notification-recipient/user
+ :user_id api/*current-user-id*}]))))))
+
+;;; ---------------------------------------------------- create ----------------------------------------------------
+
+(defn- resolve-card
+ "Resolve `card_id` behind the card's read check. The notification model gates creation on the
+ same read, but resolving here lets the goal-line check see the card and collapses a missing
+ card into the shared not-found error."
+ [card-id]
+ (v2.resolve/resolve-and-read :model/Card card-id))
+
+(defn- alert-response
+ [notification]
+ (projections/project :alert :concise
+ (projections/notification-row
+ (redaction/hydrate-and-redact-notification notification))))
+
+(defn- delivery-targets
+ "Where the alert's handlers deliver: recipient email addresses, plus slack channel names."
+ [notification]
+ (into #{}
+ (comp (mapcat :recipients)
+ (keep #(or (-> % :user :email) (-> % :details :value))))
+ (:handlers notification)))
+
+(defn- notify-caller-of-delivery!
+ "Tell the caller where this alert now delivers, whenever that is anyone but themselves. The
+ notification API's own \"you were added\" mail deliberately skips the creator
+ ([[metabase.notification.api.notification/send-you-were-added-card-notification-email!]] removes
+ the current user), which is right in the UI — they picked the recipients themselves — but through
+ this tool the list may be the agent's choice, and the caller is the one person positioned to
+ notice an address they never picked. So both write paths end here."
+ [notification]
+ (when (channel.settings/email-configured?)
+ (let [caller-email (:email @api/*current-user*)]
+ (when (seq (disj (delivery-targets notification) caller-email))
+ (messages/send-you-were-added-card-notification-email!
+ (update notification :payload t2/hydrate :card)
+ [caller-email]
+ @api/*current-user*)))))
+
+(defn- create!
+ [{:keys [card_id condition schedule active] :as args}]
+ (let [condition (m/remove-vals nil? condition)
+ card (resolve-card card_id)
+ send-condition (or (:type condition) "has_result")]
+ (when (goal-conditions send-condition)
+ (check-goal-line! card))
+ (let [created (notification.api/create-notification!
+ {:payload_type :notification/card
+ :active (if (some? active) (boolean active) true)
+ :creator_id api/*current-user-id*
+ :payload {:card_id (:id card)
+ :send_condition (keyword send-condition)
+ :send_once (boolean (:send_once condition))}
+ :subscriptions (cron-subscription schedule)
+ :handlers [(build-handler args nil)]})]
+ (notify-caller-of-delivery! created)
+ (alert-response created))))
+
+;;; ---------------------------------------------------- update ----------------------------------------------------
+
+(defn- fetch-alert
+ "Fetch the stored alert as the whole hydrated notification an update writes back. Notifications
+ have no entity_id column, so a non-numeric id is a teaching error rather than a lookup.
+
+ GHY-4217: unreadable, unwritable, and nonexistent all collapse to the same not-found. A
+ recipient can read an alert without being able to edit it, so answering that case with a 403
+ would tell targets apart from strangers — an existence oracle. Checking write here rather than
+ letting the API's own 403 surface later is what lets the update path report every *other* 403 —
+ a disallowed email domain, a channel template the caller can't write — with its real message.
+ `can-write?` mirrors `can-update?` for the bodies this tool sends: it never reassigns
+ `creator_id` and never moves the alert to another card."
+ [id]
+ (when-not (int? id)
+ (common/throw-teaching-error "Alerts take a numeric id — they have no entity_id."))
+ (let [notification (mcp.db/notification-by-payload-type id :notification/card)]
+ (when-not (and notification (mi/can-read? notification) (mi/can-write? notification))
+ (common/throw-not-found :alert id))
+ (notification.api/get-notification id)))
+
+(defn- update!
+ [id {:keys [condition schedule active] :as args}]
+ (when (contains? args :card_id)
+ (common/throw-teaching-error
+ "`card_id` can't be changed on an existing alert — create a new alert on the other question instead."))
+ (let [condition (m/remove-vals nil? condition)
+ existing (fetch-alert id)
+ delivery? (boolean (some #(contains? args %) [:channel :slack_channel :recipients]))
+ payload (cond-> (:payload existing)
+ (:type condition) (assoc :send_condition (keyword (:type condition)))
+ (some? (:send_once condition)) (assoc :send_once (boolean (:send_once condition))))]
+ ;; Only re-check the goal line when the caller is setting the condition: an alert whose chart
+ ;; lost its goal since it was created must still be pausable.
+ (when (goal-conditions (:type condition))
+ (check-goal-line! (resolve-card (:card_id payload))))
+ (when (and delivery? (< 1 (count (:handlers existing))))
+ (common/throw-teaching-error
+ (str "This alert delivers over more than one channel, and alert_write writes a single one — "
+ "editing its delivery here would silently drop the others. Edit it in Metabase instead.")))
+ ;; `:subscriptions` is a `:multi-row?` nested spec, so writing one back deletes the rest.
+ (when (and schedule (< 1 (count (:subscriptions existing))))
+ (common/throw-teaching-error
+ (str "This alert runs on more than one schedule, and alert_write writes a single one — "
+ "changing its schedule here would silently drop the others. Edit it in Metabase instead.")))
+ ;; The permission rejection [[fetch-alert]] has to hide is already spent; any 403 from here on
+ ;; is about the edit itself, and says so.
+ ;;
+ ;; `existing` and `payload` are hydrated for reads (ids, timestamps, the nested Card and User) —
+ ;; the update schema is closed over a narrower write shape, so only that shape is sent back.
+ ;; `:subscriptions`/`:handlers` still carry their full existing rows when untouched, since the
+ ;; update spec deletes whatever a body omits.
+ (let [updated (notification.api/update-notification!
+ id
+ (cond-> {:payload_type :notification/card
+ :payload (select-keys payload [:card_id :send_condition :send_once])
+ :subscriptions (:subscriptions existing)
+ :handlers (:handlers existing)}
+ (some? active) (assoc :active (boolean active))
+ schedule (assoc :subscriptions (cron-subscription schedule))
+ delivery? (assoc :handlers [(build-handler args (first (:handlers existing)))])))]
+ (when delivery?
+ (notify-caller-of-delivery! updated))
+ (alert-response updated))))
+
+;;; ----------------------------------------------------- tool -----------------------------------------------------
+
+(defn- check-query-execute-scope!
+ "An alert is a scheduled run of its question with the results delivered, so establishing one — or
+ redirecting where one delivers — needs the same scope that seeing those results in-session
+ would. The send itself happens later, tokenlessly, under the creator's permissions; this check
+ at write time is the only place the token's scopes can bound that deferred execution. No-op for
+ unscoped callers (cookie sessions bind the unrestricted sentinel, which matches everything)."
+ [token-scopes action]
+ (when-not (mcp.scope/matches? token-scopes metabot.scope/agent-query-run)
+ (throw (ex-info (format (str "%s runs its question and delivers the results, which requires the %s scope — "
+ "this token can manage alerts but not execute queries.")
+ action metabot.scope/agent-query-run)
+ {:status-code 403 ::common/error-code common/error-code-invalid-request}))))
+
+(defn- execute-scope-trigger
+ "The reason [[check-query-execute-scope!]] should refuse `updates` with, or nil when the update
+ commits the alert to nothing it wasn't already committed to. Every field that newly puts the
+ question in front of the scheduler counts, not just the delivery target: resuming a paused alert
+ restarts the sends, a new schedule changes how often they happen, and dropping `send_once` turns
+ a single run into an unbounded series. Pausing (`active: false`)
+ is deliberately absent — a kill switch must never need more scope than the thing it kills. The
+ alert's stored state is not consulted, so `active: true` on an already-running alert is refused
+ too: telling that no-op from a real resume would take a read the token may not be entitled to."
+ [updates]
+ (cond
+ (some #(contains? updates %) [:channel :slack_channel :recipients])
+ "Changing where an alert delivers"
+
+ (true? (:active updates))
+ "Resuming a paused alert"
+
+ (contains? updates :schedule)
+ "Changing an alert's schedule"
+
+ ;; `send_once` archives the alert after its first send, so clearing it turns one scheduled run
+ ;; into an unbounded series — the same commitment a new schedule makes. Only an explicit
+ ;; `false` counts: nested nulls survive the boundary's stripping, so `send_once: null` is an
+ ;; omission.
+ (false? (:send_once (:condition updates)))
+ "Removing an alert's send-once limit"))
+
+(def ^:private alert-write-args-schema
+ [:map {:closed true}
+ [:method [:enum "create" "update"]]
+ [:id {:optional true} [:maybe [:or :int :string]]]
+ [:card_id {:optional true} [:maybe [:or :int :string]]]
+ [:condition {:optional true}
+ [:maybe [:map {:closed true}
+ [:type {:optional true} [:maybe [:enum "has_result" "goal_above" "goal_below"]]]
+ [:send_once {:optional true} [:maybe :boolean]]]]]
+ [:schedule {:optional true}
+ [:maybe [:map {:closed true}
+ [:schedule_type [:enum "hourly" "daily" "weekly" "monthly"]]
+ [:schedule_hour {:optional true} [:maybe [:int {:min 0 :max 23}]]]
+ [:schedule_minute {:optional true} [:maybe [:int {:min 0 :max 59}]]]
+ [:schedule_day {:optional true} [:maybe [:enum "mon" "tue" "wed" "thu" "fri" "sat" "sun"]]]
+ [:schedule_frame {:optional true} [:maybe [:enum "first" "mid" "last"]]]]]]
+ [:channel {:optional true} [:maybe [:enum "email" "slack"]]]
+ [:slack_channel {:optional true} [:maybe [:string {:min 1}]]]
+ [:recipients {:optional true} [:maybe [:sequential [:or :int [:string {:min 1}]]]]]
+ [:active {:optional true} [:maybe :boolean]]])
+
+(registry/deftool alert-write
+ "Create or update an alert: a notification sent on a schedule when a saved question's results meet a condition.
+ method: \"create\" requires card_id (the question) and schedule; method: \"update\" requires id and changes only the
+ fields you pass. schedule is {schedule_type: \"hourly\" | \"daily\" | \"weekly\" | \"monthly\", schedule_hour?
+ (0-23, required for daily, weekly, and monthly), schedule_minute? (0-59, hourly only), schedule_day? (\"mon\"…\"sun\", required
+ for weekly, and picks the weekday for a monthly \"first\" or \"last\" frame), schedule_frame? (\"first\" | \"mid\"
+ | \"last\", required for monthly — \"mid\" is the 15th and takes no schedule_day)} — never a cron string. condition is {type: \"has_result\" (default) |
+ \"goal_above\" | \"goal_below\", send_once?: boolean} — the goal conditions need a goal line on the question's chart,
+ and send_once archives the alert after it fires. Delivery is one channel: \"email\" (default) with recipients, a list
+ mixing user ids and email addresses that defaults to you, or \"slack\" with slack_channel, a channel name like
+ \"#data-team\" (recipients don't apply). Passing any of channel, slack_channel, or recipients on update replaces the
+ alert's delivery; omit them all to leave it alone. active: false pauses an alert and true resumes it — alerts have no
+ archived state, and this tool cannot delete one. An alert's question is fixed at creation. Creating an alert, changing
+ its delivery or its schedule, resuming a paused one, or clearing send_once additionally requires the agent:query:run
+ scope — the alert runs the question and delivers its results. Pausing one never does. Alerts are for saved questions; use subscription_write to schedule a whole dashboard."
+ {:name "alert_write"
+ :scope metabot.scope/agent-delivery-write
+ :annotations {:readOnlyHint false :destructiveHint false}
+ :args alert-write-args-schema}
+ [args {:keys [token-scopes]}]
+ (let [[op a b] (v2.write/dispatch-write {:create-required [:card_id :schedule]} args)]
+ (common/success-content
+ ;; Reading an alert back demands the read tool's base scope plus the notification extra —
+ ;; without them the response is the minimal ack, or a no-op update reads the recipients.
+ (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (case op
+ :create (do (check-query-execute-scope! token-scopes "Creating an alert")
+ (create! a))
+ :update (do (when-let [reason (execute-scope-trigger b)]
+ (check-query-execute-scope! token-scopes reason))
+ (update! a b)))
+ nil))))
diff --git a/src/metabase/mcp/v2/tools/bookmark.clj b/src/metabase/mcp/v2/tools/bookmark.clj
new file mode 100644
index 00000000000..54bcdf09654
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/bookmark.clj
@@ -0,0 +1,92 @@
+(ns metabase.mcp.v2.tools.bookmark
+ "The v2 MCP `bookmark_content` tool: per-user favorites. Bookmarks are their own REST resource
+ (`/api/bookmark/:model/:id`) keyed by a (model, id) tuple rather than a row id, so they can't
+ ride a `_write` tool — hence a tool of their own, with `bookmarked: true|false` in place of
+ `method`.
+
+ Unlike REST, both directions are idempotent: bookmarking something already bookmarked, and
+ un-bookmarking something that isn't, both succeed. An agent that can't observe its own prior
+ calls would otherwise have to guess, and the REST 400 teaches it nothing it can act on.
+
+ The three card flavors (question/model/metric) share the REST model `card`; the tool still
+ takes them apart so a type/flavor mismatch is caught here rather than silently bookmarking the
+ wrong kind of thing.
+
+ Both directions read-check the item, where REST only read-checks the create. Un-bookmarking
+ something the caller can no longer read is thus a not-found here — the tool resolves entity_ids
+ and echoes the item's name, and neither can happen across the permission boundary without
+ turning the response into an existence oracle.
+
+ The name echo is gated a second time, on the read scope: permission is not the only boundary a
+ token has, and a write scope that echoes a name is a read scope for names."
+ (:require
+ [metabase.api.common :as api]
+ [metabase.bookmarks.db :as bookmarks.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private type->spec
+ "Per-type dispatch: the Toucan model the id resolves against, the REST bookmark model string
+ (the three card flavors share `card`), and the card `:type` a card-backed entry must have."
+ {"question" {:model :model/Card :bookmark-model "card" :card-type :question}
+ "model" {:model :model/Card :bookmark-model "card" :card-type :model}
+ "metric" {:model :model/Card :bookmark-model "card" :card-type :metric}
+ "dashboard" {:model :model/Dashboard :bookmark-model "dashboard"}
+ "collection" {:model :model/Collection :bookmark-model "collection"}
+ "document" {:model :model/Document :bookmark-model "document"}})
+
+(def ^:private content-types
+ (vec (sort (keys type->spec))))
+
+(def ^:private card-type->tool-type
+ {:question "question" :model "model" :metric "metric"})
+
+(defn- fetch-item
+ "Resolve `id-or-eid` for `type` behind the same read check `POST /api/bookmark/:model/:id` runs,
+ and return the row. A card whose flavor doesn't match `type` is a teaching error naming the
+ right type."
+ [type id-or-eid]
+ (let [{:keys [model card-type]} (type->spec type)
+ row (v2.resolve/resolve-and-read model id-or-eid)]
+ (when card-type
+ (let [actual (card-type->tool-type (:type row))]
+ (when (not= actual type)
+ ;; `actual` is nil for a card type this tool doesn't surface (only question/model/metric
+ ;; are bookmarkable-by-flavor); name the id without a "null" type in that case.
+ (common/throw-teaching-error
+ (if actual
+ (format "Card %s is a %s — bookmark it with type: \"%s\"." (:id row) actual actual)
+ (format "Card %s can't be bookmarked as type: \"%s\"." (:id row) type))))))
+ row))
+
+(def ^:private bookmark-content-args-schema
+ [:map {:closed true}
+ [:type (into [:enum {:description "The content type, as returned by search/browse_collection."}]
+ content-types)]
+ [:id [:or
+ [:int {:min 1 :description "Numeric id."}]
+ [:string {:min 1 :description "A 21-character entity_id."}]]]
+ [:bookmarked [:boolean {:description "true bookmarks the item, false removes the bookmark."}]]])
+
+(registry/deftool bookmark-content
+ "Add or remove a bookmark on content for the calling user — the same starred/favorites list the Metabase sidebar shows. Pass type (question, model, metric, dashboard, collection, or document), id (numeric or 21-char entity_id), and bookmarked: true to bookmark or false to un-bookmark. Both directions are idempotent: bookmarking something already bookmarked, or un-bookmarking something that isn't, succeeds and reports the resulting state. Bookmarks are per-user and grant no access — the item must already be readable by the caller. The item's name comes back only when your token also holds agent:content:read; without it the response is a minimal acknowledgement. This response is the only place bookmark state is reported: no tool reads a bookmark back, search and get_content carry no bookmarked field, and there is no bookmark listing — so keep this result if you need it later rather than spending calls looking for a read path."
+ {:name "bookmark_content"
+ :scope metabot.scope/agent-content-write
+ :annotations {:readOnlyHint false :destructiveHint false :idempotentHint true}
+ :args bookmark-content-args-schema}
+ [{:keys [type id bookmarked]} {:keys [token-scopes]}]
+ (let [row (fetch-item type id)
+ bookmark-model (get-in type->spec [type :bookmark-model])
+ user-id api/*current-user-id*]
+ (if bookmarked
+ (bookmarks.db/insert-bookmark! bookmark-model (:id row) user-id)
+ (bookmarks.db/delete-bookmark! bookmark-model (:id row) user-id))
+ (common/success-content
+ (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ {:type type :id (:id row) :name (:name row) :bookmarked bookmarked}
+ [:bookmarked]))))
diff --git a/src/metabase/mcp/v2/tools/browse.clj b/src/metabase/mcp/v2/tools/browse.clj
new file mode 100644
index 00000000000..94f7edb2c44
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/browse.clj
@@ -0,0 +1,862 @@
+(ns metabase.mcp.v2.tools.browse
+ "The v2 MCP browse tools.
+
+ `browse_data`: one tool for the data hierarchy, dispatched on an explicit `action` enum.
+ The `list_*` actions page server-side over the full permission-filtered sets (the backing
+ endpoints have no paging); `get_fields` rides the batched, sandbox-aware table-metadata
+ fetch and applies a byte budget — whole tables in request order, the rest named under
+ `omitted`, never a silently truncated table.
+
+ `browse_collection`: structural navigation over every collection partition — items mode
+ over any id form (numeric | entity_id | \"root\" | \"trash\") and namespace, tree mode
+ composing the shallow tree fetch per expandable node under a depth, per-node child cap,
+ and total node budget."
+ (:require
+ [clojure.string :as str]
+ [medley.core :as m]
+ [metabase.api.common :as api]
+ [metabase.collections.children :as collections.children]
+ [metabase.collections.models.collection :as collection]
+ [metabase.documents.core :as documents]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.metabot.metadata-perms :as metabot.perms]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.models.interface :as mi]
+ [metabase.parameters.field-values :as params.field-values]
+ [metabase.permissions.core :as perms]
+ [metabase.request.core :as request]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.warehouse-schema.models.field-values :as field-values]
+ [metabase.warehouse-schema.table :as schema.table]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------ Projections ---------------------------------------------------
+
+(def ^:private database-concise-keys
+ [:id :name :engine :description])
+
+(def ^:private database-detailed-keys
+ (into database-concise-keys
+ [:timezone :dbms_version :is_sample :is_on_demand :uploads_enabled :auto_run_queries
+ :initial_sync_status :created_at :updated_at]))
+
+(projections/register-key-projection! :database database-concise-keys
+ :detailed-keys database-detailed-keys :compact? false)
+
+(def ^:private field-concise-keys
+ [:id :name :display_name :base_type :semantic_type :fk_target_field_id :description])
+
+(def ^:private field-detailed-keys
+ (into field-concise-keys
+ [:effective_type :coercion_strategy :database_type :fingerprint :has_field_values
+ :values :position]))
+
+(def ^:private table-metadata-sample
+ {:id 1
+ :name "x"
+ :display_name "x"
+ :schema "x"
+ :db_id 1
+ :description "x"
+ :fields [(-> (zipmap field-detailed-keys (repeat "x"))
+ (assoc :fingerprint {:global {:distinct-count 1}}
+ :values [["x" "x"]]))]
+ :measures [{:id 1 :name "x" :description "x"}]
+ :segments [{:id 1 :name "x" :description "x"}]
+ :metrics [{:id 1 :name "x" :description "x"}]
+ :related_tables [{:id 1 :name "x" :display_name "x" :schema "x" :fields ["x"]}]})
+
+;; Registered for the `fields` dot-path catalog; the row itself is built by
+;; [[table-metadata-row]] (the projection needs the batch-fetched hydrations, not a plain row).
+(projections/register-projection!
+ :table-metadata
+ {:concise identity
+ :detailed identity
+ :sample table-metadata-sample})
+
+;;; -------------------------------------------- Per-action validation ---------------------------------------------
+
+(def ^:private action->arg-spec
+ {"list_databases" {:allowed #{:limit :offset :response_format :fields}}
+ "list_schemas" {:required [:database_id]
+ :allowed #{:database_id :include_hidden :limit :offset}}
+ "list_tables" {:required [:database_id]
+ :allowed #{:database_id :schema :search :include_hidden :limit :offset
+ :response_format :fields}}
+ "list_models" {:required [:database_id]
+ :allowed #{:database_id :limit :offset :response_format :fields}}
+ "get_fields" {:required [:table_ids]
+ :allowed #{:database_id :table_ids :include_hidden :offset :response_format :fields}}})
+
+(defn- validate-args-for-action!
+ [{:keys [action] :as args}]
+ (let [{:keys [required allowed]} (action->arg-spec action)]
+ (doseq [k required]
+ (when-not (contains? args k)
+ (common/throw-teaching-error (format "`%s` is required for action %s." (name k) action))))
+ (when-let [bad (seq (sort (map name (remove (conj allowed :action) (keys args)))))]
+ (common/throw-teaching-error
+ (format "%s not apply to action %s — remove %s."
+ (if (next bad) (str "`" (str/join "`, `" bad) "` do") (str "`" (first bad) "` does"))
+ action
+ (if (next bad) "them" "it"))))))
+
+(defn- check-database!
+ "Read-check `database-id` and confirm it is browsable, collapsing \"doesn't exist\", \"not
+ readable\", and \"not browsable\" (a stub, or a router-destination database — a multi-tenant
+ boundary a raw id must not cross) into the shared not-found teaching error. Selecting through
+ the same filter [[list-databases]] pages means the tool never serves a database it would not
+ list, independent of what the schema/table helpers happen to filter."
+ [database-id]
+ (v2.resolve/resolve-and-read-with :model/Database database-id
+ (fn [id]
+ (api/read-check (mcp.db/browsable-database
+ id
+ (schema.table/browsable-databases-honeysql-filter))))))
+
+;;; ------------------------------------------------ List plumbing -------------------------------------------------
+
+(def ^:private default-limit 50)
+
+(defn- page-args
+ [args]
+ {:limit (or (:limit args) default-limit)
+ :offset (or (:offset args) 0)})
+
+(defn- paged-list-content
+ "Slice `rows` (the full filtered set) per `limit`/`offset` and build the envelope content.
+ `project-fn` runs on the page only; `opts` pass through to [[common/list-content]]."
+ [args rows opts project-fn]
+ (let [{:keys [limit offset]} (page-args args)
+ page (into [] (comp (drop offset) (take limit)) rows)]
+ (common/list-content (project-fn page) (count rows)
+ (assoc opts :offset offset :limit limit))))
+
+(defn- project-rows
+ [type args rows]
+ (if-let [fields (:fields args)]
+ (common/select-fields type
+ (mapv #(projections/project type :detailed %) rows)
+ fields
+ {:response-format (:response_format args)})
+ (let [fmt (common/response-format args)]
+ (mapv #(projections/project type fmt %) rows))))
+
+;;; ------------------------------------------------ list_* actions ------------------------------------------------
+
+(defn- list-databases
+ [args]
+ ;; Nothing projected reads the `details`/`settings` blobs, and `mi/can-read?` needs only `:id`.
+ (let [rows (mcp.db/browsable-databases database-detailed-keys
+ (schema.table/browsable-databases-honeysql-filter))
+ ;; `mi/can-read?` below is one permission check per database; load them in one query first.
+ _ (perms/prime-database-perms-cache {:db-ids (into #{} (map :id) rows)})
+ dbs (filterv mi/can-read? rows)]
+ (paged-list-content args dbs {:empty-hint "No databases are visible to you. Browsing data needs query-builder or table-metadata permission on at least one database."}
+ #(project-rows :database args %))))
+
+(defn- list-schemas
+ [{:keys [database_id include_hidden] :as args}]
+ (check-database! database_id)
+ (let [schemas (vec (schema.table/database-schemas database_id {:include-hidden? include_hidden}))]
+ (paged-list-content args schemas {} identity)))
+
+(defn- named-schema-tables
+ [database-id schema include-hidden?]
+ (try
+ (schema.table/schema-tables-list database-id schema {:include-hidden? include-hidden?})
+ (catch clojure.lang.ExceptionInfo e
+ ;; The schema-level permission check collapses with "no such schema": both answers must
+ ;; be indistinguishable, so listings never form an existence oracle.
+ (if (= 403 (:status-code (ex-data e)))
+ (common/throw-teaching-error
+ (format "Schema %s not found in database %s — it may not exist, or you may not have access to it."
+ (pr-str schema) database-id)
+ {:status-code 404})
+ (throw e)))))
+
+(defn- blank-schema-tables
+ "Tables whose schema is nil or the empty string — the blank-schema path for databases without
+ schemas. An unreadable/absent blank schema is an empty list, not an error, so omitting
+ `schema` on a schema-ful database degrades gracefully."
+ [database-id include-hidden?]
+ (into []
+ (mapcat (fn [schema]
+ (try
+ (schema.table/schema-tables-list database-id schema {:include-hidden? include-hidden?})
+ (catch clojure.lang.ExceptionInfo e
+ (when-not (= 403 (:status-code (ex-data e)))
+ (throw e))))))
+ [nil ""]))
+
+(defn- matches-search?
+ "Case-insensitive substring match on either name the row exposes. `display_name` is nullable and
+ is what an admin edits when renaming a table, so it is the name the caller was most likely
+ shown — matching only `name` loses renamed tables."
+ [needle table]
+ (boolean (some #(and % (str/includes? (u/lower-case-en %) needle))
+ [(:name table) (:display_name table)])))
+
+(defn- list-tables
+ [{:keys [database_id schema search include_hidden] :as args}]
+ (check-database! database_id)
+ (let [tables (if (str/blank? schema)
+ (blank-schema-tables database_id include_hidden)
+ (named-schema-tables database_id schema include_hidden))
+ filtered (if search
+ (let [needle (u/lower-case-en search)]
+ (filterv (partial matches-search? needle) tables))
+ (vec tables))]
+ ;; Once search was supplied there is nothing left to narrow by, so drop the `:search` steering.
+ (paged-list-content args filtered (if search {} {:param :search}) #(project-rows :table args %))))
+
+(def ^:private question-select-columns
+ "Columns `list_models` selects for the `:question` projection."
+ ;; Naming the columns keeps `t2/select` from running the `dataset_query` and `result_metadata`
+ ;; transforms on every model — the expensive part of listing a database with thousands of cards.
+ ;; `:card_schema` is never projected, but Card's after-select hook throws without it once the
+ ;; row carries `:id` plus any of `:dataset_query`/`:result_metadata`/`:database_id`/`:type`.
+ ;; `question-enrichment-keys` are projection keys `get_content` computes, not Card columns;
+ ;; selecting them would name a nonexistent column, so they are dropped from the DB select here.
+ (into [:model/Card :card_schema]
+ (remove projections/question-enrichment-keys projections/question-detailed-keys)))
+
+(defn- list-models
+ [{:keys [database_id] :as args}]
+ (check-database! database_id)
+ (let [models (->> (mcp.db/unarchived-models-in-database question-select-columns database_id)
+ (filterv mi/can-read?))]
+ (paged-list-content args models {} #(project-rows :question args %))))
+
+;;; ------------------------------------------------- get_fields ---------------------------------------------------
+
+(def ^:private max-table-ids 20)
+
+(def ^:private get-fields-byte-budget
+ "Response budget for one get_fields call, in actual serialized bytes. Whole tables are
+ included in request order until it runs out; the exact value is not spec-bound."
+ (* 100 1024))
+
+(def ^:private max-related-tables
+ "Ceiling on related tables surfaced per requested table; see v1's identically-motivated cap
+ (heap blowups on highly-connected schemas, metabase#76493)."
+ 50)
+
+(def ^:private max-related-tables-with-fields
+ "Of the related tables surfaced, only this many carry their column names."
+ 10)
+
+(defn- fetch-table-metadata-rows
+ "Fetch query-metadata rows for `table-ids` in request order. Always goes through the
+ defenterprise fetchers so EE column-level sandboxing applies; `include-hidden?` forces the
+ per-table path (the batch helper cannot include hidden fields). Ids that don't resolve to a
+ readable table land in `:missing` — indistinguishable between absent and unreadable.
+ Returns `{:rows [...] :missing [ids]}`."
+ [table-ids include-hidden?]
+ (let [rows (if include-hidden?
+ (keep (fn [id]
+ (try
+ (schema.table/fetch-table-query-metadata id {:include-hidden-fields? true})
+ (catch clojure.lang.ExceptionInfo e
+ (when-not (contains? #{403 404} (:status-code (ex-data e)))
+ (throw e)))))
+ table-ids)
+ (schema.table/batch-fetch-table-query-metadatas table-ids nil))
+ by-id (m/index-by :id rows)]
+ {:rows (into [] (keep by-id) table-ids)
+ :missing (into [] (remove by-id) table-ids)}))
+
+(defn- related-tables-by-requested-table
+ "Map of requested table id → vector of its FK-target tables (readable ones only, capped at
+ [[max-related-tables]]), the first [[max-related-tables-with-fields]] of which carry their
+ visible column names — sandbox-filtered, so a sandboxed caller never sees hidden columns of
+ a neighboring table.
+
+ `browsable-db-ids` re-applies the browsable-database filter the requested tables already
+ passed. `mi/can-read?` on a Table evaluates per-table perms against its `:db_id` and has no
+ notion of a router destination: a destination reads as affirmatively readable, because the
+ Database read check redirects to its router. An FK from a still-router table into a table
+ whose `:db_id` was reassigned would otherwise carry the destination's column names into the
+ response by the neighbour path, which the directly-requested path already refuses."
+ [browsable-db-ids metadata-rows]
+ (let [targets-by-table (into {}
+ (map (fn [{:keys [id fields]}]
+ [id (into []
+ (comp (keep #(get-in % [:target :table_id]))
+ (remove #{id})
+ (distinct))
+ fields)]))
+ metadata-rows)
+ related-ids (into #{} (mapcat val) targets-by-table)
+ related (when (seq related-ids)
+ (->> (mcp.db/active-tables-by-ids related-ids)
+ (filter (comp browsable-db-ids :db_id))
+ (filter mi/can-read?)
+ (m/index-by :id)))
+ expand-ids (into #{}
+ (mapcat (fn [[_ target-ids]]
+ (->> target-ids
+ (filter related)
+ (take max-related-tables-with-fields))))
+ targets-by-table)
+ columns (when (seq expand-ids)
+ (-> (group-by :table_id (mcp.db/active-visible-fields-for-tables expand-ids))
+ schema.table/batch-filter-sandboxed-fields))]
+ (update-vals targets-by-table
+ (fn [target-ids]
+ (into []
+ (comp (keep related)
+ (take max-related-tables)
+ (map-indexed
+ (fn [i {:keys [id name display_name schema]}]
+ (cond-> {:id id :name name :display_name display_name :schema schema}
+ (and (< i max-related-tables-with-fields) (get columns id))
+ (assoc :fields (mapv :name (get columns id)))))))
+ target-ids)))))
+
+(defn- list-type-field?
+ [field]
+ (contains? #{:list :auto-list} (keyword (:has_field_values field))))
+
+(defn- attach-inline-values
+ "Inline cached sample `:values` (as `[value human-readable?]` pairs, the REST field/values
+ shape) onto the list-type fields of every table in `tables` the current user can query, for
+ the detailed projection. Tables they can only read come back unchanged — full field metadata,
+ no `:values`. One current-user-aware batched FieldValues fetch across the queryable tables —
+ sandboxed/impersonated fields resolve through their per-user cache, never the shared one."
+ [tables]
+ ;; Read permission is not enough: values are rows of the table, not metadata about it. REST draws
+ ;; the same line — `/api/field/:id/summary` gates on `read-check`, `/api/field/:id/values` on
+ ;; `query-check` — so a metadata-only caller who is refused there must be refused here too.
+ (perms/prime-table-perms-cache {:db-ids (into #{} (keep :db_id) tables)
+ :table-ids (into #{} (keep :id) tables)})
+ (let [queryable (into #{} (comp (filter mi/can-query?) (keep :id)) tables)
+ ;; Field ids are unique across tables, so restricting the fetch to queryable tables is the
+ ;; whole gate — nothing withheld here can be looked up again below.
+ field-ids (into []
+ (comp (filter (comp queryable :id))
+ (mapcat :fields)
+ (filter list-type-field?)
+ (keep :id))
+ tables)
+ id->values (when (seq field-ids)
+ (params.field-values/field-id->field-values-for-current-user field-ids))]
+ (if (empty? id->values)
+ tables
+ (mapv (fn [table]
+ (update table :fields
+ (partial mapv
+ (fn [field]
+ (if-let [fv (and (list-type-field? field)
+ (get id->values (:id field)))]
+ (assoc field :values (field-values/field-values->pairs fv))
+ field)))))
+ tables))))
+
+(defn- withhold-restricted-fingerprints
+ "Strips `:fingerprint` from the fields of every table in `tables` whose current user's row access
+ is narrowed by sandboxing, connection impersonation, or database routing. Fingerprints are
+ computed at sync time across every row of the table, so `:min`/`:max`/`:earliest`/`:latest` are
+ literal values from rows the user cannot see and `:global :distinct-count` is whole-table
+ cardinality — there is no safe subset, so the whole map goes. One batched, fail-closed
+ restriction lookup for the request."
+ [tables]
+ (let [restricted (metabot.perms/row-restricted-table-ids (into #{} (keep :id) tables))]
+ (if (empty? restricted)
+ tables
+ (mapv (fn [table]
+ (cond-> table
+ (contains? restricted (:id table))
+ (update :fields (partial mapv #(dissoc % :fingerprint)))))
+ tables))))
+
+(defn- compact
+ [m]
+ (into {} (remove (comp nil? val)) m))
+
+(defn- brief-row
+ [row]
+ (compact (select-keys row [:id :name :description])))
+
+(defn- table-metadata-row
+ "Build the get_fields response row for one batch-fetched `table`, at detail level `fmt`.
+ Fields come out in `position` order — the order the single-table slice pages through."
+ [fmt related table]
+ (let [field-keys (case fmt
+ :concise field-concise-keys
+ :detailed field-detailed-keys)]
+ (-> (compact (select-keys table [:id :name :display_name :schema :db_id :description]))
+ (assoc :fields (into []
+ (map #(compact (select-keys % field-keys)))
+ (sort-by #(or (:position %) 0) (:fields table)))
+ :measures (mapv brief-row (:measures table))
+ :segments (mapv brief-row (:segments table))
+ :metrics (mapv brief-row (:metrics table))
+ :related_tables (get related (:id table) [])))))
+
+(defn- project-table
+ [args related table]
+ (if-let [fields (:fields args)]
+ (common/select-fields :table-metadata
+ (table-metadata-row :detailed related table)
+ fields
+ {:response-format (:response_format args)})
+ (table-metadata-row (common/response-format args) related table)))
+
+(defn- byte-size
+ ^long [x]
+ (alength (.getBytes ^String (json/encode x) "UTF-8")))
+
+(defn- slice-table-payload
+ "The explicit single-table slice: fields in position order from `offset`, as many as fit the
+ budget (never fewer than one, so paging always advances), plus counts and — when fields
+ remain — the continuation message naming the next offset."
+ [payload offset]
+ (let [all-fields (vec (:fields payload))
+ total (count all-fields)
+ base (assoc payload :fields [] :total_fields total :offset offset)
+ [included] (reduce (fn [[fields used] field]
+ (let [used' (+ used (byte-size field) 1)]
+ (if (and (seq fields) (> used' get-fields-byte-budget))
+ (reduced [fields used])
+ [(conj fields field) used'])))
+ [[] (byte-size base)]
+ (drop offset all-fields))
+ next-offset (+ offset (count included))
+ message (when (< next-offset total)
+ (format "%s: %d of %d fields, continue with `offset: %d`."
+ (or (:name payload) (:id payload)) (count included) total next-offset))]
+ {:payload (assoc base :fields included)
+ :message message}))
+
+(defn- assemble-tables
+ "Apply the byte budget to `payloads` (in request order): whole tables until the budget runs out.
+ When the first table alone exceeds the budget — or the caller passed an explicit `offset` — it
+ is returned as a single-table slice instead. Returns `{:tables [...] :message ...}`; `:tables`
+ is always a prefix of `payloads`, so the caller names what was dropped from its own source rows."
+ [payloads offset]
+ (if (and (seq payloads)
+ (or (some? offset)
+ (> (byte-size (first payloads)) get-fields-byte-budget)))
+ (let [{:keys [payload message]} (slice-table-payload (first payloads) (or offset 0))]
+ {:tables [payload]
+ :message message})
+ (loop [[payload & more :as remaining] payloads
+ used 0
+ tables []]
+ (if (empty? remaining)
+ {:tables tables}
+ (let [size (byte-size payload)]
+ (if (<= (+ used size) get-fields-byte-budget)
+ (recur more (+ used size) (conj tables payload))
+ {:tables tables}))))))
+
+(defn- get-fields
+ [{:keys [table_ids include_hidden offset] :as args}]
+ ;; Dedup before the guards: the cap and the single-table `offset` rule are about distinct tables,
+ ;; so `[1 1]` is one table (a valid `offset` target), not two, and repeated ids don't inflate the
+ ;; count toward the cap.
+ (let [table-ids (into [] (distinct) table_ids)]
+ (when (empty? table-ids)
+ (common/throw-teaching-error "`table_ids` must name at least one table."))
+ (when (> (count table-ids) max-table-ids)
+ (common/throw-teaching-error
+ (format "`table_ids` accepts at most %d ids per call — you passed %d; split the request."
+ max-table-ids (count table-ids))))
+ (when (and offset (> (count table-ids) 1))
+ (common/throw-teaching-error
+ "`offset` with get_fields pages the fields of one large table — request that table alone."))
+ (let [{fetched :rows missing :missing} (fetch-table-metadata-rows table-ids (true? include_hidden))
+ ;; A table whose database isn't browsable (a stub or router-destination database) is
+ ;; collapsed into `missing` exactly like an unreadable one — enforced here against the same
+ ;; filter [[list-databases]] uses, so a change to the metadata fetch can't reopen a leak.
+ browsable-db-ids (let [db-ids (into #{} (map :db_id) fetched)]
+ (when (seq db-ids)
+ (mcp.db/browsable-database-ids
+ db-ids
+ (schema.table/browsable-databases-honeysql-filter))))
+ browsable? (fn [row] (contains? browsable-db-ids (:db_id row)))
+ rows (filterv browsable? fetched)
+ missing (into (vec missing) (comp (remove browsable?) (map :id)) fetched)
+ detailed? (or (contains? args :fields)
+ (= :detailed (common/response-format args)))
+ rows (cond-> rows
+ detailed? attach-inline-values
+ detailed? withhold-restricted-fingerprints)
+ related (related-tables-by-requested-table browsable-db-ids rows)
+ payloads (mapv #(project-table args related %) rows)
+ {:keys [tables message]} (assemble-tables payloads offset)
+ ;; `tables` is a prefix of `payloads`, which is index-aligned with `rows`, so the tables
+ ;; the budget dropped are the matching suffix of `rows` — named from the source rows
+ ;; because a `fields` projection can strip `:id`/`:name` off the payloads.
+ omitted (into (mapv (fn [id]
+ {:id id
+ :reason "not found — it may not exist, or you may not have access to it"})
+ missing)
+ (map (fn [row]
+ {:id (:id row)
+ :name (:name row)
+ :reason "response budget — request in a separate call"}))
+ (drop (count tables) rows))
+ body (cond-> {:tables tables}
+ (seq omitted) (assoc :omitted omitted))]
+ (common/success-content (cond-> (json/encode body)
+ message (str "\n" message))))))
+
+;;; -------------------------------------------------- The tool ----------------------------------------------------
+
+(def ^:private browse-args-schema
+ [:map {:closed true}
+ [:action (into [:enum {:description "What to browse. list_databases → list_schemas → list_tables → get_fields walks the hierarchy; list_models lists the models built on a database."}]
+ ["list_databases" "list_schemas" "list_tables" "list_models" "get_fields"])]
+ [:database_id {:optional true}
+ [:maybe [:int {:description "Numeric database id (databases have no entity_id). Required for list_schemas, list_tables, and list_models. Ignored by get_fields."}]]]
+ [:schema {:optional true}
+ [:maybe [:string {:description "list_tables only: the schema to list. Omit (or pass \"\") for databases without schemas."}]]]
+ [:search {:optional true}
+ [:maybe [:string {:min 1 :description "list_tables only: case-insensitive substring filter on table name or display name, applied before paging."}]]]
+ [:table_ids {:optional true}
+ [:maybe [:sequential {:description "get_fields only: numeric table ids (tables have no entity_id), at most 20 per call."}
+ [:int {:min 1}]]]]
+ [:include_hidden {:optional true}
+ [:maybe [:boolean {:description "Include hidden schemas/tables (list_schemas, list_tables) or hidden fields (get_fields). Sensitive fields are always excluded. Default false."}]]]
+ [:limit {:optional true}
+ [:maybe [:int {:min 1 :max 500 :description "list_* actions: maximum rows to return (default 50)."}]]]
+ [:offset {:optional true}
+ [:maybe [:int {:min 0 :description "list_* actions: rows to skip, for paging. For get_fields it pages the fields of a single oversized table, as directed by the continuation message."}]]]
+ [:response_format {:optional true}
+ [:maybe [:enum {:description "concise (default) returns the essential columns; detailed adds the full projection (for get_fields: effective_type, coercion_strategy, database_type, fingerprint, has_field_values, and inline values for list-type fields). Values and fingerprints are permission-dependent, and absent rather than empty when withheld: values need permission to query the table, not just to read its metadata, and fingerprints are withheld entirely when your row access to the table is narrowed."}
+ "concise" "detailed"]]]
+ [:fields {:optional true}
+ [:maybe [:sequential [:string {:min 1 :description "Dot-paths picked from the detailed row shape, item-relative (e.g. \"fields.name\"). Mutually exclusive with response_format. Not supported for list_schemas."}]]]]])
+
+(registry/deftool browse-data
+ "Browse the data hierarchy: databases → schemas → tables → fields. Actions: list_databases — databases you can see; list_schemas — schema names in a database; list_tables — tables in a database, scoped to `schema` (omit it for databases without schemas) and optionally narrowed with `search`; list_models — models built on a database; get_fields — field metadata for up to 20 tables in one call, each table carrying its measures, segments, metrics, and related tables (FK targets with column names) for query construction. list_* actions return the {data, returned, total} envelope paged with limit/offset. get_fields returns whole tables within a response byte budget and names any tables it had to omit; a single table too large for the budget comes back as a position-ordered field slice with a continuation offset."
+ {:name "browse_data"
+ :scope metabot.scope/agent-content-read
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :args browse-args-schema}
+ [{:keys [action] :as args} _context]
+ (validate-args-for-action! args)
+ (case action
+ "list_databases" (list-databases args)
+ "list_schemas" (list-schemas args)
+ "list_tables" (list-tables args)
+ "list_models" (list-models args)
+ "get_fields" (get-fields args)))
+
+;;; --------------------------------------------- browse_collection ------------------------------------------------
+
+(def ^:private collection-item-concise-keys
+ [:id :name :model :description :collection_position])
+
+(def ^:private collection-item-detailed-keys
+ (into collection-item-concise-keys
+ [:entity_id :collection_id :database_id :display :archived :authority_level
+ :moderated_status :last_used_at :location :here :below :last-edit-info]))
+
+(projections/register-key-projection!
+ :collection-item collection-item-concise-keys
+ :detailed-keys collection-item-detailed-keys
+ :sample (-> (zipmap collection-item-detailed-keys (repeat "x"))
+ (assoc :last-edit-info {:id 1 :email "x" :first_name "x" :last_name "x" :timestamp "x"}
+ :here ["card"]
+ :below ["card"])))
+
+;;; ------------------------------------------ browse_collection validation ----------------------------------------
+
+(def ^:private collection-items-mode-args
+ #{:id :mode :namespace :type :created_by :pinned_state :sort_column :sort_direction :limit :offset
+ :response_format :fields})
+
+(def ^:private collection-tree-mode-args
+ #{:id :mode :namespace :depth})
+
+(defn- validate-browse-collection-args!
+ [{:keys [mode] :as args}]
+ (if (= mode "tree")
+ (when-let [bad (seq (sort (map name (remove collection-tree-mode-args (keys args)))))]
+ (common/throw-teaching-error
+ (format "`%s` do%s not apply to tree mode — trees have no pagination or item filters; re-root with browse_collection(id: <subcollection>, mode: \"tree\"), raise `depth`, or use mode: \"items\"."
+ (str/join "`, `" bad) (if (next bad) "" "es"))))
+ (when-let [bad (seq (sort (map name (remove collection-items-mode-args (keys args)))))]
+ (common/throw-teaching-error
+ (format "`%s` do%s not apply to items mode — `depth` shapes the tree; pass mode: \"tree\" to get one."
+ (str/join "`, `" bad) (if (next bad) "" "es"))))))
+
+(defn- namespace-arg
+ "The requested namespace as collection rows carry it: nil for content."
+ [{:keys [namespace]}]
+ (when-not (contains? #{nil "content"} namespace)
+ namespace))
+
+(defn- check-collection-namespace!
+ "A real collection id already carries its namespace; an explicit `namespace` argument that
+ contradicts it is a teaching error."
+ [{:keys [id] :as args} target-collection]
+ (when (contains? args :namespace)
+ (let [wanted (namespace-arg args)
+ actual (some-> (:namespace target-collection) u/qualified-name)]
+ (when (not= wanted actual)
+ (common/throw-teaching-error
+ (format "Collection %s is in the %s namespace — a real collection id already carries its namespace, so drop `namespace` or pass %s."
+ id (or actual "content") (pr-str (or actual "content"))))))))
+
+(defn- read-checked-collection
+ [id-or-eid]
+ (v2.resolve/resolve-and-read :model/Collection id-or-eid))
+
+(defn- read-checked-trash
+ []
+ (try
+ (api/read-check (collection/trash-collection))
+ (catch clojure.lang.ExceptionInfo e
+ (if (contains? #{403 404} (:status-code (ex-data e)))
+ (common/throw-not-found :collection "trash")
+ (throw e)))))
+
+(defn- resolve-browse-target
+ "Resolve the `id` argument to `{:root? <bool> :collection <row-or-root-placeholder>}`. Real
+ collections come back read-checked, with \"doesn't exist\" and \"not readable\" collapsed."
+ [{:keys [id] :as args}]
+ (cond
+ (= id "root")
+ {:root? true
+ :collection (assoc collection/root-collection :namespace (namespace-arg args))}
+
+ (= id "trash")
+ (let [trash (read-checked-trash)]
+ (check-collection-namespace! args trash)
+ {:collection trash})
+
+ :else
+ (let [coll (read-checked-collection id)]
+ (check-collection-namespace! args coll)
+ {:collection coll})))
+
+;;; --------------------------------------------- browse_collection items ------------------------------------------
+
+(def ^:private type->rest-model
+ {"question" :card
+ "model" :dataset
+ "metric" :metric
+ "dashboard" :dashboard
+ "collection" :collection
+ "document" :document})
+
+(defn- root-namespace-models
+ "Model set for a root listing: each namespace's own model plus subfolders; content follows
+ `type` (empty set = every type)."
+ [ns-str type]
+ (case ns-str
+ nil (into #{} (map type->rest-model) type)
+ "snippets" #{:snippet :collection}
+ "transforms" #{:transform :collection}
+ "analytics" #{:collection}))
+
+(defn- collection-items-content
+ [{:keys [type created_by pinned_state sort_column sort_direction] :as args} {:keys [root? collection]}]
+ (let [{:keys [limit offset]} (page-args args)
+ ns-str (some-> (:namespace collection) u/qualified-name)
+ _ (when (and (seq type) (some? ns-str))
+ (common/throw-teaching-error
+ (format "`type` applies to the content namespace only — the %s namespace returns its own model plus subfolders; drop `type`."
+ ns-str)))
+ created-by-id (when (= created_by "me") api/*current-user-id*)
+ models (if root?
+ (collections.children/visible-model-kwds collection (root-namespace-models ns-str type))
+ (into #{} (map type->rest-model) type))
+ trash? (collection/is-trash? collection)
+ options {:show-dashboard-questions? false
+ :include-library? (not root?)
+ :archived? (boolean (or (:archived collection) trash?))
+ :models models
+ :created-by-id created-by-id
+ :pinned-state (keyword (or pinned_state "all"))
+ :sort-info {:sort-column (keyword (str/replace (or sort_column "name") "_" "-"))
+ :sort-direction (keyword (or sort_direction "asc"))
+ :official-collections-first? (not trash?)}}
+ ;; scope the document content-gate cache over the listing: each document row's hydration
+ ;; adjudicates the gate, and the cache keeps that to once per document
+ res (request/with-limit-and-offset limit offset
+ (documents/with-content-gate-cache
+ (collections.children/collection-children collection options)))
+ total (or (:total res) 0)
+ ;; the snippets-namespace root path ignores the limit/offset binding (no :limit key on
+ ;; the result) and returns every row, so the page is sliced here
+ rows (if (contains? res :limit)
+ (vec (:data res))
+ (into [] (comp (drop offset) (take limit)) (:data res)))
+ projected (project-rows :collection-item args rows)
+ line (when (< (+ offset (count rows)) total)
+ (if (nil? ns-str)
+ (common/truncation-line {:param :type :offset offset :limit limit :total total
+ :returned (count rows)})
+ (format "Returned %d of %d — continue with `offset: %d`."
+ (count rows) total (+ offset limit))))]
+ (common/success-content (cond-> (json/encode (common/list-envelope projected total))
+ line (str "\n" line)))))
+
+;;; --------------------------------------------- browse_collection tree -------------------------------------------
+
+(def ^:private tree-default-depth 2)
+
+(def ^:private tree-child-cap
+ "Children surfaced per node in tree mode; the rest are named in the truncation marker."
+ 50)
+
+(def ^:private tree-node-budget
+ "Total nodes one tree response may contain, bounding the shallow-fetch composition."
+ 250)
+
+(defn- pr-id
+ [id]
+ (if (number? id) id (pr-str id)))
+
+(defn- tree-marker
+ "Marker for a node re-rooting recovers: re-rooting resets the depth and node budget, so a
+ fresh `mode: \"tree\"` call at this node reveals what depth or budget cut off here."
+ [more-count parent-name parent-id]
+ (format "… %s under %s — browse_collection(id: %s, mode: \"tree\")"
+ (if more-count (str more-count " more") "more")
+ (pr-str parent-name)
+ (pr-id parent-id)))
+
+(defn- cap-marker
+ "Marker for a node the per-node child cap trimmed. Re-rooting in tree mode re-applies the same
+ cap and returns the identical page, so this steers to items-mode pagination — the only way to
+ reach the children past the cap."
+ [more parent-name parent-id offset]
+ (format "… %d more under %s — browse_collection(id: %s, mode: \"items\", type: [\"collection\"], offset: %d)"
+ more (pr-str parent-name) (pr-id parent-id) offset))
+
+(defn- expand-tree-node
+ "Build the output node for `node` (`{:id :name :children <expandable?>}`), expanding up to
+ `depth` more levels through `fetch` while the shared node `budget` (an atom) lasts. A node
+ left unexpanded carries a truncation marker: depth/budget exhaustion recovers by re-rooting
+ in tree mode, but a node trimmed by the per-node cap steers to items-mode pagination, which
+ is the only call that reaches the trimmed children."
+ [fetch {:keys [id name] :as node} depth budget]
+ (cond
+ (not (:children node))
+ {:id id :name name :children []}
+
+ (or (zero? depth) (not (pos? @budget)))
+ {:id id :name name :children [] :truncated (tree-marker nil name id)}
+
+ :else
+ (let [children (fetch id)
+ allowed (min tree-child-cap @budget)
+ included (vec (take allowed children))
+ _ (swap! budget - (count included))
+ expanded (mapv #(expand-tree-node fetch % (dec depth) budget) included)
+ more (- (count children) (count included))]
+ (cond-> {:id id :name name :children expanded}
+ (pos? more) (assoc :truncated
+ ;; cap-bound (budget left room) → items pagination; budget-bound → tree
+ (if (<= tree-child-cap allowed)
+ (cap-marker more name id (count included))
+ (tree-marker more name id)))))))
+
+(defn- tree-child-fetch
+ "A `fetch` for [[expand-tree-node]] backed by a single query: the visible, non-archived
+ collections of `namespaces` grouped by direct-parent id (root-level under `::root`), each an
+ expandable tree node in `select-collections` order. Replaces the former per-node fetch — one
+ permission-filtered query for the whole tree instead of one per expanded node."
+ [namespaces]
+ (let [colls (collections.children/select-collections
+ {:archived false
+ :exclude-other-user-collections false
+ :namespaces namespaces
+ :shallow false
+ :include-library? false})
+ visible (into #{} (map :id) colls)
+ ;; Group by the nearest VISIBLE ancestor, not the direct parent. `select-collections` is
+ ;; permission-filtered, so a collection the caller can read may sit under one they cannot; keying on
+ ;; the direct parent would drop it from the tree entirely. `collections->tree` pulls such a
+ ;; collection up to its nearest visible ancestor (A > B > C with B hidden renders as A > C) and this
+ ;; mirrors that.
+ grouped (group-by (fn [c]
+ (or (last (filterv visible (collection/location-path->ids (:location c))))
+ ::root))
+ colls)]
+ (fn [id]
+ (mapv (fn [c] {:id (:id c) :name (:name c) :children (contains? grouped (:id c))})
+ (grouped (if (number? id) id ::root))))))
+
+(defn- collection-tree-content
+ [args {:keys [root? collection]}]
+ (when (collection/is-trash? collection)
+ (common/throw-teaching-error
+ "The trash never appears in tree mode — use mode: \"items\" to list trashed items."))
+ (when (:archived collection)
+ (common/throw-teaching-error
+ (format "Collection %s is archived — archived subtrees never appear in tree mode; browse its items instead."
+ (:id collection))))
+ (let [depth (or (:depth args) tree-default-depth)
+ ns-str (some-> (:namespace collection) u/qualified-name)
+ fetch (tree-child-fetch #{ns-str})
+ budget (atom tree-node-budget)
+ root-node {:id (if root? "root" (:id collection))
+ :name (if root?
+ (:name (collection/root-collection-with-ui-details ns-str))
+ (:name collection))
+ :children true}]
+ (common/success-content (json/encode (expand-tree-node fetch root-node depth budget)))))
+
+;;; --------------------------------------------- browse_collection tool -------------------------------------------
+
+(def ^:private browse-collection-args-schema
+ [:map {:closed true}
+ [:id [:or
+ [:int {:description "Numeric collection id."}]
+ [:string {:min 1 :description "A 21-character entity_id, \"root\" (the per-namespace root), or \"trash\" (items mode only — archived content, making restore discoverable)."}]]]
+ [:mode {:optional true}
+ [:maybe [:enum {:description "items (default) lists the collection's contents; tree returns the nested subcollection structure (collections only, no items, no pagination)."}
+ "items" "tree"]]]
+ [:namespace {:optional true}
+ [:maybe [:enum {:description "Which collection partition to browse; only meaningful with id: \"root\" (a real collection id already carries its namespace). content (default) holds questions/dashboards/etc.; snippets holds snippet folders and snippets; transforms holds transform folders and transforms; analytics is the read-only usage-analytics tree."}
+ "content" "snippets" "transforms" "analytics"]]]
+ [:type {:optional true}
+ [:maybe [:sequential [:enum {:description "items mode, content namespace only: return only these item types."}
+ "question" "model" "metric" "dashboard" "collection" "document"]]]]
+ [:created_by {:optional true}
+ [:maybe [:enum {:description "items mode: me restricts results to items the current user created (questions, models, metrics, dashboards, documents — other types return nothing under this filter). Composes with type."}
+ "me"]]]
+ [:pinned_state {:optional true}
+ [:maybe [:enum {:description "items mode: all (default) interleaves pinned and unpinned rows. Pinned-first as in the product is two calls — is_pinned, then is_not_pinned — each paging independently."}
+ "all" "is_pinned" "is_not_pinned"]]]
+ [:sort_column {:optional true}
+ [:maybe [:enum {:description "items mode: sort key (default name)."} "name" "last_edited_at" "model"]]]
+ [:sort_direction {:optional true}
+ [:maybe [:enum {:description "items mode: sort direction (default asc)."} "asc" "desc"]]]
+ [:limit {:optional true}
+ [:maybe [:int {:min 1 :max 500 :description "items mode: maximum rows to return (default 50)."}]]]
+ [:offset {:optional true}
+ [:maybe [:int {:min 0 :description "items mode: rows to skip, for paging."}]]]
+ [:depth {:optional true}
+ [:maybe [:int {:min 1 :max 10 :description "tree mode: subcollection levels to expand (default 2). Deeper or trimmed nodes carry a truncation marker naming the re-rooting call."}]]]
+ [:response_format {:optional true}
+ [:maybe [:enum {:description "items mode: concise (default) returns {id, name, model, description, collection_position} rows; detailed adds entity_id, collection_id, archived, location, and last-edit info."}
+ "concise" "detailed"]]]
+ [:fields {:optional true}
+ [:maybe [:sequential [:string {:min 1 :description "items mode: dot-paths picked from the detailed row shape, item-relative (e.g. \"last-edit-info.email\"). Mutually exclusive with response_format."}]]]]])
+
+(registry/deftool browse-collection
+ "Browse collections structurally — one uniform id over every partition: a numeric id, a 21-char entity_id, \"root\" (re-rooted per namespace), or \"trash\" (archived content, items mode only). items mode (default) lists one collection's contents with type/created_by/pinned_state/sort_column/sort_direction and limit/offset paging in the {data, returned, total} envelope; browsing the trash or an archived collection returns archived children. tree mode returns the nested subcollection structure (collections only, no items, no pagination) down to depth (default 2) under a per-node child cap and total node budget; trimmed or deeper nodes carry a marker naming the expansion call, e.g. … 14 more under \"Finance\" — browse_collection(id: 45, mode: \"tree\"); archived subtrees and the trash never appear in trees. For content search or recents use the search tool."
+ {:name "browse_collection"
+ :scope metabot.scope/agent-content-read
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :args browse-collection-args-schema}
+ [{:keys [mode] :as args} _context]
+ (validate-browse-collection-args! args)
+ (let [target (resolve-browse-target args)]
+ (if (= mode "tree")
+ (collection-tree-content args target)
+ (collection-items-content args target))))
diff --git a/src/metabase/mcp/v2/tools/collection.clj b/src/metabase/mcp/v2/tools/collection.clj
new file mode 100644
index 00000000000..3dd8e99fbb8
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/collection.clj
@@ -0,0 +1,185 @@
+(ns metabase.mcp.v2.tools.collection
+ "The v2 MCP `collection_write` tool: create, rename, move, archive, and restore collections.
+ Both methods delegate to the shared domain fns the REST endpoints use
+ ([[metabase.collections.core/create-collection!]] and
+ [[metabase.collections.core/update-collection!]]), so parent write-checks, authority-level
+ gating, parent inheritance, descendant path rewriting, and the event pair are inherited
+ rather than reimplemented. The tool's own work is id resolution behind read checks,
+ method-appropriateness checks, and the write echo."
+ (:require
+ [metabase.channel.urls :as channel.urls]
+ [metabase.collections.core :as collections]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]))
+
+(set! *warn-on-reflection* true)
+
+(defn- write-result
+ "The created/updated collection echoed to the caller: the concise read projection — so the echo
+ and a concise get_content read carry the same fields by construction — plus `:entity_id` (a
+ portable id to update by), `:url` (where the collection lives in the app), and the two write
+ args the concise projection omits, `:authority_level` and `:namespace`, so every field this
+ tool accepts is confirmed back rather than silently dropped."
+ [collection]
+ ;; The :collection projection is registered by metabase.mcp.v2.projections itself, which this ns
+ ;; requires — so the registry is populated before any tool dispatch reaches here.
+ (assoc (projections/project :collection :concise collection)
+ :entity_id (:entity_id collection)
+ :url (common/frontend-url (channel.urls/collection-path (:id collection)))
+ :authority_level (:authority_level collection)
+ :namespace (:namespace collection)))
+
+(defn- check-method-args!
+ "Reject arguments that don't apply to the dispatched method, so a caller never believes an
+ ignored field took effect."
+ [method args]
+ (case method
+ :create (doseq [k [:id :archived]]
+ (when (contains? args k)
+ (common/throw-teaching-error
+ (format "`%s` applies to method \"update\" only — remove it from this create call." (name k)))))
+ :update (do
+ (when (contains? args :namespace)
+ (common/throw-teaching-error
+ (str "`namespace` applies to method \"create\" only — a collection cannot move between "
+ "namespaces, which are independent hierarchies.")))
+ (when (and (true? (:archived args)) (contains? args :parent_id))
+ (common/throw-teaching-error
+ (str "`archived: true` and `parent_id` can't be combined — archiving moves the collection "
+ "to the trash, so the parent_id move never happens. Move first, then archive; or "
+ "archive now and pass `parent_id` on a later `archived: false` restore call."))))))
+
+(defn- check-move-out-of-trash!
+ "Reject a `parent_id` move of a trashed `collection` that doesn't say what to do about the trash.
+ Archiving leaves `:location` untouched, so the move would succeed against the collection's
+ pre-trash location and report the new parent while the collection stayed in the trash."
+ [collection args]
+ (when (and (:archived collection)
+ (contains? args :parent_id)
+ (not (contains? args :archived)))
+ (common/throw-teaching-error
+ (str "This collection is in the trash, and `parent_id` on its own would move it without taking it "
+ "out — nothing would appear under the new parent. Pass `archived: false` alongside `parent_id` "
+ "to restore it into the new parent."))))
+
+(defn- resolve-existing
+ "Resolve an update's `id` (numeric or entity_id) to the collection behind its read check.
+ \"Doesn't exist\" and \"exists but not readable\" collapse into the same not-found error, so
+ the response never leaks existence across the permission boundary. `update-collection!` still
+ runs its own write check."
+ [id-or-eid]
+ (v2.resolve/resolve-and-read :model/Collection id-or-eid))
+
+(defn- create!
+ [{:keys [description parent_id authority_level], coll-name :name, coll-namespace :namespace, :as args}]
+ (check-method-args! :create args)
+ ;; A namespaced collection ("snippets", "transforms") is its own hierarchy, and personal
+ ;; collections only exist in the default one — so only a normal collection can default into the
+ ;; caller's.
+ (let [parent-id (if coll-namespace
+ (v2.resolve/resolve-collection-id parent_id)
+ (v2.resolve/resolve-collection-id-or-personal parent_id))]
+ (write-result
+ (collections/create-collection!
+ (cond-> {:name coll-name}
+ description (assoc :description description)
+ parent-id (assoc :parent_id parent-id)
+ coll-namespace (assoc :namespace coll-namespace)
+ authority_level (assoc :authority_level authority_level))))))
+
+(defn- update!
+ [id {:keys [description parent_id archived authority_level], coll-name :name, :as args}]
+ (check-method-args! :update args)
+ (let [collection (resolve-existing id)]
+ (check-move-out-of-trash! collection args)
+ (write-result
+ (collections/update-collection!
+ (:id collection)
+ (cond-> {}
+ (contains? args :name) (assoc :name coll-name)
+ (contains? args :description) (assoc :description description)
+ (contains? args :parent_id) (assoc :parent_id (v2.resolve/resolve-collection-id parent_id))
+ (contains? args :archived) (assoc :archived (boolean archived))
+ (contains? args :authority_level) (assoc :authority_level authority_level))))))
+
+(def ^:private collection-write-args-schema
+ [:map {:closed true}
+ [:method
+ [:enum {:description (str "\"create\" makes a new collection (requires `name`); \"update\" edits the one named "
+ "by `id`.")}
+ "create" "update"]]
+ [:id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the collection to update."}]
+ [:string {:description "21-character entity_id of the collection to update."}]]]]
+ [:name {:optional true}
+ [:maybe [:string {:min 1 :description "Required on create; editable on update: display name of the collection."}]]]
+ [:description {:optional true}
+ [:maybe [:string {:min 1 :description (str "Optional human-readable description. To remove one, name it in "
+ "`clear` — `clear: [\"description\"]`.")}]]]
+ [:parent_id {:optional true}
+ [:maybe [:or {:description (str "The collection to nest under (create) or move into (update). Numeric id, "
+ "21-character entity_id, or \"root\" for the top level. Omitted on create means "
+ "your personal collection. You need write access to the parent.")}
+ :int :string]]]
+ [:clear {:optional true}
+ [:maybe [:sequential [:enum {:description "Update only: property names to unset (description, authority_level). Needed because a null cannot say \"clear this\" — strict clients fill every unset property with null, so nulls are stripped at the boundary."}
+ "description" "authority_level"]]]]
+ [:archived {:optional true}
+ [:maybe [:boolean {:description (str "Update only: true moves the collection and its contents to the trash, false "
+ "restores them. Archiving is the only removal path — there is no hard "
+ "delete. Omit to leave the collection's trashed state alone.")}]]]
+ [:namespace {:optional true}
+ [:maybe [:enum {:description (str "Create only: puts the collection in a separate hierarchy instead of the "
+ "normal one. \"snippets\" holds SQL snippet folders; \"transforms\" holds "
+ "transform folders, the ones transform_write's `collection_id` names. Omit "
+ "for a normal collection.")}
+ "snippets" "transforms"]]]
+ [:authority_level {:optional true}
+ [:maybe [:enum {:description (str "Marks the collection Official. Requires an admin on an instance with the "
+ "Official Collections feature. To make a collection unofficial again, name "
+ "it in `clear` — `clear: [\"authority_level\"]`.")}
+ "official"]]]])
+
+(def ^:private collection-write-entry
+ {:create-required [:name]
+ :clearable #{:description :authority_level}})
+
+(registry/deftool collection-write
+ "Create, rename, move, archive, or restore a collection — the folders that hold questions, dashboards, models, and
+ documents. method: \"create\" requires name and accepts description, parent_id, namespace, and authority_level;
+ method: \"update\" requires id and accepts name, description, parent_id, archived, and authority_level. parent_id
+ nests a new collection or moves an existing one: pass a numeric id, a 21-character entity_id, or \"root\" for the top
+ level; omitting it on create means your personal collection (the root collection for a namespaced one), and omitting
+ it on update leaves the collection where it is.
+ You need write access to the parent. archived: true moves the collection and everything in it to the trash, false
+ restores it — there is no hard delete, and omitting archived leaves the trashed state alone. To move something out of
+ the trash, pass archived: false together with parent_id; parent_id on its own would leave it trashed. namespace is
+ create-only
+ (\"snippets\" for SQL snippet folders, \"transforms\" for the transform folders transform_write files transforms
+ into); collections cannot move between namespaces. authority_level \"official\"
+ marks the collection Official and needs an admin on an instance with that feature. description and authority_level
+ can be set, rewritten, and cleared — to erase one, name it in clear (clear: [\"description\"]); sending null does
+ not work, because unset properties are stripped before the tool sees them. Personal collections
+ themselves cannot be created or moved, but you can nest collections inside one by passing its id as parent_id.
+ Returns the resulting collection, including authority_level and namespace, so no follow-up read is needed."
+ {:name "collection_write"
+ :scope metabot.scope/agent-content-write
+ ;; `archived: true` trashes the collection and everything under it, so this is not the
+ ;; additive-only update `destructiveHint false` would assert.
+ :annotations {:readOnlyHint false :destructiveHint true}
+ :args collection-write-args-schema}
+ [args {:keys [token-scopes]}]
+ (let [[op a b] (v2.write/dispatch-write collection-write-entry args)
+ payload (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (case op
+ :create (create! a)
+ :update (update! a b))
+ nil)]
+ ;; text-only, matching the stack convention (see common/success-content): the write echo has no
+ ;; concrete programmatic consumer, so it doesn't ride structuredContent.
+ (common/success-content payload)))
diff --git a/src/metabase/mcp/v2/tools/content.clj b/src/metabase/mcp/v2/tools/content.clj
new file mode 100644
index 00000000000..d5d78e302ba
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/content.clj
@@ -0,0 +1,682 @@
+(ns metabase.mcp.v2.tools.content
+ "The v2 MCP `get_content` tool: a batched, typed fetch over every content type an agent can
+ hold a `{type, id}` pair for. Each item is resolved (numeric id or entity_id), read-checked, and
+ projected through the shared concise/detailed machinery with per-type `include` sections. Items
+ are fault-isolated: one bad id, denied read, or teaching error becomes that item's
+ `{type, id, error}` object and never sinks the rest of the batch.
+
+ The scope gate is the tool's alone — one `agent:content:read` check at the registry boundary,
+ covering every type. The per-entity read scopes these types once needed folded into it in
+ GHY-4225, so there is deliberately no per-type scope here.
+
+ Per-type notes:
+ - question/model/metric ride one Card fetch; `definition` returns the stored `dataset_query`
+ normalized and serialized — the numeric-id MBQL 5 shape execute_query and question_write
+ accept back verbatim.
+ - dashboard returns the editing skeleton (tabs, parameters with wired dashcard ids, one
+ summary row per dashcard) — never the raw REST `dashcards` array.
+ - alert/subscription redact recipients for non-admin callers exactly as `/api/pulse` does;
+ subscription reads cover live Pulse rows and rows migrated to the notification API."
+ (:require
+ [clojure.string :as str]
+ [metabase.comments.core :as comments]
+ [metabase.documents.core :as documents]
+ [metabase.documents.prose-mirror :as prose-mirror]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.redaction :as redaction]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.metabot.metadata-perms :as metadata-perms]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.metrics.core :as metrics]
+ [metabase.models.interface :as mi]
+ [metabase.pulse.core :as pulse]
+ [metabase.queries.core :as queries]
+ [metabase.transforms.core :as transforms]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.util.log :as log]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private max-items
+ "Batch cap for one get_content call."
+ 10)
+
+;;; --------------------------------------------- question / model / metric ----------------------------------------
+
+(defn- card-query
+ "The card's own saved query as a lib query, or nil when the stored `dataset_query` is
+ empty/broken — reads degrade by dropping the query-derived keys, never by failing."
+ [mp dataset-query]
+ (when (and mp (map? dataset-query) (seq dataset-query))
+ (try
+ (lib/query mp (lib-be/normalize-query dataset-query))
+ (catch Exception _ nil))))
+
+(defn- raw-template-tags
+ "The stored template-tags of a native `dataset-query`, keyed by tag name — read from whichever
+ slot the query keeps them in: the legacy `[:native :template-tags]` map, or a pMBQL native
+ stage's tag vector."
+ [dataset-query]
+ (or (not-empty (get-in dataset-query [:native :template-tags]))
+ (when-let [tags (some (comp not-empty :template-tags) (:stages dataset-query))]
+ (into {} (map (juxt :name identity)) tags))))
+
+(defn- source-cards-readable?
+ "Whether the current user can read every Card `query` reads, at any depth.
+
+ [[metabase.lib.core/describe-query]] resolves source cards through
+ [[metabase.lib-be.core/application-database-metadata-provider]], which applies no per-user read
+ check, and renders their display names into the summary. Without this gate a caller who can read
+ a wrapper card but not its source learns the source's name from the wrapper — the one read
+ surface that leaked it, while the direct read, the run path, and search all deny it (GHY-4510).
+
+ Fails closed: a source card that no longer exists, or a query this can't walk, counts as
+ unreadable rather than rendering a summary from metadata we cannot account for."
+ [query]
+ (try
+ (let [ids (lib/all-source-card-ids-recursive query)]
+ (or (empty? ids)
+ (let [cards (mcp.db/select-by-ids :model/Card ids)]
+ (and (= (count cards) (count ids))
+ (every? mi/can-read? cards)))))
+ (catch Exception _ false)))
+
+(def ^:private max-native-summary-length
+ "Character budget for the query text rendered into a native card's `query_summary`."
+ 300)
+
+(defn- native-query-summary
+ "A one-line summary of a native `query`: the head of the query text itself, whitespace-collapsed
+ and truncated to [[max-native-summary-length]]. nil when the stage holds no text or holds a
+ non-string one — Mongo and friends store a map — leaving the caller on the generic
+ Lib description."
+ [query]
+ (let [sql (try (lib/raw-native-query query) (catch Exception _ nil))]
+ (when (string? sql)
+ (let [one-line (str/trim (str/replace sql #"\s+" " "))]
+ (when-not (str/blank? one-line)
+ (str "SQL: " (u/truncate one-line max-native-summary-length)
+ (when (> (count one-line) max-native-summary-length) "…")))))))
+
+(defn- database-name
+ "The name of the database `mp` provides metadata for, or nil when that database is gone. Read off
+ the provider the row already built rather than with a second query."
+ [mp]
+ (when mp
+ (try (:name (lib.metadata/database mp)) (catch Exception _ nil))))
+
+(defn- card-content-row
+ [card]
+ (let [dataset-query (:dataset_query card)
+ native? (= :native (some-> (:query_type card) keyword))
+ mp (some-> (:database_id card) lib-be/application-database-metadata-provider)
+ query (card-query mp dataset-query)]
+ (assoc card
+ ;; The bare `collection_id` alone does not say where an item lives, so a caller that
+ ;; wanted to state that had to spend a second call resolving the collection — search
+ ;; already returns the same path on its rows.
+ :collection_path (v2.resolve/collection-path (:collection_id card))
+ ;; Lib's native-stage display name is the bare placeholder "Native query" — enough in
+ ;; the UI, where the SQL renders beside it, and nothing at all to a caller holding only
+ ;; this row (GHY-4518). Both branches stay behind the source-card gate: a native query
+ ;; can name a Card in a template tag as readily as an MBQL stage can.
+ :query_summary (when (and query (source-cards-readable? query))
+ (or (when native? (native-query-summary query))
+ (try (lib/describe-query query) (catch Exception _ nil))))
+ ;; `database_id` alone made naming the source cost a second `search` call.
+ :database_name (database-name mp)
+ :template_tags (when native? (raw-template-tags dataset-query))
+ ;; The materialized parameter list — for native cards it is derived from the raw
+ ;; template tags above (same data, two views), for MBQL cards it is the stored array.
+ :parameters (if (and native? (empty? (:parameters card)))
+ (not-empty (vec (queries/card-template-tag-parameters card)))
+ (not-empty (:parameters card)))
+ ::query query
+ ::mp mp)))
+
+(defn- fetch-card
+ [tool-type id-or-eid]
+ (let [card (v2.resolve/resolve-and-read :model/Card id-or-eid)]
+ (when (not= (:type card) tool-type)
+ (let [actual (name (:type card))]
+ (common/throw-teaching-error
+ (format "Card %s is a %s — request it with type: \"%s\"." (:id card) actual actual))))
+ (card-content-row card)))
+
+(defn- card-definition
+ [row]
+ (some-> (::query row) lib/prepare-for-serialization))
+
+;; The projections another tool also builds on — `:question` (browse_collection), `:metric`
+;; (metric_write), `:document` (document_write) — are registered in [[metabase.mcp.v2.projections]],
+;; the namespace every consumer requires. The ones registered below are get_content's alone.
+
+;;; ------------------------------------------------ measure / segment ---------------------------------------------
+
+(def ^:private measure-segment-concise-keys
+ [:id :name :description :table_id :archived])
+
+(def ^:private measure-segment-detailed-keys
+ (into measure-segment-concise-keys
+ [:entity_id :creator_id :created_at :updated_at]))
+
+(doseq [type [:measure :segment]]
+ (projections/register-key-projection! type measure-segment-concise-keys
+ :detailed-keys measure-segment-detailed-keys))
+
+(defn- fetch-measure-or-segment
+ [model id-or-eid]
+ (v2.resolve/resolve-and-read model id-or-eid))
+
+(defn- measure-or-segment-definition
+ "The measure's aggregation clause / segment's filter clauses in the numeric-id MBQL 5 shape,
+ or nil when the stored definition can't be serialized."
+ [kind row]
+ (try
+ (let [table (mcp.db/table-by-id (:table_id row))
+ mp (lib-be/application-database-metadata-provider (:db_id table))
+ metadata (case kind
+ :measure (lib.metadata/measure mp (:id row))
+ :segment (lib.metadata/segment mp (:id row)))
+ definition-key (case kind :measure :aggregation :segment :filters)]
+ (some-> (:definition metadata)
+ lib/prepare-for-serialization
+ (get-in [:stages 0 definition-key])))
+ (catch Exception _ nil)))
+
+;;; -------------------------------------------------- dimensions --------------------------------------------------
+
+(defn- dimensions-section
+ "The `dimensions` include for metrics and measures: the same permission-filtered
+ `dimensions`/`dimension_mappings` pair `GET /api/metric/:id` and `GET /api/measure/:id`
+ return — computed on read but, unlike those endpoints, never persisted, so this stays within
+ the tool's `readOnlyHint` contract."
+ [type row]
+ (let [[metadata-type model] (case type
+ :metric [:metadata/metric :model/Card]
+ :measure [:metadata/measure :model/Measure])]
+ (when-let [computed (metrics/compute-dimensions metadata-type (:id row))]
+ (let [fresh (-> (mcp.db/select-one-by-id model (:id row))
+ (merge computed)
+ metrics/filter-dimensions-for-user
+ ;; Both endpoints drop orphaned dimensions unless asked for them; an agent
+ ;; that grouped by one would be querying a column that no longer exists.
+ metrics/without-orphaned-dimensions)]
+ ;; Encoded the way the endpoints encode them — snake_case keys and qualified type strings.
+ ;; The internal shape is kebab-case and carries `:lib/source`, which no other field in this
+ ;; tool's output uses and which the REST wire shape has never exposed.
+ {:dimensions (metrics/->api-dimensions (:dimensions fresh))
+ :dimension_mappings (metrics/->api-dimension-mappings (:dimension_mappings fresh))}))))
+
+;;; -------------------------------------------------- collection --------------------------------------------------
+
+(defn- fetch-collection
+ [id-or-eid]
+ (v2.resolve/resolve-and-read :model/Collection id-or-eid))
+
+;;; --------------------------------------------------- snippet ----------------------------------------------------
+
+(def ^:private snippet-concise-keys
+ [:id :name :description :content :collection_id :archived])
+
+(def ^:private snippet-detailed-keys
+ (into snippet-concise-keys
+ [:entity_id :creator_id :created_at :updated_at]))
+
+(projections/register-key-projection! :snippet snippet-concise-keys
+ :detailed-keys snippet-detailed-keys)
+
+(defn- fetch-snippet
+ [id-or-eid]
+ (v2.resolve/resolve-and-read :model/NativeQuerySnippet id-or-eid))
+
+;;; --------------------------------------------------- document ---------------------------------------------------
+
+;; The `:document` projection is registered in [[metabase.mcp.v2.projections]] because
+;; `document_write` echoes through it too.
+
+(defn- fetch-document
+ [id-or-eid]
+ (let [doc (v2.resolve/resolve-and-read-with :model/Document id-or-eid
+ ;; `:log-view? false` — this tool is readOnlyHint, and
+ ;; an agent's read has no business in a user's recents.
+ (fn [id] (documents/get-document id :log-view? false)))
+ ;; The Metabase-flavored Markdown body — the same text document_write's old_str edits
+ ;; match against — plus the node-id -> character-offset spans the comments include
+ ;; anchors threads with. A body the serializer can't render (e.g. an unrecognized node
+ ;; type) omits the key rather than failing the read.
+ ;;
+ ;; `content_markdown` is omitted rather than filled with a degraded rendering, matching
+ ;; `document_write`'s body-projection and for the same reason: `content_markdown` is the
+ ;; key document_write takes as a whole-body rewrite, and the flattened prose
+ ;; `prose-mirror/ast->text` produces drops headings, card embeds and layout containers.
+ ;; Writing it back replaces the stored AST with a single paragraph and orphans every
+ ;; anchored comment thread — and both tool descriptions route a read-modify-write through
+ ;; exactly this key, so a degraded value here is a destructive round trip the agent has no
+ ;; way to see. `Throwable`, again matching body-projection: an unrenderable body is exactly
+ ;; the input that finds a way to fail that isn't an `Exception`.
+ ser (try
+ (documents/serialize (:document doc))
+ (catch Throwable e
+ (log/warn e "document body has no Markdown rendering; omitting content_markdown"
+ (:id doc))
+ nil))]
+ (-> doc
+ (assoc ::document doc
+ ::spans (:spans ser))
+ (merge (if ser
+ {:content_markdown (:markdown ser)}
+ {:content_markdown_unavailable
+ (str "This document's body contains a block that has no Markdown form, so "
+ "content_markdown is omitted and edits cannot be applied to it. Writing "
+ "this document back through content_markdown would discard that block.")})))))
+
+(defn- document-layout
+ "Top-level node outline of the document's ProseMirror AST: one entry per block, with the
+ embedded card id for cardEmbed nodes and the block's flattened text."
+ [row]
+ (mapv (fn [node]
+ (u/remove-nils {:type (:type node)
+ :card_id (when (= (:type node) prose-mirror/card-embed-type)
+ (get-in node [:attrs "id"]))
+ :text (not-empty (prose-mirror/ast->text node))}))
+ (get-in row [::document :document :content])))
+
+(defn- comment-thread-row
+ [comment-row]
+ (u/remove-nils {:id (:id comment-row)
+ :parent_comment_id (:parent_comment_id comment-row)
+ :creator (get-in comment-row [:creator :common_name])
+ :created_at (:created_at comment-row)
+ :is_resolved (:is_resolved comment-row)
+ :text (prose-mirror/ast->text (:content comment-row))}))
+
+(defn- node-id->ancestor-ids
+ "Every `_id` in the document mapped to its ancestors' `_id`s, nearest first. Blocks nested inside
+ lists/blockquotes carry no span of their own (their text is re-rendered with line prefixes), so
+ a comment anchored to one resolves to the nearest ancestor that does have a span. The chain has
+ to be walked rather than jumping to the top-level block: layout containers (`resizeNode`,
+ `flexContainer`) carry no `_id` at all, so a top-level lookup finds nothing for anything nested
+ in one, while their `supportingText` children are emitted verbatim and do have spans."
+ [row]
+ (letfn [(walk [node ancestors]
+ (let [id (get-in node [:attrs "_id"])
+ inherited (cond->> ancestors id (cons id))]
+ (concat (when id [[id ancestors]])
+ (mapcat #(walk % inherited) (:content node)))))]
+ (into {} (mapcat #(walk % [])) (get-in row [::document :document :content]))))
+
+(defn- document-comments
+ "The `comments` include: the document's live comment threads, grouped by the block node id
+ (`child_target_id`) they anchor to, each with an `anchor` locating that block in the returned
+ `markdown` — the exact `[start, end)` slice of the anchored block, joined via the serializer's
+ node-id spans (a nested block rolls up to the nearest enclosing block that has one). Threads
+ whose anchor id matches nothing (their block was rewritten or deleted) land in
+ `orphaned_comments` instead. On
+ the serializer-fallback read there are no spans at all, so every thread is returned unanchored
+ under `comments` — absence of anchors there means \"unknown\", not \"orphaned\"."
+ [row]
+ (let [markdown (:content_markdown row)
+ spans (::spans row)
+ span-by-id (into {} (map (juxt :node-id identity)) spans)
+ ancestor-ids (node-id->ancestor-ids row)
+ threads (->> (comments/comments-for-document (:id row))
+ (group-by :child_target_id)
+ (sort-by (fn [[_ cs]] ((juxt :created_at :id) (first cs))))
+ (mapv (fn [[child-id cs]]
+ (u/remove-nils
+ {:child_target_id child-id
+ :anchor (when-let [{:keys [start end]}
+ (some span-by-id (cons child-id (ancestor-ids child-id)))]
+ {:start start
+ :end end
+ :text (subs markdown start end)})
+ :thread (mapv comment-thread-row cs)}))))]
+ (if (nil? spans)
+ {:comments threads}
+ (let [{anchored true orphaned false} (group-by (comp some? :anchor) threads)]
+ (cond-> {:comments (vec (sort-by #(get-in % [:anchor :start]) anchored))}
+ (seq orphaned) (assoc :orphaned_comments (vec orphaned)))))))
+
+;;; --------------------------------------------------- dashboard --------------------------------------------------
+
+(defn- fetch-dashboard
+ [id-or-eid]
+ (let [dash (-> (v2.resolve/resolve-and-read :model/Dashboard id-or-eid)
+ (t2/hydrate [:dashcards :series :card] :tabs)
+ redaction/redact-dashboard)]
+ (assoc (projections/dashboard-row dash) ::dashboard dash)))
+
+(defn- link-entity-ref
+ "The read-checked form of one link card's stored entity snapshot, as
+ `:dashcard/linkcard-info` hydrated it: the bare `{model, id}` reference — the shape
+ `patch_dashcard` takes back verbatim — when the caller can read the target, `{restricted
+ true}` when they cannot. The `name` and `description` cached beside the reference when the
+ card was written never ride along; they are a snapshot no read check stands behind."
+ [entity]
+ (if (:restricted entity)
+ {:restricted true}
+ (not-empty (select-keys entity [:model :id]))))
+
+(defn- read-checked-link
+ "A link card's `:link` visualization setting with its entity snapshot reduced to a read-checked
+ reference. An external-url link carries no entity and passes through untouched; an entity that
+ reduces to nothing — a stored snapshot naming neither a model nor an id — drops out rather than
+ reading back as an empty reference."
+ [link]
+ (if-let [entity (some-> (:entity link) link-entity-ref)]
+ (assoc link :entity entity)
+ (dissoc link :entity)))
+
+(defn- dashboard-layout
+ "The `layout` include: tabs with positions and the per-dashcard grid/wiring detail
+ `patch_dashcard` edits — parameter mappings, inline parameters, and visualization settings,
+ with each link card's entity reduced to a read-checked reference by [[link-entity-ref]]."
+ [row]
+ (let [dash (::dashboard row)
+ ;; the same batched hydration the REST dashboard endpoint runs, so a link target the
+ ;; caller cannot read arrives already collapsed to `{:restricted true}`
+ dashcards (t2/hydrate (:dashcards dash) :dashcard/linkcard-info)]
+ {:tabs (mapv #(select-keys % [:id :name :position]) (:tabs dash))
+ :dashcards (mapv (fn [dc]
+ (-> (select-keys dc [:id :card_id :action_id :dashboard_tab_id :row :col
+ :size_x :size_y :inline_parameters :parameter_mappings
+ :visualization_settings])
+ (update :visualization_settings
+ #(cond-> % (map? (:link %)) (update :link read-checked-link)))
+ u/remove-nils))
+ dashcards)}))
+
+;;; ----------------------------------------------------- alert ----------------------------------------------------
+
+(defn- fetch-notification
+ "Fetch + read-check one notification row of `payload-type` by numeric id. Notifications have
+ no entity_id column, so entity_id strings are a teaching error for these types."
+ [tool-type payload-type id-or-eid]
+ (when-not (int? id-or-eid)
+ (common/throw-teaching-error
+ (format "%ss take a numeric id — they have no entity_id." (str/capitalize tool-type))))
+ (let [notification (mcp.db/notification-by-payload-type id-or-eid payload-type)]
+ (when-not (and notification (mi/can-read? notification))
+ (common/throw-not-found (keyword tool-type) id-or-eid))
+ (projections/notification-row
+ (redaction/hydrate-and-redact-notification notification))))
+
+;;; ------------------------------------------------- subscription -------------------------------------------------
+
+(defn- subscription-pulse-id
+ "Resolve a subscription id argument against the Pulse id space; nil when an entity_id doesn't
+ resolve (the notification source is then tried)."
+ [id-or-eid]
+ (try
+ (v2.resolve/resolve-id-or-404 :model/Pulse id-or-eid)
+ (catch clojure.lang.ExceptionInfo e
+ (when-not (= 404 (:status-code (ex-data e)))
+ (throw e)))))
+
+(defn- fetch-subscription
+ "Dashboard subscriptions are a dual-source read: live Pulse rows (the only kind writes create
+ today) and rows already migrated to the notification API as `payload_type:
+ notification/dashboard`. A Pulse that exists in the pulse id space owns the id — including
+ when the caller cannot read it, which collapses to not-found rather than falling through to
+ an unrelated notification that happens to share the numeric id."
+ [id-or-eid]
+ (let [pulse-id (subscription-pulse-id id-or-eid)]
+ (if (and pulse-id (mcp.db/subscription-pulse-exists? pulse-id))
+ (let [pulse-row (pulse/retrieve-pulse pulse-id)]
+ (if (and pulse-row (mi/can-read? pulse-row))
+ (projections/subscription-row (redaction/redact-pulse pulse-row))
+ (common/throw-not-found :subscription id-or-eid)))
+ (or (when (int? id-or-eid)
+ (let [notification (mcp.db/notification-by-payload-type id-or-eid :notification/dashboard)]
+ (when (and notification (mi/can-read? notification))
+ (projections/notification-row
+ (redaction/hydrate-and-redact-notification notification)))))
+ (common/throw-not-found :subscription id-or-eid)))))
+
+;;; --------------------------------------------------- transform --------------------------------------------------
+
+(defn- fetch-transform
+ [id-or-eid]
+ (let [transform (v2.resolve/resolve-and-read-with :model/Transform id-or-eid
+ (fn [id] (transforms/get-transform id)))]
+ (-> (select-keys transform [:id :name :description :source_type :collection_id :entity_id
+ :source_database_id :target_db_id :run_trigger :creator_id
+ :owner_user_id :owner_email :tag_ids :created_at :updated_at])
+ (assoc :target (:target transform)
+ :last_run (some-> (:last_run transform)
+ (select-keys [:id :status :start_time :end_time :message])
+ u/remove-nils)
+ ;; The target table is hydrated without its own permission check (the transform
+ ;; read-check verifies source tables only), so gate it here.
+ :table (when-let [table (:table transform)]
+ (when (mi/can-read? table)
+ (select-keys table [:id :name :schema :db_id])))
+ ::transform transform))))
+
+(defn- transform-definition
+ "The transform's source: query sources have their query normalized and serialized to the
+ numeric-id MBQL 5 shape; other source types (e.g. python) pass through as stored."
+ [row]
+ (let [source (get-in row [::transform :source])]
+ (if-let [query (:query source)]
+ (let [mp (some-> (:database query) lib-be/application-database-metadata-provider)
+ serialized (some-> (card-query mp query) lib/prepare-for-serialization)]
+ (when serialized
+ (assoc (dissoc source :query) :query serialized)))
+ source)))
+
+(def ^:private transform-concise-keys
+ [:id :name :description :source_type :target :collection_id :last_run])
+
+(def ^:private transform-detailed-keys
+ (into transform-concise-keys
+ [:entity_id :source_database_id :target_db_id :run_trigger :creator_id :owner_user_id
+ :owner_email :tag_ids :table :created_at :updated_at]))
+
+(def ^:private transform-sample
+ (-> (zipmap transform-detailed-keys (repeat "x"))
+ (assoc :target {:type "x" :schema "x" :name "x"}
+ :last_run {:id 1 :status "x" :start_time "x" :end_time "x" :message "x"}
+ :table {:id 1 :name "x" :schema "x" :db_id 1}
+ :tag_ids [1])))
+
+(projections/register-key-projection! :transform transform-concise-keys
+ :detailed-keys transform-detailed-keys
+ :sample transform-sample)
+
+;;; ------------------------------------------------ type dispatch -------------------------------------------------
+
+;;; Include-section builders — each a `(row -> fragment-map-or-nil)`, co-located into `type->spec`
+;;; below so a type declares which sections it supports, and how, in one place.
+
+(defn- definition-include
+ "A `definition` section builder that exports `row`'s query via `export-fn`, omitting the section
+ when there is nothing to export."
+ [export-fn]
+ (fn [row]
+ (when-let [definition (export-fn row)]
+ {:definition definition})))
+
+(def ^:private card-definition-include (definition-include card-definition))
+
+(defn- strip-restricted-fingerprints
+ "Drop `:fingerprint` from any column belonging to a table whose rows the current user only sees
+ part of. A fingerprint is computed over the whole table: `:min` and `:max` are individual cell
+ values, and `:distinct-count` counts every row — so handing one to a sandboxed caller reports
+ data the sandbox exists to hide, and a caller with no data permission at all gets the same
+ numbers. Nothing else in the column metadata is data-derived — names, types, semantic types and
+ field ids are schema, not rows — so only this key moves.
+
+ `row-restricted-table-ids` fails closed, so a table whose restriction can't be resolved is
+ treated as restricted and loses its fingerprints."
+ [columns]
+ (let [restricted (metadata-perms/row-restricted-table-ids
+ (into #{} (keep :table_id) columns))]
+ (cond->> columns
+ (seq restricted) (mapv (fn [col]
+ (cond-> col
+ (contains? restricted (:table_id col)) (dissoc :fingerprint)))))))
+
+(defn- fields-include [row]
+ {:result_metadata (vec (strip-restricted-fingerprints (:result_metadata row)))})
+
+(defn- settings-include
+ "The `visualization_settings` section: the card's stored settings, verbatim and in the shape
+ `question_write` takes back, so a read-modify-write round-trips. The section is named for the
+ property it returns, the name every other surface uses. A card with nothing stored returns `{}`
+ rather than omitting the section — an absent key would read as \"not available\"."
+ [row]
+ {:visualization_settings (or (:visualization_settings row) {})})
+
+(def ^:private type->spec
+ "Per-type dispatch, co-located. Each entry carries the fetch fn (`:fetch`, id-or-eid ->
+ permission-checked row) and the `:includes` sections it supports (section name -> a
+ `(row -> fragment)` builder). `:proj` (the projection key) defaults to `(keyword type)` and is
+ only spelled out when it differs — a model reads with the question projection.
+
+ No entry carries a scope: every type here is gated by the tool's single `agent:content:read`
+ check (see the ns docstring)."
+ {"question" {:fetch #(fetch-card :question %)
+ :includes {"definition" card-definition-include "fields" fields-include
+ "visualization_settings" settings-include}}
+ "model" {:proj :question :fetch #(fetch-card :model %)
+ :includes {"definition" card-definition-include "fields" fields-include
+ "visualization_settings" settings-include}}
+ "metric" {:fetch #(fetch-card :metric %)
+ :includes {"definition" card-definition-include
+ "dimensions" #(dimensions-section :metric %)}}
+ "measure" {:fetch #(fetch-measure-or-segment :model/Measure %)
+ :includes {"definition" (definition-include #(measure-or-segment-definition :measure %))
+ "dimensions" #(dimensions-section :measure %)}}
+ "segment" {:fetch #(fetch-measure-or-segment :model/Segment %)
+ :includes {"definition" (definition-include #(measure-or-segment-definition :segment %))}}
+ "dashboard" {:fetch fetch-dashboard
+ :includes {"parameters" (fn [row] {:parameters (vec (:parameters row))})
+ "layout" (fn [row] {:layout (dashboard-layout row)})}}
+ "document" {:fetch fetch-document
+ :includes {"layout" (fn [row] {:layout (document-layout row)})
+ "comments" document-comments}}
+ "collection" {:fetch fetch-collection}
+ "snippet" {:fetch fetch-snippet}
+ "alert" {:fetch #(fetch-notification "alert" :notification/card %)}
+ "subscription" {:fetch fetch-subscription}
+ "transform" {:fetch fetch-transform
+ :includes {"definition" (definition-include transform-definition)}}})
+
+(def ^:private content-types
+ (vec (sort (keys type->spec))))
+
+(def ^:private include->types
+ "Which types each `include` section applies to — derived from the `:includes` each type declares
+ in [[type->spec]], so the two never drift. A section is applied to each batch item whose type
+ supports it and skipped for the rest, so a mixed-type batch can name a section that only some
+ items have; a section no item in the batch supports is a teaching error."
+ (transduce
+ (mapcat (fn [[type {:keys [includes]}]]
+ (for [inc-name (keys includes)] [inc-name type])))
+ (completing (fn [acc [inc-name type]]
+ (update acc inc-name (fnil conj #{}) type)))
+ {}
+ type->spec))
+
+(defn- check-includes!
+ "Reject an `include` section that no item in the batch can supply — a caller typo, rather than
+ a mixed-type batch where the section legitimately applies to only some items. `batch-types`
+ is the set of item types present in the call."
+ [batch-types includes]
+ (doseq [inc-name includes]
+ (let [applicable (get include->types inc-name)]
+ (when-not (some applicable batch-types)
+ (common/throw-teaching-error
+ (format "`include: \"%s\"` does not apply to type%s %s — it is available for: %s."
+ inc-name
+ (if (= 1 (count batch-types)) "" "s")
+ (str/join ", " (sort batch-types))
+ (str/join ", " (sort applicable))))))))
+
+(defn- build-include
+ "Apply the `inc-name` section builder that `type` declares in [[type->spec]] to `row`, or nil
+ when the type does not support the section (it is simply skipped for that item)."
+ [type row inc-name]
+ (when-let [builder (get-in type->spec [type :includes inc-name])]
+ (builder row)))
+
+;;; -------------------------------------------------- the handler -------------------------------------------------
+
+(defn- content-item-result
+ "Build one batch item's result: its projection (with `include` sections or `fields`
+ narrowing), or the `{type, id, error}` object that keeps a failing item from sinking the
+ rest of the batch. The `error` text is whatever [[common/->mcp-error-content]] judges safe to
+ return, so incidental exceptions collapse to a generic internal error."
+ [{:keys [include] :as args} {:keys [type fields] :as item}]
+ ;; `alert` and `subscription` reject a non-numeric id outright, so an id a client serialized as
+ ;; a string has to be coerced before the fetch rather than inside it (GHY-4498).
+ (let [id (v2.resolve/normalize-id (:id item))]
+ (try
+ (let [{:keys [proj fetch]} (type->spec type)
+ proj (or proj (keyword type))
+ row (fetch id)]
+ (if fields
+ (common/select-fields proj (projections/project proj :detailed row) fields
+ {:response-format (:response_format args)
+ :include include})
+ (let [fmt (common/response-format args)
+ ;; Only the sections this item's type supports; the batch may name sections that
+ ;; apply to other items (check-includes! has already rejected any that no item has).
+ sections (filter #(contains? (get include->types %) type) (distinct include))]
+ (-> (projections/project proj fmt row)
+ (merge (reduce (fn [acc inc-name]
+ (merge acc (build-include type row inc-name)))
+ {}
+ sections))
+ (assoc :type type)))))
+ (catch Exception e
+ ;; Fault isolation must not become a second, unjudged error channel: reuse the tool-level
+ ;; judgment and unwrap its text back into the item's `{type, id, error}` shape.
+ {:type type :id id :error (-> (common/->mcp-error-content e) :content first :text)}))))
+
+(def ^:private get-content-args-schema
+ [:map {:closed true}
+ [:items [:sequential {:min 1 :description "The content to fetch — up to 10 items, mixed types allowed (e.g. a dashboard and its questions in one call)."}
+ [:map {:closed true}
+ [:type (into [:enum {:description "The item's content type, as returned by search/browse_collection."}]
+ content-types)]
+ [:id [:or
+ [:int {:description "Numeric id."}]
+ [:string {:min 1 :description "A 21-character entity_id (alerts and migrated subscriptions are numeric-only)."}]]]
+ [:fields {:optional true}
+ [:maybe [:sequential [:string {:min 1 :description "Dot-paths picked from this type's detailed projection (see the catalog://metabase/fields resource), item-relative inside arrays; a named path with nothing stored comes back null. Mutually exclusive with response_format and include."}]]]]]]]
+ [:include {:optional true}
+ [:maybe [:sequential [:enum {:description "Extra sections, each applied to every item whose type supports it and ignored for the rest — so a mixed-type batch can ask for several at once: definition (query-bearing types, returned as the stored query — numeric ids, the shape execute_query and question_write accept back verbatim), fields (question/model column metadata), visualization_settings (question/model stored chart settings, the shape question_write takes back; {} when nothing is stored), parameters (dashboard's full parameter array), layout (dashboard grid + tabs, document block outline), dimensions (metric/measure), comments (document comment threads, each anchored into the returned content_markdown by {start, end, text} character offsets — the exact slice of the block the thread is attached to; comments attach to whole blocks, a block nested inside a list/blockquote anchors to the span of the nearest enclosing block that has one, and an empty block gives start == end; threads whose block no longer exists come back under orphaned_comments so they can be re-anchored by editing the right block, and if the document read fell back to flattened text no thread carries an anchor). A section no item in the batch supports is an error."}
+ "definition" "fields" "visualization_settings" "parameters" "layout" "dimensions" "comments"]]]]
+ [:response_format {:optional true}
+ [:maybe [:enum {:description "concise (default) returns each type's essential shape; detailed adds entity_id, creator, timestamps, and other secondary columns."}
+ "concise" "detailed"]]]])
+
+(registry/deftool get-content
+ "Fetch content by {type, id} — the typed read for anything found via search or browse_collection. Batch up to 10 items of mixed types; each is permission-checked independently and a bad item returns {type, id, error} without failing the batch. Types: question, model, metric, measure, dashboard, document, collection, snippet, segment, alert, subscription, transform. Ids: numeric or 21-char entity_id. Concise shapes are task-focused: a question carries its source (database id and name, table, source card), display, a one-line query summary — for a native question the head of its query text rather than a placeholder — raw template_tags (in the stored shape question_write accepts back verbatim — read-modify-write round-trips), and materialized parameters (the same tags viewed as parameters, not a second concept); a dashboard returns the editing skeleton (tabs, parameters with wired dashcard ids, one summary row per dashcard with position/size/series/inline parameters), never the raw REST dashcards; a document returns its body text as content_markdown — the same field name document_write takes and returns, so a read-modify-write needs no renaming (a body holding a block with no Markdown form returns content_markdown_unavailable in its place instead: that document cannot be edited or rewritten as Markdown); alerts and subscriptions return condition, schedule, channels, recipients (redacted for non-admins); a transform returns source type, target, latest run. include adds sections on demand — definition returns the stored query (numeric ids), the same shape execute_query and question_write accept, so read-modify-write round-trips; visualization_settings returns a question's or model's stored chart settings, the same property question_write takes back, so a chart can be read back and patched; comments returns a document's threads, each anchored to the exact character range of its block in the returned markdown."
+ {:name "get_content"
+ :scope metabot.scope/agent-content-read
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :args get-content-args-schema}
+ [{:keys [items include] :as args} _]
+ (when (> (count items) max-items)
+ (common/throw-teaching-error
+ (format "`items` accepts at most %d entries per call — you passed %d; split the batch."
+ max-items (count items))))
+ ;; Surface an invalid response_format once, before any item work.
+ (common/response-format args)
+ ;; Reject include sections no item in the batch supports, before any per-item work.
+ (when (seq include)
+ (check-includes! (into #{} (map :type) items) (distinct include)))
+ (common/success-content
+ (json/encode {:results (mapv #(content-item-result args %) items)})))
diff --git a/src/metabase/mcp/v2/tools/dashboard.clj b/src/metabase/mcp/v2/tools/dashboard.clj
new file mode 100644
index 00000000000..ea634ffc3d2
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/dashboard.clj
@@ -0,0 +1,518 @@
+(ns metabase.mcp.v2.tools.dashboard
+ "The v2 MCP `dashboard_write` tool: create and update dashboards, and apply an ordered list of
+ editor operations.
+
+ An update applies its ops as one save. A create does not: it writes the dashboard row, then
+ applies the ops to it. The ops are compiled against a blank dashboard first so a malformed one
+ fails before anything is written, but per-field parameter-mapping permission checks run only on
+ the real save — so that second save can still fail and leave an empty dashboard behind. The tool
+ description says so, since the agent is the one that has to recover.
+
+ A whole dashboard's JSON cannot survive a round trip through model context, so callers send
+ *ops*. This namespace reads current state, hands it to the pure compiler in
+ [[metabase.mcp.v2.dashboard-ops]], and passes the compiled payload to the same domain fns the
+ REST endpoints use ([[metabase.dashboards.write/create-dashboard!]] and
+ [[metabase.dashboards.write/update-dashboard!]]) — so write permission enforcement,
+ transactionality, and event publishing are inherited, never reimplemented."
+ (:require
+ [malli.error :as me]
+ [metabase.dashboards.write :as dashboards.write]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.dashboard-ops :as dashboard-ops]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.redaction :as redaction]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.models.interface :as mi]
+ [metabase.parameters.core :as parameters]
+ [metabase.util :as u]
+ [metabase.util.malli.registry :as mr]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------- Reading ------------------------------------------------------
+
+(defn- fetch-dashboard
+ "The dashboard behind its read check, hydrated for the compiler."
+ [id-or-eid]
+ (-> (v2.resolve/resolve-and-read :model/Dashboard id-or-eid)
+ (t2/hydrate [:dashcards :series :card] :tabs)))
+
+(defn- referenced-card-ids
+ "Every card id the compiled payload may need metadata for: those already on the dashboard, plus
+ any named by an op."
+ [dash ops]
+ (into (set (keep :card_id (:dashcards dash)))
+ ;; `:series` is add_card's series list, `:card_ids` set_series'. Both name cards the
+ ;; projection reads back, so a missed one reaches it as a bare `{:id n}` map.
+ (mapcat (fn [op] (concat [(:card_id op)] (:series op) (:card_ids op))))
+ ops))
+
+(defn- fetch-cards
+ "`{card-id card}` for `ids`, behind read checks. A card the caller cannot read is omitted, so
+ an op referencing it fails with a teaching error rather than leaking its existence."
+ [ids]
+ (let [ids (into #{} (filter int?) ids)]
+ (when (seq ids)
+ (into {} (for [card (mcp.db/select-by-ids :model/Card ids)
+ :when (mi/can-read? card)]
+ [(:id card) card])))))
+
+(defn- check-cards-exist!
+ "Reject an op naming a card the caller cannot read, before any write happens. Covers series
+ cards too: they are placed on the dashboard just as `card_id` is, and leaving them unchecked
+ would both skip the permission boundary and hand the projection a card it never fetched."
+ [ops cards]
+ (doseq [[idx op] (map-indexed vector ops)
+ card-id (concat [(:card_id op)] (:series op) (:card_ids op))
+ :when (and card-id (not (contains? cards card-id)))]
+ (dashboard-ops/op-error!
+ idx (format "%s): no card with id %s that you can read." (:op op) card-id))))
+
+;;; ------------------------------------------------ Response ------------------------------------------------------
+
+(defn- saved-row
+ "The projection row for the dashboard `id`, read back through the same hydration `get_content`
+ uses so both tools return byte-identical shapes."
+ [id]
+ (-> (mcp.db/select-one-by-id :model/Dashboard id)
+ (t2/hydrate [:dashcards :series :card] :tabs)
+ redaction/redact-dashboard
+ projections/dashboard-row))
+
+(defn- attach-card-metadata
+ "Give a compiled dashcard the `:card` and `:series` card rows the projection reads. Compiled
+ rows carry ids only — a new one has never been hydrated, and hydration would fail on its
+ negative id — so the cards already fetched for the ops stand in."
+ [cards dc]
+ (cond-> dc
+ (and (:card_id dc) (nil? (:card dc)))
+ (assoc :card (get cards (:card_id dc)))
+
+ (seq (:series dc))
+ (update :series (partial mapv (fn [s] (or (get cards (:id s)) s))))))
+
+(defn- dry-run-row
+ "The projection row the ops would produce, built without a save. Same builder as [[saved-row]],
+ so a dry run and a real response have the same shape."
+ [dash attrs payload cards]
+ (-> (merge dash attrs payload)
+ (update :dashcards (partial mapv (partial attach-card-metadata cards)))
+ redaction/redact-dashboard
+ projections/dashboard-row))
+
+(defn- normalize-parameters
+ "Coerce the compiled `:parameters` from their JSON shape — string `type`, string enums — to the
+ internal keyword shape the REST endpoint's body decoding produces, so the same payload
+ validates and saves. A value too malformed to normalize passes through untouched and is
+ reported by [[validate-payload!]] instead."
+ [payload]
+ (cond-> payload
+ (seq (:parameters payload))
+ (update :parameters #(try (parameters/normalize-parameters %) (catch Exception _ %)))))
+
+(defn- validate-payload!
+ "Reject a payload the real save would reject, so a dry run is worth trusting."
+ [payload]
+ (when-let [explanation (mr/explain dashboards.write/DashUpdates payload)]
+ (common/throw-teaching-error
+ (format "The requested ops produce an invalid dashboard: %s"
+ (pr-str (me/humanize explanation))))))
+
+;;; ------------------------------------------------- Schema -------------------------------------------------------
+
+(def ^:private position-schema
+ [:map {:closed true :description "Grid slot; omit to autoplace."}
+ [:row [:int {:min 0 :description "Zero-based row."}]]
+ [:col [:int {:min 0 :max 23 :description "Zero-based column; the grid is 24 wide."}]]])
+
+(def ^:private size-schema
+ [:map {:closed true :description "Size in grid cells."}
+ [:size_x [:int {:min 1 :max 24 :description "Width in columns (grid is 24 wide)."}]]
+ [:size_y [:int {:min 1 :description "Height in rows."}]]])
+
+(def ^:private new-id-schema
+ [:int {:max -1
+ :description "Negative id you choose for the new row (-1, -2, …); later ops may reference it."}])
+
+(def ^:private tab-ref-schema
+ [:maybe [:int {:description "Tab id; negative ids from this call work. Omit when the dashboard has no tabs."}]])
+
+(def ^:private inline-parameters-schema
+ [:maybe [:sequential [:string {:description "Parameter id to render on this card, not the header."}]]])
+
+(def ^:private dashcard-ref-schema
+ [:int {:description "Dashcard id; negative ids from this call work."}])
+
+(def ^:private parameter-id-schema
+ [:string {:min 1 :description "Parameter id — a short string you choose and reuse in later ops."}])
+
+;; `add_parameter` and `update_parameter` write REST parameter properties straight through, so the
+;; camelCase names (`isMultiSelect`, `filteringParameters`, `sectionId`) are preserved verbatim.
+(def ^:private parameter-name-schema
+ [:string {:min 1 :description "Label shown on the dashboard."}])
+
+;; `:name` is required on `add_parameter` and optional on `update_parameter`, so it is not in
+;; `parameter-fields` — each op supplies its own entry.
+(def ^:private parameter-fields
+ [[:type {:optional true}
+ [:maybe [:string {:description (str "Parameter type, e.g. \"string/=\", \"string/contains\", "
+ "\"number/=\", \"number/between\", \"date/all-options\", "
+ "\"date/relative\", \"id\", \"temporal-unit\".")}]]]
+ [:sectionId {:optional true}
+ [:maybe [:string {:description "Widget section, e.g. \"string\", \"number\", \"date\", \"id\"."}]]]
+ [:default {:optional true}
+ [:maybe [:any {:description "Default value: a scalar, or an array for multi-select."}]]]
+ [:required {:optional true}
+ [:maybe [:boolean {:description "When true the dashboard needs a value to view; pair with a default."}]]]
+ [:isMultiSelect {:optional true}
+ [:maybe [:boolean {:description "Whether the widget accepts several values."}]]]
+ [:temporal_units {:optional true}
+ [:maybe [:sequential [:string {:description "Allowed unit for a \"temporal-unit\" parameter, e.g. \"month\"."}]]]]
+ [:values_query_type {:optional true}
+ [:maybe [:enum {:description "Value picker behavior: dropdown list, search box, or free text."}
+ "list" "search" "none"]]]
+ [:values_source_type {:optional true}
+ [:maybe [:enum {:description "Picker value source; omit to use the connected field's values."}
+ "static-list" "card"]]]
+ [:values_source_config {:optional true}
+ [:maybe [:map {:description (str "Config for values_source_type: {\"values\": [...]} for "
+ "static-list, or {\"card_id\": n, \"value_field\": target} for card.")}]]]
+ [:filteringParameters {:optional true}
+ [:maybe [:sequential [:string {:description "Id of a parameter whose value narrows this one (linked filter)."}]]]]])
+
+(defn- op-map
+ "One closed op entry for [[op-schema]]: the `op` discriminator plus `fields`."
+ [op-name description fields]
+ [op-name
+ (into [:map {:closed true :description description}
+ [:op [:= op-name]]]
+ fields)])
+
+(def ^:private op-schema
+ [:multi {:dispatch :op
+ :description "One editor operation; `op` selects which."}
+ (op-map "add_card" "Place a saved question, model, or metric on the dashboard."
+ [[:id new-id-schema]
+ [:card_id [:int {:description "Numeric id of the saved question, model, or metric to place."}]]
+ [:tab {:optional true} tab-ref-schema]
+ [:position {:optional true} [:maybe position-schema]]
+ [:size {:optional true} [:maybe size-schema]]
+ [:series {:optional true}
+ [:maybe [:sequential [:int {:description "Numeric id of a card to overlay on this one as an extra series."}]]]]
+ [:inline_parameters {:optional true} inline-parameters-schema]])
+ (op-map "add_text" "Add a markdown text card."
+ [[:id new-id-schema]
+ [:markdown [:string {:description "Markdown body of the text card."}]]
+ [:tab {:optional true} tab-ref-schema]
+ [:position {:optional true} [:maybe position-schema]]
+ [:size {:optional true} [:maybe size-schema]]
+ [:inline_parameters {:optional true} inline-parameters-schema]])
+ (op-map "add_heading" "Add a section heading — a full-width label with no card background."
+ [[:id new-id-schema]
+ [:text [:string {:description "Heading text; plain text, not markdown."}]]
+ [:tab {:optional true} tab-ref-schema]
+ [:position {:optional true} [:maybe position-schema]]
+ [:size {:optional true} [:maybe size-schema]]
+ [:inline_parameters {:optional true} inline-parameters-schema]])
+ (op-map "add_link" "Add a link card. Pass exactly one of `url` or `entity`."
+ [[:id new-id-schema]
+ [:url {:optional true} [:maybe [:string {:description "External URL to link to."}]]]
+ [:entity {:optional true}
+ [:maybe [:map {:closed true :description "A Metabase entity to link to, instead of `url`."}
+ [:type [:enum {:description "Kind of entity being linked."}
+ "dashboard" "card" "dataset" "collection" "database" "table"]]
+ [:id [:int {:description "Numeric id of that entity."}]]]]]
+ [:tab {:optional true} tab-ref-schema]
+ [:position {:optional true} [:maybe position-schema]]
+ [:size {:optional true} [:maybe size-schema]]
+ [:inline_parameters {:optional true} inline-parameters-schema]])
+ (op-map "add_iframe" "Embed an external page. The host must be allowed by the instance's iframe settings."
+ [[:id new-id-schema]
+ [:src [:string {:description "URL to embed, or a full <iframe> tag."}]]
+ [:tab {:optional true} tab-ref-schema]
+ [:position {:optional true} [:maybe position-schema]]
+ [:size {:optional true} [:maybe size-schema]]
+ [:inline_parameters {:optional true} inline-parameters-schema]])
+ (op-map "add_action" "Add a button that runs a saved action."
+ [[:id new-id-schema]
+ [:action_id [:int {:description "Numeric id of the saved action to run."}]]
+ [:label {:optional true} [:maybe [:string {:description "Button text. Defaults to the action's own name."}]]]
+ [:display {:optional true}
+ [:maybe [:enum {:description "\"button\" (default) runs on click; \"form\" renders the action's fields inline."}
+ "button" "form"]]]
+ [:tab {:optional true} tab-ref-schema]
+ [:position {:optional true} [:maybe position-schema]]
+ [:size {:optional true} [:maybe size-schema]]])
+ (op-map "duplicate_card"
+ (str "Copy a dashcard with its card, visualization settings, and parameter mappings; "
+ "same size, its own slot.")
+ [[:id new-id-schema]
+ [:dashcard_id dashcard-ref-schema]
+ [:tab {:optional true} tab-ref-schema]
+ [:position {:optional true} [:maybe position-schema]]])
+ (op-map "replace_card"
+ (str "Point a dashcard at a different card, keeping slot and size; series, parameter "
+ "mappings, and visualization settings reset, as the editor does.")
+ [[:dashcard_id dashcard-ref-schema]
+ [:card_id [:int {:description "Numeric id of the card to show instead."}]]])
+ (op-map "move" "Move a dashcard to a different slot, a different tab, or both."
+ [[:dashcard_id dashcard-ref-schema]
+ [:tab {:optional true} tab-ref-schema]
+ [:position {:optional true} [:maybe position-schema]]])
+ (op-map "resize" "Resize a dashcard in place."
+ [[:dashcard_id dashcard-ref-schema]
+ [:size size-schema]])
+ (op-map "remove" "Delete a dashcard from the dashboard. The underlying card is untouched."
+ [[:dashcard_id dashcard-ref-schema]])
+ (op-map "set_series"
+ "Replace a dashcard's overlaid series with this ordered list; pass an empty list to clear them."
+ [[:dashcard_id dashcard-ref-schema]
+ [:card_ids [:sequential [:int {:description "Numeric id of a card to overlay, in draw order."}]]]])
+ (op-map "patch_dashcard"
+ (str "Merge content settings into a dashcard — visualization settings, click behavior, "
+ "column settings, a link card's target. Layout/identity keys (row, col, size_x, "
+ "size_y, dashboard_tab_id, card_id, action_id, series, id) are rejected; use move, "
+ "resize, replace_card, or set_series.")
+ [[:dashcard_id dashcard-ref-schema]
+ [:patch [:map {:description (str "Dashcard properties to merge; `visualization_settings` "
+ "merges key by key rather than replacing the map.")}]]])
+ (op-map "add_tab" (str "Add a tab. Existing cards are adopted only when the save ends with "
+ "exactly one tab; adding several at once leaves them orphaned — `move` "
+ "them onto a tab in the same call.")
+ [[:id new-id-schema]
+ [:name [:string {:min 1 :description "Tab label."}]]])
+ (op-map "rename_tab" "Rename an existing tab."
+ [[:tab_id [:int {:description "Id of the tab to rename (negative ids from this call work)."}]]
+ [:name [:string {:min 1 :description "New tab label."}]]])
+ (op-map "move_tab" "Reorder the tab strip by moving one tab to a new position."
+ [[:tab_id [:int {:description "Id of the tab to move."}]]
+ [:index [:int {:min 0 :description "Zero-based position to move it to, counting the other tabs only."}]]])
+ (op-map "duplicate_tab" "Copy a tab and every card on it."
+ [[:id new-id-schema]
+ [:tab_id [:int {:description "Id of the tab to copy."}]]])
+ (op-map "remove_tab" "Delete a tab and every card on it."
+ [[:tab_id [:int {:description "Id of the tab to delete."}]]])
+ (op-map "add_parameter"
+ (str "Add a filter or parameter widget to the dashboard. It does nothing until "
+ "`wire_parameter` connects it to at least one card.")
+ (into [[:parameter_id parameter-id-schema]
+ [:name parameter-name-schema]]
+ parameter-fields))
+ (op-map "update_parameter"
+ (str "Change properties of an existing parameter. Only the properties you pass change; "
+ "the rest are left alone. Passing null does not clear a property — it is treated as "
+ "omitted — so to remove one, name it in `clear`.")
+ (into [[:parameter_id parameter-id-schema]
+ [:name {:optional true} [:maybe parameter-name-schema]]
+ [:clear {:optional true}
+ [:maybe [:sequential
+ [:enum {:description (str "Property names to remove from this parameter "
+ "(default, filteringParameters, "
+ "values_source_config, values_source_type, "
+ "sectionId, temporal_units). Null cannot say this: "
+ "strict clients fill every unset property with "
+ "null, so nulls are treated as omitted.")}
+ "default" "filteringParameters" "values_source_config"
+ "values_source_type" "sectionId" "temporal_units"]]]]]
+ parameter-fields))
+ (op-map "remove_parameter"
+ (str "Delete a parameter with its card mappings, inline placements, and linked-filter "
+ "references; dependent subscriptions are archived and their owners emailed.")
+ [[:parameter_id parameter-id-schema]])
+ (op-map "move_parameter" "Reorder a parameter in the header, or move it onto a card. Pass exactly one of `index` or `dashcard_id`."
+ [[:parameter_id parameter-id-schema]
+ [:index {:optional true}
+ [:maybe [:int {:min 0 :description "Zero-based position in the header, counting the other parameters only."}]]]
+ [:dashcard_id {:optional true}
+ [:maybe [:int {:description "Render the parameter on this dashcard instead of in the header."}]]]])
+ (op-map "wire_parameter"
+ (str "Connect a parameter to a card so the widget actually filters it. Pass exactly one "
+ "of `target_field`, `target_tag`, or `target`.")
+ [[:parameter_id parameter-id-schema]
+ [:dashcard_id dashcard-ref-schema]
+ [:target_field {:optional true}
+ [:maybe [:int {:description (str "Numeric field id to filter on — the usual choice; the "
+ "server derives the mapping from the card's query.")}]]]
+ [:target_tag {:optional true}
+ [:maybe [:string {:description (str "Template tag name on a native-SQL card; the server "
+ "derives the mapping from the tag's type (field filter "
+ "vs raw variable).")}]]]
+ [:target {:optional true}
+ [:maybe [:sequential [:any {:description (str "Raw mapping-target clause, e.g. "
+ "[\"dimension\", [\"template-tag\", \"category\"]] or "
+ "[\"text-tag\", \"name\"] for a {{name}} placeholder in a "
+ "text/heading/iframe card. Advanced; prefer target_field.")}]]]]
+ [:autowire {:optional true}
+ [:maybe [:boolean {:description (str "With target_field, also map every other card exposing "
+ "the same field; cards that don't are skipped silently.")}]]]])
+ (op-map "unwire_parameter" "Disconnect a parameter from one card, or from every card when `dashcard_id` is omitted."
+ [[:parameter_id parameter-id-schema]
+ [:dashcard_id {:optional true}
+ [:maybe [:int {:description "Dashcard to disconnect. Omit to disconnect the parameter everywhere."}]]]])])
+
+(def ^:private dashboard-write-args-schema
+ [:map {:closed true}
+ [:method
+ [:enum {:description (str "\"create\" makes a new dashboard (requires `name`); "
+ "\"update\" edits the one named by `id`.")}
+ "create" "update"]]
+ [:id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the dashboard to update."}]
+ [:string {:description "21-character entity_id of the dashboard to update."}]]]]
+ [:name {:optional true} [:maybe [:string {:min 1 :description "Dashboard title."}]]]
+ [:description {:optional true} [:maybe [:string {:description "One or two sentences on what the dashboard answers."}]]]
+ [:collection_id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the collection to put it in. Omit on create for your personal collection."}]
+ [:string {:description "Collection entity_id, or \"root\" for the top-level collection."}]]]]
+ [:collection_position {:optional true}
+ [:maybe [:int {:min 1 :description "Pin position within the collection; omit to leave it unpinned."}]]]
+ [:width {:optional true}
+ [:maybe [:enum {:description "\"fixed\" (default) centers the grid; \"full\" stretches it to the browser width."}
+ "fixed" "full"]]]
+ [:auto_apply_filters {:optional true}
+ [:maybe [:boolean {:description "When false, filter changes wait for the viewer to press Apply. Default true."}]]]
+ [:cache_ttl {:optional true} [:maybe [:int {:min 1 :description "Cache lifetime for this dashboard's results, in hours."}]]]
+ [:archived {:optional true}
+ [:maybe [:boolean {:description (str "Update only: true moves it to the trash, false restores it. "
+ "Archiving is the only removal path — there is no hard delete.")}]]]
+ [:validate_only {:optional true}
+ [:maybe [:boolean {:description "Dry run: returns the layout the ops would produce, writing nothing."}]]]
+ [:clear {:optional true}
+ [:maybe [:sequential [:enum {:description "Update only: property names to unset (description, collection_position, cache_ttl). Needed because a null cannot say \"clear this\" — strict clients fill every unset property with null, so nulls are stripped at the boundary."}
+ "description" "collection_position" "cache_ttl"]]]]
+ [:ops {:optional true}
+ [:maybe [:sequential {:description (str "Editor operations, applied in order. One atomic save on update; on "
+ "create the dashboard row is written before the ops are applied.")}
+ op-schema]]]])
+
+(def ^:private dashboard-write-entry
+ {:create-required [:name]
+ :clearable #{:description :collection_position :cache_ttl}})
+
+;;; ------------------------------------------------- Handler ------------------------------------------------------
+
+(def ^:private attribute-keys
+ [:name :description :collection_id :collection_position :width :auto_apply_filters :cache_ttl :archived])
+
+(defn- dashboard-attrs
+ "The dashboard-level attributes in `body`, with `collection_id` resolved through the v2
+ collection-reference convention."
+ [body]
+ (cond-> (select-keys body attribute-keys)
+ (contains? body :collection_id)
+ (assoc :collection_id (v2.resolve/resolve-collection-id (:collection_id body)))))
+
+(defn- create-attrs
+ "[[dashboard-attrs]] for the create path, where an omitted `collection_id` means the caller's
+ personal collection rather than the root collection."
+ [body]
+ (assoc (dashboard-attrs body)
+ :collection_id (v2.resolve/resolve-collection-id-or-personal (:collection_id body))))
+
+(defn- compact-op
+ "Strip null-valued keys from one op. Strict MCP clients send every declared property, filling
+ the ones they do not set with null; the ops that distinguish absent from null — `move` and
+ `duplicate_card` on `tab`, `move_parameter` on `index`/`dashcard_id`, `unwire_parameter` on
+ `dashcard_id` — would otherwise read a filled-in null as a deliberate value."
+ [op]
+ (into {} (remove (comp nil? val)) op))
+
+(defn- apply-ops!
+ "Compile `ops` against `dash` and save, returning the projection row. With `validate-only?` the
+ would-be row is built from the compiled payload instead and nothing is written."
+ [dash ops attrs validate-only?]
+ (let [ops (mapv compact-op ops)
+ cards (fetch-cards (referenced-card-ids dash ops))
+ _ (check-cards-exist! ops cards)
+ payload (normalize-parameters (dashboard-ops/compile-ops dash ops cards))]
+ (validate-payload! (merge attrs payload))
+ (if validate-only?
+ (dry-run-row dash attrs payload cards)
+ (saved-row (:id (dashboards.write/update-dashboard! (u/the-id dash) (merge attrs payload)))))))
+
+(defn- blank-dashboard
+ "The empty dashboard a `validate_only` create compiles against, so a dry run writes nothing at
+ all — not even the dashboard row."
+ [attrs]
+ (merge {:id nil :dashcards [] :tabs [] :parameters []} attrs))
+
+(registry/deftool dashboard-write
+ "Create or update a dashboard and edit its layout with ordered ops. On update the ops are one atomic save —
+ nothing is written unless every op succeeds, so a failed call leaves the dashboard untouched and a retry
+ cannot double-add. Create is not atomic: the dashboard row is written first and the ops applied second, so a
+ failure on that second save leaves an empty dashboard behind (the ops are compiled beforehand, but per-field
+ parameter-mapping permission checks run only on the real save). Find it by name and finish it with method
+ \"update\" — calling create again leaves a second one.
+ method: \"create\" requires name; \"update\" requires id and accepts archived (true trashes,
+ false restores — there is no hard delete). Give each new card or tab its own negative id (-1, -2, …); later
+ ops in the same call reference it, and the server assigns real ids on save. Ops: add_card, add_text,
+ add_heading, add_link, add_iframe, add_action, duplicate_card, replace_card, move, resize, remove,
+ set_series, patch_dashcard, add_tab, rename_tab, move_tab, duplicate_tab, remove_tab, add_parameter,
+ update_parameter, remove_parameter, move_parameter, wire_parameter, unwire_parameter. Before your first
+ add_parameter or wire_parameter, read learn(\"dashboard-filters\") unless already loaded — parameter types,
+ target grammar, linked filters, value sources; learn(\"dashboard-layout\") covers the 24-column grid,
+ per-display default sizes, and layout conventions. validate_only: true returns the layout the ops would
+ produce without writing — but per-field parameter-mapping permission checks run only on the real save, so a
+ clean dry run can still be rejected. Returns the resulting dashboard, so no follow-up read is needed.
+ Requires write permission on the dashboard and read permission on every referenced card."
+ {:name "dashboard_write"
+ :scope metabot.scope/agent-content-write
+ ;; `archived: true` trashes the dashboard, and `remove`/`remove_tab`/`remove_parameter` drop
+ ;; cards, tabs, and subscriptions — not the additive-only update `destructiveHint false`
+ ;; would assert.
+ :annotations {:readOnlyHint false :destructiveHint true}
+ :args dashboard-write-args-schema}
+ [args {:keys [token-scopes]}]
+ (let [dispatched (v2.write/dispatch-write dashboard-write-entry args)]
+ (common/success-content
+ (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (projections/project
+ :dashboard :concise
+ (case (first dispatched)
+ :create
+ (let [[_ body] dispatched
+ attrs (create-attrs body)
+ ops (:ops body)
+ validate-only? (boolean (:validate_only body))]
+ (when (contains? body :archived)
+ (common/throw-teaching-error
+ "`archived` applies to method \"update\" only — remove it from this create call."))
+ (cond
+ validate-only? (apply-ops! (blank-dashboard attrs) (or ops []) attrs true)
+ (seq ops) (do
+ ;; Compile before creating anything, so a bad op can't leave an
+ ;; orphaned empty dashboard behind for a retry to duplicate. A new
+ ;; dashboard is empty by definition, so compiling against a blank
+ ;; checks everything the post-create compile would.
+ (apply-ops! (blank-dashboard attrs) ops attrs true)
+ ;; ...and the two writes share a transaction, because the compile
+ ;; above only proves the OPS are good. Anything else that throws
+ ;; after the row exists — a schema check, a permission check, a
+ ;; failing save — would otherwise strand an empty dashboard that
+ ;; the tool's own advice ("find it by name and finish it with
+ ;; update") turns into a pile of them on retry (GHY-4501).
+ (t2/with-transaction [_conn]
+ (apply-ops! (t2/hydrate (dashboards.write/create-dashboard! attrs)
+ [:dashcards :series :card] :tabs)
+ ops {} false)))
+ :else (saved-row (:id (dashboards.write/create-dashboard! attrs)))))
+
+ :update
+ (let [[_ id body] dispatched
+ dash (fetch-dashboard id)
+ attrs (dashboard-attrs body)
+ ops (:ops body)
+ validate-only? (boolean (:validate_only body))]
+ (cond
+ (seq ops) (apply-ops! dash ops attrs validate-only?)
+ validate-only? (do (validate-payload! attrs)
+ (dry-run-row dash attrs nil nil))
+ :else (saved-row (:id (dashboards.write/update-dashboard! (:id dash) attrs)))))))
+ nil))))
diff --git a/src/metabase/mcp/v2/tools/definitions.clj b/src/metabase/mcp/v2/tools/definitions.clj
new file mode 100644
index 00000000000..ec96323121c
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/definitions.clj
@@ -0,0 +1,431 @@
+(ns metabase.mcp.v2.tools.definitions
+ "The v2 MCP `segment_write` and `measure_write` tools: authoring for the two table-attached
+ MBQL macros. Both call the same domain create/update fns the REST endpoints use
+ ([[metabase.segments.api]]/[[metabase.measures.api]]), so permission enforcement — superuser
+ OR data-analyst-with-unrestricted-view-data on the table, plus the table's remote-sync
+ editability — is inherited, never reimplemented. The tools' own work is id resolution behind
+ read checks, definition-shape handling (the bare clause form `get_content` returns, full
+ MBQL 5 queries, and MBQL 4 auto-convert for segments), and translating the model layer's
+ raw validation exceptions into teaching errors."
+ (:require
+ [clojure.string :as str]
+ [medley.core :as m]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]))
+
+(set! *warn-on-reflection* true)
+
+;; segments.api / measures.api are reached through `requiring-resolve` rather than a static
+;; `:require`. A static require would form an `mcp -> segments`/`-> measures` module `:uses` edge,
+;; and since `mcp` sits upstream of `query-processor`/`driver`, that edge drags the whole
+;; segments↔xrays / measures closure into the driver-test-triggering set (the mage module-graph
+;; ratchet). Resolving the modules' public `:api` write fns at call time keeps `mcp` a consumer of
+;; the *models*, not the *modules*. The target is built with `symbol` (not a quoted literal) so the
+;; namespace stays opaque to the static dependency analysis that derives module `:uses`.
+#_{:clj-kondo/ignore [:metabase/modules]}
+(defn- api-fn [ns-name fn-name] (requiring-resolve (symbol ns-name fn-name)))
+
+(defn- create-segment! [body] ((api-fn "metabase.segments.api" "create-segment!") body))
+(defn- update-segment! [id body] ((api-fn "metabase.segments.api" "write-check-and-update-segment!") id body))
+(defn- create-measure! [body] ((api-fn "metabase.measures.api" "create-measure!") body))
+(defn- update-measure! [id body] ((api-fn "metabase.measures.api" "write-check-and-update-measure!") id body))
+
+;;; ------------------------------------------------ Shared plumbing -----------------------------------------------
+
+(defn- write-result
+ "The created/updated row echoed to the caller: `kind`'s concise read projection — so the echo
+ and a concise get_content read carry the same identity fields by construction — plus
+ `:entity_id` (a portable id to update by) and `:definition`, the stored MBQL 5 shape, so the
+ caller sees the result of any input conversion. The concise projection already drops its own
+ nil-valued keys, so an unset description is omitted rather than echoed as null."
+ [row kind]
+ ;; The :segment/:measure projections are registered by metabase.mcp.v2.tools.content, which
+ ;; metabase.mcp.v2.api loads alongside this ns — so the registry is populated before any tool
+ ;; dispatch reaches here.
+ (cond-> (assoc (projections/project kind :concise row) :entity_id (:entity_id row))
+ (:definition row) (assoc :definition (lib/prepare-for-serialization (:definition row)))))
+
+(defn- resolve-table
+ "Resolve a numeric `table_id` behind the table's read check. \"Doesn't exist\" and \"exists but
+ not readable\" collapse into the same not-found error."
+ [table-id]
+ (v2.resolve/resolve-and-read :model/Table table-id))
+
+(defn- resolve-existing
+ "Resolve an update's `id` (numeric or entity_id) to the row behind `model`'s read check, with
+ the same not-found collapse as [[resolve-table]]. The domain update fn still runs its own
+ write check."
+ [model id-or-eid]
+ (v2.resolve/resolve-and-read model id-or-eid))
+
+(defn- check-method-args!
+ "Reject arguments that don't apply to the dispatched method, so a caller never believes an
+ ignored field took effect."
+ [method args]
+ (case method
+ :create (doseq [k [:id :archived :revision_message]]
+ (when (contains? args k)
+ (common/throw-teaching-error
+ (format "`%s` applies to method \"update\" only — remove it from this create call." (name k)))))
+ :update (when (contains? args :table_id)
+ (common/throw-teaching-error
+ "`table_id` cannot be changed on update — the server derives it from `definition`'s source table."))))
+
+(defn- check-name!
+ "Reject a present-but-blank `name`. The REST endpoints these tools delegate to take
+ `ms/NonBlankString`; the tools' own JSON schema can only say `:min 1`, which \" \" satisfies, so
+ without this the tools would be laxer than the endpoints whose checks they inherit."
+ [{entity-name :name} entity]
+ (when (and (some? entity-name) (str/blank? entity-name))
+ (common/throw-teaching-error
+ (format "`name` cannot be blank — pass a short descriptive name for the %s." entity))))
+
+(defn- check-revision-message!
+ [{:keys [revision_message]} entity]
+ (when (str/blank? revision_message)
+ (common/throw-teaching-error
+ (format (str "`revision_message` is required when method is \"update\" — pass a short sentence describing "
+ "the change; it is recorded in the %s's revision history.")
+ entity))))
+
+;;; --------------------------------------------- Definition handling ----------------------------------------------
+
+(defn- wrap-mbql4-fragment
+ "Inject the tool's `table` into a bare MBQL 4 fragment (a map with no full-query shape, e.g.
+ `{:filter [...]}`) by wrapping it in a legacy full query, so `create-segment!` can derive a
+ source table from a fragment that names none — the segment REST endpoint takes no `table_id`
+ and 400s on such a fragment. Full queries (MBQL 5 or legacy) pass through unchanged. This is
+ not what converts MBQL 4 to MBQL 5: the segment model's before-insert normalizes any MBQL 4
+ definition on store, and would convert an unwrapped fragment identically. A fragment's own
+ `:source-table` wins over `table`, matching that same model merge."
+ [definition {table-id :id, db-id :db_id}]
+ (case (lib/normalized-mbql-version definition)
+ (:mbql-version/mbql5 :mbql-version/legacy) definition
+ {:database db-id
+ :type :query
+ :query (merge {:source-table table-id} definition)}))
+
+(defn- accepted-shapes
+ "The sentence every definition-shape teaching error ends with, naming both accepted shapes."
+ [kind]
+ (case kind
+ :segment (str "`definition` accepts either the bare clause form — the array of filter clauses get_content's "
+ "\"definition\" include returns for a segment, reassembled onto `table_id` — or a full "
+ "single-stage query holding only filters.")
+ :measure (str "`definition` accepts either the bare clause form — the aggregation clause get_content's "
+ "\"definition\" include returns for a measure, as the one-element array or the bare clause, "
+ "reassembled onto `table_id` — or a full single-stage query holding exactly one "
+ "aggregation.")))
+
+(defn- check-normalizable!
+ "Probe `definition` against strict MBQL normalization before handing it to the domain layer.
+ The models normalize non-strictly, where an unparseable definition silently degrades to `{}`
+ and would be stored as an empty definition; failing here turns that silent data loss into a
+ teaching error."
+ [kind definition]
+ (try
+ (lib-be/normalize-query nil definition {:strict? true})
+ (catch Exception e
+ (common/throw-teaching-error
+ (format "`definition` is not a valid MBQL query: %s %s"
+ (common/ellipsize (ex-message e) 300) (accepted-shapes kind))))))
+
+;; measure_write is deliberately MBQL-5-only, stricter than POST /api/measure — that endpoint's
+;; schema still decodes legacy MBQL, but that is a back-compatibility affordance, not an agent path
+;; (agents author MBQL 5 from execute_query / get_content). Keeping the narrower contract here
+;; teaches the model the one dialect it should speak.
+(defn- require-mbql5-definition!
+ [definition]
+ (when-not (= :mbql-version/mbql5 (lib/normalized-mbql-version definition))
+ (common/throw-teaching-error
+ (str "A full-query `definition` must be a map with "
+ "\"lib/type\": \"mbql/query\", \"database\", and one entry in \"stages\". "
+ (accepted-shapes :measure)))))
+
+(defn- clause-form->definition
+ "Reassemble the bare clause form onto `table` and resolve it. The clause form names no source of
+ its own, so `table` — `table_id` on create, the row's own table on update — is what makes it a
+ query at all. A caller may pass the array get_content returns or a single bare clause; a clause
+ is distinguished from an array of clauses by its string head."
+ [kind definition table]
+ (let [clauses (if (string? (first definition)) [definition] (vec definition))]
+ (v2.queries/resolve-external-query
+ {:lib/type "mbql/query"
+ :stages [(assoc {:lib/type "mbql.stage/mbql"
+ :source-table (:id table)}
+ (case kind :segment :filters :measure :aggregation)
+ clauses)]}
+ (accepted-shapes kind))))
+
+(defn- prepare-definition
+ "Resolve a caller-supplied `definition` into the MBQL 5 query the domain layer stores, accepting
+ both the bare clause form (reassembled onto `table`) and a full single-stage query. Throws a
+ teaching error naming both shapes when neither resolves."
+ [kind definition table]
+ (cond
+ (sequential? definition)
+ (clause-form->definition kind definition table)
+
+ (v2.queries/portable-query? definition)
+ (v2.queries/resolve-external-query definition (accepted-shapes kind))
+
+ :else
+ (case kind
+ :segment (let [wrapped (wrap-mbql4-fragment definition table)]
+ (check-normalizable! kind wrapped)
+ wrapped)
+ :measure (do (require-mbql5-definition! definition)
+ (check-normalizable! kind definition)
+ definition))))
+
+(defn- check-table-match!
+ "On create, `table_id` is an explicit argument and a full-query `definition` also names its own
+ source table; when they disagree, fail loud rather than silently storing on the definition's
+ table (the `table_id` read check would also have been on the wrong table). The clause form is
+ built on `table`, so its source always matches and this never trips. Runs after
+ [[prepare-definition]], so the definition is already known to normalize."
+ [table definition]
+ (when-let [defn-table-id (lib/primary-source-table-id (lib-be/normalize-query definition))]
+ (when (not= defn-table-id (:id table))
+ (common/throw-teaching-error
+ (format (str "`table_id` (%d) and `definition`'s source table (%d) must be the same table. "
+ "Pass table_id %d, or point `definition` at table %d.")
+ (:id table) defn-table-id defn-table-id (:id table))))))
+
+;;; ---------------------------------------------- Error translation -----------------------------------------------
+
+(defn- humanized-messages
+ [x]
+ (cond
+ (map? x) (mapcat humanized-messages (vals x))
+ (sequential? x) (mapcat humanized-messages x)
+ (string? x) [x]
+ :else []))
+
+(defn- custom-messages
+ "The `:error/message` strings schema authors wrote (surfaced by malli under `:malli/error`) —
+ e.g. \"A segment must have exactly one stage\" — which teach far better than the generic
+ per-key output around them."
+ [x]
+ (cond
+ (map? x) (concat (humanized-messages (:malli/error x))
+ (mapcat custom-messages (vals (dissoc x :malli/error))))
+ (sequential? x) (mapcat custom-messages x)
+ :else []))
+
+(defn- schema-error-summary
+ [humanized]
+ (->> (or (seq (distinct (custom-messages humanized)))
+ (distinct (humanized-messages humanized)))
+ (take 3)
+ (map #(common/ellipsize % 200))
+ (str/join "; ")))
+
+(defn- run-domain-write
+ "Call `thunk` (a domain create/update fn), translating the model layer's raw validation
+ exceptions into teaching errors: Malli shape failures from `mu/validate-throw` (disallowed
+ clauses, stage-count and aggregation-count rules) and the lib cycle/existence checks, none
+ of which carry a client-facing status code of their own. Exceptions that do carry one pass
+ through untouched, and anything unrecognized stays an internal error."
+ [thunk]
+ (try
+ (thunk)
+ (catch clojure.lang.ExceptionInfo e
+ (let [data (ex-data e)]
+ (cond
+ (:status-code data)
+ (throw e)
+
+ ;; mu/validate-throw: pre-humanized malli explain output under :error
+ (and (:error data) (= (ex-message e) "Value does not match schema"))
+ (common/throw-teaching-error
+ (format "Invalid `definition`: %s." (schema-error-summary (:error data))))
+
+ ;; lib cycle detection and referenced-id existence checks
+ (or (contains? data :cycle-path)
+ (contains? data :segment-id)
+ (contains? data :measure-id))
+ (common/throw-teaching-error (ex-message e))
+
+ :else
+ (throw e))))))
+
+;;; -------------------------------------------------- Schemas -----------------------------------------------------
+
+(defn- write-args-schema
+ [{:keys [entity definition-desc name-desc]}]
+ [:map {:closed true}
+ [:method
+ [:enum {:description (format (str "\"create\" makes a new %s (requires `table_id`, `name`, `definition`); "
+ "\"update\" edits the one named by `id` (requires `revision_message`).")
+ entity)}
+ "create" "update"]]
+ [:id {:optional true}
+ [:maybe [:or
+ [:int {:description (format "Numeric id of the %s to update." entity)}]
+ [:string {:description (format "21-character entity_id of the %s to update." entity)}]]]]
+ [:table_id {:optional true}
+ [:maybe [:int {:description (str "Create only: numeric table id (tables have no entity_ids). A bare-clause "
+ "`definition` is reassembled into a query on this table; a full-query one "
+ "must name this same source table — a mismatch is a teaching error, not "
+ "silently reconciled.")}]]]
+ [:name {:optional true}
+ [:maybe [:string {:min 1 :description name-desc}]]]
+ [:definition {:optional true}
+ [:maybe [:or {:description definition-desc}
+ [:map]
+ [:sequential :any]]]]
+ [:description {:optional true}
+ [:maybe [:string {:description "Optional human-readable description."}]]]
+ [:archived {:optional true}
+ [:maybe [:boolean {:description (str "Update only: true moves it to the trash, false restores it. Archiving is "
+ "the only removal path — there is no hard delete.")}]]]
+ [:revision_message {:optional true}
+ [:maybe [:string {:min 1 :description (str "Update only, required: a short sentence describing the change, "
+ "recorded in the revision history.")}]]]
+ [:clear {:optional true}
+ [:maybe [:sequential [:enum {:description (str "Update only: property names to unset (description). Needed "
+ "because a null cannot say \"clear this\" — strict clients fill "
+ "every unset property with null, so nulls are stripped at the "
+ "boundary.")}
+ "description"]]]]])
+
+;;; ------------------------------------------------ segment_write -------------------------------------------------
+
+(def ^:private segment-write-args-schema
+ (write-args-schema
+ {:entity "segment"
+ :name-desc "Create only (editable on update): display name of the segment."
+ :definition-desc (str "Either (a) an array of filter clauses — what get_content's "
+ "\"definition\" include returns for a segment and what execute_query takes in "
+ "stages[0].filters — reassembled onto `table_id`; or (b) a full single-stage query. "
+ "Filters only: no aggregations, breakouts, joins, expressions, or limits. May "
+ "reference other segments; cycles are rejected.")}))
+
+(def ^:private segment-write-entry
+ {:create-required [:table_id :name :definition]
+ :clearable #{:description}})
+
+(registry/deftool segment-write
+ "Create or update a segment: a named, reusable MBQL filter attached to one table, referenced from other queries'
+ filters. method: \"create\" requires table_id, name, definition; \"update\" requires id and revision_message and
+ accepts name, description, definition, archived (true trashes, false restores — no hard delete). definition holds
+ only filters, in either shape: the array of filter clauses get_content's \"definition\" include returns for a
+ segment (the same clauses execute_query takes in stages[0].filters), reassembled onto table_id; or a full
+ single-stage query. For a full query table_id must name the definition's own source table; a mismatch is
+ a teaching error. Not admin-only: writing requires superuser OR a data analyst with unrestricted view-data on the
+ table, and the table must not live in a read-only remote-synced collection."
+ {:name "segment_write"
+ :scope metabot.scope/agent-content-write
+ ;; `archived: true` trashes the segment, so this is not the additive-only update
+ ;; `destructiveHint false` would assert.
+ :annotations {:readOnlyHint false :destructiveHint true}
+ :args segment-write-args-schema}
+ [args {:keys [token-scopes]}]
+ (let [dispatched (v2.write/dispatch-write segment-write-entry args)]
+ (case (first dispatched)
+ :create
+ (let [[_ body] dispatched
+ _ (check-method-args! :create body)
+ _ (check-name! body "segment")
+ table (resolve-table (:table_id body))
+ definition (prepare-definition :segment (:definition body) table)
+ _ (check-table-match! table definition)]
+ (-> (run-domain-write #(create-segment! {:name (:name body)
+ :description (:description body)
+ :definition definition}))
+ (write-result :segment)
+ (as-> row (v2.write/readback token-scopes [metabot.scope/agent-content-read] row nil))
+ common/success-content))
+
+ :update
+ (let [[_ id body] dispatched
+ _ (check-method-args! :update body)
+ _ (check-name! body "segment")
+ _ (check-revision-message! body "segment")
+ segment (resolve-existing :model/Segment id)
+ body (m/update-existing body :definition
+ (fn [definition]
+ (prepare-definition
+ :segment definition
+ (mcp.db/table-by-id (:table_id segment)))))]
+ (-> (run-domain-write #(update-segment! (:id segment) body))
+ (write-result :segment)
+ (as-> row (v2.write/readback token-scopes [metabot.scope/agent-content-read] row nil))
+ common/success-content)))))
+
+;;; ------------------------------------------------ measure_write -------------------------------------------------
+
+(def ^:private measure-write-args-schema
+ (write-args-schema
+ {:entity "measure"
+ :name-desc "Create only (editable on update): display name of the measure."
+ :definition-desc (str "Either (a) the aggregation clause — what get_content's "
+ "\"definition\" include returns for a measure (one-element array or bare clause) and "
+ "what execute_query takes in stages[0].aggregation — reassembled onto `table_id`; or "
+ "(b) a full single-stage query (\"lib/type\": \"mbql/query\") holding exactly "
+ "one aggregation. No filters, breakouts, joins, expressions, or limits. May reference other measures "
+ "but not metrics; cycles are rejected.")}))
+
+(def ^:private measure-write-entry
+ {:create-required [:table_id :name :definition]
+ :clearable #{:description}})
+
+(registry/deftool measure-write
+ "Create or update a measure: a named, reusable MBQL aggregation attached to one table, referenced inside another
+ query's aggregation as [\"measure\", id]. A measure is not a metric — metrics are standalone saved cards queryable
+ on their own; a measure belongs to a table and is only usable inside a query against it. method: \"create\"
+ requires table_id, name, definition; \"update\" requires id and revision_message and accepts name, description,
+ definition, archived (true trashes, false restores — no hard delete). definition holds exactly one aggregation, in
+ either shape: the aggregation clause get_content's \"definition\" include returns for a measure (the same clause
+ execute_query takes in stages[0].aggregation), as the one-element array or bare clause, reassembled onto table_id;
+ or a full single-stage query. For a
+ full query table_id must name the definition's own source table; a mismatch is a teaching error. Not admin-only:
+ writing requires superuser OR a data analyst with unrestricted view-data on the table, and the table must not live
+ in a read-only remote-synced collection."
+ {:name "measure_write"
+ :scope metabot.scope/agent-content-write
+ ;; `archived: true` trashes the measure, so this is not the additive-only update
+ ;; `destructiveHint false` would assert.
+ :annotations {:readOnlyHint false :destructiveHint true}
+ :args measure-write-args-schema}
+ [args {:keys [token-scopes]}]
+ (let [dispatched (v2.write/dispatch-write measure-write-entry args)]
+ (case (first dispatched)
+ :create
+ (let [[_ body] dispatched
+ _ (check-method-args! :create body)
+ _ (check-name! body "measure")
+ table (resolve-table (:table_id body))
+ definition (prepare-definition :measure (:definition body) table)
+ _ (check-table-match! table definition)]
+ (-> (run-domain-write #(create-measure! {:name (:name body)
+ :description (:description body)
+ :definition definition}))
+ (write-result :measure)
+ (as-> row (v2.write/readback token-scopes [metabot.scope/agent-content-read] row nil))
+ common/success-content))
+
+ :update
+ (let [[_ id body] dispatched
+ _ (check-method-args! :update body)
+ _ (check-name! body "measure")
+ _ (check-revision-message! body "measure")
+ measure (resolve-existing :model/Measure id)
+ body (m/update-existing body :definition
+ (fn [definition]
+ (prepare-definition
+ :measure definition
+ (mcp.db/table-by-id (:table_id measure)))))]
+ (-> (run-domain-write #(update-measure! (:id measure) body))
+ (write-result :measure)
+ (as-> row (v2.write/readback token-scopes [metabot.scope/agent-content-read] row nil))
+ common/success-content)))))
diff --git a/src/metabase/mcp/v2/tools/document.clj b/src/metabase/mcp/v2/tools/document.clj
new file mode 100644
index 00000000000..e1d918375a8
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/document.clj
@@ -0,0 +1,513 @@
+(ns metabase.mcp.v2.tools.document
+ "The v2 MCP `document` write tool. Documents are the one content type whose body is
+ written as Markdown rather than compact JSON: the handler converts Metabase-flavored
+ Markdown to the stored ProseMirror AST through [[metabase.documents.core/parse]] /
+ [[metabase.documents.core/serialize]] / [[metabase.documents.core/splice]], and mirrors
+ the REST `POST`/`PUT /api/document` permission checks, card-embed cloning, and event
+ publishing via the shared domain functions."
+ (:require
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [clojure.walk :as walk]
+ [metabase.api.common :as api]
+ [metabase.comments.core :as comments]
+ [metabase.documents.core :as documents]
+ [metabase.documents.prose-mirror :as prose-mirror]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.models.interface :as mi]
+ [metabase.permissions.core :as perms]
+ [metabase.users.models.user :as user]
+ [metabase.users.settings :as users.settings]
+ [metabase.util.log :as log]
+ [metabase.util.malli.schema :as ms]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------ :document projection ------------------------------------------
+
+;; Relocated here from `content.clj` (slice 11), which hasn't landed yet: this tool is the first
+;; consumer of a `:document` response, and `document-response` below calls `projections/project
+;; :document`. content/11 drops its duplicate registration when it lands — the same
+;; projection-ownership dance used for metric/content in earlier slices.
+;; The `:document` projection is registered in [[metabase.mcp.v2.projections]], the namespace both
+;; this tool and `get_content` load. Registering it here instead would leave `get_content` — which
+;; requires `projections` but not this namespace — depending on `api.clj`'s require order to have
+;; populated the registry before it reads.
+
+;;; ------------------------------------------------ Smart links ---------------------------------------------------
+
+;; Parsing a `{% entity %}` token yields a smartLink with only its `entityId`/`model`; filling in
+;; the `label`/`href` the editor displays means reading the referenced row, which is a permission
+;; decision. That is why it happens here and not in [[metabase.documents.markdown]] — that
+;; namespace stays pure data, and the `documents` module stays clear of a `permissions` dependency
+;; that would pull every documents change into the driver test suite.
+
+(defn- smart-link-href
+ [model {:keys [id db_id]}]
+ (case model
+ "card" (str "/question/" id)
+ "dataset" (str "/model/" id)
+ "metric" (str "/metric/" id)
+ "dashboard" (str "/dashboard/" id)
+ "collection" (str "/collection/" id)
+ "document" (str "/document/" id)
+ "database" (str "/browse/databases/" id)
+ "table" (str "/question#?db=" db_id "&table=" id)
+ "/"))
+
+(defn- smart-link-label
+ [row]
+ (or (:display_name row)
+ (:name row)
+ (:common_name row)
+ (not-empty (str/trim (str (:first_name row) " " (:last_name row))))))
+
+(defn- smart-link-readable?
+ "Whether the current user is allowed to see `row`'s display name. Every model but `user` has
+ a [[mi/can-read?]] implementation to defer to; user rows are pre-filtered by
+ [[visible-user-rows]], and a sandboxed or impersonated caller resolves nobody but themselves."
+ [model row]
+ (if (= "user" model)
+ (or (= (:id row) api/*current-user-id*)
+ (not (perms/sandboxed-or-impersonated-user?)))
+ (mi/can-read? row)))
+
+(defn- visible-user-rows
+ "The `:model/User` rows among `ids` whose names the current user may see: the mention picker's
+ rule (`GET /api/comment/mentions`, `GET /api/user/recipients`). A superuser sees everyone; anyone
+ else sees active personal accounts in their own tenant, narrowed further by the `user-visibility`
+ setting (`:group` — users sharing a group; `:none` — only themselves). `:model/User` has no
+ `can-read?`, and resolving any id the caller names would let a document author enumerate names and
+ emails (`:common_name` is the email when a user has no name) across tenants."
+ [ids]
+ (let [clauses (cond-> [:and [:in :id ids] [:= :type "personal"] [:= :is_active true]]
+ (not api/*is-superuser?*)
+ (conj [:= :tenant_id (:tenant_id @api/*current-user*)]))
+ clauses (if api/*is-superuser?*
+ clauses
+ (case (users.settings/user-visibility)
+ :all clauses
+ :group (conj clauses [:in :id (-> (user/same-groups-user-ids api/*current-user-id*)
+ set
+ (conj api/*current-user-id*))])
+ :none (conj clauses [:= :id api/*current-user-id*])))]
+ (mcp.db/select-users-where clauses)))
+
+(defn- smart-link-rows
+ "`{[model id] row}` for every distinct smart-link target among `links` the current user may
+ see, one query per referenced model. A target the caller can't read is left out, so it is
+ indistinguishable from one that doesn't exist and its name never crosses the permission
+ boundary — the caller's write check on the *document* does not extend to whatever the
+ document happens to point at."
+ [links]
+ (into {}
+ (mapcat (fn [[model model-links]]
+ (let [db-model (prose-mirror/smart-link-model->db-model model)
+ ids (distinct (map #(get-in % [:attrs "entityId"]) model-links))
+ rows (when db-model
+ (try
+ (filterv #(smart-link-readable? model %)
+ (if (= "user" model)
+ (visible-user-rows ids)
+ (mcp.db/select-by-ids db-model ids)))
+ (catch Exception e
+ (log/warnf e "smart link lookup failed for %s" model)
+ nil)))]
+ (for [row rows]
+ [[model (:id row)] row]))))
+ (group-by #(get-in % [:attrs "model"]) links)))
+
+(defn- stored-smart-link-attrs
+ "`{[model entityId] attrs}` for every already-labelled smartLink in `ast`."
+ [ast]
+ (into {}
+ (keep (fn [node]
+ (when (and (map? node) (= "smartLink" (:type node)))
+ (let [{:strs [entityId model label] :as attrs} (:attrs node)]
+ (when label
+ [[model entityId] attrs])))))
+ (tree-seq :content :content ast)))
+
+(defn- resolve-smart-links!
+ "Fill `:label`/`:href` on every smartLink node in `ast` from its target row, falling back to the
+ same link's attrs in `previous-ast` (nil at create) and then to the defaults `parse` gave it.
+
+ Re-reading the row is what heals a renamed target, so it wins whenever it is available. The
+ fallback covers the case where it isn't: a `{% entity %}` token carries only `entityId`/`model`,
+ so every re-parsed block's links arrive label-less, and an editor who can't read the target
+ resolves nothing. Without a fallback, editing one sentence blanks the label of a link elsewhere
+ in the same block for everyone, including the people who can see it — the editor is treated as
+ authoritative about a name they were never shown.
+
+ Carrying the old label forward writes back a string the caller can't see, which is safe in the
+ one direction that matters: labels live in the AST and never in the Markdown projection, so no
+ response hands the caller a name they can't read. An id that resolves no row and has no previous
+ label keeps `parse`'s defaults and logs a warning: bad content, not a write error."
+ [ast previous-ast]
+ (let [links (->> (tree-seq :content :content ast)
+ (filter #(= "smartLink" (:type %))))]
+ (if (empty? links)
+ ast
+ (let [rows (smart-link-rows links)
+ stored (some-> previous-ast stored-smart-link-attrs)]
+ (walk/postwalk
+ (fn [node]
+ (if (and (map? node) (= "smartLink" (:type node)))
+ (let [{:strs [entityId model]} (:attrs node)
+ k [model entityId]]
+ (if-let [row (get rows k)]
+ (update node :attrs assoc
+ "label" (smart-link-label row)
+ "href" (smart-link-href model row))
+ (if-let [prior (get stored k)]
+ (update node :attrs assoc "label" (get prior "label") "href" (get prior "href"))
+ (do
+ (when (prose-mirror/smart-link-model->db-model model)
+ (log/warnf "smart link target not found or not readable for %s at id: %s" model entityId))
+ node))))
+ node))
+ ast)))))
+
+(defn- ast-id-set
+ [ast]
+ (set (prose-mirror/collect-ast {:document ast :content_type prose-mirror/prose-mirror-content-type}
+ (comp #(get % "_id") :attrs))))
+
+(defn- ast-id->type
+ [ast]
+ (into {} (prose-mirror/collect-ast
+ {:document ast :content_type prose-mirror/prose-mirror-content-type}
+ (fn [{:keys [type attrs]}]
+ (when-let [id (get attrs "_id")]
+ [id type])))))
+
+(defn- changed-blocks
+ [before after]
+ (let [after-types (ast-id->type after)]
+ (->> (prose-mirror/collect-ast
+ {:document before :content_type prose-mirror/prose-mirror-content-type}
+ (fn [{:keys [type attrs]}]
+ (when-let [id (get attrs "_id")]
+ [id type])))
+ (keep (fn [[id old-type]]
+ (let [new-type (get after-types id)]
+ (when (not= old-type new-type)
+ {:block_id id :old_type old-type :new_type new-type}))))
+ vec)))
+
+(defn- check-card-embeds!
+ "Every `{% card id=N %}` embed in `ast` must reference a card the caller can read, or one
+ already owned by `document-id` (nil at create). \"Doesn't exist\" and \"exists but not
+ readable\" collapse into the same not-found error, so the response never leaks existence
+ across the permission boundary. The write path's own clone step read-checks foreign cards
+ too, but only after this — a dangling id would otherwise be silently skipped by the clone
+ SELECT and persist as a broken embed."
+ [ast document-id]
+ (let [ids (distinct (prose-mirror/card-ids {:document ast
+ :content_type prose-mirror/prose-mirror-content-type}))]
+ (when (seq ids)
+ (let [cards (into {} (map (juxt :id identity)) (mcp.db/select-by-ids :model/Card ids))]
+ (doseq [id ids]
+ (let [card (get cards id)]
+ (when-not (and card
+ (or (and document-id (= document-id (:document_id card)))
+ (mi/can-read? card)))
+ (common/throw-not-found :model/Card id))))))))
+
+(defn- body-projection
+ "`{:content_markdown …}` for a stored AST, or an explanation in its place when the body has no
+ Markdown rendering — a block type from a newer frontend, or one a REST caller stored through
+ `[:document :any]`.
+
+ Serialized fresh from the stored AST, so it reflects post-clone card ids — the next edit's
+ old_str has to match this text, not what the caller submitted. Every caller reaches this after
+ its write has committed, so a body that won't render must not turn a completed write into a
+ failed call; `Throwable` for the same reason the search indexer uses it, since an unrenderable
+ body is exactly the input that finds a way to fail that isn't an `Exception`. The key is omitted
+ rather than filled with a degraded rendering: old_str is matched against this exact text, so
+ text that isn't the serialization is worse than none."
+ [ast]
+ (try
+ {:content_markdown (:markdown (documents/serialize ast))}
+ (catch Throwable e
+ (log/warn e "document body has no Markdown rendering; omitting content_markdown")
+ {:content_markdown_unavailable
+ (str "The write succeeded, but this document's body contains a block that has no Markdown "
+ "form, so content_markdown is omitted and edits cannot be applied to it. Read it with "
+ "get_content, or replace the whole body with content_markdown.")})))
+
+(defn- document-response
+ "The written document echoed to the caller: the `:document` concise read projection, so the echo
+ and a concise `get_content` read name the body identically and a read-modify-write needs no
+ renaming, plus the write-only fields — `:entity_id` (a portable id to update by),
+ `:collection_position`, changed blocks, and the comment threads this write orphaned.
+
+ The body is re-serialized from the stored AST rather than taken from the projection, so it
+ reflects post-clone card ids: the next edit's `old_str` is matched against this exact text."
+ [document orphaned-threads changed-blocks]
+ (-> (projections/project :document :concise document)
+ (merge {:entity_id (:entity_id document)
+ :collection_position (:collection_position document)
+ :archived (boolean (:archived document))
+ :orphaned_comment_threads orphaned-threads
+ :changed_blocks changed-blocks}
+ (body-projection (:document document)))))
+
+;;; ------------------------------------------------------ Edits ---------------------------------------------------
+
+(defn- match-indexes
+ "Start offsets of the non-overlapping occurrences of `needle` in `haystack`."
+ [^String haystack ^String needle]
+ (loop [from 0 acc []]
+ (if-let [i (str/index-of haystack needle from)]
+ (recur (long (+ i (count needle))) (conj acc i))
+ acc)))
+
+(defn- snippet
+ [s]
+ (let [s (str s)]
+ (pr-str (if (> (count s) 80) (str (subs s 0 77) "…") s))))
+
+(def ^:private max-edit-work
+ "Ceiling on `splices × document-KB` for one `document_write` call, the product that sets its cost:
+ every splice re-serializes the whole document, so the work is quadratic in a document's size once a
+ `replace_all`'s `old_str` is short enough to appear throughout it.
+
+ Measured at roughly 0.03ms per splice·KB, so this caps a call near 600ms. Real edits are orders of
+ magnitude under — renaming a term appearing 30 times in a 50KB document is 1,500 — while the shape
+ this exists to stop, a one-character `old_str` on a 64KB document, prices at ~460,000 and took ~14s
+ before the ceiling existed. Left unbounded it grows with document size: an 85-byte request against a
+ 1MB document buys about an hour of one thread.
+
+ Budgeted per call rather than per edit because `edits` is an unbounded list: an allowance handed
+ fresh to each entry is no bound at all, since 100 edits each just under it buy 100x the work in one
+ request."
+ 20000)
+
+(defn- edit-work
+ "`splices × document-KB` against `markdown` — the cost estimate [[max-edit-work]] bounds. One splice
+ for a single edit, one per occurrence for a `replace_all`. Sub-KB documents price at zero, which is
+ correct: they are cheap however many splices they take."
+ [^String markdown ^long splices]
+ (long (* splices (/ (count markdown) 1024.0))))
+
+(defn- check-no-markdown-tables!
+ [^String markdown]
+ (when (documents/contains-table? markdown)
+ (common/throw-teaching-error
+ "Markdown tables are not supported. Save the query as a question with `display: table` and embed it with {% card id=… %}.")))
+
+(defn- replace-all
+ "Splice every occurrence of `old_str`, right-to-left so a replacement containing `old_str`
+ is never re-matched, re-serializing between splices so each offset is taken against the
+ AST it applies to. Re-parsing a touched block can shift text before it, so when `new_str`
+ cannot reintroduce `old_str` the bound resets and the sweep repeats until no occurrence
+ remains; an iteration cap turns any pathological non-convergence into a teaching error
+ rather than a silent miss.
+
+ `ser` and `initial-matches` are [[apply-edit]]'s serialization of `ast` and the occurrences it
+ found there, already priced against [[max-edit-work]]. Taking them rather than recomputing them
+ keeps a `replace_all` to one serialization per splice, with none spent on pricing."
+ [ast ser initial-matches old_str new_str]
+ (let [self-matching? (str/includes? new_str old_str)]
+ ;; `splice` reuses a serialization only when it is of the very AST being spliced, so each recur
+ ;; re-serializes the AST it produced.
+ (loop [ast ast, ser ser, bound Long/MAX_VALUE, iterations 0]
+ (when (> iterations (+ 100 (* 2 (count initial-matches))))
+ (common/throw-teaching-error
+ (format (str "replace_all could not converge for old_str %s — the replacement keeps re-creating "
+ "text that matches. Use distinct old_str/new_str pairs or edit the surrounding "
+ "blocks individually.")
+ (snippet old_str))))
+ (let [matches (match-indexes (:markdown ser) old_str)
+ idx (last (filter #(< % bound) matches))]
+ (cond
+ (some? idx)
+ (let [spliced (documents/splice ast ser idx (+ idx (count old_str)) new_str)]
+ (recur spliced (documents/serialize spliced) (long idx) (inc iterations)))
+
+ (and (not self-matching?) (seq matches))
+ (recur ast ser Long/MAX_VALUE (inc iterations))
+
+ :else ast)))))
+
+(defn- apply-edit
+ "Apply one `{old_str, new_str, replace_all?}` edit to `ast`, locating `old_str` in a fresh
+ serialization of the current AST — never a client-supplied snapshot.
+
+ Takes and returns `{:ast :spent}`, where `spent` is the work the edits before it in this call have
+ already priced, so [[max-edit-work]] bounds the call rather than each entry. The budget is spent
+ down as the sweep goes rather than totalled up front because an edit's cost is only knowable once
+ its predecessors have run — its matches are counted against the text they produced."
+ [{:keys [ast spent]} {:keys [old_str new_str replace_all]}]
+ (when (empty? old_str)
+ (common/throw-teaching-error "old_str must be a non-empty string."))
+ (let [{:keys [markdown] :as ser} (documents/serialize ast)
+ matches (match-indexes markdown old_str)]
+ (cond
+ (empty? matches)
+ (common/throw-teaching-error
+ (format (str "old_str %s matches 0 places in the document's current Markdown. The document may "
+ "have changed since you read it — copy the snippet exactly from the content_markdown "
+ "this tool (or get_content) returns.")
+ (snippet old_str)))
+
+ (and (> (count matches) 1) (not replace_all))
+ (common/throw-teaching-error
+ (format (str "old_str %s matches %d places — extend the snippet with more surrounding context so "
+ "it matches exactly once, or set replace_all: true.")
+ (snippet old_str) (count matches)))
+
+ :else
+ (let [splices (if replace_all (count matches) 1)
+ spent (+ spent (edit-work markdown splices))]
+ (when (> spent max-edit-work)
+ (common/throw-teaching-error
+ (format (str "The edit for old_str %s would splice %d times across a %dKB document, putting this "
+ "call past the rewriting work one call can do — the ceiling covers every edit in the "
+ "call together, not each one on its own. Split the edits across several "
+ "document_write calls, or, for a replace_all matching everywhere, extend old_str "
+ "with surrounding context so it matches fewer places. Replacing the whole body with "
+ "content_markdown rewrites it in a single pass instead — note that a full rewrite "
+ "re-creates every block, so comment threads anchored to the body are orphaned.")
+ (snippet old_str)
+ splices
+ (quot (count markdown) 1024))))
+ {:ast (if replace_all
+ (replace-all ast ser matches old_str new_str)
+ (documents/splice ast ser (first matches) (+ (first matches) (count old_str)) new_str))
+ :spent spent}))))
+
+;;; ------------------------------------------------------ Create --------------------------------------------------
+
+(defn- create!
+ [{:keys [name content_markdown collection_position] :as args}]
+ (when (:edits args)
+ (common/throw-teaching-error "edits only apply to method: \"update\" — pass content_markdown to create."))
+ (when (:id args)
+ (common/throw-teaching-error "id only applies to method: \"update\" — create makes a new document."))
+ (when (contains? args :archived)
+ (common/throw-teaching-error "archived only applies to method: \"update\" — a new document is never archived."))
+ (let [collection-id (v2.resolve/resolve-collection-id-or-personal (:collection_id args))]
+ (api/create-check :model/Document {:collection_id collection-id})
+ (let [ast (resolve-smart-links! (documents/parse content_markdown) nil)]
+ (check-card-embeds! ast nil)
+ (let [created (documents/create-document! {:name name
+ :document ast
+ :collection_id collection-id
+ :collection_position collection_position})]
+ (document-response created [] [])))))
+
+;;; ------------------------------------------------------ Update --------------------------------------------------
+
+(defn- update!
+ [id {:keys [content_markdown edits collection_position archived] :as args}]
+ (when (and content_markdown edits)
+ (common/throw-teaching-error
+ "Pass exactly one of content_markdown (a deliberate full-body rewrite) or edits (surgical text edits), not both."))
+ (when-not (or content_markdown edits)
+ (common/throw-teaching-error
+ (str "An update needs exactly one of content_markdown (full rewrite) or edits (surgical text "
+ "edits). To change only collection_id/collection_position/archived, pass edits: [].")))
+ (let [existing (v2.resolve/resolve-and-read-with :model/Document id
+ (fn [document-id] (documents/get-document document-id)))]
+ (when-not (contains? args :archived)
+ (api/check-not-archived existing))
+ (api/write-check existing)
+ (let [collection-id (when (contains? args :collection_id)
+ (v2.resolve/resolve-collection-id (:collection_id args)))]
+ (when (and (contains? args :collection_id)
+ (not= collection-id (:collection_id existing)))
+ (documents/validate-collection-move-permissions (:collection_id existing) collection-id))
+ (let [old-ids (ast-id-set (:document existing))
+ ;; `edits: []` is the metadata-only escape hatch: no new AST, and the document
+ ;; column is left entirely alone below.
+ ;; Resolved once on the finished AST rather than per splice: fewer queries, and it
+ ;; picks up a link any of the edits introduced. The pre-edit AST goes along so a link
+ ;; whose target this caller can't read keeps the label it already had.
+ new-ast (some-> (cond
+ ;; Full rewrite: everything re-parses, nothing keeps its node id, so
+ ;; every anchored comment thread is reported orphaned below.
+ content_markdown (documents/parse content_markdown)
+ (seq edits) (:ast (reduce apply-edit
+ {:ast (:document existing) :spent 0}
+ edits)))
+ (resolve-smart-links! (:document existing)))
+ _ (when new-ast
+ (check-card-embeds! new-ast (:id existing)))
+ body (cond-> {}
+ new-ast (assoc :document new-ast)
+ (contains? args :name) (assoc :name (:name args))
+ (contains? args :collection_id) (assoc :collection_id collection-id)
+ (contains? args :collection_position) (assoc :collection_position collection_position)
+ (contains? args :archived) (assoc :archived (boolean archived)))
+ updated (documents/update-document! existing body)
+ removed (when new-ast
+ (set/difference old-ids (ast-id-set (:document updated))))
+ changed (if (seq edits)
+ (changed-blocks (:document existing) (:document updated))
+ [])]
+ (document-response updated
+ (if (seq removed)
+ (filterv #(contains? removed (:child_target_id %))
+ (comments/child-target-ids-for-document (:id updated)))
+ [])
+ changed)))))
+
+;;; ------------------------------------------------------ Tool ----------------------------------------------------
+
+(def ^:private document-write-args-schema
+ [:map {:closed true}
+ [:method [:enum "create" "update"]]
+ [:id {:optional true} [:maybe [:or :int :string]]]
+ [:name {:optional true} [:maybe documents/DocumentName]]
+ [:content_markdown {:optional true} [:maybe :string]]
+ [:edits {:optional true}
+ [:maybe [:sequential
+ [:map
+ [:old_str :string]
+ [:new_str :string]
+ [:replace_all {:optional true} [:maybe :boolean]]]]]]
+ ;; Numeric ids and positions are positive here, matching what the model layer enforces. Declared
+ ;; loosely they pass validation and then fail a `mu/defn` schema deeper in, which the caller only
+ ;; ever sees as the sanitized "Internal error" — a rejection that names the constraint is the
+ ;; whole value of declaring it.
+ ;; Kept as an `:or` so the generated JSON schema still shows both accepted shapes, which is what
+ ;; the agent reads. The humanized message lists each branch rather than one sentence; an
+ ;; `:error/message` on the `:or` itself is ignored by Malli's humanizer.
+ [:collection_id {:optional true} [:maybe [:or ms/PositiveInt :string]]]
+ [:collection_position {:optional true} [:maybe ms/PositiveInt]]
+ [:archived {:optional true} [:maybe :boolean]]
+ [:clear {:optional true}
+ [:maybe [:sequential [:enum {:description (str "Update only: property names to unset "
+ "(collection_position). A null cannot say this — "
+ "strict clients fill every unset property with "
+ "null, so nulls are stripped at the boundary.")}
+ "collection_position"]]]]])
+
+(registry/deftool document-write-tool
+ "Create or update a document. method: \"create\" | \"update\". Documents are Metabase-flavored Markdown: CommonMark plus {% card id=118 name=\"…\" %} block embeds of saved questions you can read (build with question_write first; an id that doesn't resolve fails the write; the embed is given a height for you), {% entity id=\"42\" model=\"dashboard\" %} inline links (models: card, dataset, metric, dashboard, collection, table, database, document), and ::: fenced layout containers — ::: flex {columns=[60,40]} holds 1-3 cells (prose in ::: supporting, or a card embed); ::: resize {height=442 minHeight=280} pins the height of one flex container or embed; a bare ::: line closes the innermost container, so every opener needs its name. No Markdown tables - embed a table-display question instead. Before authoring layout containers, call learn(\"documents\") — the grammar, nesting rules, and a worked example. A card not already owned by the document is cloned into it on write and its id rewritten, so always take the returned content_markdown as the current text. Create: name + content_markdown; optional collection_id (omit for your personal collection; \"root\" for the root collection) and collection_position. Update: id + exactly one of content_markdown (a deliberate full-body rewrite — re-creates every block, orphaning every comment thread anchored to the body) or edits: [{old_str, new_str, replace_all?}] (each old_str must match the current server-side Markdown exactly once; 0 or >1 matches is an error — extend the snippet or set replace_all; new_str is parsed as Markdown; blocks keep their ids and comment anchors through edits to their text, so only a removed block loses its comments); edits: [] changes only name/collection_id/collection_position/archived without touching the body (archived: true trashes, false restores; name renames). To unset a property rather than change it, name it in clear: [\"collection_position\"] — a null does not clear, since strict clients fill every unset property with null and those are stripped. The response lists changed_blocks and orphaned_comment_threads, and carries content_markdown_unavailable in place of content_markdown when the stored body holds a block with no Markdown form — the write still happened, but this body cannot be edited or rewritten as Markdown — get_content omits content_markdown for it too, and rewriting it from any flattened text would discard the block that has no Markdown form. Writes are last-write-wins — no version check, a concurrent change between read and write is overwritten; a stale old_str failing to match is the only staleness signal."
+ {:name "document_write"
+ :scope metabot.scope/agent-content-write
+ :annotations {:readOnlyHint false :destructiveHint false}
+ :args document-write-args-schema}
+ [args {:keys [token-scopes]}]
+ (let [[op a b] (v2.write/dispatch-write
+ {:create-required [:name :content_markdown]
+ :clearable #{:collection_position}}
+ args)
+ write-args (if (= op :create) a b)
+ _ (doseq [markdown (cons (:content_markdown write-args) (map :new_str (:edits write-args)))]
+ (check-no-markdown-tables! markdown))
+ payload (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (case op
+ :create (create! a)
+ :update (update! a b))
+ nil)]
+ (common/success-content payload)))
diff --git a/src/metabase/mcp/v2/tools/duplicate.clj b/src/metabase/mcp/v2/tools/duplicate.clj
new file mode 100644
index 00000000000..ad74d2f079b
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/duplicate.clj
@@ -0,0 +1,177 @@
+(ns metabase.mcp.v2.tools.duplicate
+ "The v2 MCP `duplicate_content` tool: copy a question, dashboard, or document into a collection.
+
+ The input contract doesn't vary with type, but the backing does — a dashboard copy takes name,
+ collection, and the deep-copy flag; a document copy takes name and collection; a card copy takes
+ neither, so the new name and collection are folded into the create itself. The tool absorbs that
+ difference so one call is one copy, and the caller never has to follow a copy with a move."
+ (:require
+ [metabase.api.common :as api]
+ [metabase.dashboards.write :as dashboards.write]
+ [metabase.documents.core :as documents]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.queries.core :as queries]
+ [metabase.util.i18n :refer [tru]]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------- per-type copies ----------------------------------------------
+
+(defn- check-not-archived!
+ "Refuse a trashed source. Archived content keeps its real `collection_id` (the trash is
+ presentational), and neither copy path carries `:archived` over — so duplicating a trashed item
+ would resurrect it as a live copy in the collection it was trashed from. Runs after the read
+ check, so an unreadable source still collapses to not-found rather than admitting it exists."
+ [model item]
+ (when (:archived item)
+ (common/throw-teaching-error
+ (format "%s %s is in the trash — restore it before duplicating." (name model) (:id item))))
+ item)
+
+(defn- fetch-question
+ [id-or-eid]
+ (let [card (->> (v2.resolve/resolve-and-read :model/Card id-or-eid)
+ (check-not-archived! :model/Card))]
+ (when (not= :question (:type card))
+ (common/throw-teaching-error
+ (format "Card %s is a %s — duplicate_content supports type \"question\" only."
+ (:id card) (name (:type card)))))
+ ;; A Card scoped to a Document is gated by that Document, not by its collection:
+ ;; `mi/can-read? :model/Card` conjoins `parent-document-permits?`, which short-circuits to true
+ ;; on a nil `document_id`. So a copy that dropped the column would be adjudicated by collection
+ ;; perms alone and would disclose, permanently and to everyone reading the destination, material
+ ;; the Document's content gate exists to withhold. Carrying the column instead is no better: the
+ ;; copy would claim membership in a document whose body never references it, and
+ ;; `copy-document!` re-parents such cards precisely because their `collection_id` tracks the
+ ;; document rather than standing on its own. Neither outcome is a "standalone question in
+ ;; `collection-id`", so refuse and name the operation that does work.
+ (when (:document_id card)
+ (common/throw-teaching-error
+ (format (str "Card %s is saved inside a document — duplicate the document instead, which "
+ "copies the questions saved in it.")
+ (:id card))))
+ card))
+
+(defn- copy-question!
+ "Create the card copy directly rather than copying then moving: `POST /api/card/:id/copy` takes no
+ arguments, so a two-step copy would leave a wrongly-named card behind on any failure. Clears
+ `dashboard_id` — the copy is a standalone question in `collection-id`, not a second card saved
+ inside the source's dashboard. A document-scoped source never reaches here; [[fetch-question]]
+ refuses it, because `document_id` carries the card's read gate rather than its placement.
+
+ Copy semantics, not create semantics: the query comes from a row the caller already passed a
+ read check on, so they are not authoring it. `check-allowed-to-create-card!` would additionally
+ demand run-permission on that query, which refuses a user who can read and run a native card but
+ lacks native authoring perms — the case `documents.models.document/clone-card!` calls out
+ (UXW-5037), and one `POST /api/card/:id/copy` allows. Destination create-permission is still
+ enforced."
+ [card collection-id new-name]
+ (let [new-card (-> card
+ (assoc :name new-name :collection_id collection-id)
+ (dissoc :dashboard_id :collection_position))]
+ (api/create-check :model/Card {:collection_id collection-id})
+ (queries/create-card! new-card @api/*current-user*)))
+
+(defn- fetch-dashboard
+ [id-or-eid]
+ (->> (v2.resolve/resolve-and-read :model/Dashboard id-or-eid)
+ (check-not-archived! :model/Dashboard)))
+
+(defn- copy-dashboard!
+ [dashboard collection-id new-name deep-copy?]
+ (when (and (not deep-copy?) (dashboards.write/contains-dashboard-questions? (:id dashboard)))
+ (common/throw-teaching-error
+ "This dashboard has questions saved inside it, so it can't be copied without them — pass is_deep_copy: true to copy the questions too."))
+ (dashboards.write/copy-dashboard! (:id dashboard)
+ {:name new-name
+ :collection_id collection-id
+ :is_deep_copy deep-copy?}))
+
+(defn- fetch-document
+ [id-or-eid]
+ ;; Selected without an `:archived false` filter so a trashed-but-readable document earns the
+ ;; teaching error below rather than the not-found collapse, which would wrongly imply the caller
+ ;; can't see it.
+ (->> (v2.resolve/resolve-and-read :model/Document id-or-eid)
+ (check-not-archived! :model/Document)))
+
+(defn- copy-document!
+ [document collection-id new-name]
+ (documents/copy-document! (:id document) {:name new-name :collection_id collection-id}))
+
+(def ^:private type->spec
+ "Per-type fetch and copy. GHY-4225 collapsed the per-type create scopes into the single
+ `agent:content:write` this tool already gates on, so there is no longer a second scope to check."
+ {"question" {:fetch fetch-question
+ :copy! (fn [source collection-id new-name _deep-copy?]
+ (copy-question! source collection-id new-name))}
+ "dashboard" {:fetch fetch-dashboard
+ :copy! copy-dashboard!}
+ "document" {:fetch fetch-document
+ :copy! (fn [source collection-id new-name _deep-copy?]
+ (copy-document! source collection-id new-name))}})
+
+;;; ---------------------------------------------------- handler ---------------------------------------------------
+
+(defn- destination-collection-id
+ "The copy's collection: the caller's `collection_id` when they passed one (`\"root\"` included),
+ otherwise the caller's personal collection."
+ [args]
+ (v2.resolve/resolve-collection-id-or-personal (:collection_id args)))
+
+(def ^:private duplicate-content-args-schema
+ [:map {:closed true}
+ [:type [:enum {:description "The kind of content to copy. Card flavors other than question (model, metric) aren't supported yet."}
+ "question" "dashboard" "document"]]
+ [:id [:or
+ [:int {:description "Numeric id of the item to copy."}]
+ [:string {:min 1 :description "A 21-character entity_id of the item to copy."}]]]
+ [:collection_id {:optional true}
+ [:maybe [:or
+ [:int {:description "Collection to copy into. Omit to copy into your personal collection; pass \"root\" for the root collection."}]
+ [:string {:min 1 :description "A 21-character collection entity_id, or \"root\"."}]]]]
+ [:new_name {:optional true}
+ [:maybe [:string {:min 1 :description "Name for the copy. Defaults to \"Copy of <source name>\"."}]]]
+ [:is_deep_copy {:optional true}
+ [:maybe [:boolean {:description "Dashboards only: also copy the dashboard's questions into the destination collection, instead of pointing the copy at the originals."}]]]])
+
+(registry/deftool duplicate-content
+ "Copy a question, dashboard, or document into a collection — cheaper and safer than reading the original and re-creating it, and it preserves everything the read projections leave out. Pass type, id (numeric or 21-char entity_id), and optionally collection_id (omit to copy into your personal collection; \"root\" for the root collection) and new_name (defaults to \"Copy of <source name>\"). is_deep_copy is dashboards-only: false (the default) makes the copy point at the original's questions, true duplicates those questions into the destination collection as well — a dashboard that holds questions saved inside it can only be copied with is_deep_copy: true. Any copy of a dashboard, shallow or deep, reports cards it had to leave behind as `uncopied` — cards you can't read (reported as an id alone) or that are in the trash; the copy simply omits them, so check this field on every dashboard copy. A question saved inside a document can't be duplicated on its own — duplicate the document instead. Duplicating is creating: you need curate permission on the destination collection. The copy's name and collection come back only when your token also holds agent:content:read; without it the response is a minimal acknowledgement carrying the id, the type, and a count of any uncopied cards."
+ {:name "duplicate_content"
+ :scope metabot.scope/agent-content-write
+ :annotations {:readOnlyHint false :destructiveHint false}
+ :args duplicate-content-args-schema}
+ [{:keys [type id new_name is_deep_copy] :as args} {:keys [token-scopes]}]
+ (let [{:keys [fetch copy!]} (type->spec type)]
+ ;; `true?`, not `some?`: `false` is the documented default and means exactly what a question or
+ ;; document copy already does, so rejecting it refuses a request the tool can serve — and the
+ ;; published strict inputSchema marks every property required, so a strict client must send it.
+ (when (and (true? is_deep_copy) (not= type "dashboard"))
+ (common/throw-teaching-error
+ (format "`is_deep_copy` applies to dashboards only — omit it when duplicating a %s." type)))
+ (let [source (fetch id)
+ collection-id (destination-collection-id args)
+ copy (copy! source collection-id (or new_name (tru "Copy of {0}" (:name source)))
+ (boolean is_deep_copy))]
+ (common/success-content
+ ;; `new_name` defaults to "Copy of <source name>", so echoing the copy's name hands back the
+ ;; source's — the same read the read tools would refuse this token.
+ ;;
+ ;; `:uncopied` itself must not survive the degradation: `cards-to-copy`'s `redact` reduces a
+ ;; card to its id only when it is *unreadable*, so an archived-but-readable card rides out
+ ;; with its real name — handing a write-only token names it cannot read back through any read
+ ;; tool. `:uncopied_count` carries the completeness signal without the names, and `:type` is
+ ;; the caller's own argument, so both are safe as ack-keys.
+ (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (cond-> {:type type
+ :id (:id copy)
+ :name (:name copy)
+ :collection_id (:collection_id copy)}
+ (seq (:uncopied copy))
+ (assoc :uncopied (mapv #(select-keys % [:id :name]) (:uncopied copy))
+ :uncopied_count (count (:uncopied copy))))
+ [:type :uncopied_count])))))
diff --git a/src/metabase/mcp/v2/tools/learn.clj b/src/metabase/mcp/v2/tools/learn.clj
new file mode 100644
index 00000000000..fc4eb2bd826
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/learn.clj
@@ -0,0 +1,62 @@
+(ns metabase.mcp.v2.tools.learn
+ "The v2 MCP `learn` tool: on-demand delivery of the skill packs in
+ [[metabase.mcp.v2.skills]] — the deep, task-shaped knowledge tool descriptions cannot carry
+ (template-tag shapes, the MBQL query dialect, parameter wiring, layout conventions).
+
+ One tool is the whole delivery surface: it rides `tools/list`, the one discovery channel
+ every MCP client implements, so it is model-invokable everywhere. The tool's own description
+ carries the catalog inline, so even a model that ignores every per-tool pointer sees the
+ topics in its tool list. Knowledge is not sensitive — it describes the API, not the
+ instance's data — but what it documents is the content tools, so it rides their
+ `agent:content:read` rather than adding a sixth scope to the v2 surface. Declaring some scope
+ is not optional: the v2 gate denies a nil `:scope` outright, so omitting it would hide the
+ tool rather than make it public."
+ (:require
+ [clojure.string :as str]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.skills :as skills]
+ [metabase.metabot.scope :as metabot.scope]))
+
+(set! *warn-on-reflection* true)
+
+(defn- unknown-topic!
+ [topic]
+ (common/throw-teaching-error
+ (format "Unknown topic %s. Topics: %s. Call learn() with no arguments for the catalog with descriptions."
+ (pr-str topic) (str/join ", " (skills/topics)))))
+
+(registry/deftool learn
+ "Read this server's task docs (skills) for the write dialects the schemas can't fully describe. learn() lists topics; learn(topic) returns that skill whole; learn(topic, reference) one of its reference files. Topics: query-dialect (the query language for execute_query and question_write's query; reference \"operators\" = operator catalog), native-parameters (template tags and field filters for native SQL), dashboard-filters (dashboard parameters and the wire_parameter target grammar), dashboard-layout (24-column grid, sizes, tabs), documents (document_write's Markdown grammar), transforms (transform_write: materializing a query into a warehouse table), visualization-settings (display choice and settings; reference \"settings\" = per-chart key catalog). Read the matching topic before your first complex write of that kind; skip when already in context."
+ {:name "learn"
+ :scope metabot.scope/agent-content-read
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :args [:map {:closed true}
+ [:topic {:optional true}
+ [:maybe [:string {:min 1 :description "A topic from the catalog. Omit to list all topics."}]]]
+ [:reference {:optional true}
+ [:maybe [:string {:min 1 :description "A reference file of `topic`, by the name the skill (or the catalog) lists."}]]]]}
+ [{:keys [topic reference]} _context]
+ (common/success-content
+ (cond
+ (and reference (nil? topic))
+ (common/throw-teaching-error
+ "`reference` names a file within a topic — pass `topic` alongside it, e.g. learn(\"query-dialect\", \"operators\").")
+
+ (nil? topic)
+ (skills/catalog-text)
+
+ reference
+ (or (skills/reference-text topic reference)
+ (if-let [names (skills/reference-names topic)]
+ (common/throw-teaching-error
+ (format "Topic %s has no reference %s.%s"
+ (pr-str topic) (pr-str reference)
+ (if (seq names)
+ (str " Its references: " (str/join ", " names) ".")
+ " It has no reference files — call learn(topic) for the skill itself.")))
+ (unknown-topic! topic)))
+
+ :else
+ (or (skills/skill-text topic)
+ (unknown-topic! topic)))))
diff --git a/src/metabase/mcp/v2/tools/metric.clj b/src/metabase/mcp/v2/tools/metric.clj
new file mode 100644
index 00000000000..5aeaab09cc5
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/metric.clj
@@ -0,0 +1,299 @@
+(ns metabase.mcp.v2.tools.metric
+ "The v2 MCP `metric_write` tool. A metric is a Card with `type: \"metric\"` — the same table and
+ the same REST endpoint as a saved question — so this tool routes through the shared card check
+ stack ([[metabase.queries.core]]) that `POST`/`PUT /api/card` and `question_write` run, never
+ reimplementing permissions or persistence.
+
+ Its own work is the metric authoring contract: one `definition` query source (a full query in
+ the numeric-id MBQL 5 `get_content` returns, the older name-based dialect, or a `query_handle` from an
+ execute tool), the metric shape gate (`lib/can-save?`: one stage, exactly one aggregation, at
+ most one breakout), and refusing to retype an existing question or model."
+ (:require
+ [metabase.agent-api.query-guards :as query-guards]
+ [metabase.api.common :as api]
+ [metabase.channel.urls :as channel.urls]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.queries.core :as queries]
+ [metabase.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private accepted-shapes
+ "The sentence every definition-shape teaching error ends with, naming what `definition` accepts."
+ (str "`definition` accepts a full single-stage query holding exactly one aggregation: MBQL 5 with "
+ "numeric ids — what get_content's \"definition\" include returns for a metric and what "
+ "execute_query takes — or the older name-based dialect, still resolved on input. "
+ "Alternatively pass a query_handle from an execute tool instead of `definition`."))
+
+(def ^:private accepted-displays
+ "Card display types `display` accepts. Enumerated so an LLM-invented value is an argument error
+ instead of junk persisted on the card."
+ ["table" "bar" "line" "pie" "scatter" "area" "row" "combo" "pivot"
+ "scalar" "smartscalar" "gauge" "progress" "funnel" "map" "waterfall" "sankey"])
+
+(def ^:private default-display
+ "The display a created metric gets when the caller names none."
+ :scalar)
+
+(def ^:private shape-rule
+ "The metric shape rule, quoted verbatim in every gate error so the caller learns it once."
+ (str "A metric needs exactly one aggregation and at most one grouping, in a single "
+ "query stage."))
+
+;; This tool's write echo is built from the `:metric` projection, which `get_content` reads too, so
+;; the registration lives in [[metabase.mcp.v2.projections]] — the namespace both require. Owning it
+;; from either tool leaves the other depending on `api.clj`'s require order for it.
+
+;;; --------------------------------------------- Definition handling ----------------------------------------------
+
+(defn- normalize-definition
+ "Normalize a numeric-ref query — hand-written MBQL 5, MBQL 4 (which normalizes into it), a
+ resolved portable query, or a handle's stored query — into the canonical MBQL 5 the card layer
+ takes. Strict, so a malformed or empty definition is a teaching error here rather than silently
+ degrading to `{}` on store; the result carries the metadata provider the card write checks require."
+ [definition]
+ (let [normalized (try
+ (lib-be/normalize-query nil definition {:strict? true})
+ (catch Exception e
+ (common/throw-teaching-error
+ (format "`definition` is not a valid MBQL query: %s %s"
+ (common/ellipsize (ex-message e) 300) accepted-shapes))))]
+ ;; normalize-query short-circuits an empty query to `{}` before its strict validation runs, so
+ ;; an empty `definition` arrives here unvalidated instead of throwing above.
+ (when (empty? normalized)
+ (common/throw-teaching-error
+ (str "`definition` is empty. Pass the metric's query in it, or leave `definition` out of the "
+ "call entirely — on update that keeps the stored query as it is. " accepted-shapes)))
+ normalized))
+
+(defn- resolve-definition
+ "Resolve the caller's query source to the query the metric card stores. Exactly one of
+ `definition` (portable external dialect or MBQL 5) and `query_handle` (a handle from an execute
+ tool, re-checked for shape and permissions on resolve) may be present; `nil` when neither is,
+ which on update means \"leave the stored query alone\"."
+ [{:keys [definition query_handle]} session-id]
+ (when (and definition query_handle)
+ (common/throw-teaching-error
+ (str "Pass exactly one query source: `definition` (the metric's query) or `query_handle` "
+ "(a handle from an execute tool).")))
+ (some-> (cond
+ definition (if (v2.queries/portable-query? definition)
+ (v2.queries/resolve-external-query definition accepted-shapes)
+ definition)
+ query_handle (:query (v2.queries/resolve-query-handle-for-save!
+ session-id api/*current-user-id* query_handle)))
+ normalize-definition))
+
+(defn- check-metric-shape!
+ "Throw a teaching error unless `dataset-query` is a saveable metric. `lib/can-save?` reads field
+ metadata to type-check the breakout, which the query carries: [[normalize-definition]] leaves a
+ metadata provider attached. Restates the rule rather than reusing
+ [[metabase.queries.core/check-card-can-be-saved!]]'s REST-facing 400, whose message an agent
+ can't act on — and which the update-side check stack doesn't run at all."
+ [dataset-query]
+ ;; Whole-tree, not lib/native-only-query? (which sees only a single pure-native stage): a
+ ;; definition with a native stage anywhere — e.g. native + an appended MBQL stage — is still SQL
+ ;; a metric must refuse, and would otherwise fall through to the generic "can't be saved" message.
+ (when (query-guards/native-query? dataset-query)
+ (common/throw-teaching-error
+ (str "A metric can't be built from a native (SQL) query — metrics are MBQL so other queries can "
+ "reuse them. Save it with question_write instead, or rebuild the aggregation with execute_query.")))
+ (when-not (lib/can-save? dataset-query :metric)
+ (common/throw-teaching-error
+ (format (str "This query can't be saved as a metric. %s Build it with execute_query first — "
+ "a single summarize (count, sum, average…) with at most one grouping.")
+ shape-rule))))
+
+;;; ------------------------------------------------- Responses ----------------------------------------------------
+
+(defn- write-result
+ "The created/updated metric echoed to the caller: the `:metric` concise read projection, plus
+ `:entity_id` (a portable id to update by), `:archived`, `:display`, and the metric's URL. The
+ echo confirms what was written rather than standing in for a read — `:query_summary` is derived
+ from the query at read time rather than stored on the card, so it is the one concise key the
+ echo never carries. Read the metric back through `get_content` if you need it."
+ [card]
+ ;; :display is a detailed-projection key, echoed here anyway: it is the one written field a
+ ;; caller can set without naming it, so the echo is where a defaulted :scalar becomes visible.
+ (assoc (projections/project :metric :concise card)
+ :entity_id (:entity_id card)
+ :archived (boolean (:archived card))
+ :display (:display card)
+ :url (common/frontend-url (channel.urls/metric-path (:id card)))))
+
+;;; -------------------------------------------------- Create ------------------------------------------------------
+
+(defn- create!
+ "Run the shared REST create check stack on the resolved query and target collection, then save a
+ `metric` card. An omitted `collection_id` means the caller's personal collection."
+ [{:keys [name description display collection_position] :as args} session-id]
+ (let [dataset-query (or (resolve-definition args session-id)
+ (common/throw-teaching-error
+ "Pass the metric's query: `definition` (inline) or `query_handle` (from an execute tool)."))
+ collection-id (v2.resolve/resolve-collection-id-or-personal (:collection_id args))]
+ (check-metric-shape! dataset-query)
+ (queries/check-allowed-to-create-card! {:dataset_query dataset-query :collection_id collection-id} :metric)
+ (-> (queries/create-card!
+ (u/remove-nils
+ {:name name
+ :type :metric
+ :dataset_query dataset-query
+ ;; REST requires both on create, so an omitted `display` falls back to the app's default
+ ;; for a single aggregation rather than being left off the insert.
+ :display (if display (keyword display) default-display)
+ :visualization_settings {}
+ :description description
+ :collection_id collection-id
+ :collection_position collection_position})
+ {:id api/*current-user-id*})
+ write-result)))
+
+;;; -------------------------------------------------- Update ------------------------------------------------------
+
+(defn- check-is-metric!
+ "Refuse to write a metric's contract onto a question or model, so a caller can't retype a card by
+ addressing it with the wrong tool."
+ [card]
+ (when-not (= :metric (:type card))
+ (common/throw-teaching-error
+ (format "Card %d is a %s, not a metric — use question_write to update it."
+ (:id card) (name (:type card))))))
+
+(defn- update!
+ "Write-check the existing metric, patch only the caller-supplied fields, then run the shared REST
+ update check stack before persisting. A `definition`/`query_handle` re-runs the metric shape
+ gate; omitting both leaves the stored query untouched."
+ [id {:keys [name description display collection_position archived] :as args} session-id]
+ (let [card-before (v2.resolve/resolve-and-read-with
+ :model/Card id
+ ;; Hydrated like PUT /api/card/:id hydrates it: `update-card!` un-verifies a
+ ;; verified card whose query changes by reading `:moderation_reviews` off the
+ ;; card-before, and a bare row would leave the Verified badge on a swapped
+ ;; definition.
+ (fn [cid] (mcp.db/hydrate-moderation-reviews (api/write-check :model/Card cid))))
+ _ (check-is-metric! card-before)
+ card-id (:id card-before)
+ new-query (resolve-definition args session-id)
+ _ (some-> new-query check-metric-shape!)
+ new-coll-id (when (contains? args :collection_id)
+ (v2.resolve/resolve-collection-id (:collection_id args)))
+ raw-updates (cond-> {}
+ (contains? args :name) (assoc :name name)
+ (contains? args :description) (assoc :description description)
+ (contains? args :display) (assoc :display (keyword display))
+ (contains? args :collection_id) (assoc :collection_id new-coll-id)
+ (contains? args :collection_position) (assoc :collection_position collection_position)
+ (contains? args :archived) (assoc :archived (boolean archived))
+ new-query (assoc :dataset_query new-query))
+ card-updates (api/updates-with-archived-directly card-before raw-updates)]
+ (when-some [query (:dataset_query card-updates)]
+ (queries/check-no-save-cycle! card-id query))
+ (queries/check-allowed-to-update-card! card-before card-updates)
+ (queries/update-card! {:card-before-update card-before
+ :card-updates card-updates
+ :actor @api/*current-user*
+ :delete-old-dashcards? false})
+ (write-result (mcp.db/select-one-by-id :model/Card card-id))))
+
+;;; -------------------------------------------------- The tool ----------------------------------------------------
+
+(def ^:private metric-write-args-schema
+ [:map {:closed true}
+ [:method
+ [:enum {:description (str "\"create\" makes a new metric (requires `name` and one query source); "
+ "\"update\" edits the one named by `id`.")}
+ "create" "update"]]
+ [:id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the metric to update."}]
+ [:string {:description "21-character entity_id of the metric to update."}]]]]
+ [:name {:optional true}
+ [:maybe [:string {:min 1 :description "Create only (editable on update): display name of the metric."}]]]
+ [:definition {:optional true}
+ [:maybe [:map {:description (str "The metric's query: a full single-stage query holding exactly one aggregation "
+ "and at most one breakout. Accepts the same numeric-id shape get_content's "
+ "\"definition\" include returns for a metric and execute_query takes. "
+ "Pass this or query_handle, not both.")}]]]
+ [:query_handle {:optional true}
+ [:maybe [:string {:min 1 :description (str "A query_handle from execute_query — saves exactly the query "
+ "that ran. Pass this or definition, not both.")}]]]
+ [:description {:optional true}
+ [:maybe [:string {:description "Optional human-readable description."}]]]
+ [:display {:optional true}
+ [:maybe (into [:enum {:description
+ (str "How the metric's result is visualized. Defaults to \"scalar\" — right for a "
+ "single number, wrong for a metric with a grouping, which usually wants "
+ "\"line\" (a grouping over time) or \"bar\" (a grouping over categories). "
+ "Editable on update.")}]
+ accepted-displays)]]
+ [:collection_id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the collection to save the metric in."}]
+ [:string {:description
+ "21-character entity_id of the collection, or \"root\" for the root collection."}]]]]
+ [:collection_position {:optional true}
+ [:maybe [:int {:min 1 :description "Pins the metric at this position in its collection."}]]]
+ [:clear {:optional true}
+ [:maybe [:sequential [:enum {:description
+ (str "Update only: property names to unset (description, collection_position). "
+ "Needed because a null cannot say \"clear this\" — strict clients fill "
+ "every unset property with null, so nulls are stripped at the boundary.")}
+ "description" "collection_position"]]]]
+ [:archived {:optional true}
+ [:maybe [:boolean {:description (str "Update only: true moves the metric to the trash, false restores it. "
+ "Archiving is the only removal path — there is no hard delete.")}]]]])
+
+(def ^:private metric-write-entry
+ {:create-required [:name]
+ :clearable #{:description :collection_position}})
+
+(registry/deftool metric-write
+ "Create or update a metric: a saved, reusable aggregation that lives in a collection and can be queried on its own
+ or referenced from other queries. A metric is not a measure — a measure belongs to one table and is only usable
+ inside a query against that table, while a metric is standalone content. method: \"create\" requires name and one
+ query source; method: \"update\" requires id and accepts archived (true trashes, false restores — there is no hard
+ delete). Pass the query as definition (a full single-stage query in the same numeric-id shape execute_query
+ takes and get_content's \"definition\" include returns) or as a query_handle from
+ execute_query — one or the other, not both. The query must have exactly one aggregation (count, sum, average…) and
+ at most one grouping; anything else is a teaching error, so build it with execute_query first. Native
+ SQL cannot be a metric — save it with question_write. Optional: description, display (how the result is visualized;
+ defaults to \"scalar\", so a metric with a grouping usually wants \"line\" or \"bar\"), collection_id (omit to save
+ to your personal collection; pass \"root\" for the root collection), collection_position to pin. Updating a card that is a
+ question or a model is refused rather than retyping it. Requires write permission on the metric and curate
+ permission on the target collection."
+ {:name "metric_write"
+ :scope metabot.scope/agent-content-write
+ ;; `archived: true` trashes the metric, so this is not the additive-only update
+ ;; `destructiveHint false` would assert (matches collection_write).
+ :annotations {:readOnlyHint false :destructiveHint true}
+ :args metric-write-args-schema}
+ [args {:keys [token-scopes session-id]}]
+ (let [dispatched (v2.write/dispatch-write metric-write-entry args)
+ payload (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (case (first dispatched)
+ :create
+ (let [[_ body] dispatched]
+ (doseq [k [:id :archived]]
+ (when (contains? body k)
+ (common/throw-teaching-error
+ (format (str "`%s` applies to method \"update\" only — "
+ "remove it from this create call.")
+ (name k)))))
+ (create! (dissoc body :id) session-id))
+
+ :update
+ (let [[_ id body] dispatched]
+ (update! id body session-id)))
+ nil)]
+ ;; text-only, matching the stack convention (see common/success-content): the write echo has no
+ ;; concrete programmatic consumer, so it doesn't ride structuredContent.
+ (common/success-content payload)))
diff --git a/src/metabase/mcp/v2/tools/parameters.clj b/src/metabase/mcp/v2/tools/parameters.clj
new file mode 100644
index 00000000000..77817df1dab
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/parameters.clj
@@ -0,0 +1,433 @@
+(ns metabase.mcp.v2.tools.parameters
+ "The v2 MCP `get_parameter_values` tool: the valid values behind a dashboard or question filter.
+
+ It can't ride `get_content` as an include — it takes its own arguments (a parameter id, a
+ prefix `query`, chain-filter `constraints`) — so it is its own tool. Read permission on the
+ dashboard or card is the whole gate: a caller who can read it can look up its filter values
+ without query permission on the underlying table, and sandboxing still narrows the values
+ themselves.
+
+ Both object-dependent arguments are checked against the resolved object before any values are
+ fetched. An unknown `parameter_id` answers with the ids that do exist. A `constraints` key is
+ rejected — rather than silently dropped — when it names no dashboard parameter, when it names
+ one that resolves to no queryable field (chain filtering can't use it), when its field has no FK
+ join path to the target parameter's table (chain filtering would ignore it), or when the target
+ parameter draws its values from a fixed list or a card (a source that never consults
+ constraints). A dropped constraint would hand back values the agent believes were filtered.
+
+ Scope note: this is content-read (`agent:content:read`), NOT the `agent:sql:run` + kill switch
+ that the native-query source in `question_write` carries — deliberately. Fetching values does run
+ warehouse queries under the hood, but only Metabase-generated MBQL over the object's own fields or
+ the object's *stored* (already-read-checked) values-source card; it never executes caller-supplied
+ SQL.
+
+ That holds only while every caller-supplied value stays a value. `constraints` is compiled into
+ the chain-filter query, so a value shaped like an MBQL clause used to be compiled as one — which
+ let a caller with no query permission at all compare two columns and read the rows that matched.
+ [[::constraint-value]] is what keeps the claim above true; widening it reopens that path."
+ (:require
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.parameters.chain-filter :as chain-filter]
+ [metabase.parameters.dashboard :as parameters.dashboard]
+ [metabase.parameters.field :as parameters.field]
+ [metabase.parameters.params :as params]
+ [metabase.queries.core :as queries]
+ [metabase.query-processor.middleware.permissions :as qp.perms]
+ [metabase.query-processor.parameters.dates :as params.dates]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.util.malli.registry :as mr]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private default-limit 100)
+
+;; The backends cap at 1000 (`parameters.dashboard/result-limit`, `custom-values/*max-rows*`), so
+;; a limit above it could never be filled.
+(def ^:private max-limit 1000)
+
+;;; ------------------------------------------------ Parameter lookup ----------------------------------------------
+
+(defn- parameter-catalog
+ "The `id (name)` list a teaching error names when a parameter id doesn't match."
+ [params]
+ (or (not-empty
+ (str/join ", " (map (fn [{param-id :id param-name :name}]
+ (cond-> (u/qualified-name param-id)
+ (not (str/blank? param-name)) (str " (" param-name ")")))
+ params)))
+ "none"))
+
+(defn- check-parameter-id!
+ [target parameter-id params]
+ (when-not (some #(= parameter-id (u/qualified-name (:id %))) params)
+ (common/throw-teaching-error
+ (format "This %s has no parameter %s — pass one of its parameter ids (get_content returns them under `parameters`). Available: %s."
+ target (pr-str parameter-id) (parameter-catalog params)))))
+
+(defn- card-parameters
+ "A card's parameters, falling back to its native query's template tags viewed as parameters."
+ [card]
+ (or (seq (:parameters card))
+ (queries/card-template-tag-parameters card)))
+
+;;; --------------------------------------------------- Fetching ---------------------------------------------------
+
+(defn- temporal-field?
+ "Whether `add-filter` would treat `field-id` as temporal — it tests the Lib column's effective type,
+ which `lib-be/instance->metadata` carries over from the Field's `effective_type` (`base_type` when
+ unset)."
+ [field-id]
+ (let [{:keys [base_type effective_type]} (mcp.db/field-types field-id)]
+ (isa? (or effective_type base_type) :type/Temporal)))
+
+(defn- parses-as-date?
+ "Whether `value` yields a date filter for `field-id`. Runs the same call `add-filter` makes, so this
+ can't disagree with it about what parses."
+ [value field-id]
+ (try
+ (some? (params.dates/date-string->filter value field-id))
+ (catch Throwable _ false)))
+
+(defn- check-constraints!
+ "Reject a constraints key that chain filtering would silently drop rather than apply — so the
+ caller never gets unnarrowed values believing they were filtered. Four drop paths:
+ the key names no dashboard parameter; it resolves to no queryable field (unmapped, or mapped
+ only via field-refs or a SQL text variable); its field has no FK join path to the target
+ parameter's field within chain filtering's traversal limit; or its value is a string on a
+ temporal field that won't parse as a date.
+
+ The join-path check must match what fetching actually does. `parameters.dashboard/param-values`
+ runs a SEPARATE `chain-filter` per target field-id and UNIONS the resulting values, passing the
+ constraints to every run; `add-filters` silently drops a constraint on any run whose source table
+ can't reach the constraint's field. So a single unreachable target field-id leaks its own
+ unnarrowed values into the union. Honesty therefore requires the constraint be reachable from
+ EVERY target field-id, not merely some — reachability from one field is not enough when another
+ field's run drops the filter and contributes unfiltered values. We probe each target field-id with
+ `chain-filter/filterable-field-ids` (which builds the same query the fetch will) and reject unless
+ the constraint survives on all of them.
+
+ `target-param` is the parameter whose values are being fetched; `resolved-params` is the
+ dashboard's full parameter map."
+ [target-param resolved-params constraints]
+ ;; First reject the two per-key problems (unknown key, no queryable field) — these must run before
+ ;; any field resolution, since an unknown key has no param to resolve fields from.
+ (doseq [param-key (keys constraints)]
+ (let [param (get resolved-params param-key)]
+ (cond
+ (nil? param)
+ (common/throw-teaching-error
+ (format "This dashboard has no parameter %s — each constraints key names another of its filters and the value is that filter's current selection. Available: %s."
+ (pr-str param-key) (parameter-catalog (vals resolved-params))))
+
+ (empty? (params/dashboard-param->field-ids param))
+ (common/throw-teaching-error
+ (format "Constraint %s can't narrow this filter — it isn't mapped to a queryable field, so chain filtering would silently ignore it. Drop it from constraints."
+ (pr-str param-key))))))
+ ;; Every constraint now maps to a field. Compute, per target field-id, which constraint fields are
+ ;; reachable from it; a constraint is honestly applied only when reachable from EVERY target field-id
+ ;; (see the docstring — the fetch unions per-field runs and drops the filter on any run that can't
+ ;; reach it). `filterable-field-ids` builds the same query add-filters runs, so this can't diverge.
+ (let [target-field-ids (params/dashboard-param->field-ids target-param)
+ constraint-field-ids (into #{} (mapcat #(params/dashboard-param->field-ids (get resolved-params %)))
+ (keys constraints))
+ ;; Intersect the reachable sets across target fields: a constraint field is kept only if every
+ ;; target field-id's run can reach it. (One target field-id degenerates to that field's set.)
+ reachable-everywhere (transduce (map #(chain-filter/filterable-field-ids % constraint-field-ids))
+ (completing (fn [acc s] (if acc (set/intersection acc s) s)))
+ nil
+ target-field-ids)]
+ (doseq [param-key (keys constraints)]
+ (when (empty? (set/intersection (params/dashboard-param->field-ids (get resolved-params param-key))
+ (or reachable-everywhere #{})))
+ (common/throw-teaching-error
+ (if (empty? target-field-ids)
+ ;; No target fields at all: chain filtering falls back to `filter-values-from-field-refs`,
+ ;; which ignores constraints outright. Blaming the join path would misdiagnose it.
+ (format "This parameter's values come from a card's own column rather than a queryable field, so constraints can't narrow it — chain filtering would silently ignore %s. Fetch without constraints."
+ (pr-str param-key))
+ (format "Constraint %s can't narrow this filter — its field has no join path to this parameter's table (or reaches only some of the fields it maps to), so chain filtering would silently ignore it. Drop it from constraints."
+ (pr-str param-key)))))))
+ ;; The last drop path is in the value rather than the field: `add-filter` routes a string value on a
+ ;; temporal field through `date-string->filter` and catches a parse failure into a dropped filter.
+ (doseq [[param-key value] constraints
+ :when (string? value)
+ field-id (params/dashboard-param->field-ids (get resolved-params param-key))
+ :when (temporal-field? field-id)]
+ (when-not (parses-as-date? value field-id)
+ (common/throw-teaching-error
+ (format "Constraint %s is a date filter, and %s isn't a date it can parse — chain filtering would silently ignore it. Pass a day (\"2024-01-31\"), a range (\"2024-01-01~2024-03-31\"), or a relative window (\"past30days\", \"thismonth\")."
+ (pr-str param-key) (pr-str value))))))
+
+(def ^:private no-values
+ {:values [] :has_more_values false})
+
+(def ^:private date-accepts
+ "The grammar a date parameter's value is written in. Templates rather than sample dates: the
+ concrete dates of the column are `min` and `max`, and a caller that confuses an example for a
+ bound filters on the wrong day. One list covers every date subtype — the QP runs the whole
+ decoder set no matter which one the parameter declares, so the subtype narrows the widget
+ rather than what the API accepts."
+ ["YYYY-MM-DD" "YYYY-MM-DD~YYYY-MM-DD" "past30days" "thisyear"])
+
+(defn- range-shaped-date-param?
+ "Whether this parameter's values should come back as a range rather than a list. True for a date
+ parameter drawing values from a column, where the distinct dates are pages of noise and the
+ useful answer is the span they cover. A date parameter with a static-list or card source is
+ excluded: those dates are a curated set to pick from, and a range would throw the set away."
+ [param]
+ (and (nil? (:values_source_type param))
+ (some-> (:type param) keyword params.dates/date-type?)))
+
+(defn- valueless-dashboard-param?
+ "True when a dashboard filter has nothing behind it to fetch values from: no values source, and no
+ dashcard mapping to supply a field. Chain filtering has nothing to query in that case."
+ [param]
+ (and (nil? (:values_source_type param))
+ (empty? (:mappings param))))
+
+(defn- valueless-card-param?
+ "True when a card parameter has nothing behind it to fetch values from: no values source, and no
+ field under its target. A free-text template tag is the common case."
+ [card param]
+ (and (nil? (:values_source_type param))
+ (nil? (params/param-target->field-id (:target param) card))))
+
+(defn- check-no-query-for-range!
+ "A range has nothing to search: `query` narrows a list of values by text, and the answer here is two
+ dates and a grammar. Silently ignoring it would hand back the column's whole span as though it had
+ been narrowed."
+ [query]
+ (when query
+ (common/throw-teaching-error
+ "This is a date parameter, so it answers with its column's range rather than a list of values — there is no list for `query` to search. Drop `query` and filter within the `min`/`max` it returns, using the forms in `accepts`.")))
+
+(defn- fetch-dashboard-values
+ "The value list for a dashboard parameter. `*param-values-query*` is what lets a caller who can read
+ the dashboard look up its filter values without query permission on the underlying table. The
+ search path additionally pins remapping to the field actually being filtered (#59020)."
+ [dash parameter-id query constraints]
+ (binding [qp.perms/*param-values-query* true]
+ (if query
+ (binding [chain-filter/*allow-implicit-uuid-field-remapping* false]
+ (parameters.dashboard/param-values dash parameter-id constraints query))
+ (parameters.dashboard/param-values dash parameter-id constraints))))
+
+(defn- dashboard-values
+ [id-or-eid parameter-id query constraints]
+ (let [dash (-> (v2.resolve/resolve-and-read :model/Dashboard id-or-eid)
+ (t2/hydrate :resolved-params))
+ resolved-params (:resolved-params dash)
+ constraints (update-keys constraints u/qualified-name)
+ param (get resolved-params parameter-id)]
+ (check-parameter-id! "dashboard" parameter-id (vals resolved-params))
+ ;; A static-list or card values source never consults the chain-filter constraints, so applying
+ ;; them would silently do nothing — reject rather than hand back a list the caller thinks was
+ ;; narrowed.
+ (when (and (seq constraints) (some? (:values_source_type param)))
+ (common/throw-teaching-error
+ "This parameter's values come from a fixed list or a card, not a chain-filterable field, so constraints can't narrow it — fetch without constraints."))
+ (check-constraints! param resolved-params constraints)
+ (cond
+ ;; Chain filtering raises on an unmapped parameter; an empty value list is the honest answer,
+ ;; and the one target "question" gives for the same shape of parameter.
+ (valueless-dashboard-param? param)
+ no-values
+
+ (range-shaped-date-param? param)
+ (do
+ (check-no-query-for-range! query)
+ ;; `param-range` answers nil for a parameter mapped only by field-ref, which has no column to
+ ;; aggregate — listing its values is then the only answer available.
+ (or (some-> (binding [qp.perms/*param-values-query* true]
+ (parameters.dashboard/param-range dash parameter-id constraints))
+ (assoc ::date-range true))
+ (fetch-dashboard-values dash parameter-id query constraints)))
+
+ :else
+ (fetch-dashboard-values dash parameter-id query constraints))))
+
+(defn- question-values
+ [id-or-eid parameter-id query]
+ (let [card (v2.resolve/resolve-and-read :model/Card id-or-eid)
+ params (card-parameters card)]
+ (check-parameter-id! "question" parameter-id params)
+ (let [param (some #(when (= parameter-id (u/qualified-name (:id %))) %) params)]
+ ;; `card-param-values` answers nil for a valueless parameter, which its own output schema
+ ;; rejects — so the tool decides this case rather than calling and catching.
+ (cond
+ (valueless-card-param? card param)
+ no-values
+
+ ;; Field-backed source (no `values_source_type`): `card-param-values` would route to
+ ;; `search-values-from-field-id`, which lies to an agent two ways — it reports
+ ;; `has_more_values false` even when the fetch fills its 1000-row cap (a truncated list read as
+ ;; complete), and it swallows a fetch error into `[]` (a warehouse/sandbox failure read as "no
+ ;; values"). The strict variant reports a truthful floor at the cap and lets the error surface as
+ ;; an isError, matching the dashboard path. Static-list and card sources already report
+ ;; `has_more_values` truthfully, so they keep the normal path.
+ (nil? (:values_source_type param))
+ (let [field-id (params/param-target->field-id (:target param) card)]
+ (if (range-shaped-date-param? param)
+ (do
+ (check-no-query-for-range! query)
+ (-> (binding [qp.perms/*param-values-query* true]
+ (chain-filter/chain-filter-range field-id nil))
+ (assoc ::date-range true)))
+ (binding [qp.perms/*param-values-query* true]
+ (parameters.field/search-values-from-field-id-strict field-id query))))
+
+ :else
+ (binding [qp.perms/*param-values-query* true]
+ (queries/card-param-values card parameter-id query))))))
+
+;;; --------------------------------------------------- Response ---------------------------------------------------
+
+(defn- steering-line
+ "The sentence appended when the page isn't the whole story. `total` is what the backend
+ returned; `more?` marks it as a floor — the source held more than the backend's 1000-row cap.
+ `query` is the caller's search, when there was one: an empty result means something different
+ with a search in hand, and the recovery it points at is different too."
+ [{:keys [returned total more? offset limit query]}]
+ (cond
+ (and (zero? total) query)
+ (format "No values match %s — try a shorter or less specific search, or omit `query` to list every value."
+ (pr-str query))
+
+ (zero? total)
+ "No values available for this parameter — its source may be empty, filtered to nothing for you, or a free-text filter with no value list."
+
+ (zero? returned)
+ (if more?
+ (format "No values at offset %d — the source stopped at %d before returning everything; narrow with `query` rather than paging further."
+ offset total)
+ (format "No values at offset %d — %d available." offset total))
+
+ :else
+ (or (common/truncation-line {:param :query :offset offset :limit limit :returned returned
+ :total total :total-floor? more?})
+ (when more?
+ (format "Returned %d — the source holds more values than it will return; narrow with `query` to reach the rest."
+ returned)))))
+
+(defn- values-content
+ "Slice `limit`/`offset` out of the backend's value list and render the response. `has_more_values`
+ stays true when the slice dropped values, not only when the backend hit its own cap — a page is
+ never reported as the whole set."
+ [{:keys [values has_more_values]} limit offset query]
+ (let [values (vec values)
+ total (count values)
+ page (if (< offset total)
+ (subvec values offset (min total (+ offset limit)))
+ [])
+ payload {:values page
+ :returned (count page)
+ :has_more_values (boolean (or has_more_values (< (+ offset (count page)) total)))}
+ line (steering-line {:returned (count page) :total total :more? (boolean has_more_values)
+ :offset offset :limit limit :query query})]
+ (common/success-content (cond-> (json/encode payload)
+ line (str "\n" line)))))
+
+(defn- ->day
+ "The `YYYY-MM-DD` day of one fetched value, or nil when it isn't date-shaped. A timestamp column
+ yields its values with a time part (`2013-01-03T00:00:00Z`), and handing those back would
+ contradict the `YYYY-MM-DD` grammar in the same response. Truncating is safe at both ends
+ because a day bound is inclusive: the day holding the earliest value is still a floor under it,
+ and the day holding the latest is still a ceiling over it."
+ [value]
+ (some->> value str not-empty (re-find #"^\d{4}-\d{2}-\d{2}")))
+
+(defn- date-range-content
+ "Render a date parameter as the span its column covers plus the grammar to write a value in. The
+ span comes from an aggregation over the whole column, so `max` is the column's last date rather
+ than the last of a capped page — the reason this path doesn't reuse the value list."
+ [{:keys [distinct-count] lo :min hi :max}]
+ (let [payload (cond-> {:kind "date"
+ :min (->day lo)
+ :max (->day hi)
+ :accepts date-accepts}
+ ;; Absent for a parameter mapped to several columns, whose distinct values only a
+ ;; union could count. Omitted rather than guessed at.
+ distinct-count (assoc :distinct_dates distinct-count))
+ line (when-not (->day lo)
+ "No dates available for this parameter — its column may be empty, or filtered to nothing for you.")]
+ (common/success-content (cond-> (json/encode payload)
+ line (str "\n" line)))))
+
+;;; --------------------------------------------------- The tool ---------------------------------------------------
+
+(mr/def ::constraint-scalar
+ "One filter selection: a literal the chain filter binds as a value."
+ [:or :string :int :double :boolean])
+
+(mr/def ::constraint-value
+ "A filter's current selection — one literal, or several for a multi-select.
+
+ Deliberately narrow, and the narrowness is the security boundary rather than tidiness. Chain
+ filtering compiles these into MBQL, so a value shaped like a clause is compiled as one:
+ `[[\"field\" 49 nil]]` becomes a reference to that column and the server compares one column
+ against another, handing back the rows where they match. That reads data the caller may hold no
+ query permission for — this tool runs its lookups under `*param-values-query*` precisely so a
+ caller who can only READ a dashboard can still see its filter values — and it reaches columns
+ marked `visibility_type: sensitive`, which exist to be unreachable. A name-shaped reference
+ (`[[\"field\" {\"base-type\" \"type/Integer\"} \"CATEGORY_ID\"]]`) does the same without needing a
+ field id.
+
+ Accepting only scalars and sequences of scalars refuses every clause shape at the boundary, before
+ anything is compiled — rather than blacklisting the clause forms known today.
+ `constraints-value-must-not-name-a-column-test` pins it."
+ [:or ::constraint-scalar [:sequential ::constraint-scalar]])
+
+(def ^:private get-parameter-values-args-schema
+ [:map {:closed true}
+ [:target [:enum {:description "Whether id names a dashboard or a card. \"question\" covers any card — question, model, or metric."}
+ "dashboard" "question"]]
+ [:id [:or
+ [:int {:description "Numeric id."}]
+ [:string {:min 1 :description "A 21-character entity_id."}]]]
+ [:parameter_id
+ [:string {:min 1 :description "The parameter's id, as returned by get_content under `parameters` — not its name or slug."}]]
+ [:query {:optional true}
+ [:maybe [:string {:min 1 :description "Return only values matching this search string. Use it to narrow a large value list."}]]]
+ [:constraints {:optional true}
+ [:maybe [:map-of {:description "Chain filtering: the current selections of the dashboard's OTHER filters, keyed by their parameter ids, narrowing this filter to the values still valid alongside them. Dashboards only."}
+ :keyword ::constraint-value]]]
+ [:limit {:optional true}
+ [:maybe [:int {:min 1 :max max-limit :description "Maximum values to return in this call (default 100, max 1000)."}]]]
+ [:offset {:optional true}
+ [:maybe [:int {:min 0 :description "Index of the first value to return (default 0) — continue a truncated response. Each page refetches from the source, which returns at most 1000 values, so narrow with `query` rather than paging to reach anything past that."}]]]])
+
+(registry/deftool get-parameter-values
+ "Fetch the valid values for one filter on a dashboard or saved question, so you filter with real values instead of guessing. Pass target (\"dashboard\" or \"question\" — the latter accepts any card id: question, model, or metric), id (numeric or 21-char entity_id), and parameter_id from get_content's `parameters` (each lists id, name, type). Values come back as [value] pairs, or [value, display_label] when the column is remapped — filter with the first element, show the second. query searches a large list rather than paging it; constraints (dashboards only) chain-filters — pass the other filters' current selections keyed by parameter id to get only the values still valid alongside them. Paged with limit (default 100, max 1000) and offset. A parameter with nothing behind it (e.g. a free-text template tag) returns no values. A column-backed date parameter answers with its range instead of a value list — {kind: \"date\", min, max, distinct_dates, accepts} — where accepts is the grammar to write a value in (\"YYYY-MM-DD\", \"YYYY-MM-DD~YYYY-MM-DD\", \"past30days\", \"thisyear\") and min/max are the column's real first and last dates to write between. constraints narrow the range as they narrow a list; query, limit and offset don't apply to it. Pair with run_saved_question, which takes these values as its `parameters`."
+ {:name "get_parameter_values"
+ :scope metabot.scope/agent-content-read
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :args get-parameter-values-args-schema}
+ [{:keys [target id parameter_id query constraints limit offset]} _context]
+ (when (and query (str/blank? query))
+ (common/throw-teaching-error
+ "`query` is the text to match, so it can't be blank — pass a search string, or omit `query` to list every value."))
+ (when (and (seq constraints) (= target "question"))
+ (common/throw-teaching-error
+ "`constraints` chain-filters a dashboard's filters against each other, so it needs target: \"dashboard\" — a question's parameters are independent and take none."))
+ (let [result (if (= target "dashboard")
+ (dashboard-values id parameter_id query constraints)
+ (question-values id parameter_id query))
+ ;; The card path still answers nil when a parameter's source card was archived and its target
+ ;; has no field to fall back to; an empty value list is the honest answer there too.
+ result (or result no-values)]
+ (if (::date-range result)
+ ;; `limit`/`offset` are dropped rather than applied: the range is one object, not a page of a
+ ;; list, and `kind` is what tells the caller its paging arguments had nothing to page.
+ (date-range-content result)
+ (values-content result
+ (or limit default-limit)
+ (or offset 0)
+ query))))
diff --git a/src/metabase/mcp/v2/tools/query.clj b/src/metabase/mcp/v2/tools/query.clj
new file mode 100644
index 00000000000..88ab5504f88
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/query.clj
@@ -0,0 +1,652 @@
+(ns metabase.mcp.v2.tools.query
+ "The v2 MCP query-execution tools.
+
+ `execute_query`: one surface where v1 shipped three (`construct_query` + `query` +
+ `execute_query`). A fresh MBQL 5 `query` — numeric ids, with the portable name dialect
+ also accepted — runs the representations pipeline
+ (validate → repair → resolve against database metadata, with teaching errors); a
+ `query_handle` or `cursor` resolves through the handle store with the fresh-query guards
+ re-run. Every call mints a handle — the query that ran, less the page boundary a cursor call
+ resumed from, so what the agent saves or visualizes through it is the question rather than a
+ scroll position — and a truncated MBQL page mints a keyset `next_cursor` so the model continues
+ with one opaque string, never a hand-written keyset filter.
+
+ `execute_sql`: raw SQL in the same response envelope, gated by the `mcp-execute-sql-enabled`
+ kill switch and native-query permission. It also mints a handle on every call (including
+ `validate_only`, which replaces v1's `construct_native_query`), so saving or visualizing SQL
+ needs no separate construct step. Never a cursor: arbitrary SQL can't be rewritten with a
+ server-side keyset predicate — the server can't know whether the SQL has a total order. The
+ caller does, so truncation steers it to page the SQL itself with a keyset filter, or to narrow
+ the query / raise `row_limit`.
+
+ `run_saved_question`: a stored card by numeric id or entity_id, with parameters resolved
+ server-side against the card's own parameter list — the stored target and type always
+ apply, and a client-supplied target is ignored, so a caller can set a filter's value but
+ never repoint it at another field. No handle and no cursor: a truncated result steers the
+ caller to narrow through the card's own parameters or to raise `row_limit`."
+ (:require
+ [clojure.string :as str]
+ [medley.core :as m]
+ [metabase.agent-api.query-guards :as query-guards]
+ [metabase.api.common :as api]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.query :as v2.query]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.models.interface :as mi]
+ [metabase.query-processor.card :as qp.card]
+ [metabase.query-processor.core :as qp]
+ [metabase.query-processor.middleware.permissions :as qp.perms]
+ [metabase.util :as u]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private default-row-limit 100)
+
+(def ^:private max-row-limit 2000)
+
+;;; ------------------------------------------------ Query inputs --------------------------------------------------
+
+(defn- query-input
+ "Which of the three mutually exclusive query inputs was supplied. Runtime-enforced rather
+ than schema `oneOf` — strict MCP clients bar `oneOf` in tool input schemas."
+ [{:keys [query query_handle cursor]}]
+ (let [provided (cond-> []
+ query (conj :query)
+ query_handle (conj :query_handle)
+ cursor (conj :cursor))]
+ (when-not (= 1 (count provided))
+ (common/throw-teaching-error
+ (str "Pass exactly one of query | query_handle | cursor: `query` for a fresh "
+ "MBQL query, `query_handle` to re-run a stored query, `cursor` to continue a "
+ "truncated result.")))
+ (first provided)))
+
+(defn- resolve-input
+ "Resolve the supplied input to `{:query <serialized MBQL map> :prompt <string-or-nil>}`.
+
+ The fresh path rejects native stages up front, then runs the representations pipeline
+ (validate → repair → resolve; permission-checked, teaching errors on unknown names) and
+ serializes the resolved query. The handle and cursor paths resolve through the handle store,
+ which re-runs the native/shape/permission guards — a stored handle never grants access the
+ caller has since lost. A cursor is an ordinary handle whose stored query already embeds the
+ next-page keyset boundary, so the two resolve identically.
+
+ The fresh path strips the private keyset marker (see [[v2.query/strip-caller-keyset-markers]]):
+ it means \"this namespace minted this predicate\", so a caller must not be able to supply one. The
+ handle and cursor paths must NOT strip it — a cursor's own boundary carries it."
+ [input {:keys [query query_handle cursor prompt]} session-id]
+ (case input
+ :query
+ (do
+ (query-guards/reject-native-query! query)
+ {:query (-> (v2.queries/execute-representations-query query)
+ (get-in [:structured-output :query])
+ lib/prepare-for-serialization
+ v2.query/strip-caller-keyset-markers)
+ :prompt prompt})
+
+ (:query_handle :cursor)
+ (let [{stored :query stored-prompt :prompt}
+ (v2.queries/resolve-query-handle! session-id api/*current-user-id* (or query_handle cursor))]
+ ;; Prompts ride handle chains: a cursor page minted without an explicit `prompt` keeps
+ ;; the original request for the visualization feedback flow.
+ ;;
+ ;; Deliberately NOT stripped here: a cursor's stored query carries the marker this namespace
+ ;; minted, and [[metabase.mcp.v2.query/next-page-query]] needs it to supersede the previous
+ ;; page's predicate rather than stack a dead one beside it. The `:query` branch above is the
+ ;; one place a caller-supplied query is stripped.
+ ;;
+ ;; `POST /api/embed-mcp/drills` stores its caller-supplied query verbatim and does NOT strip,
+ ;; so a caller holding a UI credential can still land a marked filter in a drill handle and
+ ;; have it silently dropped from later pages. Accepted: reaching that needs the scoped UI
+ ;; credential, and the damage is confined to the caller's own narrowed-question reporting.
+ {:query stored :prompt (or prompt stored-prompt)})))
+
+;;; ------------------------------------------------- Execution ----------------------------------------------------
+
+(def ^:private query-passthrough-keys
+ "The only keys of an incoming query that MCP forwards to the QP. Everything else — `:middleware`,
+ `:info`, `:constraints`, and any unknown key — is MCP's to set, because the query map is
+ caller-controlled and an agent that could name its own `:info` would forge `query_execution`
+ attribution. A fresh `:query` is also rejected upstream by the closed
+ `:metabase.lib.schema/query`, but that covers only the fresh path: a handle's stored query is
+ checked shallowly and the `/drills` callback stores one verbatim, so an unknown key does reach
+ here. This whitelist, not the schema, is what the guarantee rests on. The QP strips some of
+ these itself; that is defense in depth, not this boundary's contract."
+ [:lib/type :database :stages :parameters])
+
+(defn- execute!
+ "Run a serialized MBQL query through the QP with the standard agent userland preparation,
+ capping this call's rows at `row-limit` (within the backend's 2000/10000 userland
+ ceilings). Returns the QP result; surfaces a failed run as a teaching error."
+ [serialized-query row-limit]
+ (let [result (qp/process-query
+ (-> (select-keys serialized-query query-passthrough-keys)
+ (assoc :middleware {:js-int-to-string? true})
+ qp/userland-query-with-default-constraints
+ (assoc :constraints {:max-results row-limit
+ :max-results-bare-rows row-limit}
+ :info {:executed-by api/*current-user-id*
+ :context :agent})))]
+ (when-not (= (:status result) :completed)
+ (common/throw-teaching-error (str "Query failed: " (or (:error result) "unknown error"))))
+ result))
+
+(defn- execute-page!
+ "Run `serialized-query` for one page of at most `row-limit` rows. Fetches one row past the
+ limit so truncation is *observed* rather than inferred from a full page: a result that fills
+ the page exactly is complete, and is reported that way. Returns
+ `{:cols :rows :returned :truncated?}` with the probe row already dropped, so `rows` is the
+ page and `(last rows)` is a real page boundary."
+ [serialized-query row-limit]
+ (let [result (execute! serialized-query (inc row-limit))
+ all-rows (vec (get-in result [:data :rows]))
+ truncated? (> (count all-rows) row-limit)
+ rows (cond-> all-rows truncated? (subvec 0 row-limit))]
+ {:cols (get-in result [:data :cols])
+ :rows rows
+ :returned (count rows)
+ :truncated? truncated?}))
+
+(defn- last-stage
+ [serialized-query]
+ (peek (vec (:stages serialized-query))))
+
+(defn- aggregated-last-stage?
+ [serialized-query]
+ (let [stage (last-stage serialized-query)]
+ (boolean (or (seq (:aggregation stage))
+ (seq (:breakout stage))))))
+
+(defn- remaining-rows
+ "Rows still owed by the query's own last-stage limit once `returned` of them have been served,
+ or nil when the query carries no limit of its own. That limit bounds the whole result set, so
+ paging has to spend it down across pages rather than reapply it to each one."
+ [serialized-query returned]
+ (when-let [limit (:limit (last-stage serialized-query))]
+ (- limit returned)))
+
+(defn- cursor-query
+ "The query the next-page cursor stores: the page's own query carrying `remaining` — the rows
+ still owed by the query's own limit — as its last-stage limit, so a `limit 500` query pages
+ to row 500 and stops there. A query that set no limit of its own stores none either: a limit
+ at this position reads as the caller's whole-result budget, so embedding the page size there
+ would make the next page look complete the moment it filled, and the chain would stop one
+ page in. Page size is `row_limit`'s job, and a cursor call takes it like any other. An
+ aggregated last stage is passed through unchanged — an embedded limit there would cut the
+ base set before the keyset order can pin it down, and
+ [[metabase.mcp.v2.query/next-page-cursor!]] would rightly refuse to mint."
+ [serialized-query remaining]
+ (if (or (nil? remaining) (aggregated-last-stage? serialized-query))
+ serialized-query
+ (assoc-in serialized-query [:stages (dec (count (:stages serialized-query))) :limit] remaining)))
+
+;;; ------------------------------------------------- Response -----------------------------------------------------
+
+(defn- response-cols
+ [cols]
+ (mapv (fn [{:keys [name base_type effective_type display_name]}]
+ (cond-> {:name name
+ :base_type (u/qualified-name base_type)
+ :display_name display_name}
+ effective_type (assoc :effective_type (u/qualified-name effective_type))))
+ cols))
+
+(defn- steering-line
+ [returned next-cursor]
+ (if next-cursor
+ (format "returned %d rows, more available — continue with `cursor`, or narrow the query (filter/aggregate)"
+ returned)
+ (format "returned %d rows, more available — narrow the query (filter/aggregate), or raise `row_limit` (max %d)"
+ returned max-row-limit)))
+
+(defn- mint-handle!
+ "Store `serialized-query` under a fresh handle for the caller, with the page boundary stripped
+ first ([[metabase.mcp.v2.query/without-page-boundary]]) — a handle is what a later tool saves or
+ visualizes, and a cursor page's keyset predicate is a scroll position rather than part of the
+ question. A no-op for a query that never paged, and paging is unaffected either way: the cursor
+ carries its own boundary."
+ [session-id serialized-query prompt]
+ (v2.queries/mint-query-handle! session-id
+ api/*current-user-id*
+ (v2.queries/encode-serialized-query
+ (v2.query/without-page-boundary serialized-query))
+ prompt))
+
+(defn- validate-only-response!
+ [session-id serialized-query prompt]
+ (let [counts {:query_handle (mint-handle! session-id serialized-query prompt)
+ :returned 0
+ :truncated false}]
+ (common/success-content
+ (str (json/encode counts)
+ "\nQuery validated, not executed — execute or save it later by passing this query_handle."))))
+
+(defn- execute-response!
+ [session-id serialized-query prompt row-limit]
+ (let [{:keys [cols rows returned truncated?]} (execute-page! serialized-query row-limit)
+ ;; `truncated?` is observed, so the query's own limit needs no separate accounting here:
+ ;; a `limit 3` query can never yield a 4th row to trip the probe. `remaining` is still
+ ;; needed to spend that limit down across cursor pages.
+ remaining (remaining-rows serialized-query returned)
+ handle (mint-handle! session-id serialized-query prompt)
+ next-cursor (when truncated?
+ (v2.query/next-page-cursor! session-id
+ api/*current-user-id*
+ (cursor-query serialized-query remaining)
+ (last rows)
+ {:result-cols cols :prompt prompt}))
+ counts (cond-> {:query_handle handle
+ :returned returned
+ :truncated truncated?}
+ next-cursor (assoc :next_cursor next-cursor))
+ payload (assoc counts
+ :cols (response-cols cols)
+ :rows rows)]
+ (common/success-content
+ (cond-> (json/encode payload)
+ truncated? (str "\n" (steering-line returned next-cursor))))))
+
+;;; -------------------------------------------------- The tool ----------------------------------------------------
+
+(def ^:private execute-query-args-schema
+ [:map {:closed true}
+ [:query {:optional true}
+ [:maybe [:map {:description "A fresh query (see the tool description): numeric table/field ids from browse_data, never base64. Exactly one of query | query_handle | cursor."}]]]
+ [:query_handle {:optional true}
+ [:maybe [:string {:min 1 :description "A query_handle from a previous call — re-validates and re-runs the exact stored query. Exactly one of query | query_handle | cursor."}]]]
+ [:cursor {:optional true}
+ [:maybe [:string {:min 1 :description "The next_cursor from a previous truncated response — fetches the next page. Exactly one of query | query_handle | cursor, but row_limit may accompany it and sets this page's size."}]]]
+ [:prompt {:optional true}
+ [:maybe [:string {:min 1 :max 10000 :description "The user's original request, stored with the minted query_handle and carried along its cursor pages."}]]]
+ [:validate_only {:optional true}
+ [:maybe [:boolean {:description "true validates against schema + database metadata and mints a query_handle without executing (default false)."}]]]
+ [:row_limit {:optional true}
+ [:maybe [:int {:min 1 :max max-row-limit :description "Maximum rows to return in this call (default 100, max 2000)."}]]]])
+
+(registry/deftool execute-query
+ "Validate and execute a query, returning rows plus a query_handle. Pass exactly one of: query (a fresh query in the dialect below), query_handle (re-run a stored query), or cursor (continue a truncated result). Every call returns a query_handle — it holds the query that ran without the cursor's paging position, so saving or visualizing from any page gives the whole question rather than that one page. validate_only: true checks against schema + database metadata and mints a handle without executing. Results are cols + rows with returned/truncated counts; on next_cursor, call again with cursor (row_limit alongside keeps the page size), otherwise narrow the query (filter/aggregate) or raise row_limit (max 2000).
+
+Dialect (JSON): tables and columns go by NUMERIC ID — discover ids first (browse_data get_fields lists every column's id) — never invent or guess ids, never base64. Top level: {\"lib/type\": \"mbql/query\", \"stages\": [...]}; each stage \"lib/type\": \"mbql.stage/mbql\" plus source-table: <numeric table id> or source-card: <numeric card id> on the FIRST stage only — later stages read the previous stage's output. Every clause is [\"op\", {}, ...args], options map mandatory at position 1. Field refs: [\"field\", {}, <numeric field id>], or a bare column-name string against a previous stage ([\"field\", {}, \"count\"]). Stage keys: filters, aggregation, breakout, expressions, fields, joins, order-by, limit. Simplest aggregate (row count of one table): {\"lib/type\": \"mbql/query\", \"stages\": [{\"lib/type\": \"mbql.stage/mbql\", \"source-table\": <TABLE_ID>, \"aggregation\": [[\"count\", {}]]}]}. Example (row count by month): {\"lib/type\": \"mbql/query\", \"stages\": [{\"lib/type\": \"mbql.stage/mbql\", \"source-table\": <TABLE_ID>, \"aggregation\": [[\"count\", {}]], \"breakout\": [[\"field\", {\"temporal-unit\": \"month\"}, <FIELD_ID>]]}]}. <TABLE_ID> and <FIELD_ID> are placeholders — ids differ per instance, so resolve yours with browse_data before calling. get_content's definition include returns queries in this same shape, so an edited definition can be sent back as-is. Call learn(\"query-dialect\") before authoring a non-trivial query (joins, expressions, multi-stage); learn(\"query-dialect\", \"operators\") lists every operator. Use this, not execute_sql, for any card bound for a filtered dashboard — MBQL cards wire to dashboard filters as-is, raw-SQL cards need template tags first. Native SQL is rejected at any depth — use execute_sql."
+ {:name "execute_query"
+ :scope metabot.scope/agent-query-run
+ :annotations {:readOnlyHint true}
+ :args execute-query-args-schema}
+ [{:keys [validate_only row_limit] :as args} {:keys [session-id]}]
+ (let [input (query-input args)
+ {resolved :query prompt :prompt} (resolve-input input args session-id)
+ ;; The total order goes on before the query runs, not when the cursor is minted: a page
+ ;; is continuable only if it was served in the order the keyset seeks past. Handles are
+ ;; minted from this query, so what a later call re-runs is what ran here.
+ serialized-query (v2.query/with-total-order resolved)]
+ (if (true? validate_only)
+ (validate-only-response! session-id serialized-query prompt)
+ (execute-response! session-id serialized-query prompt (or row_limit default-row-limit)))))
+
+;;; ------------------------------------------------ execute_sql ---------------------------------------------------
+
+(defn- check-execute-sql-gates!
+ "The execute_sql pre-checks, in order: the `mcp-execute-sql-enabled` kill switch, the
+ collapsed not-found for a database the caller can't see (identical for \"doesn't exist\" and
+ \"exists but unreadable\", so the response never forms an existence oracle), then native-query
+ permission. The permission error is only reachable for a database the caller can already
+ browse — native permission implies `can-read?` — so its distinct message discloses nothing.
+ All three run on the execute AND `validate_only` paths — a handle minted without them would
+ make `validate_only` a kill-switch bypass and a native-permission oracle. Running them on
+ `validate_only` is a deliberate tightening over v1's `construct_native_query`, which only
+ read-checked the database. They run at the tool layer (the QP permissions middleware
+ re-checks inside `process-query`) so a refusal short-circuits before any query machinery
+ spins up."
+ [database-id]
+ (v2.queries/check-execute-sql-enabled! "execute_sql")
+ (when-not (mi/can-read? :model/Database database-id)
+ (common/throw-not-found :model/Database database-id))
+ (when-not (qp.perms/current-user-has-adhoc-native-query-perms? {:database database-id})
+ (throw (ex-info "You do not have permission to run native queries against this database."
+ {:status-code 403 :database_id database-id}))))
+
+(defn- value->tag-type
+ "The template-tag (and parameter) type for a supplied binding value, from its JSON type. The
+ tag type drives the QP's value parsing, so a number value must flip the extracted tag's
+ default `:text` to `:number` to bind as a numeric prepared-statement parameter."
+ [value]
+ (cond
+ (number? value) :number
+ (boolean? value) :boolean
+ :else :text))
+
+(defn- bind-template-tag-values
+ "Bind `template-tag-values` into `query` (a live lib native query whose `{{tag}}` occurrences
+ are already extracted as `:text` tag declarations). Returns
+ `{:query <query with retyped tags> :parameters <parameter list>}` — the parameters ride
+ outside the query because [[metabase.lib.core/prepare-for-serialization]] strips
+ `:parameters` at every level as runtime-only; the caller re-attaches them top-level after
+ serializing, where the QP's parameter middleware picks them up and compiles them to
+ driver-level prepared-statement bind params. A name with no matching `{{tag}}` in the SQL
+ is a teaching error, as is naming a snippet or card-reference tag — those splice
+ server-side SQL text, never caller values."
+ [query template-tag-values]
+ (let [tags (lib/template-tags query)
+ by-name (m/index-by :name tags)
+ bindings (mapv (fn [[k value]]
+ (let [tag-name (u/qualified-name k)
+ {tag-type :type :as tag} (get by-name tag-name)]
+ (cond
+ (nil? tag)
+ (common/throw-teaching-error
+ (format "No {{%s}} template tag in the SQL — template_tag_values keys must name a {{tag}} placeholder that appears in sql. Tags found: %s."
+ tag-name
+ (if-let [names (seq (map :name tags))]
+ (str/join ", " names)
+ "none")))
+
+ (contains? #{:card :snippet} tag-type)
+ (common/throw-teaching-error
+ (format "{{%s}} is a %s-reference tag — it splices server-side SQL text and cannot be populated through template_tag_values, which binds only plain {{tag}} variables."
+ tag-name (name tag-type)))
+
+ :else
+ {:tag (assoc tag :type (value->tag-type value)) :value value})))
+ template-tag-values)]
+ {:query (lib/with-template-tags query (mapv :tag bindings))
+ :parameters (mapv (fn [{:keys [tag value]}]
+ {:type (:type tag)
+ :target [:variable [:template-tag (:name tag)]]
+ :value value})
+ bindings)}))
+
+(defn- sql-steering-line
+ [returned]
+ ;; The keyset hint is execute_sql's alone. The MBQL dead end it mirrors is the fan-out join,
+ ;; where a keyset is unsound — that is why that path refuses to mint a cursor — so suggesting
+ ;; one there would hand back the gapped pagination the refusal exists to prevent. Here the
+ ;; caller wrote the SQL and knows its key, which is the information the server lacks.
+ (format (str "returned %d rows, more available — narrow the SQL (add filters/aggregation), "
+ "raise `row_limit` (max %d), or page with `ORDER BY <unique key>` + "
+ "`WHERE <key> > <last value returned>`")
+ returned max-row-limit))
+
+(def ^:private mbql-hint
+ "Carried as `hint` by an `execute_sql` response whose SQL [[mbql-expressible-sql?]]. A raw-SQL card
+ can't take dashboard filters until rewritten with template tags, so the steer toward MBQL is
+ cheapest before the card exists."
+ (str "This query can be expressed in MBQL; MBQL cards accept dashboard filters without changes. "
+ "If the card will go on a filtered dashboard, build it with execute_query instead "
+ "(learn(\"query-dialect\"))."))
+
+(defn- strip-sql-noise
+ "Lower-cased `sql` with string literals, double-quoted identifiers, and comments blanked, so the
+ keyword probes in [[mbql-expressible-sql?]] never match inside one.
+
+ The literal pattern is an unrolled loop (`[^']*(?:''[^']*)*`) rather than the equivalent-looking
+ alternation `(?:[^']|'')*`. `java.util.regex` compiles an alternation under a quantifier to a
+ recursive match chain — one stack frame per character consumed — so the alternation form throws
+ a `StackOverflowError` on a long literal, and on an *unterminated* quote it backtracks across the
+ whole remaining query, which a single typo in an ordinary query is enough to trigger. The
+ unrolled form consumes each run iteratively and recurses only once per escaped quote."
+ [sql]
+ (-> sql
+ (str/replace #"'[^']*(?:''[^']*)*'" "''")
+ (str/replace #"\"[^\"]*\"" "\"\"")
+ (str/replace #"--[^\n]*" " ")
+ (str/replace #"(?s)/\*.*?\*/" " ")
+ u/lower-case-en))
+
+(defn- mbql-expressible-sql?
+ "Whether `sql` is a plain `SELECT … GROUP BY` aggregate MBQL expresses directly: one SELECT
+ statement with a GROUP BY and none of CTEs, window functions, set operations, subselects, or
+ `{{tag}}` placeholders (a tagged query is no longer the same query in MBQL). A conservative regex
+ heuristic, not a parse: a false negative costs one missed hint, a false positive would steer the
+ caller to rewrite SQL that MBQL cannot express."
+ [sql]
+ (let [s (-> (strip-sql-noise sql) str/trim (str/replace #";\s*$" ""))]
+ (boolean
+ (and (re-find #"^select\b" s)
+ (re-find #"\bgroup\s+by\b" s)
+ (not (str/includes? s ";"))
+ (not (str/includes? s "{{"))
+ (not (re-find #"\bwith\b" s))
+ (not (re-find #"\bover\s*\(" s))
+ (not (re-find #"\b(?:union|intersect|except)\b" s))
+ (not (re-find #"\(\s*select\b" s))))))
+
+(defn- validate-sql-response!
+ [session-id serialized-query prompt hint]
+ (let [counts (cond-> {:query_handle (mint-handle! session-id serialized-query prompt)
+ :returned 0
+ :truncated false}
+ hint (assoc :hint hint))]
+ (common/success-content
+ (str (json/encode counts)
+ "\nSQL accepted, not executed — template tags and permissions were checked; the SQL text itself was not validated. Execute, save, or visualize it later by passing this query_handle."))))
+
+(defn- execute-sql-response!
+ [session-id serialized-query prompt row-limit hint]
+ (let [;; The probe row matters more here than on the MBQL path: with no cursor to page, a
+ ;; complete result mis-reported as truncated would steer the agent to rewrite SQL that
+ ;; was already right, and nothing downstream could correct it.
+ {:keys [cols rows returned truncated?]} (execute-page! serialized-query row-limit)
+ counts (cond-> {:query_handle (mint-handle! session-id serialized-query prompt)
+ :returned returned
+ :truncated truncated?}
+ hint (assoc :hint hint))
+ payload (assoc counts
+ :cols (response-cols cols)
+ :rows rows)]
+ (common/success-content
+ (cond-> (json/encode payload)
+ truncated? (str "\n" (sql-steering-line returned))))))
+
+(def ^:private execute-sql-args-schema
+ [:map {:closed true}
+ [:database_id
+ [:int {:min 1 :description "Numeric id of the database to run the SQL against. Requires native-query permission on it."}]]
+ [:sql
+ [:string {:min 1 :description "The raw SQL text, run verbatim against the database. Put caller-supplied values behind {{tag}} placeholders bound via template_tag_values — never splice them into this string."}]]
+ [:template_tag_values {:optional true}
+ [:maybe [:map-of {:description "Values for the {{tag}} placeholders in sql, keyed by tag name. Each value binds as a driver-level prepared-statement parameter (injection-safe): strings bind as text, numbers as numbers. Snippet ({{snippet: …}}) and card-reference ({{#123}}) tags cannot be populated here."}
+ ;; No date case: a date value arrives as a JSON string and binds as `:text`, which
+ ;; the warehouse coerces. A `:date` tag type would change the QP's parsing, so it
+ ;; needs an explicit caller signal rather than a guess at the string's shape.
+ :keyword [:or :string number? :boolean]]]]
+ [:prompt {:optional true}
+ [:maybe [:string {:min 1 :max 10000 :description "The user's original request, stored with the minted query_handle and carried along its cursor pages."}]]]
+ [:validate_only {:optional true}
+ [:maybe [:boolean {:description "true mints a query_handle without executing — template tags and permissions are checked, the SQL text itself is not (default false)."}]]]
+ [:row_limit {:optional true}
+ [:maybe [:int {:min 1 :max max-row-limit :description "Maximum rows to return in this call (default 100, max 2000)."}]]]])
+
+(registry/deftool execute-sql
+ "Execute a raw SQL string against a database, returning rows plus a query_handle. Requires native-query permission on the database and the instance-level mcp-execute-sql-enabled setting — both enforced even with validate_only: true. Prefer execute_query for anything MBQL can express — a card saved from raw SQL cannot be filtered on a dashboard until rewritten with template tags, so a card bound for a filtered dashboard should be MBQL. The sql runs verbatim against the warehouse, so it is the injection surface — never splice caller- or user-supplied values into it; put values behind {{tag}} placeholders bound via template_tag_values, driver-level prepared-statement parameters that are injection-safe for the values. {{snippet: …}} and {{#123}} card-reference tags splice server-side SQL text and can never be populated through template_tag_values. validate_only: true mints a query_handle without executing (tags and permissions checked; the SQL text itself is not) — stage SQL for saving or visualizing without pulling rows into context. The query_handle is accepted by question_write; execute_query is MBQL-only and rejects it. Results are cols + rows with returned/truncated counts. No cursor pagination: the server cannot know whether arbitrary SQL has a total order, so page it yourself — ORDER BY a unique key plus WHERE <key> > <last value returned>, which is exact where an offset would silently repeat or skip rows. Otherwise narrow the SQL (filters/aggregation) or raise row_limit (max 2000)."
+ {:name "execute_sql"
+ :scope metabot.scope/agent-sql-run
+ ;; Unlike execute_query, arbitrary SQL can write. These match MCP's defaults for an unannotated
+ ;; tool, stated explicitly so the tool is covered by the mutating-tool invariants in
+ ;; `metabase.mcp.v2.registry-test`, which enumerate on `:readOnlyHint`.
+ :annotations {:readOnlyHint false :destructiveHint true}
+ :args execute-sql-args-schema}
+ [{:keys [database_id sql template_tag_values prompt validate_only row_limit]} {:keys [session-id]}]
+ (check-execute-sql-gates! database_id)
+ (let [mp (lib-be/application-database-metadata-provider database_id)
+ query (lib/native-query mp sql)
+ {:keys [query parameters]} (if (seq template_tag_values)
+ (bind-template-tag-values query template_tag_values)
+ {:query query})
+ ;; Re-attached after serialization (which strips `:parameters` as runtime-only) so the
+ ;; execution and the minted handle both carry the bound values: what the agent later
+ ;; visualizes or re-runs through the handle is exactly what ran here.
+ ;;
+ ;; This makes the stored query deliberately wider than the app-DB shape —
+ ;; [[metabase.lib.schema]]'s serialize-query strips `:parameters` because it "doesn't get
+ ;; saved along with the query in the app DB". Re-run and visualize want it; a consumer
+ ;; that saves the handle as a card must lift these into the card's own `:parameters` (or
+ ;; template-tag `:default`s) rather than storing them inside `dataset_query`.
+ serialized (cond-> (lib/prepare-for-serialization query)
+ (seq parameters) (assoc :parameters parameters))
+ hint (when (mbql-expressible-sql? sql) mbql-hint)]
+ (if (true? validate_only)
+ (validate-sql-response! session-id serialized prompt hint)
+ (execute-sql-response! session-id serialized prompt (or row_limit default-row-limit) hint))))
+
+;;; --------------------------------------------- run_saved_question -----------------------------------------------
+
+(defn- card-parameter-label
+ [{:keys [id slug]}]
+ (if slug
+ (format "%s (slug %s)" (pr-str id) (pr-str slug))
+ (pr-str id)))
+
+(defn- throw-unknown-parameter
+ [card-params requested]
+ (common/throw-teaching-error
+ (if (seq card-params)
+ (format "Unknown parameter %s — pass one of this card's parameter ids or slugs: %s."
+ (pr-str requested)
+ (str/join ", " (map card-parameter-label card-params)))
+ (format "Unknown parameter %s — this card has no parameters." (pr-str requested)))))
+
+(defn- check-parameter-value!
+ "Reject a value whose JSON type can't satisfy the parameter's stored type, as a teaching
+ error naming the expectation rather than an opaque QP substitution failure. Multi-value
+ parameters arrive as arrays; each element is checked."
+ [{param-type :type :keys [id slug]} value]
+ (let [family (or (namespace param-type) (name param-type))
+ expected (case family
+ "number" "a number"
+ "boolean" "a boolean"
+ ("date" "temporal-unit") "a string"
+ "a string, number, or boolean")]
+ (doseq [v (if (sequential? value) value [value])]
+ (let [ok? (case family
+ "number" (or (number? v)
+ (and (string? v) (re-matches #"-?\d+(\.\d+)?([eE][+-]?\d+)?" v)))
+ "boolean" (or (boolean? v) (contains? #{"true" "false"} v))
+ ("date" "temporal-unit") (string? v)
+ (or (string? v) (number? v) (boolean? v)))]
+ (when-not ok?
+ (common/throw-teaching-error
+ (format "Invalid value %s for parameter %s of type %s — expected %s."
+ (pr-str v) (pr-str (or slug id)) (u/qualified-name param-type) expected)))))))
+
+(defn- resolve-card-parameters
+ "Resolve each caller-supplied `{id|slug, value}` against the card's own parameter list (its
+ declared parameters merged with the query's template-tag parameters), returning bare
+ `{:id :value}` entries. Every `:id` resolves against the same
+ [[qp.card/combined-parameters-and-template-tags]] set the QP enriches from, so an accepted
+ id is always one the card itself declares; an unknown id is a teaching error here rather
+ than a downstream QP failure.
+
+ Forwarding value-only — never the caller's `:type` or `:target` — is the load-bearing
+ security property, and what lets [[run-card!]] enable arbitrary-MBQL parameters:
+ [[qp.card/process-query-for-card]] fills type and target back in from the card's own
+ declaration, so a caller can set a declared parameter's value but can never point it at a
+ different field. This covers both native template-tag parameters and a saved question's
+ declared filter-widget (MBQL dimension) parameters with one rule."
+ [card parameters]
+ (let [card-params (qp.card/combined-parameters-and-template-tags card)]
+ (mapv (fn [{:keys [id slug value]}]
+ (let [requested (or id slug)
+ _ (when (nil? requested)
+ (common/throw-teaching-error
+ "Each parameter needs an `id` — the parameter's id or slug — and a `value`."))
+ stored (or (m/find-first #(= (:id %) requested) card-params)
+ (m/find-first #(= (:slug %) requested) card-params)
+ (throw-unknown-parameter card-params requested))]
+ (check-parameter-value! stored value)
+ {:id (:id stored) :value value}))
+ parameters)))
+
+(defn- run-card!
+ "Run the saved card through [[qp.card/process-query-for-card]] — the same domain entry the
+ REST card-query endpoint uses, so the read check, sandboxing, and impersonation all apply —
+ with `row-limit` injected as the userland constraints. Returns the QP result; surfaces a
+ failed run as a teaching error.
+
+ Binds [[qp.card/*allow-arbitrary-mbql-parameters*]] true so a saved question's declared
+ MBQL filter-widget parameters run, not just native template tags — the same relaxation the
+ dashboard path takes once it has validated parameters. It is safe here only because
+ [[resolve-card-parameters]] forwards value-only entries resolved against the card's own
+ parameter list, so every parameter's target comes from the card and none from the caller:
+ the arbitrary-parameter door this opens has nothing arbitrary to walk through."
+ [card parameters row-limit]
+ (let [result (binding [qp.card/*allow-arbitrary-mbql-parameters* true]
+ (qp.card/process-query-for-card
+ card :api
+ :parameters parameters
+ :context :question
+ :constraints {:max-results row-limit
+ :max-results-bare-rows row-limit}
+ :middleware {:process-viz-settings? false}
+ :make-run (fn [qp _export-format]
+ (fn [query info]
+ (qp (update query :info merge info) nil)))))]
+ (when-not (= (:status result) :completed)
+ (common/throw-teaching-error (str "Query failed: " (or (:error result) "unknown error"))))
+ result))
+
+(defn- saved-question-steering-line
+ [returned]
+ (format "returned %d rows, more available — narrow with `parameters`, or raise `row_limit` (max %d)"
+ returned max-row-limit))
+
+(def ^:private scalar-parameter-value-schema
+ "A parameter value is a scalar or a list of scalars, never a nested structure — so a value can
+ never smuggle an MBQL fragment (a field ref, a clause) into the filter it feeds. Defense in
+ depth with [[check-parameter-value!]], which additionally checks each scalar against the
+ parameter's declared type; this schema stops the structural cases before the tool runs."
+ (let [scalar [:or :string number? :boolean]]
+ [:or scalar [:sequential scalar]]))
+
+(def ^:private run-saved-question-args-schema
+ [:map {:closed true}
+ [:id [:or
+ [:int {:min 1 :description "Numeric card id."}]
+ [:string {:min 1 :description "A 21-character entity_id."}]]]
+ [:parameters {:optional true}
+ [:maybe [:sequential
+ [:map
+ [:id {:optional true}
+ [:maybe [:string {:min 1 :description "The parameter's id (or slug) from the card's parameter list."}]]]
+ [:slug {:optional true}
+ [:maybe [:string {:min 1 :description "The parameter's slug — equivalent to passing it as id."}]]]
+ [:value {:description "The parameter value: a scalar, or an array of scalars for multi-value parameters (an equality field filter takes an array even for a single value). The parameter's stored target and type always apply."}
+ scalar-parameter-value-schema]]]]]
+ [:row_limit {:optional true}
+ [:maybe [:int {:min 1 :max max-row-limit :description "Maximum rows to return in this call (default 100, max 2000)."}]]]])
+
+(registry/deftool run-saved-question
+ "Run a saved question (card) by numeric id or entity_id, returning rows inline. Pass each parameter as {id, value} where id is the parameter's id or slug — the stored target and type always apply and client-supplied ones are ignored, so you can set a filter's value but never repoint it at another field. Both native template-tag parameters ({{variable}} and field-filter tags) and declared filter-widget parameters can be set; value types are checked per parameter. Discover them with get_content (a question's concise shape carries its template tags and materialized parameters). Results are cols + rows with returned/truncated counts, capped by row_limit. No query_handle and no cursor: on truncation, narrow through the card's parameters or raise row_limit (max 2000)."
+ {:name "run_saved_question"
+ :scope metabot.scope/agent-query-run
+ :annotations {:readOnlyHint true}
+ :args run-saved-question-args-schema}
+ [{:keys [id parameters row_limit]} _context]
+ (let [row-limit (or row_limit default-row-limit)
+ card (v2.resolve/resolve-and-read :model/Card id)
+ mbql-params (when (seq parameters)
+ (resolve-card-parameters card parameters))
+ ;; One row past the limit, so truncation is *observed* rather than inferred from a full
+ ;; page: a card whose result fills `row_limit` exactly is complete, and says so.
+ result (run-card! card mbql-params (inc row-limit))
+ cols (get-in result [:data :cols])
+ ;; The constraints injected by [[run-card!]] don't bind every display type — a
+ ;; `:display :pivot` card routes through `qp.pivot/run-pivot-query`, which replaces
+ ;; `:max-results` with its own pivot ceiling — so the cap is enforced on the result
+ ;; rows here, where it holds regardless of which QP path ran.
+ all-rows (vec (get-in result [:data :rows]))
+ truncated? (> (count all-rows) row-limit)
+ rows (cond-> all-rows truncated? (subvec 0 row-limit))
+ returned (count rows)
+ counts {:returned returned :truncated truncated?}
+ payload (assoc counts
+ :cols (response-cols cols)
+ :rows rows)]
+ (common/success-content
+ (cond-> (json/encode payload)
+ truncated? (str "\n" (saved-question-steering-line returned))))))
diff --git a/src/metabase/mcp/v2/tools/question.clj b/src/metabase/mcp/v2/tools/question.clj
new file mode 100644
index 00000000000..e21afadb0a4
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/question.clj
@@ -0,0 +1,551 @@
+(ns metabase.mcp.v2.tools.question
+ "The v2 MCP `question` write tool: resolves one of three query sources — `query_handle`
+ (a handle from an execute tool), inline `query` (MBQL 5), or `native` (raw SQL) — into a
+ `dataset_query` map, then mirrors REST `POST /api/card/`'s pre-checks to create a saved
+ question."
+ (:require
+ [clojure.string :as str]
+ [metabase.agent-api.query-guards :as query-guards]
+ [metabase.api.common :as api]
+ [metabase.channel.urls :as channel.urls]
+ [metabase.collections.models.collection :as collection]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.scope :as mcp.scope]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.skills :as skills]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.queries.core :as queries]
+ [metabase.util :as u]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private tag-type->kw
+ {"text" :text "number" :number "date" :date "boolean" :boolean
+ "dimension" :dimension "temporal-unit" :temporal-unit})
+
+(defn- tag-field-id
+ "The field the tag binds: `field_id` (the write dialect), or the id embedded in a read-shape
+ `dimension` ref — `[\"field\", <id>, opts]` legacy or `[\"field\", opts, <id>]` MBQL 5 — so the
+ tags `get_content` returns round-trip through this tool unchanged."
+ [{:keys [field_id dimension]}]
+ (or field_id
+ (when (sequential? dimension)
+ (some #(when (or (int? %) (v2.resolve/entity-id? %)) %) (rest dimension)))))
+
+(defn- ->lib-template-tag
+ "Map the tool's tag shape onto `existing-tag` (the lib-extracted template-tag map, which
+ already carries `:id`/`:name`/`:display-name`). `dimension` and `temporal-unit` tags
+ additionally carry a field (`field_id` — a numeric field id, resolved here and built into a
+ pMBQL field ref, since a JSON caller cannot construct one directly: it requires a `:lib/uuid`.
+ Numeric only: `metabase_field.entity_id` was dropped by migration and `:model/Field` is not in
+ the eid-translation map, so an entity_id here could only ever fail); `dimension` tags also carry a widget type (`widget_type`). Alongside the
+ underscore write dialect, the kebab-case read shape `get_content` emits (`display-name`,
+ `widget-type`, a `dimension` ref) is accepted, so a read-modify-write round-trip needs no
+ translation."
+ [existing-tag {tag-type :type :keys [display_name widget_type required default] :as tag}]
+ (let [t (or (tag-type->kw tag-type)
+ (common/throw-teaching-error
+ (format "Invalid template tag type %s — use \"text\", \"number\", \"date\", \"boolean\", \"dimension\", or \"temporal-unit\".\n%s"
+ (pr-str tag-type) skills/template-tag-contract)))
+ display-name (or display_name (:display-name tag))
+ widget-type (or widget_type (:widget-type tag))
+ field-ref? (contains? #{:dimension :temporal-unit} t)
+ field-id (when field-ref? (tag-field-id tag))]
+ (when (and (= t :dimension) (str/blank? widget-type))
+ (common/throw-teaching-error
+ (str "A dimension template tag requires a widget_type, e.g. \"string/=\", \"number/=\", or \"date/all-options\".\n"
+ skills/template-tag-contract)))
+ (when (and field-ref? (nil? field-id))
+ (common/throw-teaching-error
+ (format "A %s template tag requires a field_id — the numeric id of the column it binds.\n%s"
+ (name t) skills/template-tag-contract)))
+ (cond-> (assoc existing-tag :type t)
+ display-name (assoc :display-name display-name)
+ (some? required) (assoc :required (boolean required))
+ (some? default) (assoc :default default)
+ field-ref? (assoc :dimension [:field {:lib/uuid (str (random-uuid))}
+ (v2.resolve/resolve-id-or-404 :model/Field field-id)])
+ (and (= t :dimension) widget-type) (assoc :widget-type (keyword widget-type)))))
+
+(def ^:private reference-tag-types
+ "Tag types that reference server-side SQL text — `{{snippet: …}}`, `{{#42}}` card refs, and
+ source-table tags. They carry no caller-configurable value, but `get_content` emits them
+ alongside the value tags, so a verbatim round-trip must accept them; entries of these types
+ are skipped and the auto-extracted tag stands."
+ #{"snippet" "card" "table"})
+
+(defn- apply-template-tags
+ "Apply caller-supplied `template_tags` to a native `query`. Every supplied tag name must
+ appear in the SQL (i.e. among the tags `lib/native-query` auto-extracted); unknown names
+ are a teaching error naming the tag."
+ [query template_tags]
+ (if (empty? template_tags)
+ query
+ (let [extracted (get-in query [:stages 0 :template-tags])
+ present (into #{} (map :name) extracted)
+ existing-by-name (into {} (map (juxt :name identity)) extracted)]
+ (doseq [tag-name (keys template_tags)]
+ (when-not (contains? present (name tag-name))
+ (common/throw-teaching-error
+ (format "Template tag %s does not appear in the SQL — add {{%s}} to the query or drop the tag."
+ (str "{{" (name tag-name) "}}") (name tag-name)))))
+ (lib/with-template-tags
+ query
+ (into {}
+ (keep (fn [[tag-name tag]]
+ (let [nm (name tag-name)]
+ (when-not (contains? reference-tag-types (:type tag))
+ [nm (->lib-template-tag (get existing-by-name nm) tag)]))))
+ template_tags)))))
+
+(defn- ensure-pmbql-type
+ "Fill in the pMBQL `:lib/type` discriminators a hand-written JSON `query` can't be expected to
+ supply: `:mbql/query` at the top level (unless the query is already legacy MBQL 4, carrying
+ `:type`), and `:mbql.stage/native` or `:mbql.stage/mbql` on each stage. A query that already
+ carries `:lib/type` throughout — e.g. one round-tripped through a lib helper — passes through
+ unchanged."
+ [query]
+ (cond-> query
+ (not (or (:lib/type query) (:type query)))
+ (assoc :lib/type :mbql/query)
+
+ (:stages query)
+ (update :stages
+ (fn [stages]
+ (mapv #(cond-> % (not (:lib/type %))
+ (assoc :lib/type (if (:native %) :mbql.stage/native :mbql.stage/mbql)))
+ stages)))))
+
+(defn- check-native-source-gates!
+ "The gates an inline `native` source passes: the `agent:sql:run` scope and the
+ `mcp-execute-sql-enabled` kill switch — `execute_sql`'s own two, because the stored card is raw
+ SQL a later `run_saved_question` executes, so accepting one under the content write scope alone
+ would rebuild `execute_sql` without its scope or its kill switch. Every source that can resolve
+ to native passes these, `query_handle` included — holding a handle is not proof the gates were
+ spent (`construct_native_query` mints under `agent:sql:construct` and never consults the kill
+ switch, and a handle resolves on `core_session.user_id`, so any credential of that user can spend
+ one minted by another). No-op on the scope half for unscoped callers (cookie sessions bind the
+ unrestricted sentinel, which matches everything)."
+ [token-scopes]
+ (when-not (mcp.scope/matches? token-scopes metabot.scope/agent-sql-run)
+ (throw (ex-info (format (str "Saving a native (SQL) query requires the %s scope — this token can "
+ "write content but not author raw SQL.")
+ metabot.scope/agent-sql-run)
+ {:status-code 403 ::common/error-code common/error-code-invalid-request})))
+ (v2.queries/check-execute-sql-enabled! "Saving a native (SQL) query"))
+
+(defn- resolve-query-source
+ "Resolve exactly one query source to a `dataset_query` map. `query_handle` re-runs the
+ save-path guards (native allowed); `query` is inline MBQL 5; `native` is built from raw SQL
+ once `token-scopes` clears [[check-native-source-gates!]].
+
+ Every branch returns genuine normalized pMBQL: the save path feeds `dataset_query` into
+ strictly schema-checked functions (`queries/check-allowed-to-create-card!` and friends), so
+ the JSON-shaped maps a handle or inline source yields — keyword *values* flattened to strings
+ by the JSON round-trip — must be restored first."
+ [{:keys [query_handle query native]} session-id token-scopes]
+ (let [sources (cond-> []
+ query_handle (conj :query_handle)
+ query (conj :query)
+ native (conj :native))]
+ (when-not (= 1 (count sources))
+ (common/throw-teaching-error
+ "Pass exactly one query source: `query_handle` (a handle from an execute tool), `query` (an inline query), or `native` ({database_id, sql})."))
+ (cond
+ query_handle
+ (let [resolved (lib-be/normalize-query
+ nil
+ (:query (v2.queries/resolve-query-handle-for-save! session-id api/*current-user-id* query_handle))
+ {:strict? true})]
+ (when (query-guards/native-query? resolved)
+ (check-native-source-gates! token-scopes))
+ resolved)
+
+ query
+ (let [resolved (try
+ (lib-be/normalize-query nil (ensure-pmbql-type query) {:strict? true})
+ (catch clojure.lang.ExceptionInfo e
+ (common/throw-teaching-error
+ (str "Invalid inline query — see learn(\"query-dialect\"). " (ex-message e)))))]
+ ;; `native` on the source arg is not the same thing as native in the resolved query: an inline
+ ;; `query` can carry a native stage (`ensure-pmbql-type` stamps `:mbql.stage/native` on any stage
+ ;; with `:native`), and that stored card is raw SQL a later run_saved_question executes. Gate on
+ ;; the resolved query's shape, whole-tree (nested native too), so the `query` source can't be a
+ ;; back door around the scope + kill switch the `native` source enforces.
+ (when (query-guards/native-query? resolved)
+ (check-native-source-gates! token-scopes))
+ resolved)
+
+ native
+ (do
+ (check-native-source-gates! token-scopes)
+ (let [{:keys [database_id sql template_tags]} native
+ mp (lib-be/application-database-metadata-provider database_id)]
+ (-> (lib/native-query mp sql)
+ (apply-template-tags template_tags)))))))
+
+;;; ------------------------------------------------------ Create --------------------------------------------------
+
+(defn- collection-path
+ "Permission-filtered location breadcrumb of `collection-id`, e.g. \"Our analytics / Marketing
+ / Q3\". Ancestors the caller can't read are omitted, matching the app breadcrumb. A `nil`
+ `collection-id` is the root collection (\"Our analytics\"), not a personal collection."
+ [collection-id]
+ (if-not collection-id
+ (:name (collection/root-collection-with-ui-details nil))
+ (let [coll (mcp.db/select-one-by-id [:model/Collection :id :name :location :personal_owner_id
+ :namespace :archived_directly]
+ collection-id)
+ ancestors (cond->> (:effective_ancestors (t2/hydrate coll :effective_ancestors))
+ (collection/is-personal-collection-or-descendant-of-one? coll)
+ (remove #(= "root" (:id %))))
+ chain (collection/personal-collections-with-ui-details (conj (vec ancestors) coll))]
+ (str/join " / " (map :name chain)))))
+
+(defn- card-response
+ "The card fields the create and update responses share. `visualization_settings` is
+ echoed as stored — a write that names it is otherwise unverifiable without a second read, and an
+ update that leaves it alone still reports what the chart is drawing from."
+ [card]
+ {:id (:id card)
+ :name (:name card)
+ :display (name (:display card))
+ :collection_id (:collection_id card)
+ :collection_path (collection-path (:collection_id card))
+ :description (:description card)
+ :visualization_settings (or (:visualization_settings card) {})})
+
+(def ^:private visibility-type-strs
+ "String form of `::lib.schema.metadata/column.visibility-type`'s enum — the args schema and the
+ value check below both need the string set the caller writes."
+ #{"normal" "details-only" "hidden" "sensitive" "retired"})
+
+(defn- check-semantic-type!
+ "`semantic_type` names a keyword in the open `type/…` hierarchy (`type/Currency`,
+ `type/PK`, …) — too large to enumerate in the args schema — so validate it here instead
+ of letting an unrecognized value fail deep in the insert as a sanitized internal error."
+ [semantic_type]
+ (let [k (keyword semantic_type)]
+ ;; `type/PK` and `type/FK` are relation types, not semantic ones, but the column schema accepts
+ ;; either under `semantic_type` and the tool's own examples name them.
+ (when-not (or (isa? k :Semantic/*) (isa? k :Relation/*))
+ (common/throw-teaching-error
+ (format "Invalid semantic_type %s — pass a type in the \"type/…\" namespace, e.g. \"type/Currency\" or \"type/PK\"."
+ (pr-str semantic_type))))
+ k))
+
+(defn- apply-column-override
+ "Apply one caller-supplied override map onto `col`. A key's presence (even with an explicit
+ `null`, which — unlike top-level args — survives the registry's nil-stripping on nested
+ values) sets or clears that property; an absent key leaves `col`'s existing value alone."
+ [col {:keys [display_name description semantic_type visibility_type] :as override}]
+ (cond-> col
+ (contains? override :display_name) (assoc :display_name display_name)
+ (contains? override :description) (assoc :description description)
+ (contains? override :semantic_type) (assoc :semantic_type (some-> semantic_type check-semantic-type!))
+ (contains? override :visibility_type) (assoc :visibility_type (some-> visibility_type keyword))))
+
+(defn- merge-column-metadata
+ "Overlay caller-supplied `column_metadata` overrides onto `computed-columns` (the query's
+ real, inferred result metadata), matching by `:name`. Only the override keys
+ (display_name, description, semantic_type, visibility_type) are changed on a matched
+ column — base_type, id, field_ref, fingerprints, and every non-annotated column pass
+ through untouched. Every `column_metadata` name must match a computed column, or a
+ teaching error names the offending one."
+ [computed-columns column_metadata]
+ (let [by-name (into {} (map (juxt :name identity)) computed-columns)]
+ (doseq [{col-name :name} column_metadata]
+ (when-not (contains? by-name col-name)
+ (common/throw-teaching-error
+ (format "Column %s is not in the query results — column_metadata names must match the query's output columns."
+ (pr-str col-name)))))
+ (let [overrides (into {} (map (juxt :name identity)) column_metadata)]
+ (mapv (fn [col]
+ (if-let [override (get overrides (:name col))]
+ (apply-column-override col override)
+ col))
+ computed-columns))))
+
+(defn- resolve-result-metadata
+ "Compute `dataset-query`'s real column metadata — folding in `card`'s already-stored model
+ overrides (so a partial update keeps annotations on columns the caller didn't resend) — then
+ overlay the caller's `column_metadata` overrides by name. `card` carries `:type` and any existing
+ `:result_metadata`; for create it's just the pending `{:type ...}`. Throws a teaching error for a
+ native query (no inferable columns) or an unknown column name."
+ [dataset-query card column_metadata]
+ (let [computed-columns (queries/infer-metadata-with-model-overrides dataset-query card)]
+ (when (empty? computed-columns)
+ ;; infer-metadata swallows preprocess errors and returns nothing, so distinguish the two ways
+ ;; to get here: a native query (columns genuinely can't be inferred) vs. an MBQL query that
+ ;; failed to analyze (a real problem the caller should hear about, not a "native" red herring).
+ (if (lib/native-only-query? dataset-query)
+ (common/throw-teaching-error
+ "column_metadata isn't supported for models built from a native (SQL) query — Metabase can't determine column types without running the SQL. Omit column_metadata; you can annotate the model's columns after it's created.")
+ (common/throw-teaching-error
+ "Couldn't determine the query's result columns, so column_metadata can't be applied — check that the query is valid and returns columns.")))
+ (merge-column-metadata computed-columns column_metadata)))
+
+(defn- check-dashboard-collection-exclusive!
+ "`dashboard_id` and `collection_id` are mutually exclusive — a dashboard question's collection
+ is the dashboard's collection, not a caller-chosen one."
+ [dashboard_id args]
+ (when (and dashboard_id (contains? args :collection_id))
+ (common/throw-teaching-error
+ "Pass either collection_id or dashboard_id, not both — a dashboard question's collection is the dashboard's collection.")))
+
+(defn- normalize-model-display
+ "Force `display` to table when a patch retypes a card to a model, as `PUT /api/card/:id` does. A
+ model's display is not inert: the query processor runs the pivot QP when it is `:pivot`, and a
+ chart display also drives subscription rendering, dashcard sizing, and the search display filter.
+ An explicit `list` is left alone, as REST leaves it: the list view is one of the two displays the
+ model editor offers, so it is a real choice rather than a leftover chart display."
+ [card-updates]
+ (cond-> card-updates
+ (and (= :model (:type card-updates))
+ (not= :list (:display card-updates)))
+ (assoc :display :table)))
+
+(defn- resolve-dashboard!
+ "Resolve `dashboard_id` to `{:dashboard-id id :collection-id (its collection_id)}`, or nil when
+ `dashboard_id` is absent. Read-checked, so a dashboard that doesn't exist and one the caller
+ can't read are the same not-found — answering the second with the later write check's 403 would
+ make the argument an existence oracle for every dashboard on the instance. The write check still
+ decides whether a card may actually be saved into it."
+ [dashboard_id]
+ (when dashboard_id
+ (let [dashboard (v2.resolve/resolve-and-read :model/Dashboard dashboard_id)]
+ {:dashboard-id (:id dashboard) :collection-id (:collection_id dashboard)})))
+
+(defn- create!
+ "Run the shared REST create check stack ([[metabase.queries.core/check-allowed-to-create-card!]])
+ on the resolved query and target collection, then save a `question` (or `model`) card. Returns
+ the create response: [[card-response]] plus the saved card's `:url`."
+ [{:keys [name description display visualization_settings cache_ttl collection_position
+ card_type column_metadata dashboard_id] :as args}
+ session-id token-scopes]
+ (check-dashboard-collection-exclusive! dashboard_id args)
+ (let [dataset-query (resolve-query-source args session-id token-scopes)
+ dashboard (resolve-dashboard! dashboard_id)
+ dashboard-id (:dashboard-id dashboard)
+ collection-id (if dashboard
+ (:collection-id dashboard)
+ (v2.resolve/resolve-collection-id-or-personal (:collection_id args)))]
+ (queries/check-allowed-to-create-card! {:dataset_query dataset-query :collection_id collection-id}
+ (keyword (or card_type "question")))
+ (let [result-metadata (when (seq column_metadata)
+ (resolve-result-metadata dataset-query
+ {:type (keyword (or card_type "question"))}
+ column_metadata))
+ card (queries/create-card!
+ (cond-> (u/remove-nils
+ {:name name
+ :type (keyword (or card_type "question"))
+ :dataset_query dataset-query
+ :display (keyword (or display "table"))
+ :description description
+ :collection_id collection-id
+ :collection_position collection_position
+ :cache_ttl cache_ttl
+ :visualization_settings (or visualization_settings {})})
+ result-metadata (assoc :result_metadata result-metadata)
+ dashboard-id (assoc :dashboard_id dashboard-id))
+ {:id api/*current-user-id*})]
+ (assoc (card-response card)
+ :url (common/frontend-url (channel.urls/card-path (:id card)))))))
+
+(defn- update-card-response
+ "The update response: [[card-response]] plus `:archived`."
+ [card]
+ (assoc (card-response card) :archived (boolean (:archived card))))
+
+(defn- check-is-question!
+ "Refuse to write a question's contract onto a metric, so a caller can't retype a card by
+ addressing it with the wrong tool. Questions and models both pass — this tool owns both, and
+ converting between them stays a legitimate update."
+ [card]
+ (when-not (contains? #{:question :model} (:type card))
+ (common/throw-teaching-error
+ (format "Card %d is a %s, not a question — use metric_write to update it."
+ (:id card) (name (:type card))))))
+
+(defn- force-restore-on-dashboard-move
+ "Mirrors REST's `update-card!` guard: when `card-updates` moves the card into a dashboard
+ (`:dashboard_id` changing to non-nil), a caller-requested `archived true` in the same patch is
+ refused — archiving and moving-into-a-dashboard are separate operations — and an already
+ `archived` card being moved is force-restored (`archived false`, `archived_directly false`).
+ Without this, a trashed card can be re-parented under a dashboard while `archived` (and
+ `archived_directly`) stay true,
+ since the model layer's `apply-dashboard-question-updates` re-derives `:collection_id` from
+ the dashboard whenever `:dashboard_id` is present, independent of `:archived`."
+ [card-before card-updates]
+ (cond-> card-updates
+ (and (api/column-will-change? :dashboard_id card-before card-updates)
+ (:dashboard_id card-updates))
+ (as-> updates
+ (do
+ (when (:archived updates)
+ (common/throw-teaching-error
+ "Can't move a card into a dashboard while also archiving it — archive and move are separate operations."))
+ (assoc updates :archived false :archived_directly false)))))
+
+(defn- update!
+ "Write-check the existing card, patch only the caller-supplied fields (archiving/restoring via
+ `archived`; moving into a dashboard via `dashboard_id`, which forces the card's collection to
+ the dashboard's — the model layer enforces the dashboard-question move rules), then run the
+ shared REST update check stack ([[metabase.queries.core/check-allowed-to-update-card!]] plus the
+ save-cycle guard) before persisting. Returns [[update-card-response]].
+
+ Moving a card OUT of a dashboard isn't expressible here: a `nil` `dashboard_id` is
+ indistinguishable from an omitted one once JSON-RPC args are stripped of nulls."
+ [id {:keys [name description display visualization_settings cache_ttl collection_position
+ card_type archived column_metadata dashboard_id] :as args}
+ session-id token-scopes]
+ (check-dashboard-collection-exclusive! dashboard_id args)
+ (let [card-before (v2.resolve/resolve-and-read-with
+ :model/Card id
+ ;; Hydrated like PUT /api/card/:id hydrates it: `update-card!` un-verifies a
+ ;; verified card whose query changes by reading `:moderation_reviews` off the
+ ;; card-before, and a bare row would leave the Verified badge on a swapped query.
+ (fn [cid] (t2/hydrate (api/write-check :model/Card cid)
+ [:moderation_reviews :moderator_details])))
+ ;; The resolved numeric id, never the raw `id` arg: a 21-char entity_id would build the
+ ;; save-cycle graph on a node no dependency matches, and select the readback by a string.
+ card-id (:id card-before)
+ _ (check-is-question! card-before)
+ dashboard (resolve-dashboard! dashboard_id)
+ dashboard-id (:dashboard-id dashboard)
+ new-query (when (or (:query_handle args) (:query args) (:native args))
+ (resolve-query-source args session-id token-scopes))
+ raw-updates (cond-> {}
+ (contains? args :name) (assoc :name name)
+ (contains? args :description) (assoc :description description)
+ (contains? args :collection_id) (assoc :collection_id (v2.resolve/resolve-collection-id (:collection_id args)))
+ dashboard-id (assoc :dashboard_id dashboard-id
+ :collection_id (:collection-id dashboard))
+ (contains? args :collection_position) (assoc :collection_position collection_position)
+ (contains? args :display) (assoc :display (some-> display keyword))
+ (contains? args :visualization_settings) (assoc :visualization_settings visualization_settings)
+ (contains? args :cache_ttl) (assoc :cache_ttl cache_ttl)
+ (contains? args :card_type) (assoc :type (keyword card_type))
+ (contains? args :archived) (assoc :archived (boolean archived))
+ new-query (assoc :dataset_query new-query))
+ card-updates (api/updates-with-archived-directly card-before raw-updates)
+ card-updates (force-restore-on-dashboard-move card-before card-updates)
+ card-updates (normalize-model-display card-updates)]
+ ;; the type the card will have once written: the patch's when the caller is converting, else the
+ ;; stored one. Never the raw request, which is nil whenever `card_type` is omitted.
+ (queries/check-card-can-be-saved! (:dataset_query card-updates)
+ (or (:type card-updates) (:type card-before)))
+ (when-some [query (:dataset_query card-updates)]
+ (queries/check-no-save-cycle! card-id query))
+ (queries/check-allowed-to-update-card! card-before card-updates)
+ ;; Result-metadata inference runs the query's preprocess over whatever tables and cards the query
+ ;; names, and its teaching errors name the columns it found — so it must come AFTER a permission
+ ;; check on that query, or a caller could learn the columns of a table (or another user's card)
+ ;; they cannot run, one guessed name at a time. The stack above only checks the query when the
+ ;; query itself changes, so a column_metadata-only update needs this check of its own. It also
+ ;; covers what `check-update-result-metadata-data-perms` checks on the REST body: the overrides
+ ;; only annotate columns the inference produced, so the metadata names no table the query doesn't.
+ (when (seq column_metadata)
+ (queries/check-allowed-to-run-query! (or new-query (:dataset_query card-before))))
+ (let [card-updates (cond-> card-updates
+ (seq column_metadata) (assoc :result_metadata
+ (resolve-result-metadata
+ (or new-query (:dataset_query card-before))
+ card-before
+ column_metadata)))]
+ (queries/update-card! {:card-before-update card-before
+ :card-updates card-updates
+ :actor @api/*current-user*
+ :delete-old-dashcards? false}))
+ (update-card-response (mcp.db/select-one-by-id :model/Card card-id))))
+
+(def ^:private question-write-args-schema
+ [:map {:closed true}
+ [:method [:enum "create" "update"]]
+ [:id {:optional true} [:maybe [:or :int :string]]]
+ [:card_type {:optional true} [:maybe [:enum "question" "model"]]]
+ [:query_handle {:optional true} [:maybe :string]]
+ [:query {:optional true} [:maybe :map]]
+ [:native {:optional true}
+ [:maybe [:map
+ [:database_id [:or :int :string]]
+ [:sql [:string {:min 1}]]
+ [:template_tags {:optional true}
+ [:maybe [:map-of
+ {:description (str "One entry per {{tag}} in the SQL, keyed by tag name; a name "
+ "absent from the SQL is an error. The shape get_content "
+ "returns round-trips verbatim.")}
+ :keyword
+ [:map
+ [:type [:enum {:description (str "\"dimension\" = field filter, a widget bound to a column — "
+ "write it bare in SQL (WHERE {{tag}}); \"temporal-unit\" = "
+ "time-bucket picker for a datetime column; text/number/date/"
+ "boolean = raw variables spliced as literals (you write the "
+ "operator: WHERE total > {{tag}}); snippet/card/table "
+ "reference entries are accepted and ignored — the SQL text "
+ "configures them.")}
+ "text" "number" "date" "boolean" "dimension" "temporal-unit"
+ "snippet" "card" "table"]]
+ [:display_name {:optional true} [:maybe [:string {:description "Widget label."}]]]
+ [:field_id {:optional true}
+ [:maybe [:int {:description (str "Required for dimension/temporal-unit: the bound column, as "
+ "a numeric field id. Fields have no entity_id.")}]]]
+ [:widget_type {:optional true}
+ [:maybe [:string {:description (str "Required for dimension: widget/operator matched to the "
+ "column's type — e.g. \"string/=\", \"string/contains\", "
+ "\"number/between\", \"date/all-options\", \"category\", "
+ "\"id\".")}]]]
+ [:required {:optional true} [:maybe :boolean]]
+ [:default {:optional true} [:maybe :any]]]]]]]]]
+ [:name {:optional true} [:maybe [:string {:min 1}]]]
+ [:description {:optional true} [:maybe :string]]
+ [:collection_id {:optional true} [:maybe [:or :int :string]]]
+ [:dashboard_id {:optional true} [:maybe [:or :int :string]]]
+ [:collection_position {:optional true} [:maybe :int]]
+ [:display {:optional true} [:maybe common/card-display-enum]]
+ [:visualization_settings {:optional true} [:maybe :map]]
+ [:cache_ttl {:optional true} [:maybe :int]]
+ [:archived {:optional true} [:maybe :boolean]]
+ [:clear {:optional true}
+ [:maybe [:sequential [:enum {:description "Update only: property names to unset (description, collection_position, cache_ttl). Needed because a null cannot say \"clear this\" — strict clients fill every unset property with null, so nulls are stripped at the boundary."}
+ "description" "collection_position" "cache_ttl"]]]]
+ [:column_metadata {:optional true}
+ [:maybe [:sequential
+ [:map
+ [:name [:string {:min 1}]]
+ [:display_name {:optional true} [:maybe :string]]
+ [:description {:optional true} [:maybe :string]]
+ [:semantic_type {:optional true}
+ [:maybe [:string {:description (str "A type in the \"type/…\" namespace, e.g. \"type/Currency\", "
+ "\"type/PK\", \"type/Email\".")}]]]
+ [:visibility_type {:optional true}
+ [:maybe (into [:enum {:description "How the column shows up in the UI."}]
+ visibility-type-strs)]]]]]]])
+
+(registry/deftool question-write-tool
+ "Create, update, or archive a saved question or model. method: \"create\" | \"update\". On create, pass a name and exactly one query source: query_handle (from an execute tool — MBQL or native SQL), query (an inline query — numeric ids and a top-level database id, learn(\"query-dialect\"); prefer query_handle, which saves exactly the query execute_query validated), or native ({database_id, sql, template_tags?} — the template_tags shape is MCP-specific and not guessable: before first passing it, call learn(\"native-parameters\") unless already read; on create or update, native additionally requires the agent:sql:run scope and the instance-level mcp-execute-sql-enabled setting, since the saved card is raw SQL). Optional: card_type (\"question\" default, or \"model\"), description, collection_id (omit = your personal collection; \"root\" = the root collection) or dashboard_id (saves the question inside that dashboard, whose collection it inherits — passing both is an error), display, visualization_settings (learn(\"visualization-settings\") covers display choice and settings keys), cache_ttl, column_metadata (list of {name, display_name?, description?, semantic_type?, visibility_type?} — sets result_metadata; typically used with card_type \"model\"). On update, pass id and the fields to change; archived: true trashes, false restores; dashboard_id moves the card into that dashboard (collection follows; a question saved in another dashboard can't move to a different one; moving a card OUT of a dashboard isn't supported yet). Updating a card that is a metric is refused rather than retyping it — use metric_write."
+ {:name "question_write"
+ :scope metabot.scope/agent-content-write
+ ;; `archived: true` trashes the card, so this is not the additive-only update
+ ;; `destructiveHint false` would assert.
+ :annotations {:readOnlyHint false :destructiveHint true}
+ :args question-write-args-schema}
+ [args {:keys [token-scopes session-id]}]
+ (let [[op a b] (v2.write/dispatch-write
+ {:create-required [:name]
+ :clearable #{:description :collection_position :cache_ttl}}
+ args)
+ payload (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (case op
+ :create (create! a session-id token-scopes)
+ :update (update! a b session-id token-scopes))
+ nil)]
+ (common/success-content payload payload)))
diff --git a/src/metabase/mcp/v2/tools/search.clj b/src/metabase/mcp/v2/tools/search.clj
new file mode 100644
index 00000000000..ef2dec42375
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/search.clj
@@ -0,0 +1,575 @@
+(ns metabase.mcp.v2.tools.search
+ "The v2 MCP `search` tool: one entry point for discovery, backed by the v1 metabot search
+ pipeline (each query runs separately, results merged by rank). Three explicit modes —
+ ranked queries, filters-only listing, and recents — plus a server-side snippet union
+ (snippets aren't in the search index). An explicitly named type that doesn't support a filter
+ is a teaching error; an omitted type is narrowed to the types that do, disclosed in the
+ response — the engine's silent, undisclosed narrowing is never relied on."
+ (:require
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [medley.core :as m]
+ [metabase.activity-feed.core :as activity-feed]
+ [metabase.api.common :as api]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.metabot.tools.search :as metabot.search]
+ [metabase.models.interface :as mi]
+ [metabase.premium-features.core :as premium-features]
+ [metabase.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------ Type tables ---------------------------------------------------
+
+(def ^:private all-types
+ ["question" "model" "metric" "measure" "segment" "dashboard" "document" "collection"
+ "table" "database" "snippet" "transform" "action"])
+
+(def ^:private created-by-types
+ "Types whose search model indexes a creator (`in_place/filter.clj`'s created-by methods);
+ `created_by` with any other type is a teaching error rather than the engine's silent narrowing."
+ #{"question" "model" "metric" "dashboard" "document" "measure" "action"})
+
+(def ^:private collectionless-types
+ "Types the collection filter can never serve — they don't live in collections."
+ #{"measure" "segment" "database"})
+
+(def ^:private non-archivable-types
+ "Types whose search model has no archived state (`:archived false` in their spec). `archived: true`
+ with any of them can only ever return nothing, so the engine silently drops the type — a teaching
+ error instead. Note transforms *do* live in collections, so this is distinct from
+ `collectionless-types`."
+ #{"table" "database" "transform"})
+
+(def ^:private type->rv-model
+ "v2 type → the recent-views model keyword; the domain of this map is exactly the set of
+ types recents tracks."
+ {"question" :card
+ "model" :dataset
+ "metric" :metric
+ "dashboard" :dashboard
+ "table" :table
+ "collection" :collection
+ "document" :document})
+
+(def ^:private rv-model->type
+ (set/map-invert type->rv-model))
+
+;;; ------------------------------------------------ Projections ---------------------------------------------------
+
+(def ^:private concise-row-keys
+ #{:type :id :name :collection_path :description})
+
+(projections/register-projection!
+ :search-result
+ {:concise (fn [row]
+ (m/remove-vals nil? (select-keys row concise-row-keys)))
+ ;; The v1 engine enriches some rows (metrics) with its own field vocabulary; the v2 surface
+ ;; names entity ids `entity_id` and never emits portable FK arrays, so translate/strip here.
+ :detailed (fn [row]
+ (cond-> (dissoc row :portable_entity_id :base_table_portable_fk)
+ (and (:portable_entity_id row) (nil? (:entity_id row)))
+ (assoc :entity_id (:portable_entity_id row))))
+ :sample {:id 1
+ :type "question"
+ :name "x"
+ :description "x"
+ :created_at "x"
+ :updated_at "x"
+ :collection {:id 1 :name "x" :authority_level "official" :description "x"}
+ :collection_path "x"
+ :location "x"
+ :database_id 1
+ :database_engine "x"
+ :database_name "x"
+ :database_schema "x"
+ :display_name "x"
+ :verified true
+ :official true
+ :curated true
+ :data_authority "x"
+ :data_layer "x"
+ :model_id 1
+ :table_id 1
+ :table_name "x"
+ :table_schema "x"
+ :entity_id "x"
+ :base_table_id 1
+ :base_table_name "x"
+ :base_table_schema "x"}})
+
+;;; --------------------------------------------- Collection paths -------------------------------------------------
+
+(defn- location->ids
+ [location]
+ (when location
+ (mapv parse-long (re-seq #"\d+" location))))
+
+(defn- readable-id->name
+ "Map of collection id -> name for the given ids, omitting collections the current user cannot
+ read. `:namespace` and `:type` are selected because [[mi/can-read?]] consults them."
+ [ids]
+ (when (seq ids)
+ (into {}
+ (comp (filter mi/can-read?)
+ (map (juxt :id :name)))
+ (mcp.db/collections-for-read-check ids))))
+
+(defn- add-collection-paths
+ "Attach `:collection_path` — ancestor collection names joined with `/`, ending in the
+ containing collection's own name — to every row that has a `:collection`. Collection rows
+ use their own `:location` (path of their ancestors). Two batched lookups total; rows with
+ no collection context (root items, snippets, tables, databases) get no path.
+
+ Ancestors the current user cannot read are omitted from the path, matching the breadcrumb
+ semantics of [[metabase.collections.models.collection/effective-ancestors]]: for A > B > C
+ where B is unreadable, the path reads \"A/C\"."
+ [rows]
+ (let [parent-ids (into #{} (keep #(get-in % [:collection :id])) rows)
+ parents (when (seq parent-ids)
+ (mcp.db/collection-id->name+location parent-ids))
+ ancestor-ids (into #{}
+ (comp (mapcat location->ids)
+ (remove parent-ids))
+ (concat (map second (vals parents))
+ (keep :location rows)))
+ id->name (merge (readable-id->name ancestor-ids)
+ (update-vals parents first))
+ location-path (fn [location]
+ (when-let [segments (seq (keep id->name (location->ids location)))]
+ (str/join "/" segments)))]
+ (mapv (fn [row]
+ (let [parent-id (get-in row [:collection :id])
+ [pname ploc] (get parents parent-id)
+ path (cond
+ pname (str/join "/" (concat (keep id->name (location->ids ploc))
+ [pname]))
+ (:location row) (location-path (:location row)))]
+ (m/assoc-some row :collection_path path)))
+ rows)))
+
+;;; ------------------------------------------------ Validation ----------------------------------------------------
+
+(defn- collection-scoping?
+ "True when `collection_id` scopes the search to a specific collection: present and not the inert
+ \"root\" sentinel (nil is stripped before the handler, so a present value is non-nil). A missing
+ or \"root\" filter does nothing, so it must not trip the collection checks. \"trash\" counts as
+ scoping and surfaces its teaching error when [[resolve-collection-filter]] resolves it."
+ [{:keys [collection_id] :as args}]
+ (and (contains? args :collection_id)
+ (not= "root" collection_id)))
+
+(def ^:private data-source-types
+ "Types the data-hierarchy browser (browse_data) serves; every other type lives in a collection
+ and is browsed with browse_collection."
+ #{"table" "database"})
+
+(defn- browse-redirect!
+ "Throw a teaching error for a filters-only call — filters but no query. search only ranks
+ queries, so a query-less listing belongs in a browse_* tool, whose order is stable and whose
+ count isn't ranking-capped. Route to the closest match by the filters given."
+ [{:keys [type collection_id created_by archived] :as args}]
+ (let [types (set type)
+ target (cond
+ (contains? types "snippet")
+ "browse_collection(namespace: \"snippets\")"
+
+ (contains? types "transform")
+ "browse_collection(namespace: \"transforms\")"
+
+ (collection-scoping? args)
+ (format "browse_collection(id: %s, mode: \"items\"%s%s)"
+ (pr-str collection_id)
+ (if (seq types) (str ", type: " (pr-str (vec (sort types)))) "")
+ (if created_by ", created_by: \"me\"" ""))
+
+ created_by
+ (str "browse_collection(id: <collection>, mode: \"items\", created_by: \"me\") — "
+ "browse lists your content within a collection, not instance-wide")
+
+ (true? archived)
+ "browse_collection(id: \"trash\", mode: \"items\")"
+
+ (and (seq types) (every? data-source-types types))
+ "browse_data (list_databases, then list_tables)"
+
+ :else
+ "browse_collection(id: <collection>, mode: \"items\") for a specific collection")]
+ (common/throw-teaching-error
+ (str "This is a listing, not a search — it has filters but no term_queries or semantic_queries. "
+ "To browse without a query, use " target "."))))
+
+(def ^:private max-queries-per-list
+ "Cap on term_queries/semantic_queries entries. Each entry fans out into its own subsearch (a full
+ ranked-pool fetch, plus an embedding call for a semantic query), and the MCP throttler counts
+ requests, not the queries inside one — so an uncapped list turns one call into many concurrent
+ searches."
+ 10)
+
+(def ^:private max-query-length
+ "Cap on each query string, in characters — a long query wastes embedding tokens and slows the
+ full-text scan without adding signal."
+ 500)
+
+(defn- validate-modes!
+ [{:keys [recent term_queries semantic_queries] :as args} queries? filters?]
+ (when (some str/blank? (concat term_queries semantic_queries))
+ (common/throw-teaching-error
+ (str "A blank query matches everything — every term_queries and semantic_queries entry must "
+ "be non-empty. Drop the blank entry.")))
+ (when (or (> (count term_queries) max-queries-per-list)
+ (> (count semantic_queries) max-queries-per-list))
+ (common/throw-teaching-error
+ (format (str "Too many queries — pass at most %d entries each in term_queries and "
+ "semantic_queries. Combine related queries or drop some.")
+ max-queries-per-list)))
+ (when (some #(> (count %) max-query-length) (concat term_queries semantic_queries))
+ (common/throw-teaching-error
+ (format "A query is too long — each term_queries/semantic_queries entry must be at most %d characters."
+ max-query-length)))
+ (when (and (true? recent) queries?)
+ (common/throw-teaching-error
+ (str "recent: true returns your recently viewed items and cannot be combined with "
+ "term_queries or semantic_queries — drop the queries or drop recent.")))
+ (when-not (or queries? filters? (true? recent))
+ (common/throw-teaching-error
+ (str "Nothing to search for — pass term_queries and/or semantic_queries (optionally narrowed "
+ "by type, collection_id, created_by, archived), or recent: true for your recently viewed "
+ "items. To list without a query, browse with browse_collection or browse_data.")))
+ (when (and filters? (not queries?) (not (true? recent)))
+ (browse-redirect! args))
+ args)
+
+(def ^:private engine-searchable-types
+ "Every type search can run against the engine — `all-types` minus snippet, which is served by its
+ own listing. This is the type set an omitted `type` expands to, and the set `created_by`/
+ `collection_id`/`archived` compatibility is checked against when the caller didn't name types
+ explicitly — otherwise the engine's own silent per-type narrowing would apply unannounced."
+ (into (sorted-set) (remove #{"snippet"}) all-types))
+
+(defn- validate-filters!
+ "Validate `created_by`/`collection_id`/`archived` against `type`, throwing a teaching error for
+ a genuinely invalid combination. Returns `{:types :disclosures}`: when the caller named `type`
+ explicitly, `:types` is nil (unchanged) and `:disclosures` empty. When `type` was omitted and a
+ filter is supported by only some of the engine's types, the search is narrowed to the
+ supporting types instead of thrown — the caller never asked for the unsupported types
+ specifically, and rejecting the whole call would break the common unscoped case (`created_by:
+ \"me\"` with no `type`) — and `:disclosures` names every such narrowing for the response."
+ [{:keys [type created_by archived semantic_queries recent] :as args}]
+ (let [types (set type)
+ ;; The set a compatibility check runs against: the caller's explicit types, or — when
+ ;; omitted from an engine search — every type the engine would otherwise search, so a
+ ;; filter that only some types support is caught instead of silently narrowing an unscoped
+ ;; search. recent: true never reaches the engine and has its own, more specific
+ ;; incompatibility check below, so it must not be widened into this one.
+ type-omitted? (and (empty? types) (not (true? recent)))
+ effective-types (if type-omitted? engine-searchable-types types)
+ ;; [{:excluded #{...} :label "..." :because "..."}], one entry per narrowing filter. The
+ ;; message is built after the fold, from the final narrowed set — a message built here would
+ ;; name this filter's own subtraction and so advertise types a sibling filter also removed.
+ narrowed (atom [])]
+ (when (and (contains? types "snippet") (next types))
+ (common/throw-teaching-error
+ (format (str "type: [\"snippet\"] cannot be combined with other types — snippets aren't in the "
+ "search index and are paged separately. List them in their own call, and search %s in another.")
+ (str/join ", " (sort (disj types "snippet"))))))
+ (when (and (contains? types "snippet") (seq semantic_queries))
+ (common/throw-teaching-error
+ (str "semantic_queries cannot search snippets — snippets aren't in the search index and are "
+ "matched by substring against their name, not semantic similarity. Use term_queries instead, "
+ "or drop semantic_queries.")))
+ (when created_by
+ (when-let [bad (seq (sort (remove created-by-types effective-types)))]
+ (if type-omitted?
+ (swap! narrowed conj
+ {:excluded (set bad)
+ :label "created_by"
+ :because "don't index a creator"})
+ (common/throw-teaching-error
+ (format (str "created_by only applies to types that index a creator: %s. "
+ "Remove %s from type or drop created_by.")
+ (str/join ", " (sort created-by-types))
+ (str/join ", " bad))))))
+ (when (collection-scoping? args)
+ (when-let [bad (seq (sort (filter collectionless-types effective-types)))]
+ (if type-omitted?
+ (swap! narrowed conj
+ {:excluded (set bad)
+ :label "collection_id"
+ :because "don't live in collections"})
+ (common/throw-teaching-error
+ (format (str "collection_id cannot filter %s — these types don't live in collections. "
+ "Remove them from type or drop collection_id.")
+ (str/join ", " bad)))))
+ (when (contains? types "snippet")
+ (common/throw-teaching-error
+ "collection_id cannot filter snippets — list them with type: [\"snippet\"] and no collection_id."))
+ (when (contains? types "transform")
+ (common/throw-teaching-error
+ "collection_id cannot filter transforms — the search index doesn't record their collection. Remove transform from type or drop collection_id."))
+ (when (and (contains? types "table")
+ (not (premium-features/has-feature? :library)))
+ (common/throw-teaching-error
+ "Filtering tables by collection_id requires the Library feature, which this instance doesn't have — remove table from type or drop collection_id."))
+ ;; Two more types a collection-scoped search never covers, each dropped by a different part of
+ ;; the engine rather than by the spec's collection attr: transform (no collection recorded in
+ ;; the index, so `search-context->applicable-models` drops the model) and, without the Library
+ ;; feature, table (excluded by the ::collection-hierarchy where-clause). Named explicitly each
+ ;; is a teaching error above; with `type` omitted they must be narrowed and disclosed, not
+ ;; dropped in silence.
+ (when type-omitted?
+ (when (contains? effective-types "transform")
+ (swap! narrowed conj
+ {:excluded #{"transform"}
+ :label "collection_id"
+ :because "isn't recorded with a collection in the search index"}))
+ (when (and (contains? effective-types "table")
+ (not (premium-features/has-feature? :library)))
+ (swap! narrowed conj
+ {:excluded #{"table"}
+ :label "collection_id"
+ :because "isn't filtered by collection without the Library feature"}))))
+ (when (true? archived)
+ (when-let [bad (seq (sort (filter non-archivable-types effective-types)))]
+ (if type-omitted?
+ (swap! narrowed conj
+ {:excluded (set bad)
+ :label "archived: true"
+ :because "have no archived state"})
+ (common/throw-teaching-error
+ (format (str "archived: true cannot filter %s — these types have no archived state. "
+ "Remove them from type or drop archived.")
+ (str/join ", " bad))))))
+ (when (true? (:recent args))
+ (when-let [bad (seq (sort (remove (set (keys type->rv-model)) types)))]
+ (common/throw-teaching-error
+ (format "Recents only track %s — remove %s from type or drop recent: true."
+ (str/join ", " (sort (keys type->rv-model)))
+ (str/join ", " bad))))
+ (when (or created_by (collection-scoping? args) (true? archived))
+ (common/throw-teaching-error
+ "recent: true supports only the type filter — drop collection_id, created_by, and archived.")))
+ (if (seq @narrowed)
+ (let [final-types (vec (sort (reduce set/difference effective-types (map :excluded @narrowed))))
+ type-list (str/join ", " final-types)]
+ {:types final-types
+ :disclosures (mapv (fn [{:keys [excluded label because]}]
+ (format "%s narrowed the search to %s — %s %s."
+ label type-list (str/join ", " (sort excluded)) because))
+ @narrowed)})
+ {:types nil :disclosures []})))
+
+(defn- resolve-collection-filter
+ "Resolve the `collection_id` argument to a numeric collection id behind the collection's read
+ check, or nil when it means the root (no scoping). Sentinel handling is delegated to
+ [[v2.resolve/resolve-collection-id]] — nil/\"root\" resolve to nil, \"trash\" is a teaching error —
+ and a real id still gets the read check the REST endpoint runs. The search context takes numeric
+ ids only, so entity_ids are translated here."
+ [collection-id]
+ (when-let [id (v2.resolve/resolve-collection-id collection-id)]
+ (:id (v2.resolve/resolve-and-read :model/Collection id))))
+
+;;; ------------------------------------------------ Recents mode --------------------------------------------------
+
+(defn- recent-item->row
+ [fmt {:keys [model parent_collection] :as item}]
+ (case fmt
+ :concise (-> {:type (rv-model->type model)
+ :id (:id item)
+ :name (:name item)}
+ (m/assoc-some :collection_path (:name parent_collection)
+ :description (:description item)))
+ :detailed (assoc item :type (rv-model->type model))))
+
+(defn- recents-page
+ [{:keys [type]} fmt limit offset]
+ (let [models (into [] (comp (map type->rv-model) (distinct)) type)
+ {:keys [recents]} (activity-feed/get-recents api/*current-user-id*
+ [:views :selections]
+ {:models models})
+ page (into [] (comp (drop offset) (take limit)) recents)]
+ {:rows (mapv #(recent-item->row fmt %) page)
+ :total (count recents)}))
+
+(defn- recents-floor-line
+ "The floor line for a full recents page: `total` is never an exact count for recents (the
+ per-model retention cap, dropped unreadable/inconsistent rows), so [[common/truncation-line]]'s
+ arithmetic (which only fires when the page is truncated) silently omits any line when a page
+ happens to reach `total` exactly — reading as \"this is everything\" when it's actually the cap.
+ Recents can't be paged past that cap (there is nothing stored beyond it), so this steers to
+ narrowing with `type` rather than an offset, unlike the ordinary truncation line."
+ [{:keys [returned total offset limit]}]
+ (when (and (pos? total) (pos? returned) (>= (+ offset limit) total))
+ (format "Returned %d of at least %d — this is a capped view; narrow with `type` to reach specific items."
+ returned total)))
+
+;;; ---------------------------------------------- Snippet union ---------------------------------------------------
+
+;; TODO(GHY-4171): snippets are a bolt-on — not in the search engine, so they can't be scored,
+;; ranked, or fused, and must be listed and paged on their own track (the reason the
+;; snippet-exclusivity teaching error exists). Moving them into the engine lets this function, that
+;; error, and the namespace redirect all be deleted.
+(defn- snippet-rows
+ "Snippet rows for the server-side union: all (non-)archived snippets the caller can read —
+ filtered per row through `mi/can-read?`, so EE snippet-folder permissions and the
+ sandboxed-user exclusion apply — optionally narrowed to names containing any query as a
+ case-insensitive substring."
+ [queries archived]
+ (let [readable (filter mi/can-read? (mcp.db/snippets-by-archived-state archived))
+ matches (if (seq queries)
+ (let [needles (mapv u/lower-case-en queries)]
+ (filter (fn [{:keys [name]}]
+ (let [haystack (u/lower-case-en name)]
+ (some #(str/includes? haystack %) needles)))
+ readable))
+ readable)]
+ (mapv (fn [{:keys [id name description]}]
+ (cond-> {:type "snippet" :id id :name name}
+ description (assoc :description description)))
+ matches)))
+
+;;; ------------------------------------------------ Search mode ---------------------------------------------------
+
+(defn- engine-results
+ "Run the shared metabot search pipeline and return `{:rows [...] :total <int>}`. Rows are the
+ postprocessed+enriched results with `:collection_path` attached; `total` is the engine's match
+ count for the (fused) result set."
+ [{:keys [term_queries semantic_queries created_by archived]} entity-types collection-id limit offset]
+ ;; The tool redirects query-less listings to browse_*, so engine-results only ever runs with a
+ ;; query present — no :filters-only? branch to trip.
+ (let [results (metabot.search/search
+ (cond-> {:term-queries (vec term_queries)
+ :semantic-queries (vec semantic_queries)
+ :entity-types (vec entity-types)
+ :archived (true? archived)
+ :limit limit
+ :offset offset}
+ created_by (assoc :created-by #{api/*current-user-id*})
+ collection-id (assoc :collection-id collection-id)))]
+ {:rows (add-collection-paths (vec results))
+ :total (:total (meta results))}))
+
+;;; -------------------------------------------------- The tool ----------------------------------------------------
+
+(def ^:private type-desc
+ (str "Restrict results to these entity types. \"snippet\" is served by a separate listing "
+ "(snippets aren't in the search index), requires the " metabot.scope/agent-content-read
+ " scope, and must be requested on its own — combining it with other types is an error. "
+ "Omit to search every type this tool supports except snippets."))
+
+(def ^:private search-args-schema
+ [:map {:closed true}
+ [:term_queries {:optional true}
+ [:maybe [:sequential [:string {:min 1 :description "A keyword query matched against names and descriptions via full-text search. Each query runs separately; results are merged by rank."}]]]]
+ [:semantic_queries {:optional true}
+ [:maybe [:sequential [:string {:min 1 :description "A natural-language query matched by semantic similarity when a semantic engine is active (keyword-ranked otherwise). Each query runs separately; results are merged by rank."}]]]]
+ [:recent {:optional true}
+ [:maybe [:boolean {:description "true returns your recently viewed items instead of searching. Combines with type (only question, model, metric, dashboard, document, collection, table are tracked) but not with queries or other filters. Reflects Metabase UI views only — content you read through these tools is not recorded as a view, so a fresh token's recents can be empty even after get_content calls in the same session."}]]]
+ [:type {:optional true}
+ [:maybe [:sequential (into [:enum {:description type-desc}] all-types)]]]
+ [:collection_id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric collection id."}]
+ [:string {:description "A 21-character entity_id, or \"root\" for no scoping."}]]]]
+ [:created_by {:optional true}
+ [:maybe [:enum {:description "\"me\" restricts results to items you created. Only question, model, metric, dashboard, document, measure, and action index a creator."} "me"]]]
+ [:archived {:optional true}
+ [:maybe [:boolean {:description "true searches the trash instead of active content."}]]]
+ [:limit {:optional true}
+ [:maybe [:int {:min 1 :max 50 :description "Maximum results to return (default 20, max 50)."}]]]
+ [:offset {:optional true}
+ [:maybe [:int {:min 0 :description "Number of results to skip, for paging (default 0)."}]]]
+ [:response_format {:optional true}
+ [:maybe [:enum {:description "concise (default) returns {type, id, name, collection_path, description} rows; detailed returns the full search-result rows."} "concise" "detailed"]]]
+ [:fields {:optional true}
+ [:maybe [:sequential [:string {:min 1 :description "Dot-paths picked from the detailed row shape, item-relative (e.g. \"collection.name\"). Mutually exclusive with response_format."}]]]]])
+
+(defn- project-rows
+ [args rows]
+ (if-let [fields (:fields args)]
+ (common/select-fields :search-result
+ (mapv #(projections/project :search-result :detailed %) rows)
+ fields
+ {:response-format (:response_format args)})
+ (let [fmt (common/response-format args)]
+ (mapv #(projections/project :search-result fmt %) rows))))
+
+(defn- append-lines
+ "Append extra lines (a disclosure, a floor line) to the text block of an already-built MCP
+ response, after whatever steering line `common/list-content` appended."
+ [content lines]
+ (if (seq lines)
+ (update-in content [:content 0 :text] str "\n" (str/join "\n" lines))
+ content))
+
+(registry/deftool search-tool
+ "Find content across the Metabase instance by relevance. Two modes: (1) ranked search — term_queries (keywords)
+ and/or semantic_queries (natural language), optionally narrowed by type, collection_id (scopes to the collection
+ subtree), created_by: \"me\", archived: true; (2) recent: true — your recently viewed items. A query is required
+ for mode (1): to browse or list without one (a collection's contents, a database's tables, your content in a
+ collection), use browse_collection or browse_data instead — this tool redirects query-less listings there.
+ type: [\"snippet\"] searches SQL snippets you can read by name and must be requested on its own, not alongside
+ other types. Transforms are searchable by admins only — other users browse them with browse_collection(namespace:
+ \"transforms\"). Returns {data, returned, total}; total is the number of matches, capped at the search ranking
+ limit — so a large total is a floor (the response says \"at least N\"). An empty {data: [], total: 0} means no
+ match against the search index, which on a freshly started instance can still be building — if content you can
+ reach with browse_collection or browse_data does not turn up here, prefer those over concluding it is absent." {:name "search"
+ :scope metabot.scope/agent-content-read
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :args search-args-schema}
+ [{:keys [term_queries semantic_queries recent type collection_id archived] :as args} _]
+ (let [queries? (boolean (or (seq term_queries) (seq semantic_queries)))
+ filters? (boolean (or (seq type)
+ (collection-scoping? args)
+ (:created_by args)
+ (true? archived)))
+ limit (or (:limit args) 20)
+ offset (or (:offset args) 0)]
+ (validate-modes! args queries? filters?)
+ (let [{:keys [types disclosures]} (validate-filters! args)]
+ (if (true? recent)
+ (let [fmt (if (:fields args)
+ (common/throw-teaching-error
+ "`fields` is not supported with recent: true — use response_format instead.")
+ (common/response-format args))
+ {:keys [rows total]} (recents-page args fmt limit offset)
+ ;; RecentViews retains at most 20 rows per user per model per context and drops
+ ;; unreadable/inconsistent rows, so `total` (the size of that already-capped,
+ ;; already-filtered set) is a floor on how much the user has actually viewed, never
+ ;; an exact count.
+ floor-line (recents-floor-line {:returned (count rows) :total total :offset offset :limit limit})]
+ (append-lines
+ (common/list-content rows total {:param :type :offset offset :limit limit :total-floor? true})
+ (cond-> [] floor-line (conj floor-line))))
+ ;; `validate-filters!` has already rejected snippet alongside any other type, so these
+ ;; two listings are mutually exclusive and each pages on its own terms.
+ (let [caller-types (into [] (distinct) type)
+ {:keys [rows total total-floor?]}
+ (if (contains? (set caller-types) "snippet")
+ (let [snippets (snippet-rows (concat term_queries semantic_queries) archived)]
+ {:rows (into [] (comp (drop offset) (take limit)) snippets)
+ :total (count snippets)
+ :total-floor? false})
+ ;; `types` is validate-filters!'s narrowed type set — non-nil only when `type` was
+ ;; omitted and a filter (created_by/collection_id/archived) supports only some of
+ ;; the engine's types, in which case it replaces the full engine surface below.
+ (let [engine-types (into [] (remove #{"snippet"})
+ (cond
+ types types
+ (seq caller-types) caller-types
+ :else all-types))
+ collection-id (when (contains? args :collection_id)
+ (resolve-collection-filter collection_id))
+ engine (engine-results args engine-types collection-id limit offset)]
+ ;; The engine total is the size of the ranked pool, capped at the search ranking
+ ;; limit — so it is a floor, not an exact count, when the cap is hit.
+ {:rows (vec (:rows engine)) :total (:total engine) :total-floor? true}))]
+ (append-lines
+ (common/list-content (project-rows args rows) total
+ {:param :type :offset offset :limit limit :total-floor? total-floor?})
+ disclosures))))))
diff --git a/src/metabase/mcp/v2/tools/subscription.clj b/src/metabase/mcp/v2/tools/subscription.clj
new file mode 100644
index 00000000000..b4454edd101
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/subscription.clj
@@ -0,0 +1,490 @@
+(ns metabase.mcp.v2.tools.subscription
+ "The v2 MCP `subscription_write` tool: scheduled delivery of a dashboard — \"send me this
+ dashboard every Monday morning\".
+
+ Backed by the pulse API, which is deprecated but live and still what the product's
+ subscription sidebar uses; it is also the only option, since the notification API has no
+ dashboard payload wired up. A future move to `/api/notification` changes the backing, not this
+ tool's contract.
+
+ The tool speaks one delivery target at a time — a channel type, a schedule, and a recipient
+ list — while a Pulse is a list of channels. Writes therefore patch the one channel of the
+ named type and leave the others alone, so a subscription the app created with both email and
+ Slack survives an edit here. Permission enforcement, transactionality, and event publishing
+ are inherited from [[metabase.pulse.api/create-pulse-with-perm-checks!]] and
+ [[metabase.pulse.api/update-pulse-with-perm-checks!]] — the same fns the REST endpoints call."
+ (:require
+ [clojure.string :as str]
+ [medley.core :as m]
+ [metabase.api.common :as api]
+ [metabase.channel.settings :as channel.settings]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.scope :as mcp.scope]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.recipients :as mcp.recipients]
+ [metabase.mcp.v2.redaction :as redaction]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.premium-features.core :as premium-features]
+ [metabase.pulse.api :as pulse.api]
+ [metabase.pulse.core :as pulse]
+ [metabase.util :as u]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+;;; ------------------------------------------------- Schedule -----------------------------------------------------
+
+(def ^:private schedule-fields-used
+ "The schedule fields the pulse channel writer reads, per schedule type. Anything outside its
+ type's set is dropped on the floor. Mirrors `alert_write`'s table over this tool's vocabulary,
+ which has no `:schedule_minute`."
+ {"hourly" #{}
+ "daily" #{:schedule_hour}
+ "weekly" #{:schedule_hour :schedule_day}
+ "monthly" #{:schedule_hour :schedule_frame :schedule_day}})
+
+(def ^:private schedule-field-advice
+ "What to do instead, per field a schedule type doesn't read."
+ {:schedule_hour "an hourly schedule sends every hour — use \"daily\", \"weekly\", or \"monthly\" to send at one hour"
+ :schedule_day "use \"weekly\", or \"monthly\" with schedule_frame \"first\" or \"last\", to send on a weekday"
+ :schedule_frame "only a monthly schedule sends on a frame of the month"})
+
+(defn- check-ignored-schedule-fields!
+ "Reject a schedule field the caller's `schedule_type` doesn't read. `create-pulse-channel!`
+ nils such a field out silently, so the subscription would deliver on a schedule nobody asked
+ for while the call reports success — `{hourly, schedule_hour 9}` sends 24 times a day, not once
+ at nine. Only a non-nil value counts: the strict-client transform lists every property as
+ required and spells \"no value\" as null, so a filled-in null is an omission, not a request."
+ [{:keys [schedule_type] :as schedule}]
+ (let [used (get schedule-fields-used schedule_type #{})
+ ignored (->> (keys schedule-field-advice)
+ (filter #(some? (get schedule %)))
+ (remove used)
+ sort
+ first)]
+ (when ignored
+ (common/throw-teaching-error
+ (format "%s %s schedule doesn't use %s, so it would be ignored — %s."
+ (if (= "hourly" schedule_type) "An" "A")
+ schedule_type (name ignored) (schedule-field-advice ignored))))))
+
+(defn- check-schedule!
+ "Reject a schedule the pulse channel would reject or mis-encode: one missing a field its type
+ needs, or one carrying a field its type doesn't read. `create-pulse-channel!`'s validation is an
+ assertion, so an incomplete schedule would otherwise surface as a generic internal error
+ instead of a sentence naming the missing field, and it drops a surplus field silently. Kept in
+ step with `alert_write`'s check of the same vocabulary, so an agent that has learned one tool's
+ schedule has learned the other's."
+ [{:keys [schedule_type schedule_hour schedule_day schedule_frame] :as schedule}]
+ (letfn [(require! [v field explanation]
+ (when (nil? v)
+ (common/throw-teaching-error
+ (format "A %s schedule needs %s — %s." schedule_type field explanation))))]
+ (case schedule_type
+ "hourly" nil
+ "daily" (require! schedule_hour "schedule_hour" "the hour of the day to send, 0-23")
+ "weekly" (do (require! schedule_hour "schedule_hour" "the hour of the day to send, 0-23")
+ (require! schedule_day "schedule_day" "the day of the week, e.g. \"mon\""))
+ "monthly" (do (require! schedule_hour "schedule_hour" "the hour of the day to send, 0-23")
+ (require! schedule_frame "schedule_frame" "\"first\", \"mid\", or \"last\"")
+ (when (and (= "mid" schedule_frame) schedule_day)
+ (common/throw-teaching-error
+ "A monthly schedule with schedule_frame \"mid\" sends on the 15th, so it cannot also take a schedule_day — drop schedule_day, or use frame \"first\" or \"last\" to send on a particular weekday.")))))
+ (check-ignored-schedule-fields! schedule))
+
+;;; ------------------------------------------------- Channels -----------------------------------------------------
+
+(defn- recipient-maps
+ "Turn the tool's flat recipient list — user ids and raw email addresses — into the
+ `{:id user-id}` / `{:email address}` maps a pulse channel stores."
+ [recipients]
+ (mapv (fn [recipient]
+ (let [[kind value] (mcp.recipients/classify recipient)]
+ (case kind
+ :user {:id value}
+ :email {:email value})))
+ recipients))
+
+(defn- slack-details
+ "The `details` map for a Slack channel: the cached channel's display name, which is what the
+ sender reads, plus its `channel_id`. The sender prefers the id over the name, so that delivery
+ survives a channel rename; a details map carrying only the name is the legacy fallback shape.
+ An unknown name is rejected here rather than at send time, hours later."
+ [slack-channel]
+ (when-not (channel.settings/slack-configured?)
+ (common/throw-teaching-error
+ "Slack is not connected to this Metabase — ask an admin to set it up in Admin settings, or use channel \"email\"."))
+ (when (str/blank? slack-channel)
+ (common/throw-teaching-error
+ "channel \"slack\" needs a slack_channel — the name of the channel to post to, e.g. \"data-team\"."))
+ (let [entry (channel.settings/find-cached-slack-channel-or-username slack-channel)
+ display-name (:display-name entry)]
+ (when-not display-name
+ (common/throw-teaching-error
+ (format "Metabase can't see a Slack channel or user named %s, so a subscription to it would deliver nowhere — check the name, or invite the Metabase Slack app to the channel."
+ (pr-str slack-channel))))
+ ;; Unconditional rather than `cond->`: the details map is merged onto the stored one, and the
+ ;; sender prefers `:channel_id` over the name. An entry without an id would otherwise leave the
+ ;; *previous* channel's id in place, so a repoint would show the new name and deliver to the old
+ ;; channel. Every cache entry the Slack API builds carries an id, so this only rules out a shape
+ ;; that cannot occur — cheaply.
+ {:channel display-name :channel_id (:id entry)}))
+
+(def ^:private schedule-keys
+ [:schedule_type :schedule_hour :schedule_day :schedule_frame])
+
+(defn- effective-schedule
+ "The schedule the channel ends up on: the caller's when they sent one, otherwise the one
+ `existing` already carries (stored as keywords, restated as the strings this tool speaks).
+ Validated either way, so adding a channel to a subscription can't skip the check."
+ [existing schedule]
+ (let [s (if schedule
+ (select-keys schedule schedule-keys)
+ (-> (u/select-non-nil-keys existing schedule-keys)
+ (u/update-if-exists :schedule_type name)
+ (u/update-if-exists :schedule_frame name)))]
+ (when (str/blank? (:schedule_type s))
+ (common/throw-teaching-error
+ "`schedule` is required to add a delivery channel — pass {schedule_type: \"hourly\" | \"daily\" | \"weekly\" | \"monthly\", …}."))
+ (check-schedule! s)
+ (u/select-non-nil-keys s schedule-keys)))
+
+(defn- build-channel
+ "Merge the caller's delivery arguments onto `existing` (the subscription's current channel of
+ this type, or nil when there isn't one yet). Only the arguments actually present change, so a
+ caller who sends just a schedule keeps the channel's recipients — and its row, since the
+ preserved `:id` makes [[metabase.pulse.core/update-pulse!]] update rather than recreate it.
+
+ `enabled?` must be the negation of the subscription's resulting `archived` state. A Pulse
+ encodes \"archived\" by disabling every one of its channels, and the channel write lands after
+ the Pulse write, so an `:enabled` that disagrees resurrects a trashed subscription: its Quartz
+ send trigger is re-registered and it keeps delivering from the trash."
+ [existing channel-type enabled? {:keys [schedule recipients slack_channel] :as args}]
+ (when (and (= "slack" channel-type) (contains? args :recipients))
+ (common/throw-teaching-error
+ "A Slack subscription posts to a channel and has no recipient list — drop recipients, or use channel \"email\" to send to people."))
+ (when (and (= "email" channel-type) (contains? args :recipients) (empty? recipients))
+ (common/throw-teaching-error
+ "An empty recipients list would deliver this subscription to nobody — pass at least one user id or email address, or omit recipients to leave the current recipients alone."))
+ (when (and (= "email" channel-type) slack_channel)
+ (common/throw-teaching-error
+ "`slack_channel` only applies to a Slack subscription — pass channel \"slack\" to post there, or drop slack_channel to keep delivering by email."))
+ (merge {:channel_type channel-type
+ :enabled enabled?}
+ (select-keys existing [:id])
+ (effective-schedule existing schedule)
+ (case channel-type
+ ;; `:details` carries the channel's format choices (attach PDF, attachment-only) that the
+ ;; app sets; the pulse-channel update rewrites the column from what it is handed, so an edit
+ ;; that omits them would silently erase them.
+ "email" {:details (or (:details existing) {})
+ :recipients (if (contains? args :recipients)
+ (recipient-maps recipients)
+ (or (:recipients existing)
+ [{:id api/*current-user-id*}]))}
+ ;; Same hazard as the email branch: the pulse-channel update rewrites `:details`
+ ;; wholesale, so repointing a Slack channel has to merge onto what is already stored
+ ;; rather than replace it — otherwise `include_pdf`/`attachment_only` set in the app are
+ ;; erased. `slack-details` supplies a fresh `:channel_id`, which overwrites the stale one
+ ;; for the channel we just moved off.
+ "slack" {:details (if slack_channel
+ (merge (:details existing) (slack-details slack_channel))
+ (or (not-empty (:details existing))
+ (slack-details nil)))}
+ ;; `:http` (webhook) is a real PulseChannel type this tool doesn't build, and
+ ;; `target-channel-type` reaches it by reading an existing subscription's only channel.
+ ;; Without this the `case` throws an IllegalArgumentException that surfaces as a bare
+ ;; "Internal error", which tells the agent nothing about what to do instead.
+ (common/throw-teaching-error
+ (format (str "This subscription delivers over \"%s\", which this tool cannot edit — it handles "
+ "\"email\" and \"slack\". Edit it in Metabase, or create a separate email or Slack "
+ "subscription for the dashboard.")
+ channel-type)))))
+
+(defn- target-channel-type
+ "Which of the subscription's channels this call edits. Explicit `channel` wins; otherwise a
+ subscription with exactly one channel is unambiguous. A subscription with several channels has
+ to be told, rather than have one picked for it."
+ [channel existing-channels]
+ (or channel
+ (when (= 1 (count existing-channels))
+ (name (:channel_type (first existing-channels))))
+ (common/throw-teaching-error
+ (format "This subscription delivers to %d channels, so pass `channel` (\"email\" or \"slack\") to say which one to change."
+ (count existing-channels)))))
+
+(defn- channel-affecting?
+ "Does `args` ask for a change to the delivery channel at all? An update that only touches
+ `archived` or `parameters` must leave the channel list out of the payload entirely — sending
+ it back would re-register the send trigger for no reason."
+ [args]
+ (boolean (some #(contains? args %) [:schedule :channel :slack_channel :recipients])))
+
+;;; ------------------------------------------------ Parameters ----------------------------------------------------
+
+(defn- resolve-parameters
+ "Validate that every `{id, value}` names a parameter the dashboard actually has. A subscription
+ stores only the id and value; the dashboard's own definition of the parameter is merged in at
+ send time, so an id that matches nothing is stored and then silently ignored.
+
+ Refused outright without the `dashboard-subscription-filters` feature: the send-time merge is the
+ EE half of `notification.payload.impl.dashboard/the-parameters`, and the OSS one returns the
+ dashboard's own parameters untouched. Storing the pairs there would report a filtered subscription
+ that delivers unfiltered."
+ [parameters dashboard-parameters]
+ (when (and (seq parameters) (not (premium-features/enable-dashboard-subscription-filters?)))
+ (common/throw-teaching-error
+ (str "Filtered subscriptions need the dashboard-subscription-filters feature, which this instance "
+ "doesn't have — the filter values would be stored and then ignored at send time. Omit "
+ "`parameters` to subscribe to the dashboard's own default filter values.")))
+ (let [known (into #{} (map (comp u/qualified-name :id)) dashboard-parameters)]
+ (doseq [{param-id :id} parameters]
+ (when-not (contains? known param-id)
+ (common/throw-teaching-error
+ (format "The dashboard has no parameter %s. Its parameter ids are: %s."
+ (pr-str param-id)
+ (if (seq known) (str/join ", " (sort known)) "(none)")))))
+ (mapv #(select-keys % [:id :value]) parameters)))
+
+;;; -------------------------------------------------- Create ------------------------------------------------------
+
+(defn- subscription-cards
+ "The pulse's `cards` list, assembled from the dashboard's dashcards as the subscription sidebar
+ does: every card-backed dashcard, in layout order, tagged with the `dashboard_card_id` it came
+ from. Virtual dashcards (text, headings, links) have no card and are skipped. Each card is
+ read-checked, since subscribing to it delivers its results. A dashboard with no cards is a
+ teaching error.
+
+ This list does not decide what a send renders — the dashboard payload re-executes the whole
+ dashboard by id. It exists because [[metabase.pulse.core/create-pulse!]] requires at least one
+ card ref, and because `dashboard_card_id` is what the email channel matches per-card attachment
+ flags against for visualizer dashcards."
+ [dashboard]
+ (let [cards (for [{dashcard-id :id :keys [card]} (sort-by (juxt #(or (:row %) 0) #(or (:col %) 0))
+ (:dashcards dashboard))
+ :when (int? (:id card))]
+ (-> (api/read-check card)
+ (select-keys [:id :name :collection_id :description :display :parameter_mappings])
+ (assoc :dashboard_card_id dashcard-id :dashboard_id (:id dashboard))))]
+ (when (empty? cards)
+ (common/throw-teaching-error
+ "This dashboard has no cards to send — a subscription needs at least one saved question, model, or metric on the dashboard."))
+ (vec cards)))
+
+(defn- create!
+ [{:keys [dashboard_id channel parameters skip_if_empty] :as args}]
+ (let [dashboard (-> (v2.resolve/resolve-and-read :model/Dashboard dashboard_id)
+ (t2/hydrate [:dashcards :card]))
+ cards (subscription-cards dashboard)
+ channel (build-channel nil (or channel "email") true args)
+ ;; `collection_id` is deliberately nil rather than the dashboard's: the Pulse model derives
+ ;; it from `dashboard_id`, and naming it here would make the create-check demand *write*
+ ;; access to the dashboard's collection — anyone who can view a dashboard can subscribe to
+ ;; it. Both collection keys must still be present, since the position reconciler requires
+ ;; them.
+ pulse (pulse.api/create-pulse-with-perm-checks!
+ cards
+ [channel]
+ {:name (:name dashboard)
+ :creator_id api/*current-user-id*
+ :dashboard_id (:id dashboard)
+ :collection_id nil
+ :collection_position nil
+ :skip_if_empty (boolean skip_if_empty)
+ :parameters (resolve-parameters parameters (:parameters dashboard))})]
+ (:id pulse)))
+
+;;; -------------------------------------------------- Update ------------------------------------------------------
+
+(defn- fetch-subscription
+ "The subscription behind its *write* check, hydrated. Alerts share the Pulse id space but are a
+ different concept with their own tool, so one collapses to not-found here.
+
+ The gate is `write-check` rather than `read-check` because everything [[update!]] does before
+ `update-pulse-with-perm-checks!` runs its own check — resolving parameter ids against the
+ dashboard, classifying recipients, naming the channel topology — would otherwise run for a
+ caller who only satisfies `can-read?`. For a subscription that is `(or superuser? creator?
+ recipient?)`, so merely being on the recipient list buys those answers about a dashboard in a
+ collection the caller cannot see. It also collapses the write check's 403 into the same
+ not-found everyone else gets, which is what keeps rejections from telling a recipient's
+ subscriptions apart from ids they know nothing about (the GHY-4217 pattern `alert_write`
+ carries). `update-pulse-with-perm-checks!` re-runs the check regardless, so this is additive."
+ [id-or-eid]
+ (v2.resolve/resolve-and-read-with
+ :model/Pulse id-or-eid
+ (fn [id]
+ (when (mcp.db/subscription-pulse-exists? id)
+ (api/write-check (pulse/retrieve-pulse id))))))
+
+(defn- patched-channels
+ "The subscription's full channel list with the targeted one replaced (or appended). The pulse
+ update path treats `:channels` as definitive — anything omitted is deleted — so the channels
+ this call doesn't touch have to ride along unchanged, apart from `:enabled`: that one tracks
+ the subscription's archived state for every channel, not just the edited one (see
+ [[build-channel]])."
+ [existing-channels channel enabled? args]
+ (let [channel-type (target-channel-type channel existing-channels)
+ same-type? #(= channel-type (name (:channel_type %)))]
+ (conj (mapv #(assoc % :enabled enabled?) (remove same-type? existing-channels))
+ (build-channel (m/find-first same-type? existing-channels) channel-type enabled? args))))
+
+(defn- update!
+ [id-or-eid {:keys [channel parameters skip_if_empty archived] :as args}]
+ (let [subscription (fetch-subscription id-or-eid)
+ archived? (if (contains? args :archived)
+ (boolean archived)
+ (boolean (:archived subscription)))
+ updates (cond-> {}
+ (contains? args :skip_if_empty) (assoc :skip_if_empty (boolean skip_if_empty))
+ (contains? args :archived) (assoc :archived (boolean archived))
+
+ (contains? args :parameters)
+ (assoc :parameters
+ (resolve-parameters
+ parameters
+ (mcp.db/dashboard-parameters (:dashboard_id subscription))))
+
+ (channel-affecting? args)
+ (assoc :channels (patched-channels (:channels subscription) channel
+ (not archived?) args)))]
+ (when (empty? updates)
+ (common/throw-teaching-error
+ "Nothing to update — pass at least one of schedule, channel, slack_channel, recipients, parameters, skip_if_empty, or archived."))
+ (pulse.api/update-pulse-with-perm-checks! (:id subscription) updates)
+ (:id subscription)))
+
+;;; -------------------------------------------------- Schema ------------------------------------------------------
+
+(def ^:private schedule-schema
+ [:map {:closed true
+ :description "When to deliver. Metabase sends at the top of the hour, in the instance's report time zone."}
+ [:schedule_type
+ [:enum {:description "How often to send."} "hourly" "daily" "weekly" "monthly"]]
+ [:schedule_hour {:optional true}
+ [:maybe [:int {:min 0 :max 23
+ :description "Hour of the day to send, 0-23. Required for daily, weekly, and monthly."}]]]
+ [:schedule_day {:optional true}
+ [:maybe [:enum {:description (str "Day of the week. Required for weekly; with a monthly "
+ "schedule_frame of \"first\" or \"last\" it picks that weekday "
+ "of the month.")}
+ "mon" "tue" "wed" "thu" "fri" "sat" "sun"]]]
+ [:schedule_frame {:optional true}
+ [:maybe [:enum {:description (str "Which part of the month to send on. Required for monthly. "
+ "\"mid\" is the 15th and takes no schedule_day.")}
+ "first" "mid" "last"]]]])
+
+(def ^:private subscription-write-args-schema
+ [:map {:closed true}
+ [:method
+ [:enum {:description (str "\"create\" subscribes to the dashboard named by `dashboard_id`; "
+ "\"update\" edits the subscription named by `id`.")}
+ "create" "update"]]
+ [:id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the subscription to update."}]
+ [:string {:description "21-character entity_id of the subscription to update."}]]]]
+ [:dashboard_id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the dashboard to deliver."}]
+ [:string {:description "21-character entity_id of the dashboard to deliver."}]]]]
+ [:schedule {:optional true} [:maybe schedule-schema]]
+ [:channel {:optional true}
+ [:maybe [:enum {:description (str "Where to deliver. Defaults to \"email\" on create; on update, "
+ "to the subscription's channel when it has exactly one.")}
+ "email" "slack"]]]
+ [:slack_channel {:optional true}
+ [:maybe [:string {:description "Slack channel or username to post to, e.g. \"data-team\". Required for channel \"slack\"."}]]]
+ [:recipients {:optional true}
+ [:maybe [:sequential {:description (str "Who gets the email: numeric user ids, or raw email "
+ "addresses for people without a Metabase account. "
+ "Defaults to you. On update this replaces the current list.")}
+ [:or [:int {:description "Numeric id of a Metabase user."}]
+ [:string {:min 1 :description "An email address."}]]]]]
+ [:parameters {:optional true}
+ [:maybe [:sequential {:description (str "Filter values applied to the dashboard before it is "
+ "sent, making a filtered subscription. Only ids the "
+ "dashboard actually has are accepted.")}
+ [:map {:closed true}
+ [:id [:string {:min 1 :description "Id of a dashboard parameter (from a dashboard read)."}]]
+ [:value [:any {:description "Value to filter by: a scalar, or an array for a multi-select parameter."}]]]]]]
+ [:skip_if_empty {:optional true}
+ [:maybe [:boolean {:description "When true, no email is sent if every card comes back empty. Default false."}]]]
+ [:archived {:optional true}
+ [:maybe [:boolean {:description (str "Update only: true pauses the subscription and moves it to "
+ "the trash, false restores it. This is the only removal path.")}]]]])
+
+(def ^:private subscription-write-entry
+ {:create-required [:dashboard_id :schedule]})
+
+(defn- check-query-execute-scope!
+ "A subscription is a scheduled run of every question on its dashboard with the results delivered,
+ so establishing one — or redirecting where one delivers — needs the same scope that seeing those
+ results in-session would. The send itself happens later, tokenlessly, under the creator's
+ permissions; this check at write time is the only place the token's scopes can bound that
+ deferred execution. No-op for unscoped callers (cookie sessions bind the unrestricted sentinel,
+ which matches everything). Mirrors alert_write's check of the same scope."
+ [token-scopes action]
+ (when-not (mcp.scope/matches? token-scopes metabot.scope/agent-query-run)
+ (throw (ex-info (format (str "%s runs the dashboard's questions and delivers the results, which requires the "
+ "%s scope — this token can manage subscriptions but not execute queries.")
+ action metabot.scope/agent-query-run)
+ {:status-code 403 ::common/error-code common/error-code-invalid-request}))))
+
+(defn- execute-scope-trigger
+ "The reason [[check-query-execute-scope!]] should refuse `updates` with, or nil when the update
+ commits the subscription to nothing it wasn't already committed to. Every field that newly puts
+ the dashboard in front of the scheduler counts, not just the delivery target: restoring a trashed
+ subscription restarts the sends, and a new schedule changes how often they happen. Trashing
+ (`archived: true`) is deliberately absent — a kill switch must never need more scope than the
+ thing it kills. The subscription's stored state is not consulted, so `archived: false` on a live
+ subscription is refused too: telling that no-op from a real restore would take a read the token
+ may not be entitled to. Mirrors alert_write's trigger set."
+ [updates]
+ (cond
+ (some #(contains? updates %) [:channel :slack_channel :recipients])
+ "Changing where a subscription delivers"
+
+ (false? (:archived updates))
+ "Restoring a trashed subscription"
+
+ (contains? updates :schedule)
+ "Changing a subscription's schedule"))
+
+(registry/deftool subscription-write
+ "Create or update a dashboard subscription — scheduled delivery of a whole dashboard, e.g. \"send me this dashboard
+ every Monday morning\". method: \"create\" requires dashboard_id and schedule; method: \"update\" requires id and
+ accepts archived (true pauses and trashes it, false restores — there is no hard delete). The server assembles what
+ gets sent from the dashboard's own cards, so you never list them. schedule is {schedule_type: \"hourly\" | \"daily\"
+ | \"weekly\" | \"monthly\", schedule_hour?, schedule_day?, schedule_frame?} — daily and up need schedule_hour,
+ weekly also needs schedule_day, monthly needs schedule_frame. channel is \"email\" (default) or \"slack\"; Slack
+ needs slack_channel, email takes recipients (user ids or raw email addresses, defaulting to you). parameters
+ ({id, value} pairs naming the dashboard's own filters) makes a filtered subscription. On update, only the fields
+ you pass change: a schedule-only update keeps the recipients, and a recipients list replaces the current one.
+ A subscription that already delivers to both email and Slack needs channel to say which to edit. Creating a
+ subscription, changing its delivery or its schedule, or restoring a trashed one additionally requires the
+ agent:query:run scope — the subscription runs the dashboard's questions and delivers the results. Trashing one
+ never does. This is for dashboards on a schedule — use alert_write for a
+ question that fires on a condition. Requires read permission on the dashboard; only its creator (or an admin) can
+ update it."
+ {:name "subscription_write"
+ :scope metabot.scope/agent-delivery-write
+ :annotations {:readOnlyHint false :destructiveHint false}
+ :args subscription-write-args-schema}
+ [args {:keys [token-scopes]}]
+ (let [[op a b] (v2.write/dispatch-write subscription-write-entry args)
+ id (case op
+ :create (do (check-query-execute-scope! token-scopes "Creating a subscription")
+ (create! a))
+ :update (do (when-let [reason (execute-scope-trigger b)]
+ (check-query-execute-scope! token-scopes reason))
+ (update! a b)))]
+ (common/success-content
+ (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (projections/project :subscription :concise
+ (projections/subscription-row
+ (redaction/redact-pulse (pulse/retrieve-pulse id))))
+ nil))))
diff --git a/src/metabase/mcp/v2/tools/transform.clj b/src/metabase/mcp/v2/tools/transform.clj
new file mode 100644
index 00000000000..253d3ff2d6d
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/transform.clj
@@ -0,0 +1,433 @@
+(ns metabase.mcp.v2.tools.transform
+ "The v2 MCP `transform_write` tool. A transform materializes a query into a table in the
+ warehouse; this tool creates and edits the query kind, routing through the same domain fns and
+ check stack `POST`/`PUT /api/transform` run ([[metabase.transforms.core]]), so feature gating,
+ transforms permissions, target-table conflicts, schema requirements, and cycle detection are
+ inherited rather than reimplemented.
+
+ Its own work is the transform authoring contract: one query source (a `definition` in the same
+ shape `get_content`'s \"definition\" include returns, or a `query_handle` from an execute tool),
+ a `target` patched rather than replaced so a rename keeps its schema, and refusing the two shapes
+ it cannot author — python sources and incremental targets — instead of silently rewriting them."
+ (:require
+ [clojure.string :as str]
+ [metabase.agent-api.query-guards :as query-guards]
+ [metabase.api.common :as api]
+ [metabase.channel.urls :as channel.urls]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.mcp.scope :as mcp.scope]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.mcp.v2.write :as v2.write]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.models.interface :as mi]
+ [metabase.transforms.core :as transforms]
+ [metabase.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private accepted-shapes
+ "The sentence every source-shape teaching error ends with, naming what `definition` accepts."
+ (str "`definition` is a transform source: {\"type\": \"query\", \"query\": …} — exactly what "
+ "get_content's \"definition\" include returns for a transform. The query inside is either "
+ "the same numeric-id dialect execute_query takes, or the older name-based dialect, still "
+ "resolved on input. "
+ "Alternatively pass a query_handle from execute_query or execute_sql instead of "
+ "`definition`."))
+
+(def ^:private python-note
+ "transform_write authors query transforms only — python transforms are written in Metabase.")
+
+;;; ----------------------------------------------- Source handling ------------------------------------------------
+
+(defn- normalize-transform-query
+ "Normalize a numeric-ref query — hand-written MBQL 5, MBQL 4 (which normalizes into it), a
+ resolved portable query, or a handle's stored query — into the canonical MBQL 5 the transform
+ stores. Strict, so a malformed query is a teaching error here rather than a failure at the next
+ run."
+ [query]
+ (try
+ (lib-be/normalize-query nil query {:strict? true})
+ (catch Exception e
+ (common/throw-teaching-error
+ (format "The transform's query is not valid MBQL: %s %s"
+ (common/ellipsize (ex-message e) 300) accepted-shapes)))))
+
+(defn- definition->query
+ "The query inside a caller-supplied `definition`, resolved to canonical MBQL 5. Source kinds this
+ tool can't author are refused here rather than stored in a degraded form."
+ [definition]
+ (let [source-type (some-> (:type definition) name)]
+ (cond
+ ;; A legacy MBQL query carries `:type "query"` and `:query` too, so it reads as a source map
+ ;; and fails much later on the inner query. Name the wrap instead.
+ (or (contains? definition :database) (contains? definition :stages))
+ (common/throw-teaching-error
+ (str "`definition` is a query, not a transform source — wrap it: "
+ "{\"type\": \"query\", \"query\": <your query>}."))
+
+ (= "python" source-type)
+ (common/throw-teaching-error (str "This is a python transform's definition. " python-note))
+
+ (not= "query" source-type)
+ (common/throw-teaching-error
+ (format "`definition.type` is %s. %s" (pr-str source-type) accepted-shapes))
+
+ (contains? definition :source-incremental-strategy)
+ (common/throw-teaching-error
+ (str "`definition.source-incremental-strategy` sets up incremental (checkpoint) loading, which "
+ "transform_write can't author — configure it in Metabase, and edit the query here without it."))
+
+ :else
+ (let [query (or (:query definition)
+ (common/throw-teaching-error (str "`definition` has no `query`. " accepted-shapes)))]
+ (normalize-transform-query
+ (if (v2.queries/portable-query? query)
+ (v2.queries/resolve-external-query query accepted-shapes)
+ query))))))
+
+(defn- check-native-source-gates!
+ "The gates an inline native `definition` passes: the `agent:sql:run` scope and the
+ `mcp-execute-sql-enabled` kill switch — `execute_sql`'s own two. A stored native transform is raw
+ SQL the transform runner later executes against the warehouse as a CTAS, so accepting one under the
+ content write scope alone would rebuild `execute_sql` (with a write to the warehouse on top) without
+ its scope or its kill switch. Same gate `question_write` puts on its native sources. A
+ `query_handle` needs neither here: minting one already passed them. No-op on the scope half for
+ unscoped callers (cookie sessions bind the unrestricted sentinel, which matches everything)."
+ [token-scopes]
+ (when-not (mcp.scope/matches? token-scopes metabot.scope/agent-sql-run)
+ (throw (ex-info (format (str "Saving a native (SQL) transform requires the %s scope — this token can "
+ "write content but not author raw SQL.")
+ metabot.scope/agent-sql-run)
+ {:status-code 403 ::common/error-code common/error-code-invalid-request})))
+ (v2.queries/check-execute-sql-enabled! "Saving a native (SQL) transform"))
+
+(defn- resolve-source
+ "Resolve the caller's query source to the `source` map the transform stores. Exactly one of
+ `definition` and `query_handle` (a handle from an execute tool, re-checked for shape and
+ permissions on resolve — native included, so an execute_sql handle saves as a SQL transform) may
+ be present; `nil` when neither is, which on update means \"leave the stored source alone\".
+ An inline `definition` that carries native SQL — a legacy `:type :native` or an MBQL 5 native
+ stage, however nested — clears [[check-native-source-gates!]] first."
+ [{:keys [definition query_handle]} session-id token-scopes]
+ (when (and definition query_handle)
+ (common/throw-teaching-error
+ "Pass exactly one query source: `definition` (the transform's source) or `query_handle` (a handle from an execute tool)."))
+ (when-let [query (cond
+ definition (let [query (definition->query definition)]
+ (when (query-guards/native-query? query)
+ (check-native-source-gates! token-scopes))
+ query)
+ query_handle (-> (v2.queries/resolve-query-handle-for-save!
+ session-id api/*current-user-id* query_handle)
+ :query
+ normalize-transform-query))]
+ {:type "query" :query query}))
+
+;;; ----------------------------------------------- Target handling ------------------------------------------------
+
+(defn- resolve-target
+ "The `target` to store: the caller's fields laid over `existing` (nil on create), so
+ `target: {\"name\": …}` on update renames the output table without dropping its schema. Always a
+ plain `table` target — an incremental target carries a load strategy this tool can't author, and
+ overwriting one would silently turn an incremental transform into a full rebuild.
+
+ `type`, `database`, and the incremental strategy are derived rather than authored, but a read
+ hands them back on every target, so they are accepted to keep read-modify-write working and
+ refused only when they disagree with what this tool would write. `source-db-id` is the database
+ the query runs on, which the target always follows.
+
+ Nils are stripped first: the registry boundary only strips top-level nils, so a strict
+ client's nulls arrive inside `target` and would otherwise read as \"set this to nil\"."
+ [existing target source-db-id]
+ (let [{target-name :name, :keys [schema database] :as target} (u/remove-nils target)
+ existing-type (some-> (:type existing) name)
+ target-type (some-> (:type target) name)]
+ (when (and existing (not= "table" existing-type))
+ (common/throw-teaching-error
+ (format (str "This transform writes to a %s target, which transform_write can't edit — change it in "
+ "Metabase, or omit `target` to leave it alone.")
+ existing-type)))
+ (when (and target-type (not= "table" target-type))
+ (common/throw-teaching-error
+ (format (str "`target.type` is %s — transform_write authors plain \"table\" targets, rebuilt in full on "
+ "every run. Incremental targets are configured in Metabase; omit `target.type`.")
+ (pr-str target-type))))
+ (when (:target-incremental-strategy target)
+ (common/throw-teaching-error
+ (str "`target.target-incremental-strategy` sets up incremental (append/merge) loading, which "
+ "transform_write can't author — configure it in Metabase, and edit the transform here without it.")))
+ (when (and database source-db-id (not= database source-db-id))
+ (common/throw-teaching-error
+ (format (str "`target.database` is %d but the query reads from database %d — a transform writes to the "
+ "database its query reads, so the target database follows the query rather than being set "
+ "separately. Omit `target.database`, or point the query at database %d.")
+ database source-db-id database)))
+ (when (and (nil? existing) (nil? target-name))
+ (common/throw-teaching-error "`target.name` is required when method is \"create\" — it names the table the transform writes."))
+ ;; `:database` is derived from the query being stored, never carried over from `existing`: on a
+ ;; source-database swap the stored target would otherwise keep the OLD database while the query reads
+ ;; the new one, so the echo reports a database the transform does not write, and passing that echo
+ ;; back unchanged is refused by the check above — the tool rejecting the round-trip it promises.
+ (cond-> (assoc (select-keys existing [:schema]) :type "table"
+ :name (or target-name (:name existing))
+ :database (or source-db-id (:database existing)))
+ schema (assoc :schema schema))))
+
+(defn- check-target-free!
+ "Refuse a target table that already exists, as the REST create and update check stacks both do.
+ Restated as a teaching error naming the fix — the REST 403 (\"A table with that name already
+ exists.\") says neither which table clashed nor what to do about it."
+ [{:keys [target] :as body}]
+ (when (transforms/target-table-exists? body)
+ (common/throw-teaching-error
+ (format (str "A table named %s already exists in the target database. Pick a different `target.name` "
+ "(or schema) — a transform creates its output table, it doesn't adopt one.")
+ (pr-str (str (when-let [s (:schema target)] (str s ".")) (:name target)))))))
+
+(defn- check-target-move!
+ "Run [[check-target-free!]] over the transform `updates` would produce, but only when the target is
+ actually moving — REST guards on the same condition, and it is load-bearing: a transform that has
+ already built its own output table would otherwise clash with itself and become uneditable."
+ [transform updates]
+ (when (contains? updates :target)
+ (let [where #(select-keys (:target %) [:schema :name])]
+ (when (not= (where transform) (where updates))
+ (check-target-free! (merge transform updates))))))
+
+;;; ---------------------------------------------------- Tags ------------------------------------------------------
+
+(defn- check-tags-exist!
+ "Refuse `tag-ids` that name no transform tag. The shared write silently filters unknown ids out,
+ so without this the tool's own \"replaces the current list\" would quietly mean \"replaces it
+ with a shorter one\" — and jobs select the transforms they run by tag, so the dropped one is
+ noticed only when a schedule doesn't fire."
+ [tag-ids]
+ (when (seq tag-ids)
+ (let [known (mcp.db/existing-transform-tag-ids (distinct tag-ids))
+ unknown (sort (remove known (distinct tag-ids)))]
+ (when (seq unknown)
+ (common/throw-teaching-error
+ (format (str "No transform tag has id %s. Tags are created in Metabase and listed on a "
+ "transform's read — pass only ids that exist, or omit `tag_ids` to leave "
+ "the current ones alone.")
+ (str/join ", " unknown)))))))
+
+;;; -------------------------------------------------- Responses ---------------------------------------------------
+
+(defn- write-result
+ "The created/updated transform echoed to the caller: the `:transform` concise read projection — so
+ every field the echo carries is named and shaped exactly as a concise `get_content` read names
+ it — plus `:entity_id` (a portable id to update by), the transform's URL, and `:tag_ids` — the
+ one write arg the concise projection omits — so every field this tool accepts is confirmed back
+ rather than silently dropped.
+
+ A confirmation of the write, not a read of the result: `:last_run` is the one concise key the
+ echo never carries, because it is hydrated state the write neither sets nor loads. Its absence
+ here means \"not fetched\" rather than \"never run\" — run state comes from `get_content`."
+ [transform]
+ ;; The :transform projection is registered by metabase.mcp.v2.tools.content, which the v2 api ns
+ ;; requires alongside this one — so the registry is populated before any tool dispatch reaches here.
+ (assoc (projections/project :transform :concise transform)
+ :entity_id (:entity_id transform)
+ :url (common/frontend-url (channel.urls/transform-path (:id transform)))
+ :tag_ids (vec (:tag_ids transform))))
+
+;;; --------------------------------------------------- Create -----------------------------------------------------
+
+(defn- create!
+ "Run the shared REST create check stack on the resolved source and target, then save the
+ transform. An omitted `collection_id` leaves the transform at the root of the transforms tree,
+ as REST create does."
+ [{:keys [name description tag_ids] :as args} session-id token-scopes]
+ (let [source (or (resolve-source args session-id token-scopes)
+ (common/throw-teaching-error
+ "Pass the transform's query: `definition` (inline) or `query_handle` (from an execute tool)."))
+ body (u/remove-nils
+ {:name name
+ :description description
+ :source source
+ :target (resolve-target nil (:target args) (-> source :query :database))
+ :collection_id (when (contains? args :collection_id)
+ (v2.resolve/resolve-collection-id (:collection_id args)))
+ :tag_ids tag_ids})]
+ (transforms/check-feature-enabled! body)
+ (api/create-check :model/Transform body)
+ ;; Before the target check, which opens a warehouse connection — a bad argument shouldn't pay for that.
+ (check-tags-exist! tag_ids)
+ (transforms/check-database-feature body)
+ (check-target-free! body)
+ (write-result (transforms/create-transform! body))))
+
+;;; --------------------------------------------------- Update -----------------------------------------------------
+
+(defn- check-is-query-transform!
+ "Refuse to write a query transform's contract onto a python one, so an update can't retype a
+ transform by addressing it with the wrong tool — or silently drop its source tables."
+ [transform]
+ (when-not (transforms/query-transform? transform)
+ (common/throw-teaching-error
+ (format "Transform %d is a %s transform. %s"
+ (:id transform) (name (:source_type transform)) python-note))))
+
+(defn- check-source-replaceable!
+ "Refuse to replace a source that loads incrementally. The strategy lives on the source, and a
+ source is stored whole — so writing the plain `{type, query}` source this tool builds over one
+ would drop the strategy and silently turn an incremental transform into a full read."
+ [transform]
+ (when-let [strategy (get-in transform [:source :source-incremental-strategy])]
+ (common/throw-teaching-error
+ (format (str "This transform's source loads incrementally (%s), which transform_write can't author — "
+ "replacing its query here would drop that. Edit the query in Metabase, or omit "
+ "`definition`/`query_handle` to leave the source alone.")
+ (name (:type strategy))))))
+
+(defn- update!
+ "Write-check the existing transform, patch only the caller-supplied fields, then hand the patch to
+ the shared REST update path, which re-runs feature, database, schema, target-conflict, and cycle
+ checks against the merged transform."
+ [id {:keys [name description tag_ids] :as args} session-id token-scopes]
+ (let [transform (v2.resolve/resolve-and-read-with
+ :model/Transform id
+ (fn [tid] (api/write-check :model/Transform tid)))
+ _ (check-is-query-transform! transform)
+ ;; Refuse before resolving, so a doomed source doesn't pay for the query pipeline first.
+ _ (when (or (:definition args) (:query_handle args))
+ (check-source-replaceable! transform))
+ new-source (resolve-source args session-id token-scopes)
+ ;; The target follows the query being stored — the new one when the source is changing in
+ ;; this same call, otherwise the one already there.
+ source-db (-> (or new-source (:source transform)) :query :database)
+ ;; A source swap onto another database has to carry the target's database with it even when
+ ;; the call names no `target`: the target records the database it writes, that database
+ ;; follows the query, and one left behind names a database the transform does not write —
+ ;; which `resolve-target` then refuses when the agent passes the echo back, dead-ending the
+ ;; read-modify-write. Patched in place rather than rebuilt through `resolve-target`, so a
+ ;; target this tool can't author still gets its database corrected instead of becoming
+ ;; uneditable. Ordered before the caller's own `target` in the `cond->`, which wins.
+ retarget (when-let [target (and new-source (:target transform))]
+ (when (not= source-db (:database target))
+ (assoc target :database source-db)))
+ updates (cond-> {}
+ (contains? args :name) (assoc :name name)
+ (contains? args :description) (assoc :description description)
+ (contains? args :collection_id) (assoc :collection_id (v2.resolve/resolve-collection-id (:collection_id args)))
+ (contains? args :tag_ids) (assoc :tag_ids (vec tag_ids))
+ retarget (assoc :target retarget)
+ (contains? args :target) (assoc :target (resolve-target (:target transform) (:target args) source-db))
+ new-source (assoc :source new-source))]
+ (when (empty? updates)
+ (common/throw-teaching-error
+ (str "Nothing to update — pass at least one of name, description, definition, query_handle, target, "
+ "collection_id, or tag_ids.")))
+ (when (contains? args :tag_ids)
+ (check-tags-exist! tag_ids))
+ ;; The new state's gates before the target check, which opens a warehouse connection — the same
+ ;; ordering the create path states. `write-check` above covers the transform as stored; a
+ ;; `definition` naming another database is resolved with no permission check of its own, so
+ ;; until these run the caller has not been authorized against the database about to be probed.
+ (let [merged (merge transform updates)]
+ (api/check-403 (mi/can-write? merged))
+ (transforms/check-database-feature merged))
+ (check-target-move! transform updates)
+ (write-result (transforms/update-transform! (:id transform) updates))))
+
+;;; -------------------------------------------------- The tool ----------------------------------------------------
+
+(def ^:private transform-write-args-schema
+ [:map {:closed true}
+ [:method
+ [:enum {:description (str "\"create\" makes a new transform (requires `name`, `target`, and one query "
+ "source); \"update\" edits the one named by `id`.")}
+ "create" "update"]]
+ [:id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the transform to update."}]
+ [:string {:description "21-character entity_id of the transform to update."}]]]]
+ [:name {:optional true}
+ [:maybe [:string {:min 1 :description "Create only (editable on update): display name of the transform."}]]]
+ [:definition {:optional true}
+ [:maybe [:map {:description (str "The transform's source: {\"type\": \"query\", \"query\": …}, the shape "
+ "get_content's \"definition\" include returns for a transform. The query "
+ "inside is the same numeric-id dialect execute_query takes, and may be "
+ "native SQL. Pass this or "
+ "query_handle, not both.")}]]]
+ [:query_handle {:optional true}
+ [:maybe [:string {:min 1 :description (str "A query_handle from execute_query or execute_sql — saves exactly "
+ "the query that ran. Pass this or definition, not both.")}]]]
+ [:target {:optional true}
+ [:maybe [:map {:closed true
+ :description (str "The table the transform writes, recreated on every run. On update this "
+ "patches the current target, so passing only `name` renames the table and "
+ "keeps its schema. A target read back from get_content can be passed back "
+ "unchanged.")}
+ [:name {:optional true}
+ [:maybe [:string {:min 1 :description "Name of the output table. Required on create."}]]]
+ [:schema {:optional true}
+ [:maybe [:string {:min 1 :description (str "Schema to write the table into. Required on databases "
+ "that have schemas.")}]]]
+ ;; `type`, `database`, and the incremental strategy are derived, not authored — but a read
+ ;; hands all three back, so the schema tolerates them and resolve-target does the teaching.
+ [:type {:optional true}
+ [:maybe [:string {:min 1 :description (str "Always \"table\" — a full rebuild each run. Incremental "
+ "targets are configured in Metabase, not here.")}]]]
+ [:database {:optional true}
+ [:maybe [:int {:description (str "Numeric id of the database the table is written to. Not a choice — "
+ "it always follows the query's database. Accepted so a target can "
+ "be passed back unchanged.")}]]]
+ [:target-incremental-strategy {:optional true}
+ [:maybe [:map {:description (str "Incremental (append/merge) loading, configured in Metabase, not "
+ "here. Accepted only so passing a target back unchanged reports "
+ "what can't be edited rather than a schema error.")}]]]]]]
+ [:description {:optional true}
+ [:maybe [:string {:description "Optional human-readable description."}]]]
+ [:collection_id {:optional true}
+ [:maybe [:or
+ [:int {:description "Numeric id of the transform folder to file the transform in."}]
+ [:string {:description (str "21-character entity_id of the transform folder, or \"root\" for the top "
+ "level of the transforms tree.")}]]]]
+ [:tag_ids {:optional true}
+ [:maybe [:sequential {:description (str "Numeric ids of transform tags to label the transform with; jobs select "
+ "transforms by tag. Replaces the current list — pass [] to clear it.")}
+ :int]]]
+ [:clear {:optional true}
+ [:maybe [:sequential [:enum {:description "Update only: property names to unset (description). Needed because a null cannot say \"clear this\" — strict clients fill every unset property with null, so nulls are stripped at the boundary."}
+ "description"]]]]])
+
+(def ^:private transform-write-entry
+ {:create-required [:name :target]
+ :clearable #{:description}})
+
+(registry/deftool transform-write
+ "Create or update a transform: a saved query that Metabase runs to materialize its results into a real table in your
+ warehouse, which questions and other transforms can then query. method: \"create\" requires name, target, and one
+ query source; method: \"update\" requires id and changes only the fields you pass. Pass the query as definition
+ ({\"type\": \"query\", \"query\": …} — the shape get_content's \"definition\" include returns, with the query in the
+ same numeric-id dialect execute_query takes) or as a query_handle from execute_query or
+ execute_sql — one or the other, not both. Native SQL is fine: save an execute_sql handle. target is the output table,
+ {name, schema?}; a schema is required on databases that have schemas, and on update target patches the current one,
+ so passing only name renames the table. The target database always follows the query's database. Creating a transform
+ whose target table already exists is refused — a transform creates its table, it doesn't adopt one. Optional:
+ description, collection_id (a transform folder; omit for the top level of the transforms tree), tag_ids (replaces
+ the current list; jobs select transforms by tag). Two things this tool deliberately can't do: python transforms and
+ incremental (checkpoint/append/merge) loading are authored in Metabase, and an update that would rewrite either is
+ refused rather than degrading it. There is no archive or delete here either — transforms have no trash, so removing
+ one is done in Metabase. Running a transform is separate from writing it. Requires transforms permission on the
+ source database and the transforms feature enabled. Before your first transform_write, read learn(\"transforms\")
+ unless already in context — the source shapes, what patching `target` renames, and the refusals above in full."
+ {:name "transform_write"
+ :scope metabot.scope/agent-content-write
+ :annotations {:readOnlyHint false :destructiveHint false}
+ :args transform-write-args-schema}
+ [args {:keys [token-scopes session-id]}]
+ (let [[op a b] (v2.write/dispatch-write transform-write-entry args)
+ payload (v2.write/readback token-scopes [metabot.scope/agent-content-read]
+ (case op
+ :create (create! a session-id token-scopes)
+ :update (update! a b session-id token-scopes))
+ nil)]
+ (common/success-content payload payload)))
diff --git a/src/metabase/mcp/v2/tools/ui_credential.clj b/src/metabase/mcp/v2/tools/ui_credential.clj
new file mode 100644
index 00000000000..1f84d0357e7
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/ui_credential.clj
@@ -0,0 +1,41 @@
+(ns metabase.mcp.v2.tools.ui-credential
+ "The v2 `refresh_ui_credential` tool: the channel by which an MCP Apps iframe gets the short-lived credential
+ it authenticates with.
+
+ The shell used to carry the credential in its rendered HTML, but #81041 moved delivery to a server tool and
+ dropped the placeholder from the production template — so a v2 iframe boots with no credential and must ask
+ for one. v1 gained that tool; v2 did not, which left its Apps unable to bootstrap at all.
+
+ The credential rides private `_meta` rather than the content channel: it is for the host, never for the
+ model, and `metabase.mcp.v2.registry` strips it before the result reaches an eval trace."
+ (:require
+ [metabase.api.common :as api]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.metabot.scope :as metabot.scope]))
+
+(set! *warn-on-reflection* true)
+
+(registry/deftool refresh-ui-credential
+ "Refresh the scoped credential used by a Metabase MCP App. Called by the app itself, not by the model."
+ {:name "refresh_ui_credential"
+ ;; The same scope the iframe shells gate on: this tool exists only to serve them, and a caller who cannot
+ ;; read the shell has nothing to authenticate to.
+ :scope metabot.scope/agent-query-run
+ ;; Hidden from clients that cannot render an iframe, exactly like the shells — otherwise a model in a
+ ;; text-only client sees a tool whose whole output is a credential it must not handle.
+ :required-extensions #{:mcp-app-ui}
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :_meta {:ui {:visibility ["app"]}}
+ :args [:map {:closed true}]}
+ [_arguments {:keys [session-id token-scopes]}]
+ (if (and session-id api/*current-user-id*)
+ ;; Always minted with the caller's scopes, which is what subjects the credential to the native-SQL gate
+ ;; on /api/dataset. (v1's claimless, gate-exempt 2-arity retired with v1 in this slice.)
+ (assoc (common/success-content "MCP UI credential refreshed.")
+ :_meta {common/mcp-apps-meta-key
+ {:credential (mcp.session/issue-ui-credential session-id api/*current-user-id* token-scopes)
+ :sessionId session-id}})
+ (common/error-content "Refreshing an MCP UI credential requires an authenticated MCP session."
+ common/error-code-invalid-request)))
diff --git a/src/metabase/mcp/v2/tools/visualize.clj b/src/metabase/mcp/v2/tools/visualize.clj
new file mode 100644
index 00000000000..4b1aa665839
--- /dev/null
+++ b/src/metabase/mcp/v2/tools/visualize.clj
@@ -0,0 +1,142 @@
+(ns metabase.mcp.v2.tools.visualize
+ "The v2 MCP Apps visualization tools: `visualize_query` renders a query as an interactive
+ in-chat chart, `render_drill_through` renders the follow-up when the user clicks into one.
+
+ Both are UI tools — they return a `query_handle` and point the host at a `ui://` iframe shell
+ ([[metabase.mcp.v2.resources]]). The iframe exchanges the handle for the query at
+ `GET /api/embed-mcp/queries/:handle` ([[metabase.mcp.callback-api]]), authenticated with the
+ scoped UI credential it was rendered with. The result data never enters the model context: the
+ agent gets a handle and a steering line, the iframe gets the rows. That's the v2 change from v1,
+ which inlined the base64 query in `structuredContent`."
+ (:require
+ [metabase.agent-api.query-guards :as query-guards]
+ [metabase.api.common :as api]
+ [metabase.lib.core :as lib]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resources :as v2.resources]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private visualize-steering
+ "Rendering the visualization in the interactive UI. This is the final answer — do not call an execute tool afterwards, and do not tell the user to switch display types or open a Metabase panel or sidebar.")
+
+(defn- resolve-visualizable-handle!
+ "Assert `handle` exists and belongs to the caller, throwing a teaching error otherwise.
+
+ Deliberately the raw store read rather than [[metabase.mcp.v2.queries/resolve-query-handle!]]
+ and friends: those re-validate the stored query against the shape v2's execute tools mint
+ (`:stages`, positive `:limit`, MBQL-only). A visualizable handle need not have that shape —
+ the drill-through handles the iframe mints through `POST /api/embed-mcp/drills` hold the
+ SDK's legacy `dataset_query`, and `execute_sql` handles hold native SQL. Both are visualizable
+ by design, so the guards would reject exactly the handles these tools exist to render.
+
+ Access control still holds. The store read is user-scoped — [[metabase.mcp.session/find-handle-row]]
+ joins `core_session` and filters on its `user_id`, so a handle resolves only for the user who
+ minted it; the `mcp_session_id` on the row is telemetry, and handles deliberately survive a
+ client rotating its MCP session. Native SQL is re-enforced downstream rather than here:
+ `check-mcp-ui-native-query!`, mounted on `/api/dataset` via `+refuse-unscoped-native-sql`, is the
+ boundary that decides whether the iframe may execute a native query."
+ [session-id handle]
+ (or (mcp.session/resolve-query-handle session-id api/*current-user-id* handle)
+ (common/throw-teaching-error
+ "Query handle not found — it may have expired; run the query again.")))
+
+(defn- handle-for-visualization!
+ "Resolve `visualize_query`'s mutually exclusive inputs to the handle the iframe will render.
+
+ A fresh `query` runs the representations pipeline (validate → repair → resolve, permission
+ checked) and mints a handle, so the iframe renders exactly what was resolved. A supplied
+ `query_handle` is reused as-is rather than re-minted — the stored query is unchanged, and a
+ duplicate handle would only add a row for the GC to collect.
+
+ Native is allowed through the handle path but not the fresh path: `execute_sql` mints handles
+ whose SQL is visualizable by design, while inline `query` is MBQL 5 only, matching
+ `execute_query`."
+ [{:keys [query query_handle prompt]} session-id]
+ (let [provided (cond-> []
+ query (conj :query)
+ query_handle (conj :query_handle))]
+ (when-not (= 1 (count provided))
+ (common/throw-teaching-error
+ (str "Pass exactly one of query | query_handle: `query_handle` for a query you already ran "
+ "(preferred — no re-resolution), `query` for a fresh query.")))
+ (if query_handle
+ (do (resolve-visualizable-handle! session-id query_handle)
+ query_handle)
+ (do
+ (query-guards/reject-native-query! query)
+ (v2.queries/mint-query-handle!
+ session-id
+ api/*current-user-id*
+ (-> (v2.queries/execute-representations-query query)
+ (get-in [:structured-output :query])
+ lib/prepare-for-serialization
+ v2.queries/encode-serialized-query)
+ prompt)))))
+
+(defn- visualization-content
+ "The two response channels for both UI tools. `structuredContent` is what the iframe reads —
+ it resolves the handle at `GET /api/embed-mcp/queries/:handle`; the text mirrors it so the model
+ is never told less than the iframe was."
+ [payload]
+ (common/success-content (str (json/encode payload) "\n" visualize-steering) payload))
+
+;;; ---------------------------------------------- visualize_query -------------------------------------------------
+
+(def ^:private visualize-query-args-schema
+ [:map {:closed true}
+ [:query {:optional true}
+ [:maybe [:map {:description "A fresh query in the same dialect execute_query takes: numeric table/field ids from browse_data, never base64. Exactly one of query | query_handle."}]]]
+ [:query_handle {:optional true}
+ [:maybe [:string {:min 1 :description "A query_handle from a previous execute_query / execute_sql call — visualizes the exact stored query, MBQL or native SQL. Preferred over query. Exactly one of query | query_handle."}]]]
+ [:prompt {:optional true}
+ [:maybe [:string {:min 1 :max 10000 :description "The user's original request, recorded with a freshly minted handle for the iframe's feedback flow. Ignored alongside `query_handle`: the stored prompt is fixed at mint time and there is no update path, so pass `prompt` on the call that mints the handle."}]]]])
+
+(def ^:private visualize-query-output-schema
+ [:map
+ [:query_handle {:description "Handle the visualization iframe exchanges for the query at GET /api/embed-mcp/queries/:handle."}
+ :string]])
+
+(registry/deftool visualize-query
+ "Visualize a query as an interactive chart or table, rendered inline in the conversation. Pass exactly one of: query_handle (preferred — a handle from execute_query or execute_sql, MBQL or native SQL) or query (a fresh query, in the same dialect execute_query takes). The chart type is inferred from the result shape.
+
+Use this for any request to show, display, visualize, plot, chart, or present results — for example `Show me customers`, `Show me orders by month`, `Display revenue by region`, `Visualize active users over time`. Rendering the visualization IS the final answer: do not call execute_query or execute_sql afterwards to restate the numbers, and do not tell the user to change display types or open the Metabase query builder, a panel, or a sidebar — this is a lightweight inline visualization, not the full Metabase UI."
+ {:name "visualize_query"
+ :scope (v2.resources/resource-scope v2.resources/visualize-query-uri)
+ ;; Not idempotent: the fresh-`query` path mints a new handle row on every call.
+ :annotations {:readOnlyHint true}
+ :required-extensions #{:mcp-app-ui}
+ :_meta {:ui {:resourceUri v2.resources/visualize-query-uri}}
+ :output-schema visualize-query-output-schema
+ :args visualize-query-args-schema}
+ [args {:keys [session-id]}]
+ (visualization-content {:query_handle (handle-for-visualization! args session-id)}))
+
+;;; -------------------------------------------- render_drill_through ----------------------------------------------
+
+(def ^:private render-drill-through-args-schema
+ [:map {:closed true}
+ [:query_handle
+ [:string {:min 1 :description "The handle UUID from the user's drill-through message. Pass it through verbatim — do not run the query yourself."}]]])
+
+(def ^:private render-drill-through-output-schema
+ [:map
+ [:query_handle {:description "Handle the visualization iframe exchanges for the drill-through query at GET /api/embed-mcp/queries/:handle."}
+ :string]])
+
+(registry/deftool render-drill-through
+ "Render the drill-through visualization the user just navigated into. Use this — not an execute tool — when the user asks to show a result and their message carries a handle UUID; it is the exact follow-up for the phrase `Show me the result`. Pass that UUID through as query_handle without running the query yourself. Like visualize_query, this renders a lightweight inline visualization and is the final answer: do not restate the numbers with an execute tool, and do not tell the user to change display types or open a Metabase panel or sidebar."
+ {:name "render_drill_through"
+ :scope (v2.resources/resource-scope v2.resources/render-drill-through-uri)
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :required-extensions #{:mcp-app-ui}
+ :_meta {:ui {:resourceUri v2.resources/render-drill-through-uri}}
+ :output-schema render-drill-through-output-schema
+ :args render-drill-through-args-schema}
+ [{:keys [query_handle]} {:keys [session-id]}]
+ (resolve-visualizable-handle! session-id query_handle)
+ (visualization-content {:query_handle query_handle}))
diff --git a/src/metabase/mcp/v2/write.clj b/src/metabase/mcp/v2/write.clj
new file mode 100644
index 00000000000..338aae1dc5f
--- /dev/null
+++ b/src/metabase/mcp/v2/write.clj
@@ -0,0 +1,93 @@
+(ns metabase.mcp.v2.write
+ "Write-path machinery shared by v2 `_write` tools. Landed with its first consumers: [[readback]] with
+ `bookmark_content`, `_write` method dispatch with `collection_write`."
+ (:require
+ [clojure.string :as str]
+ [metabase.mcp.scope :as mcp.scope]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.resolve :as v2.resolve]))
+
+(set! *warn-on-reflection* true)
+
+(defn readback
+ "`row` when `token-scopes` could read the entity back through the read tools, else a
+ minimal `{id, url?, note}` acknowledgement plus `ack-keys` — a write succeeding must never
+ double as a read, or the write scope becomes a read oracle for content the token's read
+ scopes deny (a no-op update would return the full entity). `read-scopes` is everything the
+ read path would demand: the read tool's own scope plus any per-type extra. `ack-keys` are
+ keys of `row` the caller already supplied (and are thus not read-gated) that should survive
+ the degradation — e.g. `bookmark_content`'s `:bookmarked`. Unscoped callers (cookie sessions
+ bind the unrestricted sentinel) always get the row. Throws when `read-scopes` is empty."
+ [token-scopes read-scopes row ack-keys]
+ ;; An empty `read-scopes` would make `missing` empty and hand back the ungated row, which is
+ ;; indistinguishable from a gate that ran and passed. Every caller reads something back, so
+ ;; there is no legitimate empty case -- refuse it rather than silently degrade to no gate.
+ (when (empty? read-scopes)
+ (throw (ex-info "readback needs at least one read scope; an empty read-scopes would skip the gate"
+ {:read-scopes read-scopes})))
+ (let [missing (remove #(mcp.scope/matches? token-scopes %) read-scopes)]
+ (if (empty? missing)
+ row
+ (assoc (select-keys row (into [:id :url] ack-keys))
+ :note (format "Written. Reading it back requires the %s scope%s this token doesn't have."
+ (str/join " and " missing)
+ (if (next missing) "s" ""))))))
+
+(defn- expand-clear
+ "Turn a `clear` list of property names into explicit nils on `args`. Null can't carry this
+ meaning itself: the registry strips nulls at the boundary because strict clients flood every
+ declared property with null, so `description: null` cannot be told apart from \"didn't touch
+ it\". A list of names survives that stripping and says it unambiguously. The nils are what the
+ tools' update paths already read — they test `contains?` (or `select-keys`), so a present-but-nil
+ key sets the column to nil without any per-tool change."
+ [args clearable clear]
+ (if (empty? clear)
+ (dissoc args :clear)
+ (let [clearable (set clearable)
+ fields (map keyword clear)]
+ (doseq [field fields]
+ (when-not (contains? clearable field)
+ (common/throw-teaching-error
+ (if (seq clearable)
+ (format "`%s` can't be cleared. This tool can clear: %s."
+ (name field) (str/join ", " (sort (map name clearable))))
+ (format "`%s` can't be cleared — this tool has no clearable properties."
+ (name field)))))
+ (when (some? (get args field))
+ (common/throw-teaching-error
+ (format "`%s` is both set and cleared in the same call — pass one or the other."
+ (name field)))))
+ (reduce #(assoc %1 %2 nil) (dissoc args :clear) fields))))
+
+(defn dispatch-write
+ "Shared `method` dispatch for `_write` tools. `entry` carries the tool's write contract:
+ `:create-required` (arg keys enforced at create with teaching errors — the \"(create)\" markers
+ in the spec) and `:clearable` (the property names `clear` may name — see [[expand-clear]]). The
+ tool's single write `:scope` is enforced at the registry gate, so dispatch itself does no scope
+ checking.
+
+ Returns `[:create args]` or `[:update id args]` (with `:method`/`:id`/`:clear` stripped, and any
+ cleared property present as an explicit nil), or throws a teaching error. Does not itself touch
+ the DB — the tool handler consumes the result."
+ [{:keys [create-required clearable]} {:keys [method id clear] :as args}]
+ (case method
+ "create"
+ (do
+ (when (seq clear)
+ (common/throw-teaching-error
+ "`clear` applies to method \"update\" only — a new object has nothing set to clear."))
+ (doseq [k create-required]
+ (when (nil? (get args k))
+ (common/throw-teaching-error (format "`%s` is required when method is \"create\"." (name k)))))
+ [:create (dissoc args :method :clear)])
+
+ "update"
+ (do
+ (when (nil? id)
+ (common/throw-teaching-error "`id` is required when method is \"update\"."))
+ ;; Every `_write` tool's `id` takes an int or a string, so a client that serializes such a
+ ;; param as a string reaches the tool's own id handling already coerced (GHY-4498).
+ [:update (v2.resolve/normalize-id id) (-> (dissoc args :method :id)
+ (expand-clear clearable clear))])
+
+ (common/throw-teaching-error (format "Invalid method %s — use \"create\" or \"update\"." (pr-str method)))))
diff --git a/src/metabase/measures/api.clj b/src/metabase/measures/api.clj
index 1b40889c62d..10c51ad0604 100644
--- a/src/metabase/measures/api.clj
+++ b/src/metabase/measures/api.clj
@@ -4,6 +4,7 @@
[metabase.api.common :as api]
[metabase.api.macros :as api.macros]
[metabase.events.core :as events]
+ [metabase.lib-be.core :as lib-be]
[metabase.lib.core :as lib]
[metabase.measures.db :as measures.db]
[metabase.measures.schema :as measures.schema]
@@ -42,21 +43,32 @@
(lib/primary-source-table-id normalized-definition))
(tru "Measure definition must specify a source table.")))
-(api.macros/defendpoint :post "/" :- ::measure
- "Create a new `Measure`. The Measure's table is derived from its `definition`."
- [_route-params
- _query-params
- {:keys [name description definition], :as body} :- [:map {:closed true}
- [:name ms/NonBlankString]
- [:definition ::measures.schema/definition]
- [:description {:optional true} [:maybe :string]]]]
- (let [table-id (definition-table-id definition)]
+(defn create-measure!
+ "Create-check and insert a new Measure whose table is derived from its `definition`; publishes
+ `:event/measure-create` and returns the hydrated Measure. The shared domain create path, so
+ the create-check runs wherever a Measure is authored."
+ [{:keys [name description definition], :as body}]
+ ;; The REST endpoint's `::measures.schema/definition` normalizes legacy MBQL on decode, but this
+ ;; is the shared entry point — a non-REST caller (MCP's measure_write) arrives undecoded, and
+ ;; `definition-table-id` requires a normalized definition.
+ (let [definition (lib-be/normalize-query definition)
+ table-id (definition-table-id definition)]
(api/create-check :model/Measure (assoc body :table_id table-id))
(let [measure (api/check-500
(measures.db/insert-measure! api/*current-user-id* name description definition))]
(events/publish-event! :event/measure-create {:object measure :user-id api/*current-user-id*})
(t2/hydrate measure :creator))))
+(api.macros/defendpoint :post "/" :- ::measure
+ "Create a new `Measure`. The Measure's table is derived from its `definition`."
+ [_route-params
+ _query-params
+ body :- [:map {:closed true}
+ [:name ms/NonBlankString]
+ [:definition ::measures.schema/definition]
+ [:description {:optional true} [:maybe :string]]]]
+ (create-measure! body))
+
(mu/defn- hydrated-measure [id :- ms/PositiveInt
include-orphaned? :- :boolean]
(api/read-check (measures.db/measure id))
@@ -96,14 +108,19 @@
(->> (t2/hydrate (filterv mi/can-read? measures) :creator :definition_description)
(mapv with-api-dimensions))))
-(defn- write-check-and-update-measure!
+(defn write-check-and-update-measure!
"Check whether current user has write permissions, then update Measure with values in `body`. Publishes appropriate
- event and returns updated/hydrated Measure."
+ event and returns updated/hydrated Measure. The shared domain update path, so the write-check runs
+ wherever a Measure is edited."
[id {:keys [revision_message], :as body}]
(let [existing (api/write-check :model/Measure id)
- clean-body (u/select-keys-when body
- :present #{:description}
- :non-nil #{:archived :definition :name})
+ ;; Normalized for the same reason as in `create-measure!` — non-REST callers (MCP's
+ ;; measure_write) arrive undecoded, and both the stored definition and the table-id
+ ;; derivation below need MBQL 5.
+ clean-body (cond-> (u/select-keys-when body
+ :present #{:description}
+ :non-nil #{:archived :definition :name})
+ (some? (:definition body)) (update :definition lib-be/normalize-query))
new-body (dissoc clean-body :revision_message)
changes (when-not (= new-body existing)
new-body)]
diff --git a/src/metabase/measures/schema.clj b/src/metabase/measures/schema.clj
index 090f89b1653..f20e73992be 100644
--- a/src/metabase/measures/schema.clj
+++ b/src/metabase/measures/schema.clj
@@ -16,7 +16,7 @@
[:and
::lib-be.schema/maybe-legacy-query
[:fn
- {:error/message (deferred-tru "measure definition must have a source table")}
+ {:error/fn (fn [_ _] (str (deferred-tru "measure definition must have a source table")))}
#(some? (lib/primary-source-table-id %))]]])
(mr/def ::measure.definition
diff --git a/src/metabase/metabot/db.clj b/src/metabase/metabot/db.clj
index b008e2390bd..e372d9ba4bf 100644
--- a/src/metabase/metabot/db.clj
+++ b/src/metabase/metabot/db.clj
@@ -444,6 +444,24 @@
[table-id :- ::lib.schema.id/table]
(t2/select-one-fn :db_id :model/Table :id table-id))
+(defn readable-active-table-database-id
+ "The Database ID of the active Table with `table-id`, or nil when there is no such table *or*
+ the current user cannot read it.
+
+ Collapsing those two cases is the point. A caller resolving an agent-authored numeric id has
+ no metadata provider yet — this lookup is what decides which one to build — so a bare
+ existence answer here runs ahead of every permission check, and lets the id argument
+ enumerate table ids across databases the caller cannot otherwise see.
+
+ Selects the whole row rather than the two columns this fn returns: `mi/can-read?` for a Table
+ is polymorphic over the instance, and its published-collection branch reads `:is_published`
+ and `:collection_id`. Handing it a trimmed row makes it answer a narrower question and deny a
+ user whose access comes through that path."
+ [table-id]
+ (when-let [table (t2/select-one :model/Table :id table-id :active true)]
+ (when (mi/can-read? table)
+ (:db_id table))))
+
(mu/defn tables-by-id
"A map of ID to Table for `table-ids`."
[table-ids :- [:set ::lib.schema.id/table]]
@@ -906,10 +924,14 @@
:exploration_id nil
{:order-by [[:%lower.name :asc]]}))
-(mu/defn unarchived-documents
- "The unarchived Documents with `document-ids`."
- [document-ids :- [:set ms/PositiveInt]]
- (t2/select :model/Document :id [:in document-ids] :archived false))
+(mu/defn documents-in-archived-state
+ "The Documents with `document-ids` whose archived flag matches `archived?`. The flag is the
+ caller's search state, not a constant: an archived search validates its hits against the
+ archived set, and hardcoding `false` here drops every archived hit while the caller's total
+ still counts it."
+ [document-ids :- [:set ms/PositiveInt]
+ archived? :- :any]
+ (t2/select :model/Document :id [:in document-ids] :archived (boolean archived?)))
(mu/defn transforms
"The Transforms with `transform-ids`."
diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.clj
index c628ec1bf9e..094ee7c30db 100644
--- a/src/metabase/metabot/tools/construct.clj
+++ b/src/metabase/metabot/tools/construct.clj
@@ -8,6 +8,7 @@
[metabase.api.common :as api]
[metabase.lib-be.core :as lib-be]
[metabase.lib.core :as lib]
+ [metabase.lib.metadata.protocols :as lib.metadata.protocols]
[metabase.lib.schema]
[metabase.lib.schema.expression :as lib.schema.expression]
[metabase.metabot.agent.links :as links]
@@ -16,6 +17,7 @@
[metabase.metabot.scope :as scope]
[metabase.metabot.tmpl :as te]
[metabase.metabot.tools.charts.create :as create-chart-tools]
+ [metabase.metabot.tools.recovery-hints :as recovery-hints]
[metabase.metabot.tools.shared.content-store :as shared.content-store]
[metabase.metabot.tools.shared.instructions :as instructions]
[metabase.metabot.tools.shared.llm-shape :as llm-shape]
@@ -124,6 +126,18 @@
[parsed-query]
(portable-table-fk (get-in parsed-query ["stages" 0 "source-table"])))
+(defn- first-stage-numeric-source-table
+ "Pull the numeric table id out of `stages[0].source-table`, or `nil` if not numeric."
+ [parsed-query]
+ (let [st (get-in parsed-query ["stages" 0 "source-table"])]
+ (when (pos-int? st) st)))
+
+(defn- first-stage-numeric-source-card
+ "Pull the numeric card id out of `stages[0].source-card`, or `nil` if not numeric."
+ [parsed-query]
+ (let [sc (get-in parsed-query ["stages" 0 "source-card"])]
+ (when (pos-int? sc) sc)))
+
(def ^:private metabase-uri-source-table-pattern
"Matches values the LLM sometimes writes into `source-table:` by confusing the Metabase
`metabase://<entity-type>/<id>` URIs (which appear in prompts as a way to read entities)
@@ -144,32 +158,13 @@
(let [raw (get-in parsed-query ["stages" 0 "source-table"])]
(when (string? raw)
(when-let [[_ entity-type entity-id] (re-find metabase-uri-source-table-pattern raw)]
- (let [hint (case entity-type
- "metric"
- (str "Metrics are aggregations, not sources. To use metric " entity-id
- ", put its base table into `source-table:` — combine the `database_name` "
- "and `base_table_fully_qualified_name` attributes from its search result "
- "or `read_resource metabase://metric/" entity-id "` — and reference the "
- "metric as `aggregation: [[metric, {}, \"<portable_entity_id>\"]]`.")
- ("question" "model" "card")
- (str "To reference saved " entity-type " " entity-id
- " as a query source, put its `portable_entity_id` (the 21-char "
- "string from its search result or `read_resource`) into "
- "`source-card:` — not a URI.")
- "table"
- (str "Use the portable FK `[<db-name>, <schema>, <table-name>]` in "
- "`source-table:` — not a URI. `read_resource metabase://table/" entity-id
- "` reports the exact names.")
- (str "`source-table:` accepts a portable FK `[<db-name>, <schema>, <table-name>]` "
- "or, via `source-card:`, a saved-card `portable_entity_id`."))]
- (throw (ex-info (tru "`source-table:` does not accept URIs like `{0}`. {1}"
- raw hint)
- {:agent-error? true
- :status-code 400
- :error :uri-in-source-table
- :source-table raw
- :entity-type entity-type
- :entity-id entity-id})))))))
+ (throw (ex-info (tru "`source-table:` does not accept URIs like `{0}`." raw)
+ {:agent-error? true
+ :status-code 400
+ :error :uri-in-source-table
+ :source-table raw
+ :entity-type entity-type
+ :entity-id entity-id}))))))
(defn- first-stage-source-card-eid
"Pull the `source-card:` entity_id string from `stages[0]`, or `nil` if not present."
@@ -193,20 +188,81 @@
(string? (nth x 2)))
(subvec x 0 3)))
+(defn- numeric-table-id
+ "A bare numeric `source-table`, which only the numeric-id surface may author. Off that surface it
+ is not a table reference at all, so it must not be collected — and on it, it still has to be
+ permission-checked like any portable FK."
+ [x]
+ (when (and serdes.resolve/*numeric-ids-allowed?* (pos-int? x))
+ x))
+
+(defn- numeric-field-id-ref
+ "A bare numeric field id — the numeric-id surface's form of `[db schema table field]`. Its own
+ table is not the source table (the field may live on an FK-related table reached by an implicit
+ join), so it must be permission-checked like a portable field FK. A portable field FK contributes
+ its `[db schema table]` prefix via [[portable-field-fk-table]]; the numeric form carries no name,
+ so we tag the raw id and resolve it to a table id in [[resolve-table-fk]]. Off the numeric-id
+ surface a bare number is not a field reference at all, so it must not be collected."
+ [x]
+ (when (and serdes.resolve/*numeric-ids-allowed?* (pos-int? x))
+ [::field-id x]))
+
+(defn- numeric-scoped-content-ref
+ "A bare numeric measure / segment id, tagged with the model it names so
+ [[resolve-table-fk]] can resolve it to the table it is scoped to.
+
+ Measures and segments live on a table, and that table is the thing a query permission is
+ about — but a `[\"measure\" {} 44]` clause names neither a table nor a field, so without this
+ the sweep never sees it and `api/query-check` never runs for it. They do get `api/read-check`
+ through the content store, but `mi/can-read?` on both models delegates to the Table's
+ `can-read?`, which is strictly weaker than `can-query?` (only `can-read?` has the
+ `manage-table-metadata` disjunct). Metric refs are Cards and are deliberately not covered:
+ a card pulls in whatever tables its own query names, which this pre-flight sweep cannot see,
+ and the QP re-checks them at execution."
+ [model x]
+ (when (and serdes.resolve/*numeric-ids-allowed?* (pos-int? x))
+ [::scoped-content model x]))
+
+(defn- node-scoped-content-ref
+ "The tagged ref for a `[\"measure\" {} 44]` / `[\"segment\" {} 43]` clause, or nil."
+ [node]
+ (when (and (vector? node) (not (map-entry? node)))
+ (let [op (nth node 0 nil)]
+ (when-let [model (case op
+ ("measure" :measure) :model/Measure
+ ("segment" :segment) :model/Segment
+ nil)]
+ ;; the id sits in slot 2 (`[op {} id]`) or slot 1 (`[op id]`, pre-repair)
+ (or (numeric-scoped-content-ref model (nth node 2 nil))
+ (numeric-scoped-content-ref model (nth node 1 nil)))))))
+
(defn- node-table-fks
[node]
(cond
(map? node)
(keep identity [(portable-table-fk (get node "source-table"))
- (portable-field-fk-table (get node "source-field"))])
+ (numeric-table-id (get node "source-table"))
+ (portable-field-fk-table (get node "source-field"))
+ (numeric-field-id-ref (get node "source-field"))])
+
+ (node-scoped-content-ref node)
+ [(node-scoped-content-ref node)]
(and (vector? node)
(not (map-entry? node))
(= "field" (nth node 0 nil)))
+ ;; Both slots, for both forms. Repair inserts the options map later, so an LLM-authored
+ ;; `["field", 42]` still carries its target in slot 1 when this pass runs — checking the
+ ;; numeric form in slot 2 only (as this did) let that shape through uncollected, and so
+ ;; unchecked. The portable form already looked at both slots; the numeric one has to match.
(keep identity [(or (portable-field-fk-table (nth node 2 nil))
- (portable-field-fk-table (nth node 1 nil)))])))
+ (portable-field-fk-table (nth node 1 nil))
+ (numeric-field-id-ref (nth node 2 nil))
+ (numeric-field-id-ref (nth node 1 nil)))])))
(defn- referenced-table-fks
+ "Every table reference in the query: portable `[db schema table]` FKs, plus bare table ids on the
+ numeric-id surface."
[parsed-query]
(into []
(comp (mapcat node-table-fks) (distinct))
@@ -215,14 +271,221 @@
(def ^:private unresolved-table-fk-errors
#{:unknown-table :ambiguous-table})
-(defn- resolve-table-fk
- [resolver table-fk]
+;;; ----- the numeric-id boundary contract -------------------------------------------------
+;;;
+;;; A portable reference names a table or column, and resolution answers "is there something
+;;; with this name, in this database, that the caller may use?" — so being in the query's
+;;; database, and being a column the warehouse actually exposes, both fall out of resolving the
+;;; name. A bare numeric id skips all of that: it is an LLM-authored integer pointing at a row.
+;;;
+;;; These two helpers put that contract back. Everything the numeric dialect accepts goes
+;;; through the query's own metadata provider, which is scoped to the query's database — so a
+;;; table in another database simply is not there. On top of that we re-apply the visibility
+;;; rules, because `metadata-spec->honey-sql` deliberately drops its active/visibility filter
+;;; for by-id lookups (`active-only?` is `(not (or id-set name-set))`): asking for a specific
+;;; id is normally a deliberate act by trusted code, which is exactly the assumption an
+;;; agent-authored id breaks.
+
+(defn- visible-table
+ "The table `table-id` names, as seen from `metadata-provider`, or nil when it is not a table
+ this query may reference: a table in another database (the provider is database-scoped, so it
+ is simply absent), an inactive one, or one the warehouse hides."
+ [metadata-provider table-id]
+ ;; Any lookup failure — not just a miss — is treated as "not referenceable". This pass decides
+ ;; only what a numeric id is allowed to name; it is deliberately not the place a provider
+ ;; outage is diagnosed, and failing closed here is the safe direction.
+ (when-let [table (try
+ (lib.metadata.protocols/table metadata-provider table-id)
+ (catch Exception _ nil))]
+ (when (and (not (false? (:active table)))
+ (not (contains? #{:hidden :technical :cruft} (:visibility-type table))))
+ table)))
+
+(def ^:private hidden-field-visibility-types
+ "Field visibility types the warehouse marks as not for querying."
+ #{:sensitive :retired})
+
+(defn- field-itself-visible?
+ "The per-field half of [[visible-field]]: active, and not marked unqueryable. Says nothing
+ about the field's table or its ancestors."
+ [field]
+ (and (some? field)
+ (not (false? (:active field)))
+ (not (contains? hidden-field-visibility-types (:visibility-type field)))))
+
+(defn- fetch-field
+ "`field-id` from `metadata-provider`, or nil. Catch-all for the same reason as
+ [[visible-table]]: fail closed, diagnose elsewhere."
+ [metadata-provider field-id]
(try
- (serdes.resolve/import-table-fk resolver table-fk)
- (catch clojure.lang.ExceptionInfo e
- (when-not (contains? unresolved-table-fk-errors (:error (ex-data e)))
- (throw e))
- nil)))
+ (lib.metadata.protocols/field metadata-provider field-id)
+ (catch Exception _ nil)))
+
+(def ^:private max-parent-chain-depth
+ "Depth bound for the `:parent-id` walk. JSON-unfolded columns nest a handful deep at most; the
+ bound is here so a cyclic or corrupt chain cannot spin, not because real data approaches it."
+ 50)
+
+(defn- visible-field
+ "The field `field-id` names, as seen from `metadata-provider`, or nil when it is not a field
+ this query may reference — same rules as [[visible-table]], plus the field-level visibility
+ types. `:sensitive` and `:retired` columns are excluded: the warehouse marks them as not for
+ querying, and the portable dialect cannot name them because they are absent from the by-name
+ fetch.
+
+ Walks the whole `:parent-id` chain, not just the named field. A JSON column unfolds into child
+ fields that carry their own visibility, so a perfectly ordinary-looking child of a `:sensitive`
+ parent would otherwise be referenceable by id — reaching inside a column the warehouse marked
+ unqueryable. Hiding a parent has to hide everything under it.
+
+ The walk checks each ancestor's own visibility, not its `:table-id`. Sync is the only writer
+ of `parent_id` and always threads a field's table and parent together; there is no API that
+ sets it, so a cross-table chain would take direct app-DB manipulation. The leaf's table is
+ checked, which is the reference the query actually names."
+ [metadata-provider field-id]
+ (when-let [field (fetch-field metadata-provider field-id)]
+ (when (and (field-itself-visible? field)
+ ;; the field's own table has to be referenceable too
+ (visible-table metadata-provider (:table-id field))
+ ;; …as does every ancestor, for its own sake
+ (loop [parent-id (:parent-id field)
+ depth 0]
+ (cond
+ (nil? parent-id) true
+ (>= depth max-parent-chain-depth) false
+ :else (when-let [parent (fetch-field metadata-provider parent-id)]
+ (when (field-itself-visible? parent)
+ (recur (:parent-id parent) (inc depth)))))))
+ field)))
+
+(defn- resolve-field-id->table-id
+ "The table a numeric field id lives on, via the metadata provider, or nil when the field is not
+ one this query may reference (see [[visible-field]]).
+
+ Returning nil leaves the table out of the permission sweep, which is safe precisely because
+ the same predicate gates the id downstream: a field that fails here never resolves either, so
+ there is no table to check. `assert-numeric-ids-are-referenceable!` raises the agent-facing
+ error; this pass only decides what to permission-check."
+ [metadata-provider field-id]
+ (:table-id (visible-field metadata-provider field-id)))
+
+(defn- resolve-table-fk
+ [metadata-provider resolver table-fk]
+ (cond
+ (pos-int? table-fk)
+ ;; Already a table id, but not necessarily one this query may reference. Resolve it through
+ ;; the (database-scoped) provider rather than trusting the integer: a table in another
+ ;; database is absent there, and `api/query-check` would not catch that on its own — it asks
+ ;; whether the caller can query *that* table, never whether it belongs to this query's
+ ;; database. nil here leaves it unchecked, which is safe because
+ ;; `assert-numeric-ids-are-referenceable!` has already rejected the query.
+ (:id (visible-table metadata-provider table-fk))
+
+ ;; A numeric field id: check the table the field lives on, not the id itself.
+ (and (vector? table-fk) (= ::field-id (nth table-fk 0 nil)))
+ (resolve-field-id->table-id metadata-provider (nth table-fk 1))
+
+ ;; A numeric measure / segment id: same idea, via the table it is scoped to. The lookup goes
+ ;; through the read-checked store, so an unreadable one resolves to nil and is skipped —
+ ;; `assert-numeric-ids-are-referenceable!` is what turns that into the caller-facing error.
+ (and (vector? table-fk) (= ::scoped-content (nth table-fk 0 nil)))
+ (let [[_ model id] table-fk
+ row (try
+ (case model
+ :model/Measure (resolve.mp/measure-by-id permission-aware-content-store id)
+ :model/Segment (resolve.mp/segment-by-id permission-aware-content-store id)
+ nil)
+ (catch Exception _ nil))]
+ (when-let [table-id (or (:table-id row) (:table_id row))]
+ (:id (visible-table metadata-provider table-id))))
+
+ :else
+ (try
+ (serdes.resolve/import-table-fk resolver table-fk)
+ (catch clojure.lang.ExceptionInfo e
+ (when-not (contains? unresolved-table-fk-errors (:error (ex-data e)))
+ (throw e))
+ nil))))
+
+(defn- assert-numeric-ids-are-referenceable!
+ "Reject every numeric table / field id in `parsed-query` that this query may not reference,
+ before anything looks the ids up for real.
+
+ This is the numeric dialect's equivalent of name resolution failing on the portable path. It
+ runs ahead of the permission sweep on purpose: `api/query-check` asks whether the caller may
+ query a given table, not whether that table belongs to *this* query's database, so an id from
+ another database would otherwise pass the check and travel on into repair. Errors are phrased
+ as plain not-found — an id being absent, hidden, or in the wrong database are all the same
+ answer to the agent, and distinguishing them would report on rows it cannot otherwise see."
+ [metadata-provider parsed-query]
+ (when serdes.resolve/*numeric-ids-allowed?*
+ (doseq [ref (referenced-table-fks parsed-query)]
+ (cond
+ (pos-int? ref)
+ (when-not (visible-table metadata-provider ref)
+ (throw (ex-info (tru "No table found with id {0}." (str ref))
+ {:agent-error? true
+ :status-code 400
+ :error :unknown-table-id
+ :table-id ref})))
+
+ (and (vector? ref) (= ::field-id (nth ref 0 nil)))
+ (let [field-id (nth ref 1)]
+ (when-not (visible-field metadata-provider field-id)
+ (throw (ex-info (tru "No field found with id {0}." (str field-id))
+ {:agent-error? true
+ :status-code 400
+ :error :unknown-field-id
+ :field-id field-id}))))
+
+ (and (vector? ref) (= ::scoped-content (nth ref 0 nil)))
+ (let [[_ model id] ref]
+ (when-not (resolve-table-fk metadata-provider nil ref)
+ (throw (ex-info (if (= model :model/Measure)
+ (tru "No measure found with id {0}." (str id))
+ (tru "No segment found with id {0}." (str id)))
+ {:agent-error? true
+ :status-code 400
+ :error (if (= model :model/Measure)
+ :unknown-measure-id
+ :unknown-segment-id)
+ :content-id id}))))
+
+ :else nil))))
+
+(defn- numeric-ref?
+ "Was this collected reference authored as a bare id rather than a portable one? Numeric refs
+ are the raw table id, or the `[::field-id n]` tag [[numeric-field-id-ref]] produces."
+ [table-fk]
+ (or (pos-int? table-fk)
+ (and (vector? table-fk)
+ (contains? #{::field-id ::scoped-content} (nth table-fk 0 nil)))))
+
+(defn- query-check-table!
+ "`api/query-check` the table, translating a denial on a *numeric* reference into the same
+ not-found error an absent id produces.
+
+ `mi/can-read?` (which gates [[visible-table]] and the first-stage lookup) is strictly weaker
+ than `mi/can-query?`: only `can-read?` has the `manage-table-metadata :yes` disjunct. So a
+ metadata-only user passes every earlier gate and lands here, and a bare 403 would confirm the
+ table exists, is active, and is in this database — the oracle the numeric path exists to
+ close, one step further along than the first-stage lookup that already closes it.
+
+ The portable path keeps its 403: its references are unguessable names, so there is nothing to
+ enumerate, and callers there benefit from the accurate status."
+ [table-fk table-id]
+ (if (numeric-ref? table-fk)
+ (try
+ (api/query-check :model/Table table-id)
+ (catch clojure.lang.ExceptionInfo e
+ (if (= 403 (:status-code (ex-data e)))
+ (throw (ex-info (tru "No table found with id {0}." (str table-id))
+ {:agent-error? true
+ :status-code 400
+ :error :unknown-table-id
+ :table-id table-id}))
+ (throw e))))
+ (api/query-check :model/Table table-id)))
(defn- check-source-table-query-permissions!
([metadata-provider portable-query]
@@ -232,10 +495,10 @@
(if-let [table-fks (not-empty (referenced-table-fks portable-query))]
(let [resolver (resolve.mp/import-resolver metadata-provider permission-aware-content-store)]
(reduce (fn [checked table-fk]
- (if-let [table-id (resolve-table-fk resolver table-fk)]
+ (if-let [table-id (resolve-table-fk metadata-provider resolver table-fk)]
(if (contains? checked table-id)
checked
- (do (api/query-check :model/Table table-id)
+ (do (query-check-table! table-fk table-id)
(conj checked table-id)))
checked))
already-checked
@@ -250,8 +513,11 @@
* If `stages[0].source-table` is a portable FK `[db schema table]`, look up the database
by that `db` name. Unknown / ambiguous names surface `:unknown-database` / `:ambiguous-database-name`
agent-errors.
+ * On a surface that accepts numeric ids, a numeric `stages[0].source-table` resolves through
+ the table row's `:db_id`. Unknown / inactive / unreadable ids surface `:unknown-table-id`.
* Otherwise, if `stages[0].source-card` is an entity_id string, look up the card by entity_id
- and use its `:database_id`. Unknown entity_id surfaces `:unknown-card`.
+ and use its `:database_id`. Unknown entity_id surfaces `:unknown-card`. On a numeric-id
+ surface a numeric `source-card` resolves the same way, behind a read check.
* Otherwise, surface `:missing-source-in-first-stage`.
All error paths are raised with `:agent-error? true` so the tool wrapper can relay a clean
@@ -263,45 +529,87 @@
step 14 follow-up."
[parsed-query]
(detect-metabase-uri-source-table! parsed-query)
- (if-let [table-fk (first-stage-source-table-fk parsed-query)]
- (let [db-name (nth table-fk 0)
- ids (metabot.db/database-ids-by-name db-name)]
- (case (count ids)
- 0 (throw (ex-info (tru (str "Unknown database: `{0}`. Use the exact database name as "
- "reported by search / `read_resource` (it appears "
- "as the first element of every portable FK, e.g. "
- "`source-table: [<db-name>, <schema>, <table>]`).")
- db-name)
+ (let [source-table-fk (first-stage-source-table-fk parsed-query)
+ numeric-table (when serdes.resolve/*numeric-ids-allowed?*
+ (first-stage-numeric-source-table parsed-query))
+ source-card-eid (first-stage-source-card-eid parsed-query)
+ numeric-card (when serdes.resolve/*numeric-ids-allowed?*
+ (first-stage-numeric-source-card parsed-query))]
+ (cond
+ source-table-fk
+ (let [db-name (nth source-table-fk 0)
+ ids (metabot.db/database-ids-by-name db-name)]
+ (case (count ids)
+ 0 (throw (ex-info (tru "Unknown database: `{0}`." db-name)
+ {:agent-error? true
+ :status-code 400
+ :error :unknown-database
+ :database db-name}))
+ 1 (first ids)
+ (throw (ex-info (tru (str "Multiple databases share the name `{0}` (ids: {1}). The "
+ "agent has no way to disambiguate; ask the user to rename "
+ "one of the databases or use a more specific identifier.")
+ db-name (pr-str (vec (sort ids))))
{:agent-error? true
:status-code 400
- :error :unknown-database
- :database db-name}))
- 1 (first ids)
- (throw (ex-info (tru (str "Multiple databases share the name `{0}` (ids: {1}). The "
- "agent has no way to disambiguate; ask the user to rename "
- "one of the databases or use a more specific identifier.")
- db-name (pr-str (vec (sort ids))))
- {:agent-error? true
- :status-code 400
- :error :ambiguous-database-name
- :database db-name
- :database-ids (vec (sort ids))}))))
- (if-let [eid (first-stage-source-card-eid parsed-query)]
- (if-let [card (tools.u/get-card-by-entity-id eid)]
+ :error :ambiguous-database-name
+ :database db-name
+ :database-ids (vec (sort ids))}))))
+
+ numeric-table
+ ;; Read-checked, and reporting a table the caller may not see exactly as it reports one
+ ;; that does not exist: this lookup runs before the metadata provider exists (it is what
+ ;; decides which provider to build), so an unchecked existence answer here would let the
+ ;; id argument enumerate table ids across databases the caller cannot otherwise see.
+ (or (metabot.db/readable-active-table-database-id numeric-table)
+ ;; the id renders via str, not as a number — tru's MessageFormat would add locale
+ ;; digit grouping ("999,999,999").
+ ;; `:unknown-table-id`, not `:unknown-table`: a portable-FK miss (`:unknown-table`)
+ ;; recovers by naming a portable FK, which is wrong advice for a numeric-id caller.
+ (throw (ex-info (tru "No table found with id {0}."
+ (str numeric-table))
+ {:agent-error? true
+ :status-code 400
+ :error :unknown-table-id
+ :table-id numeric-table})))
+
+ source-card-eid
+ (if-let [card (tools.u/get-card-by-entity-id source-card-eid)]
(:database_id card)
- (throw (ex-info (tru (str "No saved question or model found with entity_id {0}. Do not invent "
- "or guess entity_ids: call `read_resource` with "
- "`metabase://question/<numeric id>` or `metabase://model/<numeric id>` "
- "first, then copy the exact `portable_entity_id` from the response "
- "into `source-card:`.")
- (pr-str eid))
+ (throw (ex-info (tru "No saved question or model found with entity_id {0}." (pr-str source-card-eid))
{:agent-error? true
:status-code 400
:error :unknown-card
- :entity-id eid})))
- (throw (ex-info (tru (str "First stage must have either `source-table:` (as a portable FK "
- "`[<db-name>, <schema>, <table>]`) or `source-card:` (as an "
- "entity_id string). Neither was found in `stages[0]`."))
+ :entity-id source-card-eid})))
+
+ numeric-card
+ (let [card-id numeric-card
+ card (metabot.db/card card-id)
+ ;; Read-check here rather than let the 403 escape: an unreadable card and an absent
+ ;; one must be reported identically, or the status code tells a caller whether a
+ ;; hidden card exists. Same collapse the read-checked content store applies to every
+ ;; other content lookup, and the same one the numeric table branch already had.
+ readable (when card
+ (try
+ (api/read-check card)
+ true
+ (catch clojure.lang.ExceptionInfo e
+ (if (= 403 (:status-code (ex-data e)))
+ false
+ (throw e)))))]
+ (when-not readable
+ (throw (ex-info (tru "No saved question or model found with id {0}."
+ (str card-id))
+ {:agent-error? true
+ :status-code 400
+ ;; the numeric-specific key, matching `export-card-by-id` — a numeric
+ ;; miss and a portable-entity_id miss want different recovery advice
+ :error :unknown-card-id
+ :card-id card-id})))
+ (:database_id card))
+
+ :else
+ (throw (ex-info (tru "First stage must have either `source-table:` or `source-card:`; neither was found in `stages[0]`.")
{:agent-error? true
:status-code 400
:error :missing-source-in-first-stage})))))
@@ -339,7 +647,7 @@
(when-let [explanation (mr/explain :metabase.lib.schema/query pmbql-query)]
(me/humanize explanation))))
-(defn execute-representations-query
+(defn- execute-representations-query*
"Execute a notebook query in the canonical portable MBQL 5 representations format.
`external-query` is a keyword-keyed Clojure map matching [[metabase.lib.schema/external-query]]
@@ -395,6 +703,10 @@
(throw (as-agent-input-error e))))
database-id (resolve-database-id-from-first-stage parsed)
mp (lib-be/application-database-metadata-provider database-id)
+ ;; Numeric ids are LLM-authored integers rather than resolved names, so establish that
+ ;; each one actually denotes something this query may reference before the permission
+ ;; sweep runs against it. No-op on the portable-only surface.
+ _refs (assert-numeric-ids-are-referenceable! mp parsed)
;; Permission checks happen before repair/resolve so the metadata-provider-backed pipeline
;; never inspects table/card metadata that the current user cannot use.
checked (check-source-table-query-permissions! mp parsed)]
@@ -440,6 +752,33 @@
;;; ---------------------------------------- Chart helpers ----------------------------------------
+(defn- with-recovery-hint
+ "Return `e` with the caller's recovery sentence appended to its message, or unchanged when
+ `recovery-hint` is absent or has nothing to say about this error."
+ [e recovery-hint]
+ (if-let [hint (when recovery-hint (recovery-hint (ex-data e)))]
+ (ex-info (str (ex-message e) " " hint) (ex-data e) e)
+ e))
+
+(defn execute-representations-query
+ "Run `external-query` through the representations pipeline. See
+ [[execute-representations-query*]] for the pipeline itself.
+
+ `opts` may carry `:recovery-hint`, a function from an agent error's `ex-data` to the sentence
+ telling *this* caller's agent how to recover — the pipeline states what went wrong, the
+ caller supplies the vocabulary, because only the caller knows which tools its agent has.
+ Surfaces pass [[metabase.metabot.tools.recovery-hints/recovery-hint]] or
+ [[metabase.mcp.v2.recovery-hints/recovery-hint]]; omitting it yields bare statements."
+ ([external-query]
+ (execute-representations-query external-query nil))
+ ([external-query {:keys [recovery-hint]}]
+ (try
+ (execute-representations-query* external-query)
+ (catch clojure.lang.ExceptionInfo e
+ (throw (if (:agent-error? (ex-data e))
+ (with-recovery-hint e recovery-hint)
+ e))))))
+
(defn- chart-type->keyword
[chart-type]
(cond
@@ -504,7 +843,9 @@
(let [normalized-visualization (some-> visualization (update-keys (comp keyword u/->kebab-case-en name)))
chart-type (or (chart-type->keyword (:chart-type normalized-visualization))
:table)
- query-result (execute-representations-query query)
+ query-result (execute-representations-query
+ query
+ {:recovery-hint recovery-hints/recovery-hint})
structured (or (:structured-output query-result) (:structured_output query-result))]
(if (and structured (:query-id structured) (:query structured))
(let [chart-result (create-chart-tools/create-chart
diff --git a/src/metabase/metabot/tools/recovery_hints.clj b/src/metabase/metabot/tools/recovery_hints.clj
new file mode 100644
index 00000000000..1560cd15b74
--- /dev/null
+++ b/src/metabase/metabot/tools/recovery_hints.clj
@@ -0,0 +1,85 @@
+(ns metabase.metabot.tools.recovery-hints
+ "The v1 metabot / agent-api surface's recovery sentences for the shared representations
+ pipeline's agent errors.
+
+ The pipeline throws a bare statement of what went wrong plus structured `ex-data`; it does
+ not know which tools the caller has. This namespace turns that `ex-data` into the sentence
+ telling *this* surface's agent how to recover, and each v1 entry point hands it to the
+ pipeline as `:recovery-hint`. v2's equivalent is
+ [[metabase.mcp.v2.recovery-hints/recovery-hint]].
+
+ Keep every sentence inside v1's own vocabulary — `read_resource`, `metabase://` URIs,
+ portable FKs and `portable_entity_id`. An error key with no entry here yields no sentence,
+ which is the intended failure mode: a missing hint reads as terse, a wrong one sends the
+ agent at a tool it does not have."
+ (:require
+ [metabase.util.i18n :refer [tru]]))
+
+(set! *warn-on-reflection* true)
+
+(defn- uri-hint
+ "The `source-table:`-took-a-URI sentence, which varies by what the URI pointed at."
+ [entity-type entity-id]
+ (case entity-type
+ ;; The `{}` options slot has to sit outside the format string — MessageFormat reads a brace
+ ;; as a placeholder, and `tru` rejects the escaped form as a skipped argument index.
+ "metric"
+ ;; `{0}` and `{1}` are both the entity id: `tru` rejects a repeated index, because
+ ;; MessageFormat counts placeholder occurrences and distinct indices separately.
+ (str (tru "Metrics are aggregations, not sources. To use metric {0}, put its base table into `source-table:` — combine the `database_name` and `base_table_fully_qualified_name` attributes from its search result or `read_resource metabase://metric/{1}` — and reference the metric as:"
+ (str entity-id) (str entity-id))
+ " `aggregation: [[metric, {}, \"<portable_entity_id>\"]]`.")
+
+ ("question" "model" "card")
+ (tru "To reference a saved question or model as a query source, put its `portable_entity_id` (the 21-char string from its search result or `read_resource`) into `source-card:` — not a URI.")
+
+ "table"
+ (tru "Use the portable FK `[<db-name>, <schema>, <table-name>]` in `source-table:` — not a URI. `read_resource metabase://table/{0}` reports the exact names."
+ (str entity-id))
+
+ (tru "`source-table:` accepts a portable FK `[<db-name>, <schema>, <table-name>]` or, via `source-card:`, a saved-card `portable_entity_id`.")))
+
+(defn recovery-hint
+ "The v1 recovery sentence for an agent error's `ex-data`, or nil when it has none."
+ [{:keys [error entity-type entity-id]}]
+ (case error
+ :uri-in-source-table
+ (uri-hint entity-type entity-id)
+
+ :unknown-table
+ (tru "Call `read_resource` with `metabase://database/<numeric id>/tables` to list available tables and schemas, then retry with an exact portable FK from the response.")
+
+ :unknown-table-id
+ ;; A numeric-id miss, not a portable-FK miss: pointing the agent at a portable FK (as
+ ;; `:unknown-table` does) would be wrong advice. v1 authors portable FKs, so the right move
+ ;; is to find the table by name and use its portable FK.
+ (tru "That numeric table id does not resolve. Call `read_resource` with `metabase://database/<numeric id>/tables` to find the table, then use its portable FK `[<db-name>, <schema>, <table-name>]` in `source-table:`.")
+
+ :ambiguous-table
+ (tru "Call `read_resource` with `metabase://database/<numeric id>/tables` to list available tables and retry with a more specific portable FK.")
+
+ (:unknown-field :unknown-field-id)
+ (tru "Call `read_resource` with `metabase://table/<numeric id>/fields` to list this table''s columns.")
+
+ :ambiguous-fk
+ (tru "Call `read_resource` with `metabase://table/<numeric id>/fields` for the source table to list the available foreign-key columns.")
+
+ :no-fk-path
+ (tru "If a metric relates to that table, read its dimensions resource `metabase://metric/<metric_id>/dimensions`, which lists the exact `joins:` clause to paste and the columns it unlocks.")
+
+ (:unknown-card :unknown-card-id)
+ (tru "Do not invent or guess entity_ids: call `read_resource` with `metabase://question/<numeric id>` or `metabase://model/<numeric id>` first, then copy the exact `portable_entity_id` from the response into `source-card:`.")
+
+ (:unknown-measure :unknown-measure-id)
+ (tru "Do not invent or guess entity_ids: read the table that owns the measure with `read_resource` (`metabase://table/<numeric id>`) and copy the exact `portable_entity_id` from its `<measure>` tag.")
+
+ (:unknown-segment :unknown-segment-id)
+ (tru "Do not invent or guess entity_ids: read the table that owns the segment with `read_resource` (`metabase://table/<numeric id>`) and copy the exact `portable_entity_id` from its `<segment>` tag.")
+
+ :unknown-database
+ (tru "Use the exact database name as reported by search / `read_resource` (it appears as the first element of every portable FK, e.g. `source-table: [<db-name>, <schema>, <table>]`).")
+
+ :missing-source-in-first-stage
+ (tru "`source-table:` takes a portable FK `[<db-name>, <schema>, <table>]`; `source-card:` takes an entity_id string.")
+
+ nil))
diff --git a/src/metabase/metabot/tools/search.clj b/src/metabase/metabot/tools/search.clj
index 314af5f59d5..54b1e52012c 100644
--- a/src/metabase/metabot/tools/search.clj
+++ b/src/metabase/metabot/tools/search.clj
@@ -206,15 +206,16 @@
(contains? readable-ids (:id result))))))))
(defn- validate-and-enrich-documents
- "Remove stale or unreadable document hits and attach live write permission.
+ "Remove stale or unreadable document hits and attach live write permission. `archived?` is the
+ archived state the search asked for: a hit is stale unless the live Document is in that set.
Search indexes are updated asynchronously, so a deleted document can briefly remain
searchable. Destination discovery must validate hits against the live model before the
agent attempts to save into them."
- [results]
+ [archived? results]
(let [document-ids (->> results (filter #(= "document" (:type %))) (map :id) set)
id->document (when (seq document-ids)
- (->> (metabot.db/unarchived-documents document-ids)
+ (->> (metabot.db/documents-in-archived-state document-ids archived?)
(filter mi/can-read?)
(map (juxt :id identity))
(into {})))]
@@ -283,9 +284,20 @@
(defn search
"Search for data sources (tables, models, cards, dashboards, metrics, transforms) in Metabase.
- Abstracted from the API endpoint logic."
+ Abstracted from the API endpoint logic.
+
+ Optional filter keys threaded straight into the search context: `created-by` (set of user ids),
+ `archived`, `collection-id` (numeric, scopes to the collection subtree; overrides the metabot's
+ own confined collection), `offset`. `filters-only?` makes a call with no queries run a single
+ nil-query search — a pure listing over the active filters — instead of returning nothing.
+
+ Each query fetches its full ranked pool (`ranked-results`), the pools are fused by rank, and the
+ fused ranking is paginated (`offset`/`limit`) exactly once (`search-results`) — so paging a
+ multi-query search is coherent. The result carries the size of the fused, deduped match set as
+ `:total` metadata."
[{:keys [term-queries semantic-queries database-id created-at last-edited-at
- entity-types limit metabot-id profile-id search-native-query weights]}]
+ entity-types limit metabot-id profile-id search-native-query weights
+ created-by archived collection-id offset filters-only?]}]
(log/infof "[METABOT-SEARCH] Starting search with params: %s"
{:term-query-count (count term-queries)
:semantic-query-count (count semantic-queries)
@@ -295,7 +307,12 @@
:metabot-id metabot-id
:profile-id profile-id
:search-native-query search-native-query
- :weights weights})
+ :weights weights
+ :created-by created-by
+ :archived archived
+ :collection-id collection-id
+ :offset offset
+ :filters-only? filters-only?})
(let [search-models (if (seq entity-types)
(set (distinct (keep metabot.search-models/entity-type->search-model entity-types)))
metabot-search-models)
@@ -305,10 +322,15 @@
(:use_verified_content metabot)
false)
embedded-metabot? (= metabot-id metabot.config/embedded-metabot-id)
- collection-id (when (or embedded-metabot? (= profile-id "nlq"))
+ ;; A confined metabot (embedded, or the nlq profile) may only search inside its own
+ ;; collection. That is a containment boundary, not a default, so a caller-supplied
+ ;; collection-id — which the v2 search tool fills from a request filter — can never
+ ;; replace it. Unconfined, the caller's collection-id applies.
+ confined-id (when (or embedded-metabot? (= profile-id "nlq"))
(:collection_id metabot))
+ collection-id (or confined-id collection-id)
limit (or limit 50)
- search-fn (fn [search-string search-engine]
+ ranked-fn (fn [search-string search-engine]
(let [search-context (search/search-context
(cond-> {:search-string search-string
:models search-models
@@ -322,9 +344,7 @@
:current-user-perms @api/*current-user-permissions-set*
:filter-items-in-personal-collection "exclude-others"
:context :metabot
- :archived false
- :limit limit
- :offset 0}
+ :archived (boolean archived)}
;; Don't include search-native-query key if nil so that we don't
;; inadvertently filter out search models that don't support it
search-native-query
@@ -335,40 +355,69 @@
(assoc :weights weights)
search-engine
(assoc :search-engine (name search-engine))
+ (seq created-by)
+ (assoc :created-by (set created-by))
collection-id
(assoc :collection collection-id)))
_ (log/infof "[METABOT-SEARCH] Search context models: %s"
(:models search-context))
- search-results (search/search search-context)
- data (:data search-results)
- result-models (frequencies (map :model data))]
- (log/infof "[METABOT-SEARCH] Query returned entity types: %s" result-models)
- data))
- search-fn* (fn [search-engine queries]
+ ;; No :limit/:offset in the per-query context — ranked-results returns the
+ ;; full ranked pool; the fused ranking is paginated once, below. Applying
+ ;; offset per query before fusion would page the offset-N tail of each
+ ;; ranking, which is not the tail of the fused ranking.
+ ranked (search/ranked-results search-context)]
+ (log/infof "[METABOT-SEARCH] Query returned entity types: %s"
+ (frequencies (map :model ranked)))
+ ranked))
+ ranked-fn* (fn [search-engine queries]
(let [queries (search.engine/disjunction search-engine queries)]
- (join-results-by-rrf search-fn search-engine queries)))
+ (join-results-by-rrf ranked-fn search-engine queries)))
;; NOTE: if we add more semantic engines, e.g. 3rd party vector dbs, we'll need to make this more maintainable
semantic? #{:search.engine/semantic}
semantic-engine (u/seek semantic? (search.engine/active-engines))
fallback-engine (when semantic-engine
(search.engine/fallback-engine semantic-engine))
- fused-results (if semantic-engine
+ fused-ranked (cond
+ ;; A pure listing over the filters: one search with no search string.
+ (and filters-only?
+ (empty? term-queries)
+ (empty? semantic-queries))
+ (ranked-fn nil nil)
+
;; Perform semantic and non-semantic search respectively, then fuse results.
+ semantic-engine
(reciprocal-rank-fusion
- (map (fn [[engine queries]] (when (seq queries) (search-fn* engine queries)))
+ (map (fn [[engine queries]] (when (seq queries) (ranked-fn* engine queries)))
{semantic-engine semantic-queries
fallback-engine term-queries}))
+
;; Search for all the terms on equal footing, using the default engine.
- (search-fn* nil (distinct (concat term-queries semantic-queries))))]
- (->> fused-results
- (take limit)
- (map postprocess-search-result)
- enrich-with-collection-descriptions
- enrich-with-database-engines
- enrich-with-portable-entity-ids
- enrich-with-metric-base-tables
- validate-and-enrich-documents
- remove-unreadable-transforms)))
+ :else
+ (ranked-fn* nil (distinct (concat term-queries semantic-queries))))
+ ;; Paginate and hydrate the fused ranking exactly once. `search-results` slices to
+ ;; [offset, offset+limit) and reports `:total` as the size of the full fused set — so the
+ ;; total is knowable even under multi-query fusion, and only the returned page is hydrated.
+ {:keys [data total]} (search/search-results
+ (search/search-context {:search-string nil
+ :models search-models
+ :current-user-id api/*current-user-id*
+ :current-user-perms @api/*current-user-permissions-set*
+ :is-superuser? api/*is-superuser?*
+ :offset (or offset 0)
+ :limit limit})
+ search/model-set
+ (vec fused-ranked))]
+ ;; validate-and-enrich-documents drops stale/unreadable document hits and attaches live write
+ ;; permission. Transforms need no such post-filter: they are :visibility :superuser in search, so
+ ;; a non-superuser never has one in results to begin with.
+ (-> (->> data
+ (map postprocess-search-result)
+ enrich-with-collection-descriptions
+ enrich-with-database-engines
+ enrich-with-portable-entity-ids
+ enrich-with-metric-base-tables
+ (validate-and-enrich-documents (boolean archived)))
+ (vary-meta assoc :total total))))
(defn- table-refs->results
[ids]
diff --git a/src/metabase/metabot/tools/shared/content_store.clj b/src/metabase/metabot/tools/shared/content_store.clj
index e9fa063b262..747b3b59344 100644
--- a/src/metabase/metabot/tools/shared/content_store.clj
+++ b/src/metabase/metabot/tools/shared/content_store.clj
@@ -29,45 +29,74 @@
(set! *warn-on-reflection* true)
-(defn- maybe-read-check
- "Apply `api/read-check` when `*current-user-id*` is bound; otherwise return the row
- unchanged. Returning `nil` propagates through (no row → nothing to check; the
- per-model resolver functions translate `nil` into a clean `:unknown-…` agent error)."
- [row]
+(def ^:dynamic *last-lookup-refused?*
+ "Set to `true` by [[read-checked]] when a lookup was refused on permissions rather than simply
+ missing.
+
+ The two are deliberately indistinguishable to the *agent* — same status, same error key, so a
+ guessable id cannot be used to probe for hidden content. Some internal callers still need to
+ tell them apart: `llm-shape/export-query-for-llm` renders nothing at all for a refusal but
+ falls back to pretty-printed EDN for a genuine export failure, and without this it would print
+ the raw query for a card the caller may not read. Bind it per lookup and read it after; it says
+ nothing about *which* row was refused, so it cannot itself become an oracle."
+ (atom false))
+
+(defn- permission-checked
+ "Permission-check `row`, or return it unchanged when `api/*current-user-id*` is unbound. `nil`
+ propagates (no row → nothing to check; the per-model resolvers turn `nil` into a clean
+ `:unknown-…` agent error).
+
+ Two independent axes, because two fixes to this function wanted different things and both were
+ right:
+
+ `audited?` picks the check. `api/read-check` writes an audit entry for the refusal;
+ `api/check-403` does not. Refusals on `-by-entity-id` are always audited, and `-by-id` refusals
+ are audited when the caller asked for it (BOT-1956).
+
+ `collapse-denial?` picks what the *caller* sees, and the two surfaces want opposite things:
+
+ - **By numeric id** (`collapse-denial?` true): return `nil`, so \"exists but you may not read
+ it\" and \"does not exist\" reach the caller as the same `:unknown-…` error. Numeric ids are
+ sequential and trivially guessable, so a distinguishable denial is an existence oracle.
+ - **By entity_id** (`collapse-denial?` false): let the 403 through. A 21-character NanoID is
+ not guessable, so there is nothing to enumerate, and callers rely on the accurate status —
+ `POST /api/agent/v2/construct-query` returns 403 for a metric whose card the caller cannot
+ read, and `llm-shape/export-query-for-llm` suppresses its EDN fallback on one.
+
+ The axes do not trade off against each other: a collapsed denial is still audited, so the
+ refusal stays silent to the agent and visible to the audit log.
+
+ Either way the refusal is recorded in [[*last-lookup-refused?*]] for callers that need to know
+ a denial happened without depending on the status."
+ [{:keys [audited? collapse-denial?]} row]
(cond
(nil? row) nil
- api/*current-user-id* (api/read-check row)
+ api/*current-user-id* (try
+ (if (and audited? resolve.mp/*audit-refusals?*)
+ (api/read-check row)
+ (do (api/check-403 (mi/can-read? row)) row))
+ (catch clojure.lang.ExceptionInfo e
+ (if (= 403 (:status-code (ex-data e)))
+ (do (reset! *last-lookup-refused?* true)
+ (when-not collapse-denial? (throw e)))
+ (throw e))))
:else row))
-(defn- maybe-check-403
- "Like [[maybe-read-check]], but throws a bare 403 rather than an audited one."
- [row]
- (cond
- (nil? row) nil
- api/*current-user-id* (do (api/check-403 (mi/can-read? row)) row)
- :else row))
-
-(defn- checked
- "Permission-check `row`, auditing a refusal only when `audited?` and
- [[resolve.mp/*audit-refusals?*]] both hold."
- [audited? row]
- (if (and audited? resolve.mp/*audit-refusals?*)
- (maybe-read-check row)
- (maybe-check-403 row)))
-
(defn read-checked
- "Wrap `store` so every lookup permission-checks its row when `api/*current-user-id*` is bound,
- throwing a 403 when the current user cannot read it. Refusals on the `-by-entity-id` methods are
- audited; `audited-by-id?` audits the `-by-id` methods too."
+ "Wrap `store` so every lookup permission-checks its row when `api/*current-user-id*` is bound.
+ Symmetric across all six `ContentStore` methods; see [[permission-checked]] for what a refusal
+ costs on each. `audited-by-id?` audits the `-by-id` refusals too."
([store] (read-checked store false))
([store audited-by-id?]
- (reify resolve.mp/ContentStore
- (card-by-entity-id [_ eid] (checked true (resolve.mp/card-by-entity-id store eid)))
- (measure-by-entity-id [_ eid] (checked true (resolve.mp/measure-by-entity-id store eid)))
- (segment-by-entity-id [_ eid] (checked true (resolve.mp/segment-by-entity-id store eid)))
- (card-by-id [_ id] (checked audited-by-id? (resolve.mp/card-by-id store id)))
- (measure-by-id [_ id] (checked audited-by-id? (resolve.mp/measure-by-id store id)))
- (segment-by-id [_ id] (checked audited-by-id? (resolve.mp/segment-by-id store id))))))
+ (let [by-eid {:audited? true :collapse-denial? false}
+ by-id {:audited? audited-by-id? :collapse-denial? true}]
+ (reify resolve.mp/ContentStore
+ (card-by-entity-id [_ eid] (permission-checked by-eid (resolve.mp/card-by-entity-id store eid)))
+ (measure-by-entity-id [_ eid] (permission-checked by-eid (resolve.mp/measure-by-entity-id store eid)))
+ (segment-by-entity-id [_ eid] (permission-checked by-eid (resolve.mp/segment-by-entity-id store eid)))
+ (card-by-id [_ id] (permission-checked by-id (resolve.mp/card-by-id store id)))
+ (measure-by-id [_ id] (permission-checked by-id (resolve.mp/measure-by-id store id)))
+ (segment-by-id [_ id] (permission-checked by-id (resolve.mp/segment-by-id store id)))))))
(def default-store
"[[resolve.mp/unchecked-app-db-content-store]] under [[read-checked]]. The store for any agent
diff --git a/src/metabase/metabot/tools/shared/llm_shape.clj b/src/metabase/metabot/tools/shared/llm_shape.clj
index 0f3884ed2e2..6ccd41ff3bf 100644
--- a/src/metabase/metabot/tools/shared/llm_shape.clj
+++ b/src/metabase/metabot/tools/shared/llm_shape.clj
@@ -89,7 +89,7 @@
sources pass through; a `pprint`'d map is the last-resort fallback. A permission-refused
export renders nothing at all rather than the fallback.
- `store` gates the Card / Measure / Segment lookups and every caller names one: the unaudited
+ `store` gates the Card / Measure / Segment lookups and every caller names one:
[[shared.content-store/default-store]] for queries loaded from the app DB,
[[shared.content-store/audited-store]] for client-supplied queries so a denied lookup
keeps its audit trail. No defaulting arity, so the choice stays visible at the call site.
@@ -104,16 +104,23 @@
(string? query) query
(string? (:query-content query)) (:query-content query)
(and (map? query) (:database query))
- (try
- (let [normalized (if mp query (lib-be/normalize-query query))
- mp (or mp (lib-be/application-database-metadata-provider (:database normalized)))
- exported (repr.resolve/export-query mp normalized store)]
- (or (repr-data->llm-block exported)
- (query-edn-fallback normalized)))
- (catch Exception e
- (log/debugf "Failed to export query for LLM: %s" (ex-message e))
- (when-not (= 403 (:status-code (ex-data e)))
- (query-edn-fallback query))))
+ ;; The refusal marker, not the status code, is what distinguishes "you may not read this"
+ ;; from "the export failed". A by-id denial collapses into the same not-found a missing id
+ ;; produces — deliberately, so the agent cannot probe for hidden content — so the 403 this
+ ;; used to catch does not arrive on that path. Without the marker a refused card would fall
+ ;; through to the EDN fallback and print the raw query.
+ (binding [shared.content-store/*last-lookup-refused?* (atom false)]
+ (try
+ (let [normalized (if mp query (lib-be/normalize-query query))
+ mp (or mp (lib-be/application-database-metadata-provider (:database normalized)))
+ exported (repr.resolve/export-query mp normalized store)]
+ (or (repr-data->llm-block exported)
+ (query-edn-fallback normalized)))
+ (catch Exception e
+ (when-not (or (= 403 (:status-code (ex-data e)))
+ @shared.content-store/*last-lookup-refused?*)
+ (log/debugf "Failed to export query for LLM, using EDN fallback: %s" (ex-message e))
+ (query-edn-fallback query)))))
(string? (get-in query [:native :query])) (get-in query [:native :query])
(map? query) (query-edn-fallback query)
:else (some-> query str))))
diff --git a/src/metabase/metabot/tools/slackbot_query.clj b/src/metabase/metabot/tools/slackbot_query.clj
index 8d652b130ab..18492720215 100644
--- a/src/metabase/metabot/tools/slackbot_query.clj
+++ b/src/metabase/metabot/tools/slackbot_query.clj
@@ -10,6 +10,7 @@
[metabase.metabot.agent.streaming :as streaming]
[metabase.metabot.scope :as scope]
[metabase.metabot.tools.construct :as construct]
+ [metabase.metabot.tools.recovery-hints :as recovery-hints]
[metabase.util.log :as log]
[metabase.util.malli :as mu]))
@@ -41,7 +42,9 @@
tool."
[{:keys [_reasoning query title display]} :- slackbot-query-schema]
(try
- (let [query-result (construct/execute-representations-query query)
+ (let [query-result (construct/execute-representations-query
+ query
+ {:recovery-hint recovery-hints/recovery-hint})
structured (or (:structured-output query-result) (:structured_output query-result))]
(if (and structured (:query-id structured) (:query structured))
(let [metabase-link (streaming/query->question-url (:query structured) display)
diff --git a/src/metabase/metrics/core.clj b/src/metabase/metrics/core.clj
index 7344e37897b..5527a8fec49 100644
--- a/src/metabase/metrics/core.clj
+++ b/src/metabase/metrics/core.clj
@@ -148,6 +148,14 @@
{:dimensions (lib-metric/extract-persisted-dimensions dimensions)
:dimension-mappings dimension-mappings})))
+(defn- metric-seed-pairs
+ "The computed pairs a v2 metric seeds from: the entity's own columns and explicit query joins,
+ leaving implicitly-joinable FK columns out."
+ [computed-pairs]
+ (filterv #(or (lib-metric/main-group? %)
+ (= :source/joins (get-in % [:dimension :lib/source])))
+ computed-pairs))
+
(defn- seed-metric-dimensions!
"First initialization of a v2 metric: seed dimensions from the entity's own columns and explicit
query joins, leaving implicitly-joinable FK columns out.
@@ -157,11 +165,8 @@
would mark the metric initialized and permanently freeze it at zero dimensions."
[entity computed-pairs]
(when (seq computed-pairs)
- (let [seed-pairs (filterv #(or (lib-metric/main-group? %)
- (= :source/joins (get-in % [:dimension :lib/source])))
- computed-pairs)
- {:keys [dimensions dimension-mappings]}
- (lib-metric/reconcile-dimensions-and-mappings seed-pairs nil nil)]
+ (let [{:keys [dimensions dimension-mappings]}
+ (lib-metric/reconcile-dimensions-and-mappings (metric-seed-pairs computed-pairs) nil nil)]
(save-dimensions! entity
(lib-metric/extract-persisted-dimensions
dimensions)
@@ -176,6 +181,45 @@
(lib-metric/reconcile-existing-dimensions computed-pairs persisted-dims persisted-mappings)]
(save-dimensions-if-changed! entity persisted-dims persisted-mappings dimensions dimension-mappings)))
+(defn compute-dimensions
+ "Reconcile an entity's freshly-computed dimensions against what is persisted and return the
+ result WITHOUT writing anything — the read-only sibling of [[sync-dimensions!]]. Returns
+ `{:dimensions … :dimension_mappings …}` in the same shape [[sync-dimensions!]] persists (and
+ [[filter-dimensions-for-user]] consumes), or nil when the entity has no dimensionable query.
+
+ `metadata-type` is `:metadata/metric` or `:metadata/measure`; `id` is the entity id."
+ [metadata-type id]
+ (when-let [entity (first (lib.metadata.protocols/metadatas
+ (lib-metric/metadata-provider)
+ {:lib/type metadata-type :id #{id}}))]
+ (when-let [query (lib-metric/dimensionable-query entity)]
+ (let [mp (lib-metric/metadata-provider)
+ computed-pairs (lib-metric/compute-dimension-pairs mp query)
+ persisted-dims (lib-metric/get-persisted-dimensions entity)
+ persisted-mappings (lib-metric/get-persisted-dimension-mappings entity)
+
+ {:keys [dimensions dimension-mappings]}
+ ;; Branch exactly as `sync-dimensions!` does, or a read reports something the REST
+ ;; endpoint never would. A curated metric's persisted set is authoritative, so
+ ;; reconciling it the measure way re-adds dimensions its owner removed and mints a fresh
+ ;; random id for every computed pair with no persisted mapping, on every read. An
+ ;; uninitialized one seeds from its own table, so reconciling every computed pair
+ ;; reports the implicitly-joinable FK columns seeding leaves out — and because this
+ ;; read never persists, it would keep reporting them until something else seeds.
+ (if (= metadata-type :metadata/metric)
+ (cond
+ (dimensions-initialized? entity)
+ (lib-metric/reconcile-existing-dimensions computed-pairs persisted-dims persisted-mappings)
+
+ (nil? persisted-dims)
+ (lib-metric/reconcile-dimensions-and-mappings (metric-seed-pairs computed-pairs) nil nil)
+
+ :else
+ {:dimensions persisted-dims :dimension-mappings persisted-mappings})
+ (lib-metric/reconcile-dimensions-and-mappings computed-pairs persisted-dims persisted-mappings))]
+ {:dimensions (lib-metric/extract-persisted-dimensions dimensions)
+ :dimension_mappings dimension-mappings}))))
+
(defn sync-dimensions!
"Sync an entity's dimensions to the database. Behaviour differs by entity type:
diff --git a/src/metabase/models/serialization/resolve.clj b/src/metabase/models/serialization/resolve.clj
index 15a86f4d60e..ba4ef1baec6 100644
--- a/src/metabase/models/serialization/resolve.clj
+++ b/src/metabase/models/serialization/resolve.clj
@@ -54,15 +54,14 @@
"Whether bare numeric table/field/card ids are accepted alongside portable references inside
a query body being resolved.
- False — the default and today's only live value: this PR lands the flag ahead of its readers,
- so current behavior is unchanged. The agent-lib dialect rework (a later PR in this stack)
- adds the schema predicate that consults it, and the v2 MCP query pipeline is the first binder
- (it binds true for the duration of a resolve). False stays the safe direction: a numeric id
- is rejected with a teaching error rather than resolved against whatever row happens to carry
- that id.
-
- It is ambient rather than a parameter because its eventual reader is a registered Malli
- schema predicate, which has no call site to thread a value through."
+ False is the default, and the safe direction: a numeric id is rejected with a teaching error
+ rather than resolved against whatever row happens to carry that id. True means the caller has
+ established that its surface may author bare ids, and accepts that every id it passes is an
+ untrusted integer — so the readers gated on this flag re-derive, explicitly, the guarantees a
+ portable reference gets for free from resolving a name (in this database, visible, readable).
+
+ It is ambient rather than a parameter because one of its readers is a registered Malli schema
+ predicate, which has no call site to thread a value through."
false)
;;; ============================================================
@@ -82,6 +81,28 @@
(and (string? s)
(entity-id? s)))
+(defn- numeric-source-id?
+ "True for a bare numeric content id, and only on a surface that accepts them (see
+ [[*numeric-ids-allowed?*]]). Off that surface a number in a source slot is not a reference at
+ all, so it must not match — that is what keeps the portable-only surface's behavior unchanged."
+ [x]
+ (and (pos-int? x) *numeric-ids-allowed?*))
+
+(defn- content-ref?
+ "True for any reference to Metabase content the numeric dialect covers — a card, metric,
+ segment, or measure — that this surface may author: a portable entity_id, or, on the
+ numeric-id surface, a bare id. Snippets are deliberately not included; see the `snippet-id`
+ branch below.
+
+ Every `import-mbql` branch that resolves content goes through this one predicate rather than
+ matching `portable-id?` and gaining a numeric twin. The numeric form needs no translation, but
+ it must still reach `import-fk`, because that is what consults the content store — and on
+ agent paths the store is `read-checked`, so the lookup *is* the permission check. A branch
+ that matched only the portable form would silently let a numeric id past it unchecked."
+ [x]
+ (or (portable-id? x)
+ (numeric-source-id? x)))
+
(defn serialized-query-source-table
"Given a serialized query (with portable references), returns the portable reference of the table it is based
on. Measures and segments use this to omit the table_id property when it is derivable from the query. This should be
@@ -121,31 +142,31 @@
(import-fk-keyed resolver fully-qualified-name :model/Database :name)))
(->> (mbql-fully-qualified-names->ids* resolver)))
- {:card-id (entity-id :guard portable-id?)}
+ {:card-id (entity-id :guard content-ref?)}
(-> &match
(assoc :card-id (import-fk resolver entity-id 'Card))
(->> (mbql-fully-qualified-names->ids* resolver)))
- [#{:metric "metric"} opts (entity-id :guard portable-id?)]
+ [#{:metric "metric"} opts (entity-id :guard content-ref?)]
[:metric (mbql-fully-qualified-names->ids* resolver opts)
(import-fk resolver entity-id 'Card)]
- [#{:segment "segment"} opts (entity-id :guard portable-id?)]
+ [#{:segment "segment"} opts (entity-id :guard content-ref?)]
[:segment (mbql-fully-qualified-names->ids* resolver opts)
(import-fk resolver entity-id 'Segment)]
- [#{:measure "measure"} opts (entity-id :guard portable-id?)]
+ [#{:measure "measure"} opts (entity-id :guard content-ref?)]
[:measure (mbql-fully-qualified-names->ids* resolver opts)
(import-fk resolver entity-id 'Measure)]
;; support legacy MBQL 4 refs for things like the serialized Audit v2 queries
- [#{:metric "metric"} (entity-id :guard portable-id?)]
+ [#{:metric "metric"} (entity-id :guard content-ref?)]
[:metric (import-fk resolver entity-id 'Card)]
- [#{:segment "segment"} (entity-id :guard portable-id?)]
+ [#{:segment "segment"} (entity-id :guard content-ref?)]
[:segment (import-fk resolver entity-id 'Segment)]
- [#{:measure "measure"} (entity-id :guard portable-id?)]
+ [#{:measure "measure"} (entity-id :guard content-ref?)]
[:measure (import-fk resolver entity-id 'Measure)]
{:source-table (_ :guard vector?)}
@@ -164,11 +185,18 @@
(assoc :source-table (str "card__" (import-fk resolver id 'Card)))
(->> (mbql-fully-qualified-names->ids* resolver)))
- {:source-card (id :guard portable-id?)}
- (-> &match
- (assoc :source-card (import-fk resolver id 'Card))
- (->> (mbql-fully-qualified-names->ids* resolver)))
-
+ {:source-card (id :guard content-ref?)}
+ ;; Recur on the rest of the map, not on `&match`: `import-fk` of a numeric id returns a
+ ;; numeric id, which still satisfies `content-ref?`, so recurring on the whole match would
+ ;; re-enter this branch on its own output forever. The `:source-table` branch escapes only
+ ;; because it rewrites the value to "card__N" and no longer matches.
+ (assoc (mbql-fully-qualified-names->ids* resolver (dissoc &match :source-card))
+ :source-card (import-fk resolver id 'Card))
+
+ ;; Portable only, deliberately. The numeric dialect does not cover snippets: no resolver
+ ;; implements `NativeQuerySnippet`, so a numeric one would fall through `import-fk`'s model
+ ;; tests to `not-implemented!` and surface as a bare 501 with no `:agent-error?` — never
+ ;; reaching the read-checked store. Widening this needs a store-backed snippet branch first.
{:snippet-id (id :guard portable-id?)}
(-> &match
(assoc :snippet-id (import-fk resolver id 'NativeQuerySnippet))
diff --git a/src/metabase/models/serialization/resolve/mp.clj b/src/metabase/models/serialization/resolve/mp.clj
index 32d92c61628..a1a19aaa559 100644
--- a/src/metabase/models/serialization/resolve/mp.clj
+++ b/src/metabase/models/serialization/resolve/mp.clj
@@ -485,6 +485,47 @@
:else
(:id card))))
+(defn- import-card-by-id
+ "Read-check a bare numeric `source-card` and return its id, on a surface that accepts numeric
+ ids.
+
+ The numeric dialect's counterpart to [[import-card-by-entity-id]]. It resolves to the id it
+ was handed, so the return value is not the point — routing the lookup through `content-store`
+ is: the agent-facing store is `read-checked`, so this is where a card the caller cannot read
+ is turned away instead of flowing on into repair. The store collapses that denial to `nil`,
+ which the `(nil? card)` branch below reports as the same not-found error an absent id gets —
+ deliberately, so the response cannot be used to tell a hidden card from a missing one. Without it a numeric id skips the store
+ entirely (`portable-id?` matches strings only), and the repair pass's column-name inference
+ would name the card's columns back to a caller who cannot read it.
+
+ Carries the same cross-database guard as the portable path, for the same reason."
+ [metadata-provider content-store card-id]
+ (let [current-db-id (:id (lib.metadata/database metadata-provider))
+ card (card-by-id content-store card-id)
+ card-db-id (when card (or (:database-id card) (:database_id card)))]
+ (cond
+ (nil? card)
+ (throw (ex-info (tru "No saved question or model found with id {0}." (str card-id))
+ {:agent-error? true
+ :status-code 400
+ :error :unknown-card-id
+ :card-id card-id}))
+
+ (not= card-db-id current-db-id)
+ (throw (ex-info (tru "Saved question / model {0} belongs to database {1}, but this query targets database {2}. Cross-database queries are not supported."
+ (str card-id)
+ (str card-db-id)
+ (str current-db-id))
+ {:agent-error? true
+ :status-code 400
+ :error :cross-database-card
+ :card-id card-id
+ :card-database-id card-db-id
+ :expected-database current-db-id}))
+
+ :else
+ (:id card))))
+
(defn- import-measure-by-entity-id
"Resolve a measure by its portable `entity_id` to its numeric id.
@@ -518,6 +559,39 @@
:else
(:id measure))))
+(defn- import-measure-by-id
+ "Read-check a bare numeric measure id and return it, on a surface that accepts numeric ids.
+
+ The numeric counterpart to [[import-measure-by-entity-id]]; see [[import-card-by-id]] for why
+ the lookup has to go through `content-store` even though the id needs no translation. Carries
+ the same table-scoped cross-database guard as the portable path."
+ [metadata-provider content-store measure-id]
+ (let [measure (measure-by-id content-store measure-id)
+ measure-table-id (when measure (or (:table-id measure) (:table_id measure)))
+ measure-table (when measure-table-id
+ (table-belongs-to-current-database? metadata-provider measure-table-id))
+ current-db-id (:id (lib.metadata/database metadata-provider))]
+ (cond
+ (nil? measure)
+ (throw (ex-info (tru "No measure found with id {0}." (str measure-id))
+ {:agent-error? true
+ :status-code 400
+ :error :unknown-measure-id
+ :measure-id measure-id}))
+
+ (nil? measure-table)
+ (throw (ex-info (tru "Measure {0} belongs to a table in a different database than this query (target database id {1}). Cross-database queries are not supported."
+ (str measure-id) (str current-db-id))
+ {:agent-error? true
+ :status-code 400
+ :error :cross-database-measure
+ :measure-id measure-id
+ :measure-table-id measure-table-id
+ :expected-database current-db-id}))
+
+ :else
+ (:id measure))))
+
(defn- export-measure-by-id
"Resolve a measure by numeric id to its portable `entity_id`. Validates that the measure's
table belongs to the metadata provider's database (cross-database guard)."
@@ -616,6 +690,38 @@
:else
(:id segment))))
+(defn- import-segment-by-id
+ "Read-check a bare numeric segment id and return it, on a surface that accepts numeric ids.
+
+ The numeric counterpart to [[import-segment-by-entity-id]]; see [[import-card-by-id]] for why
+ the lookup has to go through `content-store`. Same table-scoped cross-database guard."
+ [metadata-provider content-store segment-id]
+ (let [segment (segment-by-id content-store segment-id)
+ segment-table-id (when segment (or (:table-id segment) (:table_id segment)))
+ segment-table (when segment-table-id
+ (table-belongs-to-current-database? metadata-provider segment-table-id))
+ current-db-id (:id (lib.metadata/database metadata-provider))]
+ (cond
+ (nil? segment)
+ (throw (ex-info (tru "No segment found with id {0}." (str segment-id))
+ {:agent-error? true
+ :status-code 400
+ :error :unknown-segment-id
+ :segment-id segment-id}))
+
+ (nil? segment-table)
+ (throw (ex-info (tru "Segment {0} belongs to a table in a different database than this query (target database id {1}). Cross-database queries are not supported."
+ (str segment-id) (str current-db-id))
+ {:agent-error? true
+ :status-code 400
+ :error :cross-database-segment
+ :segment-id segment-id
+ :segment-table-id segment-table-id
+ :expected-database current-db-id}))
+
+ :else
+ (:id segment))))
+
(defn import-resolver
"Build a `SerdesImportResolver` backed by `metadata-provider` (warehouse metadata) and
`content-store` (Metabase content / assets).
@@ -640,6 +746,17 @@
(import-fk [_ eid model]
(cond
(nil? eid) nil
+ ;; A bare numeric id, which only the numeric-id surface may author. It needs no
+ ;; translation, but it still has to go through the (read-checked) content store —
+ ;; see [[import-card-by-id]]. Every content model gets this, not just Card: a numeric
+ ;; metric / segment / measure ref reaches the resolver by exactly the same route.
+ (int? eid)
+ (cond
+ (card-model? model) (import-card-by-id metadata-provider content-store eid)
+ (measure-model? model) (import-measure-by-id metadata-provider content-store eid)
+ (segment-model? model) (import-segment-by-id metadata-provider content-store eid)
+ :else (not-implemented! :import-fk))
+
(card-model? model) (import-card-by-entity-id metadata-provider content-store eid)
(measure-model? model) (import-measure-by-entity-id metadata-provider content-store eid)
(segment-model? model) (import-segment-by-entity-id metadata-provider content-store eid)
diff --git a/src/metabase/notification/api.clj b/src/metabase/notification/api.clj
index bbd351b2ba6..354fff92254 100644
--- a/src/metabase/notification/api.clj
+++ b/src/metabase/notification/api.clj
@@ -14,7 +14,8 @@
list-notifications
get-notification
publish-notification-update!
- unsubscribe-user!])
+ unsubscribe-user!
+ update-notification!])
(def ^{:arglists '([request respond raise])} notification-routes
"`/api/notification` routes."
diff --git a/src/metabase/notification/api/notification.clj b/src/metabase/notification/api/notification.clj
index 7473624fe2b..16e6277f926 100644
--- a/src/metabase/notification/api/notification.clj
+++ b/src/metabase/notification/api/notification.clj
@@ -246,6 +246,21 @@
(cond-> (assoc body :id id)
(and (:payload body) payload_id) (assoc-in [:payload :id] payload_id)))
+(mu/defn update-notification!
+ "Update notification `id` from `body` with the permission and handler-template checks and
+ post-update side effects, and return the updated hydrated notification. `body` is a whole
+ notification, not a patch: the update spec deletes the subscription and handler rows it doesn't
+ find there."
+ [id :- ms/PositiveInt
+ body :- ::NotificationApiUpdateInput]
+ (let [existing-notification (get-notification id)]
+ (api/update-check existing-notification body)
+ (check-handler-templates! (:handlers body) (:handlers existing-notification))
+ (let [body (body-with-authoritative-ids body existing-notification)]
+ (models.notification/update-notification! existing-notification body)
+ (u/prog1 (get-notification id)
+ (publish-notification-update! <> existing-notification)))))
+
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
;;
@@ -260,13 +275,7 @@
[{:keys [id]} :- [:map {:closed true} [:id ms/PositiveInt]]
_query
body :- ::NotificationApiUpdateInput]
- (let [existing-notification (get-notification id)]
- (api/update-check existing-notification body)
- (check-handler-templates! (:handlers body) (:handlers existing-notification))
- (let [body (body-with-authoritative-ids body existing-notification)]
- (models.notification/update-notification! existing-notification body)
- (u/prog1 (get-notification id)
- (publish-notification-update! <> existing-notification)))))
+ (update-notification! id body))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
diff --git a/src/metabase/oauth_server/api/metadata.clj b/src/metabase/oauth_server/api/metadata.clj
index ff6c520e988..7a8b7dd4255 100644
--- a/src/metabase/oauth_server/api/metadata.clj
+++ b/src/metabase/oauth_server/api/metadata.clj
@@ -3,6 +3,7 @@
Mounted under `/.well-known/`."
(:require
[metabase.api.macros :as api.macros]
+ [metabase.mcp.core :as mcp]
[metabase.oauth-server.core :as oauth-server]
[metabase.oauth-server.settings :as oauth-settings]
[metabase.system.core :as system]
@@ -38,9 +39,6 @@
(or (discovery-response)
{:status 404 :body {:error "not_found"}}))
-;; One endpoint per MCP path (canonical and legacy), kept in sync with [[metabase.mcp.api/endpoint-paths]].
-;; Each advertises its own path as `:resource`, so a strict RFC 9728 client connecting via the legacy
-;; alias still sees a resource value matching the URL it hit.
(def ^:private resource-metadata-response-schema
[:map
[:status [:= 200]]
@@ -51,16 +49,25 @@
[:bearer_methods_supported [:sequential :string]]]]])
(defn- protected-resource-metadata
- "OAuth Protected Resource Metadata (RFC 9728) advertising `resource-path` as the protected resource."
+ "OAuth Protected Resource Metadata (RFC 9728) advertising `resource-path` as the protected resource.
+
+ The advertised scopes are derived from `resource-path` rather than passed in, so the resource and the
+ scope set it accepts cannot disagree. A client reads `:scopes_supported` here and requests exactly
+ those; advertising another path's set hands it a token that authorizes nothing on the resource it
+ asked about, with no in-product way to widen the grant afterwards."
[resource-path]
(let [site-url (system/site-url)]
{:status 200
:headers {"Content-Type" "application/json"}
:body {:resource (str site-url resource-path)
:authorization_servers [site-url]
- :scopes_supported (vec (oauth-server/all-agent-scopes))
+ :scopes_supported (vec (oauth-server/mcp-resource-scopes resource-path))
:bearer_methods_supported ["header"]}}))
+;; One endpoint per MCP path, kept in sync with [[metabase.mcp.paths/endpoint-paths]]. Each advertises its own
+;; path as `:resource`, so a strict RFC 9728 client connecting via an alias still sees a resource value matching
+;; the URL it hit — and [[metabase.oauth-server.core/narrow-scope-to-resource]] recognizes all of them, so the
+;; scope narrowing applies whichever path the client came in on.
(api.macros/defendpoint :get "/oauth-protected-resource/api/metabase-mcp"
:- resource-metadata-response-schema
"Returns OAuth Protected Resource Metadata (RFC 9728) for the MCP endpoint."
@@ -75,9 +82,9 @@
;; Some clients probe the bare resource path instead of the resource-specific one; serve metadata here so the
;; request doesn't fall through to the SPA's HTML catch-all and trip a `JSON.parse` error (BOT-1617). Advertise the
-;; canonical `/api/metabase-mcp` resource, matching the URL clients are now told to use.
+;; canonical path, matching the URL clients are told to use.
(api.macros/defendpoint :get "/oauth-protected-resource"
:- resource-metadata-response-schema
"Returns OAuth Protected Resource Metadata (RFC 9728) for the MCP endpoint."
[]
- (protected-resource-metadata "/api/metabase-mcp"))
+ (protected-resource-metadata (mcp/mcp-canonical-path)))
diff --git a/src/metabase/oauth_server/api/oauth.clj b/src/metabase/oauth_server/api/oauth.clj
index 763ac02ffe8..4d19357e524 100644
--- a/src/metabase/oauth_server/api/oauth.clj
+++ b/src/metabase/oauth_server/api/oauth.clj
@@ -222,12 +222,15 @@
;; clients, so we apply sensible defaults here:
;; - application_type defaults to "native" (not the RFC default "web") so
;; CLI tools and desktop apps can use HTTP loopback redirects.
- ;; - scope defaults to all provider-supported scopes when not specified.
+ ;; - scope defaults to every scope any surface advertises. That is a ceiling on
+ ;; what the client may later request, not a grant (see
+ ;; [[metabase.oauth-server.core/default-grant-scopes]]), and clients derive what
+ ;; to request from discovery metadata rather than from this value.
(let [body (cond-> body
(not (contains? body :application_type))
(assoc :application_type "native")
(not (contains? body :scope))
- (assoc :scope (str/join " " (oauth-server/all-agent-scopes)))
+ (assoc :scope (str/join " " (oauth-server/default-grant-scopes)))
;; Remove client_credentials grant type — tokens issued without a
;; user context are unusable for MCP (validate-bearer-token requires
;; a valid user-id).
@@ -292,6 +295,25 @@
(or (when-let [provider (oauth-server/get-provider)]
(try
(let [parsed (oidc/parse-authorization-request provider query-params)
+ ;; Narrow before signing: the signature then binds the narrowed scope through the
+ ;; consent form round-trip, so the decision endpoint grants exactly what was shown.
+ requested (some-> (:scope parsed) str str/trim not-empty)
+ narrowed (oauth-server/narrow-scope-to-resource (:resource parsed) (:scope parsed))
+ ;; `narrow-scope-to-resource` answers nil both for "no scope was requested" and for
+ ;; "a scope was requested and nothing survived". Only the first may drop the parameter.
+ ;; The second means the client asked exclusively for scopes this resource does not
+ ;; accept: dropping it there renders a consent screen listing nothing and mints a
+ ;; zero-scope token, which looks like success and leaves an empty `tools/list` with no
+ ;; in-product way to widen the grant. RFC 6749 section 4.1.2.1 has an error for it.
+ _ (when (and requested (not narrowed))
+ (throw (ex-info "no requested scope is accepted by the named resource"
+ {:oauth-error "invalid_scope"
+ :error-description (str "The requested scopes are not accepted by "
+ "the requested resource.")
+ :resource (:resource parsed)})))
+ parsed (if narrowed
+ (assoc parsed :scope narrowed)
+ (dissoc parsed :scope))
client (proto/get-client (:client-store provider) (:client_id parsed))
csrf-token (generate-csrf-token)
oauth-params (select-keys parsed oauth-param-keys)
@@ -308,10 +330,12 @@
(response/set-cookie csrf-cookie-name csrf-token (csrf-cookie-opts 600))))
(catch ExceptionInfo e
(log/warnf "OAuth authorize request failed: %s" (ex-message e))
- {:status 400
- :headers {"Content-Type" "application/json"}
- :body {:error "invalid_request"
- :error_description "The authorization request is invalid."}})))
+ (let [{:keys [oauth-error error-description]} (ex-data e)]
+ {:status 400
+ :headers {"Content-Type" "application/json"}
+ :body {:error (or oauth-error "invalid_request")
+ :error_description (or error-description
+ "The authorization request is invalid.")}}))))
{:status 404 :body {:error "not_found"}})))
(api.macros/defendpoint :post "/authorize/decision"
diff --git a/src/metabase/oauth_server/core.clj b/src/metabase/oauth_server/core.clj
index be7c0db10b0..9932a1b784e 100644
--- a/src/metabase/oauth_server/core.clj
+++ b/src/metabase/oauth_server/core.clj
@@ -26,20 +26,127 @@
;; after the operator corrects Site URL to https://).
(defonce ^:private provider (atom nil))
-(defn all-agent-scopes
- "All agent OAuth scopes derived from defendpoint metadata on the agent API,
- plus scopes from MCP UI resources (e.g. visualize_query). These are the scopes a
- dynamically-registered MCP client is granted by default at registration time."
+(defn supported-scopes
+ "All OAuth scopes intended to be advertised in the server's discovery metadata (`scopes-supported`).
+
+ `mb:full` is deliberately absent. Advertising it here puts a full-access grant in front of every client that reads
+ discovery metadata, so keeping it out means no client is led toward it. Note this is not a gate: dynamic
+ registration is unauthenticated and passes a client-supplied `scope` through unchecked, so a client that names
+ `mb:full` itself still registers with it. Keeping it off this list narrows who finds it, not who may ask."
[]
- (mcp/all-scopes))
+ (vec (into (sorted-set) (mcp/all-scopes))))
-(defn supported-scopes
- "All OAuth scopes advertised in the server's discovery metadata (`scopes-supported`):
- the agent/MCP scopes plus the top-level first-party scopes (e.g. `mb:full`). This is a
- superset of [[all-agent-scopes]] — the extra scopes are not part of the default grant a
- client receives at registration, so a client must explicitly request them."
+(defn mcp-resource-scopes
+ "The scopes advertised for the MCP resource at `path`. RFC 9728 metadata answers \"what does *this* resource
+ accept\", and every path in [[metabase.mcp.paths/endpoint-paths]] now reaches the same v2 surface, so they
+ all accept the same set: the scopes the v2 tool registry gates on plus the resource scopes its UI tools
+ render through.
+
+ This branched while v1 was still served. v1's tools gated on the per-entity agent-API scopes
+ (`agent:question:create`, `agent:sql:execute`, …), so the aliases that reached v1 had to advertise those or
+ a client following the metadata would land with an empty `tools/list`. With v1 retired (#81708) the branch
+ inverted: the canonical `/api/metabase-mcp` served v2 tools while advertising fourteen scopes no tool gates
+ on any more, putting them on a consent screen for capabilities that no longer exist. `path` is kept in the
+ signature because RFC 9728 metadata is per-resource and a future surface may diverge again."
+ [_path]
+ (vec (into (sorted-set) (mcp/v2-scopes))))
+
+(defn default-grant-scopes
+ "The scope set a dynamically-registered client is registered with when it sends no `scope` of its own (RFC 7591 makes
+ the parameter optional, and the major MCP clients omit it).
+
+ This is a *ceiling*, not a grant, according to the RFC: a client may later request any subset of it, and the token
+ carries only what was requested and consented to. Because it is a ceiling it must cover everything any surface
+ advertises — a client derives what to ask for from discovery metadata, never from what it registered with, so a
+ scope we advertise but do not register is one the authorization request is rejected outright. Hence the union of
+ every advertised set rather than a hand-maintained list.
+
+ Narrowing this does not produce least privilege, it produces failed authorizations. The levers that shrink an issued
+ token are what each resource advertises, [[narrow-scope-to-resource]], and the consent screen."
[]
- (conj (vec (all-agent-scopes)) full-access-scope))
+ ;; sorted so the `scope` echoed back in the registration response is stable across restarts
+ (into (sorted-set) (supported-scopes)))
+
+(def ^:private scheme-default-port
+ {"http" 80, "https" 443})
+
+(defn- canonical-resource-uri
+ "Canonical form of a resource identifier, for comparing indicators that clients spell differently.
+
+ Lowercases scheme and host, elides the scheme's default port, and trims a trailing slash. Query and fragment are
+ dropped: the canonical form has neither, and ignoring them can only cause narrowing, never widening. Returns nil for
+ anything that is not an absolute URI, which then matches nothing.
+
+ Per RFC 3986 the scheme and host are case-insensitive and the default port is elidable; the path is neither, so
+ `/API/v2` deliberately does not canonicalize to `/api/v2`."
+ [s]
+ (when s
+ (try
+ (let [^java.net.URI uri (java.net.URI. (str s))
+ scheme (some-> (.getScheme uri) u/lower-case-en)
+ ;; `.getHost` is nil for a host java.net.URI considers non-conformant -- notably one with an
+ ;; underscore, which is routine for Docker Compose / k8s service names and which Metabase's own
+ ;; `u/url?` accepts. Reading the authority instead keeps those canonicalizing; a nil host here
+ ;; would return nil, match nothing, and disable narrowing instance-wide and silently.
+ authority (some-> (.getAuthority uri) u/lower-case-en)
+ [host port] (when authority
+ (if-let [[_ h p] (re-matches #"(?:[^@]*@)?(.*?)(?::(\d+))?" authority)]
+ [h (some-> p parse-long)]
+ [authority nil]))
+ path (or (.getPath uri) "")]
+ (when (and scheme (not-empty host))
+ (str scheme "://" host
+ (when-not (or (nil? port) (= port (scheme-default-port scheme)))
+ (str ":" port))
+ (cond-> path
+ (and (> (count path) 1) (str/ends-with? path "/"))
+ (subs 0 (dec (count path)))))))
+ (catch java.net.URISyntaxException _ nil))))
+
+(defn narrow-scope-to-resource
+ "Narrow an OAuth `scope` string to what the requested `resources` accept.
+
+ `resources` are RFC 8707 resource indicators from the authorization request. When one names the MCP resource —
+ compared as [[canonical-resource-uri]], since clients disagree on trailing slashes, case, and default ports — scopes
+ no named surface accepts are dropped, so the consent screen asks for what the token can actually be used for
+ rather than everything the client registered. Several indicators may be sent, and the token has to work against
+ each, so what survives is the union of what they accept. Returns the scope unchanged when no indicator names a
+ resource we narrow for, and nil when nothing survives.
+
+ Note nil is the answer for both \"nothing was requested\" and \"nothing survived\"; the caller has the requested
+ scope and must tell them apart, since only the first may drop the parameter (see the authorize handler).
+
+ Every alias in [[metabase.mcp.core/mcp-endpoint-paths]] counts, not just the canonical one: a client that connected
+ through an alias was handed that path as its resource identifier, and narrowing has to recognize what it was told to
+ send back.
+
+ Only ever removes scopes, and runs after the provider has validated the request, so it can never turn a valid
+ authorization into a rejected one.
+
+ `mb:full` does not survive. The MCP resource metadata never advertised it, and a client naming the MCP resource is
+ asking for a token to use against that surface — which accepts none of the REST API that scope unlocks.
+
+ This shapes the consent screen and the stored grant; it is not audience enforcement. `resolve-access-token` does
+ not read `:resource` from the token row, so a token narrowed against one MCP path is still accepted at another,
+ and a client that omits the indicator is not narrowed at all. Both gaps are inherited rather than introduced
+ here; closing them is BOT-2124."
+ [resources scope]
+ (let [scope (some-> scope str str/trim not-empty)
+ ;; A lone indicator may arrive as a bare string (the endpoint schema allows one). `keep` over a String
+ ;; iterates characters, none of which canonicalize, which would silently skip narrowing entirely --
+ ;; so normalize before the scan rather than relying on the caller having vectorized.
+ named (into #{} (keep canonical-resource-uri)
+ (cond-> resources (string? resources) vector))
+ ;; Every MCP path the request actually named. A client may send several RFC 8707 indicators, and the
+ ;; token has to work against each -- so the accepted set is the UNION of what they accept, not the set
+ ;; of whichever one is checked first. Taking a single winner would drop the v1-only scopes when a v1
+ ;; alias is named alongside v2, silently shrinking a grant the client asked for and the user approved.
+ matched (filter #(contains? named (canonical-resource-uri (str (system/site-url) %)))
+ (mcp/mcp-endpoint-paths))]
+ (if (or (not scope) (empty? matched))
+ scope
+ (let [accepted (into #{} (mapcat mcp-resource-scopes) matched)]
+ (not-empty (str/join " " (filter accepted (str/split scope #"\s+"))))))))
(defn- build-provider-config
"Build the configuration map for the OAuth provider from Metabase settings."
diff --git a/src/metabase/parameters/chain_filter.clj b/src/metabase/parameters/chain_filter.clj
index 3c98ee1bcdc..f6a103a8742 100644
--- a/src/metabase/parameters/chain_filter.clj
+++ b/src/metabase/parameters/chain_filter.clj
@@ -657,6 +657,61 @@
:else
(unremapped-chain-filter field-id constraints options))))
+(mu/defn- chain-filter-range-mbql-query :- ::lib.schema/query
+ "The query behind [[chain-filter-range]]: the same source table, joins and constraint filters
+ [[chain-filter-mbql-query]] builds, aggregated to a single row instead of broken out into values.
+
+ Two deliberate differences from the values query. There is no limit — that is the whole point, since an
+ aggregation reads the entire column and yields the column's real max rather than the last of a capped
+ page. And there is no remapping: a range describes the filtered column itself, and a display label
+ (`category_id` shown as `category.name`) has no min or max worth reporting."
+ [field-id :- ::lib.schema.id/field
+ constraints :- [:maybe ::constraints]]
+ (let [database-id (field/field-id->database-id field-id)
+ mp (lib-be/application-database-metadata-provider database-id)
+ source-table-id (:table-id (lib.metadata/field mp field-id))
+ joins (find-all-joins mp database-id source-table-id (set (map :field-id constraints)))
+ joined-table-ids (set (map #(get-in % [:rhs :table]) joins))
+ field (lib.metadata/field mp field-id)]
+ (when (seq joins)
+ (log/tracef "Generating joins and filters for source %s with joins info\n%s"
+ (name-for-logging :model/Table source-table-id) (pr-str joins)))
+ (-> (lib/query mp (lib.metadata/table mp source-table-id))
+ (assoc-in [:middleware :disable-remaps?] true)
+ (add-joins source-table-id joins)
+ (lib/aggregate (lib/min field))
+ (lib/aggregate (lib/max field))
+ (lib/aggregate (lib/distinct field))
+ (add-filters source-table-id joined-table-ids constraints)
+ schema.metadata-queries/add-required-filters-if-needed
+ ;; Runs LAST for the same reason it does in the values query — see the note there.
+ tighten-join-projections)))
+
+(mu/defn chain-filter-range :- [:map
+ [:min [:maybe :any]]
+ [:max [:maybe :any]]
+ [:distinct-count [:maybe :int]]]
+ "The span of Field `field-id` under the same `constraints` [[chain-filter]] applies, as
+ `{:min :max :distinct-count}`, by aggregating rather than listing.
+
+ For a column whose distinct values are a range to filter inside rather than a set to pick from — dates,
+ above all — this is the answer [[chain-filter]] cannot give: it caps at 1000 values, and since values come
+ back ascending, a capped fetch's last value is the 1000th-earliest rather than the column's max.
+
+ A column with no rows (or none the caller can see) answers with nils and a zero count, not an error."
+ [field-id :- ::lib.schema.id/field
+ constraints :- [:maybe ::constraints]]
+ (let [mbql-query (chain-filter-range-mbql-query field-id constraints)]
+ (try
+ (let [[lo hi n] (first (:rows (:data (qp/process-query mbql-query))))]
+ {:min lo :max hi :distinct-count (or n 0)})
+ (catch Throwable e
+ (throw (ex-info (tru "Error executing chain filter range query")
+ {:field-id field-id
+ :constraints constraints
+ :mbql-query mbql-query}
+ e))))))
+
;;; ----------------- Chain filter search (powers GET /api/dashboard/:id/params/:key/search/:query) -----------------
;; TODO -- if this validation succeeds, we can probably cache that success for a bit so we can avoid unneeded DB
diff --git a/src/metabase/parameters/dashboard.clj b/src/metabase/parameters/dashboard.clj
index 1ac85731541..007fb60260d 100644
--- a/src/metabase/parameters/dashboard.clj
+++ b/src/metabase/parameters/dashboard.clj
@@ -11,6 +11,7 @@
[metabase.util :as u]
[metabase.util.i18n :refer [tru]]
[metabase.util.malli :as mu]
+ [metabase.util.malli.registry :as mr]
[metabase.util.malli.schema :as ms]
[toucan2.core :as t2]))
@@ -109,6 +110,48 @@
(api/throw-403 e)
(throw e))))))))
+(mr/def ::range
+ "The span of a parameter's column: its extremes, and how many distinct values lie between them.
+ `:distinct-count` is nil when the parameter maps to several fields, whose distinct values overlap
+ in ways only a union could count — the extremes still merge exactly."
+ [:map
+ [:min [:maybe :any]]
+ [:max [:maybe :any]]
+ [:distinct-count [:maybe :int]]])
+
+(mu/defn param-range :- [:maybe ::range]
+ "The span of `param-key`'s column under the other filters' current selections, for a parameter whose
+ values are a range to filter inside rather than a set to pick from. Answers nil when the parameter
+ maps to no queryable field — a field-ref-only mapping has no column to aggregate, so the caller must
+ fall back to listing values.
+
+ Aggregates instead of listing, which is the whole reason to prefer it over [[chain-filter]] here:
+ listing stops at `result-limit` and, since values come back ascending, its last value is the
+ 1000th-earliest rather than the column's max. Extremes merge across a multi-field parameter exactly
+ (the min of mins bounds every field, as does the max of maxes); the distinct count cannot, and is
+ dropped rather than guessed at."
+ [dashboard :- :map
+ param-key :- ms/NonBlankString
+ constraint-param-key->value :- [:map-of string? any?]]
+ (let [dashboard (cond-> dashboard
+ (nil? (:resolved-params dashboard)) (t2/hydrate :resolved-params))
+ constraints (chain-filter-constraints dashboard constraint-param-key->value)
+ param (get-in dashboard [:resolved-params param-key])
+ field-ids (into #{} (map :field-id (param->fields param)))]
+ (when (seq field-ids)
+ (try
+ (let [ranges (mapv #(chain-filter/chain-filter-range % constraints) field-ids)
+ extreme (fn [k pick]
+ (some-> (seq (keep k ranges)) sort pick))]
+ {:min (extreme :min first)
+ :max (extreme :max last)
+ :distinct-count (when (= 1 (count ranges))
+ (:distinct-count (first ranges)))})
+ (catch clojure.lang.ExceptionInfo e
+ (if (= (:type (u/all-ex-data e)) qp.error-type/missing-required-permissions)
+ (api/throw-403 e)
+ (throw e)))))))
+
(mu/defn param-values
"Fetch values for a parameter.
diff --git a/src/metabase/parameters/field.clj b/src/metabase/parameters/field.clj
index bcd6df90168..ad352cfbd1d 100644
--- a/src/metabase/parameters/field.clj
+++ b/src/metabase/parameters/field.clj
@@ -83,23 +83,63 @@
:has_more_values (boolean has_more_values)}
(params.field-values/get-or-create-field-values-for-current-user! (api/check-404 field))))
-(mu/defn search-values-from-field-id :- ms/FieldValuesResult
- "Search for values of a field given by `field-id` that contain `query`."
- [field-id :- ::lib.schema.id/field
- query-string :- [:maybe :string]]
+(defn- resolve-search-fields
+ "Resolve the `[field search-field]` pair for a `field-id` param-values search: `field` is permission-checked
+ (relaxed to a 404 check under `*param-values-query*`, since when fetching values for a card/dashboard the caller can
+ read we skip the Field read-check that requires create-queries permission), and `search-field` follows any
+ Field->Field remapping."
+ [field-id]
(let [field (if qp.perms/*param-values-query*
- ;; When fetching param values for a card/dashboard the user can read, skip the Field
- ;; read-check which requires create-queries permission on the table.
(api/check-404 (parameters.db/field field-id))
(api/read-check (parameters.db/field field-id)))
search-field (or (some->> (chain-filter/remapped-field-id field-id)
parameters.db/field)
field)]
+ [field search-field]))
+
+(mu/defn search-values-from-field-id :- ms/FieldValuesResult
+ "Search for values of a field given by `field-id` that contain `query`.
+
+ `:has_more_values` is a heuristic here, not a measurement: `true` whenever a `query-string` narrowed the search,
+ `false` otherwise. A no-query fetch that fills the underlying `default-max-field-search-limit` cap is still reported
+ `false`. Callers that must not present a capped list as complete -- e.g. so an agent isn't handed a truncated value
+ set believing it is the whole column -- should use [[search-values-from-field-id-strict]], which reports a truthful
+ floor when the cap is hit and surfaces fetch errors rather than swallowing them to `[]`."
+ [field-id :- ::lib.schema.id/field
+ query-string :- [:maybe :string]]
+ (let [[field search-field] (resolve-search-fields field-id)]
{:values (search-values field search-field query-string)
;; assume there are more if doing a search, otherwise there are no more values
:has_more_values (not (str/blank? query-string))
:field_id field-id}))
+(mu/defn search-values-from-field-id-strict :- ms/FieldValuesResult
+ "Like [[search-values-from-field-id]], but honest about the two things that fn papers over, for callers (the MCP
+ `get_parameter_values` tool) that must not mislead an agent:
+
+ 1. `:has_more_values` is a floor: `true` exactly when the underlying query filled the
+ `default-max-field-search-limit` cap, so a column with more distinct values than the cap reads as truncated
+ rather than complete. Unlike [[search-values-from-field-id]] it does NOT report `true` merely because a
+ `query-string` narrowed the search — this fn runs the query itself and can count the rows, and claiming
+ more exist when the search returned everything tells an agent to keep narrowing a list it already has
+ in full.
+
+ 2. A fetch error propagates. Unlike [[search-values]], which logs and returns `[]` -- turning a warehouse timeout
+ or sandbox error into an empty list that reads as \"no values\" -- this runs the search query directly, so the
+ exception reaches the caller.
+
+ For the field-backed source only; static-list and card sources already report `:has_more_values` truthfully via
+ `custom-values`."
+ [field-id :- ::lib.schema.id/field
+ query-string :- [:maybe :string]]
+ (let [[field search-field] (resolve-search-fields field-id)
+ limit default-max-field-search-limit
+ rows (search-values-query/search-values-query
+ (follow-fks field) (follow-fks search-field) (not-empty query-string) limit)]
+ {:values rows
+ :has_more_values (>= (count rows) limit)
+ :field_id field-id}))
+
(defn parse-query-param-value-for-field
"Parse a `value` passed as a URL query param in a way appropriate for the `field` it belongs to. E.g. for text Fields
the value doesn't need to be parsed; for numeric Fields we should parse it as a number."
diff --git a/src/metabase/parameters/mapping_targets.clj b/src/metabase/parameters/mapping_targets.clj
new file mode 100644
index 00000000000..37dbdff7bd6
--- /dev/null
+++ b/src/metabase/parameters/mapping_targets.clj
@@ -0,0 +1,203 @@
+(ns metabase.parameters.mapping-targets
+ "Enumerate the parameter mapping targets a card exposes: which of its columns or template tags a dashboard parameter
+ can be wired to.
+
+ The frontend has owned this since dashboards gained parameters (`getParameterMappingOptions`); this is the
+ server-side equivalent, which dashboard authoring over the API needs in order to validate a requested mapping and
+ to auto-wire a parameter across a dashboard's cards."
+ (:require
+ [clojure.string :as str]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.lib.schema.parameter :as lib.schema.parameter]
+ [metabase.parameters.params :as params]
+ [metabase.util :as u]
+ [metabase.util.log :as log]))
+
+(set! *warn-on-reflection* true)
+
+(defn- card-query
+ "`card`'s query as MBQL 5, or nil when it has none. Accepts cards whose query is still legacy MBQL."
+ [card]
+ (some-> card :dataset_query not-empty lib-be/normalize-query))
+
+(defn- parameter-family
+ "The part of a parameter type before the slash, e.g. `\"string\"` for `:string/=`, or nil."
+ [parameter-type]
+ (when parameter-type
+ (first (str/split (u/qualified-name parameter-type) #"/"))))
+
+(defn- types-allowed-together?
+ "Guarded [[lib.schema.parameter/parameter-type-and-widget-type-allowed-together?]]: false rather than an exception
+ when either type is not one this version knows about."
+ [parameter-type widget-type]
+ (let [parameter-type (some-> parameter-type u/qualified-name keyword)
+ widget-type (some-> widget-type u/qualified-name keyword)]
+ (boolean (and (contains? lib.schema.parameter/types parameter-type)
+ (contains? lib.schema.parameter/types widget-type)
+ (lib.schema.parameter/parameter-type-and-widget-type-allowed-together? parameter-type widget-type)))))
+
+(defn- tag-compatible?
+ "Whether a template tag can serve a parameter of `parameter-type`. A field filter (dimension) tag is matched on its
+ `:widget-type`, a raw value tag on the tag's own `:type`."
+ [parameter-type {tag-type :type, widget-type :widget-type}]
+ (if (= :dimension (keyword tag-type))
+ ;; a dimension tag with no declared widget type constrains nothing, so it can serve any parameter
+ (or (nil? widget-type)
+ (types-allowed-together? parameter-type widget-type))
+ (types-allowed-together? parameter-type tag-type)))
+
+(defn- native-targets
+ [query parameter]
+ (for [[tag-name tag] (lib/all-template-tags-map query)
+ :when (tag-compatible? (:type parameter) tag)]
+ {:target (if (= :dimension (keyword (:type tag)))
+ [:dimension [:template-tag (name tag-name)]]
+ [:variable [:template-tag (name tag-name)]])
+ :column-name (name tag-name)
+ :display-name (or (:display-name tag) (name tag-name))}))
+
+(defn- column-compatible?
+ "Whether `column` can back a parameter of `parameter-type`. Mirrors the frontend's
+ `isParameterCompatibleWithColumn`: the parameter's family decides which type of column it accepts."
+ [parameter-type column]
+ (let [column-type (or (:effective-type column) (:base-type column))
+ semantic (:semantic-type column)
+ id? (or (isa? semantic :type/PK) (isa? semantic :type/FK))
+ address? (isa? semantic :type/Address)
+ text? (or (isa? column-type :type/Text) (isa? column-type :type/TextLike))]
+ (case (parameter-family parameter-type)
+ "date" (isa? column-type :type/Temporal)
+ "temporal-unit" (isa? column-type :type/Temporal)
+ "id" id?
+ "number" (and (isa? column-type :type/Number) (not id?))
+ "string" (and text? (not address?))
+ "location" (and text? address?)
+ "boolean" (isa? column-type :type/Boolean)
+ "category" true
+ false)))
+
+(defn- dimension-ref
+ "The ref for `column` to embed in a `:dimension` target. A `:dimension` target is not an MBQL 5 clause — it still
+ holds a legacy `:field` or `:expression` ref."
+ [column]
+ (let [opts (when-let [fk-field-id (:fk-field-id column)]
+ {:source-field fk-field-id})]
+ (cond
+ (:id column) [:field (:id column) opts]
+ (= :source/expressions (:lib/source column)) [:expression (:name column)]
+ :else [:field (:name column) (assoc opts :base-type (:base-type column))])))
+
+(defn- mbql-targets
+ "Filterable columns of `card`'s query as dimension targets."
+ [card parameter]
+ (vec (for [col (params/filterable-columns-for-query card -1)
+ :when (column-compatible? (:type parameter) col)]
+ ;; `{:stage-number 0}` is not decoration — without it the target resolves wrong on multi-stage queries
+ {:target [:dimension (dimension-ref col) {:stage-number 0}]
+ :column-name (:name col)
+ :display-name (or (:display-name col) (:name col))})))
+
+(defn valid-targets
+ "The mapping targets `card` exposes for `parameter` (a parameter map with `:id` and `:type`), as
+ `[{:target :column-name :display-name} …]`. Empty when the card exposes nothing compatible. Never throws — an
+ unrunnable card yields no targets."
+ [card parameter]
+ (try
+ (let [query (card-query card)]
+ (cond
+ (nil? query) []
+ (lib/native-only-query? query) (vec (native-targets query parameter))
+ :else (mbql-targets card parameter)))
+ (catch Exception e
+ ;; an unrunnable card should narrow the wiring options, not fail the whole save
+ (log/warnf e "Could not enumerate mapping targets for card %s" (:id card))
+ [])))
+
+(defn target-for-field
+ "The target on `card` that `parameter` can use to filter on `field-id`, or nil when the card exposes no compatible
+ column for that field."
+ [card parameter field-id]
+ (->> (valid-targets card parameter)
+ ;; `param-target->field-id` is the same resolution the rest of the codebase uses for both dimension and
+ ;; template-tag targets — matching on the ref's shape here would drift from it
+ (filter #(= field-id (params/param-target->field-id (:target %) card)))
+ first
+ :target))
+
+(defn template-tag-types
+ "Map of template-tag name (string) -> tag type keyword for `card`'s native query — e.g.
+ `{\"category\" :dimension, \"min_total\" :number}`. Read from the stored query directly (either the
+ legacy `[:native :template-tags]` slot or an MBQL 5 native stage), so one malformed tag — e.g. a
+ snippet reference missing its id — can't degrade the whole map the way non-strict normalization
+ would. Empty when the card has no native query or no tags."
+ [card]
+ (let [dq (:dataset_query card)
+ tags (or (not-empty (get-in dq [:native :template-tags]))
+ (some (comp not-empty :template-tags) (:stages dq))
+ (let [query (card-query card)]
+ (when (and query (lib/native-only-query? query))
+ (lib/all-template-tags-map query))))
+ ;; a legacy native query keys tags by name; a pMBQL stage stores them as a vector of tag maps
+ tags (if (map? tags) (vals tags) tags)]
+ (into {}
+ (map (fn [tag] [(u/qualified-name (:name tag)) (keyword (:type tag))]))
+ tags)))
+
+(def variable-tag-types
+ "Template-tag types whose parameter mapping target is `[:variable [:template-tag <name>]]` — raw value
+ substitutions the caller supplies an operator for."
+ #{:text :number :date :boolean})
+
+(def dimension-tag-types
+ "Template-tag types whose parameter mapping target is `[:dimension [:template-tag <name>]]` — tags bound
+ to a real column, where the server expands the parameter into the right SQL."
+ #{:dimension :temporal-unit})
+
+(defn target-for-tag
+ "The mapping target for the template tag named `tag-name` (whose type is `tag-type`, from
+ [[template-tag-types]]): `[:dimension …]` for a field-filter or temporal-unit tag, `[:variable …]` for a
+ raw variable. Nil for a tag kind that can't back a parameter (snippet/card/table reference tags splice
+ SQL text and take no value)."
+ [tag-name tag-type]
+ (cond
+ (contains? dimension-tag-types tag-type) [:dimension [:template-tag tag-name]]
+ (contains? variable-tag-types tag-type) [:variable [:template-tag tag-name]]
+ :else nil))
+
+(defn- target-ref-name
+ "The column-name string a `:dimension` target's ref carries — `[:expression \"name\"]`, or a name-based
+ `[:field \"name\" opts]` ref — or nil for id-based refs."
+ [target]
+ (when (and (sequential? target) (= :dimension (keyword (first target))))
+ (let [[head arg] (second target)]
+ (case (some-> head keyword)
+ :expression (when (string? arg) arg)
+ :field (when (string? arg) arg)
+ nil))))
+
+(defn wireable-target?
+ "Whether `target` (a normalized mapping-target clause) points at something `card` actually exposes for
+ `parameter`: a template tag whose kind matches the clause head, or a column among the card's compatible
+ mapping targets (matched by resolved field id, or by column name for expression/name-based refs). Used to
+ reject a wire whose mapping would save cleanly but resolve to nothing at render time. `:text-tag` targets
+ bind a virtual dashcard's own content rather than a card and are out of scope here — callers validate
+ them against the dashcard."
+ [card parameter target]
+ (try
+ (let [target (lib/normalize ::lib.schema.parameter/target target)]
+ (if-let [tag-name (lib/parameter-target-template-tag-name target)]
+ (let [tag-type (get (template-tag-types card) tag-name)]
+ (= (some-> target first keyword)
+ (some-> (target-for-tag tag-name tag-type) first)))
+ (let [targets (valid-targets card parameter)
+ field-id (params/param-target->field-id target card)
+ ref-name (target-ref-name target)]
+ (boolean
+ (or (and field-id
+ (some #(= field-id (params/param-target->field-id (:target %) card)) targets))
+ (and ref-name
+ (some #(= ref-name (:column-name %)) targets)))))))
+ (catch Exception e
+ (log/warnf e "Could not validate mapping target %s for card %s" (pr-str target) (:id card))
+ false)))
diff --git a/src/metabase/parameters/params.clj b/src/metabase/parameters/params.clj
index fc06ede5bed..04ba37baab0 100644
--- a/src/metabase/parameters/params.clj
+++ b/src/metabase/parameters/params.clj
@@ -242,7 +242,7 @@
;; for backward compatibility, append a filter stage only with explicit stage numbers
(cond-> query (>= stage-number 0) lib/ensure-filter-stage))))
-(mu/defn- filterable-columns-for-query :- [:maybe [:sequential ::lib.schema.metadata/column]]
+(mu/defn filterable-columns-for-query :- [:maybe [:sequential ::lib.schema.metadata/column]]
"Get the filterable columns of `card`'s query at `stage-number`."
[card :- :metabase.queries.schema/card
stage-number :- :int]
diff --git a/src/metabase/pulse/broken_subscriptions.clj b/src/metabase/pulse/broken_subscriptions.clj
new file mode 100644
index 00000000000..11b53b941a0
--- /dev/null
+++ b/src/metabase/pulse/broken_subscriptions.clj
@@ -0,0 +1,96 @@
+(ns metabase.pulse.broken-subscriptions
+ "Detection, repair, and notification for dashboard subscriptions whose parameters no longer exist on
+ the dashboard they belong to."
+ (:require
+ [metabase.channel.email.messages :as messages]
+ [metabase.pulse.db :as pulse.db]
+ [metabase.pulse.models.pulse :as pulse]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(defn- bad-pulse-notification-data
+ "Given a pulse and bad parameters, return relevant notification data:
+ - The name of the pulse
+ - Which selected parameter values are broken
+ - The user info for the creator of the pulse
+ - The users affected by the pulse"
+ [{bad-pulse-id :id pulse-name :name :keys [parameters creator_id]}]
+ (let [creator (pulse.db/user-name-and-email creator_id)
+ bad-pulse-channels (pulse.db/pulse-channel-kinds-for-pulse bad-pulse-id)]
+ {:pulse-id bad-pulse-id
+ :pulse-name pulse-name
+ :bad-parameters parameters
+ :pulse-creator creator
+ :affected-users (into []
+ (comp
+ (filter #(contains? #{:email :slack} (:channel_type %)))
+ (mapcat (fn [{pulse-channel-id :id
+ channel-type :channel_type
+ {:keys [channel]} :details}]
+ (case channel-type
+ :email (let [pulse-channel-recipient-ids (map :user_id (pulse.db/pulse-channel-recipient-rows pulse-channel-id))
+ pulse-channel-recipients (when (seq pulse-channel-recipient-ids)
+ (pulse.db/users-names-and-emails pulse-channel-recipient-ids))]
+ (map (fn [{:keys [common_name] :as recipient}]
+ (assoc recipient
+ :notification-type channel-type
+ :recipient common_name))
+ pulse-channel-recipients))
+ :slack [{:notification-type channel-type
+ :recipient channel}]))))
+ bad-pulse-channels)}))
+
+(defn- broken-pulses
+ "Identify and return any pulses used in a subscription that contain parameters that are no longer on the dashboard."
+ [dashboard-id original-dashboard-params]
+ (when (seq original-dashboard-params)
+ (let [{:keys [resolved-params]} (t2/hydrate
+ (pulse.db/dashboard-parameters dashboard-id)
+ :resolved-params)
+ dashboard-params (set (keys resolved-params))]
+ ;; ordered so the notifications go out in a stable order rather than whatever order the rows come back in
+ (->> (pulse.db/unarchived-pulses-for-dashboard dashboard-id)
+ (keep (fn [{:keys [parameters] :as pulse}]
+ (let [bad-params (filterv
+ (fn [{param-id :id}] (not (contains? dashboard-params param-id)))
+ parameters)]
+ (when (seq bad-params)
+ (assoc pulse :parameters bad-params)))))
+ seq))))
+
+(defn- broken-subscription-data
+ "Given a dashboard id and original parameters, return data (if any) on any broken subscriptions. This will be a seq
+ of maps, each containing:
+ - The pulse id that was broken
+ - name and email data for the dashboard creator and pulse creator
+ - Affected recipient information
+ - Basic descriptive data on the affected dashboard, pulse, and parameters for use in downstream notifications"
+ [dashboard-id original-dashboard-params]
+ (when-some [broken-pulses (broken-pulses dashboard-id original-dashboard-params)]
+ (let [{dashboard-name :name
+ dashboard-description :description
+ dashboard-creator :creator} (t2/hydrate
+ (pulse.db/dashboard-name-description-creator dashboard-id)
+ :creator)]
+ (for [broken-pulse broken-pulses]
+ (assoc
+ (bad-pulse-notification-data broken-pulse)
+ :dashboard-id dashboard-id
+ :dashboard-name dashboard-name
+ :dashboard-description dashboard-description
+ :dashboard-creator (select-keys dashboard-creator [:first_name :last_name :email :common_name])
+ ;; We will not include links to Metabase for subscriptions created in modular embeddings
+ :disable_links (:disable_links broken-pulse))))))
+
+(defn handle-broken-subscriptions!
+ "Archive every subscription on `dashboard-id` whose parameters no longer exist on the dashboard
+ and notify their creators. Must run after the update: it compares the dashboard's current
+ resolved params against each pulse's stored params. Returns nil."
+ [dashboard-id original-dashboard-params]
+ (doseq [{:keys [pulse-id] :as broken-subscription}
+ (broken-subscription-data dashboard-id original-dashboard-params)]
+ ;; Archive the pulse
+ (pulse/update-pulse! {:id pulse-id :archived true})
+ ;; Let the pulse and subscription creator know about the broken pulse
+ (messages/send-broken-subscription-notification! broken-subscription)))
diff --git a/src/metabase/pulse/db.clj b/src/metabase/pulse/db.clj
index 167333d29ed..01f0f7a90b6 100644
--- a/src/metabase/pulse/db.clj
+++ b/src/metabase/pulse/db.clj
@@ -398,3 +398,38 @@
"A map of User ID to `:tenant_id` for `user-ids`."
[user-ids :- [:set ::lib.schema.id/user]]
(t2/select-pk->fn :tenant_id :model/User :id [:in user-ids]))
+
+(defn user-name-and-email
+ "The first name, last name, and email of the User with `user-id`, or nil."
+ [user-id]
+ (t2/select-one [:model/User :first_name :last_name :email] user-id))
+
+(defn users-names-and-emails
+ "The first names, last names, and emails of the Users with `user-ids`."
+ [user-ids]
+ (t2/select [:model/User :first_name :last_name :email] :id [:in user-ids]))
+
+(defn pulse-channel-kinds-for-pulse
+ "The id, channel type, and details of the PulseChannels of the Pulse with `pulse-id`."
+ [pulse-id]
+ (t2/select [:model/PulseChannel :id :channel_type :details] :pulse_id [:= pulse-id]))
+
+(defn pulse-channel-recipient-rows
+ "The `:user_id` rows of the PulseChannelRecipients of the PulseChannel with `channel-id`."
+ [channel-id]
+ (t2/select [:model/PulseChannelRecipient :user_id] :pulse_channel_id channel-id))
+
+(defn dashboard-parameters
+ "The id and parameters of the Dashboard with `dashboard-id`, or nil."
+ [dashboard-id]
+ (t2/select-one [:model/Dashboard :id :parameters] dashboard-id))
+
+(defn dashboard-name-description-creator
+ "The name, description, and creator id of the Dashboard with `dashboard-id`, or nil."
+ [dashboard-id]
+ (t2/select-one [:model/Dashboard :name :description :creator_id] dashboard-id))
+
+(defn unarchived-pulses-for-dashboard
+ "The unarchived Pulses of the Dashboard with `dashboard-id`, in id order."
+ [dashboard-id]
+ (t2/select :model/Pulse :dashboard_id dashboard-id :archived false {:order-by [[:id :asc]]}))
diff --git a/src/metabase/queries/card_write_checks.clj b/src/metabase/queries/card_write_checks.clj
new file mode 100644
index 00000000000..16c860a361a
--- /dev/null
+++ b/src/metabase/queries/card_write_checks.clj
@@ -0,0 +1,130 @@
+(ns metabase.queries.card-write-checks
+ "The pre-write permission and validation check stack for creating and updating cards. Extracted
+ from the REST card endpoints so the REST API and the MCP `question_write` tool run the exact
+ same checks and can't drift apart."
+ (:require
+ [metabase.api.common :as api]
+ [metabase.collections.models.collection :as collection]
+ [metabase.embedding.validation :as embedding.validation]
+ [metabase.lib-be.schema :as lib-be.schema]
+ [metabase.lib.core :as lib]
+ [metabase.queries.db :as queries.db]
+ [metabase.queries.schema :as queries.schema]
+ [metabase.query-permissions.core :as query-perms]
+ [metabase.util.i18n :refer [tru]]
+ [metabase.util.malli :as mu]))
+
+(set! *warn-on-reflection* true)
+
+(mu/defn check-card-can-be-saved!
+ "Throw a 400 when a `:metric` card's `dataset-query` can't be saved. No-op for other card types."
+ [dataset-query :- [:maybe ::lib-be.schema/maybe-legacy-query]
+ card-type :- [:maybe ::queries.schema/card.type]]
+ (when (and (seq dataset-query) (= card-type :metric))
+ (when-not (lib/can-save? dataset-query card-type)
+ (throw (ex-info (tru "Card of type {0} is invalid, cannot be saved." (name card-type))
+ {:type card-type
+ :status-code 400})))))
+
+(defn check-no-save-cycle!
+ "Run [[metabase.lib.core/check-card-overwrite]] for `card-id`/`query` (cycle detection),
+ re-throwing its error as a 400. Pass `:metabase.queries.card-write-checks/no-id` for `card-id`
+ on create."
+ [card-id query]
+ (try
+ (lib/check-card-overwrite card-id query)
+ (catch clojure.lang.ExceptionInfo e
+ (throw (ex-info (ex-message e) (assoc (ex-data e) :status-code 400))))))
+
+(defn actual-collection-id
+ "The `collection_id` a card will actually be placed in, given a create/update body. A dashboard
+ question's collection is inferred from its `dashboard_id`; if both are given they must match."
+ [body]
+ (let [[_ collection-id :as specified-collection-id?] (find body :collection_id)
+ ;; unlike collection_id, `dashboard_id=null` isn't different than not specifying it at all.
+ dashboard-id (:dashboard_id body)]
+ (cond
+ ;; you specified both - they must match
+ (and specified-collection-id? dashboard-id)
+ (let [dashboard-collection-id (queries.db/dashboard-collection-id dashboard-id)]
+ (api/check-400 (= collection-id dashboard-collection-id)
+ (tru "Mismatch detected between Dashboard''s `collection_id` ({0}) and `collection_id` ({1})"
+ dashboard-collection-id
+ collection-id))
+ collection-id)
+
+ specified-collection-id? collection-id
+
+ dashboard-id (queries.db/dashboard-collection-id dashboard-id)
+
+ :else nil)))
+
+(defn- check-allowed-to-remove-from-existing-dashboards [card]
+ (let [dashboards (queries.db/card-dashboards card)]
+ (doseq [dashboard dashboards]
+ (api/write-check dashboard))))
+
+(mu/defn- check-allowed-to-modify-query
+ "If the query is being modified, check that we have data permissions to run the query."
+ [card-before-updates :- ::queries.schema/card
+ card-updates :- ::queries.schema/card]
+ (when (api/column-will-change? :dataset_query card-before-updates card-updates)
+ (query-perms/check-run-permissions-for-query (dissoc (:dataset_query card-updates) :query-permissions/perms))))
+
+(defn- check-allowed-to-change-embedding
+ "You must be a superuser to change the value of `enable_embedding`, `embedding_type` or `embedding_params`. Embedding must be
+ enabled."
+ [card-before-updates card-updates]
+ (when (or (api/column-will-change? :enable_embedding card-before-updates card-updates)
+ (api/column-will-change? :embedding_type card-before-updates card-updates)
+ (api/column-will-change? :embedding_params card-before-updates card-updates))
+ (embedding.validation/check-embedding-enabled)
+ (api/check-superuser)))
+
+(mu/defn- check-allowed-to-move
+ [card-before-update :- ::queries.schema/card
+ card-updates :- ::queries.schema/card]
+ (when (api/column-will-change? :dashboard_id card-before-update card-updates)
+ (check-allowed-to-remove-from-existing-dashboards card-before-update))
+ (collection/check-allowed-to-change-collection card-before-update card-updates))
+
+(mu/defn- check-update-result-metadata-data-perms
+ [card-before-updates :- ::queries.schema/card
+ card-updates :- ::queries.schema/card]
+ (when (api/column-will-change? :result_metadata card-before-updates card-updates)
+ (let [database-id (some :database_id [card-before-updates card-updates])
+ result-metadata (:result_metadata card-updates)]
+ (query-perms/check-result-metadata-data-perms database-id result-metadata))))
+
+(defn check-allowed-to-run-query!
+ "Throw unless the current user has data permission to run `query`."
+ [query]
+ ;; Strip :query-permissions/perms first -- it is populated internally by the QP middleware, so
+ ;; any value already on the incoming query is dropped here.
+ (query-perms/check-run-permissions-for-query (dissoc query :query-permissions/perms)))
+
+(defn check-allowed-to-create-card!
+ "The full pre-write permission/validation stack for creating a card, mirroring `POST /api/card`.
+ `card` is the create body (with `:dataset_query`, and `:collection_id` and/or `:dashboard_id`);
+ `card-type` its keyword type. Runs run-permissions on the query, create-permission on the
+ target collection, and cycle detection. Throws on any failure."
+ [card card-type]
+ (let [query (:dataset_query card)]
+ (check-card-can-be-saved! query card-type)
+ (check-allowed-to-run-query! query)
+ ;; if a `dashboard-id` is specified, check permissions on the *dashboard's* collection ID.
+ (api/create-check :model/Card {:collection_id (actual-collection-id card)})
+ (check-no-save-cycle! ::no-id query)))
+
+(mu/defn check-allowed-to-update-card!
+ "The post-write permission/validation stack for updating a card, mirroring `PUT /api/card/:id`.
+ Run *after* the card's write-check: `card-before-update` is the existing card, `card-updates`
+ the patch (after [[metabase.api.common/updates-with-archived-directly]]). Checks
+ result-metadata data perms, collection/dashboard moves, query-run perms, and embedding changes."
+ [card-before-update :- ::queries.schema/card
+ card-updates :- ::queries.schema/card]
+ (doseq [f [check-update-result-metadata-data-perms
+ check-allowed-to-move
+ check-allowed-to-modify-query
+ check-allowed-to-change-embedding]]
+ (f card-before-update card-updates)))
diff --git a/src/metabase/queries/core.clj b/src/metabase/queries/core.clj
index 5bcbb3110ae..3fcadc1ad7e 100644
--- a/src/metabase/queries/core.clj
+++ b/src/metabase/queries/core.clj
@@ -2,6 +2,7 @@
(:require
[metabase.queries.cached-result]
[metabase.queries.card]
+ [metabase.queries.card-write-checks]
[metabase.queries.metadata]
[metabase.queries.models.card]
[metabase.queries.models.card.metadata]
@@ -13,6 +14,7 @@
(comment metabase.queries.cached-result/keep-me
metabase.queries.card/keep-me
+ metabase.queries.card-write-checks/keep-me
metabase.queries.metadata/keep-me
metabase.queries.models.card/keep-me
metabase.queries.models.card.metadata/keep-me
@@ -28,6 +30,13 @@
card-param-remapped-value]
[metabase.queries.models.card
create-card!]
+ [metabase.queries.card-write-checks
+ actual-collection-id
+ check-allowed-to-create-card!
+ check-allowed-to-run-query!
+ check-allowed-to-update-card!
+ check-card-can-be-saved!
+ check-no-save-cycle!]
[metabase.queries.metadata
batch-fetch-card-metadata
;; TODO does this belong here, or in the `dashboards` module?
@@ -45,6 +54,7 @@
visible-metric-cards-where-clause]
[metabase.queries.models.card.metadata
infer-metadata
+ infer-metadata-with-model-overrides
maybe-async-result-metadata
refresh-metadata
save-metadata-async!]
diff --git a/src/metabase/queries/db.clj b/src/metabase/queries/db.clj
index 8b345243485..5f3b8f9e9ee 100644
--- a/src/metabase/queries/db.clj
+++ b/src/metabase/queries/db.clj
@@ -166,6 +166,12 @@
[:in :card_id card-ids]]
:group-by [:card_id]}))
+(defn card-dashboards
+ "The Dashboards `card` appears in, hydrating `:in_dashboards` unless it is already present."
+ [card]
+ (or (:in_dashboards card)
+ (:in_dashboards (t2/hydrate card :in_dashboards))))
+
(mu/defn dashboards-for-cards
"Rows of `:card_id` plus Dashboard columns for every Dashboard each of `card-ids` appears on, directly or as a series."
[card-ids :- [:sequential ::lib.schema.id/card]]
diff --git a/src/metabase/queries_rest/api/card.clj b/src/metabase/queries_rest/api/card.clj
index c91c8ce904a..6d7fdbb5240 100644
--- a/src/metabase/queries_rest/api/card.clj
+++ b/src/metabase/queries_rest/api/card.clj
@@ -240,12 +240,6 @@
(cond-> query
(seq query) lib/->legacy-MBQL))))))
-(defn- check-allowed-to-remove-from-existing-dashboards [card]
- (let [dashboards (or (:in_dashboards card)
- (:in_dashboards (t2/hydrate card :in_dashboards)))]
- (doseq [dashboard dashboards]
- (api/write-check dashboard))))
-
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
;;
@@ -443,42 +437,6 @@
;;; ------------------------------------------------- Creating Cards -------------------------------------------------
-(mu/defn- check-if-card-can-be-saved
- [dataset-query :- [:maybe ::lib-be.schema/maybe-legacy-query]
- card-type :- [:maybe ::queries.schema/card.type]]
- (when (and (seq dataset-query) (= card-type :metric))
- (when-not (lib/can-save? dataset-query card-type)
- (throw (ex-info (tru "Card of type {0} is invalid, cannot be saved." (name card-type))
- {:type card-type
- :status-code 400})))))
-
-(defn- actual-collection-id
- "Given a body from the `POST` endpoint to create a card, returns the `collection_id` that the card will be placed in.
- Because creating a Dashboard Question does not require specifying a `collection_id` (it's inferred from the
- `dashboard_id`), this may be different from the `collection_id`. Normally if you don't specify a `collection_id`
- that means we put it in the root collection (`nil` id), but if you specify a `dashboard_id` we'll need to look it
- up."
- [body]
- (let [[_ collection-id :as specified-collection-id?] (find body :collection_id)
- ;; unlike collection_id, `dashboard_id=null` isn't different than not specifying it at all.
- dashboard-id (:dashboard_id body)
- dashboard-id->collection-id queries-rest.db/dashboard-collection-id]
- (cond
- ;; you specified both - they must match
- (and specified-collection-id? dashboard-id)
- (let [dashboard-collection-id (dashboard-id->collection-id dashboard-id)]
- (api/check-400 (= collection-id dashboard-collection-id)
- (tru "Mismatch detected between Dashboard''s `collection_id` ({0}) and `collection_id` ({1})"
- dashboard-collection-id
- collection-id))
- collection-id)
-
- specified-collection-id? collection-id
-
- dashboard-id (dashboard-id->collection-id dashboard-id)
-
- :else nil)))
-
(def ^:private CardCreateSchema
"Schema for creating a new card"
[:map {:closed true}
@@ -525,19 +483,13 @@
(some? collection-id)
(update :collection_id #(eid-translation/->id-or-404 :collection %)))
query (:dataset_query card)]
- (check-if-card-can-be-saved query card-type)
+ ;; Parameter permissions run BEFORE the create stack: the parameter-specific 403 names neither
+ ;; the table nor its ids, while the generic run-permissions error carries the query (and its
+ ;; :source-table) in ex-data. Reversing these leaks that through the parameter path.
(check-parameter-permissions (:parameters card) query)
- ;; check that we have permissions to run the query that we're trying to save.
- ;; Strip :query-permissions/perms first -- it is populated internally by the QP
- ;; middleware, so any value already on the incoming query is dropped here.
- (query-perms/check-run-permissions-for-query (dissoc query :query-permissions/perms))
- ;; check that we have permissions for the collection we're trying to save this card to, if applicable.
- ;; if a `dashboard-id` is specified, check permissions on the *dashboard's* collection ID.
- (api/create-check :model/Card {:collection_id (actual-collection-id card)})
- (try
- (lib/check-card-overwrite ::no-id query)
- (catch clojure.lang.ExceptionInfo e
- (throw (ex-info (ex-message e) (assoc (ex-data e) :status-code 400)))))
+ ;; The full create stack (can-be-saved, run-permissions, collection create-check, cycle
+ ;; detection) lives in `queries` so MCP's question_write runs the identical checks.
+ (queries/check-allowed-to-create-card! card card-type)
(let [created-card (queries/create-card! card @api/*current-user*)]
(when (and (some? (:result_metadata card))
(= (name (:type created-card)) "question"))
@@ -566,38 +518,6 @@
;;; ------------------------------------------------- Updating Cards -------------------------------------------------
-(mu/defn- check-allowed-to-modify-query
- "If the query is being modified, check that we have data permissions to run the query."
- [card-before-updates :- ::queries.schema/card
- card-updates :- ::queries.schema/card]
- (when (api/column-will-change? :dataset_query card-before-updates card-updates)
- (query-perms/check-run-permissions-for-query (dissoc (:dataset_query card-updates) :query-permissions/perms))))
-
-(defn- check-allowed-to-change-embedding
- "You must be a superuser to change the value of `enable_embedding`, `embedding_type` or `embedding_params`. Embedding must be
- enabled."
- [card-before-updates card-updates]
- (when (or (api/column-will-change? :enable_embedding card-before-updates card-updates)
- (api/column-will-change? :embedding_type card-before-updates card-updates)
- (api/column-will-change? :embedding_params card-before-updates card-updates))
- (embedding.validation/check-embedding-enabled)
- (api/check-superuser)))
-
-(mu/defn- check-allowed-to-move
- [card-before-update :- ::queries.schema/card
- card-updates :- ::queries.schema/card]
- (when (api/column-will-change? :dashboard_id card-before-update card-updates)
- (check-allowed-to-remove-from-existing-dashboards card-before-update))
- (collection/check-allowed-to-change-collection card-before-update card-updates))
-
-(mu/defn- check-update-result-metadata-data-perms
- [card-before-updates :- ::queries.schema/card
- card-updates :- ::queries.schema/card]
- (when (api/column-will-change? :result_metadata card-before-updates card-updates)
- (let [database-id (some :database_id [card-before-updates card-updates])
- result-metadata (:result_metadata card-updates)]
- (query-perms/check-result-metadata-data-perms database-id result-metadata))))
-
;;; TODO -- merge this into `:metabase.queries.schema/card`
(def ^:private CardUpdateSchema
[:map {:closed true}
@@ -628,7 +548,7 @@
[card-before-update card-updates]
(let [collection-id (when (or (contains? card-updates :collection_id)
(contains? card-updates :dashboard_id))
- (actual-collection-id card-updates))]
+ (queries/actual-collection-id card-updates))]
(cond-> card-updates
(or (api/column-will-change? :dashboard_id card-before-update card-updates)
(api/column-will-change? :collection_id card-before-update card-updates))
@@ -640,27 +560,20 @@
{metadata :result_metadata, card-type :type, :as card-updates} :- CardUpdateSchema
delete-old-dashcards? :- :boolean]
(let [query (:dataset_query card-updates)]
- (check-if-card-can-be-saved query card-type)
+ (queries/check-card-can-be-saved! query card-type)
(check-parameter-permissions (:parameters card-updates)
(or query (queries-rest.db/card-query id)))
(when-some [query (:dataset_query card-updates)]
- (try
- (lib/check-card-overwrite id query)
- (catch clojure.lang.ExceptionInfo e
- (throw (ex-info (ex-message e) (assoc (ex-data e) :status-code 400))))))
- (let [card-before-update (t2/hydrate (api/write-check :model/Card id) [:moderation_reviews :moderator_details])
+ (queries/check-no-save-cycle! id query))
+ (let [card-before-update (t2/hydrate (api/write-check :model/Card id)
+ [:moderation_reviews :moderator_details])
card-updates (maybe-populate-collection-id
card-before-update
(api/updates-with-archived-directly card-before-update card-updates))
is-model-after-update? (if (nil? card-type)
(queries/model? card-before-update)
(queries/model? card-updates))]
- ;; Do various permissions checks
- (doseq [f [check-update-result-metadata-data-perms
- check-allowed-to-move
- check-allowed-to-modify-query
- check-allowed-to-change-embedding]]
- (f card-before-update card-updates))
+ (queries/check-allowed-to-update-card! card-before-update card-updates)
(let [{:keys [metadata metadata-future]} (queries/maybe-async-result-metadata
{:original-query (:dataset_query card-before-update)
:query query
diff --git a/src/metabase/query_processor/middleware/measures.clj b/src/metabase/query_processor/middleware/measures.clj
index 2b0d49145b8..0527edb8eb9 100644
--- a/src/metabase/query_processor/middleware/measures.clj
+++ b/src/metabase/query_processor/middleware/measures.clj
@@ -89,9 +89,9 @@
{:type qp.error-type/invalid-measure, :measure measure}))
:else (do
(log/debugf "Expanding measure %d" id)
- ;; Preserve :lib/uuid and :display-name from the measure clause options if present
- ;; This is important so that :aggregation refs pointing to the measure remain valid
- (lib.options/update-options aggregation merge (select-keys opts [:lib/uuid :display-name]))))))
+ ;; Preserve :lib/uuid so that :aggregation refs pointing to the measure remain valid, and the
+ ;; caller-supplied names so the expansion keeps the column name the caller asked for.
+ (lib.options/update-options aggregation merge (select-keys opts [:lib/uuid :name :display-name]))))))
(mu/defn- expand-measures-once :- ::lib.schema/query
"Expand all :measure clauses in the query (single pass)."
diff --git a/src/metabase/segments/api.clj b/src/metabase/segments/api.clj
index deb7b83adf8..5733e6cf1df 100644
--- a/src/metabase/segments/api.clj
+++ b/src/metabase/segments/api.clj
@@ -35,15 +35,11 @@
table-id))))
(tru "Segment definition must specify a source table.")))
-#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
-(api.macros/defendpoint :post "/"
- "Create a new `Segment`. The Segment's table is derived from its `definition`."
- [_route-params
- _query-params
- {:keys [name description definition], :as body} :- [:map {:closed true}
- [:name ms/NonBlankString]
- [:definition ::segments.schema/definition]
- [:description {:optional true} [:maybe :string]]]]
+(defn create-segment!
+ "Create-check and insert a new Segment whose table is derived from its `definition`; publishes
+ `:event/segment-create` and returns the hydrated Segment. The shared domain create path, so
+ the create-check runs wherever a Segment is authored."
+ [{:keys [name description definition], :as body}]
;; TODO - why can't we set other properties like `show_in_getting_started` when we create the Segment?
(let [table-id (definition-table-id definition)]
(api/create-check :model/Segment (assoc body :table_id table-id))
@@ -52,6 +48,17 @@
(events/publish-event! :event/segment-create {:object segment :user-id api/*current-user-id*})
(t2/hydrate segment :creator))))
+#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}
+(api.macros/defendpoint :post "/"
+ "Create a new `Segment`. The Segment's table is derived from its `definition`."
+ [_route-params
+ _query-params
+ body :- [:map {:closed true}
+ [:name ms/NonBlankString]
+ [:definition ::segments.schema/definition]
+ [:description {:optional true} [:maybe :string]]]]
+ (create-segment! body))
+
(mu/defn- hydrated-segment [id :- ms/PositiveInt]
(-> (api/read-check (segments.db/segment id))
(t2/hydrate :creator)))
@@ -81,9 +88,10 @@
(-> (filterv mi/can-read? segments)
(t2/hydrate :creator :definition_description))))
-(defn- write-check-and-update-segment!
+(defn write-check-and-update-segment!
"Check whether current user has write permissions, then update Segment with values in `body`. Publishes appropriate
- event and returns updated/hydrated Segment."
+ event and returns updated/hydrated Segment. The shared domain update path, so the write-check runs
+ wherever a Segment is edited."
[id {:keys [revision_message], :as body}]
(let [existing (api/write-check :model/Segment id)
clean-body (u/select-keys-when body
diff --git a/src/metabase/segments/schema.clj b/src/metabase/segments/schema.clj
index bcb3bd140cb..23ee5c5be07 100644
--- a/src/metabase/segments/schema.clj
+++ b/src/metabase/segments/schema.clj
@@ -14,7 +14,7 @@
[:and
::lib-be.schema/maybe-legacy-query
[:fn
- {:error/message (deferred-tru "a segment definition must be a single-stage query with a source table and filters, and without joins, expressions, breakouts, aggregations, fields, order by, or limit")}
+ {:error/fn (fn [_ _] (str (deferred-tru "a segment definition must be a single-stage query with a source table and filters, and without joins, expressions, breakouts, aggregations, fields, order by, or limit")))}
(fn [query]
(and (= (lib/stage-count query) 1)
(some? (lib/primary-source-table-id query))
diff --git a/src/metabase/server/middleware/security.clj b/src/metabase/server/middleware/security.clj
index ddd01a27ba0..cb56b3879fd 100644
--- a/src/metabase/server/middleware/security.clj
+++ b/src/metabase/server/middleware/security.clj
@@ -569,7 +569,7 @@
[request]
(second (re-matches data-app-slug-regex (:uri request))))
-(defn- site-origin
+(defn site-origin
"This Metabase instance's origin as `{:protocol :domain :port}` (parsed from
`site-url`), or nil. Matches the shape [[parse-url]] returns so origins compare
with `=`."
diff --git a/src/metabase/server/middleware/session.clj b/src/metabase/server/middleware/session.clj
index 5e3712da456..3f0fd31997f 100644
--- a/src/metabase/server/middleware/session.clj
+++ b/src/metabase/server/middleware/session.clj
@@ -195,31 +195,38 @@
(m/update-existing :is-group-manager? boolean)
(assoc :token-scopes (oauth-token->token-scopes scopes)))))))
-(def ^:private mcp-ui-request-surface
- "The complete API surface used by the MCP visualization iframe. A UI credential
- is deliberately not a general Metabase API credential."
- #{[:get "/api/user/current"]
- [:get "/api/session/properties"]
- [:post "/api/dataset"]
- [:post "/api/dataset/pivot"]
- [:post "/api/dataset/query_metadata"]
- [:post "/api/dataset/parameter/remapping"]
- [:post "/api/embed-mcp/drills"]
- [:post "/api/embed-mcp/feedback"]})
-
(defn- current-user-info-for-mcp-ui-credential
"Resolve the short-lived credential from an MCP App tool result.
- Accept it only for [[mcp-ui-request-surface]]."
+
+ Two gates, both owned by [[metabase.mcp.ui-surface/request-surface]]. The first decides whether the
+ credential authenticates this route at all; a route off the surface is not authenticated, and the request
+ falls through as anonymous. The second decides whether the scopes the minting MCP session actually held —
+ carried on the credential as a signed claim — cover what the route costs.
+
+ `::scope/mcp-ui`, NOT `::scope/unrestricted`: the surface decides which routes the credential may pass
+ through, and it must not also decide what privilege it arrives with. Stamped unrestricted, a credential
+ that reached anything off the surface arrived with full session privilege. `::mcp-ui` satisfies no
+ endpoint's declared `:scope`.
+
+ `:token-scopes-checked` is what lets those routes serve the credential at all: they declare no `:scope` of
+ their own, and annotating them would push MCP vocabulary into `session` and `query-processor`. It is set
+ only when the second gate passes, so a route added to the surface without a scope decision, or reached by
+ a routing change, is refused by `ensure-scopes-checked` rather than served.
+
+ Both keys are needed, and the stamp is the easy one to mistake for decoration now that the gate computes
+ the decision on its own: `ensure-scopes-checked` passes anything whose `:token-scopes` is nil. Drop the
+ stamp and an unsatisfied route is served rather than refused. `dataset-routes-cost-the-query-scope-test`
+ is what catches that."
[request]
(when (and (init-status/complete?)
- (contains? mcp-ui-request-surface [(:request-method request) (:uri request)]))
+ (mcp/ui-credential-on-surface? (:request-method request) (:uri request)))
(when-let [{:keys [uid sid] :as claims}
(mcp/resolve-ui-credential (get-in request [:headers "x-metabase-mcp-ui-auth"]))]
(some-> (server.db/oauth-user-info uid (premium-features/enable-advanced-permissions?))
(m/update-existing :is-group-manager? boolean)
- ;; Endpoint scope middleware treats this as session-like auth, but the
- ;; route allowlist above is the actual authorization boundary.
- (assoc :token-scopes #{::scope/unrestricted}
+ (assoc :token-scopes #{::scope/mcp-ui}
+ :token-scopes-checked (mcp/ui-credential-scope-satisfied?
+ (:request-method request) (:uri request) claims)
:mcp-ui-session-id sid
:mcp-ui-credential claims)))))
diff --git a/src/metabase/transforms/core.clj b/src/metabase/transforms/core.clj
index cc453bfbffa..1aa17b7ffa6 100644
--- a/src/metabase/transforms/core.clj
+++ b/src/metabase/transforms/core.clj
@@ -35,6 +35,7 @@
output-table
python-transform?
query-transform?
+ target-table-exists?
transform-source-database
transform-source-type]
[metabase.transforms.util
diff --git a/src/metabase/warehouse_schema/db.clj b/src/metabase/warehouse_schema/db.clj
index f8704c65bf9..ee93b828fd2 100644
--- a/src/metabase/warehouse_schema/db.clj
+++ b/src/metabase/warehouse_schema/db.clj
@@ -310,6 +310,42 @@
changes :- (mut/select-keys ::warehouse-schema.schema/table.update [:field_order])]
(t2/update! :model/Table table-id changes))
+(defn active-tables-for-database
+ "The active Tables of the Database with `database-id`."
+ [database-id]
+ (t2/select :model/Table :db_id database-id :active true))
+
+(defn active-table-schemas
+ "The distinct schemas of the active Tables of the Database with `database-id`, in schema order. When
+ `include-hidden?` is false, restricted to Tables with no `visibility_type` (a non-nil value means the Table is
+ hidden -- see `metabase.warehouse-schema.models.table/visibility-types`)."
+ [database-id include-hidden?]
+ (let [clauses (cond-> []
+ (not include-hidden?) (conj [:= :visibility_type nil]))]
+ (t2/select-fn-set :schema :model/Table :db_id database-id :active true
+ (merge {:order-by [[:%lower.schema :asc]]}
+ (when clauses
+ {:where (into [:and] clauses)})))))
+
+(defn active-tables-in-schema
+ "The active Tables in `schema` of the Database with `database-id`, in display name order."
+ [database-id schema]
+ (t2/select :model/Table
+ :db_id database-id
+ :schema schema
+ :active true
+ {:order-by [[:display_name :asc]]}))
+
+(defn active-visible-tables-in-schema
+ "The active, visible Tables in `schema` of the Database with `database-id`, in display name order."
+ [database-id schema]
+ (t2/select :model/Table
+ :db_id database-id
+ :schema schema
+ :active true
+ :visibility_type nil
+ {:order-by [[:display_name :asc]]}))
+
(mu/defn unarchived-segments-for-tables
"The unarchived Segments of the Tables with `table-ids`, ordered by name."
[table-ids :- [:set ::lib.schema.id/table]]
diff --git a/src/metabase/warehouse_schema/table.clj b/src/metabase/warehouse_schema/table.clj
index 418a6517514..b4c1da16f9e 100644
--- a/src/metabase/warehouse_schema/table.clj
+++ b/src/metabase/warehouse_schema/table.clj
@@ -2,12 +2,15 @@
(:require
[medley.core :as m]
[metabase.api.common :as api]
+ [metabase.classloader.core :as classloader]
+ [metabase.config.core :as config]
[metabase.models.interface :as mi]
[metabase.permissions.core :as perms]
[metabase.premium-features.core :as premium-features :refer [defenterprise]]
[metabase.util :as u]
[metabase.warehouse-schema.db :as warehouse-schema.db]
[metabase.warehouse-schema.models.field-values :as field-values]
+ [metabase.warehouses.core :as warehouses]
[toucan2.core :as t2]))
(set! *warn-on-reflection* true)
@@ -114,6 +117,107 @@
[fields-by-table]
fields-by-table)
+(defenterprise current-user-can-manage-schema-metadata?
+ "Returns a boolean whether the current user has permission to edit table metadata for any tables in the schema.
+ On OSS, this is only available to admins."
+ metabase-enterprise.advanced-permissions.common
+ [_db-id _schema-name]
+ (mi/superuser?))
+
+(defn can-read-schema?
+ "Does the current user have permissions to know the schema with `schema-name` exists? (Do they have permissions to see
+ at least some of its tables?)"
+ [database-id schema-name]
+ (or
+ (contains? #{:query-builder :query-builder-and-native}
+ (perms/schema-permission-for-user api/*current-user-id*
+ :perms/create-queries
+ database-id
+ schema-name))
+ (current-user-can-manage-schema-metadata? database-id schema-name)))
+
+(defn browsable-databases-honeysql-filter
+ "The `:where` predicate selecting the databases a user may browse: excludes stubs (placeholder
+ rows for in-progress database creation) and — unless `:include-analytics?` — the audit
+ database, and restricts to non-router databases unless `:router-database-id` scopes to one
+ router's destinations. The per-user read permission filter is applied separately by the caller.
+
+ Excluding destination databases (`router_database_id` non-null — the same definition as
+ `metabase-enterprise.database-routing.common/is-disallowed-destination-db-access?`) is a
+ security boundary, not a nicety: a destination reached directly bypasses the router that would
+ reroute a user to their own tenant, so a caller with a raw destination id could otherwise read
+ another tenant's data. Keep this in sync with that definition."
+ ([] (browsable-databases-honeysql-filter nil))
+ ([{:keys [include-analytics? router-database-id]}]
+ [:and
+ [:= :is_stub false]
+ (when-not include-analytics?
+ [:= :is_audit false])
+ (if router-database-id
+ [:= :router_database_id router-database-id]
+ [:= :router_database_id nil])]))
+
+(defn database-schemas
+ "Returns a list of all the schemas with tables found for the database `id`. Excludes schemas with no tables."
+ [id {:keys [include-editable-data-model? include-hidden? can-query? can-write-metadata?]}]
+ (let [filter-schemas (fn [schemas]
+ (if include-editable-data-model?
+ (if-let [f (u/ignore-exceptions
+ (classloader/require 'metabase-enterprise.advanced-permissions.common)
+ (resolve 'metabase-enterprise.advanced-permissions.common/filter-schema-by-data-model-perms))]
+ (map :schema (f (map (fn [s] {:db_id id :schema s}) schemas)))
+ schemas)
+ (filter (partial can-read-schema? id) schemas)))
+ ;; For can-query? and can-write-metadata?, we need to filter based on tables in each schema
+ filter-schemas-by-tables (fn [schemas]
+ (if (or can-query? can-write-metadata?)
+ (let [tables (warehouse-schema.db/active-tables-for-database id)
+ _ (perms/prime-table-perms-cache {:db-ids #{id}})
+ filtered-tables (cond->> tables
+ can-query? (filter mi/can-query?)
+ can-write-metadata? (filter mi/can-write?))
+ allowed-schemas (set (map :schema filtered-tables))]
+ (filter #(contains? allowed-schemas %) schemas))
+ schemas))]
+ (warehouses/get-database id {:include-editable-data-model? include-editable-data-model?})
+ (->> (warehouse-schema.db/active-table-schemas id include-hidden?)
+ filter-schemas
+ filter-schemas-by-tables
+ ;; for `nil` schemas return the empty string
+ (map #(if (nil? %) "" %))
+ distinct
+ sort)))
+
+(defn schema-tables-list
+ "Returns the list of Tables in `schema` of the database `db-id` that are visible to the current user, permission-
+ filtered and ordered by `display_name`. Read-checks the database and the schema unless
+ `include-editable-data-model?` routes the filtering through data-model permissions instead."
+ ([db-id schema]
+ (schema-tables-list db-id schema {}))
+ ([db-id schema {:keys [include-hidden? include-editable-data-model? can-query? can-write-metadata? include-measures?]}]
+ (when-not include-editable-data-model?
+ (api/read-check :model/Database db-id)
+ (api/check-403 (can-read-schema? db-id schema)))
+ (let [candidate-tables (if include-hidden?
+ (warehouse-schema.db/active-tables-in-schema db-id schema)
+ (warehouse-schema.db/active-visible-tables-in-schema db-id schema))
+ _ (perms/prime-table-perms-cache {:db-ids #{db-id}})
+ filtered-tables (cond->> (if include-editable-data-model?
+ (if-let [f (when config/ee-available?
+ (classloader/require 'metabase-enterprise.advanced-permissions.common)
+ (resolve 'metabase-enterprise.advanced-permissions.common/filter-tables-by-data-model-perms))]
+ (f candidate-tables)
+ candidate-tables)
+ (filter mi/can-read? candidate-tables))
+ can-query? (filter mi/can-query?)
+ can-write-metadata? (filter mi/can-write?))
+ hydration-keys (cond-> []
+ (premium-features/any-transforms-enabled?) (conj :transform)
+ include-measures? (conj :measures))]
+ (if (seq hydration-keys)
+ (apply t2/hydrate filtered-tables hydration-keys)
+ filtered-tables))))
+
(defn- card-result-metadata->virtual-fields
"Return a sequence of 'virtual' fields metadata for the 'virtual' table for a Card in the Saved Questions 'virtual'
database.
diff --git a/src/metabase/warehouses_rest/api.clj b/src/metabase/warehouses_rest/api.clj
index a127c32fc90..cbad4598b12 100644
--- a/src/metabase/warehouses_rest/api.clj
+++ b/src/metabase/warehouses_rest/api.clj
@@ -21,7 +21,7 @@
[metabase.lib.schema.id :as lib.schema.id]
[metabase.models.interface :as mi]
[metabase.permissions.core :as perms]
- [metabase.premium-features.core :as premium-features :refer [defenterprise]]
+ [metabase.premium-features.core :as premium-features]
[metabase.queries.schema :as queries.schema]
[metabase.request.core :as request]
[metabase.sample-data.core :as sample-data]
@@ -50,11 +50,6 @@
(set! *warn-on-reflection* true)
-;; Forward declaration so `add-schemas` (near the top-of-file helpers) can
-;; reuse the same per-schema permission check used by `/api/database/:id/schemas`
-;; lower in the file.
-(declare can-read-schema?)
-
(def DBEngineString
"Schema for a valid database engine name, e.g. `h2` or `postgres`."
(mu/with-api-error-message
@@ -100,7 +95,7 @@
(let [db-id (:id db)
raw-schemas (get schemas-by-db db-id [])
readable (->> raw-schemas
- (filter (partial can-read-schema? db-id))
+ (filter (partial schema.table/can-read-schema? db-id))
(map #(if (nil? %) "" %))
distinct
sort
@@ -1209,25 +1204,6 @@
;;; ------------------------------------------ GET /api/database/:id/schemas -----------------------------------------
-(defenterprise current-user-can-manage-schema-metadata?
- "Returns a boolean whether the current user has permission to edit table metadata for any tables in the schema.
- On OSS, this is only available to admins."
- metabase-enterprise.advanced-permissions.common
- [_db-id _schema-name]
- (mi/superuser?))
-
-(defn- can-read-schema?
- "Does the current user have permissions to know the schema with `schema-name` exists? (Do they have permissions to see
- at least some of its tables?)"
- [database-id schema-name]
- (or
- (contains? #{:query-builder :query-builder-and-native}
- (perms/schema-permission-for-user api/*current-user-id*
- :perms/create-queries
- database-id
- schema-name))
- (current-user-can-manage-schema-metadata? database-id schema-name)))
-
;; TODO (Cam 10/28/25) -- fix this endpoint route to use kebab-case for consistency with the rest of our REST API
;;
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
@@ -1249,37 +1225,6 @@
(vec)
(sort))))
-(defn database-schemas
- "Returns a list of all the schemas with tables found for the database `id`. Excludes schemas with no tables."
- [id {:keys [include-editable-data-model? include-hidden? can-query? can-write-metadata?]}]
- (let [filter-schemas (fn [schemas]
- (if include-editable-data-model?
- (if-let [f (u/ignore-exceptions
- (classloader/require 'metabase-enterprise.advanced-permissions.common)
- (resolve 'metabase-enterprise.advanced-permissions.common/filter-schema-by-data-model-perms))]
- (map :schema (f (map (fn [s] {:db_id id :schema s}) schemas)))
- schemas)
- (filter (partial can-read-schema? id) schemas)))
- ;; For can-query? and can-write-metadata?, we need to filter based on tables in each schema
- filter-schemas-by-tables (fn [schemas]
- (if (or can-query? can-write-metadata?)
- (let [tables (warehouses-rest.db/active-tables-for-database id)
- _ (perms/prime-table-perms-cache {:db-ids #{id}})
- filtered-tables (cond->> tables
- can-query? (filter mi/can-query?)
- can-write-metadata? (filter mi/can-write?))
- allowed-schemas (set (map :schema filtered-tables))]
- (filter #(contains? allowed-schemas %) schemas))
- schemas))]
- (warehouses/get-database id {:include-editable-data-model? include-editable-data-model?})
- (->> (warehouses-rest.db/active-table-schemas id include-hidden?)
- filter-schemas
- filter-schemas-by-tables
- ;; for `nil` schemas return the empty string
- (map #(if (nil? %) "" %))
- distinct
- sort)))
-
;; TODO (Cam 10/28/25) -- fix this endpoint so it uses kebab-case for query parameters for consistency with the rest
;; of the REST API
;;
@@ -1300,10 +1245,10 @@
[:include_hidden {:default false} [:maybe ms/BooleanValue]]
[:can-query {:optional true} [:maybe :boolean]]
[:can-write-metadata {:optional true} [:maybe :boolean]]]]
- (database-schemas id {:include-editable-data-model? include_editable_data_model
- :include-hidden? include_hidden
- :can-query? can-query
- :can-write-metadata? can-write-metadata}))
+ (schema.table/database-schemas id {:include-editable-data-model? include_editable_data_model
+ :include-hidden? include_hidden
+ :can-query? can-query
+ :can-write-metadata? can-write-metadata}))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -1335,33 +1280,6 @@
;;; ------------------------------------- GET /api/database/:id/schema/:schema ---------------------------------------
-(defn- schema-tables-list
- ([db-id schema]
- (schema-tables-list db-id schema {}))
- ([db-id schema {:keys [include-hidden? include-editable-data-model? can-query? can-write-metadata? include-measures?]}]
- (when-not include-editable-data-model?
- (api/read-check :model/Database db-id)
- (api/check-403 (can-read-schema? db-id schema)))
- (let [candidate-tables (if include-hidden?
- (warehouses-rest.db/active-tables-in-schema db-id schema)
- (warehouses-rest.db/active-visible-tables-in-schema db-id schema))
- _ (perms/prime-table-perms-cache {:db-ids #{db-id}})
- filtered-tables (cond->> (if include-editable-data-model?
- (if-let [f (when config/ee-available?
- (classloader/require 'metabase-enterprise.advanced-permissions.common)
- (resolve 'metabase-enterprise.advanced-permissions.common/filter-tables-by-data-model-perms))]
- (f candidate-tables)
- candidate-tables)
- (filter mi/can-read? candidate-tables))
- can-query? (filter mi/can-query?)
- can-write-metadata? (filter mi/can-write?))
- hydration-keys (cond-> []
- (premium-features/any-transforms-enabled?) (conj :transform)
- include-measures? (conj :measures))]
- (if (seq hydration-keys)
- (apply t2/hydrate filtered-tables hydration-keys)
- filtered-tables))))
-
;; TODO (Cam 10/28/25) -- fix this endpoint so it uses kebab-case for query parameters for consistency with the rest
;; of the REST API
;;
@@ -1389,7 +1307,7 @@
[:can-query {:optional true} [:maybe :boolean]]
[:can-write-metadata {:optional true} [:maybe :boolean]]
[:include_measures {:optional true} [:maybe :boolean]]]]
- (api/check-404 (seq (schema-tables-list
+ (api/check-404 (seq (schema.table/schema-tables-list
id
schema
{:include-hidden? include_hidden
@@ -1430,9 +1348,9 @@
:can-write-metadata? can-write-metadata
:include-measures? include_measures}]
(api/check-404 (seq (if (str/blank? schema)
- (concat (schema-tables-list id nil opts)
- (schema-tables-list id "" opts))
- (schema-tables-list id schema opts))))))
+ (concat (schema.table/schema-tables-list id nil opts)
+ (schema.table/schema-tables-list id "" opts))
+ (schema.table/schema-tables-list id schema opts))))))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
diff --git a/src/metabase/warehouses_rest/db.clj b/src/metabase/warehouses_rest/db.clj
index 0842c03d068..95bdfa42eb7 100644
--- a/src/metabase/warehouses_rest/db.clj
+++ b/src/metabase/warehouses_rest/db.clj
@@ -268,45 +268,6 @@
:right-join [[:metabase_table :t] [:= :f.table_id :t.id]]
:where [:= :t.db_id database-id]}]}))
-(mu/defn active-tables-for-database
- "The active Tables of the Database with `database-id`."
- [database-id :- ::lib.schema.id/database]
- (t2/select :model/Table :db_id database-id :active true))
-
-(mu/defn active-table-schemas
- "The distinct schemas of the active Tables of the Database with `database-id`, in schema order. When
- `include-hidden?` is false, restricted to Tables with no `visibility_type` (a non-nil value means the Table is
- hidden -- see [[metabase.warehouse-schema.models.table/visibility-types]])."
- [database-id :- ::lib.schema.id/database
- include-hidden? :- :boolean]
- (let [clauses (cond-> []
- (not include-hidden?) (conj [:= :visibility_type nil]))]
- (t2/select-fn-set :schema :model/Table :db_id database-id :active true
- (merge {:order-by [[:%lower.schema :asc]]}
- (when clauses
- {:where (into [:and] clauses)})))))
-
-(mu/defn active-tables-in-schema
- "The active Tables in `schema` of the Database with `database-id`, in display name order."
- [database-id :- ::lib.schema.id/database
- schema :- [:maybe :string]]
- (t2/select :model/Table
- :db_id database-id
- :schema schema
- :active true
- {:order-by [[:display_name :asc]]}))
-
-(mu/defn active-visible-tables-in-schema
- "The active, visible Tables in `schema` of the Database with `database-id`, in display name order."
- [database-id :- ::lib.schema.id/database
- schema :- [:maybe :string]]
- (t2/select :model/Table
- :db_id database-id
- :schema schema
- :active true
- :visibility_type nil
- {:order-by [[:display_name :asc]]}))
-
(mu/defn collection-ids-named
"The ids of the Collections named `collection-name`, or nil."
[collection-name :- :string]
diff --git a/src/metabase/xrays/automagic_dashboards/populate.clj b/src/metabase/xrays/automagic_dashboards/populate.clj
index 60f89365997..b341cff9e44 100644
--- a/src/metabase/xrays/automagic_dashboards/populate.clj
+++ b/src/metabase/xrays/automagic_dashboards/populate.clj
@@ -170,7 +170,7 @@
(merge (dashcard-defaults)
{:creator_id api/*current-user-id*
:visualization_settings (merge
- (dashboard-card/virtual-card-settings "text" text)
+ (dashboard-card/virtual-card-settings "text" {:text text})
visualization-settings)
:col y
:row x
diff --git a/test/metabase/agent_api/query_guards_test.clj b/test/metabase/agent_api/query_guards_test.clj
index 3534991f82f..fa899391eb7 100644
--- a/test/metabase/agent_api/query_guards_test.clj
+++ b/test/metabase/agent_api/query_guards_test.clj
@@ -8,7 +8,8 @@
(:require
[clojure.test :refer [are deftest is testing]]
[metabase.agent-api.query-guards :as query-guards]
- [metabase.test :as mt]))
+ [metabase.test :as mt]
+ [metabase.util.json :as json]))
(set! *warn-on-reflection* true)
@@ -105,8 +106,8 @@
(deftest ^:parallel native-query?-is-case-and-separator-insensitive-test
(testing "the QP normalizer canonicalizes keys case-insensitively and treats `_` and `-` alike, so a payload
spelled `:SOURCE_QUERY` still reaches the query processor as a native stage. Matching edge names and
- markers case-exactly let a caller walk straight past the guard by changing the spelling — and once
- `check-mcp-ui-native-query!` is wired onto /api/dataset (the next slice), this scan is the only gate
+ markers case-exactly let a caller walk straight past the guard by changing the spelling — and with
+ `check-mcp-ui-native-query!` wired onto /api/dataset by this slice, this scan is the only gate
standing between an unrestricted-stamped MCP UI credential and raw SQL."
(testing "nested-query edges, however spelled"
(are [q] (true? (query-guards/native-query? q))
@@ -134,6 +135,36 @@
{:stages [{:lib/type "mbql.stage/mbql" :expressions {:NATIVE [:+ 1 1]}}]}
{:query {:source-table 1 :template-tags {:Source_Query {:name "x"}}}}))))
+(deftest ^:parallel native-query?-sees-a-json-encoded-query-test
+ (testing "`POST /api/dataset/:export-format` accepts `query` as a JSON STRING for `<form>`-submit
+ back-compat, decoding it in Malli (`:decode/api`). `+refuse-unscoped-native-sql` runs ahead of that
+ decoding, so the guard is handed the raw string — and a string edge fell through to `deep-scan`,
+ which finds no marker inside text. The guard therefore could not see native SQL in that shape.
+
+ Unreachable today only because that route is absent from the MCP UI credential's allowlist, which
+ is exactly the coupling the middleware's docstring promises does NOT matter: \"a route later added
+ to the allowlist is covered the day it is added\"."
+ (testing "a JSON-encoded query is decoded and scanned, not skipped"
+ (are [q] (true? (query-guards/native-query? q))
+ {:query (json/encode {:type "native" :native {:query "select 1"}})}
+ {:query (json/encode {:query {:source_query {:native "select 1"}}})}
+ {:query (json/encode {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/native" :native "select 1"}]})}))
+ (testing "an encoded MBQL query is still not native"
+ (is (false? (query-guards/native-query? {:query (json/encode {:type "query"
+ :query {:source-table 1}})}))))
+ (testing "sequence edges decode symmetrically, so a JSON-string `stages` cannot become the one shape the
+ scan is blind to"
+ (is (true? (query-guards/native-query?
+ {:stages (json/encode [{:lib/type "mbql.stage/native" :native "select 1"}])})))
+ (is (false? (query-guards/native-query?
+ {:stages (json/encode [{:lib/type "mbql.stage/mbql" :source-table 1}])}))))
+ (testing "a string that is not JSON at all is left to the existing fallback rather than throwing"
+ (are [q] (false? (query-guards/native-query? q))
+ {:query "not json at all"}
+ {:query ""}
+ {:query "[1,2,3]"}))))
+
(deftest reject-native-query!-test
(testing "native queries throw a 400 with a steering message"
(let [query {:stages [{:lib/type :mbql.stage/native :native "SELECT 1"}]}]
diff --git a/test/metabase/api/macros/scope_test.clj b/test/metabase/api/macros/scope_test.clj
index c5f51230e79..b857486f0b2 100644
--- a/test/metabase/api/macros/scope_test.clj
+++ b/test/metabase/api/macros/scope_test.clj
@@ -82,6 +82,26 @@
(invoke-handler (middleware spy-handler) {:token-scopes #{"agent:reports"}})
(is (true? (:token-scopes-checked (deref seen-request 1000 ::timeout)))))))
+(deftest ^:parallel enforce-scope-defers-to-the-mcp-ui-gate-test
+ (let [ok-handler (fn [_request respond _raise]
+ (respond {:status 200 :body "ok"}))
+ middleware (scope/enforce-scope "agent:reports")
+ invoke #(invoke-handler (middleware ok-handler) %)]
+ (testing "an MCP Apps UI credential already cleared by its own route gate passes a declared scope it
+ does not hold — `metabase.mcp.ui-surface/request-surface` is what confines that credential,
+ and it is strictly narrower than any endpoint scope"
+ (is (= {:status 200 :body "ok"}
+ (invoke {:token-scopes #{::scope/mcp-ui} :token-scopes-checked true}))))
+ (testing "without the stamp it is refused — the carve-out defers to the gate's decision, it does not
+ exempt the credential from having one"
+ (is (= 403 (:status (invoke {:token-scopes #{::scope/mcp-ui}}))))
+ (is (= 403 (:status (invoke {:token-scopes #{::scope/mcp-ui} :token-scopes-checked false})))))
+ (testing "and the carve-out does not leak to ordinary scoped tokens. `enforce-scope` stamps
+ `:token-scopes-checked` itself on success, so trusting the stamp alone would make every
+ per-endpoint `:scope` a no-op underneath a namespace-level `enforce-scope`"
+ (is (= 403 (:status (invoke {:token-scopes #{"agent:queries"} :token-scopes-checked true}))))
+ (is (= 403 (:status (invoke {:token-scopes #{} :token-scopes-checked true})))))))
+
(deftest ^:parallel ensure-scopes-checked-test
(let [ok-handler (fn [_request respond _raise]
(respond {:status 200 :body "ok"}))]
diff --git a/test/metabase/app_db/custom_migrations_test.clj b/test/metabase/app_db/custom_migrations_test.clj
index 13fa3c56575..cb14136ed69 100644
--- a/test/metabase/app_db/custom_migrations_test.clj
+++ b/test/metabase/app_db/custom_migrations_test.clj
@@ -3013,3 +3013,76 @@
(is (= "metabase-transform" (:data_source provisional)))
(is (= "computed" (:data_authority provisional)))
(is (= "New Target Table" (:display_name provisional)))))))))
+
+(deftest retire-mcp-v1-oauth-scopes-test
+ (testing (str "v64.2026-09-09T12:00:00/01: a client connected to a shipped v0.60–v0.63 release holds a 17-scope "
+ "registration snapshot and tokens scoped to it. The v2 surface gates on six coarse scopes that no "
+ "legacy scope satisfies, so without this migration the client gets HTTP 200 with an empty tools list "
+ "and never recovers — the refresh grant can only narrow. The migration widens the ceiling so a "
+ "re-authorization validates, then revokes the legacy-shaped tokens so the client actually "
+ "re-authenticates instead of refreshing.")
+ (impl/test-migrations ["v64.2026-09-09T12:00:00" "v64.2026-09-09T12:00:01"] [migrate!]
+ (let [;; The 17 scopes DCR snapshots on v0.63: 15 per-entity agent scopes + 2 mcp-ui resource scopes.
+ legacy-scopes ["agent:sql:construct" "agent:sql:create" "agent:sql:edit" "agent:sql:read"
+ "agent:notebook:create" "agent:query:construct" "agent:query:execute"
+ "agent:question:create" "agent:question:update" "agent:question:execute"
+ "agent:metric:create" "agent:metric:update"
+ "agent:dashboard:create" "agent:dashboard:update" "agent:collection:create"
+ "agent:viz:mcp-ui:query" "agent:viz:mcp-ui:drill-through"]
+ v2-scopes ["agent:content:read" "agent:content:write" "agent:query:run"
+ "agent:sql:run" "agent:delivery:write" "agent:resource:read"]
+ ;; `oauth_access_token.user_id` is a real FK, so the row must exist. Inserted directly rather
+ ;; than via `new-instance-with-default` because this release makes `entity_id` NOT NULL.
+ user-id (t2/insert-returning-pk!
+ :core_user {:first_name "MCP"
+ :last_name "Migration"
+ :email (str (random-uuid) "@metabase.com")
+ :password "irrelevant"
+ :entity_id (subs (str/replace (str (random-uuid)) "-" "") 0 21)
+ :date_joined :%now})
+ insert-client! (fn [client-id registration-type scopes]
+ (t2/insert-returning-pk!
+ :oauth_client {:client_id client-id
+ :client_name "Legacy MCP Client"
+ :redirect_uris (json/encode ["http://localhost/callback"])
+ :grant_types (json/encode ["authorization_code"])
+ :response_types (json/encode ["code"])
+ :scopes (json/encode scopes)
+ :registration_type registration-type
+ :client_type "public"
+ :created_at :%now
+ :updated_at :%now}))
+ insert-token! (fn [table client-id scopes]
+ (t2/insert-returning-pk!
+ table {:token (str (random-uuid))
+ :user_id user-id
+ :client_id client-id
+ :scope (json/encode scopes)
+ :expiry (+ (System/currentTimeMillis) 3600000)
+ :created_at :%now}))
+ dynamic-id (insert-client! "dynamic-legacy" "dynamic" legacy-scopes)
+ static-id (insert-client! "static-legacy" "static" legacy-scopes)
+ legacy-access (insert-token! :oauth_access_token "dynamic-legacy" legacy-scopes)
+ legacy-refresh (insert-token! :oauth_refresh_token "dynamic-legacy" legacy-scopes)
+ ;; A token already minted against the v2 surface — the migration must leave it alone, or upgrading
+ ;; would log out clients that were working.
+ v2-access (insert-token! :oauth_access_token "dynamic-legacy" ["agent:content:read"])
+ v2-refresh (insert-token! :oauth_refresh_token "dynamic-legacy" v2-scopes)
+ scopes-of (fn [table id col]
+ (set (json/decode (get (t2/query-one {:select [col] :from [table] :where [:= :id id]}) col))))
+ revoked? (fn [table id]
+ (some? (:revoked_at (t2/query-one {:select [:revoked_at] :from [table] :where [:= :id id]}))))]
+ (migrate!)
+ (testing "the dynamic client's snapshot gains the six v2 scopes, so a re-authorization validates"
+ (let [scopes (scopes-of :oauth_client dynamic-id :scopes)]
+ (is (every? scopes v2-scopes))
+ (testing "and keeps its legacy scopes — issued tokens carry literal strings, so none may be dropped"
+ (is (every? scopes legacy-scopes)))))
+ (testing "a statically registered client is left alone — it did not snapshot via DCR"
+ (is (= (set legacy-scopes) (scopes-of :oauth_client static-id :scopes))))
+ (testing "legacy-scoped tokens are revoked — both tables, or the client refreshes instead of re-authing"
+ (is (revoked? :oauth_access_token legacy-access))
+ (is (revoked? :oauth_refresh_token legacy-refresh)))
+ (testing "tokens already carrying a v2 tool scope keep working"
+ (is (not (revoked? :oauth_access_token v2-access)))
+ (is (not (revoked? :oauth_refresh_token v2-refresh))))))))
diff --git a/test/metabase/bookmarks/api_test.clj b/test/metabase/bookmarks/api_test.clj
index 6cd32d67c5c..c80f20da11a 100644
--- a/test/metabase/bookmarks/api_test.clj
+++ b/test/metabase/bookmarks/api_test.clj
@@ -2,6 +2,7 @@
"Tests for /api/bookmark endpoints."
(:require
[clojure.test :refer :all]
+ [metabase.bookmarks.db :as bookmarks.db]
[metabase.models.interface :as mi]
[metabase.permissions.core :as perms]
[metabase.test :as mt]
@@ -59,6 +60,36 @@
(is (some #(= (u/the-id card) (:item_id %))
(mt/user-http-request :rasta :get 200 "bookmark"))))))
+(deftest insert-bookmark!-idempotent-test
+ (testing "GHY-4152: insert-bookmark! returns the existing row rather than tripping the (user_id, item)
+ unique constraint, so a caller racing itself gets the state it asked for"
+ (mt/with-temp [:model/Card card {}]
+ (let [user-id (mt/user->id :rasta)
+ card-id (u/the-id card)
+ first! (bookmarks.db/insert-bookmark! "card" card-id user-id)]
+ (is (= (:id first!) (:id (bookmarks.db/insert-bookmark! "card" card-id user-id))))
+ (is (= 1 (t2/count :model/CardBookmark :card_id card-id :user_id user-id)))))))
+
+(deftest unknown-bookmark-model-test
+ (testing "GHY-4152: bookmark-exists?, insert-bookmark!, and delete-bookmark! all fail the same way for a model
+ string none of them recognize, now that metabase.bookmarks.db is module API and can be reached
+ directly by callers the REST/MCP schemas don't validate"
+ (let [user-id (mt/user->id :rasta)]
+ (doseq [[label thunk] [["bookmark-exists?" #(bookmarks.db/bookmark-exists? "bogus" 1 user-id)]
+ ["insert-bookmark!" #(bookmarks.db/insert-bookmark! "bogus" 1 user-id)]
+ ["delete-bookmark!" #(bookmarks.db/delete-bookmark! "bogus" 1 user-id)]]]
+ (testing label
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Unknown bookmarkable model" (thunk))))))))
+
+(deftest duplicate-bookmark-post-returns-400-test
+ (testing "GHY-4152: POST /api/bookmark/:model/:id returns 400 \"Bookmark already exists\" on a duplicate request.
+ Regression guard for the insert-bookmark! swap from t2/insert-returning-instance! to
+ mdb/select-or-insert!, which could silently succeed on a duplicate instead of 400ing."
+ (mt/with-temp [:model/Card card {}]
+ (mt/user-http-request :rasta :post 200 (str "bookmark/card/" (u/the-id card)))
+ (is (= "Bookmark already exists"
+ (mt/user-http-request :rasta :post 400 (str "bookmark/card/" (u/the-id card))))))))
+
(deftest bookmark-requires-only-read-perms-test
(testing "POST /api/bookmark/card/:id succeeds for a read-only (collection-read) user"
(mt/with-non-admin-groups-no-root-collection-perms
diff --git a/test/metabase/collections_rest/api_test.clj b/test/metabase/collections_rest/api_test.clj
index 2b995d4a113..3d524948dc3 100644
--- a/test/metabase/collections_rest/api_test.clj
+++ b/test/metabase/collections_rest/api_test.clj
@@ -6,8 +6,7 @@
[clojure.string :as str]
[clojure.test :refer :all]
[metabase.app-db.core :as mdb]
- [metabase.collections-rest.api :as api.collection]
- [metabase.collections-rest.children-query :as children-query]
+ [metabase.collections.children :as collections.children]
[metabase.collections.models.collection :as collection]
[metabase.collections.models.collection-test :as collection-test]
[metabase.collections.test-utils :refer [personal-collection with-library-not-synced without-library]]
@@ -361,11 +360,11 @@
ids (set (map :id (cons personal-collection [a b c d e f g])))]
(mt/with-test-user :crowberto
(testing "Make sure we get the expected collections when collection-id is nil"
- (let [collections (#'api.collection/select-collections {:archived false
- :exclude-other-user-collections false
- :namespaces #{nil}
- :shallow true
- :permissions-set #{"/"}})]
+ (let [collections (collections.children/select-collections {:archived false
+ :exclude-other-user-collections false
+ :namespaces #{nil}
+ :shallow true
+ :permissions-set #{"/"}})]
(is (= #{{:name "A"}
{:name "B"}
{:name "C"}
@@ -375,12 +374,12 @@
(map #(select-keys % [:name]))
(into #{}))))))
(testing "Make sure we get the expected collections when collection-id is an integer"
- (let [collections (#'api.collection/select-collections {:archived false
- :exclude-other-user-collections false
- :namespaces #{nil}
- :shallow true
- :collection-id (:id a)
- :permissions-set #{"/"}})]
+ (let [collections (collections.children/select-collections {:archived false
+ :exclude-other-user-collections false
+ :namespaces #{nil}
+ :shallow true
+ :collection-id (:id a)
+ :permissions-set #{"/"}})]
;; E & G are too deep to show up
(is (= #{{:name "C"}
{:name "B"}
@@ -390,11 +389,11 @@
(filter (fn [coll] (contains? ids (:id coll))))
(map #(select-keys % [:name]))
(into #{})))))
- (let [collections (#'api.collection/select-collections {:archived false
- :exclude-other-user-collections false
- :shallow true
- :collection-id (:id b)
- :permissions-set #{"/"}})]
+ (let [collections (collections.children/select-collections {:archived false
+ :exclude-other-user-collections false
+ :shallow true
+ :collection-id (:id b)
+ :permissions-set #{"/"}})]
(is (= #{}
(->> collections
(filter (fn [coll] (contains? ids (:id coll))))
@@ -1766,7 +1765,7 @@
[:type :asc :nulls-first]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:official-collections-first? true} app-db))))))
+ (collections.children/children-sort-clause {:official-collections-first? true} app-db))))))
(deftest ^:parallel children-sort-clause-test-2
(testing "Sorting by last-edited-at"
@@ -1776,9 +1775,9 @@
[:last_edit_timestamp :asc]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:sort-column :last-edited-at
- :sort-direction :asc
- :official-collections-first? true} :mysql)))))
+ (collections.children/children-sort-clause {:sort-column :last-edited-at
+ :sort-direction :asc
+ :official-collections-first? true} :mysql)))))
(deftest ^:parallel children-sort-clause-test-2b
(testing "Sorting by last-edited-at"
@@ -1788,9 +1787,9 @@
[:last_edit_timestamp :asc]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:sort-column :last-edited-at
- :sort-direction :asc
- :official-collections-first? true} :postgres)))))
+ (collections.children/children-sort-clause {:sort-column :last-edited-at
+ :sort-direction :asc
+ :official-collections-first? true} :postgres)))))
(deftest ^:parallel children-sort-clause-test-2c
(testing "Sorting by last-edited-by"
@@ -1802,9 +1801,9 @@
[:last_edit_first_name :asc]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:sort-column :last-edited-by
- :sort-direction :asc
- :official-collections-first? true} :postgres)))))
+ (collections.children/children-sort-clause {:sort-column :last-edited-by
+ :sort-direction :asc
+ :official-collections-first? true} :postgres)))))
(deftest ^:parallel children-sort-clause-test-2d
(testing "Sorting by last-edited-by"
@@ -1816,9 +1815,9 @@
[:last_edit_first_name :asc]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:sort-column :last-edited-by
- :sort-direction :asc
- :official-collections-first? true} :mysql)))))
+ (collections.children/children-sort-clause {:sort-column :last-edited-by
+ :sort-direction :asc
+ :official-collections-first? true} :mysql)))))
(deftest ^:parallel children-sort-clause-test-3
(testing "Sorting by model"
@@ -1827,9 +1826,9 @@
[:model_ranking :asc]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:sort-column :model
- :sort-direction :asc
- :official-collections-first? true} :postgres)))))
+ (collections.children/children-sort-clause {:sort-column :model
+ :sort-direction :asc
+ :official-collections-first? true} :postgres)))))
(deftest ^:parallel children-sort-clause-test-3b
(testing "Sorting by model"
@@ -1838,9 +1837,9 @@
[:model_ranking :desc]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:sort-column :model
- :sort-direction :desc
- :official-collections-first? true} :mysql)))))
+ (collections.children/children-sort-clause {:sort-column :model
+ :sort-direction :desc
+ :official-collections-first? true} :mysql)))))
(deftest ^:parallel children-sort-clause-description-test
(testing "Sorting by description"
@@ -1850,18 +1849,18 @@
[:%lower.description :asc :nulls-last]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:sort-column :description
- :sort-direction :asc
- :official-collections-first? true} :postgres))))
+ (collections.children/children-sort-clause {:sort-column :description
+ :sort-direction :asc
+ :official-collections-first? true} :postgres))))
(testing "descending"
(is (= [[:authority_level :asc :nulls-last]
[:type :asc :nulls-first]
[:%lower.description :desc :nulls-last]
[:%lower.name :asc]
[:id :asc]]
- (children-query/children-sort-clause {:sort-column :description
- :sort-direction :desc
- :official-collections-first? true} :postgres))))))
+ (collections.children/children-sort-clause {:sort-column :description
+ :sort-direction :desc
+ :official-collections-first? true} :postgres))))))
(deftest ^:parallel snippet-collection-items-test
(testing "GET /api/collection/:id/items"
@@ -1900,7 +1899,7 @@
(swap! queries conj query))
(apply real-query query args))]
(request/with-limit-and-offset 0 0
- (is (pos? (:total (#'api.collection/collection-children
+ (is (pos? (:total (collections.children/collection-children
(assoc collection/root-collection :namespace "snippets")
{:archived? false
:show-dashboard-questions? false
diff --git a/test/metabase/dashboards_rest/api_test.clj b/test/metabase/dashboards_rest/api_test.clj
index 3e84b552078..bf15d65143e 100644
--- a/test/metabase/dashboards_rest/api_test.clj
+++ b/test/metabase/dashboards_rest/api_test.clj
@@ -36,7 +36,6 @@
[metabase.permissions.models.permissions-group :as perms-group]
[metabase.permissions.test-util :as perms.test-util]
[metabase.pulse.dashboard-subscription-test :as dashboard-subscription-test]
- [metabase.pulse.models.pulse :as models.pulse]
[metabase.queries-rest.api.card-test :as api.card-test]
[metabase.query-processor.middleware.permissions :as qp.perms]
[metabase.query-processor.pivot.test-util :as api.pivots]
@@ -4569,124 +4568,6 @@
(is (= ["A sian" "As"]
(mt/user-http-request :crowberto :get 200 (url list-param-id "A sian"))))))))
-(deftest broken-subscription-data-logic-test
- (testing "Ensure underlying logic of fixing broken pulses works (#30100)"
- (let [{param-id :id :as param} {:name "Source"
- :slug "source"
- :id "_SOURCE_PARAM_ID_"
- :type :string/=}]
- (mt/dataset test-data
- (mt/with-temp
- [:model/Card {card-id :id} {:name "Native card"
- :database_id (mt/id)
- :dataset_query {:database (mt/id)
- :type :query
- :query {:source-table (mt/id :people)}}
- :type :model}
- :model/Dashboard {dash-id :id} {:name "My Awesome Dashboard"}
- :model/DashboardCard {dash-card-id :id} {:dashboard_id dash-id
- :card_id card-id}
- ;; Broken pulse
- :model/Pulse {bad-pulse-id :id
- :as bad-pulse} {:name "Bad Pulse"
- :dashboard_id dash-id
- :creator_id (mt/user->id :trashbird)
- :parameters [(assoc param :value ["Twitter", "Facebook"])]}
- :model/PulseCard _ {:pulse_id bad-pulse-id
- :card_id card-id
- :dashboard_card_id dash-card-id}
- :model/PulseChannel {pulse-channel-id :id} {:channel_type :email
- :pulse_id bad-pulse-id
- :enabled true}
- :model/PulseChannelRecipient _ {:pulse_channel_id pulse-channel-id
- :user_id (mt/user->id :rasta)}
- :model/PulseChannelRecipient _ {:pulse_channel_id pulse-channel-id
- :user_id (mt/user->id :crowberto)}
- ;; Broken slack pulse
- :model/Pulse {bad-slack-pulse-id :id} {:name "Bad Slack Pulse"
- :dashboard_id dash-id
- :creator_id (mt/user->id :trashbird)
- :parameters [(assoc param :value ["LinkedIn"])]}
- :model/PulseCard _ {:pulse_id bad-slack-pulse-id
- :card_id card-id
- :dashboard_card_id dash-card-id}
- :model/PulseChannel _ {:channel_type :slack
- :pulse_id bad-slack-pulse-id
- :details {:channel "#my-channel"}
- :enabled true}
- ;; Non broken pulse
- :model/Pulse {good-pulse-id :id} {:name "Good Pulse"
- :dashboard_id dash-id
- :creator_id (mt/user->id :trashbird)}
- :model/PulseCard _ {:pulse_id good-pulse-id
- :card_id card-id
- :dashboard_card_id dash-card-id}
- :model/PulseChannel {good-pulse-channel-id :id} {:channel_type :email
- :pulse_id good-pulse-id
- :enabled true}
- :model/PulseChannelRecipient _ {:pulse_channel_id good-pulse-channel-id
- :user_id (mt/user->id :rasta)}
- :model/PulseChannelRecipient _ {:pulse_channel_id good-pulse-channel-id
- :user_id (mt/user->id :crowberto)}]
- (testing "We can identify the broken parameter ids"
- (is (=? [{:archived false
- :name "Bad Pulse"
- :creator_id (mt/user->id :trashbird)
- :id bad-pulse-id
- :parameters
- [{:name "Source" :slug "source" :id "_SOURCE_PARAM_ID_" :type "string/=" :value ["Twitter" "Facebook"]}]
- :dashboard_id dash-id}
- {:archived false
- :name "Bad Slack Pulse"
- :creator_id (mt/user->id :trashbird)
- :id bad-slack-pulse-id
- :parameters [{:name "Source"
- :slug "source"
- :id "_SOURCE_PARAM_ID_"
- :type "string/="
- :value ["LinkedIn"]}],
- :dashboard_id dash-id}]
- ;; `broken-pulses` doesn't order its results, so sort them for a stable comparison
- (sort-by :id (#'api.dashboard/broken-pulses dash-id {param-id param})))))
- (testing "We can gather all needed data regarding broken params"
- (let [bad-pulses (mapv
- #(update % :affected-users (partial sort-by :email))
- (sort-by :pulse-id (#'api.dashboard/broken-subscription-data dash-id {param-id param})))
- bad-pulse-ids (set (map :pulse-id bad-pulses))]
- (testing "We only detect the bad pulse and not the good one"
- (is (true? (contains? bad-pulse-ids bad-pulse-id)))
- (is (false? (contains? bad-pulse-ids good-pulse-id))))
- (is (=? [{:pulse-creator {:email "[email protected]"}
- :dashboard-creator {:email "[email protected]"}
- :pulse-id bad-pulse-id
- :pulse-name "Bad Pulse"
- :dashboard-id dash-id
- :bad-parameters [{:name "Source" :value ["Twitter" "Facebook"]}]
- :dashboard-name "My Awesome Dashboard"
- :affected-users [{:notification-type :email
- :recipient "Crowberto Corv"}
- {:notification-type :email
- :recipient "Rasta Toucan"}]}
- {:pulse-creator {:email "[email protected]"}
- :affected-users [{:notification-type :slack
- :recipient "#my-channel"}]
- :dashboard-creator {:email "[email protected]"}
- :pulse-id bad-slack-pulse-id
- :pulse-name "Bad Slack Pulse"
- :dashboard-id dash-id
- :bad-parameters [{:name "Source"
- :slug "source"
- :id "_SOURCE_PARAM_ID_"
- :type "string/="
- :value ["LinkedIn"]}]
- :dashboard-name "My Awesome Dashboard"}]
- bad-pulses))))
- (testing "Pulse can be archived"
- (testing "Pulse starts as unarchived"
- (is (false? (:archived bad-pulse))))
- (testing "Pulse is now archived"
- (is (true? (:archived (models.pulse/update-pulse! {:id bad-pulse-id :archived true})))))))))))
-
(deftest handle-broken-subscriptions-due-to-bad-parameters-test
(defn- test-handle-broken-subscription-notification!
[{:keys [disable-links? email-body-pattern match-email-body-pattern?]}]
diff --git a/test/metabase/documents/api/collection_test.clj b/test/metabase/documents/api/collection_test.clj
index 608cd5befe4..849225550e1 100644
--- a/test/metabase/documents/api/collection_test.clj
+++ b/test/metabase/documents/api/collection_test.clj
@@ -37,14 +37,26 @@
:name "Root Dashboard"}]
(testing "Normal cards and dashboards in root appear, but in_document cards do not"
(let [items (mt/user-http-request :rasta :get 200 "collection/root/items")
- root-test-items (filter #(#{normal-card-id dash-id in-document-card-id} (:id %))
+ ;; Match on (id, model) pairs: a bare id set both throws `Duplicate key` when a Card
+ ;; and a Dashboard draw the same id from their separate sequences (guaranteed in a
+ ;; fresh app DB, where both start at 1) and would pull in an unrelated same-id row.
+ root-test-items (filter (comp #{[normal-card-id "card"]
+ [in-document-card-id "card"]
+ [dash-id "dashboard"]}
+ (juxt :id :model))
(:data items))]
(is (= #{[normal-card-id "card"]
[dash-id "dashboard"]}
(set (map (juxt :id :model) root-test-items))))))
(testing "Even with show-dashboard-questions=true, in_document cards do not appear"
(let [items (mt/user-http-request :rasta :get 200 "collection/root/items?show-dashboard-questions=true")
- root-test-items (filter #(#{normal-card-id dash-id in-document-card-id} (:id %))
+ ;; Match on (id, model) pairs: a bare id set both throws `Duplicate key` when a Card
+ ;; and a Dashboard draw the same id from their separate sequences (guaranteed in a
+ ;; fresh app DB, where both start at 1) and would pull in an unrelated same-id row.
+ root-test-items (filter (comp #{[normal-card-id "card"]
+ [in-document-card-id "card"]
+ [dash-id "dashboard"]}
+ (juxt :id :model))
(:data items))]
(is (= #{[normal-card-id "card"]
[dash-id "dashboard"]}
@@ -103,7 +115,11 @@
:archived_directly true}]
(testing "Archived documents appear alongside other archived items in trash"
(let [items (mt/user-http-request :rasta :get 200 (format "collection/%d/items" (collection/trash-collection-id)))
- trash-test-items (filter #(#{archived-doc-id normal-doc-id archived-card-id archived-dash-id} (:id %))
+ trash-test-items (filter (comp #{[archived-doc-id "document"]
+ [normal-doc-id "document"]
+ [archived-card-id "card"]
+ [archived-dash-id "dashboard"]}
+ (juxt :id :model))
(:data items))]
(is (= #{[archived-doc-id "document" true true]
[archived-card-id "card" true true]
diff --git a/test/metabase/documents/api/document_test.clj b/test/metabase/documents/api/document_test.clj
index 6c5c8694725..4b0b042b1e3 100644
--- a/test/metabase/documents/api/document_test.clj
+++ b/test/metabase/documents/api/document_test.clj
@@ -143,6 +143,22 @@
(is (some? (recent-view (mt/user->id :crowberto) document-id))
"reading a document should record a recent view")))))
+(deftest post-document-records-a-recent-view-test
+ (testing "POST /api/document should record a recent view so the creator finds the document in recents (UXW-1786)"
+ ;; The command palette surfaces a freshly created document only through recents, and the only thing that
+ ;; writes that row is the `:event/document-read` handler. Creating is arguably not reading, but the two are
+ ;; carried by one event: suppressing it to keep view counts honest silently drops the document out of the
+ ;; palette. Pinned here because the only other guard is an e2e spec (onboarding/command-palette.cy.spec.js),
+ ;; which reports an empty palette without saying why.
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (mt/with-model-cleanup [:model/Document]
+ (let [document (mt/user-http-request :crowberto
+ :post 200 "document/"
+ {:name "Test Document"
+ :document (documents.test-util/text->prose-mirror-ast "Doc 1")})]
+ (is (some? (recent-view (mt/user->id :crowberto) (:id document)))
+ "creating a document should record a recent view"))))))
+
(deftest put-document-does-not-record-view-test
(testing "PUT /api/document/:id should not record a view (saving is not a read)"
(mt/with-temporary-setting-values [synchronous-batch-updates true]
diff --git a/test/metabase/documents/markdown_test.clj b/test/metabase/documents/markdown_test.clj
new file mode 100644
index 00000000000..eaaa98ece8e
--- /dev/null
+++ b/test/metabase/documents/markdown_test.clj
@@ -0,0 +1,1178 @@
+(ns metabase.documents.markdown-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [clojure.walk :as walk]
+ [metabase.documents.markdown :as md]))
+
+(set! *warn-on-reflection* true)
+
+(defn- strip-ids
+ [ast]
+ (walk/postwalk #(if (map? %) (dissoc % "_id") %) ast))
+
+(defn- para
+ [text]
+ {:type "paragraph" :attrs {"_id" (str (random-uuid))} :content [{:type "text" :text text}]})
+
+(defn- collect-type
+ "Every node of `type` anywhere in `ast`."
+ [ast type]
+ (let [found (atom [])]
+ (walk/postwalk (fn [n] (when (and (map? n) (= type (:type n))) (swap! found conj n)) n) ast)
+ @found))
+
+(defn- text+marks
+ [node]
+ ((juxt :text :marks) node))
+
+(defn- reserialize
+ [ast]
+ (:markdown (md/serialize ast)))
+
+;;; ------------------------------------------------ Round-trip ----------------------------------------------------
+
+(deftest ^:parallel round-trip-every-node-type-test
+ (testing "serialize∘parse is a fixed point over a document exercising every node type"
+ (let [ast {:type "doc"
+ :content
+ [{:type "heading" :attrs {"level" 2 "_id" "h1"} :content [{:type "text" :text "Q3 summary"}]}
+ {:type "paragraph" :attrs {"_id" "p1"}
+ :content [{:type "text" :text "Revenue was "}
+ {:type "text" :text "up 12%" :marks [{:type "bold"}]}
+ {:type "text" :text " on "}
+ {:type "text" :text "EMEA" :marks [{:type "italic"}]}
+ {:type "text" :text " with "}
+ {:type "text" :text "inline code" :marks [{:type "code"}]}
+ {:type "text" :text " and a "}
+ {:type "text" :text "link"
+ :marks [{:type "link" :attrs {"href" "https://example.com"
+ "target" "_blank"
+ "rel" "noopener noreferrer nofollow"}}]}
+ {:type "text" :text "."}]}
+ {:type "resizeNode" :attrs {"height" 442 "minHeight" 280}
+ :content [{:type "cardEmbed" :attrs {"id" 118 "name" "Revenue by region" "_id" "c1"}}]}
+ {:type "resizeNode" :attrs {"height" 300 "minHeight" 200}
+ :content [{:type "cardEmbed" :attrs {"id" 119 "name" nil "_id" "c2"}}]}
+ {:type "bulletList" :attrs {"_id" "l1"}
+ :content [{:type "listItem" :content [(para "first")]}
+ {:type "listItem" :content [(para "second")]}]}
+ {:type "orderedList" :attrs {"start" 1 "type" nil "_id" "l2"}
+ :content [{:type "listItem" :content [(para "one")]}]}
+ {:type "blockquote" :attrs {"_id" "q1"} :content [(para "quoted")]}
+ {:type "codeBlock" :attrs {"language" "sql" "_id" "cb1"}
+ :content [{:type "text" :text "SELECT *\nFROM orders"}]}
+ {:type "horizontalRule"}
+ {:type "metabot" :attrs {} :content [{:type "text" :text "scratch"}]}
+ {:type "resizeNode" :attrs {"height" 442 "minHeight" 280}
+ :content [{:type "flexContainer" :attrs {"columnWidths" [60 40]}
+ :content [{:type "supportingText" :attrs {"_id" "st1"}
+ :content [(para "Supporting prose.")]}
+ {:type "cardEmbed" :attrs {"id" 120 "name" "Trend" "_id" "c3"}}]}]}
+ {:type "paragraph" :attrs {"_id" "pz"}}]}
+ {m1 :markdown} (md/serialize ast)
+ reparsed (md/parse m1)
+ expected (strip-ids (update ast :content (fn [c] (vec (remove #(= "metabot" (:type %)) c)))))]
+ (is (= expected (strip-ids reparsed)))
+ (is (= m1 (reserialize reparsed)))
+ (is (not (str/includes? m1 "scratch")) "metabot nodes emit nothing"))))
+
+(deftest ^:parallel serialize-deterministic-test
+ (let [ast {:type "doc" :content [(para "hello") (para "world")]}]
+ (is (= (md/serialize ast) (md/serialize ast)))))
+
+(deftest ^:parallel parse-is-in-editor-normal-form-test
+ (testing "a text node's marks are in the editor schema's rank order"
+ (is (= [["outer " ["italic"]]
+ ["code" ["code" "italic"]]
+ [" and " ["italic"]]
+ ["bold" ["bold" "italic"]]
+ [" here" ["italic"]]]
+ (for [node (get-in (md/parse "*outer `code` and **bold** here*") [:content 0 :content])]
+ [(:text node) (mapv :type (:marks node))]))))
+ (testing "a childless node omits :content, the way ProseMirror's own toJSON does"
+ (is (= [{:type "paragraph" :attrs {}}]
+ (strip-ids (:content (md/parse "")))))
+ (is (= [{:type "codeBlock" :attrs {"language" nil}} {:type "paragraph" :attrs {}}]
+ (strip-ids (:content (md/parse "```\n```"))))))
+ (testing "every attribute the editor's schema declares is present, so no default is filled in on load"
+ (is (= {"start" 1 "type" nil}
+ (-> (md/parse "1. one") :content first :attrs (dissoc "_id"))))
+ (is (= {"href" "https://example.com" "target" "_blank" "rel" "noopener noreferrer nofollow"}
+ (-> (md/parse "[x](https://example.com)") :content first :content first :marks first :attrs)))))
+
+(deftest ^:parallel body-ends-in-a-paragraph-test
+ (testing "a body whose last block isn't a paragraph gets an empty one, the way the editor's trailingNode plugin would"
+ (doseq [markdown ["# Heading"
+ "> quoted"
+ "- a\n- b"
+ "```\ncode\n```"
+ "---"
+ "{% card id=118 %}"
+ "::: flex {columns=[60,40]}\n{% card id=1 %}\n{% card id=2 %}\n:::"]]
+ (is (= {:type "paragraph" :attrs {}}
+ (strip-ids (peek (:content (md/parse markdown)))))
+ markdown)))
+ (testing "a body already ending in a paragraph is left alone"
+ (is (= ["heading" "paragraph"]
+ (mapv :type (:content (md/parse "# Heading\n\nProse."))))))
+ (testing "an edit that leaves a non-paragraph last gets one appended, and re-editing doesn't stack them up"
+ (let [ast (md/parse "Intro.\n\nOutro.")
+ ser (md/serialize ast)
+ start (str/index-of (:markdown ser) "Outro.")
+ spliced (md/splice ast ser start (+ start (count "Outro.")) "# Heading")]
+ (is (= ["paragraph" "heading" "paragraph"] (mapv :type (:content spliced))))
+ (let [ser (md/serialize spliced)]
+ (is (= ["paragraph" "heading" "paragraph"]
+ (mapv :type (:content (md/splice spliced ser 0 (count "Intro.") "Preamble."))))))))
+ (testing "an empty body is floored to a single paragraph"
+ (is (= [{:type "paragraph" :attrs {}}]
+ (strip-ids (:content (md/parse "")))))))
+
+(deftest ^:parallel loose-embeds-get-a-resize-wrapper-test
+ (testing "a bare card token becomes a resize-wrapped embed — the wrapper is the only thing carrying a height"
+ (is (= [{:type "resizeNode"
+ :attrs {"height" 442 "minHeight" 280}
+ :content [{:type "cardEmbed" :attrs {"id" 118 "name" "Revenue"}}]}
+ {:type "paragraph" :attrs {}}]
+ (strip-ids (:content (md/parse "{% card id=118 name=\"Revenue\" %}"))))))
+ (testing "a bare flex container gets one too"
+ (is (= ["resizeNode" "paragraph"]
+ (mapv :type (:content (md/parse "::: flex {columns=[60,40]}\n{% card id=1 %}\n{% card id=2 %}\n:::"))))))
+ (testing "an explicit ::: resize fence keeps its own dimensions and is not double-wrapped"
+ (is (= [{:type "resizeNode"
+ :attrs {"height" 600 "minHeight" 300}
+ :content [{:type "cardEmbed" :attrs {"id" 118 "name" nil}}]}
+ {:type "paragraph" :attrs {}}]
+ (strip-ids (:content (md/parse "::: resize {height=600 minHeight=300}\n{% card id=118 %}\n:::"))))))
+ (testing "an edit that introduces a card token wraps it, leaving untouched blocks alone"
+ (let [ast (md/parse "Intro.\n\nOutro.")
+ ser (md/serialize ast)
+ start (str/index-of (:markdown ser) "Outro.")
+ spliced (md/splice ast ser start (+ start (count "Outro.")) "{% card id=118 %}")]
+ (is (= ["paragraph" "resizeNode" "paragraph"] (mapv :type (:content spliced))))
+ (is (= (get-in ast [:content 0 :attrs "_id"])
+ (get-in spliced [:content 0 :attrs "_id"]))))))
+
+;;; ------------------------------------------------ Token scanning ------------------------------------------------
+
+(deftest ^:parallel code-block-token-opacity-test
+ (testing "card tokens and container fences inside a fenced code block are content, not structure"
+ (let [ast {:type "doc"
+ :content [{:type "codeBlock" :attrs {"language" nil "_id" "cb"}
+ :content [{:type "text" :text "{% card id=118 %}\n::: flex\ntext"}]}
+ {:type "paragraph" :attrs {"_id" "pz"}}]}
+ {m :markdown} (md/serialize ast)
+ reparsed (md/parse m)]
+ (is (= (strip-ids ast) (strip-ids reparsed)))
+ (is (= ["codeBlock" "paragraph"] (mapv :type (:content reparsed))))))
+ (testing "a tilde fence is opaque too"
+ (let [reparsed (md/parse "~~~\n{% card id=118 %}\n~~~")]
+ (is (= ["codeBlock" "paragraph"] (mapv :type (:content reparsed)))))))
+
+(deftest ^:parallel code-language-cannot-break-the-fence-test
+ (testing "a :language holding a backtick — a tilde fence's info string legitimately carries one —
+ serializes behind a tilde fence, so re-parsing cannot promote the fenced content to
+ structure"
+ (let [ast {:type "doc"
+ :content [{:type "codeBlock" :attrs {"language" "foo`bar" "_id" "cb"}
+ :content [{:type "text" :text "{% card id=666 %}"}]}
+ {:type "paragraph" :attrs {"_id" "pz"}}]}
+ {m :markdown} (md/serialize ast)
+ reparsed (md/parse m)]
+ (is (= (strip-ids ast) (strip-ids reparsed)))
+ (is (not-any? #(= "cardEmbed" (:type %)) (tree-seq :content :content reparsed)))))
+ (testing "the tilde fence still clears a tilde run inside the code text"
+ (let [ast {:type "doc"
+ :content [{:type "codeBlock" :attrs {"language" "a`b" "_id" "cb"}
+ :content [{:type "text" :text "~~~~\n{% card id=666 %}"}]}
+ {:type "paragraph" :attrs {"_id" "pz"}}]}
+ reparsed (md/parse (:markdown (md/serialize ast)))]
+ (is (= (strip-ids ast) (strip-ids reparsed)))))
+ (testing "a newline in :language collapses to a space rather than splitting the fence line"
+ (let [ast {:type "doc"
+ :content [{:type "codeBlock" :attrs {"language" "sql\n{% card id=666 %}" "_id" "cb"}
+ :content [{:type "text" :text "SELECT 1"}]}
+ {:type "paragraph" :attrs {"_id" "pz"}}]}
+ reparsed (md/parse (:markdown (md/serialize ast)))]
+ (is (= ["codeBlock" "paragraph"] (mapv :type (:content reparsed))))
+ (is (not-any? #(= "cardEmbed" (:type %)) (tree-seq :content :content reparsed))))))
+
+(deftest ^:parallel unclosed-token-never-overflows-test
+ (testing "a very long unclosed token parses as plain text instead of overflowing the regex engine"
+ (let [text (str "{% entity " (apply str (repeat 100000 "a")))]
+ (is (= ["paragraph"] (mapv :type (:content (md/parse text)))))))
+ (testing "an absurdly long card token body is a teaching error, not a crash"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"attributes exceed"
+ (md/parse (str "{% card " (apply str (repeat 100000 "a")) " %}"))))))
+
+(deftest ^:parallel oversized-numeric-token-test
+ (testing "a >18-digit id stays a string and hits the token's own teaching error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Invalid card token"
+ (md/parse "{% card id=99999999999999999999 %}")))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"height must be a number"
+ (md/parse "::: resize {height=99999999999999999999}\n{% card id=1 %}\n:::")))))
+
+(deftest ^:parallel malformed-token-grammar-is-a-teaching-error-test
+ (testing "an unknown card token attribute"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Unknown card token attribute"
+ (md/parse "{% card id=1 foo=2 %}"))))
+ (testing "an unclosed container fence"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Unclosed ::: flex"
+ (md/parse "::: flex\n{% card id=1 %}"))))
+ (testing "an unknown container fence attribute"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Unknown ::: resize attribute"
+ (md/parse "::: resize {bogus=1}\n{% card id=1 %}\n:::"))))
+ (testing "flex columns that aren't a numeric array"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"numeric array"
+ (md/parse "::: flex {columns=abc}\n{% card id=1 %}\n:::")))))
+
+;;; ------------------------------------------------ Container content models --------------------------------------
+
+(deftest ^:parallel container-content-model-violations-are-teaching-errors-test
+ (testing "a resize container wrapping prose"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"resize container must wrap"
+ (md/parse "::: resize\nprose\n:::"))))
+ (testing "a flex container holding a bare paragraph"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"flex container must hold"
+ (md/parse "::: flex\nsome prose\n:::"))))
+ (testing "a flex container with four columns"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"flex container must hold"
+ (md/parse (str "::: flex\n"
+ "{% card id=1 %}\n{% card id=2 %}\n{% card id=3 %}\n{% card id=4 %}\n"
+ ":::")))))
+ (testing "a supporting block holding a card embed"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"supporting block can only hold"
+ (md/parse "::: supporting\n{% card id=1 %}\n:::"))))
+ (testing "a splice whose re-parse breaks the touched container's content model"
+ (let [ast (md/parse "::: resize\n{% card id=118 %}\n:::")
+ ser (md/serialize ast)
+ i (str/index-of (:markdown ser) "{% card id=118 %}")]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"resize container must wrap"
+ (md/splice ast ser i (+ i (count "{% card id=118 %}")) "just prose"))))))
+
+;;; ------------------------------------------------ Nesting depth -------------------------------------------------
+
+(defn- deeply-nested-markdown
+ "Markdown nested `n` levels deep by each structure whose conversion recurses. Every one of these
+ overflowed the stack before a depth bound existed, at inputs as small as 8KB. Deep bullet lists
+ are deliberately absent: past four columns CommonMark reads the indentation as a code block
+ rather than a deeper list, so they cannot actually nest — and blockquotes already exercise the
+ same `convert-block` recursion a list would."
+ [n]
+ {"container fences" (str (apply str (repeat n "::: flex\n")) (apply str (repeat n ":::\n")))
+ "blockquotes" (str (apply str (repeat n "> ")) "hi")
+ ;; This one overflows inside flexmark itself, before any of our conversion runs, so only a
+ ;; StackOverflowError backstop can turn it into an error response.
+ "emphasis runs" (str (apply str (repeat n "*")) "x" (apply str (repeat n "*")))})
+
+(defn- parse-outcome
+ "`:parsed`, or the ex-data of the teaching error, or `:stack-overflow`. Deliberately not
+ `thrown-with-msg?`: a StackOverflowError is an Error rather than an ExceptionInfo, so it would
+ sail straight through that assertion — the distinction between the two is the whole point here."
+ [markdown]
+ (try (md/parse markdown)
+ :parsed
+ (catch clojure.lang.ExceptionInfo e (assoc (ex-data e) ::message (ex-message e)))
+ (catch StackOverflowError _ :stack-overflow)))
+
+(deftest ^:parallel deep-nesting-is-a-teaching-error-not-a-stack-overflow-test
+ (testing "input nested far past anything a document can express is refused with a 400 naming the
+ problem. A StackOverflowError would be worse than a poor message: it is an Error, so it
+ slips past the `catch Exception` that sanitizes every MCP tool failure and reaches the
+ client as an unhandled 500. Note the exact depth at which the stack gives out shifts with
+ the caller's own frame depth, so the bound — not the overflow — has to be what rejects
+ these."
+ (doseq [[label markdown] (deeply-nested-markdown 4000)]
+ (testing label
+ (let [outcome (parse-outcome markdown)]
+ (is (= 400 (:status-code outcome))
+ (format "%s should be a 400 teaching error, got %s" label (pr-str outcome)))
+ ;; Without this the container case would pass on its content-model error alone, which
+ ;; says nothing about whether a depth bound exists.
+ (is (re-find #"(?i)nest|deep" (str (::message outcome)))
+ (format "%s should name nesting depth as the problem, got %s"
+ label (pr-str (::message outcome)))))))))
+
+(deftest ^:parallel legitimate-nesting-still-round-trips-test
+ (testing "the bound sits far above anything a real document holds, so ordinary nesting is
+ untouched. Layout containers are checked at their true maximum — resize > flex >
+ supporting is as deep as the content model allows — rather than at an arbitrary depth,
+ which would be rejected for violating the content model and prove nothing."
+ (doseq [[label markdown] {"blockquotes" (str (apply str (repeat 20 "> ")) "hi")
+ "emphasis runs" (str (apply str (repeat 20 "*")) "x" (apply str (repeat 20 "*")))
+ "container stack" (str "::: resize {height=442 minHeight=280}\n"
+ "::: flex {columns=[60,40]}\n"
+ "::: supporting\nProse.\n:::\n"
+ "{% card id=1 %}\n:::\n:::")}]
+ (testing label
+ (let [ast (md/parse markdown)
+ m1 (:markdown (md/serialize ast))]
+ (is (seq (:content ast)))
+ (is (= m1 (reserialize (md/parse m1)))))))))
+
+;;; ------------------------------------------------ Inline conversion ---------------------------------------------
+
+(deftest ^:parallel bare-url-autolink-test
+ (testing "a bare URL gets a link mark and the run around it converts normally"
+ (let [inlines (get-in (md/parse "cost *5* at http://x.com ok") [:content 0 :content])]
+ (is (some (fn [n] (some #(= "link" (:type %)) (:marks n))) inlines))))
+ (testing "escapes near a bare URL don't double on re-serialization"
+ (let [m1 (reserialize (md/parse "cost *5* at http://x.com ok"))
+ m2 (reserialize (md/parse m1))]
+ (is (= m1 m2)))))
+
+(deftest ^:parallel emphasis-boundary-whitespace-test
+ (testing "boundary whitespace moves outside the delimiters so the mark survives re-parse"
+ (let [ast {:type "doc" :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "text" :text "see "}
+ {:type "text" :text " word " :marks [{:type "bold"}]}
+ {:type "text" :text "end"}]}]}
+ {m :markdown} (md/serialize ast)]
+ (is (= "see **word** end" m))
+ (is (= [["see " nil] ["word" [{:type "bold"}]] [" end" nil]]
+ (mapv text+marks (get-in (md/parse m) [:content 0 :content]))))))
+ (testing "a leading-space italic can't turn the paragraph into a list"
+ (let [ast {:type "doc" :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "text" :text " hi" :marks [{:type "italic"}]}
+ {:type "text" :text " after"}]}]}
+ {m :markdown} (md/serialize ast)]
+ (is (= ["paragraph"] (mapv :type (:content (md/parse m)))))))
+ (testing "whole-whitespace marked text drops its delimiters"
+ (let [ast {:type "doc" :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "text" :text "a"}
+ {:type "text" :text " " :marks [{:type "bold"}]}
+ {:type "text" :text "b"}]}]}]
+ (is (= "a b" (:markdown (md/serialize ast)))))))
+
+(deftest ^:parallel code-span-delimiter-test
+ (testing "content with backtick runs gets a longer delimiter and round-trips"
+ (let [ast {:type "doc" :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "text" :text "a``b" :marks [{:type "code"}]}]}]}
+ {m :markdown} (md/serialize ast)]
+ (is (= [["a``b" [{:type "code"}]]]
+ (mapv text+marks (get-in (md/parse m) [:content 0 :content]))))))
+ (testing "content with symmetric edge spaces is padded and round-trips"
+ (let [ast {:type "doc" :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "text" :text " x " :marks [{:type "code"}]}]}]}
+ {m :markdown} (md/serialize ast)]
+ (is (= [[" x " [{:type "code"}]]]
+ (mapv text+marks (get-in (md/parse m) [:content 0 :content])))))))
+
+(deftest ^:parallel link-destination-test
+ (testing "hrefs with spaces and parens keep their link mark through a round trip"
+ (doseq [[href expected] [["/a b(c)" "/a%20b(c)"]
+ ["https://x.com/q?a=(1)" "https://x.com/q?a=(1)"]
+ ["/plain" "/plain"]]]
+ (let [ast {:type "doc" :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "text" :text "go"
+ :marks [{:type "link" :attrs {"href" href}}]}]}]}
+ {m :markdown} (md/serialize ast)
+ reparsed (md/parse m)]
+ (is (= expected (get-in reparsed [:content 0 :content 0 :marks 0 :attrs "href"]))
+ (str "href " (pr-str href)))
+ (is (= m (reserialize reparsed)))))))
+
+;;; ------------------------------------------------ Block serialization -------------------------------------------
+
+(deftest ^:parallel indented-paragraph-stays-paragraph-test
+ (let [ast {:type "doc" :content [(para " indented start")]}
+ {m :markdown} (md/serialize ast)]
+ (is (= ["paragraph"] (mapv :type (:content (md/parse m)))))))
+
+(deftest ^:parallel card-name-escaping-test
+ (testing "backslashes, quotes, and newlines in a card name survive the token round trip"
+ (let [ast {:type "doc" :content [{:type "cardEmbed" :attrs {"id" 5 "name" "back\\slash\" q\nnewline" "_id" "c"}}]}
+ {m :markdown} (md/serialize ast)
+ reparsed (md/parse m)]
+ (is (= ["cardEmbed"] (mapv :type (get-in reparsed [:content 0 :content]))))
+ (is (= "back\\slash\" q newline" (get-in reparsed [:content 0 :content 0 :attrs "name"]))))))
+
+(def ^:private token-lookalike-strings
+ "Strings that, emitted verbatim, would be re-read as structure rather than as the prose they
+ came from. `:model`/`:label`/`:name`/`:text` are all `[:document :any]` as far as the REST API is
+ concerned, so any of them can hold one of these."
+ {"card token" "before\n\n{% card id=42 %}\n\nafter"
+ "indented card" "before\n\n {% card id=42 %}\n\nafter"
+ "flex fence" "before\n\n::: flex {columns=[50,50]}\n\nafter"
+ "closing fence" "before\n\n:::\n\nafter"
+ "atx heading" "before\n\n## Injected\n\nafter"
+ "thematic break" "before\n\n---\n\nafter"})
+
+(defn- text-bearing-blocks
+ "One AST per block type that renders `s` as its text, each already ending in a paragraph so
+ `ensure-trailing-paragraph` is a no-op and the round trip is a true fixed point."
+ [s]
+ (let [t {:type "text" :text s}
+ pgh {:type "paragraph" :attrs {"_id" "inner"} :content [t]}]
+ {"paragraph" {:type "paragraph" :attrs {"_id" "b"} :content [t]}
+ "heading" {:type "heading" :attrs {"level" 2 "_id" "b"} :content [t]}
+ "listItem" {:type "bulletList" :attrs {"_id" "b"} :content [{:type "listItem" :content [pgh]}]}
+ "blockquote" {:type "blockquote" :attrs {"_id" "b"} :content [pgh]}
+ "codeBlock" {:type "codeBlock" :attrs {"language" nil "_id" "b"} :content [t]}}))
+
+(deftest ^:parallel serializing-prose-never-manufactures-structure-test
+ (testing "text that merely looks like Metabase-flavored markup stays text — serializing a
+ document must not be able to invent a card embed or a layout container out of prose,
+ whichever block type the text sits in. The stored AST is unvalidated (`[:document :any]`
+ on the REST write path), so this is what stops a crafted attribute from injecting
+ structure into the body an agent reads and writes back."
+ (doseq [[label hostile] token-lookalike-strings
+ [block-name node] (text-bearing-blocks hostile)]
+ (let [ast {:type "doc" :content [node {:type "paragraph" :attrs {"_id" "z"}}]}
+ markdown (:markdown (md/serialize ast))
+ types (mapv :type (:content (md/parse markdown)))]
+ (is (empty? (filter #{"cardEmbed" "resizeNode" "flexContainer" "supportingText"} types))
+ (format "%s in a %s manufactured structure: %s" label block-name (pr-str types)))))))
+
+(def ^:private parser-line-endings
+ "Line terminators the Markdown parser ends a line on, `\\n` aside. Prose holding one of these is
+ re-read as two lines, so the second one can open a block."
+ {"carriage return" "\r"
+ "CRLF" "\r\n"})
+
+(def ^:private non-ending-separators
+ "Unicode separators the Markdown parser reads as ordinary text. They are line terminators to
+ Java's regex engine, where `.` excludes them, so line-oriented serialization has to keep them
+ out of a `.`-shaped pattern."
+ {"next line" (str (char 0x85))
+ "line separator" (str (char 0x2028))
+ "paragraph separator" (str (char 0x2029))})
+
+(defn- round-trip-block-types
+ "The block types `text` round-trips to when it is the prose of `block-name`."
+ [block-name text]
+ (let [node (get (text-bearing-blocks text) block-name)]
+ (mapv :type (:content (md/parse (reserialize {:type "doc"
+ :content [node {:type "paragraph" :attrs {"_id" "z"}}]}))))))
+
+(deftest ^:parallel exotic-line-terminators-cannot-manufacture-structure-test
+ (testing "a line terminator other than \\n inside a text node serializes without failing and
+ cannot open a block on re-parse — the block structure has to come out the same as it
+ would for a plain space. `[:document :any]` on the REST write path lets any of these
+ reach the serializer, and text pasted from a PDF or a Word document routinely carries
+ one."
+ (doseq [[label separator] (merge parser-line-endings non-ending-separators)
+ block-name (keys (text-bearing-blocks ""))]
+ (let [types (round-trip-block-types block-name (str "before" separator "# Injected"))]
+ (is (= (round-trip-block-types block-name "before # Injected") types)
+ (format "%s in a %s changed the block structure: %s" label block-name (pr-str types)))))))
+
+(defn- code-block-in
+ "A document holding one code block whose text is `text`, nested in `container`."
+ [container text]
+ (let [code {:type "codeBlock" :attrs {"language" nil "_id" "code"} :content [{:type "text" :text text}]}]
+ {:type "doc"
+ :content [(case container
+ "blockquote" {:type "blockquote" :attrs {"_id" "b"} :content [code]}
+ "bulletList" {:type "bulletList" :attrs {"_id" "b"}
+ :content [{:type "listItem" :content [code]}]})
+ {:type "paragraph" :attrs {"_id" "z"}}]}))
+
+(defn- code-block-texts
+ "The text of every codeBlock in `ast`, however deeply nested."
+ [ast]
+ (->> (tree-seq :content :content ast)
+ (filter #(= "codeBlock" (:type %)))
+ (mapv #(apply str (map :text (:content %))))))
+
+(deftest ^:parallel nested-code-block-survives-its-line-endings-test
+ (testing "code block content is emitted raw — it is the one text the serializer must not escape
+ — so the line prefixes a blockquote or list adds have to be applied per line the parser
+ will see. Miss one and the closing fence lands outside the prefix, which does not merely
+ render oddly: it re-opens as a new block, the code's tail leaks out as top-level prose,
+ and `splice` writes that structure back to the document column on the next edit."
+ (doseq [[label separator] parser-line-endings
+ container ["blockquote" "bulletList"]]
+ (let [reparsed (md/parse (reserialize (code-block-in container (str "foo" separator "bar"))))]
+ (testing "the code survives as one code block, its line endings normalized to \\n"
+ (is (= ["foo\nbar"] (code-block-texts reparsed))
+ (format "%s in a code block inside a %s" label container)))
+ (testing "and the document is shaped exactly as the same code written with \\n"
+ (is (= (strip-ids (:content (md/parse (reserialize (code-block-in container "foo\nbar")))))
+ (strip-ids (:content reparsed)))
+ (format "%s in a code block inside a %s" label container)))))))
+
+(deftest ^:parallel non-ending-separators-survive-round-trip-test
+ (testing "a separator the parser reads as text stays in the prose verbatim — it is not a line
+ boundary to the grammar, so nothing about it needs normalizing away. The prefixes are
+ the ones that send the line down an escaping branch, where a pattern that stops at the
+ separator would drop the rest of the line."
+ (doseq [[label separator] non-ending-separators
+ prefix ["before" "1. before" "# before" "- before" "> before"]]
+ (let [text (str prefix separator "after")
+ ast {:type "doc" :content [(para text) {:type "paragraph" :attrs {"_id" "z"}}]}]
+ (is (= text (get-in (md/parse (reserialize ast)) [:content 0 :content 0 :text]))
+ (format "%s after %s did not survive the round trip" label (pr-str prefix)))))))
+
+;;; ------------------------------------------------ HTML ---------------------------------------------------------
+
+(def ^:private html-line-start-strings
+ "Prose that opens a line with `<`. Emitted verbatim, each one is re-read as HTML rather than as
+ the text it came from — and an HTML comment block converts to no nodes at all, so the prose is
+ silently gone by the time the document is written back."
+ {"html comment" "<!-- secret note -->"
+ "block-level tag" "<div>hi</div>"
+ "inline tag" "<span>hi</span>"
+ "declaration" "<!DOCTYPE html>"
+ "processing intruction" "<?php echo 1; ?>"
+ "cdata" "<![CDATA[x]]>"})
+
+(deftest ^:parallel html-at-line-start-survives-round-trip-test
+ (testing "text that begins with `<` stays text through serialize → parse. An HTML comment is the
+ worst of these: `convert-block` maps `HtmlCommentBlock` to no nodes, so the paragraph
+ comes back empty and the prose is lost with no error anywhere."
+ (doseq [[label text] html-line-start-strings]
+ (let [ast {:type "doc" :content [(para text)]}
+ reparsed (md/parse (reserialize ast))]
+ (is (= text (get-in reparsed [:content 0 :content 0 :text]))
+ (format "%s at paragraph start did not survive the round trip" label))
+ (is (= (strip-ids (:content ast)) (strip-ids (:content reparsed)))
+ (format "%s at paragraph start changed the document" label))))))
+
+(deftest ^:parallel html-at-line-start-in-a-blockquote-keeps-its-content-test
+ (testing "a container whose only child is prose starting with `<` still has children after the
+ round trip — the editor's schema declares `block+`, so a blockquote that loses its
+ paragraph is a document the editor cannot load"
+ (doseq [[label text] html-line-start-strings]
+ (let [ast {:type "doc"
+ :content [{:type "blockquote" :attrs {"_id" "q"} :content [(para text)]}
+ {:type "paragraph" :attrs {"_id" "z"}}]}
+ quoted (get-in (md/parse (reserialize ast)) [:content 0])]
+ (is (= "blockquote" (:type quoted))
+ (format "%s in a blockquote changed the block type" label))
+ (is (seq (:content quoted))
+ (format "%s in a blockquote left the container with no :content" label))
+ (is (= text (get-in quoted [:content 0 :content 0 :text]))
+ (format "%s in a blockquote did not survive the round trip" label))))))
+
+(deftest ^:parallel html-mid-paragraph-survives-round-trip-test
+ (testing "a `<` that is not at the start of a line needs no escape and still round-trips — the
+ escape is line-start only, so it must not fire mid-prose"
+ (doseq [[label html] html-line-start-strings]
+ (let [text (str "before " html " after")
+ ast {:type "doc" :content [(para text)]}
+ {m :markdown} (md/serialize ast)]
+ (is (= text (get-in (md/parse m) [:content 0 :content 0 :text]))
+ (format "%s mid-paragraph did not survive the round trip" label))
+ (is (not (str/includes? m "\\<"))
+ (format "%s mid-paragraph was escaped: %s" label (pr-str m)))))))
+
+(def ^:private childless-container-types
+ "Node types the editor's schema will not accept without children: `blockquote`, `listItem` and
+ `supportingText` hold blocks, the lists hold list items, and the layout containers hold one to
+ three of theirs."
+ #{"blockquote" "listItem" "bulletList" "orderedList" "supportingText" "flexContainer" "resizeNode"})
+
+(defn- contentless-containers
+ "The types of every node in `ast` that must have children and came back with none."
+ [ast]
+ (->> (tree-seq :content :content ast)
+ (filter #(and (childless-container-types (:type %)) (empty? (:content %))))
+ (mapv :type)))
+
+(def ^:private nothing-to-show-markdown
+ "Markdown whose container ends up holding nothing a document can render: an HTML comment converts
+ to no nodes at all, and a bare `>` or `-` never had a child to begin with. The serializer escapes
+ a line-start `<` so it never writes the first shape, but `document_write` takes `content_markdown`
+ straight from the agent, so all of these reach `parse` anyway."
+ {"blockquote holding only a comment" "> <!-- secret note -->"
+ "bullet item holding only a comment" "- <!-- secret note -->"
+ "ordered item holding only a comment" "1. <!-- secret note -->"
+ "blockquote with no children" ">"
+ "bullet item with no children" "-"})
+
+(deftest ^:parallel container-with-nothing-to-show-is-dropped-test
+ (testing "a container whose children all convert to nothing is dropped rather than emitted empty.
+ The editor's content model requires children, so a container without them is a document
+ body that cannot be loaded at all — the write succeeds and the document never opens."
+ (doseq [[label markdown] nothing-to-show-markdown]
+ (let [ast (md/parse markdown)]
+ (is (= [] (contentless-containers ast))
+ (format "%s produced a container with no :content" label))
+ (is (= ["paragraph"] (mapv :type (:content ast)))
+ (format "%s left more than the trailing paragraph behind: %s" label (pr-str (:content ast))))))))
+
+(deftest ^:parallel comment-in-a-list-costs-only-its-own-item-test
+ (testing "an item holding only a comment leaves the list — and the items around it — alone"
+ (let [ast (md/parse "- a\n- <!-- secret note -->\n- c")]
+ (is (= [] (contentless-containers ast)))
+ (is (= ["bulletList" "paragraph"] (mapv :type (:content ast))))
+ (is (= [["a"] ["c"]]
+ (for [item (get-in ast [:content 0 :content])]
+ (mapv #(get-in % [:content 0 :text]) (:content item))))))))
+
+(deftest ^:parallel comment-beside-prose-keeps-the-prose-and-the-container-test
+ (testing "a comment accompanied by real content costs that content nothing — the container stays
+ and keeps its structure, with only the comment gone"
+ (doseq [[label markdown] {"blockquote" "> <!-- secret note -->\n> real prose"
+ "list item" "- <!-- secret note -->\n\n real prose"}]
+ (let [ast (md/parse markdown)
+ container (get-in ast [:content 0])]
+ (is (= [] (contentless-containers ast)) label)
+ (is (= (if (= "blockquote" label) "blockquote" "bulletList") (:type container)) label)
+ (is (= ["real prose"]
+ (->> (tree-seq :content :content container)
+ (filter #(= "paragraph" (:type %)))
+ (map #(get-in % [:content 0 :text]))))
+ (format "%s lost the prose beside the comment: %s" label (pr-str container)))))))
+
+;;; ------------------------------------------------ Tables -------------------------------------------------------
+
+(def ^:private table-markdown
+ "A GFM pipe table. The editor's schema has no table node, so this can only ever come back as
+ prose — but every row is its own line, and a paragraph joins its lines with a space, so without
+ help the whole grid collapses onto one line and stops being readable as a table at all."
+ (str "| Region | Revenue |\n"
+ "| --- | --- |\n"
+ "| EMEA | 12 |\n"
+ "| APAC | 9 |"))
+
+(def ^:private table-rows
+ ["| Region | Revenue |" "| --- | --- |" "| EMEA | 12 |" "| APAC | 9 |"])
+
+(defn- block-lines
+ "The text of each line of a block node, split at its `hardBreak`s."
+ [node]
+ (reduce (fn [lines {:keys [type text]}]
+ (if (= "hardBreak" type)
+ (conj lines "")
+ (update lines (dec (count lines)) str text)))
+ [""]
+ (:content node)))
+
+(deftest ^:parallel table-rows-keep-their-own-lines-test
+ (testing "a table parses to one paragraph per table, with a line break between rows. LLM agents
+ emit tables constantly and the rows arrive separated by soft line breaks, which convert
+ to spaces — the pipes survive but the grid does not, so what comes back is one run-on
+ line no reader can recover the table from."
+ (is (= table-rows (block-lines (first (:content (md/parse table-markdown)))))))
+ (testing "a line of prose ahead of the table is a line of the same paragraph and keeps its break too"
+ (is (= (into ["Quarterly numbers:"] table-rows)
+ (block-lines (first (:content (md/parse (str "Quarterly numbers:\n" table-markdown)))))))))
+
+(deftest ^:parallel table-survives-round-trip-test
+ (testing "serialize → parse is a fixed point on a table, and the Markdown written back still has
+ one row per line — a document read after a write has to show the agent the table it sent"
+ (let [ast (md/parse table-markdown)
+ markdown (reserialize ast)
+ lines (str/split-lines markdown)]
+ (is (= 4 (count lines))
+ (format "table did not serialize one row per line: %s" (pr-str markdown)))
+ (is (every? #(str/starts-with? % "|") lines)
+ (format "a serialized table row lost its leading pipe: %s" (pr-str markdown)))
+ (is (= (strip-ids (:content ast)) (strip-ids (:content (md/parse markdown))))
+ (format "table round trip changed the document: %s" (pr-str markdown))))))
+
+(deftest ^:parallel table-in-a-container-keeps-its-rows-test
+ (testing "a table nested in a blockquote or a list item keeps its rows, and the line prefixes the
+ serializer adds are applied to every line the parser will see"
+ (doseq [[label markdown] {"blockquote" (str/join "\n" (map #(str "> " %) table-rows))
+ "list item" (str "- " (str/join "\n " table-rows))}]
+ (let [reparsed (md/parse (reserialize (md/parse markdown)))
+ table (->> (tree-seq :content :content reparsed)
+ (filter #(= "paragraph" (:type %)))
+ (some #(when (seq (:content %)) %)))]
+ (is (= table-rows (block-lines table))
+ (format "table in a %s did not survive the round trip" label))))))
+
+(deftest ^:parallel wrapped-prose-still-joins-its-lines-test
+ (testing "an ordinary soft-wrapped paragraph is not a table and keeps CommonMark's behavior — its
+ lines join with a space and no hard break is invented for them"
+ (is (= ["one two three"] (block-lines (first (:content (md/parse "one\ntwo\nthree"))))))
+ (is (not (str/includes? (reserialize (md/parse "one\ntwo\nthree")) "\\"))))
+ (testing "a run of pipes that is not a table — no delimiter row — is prose too"
+ (is (= ["a | b c | d"] (block-lines (first (:content (md/parse "a | b\nc | d"))))))))
+
+;;; -------------------------------------------- Reference links --------------------------------------------------
+
+(def ^:private reference-link-markdown
+ (str "See [the docs][d] and [d] for more.\n"
+ "\n"
+ "[d]: https://example.com/docs"))
+
+(defn- link-hrefs
+ [ast]
+ (->> (tree-seq :content :content ast)
+ (mapcat :marks)
+ (keep #(when (= "link" (:type %)) (get-in % [:attrs "href"])))
+ vec))
+
+(deftest ^:parallel reference-link-keeps-its-url-test
+ (testing "a reference link resolves to a link mark carrying the definition's URL. `LinkRef` has no
+ branch of its own, so it used to fall through to its source text and the URL — which
+ lives in a separate definition block that converts to nothing — was gone from the
+ document with nothing to recover it from."
+ (let [ast (md/parse reference-link-markdown)]
+ (is (= ["https://example.com/docs" "https://example.com/docs"] (link-hrefs ast)))
+ (is (= ["See the docs and d for more."] (block-lines (first (:content ast))))))))
+
+(deftest ^:parallel reference-link-survives-round-trip-test
+ (testing "the resolved link round-trips as an inline link — the definition it came from is
+ consumed, so the second pass has nothing left to resolve"
+ (let [ast (md/parse reference-link-markdown)
+ markdown (reserialize ast)]
+ (is (str/includes? markdown "https://example.com/docs")
+ (format "the URL is not in the serialized document: %s" (pr-str markdown)))
+ (is (= (strip-ids (:content ast)) (strip-ids (:content (md/parse markdown))))
+ (format "reference link round trip changed the document: %s" (pr-str markdown))))))
+
+(deftest ^:parallel undefined-reference-link-stays-text-test
+ (testing "a reference with no definition is not a link — CommonMark leaves it as literal text, and
+ so does the round trip"
+ (let [ast (md/parse "See [the docs][missing] for more.")]
+ (is (= [] (link-hrefs ast)))
+ (is (= "See [the docs][missing] for more."
+ (get-in (md/parse (reserialize ast)) [:content 0 :content 0 :text]))))))
+
+(deftest ^:parallel unused-reference-definition-keeps-its-url-test
+ (testing "a definition no link consumed still holds a URL a reader can use, so it stays as prose
+ rather than converting to nothing"
+ (let [ast (md/parse "[d]: https://example.com/docs")]
+ (is (= ["[d]: https://example.com/docs"] (block-lines (first (:content ast)))))
+ (testing "and its text survives the round trip. Not an AST fixed point: the URL is bare prose
+ now, so the second pass gives it the autolink mark any prose URL gets."
+ (is (= ["[d]: https://example.com/docs"]
+ (block-lines (first (:content (md/parse (reserialize ast)))))))))))
+
+(deftest ^:parallel lone-reference-definition-in-a-blockquote-keeps-its-content-test
+ (testing "a blockquote holding nothing but a definition still has children — the editor's schema
+ declares `block+`, so a container that loses its only child is a document it cannot load"
+ (let [quoted (get-in (md/parse "> [d]: https://example.com/docs") [:content 0])]
+ (is (= "blockquote" (:type quoted)))
+ (is (seq (:content quoted)) "the blockquote came back with no :content")
+ (is (= ["[d]: https://example.com/docs"] (block-lines (first (:content quoted))))))))
+
+(deftest ^:parallel unrepresentable-smart-link-model-degrades-to-text-test
+ (testing "a smartLink whose model has no token — a link type the frontend added, or a corrupted
+ attr — serializes as its label rather than failing the whole document body"
+ (let [link (fn [model] {:type "doc" :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "smartLink"
+ :attrs {"entityId" 1 "model" model
+ "label" "Revenue Measure" "href" "/"}}]}]})]
+ (testing "a known model still emits its token"
+ (is (= "{% entity id=\"1\" model=\"dashboard\" %}" (reserialize (link "dashboard")))))
+ (testing "an unknown model degrades to the label, and does not throw"
+ (is (= "Revenue Measure" (reserialize (link "measure")))))
+ (testing "a model carrying token syntax cannot smuggle it into the output"
+ (doseq [model ["dashboard\n\n{% card id=42 %}\n\nx"
+ "card\" %} {% card id=9 %} {% entity id=\"1\" model=\"card"]]
+ (let [markdown (reserialize (link model))]
+ (is (not (str/includes? markdown "{%")) (pr-str markdown))
+ (is (= ["paragraph"] (mapv :type (:content (md/parse markdown)))))))))))
+
+(deftest ^:parallel card-name-with-token-delimiter-keeps-the-embed-test
+ (testing "a card whose name contains {% or %} keeps its embed and drops just the name — the
+ delimiter can't be escaped past the block scanner, and previously the whole document
+ became unrewritable with a misleading container-content error"
+ (doseq [nm ["Q3 %} report" "a {% b"]]
+ (let [ast {:type "doc" :content [{:type "resizeNode" :attrs {"height" 442 "minHeight" 280}
+ :content [{:type "cardEmbed" :attrs {"id" 7 "name" nm "_id" "c"}}]}
+ {:type "paragraph" :attrs {"_id" "z"}}]}
+ markdown (:markdown (md/serialize ast))
+ reparsed (md/parse markdown)]
+ (is (= "{% card id=7 %}" (str/trim (second (str/split-lines markdown)))) nm)
+ (is (= ["cardEmbed"] (mapv :type (get-in reparsed [:content 0 :content]))) nm)
+ (is (= 7 (get-in reparsed [:content 0 :content 0 :attrs "id"])) nm)
+ (is (= markdown (reserialize reparsed)) nm)))))
+
+(deftest ^:parallel heading-single-line-test
+ (testing "hardBreak renders as a space inside a heading"
+ (let [ast {:type "doc" :content [{:type "heading" :attrs {"level" 2 "_id" "h"}
+ :content [{:type "text" :text "one"}
+ {:type "hardBreak"}
+ {:type "text" :text "two"}]}]}
+ {m :markdown} (md/serialize ast)
+ reparsed (md/parse m)]
+ (is (= ["heading" "paragraph"] (mapv :type (:content reparsed))))
+ (is (= "one two" (get-in reparsed [:content 0 :content 0 :text])))))
+ (testing "a trailing hash run is not stripped as an ATX closing sequence"
+ (let [ast {:type "doc" :content [{:type "heading" :attrs {"level" 1 "_id" "h"}
+ :content [{:type "text" :text "foo #"}]}]}
+ {m :markdown} (md/serialize ast)]
+ (is (= "foo #" (get-in (md/parse m) [:content 0 :content 0 :text]))))))
+
+(deftest ^:parallel adjacent-same-type-lists-test
+ (let [li (fn [t] {:type "listItem" :content [(para t)]})
+ ast {:type "doc" :content [{:type "bulletList" :attrs {"_id" "l1"} :content [(li "a") (li "b")]}
+ {:type "bulletList" :attrs {"_id" "l2"} :content [(li "c")]}
+ {:type "paragraph" :attrs {"_id" "pz"}}]}
+ {m :markdown} (md/serialize ast)
+ reparsed (md/parse m)]
+ (is (= ["bulletList" "bulletList" "paragraph"] (mapv :type (:content reparsed))))
+ (is (= (strip-ids ast) (strip-ids reparsed)))))
+
+(deftest ^:parallel serialize-coerces-or-rejects-attr-types-test
+ (testing "numeric-looking string attrs coerce"
+ (is (= "{% card id=118 %}"
+ (:markdown (md/serialize {:type "doc" :content [{:type "cardEmbed" :attrs {"id" "118" "_id" "c"}}]}))))
+ (is (str/includes?
+ (:markdown (md/serialize {:type "doc"
+ :content [{:type "resizeNode" :attrs {"height" "442" "minHeight" 280}
+ :content [{:type "cardEmbed" :attrs {"id" 1 "_id" "c"}}]}]}))
+ "{height=442 minHeight=280}")))
+ (testing "non-coercible attrs are teaching errors, not ClassCastException/NPE"
+ (doseq [ast [{:type "doc" :content [{:type "cardEmbed" :attrs {"id" nil "_id" "c"}}]}
+ {:type "doc" :content [{:type "cardEmbed" :attrs {"id" "nope" "_id" "c"}}]}
+ {:type "doc" :content [{:type "resizeNode" :attrs {"height" {"x" 1} "minHeight" 280}
+ :content [{:type "cardEmbed" :attrs {"id" 1 "_id" "c"}}]}]}
+ {:type "doc" :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "smartLink" :attrs {"entityId" "bad" "model" "card"}}]}]}]]
+ (is (= 400 (try (md/serialize ast)
+ ::no-error
+ (catch clojure.lang.ExceptionInfo e (:status-code (ex-data e)))))))))
+
+(deftest ^:parallel out-of-range-numeric-attr-test
+ (testing "an integral double a long can't hold is a teaching error, not an IllegalArgumentException"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"expected a positive integer"
+ (md/serialize {:type "doc" :content [{:type "cardEmbed" :attrs {"id" 1.0E19 "_id" "c"}}]})))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"expected a positive integer"
+ (md/serialize {:type "doc"
+ :content [{:type "paragraph" :attrs {"_id" "p"}
+ :content [{:type "smartLink"
+ :attrs {"entityId" 1.0E19 "model" "card"}}]}]}))))
+ (testing "a resize height past long range serializes in double notation instead of throwing"
+ (let [ast {:type "doc" :content [{:type "resizeNode" :attrs {"height" 1.0E19 "minHeight" 280}
+ :content [{:type "cardEmbed" :attrs {"id" 1 "_id" "c"}}]}]}]
+ (is (str/includes? (:markdown (md/serialize ast)) "height=1.0E19")))))
+
+;;; ------------------------------------------------ Smart links ---------------------------------------------------
+
+(deftest ^:parallel unresolved-smart-link-defaults-test
+ (testing "an entity token whose id doesn't resolve keeps the node with default label/href"
+ (let [reparsed (md/parse "x {% entity id=\"987654321\" model=\"dashboard\" %} y")]
+ (is (= {"entityId" 987654321 "model" "dashboard" "label" nil "href" "/"}
+ (get-in reparsed [:content 0 :content 1 :attrs]))))))
+
+(defn- smart-links-in
+ [ast]
+ (filter #(= "smartLink" (:type %)) (tree-seq :content :content ast)))
+
+(deftest ^:parallel entity-token-guards-test
+ (testing "an entity token inside an inline code span stays literal code text"
+ (let [reparsed (md/parse "use `{% entity id=\"1\" model=\"card\" %}` here")
+ code (some #(when (some (comp #{"code"} :type) (:marks %)) %)
+ (tree-seq :content :content reparsed))]
+ (is (empty? (smart-links-in reparsed)))
+ (is (= "{% entity id=\"1\" model=\"card\" %}" (:text code)))))
+ (testing "an entity token with a model this grammar has no node for stays prose"
+ (is (empty? (smart-links-in (md/parse "{% entity id=\"1\" model=\"bogus\" %} x")))))
+ (testing "an entity token with a non-positive id stays prose"
+ (is (empty? (smart-links-in (md/parse "{% entity id=\"0\" model=\"card\" %} x"))))))
+
+;;; ------------------------------------------------ Splice --------------------------------------------------------
+
+(defn- splice-replacing
+ "Splice `old-text` -> `new-text` in the serialization of `markdown-src`, returning the resulting
+ top-level node types and re-serialized body."
+ [markdown-src old-text new-text]
+ (let [ast (md/parse markdown-src)
+ ser (md/serialize ast)
+ i (str/index-of (:markdown ser) old-text)
+ out (md/splice ast ser i (+ i (count old-text)) new-text)]
+ [(mapv :type (:content out)) (reserialize out)]))
+
+(deftest ^:parallel splice-can-convert-a-block-to-another-type-test
+ (testing "an edit that turns a block into a different type must work. `convertible-block-types`
+ deliberately lets a paragraph pair with a bulletList or blockquote so the block keeps its
+ `:_id` and its comment anchors, but a paragraph's `:content` is inline while a list's is
+ blocks — reconciling ids down both at once fed text nodes to a block renderer and blew up
+ with `Cannot serialize unknown block node type \"text\"`. \"Turn this into a bulleted
+ list\" is an everyday edit, and it failed for every target type whose content is blocks."
+ (doseq [[label src old-text new-text expected-types]
+ [["paragraph to bullet list, following an existing list"
+ "- a\n- b\n\nplain para\n\ntail" "plain para" "- converted" ["bulletList" "bulletList" "paragraph"]]
+ ["paragraph to bullet list on its own"
+ "intro\n\nplain para\n\ntail" "plain para" "- converted" ["paragraph" "bulletList" "paragraph"]]
+ ["paragraph to blockquote"
+ "intro\n\nplain para\n\ntail" "plain para" "> quoted" ["paragraph" "blockquote" "paragraph"]]
+ ;; This direction always worked — heading content is inline, like a paragraph's — so it
+ ;; pins that the fix did not narrow what already converted.
+ ["paragraph to heading"
+ "intro\n\nplain para\n\ntail" "plain para" "## Heading" ["paragraph" "heading" "paragraph"]]
+ ["blockquote back to a paragraph"
+ "intro\n\n> quoted\n\ntail" "> quoted" "now plain" ["paragraph" "paragraph" "paragraph"]]
+ ["list back to a paragraph"
+ "- a\n- b\n\ntail" "- a\n- b" "now plain" ["paragraph" "paragraph"]]]]
+ (testing label
+ (is (= expected-types (first (splice-replacing src old-text new-text))))))))
+
+(deftest ^:parallel splice-leaves-earlier-siblings-byte-identical-test
+ (testing "splicing a block cannot disturb the serialized text before it — untouched siblings are
+ reused by identity and serialization is deterministic. Worth pinning because the
+ same-type-list separator (`<!-- -->`) is emitted between blocks, so a converted block can
+ change a separator; that stays safe only because the longer separator extends \"\\n\\n\"
+ rather than replacing it."
+ (doseq [[label src old-text new-text]
+ [["plain edit" "alpha\n\nbeta\n\ngamma" "gamma" "GAMMA"]
+ ["separator-changing" "- a\n- b\n\nplain para\n\ntail" "plain para" "- converted"]
+ ["inside a blockquote" "intro\n\n> quoted text\n\ntail" "quoted text" "changed text"]
+ ["block removed" "one\n\ntwo\n\nthree" "two" ""]]]
+ (testing label
+ (let [before (:markdown (md/serialize (md/parse src)))
+ i (str/index-of before old-text)
+ after (second (splice-replacing src old-text new-text))]
+ (is (= (subs before 0 i) (subs after 0 (min i (count after))))))))))
+
+(deftest ^:parallel splice-preserves-untouched-siblings-test
+ (let [ast {:type "doc" :content [(para "block one") (para "block two") (para "block three")]}
+ ser (md/serialize ast)
+ s (str/index-of (:markdown ser) "two")
+ out (md/splice ast ser s (+ s 3) "TWO")]
+ (is (identical? (nth (:content ast) 0) (nth (:content out) 0)))
+ (is (identical? (nth (:content ast) 2) (nth (:content out) 2)))
+ (is (= "block TWO" (get-in out [:content 1 :content 0 :text])))
+ (testing "the rewritten block keeps its node id, so comments anchored to it stay anchored"
+ (is (= (get-in ast [:content 1 :attrs "_id"])
+ (get-in out [:content 1 :attrs "_id"]))))))
+
+(deftest ^:parallel splice-descends-into-containers-test
+ (let [ast {:type "doc"
+ :content [{:type "resizeNode" :attrs {"height" 300 "minHeight" 280}
+ :content [{:type "flexContainer" :attrs {"columnWidths" nil}
+ :content [{:type "supportingText" :attrs {"_id" "st"}
+ :content [(para "inner one") (para "inner two")]}]}]}]}
+ ser (md/serialize ast)
+ s (str/index-of (:markdown ser) "inner one")
+ out (md/splice ast ser s (+ s 9) "INNER ONE")]
+ (is (= "st" (get-in out [:content 0 :content 0 :content 0 :attrs "_id"])))
+ (is (identical? (get-in ast [:content 0 :content 0 :content 0 :content 1])
+ (get-in out [:content 0 :content 0 :content 0 :content 1])))))
+
+(deftest ^:parallel splice-empty-result-floors-to-one-paragraph-test
+ (let [ast (md/parse "hello world")
+ ser (md/serialize ast)
+ out (md/splice ast ser 0 11 "")]
+ (is (= 1 (count (:content out))))
+ (is (= "paragraph" (:type (first (:content out)))))
+ (is (some? (get-in out [:content 0 :attrs "_id"])))))
+
+(deftest ^:parallel splice-deep-replacement-is-a-teaching-error-test
+ (testing "the replacement text re-parses behind the same StackOverflowError backstop [[md/parse]]
+ has — a raw Error would sail past the `catch Exception` that sanitizes tool failures"
+ (let [ast (md/parse "alpha\n\nomega")
+ ser (md/serialize ast)
+ i (str/index-of (:markdown ser) "omega")]
+ (doseq [[label replacement] (deeply-nested-markdown 4000)]
+ (testing label
+ (let [outcome (try (md/splice ast ser i (+ i (count "omega")) replacement)
+ :spliced
+ (catch clojure.lang.ExceptionInfo e (:status-code (ex-data e)))
+ (catch StackOverflowError _ :stack-overflow))]
+ (is (= 400 outcome)
+ (format "%s should be a 400 teaching error, got %s" label (pr-str outcome)))))))))
+
+(deftest ^:parallel splice-span-bounds-test
+ (testing "an out-of-range or non-int span is a teaching error, not a StringIndexOutOfBoundsException"
+ (let [ast (md/parse "alpha")
+ ser (md/serialize ast)
+ n (count (:markdown ser))]
+ (doseq [[s e] [[-1 1] [2 1] [0 (inc n)] [nil 1] [0.5 1]]]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Invalid splice span"
+ (md/splice ast ser s e "x")))))))
+
+(deftest ^:parallel splice-insertion-between-blocks-test
+ (testing "a pure insertion (start = end) inside the separator between two blocks parses the
+ replacement alone and reuses both neighbours by identity"
+ (let [ast (md/parse "alpha\n\nomega")
+ ser (md/serialize ast)
+ pos (dec (str/index-of (:markdown ser) "omega"))
+ out (md/splice ast ser pos pos "middle")]
+ (is (= [["paragraph" "alpha"] ["paragraph" "middle"] ["paragraph" "omega"]]
+ (mapv (juxt :type #(get-in % [:content 0 :text])) (:content out))))
+ (is (identical? (nth (:content ast) 0) (nth (:content out) 0)))
+ (is (identical? (nth (:content ast) 1) (nth (:content out) 2))))))
+
+(deftest ^:parallel splice-separator-only-span-test
+ (testing "a span confined to the separator between two blocks re-parses both neighbours; a
+ replacement that joins them merges into one block keeping the head block's id"
+ (let [ast (md/parse "alpha\n\nomega")
+ ser (md/serialize ast)
+ s (str/index-of (:markdown ser) "\n\n")
+ out (md/splice ast ser s (+ s 2) " ")]
+ (is (= 1 (count (remove #(empty? (:content %)) (:content out)))))
+ (is (= "alpha omega" (get-in out [:content 0 :content 0 :text])))
+ (is (= (get-in ast [:content 0 :attrs "_id"]) (get-in out [:content 0 :attrs "_id"])))))
+ (testing "deleting the separator outright merges the blocks the same way"
+ (let [ast (md/parse "alpha\n\nomega")
+ ser (md/serialize ast)
+ s (str/index-of (:markdown ser) "\n\n")
+ out (md/splice ast ser s (+ s 2) "")]
+ (is (= "alphaomega" (get-in out [:content 0 :content 0 :text]))))))
+
+(deftest ^:parallel splice-stale-markdown-test
+ (let [ast (md/parse "hello world")
+ ser (md/serialize ast)]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"re-serialize"
+ (md/splice ast (update ser :markdown str "x") 0 1 "y")))))
+
+;;; --------------------------------------------- Node reconciliation ----------------------------------------------
+
+(defn- ids-of
+ "Every `:_id` in the ast, mapped to the type and leading text of the node carrying it."
+ [ast]
+ (into {} (for [n (tree-seq :content :content ast)
+ :let [id (get-in n [:attrs "_id"])]
+ :when id]
+ [id [(:type n) (some :text (:content n))]])))
+
+(defn- edit-text
+ "Splice the first occurrence of `old` in the ast's Markdown to `new`."
+ [ast old new]
+ (let [ser (md/serialize ast)
+ i (str/index-of (:markdown ser) old)]
+ (md/splice ast ser i (+ i (count old)) new)))
+
+(deftest ^:parallel splice-keeps-ids-of-edited-blocks-test
+ (testing "editing a block's text leaves every node id in the document intact"
+ (let [ast (md/parse "## Heading\n\nEdit me please.\n\nLeave me alone.")
+ out (edit-text ast "Edit me please." "Edited!")]
+ (is (= (set (keys (ids-of ast))) (set (keys (ids-of out)))))))
+ (testing "ids nested inside blockquotes and lists survive too"
+ (let [ast (md/parse "> quoted text\n\n- alpha\n- beta\n\nplain")
+ out (edit-text ast "alpha" "ALPHA")]
+ (is (= (set (keys (ids-of ast))) (set (keys (ids-of out)))))))
+ (testing "a sweep touching every block keeps every id"
+ (let [ast (md/parse "# Unit DS-7\n\nDS-7 did not sleep.\n\n> DS-7 wrote a memo.\n\n- DS-7 alpha\n- untouched\n\nDS-7 logged it.")
+ out (loop [a ast]
+ (let [ser (md/serialize a)
+ i (str/last-index-of (:markdown ser) "DS-7")]
+ (if i (recur (md/splice a ser i (+ i 4) "DS-10")) a)))]
+ (is (= (set (keys (ids-of ast))) (set (keys (ids-of out)))))
+ (is (not (str/includes? (:markdown (md/serialize out)) "DS-7"))))))
+
+(deftest ^:parallel splice-id-reconciliation-follows-editor-semantics-test
+ (testing "a split leaves the id on the first of the two halves, as the editor's node-id plugin does"
+ (let [ast (md/parse "one two three")
+ out (edit-text ast "two" "two\n\nsplit")]
+ (is (= 2 (count (:content out))))
+ (is (= (get-in ast [:content 0 :attrs "_id"]) (get-in out [:content 0 :attrs "_id"])))
+ (is (not= (get-in ast [:content 0 :attrs "_id"]) (get-in out [:content 1 :attrs "_id"])))))
+ (testing "a merge keeps the head block's id and drops the tail's"
+ (let [ast (md/parse "head block\n\ntail block")
+ out (edit-text ast "head block\n\ntail block" "head block tail block")]
+ (is (= (get-in ast [:content 0 :attrs "_id"]) (get-in out [:content 0 :attrs "_id"])))
+ (is (not (contains? (ids-of out) (get-in ast [:content 1 :attrs "_id"]))))))
+ (testing "converting a paragraph to a heading keeps the id, matching setNode in the editor"
+ (let [ast (md/parse "Some title")
+ out (edit-text ast "Some title" "## Some title")]
+ (is (= "heading" (get-in out [:content 0 :type])))
+ (is (= (get-in ast [:content 0 :attrs "_id"]) (get-in out [:content 0 :attrs "_id"])))))
+ (testing "a deleted block's id is dropped rather than handed to a surviving neighbour"
+ (let [ast (md/parse "alpha\n\nbeta\n\ngamma")
+ alpha (get-in ast [:content 0 :attrs "_id"])
+ beta (get-in ast [:content 1 :attrs "_id"])
+ out (edit-text ast "alpha\n\nbeta" "beta")]
+ (is (= "beta" (get-in out [:content 0 :content 0 :text])))
+ (is (= beta (get-in out [:content 0 :attrs "_id"])))
+ (is (not (contains? (ids-of out) alpha)))))
+ (testing "a card embed never donates its id to prose that replaces it"
+ (let [ast (md/parse "::: flex\n{% card id=118 %}\n::: supporting\nwords\n:::\n:::")
+ card (some #(when (= "cardEmbed" (:type %)) (get-in % [:attrs "_id"]))
+ (tree-seq :content :content ast))
+ out (edit-text ast "{% card id=118 %}" "::: supporting\njust words now\n:::")]
+ (is (some? card))
+ (is (not (contains? (ids-of out) card))))))
+
+(deftest ^:parallel splice-without-fast-path-keys-test
+ (testing "a caller passing only :markdown gets the re-serialize fallback"
+ (let [ast {:type "doc" :content [(para "alpha") (para "beta")]}
+ {m :markdown} (md/serialize ast)
+ s (str/index-of m "beta")
+ out (md/splice ast {:markdown m} s (+ s 4) "BETA")]
+ (is (identical? (nth (:content ast) 0) (nth (:content out) 0)))
+ (is (= "BETA" (get-in out [:content 1 :content 0 :text]))))))
+
+(deftest ^:parallel code-fence-behind-list-marker-is-opaque-test
+ (testing "a fence opening on a list item's marker line still makes its content code, so token
+ syntax inside it stays text instead of being read as structure"
+ (doseq [src ["- ```\n {% card id=99 %}\n ```\n"
+ "1. ```\n {% card id=99 %}\n ```\n"
+ "* ```\n {% card id=99 %}\n ```\n"]]
+ (testing (pr-str src)
+ (is (empty? (collect-type (md/parse src) "cardEmbed"))))))
+ (testing "a card token outside any fence is still a real embed"
+ (is (= 1 (count (collect-type (md/parse "{% card id=99 %}\n")
+ "cardEmbed"))))))
+
+(deftest ^:parallel splice-keeps-untokenized-card-attrs-test
+ (testing "re-parsing a card embed keeps the attrs its token does not carry -- child_target_id
+ anchors comments and the rest is user-visible visualization state"
+ (let [card {:type "cardEmbed"
+ :attrs {"id" 7 "name" "Chart" "_id" "c1" "stored_result_id" 42 "sort" "asc"
+ "chart_href" "/q/7" "child_target_id" "anchor-9" "host_data" {"k" "v"}}}
+ ast {:type "doc" :content [(para "intro") card]}
+ ser (md/serialize ast)
+ s (str/index-of (:markdown ser) "\n\n")
+ out (md/splice ast ser s (+ s 2) "\n\n\n")
+ out-card (first (collect-type out "cardEmbed"))]
+ (is (= (:attrs card) (:attrs out-card)))))
+ (testing "a freshly parsed value still wins over the carried one, so retargeting a card works"
+ (let [card {:type "cardEmbed"
+ :attrs {"id" 7 "name" "Chart" "_id" "c1" "stored_result_id" 42 "child_target_id" "anchor-9"}}
+ ast {:type "doc" :content [(para "intro") card]}
+ ser (md/serialize ast)
+ m (:markdown ser)
+ s (str/index-of m "{%")
+ out (md/splice ast ser s (count m) "{% card id=1234 name=\"Other\" %}")
+ out-card (first (collect-type out "cardEmbed"))]
+ (is (= 1234 (get-in out-card [:attrs "id"])))
+ (is (= "Other" (get-in out-card [:attrs "name"])))
+ (is (= "anchor-9" (get-in out-card [:attrs "child_target_id"]))))))
+
+(deftest ^:parallel lone-cr-cannot-manufacture-a-card-embed-test
+ (testing "the scanner and the parser have to agree on where a line begins. `str/split-lines`
+ breaks on \\r?\\n and leaves a lone CR sitting inside the line it returns, but the parser
+ ends the line there — so a CR in a code fence's info line hides the fence from the
+ scanner while the parser still opens one, and a `{% card %}` the author fenced as code
+ is promoted to a real embed: a permission-scoped read of a card they never referenced."
+ (doseq [[label separator] parser-line-endings]
+ (let [fenced (str "```sql" separator "SELECT 1\n{% card id=999 %}\n```")]
+ (is (empty? (collect-type (md/parse fenced) "cardEmbed"))
+ (format "%s in a code fence info line manufactured a card embed" label))))))
+
+(deftest ^:parallel tab-indented-token-is-code-not-structure-test
+ (testing "a tab advances to the next 4-column tab stop, so a leading tab indents to column 4 and
+ opens an indented code block. The token and fence regexes bound their indent by
+ character count, which reads that same tab as one column of indent — the scanner
+ promotes to structure exactly what the parser reads as content."
+ (doseq [[label line] {"a tab" (str \tab "{% card id=118 %}")
+ "a space and tab" (str \space \tab "{% card id=118 %}")
+ "four spaces" " {% card id=118 %}"}]
+ (is (empty? (collect-type (md/parse line) "cardEmbed"))
+ (format "%s before a card token manufactured a card embed" label)))
+ (testing "and a container fence indented the same way is code too"
+ (is (empty? (collect-type (md/parse (str \tab "::: flex\n" \tab "{% card id=1 %}\n" \tab ":::"))
+ "cardEmbed"))))
+ (testing "while a token indented within the parser's 3-column budget is still structure"
+ (is (= [7] (mapv #(get-in % [:attrs "id"])
+ (collect-type (md/parse " {% card id=7 %}") "cardEmbed")))))
+ (testing "and a blank line separates blocks however wide its whitespace — measuring the indent
+ must not turn one into a code block"
+ (doseq [[label blank] {"four spaces" " "
+ "eight spaces" " "
+ "one tab" "\t"
+ "two tabs" "\t\t"}]
+ (is (= (strip-ids (:content (md/parse "para one\n\npara two")))
+ (strip-ids (:content (md/parse (str "para one\n" blank "\npara two")))))
+ (format "a blank line parsed differently from an empty one: %s" label))))))
+
+(deftest ^:parallel indented-code-line?-measures-the-first-content-column-test
+ (testing "a line is indented code when its first non-whitespace character sits at column 4 or
+ later, counting a tab to the next 4-column stop"
+ (are [expected line] (= expected (#'md/indented-code-line? line))
+ true " x"
+ true "\tx"
+ true " \tx"
+ true " x"
+ false " x"
+ false "x"))
+ (testing "a whitespace-only line is blank however wide — it separates blocks rather than opening
+ a code block, so the column test must run on a content character, not on entry"
+ (are [line] (false? (#'md/indented-code-line? line))
+ ""
+ " "
+ " "
+ " "
+ "\t"
+ "\t\t")))
diff --git a/test/metabase/lib/serialize_test.cljc b/test/metabase/lib/serialize_test.cljc
index b7f024673d1..1d5edd73f74 100644
--- a/test/metabase/lib/serialize_test.cljc
+++ b/test/metabase/lib/serialize_test.cljc
@@ -185,7 +185,8 @@
:metabase.driver.sql.query-processor/wrap-in-case true
:metabase.driver.sql.parameters.substitution/compiling-field-filter? true
:metabase.driver.sqlserver/optimized-bucketing? true
- :metabase.driver.mongo.query-processor/join-local "Cat"})
+ :metabase.driver.mongo.query-processor/join-local "Cat"
+ :metabase.mcp.v2.query/keyset true})
(def ^:private stage-internal-keys
"Every internal key middleware adds to a stage, other than the native-only `:query-permissions/referenced-card-ids`."
diff --git a/test/metabase/mcp/api_test.clj b/test/metabase/mcp/api_test.clj
deleted file mode 100644
index fabd9aecbac..00000000000
--- a/test/metabase/mcp/api_test.clj
+++ /dev/null
@@ -1,1771 +0,0 @@
-(ns metabase.mcp.api-test
- (:require
- [clojure.string :as str]
- [clojure.test :refer :all]
- [clojure.walk :as walk]
- [metabase.agent-api.settings :as agent-api.settings]
- [metabase.ai-tracing.core :as ait]
- [metabase.api.macros.scope :as scope]
- [metabase.collections.models.collection :as collection]
- [metabase.lib.core :as lib]
- [metabase.lib.metadata :as lib.metadata]
- [metabase.mcp.api :as mcp.api]
- [metabase.mcp.resources :as mcp.resources]
- [metabase.mcp.session :as mcp.session]
- [metabase.mcp.settings :as mcp.settings]
- [metabase.mcp.tools :as mcp.tools]
- [metabase.oauth-server.core :as oauth-server]
- [metabase.oauth-server.test-util :as oauth-server.tu]
- [metabase.search.test-util :as search.tu]
- [metabase.system.settings :as system.settings]
- [metabase.test :as mt]
- [metabase.test.data.users :as test.users]
- [metabase.test.fixtures :as fixtures]
- [metabase.test.http-client :as client]
- [metabase.util.json :as json]
- [oidc-provider.store :as oidc.store]
- [throttle.core :as throttle]
- [toucan2.core :as t2]))
-
-(set! *warn-on-reflection* true)
-
-(use-fixtures :once (fixtures/initialize :db :test-users))
-
-;; Backend-only test runs don't produce embed-mcp.html; install the inline fallback.
-(use-fixtures :each
- (fn [thunk]
- (mcp.resources/with-fallback-template (thunk))))
-
-;;; --------------------------------------------------- Helpers ----------------------------------------------------
-
-(defn- mcp-request
- "Make a POST request to /api/mcp with the given JSON-RPC body and optional extra headers.
- Authenticates as :crowberto (superuser) by default."
- ([body]
- (mcp-request body {}))
- ([body extra-headers]
- (client/client-full-response (test.users/username->token :crowberto)
- :post "mcp"
- {:request-options {:headers extra-headers}}
- body)))
-
-(defn- mcp-request-as
- "Like `mcp-request` but authenticates as the given test username."
- [username body extra-headers]
- (client/client-full-response (test.users/username->token username)
- :post "mcp"
- {:request-options {:headers extra-headers}}
- body))
-
-(defn- mcp-request-unauthenticated
- "Make an unauthenticated POST request to /api/mcp."
- ([body]
- (mcp-request-unauthenticated body {}))
- ([body extra-headers]
- (client/client-full-response :post 401 "mcp"
- {:request-options {:headers extra-headers}}
- body)))
-
-(defn- mcp-request-with-bearer
- "Make a POST request to /api/mcp with a bearer token and optional extra headers."
- [bearer-token expected-status body extra-headers]
- (client/client-full-response :post expected-status "mcp"
- {:request-options {:headers (merge {"authorization" (str "Bearer " bearer-token)}
- extra-headers)}}
- body))
-
-(defn- save-access-token!
- "Persist an OAuth access token into the provider backing the MCP endpoint. `client-id` should come
- from [[oauth-server.tu/with-oauth-client]]."
- [token user-id client-id scopes]
- (oidc.store/save-access-token (:token-store (oauth-server/get-provider))
- token (str user-id) client-id (vec scopes)
- (+ (inst-ms (java.util.Date.)) 3600000) nil))
-
-(defn- mcp-delete
- "Make a DELETE request to /api/mcp with optional headers.
- Authenticates as :crowberto (superuser) by default."
- [extra-headers]
- (client/client-full-response (test.users/username->token :crowberto)
- :delete "mcp"
- {:request-options {:headers extra-headers}}))
-
-(def ^:private mcp-endpoint-paths
- "Client paths that serve the MCP endpoint, appended to the test client's `/api`: the canonical
- `metabase-mcp` and the legacy `mcp` alias."
- ["metabase-mcp" "mcp"])
-
-(defn- mcp-request-to
- "Like `mcp-request` but to an explicit endpoint path (e.g. \"metabase-mcp\"), authenticated as :crowberto."
- [path body]
- (client/client-full-response (test.users/username->token :crowberto)
- :post path
- {:request-options {:headers {}}}
- body))
-
-(defn- mcp-request-unauthenticated-to
- "Make an unauthenticated POST to an explicit endpoint path, expecting a 401."
- [path body]
- (client/client-full-response :post 401 path {:request-options {:headers {}}} body))
-
-(defn- jsonrpc-request
- "Build a JSON-RPC 2.0 request map."
- ([method]
- (jsonrpc-request method {} 1))
- ([method params]
- (jsonrpc-request method params 1))
- ([method params id]
- {:jsonrpc "2.0" :method method :params params :id id}))
-
-(defn- jsonrpc-notification
- "Build a JSON-RPC 2.0 notification (no id)."
- ([method]
- (jsonrpc-notification method {}))
- ([method params]
- {:jsonrpc "2.0" :method method :params params}))
-
-(def ^:private mcp-app-ui-capabilities
- {:extensions {:io.modelcontextprotocol/ui {:mimeTypes ["text/html;profile=mcp-app"]}}})
-
-(defn- initialize-with-params!
- "Perform the full MCP initialize handshake with custom initialize params.
- Returns [session-id init-response]."
- [params]
- (let [response (mcp-request (jsonrpc-request "initialize" params))
- session-id (get-in response [:headers "Mcp-Session-Id"])]
- ;; Complete the handshake so the session is marked initialized
- (mcp-request (jsonrpc-notification "notifications/initialized")
- {"mcp-session-id" session-id})
- [session-id response]))
-
-(defn- initialize!
- "Perform the full MCP initialize handshake (initialize + notifications/initialized).
- Returns [session-id init-response]."
- []
- (initialize-with-params! {:capabilities mcp-app-ui-capabilities}))
-
-(defn- initialize-without-ui!
- "Perform the full MCP initialize handshake without MCP Apps UI capability.
- Returns [session-id init-response]."
- []
- (initialize-with-params! {}))
-
-(defn- initialize-as!
- "Like `initialize!` but authenticates as the given test username."
- [username]
- (let [response (mcp-request-as username
- (jsonrpc-request "initialize" {:capabilities mcp-app-ui-capabilities})
- {})
- session-id (get-in response [:headers "Mcp-Session-Id"])]
- (mcp-request-as username
- (jsonrpc-notification "notifications/initialized")
- {"mcp-session-id" session-id})
- [session-id response]))
-
-(defn- call-tool
- "Call an MCP tool within an initialized session. Returns the parsed MCP result
- content (the JSON-decoded text from the first content block).
- Records test failures if the response status is not 200 or the tool returns an error."
- [session-id tool-name arguments]
- (let [response (mcp-request (jsonrpc-request "tools/call"
- {:name tool-name :arguments arguments})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- (is (= 200 (:status response))
- (str "Expected 200 from tools/call " tool-name))
- (is (not (:isError result))
- (str "Tool " tool-name " error: " (some-> result :content first :text)))
- (when-not (:isError result)
- (is (contains? result :structuredContent)
- (str "Tool " tool-name " declared an outputSchema in tools/list but did "
- "not return structuredContent — MCP spec violation."))
- (json/decode+kw (:text (first (:content result)))))))
-
-;;; ---------------------------------------------------- Tests -----------------------------------------------------
-
-(deftest authentication-required-test
- (testing "unauthenticated requests return 401"
- (let [response (client/client-full-response :post 401 "mcp"
- (jsonrpc-request "initialize"))]
- (is (= 401 (:status response)))
- (is (= -32603 (get-in response [:body :error :code]))))))
-
-(deftest origin-validation-test
- (testing "cross-origin browser requests are rejected when the origin is not configured"
- (let [response (mcp-request (jsonrpc-request "initialize")
- {"host" "mbtest.poom.dev"
- "origin" "http://127.0.0.1:6274"})]
- (is (= 403 (:status response)))
- (is (= "Origin not allowed" (get-in response [:body :error :message])))))
- (testing "cross-origin browser requests are accepted for configured MCP client origins"
- (mt/with-temporary-setting-values [mcp.settings/mcp-apps-cors-custom-origins "http://127.0.0.1:6274"]
- (let [response (mcp-request (jsonrpc-request "initialize")
- {"host" "mbtest.poom.dev"
- "origin" "http://127.0.0.1:6274"})]
- (is (= 200 (:status response)))
- (is (some? (get-in response [:headers "Mcp-Session-Id"]))))))
- (testing "same-origin requests with bracketed IPv6 hosts are accepted"
- (let [response (mcp-request (jsonrpc-request "initialize")
- {"host" "[::1]:3000"
- "origin" "http://[::1]:3000"})]
- (is (= 200 (:status response)))))
- (testing "same-origin requests with mixed-case host/origin are accepted"
- (let [response (mcp-request (jsonrpc-request "initialize")
- {"host" "Example.com"
- "origin" "https://example.COM"})]
- (is (= 200 (:status response)))))
- (testing "approved MCP origins match the Origin header case-insensitively"
- (mt/with-temporary-setting-values [mcp.settings/mcp-apps-cors-custom-origins "https://Example.COM"]
- (let [response (mcp-request (jsonrpc-request "initialize")
- {"host" "mbtest.poom.dev"
- "origin" "HTTPS://example.com"})]
- (is (= 200 (:status response)))
- (is (some? (get-in response [:headers "Mcp-Session-Id"]))))))
- (testing "a trailing slash on a configured MCP CORS origin has no effect (#75839)"
- (mt/with-temporary-setting-values [mcp.settings/mcp-apps-cors-custom-origins "http://127.0.0.1:6274/"]
- (let [response (mcp-request (jsonrpc-request "initialize")
- {"host" "mbtest.poom.dev"
- "origin" "http://127.0.0.1:6274"})]
- (is (= 200 (:status response)))
- (is (some? (get-in response [:headers "Mcp-Session-Id"])))))))
-
-(deftest mcp-enabled-setting-test
- (testing "external MCP requests return 403 when disabled"
- (mt/with-temporary-setting-values [mcp.settings/mcp-enabled? false]
- (let [response (mcp-request (jsonrpc-request "initialize"))]
- (is (= 403 (:status response)))
- (is (= "MCP server is not enabled." (:body response)))))))
-
-(deftest ai-features-enabled-setting-test
- (testing "external MCP requests return 403 when AI features are globally disabled"
- (mt/with-temporary-raw-setting-values [:ai-features-enabled? "false"
- :mcp-enabled? "true"]
- (let [response (mcp-request (jsonrpc-request "initialize"))]
- (is (= 403 (:status response)))
- (is (= "AI features are not enabled." (:body response)))))))
-
-(deftest initialize-test
- (testing "initialize returns protocol version, capabilities, and server info"
- (let [[session-id response] (initialize!)]
- (is (= 200 (:status response)))
- (is (some? session-id))
- (is (= "2.0" (get-in response [:body :jsonrpc])))
- (is (= 1 (get-in response [:body :id])))
- (let [result (get-in response [:body :result])]
- (is (= "2025-03-26" (:protocolVersion result)))
- (is (= {:tools {:listChanged true} :resources {}} (:capabilities result)))
- (is (= {:name "metabase" :version "0.1.0"} (:serverInfo result)))))))
-
-(deftest notifications-initialized-test
- (testing "notifications/initialized returns 202"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-notification "notifications/initialized")
- {"mcp-session-id" session-id})]
- (is (= 202 (:status response))))))
-
-(deftest session-validation-test
- (testing "requests without a session ID return 400"
- (let [response (mcp-request (jsonrpc-request "tools/list"))]
- (is (= 400 (:status response)))
- (is (= -32600 (get-in response [:body :error :code])))))
- (testing "requests with an invalid session ID return 404"
- (let [response (mcp-request (jsonrpc-request "tools/list")
- {"mcp-session-id" "bogus-session-id"})]
- (is (= 404 (:status response)))
- (is (= -32600 (get-in response [:body :error :code]))))))
-
-(deftest session-delete-test
- (testing "DELETE succeeds for a valid session"
- (let [[session-id _] (initialize!)
- delete-response (mcp-delete {"mcp-session-id" session-id})]
- (is (= 200 (:status delete-response))))))
-
-(deftest ^:parallel eval-session-override-test
- (testing "the x-eval-session-id header is honored only when it's a safe trace-file name"
- (let [override #'mcp.api/eval-session-override]
- (testing "a bare uuid (what the harness mints) is honored"
- (is (= "1ae768c9-5773-48dd-afca-c75780dae84c"
- (override {:headers {"x-eval-session-id" "1ae768c9-5773-48dd-afca-c75780dae84c"}}))))
- (testing "a safe slug is honored"
- (is (= "evalprobe_1.2" (override {:headers {"x-eval-session-id" "evalprobe_1.2"}}))))
- (testing "path traversal / unsafe chars are rejected (fall back to the Mcp-Session-Id)"
- (is (nil? (override {:headers {"x-eval-session-id" "../etc/passwd"}})))
- (is (nil? (override {:headers {"x-eval-session-id" "a/b"}})))
- (is (nil? (override {:headers {"x-eval-session-id" ".hidden"}}))))
- (testing "a value over max-session-id-length is rejected even though every char is safe"
- ;; 201 chars: regex-safe but one past the real cap — the boundary a looser copy of the
- ;; contract would wrongly accept (and then 500 downstream in checked-session-id).
- (is (= 200 ait/max-session-id-length))
- (is (nil? (override {:headers {"x-eval-session-id" (apply str (repeat 201 "a"))}})))
- (testing "the id exactly at the cap is honored, returned verbatim"
- (let [id (apply str (repeat 200 "a"))]
- (is (= id (override {:headers {"x-eval-session-id" id}}))))))
- (testing "absent header yields nil"
- (is (nil? (override {:headers {}})))))))
-
-(def ^:private all-tool-names
- #{"construct_query"
- "construct_native_query"
- "create_collection"
- "create_dashboard"
- "create_metric"
- "create_question"
- "execute_query"
- "execute_question"
- "execute_sql"
- "query"
- "read_resource"
- "refresh_ui_credential"
- "render_drill_through"
- "search"
- "update_dashboard"
- "update_metric"
- "update_question"
- "visualize_query"})
-
-(deftest ui-tools-declare-required-extensions-test
- (testing "UI tools declare their own required client extensions"
- (doseq [{:keys [name required-extensions]} (mcp.resources/list-ui-tools)]
- (is (= #{:mcp-app-ui} required-extensions)
- (str name " should require MCP Apps UI support")))))
-
-(deftest tools-list-all-tools-declare-required-hints-test
- (testing "every tool advertises readOnlyHint, destructiveHint, openWorldHint (some MCP clients reject tools that omit them)"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" session-id})
- tools (get-in response [:body :result :tools])]
- (is (seq tools) "tools/list should return at least one tool")
- (doseq [{:keys [name annotations]} tools]
- (is (contains? annotations :readOnlyHint) (str name " missing :readOnlyHint"))
- (is (contains? annotations :destructiveHint) (str name " missing :destructiveHint"))
- (is (contains? annotations :openWorldHint) (str name " missing :openWorldHint"))))))
-
-(deftest tools-list-omits-ui-tools-without-ui-capability-test
- (testing "clients that do not advertise MCP Apps UI support do not see UI-only tools"
- (let [[session-id _] (initialize-without-ui!)
- response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" session-id})
- tool-names (set (map :name (get-in response [:body :result :tools])))]
- (is (= (apply disj all-tool-names
- ["visualize_query"
- "render_drill_through"
- "refresh_ui_credential"])
- tool-names))
- (is (not (contains? tool-names "visualize_query")))
- (is (not (contains? tool-names "render_drill_through")))))
- (testing "clients that advertise MCP Apps UI support see UI-only tools"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" session-id})
- tool-names (set (map :name (get-in response [:body :result :tools])))]
- (is (contains? tool-names "visualize_query"))
- (is (contains? tool-names "render_drill_through")))))
-
-(deftest ui-capability-detection-requires-mcp-ui-extension-test
- (testing "the MCP Apps UI extension path enables UI-only tools"
- (let [[session-id _] (initialize-with-params! {:capabilities mcp-app-ui-capabilities})
- response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" session-id})
- tool-names (set (map :name (get-in response [:body :result :tools])))]
- (is (contains? tool-names "visualize_query"))
- (is (contains? tool-names "render_drill_through"))))
- (testing "an unrelated nested MCP Apps mimeType does not enable UI-only tools"
- (let [[session-id _] (initialize-with-params!
- {:capabilities {:experimental {:mimeTypes ["text/html;profile=mcp-app"]}}})
- response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" session-id})
- tool-names (set (map :name (get-in response [:body :result :tools])))]
- (is (not (contains? tool-names "visualize_query")))
- (is (not (contains? tool-names "render_drill_through"))))))
-
-(deftest text-content-includes-structured-content-for-maps-test
- (testing "text-content emits structuredContent for map values — MCP spec requires it for tools with outputSchema"
- (let [text-content (var-get #'mcp.tools/text-content)]
- (testing "map → both content and structuredContent"
- (let [result (text-content {:foo "bar"})]
- (is (= {:foo "bar"} (:structuredContent result)))
- (is (= "{\"foo\":\"bar\"}" (-> result :content first :text)))))
- (testing "sequential → structuredContent is the collection"
- (is (= [1 2 3] (:structuredContent (text-content [1 2 3])))))
- (testing "string → no structuredContent (nothing to structure)"
- (let [result (text-content "ok")]
- (is (not (contains? result :structuredContent)))
- (is (= "ok" (-> result :content first :text))))))))
-
-(deftest tool-result-emits-structured-content-test
- (testing "tools that declare outputSchema emit structuredContent — guards the regression where Claude Desktop got 500s because we declared outputSchema without matching structuredContent"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "read_resource"
- :arguments {:uris ["metabase://databases"]}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- (is (= 200 (:status response)))
- (is (not (:isError result))
- (str "read_resource should succeed: " (some-> result :content first :text)))
- (is (contains? result :structuredContent)
- "read_resource declares outputSchema → MUST emit structuredContent")
- (is (map? (:structuredContent result))
- "structuredContent should be the parsed response object, not a string")
- (is (sequential? (-> result :structuredContent :resources))
- "structuredContent should mirror the endpoint response shape"))))
-
-(deftest tools-list-strict-shape-test
- (testing "no tool's inputSchema uses JSON-Schema constructs that ChatGPT's strict MCP validator rejects"
- ;; Pins the strict-shape guarantee across the whole exposed tool surface. `construct_query` had
- ;; this asserted before; broadening it to every tool catches drift in any wire schema (e.g.
- ;; `query`'s `:multi` body referencing agent-lib `:tuple` schemas) that would silently leak
- ;; `:allOf`/`:prefixItems`/`items:false` constructs into a tool that worked before the regression.
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" session-id})
- tools (get-in response [:body :result :tools])]
- (is (pos? (count tools)))
- (doseq [{:keys [name inputSchema]} tools]
- (let [schema-keys (atom #{})]
- (walk/postwalk (fn [x] (when (map? x) (swap! schema-keys into (keys x))) x) inputSchema)
- (is (empty? (select-keys (frequencies @schema-keys) [:allOf :prefixItems]))
- (str "Tool " name " inputSchema contains :allOf or :prefixItems"))
- (is (not (some #(false? (:items %))
- (->> (tree-seq coll? seq inputSchema) (filter map?))))
- (str "Tool " name " inputSchema contains `items: false` (tuple closure)")))))))
-
-(deftest tools-list-test
- (testing "tools/list returns the agent and UI tools"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/list")
- {"mcp-session-id" session-id})
- tools (get-in response [:body :result :tools])]
- (is (= 200 (:status response)))
- (is (pos? (count tools)))
- (is (= all-tool-names (set (map :name tools))))
- (testing "each tool has a description and inputSchema"
- (doseq [tool tools]
- (is (string? (:description tool)))
- (is (map? (:inputSchema tool)))))
- (testing "search description guides clients toward the expected array shape"
- (let [tools-by-name (into {} (map (juxt :name identity)) tools)
- search-tool (get tools-by-name "search")
- property-schema (fn [tool-name property-name]
- (or (get-in tools-by-name [tool-name :inputSchema :properties property-name])
- (get-in tools-by-name [tool-name :inputSchema :properties (keyword property-name)])))
- collect-leaves (fn collect-leaves [schema]
- (cond
- (nil? schema) []
- (:oneOf schema) (mapcat collect-leaves (:oneOf schema))
- (:anyOf schema) (mapcat collect-leaves (:anyOf schema))
- :else [schema]))
- leaf-types (fn [schema] (set (keep :type (collect-leaves schema))))
- array-branch (fn [schema]
- (some #(when (= "array" (:type %)) %) (collect-leaves schema)))]
- (is (str/includes? (:description search-tool) "arrays of strings"))
- (is (contains? (leaf-types (property-schema "search" "term_queries")) "array"))
- (is (= "string" (get-in (array-branch (property-schema "search" "term_queries")) [:items :type])))
- (is (contains? (leaf-types (property-schema "search" "semantic_queries")) "array"))
- (is (= "string" (get-in (array-branch (property-schema "search" "semantic_queries")) [:items :type])))))
- (testing "construct_query expects the portable external-query JSON body"
- (let [tools-by-name (into {} (map (juxt :name identity)) tools)
- construct-query-tool (get tools-by-name "construct_query")
- construct-query-schema (:inputSchema construct-query-tool)
- query-schema (or (get-in construct-query-schema [:properties "query"])
- (get-in construct-query-schema [:properties :query]))
- required-fields (set (:required construct-query-schema))
- ;; ::lib.schema/external-query is generated as a deeply-nested :allOf, so the
- ;; root :type tag lives under the first branch rather than the top level.
- query-leaf-type (or (:type query-schema)
- (some :type (:allOf query-schema)))]
- (is (str/includes? (:description construct-query-tool) "construct_notebook_query"))
- (is (contains? required-fields "query"))
- (is (= "object" query-leaf-type)))))))
-
-(deftest ping-test
- (testing "ping returns empty result"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "ping")
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (= {} (get-in response [:body :result]))))))
-
-(deftest method-not-found-test
- (testing "unknown method returns -32601 error"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "nonexistent/method")
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (= -32601 (get-in response [:body :error :code]))))))
-
-(deftest batch-request-test
- (testing "batch requests are processed together"
- (let [[session-id _] (initialize!)
- response (mcp-request [(jsonrpc-request "ping" {} 1)
- (jsonrpc-request "tools/list" {} 2)]
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (sequential? (:body response)))
- (is (= 2 (count (:body response))))
- (is (= #{1 2} (set (map :id (:body response))))))))
-
-(deftest tools-call-unknown-tool-test
- (testing "calling an unknown tool returns isError content"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "nonexistent_tool" :arguments {}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- (is (= 200 (:status response)))
- (is (true? (:isError result)))
- (is (= "text" (:type (first (:content result))))))))
-
-(deftest tools-call-search-test
- (testing "search tool invocation works and returns parseable results"
- ;; Revert to the in-place search engine so test doesn't depend on the appdb search index being built.
- (search.tu/with-legacy-search
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "search"
- :arguments {:term_queries ["orders"]}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- (is (= 200 (:status response)))
- (is (nil? (:isError result)))
- (is (= "text" (:type (first (:content result)))))
- (let [search-data (json/decode+kw (:text (first (:content result))))]
- (is (contains? search-data :data))
- (is (contains? search-data :total_count))))))
- (testing "search accepts a singleton string as a one-element query list"
- (search.tu/with-legacy-search
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "search"
- :arguments {:term_queries "orders"}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- (is (= 200 (:status response)))
- (is (nil? (:isError result)))
- (let [search-data (json/decode+kw (:text (first (:content result))))]
- (is (contains? search-data :data))))))
- (testing "search coerces JSON-stringified arrays so clients that serialize args through a string layer still work"
- (search.tu/with-legacy-search
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "search"
- :arguments {:term_queries "[\"orders\"]"}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- (is (= 200 (:status response)))
- (is (nil? (:isError result)))
- (let [search-data (json/decode+kw (:text (first (:content result))))]
- (is (contains? search-data :data))
- (is (contains? search-data :total_count)))))))
-
-;;; ------------------------------------------------ SSE Transport -------------------------------------------------
-
-(deftest sse-post-response-test
- (testing "POST with Accept: text/event-stream returns SSE format"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "ping")
- {"mcp-session-id" session-id
- "accept" "text/event-stream"})]
- (is (= 200 (:status response)))
- (is (= "text/event-stream" (get-in response [:headers "Content-Type"])))
- ;; Body should be SSE events (raw string since it's not JSON)
- (is (string? (:body response)))
- (is (str/includes? (:body response) "event: message"))
- (is (str/includes? (:body response) "data: "))))
- (testing "POST without Accept: text/event-stream returns JSON (backward-compatible)"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "ping")
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (= "application/json" (get-in response [:headers "Content-Type"])))
- ;; Body should be parsed JSON
- (is (map? (:body response))))))
-
-(deftest sse-post-initialize-test
- (testing "initialize via SSE returns session header and SSE body"
- (let [response (mcp-request (jsonrpc-request "initialize")
- {"accept" "text/event-stream"})]
- (is (= 200 (:status response)))
- (is (some? (get-in response [:headers "Mcp-Session-Id"])))
- (is (= "text/event-stream" (get-in response [:headers "Content-Type"])))
- (is (string? (:body response)))
- ;; Parse the SSE data line to verify JSON-RPC structure
- (let [data-line (->> (str/split-lines (:body response))
- (filter #(str/starts-with? % "data: "))
- first)
- json-data (json/decode+kw (subs data-line 6))]
- (is (= "2.0" (:jsonrpc json-data)))
- (is (= 1 (:id json-data)))
- (is (some? (get-in json-data [:result :protocolVersion])))))))
-
-(deftest get-without-session-test
- (testing "GET without auth returns 401"
- (let [response (client/client-full-response (test.users/username->token :crowberto)
- :get "mcp")]
- (is (= 400 (:status response)))
- (is (= -32600 (get-in response [:body :error :code]))))))
-
-(deftest initialized-notification-compatibility-test
- (testing "requests succeed without notifications/initialized"
- (let [response (mcp-request (jsonrpc-request "initialize"))
- session-id (get-in response [:headers "Mcp-Session-Id"])
- list-response (mcp-request (jsonrpc-request "tools/list")
- {"mcp-session-id" session-id})]
- (is (= 200 (:status list-response)))
- (is (some? (get-in list-response [:body :result :tools])))))
- (testing "notifications/initialized is accepted as a no-op for compatibility"
- (let [response (mcp-request (jsonrpc-request "initialize"))
- session-id (get-in response [:headers "Mcp-Session-Id"])]
- (is (= 202 (:status (mcp-request (jsonrpc-notification "notifications/initialized")
- {"mcp-session-id" session-id})))))))
-
-(deftest full-handshake-test
- (testing "complete MCP handshake flow"
- (let [[session-id _] (initialize!)
- list-response (mcp-request (jsonrpc-request "tools/list")
- {"mcp-session-id" session-id})]
- (is (= 200 (:status list-response)))
- (is (seq (get-in list-response [:body :result :tools]))))))
-
-(deftest batch-with-notifications-test
- (testing "batch with mix of notifications and requests returns only request responses"
- (let [[session-id _] (initialize!)
- response (mcp-request [(jsonrpc-notification "notifications/initialized")
- (jsonrpc-request "ping" {} 1)]
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (sequential? (:body response)))
- (is (= 1 (count (:body response))))
- (is (= 1 (:id (first (:body response))))))))
-
-(deftest tools-call-missing-params-test
- (testing "tools/call without name returns an error"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:arguments {}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- (is (= 200 (:status response)))
- (is (true? (:isError result)))))
- (testing "tools/call with missing path params returns an error"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "update_question" :arguments {}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- (is (= 200 (:status response)))
- (is (true? (:isError result)))
- (is (str/includes? (:text (first (:content result))) "Missing required path parameter")))))
-
-(deftest tools-call-string-body-error-surfaces-actionable-message-test
- (testing (str "Claude's connector review explicitly rejects bare-status error messages — "
- "when the agent-api returns a string body (e.g. 404 \"Not found.\"), the MCP "
- "error content surfaces the body verbatim rather than collapsing to "
- "\"Agent API error: <status>\".")
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "update_question"
- :arguments {:id 999999 :name "Bogus"}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])
- message (:text (first (:content result)))]
- (is (= 200 (:status response)))
- (is (true? (:isError result)))
- (is (= "Not found." message)
- "string body should be surfaced verbatim")
- (is (not (str/includes? message "Agent API error"))
- "must not fall through to the bare-status fallback"))))
-
-(deftest tools-list-no-refs-test
- (testing "tool inputSchemas have no $ref, no $defs, root type is always object,
- and no top-level oneOf/anyOf/allOf (rejected by mcpjam)"
- (let [tools (mcp.tools/list-tools nil)]
- (doseq [tool tools]
- (when-let [schema (:inputSchema tool)]
- (let [as-str (pr-str schema)]
- (testing (:name tool)
- (is (not (re-find #"\$ref" as-str))
- (str (:name tool) " should have no $ref"))
- (is (not (contains? schema :$defs))
- (str (:name tool) " should have no $defs"))
- (is (= "object" (:type schema))
- (str (:name tool) " root type should be object"))
- (doseq [k [:oneOf :anyOf :allOf]]
- (is (not (contains? schema k))
- (str (:name tool) " should have no top-level " k))))))))))
-
-(defn- orders-count-query
- "Simple count query on the orders table — used as the dataset_query for smoke-test metrics."
- []
- (-> (lib/query (mt/metadata-provider)
- (lib.metadata/table (mt/metadata-provider) (mt/id :orders)))
- (lib/aggregate (lib/count))))
-
-(def ^:private smoke-tested-tools
- "Tools exercised by `tools-call-smoke-test`. New tools must be added here (and
- below) — the test compares this set against the Agent API-backed tools and
- fails when they diverge, ensuring no Agent API tool ships without a basic
- invocation check."
- #{"search" "construct_query" "construct_native_query" "query" "execute_query" "execute_sql"
- "read_resource"
- "create_question" "execute_question" "create_metric" "create_dashboard"
- "update_question" "update_metric" "update_dashboard" "create_collection"})
-
-(deftest tools-call-smoke-test-covers-all-agent-api-backed-tools-test
- (testing "every Agent API-backed tool is exercised by the smoke test"
- (is (= (apply disj
- (set (map :name (mcp.tools/list-tools nil)))
- (map :name (mcp.resources/list-ui-tools)))
- smoke-tested-tools)
- "Add the missing tool to `smoke-tested-tools` and the call sequence below.")))
-
-(deftest tools-call-smoke-test
- (testing "every tool returns a successful response with valid parameters"
- (mt/with-temporary-setting-values [system.settings/site-url "https://stats.metabase.test"]
- (search.tu/with-legacy-search
- (mt/with-temp [:model/Card _metric {:name "Smoke Metric"
- :type :metric
- :database_id (mt/id)
- :dataset_query (orders-count-query)}]
- (let [[session-id _] (initialize!)
- db-name (t2/select-one-fn :name :model/Database (mt/id))
- orders-query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table [db-name "PUBLIC" "ORDERS"]
- :limit 5}]}
- ;; A metric needs exactly one aggregation — `create_metric` rejects a plain query.
- metric-query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table [db-name "PUBLIC" "ORDERS"]
- :aggregation [["count" {}]]}]}
- ;; Track write-tool outputs in atoms so the `finally` cleanup runs even if an
- ;; assertion in `call-tool` fails partway through the sequence.
- question-id (atom nil)
- metric-id (atom nil)
- dash-id (atom nil)
- coll-id (atom nil)]
- (try
- (let [;; Discovery tools — call-tool helper asserts (not :isError) internally.
- _ (call-tool session-id "search" {:term_queries ["orders"]})
- ;; Query construction + execution
- construct-data (call-tool session-id "construct_query" {:query orders-query})
- native-data (call-tool session-id "construct_native_query"
- {:database_id (mt/id)
- :sql "SELECT 1"})
- _ (is (uuid? (parse-uuid (:query_handle native-data))))
- _ (call-tool session-id "query" {:query orders-query})
- _ (call-tool session-id "execute_query"
- {:query_handle (:query_handle construct-data)})
- _ (call-tool session-id "execute_sql"
- {:database_id (mt/id)
- :sql "SELECT 1"})
- _ (call-tool session-id "read_resource"
- {:uris ["metabase://databases"]})
- ;; Write tools — record IDs as soon as they're known so the `finally` block
- ;; can clean up even if a later step throws.
- question-data (call-tool session-id "create_question"
- {:name "Smoke Question"
- :query (mcp.session/read-handle session-id
- (mt/user->id :crowberto)
- (:query_handle construct-data))})
- _ (reset! question-id (:id question-data))
- _ (is (= (format "https://stats.metabase.test/question/%d" @question-id)
- (:url question-data)))
- ;; No collection_id given → defaults to the caller's personal collection;
- ;; collection_path must survive MCP forwarding.
- _ (is (= (collection/user->personal-collection-name (mt/user->id :crowberto) :user)
- (:collection_path question-data)))
- _ (call-tool session-id "update_question"
- {:id (:id question-data)
- :description "Smoke updated description"})
- metric-handle (call-tool session-id "construct_query" {:query metric-query})
- metric-data (call-tool session-id "create_metric"
- {:name "Smoke Metric Card"
- :query_handle (:query_handle metric-handle)})
- _ (reset! metric-id (:id metric-data))
- _ (is (= "scalar" (:display metric-data)))
- _ (call-tool session-id "update_metric"
- {:id (:id metric-data)
- :description "Smoke updated metric"})
- _ (call-tool session-id "execute_question"
- {:id (:id question-data)})
- dash-data (call-tool session-id "create_dashboard"
- {:name "Smoke Dashboard"})
- _ (reset! dash-id (:id dash-data))
- _ (is (= (format "https://stats.metabase.test/dashboard/%d" @dash-id)
- (:url dash-data)))
- dash-update (call-tool session-id "update_dashboard"
- {:id (:id dash-data)
- :description "Smoke updated dashboard"
- :dashcards [{:action "add_heading" :text "Smoke Section"}
- {:action "add_text" :text "Smoke *narrative*"}]})
- _ (is (= 2 (count (:dashcard_ids dash-update))))
- coll-data (call-tool session-id "create_collection"
- {:name "Smoke Collection"})]
- (reset! coll-id (:id coll-data)))
- (finally
- (when-let [qid @question-id] (t2/delete! :model/Card :id qid))
- (when-let [mid @metric-id] (t2/delete! :model/Card :id mid))
- (when-let [did @dash-id] (t2/delete! :model/Dashboard :id did))
- (when-let [cid @coll-id] (t2/delete! :model/Collection :id cid))))))))))
-
-(deftest tools-call-visualize-query-direct-test
- (testing "visualize_query returns UI structured content"
- (let [result (mcp.tools/call-tool nil nil "visualize_query" {:query "card__1"})]
- (is (not (:isError result)))
- (is (=? {:content [{:type "text"}]
- :structuredContent {:query "card__1"}}
- result)))))
-
-(deftest ui-tools-do-not-return-ui-credentials-test
- (testing "visualization tools leave credential minting to their app-only refresh tools"
- (let [[session-id _] (initialize!)
- visualize-result (get-in (mcp-request (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {:query "card__1"}})
- {"mcp-session-id" session-id})
- [:body :result])
- handle (mt/with-current-user (mt/user->id :crowberto)
- (mcp.session/store-handle! session-id
- (mt/user->id :crowberto)
- "card__2"))
- drill-result (get-in (mcp-request (jsonrpc-request "tools/call"
- {:name "render_drill_through"
- :arguments {:handle handle}})
- {"mcp-session-id" session-id})
- [:body :result])]
- (is (nil? (get-in visualize-result [:_meta :com.metabase/mcp-apps])))
- (is (nil? (get-in drill-result [:_meta :com.metabase/mcp-apps]))))))
-
-(deftest mcp-ui-auth-refresh-tools-test
- (testing "UI auth refresh tools are app-only and inherit their resource scopes"
- (let [[session-id _] (initialize!)
- tools (get-in (mcp-request (jsonrpc-request "tools/list")
- {"mcp-session-id" session-id})
- [:body :result :tools])
- tools-by-name (into {} (map (juxt :name identity)) tools)
- refresh-tool (get tools-by-name "refresh_ui_credential")]
- (is (=? {:_meta {:ui {:visibility ["app"]}}}
- refresh-tool))
- (is (nil? (get-in refresh-tool [:_meta :ui :resourceUri]))))
- (let [query-tools (into #{} (map :name)
- (mcp.tools/list-tools #{"agent:viz:mcp-ui:query"}))
- drill-tools (into #{} (map :name)
- (mcp.tools/list-tools #{"agent:viz:mcp-ui:drill-through"}))]
- (is (contains? query-tools "refresh_ui_credential"))
- (is (contains? drill-tools "refresh_ui_credential"))))
- (testing "a refresh call returns session-bound auth only in private metadata"
- (let [[session-id _] (initialize!)
- result (get-in (mcp-request
- (jsonrpc-request "tools/call"
- {:name "refresh_ui_credential"
- :arguments {}})
- {"mcp-session-id" session-id})
- [:body :result])
- credential (get-in result [:_meta :com.metabase/mcp-apps :credential])]
- (is (string? credential))
- (is (= session-id (get-in result [:_meta :com.metabase/mcp-apps :sessionId])))
- (is (not (str/includes? (pr-str (select-keys result [:content :structuredContent]))
- credential))))))
-
-(deftest refresh-ui-credential-is-redacted-from-tool-traces-test
- (testing "refresh_ui_credential returns private credentials without storing it in AI traces"
- (let [session-id (str (random-uuid))
- {:keys [result trace]}
- (mt/with-current-user (mt/user->id :crowberto)
- (ait/capturing
- (mcp.tools/call-tool #{::scope/unrestricted}
- session-id
- "refresh_ui_credential"
- {})))
- credential (get-in result [:_meta :com.metabase/mcp-apps :credential])
- tool-output (get-in trace [0 :attributes :ai/tool-output])]
- (is (string? credential))
- (is (= session-id (get-in result [:_meta :com.metabase/mcp-apps :sessionId])))
- (is (= (assoc result :_meta {}) tool-output))
- (is (not (str/includes? (pr-str trace) credential))))))
-
-(deftest tools-call-rejects-ui-tools-without-ui-capability-test
- (testing "direct calls to UI-only tools are rejected for clients without MCP Apps UI support"
- (let [[session-id _] (initialize-without-ui!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {:query "card__1"}})
- {"mcp-session-id" session-id})]
- (is (=? {:status 200
- :body {:result {:isError true
- :content [{:text #(str/includes? % "requires a client that supports MCP Apps UI")}]}}}
- response)))))
-
-(deftest tools-call-execute-query-test
- (testing "execute_query returns a streaming response captured as MCP text content"
- (let [streamed? (atom false)
- original-fn (mt/original-fn #'mcp.tools/capture-streaming-response)]
- (mt/with-dynamic-fn-redefs [mcp.tools/capture-streaming-response
- (fn [response]
- (reset! streamed? true)
- (original-fn response))]
- (let [[session-id _] (initialize!)
- db-name (t2/select-one-fn :name :model/Database (mt/id))
- external-query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table [db-name "PUBLIC" "ORDERS"]
- :limit 5}]}
- construct-data (call-tool session-id "construct_query" {:query external-query})
- execute-data (call-tool session-id "execute_query"
- {:query_handle (:query_handle construct-data)})]
- (is (true? @streamed?) "execute_query should use the streaming response path")
- (is (=? {:status "completed"
- :row_count 5
- :data {:cols sequential?
- :rows (fn [rows] (= 5 (count rows)))}}
- execute-data)))))))
-
-(deftest tools-call-query-accepts-query-handle-test
- (testing "the `query` tool resolves a query_handle and streams results, same as a fresh query body"
- (let [[session-id _] (initialize!)
- db-name (t2/select-one-fn :name :model/Database (mt/id))
- external-query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table [db-name "PUBLIC" "ORDERS"]
- :limit 5}]}
- construct-data (call-tool session-id "construct_query" {:query external-query})
- query-data (call-tool session-id "query"
- {:query_handle (:query_handle construct-data)})]
- (is (=? {:status "completed"
- :row_count 5
- :continuation_token nil?
- :data {:cols sequential?
- :rows (fn [rows] (= 5 (count rows)))}}
- query-data)))))
-
-(deftest tools-call-query-stale-query-handle-test
- (testing "the `query` tool returns a tool-level error for an unknown handle rather than a 500"
- (let [[session-id _] (initialize!)
- result (mcp-request (jsonrpc-request "tools/call"
- {:name "query"
- :arguments {:query_handle (str (random-uuid))}})
- {"mcp-session-id" session-id})]
- (is (=? {:status 200
- :body {:result {:isError true
- :content [{:text #(str/includes? % "Query handle not found")}]}}}
- result)))))
-
-(deftest tools-call-create-question-accepts-query-handle-test
- (testing "create_question resolves query_handle through the MCP layer instead of requiring raw base64"
- (let [[session-id _] (initialize!)
- db-name (t2/select-one-fn :name :model/Database (mt/id))
- construct-data (call-tool session-id "construct_query"
- {:query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table [db-name "PUBLIC" "ORDERS"]
- :limit 5}]}})
- question-id (atom nil)]
- (try
- (let [question-data (call-tool session-id "create_question"
- {:name "Handle-Path Question"
- :query_handle (:query_handle construct-data)})]
- (reset! question-id (:id question-data))
- (is (pos-int? (:id question-data)))
- (is (= "Handle-Path Question" (:name question-data)))
- ;; Card was actually persisted with a dataset_query (handle resolved correctly).
- (is (some? (t2/select-one-fn :dataset_query :model/Card :id (:id question-data)))))
- (finally
- (when-let [qid @question-id] (t2/delete! :model/Card :id qid)))))))
-
-(deftest tools-call-update-question-accepts-query-handle-test
- (testing "update_question resolves query_handle through the MCP layer"
- (mt/with-temp [:model/Card {card-id :id} {:name "Card To Re-query via Handle"
- :dataset_query (-> (lib/query (mt/metadata-provider)
- (lib.metadata/table (mt/metadata-provider)
- (mt/id :orders)))
- (lib/aggregate (lib/count)))
- :display :table}]
- (let [db-name (t2/select-one-fn :name :model/Database (mt/id))
- products-id (mt/id :products)
- products-fk [db-name "PUBLIC" "PRODUCTS"]
- [session-id _] (initialize!)
- construct-data (call-tool session-id "construct_query"
- {:query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table products-fk
- :limit 5}]}})
- update-data (call-tool session-id "update_question"
- {:id card-id
- :query_handle (:query_handle construct-data)})
- persisted (t2/select-one-fn :dataset_query :model/Card :id card-id)
- persisted-table (some :source-table (:stages persisted))]
- (is (= card-id (:id update-data)))
- ;; Handle was resolved and applied to the card. Construct sends portable FKs over the
- ;; wire; the persisted dataset_query is the resolved MBQL 5 map with numeric IDs.
- (is (= products-id persisted-table)
- (str "Expected handle-resolved query's :source-table = products id " products-id
- ", got " persisted-table))))))
-
-(deftest tools-call-update-question-stale-query-handle-test
- (testing "An unknown query_handle returns a tool-level error rather than 500"
- (mt/with-temp [:model/Card {card-id :id} {:name "Stale-Handle Target"
- :dataset_query (-> (lib/query (mt/metadata-provider)
- (lib.metadata/table (mt/metadata-provider)
- (mt/id :orders)))
- (lib/aggregate (lib/count)))
- :display :table}]
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "update_question"
- :arguments {:id card-id
- :query_handle (str (random-uuid))}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- ;; JSON-RPC: HTTP 200, result.isError, friendly message.
- (is (= 200 (:status response)))
- (is (nil? (get-in response [:body :error])))
- (is (true? (:isError result)))
- (is (str/includes? (-> result :content first :text) "Query handle not found")
- "Stale handle should surface the dedicated message from mcp/tools.clj")
- ;; Card should be unchanged - still pointed at orders, not whatever the stale handle would have meant.
- (let [persisted (t2/select-one-fn :dataset_query :model/Card :id card-id)]
- (is (= (mt/id :orders) (some :source-table (:stages persisted)))
- "A stale handle must not mutate the card's source table."))))))
-
-(deftest tools-call-update-dashboard-move-without-position-test
- (testing "Missing required field on a discriminated mutation surfaces as a tool error, not a JSON-RPC error"
- (mt/with-temp [:model/Dashboard {dash-id :id} {:name "MCP move validation"}
- :model/Card {card-id :id} {:name "x" :dataset_query (-> (lib/query (mt/metadata-provider)
- (lib.metadata/table (mt/metadata-provider)
- (mt/id :orders)))
- (lib/aggregate (lib/count)))
- :display :table}
- :model/DashboardCard {dc-id :id} {:dashboard_id dash-id :card_id card-id
- :row 0 :col 0 :size_x 6 :size_y 4}]
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "update_dashboard"
- :arguments {:id dash-id
- :dashcards [{:action "move" :dashcard_id dc-id}]}})
- {"mcp-session-id" session-id})
- result (get-in response [:body :result])]
- ;; JSON-RPC layer: HTTP 200, response in `result` not `error`. Bad-input is a tool-level error.
- (is (= 200 (:status response)))
- (is (nil? (get-in response [:body :error])))
- (is (true? (:isError result))
- "missing :position on move should surface as a tool error")))))
-
-(deftest tools-call-read-resource-test
- (testing "read_resource returns the shared dispatcher's response shape"
- (let [[session-id _] (initialize!)
- result (call-tool session-id "read_resource"
- {:uris ["metabase://databases"]})]
- ;; `result` is the parsed MCP text-content JSON, which is the dispatcher's
- ;; full return map (`:resources` per-URI + formatted `:output` string).
- (is (sequential? (:resources result)))
- (is (= 1 (count (:resources result))))
- (is (= "metabase://databases" (-> result :resources first :uri)))
- (is (some? (-> result :resources first :content))
- "Top-level navigation URI must come back with :content (no :error)")
- (is (string? (:output result)))
- (is (str/includes? (:output result) "<resources>")
- "Output is XML-shaped for LLM consumption")))
- (testing "read_resource fetches a single-entity URI"
- (let [[session-id _] (initialize!)
- uri (str "metabase://table/" (mt/id :orders))
- result (call-tool session-id "read_resource" {:uris [uri]})]
- (is (= [uri] (mapv :uri (:resources result))))
- (is (some? (-> result :resources first :content)))))
- (testing "read_resource reports a per-URI error rather than failing the whole call"
- (let [[session-id _] (initialize!)
- result (call-tool session-id "read_resource"
- {:uris ["metabase://nonsense/path"]})]
- (is (= 1 (count (:resources result))))
- (is (nil? (-> result :resources first :content)))
- (is (some? (-> result :resources first :error))))))
-
-;;; ----------------------------------------------- Drill Handles ---------------------------------------------------
-
-(deftest render-drill-through-publishes-its-own-resource-uri-test
- (testing "render_drill_through publishes a distinct `_meta.ui.resourceUri` from visualize_query — ChatGPT dedupes iframes by URI, and reusing the visualize_query URI would prevent a fresh drill widget from mounting"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" session-id})
- tools-by-name (into {} (map (juxt :name identity)) (get-in response [:body :result :tools]))
- drill-uri (get-in tools-by-name ["render_drill_through" :_meta :ui :resourceUri])
- viz-uri (get-in tools-by-name ["visualize_query" :_meta :ui :resourceUri])]
- (is (string? drill-uri))
- (is (string? viz-uri))
- (is (not= drill-uri viz-uri)
- "render_drill_through and visualize_query must publish different resourceUris"))))
-
-(deftest tools-call-render-drill-through-test
- (testing "render_drill_through resolves a stored handle to its encoded query"
- (let [user-id (mt/user->id :crowberto)
- [session-id _] (initialize!)
- handle (mt/with-current-user user-id
- (mcp.session/store-handle! session-id user-id "ZW5jb2RlZA=="))]
- ;; The error path returns no :structuredContent, so asserting it is present is
- ;; equivalent to asserting :isError is not set.
- (is (=? {:status 200
- :body {:result {:structuredContent {:query "ZW5jb2RlZA=="}}}}
- (mcp-request (jsonrpc-request "tools/call"
- {:name "render_drill_through"
- :arguments {:handle handle}})
- {"mcp-session-id" session-id})))))
- (testing "render_drill_through returns an error when the handle is unknown"
- (let [[session-id _] (initialize!)]
- (is (=? {:status 200
- :body {:result {:isError true}}}
- (mcp-request (jsonrpc-request "tools/call"
- {:name "render_drill_through"
- :arguments {:handle (str (random-uuid))}})
- {"mcp-session-id" session-id}))))))
-
-(deftest tools-call-visualize-query-test
- (testing "visualize_query echoes the inline query"
- (let [[session-id _] (initialize!)]
- (is (=? {:status 200
- :body {:result {:structuredContent {:query "ZW5jb2RlZA=="}}}}
- (mcp-request (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {:query "ZW5jb2RlZA=="}})
- {"mcp-session-id" session-id}))))))
-
-(deftest tools-call-visualize-query-test-2
- (testing "visualize_query resolves a stored handle"
- (let [user-id (mt/user->id :crowberto)
- [session-id _] (initialize!)
- handle (mt/with-current-user user-id
- (mcp.session/store-handle! session-id user-id "ZW5jb2RlZA=="))]
- (is (=? {:status 200
- :body {:result {:structuredContent {:query "ZW5jb2RlZA=="}}}}
- (mcp-request (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {:query_handle handle}})
- {"mcp-session-id" session-id}))))))
-
-(deftest tools-call-visualize-query-test-3
- (testing "visualize_query includes the prompt stored with a construct_query handle"
- ;; Mirrors master's assertion that the user's original prompt round-trips through the
- ;; construct→store→visualize flow so the iframe can include it when submitting
- ;; visualization feedback. Adapted from master's `:source`/`:operations` shape to our
- ;; branch's `:query` representations shape; the `:prompt` round-trip semantic is
- ;; preserved exactly.
- (let [[session-id _] (initialize!)
- db-name (t2/select-one-fn :name :model/Database (mt/id))
- external-query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table [db-name "PUBLIC" "ORDERS"]
- :limit 5}]}
- construct-data (call-tool session-id "construct_query"
- {:query external-query
- :prompt "show 5 orders"})
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {:query_handle (:query_handle construct-data)}})
- {"mcp-session-id" session-id})]
- (is (=? {:status 200
- :body {:result {:structuredContent {:query string?
- :prompt "show 5 orders"}}}}
- response)))))
-
-(deftest tools-call-visualize-query-test-4
- (testing "visualize_query asks for an argument when neither query nor handle is provided"
- (let [[session-id _] (initialize!)]
- (is (=? {:status 200
- :body {:result {:isError true
- :content [{:text #(str/includes? % "Provide either")}]}}}
- (mcp-request (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {}})
- {"mcp-session-id" session-id}))))))
-
-(deftest tools-call-visualize-query-test-5
- (testing "visualize_query returns 'handle not found' when query_handle is unknown"
- (let [[session-id _] (initialize!)]
- (is (=? {:status 200
- :body {:result {:isError true
- :content [{:text #(str/includes? % "Query handle not found")}]}}}
- (mcp-request (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {:query_handle (str (random-uuid))}})
- {"mcp-session-id" session-id}))))))
-
-;;; --------------------------------------- cross-session handle resolution -------------------------------------
-
-(deftest tools-expose-output-schema-test
- (testing "MCP tools/list declares outputSchema for tools that emit structuredContent"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" session-id})
- tools (get-in response [:body :result :tools])
- tools-by-name (into {} (map (juxt :name identity)) tools)]
- (testing "construct_query advertises {query_handle} as its output"
- (let [output-schema (get-in tools-by-name ["construct_query" :outputSchema])
- prop-names (set (map name (keys (:properties output-schema))))]
- (is (= "object" (:type output-schema)))
- (is (contains? prop-names "query_handle"))
- (is (not (contains? prop-names "widgetSessionId"))
- "widgetSessionId was retired in favour of cross-session per-user lookup")))
- (testing "visualize_query advertises its structuredContent shape"
- (let [output-schema (get-in tools-by-name ["visualize_query" :outputSchema])]
- (is (= "object" (:type output-schema)))
- (is (contains? (set (map name (keys (:properties output-schema)))) "query"))))
- (testing "render_drill_through advertises its structuredContent shape"
- (let [output-schema (get-in tools-by-name ["render_drill_through" :outputSchema])]
- (is (= "object" (:type output-schema)))
- (is (contains? (set (map name (keys (:properties output-schema)))) "query")))))))
-
-(deftest construct-query-returns-bare-handle-test
- (testing "construct_query returns just `{:query_handle uuid}` — no widget session plumbing"
- ;; Adapted from master's `:source`/`:operations` legacy program shape to our branch's
- ;; representations `:query` shape. The semantic — that the response is a bare handle
- ;; with no widgetSessionId field — is preserved.
- (let [[session-id _] (initialize!)
- db-name (t2/select-one-fn :name :model/Database (mt/id))
- external-query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table [db-name "PUBLIC" "ORDERS"]
- :limit 5}]}
- construct-data (call-tool session-id "construct_query"
- {:query external-query
- :prompt "show 5 orders"})]
- (is (some? (parse-uuid (:query_handle construct-data))))
- (is (not (contains? construct-data :widgetSessionId))))))
-
-(deftest visualize-query-resolves-via-cross-session-fallback-test
- (testing "visualize_query resolves a handle stored in another session of the same user — no widgetSessionId needed"
- (let [user-id (mt/user->id :crowberto)
- [owner-session _] (initialize!)
- [rotated-session _] (initialize!)
- handle (mt/with-current-user user-id
- (mcp.session/store-handle! owner-session user-id "ZW5jb2RlZA=="))]
- (is (=? {:status 200
- :body {:result {:structuredContent {:query "ZW5jb2RlZA=="}}}}
- (mcp-request (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {:query_handle handle}})
- {"mcp-session-id" rotated-session}))))))
-
-(deftest execute-query-resolves-via-cross-session-fallback-test
- (testing "execute_query resolves a handle stored in another session of the same user — no widgetSessionId needed"
- ;; Adapted from master's `:source`/`:operations` legacy program shape to our branch's
- ;; representations `:query` shape. The semantic — cross-session same-user resolution —
- ;; is preserved.
- (let [[owner-session _] (initialize!)
- [rotated-session _] (initialize!)
- db-name (t2/select-one-fn :name :model/Database (mt/id))
- external-query {:lib/type "mbql/query"
- :stages [{:lib/type "mbql.stage/mbql"
- :source-table [db-name "PUBLIC" "ORDERS"]
- :limit 5}]}
- construct-data (call-tool owner-session "construct_query"
- {:query external-query
- :prompt "show 5 orders"})
- response (mcp-request (jsonrpc-request "tools/call"
- {:name "execute_query"
- :arguments {:query_handle (:query_handle construct-data)}})
- {"mcp-session-id" rotated-session})]
- (is (= 200 (:status response)))
- (is (not (get-in response [:body :result :isError]))))))
-
-(deftest render-drill-through-resolves-via-cross-session-fallback-test
- (testing "render_drill_through resolves a handle stored in another session of the same user"
- (let [user-id (mt/user->id :crowberto)
- [owner-session _] (initialize!)
- [rotated-session _] (initialize!)
- handle (mt/with-current-user user-id
- (mcp.session/store-handle! owner-session user-id "ZW5jb2RlZA=="))]
- (is (=? {:status 200
- :body {:result {:structuredContent {:query "ZW5jb2RlZA=="}}}}
- (mcp-request (jsonrpc-request "tools/call"
- {:name "render_drill_through"
- :arguments {:handle handle}})
- {"mcp-session-id" rotated-session}))))))
-
-(deftest visualize-query-refuses-cross-user-handle-test
- (testing "visualize_query refuses to resolve another user's handle"
- (let [owner-id (mt/user->id :crowberto)
- [owner-session _] (initialize!) ;; crowberto
- ;; Fresh UUID-shaped sentinel for the stored payload so the leak
- ;; assertion below can't accidentally match against any other test fixture.
- encoded-payload (str (random-uuid))
- handle (mt/with-current-user owner-id
- (mcp.session/store-handle! owner-session owner-id encoded-payload))
- [attacker-session _] (initialize-as! :rasta)
- response (mcp-request-as :rasta
- (jsonrpc-request "tools/call"
- {:name "visualize_query"
- :arguments {:query_handle handle}})
- {"mcp-session-id" attacker-session})]
- (testing "the response is an error, NOT crowberto's encoded query"
- (is (=? {:status 200
- :body {:result {:isError true
- :content [{:text #(str/includes? % "Query handle not found")}]}}}
- response))
- (is (not= encoded-payload
- (get-in response [:body :result :structuredContent :query]))
- "cross-user handle resolution must fail")))))
-
-;;; --------------------------------------------- OAuth Bearer Auth -------------------------------------------------
-
-(deftest unauthenticated-returns-401-test
- (testing "POST without any auth returns 401 with WWW-Authenticate discovery header"
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (let [response (mcp-request-unauthenticated (jsonrpc-request "initialize"))]
- (is (=? {:status 401
- :headers {"WWW-Authenticate" #(str/includes? % "oauth-protected-resource")}}
- response))))))
-
-;;; ----------------------------------------- Canonical and legacy endpoints ---------------------------------------
-
-(deftest endpoint-alias-routing-test
- (testing "initialize succeeds (session auth) on both the canonical and legacy MCP paths"
- (doseq [path mcp-endpoint-paths]
- (testing (str "/api/" path)
- (is (=? {:status 200
- :headers {"Mcp-Session-Id" some?}
- :body {:result {:serverInfo {:name "metabase"}}}}
- (mcp-request-to path (jsonrpc-request "initialize"))))))))
-
-(deftest endpoint-alias-discovery-401-test
- (testing "unauthenticated request on each path advertises that same path as the protected resource"
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (doseq [path mcp-endpoint-paths]
- (testing (str "/api/" path)
- ;; The trailing quote pins the match to the exact path (so /api/mcp can't match /api/metabase-mcp).
- (let [expected (str "/.well-known/oauth-protected-resource/api/" path "\"")]
- (is (=? {:status 401
- :headers {"WWW-Authenticate" #(str/includes? % expected)}}
- (mcp-request-unauthenticated-to path (jsonrpc-request "initialize"))))))))))
-
-(deftest endpoint-alias-trailing-slash-discovery-test
- (testing "a trailing-slash request still advertises the matching path (not canonical fallback)"
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (let [expected "/.well-known/oauth-protected-resource/api/mcp\""]
- (is (=? {:status 401
- :headers {"WWW-Authenticate" #(str/includes? % expected)}}
- (mcp-request-unauthenticated-to "mcp/" (jsonrpc-request "initialize"))))))))
-
-(deftest endpoint-alias-bearer-token-test
- (testing "bearer-token handling is identical on the legacy path — same invalid_token 401 as canonical"
- ;; Bearer validation (validate-bearer-token) has no path logic, so reaching it via the legacy
- ;; alias must behave exactly like the canonical path. We assert the invalid-token branch since
- ;; it's deterministic and doesn't depend on minting a live token.
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (oauth-server/reset-provider!)
- (try
- (doseq [path mcp-endpoint-paths]
- (testing (str "/api/" path)
- (is (=? {:status 401
- :headers {"WWW-Authenticate" #(str/includes? % "invalid_token")}}
- (client/client-full-response
- :post 401 path
- {:request-options {:headers {"authorization" "Bearer totally-bogus-token"}}}
- (jsonrpc-request "initialize"))))))
- (finally
- (oauth-server/reset-provider!))))))
-
-(deftest invalid-bearer-token-returns-401-test
- (testing "POST with invalid bearer token returns 401 with invalid_token error"
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (oauth-server/reset-provider!)
- (try
- (let [response (mcp-request-with-bearer "totally-bogus-token" 401
- (jsonrpc-request "initialize")
- {})]
- (is (=? {:status 401
- :headers {"WWW-Authenticate" #(str/includes? % "invalid_token")}}
- response)))
- (finally
- (oauth-server/reset-provider!))))))
-
-;;; ---------------------------------------------- Resources -------------------------------------------------------
-
-(def ^:private construct-query-uri "metabase://docs/construct-query.md")
-
-(deftest resources-list-test
- (testing "resources/list returns the registered construct-query reference resource"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "resources/list")
- {"mcp-session-id" session-id})
- resources (get-in response [:body :result :resources])]
- (is (= 200 (:status response)))
- (is (=? [{:uri construct-query-uri
- :name "Construct Query Reference"
- :description string?
- :mimeType "text/markdown"}]
- (filter #(= construct-query-uri (:uri %)) resources))))))
-
-(deftest resources-read-test
- (testing "resources/read returns the markdown contents for the construct-query reference"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "resources/read"
- {:uri construct-query-uri})
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (=? {:contents [{:uri construct-query-uri
- :mimeType "text/markdown"
- :text #(str/starts-with? % "# Construct Query Reference")}]}
- (get-in response [:body :result])))))
- (testing "resources/read for an unknown URI returns -32602"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "resources/read"
- {:uri "metabase://does/not/exist"})
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (= -32602 (get-in response [:body :error :code])))))
- (testing "resources/read with missing :uri reports the missing parameter"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "resources/read" {})
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (=? {:error {:code -32602
- :message #(str/starts-with? % "Missing required parameter")}}
- (:body response)))))
- (testing "resources/read with a blank :uri reports the missing parameter (not 'Resource not found')"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "resources/read" {:uri ""})
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (=? {:error {:code -32602
- :message #(str/starts-with? % "Missing required parameter")}}
- (:body response))))))
-
-(def ^:private scoped-test-uri "test://mcp/api-test/scoped")
-
-(defn- dispatch-initialized-request [msg token-scopes]
- (let [session-id (str (random-uuid))]
- (#'mcp.api/dispatch-request msg session-id token-scopes nil nil)))
-
-(defn- with-scoped-test-resource! [f]
- (let [registry @#'mcp.resources/registry
- snapshot @registry]
- (try
- (mcp.resources/register-resource!
- {:uri scoped-test-uri
- :name "Scoped Test Resource"
- :description "Requires the agent:search scope."
- :scope "agent:search"
- :mimeType "text/plain"
- :render-fn (constantly "secret body")})
- (f)
- (finally
- (reset! registry snapshot)))))
-
-(deftest ui-resource-read-not-found-test
- (testing "resources/read returns -32602 \"Resource not found\" when caller lacks the required scope"
- (with-scoped-test-resource!
- (fn []
- (let [response (dispatch-initialized-request
- (jsonrpc-request "resources/read" {:uri scoped-test-uri})
- #{"agent:other"})]
- (is (=? {:jsonrpc "2.0"
- :id 1
- :error {:code -32602
- :message "Resource not found"}}
- response))))))
- (testing "resources/read for a scoped resource succeeds when the caller has a matching scope"
- (with-scoped-test-resource!
- (fn []
- (let [response (dispatch-initialized-request
- (jsonrpc-request "resources/read" {:uri scoped-test-uri})
- #{"agent:search"})]
- (is (=? {:result {:contents [{:uri scoped-test-uri
- :text "secret body"}]}}
- response)))))))
-
-(deftest resources-list-scope-filtering-test
- (testing "resources/list omits scoped resources the caller cannot access"
- (with-scoped-test-resource!
- (fn []
- (let [response (#'mcp.api/dispatch-request
- (jsonrpc-request "resources/list")
- "session-id"
- #{"agent:other"}
- nil
- nil)
- uris (set (map :uri (get-in response [:result :resources])))]
- (is (contains? uris construct-query-uri)
- "public construct-query reference is still listed")
- (is (not (contains? uris scoped-test-uri))
- "scoped resource must not leak via resources/list")))))
- (testing "resources/list includes scoped resources for callers with matching scope"
- (with-scoped-test-resource!
- (fn []
- (let [response (#'mcp.api/dispatch-request
- (jsonrpc-request "resources/list")
- "session-id"
- #{"agent:search"}
- nil
- nil)
- uris (set (map :uri (get-in response [:result :resources])))]
- (is (contains? uris scoped-test-uri)))))))
-
-;;; --------------------------------------------- Scope Filtering ---------------------------------------------------
-
-(deftest tools-list-scope-filtering-test
- (testing "tools/list with unrestricted scopes returns all tools"
- (let [tools (mcp.tools/list-tools #{::scope/unrestricted})]
- (is (= all-tool-names (set (map :name tools))))))
- (testing "tools/list with specific scope only returns matching tools"
- (let [tools (mcp.tools/list-tools #{"agent:search"})
- tool-names (set (map :name tools))]
- ;; Should include search (matches scope)
- (is (contains? tool-names "search"))
- ;; Should NOT include tools with other scopes
- (is (not (contains? tool-names "update_question")))
- (is (not (contains? tool-names "construct_query")))))
- (testing "tools/list with wildcard scope matches all agent and UI tools"
- (let [tools (mcp.tools/list-tools #{"agent:*"})]
- (is (= all-tool-names (set (map :name tools))))))
- (testing "tools/list with nil scopes returns all tools"
- (let [tools (mcp.tools/list-tools nil)]
- (is (= all-tool-names (set (map :name tools))))))
- (testing "tools/list with empty scopes does not return all tools"
- (let [tools (mcp.tools/list-tools #{})]
- (is (empty? tools)
- "Empty scopes should not grant access to scoped tools"))))
-
-(deftest oauth-token-scope-validation-test
- (testing "an OAuth token with a limited scope exposes only matching tools"
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (t2/with-transaction [_conn nil {:rollback-only true}]
- (oauth-server/reset-provider!)
- (oauth-server.tu/with-oauth-client [client-id]
- (let [token (str (random-uuid))]
- (save-access-token! token (mt/user->id :crowberto) client-id #{"agent:search"})
- (let [sid (-> (mcp-request-with-bearer token 200 (jsonrpc-request "initialize") {})
- (get-in [:headers "Mcp-Session-Id"]))
- response (mcp-request-with-bearer token 200 (jsonrpc-request "tools/list")
- {"mcp-session-id" sid})
- tool-names (set (map :name (get-in response [:body :result :tools])))]
- (is (contains? tool-names "search"))
- (is (not (contains? tool-names "update_question"))
- "Only matching tools should be available"))))))))
-
-(deftest full-access-token-scope-validation-test
- (testing "an OAuth token with the full-access grant exposes all tools"
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (t2/with-transaction [_conn nil {:rollback-only true}]
- (oauth-server/reset-provider!)
- (oauth-server.tu/with-oauth-client [client-id]
- (let [token (str (random-uuid))]
- (save-access-token! token (mt/user->id :crowberto) client-id #{oauth-server/full-access-scope})
- (let [sid (-> (mcp-request-with-bearer token 200 (jsonrpc-request "initialize") {})
- (get-in [:headers "Mcp-Session-Id"]))
- response (mcp-request-with-bearer token 200 (jsonrpc-request "tools/list")
- {"mcp-session-id" sid})
- tool-names (set (map :name (get-in response [:body :result :tools])))]
- (is (contains? tool-names "search"))
- (is (contains? tool-names "update_question")))))))))
-
-(deftest tools-call-token-scope-validation-test
- (testing "an OAuth token with a limited scope cannot call a tool outside that scope"
- (mt/with-temp [:model/Card {card-id :id} {:name "Scope Validation Card"
- :dataset_query (orders-count-query)
- :display :table}]
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (t2/with-transaction [_conn nil {:rollback-only true}]
- (oauth-server/reset-provider!)
- (oauth-server.tu/with-oauth-client [client-id]
- (let [token (str (random-uuid))]
- (save-access-token! token (mt/user->id :crowberto) client-id #{"agent:search"})
- (let [sid (-> (mcp-request-with-bearer token 200 (jsonrpc-request "initialize") {})
- (get-in [:headers "Mcp-Session-Id"]))
- response (mcp-request-with-bearer token 200
- (jsonrpc-request "tools/call"
- {:name "update_question"
- :arguments {:id card-id :name "Renamed by narrow token"}})
- {"mcp-session-id" sid})]
- (is (=? {:isError true} (get-in response [:body :result]))
- "update_question is outside agent:search and must be refused")
- (is (= "Scope Validation Card" (t2/select-one-fn :name :model/Card :id card-id))
- "the card must not have been renamed")))))))))
-
-(defn- insert-expired-oauth-token!
- "Insert an OAuth access token into the DB with an expiry in the past.
- Returns the token string."
- [user-id client-id]
- (let [token (str (random-uuid))
- expired (- (quot (System/currentTimeMillis) 1000) 3600)]
- (t2/insert! :model/OAuthAccessToken
- {:token token
- :user_id user-id
- :client_id client-id
- :scope ["openid"]
- :expiry expired})
- token))
-
-(deftest expired-oauth-bearer-token-returns-401-test
- (testing "POST with expired OAuth bearer token returns 401"
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (t2/with-transaction [_conn nil {:rollback-only true}]
- (oauth-server/reset-provider!)
- ;; register a live client so the expiry is the only thing rejecting the token
- (oauth-server.tu/with-oauth-client [client-id]
- (let [user-id (mt/user->id :crowberto)
- token (insert-expired-oauth-token! user-id client-id)
- response (mcp-request-with-bearer token 401
- (jsonrpc-request "initialize")
- {})]
- (is (=? {:status 401
- :headers {"WWW-Authenticate" #(str/includes? % "invalid_token")}}
- response))))))))
-
-(deftest tools-call-scope-enforcement-test
- (mt/with-temp [:model/Card {card-id :id} {:name "Scope Test Card"
- :dataset_query (orders-count-query)
- :display :table}]
- (testing "tool call is rejected when token scopes don't include the required scope"
- (let [result (mt/with-current-user (mt/user->id :crowberto)
- (mcp.tools/call-tool #{"agent:search"} nil "update_question"
- {:id card-id :name "Renamed"}))]
- (is (=? {:isError true} result))
- (is (str/includes? (-> result :content first :text) "Insufficient scope")
- "Scope enforcement error from defendpoint middleware")))
- (testing "tool call with matching scope is not rejected by scope enforcement"
- (let [result (mt/with-current-user (mt/user->id :crowberto)
- (mcp.tools/call-tool #{"agent:question:update"} nil "update_question"
- {:id card-id :name "Renamed Again"}))]
- (is (not (:isError result)))))
- (testing "tool call with empty scopes is rejected for scoped tools"
- (let [result (mt/with-current-user (mt/user->id :crowberto)
- (mcp.tools/call-tool #{} nil "update_question"
- {:id card-id :name "Nope"}))]
- (is (=? {:isError true} result))
- (is (str/includes? (-> result :content first :text) "Insufficient scope")
- "Scope enforcement error from defendpoint middleware"))))
- (testing "scope failures take precedence over missing client extensions"
- (let [result (mt/with-current-user (mt/user->id :crowberto)
- (mcp.tools/call-tool #{} nil "visualize_query" {:query "card__1"} {:supports-mcp-ui? false}))
- message (-> result :content first :text)]
- (is (=? {:isError true} result))
- (is (str/includes? message "Insufficient scope"))
- (is (not (str/includes? message "requires a client that supports MCP Apps UI"))))))
-
-(deftest check-resource-access-test
- (testing "returns :ok for a known URI with matching scope"
- (is (= :ok (mcp.resources/check-resource-access "ui://metabase/visualize-query.html" #{"agent:viz:mcp-ui:query"}))))
- (testing "returns :ok with wildcard scope"
- (is (= :ok (mcp.resources/check-resource-access "ui://metabase/visualize-query.html" #{"agent:*"}))))
- (testing "returns :scope-denied for a known URI with non-matching scope"
- (is (= :scope-denied (mcp.resources/check-resource-access "ui://metabase/visualize-query.html" #{"agent:search"}))))
- (testing "returns :scope-denied for a known URI with empty scopes"
- (is (= :scope-denied (mcp.resources/check-resource-access "ui://metabase/visualize-query.html" #{}))))
- (testing "returns :not-found for an unknown URI"
- (is (= :not-found (mcp.resources/check-resource-access "ui://metabase/nonexistent.html" #{"agent:*"})))))
-
-(deftest resources-read-scope-denied-test
- (testing "resources/read returns -32602 for unknown URI"
- (let [[session-id _] (initialize!)
- response (mcp-request (jsonrpc-request "resources/read"
- {:uri "ui://metabase/nonexistent.html"})
- {"mcp-session-id" session-id})]
- (is (= 200 (:status response)))
- (is (= -32602 (get-in response [:body :error :code])))
- (is (= "Resource not found"
- (get-in response [:body :error :message]))))))
-
-(deftest agent-api-preserves-token-scopes-test
- (testing "scoped token restrictions are enforced by the Agent API layer (defense-in-depth)"
- (mt/with-temp [:model/Card {card-id :id} {:name "Scope Probe Card"
- :dataset_query (orders-count-query)
- :display :table}]
- (testing "restricted scopes that don't match the endpoint are rejected by Agent API"
- (let [result (mt/with-current-user (mt/user->id :crowberto)
- ;; Bypass the MCP scope check by calling invoke-agent-api directly
- ;; with scopes that don't match the endpoint's required scope (agent:question:update)
- (#'mcp.tools/invoke-agent-api :put (str "/v1/question/" card-id) #{"agent:search"}
- {:name "Probe"}))]
- (is (=? {:isError true} result)
- "Agent API should reject when token scopes don't include the required scope")))
- (testing "matching scopes are accepted by Agent API"
- (let [result (mt/with-current-user (mt/user->id :crowberto)
- (#'mcp.tools/invoke-agent-api :put (str "/v1/question/" card-id) #{"agent:question:update"}
- {:name "Probe"}))]
- (is (not (:isError result))
- "Agent API should accept when token scopes include the required scope")))
- (testing "unrestricted scopes are accepted by Agent API"
- (let [result (mt/with-current-user (mt/user->id :crowberto)
- (#'mcp.tools/invoke-agent-api :put (str "/v1/question/" card-id) #{::scope/unrestricted}
- {:name "Probe"}))]
- (is (not (:isError result))
- "Agent API should accept unrestricted scopes"))))))
-
-(deftest mcp-does-not-depend-on-external-agent-api-setting-test
- (testing "MCP tool calls still work when the external Agent API is disabled"
- (mt/with-temporary-setting-values [agent-api.settings/agent-api-enabled? false]
- (let [result (mt/with-current-user (mt/user->id :crowberto)
- (mcp.tools/call-tool #{::scope/unrestricted} nil "read_resource"
- {:uris ["metabase://databases"]}))]
- (is (not (:isError result)))))))
-
-;;; ------------------------------------------------- Throttling ---------------------------------------------------
-
-(deftest mcp-throttle-returns-429-test
- (testing "MCP endpoint returns 429 with JSON-RPC error when rate-limited"
- (let [[session-id _] (initialize!)]
- ;; Replace throttler after initialization so the handshake doesn't consume attempts
- (with-redefs [mcp.api/mcp-throttler (throttle/make-throttler :user-id :attempts-threshold 1)]
- ;; First request succeeds (consumes the single attempt)
- (is (= 200 (:status (mcp-request (jsonrpc-request "ping")
- {"mcp-session-id" session-id}))))
- ;; Second request should be throttled
- (is (=? {:status 429
- :headers {"Retry-After" string?}
- :body {:jsonrpc "2.0"
- :error {:code -32000
- :message #(str/starts-with? % "Too many attempts!")}}}
- (mcp-request (jsonrpc-request "ping")
- {"mcp-session-id" session-id})))))))
-
-;;; -------------------------------------------- Session Lifecycle -------------------------------------------------
-
-(deftest resources-read-renders-ui-configuration-test
- (testing "UI resources contain stable configuration without a short-lived credential"
- (let [[session-id _] (initialize!)
- read1 (mcp-request (jsonrpc-request "resources/read"
- {:uri "ui://metabase/visualize-query.html"} 1)
- {"mcp-session-id" session-id})
- read2 (mcp-request (jsonrpc-request "resources/read"
- {:uri "ui://metabase/visualize-query.html"} 2)
- {"mcp-session-id" session-id})]
- (is (= 200 (:status read1)))
- (is (= 200 (:status read2)))
- ;; The resource is safe to cache because it contains only stable configuration.
- (let [html1 (-> (get-in read1 [:body :result :contents]) first :text)
- html2 (-> (get-in read2 [:body :result :contents]) first :text)]
- (is (some? html1))
- (is (not (str/includes? html1 "uiCredential")))
- (is (not (str/includes? html2 "uiCredential")))
- (is (not (str/includes? html1 "mcpSessionId")))
- (is (not (str/includes? html2 "mcpSessionId")))
- (is (not (str/includes? html1 "refreshTool")))
- (is (not (str/includes? html2 "refreshTool")))))))
-
-(deftest mcp-ui-credential-validation-test
- (testing "an app-only refresh tool provides the scoped UI request surface, but not general API access"
- (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
- (t2/with-transaction [_conn nil {:rollback-only true}]
- (oauth-server/reset-provider!)
- (oauth-server.tu/with-oauth-client [client-id]
- (let [token (str (random-uuid))
- _ (save-access-token! token (mt/user->id :crowberto) client-id #{"agent:viz:mcp-ui:query"})
- initialize (mcp-request-with-bearer token 200 (jsonrpc-request "initialize" {:capabilities mcp-app-ui-capabilities}) {})
- session-id (get-in initialize [:headers "Mcp-Session-Id"])
- tool-result (mcp-request-with-bearer token 200
- (jsonrpc-request "tools/call"
- {:name "refresh_ui_credential"
- :arguments {}})
- {"mcp-session-id" session-id})
- credential (get-in tool-result [:body :result :_meta :com.metabase/mcp-apps :credential])
- headers {"x-metabase-mcp-ui-auth" credential}]
- (is (string? credential))
- (is (= 200 (:status (client/client-full-response :get 200 "user/current"
- {:request-options {:headers headers}}))))
- (is (= 401 (:status (client/client-full-response :get 401 "collection"
- {:request-options {:headers headers}}))))))))))
-
-(deftest batch-initialized-then-resources-read-test
- (testing "batch containing notifications/initialized + resources/read succeeds"
- (let [response (mcp-request (jsonrpc-request "initialize"))
- session-id (get-in response [:headers "Mcp-Session-Id"])
- batch-response (mcp-request [(jsonrpc-notification "notifications/initialized")
- (jsonrpc-request "resources/read"
- {:uri "ui://metabase/visualize-query.html"} 1)]
- {"mcp-session-id" session-id})]
- (is (=? {:status 200
- :body [{:id 1
- :result {:contents some?}}]}
- batch-response)))))
diff --git a/test/metabase/mcp/callback_api_test.clj b/test/metabase/mcp/callback_api_test.clj
index ecc3d77c75f..2be038b215f 100644
--- a/test/metabase/mcp/callback_api_test.clj
+++ b/test/metabase/mcp/callback_api_test.clj
@@ -62,7 +62,7 @@
(testing "session owned by a different user returns 404"
(let [owner (mt/user->id :crowberto)
session (mcp.session/create! owner)
- _ (mcp.session/get-or-create-session-key! session owner)]
+ _ (mcp.session/get-or-create-embedding-session! session owner)]
(is (=? {:status 404}
(post-drill :rasta 404 {:encodedQuery "ZW5jb2RlZA=="}
{"mcp-session-id" session}))))))
@@ -71,7 +71,8 @@
(let [user-id (mt/user->id :crowberto)
credential-id (mcp.session/create! user-id)
other-session-id (mcp.session/create! user-id)
- credential (mcp.session/issue-ui-credential credential-id user-id)]
+ ;; v1's claimless 2-arity retired with v1; the callback surface takes a scoped credential now.
+ credential (mcp.session/issue-ui-credential credential-id user-id #{"agent:query:run"})]
(testing "a credential can use the callback surface for its own MCP session"
(is (= 200 (:status (post-drill-with-ui-credential 200 credential credential-id)))))
(testing "a credential cannot be reused with another MCP session"
@@ -81,7 +82,7 @@
(with-redefs [mcp.session/ui-credential-lifetime-seconds -1]
(is (= 401 (:status (post-drill-with-ui-credential
401
- (mcp.session/issue-ui-credential credential-id user-id)
+ (mcp.session/issue-ui-credential credential-id user-id #{"agent:query:run"})
credential-id))))))))
(deftest drills-post-rejects-blank-body-test
@@ -174,6 +175,129 @@
(is (=? {:status 404}
(post-mcp-feedback :rasta 404 body "not-a-uuid")))
(let [owner-session (mcp.session/create! (mt/user->id :crowberto))]
- (mcp.session/get-or-create-session-key! owner-session (mt/user->id :crowberto))
+ (mcp.session/get-or-create-embedding-session! owner-session (mt/user->id :crowberto))
(is (=? {:status 404}
(post-mcp-feedback :rasta 404 body owner-session)))))))
+
+;;; ------------------------------------------------- Bootstrap --------------------------------------------------
+
+(defn- get-bootstrap
+ ([user expected-status session-id]
+ (client/client-full-response (test.users/username->token user)
+ :get expected-status "embed-mcp/bootstrap"
+ {:request-options {:headers {"mcp-session-id" session-id}}}))
+ ([user expected-status]
+ (client/client-full-response (test.users/username->token user)
+ :get expected-status "embed-mcp/bootstrap")))
+
+(defn- get-bootstrap-with-ui-credential
+ [expected-status credential session-id]
+ (client/client-full-response :get expected-status "embed-mcp/bootstrap"
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential
+ "mcp-session-id" session-id}}}))
+
+(defn- bootstrap-for!
+ [user]
+ (:body (get-bootstrap user 200 (mcp.session/create! (mt/user->id user)))))
+
+(deftest bootstrap-user-projection-test
+ (testing "GHY-4400: the bootstrap user is a fixed projection, not whatever `GET /api/user/current` returns"
+ (doseq [username [:crowberto :rasta]]
+ (testing username
+ (let [user (:user (bootstrap-for! username))]
+ (is (= #{:id :locale :is_superuser :is_data_analyst :is_qbnewb
+ :tenant_id :personal_collection_id :permissions}
+ (set (keys user)))
+ "Adding a field here must be a deliberate edit to ::bootstrap-user, not an accident")
+ (is (= (mt/user->id username) (:id user)))
+ (is (some? (:personal_collection_id user))
+ "hydrated, not merely schema-optional — the iframe's collection picker reads it")
+ (is (= #{:can_create_queries :can_create_native_queries}
+ (set (keys (:permissions user))))))))
+ (testing "the projection still reports who the user is"
+ (is (true? (:is_superuser (:user (bootstrap-for! :crowberto)))))
+ (is (false? (:is_superuser (:user (bootstrap-for! :rasta))))))))
+
+(deftest bootstrap-omits-admin-only-settings-test
+ (testing "GHY-4400: an admin's credential reads only the settings a non-admin would, so a narrow MCP scope cannot
+ widen into instance configuration"
+ (let [admin-settings (:settings (bootstrap-for! :crowberto))]
+ (is (contains? (mt/user-http-request :crowberto :get 200 "session/properties")
+ :custom-geojson-enabled)
+ "`custom-geojson-enabled` is admin-visible, so it anchors this test only while it reaches admins")
+ (is (not (contains? admin-settings :custom-geojson-enabled)))
+ (is (contains? admin-settings :site-locale)
+ "Settings a non-admin may read are still served")
+ (is (= (set (keys (:settings (bootstrap-for! :rasta))))
+ (set (keys admin-settings)))
+ "the projection is the same whoever holds the credential"))))
+
+(deftest bootstrap-validates-session-header-test
+ (testing "bootstrap validates the MCP session header like the other callback routes"
+ (is (=? {:status 400} (get-bootstrap :rasta 400)))
+ (is (=? {:status 404} (get-bootstrap :rasta 404 "not-a-uuid")))
+ (testing "a session owned by another user is rejected"
+ (let [owner-session (mcp.session/create! (mt/user->id :crowberto))]
+ (mcp.session/get-or-create-embedding-session! owner-session (mt/user->id :crowberto))
+ (is (=? {:status 404} (get-bootstrap :rasta 404 owner-session)))))))
+
+(deftest bootstrap-accepts-ui-credential-test
+ (testing "the UI credential can bootstrap the iframe, and only for its own MCP session"
+ (let [user-id (mt/user->id :crowberto)
+ credential-id (mcp.session/create! user-id)
+ other-session-id (mcp.session/create! user-id)
+ credential (mcp.session/issue-ui-credential credential-id user-id #{"agent:query:run"})]
+ (is (=? {:status 200 :body {:user {:id user-id}}}
+ (get-bootstrap-with-ui-credential 200 credential credential-id)))
+ (is (= 404 (:status (get-bootstrap-with-ui-credential 404 credential other-session-id))))
+ (is (= 401 (:status (get-bootstrap-with-ui-credential 401 "not-a-credential" credential-id)))))))
+;;; --------------------------------------- GET /queries/:handle ---------------------------------------------
+
+(defn- get-query-by-handle
+ "GET /api/embed-mcp/queries/:handle with a UI credential, the way the iframe calls it."
+ [expected-status credential session-id handle]
+ (client/client-full-response :get expected-status (str "embed-mcp/queries/" handle)
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential
+ "mcp-session-id" session-id}}}))
+
+(deftest queries-get-resolves-handle-test
+ (testing "the iframe exchanges a handle for the encoded query and its prompt"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id)
+ credential (mcp.session/issue-ui-credential session-id user-id #{"agent:query:run"})
+ handle (mcp.session/store-handle! session-id user-id "ZW5jb2RlZA==" "show me orders")]
+ (is (=? {:status 200
+ :body {:query "ZW5jb2RlZA==" :prompt "show me orders"}}
+ (get-query-by-handle 200 credential session-id handle))))))
+ (testing "a handle stored without a prompt resolves with a nil one"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id)
+ credential (mcp.session/issue-ui-credential session-id user-id #{"agent:query:run"})
+ handle (mcp.session/store-handle! session-id user-id "ZW5jb2RlZA==")]
+ (is (=? {:status 200
+ :body {:query "ZW5jb2RlZA==" :prompt nil}}
+ (get-query-by-handle 200 credential session-id handle)))))))
+
+(deftest queries-get-is-user-scoped-test
+ (testing "a handle minted by another user is not resolvable, even with a valid credential"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [owner-id (mt/user->id :crowberto)
+ owner-session (mcp.session/create! owner-id)
+ handle (mcp.session/store-handle! owner-session owner-id "ZW5jb2RlZA==")
+ other-id (mt/user->id :rasta)
+ other-session (mcp.session/create! other-id)
+ other-cred (mcp.session/issue-ui-credential other-session other-id #{"agent:query:run"})]
+ (is (= 404 (:status (get-query-by-handle 404 other-cred other-session handle))))))))
+
+(deftest queries-get-rejects-bad-input-test
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id)
+ credential (mcp.session/issue-ui-credential session-id user-id #{"agent:query:run"})]
+ (testing "an unknown handle is a 404, not a 500"
+ (is (= 404 (:status (get-query-by-handle 404 credential session-id (str (random-uuid)))))))
+ (testing "a non-UUID handle never reaches the route: the credential allowlist is UUID-pinned"
+ (is (= 401 (:status (get-query-by-handle 401 credential session-id "not-a-uuid")))))
+ (testing "an invalid credential is rejected"
+ (is (= 401 (:status (get-query-by-handle 401 "not-a-credential" session-id (str (random-uuid)))))))))
diff --git a/test/metabase/mcp/db_test.clj b/test/metabase/mcp/db_test.clj
new file mode 100644
index 00000000000..8e5108eb19f
--- /dev/null
+++ b/test/metabase/mcp/db_test.clj
@@ -0,0 +1,59 @@
+(ns metabase.mcp.db-test
+ (:require
+ [clojure.test :refer [are deftest is testing use-fixtures]]
+ [metabase.mcp.db :as mcp.db]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(deftest ^:parallel user-id->tenant-id-refuses-non-integer-ids-test
+ (testing "the ids are spliced into an `[:in …]` clause, and HoneySQL renders a non-numeric element as SQL
+ rather than binding it as a parameter — so a string, a raw form or a nested query reaching this
+ fn is an injection vector, not merely a type error. The guard refuses everything that is not an
+ integer id, and refuses it before any SQL is built."
+ (testing "a collection carrying anything but integers"
+ (are [ids] (thrown-with-msg? clojure.lang.ExceptionInfo
+ #"user ids must be a collection of integers"
+ (mcp.db/user-id->tenant-id ids))
+ ["1"]
+ [:1]
+ [nil]
+ [1.5]
+ [1M]
+ ;; the shapes HoneySQL reads as syntax rather than as a value: a vector is a function call
+ ;; (`[:raw …]` renders verbatim, `[:inline …]` inlines a literal), a map is a subquery, and a
+ ;; keyword is an identifier. These are the injection vectors the guard exists for.
+ [[:raw "1) OR 1=1 --"]]
+ [[:inline "1) OR 1=1 --"]]
+ [{:select [:id] :from [:core_user]}]
+ ['user_id]
+ ;; one bad element among good ones is still refused
+ [1 2 "3"]))
+ (testing "a value that is not a collection at all"
+ (are [ids] (thrown-with-msg? clojure.lang.ExceptionInfo
+ #"user ids must be a collection of integers"
+ (mcp.db/user-id->tenant-id ids))
+ 1
+ "1"
+ nil
+ :ids))
+ (testing "the offending values ride ex-data rather than the message, so nothing caller-controlled
+ lands in a log line"
+ (is (= {:invalid ["1"]}
+ (select-keys (ex-data (try (mcp.db/user-id->tenant-id [1 "1"])
+ (catch clojure.lang.ExceptionInfo e e)))
+ [:invalid]))))))
+
+(deftest user-id->tenant-id-test
+ (testing "integer ids are accepted and resolved to their tenants"
+ (let [rasta (mt/user->id :rasta)
+ crowberto (mt/user->id :crowberto)]
+ (is (= {rasta nil crowberto nil}
+ (mcp.db/user-id->tenant-id [rasta crowberto])))))
+ (testing "an empty collection asks nothing of the database — `[:in ()]` is not valid SQL"
+ (are [ids] (= {} (mcp.db/user-id->tenant-id ids))
+ []
+ #{})))
diff --git a/test/metabase/mcp/resources_test.clj b/test/metabase/mcp/resources_test.clj
deleted file mode 100644
index e952e76fed7..00000000000
--- a/test/metabase/mcp/resources_test.clj
+++ /dev/null
@@ -1,227 +0,0 @@
-(ns metabase.mcp.resources-test
- (:require
- [clojure.string :as str]
- [clojure.test :refer :all]
- [metabase.api.macros.scope :as scope]
- [metabase.config.core :as config]
- [metabase.mcp.resources :as mcp.resources]
- [metabase.request.core :as request]
- [metabase.system.core :as system]
- [stencil.core :as stencil]))
-
-(set! *warn-on-reflection* true)
-
-(def ^:private private-uri "test://mcp/resources-test/private")
-(def ^:private public-uri "test://mcp/resources-test/public")
-
-;; The registry is process-wide state; the fixture snapshots and restores it around each test.
-;; Safe because none of the tests below are marked ^:parallel.
-#_{:clj-kondo/ignore [:metabase/validate-deftest]}
-(use-fixtures :each
- (fn [thunk]
- (let [registry @#'mcp.resources/registry
- snapshot @registry]
- (try
- (mcp.resources/register-resource!
- {:uri public-uri
- :name "Public Doc"
- :description "Anyone authenticated can read this."
- :mimeType "text/plain"
- :render-fn (constantly "public body")})
- (mcp.resources/register-resource!
- {:uri private-uri
- :name "Private Doc"
- :description "Requires the agent:search scope."
- :scope "agent:search"
- :mimeType "text/plain"
- :render-fn (constantly "private body")})
- (thunk)
- (finally
- (reset! registry snapshot))))))
-
-(deftest list-resources-public-and-scoped-test
- (testing "scopeless resources are listed for any caller, including empty scopes"
- (let [uris (set (map :uri (:resources (mcp.resources/list-resources #{}))))]
- (is (contains? uris public-uri))
- (is (not (contains? uris private-uri)))))
- (testing "scoped resources are listed only when the token-scopes match"
- (let [uris (set (map :uri (:resources (mcp.resources/list-resources #{"agent:search"}))))]
- (is (contains? uris public-uri))
- (is (contains? uris private-uri))))
- (testing "::scope/unrestricted token-scopes always match"
- (let [uris (set (map :uri (:resources (mcp.resources/list-resources #{::scope/unrestricted}))))]
- (is (contains? uris public-uri))
- (is (contains? uris private-uri)))))
-
-(deftest read-resource-test
- (testing "scopeless resources render :ok with the contents payload for any caller"
- (is (=? {:status :ok
- :contents [{:uri public-uri
- :mimeType "text/plain"
- :text "public body"}]}
- (mcp.resources/read-resource public-uri #{} {}))))
- (testing "scoped resources require a matching token-scope"
- (is (=? {:status :scope-denied}
- (mcp.resources/read-resource private-uri #{"agent:other"} {})))
- (is (=? {:status :ok :contents [{:text "private body"}]}
- (mcp.resources/read-resource private-uri #{"agent:search"} {})))
- (is (=? {:status :ok}
- (mcp.resources/read-resource private-uri #{"agent:*"} {}))))
- (testing "::scope/unrestricted token-scopes match scoped resources"
- (is (=? {:status :ok}
- (mcp.resources/read-resource private-uri #{::scope/unrestricted} {}))))
- (testing "unknown URIs return :not-found regardless of scope"
- (is (=? {:status :not-found}
- (mcp.resources/read-resource "test://nope" #{::scope/unrestricted} {})))))
-
-(deftest redact-ui-credential-test
- (testing "the top-level UI credential is removed without walking or removing other metadata"
- (is (= {:_meta {:ui {:resourceUri "ui://metabase/example.html"}}}
- (mcp.resources/redact-ui-credential
- {:_meta {:ui {:resourceUri "ui://metabase/example.html"}
- :com.metabase/mcp-apps {:credential "secret"}}}))))
- (testing "a result without private metadata is unchanged"
- (is (= {:content [{:type "text", :text "large result"}]}
- (mcp.resources/redact-ui-credential
- {:content [{:type "text", :text "large result"}]})))))
-
-(deftest register-ui-tool-validates-visibility-test
- (testing "the multi-resource registration path rejects misspelled visibility values"
- (is (thrown?
- Exception
- (#'mcp.resources/register-ui-tool-for-resources!
- [:visualize-query :render-drill-through]
- {:name "invalid_visibility_test"
- :description "Never registered"
- :inputSchema [:map]
- :visibility ["apps"]
- :response-fn (constantly {})})))))
-
-(deftest refresh-ui-credential-requires-authenticated-session-test
- (testing "missing authentication context is returned as a tool error"
- (is (= {:content [{:type "text"
- :text "MCP UI credential refresh requires an authenticated MCP session."}]
- :isError true}
- (#'mcp.resources/with-ui-credential
- {:content [{:type "text", :text "MCP UI credential refreshed."}]}
- nil)))))
-
-(deftest builtin-construct-query-resource-test
- (testing "the construct-query reference is registered as a public markdown resource"
- (is (=? {:uri "metabase://docs/construct-query.md"
- :mimeType "text/markdown"
- :name "Construct Query Reference"}
- (some #(when (= "metabase://docs/construct-query.md" (:uri %)) %)
- (:resources (mcp.resources/list-resources #{})))))))
-
-(deftest builtin-ui-resource-prefers-border-test
- (testing "the visualize query UI resource explicitly asks the host to provide a border"
- (let [uri "ui://metabase/visualize-query.html"]
- (mcp.resources/with-fallback-template
- (is (=? {:status :ok
- :contents [{:uri uri
- :mimeType "text/html;profile=mcp-app"
- :_meta {:ui {:prefersBorder true}}}]}
- (mcp.resources/read-resource uri
- #{"agent:viz:mcp-ui:query"}
- {})))))
- (is (= :scope-denied
- (mcp.resources/check-resource-access
- "ui://metabase/visualize-query.deadbeef.html"
- #{"agent:search"})))))
-
-(deftest builtin-ui-resource-supports-compatible-uris-test
- (testing "legacy and future build-hashed URIs resolve without being advertised"
- (doseq [uri ["ui://metabase/visualize-query-v2.html"
- "ui://metabase/visualize-query.deadbeef.html"]]
- (mcp.resources/with-fallback-template
- (is (=? {:status :ok
- :contents [{:uri uri}]}
- (mcp.resources/read-resource uri
- #{"agent:viz:mcp-ui:query"}
- {}))))))
- (testing "canonical and compatible URIs produce byte-distinct HTML"
- (mcp.resources/with-fallback-template
- (let [read-html (fn [uri]
- (-> (mcp.resources/read-resource uri
- #{"agent:viz:mcp-ui:query"}
- {})
- :contents first :text))]
- (is (not= (read-html "ui://metabase/visualize-query.html")
- (read-html "ui://metabase/visualize-query.deadbeef.html")))))))
-
-(deftest drill-through-ui-resource-is-distinct-from-visualize-query-test
- (testing "render_drill_through has its own UI resource URI (ChatGPT dedupes the iframe by `_meta.ui.resourceUri`; sharing the URI prevents a fresh widget from mounting on drill)"
- (let [uris (set (map :uri (:resources (mcp.resources/list-resources #{"agent:viz:*"}))))]
- (is (contains? uris "ui://metabase/visualize-query.html"))
- (is (contains? uris "ui://metabase/render-drill-through.html"))
- (is (not (contains? uris "ui://metabase/visualize-query.deadbeef.html")))))
- (testing "the two UI resources return byte-distinct HTML (ChatGPT's asset CDN appears to dedupe by body hash, so identical bodies cause the second asset to silently 404)"
- (mcp.resources/with-fallback-template
- (let [viz-html (-> (mcp.resources/read-resource "ui://metabase/visualize-query.html"
- #{"agent:viz:mcp-ui:query"} {})
- :contents first :text)
- drill-html (-> (mcp.resources/read-resource "ui://metabase/render-drill-through.html"
- #{"agent:viz:mcp-ui:drill-through"} {})
- :contents first :text)]
- (is (string? viz-html))
- (is (string? drill-html))
- (is (not= viz-html drill-html)
- "visualize-query and render-drill-through HTML must differ byte-wise")))))
-
-(deftest builtin-visualize-query-ui-resource-metadata-test
- (testing "the visualize_query UI resource publishes bare origins; :domain is gated on the ChatGPT client"
- ;; site-url is set with a subpath to confirm `_meta.ui.domain` and the CSP domain lists strip the
- ;; path — ChatGPT's MCP host treats those fields as origins and would otherwise reject the value.
- ;; `:domain` itself is only emitted for ChatGPT — Claude validates it against its own
- ;; `*.claudemcpcontent.com` namespace and rejects anything else, so the field is suppressed for
- ;; non-ChatGPT clients (detected via the in-flight request's User-Agent header).
- (let [site-url "https://metabase.example.com/sub/path"
- origin "https://metabase.example.com"
- uri "ui://metabase/visualize-query.html"
- read-ui (fn []
- (mcp.resources/with-fallback-template
- (mcp.resources/read-resource uri #{"agent:viz:mcp-ui:query"} {})))]
- (with-redefs [system/site-url (constantly site-url)]
- (testing "no request bound → CSP origins still emitted, :domain suppressed"
- (with-redefs [config/is-dev? false]
- (let [ui-meta (-> (read-ui) :contents first :_meta :ui)]
- (is (=? {:prefersBorder true
- :csp {:baseUriDomains [origin]
- :connectDomains [origin]
- :resourceDomains [origin]}}
- ui-meta))
- (is (not (contains? ui-meta :domain))))))
- (testing "development metadata allows resources from the frontend dev server"
- (with-redefs [config/is-dev? true]
- (is (=? {:csp {:baseUriDomains [origin]
- :resourceDomains [origin "http://localhost:8080"]}}
- (-> (read-ui) :contents first :_meta :ui)))))
- (testing "non-ChatGPT User-Agent → :domain suppressed"
- (with-redefs [config/is-dev? false]
- (request/with-current-request {:headers {"user-agent" "claude-ai/0.1.0"}}
- (let [ui-meta (-> (read-ui) :contents first :_meta :ui)]
- (is (not (contains? ui-meta :domain)))))))
- (testing "ChatGPT User-Agent (`openai-mcp/...`) → :domain = origin"
- (with-redefs [config/is-dev? false]
- (request/with-current-request {:headers {"user-agent" "openai-mcp/1.0.0 (ChatGPT)"}}
- (is (=? {:status :ok
- :contents [{:uri uri
- :mimeType "text/html;profile=mcp-app"
- :_meta {:ui {:prefersBorder true
- :domain origin
- :csp {:baseUriDomains [origin]
- :connectDomains [origin]
- :resourceDomains [origin]}}}}]}
- (read-ui))))))))))
-
-(deftest embed-mcp-template-base-url-test
- (testing "the MCP iframe document resolves relative bundle assets from the Metabase instance"
- (let [site-url "https://metabase.example.com/sub/path"
- html (stencil/render-file
- "frontend_client/mcp_apps_template.html"
- {:instanceUrl "\"https://metabase.example.com/sub/path\""
- :instanceUrlRaw site-url})]
- (is (str/includes? html "<base href=\"https://metabase.example.com/sub/path/\""))
- (is (not (str/includes? html "uiCredential")))
- (is (not (str/includes? html "mcpSessionId"))))))
diff --git a/test/metabase/mcp/session_test.clj b/test/metabase/mcp/session_test.clj
index dc723e0b4eb..32d7f4fc8ad 100644
--- a/test/metabase/mcp/session_test.clj
+++ b/test/metabase/mcp/session_test.clj
@@ -2,8 +2,9 @@
(:require
[clojure.string :as str]
[clojure.test :refer :all]
- [metabase.events.core :as events]
+ [metabase.api.macros.scope :as scope]
[metabase.mcp.session :as mcp.session]
+ [metabase.metabot.scope :as metabot.scope]
[metabase.session.core :as session]
[metabase.test :as mt]
[metabase.test.fixtures :as fixtures]
@@ -20,33 +21,38 @@
(defn- derived-hash
"Derives the embedding session key from an MCP session id, then hashes it."
[session-id]
- (session/hash-session-key (mcp.session/derive-embedding-session-key session-id)))
+ (session/hash-session-key (@#'mcp.session/derive-embedding-session-key session-id)))
(defn- session-correlator
[session-id]
(first (str/split session-id #"\.")))
(defn- extended-session-id
+ "A session id carrying an arbitrary capability `payload`, SIGNED as the server would sign it.
+
+ Signed deliberately: the tests using this exercise payload shape and version handling, and an unsigned id
+ would fail them for the unrelated reason that its claim is not believed at all. Forging an UNSIGNED payload
+ is what `mcp-ui-capability-claim-must-be-signed-test` covers."
[payload]
- (str (random-uuid)
- "."
- (->> (.getBytes (json/encode payload) StandardCharsets/UTF_8)
- (.encodeToString (.withoutPadding (Base64/getUrlEncoder))))))
+ (let [uuid (str (random-uuid))
+ encoded (->> (.getBytes (json/encode payload) StandardCharsets/UTF_8)
+ (.encodeToString (.withoutPadding (Base64/getUrlEncoder))))]
+ (str uuid "." encoded "." (@#'mcp.session/session-payload-signature uuid encoded))))
(deftest create-returns-uuid-string-test
(testing "create! returns a session id with a UUID correlator without writing to the database"
- (let [session-id (mcp.session/create! (mt/user->id :crowberto))]
+ (let [session-id (mcp.session/create! (mt/user->id :crowberto) nil)]
(is (string? session-id))
(is (some? (parse-uuid (session-correlator session-id))))
(is (not (t2/exists? :core_session :key_hashed (derived-hash session-id)))
"No core_session should exist yet"))))
(deftest session-ui-capability-is-stateless-test
- (testing "create! encodes MCP Apps UI support in an unsigned client capability hint"
+ (testing "create! encodes MCP Apps UI support in a signed client capability hint"
(let [ui-session-id (mcp.session/create! (mt/user->id :crowberto) {:supports-mcp-ui? true})
plain-session-id (mcp.session/create! (mt/user->id :crowberto) {:supports-mcp-ui? false})]
- (is (= 2 (count (str/split ui-session-id #"\.")))
- "New MCP session ids should include a UUID correlator and a base64url JSON capability hint")
+ (is (= 3 (count (str/split ui-session-id #"\.")))
+ "New MCP session ids are <uuid>.<base64url JSON capability hint>.<signature over both>")
(is (some? (parse-uuid (session-correlator ui-session-id))))
(is (true? (mcp.session/supports-mcp-ui? ui-session-id)))
(is (false? (mcp.session/supports-mcp-ui? plain-session-id)))
@@ -56,18 +62,72 @@
"Capability tracking should not materialize a core_session"))))
(deftest create-session-id-length-test
- (testing "generated session ids fit the persisted mcp_query_handle.mcp_session_id column"
- (is (<= (count (mcp.session/create! (mt/user->id :crowberto) {:supports-mcp-ui? true})) 254)))
- (testing "payload growth fails early in dev and tests"
- (mt/with-dynamic-fn-redefs [mcp.session/encode-session-payload (fn [_payload]
- (apply str (repeat 300 "x")))]
- (is (thrown-with-msg? AssertionError
- #"MCP session id is too long"
- (mcp.session/create! (mt/user->id :crowberto) {:supports-mcp-ui? true}))))))
+ (testing "generated session ids fit the persisted mcp_query_handle.mcp_session_id column (254)"
+ ;; Exhaustive, not a sample: the correlator is a fixed-width UUID and `create-session-id`
+ ;; collapses its argument to `(true? supports-mcp-ui?)`, so these three calls cover every
+ ;; payload the encoder can produce. Payload growth that breaks the column fails here.
+ (doseq [metadata [{:supports-mcp-ui? true} {:supports-mcp-ui? false} nil]]
+ (is (<= (count (mcp.session/create! (mt/user->id :crowberto) metadata)) 254)
+ (str "session id exceeds the column width for metadata " (pr-str metadata))))))
+
+(deftest over-long-session-id-is-rejected-at-mint-test
+ (testing (str "an id that would exceed the persisted mcp_query_handle.mcp_session_id column (254) is rejected when "
+ "it is minted, not silently created and then 404'd on every later request by the read-path length "
+ "guard. A future payload field is the realistic way this happens; here we force it by making the "
+ "capability encoder emit an over-long segment.")
+ (mt/with-dynamic-fn-redefs [mcp.session/encode-session-payload (constantly (apply str (repeat 300 "x")))]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"exceeds the persisted column width"
+ (mcp.session/create! (mt/user->id :crowberto) {:supports-mcp-ui? true}))
+ "minting must fail loudly at creation rather than defer the failure to the read path"))))
+
+(deftest mcp-ui-capability-claim-must-be-signed-test
+ (testing "GHY-4318: `supports-mcp-ui?` is what `:required-extensions` gates on, and it reads a payload the
+ CLIENT echoes back in its own session id. Unsigned, that is a self-assertion: any caller can mint
+ `<uuid>.{\"v\":1,\"ui\":true}` and claim the capability without ever having advertised it at
+ `initialize`, which is what lets a narrow token reach `refresh_ui_credential`.
+
+ The id stays a stateless correlator — a well-formed one is still ACCEPTED for its presenter, which
+ `well-formed-but-never-issued-session-id-is-accepted-for-its-presenter-test` pins. Only the claim
+ inside it has to be proven, so an unsigned or tampered payload reads as no capability rather than
+ as an invalid session."
+ (let [minted (mcp.session/create! (mt/user->id :crowberto) {:supports-mcp-ui? true})]
+ (testing "a server-minted id carries the capability"
+ (is (true? (mcp.session/valid-id? minted)))
+ (is (true? (mcp.session/supports-mcp-ui? minted))))
+ (testing "a client-forged payload claiming `ui` is still a usable session, but claims nothing"
+ (let [forged (str (random-uuid) "." (@#'mcp.session/encode-session-payload {:v 1 :ui true}))]
+ (is (true? (mcp.session/valid-id? forged))
+ "still a valid correlator — statelessness is deliberate")
+ (is (false? (mcp.session/supports-mcp-ui? forged))
+ "but an unsigned capability claim must not be believed")))
+ (testing "upgrading a signed payload under its own signature invalidates the claim"
+ ;; Tamper by swapping a `ui false` payload for a `ui true` one while keeping the signature minted for
+ ;; the original — the escalation an attacker actually wants. Re-encoding the SAME payload proves
+ ;; nothing: the id rebuilds byte-identical and is believed for the right reason.
+ (let [plain (mcp.session/create! (mt/user->id :crowberto) {:supports-mcp-ui? false})
+ [uuid _payload sig] (str/split plain #"\." -1)
+ upgraded (str uuid "." (@#'mcp.session/encode-session-payload {:v 1 :ui true}) "." sig)]
+ (is (some? sig)
+ "the split must reach the signature, or the assertion below passes for being malformed")
+ (is (false? (mcp.session/supports-mcp-ui? plain))
+ "control: the unmodified id claims nothing")
+ (is (false? (mcp.session/supports-mcp-ui? upgraded)))))
+ (testing "a signature from a different session id does not transfer"
+ (let [other (mcp.session/create! (mt/user->id :crowberto) {:supports-mcp-ui? true})
+ [uuid payload minted-sig] (str/split minted #"\." -1)
+ [_ _ other-sig] (str/split other #"\." -1)]
+ (is (some? other-sig)
+ "the split must reach the signature, or the assertion below passes for being malformed")
+ (is (not= minted-sig other-sig)
+ "the lifted signature has to differ from the original, or nothing is being tested")
+ (is (false? (mcp.session/supports-mcp-ui? (str uuid "." payload "." other-sig)))))))))
(deftest legacy-session-ui-capability-test
- (testing "plain UUID sessions minted before capability hints keep the old tools/list behavior"
- (is (true? (mcp.session/supports-mcp-ui? (str (java.util.UUID/randomUUID)))))))
+ (testing "a plain UUID session claims no capability. It used to claim MCP Apps support, which made signing
+ the payload pointless: a caller could simply omit the payload and be believed anyway. Such ids
+ predate capability hints entirely, so the honest reading of one is `unknown`, and the gate this
+ feeds fails closed."
+ (is (false? (mcp.session/supports-mcp-ui? (str (java.util.UUID/randomUUID)))))))
(deftest malformed-session-payload-test
(testing "two-part session ids must include a decodable capability hint"
@@ -106,8 +166,8 @@
(testing "derived key is UUID-formatted so it passes server.middleware.session/valid-session-key?"
;; If this regresses, the embedding SDK iframe will get 403s from /api when it sends the
;; derived key as X-Metabase-Session, because the middleware rejects non-UUID keys up-front.
- (let [session-id (mcp.session/create! (mt/user->id :crowberto))
- key (mcp.session/derive-embedding-session-key session-id)
+ (let [session-id (mcp.session/create! (mt/user->id :crowberto) nil)
+ key (@#'mcp.session/derive-embedding-session-key session-id)
parsed (parse-uuid key)]
(is (some? parsed)
"derive-embedding-session-key must return a UUID-formatted string")
@@ -118,8 +178,9 @@
(deftest ui-credential-validation-test
(let [user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)
- credential (mcp.session/issue-ui-credential session-id user-id)]
+ session-id (mcp.session/create! user-id nil)
+ scopes #{metabot.scope/agent-content-read metabot.scope/agent-query-run}
+ credential (mcp.session/issue-ui-credential session-id user-id scopes)]
(testing "a fresh credential resolves to its user and MCP session"
(is (=? {:uid user-id :sid session-id}
(mcp.session/resolve-ui-credential credential))))
@@ -128,27 +189,66 @@
(testing "expired credentials are rejected"
(with-redefs [mcp.session/ui-credential-lifetime-seconds -1]
(is (nil? (mcp.session/resolve-ui-credential
- (mcp.session/issue-ui-credential session-id user-id))))))))
+ (mcp.session/issue-ui-credential session-id user-id scopes))))))))
-(deftest get-or-create-session-key-test
- (testing "first call creates a core_session and returns the derived embedding key"
+(deftest ui-credential-carries-minting-session-scopes-test
+ (testing "GHY-4318: the credential is stamped unrestricted for the endpoint scope middleware, so the minting
+ session's real scopes have to travel on the signed claims for downstream gates to see them"
(let [user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)
- key (mcp.session/get-or-create-session-key! session-id user-id)]
- (is (= (mcp.session/derive-embedding-session-key session-id) key))
- (is (not= session-id key)
- "Derived key must not equal the MCP session id that travels on the wire")
+ session-id (mcp.session/create! user-id nil)
+ scopes-of (fn [token-scopes]
+ (:token-scopes (mcp.session/resolve-ui-credential
+ (mcp.session/issue-ui-credential session-id user-id token-scopes))))]
+ (testing "named scopes round-trip"
+ (is (= #{metabot.scope/agent-content-read metabot.scope/agent-query-run}
+ (scopes-of #{metabot.scope/agent-content-read metabot.scope/agent-query-run}))))
+ (testing "an empty grant round-trips as an empty set, not as nil"
+ (is (= #{} (scopes-of #{}))))
+ (testing "the unrestricted sentinel round-trips as the keyword, not as a string"
+ (is (= #{::scope/unrestricted} (scopes-of #{::scope/unrestricted}))))
+ (testing "a granted scope that spells the sentinel out cannot become it — the sentinel rides its own claim"
+ (is (= #{(str ::scope/unrestricted)}
+ (scopes-of #{(str ::scope/unrestricted)}))))
+ (testing "a credential minted before the claim existed fails closed rather than reading as unrestricted"
+ ;; A rolling deploy can hand this node a credential from an older one for the 300s it stays valid.
+ (mt/with-dynamic-fn-redefs [mcp.session/encode-token-scopes (constantly {})]
+ (is (= #{} (scopes-of #{metabot.scope/agent-sql-run}))))))))
+
+(deftest get-or-create-embedding-session-test
+ (testing "first call materializes the core_session backing this MCP session and returns the row"
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id nil)
+ row (mcp.session/get-or-create-embedding-session! session-id user-id)]
+ (is (some? (:id row)))
(is (t2/exists? :core_session :key_hashed (derived-hash session-id))
"core_session should now exist")
- (testing "subsequent calls return the same key and don't create duplicates"
- (is (= key (mcp.session/get-or-create-session-key! session-id user-id)))
+ (testing "subsequent calls collapse to the same row rather than creating duplicates"
+ (is (= (:id row) (:id (mcp.session/get-or-create-embedding-session! session-id user-id))))
(is (= 1 (t2/count :core_session :key_hashed (derived-hash session-id))))))))
+(deftest embedding-session-key-never-escapes-the-namespace-test
+ (testing "GHY-4333: `derive-embedding-session-key` takes only the MCP session id, which is client-supplied and
+ unsigned, so two users presenting the same id derive the SAME plaintext key — and `core_session`
+ lookups resolve a key by `key_hashed` alone, with no user filter and no ordering. Any public fn
+ handing out that plaintext is therefore an account-takeover primitive: a caller who learns another
+ user's session id gets a working session key for whoever else materialized a row under it.
+
+ `get-or-create-session-key!` was exactly such a fn. It had no production caller anywhere (dead since
+ #79312 replaced it with the signed UI credential), so it was deleted rather than guarded. The
+ derivation is private so the plaintext cannot leave this namespace at all; inside it, the value is
+ only ever hashed. This test is what stops that from being quietly undone."
+ (is (:private (meta #'mcp.session/derive-embedding-session-key))
+ (str "derive-embedding-session-key must stay private: its output authenticates as whichever user's "
+ "colliding core_session row the DB happens to return first. A caller needing the row should use "
+ "get-or-create-embedding-session!, which returns the row and never the key."))
+ (is (not (contains? (ns-publics 'metabase.mcp.session) 'get-or-create-session-key!))
+ "get-or-create-session-key! handed out that plaintext and must not come back")))
+
(deftest delete-test
(testing "delete! removes the core_session if one was created"
(let [user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)
- _ (mcp.session/get-or-create-session-key! session-id user-id)]
+ session-id (mcp.session/create! user-id nil)
+ _ (mcp.session/get-or-create-embedding-session! session-id user-id)]
(is (t2/exists? :core_session :key_hashed (derived-hash session-id)))
(mcp.session/delete! session-id user-id)
(is (not (t2/exists? :core_session :key_hashed (derived-hash session-id)))))))
@@ -157,8 +257,8 @@
(testing "delete! only removes sessions owned by the given user"
(let [user-id (mt/user->id :crowberto)
other-id (mt/user->id :rasta)
- session-id (mcp.session/create! user-id)
- _ (mcp.session/get-or-create-session-key! session-id user-id)]
+ session-id (mcp.session/create! user-id nil)
+ _ (mcp.session/get-or-create-embedding-session! session-id user-id)]
(is (t2/exists? :core_session :key_hashed (derived-hash session-id)))
(mcp.session/delete! session-id other-id)
(is (t2/exists? :core_session :key_hashed (derived-hash session-id))
@@ -169,26 +269,46 @@
(deftest owned-by-user-test
(testing "returns true when no core_session exists yet"
- (let [session-id (mcp.session/create! (mt/user->id :crowberto))]
+ (let [session-id (mcp.session/create! (mt/user->id :crowberto) nil)]
(is (true? (mcp.session/owned-by-user? session-id (mt/user->id :crowberto))))
(is (true? (mcp.session/owned-by-user? session-id (mt/user->id :rasta))))))
(testing "returns true for the owning user, false for others"
(let [user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)
- _ (mcp.session/get-or-create-session-key! session-id user-id)]
+ session-id (mcp.session/create! user-id nil)
+ _ (mcp.session/get-or-create-embedding-session! session-id user-id)]
(is (true? (mcp.session/owned-by-user? session-id user-id)))
(is (false? (mcp.session/owned-by-user? session-id (mt/user->id :rasta)))))))
+(deftest owned-by-user-tolerates-cross-user-rows-test
+ (testing "GHY-4333: an Mcp-Session-Id is client-supplied and unsigned, so two users can each materialize a
+ core_session for the same id. Each must keep access to its own row — checking ownership on key_hashed
+ alone picks one of them arbitrarily and locks the other out of every subsequent request."
+ (let [owner-id (mt/user->id :crowberto)
+ other-id (mt/user->id :rasta)
+ session-id (mcp.session/create! owner-id nil)]
+ (testing "both users pass the check while nothing has been materialized"
+ (is (true? (mcp.session/owned-by-user? session-id owner-id)))
+ (is (true? (mcp.session/owned-by-user? session-id other-id))))
+ (mcp.session/get-or-create-embedding-session! session-id owner-id)
+ (mcp.session/get-or-create-embedding-session! session-id other-id)
+ (is (= 2 (t2/count :core_session :key_hashed (derived-hash session-id)))
+ "rows are scoped to (key_hashed, user_id), so each user materializes their own")
+ (testing "neither user is locked out by the other's row"
+ (is (true? (mcp.session/owned-by-user? session-id owner-id)))
+ (is (true? (mcp.session/owned-by-user? session-id other-id))))
+ (testing "a third user with no row of their own is still rejected"
+ (is (false? (mcp.session/owned-by-user? session-id (mt/user->id :lucky))))))))
+
(deftest delete-noop-without-session-test
(testing "delete! is a no-op when no core_session was ever created"
- (let [session-id (mcp.session/create! (mt/user->id :crowberto))]
+ (let [session-id (mcp.session/create! (mt/user->id :crowberto) nil)]
;; Should not throw — just a no-op delete
(mcp.session/delete! session-id (mt/user->id :crowberto)))))
-(deftest store-and-read-handle-test
- (testing "store-handle! returns a UUID handle that read-handle resolves to the encoded query"
+(deftest store-and-resolve-handle-test
+ (testing "store-handle! returns a UUID handle that resolve-query-handle resolves to the encoded query"
(let [user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)
+ session-id (mcp.session/create! user-id nil)
h1 (mcp.session/store-handle! session-id user-id "first")
h2 (mcp.session/store-handle! session-id user-id "second")]
(is (some? (parse-uuid h1)) "store-handle! must return a UUID string")
@@ -196,32 +316,32 @@
(is (not= h1 h2) "successive calls must produce distinct handles")
(is (= session-id (t2/select-one-fn :mcp_session_id :model/McpQueryHandle :id h1))
"store-handle! stores the full MCP session id, including capability hints")
- (is (= "first" (mcp.session/read-handle session-id user-id h1)))
- (is (= "second" (mcp.session/read-handle session-id user-id h2)))
- (is (nil? (mcp.session/read-handle session-id user-id (str (random-uuid))))
- "read-handle returns nil for unknown handles"))))
+ (is (= "first" (:encoded_query (mcp.session/resolve-query-handle session-id user-id h1))))
+ (is (= "second" (:encoded_query (mcp.session/resolve-query-handle session-id user-id h2))))
+ (is (nil? (mcp.session/resolve-query-handle session-id user-id (str (random-uuid))))
+ "resolve-query-handle returns nil for unknown handles"))))
-(deftest read-handle-falls-back-across-the-users-sessions-test
- (testing "read-handle resolves a handle stored in one session when called from another session of the same user"
+(deftest resolve-query-handle-falls-back-across-the-users-sessions-test
+ (testing "resolve-query-handle resolves a handle stored in one session when called from another session of the same user"
(let [user-id (mt/user->id :crowberto)
- owner-session (mcp.session/create! user-id)
- rotated-session (mcp.session/create! user-id)
+ owner-session (mcp.session/create! user-id nil)
+ rotated-session (mcp.session/create! user-id nil)
handle (mcp.session/store-handle! owner-session user-id "payload")]
(testing "same session → resolves"
- (is (= "payload" (mcp.session/read-handle owner-session user-id handle))))
+ (is (= "payload" (:encoded_query (mcp.session/resolve-query-handle owner-session user-id handle)))))
(testing "different session, same user → still resolves (cross-session fallback)"
- (is (= "payload" (mcp.session/read-handle rotated-session user-id handle))))))
- (testing "read-handle refuses to resolve handles owned by a different user"
+ (is (= "payload" (:encoded_query (mcp.session/resolve-query-handle rotated-session user-id handle)))))))
+ (testing "resolve-query-handle refuses to resolve handles owned by a different user"
(let [owner-id (mt/user->id :crowberto)
attacker-id (mt/user->id :rasta)
- session-id (mcp.session/create! owner-id)
+ session-id (mcp.session/create! owner-id nil)
handle (mcp.session/store-handle! session-id owner-id "payload")]
- (is (nil? (mcp.session/read-handle session-id attacker-id handle))))))
+ (is (nil? (mcp.session/resolve-query-handle session-id attacker-id handle))))))
(deftest resolve-query-handle-returns-encoded-query-and-prompt-test
(testing "resolve-query-handle returns the stored query and prompt"
(let [user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)
+ session-id (mcp.session/create! user-id nil)
handle (mcp.session/store-handle! session-id user-id "encoded" "what was my question")]
(is (= {:encoded_query "encoded" :prompt "what was my question"}
(mcp.session/resolve-query-handle session-id user-id handle))))))
@@ -229,29 +349,78 @@
(deftest store-handle-cascades-with-core-session-test
(testing "deleting the backing core_session cascades to its handles"
(let [user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)
+ session-id (mcp.session/create! user-id nil)
handle (mcp.session/store-handle! session-id user-id "payload")]
- (is (= "payload" (mcp.session/read-handle session-id user-id handle)))
+ (is (= "payload" (:encoded_query (mcp.session/resolve-query-handle session-id user-id handle))))
(t2/delete! :core_session :key_hashed (derived-hash session-id))
- (is (nil? (mcp.session/read-handle session-id user-id handle))
+ (is (nil? (mcp.session/resolve-query-handle session-id user-id handle))
"cascade should reap the handle when the core_session row goes"))))
(deftest delete-removes-handles-test
(testing "delete! removes handles for the session"
(let [user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)
+ session-id (mcp.session/create! user-id nil)
handle (mcp.session/store-handle! session-id user-id "payload")
_ (mcp.session/delete! session-id user-id)]
- (is (nil? (mcp.session/read-handle session-id user-id handle))))))
+ (is (nil? (mcp.session/resolve-query-handle session-id user-id handle))))))
+
+(deftest delete-does-not-reap-another-users-handles-test
+ (testing "GHY-4333: an `Mcp-Session-Id` is client-supplied and unsigned, so two users can each materialize a
+ core_session under one id — `owned-by-user?` tolerates that by design, and
+ `owned-by-user-tolerates-cross-user-rows-test` pins it. Tearing down one user's session therefore has
+ to scope the handle delete to that user: deleting by `mcp_session_id` alone destroys the other user's
+ handles, which the FK cascade would never have touched."
+ (let [owner-id (mt/user->id :crowberto)
+ other-id (mt/user->id :rasta)
+ session-id (mcp.session/create! owner-id nil)]
+ (try
+ (let [owner-handle (mcp.session/store-handle! session-id owner-id "owner payload")
+ other-handle (mcp.session/store-handle! session-id other-id "other payload")]
+ (is (= 2 (t2/count :model/McpQueryHandle :mcp_session_id session-id))
+ "both users hold a handle under the same session id — otherwise this test proves nothing")
+ (mcp.session/delete! session-id owner-id)
+ (testing "the caller's own handle is gone"
+ (is (nil? (mcp.session/resolve-query-handle session-id owner-id owner-handle))))
+ (testing "the other user's handle survives, and stays resolvable for them"
+ (is (some? (mcp.session/resolve-query-handle session-id other-id other-handle)))))
+ (finally
+ (mcp.session/delete! session-id owner-id)
+ (mcp.session/delete! session-id other-id))))))
+
+(deftest delete-reaps-unattributed-legacy-handles-test
+ (testing "`core_session_id` is nullable, and released code predating the always-set write left rows with it
+ NULL. Scoping the delete through `core_session` alone strands those forever — `NULL IN (subquery)`
+ never matches and nothing else reaps them.
+
+ They are safe to delete on session id alone, unlike attributed rows: `find-handle-row` inner-joins
+ `core_session`, so a NULL row can never be read back by anyone. It is unreachable data, not another
+ user's working handle, so reaping it cannot destroy anything usable."
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id nil)
+ legacy-id (str (random-uuid))]
+ (try
+ (t2/insert! :model/McpQueryHandle {:id legacy-id
+ :mcp_session_id session-id
+ :core_session_id nil
+ :encoded_query "legacy payload"})
+ (is (t2/exists? :model/McpQueryHandle :id legacy-id))
+ (is (nil? (mcp.session/resolve-query-handle session-id user-id legacy-id))
+ "the row is unreadable even before deletion — that is what makes it safe to reap unscoped")
+ (mcp.session/delete! session-id user-id)
+ (is (not (t2/exists? :model/McpQueryHandle :id legacy-id))
+ "delete! must reclaim it rather than strand it")
+ (finally
+ (t2/delete! :model/McpQueryHandle :id legacy-id))))))
(deftest session-does-not-fire-login-event-test
- (testing "Creating a core_session via get-or-create-session-key! does not publish :event/user-login"
- (let [login-events (atom [])
- user-id (mt/user->id :crowberto)
- session-id (mcp.session/create! user-id)]
- (mt/with-dynamic-fn-redefs [events/publish-event! (fn [topic payload]
- (when (= topic :event/user-login)
- (swap! login-events conj payload)))]
- (mcp.session/get-or-create-session-key! session-id user-id))
- (is (empty? @login-events)
- "No :event/user-login should be published for MCP embedding sessions"))))
+ (testing "Creating a core_session via get-or-create-embedding-session! does not publish :event/user-login"
+ ;; Observed through the event's one synchronous side effect — `metabase.users.events.last-login` stamps
+ ;; `last_login` on the user — rather than by redefining `events/publish-event!`: it is a methodical
+ ;; multimethod, and `with-dynamic-fn-redefs` permanently swaps its root for a plain-fn proxy, after which
+ ;; any later `methodical/defmethod` on it (e.g. `metabase.api-routes.events`, loaded when the test web
+ ;; server first starts) fails to macroexpand.
+ (mt/with-temp [:model/User {user-id :id} {:last_login nil}]
+ (let [session-id (mcp.session/create! user-id nil)]
+ (mcp.session/get-or-create-embedding-session! session-id user-id)
+ (is (nil? (t2/select-one-fn :last_login :model/User :id user-id))
+ "No :event/user-login should be published for MCP embedding sessions")))))
diff --git a/test/metabase/mcp/task/mcp_query_handle_gc_test.clj b/test/metabase/mcp/task/mcp_query_handle_gc_test.clj
new file mode 100644
index 00000000000..12d45aead53
--- /dev/null
+++ b/test/metabase/mcp/task/mcp_query_handle_gc_test.clj
@@ -0,0 +1,43 @@
+(ns metabase.mcp.task.mcp-query-handle-gc-test
+ "Tests for the scheduled query-handle GC (GHY-4136): handles past the TTL are deleted, fresh ones kept,
+ and the TTL setting is honored."
+ (:require
+ [clojure.test :refer [deftest is testing]]
+ [java-time.api :as t]
+ [metabase.mcp.task.mcp-query-handle-gc :as gc]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(defn- mint!
+ "Mint a handle owned by `uid`; the query body is irrelevant — GC only reads `created_at`."
+ [uid]
+ (v2.queries/mint-query-handle! (str (random-uuid)) uid
+ (v2.queries/encode-serialized-query {:stages [{:source-table 1}]})))
+
+(defn- hours-ago [n]
+ (t/minus (t/offset-date-time) (t/hours (long n))))
+
+(deftest gc-deletes-handles-past-ttl-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [uid (mt/user->id :rasta)
+ old (mint! uid)
+ fresh (mint! uid)]
+ (t2/update! :model/McpQueryHandle old {:created_at (hours-ago 25)}) ; default TTL is 24h
+ (#'gc/gc-expired-query-handles!)
+ (testing "a handle older than the TTL is deleted"
+ (is (nil? (t2/select-one :model/McpQueryHandle :id old))))
+ (testing "a handle within the TTL is kept"
+ (is (some? (t2/select-one :model/McpQueryHandle :id fresh)))))))
+
+(deftest gc-respects-ttl-setting-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-temporary-setting-values [mcp-query-handle-ttl-hours 1]
+ (let [uid (mt/user->id :rasta)
+ h (mint! uid)]
+ (t2/update! :model/McpQueryHandle h {:created_at (hours-ago 2)})
+ (#'gc/gc-expired-query-handles!)
+ (is (nil? (t2/select-one :model/McpQueryHandle :id h))
+ "a 2h-old handle is deleted when the TTL is set to 1h")))))
diff --git a/test/metabase/mcp/tools_test.clj b/test/metabase/mcp/tools_test.clj
deleted file mode 100644
index b645202402b..00000000000
--- a/test/metabase/mcp/tools_test.clj
+++ /dev/null
@@ -1,110 +0,0 @@
-(ns metabase.mcp.tools-test
- "scope-matches? tests moved to [[metabase.mcp.scope-test]]."
- (:require
- [clojure.test :refer :all]
- [clojure.walk :as walk]
- [metabase.api.macros.scope :as api.scope]
- [metabase.mcp.tools :as mcp.tools]
- [metabase.util.json :as json]))
-
-(deftest ^:parallel drop-nil-args-test
- (testing "strips nil-valued top-level keys so 'missing' and 'explicit nil' are equivalent at the MCP boundary"
- (let [drop-nil-args (var-get #'mcp.tools/drop-nil-args)]
- (testing "removes top-level nils"
- (is (= {:id 42 :flag false}
- (drop-nil-args {:id 42 :flag false :extra nil}))))
- (testing "keeps non-nil falsey values"
- (is (= {:flag false :count 0 :text ""}
- (drop-nil-args {:flag false :count 0 :text ""}))))
- (testing "preserves nested nils (only top-level is rewritten)"
- (is (= {:source {:type "table" :id nil}}
- (drop-nil-args {:source {:type "table" :id nil} :continuation_token nil}))))
- (testing "nil argument → nil"
- (is (nil? (drop-nil-args nil))))
- (testing "empty map stays empty"
- (is (= {} (drop-nil-args {})))))))
-
-(deftest ^:parallel overrides-cover-known-tools-test
- (testing "every key in `mcp-input-overrides` / `mcp-output-overrides` matches a real tool"
- ;; Catches the silent-no-op failure mode if a tool gets renamed or an override key is misspelled:
- ;; the override would otherwise be dropped on the floor and the wire-shape schema would be published
- ;; in place of the intended MCP shape. Lives as a test (not a runtime check at manifest generation)
- ;; so prod startup isn't burdened with a check that only catches developer mistakes.
- (let [manifest-fn (#'mcp.tools/manifest)
- tool-names (into #{} (map :name) (:tools manifest-fn))]
- (doseq [[label override-map-var] [["mcp-input-overrides" #'mcp.tools/mcp-input-overrides]
- ["mcp-output-overrides" #'mcp.tools/mcp-output-overrides]]]
- (testing label
- (let [unknown (remove tool-names (keys @override-map-var))]
- (is (empty? unknown)
- (str label " has keys that don't match any tool name: " (vec unknown)))))))))
-
-(deftest ^:parallel search-output-schema-timestamps-are-disjoint-test
- (testing "search timestamp fields publish disjoint date-time/null oneOf branches"
- ;; `[:maybe :any]` becomes `oneOf [{}, {type:null}]`. Null then matches both
- ;; branches, and MCP clients that enforce oneOf reject the whole search response
- ;; (e.g. collections with a null updated_at). TemporalInstant keeps the branches
- ;; disjoint so null matches only the null arm.
- (let [search-tool (some #(when (= "search" (:name %)) %)
- (mcp.tools/list-tools #{::api.scope/unrestricted}))
- item-props (get-in search-tool [:outputSchema :properties :data :items :properties])
- expected {:oneOf [{:type "string" :format "date-time"} {:type "null"}]}]
- (is (= expected (:updated_at item-props)))
- (is (= expected (:created_at item-props))))))
-
-(defn- data-node?
- "True if `x` is a value type our published JSON-Schema-shaped tool schemas
- are allowed to contain. Visited via `walk/postwalk`, which traverses every
- node (branches and leaves), so this predicate must accept both scalars and
- the container types that hold them. Excludes functions, vars, atoms —
- anything that would blow up `json/encode` or whose JSON encoding isn't
- byte-stable.
-
- `java.util.regex.Pattern` is allowed: `mjs/transform` lowers `[:re #\"...\"]`
- to `{:type \"string\" :pattern #\"...\"}`, leaving the compiled Pattern in
- the schema. Note that `(hash Pattern)` is identity-based and unstable, but
- `(json/encode Pattern)` writes the regex source string — which is stable.
- `tools-hash` hashes the JSON bytes, never the Pattern object, so Pattern
- nodes are safe in practice."
- [x]
- (or (nil? x) (boolean? x) (number? x) (string? x)
- (keyword? x) (symbol? x)
- (map? x) (vector? x) (seq? x) (set? x)
- (instance? java.util.regex.Pattern x)))
-
-(deftest ^:parallel tool-schemas-are-pure-data-test
- (testing "published tool schemas must be JSON-encodable pure data so `tools-hash` is stable"
- ;; The MCP SSE keepalive emits `notifications/tools/list_changed` when `tools-hash` changes.
- ;; That hash is only meaningful if `inputSchema` / `outputSchema` are pure data: a stray fn
- ;; (e.g. a Malli predicate that leaked through `mjs/transform`) would either blow up
- ;; `json/encode` or, if hashed directly, produce an identity-hash that's stable within a JVM
- ;; but not across builds — silently breaking the list-changed contract.
- (let [tools (mcp.tools/list-tools #{::api.scope/unrestricted})]
- (is (seq tools) "list-tools should return some tools under the unrestricted scope")
- (doseq [{tool-name :name :keys [inputSchema outputSchema]} tools
- [label schema] [[:inputSchema inputSchema] [:outputSchema outputSchema]]
- :when schema]
- (testing (str tool-name " " label)
- (testing "every node is a pure-data type"
- (walk/postwalk
- (fn [x]
- (is (data-node? x)
- (str "Non-data node in " tool-name " " label ": " (pr-str x) " (" (type x) ")"))
- x)
- schema))
- (testing "json-encodes without error"
- (is (string? (json/encode schema))))
- (testing "json encoding is deterministic"
- (is (= (json/encode schema) (json/encode schema)))))))))
-
-(deftest ^:parallel tools-hash-test
- (testing "tools-hash is deterministic across calls"
- (let [scopes #{::api.scope/unrestricted}]
- (is (= (mcp.tools/tools-hash scopes) (mcp.tools/tools-hash scopes)))))
- (testing "tools-hash differs when the visible toolset differs"
- ;; Different scope set yields a different (possibly smaller) tool list, so the hash should change.
- ;; If this ever flakes because two scope filters happen to produce identical lists, narrow the
- ;; second scope to one that we know filters tools out.
- (let [unrestricted (mcp.tools/tools-hash #{::api.scope/unrestricted})
- empty-scopes (mcp.tools/tools-hash #{})]
- (is (not= unrestricted empty-scopes)))))
diff --git a/test/metabase/mcp/transport_test.clj b/test/metabase/mcp/transport_test.clj
new file mode 100644
index 00000000000..00becb5db85
--- /dev/null
+++ b/test/metabase/mcp/transport_test.clj
@@ -0,0 +1,850 @@
+(ns metabase.mcp.transport-test
+ (:require
+ [clojure.core.async :as a]
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.ai-tracing.core :as ait]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.settings :as mcp.settings]
+ [metabase.mcp.transport :as mcp.transport]
+ [metabase.mcp.v2.common :as v2.common]
+ [metabase.mcp.v2.test-util]
+ [metabase.oauth-server.test-util :as oauth-server.tu]
+ [metabase.server.streaming-response :as streaming-response]
+ [metabase.server.streaming-response.thread-pool :as thread-pool]
+ [metabase.system.core :as system]
+ [metabase.test :as mt]
+ [metabase.test.data.users :as test.users]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.test.http-client :as client]
+ [metabase.util.json :as json]
+ [oidc-provider.util :as oidc.util]
+ [throttle.core :as throttle]
+ [toucan2.core :as t2])
+ (:import
+ (java.io StringWriter Writer)))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(defn- signaling-writer!
+ "A `Writer` that copies everything written to `sink` and then offers `::request-canceled` on `chan`. Cancelling at
+ exactly the moment the stream writes a keepalive removes the timing dependency from the test below: the loop is
+ cancelled at the instant it would otherwise start waiting out the keepalive interval."
+ ^Writer [^StringWriter sink chan]
+ (proxy [Writer] []
+ (write
+ ([data]
+ (cond
+ (string? data) (.write sink ^String data)
+ (integer? data) (.write sink (int data))
+ :else (.write sink ^chars data))
+ (a/offer! chan ::request-canceled))
+ ([data off len]
+ (if (string? data)
+ (.write sink ^String data (int off) (int len))
+ (.write sink ^chars data (int off) (int len)))
+ (a/offer! chan ::request-canceled)))
+ (flush [])
+ (close [])))
+
+(defn- run-keepalive-loop!
+ "Run the keepalive loop on a separate thread, returning `:returned` if it finished within 5s and `:timed-out` if
+ it is still holding its thread."
+ [writer tools-hash-fn canceled-chan interval-ms]
+ (deref (future (#'mcp.transport/keepalive-loop! writer tools-hash-fn nil canceled-chan interval-ms)
+ :returned)
+ 5000
+ :timed-out))
+
+(deftest keepalive-loop-releases-its-thread-when-the-client-disconnects-test
+ (testing (str "GHY-4331: a stream cancelled mid-interval releases its thread promptly instead of holding it until "
+ "the next keepalive tick")
+ (let [canceled (a/promise-chan)
+ sink (StringWriter.)]
+ (is (= :returned (run-keepalive-loop! (signaling-writer! sink canceled) (constantly "hash") canceled 30000)))
+ (testing "the keepalive written before the cancellation still reached the client"
+ (is (= ": keepalive\n\n" (str sink)))))))
+
+(deftest keepalive-loop-emits-tools-list-changed-on-hash-change-test
+ (testing "a change in the visible tool set between ticks emits notifications/tools/list_changed exactly once"
+ (let [canceled (a/promise-chan)
+ sink (StringWriter.)
+ calls (atom 0)
+ hash-fn (fn [_scopes]
+ (let [n (swap! calls inc)]
+ ;; cancel on the third read so the loop terminates after a known number of ticks
+ (when (>= n 3)
+ (a/offer! canceled ::request-canceled))
+ (if (= n 1) "hash-1" "hash-2")))]
+ (is (= :returned (run-keepalive-loop! sink hash-fn canceled 1)))
+ (let [output (str sink)]
+ (is (= 3 (count (re-seq #": keepalive" output))))
+ (is (= 1 (count (re-seq #"notifications/tools/list_changed" output))))))))
+
+(defn- keepalive-counts []
+ @@#'mcp.transport/keepalive-stream-counts)
+
+(defn- with-clean-keepalive-counts
+ "Run `thunk` against an empty slot table. The table is a `defonce` atom that outlives ns reloads, so it is
+ cleared going in as well as coming out — otherwise these tests depend on which of them ran first."
+ [thunk]
+ (reset! @#'mcp.transport/keepalive-stream-counts {})
+ (try (thunk) (finally (reset! @#'mcp.transport/keepalive-stream-counts {}))))
+
+(deftest keepalive-slot-accounting-test
+ (testing (str "GHY-4331: moving the keepalive off the fixed streaming pool removed the ceiling that pool "
+ "imposed — virtual threads have none. A stream is held for as long as the client keeps it and "
+ "costs a single throttle attempt to open, so without a cap one credential can accumulate "
+ "connections indefinitely. The cap is per-user so one caller cannot crowd out the rest.")
+ (with-clean-keepalive-counts
+ (fn []
+ (let [cap @#'mcp.transport/max-concurrent-keepalive-streams
+ acquire #(#'mcp.transport/acquire-keepalive-slot! %)
+ release #(#'mcp.transport/release-keepalive-slot! %)]
+ (testing "a user may hold up to the cap"
+ (is (every? true? (repeatedly cap #(acquire 1)))))
+ (testing "and is refused past it, without the refusal costing them a held slot"
+ (is (false? (acquire 1)))
+ (is (= cap (get (keepalive-counts) 1))))
+ (testing "another user is unaffected — the cap bounds a caller, not the instance"
+ (is (true? (acquire 2))))
+ (testing "releasing frees exactly one slot"
+ (release 1)
+ (is (= (dec cap) (get (keepalive-counts) 1)))
+ (is (true? (acquire 1))))
+ (testing "a user at zero drops out of the map rather than accumulating an entry per user ever seen"
+ (release 2)
+ (is (not (contains? (keepalive-counts) 2))))
+ (testing "an unbalanced release cannot drive the count negative and hand out free slots"
+ (release 2)
+ (release 2)
+ (is (not (contains? (keepalive-counts) 2)))))))))
+
+(deftest keepalive-slot-is-held-for-the-life-of-the-stream-test
+ (testing "the stream body owns the slot: taken while it runs, returned however it ends. A slot leaked on
+ disconnect would retire the cap one connection at a time; one never taken would make the cap
+ meaningless."
+ (with-clean-keepalive-counts
+ (fn []
+ (let [canceled (a/promise-chan)
+ sink (StringWriter.)
+ held (atom nil)]
+ (#'mcp.transport/keepalive-stream-body! 7
+ (signaling-writer! sink canceled)
+ ;; read the count from inside the running loop
+ (fn [_] (reset! held (get (keepalive-counts) 7)) "hash")
+ nil canceled 30000)
+ (is (= 1 @held) "the slot is held while the stream is running")
+ (is (not (contains? (keepalive-counts) 7)) "and returned once it ends")))))
+ (testing "returned even when the loop throws rather than returning"
+ (with-clean-keepalive-counts
+ (fn []
+ (is (thrown? Exception
+ (#'mcp.transport/keepalive-stream-body! 8 nil
+ (fn [_] (throw (ex-info "boom" {})))
+ nil (a/promise-chan) 30000)))
+ (is (not (contains? (keepalive-counts) 8))))))
+ (testing "a user already at the cap never starts the loop — the body is where the cap is enforced now, so it
+ has to refuse there too and not merely be refused by the handler"
+ (with-clean-keepalive-counts
+ (fn []
+ (reset! @#'mcp.transport/keepalive-stream-counts
+ {9 @#'mcp.transport/max-concurrent-keepalive-streams})
+ (let [ran (atom false)]
+ (#'mcp.transport/keepalive-stream-body! 9 (StringWriter.)
+ (fn [_] (reset! ran true) "hash")
+ nil (a/promise-chan) 30000)
+ (is (false? @ran)))))))
+
+(deftest keepalive-slot-is-not-taken-when-the-stream-never-starts-test
+ (testing "GHY-4331: a slot must not be held by a stream that never ran. `StreamingResponse`'s `send*` binds
+ `_raise` and never calls it, and streaming-response's own `catch Throwable` sends a 500 and closes
+ its channels without rethrowing — so neither a wrapped `raise` nor a `catch` around `send*` can
+ observe a setup failure. Acquiring up front therefore leaked the slot for the process lifetime, and
+ the cap made that permanent: enough failed connects and the user can open no streams at all.
+
+ So the body owns the slot. `handle-get` only reads the count to refuse at the cap; nothing is taken
+ until the stream is actually running, and a setup failure has nothing to leak."
+ (with-clean-keepalive-counts
+ (fn []
+ (let [responded (promise)]
+ ;; Fail after `handle-get` has decided to serve, before any stream body can run.
+ (with-redefs-fn {#'mcp.transport/require-valid-session (fn [_user-id _session-id] {:session-id "session"})
+ #'streaming-response/-streaming-response (fn [_f _options]
+ (throw (ex-info "setup failed" {})))}
+ (fn []
+ (try
+ (#'mcp.transport/handle-get (constantly "hash") 9 {:headers {"mcp-session-id" "session"}}
+ #(deliver responded %) (fn [_] nil))
+ (catch Throwable _ nil))))
+ (is (not (contains? (keepalive-counts) 9))
+ "a stream that never started must leave no slot behind"))))))
+
+(deftest keepalive-stream-at-the-cap-is-refused-test
+ (testing "a user already holding the cap gets a 429 instead of another stream"
+ (with-clean-keepalive-counts
+ (fn []
+ (let [cap @#'mcp.transport/max-concurrent-keepalive-streams
+ responded (promise)]
+ (reset! @#'mcp.transport/keepalive-stream-counts {1 cap})
+ (with-redefs-fn {#'mcp.transport/require-valid-session (fn [_user-id _session-id] {:session-id "session"})}
+ (fn []
+ (#'mcp.transport/handle-get (constantly "hash") 1 {:headers {"mcp-session-id" "session"}}
+ #(deliver responded %) (fn [e] (throw e)))))
+ (let [response (deref responded 5000 nil)]
+ (is (= 429 (:status response)))
+ (is (str/includes? (str (:body response)) "concurrent"))))))))
+
+(deftest keepalive-stream-refused-mid-stream-names-the-limit-test
+ (testing (str "GHY-4331: `at-keepalive-cap?` is advisory by design, so two connects can both read under the cap "
+ "and the loser only learns it lost inside the stream body — by then 200 and the SSE headers are on "
+ "the wire and the handler's 429 is unreachable. The refusal has to go out in band carrying the same "
+ "JSON-RPC error the 429 carries, or the client cannot tell a refused stream from a healthy one that "
+ "ended immediately.")
+ (with-clean-keepalive-counts
+ (fn []
+ (let [cap @#'mcp.transport/max-concurrent-keepalive-streams
+ sink (StringWriter.)
+ ran (atom false)
+ responded (promise)]
+ (reset! @#'mcp.transport/keepalive-stream-counts {9 cap})
+ (#'mcp.transport/keepalive-stream-body! 9 sink
+ (fn [_] (reset! ran true) "hash")
+ nil (a/promise-chan) 30000)
+ (is (false? @ran) "the loop must not run without a slot")
+ (let [frames (->> (str/split-lines (str sink))
+ (keep #(when (str/starts-with? % "data: ") (json/decode+kw (subs % 6)))))]
+ (is (= 1 (count frames)) "exactly one SSE frame explaining why the stream ended")
+ (with-redefs-fn {#'mcp.transport/require-valid-session (fn [_user-id _session-id] {:session-id "session"})}
+ (fn []
+ (#'mcp.transport/handle-get (constantly "hash") 9 {:headers {"mcp-session-id" "session"}}
+ #(deliver responded %) (fn [e] (throw e)))))
+ (is (= 429 (:status (deref responded 5000 nil))))
+ (is (= (json/decode+kw (:body (deref responded 5000 nil)))
+ (first frames))
+ "the racing loser and the non-racing 429 say the same thing")))))))
+
+(deftest keepalive-stream-does-not-run-on-the-shared-streaming-pool-test
+ (testing (str "GHY-4331: the GET keepalive blocks for the life of the client's connection, so it must not be "
+ "submitted to the fixed streaming-response pool that also serves query downloads")
+ ;; The body owns the keepalive slot; this harness captures the body without running it, so no slot is ever
+ ;; taken. The counts are still cleared so a leak from elsewhere can't bleed into whichever slot test runs next.
+ (with-clean-keepalive-counts
+ (fn []
+ (let [captured (atom nil)
+ real-fn @#'streaming-response/-streaming-response
+ responded (promise)]
+ (with-redefs-fn {#'mcp.transport/require-valid-session (fn [_user-id _session-id] {:session-id "session"})
+ #'streaming-response/-streaming-response (fn [f options]
+ (reset! captured options)
+ (real-fn f options))}
+ (fn []
+ (#'mcp.transport/handle-get (constantly "hash") 1 {:headers {"mcp-session-id" "session"}}
+ #(deliver responded %) (fn [e] (throw e)))))
+ (is (= 200 (:status (deref responded 5000 nil))))
+ (let [executor (:executor @captured)]
+ (is (some? executor)
+ "the keepalive stream must name an executor rather than defaulting to the shared pool")
+ (is (not= executor (thread-pool/thread-pool)))))))))
+
+;;; ------------------------------------------ Transport-level guards ----------------------------------------------
+;;;
+;;; GHY-4337. Everything below runs upstream of every per-tool permission test: if the transport lets a request
+;;; through, no tool-level gate is ever consulted. The scenarios are ported from the deleted `metabase.mcp.api-test`,
+;;; which covered them for the v1 surface.
+
+(def ^:private endpoint "metabase-mcp")
+
+(defn- mcp-request
+ "POST `body` to the MCP endpoint as `username` (default `:crowberto`), returning the full response."
+ ([body]
+ (mcp-request :crowberto body {}))
+ ([body extra-headers]
+ (mcp-request :crowberto body extra-headers))
+ ([username body extra-headers]
+ (client/client-full-response (test.users/username->token username)
+ :post endpoint
+ {:request-options {:headers extra-headers}}
+ body)))
+
+(defn- jsonrpc-request
+ ([method] (jsonrpc-request method {} 1))
+ ([method params] (jsonrpc-request method params 1))
+ ([method params id] {:jsonrpc "2.0" :method method :params params :id id}))
+
+(defn- jsonrpc-notification [method]
+ {:jsonrpc "2.0" :method method :params {}})
+
+(defn- ping-call []
+ (jsonrpc-request "tools/call" {:name "test_echo" :arguments {}}))
+
+(defn- initialize!
+ "Run the `initialize` handshake as `username` and return the issued `Mcp-Session-Id`."
+ ([]
+ (initialize! :crowberto))
+ ([username]
+ (get-in (mcp-request username (jsonrpc-request "initialize") {}) [:headers "Mcp-Session-Id"])))
+
+;;; ------------------------------------------------ Session guards ------------------------------------------------
+
+(deftest forged-session-id-is-refused-test
+ (testing "GHY-4337: a session id the server never issued must not reach method dispatch"
+ (testing "a missing header is a 400 — the client never handshook"
+ (let [response (mcp-request (jsonrpc-request "tools/list"))]
+ (is (= 400 (:status response)))
+ (is (= "Missing Mcp-Session-Id header" (get-in response [:body :error :message])))
+ (is (nil? (get-in response [:body :result])))))
+ (doseq [[label forged] {"not a uuid" "bogus-session-id"
+ "a uuid with an undecodable capability payload" (str (random-uuid) ".!!!!")
+ "more segments than the format allows" (str (random-uuid) ".e30.e30")}]
+ (testing label
+ (let [response (mcp-request (jsonrpc-request "tools/list") {"mcp-session-id" forged})]
+ (is (= 404 (:status response)))
+ (is (= "Invalid or expired session" (get-in response [:body :error :message])))
+ (is (nil? (get-in response [:body :result]))))))))
+
+(defn- fabricated-session-id
+ "A structurally well-formed Mcp-Session-Id the server never issued: a random UUID plus a valid `{v,ui}` capability
+ payload, constructed entirely client-side. `valid-id?` passes on it (the format is the only thing it checks)."
+ []
+ (str (random-uuid)
+ "."
+ (.encodeToString (.withoutPadding (java.util.Base64/getUrlEncoder))
+ (.getBytes ^String (json/encode {:v 1 :ui true}) "UTF-8"))))
+
+(deftest well-formed-but-never-issued-session-id-is-accepted-for-its-presenter-test
+ (testing (str "GHY-4337: MCP session ids are unsigned, stateless correlators — no server-side record of what was "
+ "issued exists (see the `metabase.mcp.session` ns docstring), so the server cannot tell an id it "
+ "minted from a well-formed one a client fabricated, and does not try to. Such an id is therefore "
+ "ACCEPTED for the already-authenticated user presenting it. This is not a hole: authentication is "
+ "the session cookie / bearer token, which is checked independently and upstream; the fabricated id "
+ "only names a fresh correlator scoped to that same caller. The real boundary — a well-formed id that "
+ "ANOTHER user has already materialized a `core_session` under — is enforced by the ownership check "
+ "and covered by `session-belonging-to-another-user-is-refused-test`.")
+ (let [fabricated (fabricated-session-id)]
+ (is (true? (mcp.session/valid-id? fabricated))
+ "the fabricated id is structurally valid — the ownership model, not format, is the boundary")
+ (let [response (mcp-request (ping-call) {"mcp-session-id" fabricated})]
+ (is (= 200 (:status response)))
+ (is (= {:ok true :message "pong"} (get-in response [:body :result :structuredContent]))
+ "an authenticated caller dispatches inside a correlator it fabricated, because no other user owns it")))))
+
+(deftest session-belonging-to-another-user-is-refused-test
+ (testing (str "GHY-4337: `Mcp-Session-Id` is client-supplied and unsigned, so once a session has materialized a "
+ "`core_session` the ownership check is the only thing stopping another authenticated user from "
+ "presenting it and dispatching inside it")
+ (let [session-id (initialize! :rasta)
+ rasta-id (mt/user->id :rasta)]
+ (try
+ ;; there is no owner to violate until a `core_session` row exists, so materialize one the way a resource
+ ;; read would
+ (mcp.session/get-or-create-embedding-session! session-id rasta-id)
+ (testing "its owner still dispatches"
+ (let [response (mcp-request :rasta (ping-call) {"mcp-session-id" session-id})]
+ (is (= 200 (:status response)))
+ (is (= {:ok true :message "pong"} (get-in response [:body :result :structuredContent])))))
+ (testing "another authenticated user gets the answer a nonexistent session gets, and no tool result"
+ (let [response (mcp-request :crowberto (ping-call) {"mcp-session-id" session-id})]
+ (is (= 404 (:status response)))
+ (is (= "Invalid or expired session" (get-in response [:body :error :message])))
+ (is (nil? (get-in response [:body :result])))))
+ (testing "DELETE refuses invalid sessions and reports that valid-session termination is unsupported"
+ (testing "another user cannot tear the session down"
+ (let [response (client/client-full-response (test.users/username->token :crowberto)
+ :delete endpoint
+ {:request-options {:headers {"mcp-session-id" session-id}}})]
+ (is (= 404 (:status response)))))
+ (testing "the session is still owned afterwards, so the foreigner is still refused"
+ (is (= 404 (:status (mcp-request :crowberto (ping-call) {"mcp-session-id" session-id})))))
+ (testing "the owner gets 405 rather than a false acknowledgement of termination"
+ (let [response (client/client-full-response (test.users/username->token :rasta)
+ :delete endpoint
+ {:request-options {:headers {"mcp-session-id" session-id}}})]
+ (is (= 405 (:status response)))
+ (is (= "GET, POST" (get-in response [:headers "Allow"])))))
+ (testing "the owner still holds the session after the refused DELETE"
+ (is (= 200 (:status (mcp-request :rasta (ping-call) {"mcp-session-id" session-id}))))))
+ (finally
+ (mcp.session/delete! session-id rasta-id))))))
+
+;;; ----------------------------------------------- Origin validation ----------------------------------------------
+
+(deftest origin-validation-test
+ ;; The test instance's own origin. Bound explicitly rather than assumed so these cases state what they
+ ;; are comparing against, and do not silently change meaning if the harness's site-url does.
+ (mt/with-temporary-setting-values [site-url "http://127.0.0.1:6274"]
+ (testing (str "GHY-4337: DNS rebinding is the attack this guard names, and comparing two client-supplied "
+ "headers cannot catch it. A rebound `evil.example` resolves to 127.0.0.1 and the browser sends "
+ "BOTH `Origin: http://evil.example` and `Host: evil.example` — they match each other, so an "
+ "Origin/Host check admits the request. `site-url` is the one origin on a request the client "
+ "cannot influence, so that is what an Origin is checked against.")
+ (let [response (mcp-request (jsonrpc-request "initialize")
+ {"host" "evil.example" "origin" "http://evil.example"})]
+ (is (= 403 (:status response)))
+ (is (= "Origin not allowed" (get-in response [:body :error :message])))
+ (is (nil? (get-in response [:headers "Mcp-Session-Id"]))
+ "a refused origin must not be handed a session")))
+ (testing "the instance's own origin is served, whatever Host the request carries"
+ (is (= 200 (:status (mcp-request (jsonrpc-request "initialize")
+ {"host" "anything.example" "origin" "http://127.0.0.1:6274"})))))
+ (testing "a page on another port of the same host is a different origin — the local-MCP threat model, where
+ some other tool on 127.0.0.1 drives this server with the user's cookies"
+ (let [response (mcp-request (jsonrpc-request "initialize")
+ {"host" "127.0.0.1:6274" "origin" "http://127.0.0.1:9999"})]
+ (is (= 403 (:status response)))
+ (is (nil? (get-in response [:headers "Mcp-Session-Id"])))))
+ (testing "and so is the same host on another scheme, which an Origin/Host check could never see: `Host`
+ carries no scheme at all"
+ (is (= 403 (:status (mcp-request (jsonrpc-request "initialize")
+ {"host" "127.0.0.1:6274" "origin" "https://127.0.0.1:6274"})))))
+ (testing "the check runs ahead of authentication, so a cross-origin request is refused rather than challenged"
+ (let [response (client/client-full-response :post 403 endpoint
+ {:request-options {:headers {"host" "127.0.0.1:6274"
+ "origin" "http://evil.example.com"}}}
+ (jsonrpc-request "initialize"))]
+ (is (= 403 (:status response)))
+ (is (nil? (get-in response [:headers "WWW-Authenticate"])))))
+ (testing "a non-browser client sends no Origin at all and is allowed through — browsers are what the guard is for"
+ (is (= 200 (:status (mcp-request (jsonrpc-request "initialize") {"host" "mbtest.poom.dev"})))))
+ (testing "matching is case-insensitive, and a default port compares equal to the same port written out"
+ (mt/with-temporary-setting-values [site-url "https://Example.com"]
+ (is (= 200 (:status (mcp-request (jsonrpc-request "initialize")
+ {"host" "example.com" "origin" "https://example.COM"}))))
+ (is (= 200 (:status (mcp-request (jsonrpc-request "initialize")
+ {"host" "example.com" "origin" "https://example.com:443"})))))))
+ (testing (str "with no instance origin to check against — site-url unset or unparsable — the guard falls back "
+ "to the Origin/Host comparison. Weaker, but a misconfigured instance degrading to the previous "
+ "behaviour beats 403ing its own browser clients.")
+ (with-redefs [system/site-url (constantly nil)]
+ (testing "same host and port is served"
+ (is (= 200 (:status (mcp-request (jsonrpc-request "initialize")
+ {"host" "localhost:3000" "origin" "http://localhost:3000"})))))
+ (testing "a different port on that host is still refused"
+ (is (= 403 (:status (mcp-request (jsonrpc-request "initialize")
+ {"host" "localhost:3000" "origin" "http://localhost:9999"})))))
+ (testing "bracketed IPv6 still parses on both sides"
+ (is (= 200 (:status (mcp-request (jsonrpc-request "initialize")
+ {"host" "[::1]:3000" "origin" "http://[::1]:3000"})))))))
+ (testing "an explicitly configured MCP app origin is allowed cross-host, case-insensitively — the allowlist is
+ the other way in, and is unaffected by which origin the instance itself has"
+ (mt/with-temporary-setting-values [site-url "http://127.0.0.1:6274"
+ mcp.settings/mcp-apps-cors-custom-origins "https://Example.COM"]
+ (let [response (mcp-request (jsonrpc-request "initialize")
+ {"host" "mbtest.poom.dev" "origin" "HTTPS://example.com"})]
+ (is (= 200 (:status response)))
+ (is (some? (get-in response [:headers "Mcp-Session-Id"])))))))
+
+;;; ------------------------------------------------ Bearer tokens -------------------------------------------------
+
+(deftest invalid-bearer-token-returns-401-test
+ (testing "GHY-4337: a bearer token the store does not know authenticates nothing, and says so in the RFC 6750 form
+ a client can act on"
+ ;; the token store lives on the OAuth provider, which only builds against a real site-url
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (let [response (client/client-full-response :post 401 endpoint
+ {:request-options
+ {:headers {"authorization" "Bearer totally-bogus-token"}}}
+ (jsonrpc-request "initialize"))]
+ (is (= 401 (:status response)))
+ (is (nil? (get-in response [:headers "Mcp-Session-Id"])))
+ (is (str/includes? (get-in response [:headers "WWW-Authenticate"] "") "invalid_token"))
+ (is (str/includes? (get-in response [:headers "WWW-Authenticate"] "") "resource_metadata=")
+ "the invalid_token challenge still carries RFC 9728 discovery")))))
+
+(deftest expired-bearer-token-returns-401-test
+ (testing "GHY-4337: an access token past its expiry is refused. The row is still there and still names a real
+ user, so the expiry check is the whole guard"
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (mt/with-model-cleanup [:model/OAuthAccessToken]
+ (let [token (str (random-uuid))]
+ ;; `:token` is stored hashed — the resolver hashes the presented string before looking it up
+ (t2/insert! :model/OAuthAccessToken
+ {:token (oidc.util/hash-token token)
+ :user_id (mt/user->id :crowberto)
+ :client_id (str (random-uuid))
+ :scope ["agent:content:read"]
+ :expiry (- (inst-ms (java.util.Date.)) 3600000)})
+ (let [response (client/client-full-response :post 401 endpoint
+ {:request-options
+ {:headers {"authorization" (str "Bearer " token)}}}
+ (jsonrpc-request "initialize"))]
+ (is (= 401 (:status response)))
+ (is (nil? (get-in response [:headers "Mcp-Session-Id"])))
+ (is (str/includes? (get-in response [:headers "WWW-Authenticate"] "") "invalid_token"))
+ (is (str/includes? (get-in response [:headers "WWW-Authenticate"] "") "resource_metadata=")
+ "the invalid_token challenge still carries RFC 9728 discovery")))))))
+
+(defn- issue-bearer!
+ "Insert an OAuth access token row for `user-id` and return the raw (unhashed) token to present. `:token` is stored
+ hashed, so the row is written the way a real issued token would be — including `client-id` naming a live
+ `oauth_client` row ([[oauth-server.tu/with-oauth-client]]): the resolver fails closed on a token whose issuing
+ client is gone. Call inside `with-model-cleanup`. `scope` defaults to a single v2 read scope; pass it
+ explicitly to mint a token with a different scope shape."
+ ([user-id client-id]
+ (issue-bearer! user-id client-id ["agent:content:read"]))
+ ([user-id client-id scope]
+ (let [token (str (random-uuid))]
+ (t2/insert! :model/OAuthAccessToken
+ {:token (oidc.util/hash-token token)
+ :user_id user-id
+ :client_id client-id
+ :scope scope
+ :expiry (+ (System/currentTimeMillis) 3600000)})
+ token)))
+
+(deftest deactivated-user-bearer-token-is-refused-test
+ (testing (str "GHY-4337 / round-1 4a: a bearer token that names a DEACTIVATED user must not authenticate. The "
+ "session middleware's bearer bridge already refuses it — its user lookup filters on "
+ "`user.is_active = true` and it maps scopes through the `oauth-token->token-scopes` trust hinge — so "
+ "an active user's token reaches the transport already authenticated and a deactivated user's does "
+ "not. The transport must NOT re-resolve the token on its own (that path skipped both the active "
+ "check and the trust hinge, so a disabled user's token authenticated with raw scopes); it must "
+ "return the RFC 6750 invalid_token 401 and dispatch nothing.")
+ ;; `:trashbird` is a globally-committed, pre-seeded INACTIVE user, so it is visible to the handler thread and
+ ;; needs no is_active toggling (a `with-temp` user, created in-test, is not reliably visible cross-thread to the
+ ;; mock handler's request thread, which would 401 for the wrong reason). `:rasta` is the active control.
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (oauth-server.tu/with-oauth-client [client-id]
+ (mt/with-model-cleanup [:model/OAuthAccessToken]
+ (let [initialize (fn [expected-status token]
+ ;; `expected-status` is passed so the client asserts it rather than throwing on an
+ ;; "unexpected" 401 (which triggers its session re-auth path).
+ (client/client-full-response :post expected-status endpoint
+ {:request-options {:headers {"authorization" (str "Bearer " token)}}}
+ (jsonrpc-request "initialize" {:capabilities {}})))]
+ (testing "control: an ACTIVE user's bearer token authenticates and gets a session"
+ (let [response (initialize 200 (issue-bearer! (mt/user->id :rasta) client-id))]
+ (is (= 200 (:status response)))
+ (is (some? (get-in response [:headers "Mcp-Session-Id"])))))
+ (testing "a DEACTIVATED user's bearer token is refused — no session, invalid_token challenge"
+ (let [response (initialize 401 (issue-bearer! (mt/user->id :trashbird) client-id))]
+ (is (= 401 (:status response)))
+ (is (nil? (get-in response [:headers "Mcp-Session-Id"]))
+ "a deactivated user must not be handed a working MCP session")
+ (is (str/includes? (get-in response [:headers "WWW-Authenticate"] "") "invalid_token"))
+ (is (str/includes? (get-in response [:headers "WWW-Authenticate"] "") "resource_metadata=")
+ "the invalid_token challenge still carries RFC 9728 discovery")))))))))
+
+;;; -------------------------------------------------- Throttling --------------------------------------------------
+
+(deftest per-user-throttle-returns-429-test
+ (testing (str "GHY-4337: MCP is auth-gated, so the residual risk is a compromised credential — which is still one "
+ "user. The per-user throttler is what bounds its total throughput across every MCP surface")
+ (let [session-id (initialize!)]
+ ;; Redefine the throttler rather than sending 1000 requests: what is under test is that `check-throttle`
+ ;; refuses on the throttler's terms and shapes the refusal as JSON-RPC, not what the production cap happens
+ ;; to be. `initialize!` runs first so the handshake does not spend the single attempt.
+ (with-redefs-fn {#'mcp.transport/mcp-throttler (throttle/make-throttler :user-id :attempts-threshold 1)}
+ (fn []
+ (is (= 200 (:status (mcp-request (jsonrpc-request "ping") {"mcp-session-id" session-id})))
+ "the one allowed attempt is served")
+ (let [response (mcp-request (jsonrpc-request "ping") {"mcp-session-id" session-id})]
+ (is (= 429 (:status response)))
+ (is (string? (get-in response [:headers "Retry-After"])))
+ (is (= -32000 (get-in response [:body :error :code])))
+ (is (str/starts-with? (get-in response [:body :error :message]) "Too many attempts!"))
+ (is (nil? (get-in response [:body :result])))))))))
+
+(deftest throttle-charges-per-jsonrpc-message-not-per-request-test
+ (testing (str "GHY-4337: the per-minute cap counts JSON-RPC messages, not HTTP requests. A POST can carry a batch, "
+ "so charging one attempt per request would let a single batch smuggle arbitrarily many messages past "
+ "the cap. A batch of N must cost N attempts.")
+ (let [session-id (initialize!)]
+ ;; Threshold 3, so a single 4-message batch already exceeds it — proving the batch is charged per element, not
+ ;; once. `initialize!` ran on the real throttler before the redef, so it doesn't spend an attempt here.
+ (with-redefs-fn {#'mcp.transport/mcp-throttler (throttle/make-throttler :user-id :attempts-threshold 3)}
+ (fn []
+ (let [response (mcp-request [(jsonrpc-request "ping" {} 1)
+ (jsonrpc-request "ping" {} 2)
+ (jsonrpc-request "ping" {} 3)
+ (jsonrpc-request "ping" {} 4)]
+ {"mcp-session-id" session-id})]
+ (is (= 429 (:status response))
+ "a 4-message batch against a cap of 3 is refused — it was charged 4, not 1")
+ (is (= -32000 (get-in response [:body :error :code])))
+ (is (str/starts-with? (get-in response [:body :error :message]) "Too many attempts!"))))))
+ (testing "a single message costs exactly one attempt, so a cap of 1 serves it and refuses the next"
+ (let [session-id (initialize!)]
+ (with-redefs-fn {#'mcp.transport/mcp-throttler (throttle/make-throttler :user-id :attempts-threshold 1)}
+ (fn []
+ (is (= 200 (:status (mcp-request (jsonrpc-request "ping") {"mcp-session-id" session-id})))
+ "the one allowed message is served")
+ (is (= 429 (:status (mcp-request (jsonrpc-request "ping") {"mcp-session-id" session-id})))
+ "the second single-message request is refused")))))))
+
+;;; ------------------------------------------ JSON-RPC framing / batches ------------------------------------------
+
+(deftest jsonrpc-batch-test
+ (let [session-id (initialize!)]
+ (testing "GHY-4337: a batch dispatches every message in it and answers with an array"
+ (let [response (mcp-request [(jsonrpc-request "ping" {} 1)
+ (jsonrpc-request "tools/list" {} 2)]
+ {"mcp-session-id" session-id})]
+ (is (= 200 (:status response)))
+ (is (sequential? (:body response)))
+ (is (= #{1 2} (set (map :id (:body response)))))))
+ (testing "a notification has no id and so gets no response — a batch answers only for the requests in it"
+ (let [response (mcp-request [(jsonrpc-notification "notifications/initialized")
+ (jsonrpc-request "ping" {} 7)]
+ {"mcp-session-id" session-id})]
+ (is (= 200 (:status response)))
+ (is (= [7] (map :id (:body response))))))
+ (testing "a message set that produces no responses at all is a 202 with an empty body, not an empty array"
+ (doseq [[label body] {"a batch of notifications" [(jsonrpc-notification "notifications/initialized")]
+ "a lone notification" (jsonrpc-notification "notifications/initialized")}]
+ (testing label
+ (let [response (mcp-request body {"mcp-session-id" session-id})]
+ (is (= 202 (:status response)))
+ (is (str/blank? (str (:body response))))))))
+ (testing "initialize requires a JSON-RPC 2.0 request and cannot be batched"
+ (doseq [[label message] {"a request without a version" {:method "initialize" :id 1}
+ "a JSON-RPC 1.0 request" {:jsonrpc "1.0" :method "initialize" :id 1}
+ "a notification" {:jsonrpc "2.0" :method "initialize"}}]
+ (testing label
+ (let [response (mcp-request message)]
+ (is (= 400 (:status response)))
+ (is (= -32600 (get-in response [:body :error :code])))
+ (is (= "Invalid request" (get-in response [:body :error :message])))
+ (is (nil? (get-in response [:headers "Mcp-Session-Id"]))))))
+ (testing "a valid initialize request is still forbidden in a batch"
+ (let [response (mcp-request [(jsonrpc-request "initialize")]
+ {"mcp-session-id" session-id})]
+ (is (= 400 (:status response)))
+ (is (= "initialize must not be batched" (get-in response [:body :error :message])))
+ (is (nil? (get-in response [:headers "Mcp-Session-Id"]))))))
+ (testing "an empty batch is invalid per JSON-RPC 2.0"
+ (let [response (mcp-request [] {"mcp-session-id" session-id})]
+ (is (= 400 (:status response)))
+ (is (= "Invalid request: empty batch" (get-in response [:body :error :message])))))
+ (testing "GHY-4337: each batch element is validated on its own (JSON-RPC 2.0 §6) — a malformed element gets its
+ own -32600 rather than being silently dropped by `keep`"
+ (testing "a mix of one valid request and non-object elements answers for every element, not just the valid one"
+ (let [response (mcp-request [(jsonrpc-request "ping" {} 1) 42 "garbage"]
+ {"mcp-session-id" session-id})
+ body (:body response)]
+ (is (= 200 (:status response)))
+ (is (= 3 (count body))
+ "sent three elements, so the array must carry three answers — the two malformed ones are not dropped")
+ (let [valid (first (filter #(= 1 (:id %)) body))]
+ (is (= {} (:result valid)) "the valid request still succeeds")
+ (is (nil? (:error valid))))
+ (let [invalids (remove #(= 1 (:id %)) body)]
+ (is (= 2 (count invalids)))
+ (is (every? #(= -32600 (get-in % [:error :code])) invalids)
+ "each non-object element is Invalid Request")
+ (is (every? #(nil? (:id %)) invalids)
+ "a malformed element's id is null per JSON-RPC 2.0 §5"))))
+ (testing "an all-invalid batch answers with an error per element — NOT a 202 that would falsely signal
+ 'all notifications accepted' for malformed input"
+ (let [response (mcp-request [1 2 3] {"mcp-session-id" session-id})]
+ (is (= 200 (:status response))
+ "an all-invalid batch is answered, not 202-swallowed")
+ (is (= 3 (count (:body response))))
+ (is (every? #(= -32600 (get-in % [:error :code])) (:body response)))))
+ (testing "an object without a JSON-RPC 2.0 envelope and string method is Invalid Request (-32600)"
+ (doseq [[label malformed] {"missing method" {:jsonrpc "2.0" :id 5}
+ "non-string method" {:jsonrpc "2.0" :method 42 :id 5}
+ "missing version" {:method "ping" :id 5}
+ "missing version and id" {:method "ping"}
+ "JSON-RPC 1.0" {:jsonrpc "1.0" :method "ping" :id 5}}]
+ (testing label
+ (testing "as a single message"
+ (let [response (mcp-request malformed {"mcp-session-id" session-id})]
+ (is (= 400 (:status response)))
+ (is (= -32600 (get-in response [:body :error :code])))
+ (is (= "Invalid request" (get-in response [:body :error :message])))))
+ (testing "inside a batch, alongside a valid request"
+ (let [response (mcp-request [(jsonrpc-request "ping" {} 1) malformed]
+ {"mcp-session-id" session-id})
+ body (:body response)]
+ (is (= 200 (:status response)))
+ (is (= 2 (count body)))
+ (is (= -32600
+ (get-in (first (remove #(= 1 (:id %)) body)) [:error :code])))))))))))
+
+;;; ------------------------------------------------------ SSE -----------------------------------------------------
+
+(deftest notifications-get-no-response-test
+ (testing "JSON-RPC 2.0 §4.1: a message with no `id` is a notification and MUST NOT be answered. A known
+ method sent without an id used to execute AND reply with `\"id\": null` — the server inventing a
+ response to something the client is not listening for, and a shape §5 reserves for a request that
+ could not be parsed at all."
+ (let [session-id (initialize!)]
+ (testing "a known method as a notification executes silently and yields 202 with an empty body"
+ (let [response (mcp-request {:jsonrpc "2.0" :method "ping"} {"mcp-session-id" session-id})]
+ (is (= 202 (:status response)))
+ (is (str/blank? (str (:body response))))))
+ (testing "the same method WITH an id is answered as before — this must not silence real requests"
+ (let [response (mcp-request (jsonrpc-request "ping") {"mcp-session-id" session-id})]
+ (is (= 200 (:status response)))
+ (is (= 1 (get-in response [:body :id])))))
+ (testing "a notification for an unknown method is also silent, rather than a method-not-found reply"
+ (is (= 202 (:status (mcp-request {:jsonrpc "2.0" :method "no/such/method"}
+ {"mcp-session-id" session-id})))))
+ (testing "in a batch, notifications drop out and only the real requests are answered"
+ (let [response (mcp-request [{:jsonrpc "2.0" :method "ping"}
+ (jsonrpc-request "ping" {} 7)
+ {:jsonrpc "2.0" :method "notifications/initialized"}]
+ {"mcp-session-id" session-id})]
+ (is (= 200 (:status response)))
+ (is (= [7] (mapv :id (:body response))))))
+ (testing "a batch of nothing but notifications is a 202, not an empty array"
+ (let [response (mcp-request [{:jsonrpc "2.0" :method "ping"}
+ {:jsonrpc "2.0" :method "notifications/initialized"}]
+ {"mcp-session-id" session-id})]
+ (is (= 202 (:status response)))
+ (is (str/blank? (str (:body response))))))
+ (testing "a malformed element still answers with a null id — §5 requires that for something that could
+ not be parsed, which is a different case from a well-formed notification"
+ (let [response (mcp-request [{:jsonrpc "2.0" :no-method-here true}]
+ {"mcp-session-id" session-id})]
+ (is (= 200 (:status response)))
+ (is (= [-32600] (mapv #(get-in % [:error :code]) (:body response)))))))))
+
+(deftest sse-post-response-test
+ (testing "GHY-4337: a client that accepts text/event-stream gets its responses framed as SSE events"
+ (let [session-id (initialize!)
+ response (mcp-request (jsonrpc-request "ping") {"mcp-session-id" session-id
+ "accept" "text/event-stream"})]
+ (is (= 200 (:status response)))
+ (is (= "text/event-stream" (get-in response [:headers "Content-Type"])))
+ (is (str/includes? (:body response) "event: message"))
+ (is (str/includes? (:body response) "data: "))))
+ (testing "initialize over SSE still issues the session in a header, which is where the client looks for it"
+ (let [response (mcp-request (jsonrpc-request "initialize") {"accept" "text/event-stream"})
+ data (->> (str/split-lines (:body response))
+ (keep #(when (str/starts-with? % "data: ") (json/decode+kw (subs % 6))))
+ first)]
+ (is (= 200 (:status response)))
+ (is (= "text/event-stream" (get-in response [:headers "Content-Type"])))
+ (is (some? (get-in response [:headers "Mcp-Session-Id"])))
+ (is (= "2025-03-26" (get-in data [:result :protocolVersion])))))
+ (testing "a client that does not ask for SSE keeps getting JSON"
+ (let [session-id (initialize!)
+ response (mcp-request (jsonrpc-request "ping") {"mcp-session-id" session-id})]
+ (is (= "application/json" (get-in response [:headers "Content-Type"])))
+ (is (map? (:body response))))))
+
+(deftest sse-get-stream-is-session-guarded-test
+ (testing (str "GHY-4337: the GET keepalive stream holds a connection for as long as the client keeps it, so the "
+ "session guard has to refuse before the stream opens rather than after")
+ (testing "no session header"
+ (let [response (client/client-full-response (test.users/username->token :crowberto) :get endpoint)]
+ (is (= 400 (:status response)))
+ (is (= "Missing Mcp-Session-Id header" (get-in response [:body :error :message])))))
+ (testing "a session id the server never issued"
+ (let [response (client/client-full-response (test.users/username->token :crowberto)
+ :get endpoint
+ {:request-options {:headers {"mcp-session-id" "bogus-session-id"}}})]
+ (is (= 404 (:status response)))
+ (is (= "Invalid or expired session" (get-in response [:body :error :message])))))))
+
+;;; ---------------------------------------------- Eval session override -------------------------------------------
+
+(deftest ^:parallel eval-session-override-test
+ (testing "GHY-4337: the x-eval-session-id header names a trace file, so it is honored only when it is a safe name"
+ (let [override #'mcp.transport/eval-session-override]
+ (testing "a bare uuid (what the harness mints) is honored"
+ (is (= "1ae768c9-5773-48dd-afca-c75780dae84c"
+ (override {:headers {"x-eval-session-id" "1ae768c9-5773-48dd-afca-c75780dae84c"}}))))
+ (testing "a safe slug is honored"
+ (is (= "evalprobe_1.2" (override {:headers {"x-eval-session-id" "evalprobe_1.2"}}))))
+ (testing "path traversal / unsafe chars are rejected, falling back to the Mcp-Session-Id correlator"
+ (is (nil? (override {:headers {"x-eval-session-id" "../etc/passwd"}})))
+ (is (nil? (override {:headers {"x-eval-session-id" "a/b"}})))
+ (is (nil? (override {:headers {"x-eval-session-id" ".hidden"}}))))
+ (testing "a value over max-session-id-length is rejected even though every char is safe"
+ ;; one past the real cap — the boundary a looser copy of the contract would wrongly accept, and then 500 on
+ ;; downstream in checked-session-id
+ (is (= 200 ait/max-session-id-length))
+ (is (nil? (override {:headers {"x-eval-session-id" (apply str (repeat 201 "a"))}})))
+ (testing "the id exactly at the cap is honored, returned verbatim"
+ (let [id (apply str (repeat 200 "a"))]
+ (is (= id (override {:headers {"x-eval-session-id" id}}))))))
+ (testing "absent header yields nil"
+ (is (nil? (override {:headers {}})))))))
+
+(deftest ^:parallel redact-ui-credentials-test
+ (testing "a resources/read response has its embedded UI credential scrubbed before it is recorded
+ into an eval trace — a recorded credential is a live bearer authenticator"
+ (let [redact @#'mcp.transport/redact-ui-credentials
+ response {:jsonrpc "2.0"
+ :id 1
+ :result {:contents [{:uri "ui://metabase/visualize-query.html"
+ :mimeType "text/html;profile=mcp-app"
+ :text "<script>\nuiCredential: \"top.secret.credential\",\n</script>"}
+ {:uri "ui://metabase/logo.png" :blob "aGk=" :text nil}]}}
+ redacted (redact response)]
+ (is (not (str/includes? (get-in redacted [:result :contents 0 :text]) "top.secret.credential")))
+ (is (str/includes? (get-in redacted [:result :contents 0 :text]) "uiCredential: \"[redacted]\""))
+ (testing "a blob content with no :text passes through untouched"
+ (is (nil? (get-in redacted [:result :contents 1 :text]))))))
+ (testing "a tools/call result's private MCP Apps _meta block (refresh_ui_credential's channel) is stripped"
+ (let [redact @#'mcp.transport/redact-ui-credentials
+ response {:jsonrpc "2.0"
+ :id 4
+ :result {:content [{:type "text" :text "MCP UI credential refreshed."}]
+ :_meta {v2.common/mcp-apps-meta-key {:credential "top.secret.credential"
+ :sessionId "s"}
+ :other "kept"}}}
+ redacted (redact response)]
+ (is (not (str/includes? (pr-str redacted) "top.secret.credential")))
+ (is (= {:other "kept"} (get-in redacted [:result :_meta])))
+ (is (= (:content (:result response)) (get-in redacted [:result :content])))))
+ (testing "responses without resource contents pass through untouched"
+ (let [redact @#'mcp.transport/redact-ui-credentials]
+ (doseq [response [{:jsonrpc "2.0" :id 2 :result {:content [{:type "text" :text "hi"}]}}
+ {:jsonrpc "2.0" :id 3 :error {:code -32603 :message "Internal error"}}
+ nil]]
+ (is (= response (redact response)))))))
+
+(deftest legacy-scoped-bearer-token-never-yields-an-empty-tool-list-test
+ (testing (str "GHY-4343: `/api/metabase-mcp` now serves the v2 tool surface, but every MCP client connected to a "
+ "shipped v0.60-v0.63 release holds a token carrying the pre-v2 per-entity agent scopes. No legacy "
+ "scope satisfies any v2 tool scope and `registry/list-tools` filters silently, so the pre-fix "
+ "failure mode was a successful handshake followed by HTTP 200 with an empty tools list - no error, "
+ "nothing logged, and no self-heal (the refresh grant copies scope forward and can only narrow). "
+ "`RevokeLegacyMcpOAuthTokens` stamps such tokens revoked so the client is refused outright and "
+ "re-authenticates. Whichever way it resolves, it must never be a 200 carrying zero tools.")
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (oauth-server.tu/with-oauth-client [client-id]
+ (mt/with-model-cleanup [:model/OAuthAccessToken]
+ (let [;; Exactly the review's token: one per-entity scope the v2 surface never gates on, plus
+ ;; `agent:resource:read`, which gates a resource rather than any tool.
+ token (issue-bearer! (mt/user->id :rasta) client-id
+ ["agent:question:create" "agent:resource:read"])
+ headers (fn [& {:as extra}]
+ {:request-options {:headers (merge {"authorization" (str "Bearer " token)} extra)}})
+ ;; The tool list is only reachable through a session, so the handshake runs first. Its status is
+ ;; not asserted: the point is what `tools/list` can be answered, and revoking the token moves the
+ ;; refusal to this call rather than removing it.
+ _ (testing "before the migration this token reproduces the silent failure exactly"
+ (let [sid (get-in (client/client-full-response
+ :post 200 "metabase-mcp" (headers)
+ (jsonrpc-request "initialize" {:capabilities {}}))
+ [:headers "Mcp-Session-Id"])
+ r (client/client-full-response :post 200 "metabase-mcp"
+ (headers "mcp-session-id" sid)
+ (jsonrpc-request "tools/list" {} 2))]
+ (is (and (= 200 (:status r)) (empty? (get-in r [:body :result :tools])))
+ (str "characterizing the bug: a legacy-scoped token handshakes, then gets 200 with "
+ "zero tools - no error and nothing logged. This is what the migration ends."))))
+ ;; Then put the token in the state `RevokeLegacyMcpOAuthTokens` leaves it in. The migration
+ ;; class itself is exercised in `metabase.app-db.custom-migrations-test`, against the changelog;
+ ;; what this test owns is the consequence at the transport, which is the revoked stamp.
+ _ (t2/update! :model/OAuthAccessToken
+ {:token (oidc.util/hash-token token)} {:revoked_at :%now})
+ init (client/client-full-response :post 401 "metabase-mcp" (headers)
+ (jsonrpc-request "initialize" {:capabilities {}}))]
+ (testing "after the migration the token is refused at the handshake, so no empty tool list is reachable"
+ (is (= 401 (:status init)))
+ (is (nil? (get-in init [:headers "Mcp-Session-Id"]))
+ "a revoked token must not be handed a working MCP session")
+ (let [challenge (get-in init [:headers "WWW-Authenticate"] "")]
+ (is (str/includes? challenge "invalid_token"))
+ (is (str/includes? challenge "resource_metadata=")
+ "the challenge carries RFC 9728 discovery, so the client knows where to re-authenticate")
+ (is (str/includes? challenge "agent:content:read")
+ "and names the v2 scopes to ask for, which the widened client snapshot now validates")))))))))
diff --git a/test/metabase/mcp/ui_surface_test.clj b/test/metabase/mcp/ui_surface_test.clj
new file mode 100644
index 00000000000..cca64d7c35f
--- /dev/null
+++ b/test/metabase/mcp/ui_surface_test.clj
@@ -0,0 +1,186 @@
+(ns metabase.mcp.ui-surface-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.api.macros.scope :as scope]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.ui-surface :as mcp.ui-surface]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.test.http-client :as client]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(deftest off-surface-routes-are-not-authenticated-test
+ (testing "GHY-4400: the general REST endpoints the iframe used to reach are off the surface"
+ (are [method uri] (not (mcp.ui-surface/on-surface? method uri))
+ :get "/api/user/current"
+ :get "/api/session/properties"
+ :get "/api/collection"
+ :put "/api/user/1")))
+
+(deftest request-surface-is-a-reviewed-allowlist-test
+ (testing "GHY-4400: every route here is one the credential reaches but the bearer token that minted it could
+ NOT — these endpoints declare no `:scope`, so `ensure-scopes-checked` 403s a scoped bearer on all of
+ them. That delta is the whole point of the credential, and it is defensible only while this set stays
+ small and reviewed. What the ticket removed was the part that was not: `/api/user/current` and
+ `/api/session/properties`, which the set had accumulated because the SDK happened to call them.
+
+ Adding a route here is a decision to widen that delta. Changing this test is how you make it."
+ (is (= #{[:get "/api/embed-mcp/bootstrap"]
+ [:post "/api/embed-mcp/feedback"]
+ [:post "/api/embed-mcp/drills"]
+ [:post "/api/dataset"]
+ [:post "/api/dataset/pivot"]
+ [:post "/api/dataset/query_metadata"]
+ [:post "/api/dataset/parameter/remapping"]}
+ (set (keys mcp.ui-surface/request-surface))))
+ (is (= 1 (count mcp.ui-surface/parameterized-request-surface))
+ "a path-parameter route is still a route on the surface, and still a decision")
+ (is (mcp.ui-surface/on-surface? :get (str "/api/embed-mcp/queries/" (random-uuid))))
+ (is (not (mcp.ui-surface/on-surface? :get "/api/embed-mcp/queries/not-a-uuid"))
+ "the pattern pins the handle's shape, so a non-uuid path is off the surface entirely rather
+ than merely 404 — `queries-get-rejects-bad-input-test` asserts the 401 that follows")))
+
+(deftest scope-satisfied?-test
+ (let [bootstrap #(mcp.ui-surface/scope-satisfied? :get "/api/embed-mcp/bootstrap" %)
+ dataset #(mcp.ui-surface/scope-satisfied? :post "/api/dataset" %)]
+ (testing "a route off the surface is never satisfied"
+ (is (nil? (mcp.ui-surface/scope-satisfied?
+ :get "/api/user/current" {:token-scopes #{::scope/unrestricted}}))))
+ (testing "a route that costs no scope needs only a valid credential"
+ (is (true? (bootstrap {:token-scopes #{}}))))
+ (testing "a route that costs a scope needs the minting session to have held it"
+ (is (false? (dataset {:token-scopes #{"agent:search"}})))
+ (is (true? (dataset {:token-scopes #{"agent:query:run"}})))
+ (is (true? (dataset {:token-scopes #{"agent:query:*"}})))
+ (is (true? (dataset {:token-scopes #{::scope/unrestricted}}))))
+ (testing "a v2 credential minted before the scope claim existed reaches only the free routes"
+ (is (true? (bootstrap {})))
+ (is (false? (dataset {}))))
+ (testing "the `:legacy` exemption retired with v1 — the marker buys nothing now, so a claim carrying it
+ is still judged on its scopes"
+ (is (false? (dataset {:legacy true}))))))
+
+(defn- request-with-ui-credential
+ [method expected-status url credential session-id]
+ (client/client-full-response method expected-status url
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential
+ "mcp-session-id" session-id}}}))
+
+(deftest ui-credential-cannot-read-the-profile-test
+ (testing "GHY-4400: `refresh_ui_credential` is not a scope-escalation primitive — the credential cannot read
+ the endpoints a narrow agent token is refused"
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id)
+ credential (mcp.session/issue-ui-credential session-id user-id #{"agent:query:run"})]
+ (is (= 401 (:status (request-with-ui-credential
+ :get 401 "user/current" credential session-id))))
+ (testing "`/api/session/properties` serves anonymous callers, so dropping it from the surface degrades the
+ credential to the public payload rather than refusing it"
+ (let [with-credential (:body (request-with-ui-credential
+ :get 200 "session/properties" credential session-id))
+ anonymous (:body (client/client-full-response :get 200 "session/properties"))
+ authenticated (mt/user-http-request :rasta :get 200 "session/properties")]
+ (is (= (set (keys anonymous)) (set (keys with-credential)))
+ "the credential buys nothing here")
+ (is (seq (remove (set (keys anonymous)) (keys authenticated)))
+ "and a logged-in user really does see more, so the assertion above is not vacuous")))
+ (is (= 200 (:status (request-with-ui-credential
+ :get 200 "embed-mcp/bootstrap" credential session-id)))
+ "the purpose-built endpoint serves what the iframe actually needs"))))
+
+(deftest drills-costs-the-query-scope-test
+ (testing "GHY-4400: the scope gate covers the MCP module's own routes, not just the query endpoints"
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id)
+ post! (fn [scopes expected-status]
+ (client/client-full-response
+ :post expected-status "embed-mcp/drills"
+ {:request-options
+ {:headers {"x-metabase-mcp-ui-auth" (mcp.session/issue-ui-credential
+ session-id user-id scopes)
+ "mcp-session-id" session-id}}}
+ {:encodedQuery "ZW5jb2RlZA=="}))]
+ (is (= 403 (:status (post! #{"agent:search"} 403))))
+ (is (= 200 (:status (post! #{"agent:query:run"} 200)))))))
+
+(deftest dataset-routes-cost-the-query-scope-test
+ (testing "GHY-4400: a route on the surface is refused unless the minting session's signed scopes cover it"
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id)
+ ;; spelled out rather than via `mt/mbql-query`, which is deprecated: this test needs
+ ;; nothing from that macro beyond a valid non-native query, so that the only thing
+ ;; separating the two statuses below is the scope gate
+ query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :venues), :limit 1}}
+ post! (fn [credential expected-status]
+ (client/client-full-response
+ :post expected-status "dataset"
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential
+ "mcp-session-id" session-id}}}
+ query))]
+ (is (= 403 (:status (post! (mcp.session/issue-ui-credential session-id user-id #{"agent:search"})
+ 403))))
+ (is (= 202 (:status (post! (mcp.session/issue-ui-credential session-id user-id #{"agent:query:run"})
+ 202)))))))
+
+;;; ---------------------------------------- declared-scope collision guard ----------------------------------------
+
+(def ^:private surface-probes
+ "One probe per route on the surface: `[[method uri] body]`, where `uri` carries the `/api/` prefix so it can be
+ matched against [[mcp.ui-surface/request-surface]]'s keys.
+
+ The bodies are deliberately minimal rather than valid. The probe only has to reach the handler — what the
+ handler then does with a thin body is not what is under test."
+ {[:get "/api/embed-mcp/bootstrap"] nil
+ [:post "/api/embed-mcp/feedback"] {}
+ [:post "/api/embed-mcp/drills"] {:encodedQuery "ZW5jb2RlZA=="}
+ [:post "/api/dataset"] {}
+ [:post "/api/dataset/pivot"] {}
+ [:post "/api/dataset/query_metadata"] {}
+ [:post "/api/dataset/parameter/remapping"] {}})
+
+(def ^:private scope-rejections
+ "The two error codes the endpoint scope layer answers with: [[scope/enforce-scope]] refusing a granted set that
+ does not satisfy a declared `:scope`, and [[scope/ensure-scopes-checked]] refusing a scoped credential on an
+ endpoint that declares none."
+ #{"unsupported_scope" "scope_not_permitted"})
+
+(deftest every-surface-route-survives-the-endpoint-scope-layer-test
+ (testing "GHY-4400: a route the credential is allowed to authenticate must not then be refused by the endpoint
+ scope layer. The two confinement mechanisms are independent — `request-surface` decides what the
+ credential may authenticate, a `defendpoint`'s `:scope` decides what a granted scope set may reach —
+ and the credential carries `::scope/mcp-ui`, which satisfies no declared `:scope` by design.
+
+ So declaring a `:scope` on any route of this surface makes the iframe's request 403 while every other
+ caller is unaffected: an ordinary session carries `::scope/unrestricted` and passes. That is invisible
+ in review (the surface and the endpoint live in different modules, and the change merges clean) and
+ invisible at runtime (the iframe simply stops rendering). This is the test that sees it.
+
+ If this goes red, do NOT widen the credential to whatever scope was declared. Name the shared
+ capability, tag the route with it, and mint it into the credential's request-time `:token-scopes` —
+ the grant side of `scope-matches?` is already a set."
+ (testing "every route on the surface has a probe, so adding one cannot silently skip this check"
+ (is (= (set (keys mcp.ui-surface/request-surface))
+ (set (keys surface-probes)))))
+ (let [user-id (mt/user->id :crowberto)
+ session-id (mcp.session/create! user-id)
+ ;; the scope the whole surface costs, so nothing here is refused by `ui-surface` itself —
+ ;; `dataset-routes-cost-the-query-scope-test` above is what covers that gate
+ credential (mcp.session/issue-ui-credential session-id user-id #{"agent:query:run"})
+ probe! (fn [[method uri] body]
+ (let [url (str/replace-first uri #"^/api/" "")]
+ (apply client/client-full-response method url
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential
+ "mcp-session-id" session-id}}}
+ (when body [body]))))]
+ (doseq [[route body] (concat surface-probes
+ [[[:get (str "/api/embed-mcp/queries/" (random-uuid))] nil]])]
+ (testing (str (first route) " " (second route))
+ (let [{:keys [body]} (probe! route body)]
+ (is (not (contains? scope-rejections (:error body)))
+ "refused by the endpoint scope layer — see this test's docstring")))))))
diff --git a/test/metabase/mcp/v2/api_test.clj b/test/metabase/mcp/v2/api_test.clj
new file mode 100644
index 00000000000..ce3066fab43
--- /dev/null
+++ b/test/metabase/mcp/v2/api_test.clj
@@ -0,0 +1,639 @@
+(ns metabase.mcp.v2.api-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.ai-tracing.core :as ait]
+ [metabase.auth-identity.core :as auth-identity]
+ [metabase.mcp.paths :as mcp.paths]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.settings :as mcp.settings]
+ [metabase.mcp.ui-resource :as mcp.ui-resource]
+ [metabase.mcp.v2.api :as v2.api]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resources :as v2.resources]
+ [metabase.mcp.v2.test-util]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.oauth-server.test-util :as oauth-server.tu]
+ [metabase.server.middleware.session :as mw.session]
+ [metabase.test :as mt]
+ [metabase.test.data.users :as test.users]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.test.http-client :as client]
+ [oidc-provider.util :as oidc.util]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(def ^:private endpoint "metabase-mcp")
+
+(defn- mcp-request
+ ([body]
+ (mcp-request body {}))
+ ([body extra-headers]
+ (client/client-full-response (test.users/username->token :crowberto)
+ :post endpoint
+ {:request-options {:headers extra-headers}}
+ body)))
+
+(defn- jsonrpc-request
+ ([method] (jsonrpc-request method {}))
+ ([method params] {:jsonrpc "2.0" :method method :params params :id 1}))
+
+(defn- initialize!
+ "Perform the initialize handshake; returns [session-id init-response]."
+ []
+ (let [response (mcp-request (jsonrpc-request "initialize" {:capabilities {}}))
+ session-id (get-in response [:headers "Mcp-Session-Id"])]
+ (mcp-request {:jsonrpc "2.0" :method "notifications/initialized" :params {}}
+ {"mcp-session-id" session-id})
+ [session-id response]))
+
+(deftest mcp-enabled-gate-test
+ (testing "the route serves by default — `mcp-enabled?` is the admin toggle and defaults to true"
+ (is (= 200 (:status (mcp-request (jsonrpc-request "initialize"))))))
+ (testing "GHY-4250: the admin toggle darkens the surface"
+ (mt/with-temporary-setting-values [mcp.settings/mcp-enabled? false]
+ (let [response (mcp-request (jsonrpc-request "initialize"))]
+ (is (= 403 (:status response)))
+ (is (= "MCP server is not enabled." (:body response)))))))
+
+(deftest every-alias-serves-v2-test
+ (testing "GHY-4250: every MCP path reaches THIS surface now that the legacy paths are repointed. A 200 and
+ a session header are not enough to prove that — the retired v1 handler produced both — so each
+ alias is asked for its tool list and must name a v2-only tool. Reverting either route entry (or a
+ merge-forward resolving the wrong way) fails here rather than passing silently."
+ (doseq [path ["metabase-mcp" "mcp"]]
+ (testing path
+ (let [init (client/client-full-response (test.users/username->token :crowberto)
+ :post path
+ {:request-options {:headers {}}}
+ (jsonrpc-request "initialize"))
+ session-id (get-in init [:headers "Mcp-Session-Id"])
+ tools (-> (client/client-full-response
+ (test.users/username->token :crowberto)
+ :post path
+ {:request-options {:headers {"mcp-session-id" session-id}}}
+ (jsonrpc-request "tools/list"))
+ (get-in [:body :result :tools]))]
+ (is (= 200 (:status init)))
+ (is (some? session-id))
+ (is (some #(= "learn" (:name %)) tools)
+ "learn is registered only by the v2 registry, so seeing it proves v2 answered"))))))
+
+(deftest alias-discovery-challenge-names-the-path-the-client-hit-test
+ (testing "GHY-4250: an unauthenticated request gets a 401 whose resource_metadata names the alias the client
+ actually connected through, not the canonical path — a client configured against /api/mcp must be
+ pointed back at /api/mcp. Ported from v1's api-test, which carried this until v1 was deleted."
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (doseq [[path expected] [["metabase-mcp" "/api/metabase-mcp"]
+ ["mcp" "/api/mcp"]]]
+ (testing path
+ (let [response (client/client-full-response :post 401 path
+ {:request-options {:headers {}}}
+ (jsonrpc-request "initialize"))
+ header (get-in response [:headers "WWW-Authenticate"])]
+ ;; The closing quote anchors the match: without it "/api/mcp" also matches "/api/metabase-mcp".
+ (is (str/includes? header (str "oauth-protected-resource" expected "\"")))))))))
+
+(deftest initialize-test
+ (testing "initialize returns the handshake and a session header"
+ (let [[session-id response] (initialize!)]
+ (is (= 200 (:status response)))
+ (is (some? session-id))
+ (is (= "2025-03-26" (get-in response [:body :result :protocolVersion])))
+ (is (= {:name "metabase" :version "0.1.0"} (get-in response [:body :result :serverInfo])))
+ (testing "GHY-4157: tools and resources are advertised — resources serve the MCP Apps iframe shells; prompts stay unimplemented and so unadvertised"
+ (is (= {:tools {:listChanged true} :resources {}}
+ (get-in response [:body :result :capabilities]))))
+ (testing "the handshake carries the skills instructions — the one pre-tool-call channel"
+ (is (re-find #"learn\(\)" (get-in response [:body :result :instructions])))))))
+
+(deftest tools-list-test
+ (let [[session-id _] (initialize!)
+ response (mcp-request (jsonrpc-request "tools/list")
+ {"mcp-session-id" session-id})
+ tools (get-in response [:body :result :tools])]
+ (testing "the registry drives tools/list; cookie sessions see every tool"
+ (is (= 200 (:status response)))
+ (is (some #(= "test_echo" (:name %)) tools)))
+ (testing "inputSchema is strict JSON Schema (required + closed), safe for strict clients"
+ (let [schema (:inputSchema (first (filter #(= "test_echo" (:name %)) tools)))]
+ (is (= "object" (:type schema)))
+ (is (false? (:additionalProperties schema)))))))
+
+(deftest tools-call-test
+ (let [[session-id _] (initialize!)]
+ (testing "tools/call dispatches through the registry"
+ (let [response (mcp-request (jsonrpc-request "tools/call" {:name "test_echo" :arguments {}})
+ {"mcp-session-id" session-id})
+ result (get-in response [:body :result])]
+ (is (= 200 (:status response)))
+ (is (not (:isError result)))
+ (is (= {:ok true :message "pong"} (:structuredContent result)))))
+ (testing "argument validation failures are JSON-RPC invalid-params errors, not MCP tool results"
+ (let [response (mcp-request (jsonrpc-request "tools/call"
+ {:name "test_echo" :arguments {:message 42}})
+ {"mcp-session-id" session-id})]
+ (is (= -32602 (get-in response [:body :error :code])))
+ (is (str/starts-with? (get-in response [:body :error :message]) "Invalid arguments"))
+ (is (not (contains? (:body response) :result)))))
+ (testing "an unknown tool is a JSON-RPC method-not-found error"
+ (let [response (mcp-request (jsonrpc-request "tools/call" {:name "nope" :arguments {}})
+ {"mcp-session-id" session-id})]
+ (is (= -32601 (get-in response [:body :error :code])))
+ (is (= "Unknown tool: nope" (get-in response [:body :error :message])))
+ (is (not (contains? (:body response) :result)))))))
+
+(deftest disabled-tools-kill-switch-test
+ (let [[session-id _] (initialize!)]
+ (mt/with-temporary-setting-values [mcp.settings/mcp-v2-disabled-tools ["test_echo"]]
+ (testing "a disabled tool disappears from tools/list"
+ (let [response (mcp-request (jsonrpc-request "tools/list")
+ {"mcp-session-id" session-id})]
+ (is (not (some #(= "test_echo" (:name %))
+ (get-in response [:body :result :tools]))))))
+ (testing "a disabled tool is rejected by tools/call as if it never existed"
+ (let [response (mcp-request (jsonrpc-request "tools/call" {:name "test_echo" :arguments {}})
+ {"mcp-session-id" session-id})]
+ (is (= -32601 (get-in response [:body :error :code])))
+ (is (= "Unknown tool: test_echo" (get-in response [:body :error :message])))
+ (is (not (contains? (:body response) :result))))))))
+
+(deftest method-dispatch-fallthrough-test
+ (let [[session-id _] (initialize!)]
+ (testing "methods the surface can't serve fall through to JSON-RPC method-not-found"
+ (doseq [method ["prompts/list"]]
+ (testing method
+ (let [response (mcp-request (jsonrpc-request method)
+ {"mcp-session-id" session-id})]
+ (is (= -32601 (get-in response [:body :error :code])))
+ (is (str/includes? (get-in response [:body :error :message]) "Method not found"))))))
+ (testing "ping is handled and returns an empty success result, not a fallthrough error"
+ (let [response (mcp-request (jsonrpc-request "ping")
+ {"mcp-session-id" session-id})]
+ (is (= 200 (:status response)))
+ (is (nil? (get-in response [:body :error])))
+ (is (= {} (get-in response [:body :result])))))))
+
+(deftest resources-list-and-read-test
+ (mcp.ui-resource/with-fallback-template
+ (let [[session-id _] (initialize!)
+ listed (-> (mcp-request (jsonrpc-request "resources/list")
+ {"mcp-session-id" session-id})
+ (get-in [:body :result :resources]))]
+ (testing "GHY-4157: resources/list serves the MCP Apps iframe shells and the fields catalog"
+ (is (= #{v2.resources/visualize-query-uri v2.resources/render-drill-through-uri
+ v2.resources/fields-catalog-uri}
+ (set (map :uri listed))))
+ (is (every? #(= "text/html;profile=mcp-app" (:mimeType %))
+ (remove #(= v2.resources/fields-catalog-uri (:uri %)) listed)))
+ (is (= "application/json"
+ (:mimeType (first (filter #(= v2.resources/fields-catalog-uri (:uri %)) listed))))))
+ (testing "GHY-4157: resources/read renders a shell the host can sandbox"
+ (let [content (-> (mcp-request (jsonrpc-request "resources/read"
+ {:uri v2.resources/visualize-query-uri})
+ {"mcp-session-id" session-id})
+ (get-in [:body :result :contents])
+ first)]
+ (is (= v2.resources/visualize-query-uri (:uri content)))
+ (is (str/includes? (:text content) "metabaseConfig"))
+ (is (contains? (get-in content [:_meta :ui]) :csp))))
+ (testing "GHY-4157: an unknown URI is an invalid-params error, not a rendered shell"
+ (let [response (mcp-request (jsonrpc-request "resources/read" {:uri "ui://metabase/nope.html"})
+ {"mcp-session-id" session-id})]
+ (is (= -32602 (get-in response [:body :error :code])))))
+ (testing "GHY-4157: a missing uri parameter is rejected"
+ (let [response (mcp-request (jsonrpc-request "resources/read" {})
+ {"mcp-session-id" session-id})]
+ (is (= -32602 (get-in response [:body :error :code]))))))))
+
+(deftest credential-is-minted-only-where-it-is-embedded-test
+ (testing "GHY-4157: `resources/read` minted a UI credential before it knew what had been asked for, so every
+ read paid for one and handed it to the render — including data resources whose render-fn ignores it,
+ and reads that turn out to be unknown or scope-denied. A credential is a live 5-minute authenticator
+ for the /api/dataset surface; it should exist only where something actually embeds it, so that a
+ resource added later cannot start leaking one by accident."
+ (mcp.ui-resource/with-fallback-template
+ (let [[session-id _] (initialize!)
+ minted (atom 0)]
+ ;; Delegation captures the original through `mt/original-fn` — a value captured before the
+ ;; redef would be the dynamic-redef proxy if an earlier test already patched the var.
+ (mt/with-dynamic-fn-redefs [mcp.session/issue-ui-credential
+ (fn [& args]
+ (swap! minted inc)
+ (apply (mt/original-fn #'mcp.session/issue-ui-credential) args))]
+ (testing "a data resource does not mint one — its render-fn never asks"
+ (mcp-request (jsonrpc-request "resources/read" {:uri v2.resources/fields-catalog-uri})
+ {"mcp-session-id" session-id})
+ (is (zero? @minted)))
+ (testing "nor does a read that resolves to nothing"
+ (mcp-request (jsonrpc-request "resources/read" {:uri "ui://metabase/nope.html"})
+ {"mcp-session-id" session-id})
+ (is (zero? @minted)))
+ (testing "the iframe shell still gets exactly one, and still embeds it"
+ (let [text (-> (mcp-request (jsonrpc-request "resources/read"
+ {:uri v2.resources/visualize-query-uri})
+ {"mcp-session-id" session-id})
+ (get-in [:body :result :contents])
+ first
+ :text)]
+ (is (= 1 @minted))
+ (is (str/includes? text "uiCredential")))))))))
+
+(deftest ^:parallel v2-surface-scopes-match-metabot-scope-test
+ (testing "`v2-surface-scopes` spells its scopes as literals because `metabase.mcp.paths` must stay
+ dependency-free — `metabase.server.middleware.security` requires `metabase.mcp.core`, so requiring
+ `metabot.scope` from anything `mcp.core` reaches deadlocks namespace loading at web-server start.
+ This is what keeps the literals honest in place of that require."
+ (is (= [metabot.scope/agent-content-read
+ metabot.scope/agent-content-write
+ metabot.scope/agent-query-run
+ metabot.scope/agent-sql-run
+ metabot.scope/agent-delivery-write
+ metabot.scope/agent-resource-read]
+ mcp.paths/v2-surface-scopes))))
+
+(deftest ^:parallel challenge-scopes-are-grantable-test
+ (testing "GHY-4226: the 401 challenge tells an uninstructed client what to ask for, and DCR snapshots the
+ default grant into each newly registered client, which is what the OAuth server validates a
+ requested scope against. A challenge naming scopes that set does not contain is not merely
+ over-broad — a fresh client asks for exactly what it was told, is answered \"Invalid scope\", and the
+ connect fails outright. The surface becomes unreachable over OAuth."
+ (let [grantable (set ((requiring-resolve 'metabase.oauth-server.core/default-grant-scopes)))]
+ (doseq [scope @#'v2.api/default-ask-scopes]
+ (testing scope
+ (is (contains? grantable scope)
+ "a scope the v2 challenge asks for must be one the OAuth server will actually grant"))))))
+
+(def ^:private mcp-app-ui-capabilities
+ "The `initialize` capabilities an MCP Apps host advertises. Tools gated on `:mcp-app-ui` are hidden from — and
+ refused to — a client that does not send this, so any test driving one has to handshake as a capable client."
+ {:capabilities {:extensions {:io.modelcontextprotocol/ui {:mimeTypes ["text/html;profile=mcp-app"]}}}})
+
+(defn- initialize-ui-client!
+ "Handshake as a client that can render MCP Apps, returning the session id."
+ []
+ (-> (mcp-request (jsonrpc-request "initialize" mcp-app-ui-capabilities))
+ (get-in [:headers "Mcp-Session-Id"])))
+
+(deftest refresh-ui-credential-test
+ (testing "GHY-4157: #81041 moved MCP Apps credential delivery out of the rendered shell and into a server
+ tool — the production template carries no `uiCredential` placeholder any more. v1 got the tool;
+ v2 did not, so a v2 iframe booted with no credential, called `refresh_ui_credential`, and got
+ unknown-tool. The widget could not load at all."
+ (let [session-id (initialize-ui-client!)
+ call! (fn [] (-> (mcp-request (jsonrpc-request "tools/call"
+ {:name "refresh_ui_credential" :arguments {}})
+ {"mcp-session-id" session-id})
+ (get-in [:body :result])))]
+ (testing "the tool exists on v2 and hands back a resolvable credential in private _meta"
+ (let [result (call!)]
+ (is (not (:isError result)))
+ (let [{:keys [credential sessionId]} (get-in result [:_meta :com.metabase/mcp-apps])]
+ (is (= session-id sessionId))
+ (is (some? (mcp.session/resolve-ui-credential credential))))))
+ (testing "the credential it mints is scoped, never the v1 legacy exemption — a tool minting through the
+ 2-arity would opt v2 back out of the native-SQL gate"
+ (let [claims (-> (call!) (get-in [:_meta :com.metabase/mcp-apps :credential])
+ mcp.session/resolve-ui-credential)]
+ (is (nil? (:legacy claims)))
+ (is (contains? claims :scp))))
+ (testing "it is hidden from clients that cannot render an iframe, like the shells it serves"
+ (is (not (some #(= "refresh_ui_credential" (:name %))
+ (registry/list-tools nil {:supports-mcp-ui? false}))))
+ (is (some #(= "refresh_ui_credential" (:name %))
+ (registry/list-tools nil {:supports-mcp-ui? true}))))
+ (testing "and refused to them over the wire — hiding is not enforcement; a text-only model must never be
+ handed a live /api/dataset authenticator by calling the tool by name"
+ (let [plain-session (-> (mcp-request (jsonrpc-request "initialize" {:capabilities {}}))
+ (get-in [:headers "Mcp-Session-Id"]))
+ response (mcp-request (jsonrpc-request "tools/call"
+ {:name "refresh_ui_credential" :arguments {}})
+ {"mcp-session-id" plain-session})]
+ (is (= -32602 (get-in response [:body :error :code])))
+ (is (not (contains? (:body response) :result))))))))
+
+(deftest refresh-ui-credential-is-redacted-from-the-transport-trace-test
+ (testing "the transport records the whole JSON-RPC response one frame above the registry's tool-output
+ trace; over the wire, no recorded frame may carry the credential the client receives"
+ (let [recorded (atom [])
+ session-id (initialize-ui-client!)
+ credential (mt/with-dynamic-fn-redefs [ait/record! (fn [m] (swap! recorded conj m))]
+ (-> (mcp-request (jsonrpc-request "tools/call"
+ {:name "refresh_ui_credential" :arguments {}})
+ {"mcp-session-id" session-id})
+ (get-in [:body :result :_meta :com.metabase/mcp-apps :credential])))]
+ (is (string? credential) "the client must still receive the credential")
+ (is (seq (filter :mcp/response @recorded)) "the transport frame must actually be recorded")
+ (is (not-any? #(str/includes? (pr-str %) credential) @recorded)))))
+
+(deftest refresh-ui-credential-is-redacted-from-traces-test
+ (testing "GHY-4157: the credential rides tool-result `_meta`, and `call-tool` records the whole result into
+ the eval trace. Recording it verbatim parks a live 5-minute authenticator in trace files and the
+ superuser-readable ai-tracing API. v1 strips the same channel before tracing
+ (`mcp.resources/redact-ui-credential`); the transport's HTML scrub does not reach tool results."
+ (let [recorded (atom [])]
+ (mt/with-dynamic-fn-redefs [ait/record! (fn [m] (swap! recorded conj m))]
+ (let [{:keys [result]}
+ (mt/with-current-user (mt/user->id :crowberto)
+ (registry/call-tool #{"agent:query:run"}
+ (mcp.session/create! (mt/user->id :crowberto) nil)
+ "refresh_ui_credential"
+ {}
+ {:supports-mcp-ui? true}))]
+ (testing "the caller still gets the credential"
+ (is (some? (get-in result [:_meta :com.metabase/mcp-apps :credential]))))
+ (testing "but the trace does not"
+ (let [traced (keep :ai/tool-output @recorded)]
+ (is (seq traced) "the tool output must actually be recorded, or this proves nothing")
+ (is (not-any? #(get-in % [:_meta :com.metabase/mcp-apps]) traced)))))))))
+
+(deftest ui-credential-is-not-a-general-session-test
+ (testing "GHY-4400: the UI credential used to be stamped `::scope/unrestricted`, and then `::scope/mcp-ui`
+ over a route allowlist that included `/api/user/current` — an inventory of what the embedded app
+ happened to call rather than a decision about what the credential should reach. That made
+ `refresh_ui_credential` a scope-escalation primitive: a token granted only `agent:query:run` is
+ refused the profile, but the credential minted from it was served it.
+
+ The credential now authenticates a purpose-built surface only. It still carries `::scope/mcp-ui`,
+ which satisfies no endpoint's declared scope, and `:token-scopes-checked` is set only where the
+ credential's signed scope claim covers the route — so anything off the surface, or on it without
+ the scope, fails closed instead of arriving as the user."
+ (mcp.ui-resource/with-fallback-template
+ (let [session-id (initialize-ui-client!)
+ credential (-> (mcp-request (jsonrpc-request "tools/call"
+ {:name "refresh_ui_credential" :arguments {}})
+ {"mcp-session-id" session-id})
+ (get-in [:body :result :_meta :com.metabase/mcp-apps :credential]))
+ headers {"x-metabase-mcp-ui-auth" credential}]
+ (is (some? credential) "the tool must hand back a credential, or this proves nothing")
+ (testing "the profile the escalation exposed is no longer reachable"
+ (is (= 401 (:status (client/client-full-response :get 401 "user/current"
+ {:request-options {:headers headers}})))))
+ (testing "a route off the surface is refused, as before"
+ (is (= 401 (:status (client/client-full-response :get 401 "collection"
+ {:request-options {:headers headers}})))))
+ (testing "and the iframe still boots, on the endpoint built for it"
+ (is (= 200 (:status (client/client-full-response
+ :get 200 "embed-mcp/bootstrap"
+ {:request-options {:headers (assoc headers "mcp-session-id" session-id)}})))))
+ (testing "the request it authenticates is stamped `::scope/mcp-ui`, never unrestricted"
+ (let [info (#'mw.session/current-user-info-for-mcp-ui-credential
+ {:request-method :get
+ :uri "/api/embed-mcp/bootstrap"
+ :headers {"x-metabase-mcp-ui-auth" credential}})]
+ (is (= #{:metabase.api.macros.scope/mcp-ui} (:token-scopes info))
+ "a credential must not carry the unrestricted sentinel")
+ (is (true? (:token-scopes-checked info))
+ "the stamp must be non-nil AND checked, or `ensure-scopes-checked` refuses the iframe")))
+ (testing "a route the credential's scope claim does not cover is authenticated but not scope-checked"
+ (is (false? (:token-scopes-checked
+ (#'mw.session/current-user-info-for-mcp-ui-credential
+ {:request-method :post
+ :uri "/api/dataset"
+ :headers {"x-metabase-mcp-ui-auth"
+ (mcp.session/issue-ui-credential
+ session-id (mt/user->id :crowberto) #{"agent:search"})}})))))))))
+
+(deftest unauthenticated-discovery-test
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (testing "an unauthenticated request advertises the protected-resource metadata for the path it hit"
+ (let [response (client/client-full-response :post 401 endpoint
+ {:request-options {:headers {}}}
+ (jsonrpc-request "initialize"))]
+ (is (= 401 (:status response)))
+ (is (str/includes? (get-in response [:headers "WWW-Authenticate"] "")
+ "/.well-known/oauth-protected-resource/api/metabase-mcp"))))
+ (testing "the challenge names every scope the surface accepts, which a client that reads it prefers
+ over the resource metadata's `scopes_supported`. Asking for less would hide the write
+ tools from `tools/list` with no in-product way for the user to ask for them."
+ (let [response (client/client-full-response :post 401 endpoint
+ {:request-options {:headers {}}}
+ (jsonrpc-request "initialize"))]
+ (is (str/includes? (get-in response [:headers "WWW-Authenticate"] "")
+ ", scope=\"agent:content:read agent:content:write agent:query:run agent:sql:run agent:delivery:write agent:resource:read\""))))
+ (testing "auth-params are comma-delimited per RFC 7235, the form every spec and vendor example
+ uses and the only one a strict parser accepts"
+ (let [response (client/client-full-response :post 401 endpoint
+ {:request-options {:headers {}}}
+ (jsonrpc-request "initialize"))]
+ (is (= (str "Bearer realm=\"mcp\", "
+ "resource_metadata=\"http://localhost:3000/.well-known/oauth-protected-resource"
+ "/api/metabase-mcp\", "
+ "scope=\"agent:content:read agent:content:write agent:query:run agent:sql:run agent:delivery:write agent:resource:read\"")
+ (get-in response [:headers "WWW-Authenticate"])))))))
+
+;;; ------------------------------------------------ Auth methods --------------------------------------------------
+
+(deftest sso-provisioned-session-dispatches-test
+ (testing "GHY-4287: the embedding integration path — a customer's backend signs a JWT per end user, exchanges
+ it for a Metabase session at `/auth/sso`, and drives MCP with that session — must dispatch as that
+ end user. An SSO login mints its session through `create-session-with-auth-tracking!`, which links
+ it to the user's `auth_identity` row; the session middleware reports that row's provider as the
+ auth method, and the v2 transport's session branch must accept it like any cookie session. (This
+ slice refuses no auth method by kind; the test pins the SSO path so a later refusal keyed on auth
+ method cannot silently catch it.)
+
+ The customer's provider is JWT, but every provider mints its session through that one fn, and only
+ OSS providers derive `::provider/provider` in an OSS run — so this uses OIDC to hold the guarantee in
+ both editions rather than only where JWT SSO exists."
+ (mt/with-temp [:model/User user {}
+ :model/AuthIdentity _sso-identity {:user_id (:id user) :provider "oidc"}]
+ (let [session (auth-identity/create-session-with-auth-tracking! user nil :provider/oidc)]
+ (testing "the session really is auth-identity-linked — otherwise this degrades into a plain-session test"
+ (is (some? (:auth_identity_id session))))
+ (testing "the user is one the seat count bills, unlike the `:type :api-key` user an API key authenticates as"
+ (is (= :personal (t2/select-one-fn :type :model/User (:id user)))))
+ (let [session-key (:key session)
+ init (client/client-full-response session-key :post 200 endpoint
+ {:request-options {:headers {}}}
+ (jsonrpc-request "initialize" {:capabilities {}}))
+ session-id (get-in init [:headers "Mcp-Session-Id"])]
+ (testing "initialize is served, not met with the API-key refusal"
+ (is (= 200 (:status init)))
+ (is (some? session-id)))
+ (testing "and a tool actually dispatches — the SSO session reaches the surface, not just the handshake"
+ (let [response (client/client-full-response session-key :post 200 endpoint
+ {:request-options {:headers {"mcp-session-id" session-id}}}
+ (jsonrpc-request "tools/call" {:name "test_echo" :arguments {}}))
+ result (get-in response [:body :result])]
+ (is (not (:isError result)))
+ (is (= {:ok true :message "pong"} (:structuredContent result))))))))))
+
+(defn- do-with-temp-tool!
+ "Register a throwaway tool for the body, then restore the registry. Lets a test assert scope filtering against a
+ tool whose scope differs from the token's without depending on a not-yet-landed real tool."
+ [tool thunk]
+ (let [tools-atom @#'registry/tools*
+ snapshot @tools-atom]
+ (try
+ (registry/register-tool! tool)
+ (thunk)
+ (finally
+ (reset! tools-atom snapshot)
+ ;; register-tool! flushes the manifest cache; do the same on the way out so a later test doesn't see
+ ;; a manifest that still lists the throwaway tool.
+ (reset! @#'registry/manifest-cache nil)))))
+
+(defn- do-with-bearer-token!
+ "Issue an OAuth access token carrying `scopes` for crowberto and call `f` with the auth headers."
+ [scopes f]
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (oauth-server.tu/with-oauth-client [client-id]
+ (mt/with-model-cleanup [:model/OAuthAccessToken]
+ (let [token (str (random-uuid))]
+ ;; `:token` is stored hashed — the resolver hashes the presented string before looking it
+ ;; up, so the row has to be written the same way a real issued token would be — including a
+ ;; live `oauth_client` row, since the resolver fails closed on a token whose client is gone.
+ (t2/insert! :model/OAuthAccessToken
+ {:token (oidc.util/hash-token token)
+ :user_id (mt/user->id :crowberto)
+ :client_id client-id
+ :scope (vec scopes)
+ :expiry (+ (System/currentTimeMillis) 3600000)})
+ (f {"authorization" (str "Bearer " token)}))))))
+
+(defn- ui-credential-for
+ "Drive the full MCP Apps handshake as a client holding `scopes`: initialize, read the
+ visualize-query shell, and pull the credential back out of the rendered HTML — the same path a
+ host's iframe bootstrap takes."
+ [headers]
+ (let [session-id (-> (client/client-full-response :post 200 endpoint
+ {:request-options {:headers headers}}
+ (jsonrpc-request "initialize" {:capabilities {}}))
+ (get-in [:headers "Mcp-Session-Id"]))
+ html (-> (client/client-full-response
+ :post 200 endpoint
+ {:request-options {:headers (assoc headers "mcp-session-id" session-id)}}
+ (jsonrpc-request "resources/read" {:uri v2.resources/visualize-query-uri}))
+ (get-in [:body :result :contents])
+ first
+ :text)]
+ (second (re-find #"uiCredential:\s*\"([^\"]+)\"" html))))
+
+(deftest ui-credential-cannot-outrun-its-scopes-test
+ (testing "GHY-4318: the iframe credential is delivered to the CLIENT inside the resource HTML, so a client
+ holding only `agent:query:run` can lift it out and POST straight to /api/dataset. The credential is
+ stamped unrestricted for the endpoint scope middleware, so the only thing standing between it and raw
+ SQL is `check-mcp-ui-native-query!` — which must actually be wired into the query endpoints, not just
+ unit-tested. Without the wiring, `agent:query:run` silently becomes `agent:sql:run`."
+ (mcp.ui-resource/with-fallback-template
+ ;; Both payloads are hand-rolled legacy MBQL rather than built with Lib, deliberately and
+ ;; symmetrically: what is under test is the shape a client actually PUTs on the wire reaching the
+ ;; guard, so constructing it through Lib would test Lib's output instead of the client's.
+ (let [native-query {:database (mt/id) :type "native" :native {:query "SELECT 1"}}
+ mbql-query {:database (mt/id) :type "query" :query {:source-table (mt/id :venues) :limit 1}}]
+ (testing "a client without agent:sql:run is refused, and told which scope it needs"
+ (do-with-bearer-token!
+ #{"agent:query:run"}
+ (fn [headers]
+ (let [credential (ui-credential-for headers)]
+ (is (string? credential)
+ "the shell must render a credential — otherwise this test passes vacuously")
+ (let [response (client/client-full-response
+ :post 403 "dataset"
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential}}}
+ native-query)]
+ (is (re-find #"agent:sql:run" (str (:body response)))))))))
+ (testing "the same client's non-native queries are untouched — the gate is on raw SQL, not on the credential"
+ (do-with-bearer-token!
+ #{"agent:query:run"}
+ (fn [headers]
+ (let [credential (ui-credential-for headers)]
+ (is (= 202 (:status (client/client-full-response
+ :post 202 "dataset"
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential}}}
+ mbql-query))))))))
+ (testing "a client that WAS granted agent:sql:run runs the same native query"
+ (do-with-bearer-token!
+ #{"agent:query:run" "agent:sql:run"}
+ (fn [headers]
+ (let [credential (ui-credential-for headers)]
+ (is (= 202 (:status (client/client-full-response
+ :post 202 "dataset"
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential}}}
+ native-query))))))))))))
+
+(deftest resource-scope-gate-is-enforced-over-http-test
+ (testing "GHY-4157: every v2 resource carries a required scope, but `resources-list-and-read-test` above drives a
+ cookie session — which is stamped unrestricted, so it never exercises the gate at all. Over a real
+ bearer token the gate is the only thing between a read-only client and the iframe shell, and reading
+ that shell is what mints a UI credential. That has to be asserted on the wire, not just in the
+ registry."
+ (mcp.ui-resource/with-fallback-template
+ (do-with-bearer-token!
+ #{"agent:content:read"}
+ (fn [headers]
+ (let [session-id (-> (client/client-full-response :post 200 endpoint
+ {:request-options {:headers headers}}
+ (jsonrpc-request "initialize" {:capabilities {}}))
+ (get-in [:headers "Mcp-Session-Id"]))
+ session! (fn [body]
+ (client/client-full-response
+ :post 200 endpoint
+ {:request-options {:headers (assoc headers "mcp-session-id" session-id)}}
+ body))
+ read! #(session! (jsonrpc-request "resources/read" {:uri %}))]
+ (testing "the UI shell is refused — it gates on agent:query:run, which this token does not carry"
+ (let [response (read! v2.resources/visualize-query-uri)]
+ (is (= -32602 (get-in response [:body :error :code])))
+ (testing "with the same message an unknown URI gets, so a scope denial is not an existence oracle"
+ (is (= "Resource not found" (get-in response [:body :error :message])))
+ (is (= (get-in (read! "ui://metabase/does-not-exist.html") [:body :error :message])
+ (get-in response [:body :error :message]))))
+ (testing "and no credential is minted into the response"
+ (is (not (str/includes? (str (:body response)) "uiCredential"))))))
+ (testing "the fields catalog is refused too — agent:resource:read, also absent from this token"
+ (is (= -32602 (get-in (read! v2.resources/fields-catalog-uri) [:body :error :code]))))
+ (testing "and nothing is advertised to this token in the first place"
+ (is (empty? (-> (session! (jsonrpc-request "resources/list"))
+ (get-in [:body :result :resources])))))))))))
+
+(deftest bearer-token-dispatches-with-its-own-scopes-test
+ (testing "GHY-4287: the session middleware resolves an OAuth bearer token itself, so a bearer request reaches the
+ transport on the same authenticated branch a cookie session does. It must still dispatch with the
+ token's granted scopes — the unrestricted fallback that branch gives a cookie session would hand a
+ narrow token every tool."
+ ;; Register a throwaway tool on a DIFFERENT scope (`agent:content:write`, which the token below does not carry)
+ ;; so the negative half of the scope contract has teeth independent of which real write tools are registered:
+ ;; this test fails if `list-tools`' scope filter is removed.
+ (do-with-temp-tool!
+ {:name "scope_probe_write"
+ :scope metabot.scope/agent-content-write
+ :description "test-only tool gated on a write scope the narrow token lacks"
+ :annotations {:readOnlyHint false}
+ :args [:map]
+ :handler (fn [_ _] nil)}
+ (fn []
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (oauth-server.tu/with-oauth-client [client-id]
+ (mt/with-model-cleanup [:model/OAuthAccessToken]
+ (let [token (str (random-uuid))
+ headers {"authorization" (str "Bearer " token)}]
+ ;; `:token` is stored hashed — the resolver hashes the presented string before looking it
+ ;; up, so the row has to be written the same way a real issued token would be — including a
+ ;; live `oauth_client` row, since the resolver fails closed on a token whose client is gone.
+ (t2/insert! :model/OAuthAccessToken
+ {:token (oidc.util/hash-token token)
+ :user_id (mt/user->id :crowberto)
+ :client_id client-id
+ :scope ["agent:content:read"]
+ :expiry (+ (System/currentTimeMillis) 3600000)})
+ (let [session-id (-> (client/client-full-response :post 200 endpoint
+ {:request-options {:headers headers}}
+ (jsonrpc-request "initialize" {:capabilities {}}))
+ (get-in [:headers "Mcp-Session-Id"]))
+ tool-names (-> (client/client-full-response
+ :post 200 endpoint
+ {:request-options {:headers (assoc headers "mcp-session-id" session-id)}}
+ (jsonrpc-request "tools/list"))
+ (get-in [:body :result :tools])
+ (->> (map :name) set))]
+ (is (some? session-id))
+ (testing "a tool inside the granted scope (agent:content:read) is served"
+ (is (contains? tool-names "test_echo")))
+ (testing "a tool gated on a scope the token lacks (agent:content:write) is filtered out"
+ (is (not (contains? tool-names "scope_probe_write"))
+ "scope filtering must hide a write-scoped tool from a read-only token")))))))))))
diff --git a/test/metabase/mcp/v2/common_test.clj b/test/metabase/mcp/v2/common_test.clj
new file mode 100644
index 00000000000..cfa504e912c
--- /dev/null
+++ b/test/metabase/mcp/v2/common_test.clj
@@ -0,0 +1,331 @@
+(ns metabase.mcp.v2.common-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.channel.urls :as channel.urls]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(deftest ^:parallel teaching-error-test
+ (testing "teaching errors surface their message as MCP error content"
+ (let [content (try
+ (common/throw-teaching-error "Use `fields` OR `response_format`, not both.")
+ (catch clojure.lang.ExceptionInfo e
+ (common/->mcp-error-content e)))]
+ (is (:isError content))
+ (is (= "Use `fields` OR `response_format`, not both."
+ (-> content :content first :text))))))
+
+(deftest ^:parallel error-redaction-test
+ (let [text #(-> % :content first :text)]
+ (testing "GHY-4137: only deliberately caller-facing errors surface their message — client
+ (4xx) status codes or an explicit ::error-code"
+ (doseq [[label e expected] [["teaching 400" (ex-info "Use fields OR response_format." {:status-code 400}) "Use fields OR response_format."]
+ ["not-found 404" (ex-info "card 7 not found." {:status-code 404}) "card 7 not found."]
+ ["scope 403" (ex-info "Insufficient scope." {:status-code 403
+ ::common/error-code common/error-code-invalid-request}) "Insufficient scope."]]]
+ (testing label
+ (is (= expected (text (common/->mcp-error-content e)))))))
+ (testing "GHY-4137: 402 (missing premium feature) and 409 (conflict) are deliberate
+ caller-facing errors too — a premium-feature check names the missing feature, a
+ conflict names the clashing state, and neither may be redacted to a generic error"
+ (doseq [[label e expected]
+ [["premium-feature 402" (ex-info "Transforms is a paid feature not available on this instance."
+ {:status-code 402}) "Transforms is a paid feature not available on this instance."]
+ ["conflict 409" (ex-info "A snippet named \"totals\" already exists in this collection."
+ {:status-code 409}) "A snippet named \"totals\" already exists in this collection."]]]
+ (testing label
+ (is (= expected (text (common/->mcp-error-content e)))))))
+ (testing "internal failures are redacted to a generic message — their real text may embed SQL,
+ schema, or connection detail and must never reach the client"
+ (doseq [[label e] [["projection 500 invariant" (ex-info "No projection registered for type: widget" {:status-code 500})]
+ ["ex-info with no status-code (library wrap)" (ex-info "Error executing query: SELECT * FROM secret_accounts" {:query {}})]
+ ["JDBC SQLException" (java.sql.SQLException. "ERROR: relation \"secret_accounts\" does not exist")]
+ ["NPE naming an internal class" (NullPointerException. "metabase.driver.internal.Foo is null")]]]
+ (testing label
+ (let [content (common/->mcp-error-content e)]
+ (is (:isError content))
+ (is (= "Internal error" (text content)))
+ (is (= common/error-code-internal (::common/error-code content))
+ "internal errors carry the internal JSON-RPC code")))))
+ (testing "an explicit internal ::error-code never surfaces its message even on an ex-info"
+ (is (= "Internal error"
+ (text (common/->mcp-error-content
+ (ex-info "leaky internal detail" {::common/error-code common/error-code-internal}))))))))
+
+(deftest ^:parallel schema-failure-names-the-function-test
+ (let [text #(-> % :content first :text)
+ ;; The shape `metabase.util.malli.fn` throws in dev and test.
+ invalid-input (ex-info "Invalid input: [{:dashcard-id [\"disallowed key, got: 177\"]}]"
+ {:type :metabase.util.malli.fn/invalid-input
+ :fn-name 'check-parameter-mapping-permissions
+ :humanized [{:dashcard-id ["disallowed key, got: 177"]}]
+ :schema :ignored
+ :value [{:dashcard-id 177 :secret "hunter2"}]})
+ invalid-output (ex-info "Invalid output: {:email [\"missing required key\"]}"
+ {:type :metabase.util.malli.fn/invalid-output
+ :fn-name 'get-notification
+ :humanized {:email ["missing required key"]}
+ :schema :ignored
+ :value {:email "[email protected]"}})]
+ (testing "GHY-4502: a server-side schema failure names the function instead of collapsing to
+ \"Internal error\" — it is a bug, but a bug with a name is a one-call diagnosis rather
+ than the nine blind retries that prompted this"
+ (let [content (common/->mcp-error-content invalid-input)]
+ (is (:isError content))
+ (is (re-find #"check-parameter-mapping-permissions" (text content))
+ "the function name is what makes this actionable")
+ (is (re-find #"dashcard-id" (text content))
+ "an invalid-INPUT humanization describes the caller's own argument, so it is safe to echo")))
+ (testing "the offending value is never echoed — `:value` carries the whole argument, which may
+ hold anything the caller sent"
+ (is (not (re-find #"hunter2" (text (common/->mcp-error-content invalid-input))))))
+ (testing "an invalid-OUTPUT names the function but never its humanization: that describes
+ SERVER-produced data, which the caller may have no right to see"
+ (let [content (common/->mcp-error-content invalid-output)]
+ (is (re-find #"get-notification" (text content)))
+ (is (not (re-find #"[email protected]" (text content))))
+ (is (not (re-find #"missing required key" (text content))))))))
+
+(deftest ^:parallel success-content-test
+ (testing "read responses default to text-only"
+ (is (= {:content [{:type "text" :text "hi"}]} (common/success-content "hi"))))
+ (testing "structuredContent is emitted only when explicitly passed"
+ (is (= {:ok true} (:structuredContent (common/success-content "hi" {:ok true}))))))
+
+(deftest ^:parallel projections-test
+ (let [row {:id 5 :name "Fin" :description "d" :location "/" :archived false
+ :personal_owner_id nil :entity_id "eid" :slug "fin" :created_at "t"}]
+ (testing "concise is a subset of the REST response with the same property names"
+ (is (= {:id 5 :name "Fin" :description "d" :location "/" :archived false}
+ (projections/project :collection :concise row))))
+ (testing "the catalog is generated from the detailed projection shape"
+ (is (contains? (set (projections/catalog :collection)) "name"))
+ (is (contains? (set (projections/catalog :question)) "parameters.name")))))
+
+(deftest ^:parallel projection-bad-argument-test
+ (testing "an unregistered type throws an ex-info naming the type"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo
+ #"No projection registered for type: nope"
+ (projections/project :nope :concise {:id 1}))))
+ (testing "a format outside :concise/:detailed throws the same shape of ex-info rather than a nil-call NPE"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo
+ #"Unknown projection format: :summary"
+ (projections/project :collection :summary {:id 1})))
+ (is (= {:status-code 500 :type :collection :fmt :summary}
+ (try
+ (projections/project :collection :summary {:id 1})
+ (catch clojure.lang.ExceptionInfo e (ex-data e)))))))
+
+(deftest frontend-url-test
+ (testing "a configured site URL is prefixed onto the relative path"
+ (mt/with-dynamic-fn-redefs [channel.urls/site-url (constantly "http://metabase.example.com")]
+ (is (= "http://metabase.example.com/collection/42"
+ (common/frontend-url (channel.urls/collection-path 42))))))
+ (testing "an unset site URL yields a relative path, never the literal \"null\" host that
+ interpolating site-url directly would produce — site-url is nil both when it has
+ never been configured and when the stored value fails validation"
+ (doseq [unset [nil ""]]
+ (mt/with-dynamic-fn-redefs [channel.urls/site-url (constantly unset)]
+ (is (= "/collection/42" (common/frontend-url (channel.urls/collection-path 42))))
+ (is (= "/question/42" (common/frontend-url (channel.urls/card-path 42))))))))
+
+(deftest response-format-test
+ (testing "response_format parses to :concise (default) or :detailed"
+ (is (= :concise (common/response-format {})))
+ (is (= :concise (common/response-format {:response_format "concise"})))
+ (is (= :detailed (common/response-format {:response_format "detailed"}))))
+ (testing "an unrecognized response_format is a teaching error naming the valid values"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"concise.*detailed"
+ (common/response-format {:response_format "verbose"})))))
+
+;; A projection whose catalog deliberately includes a field (`collection`) that is a string prefix
+;; of a sibling (`collection_path`) — the exact shape that a prefix match without a `.` boundary
+;; check would confuse. `parameters` is nested so subtree selection and order-absorption can be
+;; exercised.
+(def ^:private test-catalog
+ ["name" "collection" "collection_path" "description" "last_run.status"
+ "parameters.name" "parameters.type"])
+
+(defn- register-fields-test-type! []
+ (projections/register-projection!
+ :fields-test
+ {:concise identity
+ :detailed identity
+ :catalog test-catalog}))
+
+(deftest select-fields-test
+ (register-fields-test-type!)
+ (let [row {:name "Q1"
+ :collection "Root"
+ :collection_path "Root/Sub"
+ :parameters [{:name "cat" :type "category" :extra "drop-me"}]
+ :secret "never-selected"}]
+ (testing "an exact scalar path selects just that field"
+ (is (= {:name "Q1"} (common/select-fields :fields-test row ["name"]))))
+ (testing "a field that is a string prefix of a sibling does NOT drag the sibling in"
+ ;; the prefix-boundary bug: `collection` must not match `collection_path`
+ (is (= {:collection "Root"} (common/select-fields :fields-test row ["collection"]))))
+ (testing "the longer sibling is selectable on its own"
+ (is (= {:collection_path "Root/Sub"} (common/select-fields :fields-test row ["collection_path"]))))
+ (testing "a bare nested prefix selects the whole subtree"
+ (is (= {:parameters [{:name "cat" :type "category" :extra "drop-me"}]}
+ (common/select-fields :fields-test row ["parameters"]))))
+ (testing "a leaf under a nested path selects only that leaf, per array item"
+ (is (= {:parameters [{:name "cat"}]}
+ (common/select-fields :fields-test row ["parameters.name"]))))
+ (testing "subtree absorption is order-independent: a bare prefix wins regardless of order"
+ (is (= {:parameters [{:name "cat" :type "category" :extra "drop-me"}]}
+ (common/select-fields :fields-test row ["parameters" "parameters.name"])))
+ (is (= {:parameters [{:name "cat" :type "category" :extra "drop-me"}]}
+ (common/select-fields :fields-test row ["parameters.name" "parameters"]))))
+ (testing "several paths in one call merge into one selection tree"
+ ;; the ordinary `fields: ["name","parameters.type"]` shape: distinct top-level keys must
+ ;; both survive the merge, not just two paths down one branch
+ (is (= {:name "Q1" :parameters [{:type "category"}]}
+ (common/select-fields :fields-test row ["name" "parameters.type"]))))
+ (testing "GHY-4511: a named leaf the row has no value for answers null — the compact
+ projections drop nils, and an empty object reads as \"not a readable field\""
+ (is (= {:description nil} (common/select-fields :fields-test row ["description"])))
+ (is (= {:name "Q1" :description nil}
+ (common/select-fields :fields-test row ["name" "description"]))))
+ (testing "a path through a missing parent stays dropped — answering `last_run.status` with
+ a null-valued shell would claim a run that never happened"
+ (is (= {} (common/select-fields :fields-test row ["last_run.status"]))))
+ (testing "an unknown path is a teaching error naming the nearest valid paths, ranked by edit
+ distance — the suggestion is only useful if the closest catalog entry leads"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo
+ #"Unknown field path \"nmae\".*Nearest valid paths: name, collection"
+ (common/select-fields :fields-test row ["nmae"]))))
+ (testing "empty fields is a teaching error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"at least one path"
+ (common/select-fields :fields-test row []))))
+ (testing "fields is mutually exclusive with response_format / include"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"OR"
+ (common/select-fields :fields-test row ["name"] {:response-format :detailed})))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"OR"
+ (common/select-fields :fields-test row ["name"] {:include ["x"]}))))
+ (testing "fields on a type with no catalog is a teaching error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"not supported for type"
+ (common/select-fields :no-such-type row ["name"]))))))
+
+(deftest ^:parallel truncation-line-test
+ (testing "a narrowing param is named alongside the next offset — a list the caller can filter
+ should steer to the filter first, since paging a broad list is the expensive path"
+ (is (= "Returned 2 of 5 — narrow with `query`, or continue with `offset: 2`."
+ (common/truncation-line {:param :query :offset 0 :limit 2 :total 5 :returned 2}))))
+ (testing "a floored total reads as a lower bound — a search total capped at the ranking limit is
+ not an exact count, and reporting it as one would have the caller stop paging early"
+ (is (= "Returned 2 of at least 9 — continue with `offset: 2`."
+ (common/truncation-line {:offset 0 :limit 2 :total 9 :total-floor? true :returned 2}))))
+ (testing "an untruncated page, or one whose total is unknown, has no line"
+ (is (nil? (common/truncation-line {:offset 0 :limit 10 :total 5 :returned 5})))
+ (is (nil? (common/truncation-line {:offset 0 :limit 10 :total nil :returned 5})))))
+
+(deftest list-content-empty-page-test
+ (testing "GHY-4137/P6: a page that returns nothing must say why. `truncation-line` only fires when
+ (offset + limit) < total, so an offset at or past the end produced a bare
+ {\"data\":[],\"returned\":0,\"total\":37} with no steering at all — which reads as
+ \"nothing matches\" when the truth is \"you paged past the end\"."
+ (testing "an offset past the end names the offset and the total"
+ (let [text (-> (common/list-content [] 37 {:offset 100 :limit 20}) :content first :text)]
+ (is (re-find #"No results at offset 100" text))
+ (is (re-find #"37 available" text))
+ (is (re-find #"`offset`" text) "it steers back rather than leaving the caller stuck")))
+ (testing "a floored total stays a floor in the empty-page line"
+ (let [text (-> (common/list-content [] 37 {:offset 100 :limit 20 :total-floor? true})
+ :content first :text)]
+ (is (re-find #"at least 37 available" text))))
+ (testing "an empty FIRST page — every match dropped after counting — says so instead of steering
+ to an offset that would not help"
+ (let [text (-> (common/list-content [] 3 {:offset 0 :limit 20}) :content first :text)]
+ (is (re-find #"Returned 0 of 3" text))
+ (is (not (re-find #"No results at offset" text)))))
+ (testing "a genuinely empty result set gets no line — total 0 already says it"
+ (let [text (-> (common/list-content [] 0 {:offset 0 :limit 20}) :content first :text)]
+ (is (not (re-find #"No results" text)))
+ (is (not (re-find #"Returned" text)))))
+ (testing "an unknown total gets no line — there is nothing to report against"
+ (let [text (-> (common/list-content [] nil {:offset 100 :limit 20}) :content first :text)]
+ (is (not (re-find #"No results" text)))))
+ (testing "a non-empty page is unaffected by the new branch"
+ (let [text (-> (common/list-content [{:id 1} {:id 2}] 5 {:offset 0 :limit 2}) :content first :text)]
+ (is (re-find #"Returned 2 of 5" text))
+ (is (not (re-find #"No results" text)))))))
+
+(def ^:private browse-empty-hint
+ "The `:empty-hint` `list_databases` passes — quoted verbatim so this test moves in lockstep with
+ the real call site."
+ "No databases are visible to you. Browsing data needs query-builder or table-metadata permission on at least one database.")
+
+(deftest list-content-empty-hint-test
+ (testing "`:empty-hint` supplies the domain reason a result set is genuinely empty — the envelope
+ says zero, the hint says why. Dropping the option is silent: `list-content` ignores
+ unknown keys, so the sentence would just vanish from `list_databases`."
+ (testing "guards the restack of the `:empty-hint` call site in tools/browse.clj `list_databases`:
+ if a merge resolves `list-content` back to a version without `:empty-hint`, this fails"
+ (let [text (-> (common/list-content [] 0 {:offset 0 :limit 20 :empty-hint browse-empty-hint})
+ :content first :text)]
+ (is (re-find #"\"total\":0" text))
+ (is (str/includes? text browse-empty-hint))))
+ (testing "guards the restack of the `:empty-hint` call site in tools/browse.clj: the hint must
+ stay gated on a zero total, never collapse into a bare `or`. At a positive total the
+ caller paged past the end, and printing a static \"nothing is visible to you\" would
+ state something false about data they do have"
+ (let [text (-> (common/list-content [] 37 {:offset 100 :limit 20 :empty-hint browse-empty-hint})
+ :content first :text)]
+ (is (re-find #"No results at offset 100" text))
+ (is (not (str/includes? text browse-empty-hint)))))
+ (testing "an empty first page with a positive total keeps the dropped-rows line too — that total
+ is also not a genuinely empty result set"
+ (let [text (-> (common/list-content [] 3 {:offset 0 :limit 20 :empty-hint browse-empty-hint})
+ :content first :text)]
+ (is (re-find #"Returned 0 of 3" text))
+ (is (not (str/includes? text browse-empty-hint)))))
+ (testing "an unknown total is not a known-zero one, so the hint stays out"
+ (let [text (-> (common/list-content [] nil {:offset 0 :limit 20 :empty-hint browse-empty-hint})
+ :content first :text)]
+ (is (not (str/includes? text browse-empty-hint)))))
+ (testing "a zero total reached at a nonzero offset keeps the hint out — the gate is the offset
+ as well as the total. `empty-page-line` declines at total 0 for every offset, so a
+ total-only gate would answer \"why is this empty\" for a caller who instead paged past
+ the end of an empty list"
+ (let [text (-> (common/list-content [] 0 {:offset 50 :limit 20 :empty-hint browse-empty-hint})
+ :content first :text)]
+ (is (not (str/includes? text browse-empty-hint)))
+ (is (re-find #"\"total\":0" text) "the envelope still reports the zero total")))
+ (testing "a non-empty page ignores the hint entirely — a truncated page still gets its
+ truncation line"
+ (let [text (-> (common/list-content [{:id 1} {:id 2}] 5 {:offset 0 :limit 2 :empty-hint browse-empty-hint})
+ :content first :text)]
+ (is (re-find #"Returned 2 of 5" text))
+ (is (re-find #"offset: 2" text))
+ (is (not (str/includes? text browse-empty-hint)))))))
+
+(deftest list-content-test
+ (testing "a full page (returned == total) appends no steering line"
+ (let [content (common/list-content [{:id 1} {:id 2}] 2 {:offset 0 :limit 10})
+ text (-> content :content first :text)]
+ (is (not (re-find #"Returned" text)))
+ (is (re-find #"\"returned\":2" text))))
+ (testing "a truncated page appends the steering line with the next offset"
+ (let [content (common/list-content [{:id 1} {:id 2}] 5 {:offset 0 :limit 2})
+ text (-> content :content first :text)]
+ (is (re-find #"Returned 2 of 5" text))
+ (is (re-find #"offset: 2" text))))
+ (testing "GHY-4137: a page shorter than limit/total/offset predict (a post-fetch drop — e.g. a
+ stale index hit) reports the steering line's count from the real page, matching the
+ envelope's :returned rather than contradicting it"
+ (let [content (common/list-content [{:id 1} {:id 2} {:id 3}] 40 {:offset 0 :limit 10})
+ text (-> content :content first :text)]
+ (is (re-find #"\"returned\":3" text) "the envelope reports the real page size")
+ (is (re-find #"Returned 3 of 40" text)
+ "the steering line's count matches the envelope, not the arithmetic min(limit, total-offset) = 10")
+ (is (not (re-find #"Returned 10" text))
+ "the arithmetic prediction must not appear anywhere in the text"))))
diff --git a/test/metabase/mcp/v2/dashboard_ops_test.clj b/test/metabase/mcp/v2/dashboard_ops_test.clj
new file mode 100644
index 00000000000..f0547d8515b
--- /dev/null
+++ b/test/metabase/mcp/v2/dashboard_ops_test.clj
@@ -0,0 +1,946 @@
+(ns metabase.mcp.v2.dashboard-ops-test
+ "Unit tests for the pure `dashboard_write` op compiler. No DB: `compile-ops` takes a hydrated
+ dashboard map and returns the save payload, so every op and every rejection is exercised
+ against plain maps."
+ (:require
+ [clojure.test :refer :all]
+ [metabase.mcp.v2.dashboard-ops :as dashboard-ops]
+ [metabase.parameters.mapping-targets]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private empty-dash
+ {:id 1 :dashcards [] :tabs [] :parameters []})
+
+(defn- dash-with
+ [dashcards]
+ (assoc empty-dash :dashcards dashcards))
+
+(defn- inline-parameter-owners
+ "`{parameter-id [dashcard-id ...]}` for every inline placement in a compiled payload. A parameter
+ with more than one owner is the corruption GHY-4326 is about."
+ [dashcards]
+ (reduce (fn [owners dc]
+ (reduce (fn [owners parameter-id]
+ (update owners parameter-id (fnil conj []) (:id dc)))
+ owners
+ (:inline_parameters dc)))
+ {}
+ dashcards))
+
+(deftest add-card-autoplaces-test
+ (testing "GHY-4147: add_card with no position lands at the top-left of an empty dashboard"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_card" :id -1 :card_id 42}])]
+ (is (= 1 (count dashcards)))
+ (is (= {:id -1 :card_id 42 :row 0 :col 0}
+ (select-keys (first dashcards) [:id :card_id :row :col])))
+ (is (pos-int? (:size_x (first dashcards))))
+ (is (pos-int? (:size_y (first dashcards)))))))
+
+(deftest add-card-respects-explicit-position-and-size-test
+ (testing "GHY-4147: explicit position and size are passed through untouched"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_card" :id -1 :card_id 42
+ :position {:row 3 :col 4}
+ :size {:size_x 6 :size_y 5}}])]
+ (is (= {:id -1 :card_id 42 :row 3 :col 4 :size_x 6 :size_y 5}
+ (select-keys (first dashcards) [:id :card_id :row :col :size_x :size_y]))))))
+
+(deftest existing-dashcards-are-preserved-test
+ (testing "GHY-4147: the payload is a full replacement, so untouched dashcards survive verbatim"
+ (let [existing {:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4 :dashboard_tab_id nil}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [existing])
+ [{:op "add_card" :id -1 :card_id 42}])]
+ (is (= #{7 -1} (set (map :id dashcards))))
+ (is (= existing (first (filter #(= 7 (:id %)) dashcards)))))))
+
+(deftest autoplace-avoids-existing-cards-test
+ (testing "GHY-4147: autoplace does not overlap an occupied slot"
+ (let [existing {:id 7 :card_id 9 :row 0 :col 0 :size_x 24 :size_y 4 :dashboard_tab_id nil}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [existing])
+ [{:op "add_card" :id -1 :card_id 42}])
+ added (first (filter #(= -1 (:id %)) dashcards))]
+ (is (<= 4 (:row added))))))
+
+(deftest duplicate-temp-id-is-rejected-test
+ (testing "GHY-4147: reusing a temp id inside one batch is a teaching error naming the op index"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 1.*-1"
+ (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_card" :id -1 :card_id 42}
+ {:op "add_card" :id -1 :card_id 43}])))))
+
+(deftest positive-temp-id-is-rejected-test
+ (testing "GHY-4147: a new dashcard's id must be negative — positives would silently target a real row"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*negative"
+ (dashboard-ops/compile-ops empty-dash [{:op "add_card" :id 5 :card_id 42}])))))
+
+(deftest unknown-op-is-rejected-test
+ (testing "GHY-4147: an unrecognized op names the index and the op"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*frobnicate"
+ (dashboard-ops/compile-ops empty-dash [{:op "frobnicate"}])))))
+
+(deftest add-text-test
+ (testing "GHY-4147: add_text produces a virtual text dashcard with no card_id"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_text" :id -1 :markdown "## Hello"}])
+ dc (first dashcards)]
+ (is (nil? (:card_id dc)))
+ (is (= "text" (get-in dc [:visualization_settings :virtual_card :display])))
+ (is (= "## Hello" (get-in dc [:visualization_settings :text]))))))
+
+(deftest add-heading-test
+ (testing "GHY-4147: add_heading matches the editor, including the transparent background"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_heading" :id -1 :text "Revenue"}])
+ vs (:visualization_settings (first dashcards))]
+ (is (= "heading" (get-in vs [:virtual_card :display])))
+ (is (= "Revenue" (:text vs)))
+ (is (false? (:dashcard.background vs))))))
+
+(deftest add-link-url-test
+ (testing "GHY-4147: add_link with an external url"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_link" :id -1 :url "https://example.com"}])
+ vs (:visualization_settings (first dashcards))]
+ (is (= "link" (get-in vs [:virtual_card :display])))
+ (is (= {:url "https://example.com"} (:link vs))))))
+
+(deftest add-link-entity-test
+ (testing "GHY-4147: add_link with an entity reference stores the entity, not a url"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_link" :id -1 :entity {:type "dashboard" :id 12}}])
+ vs (:visualization_settings (first dashcards))]
+ (is (= {:entity {:model "dashboard" :id 12}} (:link vs))))))
+
+(deftest add-link-requires-exactly-one-target-test
+ (testing "GHY-4147: add_link with neither url nor entity, or both, is a teaching error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*exactly one"
+ (dashboard-ops/compile-ops empty-dash [{:op "add_link" :id -1}])))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*exactly one"
+ (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_link" :id -1 :url "https://example.com"
+ :entity {:type "dashboard" :id 12}}])))))
+
+(deftest add-iframe-test
+ (testing "GHY-4147: add_iframe stores the src in visualization settings"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_iframe" :id -1 :src "https://example.com/embed"}])
+ vs (:visualization_settings (first dashcards))]
+ (is (= "iframe" (get-in vs [:virtual_card :display])))
+ (is (= "https://example.com/embed" (:iframe vs))))))
+
+(deftest add-action-test
+ (testing "GHY-4147: add_action produces an action dashcard with action_id and no card_id"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_action" :id -1 :action_id 3 :label "Run" :display "button"}])
+ dc (first dashcards)]
+ (is (= 3 (:action_id dc)))
+ (is (nil? (:card_id dc)))
+ (is (= "button" (get-in dc [:visualization_settings :actionDisplayType])))
+ (is (= "Run" (get-in dc [:visualization_settings "button.label"]))))))
+
+(deftest add-action-virtual-card-test
+ (testing "GHY-4147: add_action writes a :virtual_card so the dashcard reads as an action"
+ ;; `isActionDashCard` (frontend/src/metabase/actions/utils.ts) keys off
+ ;; visualization_settings.virtual_card.display; without it the dashcard renders empty, not as a button.
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_action" :id -1 :action_id 3 :label "Run"}])
+ vs (:visualization_settings (first dashcards))]
+ (is (= {:name nil :display "action" :visualization_settings {} :archived false}
+ (:virtual_card vs)))
+ (is (= "button" (:actionDisplayType vs)))
+ (is (= "Run" (get vs "button.label"))))))
+
+(deftest duplicate-card-test
+ (testing "GHY-4147: duplicate_card clones content but takes the new negative id and its own slot"
+ (let [existing {:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4 :dashboard_tab_id nil
+ :visualization_settings {:card.title "Original"}
+ :parameter_mappings [{:parameter_id "p1" :card_id 9 :target ["dimension" ["field" 1 nil]]}]}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [existing])
+ [{:op "duplicate_card" :id -1 :dashcard_id 7}])
+ clone (first (filter #(= -1 (:id %)) dashcards))]
+ (is (= 2 (count dashcards)))
+ (is (= 9 (:card_id clone)))
+ (is (= {:card.title "Original"} (:visualization_settings clone)))
+ (is (= (:parameter_mappings existing) (:parameter_mappings clone)))
+ (is (not= [(:row existing) (:col existing)] [(:row clone) (:col clone)])))))
+
+(deftest duplicate-card-unknown-dashcard-test
+ (testing "GHY-4147: duplicate_card on a missing dashcard names the op index"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*999"
+ (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "duplicate_card" :id -1 :dashcard_id 999}])))))
+
+(deftest duplicate-card-does-not-remap-visualizer-source-ids-test
+ (testing "GHY-4147: duplicate_card does not remap visualizer columnValuesMapping sourceIds —
+ update-colvalmap-setting (api.clj) is private and out of scope for this compiler, so a
+ cloned visualizer card still points at the source dashcard's columns. Recorded as a
+ known decision, not an oversight."
+ (let [existing {:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4 :dashboard_tab_id nil
+ :visualization_settings
+ {:visualization "table"
+ :columnValuesMapping {:COLUMN_1 [{:sourceId "card:7" :originalName "NAME" :name "COLUMN_1"}]}}}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [existing])
+ [{:op "duplicate_card" :id -1 :dashcard_id 7}])
+ clone (first (filter #(= -1 (:id %)) dashcards))]
+ (is (= (get-in existing [:visualization_settings :columnValuesMapping])
+ (get-in clone [:visualization_settings :columnValuesMapping]))))))
+
+(deftest duplicate-card-does-not-clone-inline-parameters-test
+ (testing "GHY-4326: an inline parameter is a dashboard parameter *placed on* one dashcard, so the
+ clone does not inherit the placement — the parameter stays where the user put it. Two
+ dashcards claiming one id would make cleanup-orphaned-inline-parameters! strip the
+ parameter when either copy is deleted, silently removing the original's filter."
+ (let [mapping {:parameter_id "p1" :card_id 9 :target ["dimension" ["field" 1 nil]]}
+ existing {:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4 :dashboard_tab_id nil
+ :visualization_settings {}
+ :inline_parameters ["p1"]
+ :parameter_mappings [mapping]}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ (assoc empty-dash
+ :dashcards [existing]
+ :parameters [{:id "p1" :name "Cat" :slug "cat" :type "string/="}])
+ [{:op "duplicate_card" :id -1 :dashcard_id 7}])
+ clone (first (filter #(= -1 (:id %)) dashcards))
+ source (first (filter #(= 7 (:id %)) dashcards))]
+ (is (= ["p1"] (:inline_parameters source))
+ "the source keeps the placement")
+ (is (empty? (:inline_parameters clone))
+ "the clone claims no inline parameter")
+ (is (= {"p1" [7]} (inline-parameter-owners dashcards))
+ "exactly one dashcard owns p1")
+ (is (= [mapping] (:parameter_mappings clone))
+ "the wiring is still cloned — many dashcards may map one parameter, only one may place it"))))
+
+(deftest duplicate-tab-does-not-clone-inline-parameters-test
+ (testing "GHY-4326: duplicating a whole tab leaves every inline placement on the source cards"
+ (let [current {:id 1
+ :tabs [{:id 5 :name "A"}]
+ :parameters [{:id "p1" :name "Cat" :slug "cat" :type "string/="}
+ {:id "p2" :name "Dog" :slug "dog" :type "string/="}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :dashboard_tab_id 5 :visualization_settings {}
+ :inline_parameters ["p1"]}
+ {:id 8 :card_id 9 :row 4 :col 0 :size_x 4 :size_y 4
+ :dashboard_tab_id 5 :visualization_settings {}
+ :inline_parameters ["p2"]}]}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ current
+ [{:op "duplicate_tab" :id -1 :tab_id 5}])
+ clones (filterv #(= -1 (:dashboard_tab_id %)) dashcards)]
+ (is (= 2 (count clones)))
+ (is (every? #(empty? (:inline_parameters %)) clones)
+ "no clone claims an inline parameter")
+ (is (= {"p1" [7] "p2" [8]} (inline-parameter-owners dashcards))
+ "each parameter is still owned by exactly the dashcard it was placed on"))))
+
+(def ^:private a-dashcard
+ {:id 7 :card_id 9 :row 2 :col 3 :size_x 4 :size_y 4 :dashboard_tab_id nil
+ :visualization_settings {:card.title "Old"}
+ :parameter_mappings [{:parameter_id "p1" :card_id 9 :target ["dimension" ["field" 1 nil]]}]
+ :series [{:id 11}]})
+
+(deftest replace-card-resets-content-test
+ (testing "GHY-4147: replace_card keeps the dashcard id and resets series, mappings, and viz settings"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "replace_card" :dashcard_id 7 :card_id 99}])
+ dc (first dashcards)]
+ (is (= 7 (:id dc)))
+ (is (= 99 (:card_id dc)))
+ (is (= [] (:series dc)))
+ (is (= [] (:parameter_mappings dc)))
+ (is (= {} (:visualization_settings dc)))
+ (testing "layout is untouched"
+ (is (= [2 3 4 4] [(:row dc) (:col dc) (:size_x dc) (:size_y dc)]))))))
+
+(deftest move-and-resize-test
+ (testing "GHY-4147: move relocates, resize resizes, neither disturbs the other"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "move" :dashcard_id 7 :position {:row 0 :col 0}}
+ {:op "resize" :dashcard_id 7 :size {:size_x 8 :size_y 2}}])
+ dc (first dashcards)]
+ (is (= [0 0 8 2] [(:row dc) (:col dc) (:size_x dc) (:size_y dc)])))))
+
+(deftest move-without-a-position-keeps-its-own-slot-test
+ (testing "GHY-4147: move without a position autoplaces against the *other* cards on the tab. The
+ moved card is not its own sibling — counting it means the search can never return the
+ slot it already occupies, so a card alone on a tab is displaced by its own footprint"
+ (let [wide {:id 7 :card_id 9 :row 0 :col 0 :size_x 24 :size_y 4 :dashboard_tab_id nil}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [wide])
+ [{:op "move" :dashcard_id 7}])
+ dc (first dashcards)]
+ (is (= [0 0] [(:row dc) (:col dc)])))))
+
+(deftest remove-test
+ (testing "GHY-4147: remove drops the dashcard from the payload, which deletes it on save"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "remove" :dashcard_id 7}])]
+ (is (= [] dashcards)))))
+
+(deftest set-series-test
+ (testing "GHY-4147: set_series is an ordered full replace"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "set_series" :dashcard_id 7 :card_ids [21 20]}])]
+ (is (= [{:id 21} {:id 20}] (:series (first dashcards)))))))
+
+(deftest patch-dashcard-merges-content-test
+ (testing "GHY-4147: patch_dashcard merges into visualization_settings rather than replacing them"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "patch_dashcard" :dashcard_id 7
+ :patch {:visualization_settings {:card.description "New"}}}])
+ vs (:visualization_settings (first dashcards))]
+ (is (= "Old" (:card.title vs)))
+ (is (= "New" (:card.description vs))))))
+
+(deftest patch-dashcard-rejects-layout-keys-test
+ (testing "GHY-4147: layout and identity keys in a patch are rejected, naming the op that owns them"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*`row`.*move"
+ (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "patch_dashcard" :dashcard_id 7 :patch {:row 0}}])))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*`size_x`.*resize"
+ (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "patch_dashcard" :dashcard_id 7 :patch {:size_x 4}}])))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*`card_id`.*replace_card"
+ (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "patch_dashcard" :dashcard_id 7 :patch {:card_id 1}}])))))
+
+(deftest patch-dashcard-rejects-unknown-keys-test
+ (testing "GHY-4147: a patch key that is neither a layout key nor a content column is rejected —
+ on a new dashcard it would otherwise reach the insert as a raw DB error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*`nonsense`.*not a patchable property"
+ (dashboard-ops/compile-ops
+ (dash-with [a-dashcard])
+ [{:op "patch_dashcard" :dashcard_id 7 :patch {:nonsense "x"}}])))
+ (testing "including on a card added in the same batch"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 1.*not a patchable property"
+ (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_card" :id -1 :card_id 42}
+ {:op "patch_dashcard" :dashcard_id -1 :patch {:bogus 1}}]))))))
+
+(deftest ops-apply-in-order-test
+ (testing "GHY-4147: a later op sees the effect of an earlier one — add then move the same new card"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_card" :id -1 :card_id 42}
+ {:op "move" :dashcard_id -1 :position {:row 9 :col 1}}])]
+ (is (= [9 1] [(:row (first dashcards)) (:col (first dashcards))])))))
+
+(deftest add-tab-and-place-a-card-in-it-test
+ (testing "GHY-4147: a card can reference a tab created earlier in the same batch by its negative id"
+ (let [{:keys [tabs dashcards]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_tab" :id -1 :name "Q3"}
+ {:op "add_card" :id -2 :card_id 42 :tab -1}])]
+ (is (= [{:id -1 :name "Q3"}] tabs))
+ (is (= -1 (:dashboard_tab_id (first dashcards)))))))
+
+(deftest rename-tab-test
+ (testing "GHY-4147: rename_tab changes only the name"
+ (let [{:keys [tabs]} (dashboard-ops/compile-ops
+ (assoc empty-dash :tabs [{:id 5 :name "Old" :position 0}])
+ [{:op "rename_tab" :tab_id 5 :name "New"}])]
+ (is (= "New" (:name (first tabs))))
+ (is (= 5 (:id (first tabs)))))))
+
+(deftest move-tab-reorders-test
+ (testing "GHY-4147: move_tab reorders the vector; update-dashboard! derives :position from the index"
+ (let [{:keys [tabs]} (dashboard-ops/compile-ops
+ (assoc empty-dash :tabs [{:id 5 :name "A"} {:id 6 :name "B"} {:id 7 :name "C"}])
+ [{:op "move_tab" :tab_id 7 :index 0}])]
+ (is (= [7 5 6] (mapv :id tabs))))))
+
+(deftest duplicate-tab-clones-cards-test
+ (testing "GHY-4147: duplicate_tab clones the tab and every dashcard on it, under new negative ids"
+ (let [current {:id 1
+ :tabs [{:id 5 :name "A"}]
+ :parameters []
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :dashboard_tab_id 5 :visualization_settings {}}]}
+ {:keys [tabs dashcards]} (dashboard-ops/compile-ops
+ current
+ [{:op "duplicate_tab" :id -1 :tab_id 5}])]
+ (is (= [5 -1] (mapv :id tabs)))
+ (is (= "A" (:name (second tabs))))
+ (is (= 2 (count dashcards)))
+ (let [clone (first (filter #(= -1 (:dashboard_tab_id %)) dashcards))]
+ (is (neg? (:id clone)))
+ (is (= 9 (:card_id clone)))))))
+
+(deftest duplicate-tab-minted-ids-stay-distinct-test
+ (testing "GHY-4147: the negative ids duplicate_tab mints for its clones stay distinct from each
+ other and from every id the caller uses elsewhere in the batch"
+ (let [current {:id 1
+ :tabs [{:id 5 :name "A"}]
+ :parameters []
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :dashboard_tab_id 5 :visualization_settings {}}
+ {:id 8 :card_id 9 :row 4 :col 0 :size_x 4 :size_y 4
+ :dashboard_tab_id 5 :visualization_settings {}}]}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ current
+ [{:op "duplicate_tab" :id -1 :tab_id 5}
+ {:op "add_card" :id -10 :card_id 9 :tab -1}]
+ {})
+ ids (mapv :id dashcards)]
+ (is (= 5 (count dashcards)))
+ (is (apply distinct? ids)))))
+
+(deftest remove-tab-deletes-its-cards-test
+ (testing "GHY-4147: remove_tab drops the tab and every dashcard on it"
+ (let [current {:id 1
+ :tabs [{:id 5 :name "A"} {:id 6 :name "B"}]
+ :parameters []
+ :dashcards [{:id 7 :card_id 9 :dashboard_tab_id 5 :row 0 :col 0 :size_x 4 :size_y 4}
+ {:id 8 :card_id 9 :dashboard_tab_id 6 :row 0 :col 0 :size_x 4 :size_y 4}]}
+ {:keys [tabs dashcards]} (dashboard-ops/compile-ops current [{:op "remove_tab" :tab_id 5}])]
+ (is (= [6] (mapv :id tabs)))
+ (is (= [8] (mapv :id dashcards))))))
+
+(deftest tab-coverage-is-enforced-test
+ (testing "GHY-4147: with two or more tabs present, a dashcard with no tab is rejected with a clear message"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"every card must belong to a tab"
+ (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_tab" :id -1 :name "Q3"}
+ {:op "add_tab" :id -2 :name "Q4"}
+ {:op "add_card" :id -3 :card_id 42}])))))
+
+(deftest single-tab-coverage-is-not-enforced-test
+ (testing "GHY-4147: with exactly one tab, a tabless card is allowed — update-dashboard! back-fills
+ its dashboard_tab_id itself (api.clj), so the compiler must not reject it early"
+ (is (some? (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_tab" :id -1 :name "Q3"}
+ {:op "add_card" :id -2 :card_id 42}])))))
+
+(deftest unknown-tab-is-rejected-test
+ (testing "GHY-4147: referencing a tab that does not exist names the op index"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*99"
+ (dashboard-ops/compile-ops empty-dash [{:op "rename_tab" :tab_id 99 :name "x"}])))))
+
+(def ^:private one-tab-dash
+ {:id 1 :dashcards [] :tabs [{:id 5 :name "A"}] :parameters []})
+
+(deftest add-card-rejects-a-tab-not-on-this-dashboard-test
+ (testing "GHY-4147: `tab` naming a tab that belongs to a different dashboard is a teaching error
+ naming the op index — a dashcard on a foreign tab renders nowhere and cannot be repaired
+ in the editor"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0 \(add_card\): no tab with id 77 on this dashboard\."
+ (dashboard-ops/compile-ops one-tab-dash [{:op "add_card" :id -1 :card_id 42 :tab 77}]))))
+ (testing "GHY-4147: a tab id that exists nowhere teaches the same way instead of failing opaquely later"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 1 \(add_card\): no tab with id 999 on this dashboard\."
+ (dashboard-ops/compile-ops one-tab-dash
+ [{:op "add_card" :id -1 :card_id 42 :tab 5}
+ {:op "add_card" :id -2 :card_id 42 :tab 999}])))))
+
+(deftest virtual-dashcard-rejects-a-tab-not-on-this-dashboard-test
+ (testing "GHY-4147: the virtual add ops validate `tab` the same way add_card does"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0 \(add_text\): no tab with id 77 on this dashboard\."
+ (dashboard-ops/compile-ops one-tab-dash [{:op "add_text" :id -1 :markdown "hi" :tab 77}])))))
+
+(deftest duplicate-card-rejects-a-tab-not-on-this-dashboard-test
+ (testing "GHY-4147: duplicate_card's optional `tab` is validated too"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0 \(duplicate_card\): no tab with id 77 on this dashboard\."
+ (dashboard-ops/compile-ops
+ (assoc one-tab-dash :dashcards [{:id 7 :card_id 9 :dashboard_tab_id 5
+ :row 0 :col 0 :size_x 4 :size_y 4}])
+ [{:op "duplicate_card" :id -1 :dashcard_id 7 :tab 77}])))))
+
+(def ^:private a-card
+ "Minimal stand-in for a hydrated card; mapping-targets is stubbed in these tests, so only the
+ id matters here."
+ {:id 9 :name "Revenue" :type "question"})
+
+(deftest add-parameter-test
+ (testing "GHY-4147: add_parameter appends a parameter carrying the caller's id, REST names intact"
+ (let [{:keys [parameters]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_parameter" :parameter_id "p_date" :name "Date"
+ :type "date/all-options" :isMultiSelect false}]
+ {})]
+ (is (= [{:id "p_date" :name "Date" :slug "date" :type "date/all-options" :isMultiSelect false}]
+ parameters)))))
+
+(deftest add-parameter-derives-slug-from-name-test
+ (testing "GHY-4147: a created parameter gets the URL slug the editor would give it, so it is
+ addressable by slug in embedding, public links, and URL param sync"
+ (let [{:keys [parameters]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_parameter" :parameter_id "p1" :name "Order Total"
+ :type "number/>="}]
+ {})]
+ (is (= "order_total" (:slug (first parameters)))))
+ (testing "a nameless parameter gets no slug rather than a bogus one"
+ (let [{:keys [parameters]} (dashboard-ops/compile-ops
+ empty-dash
+ [{:op "add_parameter" :parameter_id "p1" :type "string/="}]
+ {})]
+ (is (not (contains? (first parameters) :slug)))))))
+
+(deftest add-parameter-rejects-duplicate-id-test
+ (testing "GHY-4147: reusing an existing parameter id is a teaching error pointing at update_parameter"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*update_parameter"
+ (dashboard-ops/compile-ops
+ (assoc empty-dash :parameters [{:id "p1" :name "X" :type "string/="}])
+ [{:op "add_parameter" :parameter_id "p1" :name "Y" :type "string/="}]
+ {})))))
+
+(deftest update-parameter-merges-test
+ (testing "GHY-4147: update_parameter merges into the existing parameter, re-slugging on a rename"
+ (let [{:keys [parameters]} (dashboard-ops/compile-ops
+ (assoc empty-dash :parameters [{:id "p1" :name "X" :type "string/="}])
+ [{:op "update_parameter" :parameter_id "p1" :name "Y"}]
+ {})]
+ (is (= [{:id "p1" :name "Y" :slug "y" :type "string/="}] parameters)))))
+
+(deftest update-parameter-preserves-slug-when-not-renaming-test
+ (testing "GHY-4147: an update that does not touch the name leaves the slug alone, so an edit to
+ an editor-created parameter cannot silently break its existing URLs"
+ (let [{:keys [parameters]} (dashboard-ops/compile-ops
+ (assoc empty-dash
+ :parameters [{:id "p1" :name "Order-Date" :slug "order-date"
+ :type "date/all-options"}])
+ [{:op "update_parameter" :parameter_id "p1" :isMultiSelect true}]
+ {})]
+ (is (= "order-date" (:slug (first parameters)))))))
+
+(deftest remove-parameter-strips-mappings-test
+ (testing "GHY-4147: remove_parameter drops the parameter, its dashcard mappings, its inline
+ placements, and any linked-filter reference to it"
+ (let [current {:id 1 :tabs []
+ :parameters [{:id "p1" :name "X" :type "string/="}
+ {:id "p2" :name "Y" :type "string/=" :filteringParameters ["p1"]}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :inline_parameters ["p1" "p2"]
+ :parameter_mappings [{:parameter_id "p1" :card_id 9 :target [:dimension [:field 1 nil]]}
+ {:parameter_id "p2" :card_id 9 :target [:dimension [:field 2 nil]]}]}]}
+ {:keys [parameters dashcards]} (dashboard-ops/compile-ops
+ current [{:op "remove_parameter" :parameter_id "p1"}] {})
+ dc (first dashcards)]
+ (is (= ["p2"] (mapv :id parameters)))
+ (is (= [] (:filteringParameters (first parameters))))
+ (is (= ["p2"] (:inline_parameters dc)))
+ (is (= ["p2"] (mapv :parameter_id (:parameter_mappings dc)))))))
+
+(deftest move-parameter-reorders-header-test
+ (testing "GHY-4147: move_parameter with an index reorders the header"
+ (let [{:keys [parameters]} (dashboard-ops/compile-ops
+ (assoc empty-dash :parameters [{:id "a"} {:id "b"} {:id "c"}])
+ [{:op "move_parameter" :parameter_id "c" :index 0}]
+ {})]
+ (is (= ["c" "a" "b"] (mapv :id parameters))))))
+
+(deftest move-parameter-requires-exactly-one-target-test
+ (testing "GHY-4147: move_parameter with both index and dashcard_id is a teaching error rather than
+ a silent win for dashcard_id — the op documents \"exactly one\", and add_link refuses the
+ same both/neither case"
+ (let [current {:id 1 :tabs [] :parameters [{:id "p1"} {:id "p2"}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4}]}]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"op 0.*exactly one"
+ (dashboard-ops/compile-ops
+ current
+ [{:op "move_parameter" :parameter_id "p1" :index 0 :dashcard_id 7}]
+ {}))))))
+
+(deftest move-parameter-onto-a-card-test
+ (testing "GHY-4147: move_parameter with a dashcard_id makes it an inline filter on that card"
+ (let [current {:id 1 :tabs [] :parameters [{:id "p1"}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4}]}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ current [{:op "move_parameter" :parameter_id "p1" :dashcard_id 7}] {})]
+ (is (= ["p1"] (:inline_parameters (first dashcards)))))))
+
+(deftest move-parameter-moves-between-cards-test
+ (testing "GHY-4147: move_parameter onto a card removes the inline placement from every other card —
+ a parameter lives in one place — and re-running the op does not duplicate the entry"
+ (let [current {:id 1 :tabs [] :parameters [{:id "p1"}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :inline_parameters ["p1"]}
+ {:id 8 :card_id 9 :row 4 :col 0 :size_x 4 :size_y 4}]}
+ op {:op "move_parameter" :parameter_id "p1" :dashcard_id 8}
+ {:keys [dashcards]} (dashboard-ops/compile-ops current [op op] {})]
+ (is (= [] (:inline_parameters (first dashcards))))
+ (is (= ["p1"] (:inline_parameters (second dashcards)))))))
+
+(deftest move-parameter-leaves-bystanders-verbatim-test
+ (testing "GHY-4147: move_parameter onto a card leaves every card that carried no inline placements
+ exactly as it was — stamping :inline_parameters onto them, or rewriting a legacy nil as
+ [], would register untouched rows as changed in update-dashboard!'s row diff"
+ (let [bystander {:id 8 :card_id 9 :row 4 :col 0 :size_x 4 :size_y 4}
+ legacy {:id 9 :card_id 9 :row 8 :col 0 :size_x 4 :size_y 4 :inline_parameters nil}
+ current {:id 1 :tabs [] :parameters [{:id "p1"}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4}
+ bystander legacy]}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ current
+ [{:op "move_parameter" :parameter_id "p1" :dashcard_id 7}] {})]
+ (is (= bystander (nth dashcards 1)))
+ (is (= legacy (nth dashcards 2))))))
+
+(deftest unwire-parameter-leaves-unwired-cards-verbatim-test
+ (testing "GHY-4147: blanket unwire_parameter leaves cards with no mappings exactly as they were —
+ rewriting an absent or legacy-nil :parameter_mappings as [] would register untouched
+ rows as changed in update-dashboard!'s row diff"
+ (let [bystander {:id 8 :card_id 9 :row 4 :col 0 :size_x 4 :size_y 4}
+ legacy {:id 9 :card_id 9 :row 8 :col 0 :size_x 4 :size_y 4 :parameter_mappings nil}
+ current {:id 1 :tabs [] :parameters [{:id "p1"}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :parameter_mappings [{:parameter_id "p1" :card_id 9
+ :target [:dimension [:field 1 nil]]}]}
+ bystander legacy]}
+ {:keys [dashcards]} (dashboard-ops/compile-ops
+ current
+ [{:op "unwire_parameter" :parameter_id "p1"}] {})]
+ (is (= [] (:parameter_mappings (first dashcards))))
+ (is (= bystander (nth dashcards 1)))
+ (is (= legacy (nth dashcards 2))))))
+
+(deftest wire-parameter-by-field-test
+ (testing "GHY-4147: wire_parameter writes a parameter mapping using the card's target for the field"
+ (let [current {:id 1 :tabs [] :parameters [{:id "p1" :name "Cat" :type "string/="}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :parameter_mappings []}]}
+ {:keys [dashcards]} (with-redefs [metabase.parameters.mapping-targets/target-for-field
+ (fn [_card _param field-id]
+ [:dimension [:field field-id nil]])]
+ (dashboard-ops/compile-ops
+ current
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_field 55}]
+ {9 a-card}))]
+ (is (= [{:parameter_id "p1" :card_id 9 :target [:dimension [:field 55 nil]]}]
+ (:parameter_mappings (first dashcards)))))))
+
+(deftest wire-parameter-rewire-replaces-mapping-test
+ (testing "GHY-4147: wiring a parameter that is already wired on the dashcard replaces its mapping —
+ a re-wire must never accumulate a second mapping for the same parameter"
+ (let [current {:id 1 :tabs [] :parameters [{:id "p1" :name "Cat" :type "string/="}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :parameter_mappings []}]}
+ {:keys [dashcards]} (with-redefs [metabase.parameters.mapping-targets/target-for-field
+ (fn [_card _param field-id]
+ [:dimension [:field field-id nil]])]
+ (dashboard-ops/compile-ops
+ current
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_field 55}
+ {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_field 66}]
+ {9 a-card}))]
+ (is (= [{:parameter_id "p1" :card_id 9 :target [:dimension [:field 66 nil]]}]
+ (:parameter_mappings (first dashcards)))))))
+
+(deftest wire-parameter-rejects-an-unavailable-field-test
+ (testing "GHY-4147: a field the card does not expose is a teaching error naming the op"
+ (let [current {:id 1 :tabs [] :parameters [{:id "p1" :name "Cat" :type "string/="}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4 :parameter_mappings []}]}]
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*wire_parameter"
+ (with-redefs [metabase.parameters.mapping-targets/target-for-field (constantly nil)]
+ (dashboard-ops/compile-ops
+ current
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_field 55}]
+ {9 a-card})))))))
+
+(deftest wire-parameter-unknown-parameter-test
+ (testing "GHY-4147: wiring a parameter that does not exist names the op index"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*nope"
+ (dashboard-ops/compile-ops
+ {:id 1 :tabs [] :parameters []
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4 :parameter_mappings []}]}
+ [{:op "wire_parameter" :parameter_id "nope" :dashcard_id 7 :target_field 55}]
+ {9 a-card})))))
+
+(deftest autowire-maps-every-compatible-card-test
+ (testing "GHY-4147: autowire wires every card that exposes a compatible target, skipping those that don't"
+ (let [current {:id 1 :tabs [] :parameters [{:id "p1" :name "Cat" :type "string/="}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4 :parameter_mappings []}
+ {:id 8 :card_id 10 :row 4 :col 0 :size_x 4 :size_y 4 :parameter_mappings []}]}
+ {:keys [dashcards]} (with-redefs [metabase.parameters.mapping-targets/target-for-field
+ (fn [card _param field-id]
+ (when (= 9 (:id card)) [:dimension [:field field-id nil]]))]
+ (dashboard-ops/compile-ops
+ current
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7
+ :target_field 55 :autowire true}]
+ {9 {:id 9} 10 {:id 10}}))]
+ (is (= 1 (count (:parameter_mappings (first dashcards)))))
+ (is (= [] (:parameter_mappings (second dashcards)))))))
+
+(deftest unwire-parameter-test
+ (testing "GHY-4147: unwire_parameter clears one card's mapping, or every card's when dashcard_id is omitted"
+ (let [current {:id 1 :tabs [] :parameters [{:id "p1"}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :parameter_mappings [{:parameter_id "p1" :card_id 9 :target [:dimension [:field 1 nil]]}]}
+ {:id 8 :card_id 10 :row 4 :col 0 :size_x 4 :size_y 4
+ :parameter_mappings [{:parameter_id "p1" :card_id 10 :target [:dimension [:field 2 nil]]}]}]}]
+ (testing "one card"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ current [{:op "unwire_parameter" :parameter_id "p1" :dashcard_id 7}] {})]
+ (is (= [] (:parameter_mappings (first dashcards))))
+ (is (= 1 (count (:parameter_mappings (second dashcards)))))))
+ (testing "all cards"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ current [{:op "unwire_parameter" :parameter_id "p1"}] {})]
+ (is (every? (comp empty? :parameter_mappings) dashcards)))))))
+
+(def ^:private native-card
+ "A native card with one tag of each wireable kind plus a snippet-reference tag, for exercising
+ the tag-type-driven wiring."
+ {:id 9
+ :name "Native revenue"
+ :type "question"
+ :dataset_query
+ {:database 1
+ :type :native
+ :native {:query "SELECT 1 WHERE {{cat}} AND total > {{min}} /* {{unit}} {{snippet: base}} */"
+ :template-tags
+ {"cat" {:id "u1" :name "cat" :display-name "Category" :type :dimension
+ :dimension [:field 18 nil] :widget-type :string/=}
+ "min" {:id "u2" :name "min" :display-name "Min" :type :number}
+ "unit" {:id "u3" :name "unit" :display-name "Unit" :type :temporal-unit
+ :dimension [:field 22 nil]}
+ "snippet: base" {:id "u4" :name "snippet: base" :display-name "base" :type :snippet
+ :snippet-name "base"}}}}})
+
+(def ^:private native-current
+ {:id 1 :tabs []
+ :parameters [{:id "p1" :name "Cat" :type "string/="}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4 :parameter_mappings []}]})
+
+(defn- wire-native
+ [op]
+ (-> (dashboard-ops/compile-ops native-current [op] {9 native-card})
+ :dashcards first :parameter_mappings))
+
+(deftest wire-parameter-target-tag-derives-kind-test
+ (testing "target_tag emits a :dimension target for a field-filter tag"
+ (is (= [{:parameter_id "p1" :card_id 9 :target [:dimension [:template-tag "cat"]]}]
+ (wire-native {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_tag "cat"}))))
+ (testing "target_tag emits a :dimension target for a temporal-unit tag"
+ (is (= [{:parameter_id "p1" :card_id 9 :target [:dimension [:template-tag "unit"]]}]
+ (wire-native {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_tag "unit"}))))
+ (testing "target_tag emits a :variable target for a raw-variable tag"
+ (is (= [{:parameter_id "p1" :card_id 9 :target [:variable [:template-tag "min"]]}]
+ (wire-native {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_tag "min"})))))
+
+(deftest wire-parameter-target-tag-rejections-test
+ (testing "a tag that does not exist on the card is a teaching error naming the tags that do"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*no template tag named \"nope\".*cat"
+ (wire-native {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_tag "nope"}))))
+ (testing "a snippet-reference tag cannot back a parameter"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*snippet-reference tag"
+ (wire-native {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_tag "snippet: base"}))))
+ (testing "a dashcard with no card behind it has nothing to wire"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*no card behind it"
+ (dashboard-ops/compile-ops
+ (assoc native-current :dashcards [{:id 7 :row 0 :col 0 :size_x 4 :size_y 4
+ :visualization_settings {:virtual_card {:display "text"}}}])
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target_tag "cat"}]
+ {})))))
+
+(deftest wire-parameter-raw-target-coerced-and-validated-test
+ (testing "a raw target arrives as JSON strings, is keywordized, and saves when it resolves"
+ (is (= [{:parameter_id "p1" :card_id 9 :target [:dimension [:template-tag "cat"]]}]
+ (wire-native {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7
+ :target ["dimension" ["template-tag" "cat"]]}))))
+ (testing "a raw target whose kind does not match the tag is rejected, on validate_only and save alike"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*resolves to nothing"
+ (wire-native {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7
+ :target ["variable" ["template-tag" "cat"]]}))))
+ (testing "a raw target naming a nonexistent tag is rejected"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*resolves to nothing"
+ (wire-native {:op "wire_parameter" :parameter_id "p1" :dashcard_id 7
+ :target ["dimension" ["template-tag" "ghost"]]})))))
+
+(deftest wire-parameter-text-tag-target-test
+ (let [text-dashcard {:id 7 :row 0 :col 0 :size_x 12 :size_y 3
+ :visualization_settings {:virtual_card {:display "text"}
+ :text "Sales in {{region}} for {{period}}."}}
+ current (assoc native-current :dashcards [text-dashcard])]
+ (testing "a text-tag target binds a {{placeholder}} in a text card's own markdown — no card needed"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ current
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7
+ :target ["text-tag" "region"]}]
+ {})]
+ (is (= [{:parameter_id "p1" :card_id nil :target [:text-tag "region"]}]
+ (:parameter_mappings (first dashcards))))))
+ (testing "an iframe card's embed carries placeholders too"
+ (let [{:keys [dashcards]} (dashboard-ops/compile-ops
+ (assoc current :dashcards
+ [{:id 7 :row 0 :col 0 :size_x 12 :size_y 8
+ :visualization_settings {:virtual_card {:display "iframe"}
+ :iframe "https://x.test/?r={{region}}"}}])
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7
+ :target ["text-tag" "region"]}]
+ {})]
+ (is (= [[:text-tag "region"]]
+ (mapv :target (:parameter_mappings (first dashcards)))))))
+ (testing "a name absent from the card's text is a teaching error listing its placeholders"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*resolves to nothing on dashcard 7.*period.*region"
+ (dashboard-ops/compile-ops
+ current
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target ["text-tag" "ghost"]}]
+ {}))))
+ (testing "a text-tag target on a card-backed dashcard is rejected — it carries no text of its own"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo #"op 0.*carries none"
+ (dashboard-ops/compile-ops
+ native-current
+ [{:op "wire_parameter" :parameter_id "p1" :dashcard_id 7 :target ["text-tag" "region"]}]
+ {9 native-card}))))))
+
+;;; ---------------------------------------------- State algebra ----------------------------------------------------
+
+(def ^:private rows-state
+ "A plain working state for driving the row primitives directly — all three collections are
+ vectors of :id-keyed maps in save order."
+ {:dashcards [{:id 1 :a 1} {:id 2 :a 2} {:id 3 :a 3}]
+ :tabs [{:id 10 :name "A"} {:id 11 :name "B"} {:id 12 :name "C"}]
+ :parameters [{:id "p1"} {:id "p2"} {:id "p3"}]})
+
+(deftest update-row-test
+ (testing "GHY-4147 refactor: update-row rewrites only the target row, order preserved, in every collection"
+ (doseq [[coll id f expected]
+ [[:dashcards 2 #(assoc % :a 99) [{:id 1 :a 1} {:id 2 :a 99} {:id 3 :a 3}]]
+ [:tabs 10 #(assoc % :name "Z") [{:id 10 :name "Z"} {:id 11 :name "B"} {:id 12 :name "C"}]]
+ [:parameters "p3" #(assoc % :x 1) [{:id "p1"} {:id "p2"} {:id "p3" :x 1}]]]]
+ (testing coll
+ (is (= expected (get (#'dashboard-ops/update-row rows-state coll id f) coll)))))))
+
+(deftest remove-row-test
+ (testing "GHY-4147 refactor: remove-row drops only the target row, preserving the order of the rest"
+ (doseq [[coll id expected]
+ [[:dashcards 2 [{:id 1 :a 1} {:id 3 :a 3}]]
+ [:tabs 12 [{:id 10 :name "A"} {:id 11 :name "B"}]]
+ [:parameters "p1" [{:id "p2"} {:id "p3"}]]]]
+ (testing coll
+ (is (= expected (get (#'dashboard-ops/remove-row rows-state coll id) coll)))))))
+
+(deftest map-rows-test
+ (testing "GHY-4147 refactor: map-rows transforms every row in place, order preserved"
+ (is (= [{:id 1 :a 1 :m true} {:id 2 :a 2 :m true} {:id 3 :a 3 :m true}]
+ (:dashcards (#'dashboard-ops/map-rows rows-state :dashcards #(assoc % :m true)))))))
+
+(deftest move-row-test
+ (testing "GHY-4147 refactor: move-row lands the target at the index, relative order of the rest preserved"
+ (doseq [[id index expected] [[12 0 [12 10 11]]
+ [10 2 [11 12 10]]
+ [11 1 [10 11 12]]]]
+ (testing [id index]
+ (is (= expected (mapv :id (:tabs (#'dashboard-ops/move-row rows-state :tabs id index))))))))
+ (testing "the same rows come back, just reordered"
+ (is (= (frequencies (:tabs rows-state))
+ (frequencies (:tabs (#'dashboard-ops/move-row rows-state :tabs 11 0))))))
+ (testing "nil when the index falls outside [0, count-after-removal], so the op owns its error"
+ (is (nil? (#'dashboard-ops/move-row rows-state :tabs 11 -1)))
+ (is (nil? (#'dashboard-ops/move-row rows-state :tabs 11 3)))))
+
+(deftest upsert-mapping-test
+ (let [dc {:id 7 :card_id 9
+ :parameter_mappings [{:parameter_id "p1" :card_id 9 :target [:dimension [:field 1 nil]]}
+ {:parameter_id "p2" :card_id 9 :target [:dimension [:field 2 nil]]}]}]
+ (testing "GHY-4147 refactor: wiring twice leaves one mapping for the parameter, carrying the latest
+ target; other parameters' mappings and their order survive"
+ (is (= [{:parameter_id "p2" :card_id 9 :target [:dimension [:field 2 nil]]}
+ {:parameter_id "p1" :card_id 9 :target [:dimension [:field 6 nil]]}]
+ (:parameter_mappings
+ (-> dc
+ (#'dashboard-ops/upsert-mapping "p1" [:dimension [:field 5 nil]])
+ (#'dashboard-ops/upsert-mapping "p1" [:dimension [:field 6 nil]]))))))
+ (testing "card_id comes from the dashcard, including nil for a virtual card"
+ (is (= [{:parameter_id "p1" :card_id nil :target [:text-tag "region"]}]
+ (:parameter_mappings
+ (#'dashboard-ops/upsert-mapping {:id 7} "p1" [:text-tag "region"])))))))
+
+(deftest inline-parameter-round-trip-test
+ (let [dc {:id 7 :inline_parameters ["p1"]}]
+ (testing "GHY-4147 refactor: adding an inline parameter twice is the same as adding it once"
+ (is (= ["p1" "p2"]
+ (:inline_parameters (-> dc
+ (#'dashboard-ops/add-inline-parameter "p2")
+ (#'dashboard-ops/add-inline-parameter "p2"))))))
+ (testing "dropping after adding restores the original dashcard for a fresh id"
+ (is (= dc (-> dc
+ (#'dashboard-ops/add-inline-parameter "p2")
+ (#'dashboard-ops/drop-inline-parameter "p2")))))))
+
+(deftest drop-helpers-leave-empty-collections-untouched-test
+ (testing "an absent, nil, or empty collection is left exactly as it was — writing the key, or
+ rewriting nil as [], would make an untouched dashcard register as changed in
+ update-dashboard!'s row diff"
+ (doseq [dc [{:id 7}
+ {:id 7 :inline_parameters nil}
+ {:id 7 :inline_parameters []}]]
+ (is (= dc (#'dashboard-ops/drop-inline-parameter dc "p1"))))
+ (doseq [dc [{:id 7}
+ {:id 7 :parameter_mappings nil}
+ {:id 7 :parameter_mappings []}]]
+ (is (= dc (#'dashboard-ops/drop-mapping dc "p1"))))))
+
+(deftest remove-parameter-cascade-composes-from-primitives-test
+ (testing "GHY-4147 refactor: remove_parameter's cascade is exactly this primitive composition — if the
+ op's wiring drifts from the algebra, this fails"
+ (let [current {:id 1 :tabs []
+ :parameters [{:id "p1"}
+ {:id "p2" :filteringParameters ["p1"]}]
+ :dashcards [{:id 7 :card_id 9 :row 0 :col 0 :size_x 4 :size_y 4
+ :inline_parameters ["p1" "p2"]
+ :parameter_mappings [{:parameter_id "p1" :card_id 9 :target [:dimension [:field 1 nil]]}
+ {:parameter_id "p2" :card_id 9 :target [:dimension [:field 2 nil]]}]}]}
+ state (select-keys current [:dashcards :tabs :parameters])
+ s (#'dashboard-ops/remove-row state :parameters "p1")
+ s (#'dashboard-ops/map-rows s :parameters
+ (fn [p]
+ (cond-> p
+ (contains? p :filteringParameters)
+ (update :filteringParameters (partial filterv #(not= "p1" %))))))
+ via-primitives
+ (#'dashboard-ops/map-rows s :dashcards
+ (fn [dc]
+ (-> dc
+ (#'dashboard-ops/drop-inline-parameter "p1")
+ (#'dashboard-ops/drop-mapping "p1"))))]
+ (is (= via-primitives
+ (dashboard-ops/compile-ops current [{:op "remove_parameter" :parameter_id "p1"}] {}))))))
diff --git a/test/metabase/mcp/v2/queries_test.clj b/test/metabase/mcp/v2/queries_test.clj
new file mode 100644
index 00000000000..9270065ba7e
--- /dev/null
+++ b/test/metabase/mcp/v2/queries_test.clj
@@ -0,0 +1,91 @@
+(ns metabase.mcp.v2.queries-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+;;; ------------------------------------------------ Query handles (GHY-4136) -------------------------------------
+
+(defn- thrown
+ "Return `[status-code message]` from the exception `thunk` throws, or nil if it doesn't throw."
+ [thunk]
+ (try (thunk) nil
+ (catch clojure.lang.ExceptionInfo e [(:status-code (ex-data e)) (ex-message e)])))
+
+(defn- mbql-handle!
+ "Mint a handle for an orders-sourced MBQL query owned by `uid` in session `sid`."
+ [sid uid & [prompt]]
+ (v2.queries/mint-query-handle! sid uid
+ (v2.queries/encode-serialized-query
+ {:database (mt/id) :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :orders)}]})
+ prompt))
+
+(deftest handle-round-trip-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [uid (mt/user->id :rasta)
+ sid (str (random-uuid))
+ q {:database (mt/id) :stages [{:lib/type "mbql.stage/mbql" :source-table (mt/id :orders)}]}]
+ (mt/with-current-user uid
+ (testing "mint then resolve returns the stored query and prompt"
+ (let [h (v2.queries/mint-query-handle! sid uid (v2.queries/encode-serialized-query q) "show orders")
+ resolved (v2.queries/resolve-query-handle! sid uid h)]
+ (is (string? h))
+ (is (= "show orders" (:prompt resolved)))
+ ;; handles store base64 JSON, so the resolved query is the JSON round-trip of what was minted
+ (is (= (-> q json/encode json/decode+kw) (:query resolved)))))
+ (testing "prompt is optional"
+ (let [h (v2.queries/mint-query-handle! sid uid (v2.queries/encode-serialized-query q))]
+ (is (nil? (:prompt (v2.queries/resolve-query-handle! sid uid h))))))))))
+
+(deftest handle-ownership-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [uid (mt/user->id :rasta)
+ other (mt/user->id :lucky)
+ sid (str (random-uuid))]
+ (mt/with-current-user uid
+ (testing "an unknown/expired handle is a teaching error, not a 500"
+ (is (= 400 (first (thrown #(v2.queries/resolve-query-handle! sid uid (str (random-uuid))))))))
+ (testing "a handle resolves for its owner but not for another user"
+ (let [h (mbql-handle! sid uid)]
+ (is (nil? (thrown #(v2.queries/resolve-query-handle! sid uid h)))) ; owner: ok
+ (is (= 400 (first (thrown #(v2.queries/resolve-query-handle! sid other h))))))))))) ; other: not found
+
+(deftest handle-guards-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [uid (mt/user->id :rasta)
+ sid (str (random-uuid))]
+ (mt/with-current-user uid
+ (testing "a stored NATIVE query is rejected on the MBQL read path"
+ (let [h (v2.queries/mint-query-handle! sid uid
+ (v2.queries/encode-serialized-query
+ {:stages [{:lib/type "mbql.stage/native" :native "SELECT 1"}]}))]
+ (is (= [400 "Native queries are not supported here; use execute_sql instead."]
+ (thrown #(v2.queries/resolve-query-handle! sid uid h))))))
+ (testing "a garbage (non-map) stored payload is a teaching error, not a decode 500"
+ (let [h (v2.queries/mint-query-handle! sid uid (v2.queries/encode-serialized-query [1 2 3]))]
+ (is (= 400 (first (thrown #(v2.queries/resolve-query-handle! sid uid h)))))))
+ (testing "a stored query the caller can no longer access throws 403"
+ (let [h (mbql-handle! sid uid)]
+ (mt/with-no-data-perms-for-all-users!
+ (is (= 403 (first (thrown #(v2.queries/resolve-query-handle! sid uid h))))))))))))
+
+(deftest resolve-query-handle-for-save-allows-native-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [uid (mt/user->id :rasta)
+ sid (str (random-uuid))]
+ (mt/with-current-user uid
+ (testing "a stored NATIVE query resolves on the save path (no native reject)"
+ (let [native {:database (mt/id)
+ :stages [{:lib/type "mbql.stage/native" :native "SELECT 1"}]}
+ h (v2.queries/mint-query-handle! sid uid (v2.queries/encode-serialized-query native))]
+ (is (= native (:query (v2.queries/resolve-query-handle-for-save! sid uid h))))))
+ (testing "an unknown handle is a teaching error, not a 500"
+ (is (= [400 "Query handle not found — it may have expired; run the query again."]
+ (thrown #(v2.queries/resolve-query-handle-for-save! sid uid (str (random-uuid)))))))))))
diff --git a/test/metabase/mcp/v2/query_test.clj b/test/metabase/mcp/v2/query_test.clj
new file mode 100644
index 00000000000..8186da974a5
--- /dev/null
+++ b/test/metabase/mcp/v2/query_test.clj
@@ -0,0 +1,369 @@
+(ns metabase.mcp.v2.query-test
+ "Tests for keyset (seek) pagination of MBQL query results (GHY-4136)."
+ (:require
+ [clojure.test :refer [deftest is testing]]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.lib.equality :as lib.equality]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.queries :as queries]
+ [metabase.mcp.v2.query :as q]
+ [metabase.query-processor :as qp]
+ [metabase.test :as mt]))
+
+(set! *warn-on-reflection* true)
+
+(defn- mp [] (lib-be/application-database-metadata-provider (mt/id)))
+
+(defn- orders-query []
+ (lib/query (mp) (lib.metadata/table (mp) (mt/id :orders))))
+
+(defn- run-rows+cols [query]
+ (let [r (qp/process-query query)]
+ [(get-in r [:data :rows]) (get-in r [:data :cols])]))
+
+(defn- col-index [cols col-name]
+ (some (fn [[i c]] (when (= (:name c) col-name) i)) (map-indexed vector cols)))
+
+(deftest next-page-cursor-pk-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [uid (mt/user->id :rasta)
+ sid (str (random-uuid))
+ ;; the executed query carries the total order — that is what makes it continuable
+ query (q/with-total-order (lib/prepare-for-serialization (lib/limit (orders-query) 3)))
+ [rows cols] (run-rows+cols (lib/query (mp) query))
+ cursor (q/next-page-cursor! sid uid query (last rows) {:result-cols cols})
+ stage (-> (queries/resolve-query-handle! sid uid cursor) :query :stages last)]
+ (testing "a table-sourced query gets a keyset cursor: ORDER BY the PK, WHERE strictly past the boundary, LIMIT preserved"
+ (is (some? cursor))
+ (is (seq (:order-by stage)) "the next-page query carries a total order")
+ (is (= ">" (ffirst (:filters stage))) "the next-page query filters strictly past the last row")
+ (is (= 3 (:limit stage))))))))
+
+(deftest with-total-order-test
+ ;; The seam this closes: a page served under a partial order broke its ties however the engine
+ ;; happened to, while a keyset built afterwards imposes its own tie order — around a boundary
+ ;; inside a tie group the two disagree, dropping rows and repeating others. An unordered query
+ ;; is the extreme case (the whole result is one tie group), and it is what an agent writes by
+ ;; default. So the order goes on before execution, and the mint refuses anything else.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [uid (mt/user->id :rasta)
+ sid (str (random-uuid))
+ unordered (lib/prepare-for-serialization (lib/limit (orders-query) 3))
+ ordered (q/with-total-order unordered)
+ last-stage #(-> % :stages last)]
+ (testing "GHY-4142: an unordered query comes back ordered by the PK — a total order"
+ (is (empty? (:order-by (last-stage unordered))))
+ (is (= 1 (count (:order-by (last-stage ordered))))))
+ (testing "GHY-4142: idempotent — a second pass finds the tiebreakers already ordered"
+ (is (= ordered (q/with-total-order ordered))))
+ (testing "GHY-4142: a query whose own order is already total is left alone"
+ (let [by-pk (lib/prepare-for-serialization
+ (-> (orders-query)
+ (lib/order-by (lib.metadata/field (mp) (mt/id :orders :id)) :asc)
+ (lib/limit 3)))]
+ (is (= by-pk (q/with-total-order by-pk)))))
+ (testing "GHY-4142: only the ordered query is continuable — a page served unordered has no continuation to seek"
+ (let [[rows cols] (run-rows+cols (lib/query (mp) unordered))]
+ (is (nil? (q/next-page-cursor! sid uid unordered (last rows) {:result-cols cols}))))
+ (let [[rows cols] (run-rows+cols (lib/query (mp) ordered))]
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (is (some? (q/next-page-cursor! sid uid ordered (last rows) {:result-cols cols})))))))))
+
+(deftest next-page-cursor-bails-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [uid (mt/user->id :rasta)
+ sid (str (random-uuid))]
+ (testing "no cursor for a native query (keyset can't be built over opaque SQL — caller falls back to limit-only)"
+ (is (nil? (q/next-page-cursor! sid uid
+ {:database (mt/id) :stages [{:lib/type "mbql.stage/native" :native "SELECT 1"}]}
+ [1] {}))))
+ (testing "no cursor for an unusable query shape"
+ (is (nil? (q/next-page-cursor! sid uid {:stages []} [1] {})))
+ (is (nil? (q/next-page-cursor! sid uid {:database (mt/id)} [1] {})))
+ (is (nil? (q/next-page-cursor! sid uid "not-a-map" [1] {})))))))
+
+(defn- products-orders-fanout-query
+ "Products fanned out 1:many onto their Orders: the same source-table PK spans many result
+ rows, ordered by a non-unique column (TITLE) so page boundaries land inside a PK group.
+ The projection is restricted to keyset-safe columns — Products.ID, Products.TITLE, and the
+ joined Orders.ID, which is unique per result row and so serves as the completeness check."
+ []
+ (let [provider (mp)
+ orders (lib.metadata/table provider (mt/id :orders))
+ p-id (lib.metadata/field provider (mt/id :products :id))
+ p-title (lib.metadata/field provider (mt/id :products :title))
+ o-id (lib.metadata/field provider (mt/id :orders :id))
+ o-pid (lib.metadata/field provider (mt/id :orders :product_id))]
+ (-> (lib/query provider (lib.metadata/table provider (mt/id :products)))
+ (lib/join (-> (lib/join-clause orders [(lib/= p-id o-pid)])
+ (lib/with-join-fields [o-id])))
+ (lib/filter (lib/<= p-id 2))
+ (lib/order-by p-title :asc)
+ (lib/with-fields [p-id p-title]))))
+
+(deftest next-page-query-appended-stage-stays-continuable-test
+ ;; GHY-4363: the stage next-page-query appends for an aggregated page must stay a pass-through
+ ;; — no :fields, no joins — because the uniqueness proof for every later page looks back
+ ;; through it to the aggregating stage. A :fields on that stage could drop a breakout column
+ ;; and silently un-prove the tuple, so pin its shape here rather than only through the chain.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [aggregated (-> (orders-query)
+ (lib/aggregate (lib/count))
+ (lib/breakout (lib.metadata/field (mp) (mt/id :orders :user_id)))
+ lib/prepare-for-serialization
+ q/with-total-order)
+ page-of (fn [serialized] (run-rows+cols (lib/query (mp) serialized)))
+ [rows cols] (page-of aggregated)
+ page-2 (#'q/next-page-query aggregated cols (nth rows 2))]
+ (testing "GHY-4363: the appended stage carries the order and the keyset, and nothing that could drop a column"
+ (is (some? page-2))
+ (is (= 2 (count (:stages page-2))))
+ (let [appended (last (:stages page-2))]
+ (is (seq (:order-by appended)))
+ (is (seq (:filters appended)))
+ (is (nil? (:fields appended)) "a :fields here could drop a breakout column and un-prove the tuple")
+ (is (nil? (:joins appended)))))
+ (testing "GHY-4363: and the page it mints is itself continuable — the chain does not die at page 2"
+ (let [[rows-2 cols-2] (page-of page-2)]
+ (is (some? (#'q/next-page-query page-2 cols-2 (nth rows-2 2)))))))))
+
+(deftest next-page-cursor-fan-out-join-test
+ ;; The contract pinned here is "no silent gaps": whenever a cursor IS minted, following the
+ ;; chain must serve exactly the unpaged result set — and when that can't be guaranteed, the
+ ;; mechanism must mint nothing (the caller then sees a truncated page with no cursor: an
+ ;; explicit dead end, not a gap). Imposing the total order before execution — what makes an
+ ;; unjoined page continuable — doesn't rescue this one: the source-table PK repeats across
+ ;; result rows, so ordering by it still leaves ties, and the full-tuple fallback can't break
+ ;; them either since fanned-out rows can be wholly identical.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [query (products-orders-fanout-query)
+ o-id-of (fn [row] (nth row 2))
+ reference (let [[rows _] (run-rows+cols query)] (mapv o-id-of rows))
+ page-size 50
+ {:keys [paged refused?]}
+ (loop [q (q/with-total-order (lib/prepare-for-serialization (lib/limit query page-size)))
+ acc []
+ pages 1]
+ (let [[rows cols] (run-rows+cols (lib/query (mp) q))
+ acc' (into acc (map o-id-of) rows)]
+ (if (or (< (count rows) page-size) (> pages 10))
+ {:paged acc' :refused? false}
+ (if-let [nxt (#'q/next-page-query q cols (last rows))]
+ (recur (q/with-total-order nxt) acc' (inc pages))
+ {:paged acc' :refused? true}))))]
+ (testing "GHY-4142: paging a 1:many join must either serve every result row exactly once or mint no cursor at all"
+ (is (> (count reference) page-size)
+ "fixture must span multiple pages, or no boundary is exercised")
+ (is (= (count paged) (count (distinct paged)))
+ "no row served twice")
+ (when-not refused?
+ (is (= (count reference) (count paged))
+ "rows served across a completed cursor chain equal the unpaged run — a shortfall means a page boundary dropped fan-out rows")
+ (is (= [] (->> reference (remove (set paged)) sort vec))
+ "every unpaged row appears on some page — ids listed here were dropped at a boundary")))
+ (testing "GHY-4142: a fan-out page refuses the cursor — no order derivable from metadata is total when the PK repeats across rows"
+ (is (true? refused?)))
+ (testing "GHY-4142: and it is refused the imposed order too — sorting by a repeating PK buys nothing"
+ (let [joined (lib/prepare-for-serialization (lib/limit query page-size))]
+ (is (= joined (q/with-total-order joined))))))))
+
+(deftest next-page-cursor-sourced-card-fan-out-test
+ ;; The join that fans the result out need not be in the payload: a query sourcing a saved
+ ;; question inherits that question's joins, and the payload shows only `:source-card`. The
+ ;; refusal has to follow the source through, or the hole reopens one indirection away.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [joined (-> (lib/query (mp) (lib.metadata/table (mp) (mt/id :products)))
+ (lib/join (lib/join-clause (lib.metadata/table (mp) (mt/id :orders))
+ [(lib/= (lib.metadata/field (mp) (mt/id :products :id))
+ (lib.metadata/field (mp) (mt/id :orders :product_id)))])))
+ plain (lib/query (mp) (lib.metadata/table (mp) (mt/id :products)))]
+ (mt/with-temp [:model/Card {joined-id :id} {:dataset_query (lib/->legacy-MBQL joined)}
+ :model/Card {plain-id :id} {:dataset_query (lib/->legacy-MBQL plain)}]
+ (let [sourcing (fn [card-id]
+ (-> (lib/query (mp) (lib.metadata/card (mp) card-id))
+ (lib/limit 5)
+ lib/prepare-for-serialization))
+ page-of (fn [serialized] (run-rows+cols (lib/query (mp) serialized)))]
+ (testing "GHY-4142: sourcing a saved question that joins refuses the cursor, same as an inline join"
+ (let [serialized (sourcing joined-id)
+ [rows cols] (page-of serialized)]
+ (is (true? (#'q/fan-out-join? (mp) serialized)))
+ (is (nil? (#'q/next-page-query serialized cols (last rows))))))
+ ;; asserted on the guard rather than end-to-end: a card-sourced query has no projected
+ ;; source-table PK, so it falls to the full-tuple tiebreaker and bails for its own
+ ;; reasons (PRODUCTS.CREATED_AT doesn't round-trip). What matters here is that the
+ ;; fan-out refusal follows the source through instead of blanket-refusing every card.
+ (testing "GHY-4142: sourcing a join-free saved question is not a fan-out"
+ (is (false? (#'q/fan-out-join? (mp) (sourcing plain-id))))))))))
+
+(defn- page-chain
+ "Page `serialized` through [[next-page-query]] `n` times at `page-size` rows a page, returning the
+ serialized query for each page, starting with `serialized` itself. The boundary handed to
+ [[next-page-query]] is the last row of the served page, the way a truncated tool response
+ reports it — the run itself is not capped, so an aggregated stage stays free of the `:limit`
+ that would (rightly) refuse the cursor. Stops early if the result runs out or a page mints
+ nothing."
+ [serialized n page-size]
+ (loop [query serialized, acc [serialized]]
+ (if (>= (count acc) n)
+ acc
+ (let [[rows cols] (run-rows+cols (lib/query (mp) query))]
+ (if (< (count rows) page-size)
+ acc
+ (if-let [nxt (#'q/next-page-query query cols (nth rows (dec page-size)))]
+ (recur nxt (conj acc nxt))
+ acc))))))
+
+(defn- last-stage-filters [serialized]
+ (:filters (last (:stages serialized))))
+
+(deftest next-page-query-replaces-the-previous-keyset-test
+ ;; GHY-4363: each page's keyset predicate supersedes the last one — every row it admits is
+ ;; strictly past a boundary the previous predicate already admitted. Appending instead of
+ ;; replacing leaves a chain of dead predicates that grows linearly and without bound: the
+ ;; stored handle payload, the emitted WHERE, and the warehouse's parse/plan cost all grow with
+ ;; page depth, on a query whose meaning never changes.
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "GHY-4363: an unaggregated chain carries exactly one keyset predicate at every depth"
+ (let [pages (page-chain (q/with-total-order
+ (lib/prepare-for-serialization (lib/limit (orders-query) 2)))
+ 6 2)]
+ (is (= 6 (count pages)) "the chain must actually reach depth 6 for this to prove anything")
+ (is (= [0 1 1 1 1 1] (mapv (comp count last-stage-filters) pages)))))
+ (testing "GHY-4363: an aggregated chain carries exactly one on its appended stage too"
+ (let [aggregated (-> (orders-query)
+ (lib/aggregate (lib/count))
+ (lib/breakout (lib.metadata/field (mp) (mt/id :orders :user_id)))
+ lib/prepare-for-serialization
+ q/with-total-order)
+ pages (page-chain aggregated 5 3)]
+ (is (= 5 (count pages)))
+ (is (= [0 1 1 1 1] (mapv (comp count last-stage-filters) pages)))))))
+
+(deftest next-page-query-keeps-caller-filters-test
+ ;; GHY-4363: only the predicate this namespace minted may be superseded. A filter the caller
+ ;; wrote has to survive every page verbatim and keep being applied — dropping it would widen the
+ ;; result past what the caller asked for.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [total-col (lib.metadata/field (mp) (mt/id :orders :total))
+ caller (-> (orders-query)
+ (lib/filter (lib/> total-col 50))
+ (lib/limit 2)
+ lib/prepare-for-serialization
+ q/with-total-order)
+ caller-clause (first (last-stage-filters caller))
+ pages (page-chain caller 5 2)]
+ (is (= 5 (count pages)) "the chain must actually reach depth 5 for this to prove anything")
+ (testing "GHY-4363: the caller's filter stays, and only one keyset rides alongside it"
+ (is (= [1 2 2 2 2] (mapv (comp count last-stage-filters) pages)))
+ (doseq [page (rest pages)]
+ (is (some #(lib.equality/= caller-clause %) (last-stage-filters page))
+ "the caller's own clause must survive verbatim")))
+ (testing "GHY-4363: and it is still enforced — no page returns a row the caller excluded"
+ (doseq [page pages]
+ (let [[rows cols] (run-rows+cols (lib/query (mp) page))
+ idx (col-index cols "TOTAL")]
+ (is (seq rows))
+ (is (every? #(> (nth % idx) 50) rows))))))))
+
+(deftest next-page-cursor-pages-without-gaps-or-dups-test
+ ;; Proves the keyset seek is correct across page boundaries: for a unique-key (PK) source, paging
+ ;; returns strictly increasing, distinct PKs — no row skipped, none repeated. (The non-unique-key
+ ;; case, where the full-tuple tiebreaker can drop duplicate rows split across a boundary, is the
+ ;; known gap tracked as review finding #2.)
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [page-size 4
+ n-pages 4
+ ids (loop [query (q/with-total-order
+ (lib/prepare-for-serialization (lib/limit (orders-query) page-size)))
+ acc []
+ pages 0]
+ (let [[rows cols] (run-rows+cols (lib/query (mp) query))
+ id-idx (col-index cols "ID")
+ acc' (into acc (map #(nth % id-idx) rows))
+ pages' (inc pages)]
+ (if (or (>= pages' n-pages) (< (count rows) page-size))
+ acc'
+ (if-let [nxt (#'q/next-page-query query cols (last rows))]
+ (recur nxt acc' pages')
+ acc'))))]
+ (testing "keyset paging yields strictly increasing, distinct PKs across boundaries"
+ (is (= (* page-size n-pages) (count ids)))
+ (is (apply < ids) "strictly increasing => no boundary repeats and no rows skipped backwards")
+ (is (= (count ids) (count (distinct ids))))))))
+
+(deftest with-total-order-preserves-parameters-test
+ ;; GHY-4363: `:parameters` are a real filter on an MBQL query — the QP's parameter middleware ANDs
+ ;; them on — but `lib/prepare-for-serialization` strips them as runtime-only. Both rewrite paths
+ ;; round-trip through serialization, so both have to put them back or the rewritten query asks a
+ ;; wider question than the caller did.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [params [{:type :number/=
+ :value [2]
+ :target [:dimension [:field (mt/id :orders :quantity) nil]]}]
+ ;; deliberately unordered so `with-total-order` actually rewrites — the pre-existing
+ ;; coverage used an already-PK-ordered query, which only exercises the short-circuit
+ unordered (-> (orders-query)
+ (lib/limit 5)
+ lib/prepare-for-serialization
+ (assoc :parameters params))
+ ordered (q/with-total-order unordered)]
+ (is (not= (:stages unordered) (:stages ordered))
+ "the rewrite must actually fire, or this test proves nothing")
+ (testing "with-total-order keeps :parameters"
+ (is (= params (:parameters ordered))))
+ (testing "and the parameter is still enforced against the warehouse"
+ (let [[rows cols] (run-rows+cols (lib/query (mp) ordered))
+ idx (col-index cols "QUANTITY")]
+ (is (seq rows))
+ (is (every? #(= 2 (nth % idx)) rows)
+ "every row must satisfy the parameter filter the caller supplied")))
+ (testing "next-page-query keeps :parameters too, so the cursor stays as narrow as page 1"
+ (let [[rows cols] (run-rows+cols (lib/query (mp) ordered))]
+ (when-let [nxt (#'q/next-page-query ordered cols (last rows))]
+ (is (= params (:parameters nxt)))))))))
+
+(deftest caller-cannot-forge-the-keyset-marker-test
+ ;; GHY-4363: the keyset marker means "this namespace minted this predicate". A tool's `:query` is
+ ;; an open [:map] and a namespaced option key rides through JSON decode and serialization intact,
+ ;; so without stripping, a caller could stamp its own filter and have it silently dropped from the
+ ;; saved handle (and from every later page) while the visible first page still looked narrow.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [total-col (lib.metadata/field (mp) (mt/id :orders :total))
+ forged (-> (orders-query)
+ (lib/filter (-> (lib/> total-col 50)
+ (assoc-in [1 :metabase.mcp.v2.query/keyset] true)))
+ lib/prepare-for-serialization)
+ cleaned (q/strip-caller-keyset-markers forged)]
+ (testing "the forged marker survives serialization untouched (this is the hazard)"
+ (is (some #(get-in % [1 :metabase.mcp.v2.query/keyset])
+ (last-stage-filters forged))))
+ (testing "stripping removes it"
+ (is (not-any? #(get-in % [1 :metabase.mcp.v2.query/keyset])
+ (last-stage-filters cleaned))))
+ (testing "so the caller's filter now survives into the handle instead of vanishing"
+ (is (= 0 (count (last-stage-filters (q/without-page-boundary forged))))
+ "unstripped: without-page-boundary eats the caller's own filter")
+ (is (= 1 (count (last-stage-filters (q/without-page-boundary cleaned))))
+ "stripped: the caller's filter is part of the question and stays")))))
+
+(deftest no-cursor-for-a-nullable-key-column-test
+ ;; GHY-4363: a keyset predicate is all comparisons, and under three-valued logic every term is
+ ;; NULL — never true — for a row whose key column is NULL. Those rows are never served, and the
+ ;; response still says truncated:false. ORDERS.DISCOUNT is NULL for 16845 of 18760 rows, so a
+ ;; DISCOUNT-keyed cursor would silently serve about a tenth of the table and call it complete.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [disc (lib.metadata/field (mp) (mt/id :orders :discount))
+ nullable (-> (orders-query)
+ (lib/order-by disc :desc)
+ lib/prepare-for-serialization
+ q/with-total-order)
+ [rows cols] (run-rows+cols (lib/query (mp) (lib/limit (lib/query (mp) nullable) 5)))]
+ (testing "a nullable key column gets no cursor at all, rather than one with silent gaps"
+ (is (nil? (#'q/next-page-query nullable cols (last rows)))))
+ (testing "while a NOT NULL key (the PK) still pages normally"
+ (let [pk-q (q/with-total-order (lib/prepare-for-serialization (orders-query)))
+ [pk-rows pk-cols] (run-rows+cols (lib/query (mp) (lib/limit (lib/query (mp) pk-q) 5)))]
+ (is (some? (#'q/next-page-query pk-q pk-cols (last pk-rows)))))))))
diff --git a/test/metabase/mcp/v2/redaction_test.clj b/test/metabase/mcp/v2/redaction_test.clj
new file mode 100644
index 00000000000..7d05546c8b1
--- /dev/null
+++ b/test/metabase/mcp/v2/redaction_test.clj
@@ -0,0 +1,287 @@
+(ns metabase.mcp.v2.redaction-test
+ "Unit tests for the recipient filters [[metabase.mcp.v2.redaction/redact-notification]]
+ applies. The wiring — that each tool actually calls it before projecting — is pinned by the
+ `get_content` tests in `metabase.mcp.v2.tools.content-test`; these pin the rules themselves.
+ The sandboxed-caller filter lives in `metabase-enterprise.mcp.v2.redaction-sandbox-test`, since
+ in OSS `sandboxed-or-impersonated-user?` is always false."
+ (:require
+ [clojure.test :refer [deftest is testing]]
+ [metabase.api.common :as api]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.redaction :as redaction]
+ [metabase.models.interface :as mi]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private same-tenant-recipient
+ "A user recipient in the caller's tenant — the predefined test users all have a nil `tenant_id`."
+ {:type :notification-recipient/user :user_id 100 :user {:id 100 :tenant_id nil}})
+
+(def ^:private cross-tenant-recipient
+ {:type :notification-recipient/user :user_id 200 :user {:id 200 :tenant_id 42}})
+
+(def ^:private email-recipient
+ "A raw email address: no `user_id`, so no tenant to compare against."
+ {:type :notification-recipient/raw-value :details {:value "[email protected]"}})
+
+(defn- deactivated-recipient
+ "A user recipient the `:recipients-detail` hydration could not attach a `:user` to — the shape it
+ produces for a deactivated user, whose tenant must be looked up from the app DB."
+ [user-id]
+ {:type :notification-recipient/user :user_id user-id})
+
+(defn- testing-notification
+ "A hydrated-shaped notification carrying `handlers`. `:notification/testing` is outside the set
+ `redact-notification` strips, so the payload-unreadable branch stays out of the way with no
+ collection fixture at all and the per-recipient filters are the only thing that runs."
+ [handlers]
+ {:id 2 :payload_type :notification/testing :handlers handlers})
+
+(defn- card-notification
+ "A hydrated-shaped alert on `card-id` with one email handler carrying `recipients`. `:payload` is
+ the shape the `:payload` batched hydration really produces for `:notification/card`, the only
+ payload type it has a branch for. The tests bind a user who can read the card, so the
+ payload-unreadable strip stays out of the way and the per-recipient filters are what's under
+ test; the strip branch is driven on persisted rows below."
+ [card-id recipients]
+ {:id 1
+ :payload_type :notification/card
+ :payload {:card_id card-id}
+ :handlers [{:id 10 :channel_type :channel/email :recipients recipients}]})
+
+(defn- as-tenant-caller
+ "Run `thunk` with the current user belonging to tenant `tenant-id`. The predefined test users are all
+ tenantless, and the tenant filter only engages for a caller who has one."
+ [tenant-id thunk]
+ (let [me @api/*current-user*]
+ (binding [api/*current-user* (delay (assoc me :tenant_id tenant-id))]
+ (thunk))))
+
+(defn- visible-user-ids
+ [notification]
+ (->> (redaction/redact-notification notification)
+ :handlers
+ first
+ :recipients
+ (mapv :user_id)))
+
+(deftest redact-notification-hides-cross-tenant-recipients-test
+ (testing "GHY-4219: a caller who belongs to a tenant sees only that tenant's user recipients, while raw
+ email recipients — which have no tenant — always survive. Same rule as /api/pulse."
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [notification (card-notification card-id
+ [same-tenant-recipient
+ cross-tenant-recipient
+ email-recipient])]
+ (mt/with-test-user :rasta
+ (testing "a tenantless caller sees every recipient, as before tenants existed"
+ (is (= [100 200 nil] (visible-user-ids notification))))
+ (testing "a tenant caller sees only its own tenant"
+ (as-tenant-caller 42 #(is (= [200 nil] (visible-user-ids notification))))))
+ (testing "a superuser sees every recipient"
+ (mt/with-test-user :crowberto
+ (is (= [100 200 nil] (visible-user-ids notification)))))))))
+
+(deftest deactivated-recipient-tenant-is-looked-up-test
+ ;; Tenants are enterprise-only: :model/Tenant is not on the OSS classpath, so guard the body out
+ ;; of OSS builds entirely (with-premium-features only flips the flag, it does not load EE code).
+ (mt/when-ee-evailable
+ (testing "GHY-4219: the `:recipients-detail` hydration attaches `:user` nil for a deactivated
+ user, so its tenant is looked up from the app DB rather than read off the recipient
+ map — otherwise a deactivated recipient reads as tenantless and slips past (or is
+ wrongly dropped by) the tenant filter."
+ (mt/with-premium-features #{:tenants}
+ (mt/with-temp [:model/Tenant {tenant-id :id} {:name "MCP redaction T1" :slug "mcp-redaction-t1"}
+ :model/Tenant {other-tenant-id :id} {:name "MCP redaction T2" :slug "mcp-redaction-t2"}
+ :model/User {caller-id :id} {:tenant_id tenant-id}
+ :model/User {same-id :id} {:tenant_id tenant-id :is_active false}
+ :model/User {other-id :id} {:tenant_id other-tenant-id :is_active false}]
+ (let [notification (testing-notification
+ [{:id 10 :channel_type :channel/email
+ :recipients [(deactivated-recipient same-id)
+ (deactivated-recipient other-id)
+ email-recipient]}])]
+ (mt/with-current-user caller-id
+ (testing "a tenant caller keeps the same-tenant deactivated recipient and drops the other"
+ (is (= [same-id nil] (visible-user-ids notification)))))
+ (testing "a tenantless caller sees every recipient, as before tenants existed"
+ (mt/with-test-user :rasta
+ (is (= [same-id other-id nil] (visible-user-ids notification)))))))))))
+
+(defn- email-handler
+ [handler-id recipients]
+ {:id handler-id :channel_type :channel/email :recipients recipients})
+
+(defn- deactivated-recipients
+ [user-ids]
+ (mapv deactivated-recipient user-ids))
+
+(defn- redaction-query-count
+ "Queries `redact-notification` runs over a notification made of `handlers`."
+ [handlers]
+ (t2/with-call-count [call-count]
+ (redaction/redact-notification (testing-notification handlers))
+ (call-count)))
+
+(deftest tenant-filter-batches-recipient-lookups-test
+ (testing "GHY-4219: resolving the tenants of recipients with no hydrated `:user` costs one query
+ for the whole notification, however many handlers and recipients hang off it — looking
+ each recipient up inside the filter is an N+1. Counted against a same-shaped
+ notification of raw email recipients, which needs no lookup, so the per-handler cost of
+ the sandbox check drops out. `:notification/testing` keeps the payload-readable check
+ out of the window entirely. The recipient ids need not resolve to real users: only the
+ shape of the lookup is under test."
+ (mt/with-test-user :rasta
+ (as-tenant-caller
+ 42
+ (fn []
+ ;; The first redaction pays one-off caching the sandbox check does; leave it out of the
+ ;; measured counts.
+ (redaction-query-count [(email-handler 10 [email-recipient])])
+ (testing "one handler: one query however many recipients need looking up"
+ (is (= (inc (redaction-query-count [(email-handler 10 [email-recipient])]))
+ (redaction-query-count [(email-handler 10 (deactivated-recipients [1 2 3 4 5 6]))]))))
+ (testing "handlers share the one lookup rather than each running their own"
+ (is (= (inc (redaction-query-count [(email-handler 10 [email-recipient])
+ (email-handler 11 [email-recipient])]))
+ (redaction-query-count [(email-handler 10 (deactivated-recipients [1 2 3]))
+ (email-handler 11 (deactivated-recipients [4 5 6]))]))))))
+ (testing "a tenantless caller does not run the tenant filter, so it needs no lookup at all"
+ (is (= (redaction-query-count [(email-handler 10 [email-recipient])])
+ (redaction-query-count [(email-handler 10 (deactivated-recipients [1 2 3 4 5 6]))])))))))
+
+(defn- handlers-with-recipients
+ "The hydrated-and-redacted handlers of the persisted notification `notification-id`, as the
+ current user sees them."
+ [notification-id]
+ (-> (t2/select-one :model/Notification notification-id)
+ redaction/hydrate-and-redact-notification
+ :handlers))
+
+(deftest unreadable-payload-strips-recipient-lists-test
+ (testing "a caller who reaches an alert only as its creator — not through its card — loses the
+ recipient lists entirely. Driven on a persisted row through
+ `hydrate-and-redact-notification`, since the strip hinges on what hydration actually
+ attaches to the row."
+ ;; A new collection inherits its parent's grants, and the test fixtures give All Users root
+ ;; perms — revoke those so the collection (and so the card) is unreadable to rasta.
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {collection-id :id} {}
+ :model/Card {card-id :id} {:collection_id collection-id}
+ :model/NotificationCard {payload-id :id} {:card_id card-id}
+ :model/Notification {notif-id :id} {:payload_type :notification/card
+ :payload_id payload-id
+ :creator_id (mt/user->id :rasta)}
+ :model/NotificationHandler {handler-id :id} {:notification_id notif-id
+ :channel_type :channel/email}
+ :model/NotificationRecipient _ {:notification_handler_id handler-id
+ :type :notification-recipient/user
+ :user_id (mt/user->id :lucky)}]
+ (mt/with-test-user :rasta
+ (is (not-any? #(contains? % :recipients) (handlers-with-recipients notif-id))))
+ (testing "a reader of the card keeps the (filtered) lists"
+ (mt/with-test-user :crowberto
+ (is (every? #(contains? % :recipients) (handlers-with-recipients notif-id)))))))))
+
+(defn- migrate-to-dashboard-notification!
+ "Repoint the payload-less notification `notification-id` to `:notification/dashboard` with raw
+ SQL. The model lifecycle has no branch for the type — the insert schema rejects it and
+ `create-notification!` cannot build one — so a migration is the only way such a row comes to
+ exist, and raw SQL is the only way to stand one up here."
+ [notification-id]
+ (t2/query-one {:update :notification
+ :set {:payload_type "notification/dashboard"}
+ :where [:= :id notification-id]}))
+
+(deftest dashboard-notification-recipient-lists-test
+ (testing "a migrated dashboard subscription carries no payload at all — no payload table stands
+ behind `:payload_id` and the `:payload` hydration has no branch for the type — so the
+ recipient lists survive only for a superuser, who can read every dashboard. Reading
+ the id off a `:payload` map hydration never populates stripped them for everybody."
+ (mt/with-temp [:model/Notification {notif-id :id} {:payload_type :notification/card
+ :creator_id (mt/user->id :rasta)}
+ :model/NotificationHandler {handler-id :id} {:notification_id notif-id
+ :channel_type :channel/email}
+ :model/NotificationRecipient _ {:notification_handler_id handler-id
+ :type :notification-recipient/user
+ :user_id (mt/user->id :lucky)}]
+ (migrate-to-dashboard-notification! notif-id)
+ (mt/with-test-user :crowberto
+ (is (every? #(contains? % :recipients) (handlers-with-recipients notif-id))))
+ (testing "a non-superuser — here the creator, who can read the notification itself — is stripped"
+ (mt/with-test-user :rasta
+ (is (not-any? #(contains? % :recipients) (handlers-with-recipients notif-id))))))))
+
+(deftest filtered-to-empty-is-not-the-same-as-stripped-test
+ (testing "GHY-4219: a handler whose recipients are all filtered away keeps the key with an empty
+ list, while the payload-unreadable strip removes the key entirely. The projection
+ reports the two differently, so a caller can tell \"nobody you may see\" from
+ \"withheld\" — this pins that the split of redaction out of the projection preserves
+ the distinction."
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (mt/with-test-user :rasta
+ (testing "filtered to empty projects as an empty list"
+ ;; A tenant caller, so the cross-tenant recipient is filtered rather than shown.
+ (as-tenant-caller 99
+ (fn []
+ (let [handler (-> (card-notification card-id [cross-tenant-recipient])
+ redaction/redact-notification
+ projections/notification-row
+ :handlers
+ first)]
+ (is (contains? handler :recipients))
+ (is (= [] (:recipients handler)))))))
+ (testing "stripped projects without the key at all"
+ (let [handler (-> (card-notification card-id [same-tenant-recipient])
+ ;; What `redact-notification` does when the caller cannot read the
+ ;; payload; done by hand here so the assertion needs no extra fixture.
+ (update :handlers (partial mapv #(dissoc % :recipients)))
+ projections/notification-row
+ :handlers
+ first)]
+ (is (not (contains? handler :recipients)))))))))
+
+(deftest unreadable-dashcard-loses-its-card-describing-settings-test
+ (testing "reducing an unreadable dashcard's `:card` to nothing is not the whole redaction: the
+ `layout` include reads `:visualization_settings` and `:parameter_mappings` off the same
+ dashcard, and those are stored snapshots describing the card — its author-written title,
+ the warehouse columns it renders, and the field ids its filters are wired to. A caller
+ who was just denied the card must not receive them by another route."
+ (let [dashcard {:id 1
+ :card_id 12
+ :row 0
+ :col 0
+ :size_x 4
+ :size_y 4
+ :card {:id 12 :name "Executive Payroll"}
+ :visualization_settings {:card.title "Executive Payroll by Employee"
+ :column_settings {"[\"name\",\"base_salary\"]"
+ {:column_title "Salary"}}
+ :click_behavior {:targetId 999}
+ :dashcard.background true}
+ :parameter_mappings [{:card_id 12 :target [:dimension [:field 999 nil]]}]}
+ redact (fn [readable?]
+ (with-redefs [mi/can-read? (constantly readable?)]
+ (first (:dashcards (redaction/redact-dashboard {:dashcards [dashcard]})))))]
+ (testing "unreadable: nothing naming the card survives"
+ (let [dc (redact false)]
+ (is (nil? (:card dc)))
+ (is (nil? (get-in dc [:visualization_settings :card.title]))
+ "the title is the card's name by another name")
+ (is (nil? (get-in dc [:visualization_settings :column_settings]))
+ "column settings name warehouse columns the caller may hold no permission on")
+ (is (nil? (get-in dc [:visualization_settings :click_behavior]))
+ "click targets name other entities")
+ (is (= [] (:parameter_mappings dc))
+ (str "parameter mappings carry the field ids the card's filters are wired to. Emptied "
+ "rather than removed: the key is required on a DashboardCard, and the parameters "
+ "summary runs `dashboard->resolved-params` over this same row"))
+ (testing "the grid slot itself is dashboard data, not card data, and survives"
+ (is (= 4 (:size_x dc)))
+ (is (true? (get-in dc [:visualization_settings :dashcard.background]))))))
+ (testing "readable: nothing is stripped"
+ (let [dc (redact true)]
+ (is (= "Executive Payroll by Employee" (get-in dc [:visualization_settings :card.title])))
+ (is (some? (:parameter_mappings dc))))))))
diff --git a/test/metabase/mcp/v2/registry_test.clj b/test/metabase/mcp/v2/registry_test.clj
new file mode 100644
index 00000000000..9c5bd4bcf5c
--- /dev/null
+++ b/test/metabase/mcp/v2/registry_test.clj
@@ -0,0 +1,372 @@
+(ns metabase.mcp.v2.registry-test
+ (:require
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.api.macros.scope :as scope]
+ [metabase.mcp.settings :as mcp.settings]
+ [metabase.mcp.usage :as mcp.usage]
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.test-util :as v2.tu]
+ [metabase.test :as mt]))
+
+(set! *warn-on-reflection* true)
+
+;; not ^:parallel: the kondo deftest lint treats the `!` suffix of `register-tool!` as destructive
+(deftest registration-requires-scope-test
+ (testing "a tool definition without a :scope fails loudly at registration"
+ (is (thrown-with-msg? Exception #":scope"
+ (registry/register-tool! {:name "no_scope"
+ :description "x"
+ :args [:map]
+ :handler (fn [_ _] nil)}))))
+ (testing "a set-valued :scope is rejected too — `:scope` is a single string, even though `mcp.scope/matches?`
+ would honor a set, because `registered-scopes` would otherwise collect the set itself rather than
+ its members"
+ (is (thrown-with-msg? Exception #"registered without a :scope string"
+ (registry/register-tool! {:name "set_scope_probe"
+ :scope #{"agent:content:read" "agent:query:run"}
+ :description "probe: never registers"
+ :args [:map]
+ :handler (fn [_ _] nil)})))))
+
+(deftest ^:parallel list-tools-scope-filtering-test
+ (testing "tools/list filters on token scopes"
+ (is (some #(= "test_echo" (:name %)) (registry/list-tools #{"agent:content:read"})))
+ (is (not (some #(= "test_echo" (:name %)) (registry/list-tools #{"agent:metadata:read"})))))
+ (testing "the unrestricted sentinel (cookie sessions) sees every tool"
+ (is (some #(= "test_echo" (:name %)) (registry/list-tools #{::scope/unrestricted})))))
+
+(deftest ^:parallel call-tool-scope-check-test
+ (testing "tools/call re-checks scope even for a tool that exists"
+ (let [{:keys [error]} (registry/call-tool #{"agent:metadata:read"} nil "test_echo" {})]
+ (is (= common/error-code-invalid-request (:code error)))
+ (is (= (str "Insufficient scope to call tool: test_echo. Requires "
+ (:scope (get @@#'registry/tools* "test_echo"))
+ "; your token holds agent:metadata:read.")
+ (:message error))))))
+
+(deftest ^:parallel call-tool-success-test
+ (testing "a valid call dispatches to the handler; top-level nils are stripped first"
+ (let [{:keys [result]} (registry/call-tool #{"agent:content:read"} nil "test_echo" {:message nil})]
+ (is (not (:isError result)))
+ (is (= {:ok true :message "pong"} (:structuredContent result)))
+ (testing "the internal error-code marker never reaches the client"
+ (is (not (contains? result ::common/error-code)))))))
+
+(deftest ^:parallel call-tool-validation-test
+ (testing "malli validation failures surface as JSON-RPC invalid-params errors"
+ (let [{:keys [error]} (registry/call-tool nil nil "test_echo" {:message 42})]
+ (is (= common/error-code-invalid-params (:code error)))
+ (is (str/starts-with? (:message error) "Invalid arguments"))))
+ (testing "non-object arguments are invalid params, not an internal error"
+ (let [{:keys [error]} (registry/call-tool nil nil "test_echo" [1 2 3])]
+ (is (= {:code common/error-code-invalid-params
+ :message "Invalid arguments: expected a JSON object."}
+ error)))))
+
+(deftest ^:parallel call-tool-teaching-error-test
+ (testing "a handler's teaching error surfaces its message, not a stack trace"
+ (mt/with-dynamic-fn-redefs [v2.tu/test-echo (fn [_ _]
+ (common/throw-teaching-error "Use `fields` OR `response_format`, not both."))]
+ (let [{:keys [result]} (registry/call-tool nil nil "test_echo" {})]
+ (is (:isError result))
+ (is (= "Use `fields` OR `response_format`, not both." (-> result :content first :text)))))))
+
+(deftest ^:parallel call-tool-redacts-internal-errors-test
+ (testing "GHY-4137: a handler's unexpected failure — a raw exception whose message may embed
+ SQL, schema, or connection detail — is redacted to a generic internal error, never
+ returned to the (possibly scope-limited) client"
+ (doseq [[label thrown] [["raw runtime exception" (RuntimeException. "jdbc://user:[email protected] failed")]
+ ["JDBC SQLException" (java.sql.SQLException. "relation \"secret_accounts\" does not exist")]
+ ["ex-info with no status" (ex-info "SELECT ssn FROM secret_accounts" {:query {}})]]]
+ (testing label
+ (mt/with-dynamic-fn-redefs [v2.tu/test-echo (fn [_ _] (throw thrown))]
+ (let [{:keys [result]} (registry/call-tool #{"agent:content:read"} nil "test_echo" {})]
+ (is (:isError result))
+ (is (= "Internal error" (-> result :content first :text))
+ "the raw exception message must not reach the client")))))))
+
+(deftest disabled-tools-test
+ (mt/with-temporary-setting-values [mcp.settings/mcp-v2-disabled-tools ["test_echo"]]
+ (testing "a disabled tool is hidden from tools/list"
+ (is (not (some #(= "test_echo" (:name %)) (registry/list-tools nil)))))
+ (testing "and rejected by tools/call as unknown"
+ (let [{:keys [error]} (registry/call-tool nil nil "test_echo" {})]
+ (is (= {:code common/error-code-method-not-found
+ :message "Unknown tool: test_echo"}
+ error))))))
+
+(deftest ^:parallel registered-scopes-test
+ (testing "registered-scopes reports the scopes of the landed tools. (It does not feed the DCR grant: that reads
+ `mcp.paths/v2-surface-scopes`, and a tool whose :scope is outside that set is unreachable over OAuth
+ — which the containment below guards.)"
+ (is (set/subset? #{"agent:content:read"} (set (registry/registered-scopes)))))
+ ;; GHY-4225 retired :required-scopes from v2: duplicate_content's per-type create scopes all
+ ;; collapsed into the single `agent:content:write` it already gates on, so there is no longer a
+ ;; mandatory-but-separate scope to keep in the default grant.
+ ;; While the surface is being rebuilt one tool per PR, only the scopes of the landed tools are
+ ;; registered — so assert the containment in the direction that already holds: no tool sneaks in a
+ ;; scope outside the rationalized five. The other direction ("all five reach the default grant")
+ ;; comes back when the tool set reaches parity, at v1 retirement.
+ (testing "every registered scope is one of the five rationalized scopes"
+ (is (set/subset? (set (registry/registered-scopes))
+ #{"agent:content:read" "agent:content:write" "agent:query:run"
+ "agent:sql:run" "agent:delivery:write"}))))
+
+(deftest ^:parallel tools-hash-test
+ (testing "tools-hash is a stable 8-char hex string that reflects scope-visible tools"
+ (is (re-matches #"[0-9a-f]{8}" (registry/tools-hash nil)))
+ (is (= (registry/tools-hash nil) (registry/tools-hash nil)))
+ (is (not= (registry/tools-hash nil) (registry/tools-hash #{"agent:metadata:read"})))))
+
+(defn- capture-usage-records!
+ "Run `thunk` with `record-mcp-tool-call!` redefed to capture its arg maps into a vector,
+ which is returned. Lets the usage-logging contract be asserted without the EE DB writer."
+ [thunk]
+ (let [records (atom [])]
+ (mt/with-dynamic-fn-redefs [mcp.usage/record-mcp-tool-call! (fn [m] (swap! records conj m))]
+ (thunk))
+ @records))
+
+;; not ^:parallel: exercises shared registry/tool state alongside the usage redef
+(deftest usage-logging-contract-test
+ (testing "every tools/call outcome writes exactly one usage record with the right status/error-code"
+ (testing "success → status \"success\", no error"
+ (let [records (capture-usage-records! #(registry/call-tool #{"agent:content:read"} nil "test_echo" {}))]
+ (is (= 1 (count records)))
+ (let [r (first records)]
+ (is (= "test_echo" (:tool-name r)))
+ (is (= "success" (:status r)))
+ (is (nil? (:error-code r)))
+ (is (nil? (:error-message r))))))
+ (testing "scope denied → status \"error\", invalid-request code"
+ (let [records (capture-usage-records! #(registry/call-tool #{"agent:metadata:read"} nil "test_echo" {}))]
+ (is (= 1 (count records)))
+ (let [r (first records)]
+ (is (= "test_echo" (:tool-name r)))
+ (is (= "error" (:status r)))
+ (is (= common/error-code-invalid-request (:error-code r)))
+ (is (str/starts-with? (:error-message r) "Insufficient scope to call tool: test_echo.")))))
+ (testing "unknown tool → status \"error\", method-not-found code"
+ (let [records (capture-usage-records! #(registry/call-tool nil nil "does_not_exist" {}))]
+ (is (= 1 (count records)))
+ (let [r (first records)]
+ (is (= "does_not_exist" (:tool-name r)))
+ (is (= "error" (:status r)))
+ (is (= common/error-code-method-not-found (:error-code r)))
+ (is (= "Unknown tool: does_not_exist" (:error-message r))))))
+ (testing "validation failure → status \"error\", invalid-params code"
+ (let [records (capture-usage-records! #(registry/call-tool #{"agent:content:read"} nil "test_echo" {:message 42}))]
+ (is (= 1 (count records)))
+ (let [r (first records)]
+ (is (= "test_echo" (:tool-name r)))
+ (is (= "error" (:status r)))
+ (is (= common/error-code-invalid-params (:error-code r)))
+ (is (some? (:error-message r))))))))
+
+;; not ^:parallel: re-registers a tool in the shared registry
+(deftest registration-survives-a-namespace-reload-test
+ (testing "the same-name guard compares the handler var's fully-qualified symbol, not the var object: a
+ tools.namespace reload re-interns the same symbol (accepted), while a same-named var from a
+ different namespace is a genuinely different handler (refused)"
+ (let [existing (get @@#'registry/tools* "test_echo")
+ handler (:handler existing)
+ ;; What a namespace reload leaves behind: a different var object carrying the same
+ ;; fully-qualified name. Built in a throwaway namespace so the live handler is untouched.
+ reload-ns (create-ns (gensym "mcp-reload-probe"))
+ reloaded (intern reload-ns (:name (meta handler)) @handler)]
+ (try
+ (is (not (identical? reloaded handler)) "the probe must really be a different var")
+ (is (= (:name (meta handler)) (:name (meta reloaded))))
+ (is (thrown-with-msg? Exception #"already registered"
+ (registry/register-tool! (assoc existing :handler reloaded)))
+ "a same-NAMED var from another namespace is still a different handler and is refused")
+ (is (= "test_echo" (registry/register-tool! existing))
+ "and the genuine handler var re-registers cleanly")
+ (finally
+ (remove-ns (ns-name reload-ns))
+ (registry/register-tool! (assoc existing :handler handler)))))))
+
+;; not ^:parallel: exercises register-tool!'s load-time guards
+(deftest registration-validates-extensions-test
+ (testing "an unknown option key fails loudly — a misspelled :required-extensions would silently disable the gate"
+ (is (thrown-with-msg? Exception #"unknown option"
+ (registry/register-tool! {:name "typo_key"
+ :scope "agent:content:read"
+ :description "x"
+ :args [:map]
+ :handler (fn [_ _] nil)
+ :require-extensions #{:mcp-app-ui}}))))
+ (testing ":required-extensions must be a set of keywords"
+ (is (thrown-with-msg? Exception #"set of keywords"
+ (registry/register-tool! {:name "bad_extensions"
+ :scope "agent:content:read"
+ :description "x"
+ :args [:map]
+ :handler (fn [_ _] nil)
+ :required-extensions ["mcp-app-ui"]}))))
+ (testing "a required extension no client can advertise fails loudly — it would hide the tool from everyone"
+ (is (thrown-with-msg? Exception #"unknown client extension"
+ (registry/register-tool! {:name "unknown_extension"
+ :scope "agent:content:read"
+ :description "x"
+ :args [:map]
+ :handler (fn [_ _] nil)
+ :required-extensions #{:mcp-app-holodeck}})))))
+
+;; not ^:parallel: re-registers a tool in the shared registry
+(deftest registration-rejects-a-name-claimed-by-another-handler-test
+ (testing "a second definition claiming a registered name fails loudly, so load order cannot decide which
+ handler `tools/call` reaches; the registered handler itself re-registers cleanly"
+ (let [existing (get @@#'registry/tools* "test_echo")]
+ (is (some? existing) "test_echo must be registered for this to prove anything")
+ (is (thrown-with-msg? Exception #"already registered"
+ (registry/register-tool! (assoc existing :handler (fn [_ _] nil)))))
+ (is (= "test_echo" (registry/register-tool! existing))))))
+
+;; not ^:parallel: exercises register-tool!'s load-time guards
+(deftest registration-validates-required-fields-test
+ (testing "a blank :name fails loudly"
+ (is (thrown-with-msg? Exception #":name"
+ (registry/register-tool! {:name ""
+ :scope "agent:content:read"
+ :description "x"
+ :args [:map]
+ :handler (fn [_ _] nil)}))))
+ (testing "a missing :description fails loudly"
+ (is (thrown-with-msg? Exception #"without a :description"
+ (registry/register-tool! {:name "no_desc"
+ :scope "agent:content:read"
+ :args [:map]
+ :handler (fn [_ _] nil)}))))
+ (testing "a missing :args schema fails loudly"
+ (is (thrown-with-msg? Exception #":args Malli schema"
+ (registry/register-tool! {:name "no_args"
+ :scope "agent:content:read"
+ :description "x"
+ :handler (fn [_ _] nil)}))))
+ (testing "a non-fn :handler fails loudly"
+ (is (thrown-with-msg? Exception #":handler fn"
+ (registry/register-tool! {:name "bad_handler"
+ :scope "agent:content:read"
+ :description "x"
+ :args [:map]
+ :handler "not-a-fn"}))))
+ (testing "an optional non-nullable field fails the strict-tool nullability check"
+ (is (thrown-with-msg? Exception #"optional non-nullable field"
+ (registry/register-tool! {:name "bad_schema"
+ :scope "agent:content:read"
+ :description "x"
+ :args [:map [:x {:optional true} :string]]
+ :handler (fn [_ _] nil)})))))
+
+;;; ------------------------------------- Write-tool scope invariants ----------------------------------------
+
+(def ^:private write-scopes
+ "The scopes a mutating tool may gate on. GHY-4225 collapsed the per-entity write scopes into
+ `content:write` and `delivery:write`, so a mutating tool gating on anything else is a mistake
+ until someone argues otherwise here.
+
+ `sql:run` is the one such argument. `execute_sql` runs arbitrary SQL, which can write — but it is
+ a sharper capability than editing content, and one a user should be able to withhold while still
+ granting writes, so it keeps its own scope rather than folding into `content:write`."
+ #{"agent:content:write" "agent:delivery:write" "agent:sql:run"})
+
+(defn- do-with-temp-tool!
+ "Register a throwaway tool for the body, then restore the registry and flush the manifest cache."
+ [tool thunk]
+ (let [tools-atom @#'registry/tools*
+ snapshot @tools-atom]
+ (try
+ (registry/register-tool! tool)
+ (thunk)
+ (finally
+ (reset! tools-atom snapshot)
+ (reset! @#'registry/manifest-cache nil)))))
+
+(defn- mutating-tools
+ "Registered tools that declare they mutate, as `{name tool}`. Enumerated from the registry rather
+ than a hand-kept list, so a write tool landing tomorrow is covered the day it registers.
+
+ Read from the MANIFEST, not from the raw registry entries: `:annotations` are defaulted at manifest
+ time, so the raw entry for a tool that declared none carries no `:readOnlyHint` at all while clients
+ are told `false`. See [[mutating-tools-sees-what-clients-see-test]]."
+ []
+ (into {}
+ (comp (filter #(false? (get-in % [:annotations :readOnlyHint])))
+ (map (juxt :name identity)))
+ (@#'registry/manifest)))
+
+;; not ^:parallel: registers a throwaway tool
+(deftest mutating-tools-sees-what-clients-see-test
+ (testing "GHY-4337: the three invariants below are only as good as this enumeration, and `default-annotations`
+ supplies `:readOnlyHint false` at MANIFEST time rather than at registration. So a tool that declares
+ no `:annotations` is published to clients as mutating while its raw registry entry carries no
+ `:readOnlyHint` at all — and enumerating from the raw entry would skip exactly the tool these
+ invariants exist to catch: one that mutates, says nothing about it, and rides a read scope."
+ (do-with-temp-tool!
+ {:name "annotation_free_mutator"
+ :scope "agent:content:read"
+ :description "test-only tool that declares no annotations at all"
+ :args [:map]
+ :handler (fn [_ _] nil)}
+ (fn []
+ (testing "clients are told it mutates"
+ (is (false? (->> (registry/list-tools nil)
+ (filter #(= "annotation_free_mutator" (:name %)))
+ first
+ :annotations
+ :readOnlyHint))))
+ (testing "so the enumeration the invariants run over must see it too"
+ (is (contains? (set (keys (mutating-tools))) "annotation_free_mutator")))
+ (testing "and it carries the :scope the invariants check, so they can actually run on it"
+ (is (= "agent:content:read" (:scope (get (mutating-tools) "annotation_free_mutator")))))))))
+
+(deftest write-tools-are-annotated-as-mutating-test
+ (testing "a tool named `*_write` declares `:readOnlyHint false`. This guards the enumeration the
+ two tests below depend on: a write tool that omitted the annotation would drop out of
+ [[mutating-tools]] and silently lose its scope coverage rather than failing."
+ (let [tools @@#'registry/tools*
+ mutating (set (keys (mutating-tools)))
+ by-name (filter #(str/ends-with? % "_write") (keys tools))]
+ ;; `when` rather than a hard `(is (seq by-name))` while the surface is rebuilt one tool per
+ ;; PR: no write tool has landed yet, so vacuous is truthful. The guard regains teeth the day
+ ;; the first `*_write` tool registers; restore the hard assertion at v1 retirement.
+ (when (seq by-name)
+ (doseq [tool-name (sort by-name)]
+ (testing tool-name
+ (is (contains? mutating tool-name))))))))
+
+(deftest mutating-tools-gate-on-a-write-scope-test
+ (testing "every mutating tool gates on one of the write scopes, so a token can be granted read
+ access without also being able to change anything"
+ ;; `when`-guarded during the tool-by-tool rebuild — see write-tools-are-annotated-as-mutating-test.
+ (let [tools (mutating-tools)]
+ (when (seq tools)
+ (doseq [[tool-name tool] (sort-by key tools)]
+ (testing tool-name
+ (is (contains? write-scopes (:scope tool)))))))))
+
+(deftest mutating-tools-refuse-a-read-only-token-test
+ (testing "the declared scope is actually enforced: a token holding only `agent:content:read`
+ cannot call any mutating tool. Asserted per tool rather than once on a placeholder,
+ because the gate is only as good as each tool's own `:scope`, and checked at call time
+ because being hidden from `tools/list` is a separate gate from being refused."
+ ;; `when`-guarded during the tool-by-tool rebuild — see write-tools-are-annotated-as-mutating-test.
+ (let [tools (mutating-tools)]
+ (when (seq tools)
+ (doseq [[tool-name _] (sort-by key tools)]
+ (testing tool-name
+ ;; `{}` suffices: the registry checks scope before it validates arguments, so a refusal
+ ;; here can't be an argument error wearing a scope error's clothes.
+ (let [{:keys [error]} (registry/call-tool #{"agent:content:read"} nil tool-name {})]
+ (is (= common/error-code-invalid-request (:code error)))
+ (is (str/starts-with? (:message error)
+ (str "Insufficient scope to call tool: " tool-name ".")))
+ (testing "the message names the scope the tool wants and the ones the token holds —
+ naming only the tool leaves the caller nothing to act on"
+ (is (str/includes? (:message error)
+ (str "Requires " (:scope (get @@#'registry/tools* tool-name)))))
+ (is (str/includes? (:message error) "your token holds agent:content:read."))))))))))
diff --git a/test/metabase/mcp/v2/resolve_test.clj b/test/metabase/mcp/v2/resolve_test.clj
new file mode 100644
index 00000000000..00f2a6f6d63
--- /dev/null
+++ b/test/metabase/mcp/v2/resolve_test.clj
@@ -0,0 +1,141 @@
+(ns metabase.mcp.v2.resolve-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.api.common :as api]
+ [metabase.collections.models.collection :as collection]
+ [metabase.mcp.v2.resolve :as v2.resolve]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(deftest ^:parallel resolve-id-test
+ (testing "numeric ids pass through without a lookup"
+ (is (= 7 (v2.resolve/resolve-id-or-404 :model/Card 7))))
+ (testing "anything that is neither numeric nor a 21-char entity_id is a teaching error"
+ (is (thrown-with-msg? Exception #"entity_id"
+ (v2.resolve/resolve-id-or-404 :model/Card "abc")))))
+
+(deftest ^:parallel resolve-and-read-collapses-existence-test
+ (testing "\"exists but unreadable\" throws the same not-found error as \"doesn't exist\""
+ (let [denied (try (v2.resolve/resolve-and-read-with :model/Card 7
+ (fn [_] (throw (ex-info "You don't have permission." {:status-code 403}))))
+ (catch Exception e (ex-message e)))
+ missing (try (v2.resolve/resolve-and-read-with :model/Card 7
+ (fn [_] (throw (ex-info "Not found." {:status-code 404}))))
+ (catch Exception e (ex-message e)))]
+ (is (= denied missing))
+ (is (str/includes? denied "not found")))))
+
+(deftest ^:parallel entity-id?-test
+ (testing "a genuine 21-char entity_id is recognized"
+ (is (true? (v2.resolve/entity-id? (u/generate-nano-id)))))
+ (testing "numeric ids and short strings are not entity_ids"
+ (is (false? (v2.resolve/entity-id? 7)))
+ (is (false? (v2.resolve/entity-id? "abc")))))
+
+(deftest resolve-id-or-404-resolves-entity-id-test
+ (testing "a valid entity_id translates to the object's numeric id"
+ (mt/with-temp [:model/Collection {coll-id :id eid :entity_id} {}]
+ (is (= coll-id (v2.resolve/resolve-id-or-404 :model/Collection eid))))))
+
+(deftest resolve-and-read-happy-path-test
+ (mt/with-temp [:model/Collection coll {}]
+ (let [eid (:entity_id coll)]
+ (testing "returns the object when the read check yields it"
+ (is (= coll (v2.resolve/resolve-and-read-with :model/Collection eid (fn [_] coll)))))
+ (testing "a nil read check collapses to the not-found error"
+ (is (thrown-with-msg? Exception #"not found"
+ (v2.resolve/resolve-and-read-with :model/Collection eid (fn [_] nil))))))))
+
+(deftest resolve-id-or-404-entity-id-404-collapse-test
+ (testing "a well-formed entity_id that resolves to no row throws the collapsed not-found error"
+ (let [eid (u/generate-nano-id)]
+ (is (v2.resolve/entity-id? eid))
+ (is (thrown-with-msg? Exception #"not found"
+ (v2.resolve/resolve-id-or-404 :model/Collection eid))))))
+
+(deftest ^:parallel resolve-collection-id-test
+ (is (nil? (v2.resolve/resolve-collection-id nil)))
+ (is (nil? (v2.resolve/resolve-collection-id "root")))
+ (is (= 99 (v2.resolve/resolve-collection-id "trash" {:trash-collection-id 99})))
+ (is (thrown? Exception (v2.resolve/resolve-collection-id "trash"))))
+
+(deftest resolve-collection-id-collapses-unreadable-test
+ (testing "GHY-4148: a collection_id naming a collection the caller cannot read must give the
+ exact same not-found error as one naming no collection at all. Without the
+ `resolve-and-read` call in the main branch the id would travel straight into the write
+ unchecked, and a distinguishable error would turn the argument into a collection-id
+ enumeration oracle."
+ (mt/with-temp [:model/Collection {readable-id :id} {:name "Readable"}
+ :model/Collection {unreadable-id :id} {:name "Crowberto's personal subfolder"
+ :location (str "/" (:id (collection/user->personal-collection
+ (mt/user->id :crowberto)))
+ "/")}]
+ (mt/with-test-user :rasta
+ (testing "a readable collection resolves to its own id"
+ (is (= readable-id (v2.resolve/resolve-collection-id readable-id))))
+ (let [missing (try (v2.resolve/resolve-collection-id 13371337)
+ (catch Exception e (ex-message e)))
+ unreadable (try (v2.resolve/resolve-collection-id unreadable-id)
+ (catch Exception e (ex-message e)))]
+ (is (str/includes? missing "not found"))
+ ;; Compare the messages, not merely that both threw: differing wording is the leak.
+ (is (= (str/replace missing "13371337" (str unreadable-id))
+ unreadable)))))))
+
+(deftest resolve-collection-id-or-personal-test
+ (testing "GHY-4218: an absent collection argument defaults to the caller's personal collection"
+ (mt/with-test-user :rasta
+ (is (= (:id (collection/user->personal-collection (mt/user->id :rasta)))
+ (v2.resolve/resolve-collection-id-or-personal nil)))))
+ (testing "GHY-4218: the explicit \"root\" sentinel still means the root collection"
+ (mt/with-test-user :rasta
+ (is (nil? (v2.resolve/resolve-collection-id-or-personal "root")))))
+ (testing "GHY-4218: an explicit id is resolved as usual"
+ (mt/with-test-user :rasta
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (is (= coll-id (v2.resolve/resolve-collection-id-or-personal coll-id))))))
+ (testing "GHY-4218: a caller with no personal collection (API-key users) gets a teaching error
+ rather than silently falling back to the root collection"
+ (mt/with-temp [:model/User {user-id :id} {:type :api-key}]
+ (binding [api/*current-user-id* user-id]
+ (is (thrown-with-msg? Exception #"no personal collection"
+ (v2.resolve/resolve-collection-id-or-personal nil)))))))
+
+(deftest ^:parallel normalize-id-test
+ (testing "GHY-4498: a client that serializes an int-or-string id param as a JSON string still
+ names the numeric id"
+ (is (= 16211 (v2.resolve/normalize-id "16211")))
+ (is (= 1 (v2.resolve/normalize-id "1"))))
+ (testing "GHY-4498: anything that isn't the exact shape of a numeric id is left alone"
+ (doseq [x ["0" "-1" "016211" "1.0" "12x" "" "root" "trash" 7 nil]]
+ (is (= x (v2.resolve/normalize-id x)))))
+ (testing "GHY-4498: a run of digits too large for a long stays a string rather than becoming nil"
+ (is (= "99999999999999999999" (v2.resolve/normalize-id "99999999999999999999"))))
+ (testing "GHY-4498: an entity_id is never mistaken for a numeric id"
+ (let [eid (u/generate-nano-id)]
+ (is (= eid (v2.resolve/normalize-id eid))))))
+
+(deftest ^:parallel resolve-id-or-404-accepts-numeric-string-test
+ (testing "GHY-4498: a numeric id sent as a JSON string resolves like the integer it names"
+ (is (= 7 (v2.resolve/resolve-id-or-404 :model/Card "7"))))
+ (testing "GHY-4498: strings that only look numeric keep failing validation"
+ (doseq [bad ["0" "-1" "016211" "1.0"]]
+ (is (thrown-with-msg? Exception #"entity_id"
+ (v2.resolve/resolve-id-or-404 :model/Card bad))))))
+
+(deftest ^:parallel resolve-collection-id-accepts-numeric-string-test
+ (testing "GHY-4498: the sentinels still win over numeric-string coercion"
+ (is (nil? (v2.resolve/resolve-collection-id "root")))
+ (is (= 99 (v2.resolve/resolve-collection-id "trash" {:trash-collection-id 99})))))
+
+(deftest resolve-collection-id-numeric-string-test
+ (testing "GHY-4498: a collection_id sent as a JSON string resolves to that collection"
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (mt/with-test-user :crowberto
+ (is (= coll-id (v2.resolve/resolve-collection-id (str coll-id))))))))
diff --git a/test/metabase/mcp/v2/test_util.clj b/test/metabase/mcp/v2/test_util.clj
new file mode 100644
index 00000000000..6de110b3c87
--- /dev/null
+++ b/test/metabase/mcp/v2/test_util.clj
@@ -0,0 +1,19 @@
+(ns metabase.mcp.v2.test-util
+ "Test-only v2 MCP tools. Never loaded by the production surface."
+ (:require
+ [metabase.mcp.v2.common :as common]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.metabot.scope :as metabot.scope]))
+
+(set! *warn-on-reflection* true)
+
+(registry/deftool test-echo
+ "Test-only tool. Echoes `message` back, or `pong` when none is given."
+ {:name "test_echo"
+ :scope metabot.scope/agent-content-read
+ :annotations {:readOnlyHint true :idempotentHint true}
+ :args [:map {:closed true}
+ [:message {:optional true} [:maybe :string]]]}
+ [{:keys [message]} _context]
+ (let [payload {:ok true :message (or message "pong")}]
+ (common/success-content payload payload)))
diff --git a/test/metabase/mcp/v2/tools/alert_test.clj b/test/metabase/mcp/v2/tools/alert_test.clj
new file mode 100644
index 00000000000..4a9188cc72a
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/alert_test.clj
@@ -0,0 +1,861 @@
+(ns metabase.mcp.v2.tools.alert-test
+ "Contract tests for the `alert_write` v2 MCP tool, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised for
+ free."
+ (:require
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.channel.email.messages :as messages]
+ [metabase.channel.settings :as channel.settings]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the tool the assertions below drive.
+ [metabase.mcp.v2.tools.alert :as tools.alert]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.notification.test-util :as notification.tu]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(comment tools.alert/keep-me)
+
+(use-fixtures :once (fixtures/initialize :notifications))
+
+(defn- call-tool!
+ "Returns the whole dispatch outcome: `{:result <mcp content>}` for anything that reached the
+ handler, `{:error {:code .. :message ..}}` for a registry-level rejection (scope denial,
+ args-schema failure)."
+ [user scopes args]
+ (mt/with-current-user (if (keyword? user) (mt/user->id user) user)
+ (registry/call-tool scopes nil "alert_write" args)))
+
+(defn- dispatch-error?
+ "Whether a [[call-tool!]] outcome is an error, at either layer."
+ [{:keys [result error]}]
+ (boolean (or error (:isError result))))
+
+(defn- response-text
+ "The outcome's text block, or a registry-level rejection's message."
+ [{:keys [result error]}]
+ (if error (:message error) (-> result :content first :text)))
+
+(defn- tool-result
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info (str "tool call failed: " (response-text outcome)) {:outcome outcome})))
+ (-> outcome response-text json/decode+kw))
+
+(defn- tool-error
+ [outcome]
+ (when-not (dispatch-error? outcome)
+ (throw (ex-info "expected a tool error, got success" {:outcome outcome})))
+ (response-text outcome))
+
+(defn- wire
+ "Round-trip through JSON, so tests exercise the argument shapes an MCP client actually sends."
+ [x]
+ (-> x json/encode json/decode+kw))
+
+(def ^:private fake-slack-channels
+ {:channels [{:display-name "#data-team" :name "data-team" :id "C123"}]})
+
+(defmacro ^:private with-slack
+ [& body]
+ `(mt/with-dynamic-fn-redefs [channel.settings/slack-configured? (constantly true)
+ channel.settings/slack-cached-channels-and-usernames
+ (constantly fake-slack-channels)]
+ ~@body))
+
+(defn- daily-schedule [hour] {:schedule_type "daily" :schedule_hour hour})
+
+(defn- create-alert!
+ "Create an alert on `card-id` through the tool as :crowberto, returning the tool's response body."
+ ([card-id] (create-alert! card-id {}))
+ ([card-id extra]
+ (tool-result (call-tool! :crowberto nil
+ (wire (merge {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)}
+ extra))))))
+
+;;; ------------------------------------------------- create -------------------------------------------------------
+
+(deftest create-alert-test
+ (testing "GHY-4155: create makes a card notification with a cron subscription and an email handler
+ addressed to the caller, and echoes the concise alert projection"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [result (create-alert! card-id)]
+ (is (pos-int? (:id result)))
+ (is (true? (:active result)))
+ (is (= #{:id :active :payload :subscriptions :handlers :creator_id}
+ (set (keys result))))
+ (testing "the payload carries the card and the default condition"
+ (is (= {:card_id card-id :send_condition "has_result" :send_once false}
+ (:payload result))))
+ (testing "the schedule compiles to cron — agents never author cron themselves"
+ (is (= ["0 0 9 * * ? *"] (mapv :cron_schedule (:subscriptions result))))
+ (testing "and is marked as builder-authored, so the alert edits in the schedule picker"
+ (is (= ["cron/builder"] (mapv :ui_display_type (:subscriptions result))))))
+ (testing "the caller is the default recipient on the default email channel"
+ (is (= ["channel/email"] (mapv :channel_type (:handlers result))))
+ (is (= [{:type "notification-recipient/user" :user_id (mt/user->id :crowberto)
+ :email "[email protected]"}]
+ (-> result :handlers first :recipients)))))))))
+
+(deftest create-required-fields-test
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (testing "GHY-4155: create without a card_id is a teaching error, not a schema dump"
+ (is (re-find #"`card_id` is required"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :schedule (daily-schedule 9)}))))))
+ (testing "GHY-4155: create without a schedule is a teaching error"
+ (is (re-find #"`schedule` is required"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id}))))))
+ (testing "GHY-4155: update without an id is a teaching error"
+ (is (re-find #"`id` is required"
+ (tool-error (call-tool! :crowberto nil (wire {:method "update"}))))))))
+
+(deftest schedule-compilation-test
+ (testing "GHY-4155: every ScheduleMap shape compiles to the cron string the notification API stores"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (are [schedule cron] (= [cron]
+ (mapv :cron_schedule (:subscriptions (create-alert! card-id {:schedule schedule}))))
+ {:schedule_type "hourly"} "0 0 * * * ? *"
+ {:schedule_type "daily" :schedule_hour 0} "0 0 0 * * ? *"
+ {:schedule_type "weekly" :schedule_hour 8 :schedule_day "mon"} "0 0 8 ? * 2 *"
+ {:schedule_type "monthly" :schedule_hour 8 :schedule_frame "first"} "0 0 8 1 * ? *"
+ {:schedule_type "monthly" :schedule_hour 8 :schedule_frame "last"
+ :schedule_day "fri"} "0 0 8 ? * 6L *"
+ ;; A null stands for "no value": the strict-client transform lists every property as
+ ;; required, so a filled-in null is an omission and must not read as a surplus field.
+ {:schedule_type "hourly" :schedule_hour nil :schedule_day nil
+ :schedule_frame nil} "0 0 * * * ? *"
+ {:schedule_type "hourly" :schedule_minute 30} "0 30 * * * ? *")))))
+
+(deftest incomplete-schedule-test
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (letfn [(schedule-error [schedule]
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id :schedule schedule}))))]
+ (testing "GHY-4155: an incomplete schedule names the field it is missing. schedule_hour is
+ required rather than defaulted, matching subscription_write — the cron util would
+ otherwise fill it with midnight, a send time the caller never chose"
+ (are [schedule pattern] (re-find pattern (schedule-error schedule))
+ {:schedule_type "daily"} #"A daily schedule needs schedule_hour"
+ {:schedule_type "weekly" :schedule_day "mon"} #"A weekly schedule needs schedule_hour"
+ {:schedule_type "weekly" :schedule_hour 8} #"A weekly schedule needs schedule_day"
+ {:schedule_type "monthly" :schedule_frame "first"} #"A monthly schedule needs schedule_hour"
+ {:schedule_type "monthly" :schedule_hour 8} #"A monthly schedule needs schedule_frame"))
+ (testing "GHY-4155: the \"mid\" frame is the 15th, a calendar day, so pairing it with a weekday
+ is a teaching error rather than the underlying util's opaque case mismatch"
+ (is (re-find #"cannot also take a schedule_day"
+ (schedule-error {:schedule_type "monthly" :schedule_frame "mid"
+ :schedule_day "fri" :schedule_hour 8}))))
+ (testing "a field the schedule type doesn't read is rejected rather than dropped. The cron
+ compiler ignores it, so the alert would send on a schedule nobody asked for while
+ the call reported success — an {hourly, schedule_hour 9} alert fires 24 times a day"
+ (are [schedule pattern] (re-find pattern (schedule-error schedule))
+ {:schedule_type "hourly" :schedule_hour 9} #"hourly schedule doesn't use schedule_hour"
+ {:schedule_type "hourly" :schedule_day "mon"} #"hourly schedule doesn't use schedule_day"
+ {:schedule_type "daily" :schedule_hour 9 :schedule_minute 30} #"daily schedule doesn't use schedule_minute"
+ {:schedule_type "daily" :schedule_hour 9 :schedule_day "mon"} #"daily schedule doesn't use schedule_day"
+ {:schedule_type "daily" :schedule_hour 9 :schedule_frame "first"} #"daily schedule doesn't use schedule_frame"
+ {:schedule_type "weekly" :schedule_hour 8 :schedule_day "mon"
+ :schedule_frame "first"} #"weekly schedule doesn't use schedule_frame")))))
+
+(deftest condition-test
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (testing "GHY-4155: send_once rides the condition object alongside its type"
+ (is (= {:card_id card-id :send_condition "has_result" :send_once true}
+ (:payload (create-alert! card-id {:condition {:type "has_result" :send_once true}})))))
+ (testing "GHY-4155: an omitted condition type still defaults to has_result"
+ (is (= "has_result"
+ (-> (create-alert! card-id {:condition {:send_once true}}) :payload :send_condition)))))))
+
+(deftest goal-condition-requires-a-goal-line-test
+ (mt/with-model-cleanup [:model/Notification]
+ (testing "GHY-4155: a goal condition on a question with no goal line is caught at create — the
+ notification backend only discovers this at send time, where nobody is watching"
+ (mt/with-temp [:model/Card {card-id :id} {:display :table}]
+ (let [err (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :condition {:type "goal_above"}})))]
+ (is (re-find #"goal" err))
+ (is (zero? (t2/count :model/NotificationCard :card_id card-id))))))
+ (testing "GHY-4155: a line chart carrying a goal value takes the same condition"
+ (mt/with-temp [:model/Card {card-id :id} {:display :line
+ :visualization_settings {:graph.goal_value 100}}]
+ (is (= "goal_above"
+ (-> (create-alert! card-id {:condition {:type "goal_above"}}) :payload :send_condition)))))
+ (testing "a goal line toggled on with no value saved names the missing number. Toggling
+ \"Goal line\" persists only graph.show_goal — the drawn 0 is a render-time default —
+ and the send path throws on the missing value, so \"set a goal on the chart\" would
+ send the user in a circle: they already did"
+ (mt/with-temp [:model/Card {card-id :id} {:display :line
+ :visualization_settings {:graph.show_goal true
+ :graph.metrics ["count"]}}]
+ (let [err (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :condition {:type "goal_above"}})))]
+ (is (re-find #"no goal value saved" err))
+ (is (re-find #"enter a goal number" err)))))
+ (testing "a multi-series chart is refused — the alert modal doesn't offer goal alerts there,
+ and the send path would compare against whichever series is listed first"
+ (mt/with-temp [:model/Card {card-id :id} {:display :line
+ :visualization_settings {:graph.show_goal true
+ :graph.goal_value 100
+ :graph.metrics ["count" "sum"]}}]
+ (is (re-find #"more than one series"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :condition {:type "goal_above"}})))))))
+ (testing "a stale goal value with the goal line toggled off is still accepted — the send path
+ reads only graph.goal_value, so the alert works end to end"
+ (mt/with-temp [:model/Card {card-id :id} {:display :line
+ :visualization_settings {:graph.show_goal false
+ :graph.goal_value 100
+ :graph.metrics ["count"]}}]
+ (is (= "goal_above"
+ (-> (create-alert! card-id {:condition {:type "goal_above"}}) :payload :send_condition)))))
+ (testing "GHY-4155: a progress chart always has a goal, so it needs no viz setting"
+ (mt/with-temp [:model/Card {card-id :id} {:display :progress}]
+ (is (= "goal_below"
+ (-> (create-alert! card-id {:condition {:type "goal_below"}}) :payload :send_condition)))))))
+
+;;; ------------------------------------------------ recipients ----------------------------------------------------
+
+(deftest email-recipients-test
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (testing "GHY-4155: recipients accept both user ids and bare email addresses"
+ (let [result (create-alert! card-id {:recipients [(mt/user->id :rasta) "[email protected]"]})
+ recipients (-> result :handlers first :recipients)]
+ (is (= #{"notification-recipient/user" "notification-recipient/raw-value"}
+ (set (map :type recipients))))
+ (set (map :email recipients))))))
+ (testing "GHY-4155: a string that isn't an email address is a teaching error, not a raw-value recipient"
+ (is (re-find #"email"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :recipients ["data-team"]}))))))
+ (testing "GHY-4155: an empty recipients list reads as \"clear\", which this tool can't express —
+ say so rather than silently answering with the caller or the stored list"
+ (is (re-find #"`recipients` can't be empty"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9) :recipients []})))))
+ (let [alert-id (:id (create-alert! card-id))]
+ (is (re-find #"`recipients` can't be empty"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id alert-id :recipients []})))))))
+ (testing "GHY-4155: an unknown user id names the id rather than failing at the FK"
+ (is (re-find #"13371337"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :recipients [13371337]})))))))))
+
+(deftest slack-channel-test
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (with-slack
+ (testing "GHY-4155: a slack alert stores the channel as a raw-value recipient, resolved to its
+ display name and slack id — the agent passes a name, never an id"
+ (let [result (create-alert! card-id {:channel "slack" :slack_channel "data-team"})]
+ (is (= ["channel/slack"] (mapv :channel_type (:handlers result))))
+ (is (= [{:type "notification-recipient/raw-value" :email "#data-team"}]
+ (-> result :handlers first :recipients)))
+ (is (= {:value "#data-team" :channel_id "C123"}
+ (t2/select-one-fn :details :model/NotificationRecipient
+ :notification_handler_id
+ (t2/select-one-fn :id :model/NotificationHandler
+ :notification_id (:id result)))))))
+ (testing "GHY-4155: an unknown channel name is a teaching error"
+ (is (re-find #"no-such-channel"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :channel "slack" :slack_channel "no-such-channel"}))))))
+ (testing "GHY-4155: channel slack without slack_channel names the missing argument"
+ (is (re-find #"slack_channel"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :channel "slack"}))))))
+ (testing "GHY-4155: recipients are meaningless on a slack alert — the channel is the recipient"
+ (is (re-find #"recipients"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :channel "slack" :slack_channel "data-team"
+ :recipients ["[email protected]"]})))))))
+ (testing "GHY-4155: slack that isn't set up at all says so, rather than 'channel not found'"
+ (mt/with-dynamic-fn-redefs [channel.settings/slack-configured? (constantly false)]
+ (is (re-find #"not configured"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :channel "slack" :slack_channel "data-team"}))))))))))
+
+;;; ------------------------------------------------- update -------------------------------------------------------
+
+(deftest slack-channel-on-an-email-alert-is-refused-test
+ (testing "slack_channel without channel \"slack\" is a teaching error rather than a silently ignored
+ argument — otherwise the call reports success while nothing reaches Slack"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (with-slack
+ (testing "on create, where the channel defaults to email"
+ (is (re-find #"slack_channel"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :slack_channel "data-team"}))))))
+ (testing "on update of an email alert"
+ (let [alert (create-alert! card-id)]
+ (is (re-find #"slack_channel"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id alert)
+ :slack_channel "data-team"})))))
+ (is (= [:channel/email]
+ (mapv :channel_type
+ (t2/select :model/NotificationHandler :notification_id (:id alert))))))))))))
+
+(deftest update-patches-only-what-it-is-given-test
+ (testing "GHY-4155: update is a patch — the fields it doesn't mention survive, including the
+ handler and subscription rows the notification update spec would otherwise delete"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [created (create-alert! card-id {:recipients [(mt/user->id :rasta)]})
+ updated (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :condition {:send_once true}})))]
+ (is (= {:card_id card-id :send_condition "has_result" :send_once true} (:payload updated)))
+ (is (= ["0 0 9 * * ? *"] (mapv :cron_schedule (:subscriptions updated))))
+ (is (= [(mt/user->id :rasta)]
+ (map :user_id (-> updated :handlers first :recipients)))))))))
+
+(deftest update-schedule-and-recipients-test
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [created (create-alert! card-id)]
+ (testing "GHY-4155: a new schedule replaces the alert's single cron subscription"
+ (let [updated (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :schedule {:schedule_type "weekly"
+ :schedule_hour 8
+ :schedule_day "mon"}})))]
+ (is (= ["0 0 8 ? * 2 *"] (mapv :cron_schedule (:subscriptions updated))))))
+ (testing "GHY-4155: new recipients replace the old ones on the same channel"
+ (let [updated (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :recipients ["[email protected]"]})))]
+ (is (= ["channel/email"] (mapv :channel_type (:handlers updated))))
+ (is (= ["[email protected]"] (map :email (-> updated :handlers first :recipients))))))))))
+
+(deftest update-recipients-patches-the-handler-test
+ (testing "GHY-4155: editing recipients on the same channel patches the stored handler rather than
+ deleting and recreating it, so nothing downstream sees the handler disappear"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [created (create-alert! card-id)
+ handler-id (-> created :handlers first :id)
+ updated (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :recipients ["[email protected]"]})))]
+ (is (= handler-id (-> updated :handlers first :id))))))))
+
+(deftest update-refuses-to-collapse-multi-channel-delivery-test
+ (testing "GHY-4155: an alert built in the product can deliver over several channels; this tool
+ writes one, so changing delivery would silently drop the rest — refuse instead"
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers [{:channel_type :channel/email
+ :recipients [{:type :notification-recipient/user
+ :user_id (mt/user->id :crowberto)}]}
+ {:channel_type :channel/slack
+ :recipients [{:type :notification-recipient/raw-value
+ :details {:value "#data-team"}}]}]}]
+ (is (re-find #"more than one channel"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id notification)
+ :recipients ["[email protected]"]})))))
+ (testing "but an edit that leaves delivery alone still goes through"
+ (is (false? (:active (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id notification)
+ :active false}))))))))))
+
+(deftest update-refuses-to-collapse-multi-schedule-test
+ (testing "an alert built through the REST API can carry several cron subscriptions;
+ `:subscriptions` is a `:multi-row?` nested spec, so writing one back would delete the
+ rest. Refuse, the way multi-channel delivery is refused"
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :subscriptions [{:type :notification-subscription/cron
+ :cron_schedule "0 0 9 * * ? *"}
+ {:type :notification-subscription/cron
+ :cron_schedule "0 0 17 * * ? *"}]}]
+ (let [id (:id notification)
+ crons #(set (map :cron_schedule (t2/select :model/NotificationSubscription
+ :notification_id id)))]
+ (is (= 2 (count (crons))))
+ (testing "changing the schedule is refused"
+ (is (str/includes? (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id id
+ :schedule (daily-schedule 7)})))
+ "more than one schedule")))
+ (testing "and both subscriptions survive the attempt"
+ (is (= #{"0 0 9 * * ? *" "0 0 17 * * ? *"} (crons))))
+ (testing "an edit that leaves the schedule alone still goes through"
+ (is (= id (:id (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id id :active false}))))))
+ (is (= 2 (count (crons)))))))))
+
+(deftest update-403s-that-are-not-about-access-keep-their-message-test
+ (testing "only the read/write rejection collapses to not-found — that one has to, or a recipient
+ who can read an alert but not edit it could tell it apart from one that doesn't exist.
+ Every other 403 is about the edit itself and must say so, or the agent is told an alert
+ it just read no longer exists (SEC-662 domain rejections landed here)"
+ (mt/when-ee-evailable
+ (mt/with-premium-features #{:email-allow-list}
+ (notification.tu/with-channel-fixtures [:channel/email]
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers [{:channel_type :channel/email
+ :recipients [{:type :notification-recipient/user
+ :user_id (mt/user->id :crowberto)}]}]}]
+ (mt/with-temporary-setting-values [subscription-allowed-domains "example.com"]
+ (let [error (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id notification)
+ :recipients ["[email protected]"]})))]
+ (testing "the disallowed address is named"
+ (is (str/includes? error "[email protected]")))
+ (testing "and it is not disguised as a missing alert"
+ (is (not (str/includes? error "not found"))))))))))))
+
+(deftest update-refuses-to-replace-an-unmanaged-channel-test
+ (testing "an alert delivering over a channel this tool doesn't manage — an http webhook paging
+ an on-call rota, say — must survive an edit that names a channel the tool does manage.
+ Guarding the requested channel rather than the stored one let `channel: \"email\"`
+ replace the webhook handler outright and still report success."
+ (mt/with-temp [:model/Channel {chan-id :id} {:name "PagerDuty"
+ :type :channel/http
+ :active true
+ :details {:url "https://events.pagerduty.example/enqueue"
+ :auth-method "none"}}]
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers [{:channel_type :channel/http :channel_id chan-id}]}]
+ (let [handlers #(t2/select [:model/NotificationHandler :id :channel_type :channel_id]
+ :notification_id (:id notification))
+ before (handlers)]
+ (testing "omitting channel is refused"
+ (is (re-find #"doesn't manage"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id notification)
+ :recipients ["[email protected]"]}))))))
+ (testing "and naming a managed channel is refused too, rather than clobbering the webhook"
+ (is (re-find #"doesn't manage"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id notification)
+ :channel "email"}))))))
+ (testing "the stored handler is untouched by either attempt"
+ (is (= before (handlers))))
+ (testing "an edit that leaves delivery alone still goes through"
+ (is (false? (:active (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id notification)
+ :active false}))))))))))))
+
+(deftest update-preserves-a-stale-goal-condition-test
+ (testing "GHY-4155: an alert whose chart lost its goal line since creation must still be pausable —
+ the goal check belongs to setting the condition, not to every update"
+ (mt/with-temp [:model/Card {card-id :id} {:display :table}]
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :notification-card {:send_condition :goal_above}
+ :handlers []}]
+ (t2/update! :model/NotificationCard (:payload_id notification) {:card_id card-id})
+ (testing "the fixture really stored a goal condition — with anything else stored, the
+ assertions below pass even against code that re-checks the goal on every update,
+ and this test guards nothing"
+ (is (= :goal_above (t2/select-one-fn :send_condition :model/NotificationCard
+ (:payload_id notification)))))
+ (is (false? (:active (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id notification)
+ :active false}))))))
+ (testing "setting the same condition again does re-check, and now fails"
+ (is (re-find #"goal"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id notification)
+ :condition {:type "goal_above"}}))))))))))
+
+(deftest update-switches-channel-test
+ (testing "GHY-4155: switching an email alert to slack replaces the handler outright"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (with-slack
+ (let [created (create-alert! card-id)
+ updated (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :channel "slack" :slack_channel "data-team"})))]
+ (is (= ["channel/slack"] (mapv :channel_type (:handlers updated))))
+ (is (= ["#data-team"] (map :email (-> updated :handlers first :recipients))))
+ (is (= 1 (t2/count :model/NotificationHandler :notification_id (:id created))))))))))
+
+(defn- captured-emails-during!
+ "Run `thunk` with the messages layer sending synchronously and the outgoing inbox mocked,
+ returning the emails it would have sent. The messages layer sends on a future by default, so
+ without the sync redef the capture window closes before the send runs."
+ [thunk]
+ (notification.tu/with-mock-inbox-email!
+ (mt/with-dynamic-fn-redefs [messages/send-email! (fn [& args]
+ (apply @#'messages/send-email-sync! args))]
+ (thunk))))
+
+(deftest update-delivery-notifies-creator-test
+ (testing "an update that points delivery at anyone besides the caller emails the caller. In the
+ UI nobody tells the creator about a delivery change because they made it themselves;
+ through this tool the recipient list may be the agent's choice, and the creator is the
+ one person positioned to notice an address they never picked."
+ (notification.tu/with-channel-fixtures [:channel/email]
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers [{:channel_type :channel/email
+ :recipients [{:type :notification-recipient/user
+ :user_id (mt/user->id :crowberto)}]}]}]
+ (let [update! (fn [args]
+ (captured-emails-during!
+ #(tool-result (call-tool! :crowberto nil
+ (wire (merge {:method "update" :id (:id notification)}
+ args))))))
+ notice? (fn [emails]
+ (boolean (some #(and (= "Crowberto Corv added you to an alert" (:subject %))
+ (contains? (set (:bcc %)) "[email protected]"))
+ emails)))]
+ (testing "delivery kept at just the caller sends nothing"
+ (is (empty? (update! {:recipients [(mt/user->id :crowberto)]}))))
+ (testing "delivery pointed at an outside address notifies the caller"
+ (is (true? (notice? (update! {:recipients ["[email protected]"]})))))
+ (testing "delivery pointed at another user notifies the caller too — that recipient is a
+ user id, whose address only [[delivery-targets]]'s hydration can see, so the
+ raw-address case above does not cover it"
+ (is (true? (notice? (update! {:recipients [(mt/user->id :rasta)]})))))
+ (testing "a non-delivery update sends the caller no notice"
+ (is (false? (notice? (update! {:active false}))))))))))
+
+(deftest create-delivery-notifies-caller-test
+ (testing "create tells the caller where the new alert delivers. The notification API's own
+ \"you were added\" mail removes the current user, so without this the agent could stand
+ up an alert mailing a third party and the token's owner would never hear about it"
+ (mt/with-model-cleanup [:model/Notification]
+ (notification.tu/with-channel-fixtures [:channel/email]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [create! (fn [args]
+ (captured-emails-during!
+ #(tool-result (call-tool! :crowberto nil
+ (wire (merge {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)}
+ args))))))
+ notice? (fn [emails]
+ (boolean (some #(and (= "Crowberto Corv added you to an alert" (:subject %))
+ (contains? (set (:bcc %)) "[email protected]"))
+ emails)))]
+ (testing "an alert that only reaches the caller tells them nothing they don't know"
+ (is (false? (notice? (create! {})))))
+ (testing "an outside address notifies the caller"
+ (is (true? (notice? (create! {:recipients ["[email protected]"]})))))
+ (testing "and so does another user"
+ (is (true? (notice? (create! {:recipients [(mt/user->id :rasta)]})))))))))))
+
+(deftest active-round-trip-test
+ (testing "GHY-4155: alerts pause and resume through `active` — there is no archived flag for them"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [created (create-alert! card-id)]
+ (is (false? (:active (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :active false}))))))
+ (is (false? (t2/select-one-fn :active :model/Notification :id (:id created))))
+ (is (true? (:active (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :active true})))))))))))
+
+(deftest card-id-is-create-only-test
+ (testing "GHY-4155: an alert's question can't be swapped out — say so instead of silently ignoring it"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Card {other-id :id} {}]
+ (let [created (create-alert! card-id)]
+ (is (re-find #"card_id"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :card_id other-id})))))
+ (is (= card-id (t2/select-one-fn :card_id :model/NotificationCard
+ :id (t2/select-one-fn :payload_id :model/Notification
+ :id (:id created))))))))))
+
+(deftest null-arguments-are-dropped-at-the-boundary-test
+ (testing "GHY-4155: strict clients fill every declared property with null; those must read as
+ 'not set' rather than clobbering the stored alert"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [created (create-alert! card-id {:recipients [(mt/user->id :rasta)]})
+ updated (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:id created)
+ :card_id nil :condition nil :schedule nil
+ :channel nil :slack_channel nil
+ :recipients nil :active nil})))]
+ (is (true? (:active updated)))
+ (is (= ["0 0 9 * * ? *"] (mapv :cron_schedule (:subscriptions updated))))
+ (is (= [(mt/user->id :rasta)]
+ (map :user_id (-> updated :handlers first :recipients)))))))))
+
+;;; ------------------------------------------------ id handling ---------------------------------------------------
+
+(deftest id-must-be-numeric-test
+ (testing "GHY-4155: notifications have no entity_id column, so an entity_id-shaped id is a
+ teaching error rather than a confusing not-found"
+ (is (re-find #"numeric id"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id "sqkfMD8bLLBqZ0lVdOU6D"})))))))
+
+(deftest unknown-alert-is-not-found-test
+ (testing "GHY-4155: an unreadable alert and a nonexistent one are indistinguishable — no existence oracle"
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers []}]
+ (let [norm #(str/replace % #"\d+" "N")]
+ (is (= (norm (tool-error (call-tool! :rasta nil (wire {:method "update" :id (:id notification)
+ :active false}))))
+ (norm (tool-error (call-tool! :rasta nil (wire {:method "update" :id 13371337
+ :active false}))))))))))
+
+;;; ----------------------------------------------- permissions ----------------------------------------------------
+
+(deftest card-read-permission-is-inherited-test
+ (testing "GHY-4155: an alert can only be created on a question the caller can read — the check is
+ the notification model's, inherited rather than reimplemented"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:collection_id coll-id}]
+ (is (some? (tool-error (call-tool! :rasta nil
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)})))))
+ (is (zero? (t2/count :model/NotificationCard :card_id card-id))))))))
+
+(deftest update-requires-ownership-test
+ (testing "GHY-4155: a non-creator, non-admin cannot edit someone else's alert"
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers [{:channel_type :channel/email
+ :recipients [{:type :notification-recipient/user
+ :user_id (mt/user->id :rasta)}]}]}]
+ ;; rasta is a recipient, so the alert reads — but editing it is still refused.
+ (is (some? (tool-error (call-tool! :rasta nil
+ (wire {:method "update" :id (:id notification) :active false})))))
+ (is (true? (t2/select-one-fn :active :model/Notification :id (:id notification)))))))
+
+;;; -------------------------------------------------- scopes ------------------------------------------------------
+
+(deftest query-execute-scope-gates-deferred-execution-test
+ (testing "an alert is a scheduled run of its question with the results delivered, so a token that
+ can't execute queries in-session can't schedule the scheduler to do it either — the
+ send happens later, tokenlessly, under the creator's permissions, and write time is the
+ only moment scopes can bound it"
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [write-only #{metabot.scope/agent-delivery-write}
+ with-exec #{metabot.scope/agent-delivery-write metabot.scope/agent-query-run}
+ create-args (wire {:method "create" :card_id card-id :schedule (daily-schedule 9)})]
+ (testing "create with only the write scope is refused, naming the missing scope"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only create-args))))
+ (is (zero? (t2/count :model/NotificationCard :card_id card-id))))
+ (mt/with-model-cleanup [:model/Notification]
+ (testing "create with write + query:execute goes through"
+ (let [created (tool-result (call-tool! :crowberto with-exec create-args))]
+ (is (pos-int? (:id created)))
+ (testing "redirecting delivery with only the write scope is refused"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only
+ (wire {:method "update" :id (:id created)
+ :recipients ["[email protected]"]}))))))
+ (testing "but pausing with only the write scope still works — the kill switch must
+ never need more scope than the thing it kills (the response is the
+ GHY-4217 ack, so the effect is asserted from the database)"
+ (is (= (:id created)
+ (:id (tool-result (call-tool! :crowberto write-only
+ (wire {:method "update" :id (:id created)
+ :active false}))))))
+ (is (false? (t2/select-one-fn :active :model/Notification :id (:id created))))))))))))
+
+;; TODO(slice-17/query): re-enable once the execute_sql tool lands and registers agent:query:run as
+;; its own scope — until then no tool declares it, so registered-scopes can't see it.
+#_(deftest query-execute-scope-is-grantable-test
+ (testing "the scope the gate needs is grantable — it reaches the default DCR grant as
+ execute_query's own scope, so a client holding the default grant can satisfy the gate"
+ (is (contains? (registry/registered-scopes) "agent:query:run"))))
+
+(deftest resuming-and-rescheduling-gate-on-query-execute-test
+ (testing "resuming a paused alert starts the sends again, and a new schedule changes how often they
+ happen — both commit the scheduler to running the question, so both need the execute
+ scope. Only pausing stays free: a kill switch must never need more scope than the thing
+ it kills"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [write-only #{metabot.scope/agent-delivery-write}
+ with-exec #{metabot.scope/agent-delivery-write metabot.scope/agent-query-run}
+ id (:id (tool-result (call-tool! :crowberto with-exec
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)}))))
+ cron #(mapv :cron_schedule (t2/select :model/NotificationSubscription :notification_id id))]
+ (testing "pausing needs no execute scope"
+ (is (= id (:id (tool-result (call-tool! :crowberto write-only
+ (wire {:method "update" :id id :active false}))))))
+ (is (false? (t2/select-one-fn :active :model/Notification :id id))))
+ (testing "resuming it is refused, naming the missing scope, and the alert stays paused"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only
+ (wire {:method "update" :id id :active true})))))
+ (is (false? (t2/select-one-fn :active :model/Notification :id id))))
+ (testing "with the execute scope the resume goes through"
+ (is (= id (:id (tool-result (call-tool! :crowberto with-exec
+ (wire {:method "update" :id id :active true}))))))
+ (is (true? (t2/select-one-fn :active :model/Notification :id id))))
+ (testing "raising a daily alert to hourly is refused, and the cron is untouched"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only
+ (wire {:method "update" :id id
+ :schedule {:schedule_type "hourly"
+ :schedule_minute 0}})))))
+ (is (= ["0 0 9 * * ? *"] (cron))))
+ (testing "and goes through with the execute scope"
+ (is (= id (:id (tool-result (call-tool! :crowberto with-exec
+ (wire {:method "update" :id id
+ :schedule {:schedule_type "hourly"
+ :schedule_minute 0}}))))))
+ (is (= ["0 0 * * * ? *"] (cron)))))))))
+
+(deftest clearing-send-once-gates-on-query-execute-test
+ (testing "send_once archives the alert after its first send, so clearing it turns a single
+ scheduled run into an unbounded series — the same commitment a new schedule makes, and
+ so the same execute scope. Setting it stays free: it can only reduce the sends"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [write-only #{metabot.scope/agent-delivery-write}
+ with-exec #{metabot.scope/agent-delivery-write metabot.scope/agent-query-run}
+ id (:id (tool-result (call-tool! :crowberto with-exec
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)
+ :condition {:send_once true}}))))
+ send-once #(t2/select-one-fn :send_once :model/NotificationCard :card_id card-id)]
+ (is (true? (send-once)))
+ (testing "clearing it with only the write scope is refused, naming the missing scope"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only
+ (wire {:method "update" :id id
+ :condition {:send_once false}})))))
+ (testing "and the limit is still in place"
+ (is (true? (send-once)))))
+ (testing "a strict client's nulls are an omission, not a request to clear"
+ (is (= id (:id (tool-result (call-tool! :crowberto write-only
+ (wire {:method "update" :id id
+ :condition {:type nil :send_once nil}}))))))
+ (is (true? (send-once))))
+ (testing "setting it again needs no execute scope — it only shortens the series"
+ (is (= id (:id (tool-result (call-tool! :crowberto write-only
+ (wire {:method "update" :id id
+ :condition {:send_once true}}))))))
+ (is (true? (send-once))))
+ (testing "with the execute scope the clear goes through"
+ (is (= id (:id (tool-result (call-tool! :crowberto with-exec
+ (wire {:method "update" :id id
+ :condition {:send_once false}}))))))
+ (is (false? (send-once)))))))))
+
+(deftest write-response-respects-read-scopes-test
+ (testing "GHY-4217: a write scope must not double as a read scope — without the alert read scopes
+ the response is a minimal ack, so a no-op update can't read the recipients back"
+ (mt/with-model-cleanup [:model/Notification]
+ (mt/with-temp [:model/Card {card-id :id} {}]
+ (let [write-only #{metabot.scope/agent-delivery-write metabot.scope/agent-query-run}
+ readable (conj write-only "agent:content:read")
+ created (tool-result (call-tool! :crowberto write-only
+ (wire {:method "create" :card_id card-id
+ :schedule (daily-schedule 9)})))]
+ (testing "create without the read scopes returns the ack, not the alert"
+ (is (pos-int? (:id created)))
+ (is (not (contains? created :handlers)))
+ (is (re-find #"agent:content:read" (:note created))))
+ (testing "and a no-op update can't read the body back either"
+ (is (not (contains? (tool-result (call-tool! :crowberto write-only
+ (wire {:method "update" :id (:id created)
+ :active true})))
+ :handlers))))
+ (testing "with the read scopes the full body comes back"
+ (is (contains? (tool-result (call-tool! :crowberto readable
+ (wire {:method "update" :id (:id created)
+ :active true})))
+ :handlers))))))))
+
+(deftest update-rejections-are-indistinguishable-test
+ (testing "GHY-4217: a recipient can read an alert but not update it; that rejection must match
+ the not-found a stranger gets, or probing ids tells delivery targets apart"
+ (notification.tu/with-card-notification
+ [notification {:card {}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers [{:channel_type :channel/email
+ :recipients [{:type :notification-recipient/user
+ :user_id (mt/user->id :rasta)}]}]}]
+ (let [norm #(str/replace % #"\d+" "N")]
+ (is (= (norm (tool-error (call-tool! :rasta nil (wire {:method "update" :id (:id notification)
+ :active false}))))
+ (norm (tool-error (call-tool! :rasta nil (wire {:method "update" :id 13371337
+ :active false}))))))))))
+
+(deftest ^:parallel scope-gating-test
+ (let [args (wire {:method "update" :id 13371337 :active false})]
+ (testing "GHY-4155: a bearer token without the alert scope is refused before dispatch"
+ (is (re-find #"^Insufficient scope to call tool: alert_write\."
+ (tool-error (call-tool! :crowberto #{"agent:content:read"} args)))))
+ (testing "GHY-4155: the write scope covers both methods — there is no create-only alert token"
+ (is (re-find #"not found"
+ (tool-error (call-tool! :crowberto #{metabot.scope/agent-delivery-write} args)))))
+ (testing "GHY-4155: v1's agent:alert:create does not reach this tool — it gates the v1 tool only"
+ (is (re-find #"^Insufficient scope to call tool: alert_write\."
+ (tool-error (call-tool! :crowberto #{metabot.scope/agent-alert-create} args)))))
+ ;; GHY-4225: the metabot permission wildcards no longer bear on v2. In-app callers reach
+ ;; v2 through cookie sessions bound to the unrestricted sentinel, and OAuth tokens draw
+ ;; their scopes from the tool registry (`registered-scopes`), not from
+ ;; `user-metabot-perms->scopes` — so the old wildcard coupling was already vestigial here.
+ ))
+
+(deftest ^:parallel scopes-grantable-test
+ (testing "GHY-4155: the scope the tool checks must be grantable — advertised through registered-scopes"
+ (is (set/subset? #{"agent:delivery:write"} (registry/registered-scopes)))))
+
+(deftest ^:parallel tools-list-visibility-test
+ (testing "GHY-4155: the tool is visible exactly to tokens carrying its write scope"
+ (is (some #(= "alert_write" (:name %)) (registry/list-tools #{"agent:delivery:write"})))
+ (is (not (some #(= "alert_write" (:name %)) (registry/list-tools #{"agent:alert:create"}))))
+ (is (not (some #(= "alert_write" (:name %)) (registry/list-tools #{"agent:content:read"}))))))
diff --git a/test/metabase/mcp/v2/tools/bookmark_test.clj b/test/metabase/mcp/v2/tools/bookmark_test.clj
new file mode 100644
index 00000000000..21dace4560d
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/bookmark_test.clj
@@ -0,0 +1,181 @@
+(ns metabase.mcp.v2.tools.bookmark-test
+ "Contract tests for the `bookmark_content` v2 MCP tool, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, Malli validation, and teaching-error conversion are exercised for free."
+ (:require
+ [clojure.test :refer :all]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the tool the assertions below drive.
+ [metabase.mcp.v2.tools.bookmark :as tools.bookmark]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.test :as mt]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(comment tools.bookmark/keep-me)
+
+(defn- call-tool!
+ ([user args] (call-tool! user nil args))
+ ([user scopes args]
+ (mt/with-current-user (mt/user->id user)
+ (registry/call-tool scopes nil "bookmark_content" args))))
+
+(defn- tool-result
+ [{:keys [result error]}]
+ (when error
+ (throw (ex-info (str "tool call rejected: " (:message error)) {:error error})))
+ (when (:isError result)
+ (throw (ex-info (str "tool call failed: " (-> result :content first :text))
+ {:result result})))
+ (-> result :content first :text json/decode+kw))
+
+(defn- tool-error
+ [{:keys [result error]}]
+ (cond
+ error (:message error)
+ (:isError result) (-> result :content first :text)
+ :else (throw (ex-info "expected a tool error, got success" {:result result}))))
+
+(deftest bookmark-and-unbookmark-test
+ (testing "GHY-4152: bookmarked true/false creates and removes the calling user's bookmark row"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Orders over time" :type :question}]
+ (let [user-id (mt/user->id :rasta)]
+ (is (=? {:type "question" :id card-id :name "Orders over time" :bookmarked true}
+ (tool-result (call-tool! :rasta {:type "question" :id card-id :bookmarked true}))))
+ (is (t2/exists? :model/CardBookmark :card_id card-id :user_id user-id))
+ (is (=? {:type "question" :id card-id :bookmarked false}
+ (tool-result (call-tool! :rasta {:type "question" :id card-id :bookmarked false}))))
+ (is (not (t2/exists? :model/CardBookmark :card_id card-id :user_id user-id)))))))
+
+(deftest idempotent-test
+ (testing "GHY-4152: both directions are idempotent — unlike REST, a repeat call succeeds instead of
+ surfacing the 400, so an agent that can't observe its prior calls never has to guess"
+ (mt/with-temp [:model/Card {card-id :id} {:type :question}]
+ (let [user-id (mt/user->id :rasta)]
+ (testing "re-bookmarking succeeds and leaves exactly one row"
+ (call-tool! :rasta {:type "question" :id card-id :bookmarked true})
+ (is (=? {:bookmarked true}
+ (tool-result (call-tool! :rasta {:type "question" :id card-id :bookmarked true}))))
+ (is (= 1 (t2/count :model/CardBookmark :card_id card-id :user_id user-id))))
+ (testing "un-bookmarking something that isn't bookmarked succeeds"
+ (call-tool! :rasta {:type "question" :id card-id :bookmarked false})
+ (is (=? {:bookmarked false}
+ (tool-result (call-tool! :rasta {:type "question" :id card-id :bookmarked false}))))
+ (is (= 0 (t2/count :model/CardBookmark :card_id card-id :user_id user-id))))))))
+
+(deftest every-type-routes-to-its-bookmark-table-test
+ (testing "GHY-4152: each type reaches the right bookmark table; the three card flavors share `card`"
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {question-id :id} {:type :question :collection_id coll-id}
+ :model/Card {model-id :id} {:type :model :collection_id coll-id}
+ :model/Card {metric-id :id} {:type :metric :collection_id coll-id}
+ :model/Dashboard {dash-id :id} {:collection_id coll-id}
+ :model/Document {doc-id :id} {:collection_id coll-id :document {}}]
+ (doseq [[type id] [["question" question-id] ["model" model-id] ["metric" metric-id]]]
+ (testing type
+ (is (=? {:bookmarked true} (tool-result (call-tool! :rasta {:type type :id id :bookmarked true}))))
+ (is (t2/exists? :model/CardBookmark :card_id id :user_id (mt/user->id :rasta)))))
+ (testing "dashboard"
+ (call-tool! :rasta {:type "dashboard" :id dash-id :bookmarked true})
+ (is (t2/exists? :model/DashboardBookmark :dashboard_id dash-id :user_id (mt/user->id :rasta))))
+ (testing "collection"
+ (call-tool! :rasta {:type "collection" :id coll-id :bookmarked true})
+ (is (t2/exists? :model/CollectionBookmark :collection_id coll-id :user_id (mt/user->id :rasta))))
+ (testing "document"
+ (call-tool! :rasta {:type "document" :id doc-id :bookmarked true})
+ (is (t2/exists? :model/DocumentBookmark :document_id doc-id :user_id (mt/user->id :rasta)))))))
+
+(deftest entity-id-test
+ (testing "GHY-4152: id accepts a 21-char entity_id as well as a numeric id"
+ (mt/with-temp [:model/Collection {coll-id :id coll-eid :entity_id} {}]
+ (is (=? {:type "collection" :id coll-id :bookmarked true}
+ (tool-result (call-tool! :rasta {:type "collection" :id coll-eid :bookmarked true}))))
+ (is (t2/exists? :model/CollectionBookmark :collection_id coll-id :user_id (mt/user->id :rasta)))))
+ (testing "GHY-4152: a malformed id is a teaching error naming both accepted shapes"
+ (is (= "Invalid id \"nope\" — pass the positive numeric id, or the 21-character entity_id from a search or list result."
+ (tool-error (call-tool! :rasta {:type "collection" :id "nope" :bookmarked true})))))
+ (testing "GHY-4152: zero and negative numeric ids are rejected by schema, matching REST's ms/PositiveInt"
+ (doseq [bad-id [0 -1]]
+ (is (re-find #"Invalid arguments"
+ (tool-error (call-tool! :rasta {:type "collection" :id bad-id :bookmarked true})))))))
+
+(deftest card-flavor-mismatch-test
+ (testing "GHY-4152: bookmarking a card under the wrong flavor is a teaching error naming the right type"
+ (mt/with-temp [:model/Card {card-id :id} {:type :metric}]
+ (is (= (format "Card %d is a metric — bookmark it with type: \"metric\"." card-id)
+ (tool-error (call-tool! :rasta {:type "question" :id card-id :bookmarked true}))))
+ (is (not (t2/exists? :model/CardBookmark :card_id card-id))))))
+
+(deftest read-permission-test
+ (testing "GHY-4152: an unreadable item collapses to not-found — the response is never an existence oracle"
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:type :question :collection_id coll-id}]
+ (is (= (format "Card %d not found — it may not exist, or you may not have access to it." card-id)
+ (tool-error (call-tool! :rasta {:type "question" :id card-id :bookmarked true}))))
+ (is (not (t2/exists? :model/CardBookmark :card_id card-id))))))
+ (testing "GHY-4152: the read check covers un-bookmarking too, where REST only checks the create —
+ an item that became unreadable can no longer be un-bookmarked through the tool, and its
+ bookmark survives the attempt"
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:type :question :collection_id coll-id}]
+ (t2/insert! :model/CardBookmark {:card_id card-id :user_id (mt/user->id :rasta)})
+ (is (= (format "Card %d not found — it may not exist, or you may not have access to it." card-id)
+ (tool-error (call-tool! :rasta {:type "question" :id card-id :bookmarked false}))))
+ (is (t2/exists? :model/CardBookmark :card_id card-id :user_id (mt/user->id :rasta))))))
+ (testing "GHY-4152: a nonexistent id gets the same message"
+ (is (= "Card 999999999 not found — it may not exist, or you may not have access to it."
+ (tool-error (call-tool! :rasta {:type "question" :id 999999999 :bookmarked true}))))))
+
+(deftest per-user-test
+ (testing "GHY-4152: bookmarks are per-user — one user's bookmark is invisible to another's un-bookmark"
+ (mt/with-temp [:model/Card {card-id :id} {:type :question}]
+ (tool-result (call-tool! :rasta {:type "question" :id card-id :bookmarked true}))
+ ;; :lucky bookmarks and un-bookmarks its own row first, so the negative assertion below has a
+ ;; live counterfactual — it fails if un-bookmark! silently does nothing.
+ (tool-result (call-tool! :lucky {:type "question" :id card-id :bookmarked true}))
+ (tool-result (call-tool! :lucky {:type "question" :id card-id :bookmarked false}))
+ (is (t2/exists? :model/CardBookmark :card_id card-id :user_id (mt/user->id :rasta)))
+ (is (not (t2/exists? :model/CardBookmark :card_id card-id :user_id (mt/user->id :lucky)))))))
+
+(deftest scope-test
+ (testing "GHY-4152: the tool requires agent:content:write"
+ (mt/with-temp [:model/Card {card-id :id} {:type :question}]
+ (is (re-find #"^Insufficient scope to call tool: bookmark_content\."
+ (tool-error (call-tool! :rasta #{metabot.scope/agent-content-read}
+ {:type "question" :id card-id :bookmarked true}))))
+ ;; Reachability is the point here — without agent:content:read the echo degrades to the
+ ;; GHY-4227 ack, so the bookmark itself is what proves the call landed.
+ (is (=? {:id card-id}
+ (tool-result (call-tool! :rasta #{metabot.scope/agent-content-write}
+ {:type "question" :id card-id :bookmarked true}))))
+ (is (t2/exists? :model/CardBookmark :card_id card-id :user_id (mt/user->id :rasta))))))
+
+(deftest readback-requires-read-scope-test
+ (testing "GHY-4227: bookmarking echoes the item's name, so a write-only token would learn the name
+ of anything it can bookmark — the echo degrades to an ack without agent:content:read"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Salaries by employee" :type :question}]
+ (let [result (tool-result (call-tool! :rasta #{metabot.scope/agent-content-write}
+ {:type "question" :id card-id :bookmarked true}))]
+ (is (= #{:id :note :bookmarked} (set (keys result))))
+ (is (= card-id (:id result)))
+ ;; :bookmarked survives the degradation — it's not sensitive, the caller supplied it, and
+ ;; it's the one field an agent needs to confirm which direction the write went.
+ (is (true? (:bookmarked result)))
+ (is (re-find #"agent:content:read" (:note result)))
+ (testing "and the bookmark still happened"
+ (is (t2/exists? :model/CardBookmark :card_id card-id :user_id (mt/user->id :rasta)))))
+ (testing "un-bookmarking degrades the same way"
+ (let [result (tool-result (call-tool! :rasta #{metabot.scope/agent-content-write}
+ {:type "question" :id card-id :bookmarked false}))]
+ (is (= #{:id :note :bookmarked} (set (keys result))))
+ (is (false? (:bookmarked result)))
+ (is (not (t2/exists? :model/CardBookmark :card_id card-id :user_id (mt/user->id :rasta))))))
+ (testing "a token that could read the item back keeps the full echo"
+ (is (=? {:type "question" :id card-id :name "Salaries by employee" :bookmarked true}
+ (tool-result (call-tool! :rasta #{metabot.scope/agent-content-write
+ metabot.scope/agent-content-read}
+ {:type "question" :id card-id :bookmarked true}))))))))
diff --git a/test/metabase/mcp/v2/tools/browse_test.clj b/test/metabase/mcp/v2/tools/browse_test.clj
new file mode 100644
index 00000000000..82ce377b4dd
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/browse_test.clj
@@ -0,0 +1,1161 @@
+(ns metabase.mcp.v2.tools.browse-test
+ "Contract tests for the v2 `browse_data` and `browse_collection` tools.
+
+ The `browse_collection` tests go through [[registry/call-tool]] — the real dispatch,
+ including null-stripping, schema validation, and teaching-error conversion — and assert on
+ the response the model actually receives. Nothing reaches into the tool's internals except
+ the two threshold constants, which are rebound small so a handful of temp collections can
+ exercise the cap and budget paths.
+
+ Items-mode behaviour that is really `collection-children` behaviour — sorting, pinned
+ state, model filtering, archived semantics — is covered by
+ [[metabase.collections-rest.api-test]] and deliberately not duplicated here.
+
+ Fixtures are built outside [[metabase.test/with-test-user]] on purpose: creating a
+ collection while a current user is bound writes a `CollectionPermissionGraphRevision` whose
+ id is `(inc (latest-id))`, which races under `^:parallel`. Only the tool call needs a user."
+ (:require
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.collections.models.collection :as collection]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.tools.browse :as tools.browse]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.models.interface :as mi]
+ [metabase.permissions.core :as perms]
+ [metabase.permissions.models.data-permissions :as data-perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+;;; ------------------------------------------------- helpers ------------------------------------------------------
+
+(defn- browse-as
+ "Call `browse_collection` as `user` (nil token-scopes bypasses the scope gate — this is an
+ internal caller). Returns `{:error <text>}` for a teaching error, else
+ `{:json <parsed> :line <steering line>}` — the success text is the JSON envelope optionally
+ followed by a newline and the line."
+ [user args]
+ (mt/with-test-user user
+ (let [{:keys [result error]} (registry/call-tool nil nil "browse_collection" args)
+ text (if error (:message error) (-> result :content first :text))]
+ (if (or error (:isError result))
+ {:error text}
+ (let [[body line] (str/split text #"\n" 2)]
+ {:json (json/decode+kw body) :line line})))))
+
+(defn- browse
+ "[[browse-as]] `:crowberto`."
+ [args]
+ (browse-as :crowberto args))
+
+(defn- parse-arg-value
+ [v]
+ (cond
+ (re-matches #"-?\d+" v) (parse-long v)
+ (str/starts-with? v "[") (json/decode v)
+ :else (str/replace v #"^\"|\"$" "")))
+
+(defn- marker->args
+ "Parse the call a truncation marker names into a `browse_collection` args map, e.g.
+
+ … 1 more under \"Finance\" — browse_collection(id: 7, mode: \"tree\")
+ => {:id 7 :mode \"tree\"}
+
+ Throws when the marker names no parseable call: a marker the model cannot act on is itself
+ the failure this suite is looking for."
+ [marker]
+ (let [argstr (or (second (re-find #"browse_collection\(([^)]*)\)" marker))
+ (throw (ex-info "marker names no parseable browse_collection call"
+ {:marker marker})))]
+ (into {}
+ (map (fn [pair]
+ (let [[k v] (str/split pair #":" 2)]
+ [(keyword (str/trim k)) (parse-arg-value (str/trim v))])))
+ ;; split on argument commas, not commas inside a [...] value
+ (str/split argstr #",\s*(?![^\[\]]*\])"))))
+
+(defn- tree-names
+ [node]
+ (into #{(:name node)} (mapcat tree-names) (:children node)))
+
+(defn- surfaced-names
+ "Every collection name a response surfaces, whichever mode produced it — so a test can follow
+ a marker without knowing which mode the marker names."
+ [{:keys [json]}]
+ (if (contains? json :data)
+ (into #{} (map :name) (:data json))
+ (tree-names json)))
+
+(defn- follow
+ "Make the call `marker` names and return its response."
+ [marker]
+ (browse (marker->args marker)))
+
+(defn- node-named
+ "Find the node named `nm` anywhere in a tree response."
+ [node nm]
+ (if (= (:name node) nm)
+ node
+ (some #(node-named % nm) (:children node))))
+
+;;; ---------------------------------------------- tree: markers ---------------------------------------------------
+;;; The threshold tests are not ^:parallel: with-redefs mutates vars other threads read.
+
+(deftest tree-cap-truncation-marker-advances-test
+ (testing (str "GHY-4139: when a node's children are trimmed by the per-node child cap, the "
+ "truncation marker must name a call that actually reaches the trimmed children. "
+ "Re-rooting the same tree call re-applies the cap and returns an identical page, "
+ "so the marker has to steer somewhere that pages.")
+ (with-redefs [tools.browse/tree-child-cap 2]
+ (mt/with-temp [:model/Collection p {:name "browse-cap-parent"}
+ :model/Collection _a {:name "browse-cap-a" :location (collection/children-location p)}
+ :model/Collection _b {:name "browse-cap-b" :location (collection/children-location p)}
+ :model/Collection _c {:name "browse-cap-c" :location (collection/children-location p)}]
+ (let [resp (browse {:id (:id p) :mode "tree"})
+ marker (-> resp :json :truncated)]
+ (testing "the cap trims the third child and marks the node"
+ (is (= 2 (count (-> resp :json :children))))
+ (is (some? marker))
+ (is (str/includes? marker "1 more")))
+ (testing "children come back in name order, so the trimmed child is the last one"
+ (is (= ["browse-cap-a" "browse-cap-b"]
+ (mapv :name (-> resp :json :children)))))
+ (testing "obeying the marker surfaces the trimmed child"
+ (is (contains? (surfaced-names (follow marker)) "browse-cap-c"))))))))
+
+(deftest tree-budget-truncation-marker-advances-test
+ (testing (str "a node left unexpanded because the total node budget ran out carries a marker; "
+ "re-rooting there resets the budget, so the marker advances")
+ (with-redefs [tools.browse/tree-node-budget 2]
+ (mt/with-temp [:model/Collection p {:name "browse-budget-parent"}
+ :model/Collection c1 {:name "browse-budget-a" :location (collection/children-location p)}
+ :model/Collection _g {:name "browse-budget-grandchild" :location (collection/children-location c1)}
+ :model/Collection _c2 {:name "browse-budget-b" :location (collection/children-location p)}]
+ (let [resp (browse {:id (:id p) :mode "tree"})
+ marker (:truncated (node-named (:json resp) "browse-budget-a"))]
+ (testing "the budget is spent on the two children, so the grandchild is not expanded"
+ (is (some? marker))
+ (is (not (contains? (surfaced-names resp) "browse-budget-grandchild"))))
+ (testing "obeying the marker surfaces the grandchild"
+ (is (contains? (surfaced-names (follow marker)) "browse-budget-grandchild"))))))))
+
+(deftest ^:parallel tree-depth-truncation-marker-advances-test
+ (testing "a node left unexpanded at the depth limit carries a marker; re-rooting there resets depth"
+ (mt/with-temp [:model/Collection p {:name "browse-depth-parent"}
+ :model/Collection c {:name "browse-depth-child" :location (collection/children-location p)}
+ :model/Collection _g {:name "browse-depth-grandchild" :location (collection/children-location c)}]
+ (let [resp (browse {:id (:id p) :mode "tree" :depth 1})
+ marker (:truncated (node-named (:json resp) "browse-depth-child"))]
+ (testing "depth 1 stops at the child"
+ (is (some? marker))
+ (is (not (contains? (surfaced-names resp) "browse-depth-grandchild"))))
+ (testing "obeying the marker surfaces the grandchild"
+ (is (contains? (surfaced-names (follow marker)) "browse-depth-grandchild")))))))
+
+;;; ---------------------------------------------- tree: shape -----------------------------------------------------
+
+(deftest ^:parallel tree-depth-expands-exactly-n-levels-test
+ (mt/with-temp [:model/Collection p {:name "browse-levels-parent"}
+ :model/Collection c {:name "browse-levels-child" :location (collection/children-location p)}
+ :model/Collection g {:name "browse-levels-grandchild" :location (collection/children-location c)}
+ :model/Collection _gg {:name "browse-levels-great" :location (collection/children-location g)}]
+ (testing "depth 2 (the default) expands two levels below the root node"
+ (let [names (surfaced-names (browse {:id (:id p) :mode "tree"}))]
+ (is (contains? names "browse-levels-grandchild"))
+ (is (not (contains? names "browse-levels-great")))))
+ (testing "depth 1 expands one"
+ (let [names (surfaced-names (browse {:id (:id p) :mode "tree" :depth 1}))]
+ (is (contains? names "browse-levels-child"))
+ (is (not (contains? names "browse-levels-grandchild")))))))
+
+(deftest tree-pulls-a-readable-collection-past-an-unreadable-ancestor-test
+ (testing "a collection the caller CAN read, nested under one they cannot, still appears — pulled up to its
+ nearest visible ancestor, the way `collections->tree` renders A > C when B is hidden. Grouping
+ children by their direct parent id would drop it from the tree entirely."
+ (mt/with-temp [:model/Collection top {:name "browse-vis-top"}
+ :model/Collection hidden {:name "browse-vis-hidden" :location (collection/children-location top)}
+ :model/Collection _deep {:name "browse-vis-deep" :location (collection/children-location hidden)}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) hidden)
+ (let [names (surfaced-names (browse-as :rasta {:id (:id top) :mode "tree" :depth 3}))]
+ (is (not (contains? names "browse-vis-hidden"))
+ "the unreadable collection itself stays out")
+ (is (contains? names "browse-vis-deep")
+ "but its readable child is surfaced under the nearest visible ancestor")))))
+
+(deftest ^:parallel tree-leaf-has-no-marker-test
+ (testing "a childless node reports empty children and carries no truncation marker"
+ (mt/with-temp [:model/Collection p {:name "browse-leaf-parent"}
+ :model/Collection _c {:name "browse-leaf-child" :location (collection/children-location p)}]
+ (let [leaf (node-named (:json (browse {:id (:id p) :mode "tree"})) "browse-leaf-child")]
+ (is (= [] (:children leaf)))
+ (is (not (contains? leaf :truncated)))))))
+
+(deftest ^:parallel tree-omits-archived-subcollections-test
+ (testing "archived subtrees never appear in a tree"
+ (mt/with-temp [:model/Collection p {:name "browse-arch-parent"}
+ :model/Collection _live {:name "browse-arch-live" :location (collection/children-location p)}
+ :model/Collection _dead {:name "browse-arch-archived"
+ :location (collection/children-location p)
+ :archived true}]
+ (let [names (surfaced-names (browse {:id (:id p) :mode "tree"}))]
+ (is (contains? names "browse-arch-live"))
+ (is (not (contains? names "browse-arch-archived")))))))
+
+(deftest ^:parallel tree-rejects-trash-test
+ (testing "the trash is items-only; tree mode teaches the way out"
+ (let [{:keys [error]} (browse {:id "trash" :mode "tree"})]
+ (is (some? error))
+ (is (str/includes? error "items")))))
+
+(deftest ^:parallel tree-rejects-archived-collection-test
+ (testing "an archived collection has no tree; the error names items mode"
+ (mt/with-temp [:model/Collection c {:name "browse-arch-root" :archived true}]
+ (let [{:keys [error]} (browse {:id (:id c) :mode "tree"})]
+ (is (some? error))
+ (is (str/includes? error "archived"))))))
+
+;;; -------------------------------------------- namespace handling ------------------------------------------------
+
+(deftest ^:parallel namespace-conflict-is-a-teaching-error-test
+ (testing "a real collection id carries its own namespace; a contradicting namespace arg names the actual one"
+ (mt/with-temp [:model/Collection snippets {:name "browse-ns-snippets" :namespace "snippets"}
+ :model/Collection content {:name "browse-ns-content"}]
+ (testing "asking for content on a snippets collection"
+ (let [{:keys [error]} (browse {:id (:id snippets) :namespace "content"})]
+ (is (some? error))
+ (is (str/includes? error "snippets"))))
+ (testing "asking for snippets on a content collection"
+ (let [{:keys [error]} (browse {:id (:id content) :namespace "snippets"})]
+ (is (some? error))
+ (is (str/includes? error "content")))))))
+
+(deftest ^:parallel namespace-content-equals-nil-test
+ (testing "\"content\" and an absent namespace mean the same partition, so neither errors"
+ (mt/with-temp [:model/Collection c {:name "browse-ns-default"}]
+ (is (nil? (:error (browse {:id (:id c) :namespace "content"}))))
+ (is (nil? (:error (browse {:id (:id c)})))))))
+
+;;; -------------------------------------------- argument validation -----------------------------------------------
+
+(deftest ^:parallel tree-mode-rejects-items-args-test
+ (mt/with-temp [:model/Collection c {:name "browse-args-tree"}]
+ (testing "one offending arg reads in the singular and names itself"
+ (let [{:keys [error]} (browse {:id (:id c) :mode "tree" :limit 10})]
+ (is (some? error))
+ (is (str/includes? error "`limit`"))
+ (is (str/includes? error "does not apply to tree mode"))))
+ (testing "several read in the plural"
+ (let [{:keys [error]} (browse {:id (:id c) :mode "tree" :limit 10 :offset 5})]
+ (is (some? error))
+ (is (str/includes? error "do not apply to tree mode"))))))
+
+(deftest ^:parallel items-mode-rejects-depth-test
+ (testing "depth shapes a tree; in items mode it teaches the mode switch"
+ (mt/with-temp [:model/Collection c {:name "browse-args-items"}]
+ (let [{:keys [error]} (browse {:id (:id c) :depth 3})]
+ (is (some? error))
+ (is (str/includes? error "`depth`"))
+ (is (str/includes? error "tree"))))))
+
+(deftest ^:parallel type-is-content-namespace-only-test
+ (testing "type filters content items; other namespaces return their own model plus subfolders"
+ (mt/with-temp [:model/Collection c {:name "browse-type-snippets" :namespace "snippets"}]
+ (let [{:keys [error]} (browse {:id (:id c) :type ["question"]})]
+ (is (some? error))
+ (is (str/includes? error "`type`"))))))
+
+;;; ------------------------------------------------ items mode ----------------------------------------------------
+
+(deftest ^:parallel items-snippets-namespace-paging-test
+ (testing (str "collection-children skips server-side paging for snippets-namespace collections "
+ "and returns every row, so the tool slices the page itself — limit/offset must "
+ "still be honoured on that path")
+ (mt/with-temp [:model/Collection c {:name "browse-page-snippets" :namespace "snippets"}
+ :model/NativeQuerySnippet _1 {:collection_id (:id c) :name "browse-page-snip-a"}
+ :model/NativeQuerySnippet _2 {:collection_id (:id c) :name "browse-page-snip-b"}
+ :model/NativeQuerySnippet _3 {:collection_id (:id c) :name "browse-page-snip-c"}]
+ (let [page1 (browse {:id (:id c) :limit 2 :offset 0})
+ page2 (browse {:id (:id c) :limit 2 :offset 2})]
+ (testing "the limit is honoured rather than returning every row"
+ (is (= 2 (count (-> page1 :json :data))))
+ (is (= 2 (-> page1 :json :returned))))
+ (testing "the offset advances rather than repeating the first page"
+ (is (not= (surfaced-names page1) (surfaced-names page2))))))))
+
+(deftest ^:parallel items-envelope-and-projection-test
+ (mt/with-temp [:model/Collection p {:name "browse-proj-parent"}
+ :model/Collection _c {:name "browse-proj-child" :location (collection/children-location p)}]
+ (testing "the envelope carries data, returned, and a total"
+ (let [{:keys [json]} (browse {:id (:id p)})]
+ (is (= 1 (:returned json)))
+ (is (= 1 (:total json)))
+ (is (= ["browse-proj-child"] (mapv :name (:data json))))))
+ (testing "concise (the default) omits the detailed-only keys"
+ (let [row (-> (browse {:id (:id p)}) :json :data first)]
+ (is (not (contains? row :entity_id)))
+ (is (not (contains? row :location)))))
+ (testing "detailed adds them"
+ (let [row (-> (browse {:id (:id p) :response_format "detailed"}) :json :data first)]
+ (is (contains? row :entity_id))
+ (is (contains? row :location))))
+ (testing "fields picks dot-paths from the detailed shape"
+ (let [row (-> (browse {:id (:id p) :fields ["name" "entity_id"]}) :json :data first)]
+ (is (= #{:name :entity_id} (set (keys row))))))
+ (testing "fields and response_format are mutually exclusive"
+ (is (some? (:error (browse {:id (:id p) :fields ["name"] :response_format "detailed"})))))))
+
+(deftest ^:parallel items-truncation-line-test
+ (mt/with-temp [:model/Collection p {:name "browse-line-parent"}
+ :model/Collection _a {:name "browse-line-a" :location (collection/children-location p)}
+ :model/Collection _b {:name "browse-line-b" :location (collection/children-location p)}]
+ (testing "a truncated content-namespace page steers with `type`"
+ (let [{:keys [line]} (browse {:id (:id p) :limit 1})]
+ (is (some? line))
+ (is (str/includes? line "`type`"))
+ (is (str/includes? line "offset: 1"))
+ (testing "and says how many rows it actually returned — a missing `:returned` renders the count
+ as the literal \"null\", since java.util.Formatter prints that for a nil %d"
+ (is (str/includes? line "Returned 1 of 2"))
+ (is (not (str/includes? line "null"))))))
+ (testing "a complete page carries no steering line"
+ (is (nil? (:line (browse {:id (:id p) :limit 50})))))))
+
+;;; ------------------------------------------- items: created_by --------------------------------------------------
+
+(deftest ^:parallel items-created-by-me-filters-to-current-user-test
+ (testing "GHY-4139: created_by \"me\" returns only the items the calling user created"
+ (mt/with-temp [:model/Collection p {:name "browse-creator-parent"}
+ :model/Dashboard _mine {:name "browse-creator-mine" :collection_id (:id p)
+ :creator_id (mt/user->id :crowberto)}
+ :model/Dashboard _theirs {:name "browse-creator-theirs" :collection_id (:id p)
+ :creator_id (mt/user->id :rasta)}]
+ (let [names (surfaced-names (browse {:id (:id p) :created_by "me"}))]
+ (is (contains? names "browse-creator-mine"))
+ (is (not (contains? names "browse-creator-theirs")))))))
+
+(deftest ^:parallel items-created-by-composes-with-type-test
+ (testing "GHY-4139: created_by composes with type — only the caller's items of that type"
+ (mt/with-temp [:model/Collection p {:name "browse-creator-type-parent"}
+ :model/Dashboard _mine {:name "browse-creator-type-mine-dash" :collection_id (:id p)
+ :creator_id (mt/user->id :crowberto)}
+ :model/Document _minedoc {:name "browse-creator-type-mine-doc" :collection_id (:id p)
+ :creator_id (mt/user->id :crowberto)}
+ :model/Dashboard _theirs {:name "browse-creator-type-theirs-dash" :collection_id (:id p)
+ :creator_id (mt/user->id :rasta)}]
+ (let [names (surfaced-names (browse {:id (:id p) :created_by "me" :type ["dashboard"]}))]
+ (testing "the caller's dashboard survives both filters"
+ (is (contains? names "browse-creator-type-mine-dash")))
+ (testing "the caller's document is dropped by `type`"
+ (is (not (contains? names "browse-creator-type-mine-doc"))))
+ (testing "another user's dashboard is dropped by `created_by`"
+ (is (not (contains? names "browse-creator-type-theirs-dash"))))))))
+
+(deftest items-created-by-me-is-per-caller-test
+ ;; grants read on a shared collection to all users, mutating global perms rows — not ^:parallel
+ (testing "GHY-4139: \"me\" resolves to the calling user, so one user's items never show for another"
+ (mt/with-temp [:model/Collection p {:name "browse-creator-x-parent"}
+ :model/Dashboard _crow {:name "browse-creator-x-crow" :collection_id (:id p)
+ :creator_id (mt/user->id :crowberto)}
+ :model/Dashboard _rasta {:name "browse-creator-x-rasta" :collection_id (:id p)
+ :creator_id (mt/user->id :rasta)}]
+ (perms/grant-collection-read-permissions! (perms-group/all-users) (:id p))
+ (testing "crowberto sees only their own"
+ (let [names (surfaced-names (browse-as :crowberto {:id (:id p) :created_by "me"}))]
+ (is (contains? names "browse-creator-x-crow"))
+ (is (not (contains? names "browse-creator-x-rasta")))))
+ (testing "rasta sees only their own — the same call, a different caller"
+ (let [names (surfaced-names (browse-as :rasta {:id (:id p) :created_by "me"}))]
+ (is (contains? names "browse-creator-x-rasta"))
+ (is (not (contains? names "browse-creator-x-crow"))))))))
+
+(deftest ^:parallel tree-mode-rejects-created-by-test
+ (testing "GHY-4139: created_by is an item filter; tree mode rejects it with a teaching error"
+ (mt/with-temp [:model/Collection c {:name "browse-creator-tree"}]
+ (let [{:keys [error]} (browse {:id (:id c) :mode "tree" :created_by "me"})]
+ (is (some? error))
+ (is (str/includes? error "`created_by`"))
+ (is (str/includes? error "does not apply to tree mode"))))))
+
+;;; ------------------------------------------------ resolution ----------------------------------------------------
+
+(deftest ^:parallel unreadable-collection-is-not-an-existence-oracle-test
+ (testing "a collection that exists but is unreadable reports the same not-found as one that never existed"
+ (mt/with-temp [:model/Collection c {:name "browse-secret"
+ :location (collection/children-location
+ (collection/user->personal-collection
+ (mt/user->id :crowberto)))}]
+ (mt/with-test-user :rasta
+ (let [{:keys [result error]} (registry/call-tool nil nil "browse_collection" {:id (:id c)})
+ text (if error (:message error) (-> result :content first :text))]
+ (is (or error (:isError result)))
+ (is (str/includes? text "may not exist")))))))
+
+;;; ================================================ browse_data ===================================================
+
+(def ^:private byte-budget @#'tools.browse/get-fields-byte-budget)
+
+(defn- call!
+ "Invoke the tool handler and return `[envelope steering-line]` — the parsed JSON body and the
+ trailing steering sentence, which the handler appends to the text block after a newline."
+ [args]
+ (let [text (-> (tools.browse/browse-data args {}) :content first :text)
+ [body & rest*] (str/split-lines text)]
+ [(json/decode+kw body) (when (seq rest*) (str/join "\n" rest*))]))
+
+(defn- field-payload
+ "A field whose JSON encoding is at least `size` bytes."
+ [i size]
+ {:id i :name (str "field_" i) :description (apply str (repeat size \x))})
+
+(defn- table-payload
+ [id field-count field-size]
+ {:id id
+ :name (str "table_" id)
+ :fields (mapv #(field-payload % field-size) (range field-count))})
+
+;;; -------------------------------------------- Per-action validation ---------------------------------------------
+
+(deftest ^:parallel validate-args-for-action-required-test
+ (testing "GHY-4138: a missing required arg is a teaching error naming the arg, per action"
+ (are [action] (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"`database_id` is required for action"
+ (#'tools.browse/validate-args-for-action! {:action action}))
+ "list_schemas"
+ "list_tables"
+ "list_models")
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"`table_ids` is required for action get_fields\."
+ (#'tools.browse/validate-args-for-action! {:action "get_fields"})))))
+
+(deftest ^:parallel validate-args-for-action-rejects-inapplicable-test
+ (testing "GHY-4138: an arg belonging to another action is a teaching error naming the fix"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"`search` does not apply to action list_models — remove it\."
+ (#'tools.browse/validate-args-for-action! {:action "list_models" :database_id 1 :search "x"})))
+ (testing "several inapplicable args are listed together, sorted, with plural agreement"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"`schema`, `search` do not apply to action list_models — remove them\."
+ (#'tools.browse/validate-args-for-action! {:action "list_models" :database_id 1
+ :schema "s" :search "x"}))))
+ (testing "`fields`/`response_format` are rejected for list_schemas, which has no projection"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"`fields` does not apply to action list_schemas"
+ (#'tools.browse/validate-args-for-action! {:action "list_schemas" :database_id 1
+ :fields ["name"]}))))))
+
+(deftest ^:parallel validate-args-for-action-accepts-documented-args-test
+ (testing "GHY-4138: each action accepts every arg its schema documents for it"
+ (are [args] (nil? (#'tools.browse/validate-args-for-action! args))
+ {:action "list_databases" :limit 10 :offset 0 :response_format "detailed"}
+ {:action "list_databases" :fields ["name"]}
+ {:action "list_schemas" :database_id 1 :include_hidden true :limit 5 :offset 5}
+ {:action "list_tables" :database_id 1 :schema "public" :search "x" :fields ["name"]}
+ {:action "list_tables" :database_id 1 :include_hidden true :limit 1 :offset 2
+ :response_format "concise"}
+ {:action "list_models" :database_id 1 :limit 5 :offset 0 :response_format "detailed"}
+ {:action "get_fields" :table_ids [1 2] :include_hidden true}
+ {:action "get_fields" :table_ids [1] :offset 10 :response_format "detailed"})))
+
+;;; ---------------------------------------------- get_fields guards -----------------------------------------------
+
+(deftest ^:parallel get-fields-guards-test
+ (testing "GHY-4138: get_fields rejects an empty id list rather than returning an empty response"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"`table_ids` must name at least one table\."
+ (#'tools.browse/get-fields {:action "get_fields" :table_ids []}))))
+ (testing "GHY-4138: the 20-id cap is a teaching error naming the count passed and the fix"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"`table_ids` accepts at most 20 ids per call — you passed 21; split the request\."
+ (#'tools.browse/get-fields {:action "get_fields" :table_ids (vec (range 1 22))}))))
+ (testing "GHY-4138: `offset` pages one table's fields, so it is meaningless across several"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"`offset` with get_fields pages the fields of one large table"
+ (#'tools.browse/get-fields {:action "get_fields" :table_ids [1 2] :offset 5})))))
+
+(deftest get-fields-dedups-table-ids-test
+ (testing "GHY-4138: duplicate table_ids are deduped before the guards run — the same id twice is
+ one table, so it does not trip the single-table `offset` rule or inflate the 20-id cap"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t :id} {:db_id db-id :schema "public" :name "orders"}
+ :model/Field _ {:table_id t :name "id" :base_type :type/Integer :position 0}
+ :model/Field _ {:table_id t :name "total" :base_type :type/Float :position 1}]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (testing "the same table twice with an explicit offset pages that one table, not rejected"
+ (let [[envelope] (call! {:action "get_fields" :table_ids [t t] :offset 1})]
+ (is (= [t] (map :id (:tables envelope))))
+ (is (= 2 (:total_fields (first (:tables envelope))))
+ "offset paging engaged on the single deduped table")))
+ (testing "repeated ids do not count toward the 20-id cap"
+ (let [[envelope] (call! {:action "get_fields" :table_ids (vec (repeat 25 t))})]
+ (is (= [t] (map :id (:tables envelope)))
+ "25 copies of one table is one table — served, not rejected as over the cap"))))))))
+
+;;; ------------------------------------------------ Byte budget ---------------------------------------------------
+
+(deftest ^:parallel assemble-tables-within-budget-test
+ (testing "GHY-4138: when every table fits, all are returned whole in request order"
+ (let [payloads [(table-payload 1 2 10) (table-payload 2 2 10) (table-payload 3 2 10)]]
+ (is (= {:tables payloads}
+ (#'tools.browse/assemble-tables payloads nil))))))
+
+(deftest ^:parallel assemble-tables-omits-whole-tables-past-budget-test
+ (testing "GHY-4138: tables past the byte budget are dropped whole, and the tables kept are a
+ prefix of the request — the caller names the dropped ones from its own source rows"
+ ;; ~62KB each: the first fits the 100KB budget, the second would blow it.
+ (let [payloads (mapv #(table-payload % 60 1000) [1 2 3])
+ {:keys [tables]} (#'tools.browse/assemble-tables payloads nil)]
+ (is (= [1] (map :id tables)))
+ (testing "the table that made the cut is whole, not truncated"
+ (is (= 60 (count (:fields (first tables)))))
+ (is (not (contains? (first tables) :total_fields))
+ "a whole table carries no slice bookkeeping")))))
+
+(deftest ^:parallel assemble-tables-oversized-first-table-slices-test
+ (testing "GHY-4138: one table larger than the whole budget degrades to a field slice, not an error"
+ (let [payloads [(table-payload 1 200 1000)]
+ {:keys [tables message]} (#'tools.browse/assemble-tables payloads nil)
+ table (first tables)]
+ (is (= 1 (count tables)))
+ (is (= 200 (:total_fields table)))
+ (is (= 0 (:offset table)))
+ (testing "the slice is cut to fit and steers to the next offset"
+ (is (< 0 (count (:fields table)) 200))
+ (is (re-find #"continue with `offset: \d+`\." message))))))
+
+(deftest ^:parallel assemble-tables-explicit-offset-slices-test
+ (testing "GHY-4138: an explicit offset pages one table's fields even when it would fit whole"
+ (let [{:keys [tables message]} (#'tools.browse/assemble-tables [(table-payload 1 3 10)] 1)
+ table (first tables)]
+ (is (= 1 (:offset table)))
+ (is (= 3 (:total_fields table)))
+ (is (= ["field_1" "field_2"] (map :name (:fields table))))
+ (is (nil? message) "the final page carries no continuation message"))))
+
+(deftest ^:parallel assemble-tables-empty-test
+ (testing "GHY-4138: no readable tables yields an empty result rather than entering the slice path"
+ (is (= {:tables []} (#'tools.browse/assemble-tables [] nil)))
+ (is (= {:tables []} (#'tools.browse/assemble-tables [] 0)))))
+
+(deftest ^:parallel slice-table-payload-always-advances-test
+ (testing "GHY-4138: a single field larger than the whole budget is still returned alone, so paging
+ can never stall"
+ (let [{:keys [payload message]}
+ (#'tools.browse/slice-table-payload
+ {:id 1 :name "t" :fields [(field-payload 0 (* 2 byte-budget)) (field-payload 1 10)]}
+ 0)]
+ (is (= 1 (count (:fields payload))))
+ (is (= 2 (:total_fields payload)))
+ (is (re-find #"continue with `offset: 1`\." message)))))
+
+(deftest ^:parallel slice-table-payload-message-names-table-test
+ (testing "GHY-4138: the continuation message names the table and its exact next offset"
+ (let [{:keys [payload message]}
+ (#'tools.browse/slice-table-payload (table-payload 7 200 1000) 0)]
+ (is (str/starts-with? message "table_7: "))
+ (is (re-find #"of 200 fields" message))
+ (testing "the named next offset is exactly the field count returned"
+ (is (re-find (re-pattern (str "continue with `offset: " (count (:fields payload)) "`"))
+ message))))))
+
+(deftest ^:parallel slice-table-payload-final-page-test
+ (testing "GHY-4138: the last page returns the remaining fields and no continuation message"
+ (let [{:keys [payload message]}
+ (#'tools.browse/slice-table-payload (table-payload 1 3 10) 2)]
+ (is (= ["field_2"] (map :name (:fields payload))))
+ (is (= 3 (:total_fields payload)))
+ (is (nil? message)))))
+
+(deftest get-fields-omitted-entries-name-tables-under-field-projection-test
+ (testing "GHY-4138: a budget-omitted table is named even when the `fields` projection drops `id`
+ and `name` from the payload — without a name the advice to request it separately is
+ unactionable"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t1 :id} {:db_id db-id :schema "public" :name "browse_budget_a"}
+ :model/Table {t2 :id} {:db_id db-id :schema "public" :name "browse_budget_b"}]
+ ;; ~84KB per table once projected down to `fields.name`: the first fits the budget whole, the
+ ;; second is dropped.
+ (t2/insert! :model/Field
+ (for [table-id [t1 t2]
+ i (range 400)]
+ {:table_id table-id
+ :name (str "col_" i "_" (apply str (repeat 190 \x)))
+ :base_type :type/Text
+ :database_type "TEXT"
+ :position i}))
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (let [text (-> (tools.browse/browse-data
+ {:action "get_fields" :table_ids [t1 t2] :fields ["fields.name"]}
+ {})
+ :content first :text)
+ envelope (json/decode+kw (first (str/split-lines text)))]
+ (is (= 1 (count (:tables envelope)))
+ "the byte budget dropped the second table")
+ (is (= [{:id t2
+ :name "browse_budget_b"
+ :reason "response budget — request in a separate call"}]
+ (:omitted envelope)))
+ (testing "and the identifiers survive serialization rather than rendering as JSON null"
+ (is (not (str/includes? text "\"id\":null")))
+ (is (not (str/includes? text "\"name\":null")))))
+ (testing "the concise projection, which keeps id and name in the payload, names them too"
+ (let [[envelope] (call! {:action "get_fields" :table_ids [t1 t2]})]
+ (is (= [t2] (map :id (:omitted envelope))))
+ (is (= ["browse_budget_b"] (map :name (:omitted envelope)))))))))))
+
+;;; ------------------------------------------ Browsable-database filter -------------------------------------------
+
+(deftest list-databases-excludes-non-browsable-test
+ (testing "GHY-4138: list_databases hides databases no other listing shows — stubs (placeholders
+ for in-progress creation) and router destinations (browsed via their router), neither
+ of which `mi/can-read?` filters out"
+ (mt/with-temp [:model/Database {normal :id} {:name "Browse Normal DB"}
+ :model/Database {stub :id} {:name "Browse Stub DB" :is_stub true}
+ :model/Database {router :id} {:name "Browse Router Source"}
+ :model/Database {dest :id} {:name "Browse Router Dest" :router_database_id router}]
+ (mt/with-test-user :crowberto
+ (let [[envelope] (call! {:action "list_databases" :limit 500})
+ ids (set (map :id (:data envelope)))]
+ (is (contains? ids normal) "an ordinary database is listed")
+ (is (contains? ids router) "a router source database is listed")
+ (is (not (contains? ids stub)) "a stub database is hidden even from an admin")
+ (is (not (contains? ids dest)) "a router destination database is hidden even from an admin"))))))
+
+;;; --------------------------- Router-destination isolation (cross-database data access) -------------------------
+;;; Database routing is a multi-tenant boundary: a user browses a *router* database and their
+;;; queries are rerouted to their own *destination* database by user attribute. A destination
+;;; addressed directly — by database id or by a table id inside it — bypasses that boundary and can
+;;; return another tenant's data. The tool must refuse it. "Destination" is defined exactly as
+;;; `is-disallowed-destination-db-access?` in metabase-enterprise.database-routing.common defines
+;;; it: `router_database_id` non-null. The tool enforces this itself against the same filter
+;;; `list_databases` pages — it does NOT trust `schema-tables-list`/the metadata fetch to exclude
+;;; destinations — so these tests hold that line if those helpers ever change.
+
+(deftest browse-allows-router-blocks-destinations-test
+ (testing "GHY-4138: the router is browsable, but its destination databases are unreachable
+ directly through every action — and the caller here holds FULL data permissions, so the
+ refusal is provably the routing guard, not a permission failure"
+ (mt/with-temp [:model/Database {router :id} {:name "Sales Router"}
+ :model/Table {router-t :id} {:db_id router :schema "public" :name "router_orders"}
+ :model/Field _ {:table_id router-t :name "id"
+ :base_type :type/Integer :position 0}
+ ;; two tenants' destinations; tenant B holds data tenant A must never see
+ :model/Database {tenant-a :id} {:name "Tenant A DB" :router_database_id router}
+ :model/Database {tenant-b :id} {:name "Tenant B DB" :router_database_id router}
+ :model/Table {b-orders :id} {:db_id router :schema "public" :name "tenant_b_orders"}
+ :model/Field _ {:table_id b-orders :name "secret_amount"
+ :base_type :type/Float :position 0}
+ :model/Card _ {:name "Tenant B Model" :type :model
+ :database_id tenant-b :table_id b-orders}]
+ ;; The table is created on the router and moved: inserting it directly on a destination trips
+ ;; the after-insert permission grant, which destinations are forbidden to carry.
+ (t2/update! :model/Table b-orders {:db_id tenant-b})
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (is (mi/can-read? (t2/select-one :model/Database :id tenant-b))
+ "precondition: the caller CAN read the destination — so a refusal below is the routing
+ guard collapsing it into not-found, not an ordinary permission denial")
+ (testing "happy path — the router database is fully browsable"
+ (let [[dbs] (call! {:action "list_databases" :limit 500})
+ db-ids (set (map :id (:data dbs)))]
+ (is (contains? db-ids router) "the router is listed")
+ (is (not (contains? db-ids tenant-a)) "tenant A's destination is not listed")
+ (is (not (contains? db-ids tenant-b)) "tenant B's destination is not listed"))
+ (let [[tables] (call! {:action "list_tables" :database_id router :schema "public"})]
+ (is (= ["router_orders"] (map :name (:data tables))) "the router's tables list"))
+ (let [[envelope] (call! {:action "get_fields" :table_ids [router-t]})]
+ (is (= ["id"] (map :name (:fields (first (:tables envelope)))))
+ "the router's fields are served")))
+ (testing "adversarial — a directly-supplied destination id is refused across every action"
+ (are [action extra] (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"Database \d+ not found — it may not exist, or you may not have access to it\."
+ (tools.browse/browse-data (merge {:action action} extra) {}))
+ "list_schemas" {:database_id tenant-b}
+ "list_tables" {:database_id tenant-b :schema "public"}
+ "list_models" {:database_id tenant-b}))
+ (testing "adversarial — get_fields leaks nothing from a destination, even mixed with a
+ legitimate router table in the same request"
+ (let [[envelope] (call! {:action "get_fields" :table_ids [router-t b-orders]})]
+ (is (= [router-t] (map :id (:tables envelope)))
+ "only the router table is served")
+ (is (= [{:id b-orders
+ :reason "not found — it may not exist, or you may not have access to it"}]
+ (:omitted envelope))
+ "the destination table is collapsed into not-found, never expanded")
+ (is (not (str/includes? (json/encode envelope) "secret_amount"))
+ "the destination's column name never appears anywhere in the response"))))))))
+
+(deftest browse-refuses-stub-databases-test
+ (testing "GHY-4138: a stub database (a placeholder for in-progress creation) is unbrowsable the
+ same way, even if a table somehow exists under it"
+ (mt/with-temp [:model/Database {stub :id} {:name "Stub DB" :is_stub true}
+ :model/Table {stub-t :id} {:db_id stub :schema "public" :name "stub_orders"}]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"Database \d+ not found — it may not exist, or you may not have access to it\."
+ (tools.browse/browse-data {:action "list_tables" :database_id stub :schema "public"} {})))
+ (let [[envelope] (call! {:action "get_fields" :table_ids [stub-t]})]
+ (is (empty? (:tables envelope)))
+ (is (= [stub-t] (map :id (:omitted envelope))))))))))
+
+;;; ------------------------------------------- Permission filtering -----------------------------------------------
+;;; These mutate global permission rows via `with-no-data-perms-for-all-users!`, so they are not `^:parallel`.
+
+(deftest list-databases-permission-filtered-test
+ (testing "GHY-4138: list_databases returns only databases the caller can read"
+ (mt/with-temp [:model/Database {db-id :id} {:name "Browse Test DB"}
+ :model/Table {t-id :id} {:db_id db-id :schema "public" :name "t"}]
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (let [[envelope] (call! {:action "list_databases" :limit 500})]
+ (is (not (contains? (set (map :id (:data envelope))) db-id))
+ "a database the caller has no perms on is absent from the listing")))
+ (testing "an empty list says why — an unexplained empty envelope reads as `this instance
+ has no data`, and the caller stops instead of reporting the permission gap"
+ (mt/with-test-user :rasta
+ (let [[envelope hint] (call! {:action "list_databases" :limit 500})]
+ (is (zero? (:total envelope))
+ "with every database blocked, rasta sees none")
+ (is (= (str "No databases are visible to you. Browsing data needs query-builder "
+ "or table-metadata permission on at least one database.")
+ hint)))))
+ ;; Database visibility keys off create-queries, not view-data — see the `mi/can-read?`
+ ;; impl for :model/Database.
+ (data-perms/set-database-permission! (perms-group/all-users) db-id :perms/view-data :unrestricted)
+ (data-perms/set-table-permission! (perms-group/all-users) t-id :perms/create-queries :query-builder)
+ (mt/with-test-user :rasta
+ (let [[envelope] (call! {:action "list_databases" :limit 500})]
+ (is (contains? (set (map :id (:data envelope))) db-id)
+ "granting query-builder access makes it visible")))))))
+
+(deftest list-schemas-permission-filtered-test
+ (testing "GHY-4138: list_schemas returns only schemas the caller has some access to"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t1-id :id} {:db_id db-id :schema "readable"}
+ :model/Table _ {:db_id db-id :schema "secret"}]
+ (mt/with-no-data-perms-for-all-users!
+ (data-perms/set-database-permission! (perms-group/all-users) db-id :perms/view-data :unrestricted)
+ (data-perms/set-table-permission! (perms-group/all-users) t1-id :perms/create-queries :query-builder)
+ (mt/with-test-user :rasta
+ (let [[envelope] (call! {:action "list_schemas" :database_id db-id})]
+ (is (= ["readable"] (:data envelope)))
+ (is (= 1 (:total envelope)))))))))
+
+(deftest list-tables-schema-existence-collapse-test
+ (testing "GHY-4138: a schema that exists but is off-limits and one that was never there answer
+ identically, so listings never form an existence oracle across the permission boundary"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t1-id :id} {:db_id db-id :schema "readable"
+ :name "visible_table" :display_name "Visible Table"}
+ :model/Table _ {:db_id db-id :schema "secret"
+ :name "secret_table" :display_name "Secret Table"}]
+ (mt/with-no-data-perms-for-all-users!
+ (data-perms/set-database-permission! (perms-group/all-users) db-id :perms/view-data :unrestricted)
+ (data-perms/set-table-permission! (perms-group/all-users) t1-id :perms/create-queries :query-builder)
+ (mt/with-test-user :rasta
+ (testing "the readable schema lists its tables"
+ (let [[envelope] (call! {:action "list_tables" :database_id db-id :schema "readable"})]
+ (is (= ["visible_table"] (map :name (:data envelope))))))
+ (testing "the off-limits schema and the nonexistent one raise the same teaching error"
+ (are [schema] (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"not found in database \d+ — it may not exist, or you may not have access to it\."
+ (tools.browse/browse-data {:action "list_tables"
+ :database_id db-id
+ :schema schema}
+ {}))
+ "secret"
+ "no-such-schema")))))))
+
+(deftest list-tables-search-test
+ (testing "GHY-4138: `search` is a case-insensitive substring filter applied before paging"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table _ {:db_id db-id :schema "public" :name "orders" :display_name "Orders"}
+ :model/Table _ {:db_id db-id :schema "public" :name "order_items" :display_name "Order Items"}
+ :model/Table _ {:db_id db-id :schema "public" :name "people" :display_name "People"}]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (let [[envelope] (call! {:action "list_tables" :database_id db-id
+ :schema "public" :search "ORDER"})]
+ (is (= #{"orders" "order_items"} (set (map :name (:data envelope)))))
+ (is (= 2 (:total envelope))
+ "total reflects the filtered set, not the whole schema")))))))
+
+(deftest list-tables-search-matches-display-name-test
+ (testing "GHY-4138: `search` matches display_name as well as name — display_name is what an admin
+ edits when renaming a table, so it is the name the caller was shown"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ ;; renamed by an admin: display_name has diverged from the physical name
+ :model/Table _ {:db_id db-id :schema "public" :name "PEOPLE"
+ :display_name "Customers"}
+ :model/Table _ {:db_id db-id :schema "public" :name "orders"
+ :display_name "Orders"}
+ ;; display_name is nullable — the filter must not throw on it
+ :model/Table _ {:db_id db-id :schema "public" :name "legacy_log"
+ :display_name nil}]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (testing "the renamed table is findable by the display name"
+ (let [[envelope] (call! {:action "list_tables" :database_id db-id
+ :schema "public" :search "customer"})]
+ (is (= ["PEOPLE"] (map :name (:data envelope))))))
+ (testing "the physical name still matches"
+ (let [[envelope] (call! {:action "list_tables" :database_id db-id
+ :schema "public" :search "people"})]
+ (is (= ["PEOPLE"] (map :name (:data envelope))))))
+ (testing "a substring inside a display-name word matches, no word-start trick needed"
+ (let [[envelope] (call! {:action "list_tables" :database_id db-id
+ :schema "public" :search "ustom"})]
+ (is (= ["PEOPLE"] (map :name (:data envelope))))))
+ (testing "a null display_name neither throws nor matches"
+ (let [[envelope] (call! {:action "list_tables" :database_id db-id
+ :schema "public" :search "legacy"})]
+ (is (= ["legacy_log"] (map :name (:data envelope)))))))))))
+
+(deftest list-tables-paging-test
+ (testing "GHY-4138: limit/offset page the filtered set and steer with a truncation line"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table _ {:db_id db-id :schema "public" :name "t1" :display_name "A Table"}
+ :model/Table _ {:db_id db-id :schema "public" :name "t2" :display_name "B Table"}
+ :model/Table _ {:db_id db-id :schema "public" :name "t3" :display_name "C Table"}]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (let [[envelope line] (call! {:action "list_tables" :database_id db-id
+ :schema "public" :limit 2})]
+ (is (= 2 (:returned envelope)))
+ (is (= 3 (:total envelope)))
+ (is (= ["t1" "t2"] (map :name (:data envelope))))
+ (is (= "Returned 2 of 3 — narrow with `search`, or continue with `offset: 2`." line)))
+ (testing "the final page carries no steering line"
+ (let [[envelope line] (call! {:action "list_tables" :database_id db-id :schema "public"
+ :limit 2 :offset 2})]
+ (is (= 1 (:returned envelope)))
+ (is (= ["t3"] (map :name (:data envelope))))
+ (is (nil? line))))))))
+ (testing "GHY-4138: a truncated search already narrowed by `search` steers on offset only"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table _ {:db_id db-id :schema "public" :name "sales_a"}
+ :model/Table _ {:db_id db-id :schema "public" :name "sales_b"}
+ :model/Table _ {:db_id db-id :schema "public" :name "sales_c"}]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (let [[envelope line] (call! {:action "list_tables" :database_id db-id :schema "public"
+ :search "sales" :limit 2})]
+ (is (= 2 (:returned envelope)))
+ (is (= 3 (:total envelope)))
+ (is (re-find #"continue with `offset: 2`\." line))
+ (is (not (str/includes? line "narrow with `search`")))))))))
+
+(deftest list-models-test
+ (testing "GHY-4138: list_models returns the database's models and nothing else"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t-id :id} {:db_id db-id :schema "public" :name "orders"}
+ :model/Collection {c-id :id} {}
+ ;; every nilable column-backed key is populated, so `compact` drops nothing and
+ ;; a key absent below means the narrowed select failed to carry it
+ :model/Card _ {:name "Orders Model" :type :model
+ :database_id db-id :table_id t-id
+ :description "the orders model" :collection_id c-id
+ :collection_position 1 :cache_ttl 100
+ ;; a real query, so :query_type is populated too
+ :dataset_query {:database db-id :type :query
+ :query {:source-table t-id}}}
+ :model/Card _ {:name "Plain Question" :type :question
+ :database_id db-id :table_id t-id}]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :crowberto
+ (let [[envelope] (call! {:action "list_models" :database_id db-id})]
+ (is (= ["Orders Model"] (map :name (:data envelope)))
+ "plain questions are excluded — only :type :model")
+ (is (= 1 (:total envelope))))
+ (testing "list_models emits exactly the column-backed projection keys — one dropped from
+ the narrowed select would come back missing, one with no backing column would
+ surface as the SQL error the basic assertion catches, and no get_content
+ enrichment key leaks in"
+ (let [[envelope] (call! {:action "list_models" :database_id db-id
+ :response_format "detailed"})
+ row-keys (set (keys (first (:data envelope))))
+ col-keys (set (remove projections/question-enrichment-keys
+ projections/question-detailed-keys))]
+ ;; :dashboard_id and :source_card_id stay nil — a dashboard question and a sourced
+ ;; card are separate fixtures, and `compact` drops what the row doesn't carry.
+ (is (= (disj col-keys :dashboard_id :source_card_id) row-keys)
+ "every column-backed key survives the narrowed select, and nothing else appears")
+ (is (empty? (set/intersection row-keys projections/question-enrichment-keys))
+ "no enrichment key (query_summary/template_tags) leaks into a list_models row"))))))))
+
+(deftest list-models-permission-filtered-test
+ (testing "GHY-4138: list_models filters models by their parent collection's read perms, which
+ is why :collection_id has to survive the narrowed column select"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t-id :id} {:db_id db-id :schema "public" :name "orders"}
+ :model/Collection {open-id :id} {}
+ :model/Collection {closed-id :id} {}
+ :model/Card _ {:name "Open Model" :type :model :database_id db-id
+ :table_id t-id :collection_id open-id}
+ :model/Card _ {:name "Closed Model" :type :model :database_id db-id
+ :table_id t-id :collection_id closed-id}]
+ (mt/with-full-data-perms-for-all-users!
+ (perms/grant-collection-read-permissions! (perms-group/all-users) open-id)
+ (perms/revoke-collection-permissions! (perms-group/all-users) closed-id)
+ (mt/with-test-user :rasta
+ (let [[envelope] (call! {:action "list_models" :database_id db-id})]
+ (is (= ["Open Model"] (map :name (:data envelope))))
+ (is (= 1 (:total envelope))
+ "total counts the permission-filtered set, not every model on the database")))))))
+
+(deftest get-fields-missing-table-omitted-test
+ (testing "GHY-4138: an id that is absent or unreadable lands in :omitted with the collapsed
+ not-found reason rather than failing the whole call"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t-id :id} {:db_id db-id :schema "public"
+ :name "orders" :display_name "Orders"}
+ :model/Field _ {:table_id t-id :name "id" :base_type :type/Integer
+ :semantic_type :type/PK :position 0}]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (let [absent-id Integer/MAX_VALUE
+ [envelope] (call! {:action "get_fields" :database_id Integer/MAX_VALUE :table_ids [t-id absent-id]})]
+ (is (= [t-id] (map :id (:tables envelope)))
+ "the readable table still comes back whole")
+ (is (= ["id"] (map :name (:fields (first (:tables envelope))))))
+ (is (= [{:id absent-id
+ :reason "not found — it may not exist, or you may not have access to it"}]
+ (:omitted envelope)))))))))
+
+(deftest get-fields-database-not-found-collapse-test
+ (testing "GHY-4138: an unreadable database is reported exactly as a nonexistent one"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table _ {:db_id db-id :schema "public" :name "t"}]
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (are [id] (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"Database \d+ not found — it may not exist, or you may not have access to it\."
+ (tools.browse/browse-data {:action "list_schemas" :database_id id} {}))
+ db-id
+ Integer/MAX_VALUE))))))
+
+;;; ------------------------------ get_fields values require query permission ---------------------------------------
+
+(defn- get-fields-as
+ "Call `browse_data` as `user` and return the parsed JSON envelope (first line of the text block)."
+ [user args]
+ (mt/with-test-user user
+ (let [text (-> (tools.browse/browse-data args {}) :content first :text)]
+ (json/decode+kw (first (str/split-lines text))))))
+
+(defn- values-for
+ "The `:values` attached to the field with `field-id` in `envelope`, or nil if it carries none."
+ [envelope field-id]
+ (->> (:tables envelope) (mapcat :fields) (filter #(= field-id (:id %))) first :values))
+
+(defn- field-in
+ "The projected field map with `field-id` in `envelope`, or nil."
+ [envelope field-id]
+ (->> (:tables envelope) (mapcat :fields) (filter #(= field-id (:id %))) first))
+
+(deftest get-fields-values-require-query-permission-test
+ (testing "get_fields must not serve a column's values to a metadata-only caller"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t-id :id} {:db_id db-id :schema "public"
+ :name "orders" :active true}
+ :model/Field {f-id :id} {:table_id t-id :name "status"
+ :base_type :type/Text
+ :effective_type :type/Text
+ :has_field_values :list :active true}
+ :model/FieldValues _ {:field_id f-id :type :full
+ :values ["shipped" "pending" "cancelled"]}]
+ (mt/with-no-data-perms-for-all-users!
+ (data-perms/set-table-permission! (perms-group/all-users) t-id
+ :perms/manage-table-metadata :yes)
+ (testing "precondition — the fixture built the actor, not some other user"
+ (mt/with-test-user :rasta
+ (let [table (t2/select-one :model/Table :id t-id)]
+ (is (mi/can-read? table) "metadata permission alone satisfies can-read?")
+ (is (not (mi/can-query? table)) "...and does not satisfy can-query?"))))
+ (testing "the REST endpoint that serves these values refuses this caller"
+ (mt/user-http-request :rasta :get 403 (format "field/%d/values" f-id)))
+ (testing "so get_fields must refuse them too"
+ (let [envelope (get-fields-as :rasta {:action "get_fields" :table_ids [t-id]
+ :response_format "detailed"})]
+ (is (nil? (values-for envelope f-id))
+ "column values reached a caller who cannot query the table")))
+ (testing "only :values is withheld — the field's other detailed metadata still comes through"
+ (let [envelope (get-fields-as :rasta {:action "get_fields" :table_ids [t-id]
+ :response_format "detailed"})
+ field (field-in envelope f-id)]
+ (is (= [t-id] (map :id (:tables envelope)))
+ "the table itself is still readable and still listed")
+ (is (= #{:base_type :effective_type :database_type :has_field_values}
+ (set (keys (select-keys field [:base_type :effective_type
+ :database_type :has_field_values]))))
+ "the detailed field keys other than :values survive")))
+ (testing "a fields projection cannot route around the gate"
+ (let [envelope (get-fields-as :rasta {:action "get_fields" :table_ids [t-id]
+ :fields ["fields.name" "fields.values"]})]
+ (is (= ["status"] (mapcat #(map :name (:fields %)) (:tables envelope)))
+ "the projection still names the column")
+ (is (empty? (keep :values (mapcat :fields (:tables envelope))))
+ "column values reached a metadata-only caller through a fields projection")))
+ (testing "control — the probe can produce a positive, so the assertion above is not vacuous"
+ (data-perms/set-database-permission! (perms-group/all-users) db-id
+ :perms/view-data :unrestricted)
+ (data-perms/set-table-permission! (perms-group/all-users) t-id
+ :perms/create-queries :query-builder)
+ (mt/user-http-request :rasta :get 200 (format "field/%d/values" f-id))
+ (let [envelope (get-fields-as :rasta {:action "get_fields" :table_ids [t-id]
+ :response_format "detailed"})]
+ (is (some? (values-for envelope f-id))
+ "with query permission the same call does return values")))))))
+
+(deftest get-fields-values-gate-is-per-table-test
+ (testing "a batch mixing a queryable table with a metadata-only one gates each table on its own"
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {open-id :id} {:db_id db-id :schema "public"
+ :name "orders" :active true}
+ :model/Field {open-f :id} {:table_id open-id :name "status"
+ :base_type :type/Text
+ :has_field_values :list :active true}
+ :model/FieldValues _ {:field_id open-f :type :full
+ :values ["shipped" "pending"]}
+ :model/Table {meta-id :id} {:db_id db-id :schema "public"
+ :name "salaries" :active true}
+ :model/Field {meta-f :id} {:table_id meta-id :name "band"
+ :base_type :type/Text
+ :has_field_values :list :active true}
+ :model/FieldValues _ {:field_id meta-f :type :full
+ :values ["junior" "senior"]}]
+ (mt/with-no-data-perms-for-all-users!
+ (data-perms/set-database-permission! (perms-group/all-users) db-id
+ :perms/view-data :unrestricted)
+ (data-perms/set-table-permission! (perms-group/all-users) open-id
+ :perms/create-queries :query-builder)
+ (data-perms/set-table-permission! (perms-group/all-users) meta-id
+ :perms/manage-table-metadata :yes)
+ (let [envelope (get-fields-as :rasta {:action "get_fields" :table_ids [open-id meta-id]
+ :response_format "detailed"})]
+ (is (= #{open-id meta-id} (set (map :id (:tables envelope))))
+ "both tables are readable, so both are listed")
+ (is (some? (values-for envelope open-f))
+ "the queryable table keeps its values")
+ (is (nil? (values-for envelope meta-f))
+ "column values reached a caller who cannot query that table"))))))
+
+;;; ------------------------------------------ browse_data dispatch ------------------------------------------------
+;;; Everything above calls the handler directly. These go through [[registry/call-tool]] — the real
+;;; dispatch — so the scope gate, the `{:closed true}` args schema, and top-level nil-stripping are
+;;; all in play, and the assertions are on the response the model actually receives.
+
+(defn- dispatch-data
+ "Call `browse_data` through the registry as `:crowberto` carrying `token-scopes` (nil bypasses the
+ scope gate — this is an internal caller). Returns the whole dispatch outcome: `{:result <mcp
+ content>}` for anything that reached the handler, `{:error {:code .. :message ..}}` for a
+ registry-level rejection (unknown tool, scope denial, args-schema failure)."
+ [token-scopes args]
+ (mt/with-test-user :crowberto
+ (registry/call-tool token-scopes nil "browse_data" args)))
+
+(defn- dispatch-error?
+ "Whether a [[dispatch-data]] outcome is an error, at either layer."
+ [{:keys [result error]}]
+ (boolean (or error (:isError result))))
+
+(defn- dispatch-text
+ "[[dispatch-data]]'s text block, or a registry-level rejection's message."
+ [token-scopes args]
+ (let [{:keys [result error]} (dispatch-data token-scopes args)]
+ (if error (:message error) (-> result :content first :text))))
+
+(def ^:private content-read #{metabot.scope/agent-content-read})
+
+(deftest ^:parallel browse-data-scope-gating-test
+ (testing "GHY-4138: a token without the content-read scope is refused before dispatch"
+ ;; The message also names the required scope and the ones the token holds; asserted on the
+ ;; prefix here because the held set differs per case below.
+ (are [scopes] (str/starts-with? (dispatch-text scopes {:action "list_databases"})
+ "Insufficient scope to call tool: browse_data. Requires ")
+ #{metabot.scope/agent-query-run}
+ #{metabot.scope/agent-content-write}
+ #{}))
+ (testing "GHY-4138: the content-read scope, its wildcard, and an internal caller all reach the handler"
+ (are [scopes] (and (not (dispatch-error? (dispatch-data scopes {:action "list_databases"})))
+ (str/starts-with? (dispatch-text scopes {:action "list_databases"}) "{\"data\":"))
+ content-read
+ #{"agent:*"}
+ nil)))
+
+(deftest ^:parallel browse-data-tools-list-visibility-test
+ (testing "GHY-4138: tools/list visibility follows the same scope the call-time gate checks"
+ (is (some #(= "browse_data" (:name %)) (registry/list-tools content-read)))
+ (is (not (some #(= "browse_data" (:name %))
+ (registry/list-tools #{metabot.scope/agent-query-run}))))))
+
+(deftest ^:parallel browse-data-closed-schema-test
+ (testing "GHY-4138: malformed arguments come back as a teaching message from the closed args schema, never as an internal error"
+ (are [args expected] (let [outcome (dispatch-data content-read args)
+ text (dispatch-text content-read args)]
+ (and (dispatch-error? outcome)
+ (str/starts-with? text "Invalid arguments: ")
+ (str/includes? text expected)))
+ {:action "list_databases" :databse_id 1} "databse_id: disallowed key"
+ {:action "get_fields" :table_ids "7"} "table_ids: invalid type"
+ {:action "list_tables" :database_id (mt/id) :limit 9999} "should be at most 500"
+ {:action "list_tables" :database_id (mt/id) :limit 0} "should be at least 1"
+ {:action "list_fields"} "action: should be either")))
+
+(deftest ^:parallel browse-data-strips-top-level-nils-test
+ (testing (str "GHY-4138: a strict MCP client sends every declared property, nulling the ones it "
+ "does not populate — that call must be indistinguishable from the minimal one")
+ (let [table-id (mt/id :venues)]
+ (is (= (dispatch-data content-read {:action "get_fields" :table_ids [table-id]})
+ (dispatch-data content-read {:action "get_fields"
+ :table_ids [table-id]
+ :database_id nil
+ :schema nil
+ :search nil
+ :limit nil
+ :offset nil
+ :response_format nil
+ :fields nil
+ :include_hidden nil}))))))
+
+(deftest ^:parallel browse-data-nil-stripping-feeds-per-action-validation-test
+ (testing "GHY-4138: stripping runs before `validate-args-for-action!`, which is contains?-based, so a nulled key reads as absent"
+ (is (not (dispatch-error? (dispatch-data content-read {:action "list_databases" :database_id nil})))))
+ (testing "GHY-4138: the same key carrying a real value is still rejected as inapplicable"
+ (is (= "`database_id` does not apply to action list_databases — remove it."
+ (dispatch-text content-read {:action "list_databases" :database_id 1}))))
+ (testing "GHY-4138: and a required key sent as null reads as missing, not as present-and-empty"
+ (is (= "`table_ids` is required for action get_fields."
+ (dispatch-text content-read {:action "get_fields" :table_ids nil})))))
+
+(deftest ^:parallel browse-data-nested-nils-are-not-stripped-test
+ (testing "GHY-4138: stripping is top-level only, so a null nested inside a value has to be caught by the schema rather than reaching the handler"
+ (are [args expected] (let [text (dispatch-text content-read args)]
+ (and (str/starts-with? text "Invalid arguments: ")
+ (str/includes? text expected)))
+ {:action "get_fields" :table_ids [nil]} "table_ids: [0] should be an integer"
+ {:action "get_fields" :table_ids [8 nil]} "[1] should be an integer"
+ {:action "get_fields" :fields [nil]} "fields: [0] should be a string")))
diff --git a/test/metabase/mcp/v2/tools/collection_test.clj b/test/metabase/mcp/v2/tools/collection_test.clj
new file mode 100644
index 00000000000..76bb9e33234
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/collection_test.clj
@@ -0,0 +1,488 @@
+(ns metabase.mcp.v2.tools.collection-test
+ "Contract tests for the `collection_write` v2 MCP tool (GHY-4148), driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised for
+ free. Collection domain semantics (parent inheritance, descendant path rewriting, trash
+ mechanics, the permission predicates themselves) are owned by
+ `metabase.collections-rest.api-test` and the model tests; this suite pins the tool's contract
+ on top of them."
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.collections.models.collection :as collection]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the tool the assertions below drive, and the :collection projection its echo is built from.
+ [metabase.mcp.v2.tools.collection :as tools.collection]
+ [metabase.permissions.core :as perms]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(comment tools.collection/keep-me)
+
+;;; ------------------------------------------------- Harness ------------------------------------------------------
+
+(defn- call-tool!
+ "Drive `collection_write` as `user` (test-user keyword or user id) with bearer-style `scopes`
+ (nil = internal caller, which bypasses the scope gate)."
+ ([user args] (call-tool! user nil args))
+ ([user scopes args]
+ (mt/with-current-user (if (keyword? user) (mt/user->id user) user)
+ (registry/call-tool scopes nil "collection_write" args))))
+
+(defn- tool-result
+ "Decoded success payload of a tool response; throws when the call errored, so a tool-level
+ error can never masquerade as a result."
+ [{:keys [result error]}]
+ (when error
+ (throw (ex-info (str "tool call rejected: " (:message error)) {:error error})))
+ (when (:isError result)
+ (throw (ex-info (str "tool call failed: " (-> result :content first :text))
+ {:result result})))
+ (-> result :content first :text json/decode+kw))
+
+(defn- tool-error
+ "Tool-level error text of a tool response; throws when the call succeeded, so a passing call
+ can never satisfy an error assertion."
+ [{:keys [result error]}]
+ (cond
+ error (:message error)
+ (:isError result) (-> result :content first :text)
+ :else (throw (ex-info "expected a tool error, got success" {:result result}))))
+
+(defn- create!
+ "Create a collection through the tool as `user`, returning the echo payload."
+ [user args]
+ (tool-result (call-tool! user (merge {:method "create"} args))))
+
+;;; -------------------------------------------------- Create ------------------------------------------------------
+
+(deftest create-happy-path-test
+ (mt/with-model-cleanup [:model/Collection]
+ (let [payload (create! :crowberto {:name "Agent Collection" :description "made by an agent"})
+ coll (t2/select-one :model/Collection :id (:id payload))]
+ (testing "GHY-4218: the collection is really there, inside the caller's personal collection"
+ (is (= "Agent Collection" (:name coll)))
+ (is (= "made by an agent" (:description coll)))
+ (is (= (str "/" (:id (collection/user->personal-collection (mt/user->id :crowberto))) "/")
+ (:location coll)))
+ (is (false? (:archived coll))))
+ (testing "the echo is the concise read projection plus entity_id, url, and the two write args
+ the concise projection omits"
+ (is (= #{:id :name :description :location :archived :entity_id :url :authority_level :namespace}
+ (set (keys payload))))
+ (is (= (:entity_id coll) (:entity_id payload)))
+ (is (str/ends-with? (:url payload) (str "/collection/" (:id coll)))))
+ (testing "a plain collection echoes both as null rather than omitting them"
+ (is (nil? (:authority_level payload)))
+ (is (nil? (:namespace payload)))))))
+
+;; `echo-matches-concise-read-test` (the write echo vs a concise `get_content` read, plus its
+;; `echo-only-keys` helper) lives with the content tool PR — it needs
+;; `metabase.mcp.v2.tools.content`, which lands later in the stack.
+
+(deftest create-requires-name-test
+ (is (re-find #"`name` is required when method is \"create\""
+ (tool-error (call-tool! :crowberto {:method "create" :description "no name"})))))
+
+(deftest create-nests-under-parent-test
+ (mt/with-model-cleanup [:model/Collection]
+ (mt/with-temp [:model/Collection parent {:name "Parent"}]
+ (testing "a numeric parent_id nests"
+ (let [payload (create! :crowberto {:name "Child by id" :parent_id (:id parent)})]
+ (is (= (str "/" (:id parent) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id payload))))))
+ (testing "an entity_id parent_id nests identically"
+ (let [payload (create! :crowberto {:name "Child by eid" :parent_id (:entity_id parent)})]
+ (is (= (str "/" (:id parent) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id payload))))))
+ (testing "GHY-4218: parent_id \"root\" is the root collection — the only way to ask for it,
+ now that omitting parent_id means the caller's personal collection"
+ (let [payload (create! :crowberto {:name "Child at root" :parent_id "root"})]
+ (is (= "/" (t2/select-one-fn :location :model/Collection :id (:id payload))))))
+ (testing "GHY-4218: an omitted parent_id nests under the caller's personal collection"
+ (let [payload (create! :crowberto {:name "Child in personal"})]
+ (is (= (str "/" (:id (collection/user->personal-collection (mt/user->id :crowberto))) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id payload)))))))))
+
+(deftest create-accepts-namespace-test
+ (mt/with-model-cleanup [:model/Collection]
+ (testing "namespace puts the collection in an independent hierarchy (snippet folders)"
+ (let [payload (create! :crowberto {:name "Agent Snippet Folder" :namespace "snippets"})]
+ (is (= "snippets" (name (t2/select-one-fn :namespace :model/Collection :id (:id payload)))))
+ (testing "and the echo confirms it, so the agent needn't re-read to know it landed"
+ (is (= "snippets" (:namespace payload))))
+ (testing "GHY-4218: a namespaced collection still defaults to the root of its own hierarchy —
+ personal collections exist only in the default namespace, so there is none to
+ default into"
+ (is (= "/" (t2/select-one-fn :location :model/Collection :id (:id payload)))))))))
+
+(deftest create-accepts-transforms-namespace-test
+ (mt/with-model-cleanup [:model/Collection]
+ (testing "GHY-4516: transform folders are creatable — browse_collection browses the transforms
+ namespace and transform_write files a transform into a `collection_id`, so without this
+ the folders those two tools talk about could not be made through MCP at all"
+ (let [payload (create! :crowberto {:name "Rollups" :namespace "transforms"})]
+ (is (= "transforms" (name (t2/select-one-fn :namespace :model/Collection :id (:id payload)))))
+ (is (= "transforms" (:namespace payload)))
+ (testing "and lands at the root of the transforms tree, not in a personal collection"
+ (is (= "/" (t2/select-one-fn :location :model/Collection :id (:id payload)))))
+ (testing "a child nests under it and inherits the namespace from the parent"
+ (let [child (create! :crowberto {:name "Daily" :parent_id (:id payload)})]
+ (is (= (str "/" (:id payload) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id child))))
+ (is (= "transforms" (:namespace child)))))))))
+
+(deftest create-rejects-unknown-namespace-test
+ (mt/with-model-cleanup [:model/Collection]
+ (testing "GHY-4148: a mistyped namespace is rejected by the args schema rather than landing a
+ collection in a hierarchy nothing in Metabase surfaces — the echo would otherwise
+ confirm a `namespace` that took effect only in the sense that the row is unreachable"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto {:method "create"
+ :name "Typo Snippet Folder"
+ :namespace "snippet"}))
+ "Invalid arguments"))
+ (is (nil? (t2/select-one :model/Collection :name "Typo Snippet Folder"))))))
+
+(deftest create-rejects-update-only-args-test
+ (doseq [[k v] {:archived true :id 1}]
+ (testing (str "`" (name k) "` on create is a teaching error, not silently ignored")
+ (is (re-find (re-pattern (str "`" (name k) "` applies to method \"update\" only"))
+ (tool-error (call-tool! :crowberto {:method "create" :name "x" k v})))))))
+
+(deftest create-requires-write-perms-on-parent-test
+ (testing "a user with read but not write access to the parent is refused, and told why — they can
+ already see the collection, so the permission message leaks nothing"
+ (mt/with-non-admin-groups-no-collection-perms collection/root-collection
+ (mt/with-temp [:model/Collection parent {:name "Read-only shelf"}]
+ (perms/grant-collection-read-permissions! (perms/all-users-group) parent)
+ (is (re-find #"don't have permissions"
+ (tool-error (call-tool! :rasta {:method "create" :name "Snooping"
+ :parent_id (:id parent)})))))))
+ (testing "but can create inside their own"
+ (mt/with-model-cleanup [:model/Collection]
+ (let [personal-id (t2/select-one-fn :id :model/Collection :personal_owner_id (mt/user->id :rasta))
+ payload (create! :rasta {:name "Rasta's subfolder" :parent_id personal-id})]
+ (is (= (str "/" personal-id "/")
+ (t2/select-one-fn :location :model/Collection :id (:id payload))))))))
+
+(deftest create-unknown-parent-collapses-to-not-found-test
+ (testing "GHY-4148: parent_id must not become a collection-id enumeration oracle — a parent that
+ exists but the caller cannot see must give the same answer as one that does not exist.
+ POST /api/collection answers the same either way, because it reaches api/write-check
+ without a prior existence probe."
+ (mt/with-temp [:model/Collection coll {:name "Crowberto's personal subfolder"
+ :location (str "/" (t2/select-one-fn
+ :id :model/Collection
+ :personal_owner_id (mt/user->id :crowberto)) "/")}]
+ (let [nonexistent (tool-error (call-tool! :rasta {:method "create" :name "x" :parent_id 13371337}))
+ unreadable (tool-error (call-tool! :rasta {:method "create" :name "x" :parent_id (:id coll)}))]
+ (is (re-find #"not found" nonexistent))
+ (is (= (str/replace nonexistent "13371337" (str (:id coll)))
+ unreadable))))))
+
+;;; -------------------------------------------------- Update ------------------------------------------------------
+
+(deftest update-renames-test
+ (mt/with-temp [:model/Collection coll {:name "Before" :description "old"}]
+ (let [payload (tool-result (call-tool! :crowberto {:method "update" :id (:id coll)
+ :name "After" :description "new"}))]
+ (is (= "After" (:name payload)))
+ (is (= "After" (t2/select-one-fn :name :model/Collection :id (:id coll))))
+ (is (= "new" (t2/select-one-fn :description :model/Collection :id (:id coll)))))))
+
+(deftest update-moves-test
+ (mt/with-temp [:model/Collection parent {:name "New parent"}
+ :model/Collection coll {:name "Mover"}]
+ (testing "parent_id moves the collection"
+ (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :parent_id (:id parent)}))
+ (is (= (str "/" (:id parent) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id coll)))))
+ (testing "parent_id \"root\" moves it back out to the root"
+ (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :parent_id "root"}))
+ (is (= "/" (t2/select-one-fn :location :model/Collection :id (:id coll)))))))
+
+(deftest update-move-requires-write-perms-on-new-parent-test
+ (testing "moving needs write access to the destination, not just to the collection being moved —
+ the create path checks this, and the move path checks it separately"
+ (mt/with-non-admin-groups-no-collection-perms collection/root-collection
+ (mt/with-temp [:model/Collection coll {:name "Rasta's to move"
+ :location (str "/" (t2/select-one-fn
+ :id :model/Collection
+ :personal_owner_id (mt/user->id :rasta)) "/")}
+ :model/Collection destination {:name "Read-only shelf"}]
+ (perms/grant-collection-read-permissions! (perms/all-users-group) destination)
+ ;; Assert on the permission message, not merely that something failed: rasta can read both
+ ;; collections, so a not-found collapse here would mean the destination check had stopped
+ ;; running.
+ (is (re-find #"don't have permissions"
+ (tool-error (call-tool! :rasta {:method "update" :id (:id coll)
+ :parent_id (:id destination)}))))
+ (testing "and the collection stays put"
+ (is (not= (str "/" (:id destination) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id coll)))))))))
+
+(deftest update-rejects-archive-with-parent-id-test
+ (testing "archived: true combined with parent_id is a teaching error, not a silent partial move —
+ move-or-archive-collection-if-needed! is a condp that tests :archived first and returns,
+ so parent_id would otherwise be silently dropped on the way to the trash"
+ (mt/with-temp [:model/Collection parent {:name "Archive/2026"}
+ :model/Collection coll {:name "Q3 Planning"}]
+ (is (re-find #"`archived: true` and `parent_id` can't be combined"
+ (tool-error (call-tool! :crowberto {:method "update" :id (:id coll)
+ :archived true :parent_id (:id parent)}))))
+ (testing "and nothing happened — not archived, not moved"
+ (is (false? (t2/select-one-fn :archived :model/Collection :id (:id coll))))
+ (is (not= (str "/" (:id parent) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id coll))))))))
+
+(deftest update-restores-into-a-new-parent-test
+ (testing "archived: false with parent_id restores the collection somewhere new — the one path where
+ archive-or-unarchive-collection! consumes parent_id, rather than move-collection!"
+ (mt/with-temp [:model/Collection parent {:name "Somewhere else"}
+ :model/Collection coll {:name "Trashed then relocated"}]
+ (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :archived true}))
+ (is (true? (t2/select-one-fn :archived :model/Collection :id (:id coll))))
+ (let [payload (tool-result (call-tool! :crowberto {:method "update" :id (:id coll)
+ :archived false :parent_id (:id parent)}))]
+ (is (false? (:archived payload)))
+ (is (false? (t2/select-one-fn :archived :model/Collection :id (:id coll))))
+ (is (= (str "/" (:id parent) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id coll))))))))
+
+(deftest update-rejects-moving-a-trashed-collection-test
+ (testing "GHY-4148: parent_id on a trashed collection without archived: false is a teaching error, not a
+ silent wrong result — archive-collection! never rewrites :location, so the trash guards all read
+ false and the move goes through, leaving the collection in the trash while the echo reports the
+ new location"
+ (mt/with-temp [:model/Collection parent {:name "New home"}
+ :model/Collection coll {:name "Trashed mover"}]
+ (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :archived true}))
+ (let [location (t2/select-one-fn :location :model/Collection :id (:id coll))]
+ (is (re-find #"Pass `archived: false` alongside `parent_id`"
+ (tool-error (call-tool! :crowberto {:method "update" :id (:id coll)
+ :parent_id (:id parent)}))))
+ (testing "and the collection did not move"
+ (is (= location (t2/select-one-fn :location :model/Collection :id (:id coll))))
+ (is (true? (t2/select-one-fn :archived :model/Collection :id (:id coll)))))))))
+
+(deftest update-archives-and-restores-test
+ (mt/with-temp [:model/Collection coll {:name "Trashable"}]
+ (testing "archived: true trashes"
+ (let [payload (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :archived true}))]
+ (is (true? (:archived payload)))
+ (is (true? (t2/select-one-fn :archived :model/Collection :id (:id coll))))))
+ (testing "archived: false restores"
+ (let [payload (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :archived false}))]
+ (is (false? (:archived payload)))
+ (is (false? (t2/select-one-fn :archived :model/Collection :id (:id coll))))))))
+
+(deftest update-leaves-archived-alone-when-omitted-test
+ (testing "an update that doesn't mention archived must not resurrect a trashed collection — the REST
+ endpoint's schema defaults archived to false, and the tool must not inherit that"
+ (mt/with-temp [:model/Collection coll {:name "Stays trashed" :archived true}]
+ (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :name "Renamed in the trash"}))
+ (is (true? (t2/select-one-fn :archived :model/Collection :id (:id coll)))))))
+
+(deftest update-requires-id-test
+ (is (re-find #"`id` is required when method is \"update\""
+ (tool-error (call-tool! :crowberto {:method "update" :name "nope"})))))
+
+(deftest update-transforms-namespace-collection-test
+ (testing "GHY-4516: a transform folder renames and moves like any other collection — `namespace` is
+ create-only, so the row's own namespace is what decides which hierarchy the move happens in"
+ (mt/with-temp [:model/Collection parent {:name "Rollups" :namespace "transforms"}
+ :model/Collection coll {:name "Before" :namespace "transforms"}]
+ (let [payload (tool-result (call-tool! :crowberto {:method "update" :id (:id coll)
+ :name "After" :parent_id (:id parent)}))]
+ (is (= "After" (:name payload)))
+ (is (= "transforms" (:namespace payload)))
+ (is (= (str "/" (:id parent) "/")
+ (t2/select-one-fn :location :model/Collection :id (:id coll)))))
+ (testing "parent_id \"root\" moves it back to the root of the transforms tree, leaving the
+ namespace alone rather than dropping it into the content root"
+ (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :parent_id "root"}))
+ (is (= "/" (t2/select-one-fn :location :model/Collection :id (:id coll))))
+ (is (= :transforms (t2/select-one-fn :namespace :model/Collection :id (:id coll))))))))
+
+(deftest update-rejects-cross-namespace-move-test
+ (testing "GHY-4516: a transform folder cannot be moved into the content tree — namespaces are
+ independent hierarchies, and the model refuses rather than producing a folder whose
+ namespace disagrees with its parent's"
+ (mt/with-temp [:model/Collection content {:name "Content shelf"}
+ :model/Collection coll {:name "Transform folder" :namespace "transforms"}]
+ (is (re-find #"same namespace as its parent"
+ (tool-error (call-tool! :crowberto {:method "update" :id (:id coll)
+ :parent_id (:id content)}))))
+ (is (= "/" (t2/select-one-fn :location :model/Collection :id (:id coll)))))))
+
+(deftest update-rejects-namespace-test
+ (mt/with-temp [:model/Collection coll {:name "Fixed namespace"}]
+ (is (re-find #"`namespace` applies to method \"create\" only"
+ (tool-error (call-tool! :crowberto {:method "update" :id (:id coll) :namespace "snippets"}))))))
+
+(deftest update-by-entity-id-test
+ (mt/with-temp [:model/Collection coll {:name "By eid"}]
+ (tool-result (call-tool! :crowberto {:method "update" :id (:entity_id coll) :name "Renamed by eid"}))
+ (is (= "Renamed by eid" (t2/select-one-fn :name :model/Collection :id (:id coll))))))
+
+(deftest update-unknown-id-collapses-to-not-found-test
+ (testing "a nonexistent id and an unreadable one give the same answer"
+ (is (re-find #"not found" (tool-error (call-tool! :crowberto {:method "update" :id 13371337 :name "x"}))))
+ (mt/with-temp [:model/Collection coll {:name "Crowberto's personal subfolder"
+ :location (str "/" (t2/select-one-fn
+ :id :model/Collection
+ :personal_owner_id (mt/user->id :crowberto)) "/")}]
+ (is (re-find #"not found" (tool-error (call-tool! :rasta {:method "update" :id (:id coll) :name "x"})))))))
+
+(deftest invalid-method-test
+ (testing "an unknown method never reaches the handler — the args schema rejects it"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto {:method "delete" :id 1}))
+ "Invalid arguments"))))
+
+;;; --------------------------------------------- authority_level --------------------------------------------------
+
+(deftest authority-level-create-test
+ (mt/with-model-cleanup [:model/Collection]
+ (testing "an admin on an instance with the feature can create an official collection"
+ (mt/with-premium-features #{:official-collections}
+ (let [payload (create! :crowberto {:name "Official" :authority_level "official"})]
+ (is (= :official (t2/select-one-fn :authority_level :model/Collection :id (:id payload))))
+ (testing "and the echo confirms it"
+ (is (= "official" (:authority_level payload)))))))
+ (testing "without the feature it is refused"
+ (mt/with-premium-features #{}
+ (is (re-find #"paid feature"
+ (tool-error (call-tool! :crowberto {:method "create" :name "Not official"
+ :authority_level "official"}))))))
+ (testing "a non-admin is refused even with the feature"
+ (mt/with-premium-features #{:official-collections}
+ (let [personal-id (t2/select-one-fn :id :model/Collection :personal_owner_id (mt/user->id :rasta))]
+ (is (re-find #"don't have permissions"
+ (tool-error (call-tool! :rasta {:method "create" :name "Rasta official"
+ :parent_id personal-id
+ :authority_level "official"})))))))))
+
+(deftest authority-level-update-test
+ (testing "an admin on an instance with the feature can mark an existing collection official"
+ (mt/with-temp [:model/Collection coll {:name "To be blessed"}]
+ (mt/with-premium-features #{:official-collections}
+ (let [payload (tool-result (call-tool! :crowberto {:method "update" :id (:id coll)
+ :authority_level "official"}))]
+ (is (= :official (t2/select-one-fn :authority_level :model/Collection :id (:id coll))))
+ (testing "and the echo confirms it"
+ (is (= "official" (:authority_level payload))))))))
+ (testing "without the feature the change is refused"
+ (mt/with-temp [:model/Collection coll {:name "Stays plain"}]
+ (mt/with-premium-features #{}
+ (is (re-find #"paid feature"
+ (tool-error (call-tool! :crowberto {:method "update" :id (:id coll)
+ :authority_level "official"}))))
+ (is (nil? (t2/select-one-fn :authority_level :model/Collection :id (:id coll)))))))
+ (testing "re-sending the level a collection already has is a no-op, not a feature check"
+ (mt/with-temp [:model/Collection coll {:name "Already official" :authority_level "official"}]
+ (mt/with-premium-features #{}
+ (tool-result (call-tool! :crowberto {:method "update" :id (:id coll) :authority_level "official"}))
+ (is (= :official (t2/select-one-fn :authority_level :model/Collection :id (:id coll))))))))
+
+;;; --------------------------------------------------- Scopes -----------------------------------------------------
+
+(deftest scope-gating-test
+ (mt/with-model-cleanup [:model/Collection]
+ (testing "a bearer token without the write scope cannot call the tool at all"
+ (is (re-find #"^Insufficient scope to call tool: collection_write\."
+ (tool-error (call-tool! :crowberto #{"agent:content:read"} {:method "create" :name "x"})))))
+ (testing "the write scope creates"
+ (is (int? (:id (tool-result (call-tool! :crowberto #{"agent:content:write"}
+ {:method "create" :name "Scoped create"}))))))
+ (testing "the same scope updates — one scope covers both methods, so there is no second gate
+ between them and the call reaches the id lookup"
+ (is (re-find #"not found"
+ (tool-error (call-tool! :crowberto #{"agent:content:write"}
+ {:method "update" :id 13371337 :name "x"})))))
+ (testing "the v1 create scope does not reach this tool — it gates POST /api/agent/v1/collection,
+ and collection_write is not that endpoint"
+ (is (re-find #"^Insufficient scope to call tool: collection_write\."
+ (tool-error (call-tool! :crowberto #{"agent:collection:create"}
+ {:method "create" :name "x"})))))
+ ;; GHY-4225: the metabot permission wildcards no longer bear on v2 — in-app callers use
+ ;; the unrestricted sentinel and OAuth tokens draw scopes from the tool registry.
+ ))
+
+(deftest write-scope-grantable-test
+ (testing "GHY-4148: the scope the tool checks is advertised, so a token can actually be granted it"
+ (is (contains? (registry/registered-scopes) "agent:content:write"))))
+
+(deftest write-echo-degrades-without-read-scope-test
+ (testing "GHY-4148: a token holding the write scope but not `agent:content:read` gets only the
+ acknowledgement, never the row. Without this the write scope is a read oracle — a
+ rename that changes nothing would hand back the name, description, location, and
+ entity_id of a collection the token's read scopes deny. Dropping the `readback` call
+ from the tool, or widening its ack-keys, must fail here."
+ (mt/with-model-cleanup [:model/Collection]
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Secret Plans" :description "hush"}]
+ ;; Both methods go through the same `readback`, so a regression could land on either.
+ (doseq [[method args] [["create" {:method "create" :name "Write-only create"}]
+ ["update" {:method "update" :id coll-id :name "Write-only update"}]]]
+ (testing method
+ (let [payload (tool-result (call-tool! :crowberto #{"agent:content:write"} args))]
+ (is (= #{:id :url :note} (set (keys payload))))
+ (is (nil? (:name payload)))
+ (is (re-find #"agent:content:read" (:note payload))))))))
+ (testing "and the same call with read+write reads back in full, so a gate stuck on fails here too"
+ (mt/with-model-cleanup [:model/Collection]
+ (let [payload (tool-result (call-tool! :crowberto #{"agent:content:read" "agent:content:write"}
+ {:method "create" :name "Read-and-write create"}))]
+ (is (= #{:id :name :description :location :archived :entity_id :url :authority_level :namespace}
+ (set (keys payload)))))))))
+
+(deftest clear-unsets-description-and-authority-level-test
+ (testing "GHY-4191: `clear` unsets the properties `collection-write-entry` lists as `:clearable`.
+ A null cannot say \"clear this\" — strict clients fill every unset property with null and
+ the registry boundary strips them — so the explicit array is the only way to
+ erase one. Pinned because the tool description long claimed the opposite."
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Q3 Planning"
+ :description "Planning docs"}]
+ (testing "description clears"
+ (let [result (tool-result (call-tool! :crowberto {:method "update" :id coll-id
+ :clear ["description"]}))]
+ (is (nil? (:description result)) "the echo reports it unset")
+ (is (nil? (t2/select-one-fn :description :model/Collection :id coll-id))
+ "and it is unset in the database")))
+ (testing "a cleared property does not disturb the rest of the row"
+ (is (= "Q3 Planning" (t2/select-one-fn :name :model/Collection :id coll-id)))))))
+
+(deftest clear-unsets-authority-level-test
+ (testing "GHY-4191: authority_level is `:clearable` too — an Official collection can be made
+ unofficial again through the same array."
+ (mt/with-premium-features #{:official-collections}
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Official Docs" :authority_level "official"}]
+ (let [result (tool-result (call-tool! :crowberto {:method "update" :id coll-id
+ :clear ["authority_level"]}))]
+ (is (nil? (:authority_level result)) "the echo reports it unset")
+ (is (nil? (t2/select-one-fn :authority_level :model/Collection :id coll-id))
+ "and it is unset in the database"))))))
+
+(deftest numeric-string-ids-test
+ (testing "GHY-4498: clients that serialize an int-or-string param as a JSON string must still be
+ able to name a collection by its numeric id, on both `id` and `parent_id`"
+ (mt/with-model-cleanup [:model/Collection]
+ (mt/with-temp [:model/Collection {parent-id :id} {:name "String id parent"}
+ :model/Collection {coll-id :id} {:name "Renamed by string id"}]
+ (testing "`parent_id` as a numeric string nests under that collection"
+ (let [payload (create! :crowberto {:name "Child by string id" :parent_id (str parent-id)})]
+ (is (= (str "/" parent-id "/")
+ (t2/select-one-fn :location :model/Collection :id (:id payload))))))
+ (testing "`id` as a numeric string updates that collection"
+ (let [payload (tool-result (call-tool! :crowberto {:method "update" :id (str coll-id)
+ :name "Renamed"}))]
+ (is (= coll-id (:id payload)))
+ (is (= "Renamed" (t2/select-one-fn :name :model/Collection :id coll-id)))))
+ (testing "a string that only looks like an id is still an entity_id validation error"
+ (is (str/includes? (tool-error (call-tool! :crowberto {:method "update" :id "0" :name "x"}))
+ "entity_id")))))))
diff --git a/test/metabase/mcp/v2/tools/content_test.clj b/test/metabase/mcp/v2/tools/content_test.clj
new file mode 100644
index 00000000000..2d4336c5bad
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/content_test.clj
@@ -0,0 +1,1415 @@
+(ns metabase.mcp.v2.tools.content-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [clojure.walk :as walk]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.projections :as projections]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.tools.content :as tools.content]
+ [metabase.metrics.core :as metrics]
+ [metabase.notification.test-util :as notification.tu]
+ [metabase.test :as mt]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(comment tools.content/keep-me)
+
+(defn- call-content
+ "Invoke get_content through the registry — the same seam the JSON-RPC route uses, so scope
+ gating and argument validation are exercised. `token-scopes` of nil means an internal
+ caller, which satisfies every scope check."
+ ([args] (call-content nil args))
+ ([token-scopes args]
+ ;; `call-tool` answers `{:result …}` after dispatch, or `{:error …}` when the registry rejects
+ ;; the call before it. Present a rejection in the same `{:isError true}` shape a handler error
+ ;; takes, so the error-reading helpers below see both alike — the assertions here read the
+ ;; refusal text as a value, so a wrapper that threw would turn those into errors.
+ (let [{:keys [result error]} (registry/call-tool token-scopes "test-session" "get_content" args)]
+ (if error
+ {:isError true :content [{:type "text" :text (:message error)}]}
+ result))))
+
+(defn- content-results
+ "The `:results` vector from a successful get_content call. Throws when the call was rejected
+ before per-item work, so a tool-level error can never masquerade as an empty batch."
+ ([args] (content-results nil args))
+ ([token-scopes args]
+ (let [result (call-content token-scopes args)]
+ (when (:isError result)
+ (throw (ex-info (str "get_content returned a tool-level error: "
+ (-> result :content first :text))
+ {:result result})))
+ (:results (json/decode+kw (-> result :content first :text))))))
+
+(defn- content-one
+ ([args] (content-one nil args))
+ ([token-scopes args] (first (content-results token-scopes args))))
+
+(defn- content-error
+ "The tool-level error text for calls rejected before any per-item work."
+ ([args] (content-error nil args))
+ ([token-scopes args] (-> (call-content token-scopes args) :content first :text)))
+
+(defn- venues-query
+ "A Lib query over VENUES — a runnable `:dataset_query` for fixtures that only need the card to
+ have one."
+ []
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id :venues)))))
+
+(defn- venues-count-query
+ "[[venues-query]] aggregated to a single count, for fixtures that read as a scalar."
+ []
+ (lib/aggregate (venues-query) (lib/count)))
+
+(deftest get-content-question-concise-test
+ (testing "GHY-4140: a question read returns its concise projection with the type tag"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Venue Count"
+ :type :question
+ :display :scalar
+ :dataset_query (venues-count-query)}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "question" :id card-id}]})]
+ (is (nil? (:error row)))
+ (is (= "question" (:type row)))
+ (is (= card-id (:id row)))
+ (is (= "Venue Count" (:name row)))
+ (testing "concise omits the detailed-only columns"
+ (is (nil? (:entity_id row)))
+ (is (nil? (:created_at row)))))))))
+
+(defn- measure-definition
+ "A measure definition needs a real lib query against a synced table."
+ [aggregation-clause]
+ (let [mp (mt/metadata-provider)]
+ (-> (lib/query mp (lib.metadata/table mp (mt/id :venues)))
+ (lib/aggregate aggregation-clause))))
+
+(deftest get-content-per-type-happy-path-test
+ (testing "GHY-4140: each content type resolves by numeric id and returns a typed row"
+ (mt/with-test-user :crowberto
+ (testing "model"
+ (mt/with-temp [:model/Card {id :id} {:type :model :dataset_query (venues-query)}]
+ (let [row (content-one {:items [{:type "model" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= {:type "model" :id id} (select-keys row [:type :id]))))))
+ (testing "metric"
+ (mt/with-temp [:model/Card {id :id} {:type :metric
+ :dataset_query (venues-count-query)}]
+ (let [row (content-one {:items [{:type "metric" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= "metric" (:type row))))))
+ (testing "measure"
+ (mt/with-temp [:model/Measure {id :id} {:name "M1"
+ :table_id (mt/id :venues)
+ :creator_id (mt/user->id :rasta)
+ :definition (measure-definition (lib/count))}]
+ (let [row (content-one {:items [{:type "measure" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= "M1" (:name row))))))
+ (testing "segment"
+ (mt/with-temp [:model/Segment {id :id} {:name "S1" :table_id (mt/id :venues) :definition {}}]
+ (let [row (content-one {:items [{:type "segment" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= "S1" (:name row))))))
+ (testing "collection"
+ (mt/with-temp [:model/Collection {id :id} {:name "C1"}]
+ (let [row (content-one {:items [{:type "collection" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= "C1" (:name row))))))
+ (testing "snippet"
+ (mt/with-temp [:model/NativeQuerySnippet {id :id} {:name "snip"
+ :content "wow"
+ :creator_id (mt/user->id :lucky)}]
+ (let [row (content-one {:items [{:type "snippet" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= "wow" (:content row))))))
+ (testing "document returns the serialized Markdown body"
+ (mt/with-temp [:model/Document {id :id}
+ {:document {:type "doc"
+ :content [{:type "paragraph"
+ :content [{:type "text" :text "hello"}]}]}
+ :content_type "application/json+vnd.prose-mirror"}]
+ (let [row (content-one {:items [{:type "document" :id id}]})]
+ (is (nil? (:error row)))
+ (is (re-find #"hello" (:content_markdown row)))))))))
+
+(deftest get-content-dashboard-skeleton-test
+ (testing "GHY-4140: a dashboard returns the editing skeleton, never the raw REST dashcards array"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:parameters [{:name "Category" :slug "category"
+ :id "_CAT_" :type "category"}]}
+ :model/Card {card-id :id} {:name "Embedded"}
+ :model/DashboardTab {tab-id :id} {:dashboard_id dash-id :name "Tab 1" :position 0}
+ :model/DashboardCard {dc-id :id} {:dashboard_id dash-id
+ :card_id card-id
+ :dashboard_tab_id tab-id
+ :row 0
+ :col 0
+ :parameter_mappings [{:parameter_id "_CAT_"
+ :card_id card-id
+ :target [:dimension
+ [:field (mt/id :venues :name) nil]]}]}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "dashboard" :id dash-id}]})]
+ (is (nil? (:error row)))
+ (is (= [{:id tab-id :name "Tab 1"}] (:tabs row)))
+ (testing "each parameter names the dashcards it is wired to"
+ (let [expected [{:id "_CAT_" :name "Category" :type "category" :dashcard_ids [dc-id]}]]
+ (is (= expected (:parameters row)))
+ (is (= expected
+ (:parameters (content-one {:items [{:type "dashboard" :id dash-id}]
+ :include ["parameters"]}))))))
+ (testing "one summary row per dashcard, with the card reference resolved"
+ (is (= [{:id dc-id :kind "card" :card {:id card-id :name "Embedded"}
+ :dashboard_tab_id tab-id :row 0 :col 0}]
+ (mapv #(select-keys % [:id :kind :card :dashboard_tab_id :row :col])
+ (:dashcards row))))))))))
+
+(defn- dashcard-refs
+ "dashcard id -> its projected `:card` and `:series` references, for the redaction assertions."
+ [row]
+ (into {} (map (juxt :id #(select-keys % [:card :series]))) (:dashcards row)))
+
+(deftest get-content-dashboard-redacts-unreadable-cards-test
+ (testing "GHY-4219: a dashcard card and a series entry the caller cannot read collapse to an id
+ with no name. The redaction runs in the tool before the pure projection sees the row,
+ so this pins that get_content still applies it."
+ (mt/with-temp [:model/Collection {open-id :id} {}
+ :model/Collection {locked-id :id} {}
+ :model/Dashboard {dash-id :id} {:collection_id open-id}
+ :model/Card {open-card :id} {:name "Open" :collection_id open-id}
+ :model/Card {hidden-card :id} {:name "Hidden" :collection_id locked-id}
+ :model/Card {hidden-series :id} {:name "Hidden Series"
+ :collection_id locked-id}
+ :model/DashboardCard {open-dc :id} {:dashboard_id dash-id
+ :card_id open-card
+ :row 0 :col 0}
+ :model/DashboardCard {hidden-dc :id} {:dashboard_id dash-id
+ :card_id hidden-card
+ :row 1 :col 0}
+ :model/DashboardCardSeries _ {:dashboardcard_id open-dc
+ :card_id hidden-series
+ :position 0}]
+ (mt/with-non-admin-groups-no-collection-perms locked-id
+ (testing "an admin, who can read everything, sees every name"
+ (mt/with-test-user :crowberto
+ (let [refs (dashcard-refs (content-one {:items [{:type "dashboard" :id dash-id}]}))]
+ (is (= {:card {:id open-card :name "Open"}
+ :series [{:id hidden-series :name "Hidden Series"}]}
+ (get refs open-dc)))
+ (is (= {:card {:id hidden-card :name "Hidden"}}
+ (get refs hidden-dc))))))
+ (mt/with-test-user :rasta
+ (let [row (content-one {:items [{:type "dashboard" :id dash-id}]})
+ refs (dashcard-refs row)]
+ (is (nil? (:error row))
+ "the dashboard itself is readable — only the nested cards are not")
+ (testing "the readable card keeps its name"
+ (is (= {:id open-card :name "Open"} (:card (get refs open-dc)))))
+ (testing "the unreadable card is an id and nothing else"
+ (is (= {:id hidden-card} (:card (get refs hidden-dc)))))
+ (testing "and so is an unreadable series entry"
+ (is (= [{:id hidden-series}] (:series (get refs open-dc)))))))))))
+
+(defn- link-card-settings
+ "Stored `visualization_settings` for a link dashcard pointing at `model`/`id`, carrying the
+ cached entity name the frontend writes alongside the reference."
+ [model id cached-name]
+ {:virtual_card {:name nil :display "link" :visualization_settings {} :archived false}
+ :link {:entity {:model model :id id :name cached-name}}})
+
+(defn- layout-links
+ "dashcard id -> the `:link` visualization setting the `layout` include returns for it."
+ [dash-id]
+ (into {}
+ (map (juxt :id (comp :link :visualization_settings)))
+ (:dashcards (:layout (content-one {:items [{:type "dashboard" :id dash-id}]
+ :include ["layout"]})))))
+
+(deftest get-content-dashboard-layout-link-entity-test
+ (testing "GHY-4512: the layout include returns a link card's entity reference behind a read
+ check. Dropping it outright left an entity link reading back as `link: {}` —
+ indistinguishable from an empty card, and impossible to round-trip through
+ patch_dashcard."
+ (mt/with-temp [:model/Collection {locked-id :id} {}
+ :model/Dashboard {open-target :id} {:name "Open Target"}
+ :model/Dashboard {hidden-target :id} {:name "Hidden Target"
+ :collection_id locked-id}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard {open-dc :id} {:dashboard_id dash-id :row 0 :col 0
+ :visualization_settings
+ (link-card-settings "dashboard" open-target
+ "Stale Open Name")}
+ :model/DashboardCard {hidden-dc :id} {:dashboard_id dash-id :row 1 :col 0
+ :visualization_settings
+ (link-card-settings "dashboard" hidden-target
+ "SECRET-Hidden-Target")}
+ :model/DashboardCard {url-dc :id} {:dashboard_id dash-id :row 2 :col 0
+ :visualization_settings
+ {:virtual_card {:name nil
+ :display "link"
+ :visualization_settings {}
+ :archived false}
+ :link {:url "https://example.com"}}}]
+ (mt/with-non-admin-groups-no-collection-perms locked-id
+ (mt/with-test-user :rasta
+ (let [links (layout-links dash-id)]
+ (testing "a readable target reads back as the stored reference, the shape patch_dashcard takes verbatim"
+ (is (= {:entity {:model "dashboard" :id open-target}} (get links open-dc))))
+ (testing "an unreadable target is marked restricted rather than silently dropped"
+ (is (= {:entity {:restricted true}} (get links hidden-dc))))
+ (testing "the cached name stored beside the reference never rides along — no read check stands behind it"
+ (is (not (str/includes? (json/encode links) "Stale Open Name")))
+ (is (not (str/includes? (json/encode links) "SECRET-Hidden-Target"))))
+ (testing "a url link is untouched"
+ (is (= {:url "https://example.com"} (get links url-dc))))))))))
+
+(deftest query-summary-does-not-name-an-unreadable-source-card-test
+ (testing "GHY-4510: a readable wrapper's query_summary must not name a source card the caller cannot read"
+ (mt/with-temp [:model/Collection {locked-id :id} {:name "Project Falcon (confidential)"}
+ :model/Card {secret-id :id} {:collection_id locked-id
+ :name "SECRET-SourceCard-NORTHWIND"
+ :dataset_query (venues-query)}
+ :model/Card {wrapper-id :id} {:collection_id nil
+ :name "wrapper"
+ :dataset_query (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/card mp secret-id)))}]
+ (mt/with-non-admin-groups-no-collection-perms locked-id
+ (testing "the source card itself is denied outright"
+ (mt/with-test-user :rasta
+ (is (str/includes? (:error (content-one {:items [{:type "question" :id secret-id}]}))
+ "not found"))))
+ (testing "an admin, who can read the source, still gets a summary"
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "question" :id wrapper-id}]})]
+ (is (nil? (:error row)))
+ (is (some? (:query_summary row))))))
+ (mt/with-test-user :rasta
+ (let [row (content-one {:items [{:type "question" :id wrapper-id}]})]
+ (is (nil? (:error row))
+ "the wrapper is readable — only its source is not")
+ (testing "the restricted card's name is nowhere in the response"
+ (is (not (str/includes? (json/encode row) "SECRET-SourceCard-NORTHWIND"))))
+ (testing "the summary is withheld rather than rendered from unreadable metadata"
+ (is (nil? (:query_summary row))))))))))
+
+(deftest get-content-alert-test
+ (testing "GHY-4140: alert reads carry condition, schedule, and handlers"
+ (notification.tu/with-card-notification
+ [notification {:card {:dataset_query (venues-query)}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :subscriptions [{:type :notification-subscription/cron
+ :cron_schedule "0 0 0 * * ?"
+ :ui_display_type :cron/builder}]
+ :handlers [{:channel_type :channel/email
+ :recipients [{:type :notification-recipient/user
+ :user_id (mt/user->id :crowberto)}]}]}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "alert" :id (:id notification)}]})]
+ (is (nil? (:error row)))
+ (is (= "0 0 0 * * ?" (-> row :subscriptions first :cron_schedule)))
+ (is (= "channel/email" (-> row :handlers first :channel_type))))))))
+
+(deftest get-content-alert-strips-recipients-without-payload-read-test
+ (testing "GHY-4219: a caller who can read an alert only as its creator — not its card — gets
+ handlers with no recipients at all, the way /api/pulse redacts them. The strip runs in
+ the tool now, so this pins that get_content still applies it."
+ (mt/with-temp [:model/Collection {locked-id :id} {}]
+ (notification.tu/with-card-notification
+ [notification {:card {:collection_id locked-id}
+ :notification {:creator_id (mt/user->id :rasta)}
+ :handlers [{:channel_type :channel/email
+ :recipients [{:type :notification-recipient/user
+ :user_id (mt/user->id :crowberto)}]}]}]
+ (mt/with-non-admin-groups-no-collection-perms locked-id
+ (testing "an admin, who can read the card, sees the recipient list"
+ (mt/with-test-user :crowberto
+ (let [handler (-> (content-one {:items [{:type "alert" :id (:id notification)}]})
+ :handlers first)]
+ (is (= [(mt/user->id :crowberto)] (mapv :user_id (:recipients handler)))))))
+ (mt/with-test-user :rasta
+ (let [row (content-one {:items [{:type "alert" :id (:id notification)}]})]
+ (is (nil? (:error row))
+ "the creator can still read the alert itself")
+ (is (seq (:handlers row))
+ "the handler is still projected — only its recipients are withheld")
+ (is (not (contains? (-> row :handlers first) :recipients))
+ "the recipient list is gone entirely, not merely filtered to empty"))))))))
+
+(deftest get-content-alert-read-denial-test
+ (testing "GHY-4140: `mi/can-read?` in fetch-notification is the permission boundary for alerts — a caller
+ who is neither superuser, creator, nor recipient must get the not-found collapse, not the alert's
+ card_id, schedule and handlers. Every other alert test here reads as an admin or the creator, so
+ deleting that conjunct would leave the suite green."
+ (mt/with-temp [:model/Collection {locked-id :id} {}]
+ (notification.tu/with-card-notification
+ [notification {:card {:collection_id locked-id}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers [{:channel_type :channel/email
+ :recipients [{:type :notification-recipient/user
+ :user_id (mt/user->id :crowberto)}]}]}]
+ (mt/with-non-admin-groups-no-collection-perms locked-id
+ (mt/with-test-user :lucky
+ (let [row (content-one {:items [{:type "alert" :id (:id notification)}]})]
+ (is (some? (:error row))
+ "a caller with no relationship to the alert is refused")
+ (is (nil? (:handlers row))
+ "and gets none of its delivery configuration"))))))))
+
+(deftest get-content-subscription-pulse-test
+ (testing "GHY-4140: a live Pulse row reads as a subscription, with its channels and cards"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Sub Card"}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "subscription" :id pulse-id}]})]
+ (is (nil? (:error row)))
+ (is (= "Weekly" (:name row)))
+ (is (= dash-id (:dashboard_id row)))
+ (is (= [(mt/user->id :rasta)]
+ (keep :id (-> row :channels first :recipients)))))))))
+
+(deftest get-content-subscription-strips-sensitive-metadata-test
+ (testing "GHY-4219: a caller who can read a Pulse only as its creator, without collection read
+ perms, loses its cards and its channel recipient lists. The strip runs in the tool now,
+ so this pins that get_content still applies it."
+ (mt/with-temp [:model/Collection {locked-id :id} {}
+ :model/Card {card-id :id} {:name "Sub Card"}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Private Weekly"
+ :dashboard_id dash-id
+ :collection_id locked-id
+ :creator_id (mt/user->id :rasta)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :crowberto)}]
+ (mt/with-non-admin-groups-no-collection-perms locked-id
+ (testing "an admin, who has collection read perms, sees the cards and the recipients"
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "subscription" :id pulse-id}]})]
+ (is (= [card-id] (mapv :id (:cards row))))
+ (is (= [(mt/user->id :crowberto)]
+ (mapv :id (-> row :channels first :recipients)))))))
+ (mt/with-test-user :rasta
+ (let [row (content-one {:items [{:type "subscription" :id pulse-id}]})]
+ (is (nil? (:error row))
+ "the creator can still read the subscription itself")
+ (is (= "Private Weekly" (:name row)))
+ (is (nil? (:cards row))
+ "its cards are stripped")
+ (is (seq (:channels row))
+ "the channel is still projected — only its recipients are withheld")
+ (is (not (contains? (-> row :channels first) :recipients))
+ "and the channel recipient list is gone")))))))
+
+(deftest get-content-transform-test
+ (testing "GHY-4140: a transform read carries source type and target"
+ ;; The transform read-check gates on the transforms feature before the superuser bypass, so the
+ ;; feature and its setting must be on for the read to succeed — otherwise `can-read?` is false and
+ ;; the transform collapses to not-found. Enable them explicitly rather than inheriting ambient state.
+ (mt/with-premium-features #{:transforms-basic}
+ (mt/with-temp-env-var-value! [mb-transforms-enabled true]
+ (mt/with-temp [:model/Transform {id :id} {:name "t1"
+ :source {:type :query
+ :query {:database (mt/id)
+ :type "query"
+ :query {:source-table (mt/id :venues)}}}
+ :target {:type :table
+ :schema (t2/select-one-fn :schema :model/Table :id (mt/id :venues))
+ :name "t1_out"}}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "transform" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= "t1" (:name row)))
+ (is (= "t1_out" (-> row :target :name))))))))))
+
+(deftest get-content-resolves-entity-ids-test
+ (testing "GHY-4140: `id` takes a 21-character entity_id as well as a numeric id, for every type
+ carrying an entity_id column — the portable id a write echo hands back"
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "C1"}
+ :model/Card {card-id :id} {:name "Q1" :dataset_query (venues-query)}
+ :model/NativeQuerySnippet {snip-id :id} {:name "snip"
+ :content "wow"
+ :creator_id (mt/user->id :lucky)}
+ :model/Document {doc-id :id}
+ {:document {:type "doc"
+ :content [{:type "paragraph"
+ :content [{:type "text" :text "hello"}]}]}
+ :content_type "application/json+vnd.prose-mirror"}]
+ (mt/with-test-user :crowberto
+ (doseq [[type model id] [["collection" :model/Collection coll-id]
+ ["question" :model/Card card-id]
+ ["snippet" :model/NativeQuerySnippet snip-id]
+ ["document" :model/Document doc-id]]]
+ (testing type
+ (let [eid (t2/select-one-fn :entity_id model :id id)]
+ (is (= 21 (count eid)) "the fixture must actually carry an entity_id")
+ (let [row (content-one {:items [{:type type :id eid}]})]
+ (is (nil? (:error row)))
+ (is (= id (:id row)) "resolves to the row the numeric id returns")))))))))
+
+(deftest get-content-entity-id-teaching-errors-test
+ (testing "GHY-4140: a type with no entity_id column names the fix rather than collapsing to
+ not-found, and a string that is neither shape is rejected outright"
+ (notification.tu/with-card-notification
+ [notification {:card {:dataset_query (venues-query)}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers []}]
+ (mt/with-test-user :crowberto
+ (testing "alerts are numeric-only"
+ (is (re-find #"numeric id"
+ (:error (content-one {:items [{:type "alert"
+ :id "abcdefghijklmnopqrstu"}]})))))
+ (testing "and the alert still reads by its numeric id"
+ (is (nil? (:error (content-one {:items [{:type "alert" :id (:id notification)}]})))))
+ (testing "a string that is neither a numeric id nor an entity_id"
+ (is (re-find #"21-character entity_id"
+ (:error (content-one {:items [{:type "question" :id "nope"}]})))))))))
+
+(deftest get-content-transform-target-table-test
+ (testing "GHY-4140: `table` is the transform's target, hydrated with no permission check of its own
+ — `can-read?` on a Transform gates on the SOURCE tables only — so `fetch-transform`
+ re-checks it before returning it.
+
+ That gate's false branch is unreachable through permissions today, so there is no test
+ for it: reading a transform at all requires superuser or data analyst; superusers read
+ every table; and `table-permission-for-user` hands every data analyst
+ `manage-table-metadata :yes` unconditionally, which by itself satisfies `can-read?` on a
+ Table. The check is defence in depth for the day the transform read check widens. What
+ is reachable is covered here."
+ (mt/with-premium-features #{:transforms-basic}
+ (mt/with-temp-env-var-value! [mb-transforms-enabled true]
+ ;; Target an already-synced table rather than the usual nonexistent one, so `:table` actually
+ ;; hydrates and there is something to withhold. Source and target must differ: blocking the
+ ;; source would make the transform itself unreadable and prove nothing.
+ (mt/with-temp [:model/Transform {id :id}
+ {:name "t1"
+ :source {:type :query
+ :query {:database (mt/id)
+ :type "query"
+ :query {:source-table (mt/id :venues)}}}
+ :target {:type :table
+ :schema (t2/select-one-fn :schema :model/Table :id (mt/id :checkins))
+ :name (t2/select-one-fn :name :model/Table :id (mt/id :checkins))}}]
+ ;; `table` is a detailed-only key, so the gate only ever runs on a detailed read.
+ (testing "an admin, who can read the target, gets it"
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "transform" :id id}]
+ :response_format "detailed"})]
+ (is (nil? (:error row)))
+ (is (= (mt/id :checkins) (-> row :table :id))))))
+ (testing "and it is a detailed-only key, absent from a concise read"
+ (mt/with-test-user :crowberto
+ (is (nil? (:table (content-one {:items [{:type "transform" :id id}]})))))))))
+ (testing "a transform whose target table does not exist yet reads without a `table`"
+ (mt/with-premium-features #{:transforms-basic}
+ (mt/with-temp-env-var-value! [mb-transforms-enabled true]
+ (mt/with-temp [:model/Transform {id :id}
+ {:name "t2"
+ :source {:type :query
+ :query {:database (mt/id)
+ :type "query"
+ :query {:source-table (mt/id :venues)}}}
+ :target {:type :table
+ :schema (t2/select-one-fn :schema :model/Table :id (mt/id :venues))
+ :name "never_run_out"}}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "transform" :id id}]
+ :response_format "detailed"})]
+ (is (nil? (:error row)))
+ (is (= "t2" (:name row)))
+ (is (nil? (:table row)) "nothing to hydrate, so the section is omitted")))))))))
+
+(deftest get-content-not-found-is-not-an-existence-oracle-test
+ (testing "GHY-4140: a nonexistent id and an existing-but-unreadable id are indistinguishable,
+ so responses never form an existence oracle across the permission boundary"
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:collection_id coll-id
+ :dataset_query (venues-query)}]
+ (mt/with-non-admin-groups-no-collection-perms coll-id
+ (mt/with-test-user :rasta
+ (let [unreadable (:error (content-one {:items [{:type "question" :id card-id}]}))
+ missing (:error (content-one {:items [{:type "question" :id 999999999}]}))]
+ (is (some? unreadable))
+ (is (some? missing))
+ (testing "the two messages are identical apart from the id"
+ (is (= (str/replace unreadable (str card-id) "ID")
+ (str/replace missing "999999999" "ID"))))))))))
+
+(deftest get-content-fault-isolation-test
+ (testing "GHY-4140: one bad item becomes its own error object and the rest of the batch survives"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Good" :dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (let [rows (content-results {:items [{:type "question" :id card-id}
+ {:type "question" :id 999999999}]})]
+ (is (= 2 (count rows)))
+ (is (= "Good" (:name (first rows))))
+ (is (nil? (:error (first rows))))
+ (testing "the failing item names its type and id alongside the error"
+ (is (= {:type "question" :id 999999999} (select-keys (second rows) [:type :id])))
+ (is (some? (:error (second rows))))))))))
+
+(deftest get-content-item-error-is-judged-safe-test
+ (testing "GHY-4322: a per-item failure is judged by the same rule as a tool-level error — an
+ incidental exception (JDBC, library ex-info, NPE) becomes a generic internal error
+ instead of leaking driver or app-DB detail, while deliberately caller-facing errors
+ keep their full teaching message"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Good" :dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (mt/with-dynamic-fn-redefs [tools.content/fetch-measure-or-segment
+ (fn [& _]
+ (throw (ex-info "ERROR: relation \"report_card\" does not exist"
+ {:sql "SELECT * FROM report_card"})))]
+ (let [[leaky teaching good]
+ (content-results {:items [{:type "measure" :id 1}
+ {:type "question" :id 999999999}
+ {:type "question" :id card-id}]})]
+ (testing "the incidental exception's message never reaches the caller"
+ (is (= {:type "measure" :id 1} (select-keys leaky [:type :id])))
+ (is (= "Internal error" (:error leaky)))
+ (is (not (str/includes? (:error leaky) "report_card"))))
+ (testing "a teaching error still surfaces its full message"
+ (is (str/includes? (:error teaching) "not found")))
+ (testing "fault isolation survives: the good item is unaffected"
+ (is (= "Good" (:name good)))
+ (is (nil? (:error good))))))))))
+
+(deftest get-content-card-type-mismatch-test
+ (testing "GHY-4140: asking for a model with type question teaches the actual type"
+ (mt/with-temp [:model/Card {card-id :id} {:type :model :dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (let [error (:error (content-one {:items [{:type "question" :id card-id}]}))]
+ (is (some? error))
+ (is (re-find #"is a model" error))
+ (is (re-find #"type: \"model\"" error)))))))
+
+(deftest get-content-batch-cap-test
+ (testing "GHY-4140: the batch cap is a tool-level teaching error, not a silent truncation"
+ (mt/with-test-user :crowberto
+ (let [error (content-error {:items (vec (repeat 11 {:type "question" :id 1}))})]
+ (is (re-find #"at most 10" error))
+ (is (re-find #"you passed 11" error))))))
+
+(deftest get-content-reads-formerly-gated-types-test
+ (testing "GHY-4225: alerts, transforms, snippets and documents each used to need their own read
+ scope on top of the base one. Those folded into `agent:content:read`, so the single
+ scope now carries them — the per-type gate is gone, not merely renamed."
+ (testing "alert"
+ (notification.tu/with-card-notification
+ [notification {:card {:dataset_query (venues-query)}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers []}]
+ (mt/with-test-user :crowberto
+ (is (nil? (:error (content-one #{"agent:content:read"}
+ {:items [{:type "alert" :id (:id notification)}]})))))))
+ (testing "snippet, including its body"
+ (mt/with-temp [:model/NativeQuerySnippet {id :id} {:name "snip" :content "wow"
+ :creator_id (mt/user->id :lucky)}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one #{"agent:content:read"} {:items [{:type "snippet" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= "wow" (:content row)))))))
+ (testing "document, including its body"
+ (mt/with-temp [:model/Document {id :id}
+ {:document {:type "doc" :content [{:type "paragraph"
+ :content [{:type "text" :text "hello"}]}]}
+ :content_type "application/json+vnd.prose-mirror"}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one #{"agent:content:read"} {:items [{:type "document" :id id}]})]
+ (is (nil? (:error row)))
+ (is (re-find #"hello" (:content_markdown row)))))))
+ (testing "transform — `agent:transforms:read` is still declared, but this tool does not ask for it"
+ (mt/with-premium-features #{:transforms-basic}
+ (mt/with-temp-env-var-value! [mb-transforms-enabled true]
+ (mt/with-temp [:model/Transform {id :id} {:name "t1"
+ :source {:type :query
+ :query {:database (mt/id)
+ :type "query"
+ :query {:source-table (mt/id :venues)}}}
+ :target {:type :table
+ :schema (t2/select-one-fn :schema :model/Table :id (mt/id :venues))
+ :name "t1_out"}}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one #{"agent:content:read"} {:items [{:type "transform" :id id}]})]
+ (is (nil? (:error row)))
+ (is (= "t1" (:name row)))))))))))
+
+(defn- comment-content
+ [text]
+ {:type "doc"
+ :content [{:type "paragraph" :content [{:type "text" :text text}]}]})
+
+(def ^:private commented-doc
+ "Four top-level blocks with fixed node ids: a plain paragraph, a blockquote whose inner
+ paragraph has its own id (nested blocks carry no span of their own), an empty paragraph
+ (zero-width span), and a closing paragraph."
+ {:type "doc"
+ :content [{:type "paragraph" :attrs {"_id" "para-1"}
+ :content [{:type "text" :text "First paragraph."}]}
+ {:type "blockquote" :attrs {"_id" "quote-1"}
+ :content [{:type "paragraph" :attrs {"_id" "quote-para"}
+ :content [{:type "text" :text "Quoted text."}]}]}
+ {:type "paragraph" :attrs {"_id" "empty-1"}}
+ {:type "paragraph" :attrs {"_id" "para-2"}
+ :content [{:type "text" :text "Last paragraph."}]}]})
+
+(deftest get-content-document-comments-include-test
+ (testing "GHY-4159: the comments include anchors each thread to the exact markdown slice of its block"
+ (mt/with-temp [:model/Document {doc-id :id} {:document commented-doc
+ :content_type "application/json+vnd.prose-mirror"}
+ :model/Comment {root-id :id} {:target_id doc-id
+ :child_target_id "para-1"
+ :content (comment-content "make this punchier")}
+ :model/Comment {reply-id :id} {:target_id doc-id
+ :child_target_id "para-1"
+ :parent_comment_id root-id
+ :content (comment-content "agreed")}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "quote-para"
+ :content (comment-content "on a nested block")}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "empty-1"
+ :content (comment-content "on an empty paragraph")}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "para-2"
+ :is_resolved true
+ :content (comment-content "resolved note")}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "para-2"
+ :deleted_at :%now
+ :content (comment-content "deleted note")}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "gone-0000"
+ :content (comment-content "my block was rewritten")}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "document" :id doc-id}] :include ["comments"]})
+ markdown (:content_markdown row)
+ threads (:comments row)
+ by-id (into {} (map (juxt :child_target_id identity)) threads)]
+ (is (nil? (:error row)))
+ (testing "every live anchored thread is present, in document order"
+ (is (= ["para-1" "quote-para" "empty-1" "para-2"] (mapv :child_target_id threads))))
+ (testing "the anchor is the exact [start, end) slice of the commented block"
+ (let [{:keys [start end text]} (:anchor (by-id "para-1"))]
+ (is (= "First paragraph." text))
+ (is (= text (subs markdown start end)))))
+ (testing "threads are flat and ordered, replies carrying parent_comment_id"
+ (is (= [{:id root-id :text "make this punchier"}
+ {:id reply-id :parent_comment_id root-id :text "agreed"}]
+ (mapv #(select-keys % [:id :parent_comment_id :text])
+ (:thread (by-id "para-1"))))))
+ (testing "a comment on a block nested in a blockquote anchors to the outermost block's span"
+ (is (= "> Quoted text." (get-in (by-id "quote-para") [:anchor :text]))))
+ (testing "an empty paragraph is a legal zero-width anchor"
+ (let [{:keys [start end text]} (:anchor (by-id "empty-1"))]
+ (is (= start end))
+ (is (= "" text))))
+ (testing "is_resolved is surfaced and deleted comments are excluded"
+ (is (= [{:is_resolved true :text "resolved note"}]
+ (mapv #(select-keys % [:is_resolved :text]) (:thread (by-id "para-2"))))))
+ (testing "the creator is the user's display name"
+ (is (= "Rasta Toucan" (-> (by-id "para-1") :thread first :creator))))
+ (testing "a thread whose block no longer exists lands in orphaned_comments, text readable"
+ (is (= [{:child_target_id "gone-0000" :text "my block was rewritten"}]
+ (mapv #(assoc (select-keys % [:child_target_id])
+ :text (-> % :thread first :text))
+ (:orphaned_comments row))))))))))
+
+(def ^:private layout-commented-doc
+ "A layout container holding a list. `resizeNode`/`flexContainer` carry no `_id` at all, so a
+ block nested inside one has to resolve its anchor past them; the paragraph inside the list item
+ is the block with no span of its own — the list re-renders it with a `- ` prefix."
+ {:type "doc"
+ :content [{:type "resizeNode" :attrs {"height" 442 "minHeight" 280}
+ :content [{:type "flexContainer" :attrs {"columnWidths" [60 40]}
+ :content [{:type "supportingText" :attrs {"_id" "support-1"}
+ :content [{:type "bulletList" :attrs {"_id" "list-1"}
+ :content [{:type "listItem"
+ :content [{:type "paragraph" :attrs {"_id" "list-para"}
+ :content [{:type "text"
+ :text "Nested in a list."}]}]}]}]}
+ {:type "supportingText" :attrs {"_id" "support-2"}
+ :content [{:type "paragraph" :attrs {"_id" "support-para"}
+ :content [{:type "text" :text "Beside it."}]}]}]}]}
+ {:type "paragraph" :attrs {"_id" "tail"} :content [{:type "text" :text "Tail."}]}]})
+
+(deftest get-content-document-comments-inside-a-layout-container-test
+ (testing "a live comment inside a layout container is anchored, not reported orphaned — a block
+ with no span of its own rolls up to the nearest ancestor that has one, and the
+ id-less resizeNode/flexContainer wrappers in between must not break the chain"
+ (mt/with-temp [:model/Document {doc-id :id} {:document layout-commented-doc
+ :content_type "application/json+vnd.prose-mirror"}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "list-para"
+ :content (comment-content "on a list paragraph")}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "support-para"
+ :content (comment-content "on a supporting paragraph")}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "support-1"
+ :content (comment-content "on the supporting block")}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "gone-0000"
+ :content (comment-content "my block was rewritten")}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "document" :id doc-id}] :include ["comments"]})
+ markdown (:content_markdown row)
+ by-id (into {} (map (juxt :child_target_id identity)) (:comments row))]
+ (is (nil? (:error row)))
+ (testing "every block that still exists is anchored, whatever it is nested in"
+ (is (= #{"support-1" "list-para" "support-para"} (set (keys by-id)))))
+ (testing "a paragraph the list re-renders anchors to its list's span"
+ (is (= "- Nested in a list." (get-in (by-id "list-para") [:anchor :text]))))
+ (testing "a block that has its own span still uses it rather than an ancestor's"
+ (is (= "Beside it." (get-in (by-id "support-para") [:anchor :text])))
+ (is (str/starts-with? (get-in (by-id "support-1") [:anchor :text]) "::: supporting")))
+ (testing "every anchor is a true slice of the returned markdown"
+ (doseq [[id thread] by-id
+ :let [{:keys [start end text]} (:anchor thread)]]
+ (is (= text (subs markdown start end)) id)))
+ (testing "a thread whose block is genuinely gone is still orphaned"
+ (is (= ["gone-0000"] (mapv :child_target_id (:orphaned_comments row))))))))))
+
+(deftest get-content-document-comments-scope-and-batch-test
+ (mt/with-temp [:model/Document {doc-id :id} {:document commented-doc
+ :content_type "application/json+vnd.prose-mirror"}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "para-1"
+ :content (comment-content "hi")}
+ :model/Card {card-id :id} {:dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (testing "GHY-4159/GHY-4225: comment threads are document content, so the tool's own
+ agent:content:read carries them — they used to need agent:document:read on top,
+ and that per-type gate is gone rather than renamed"
+ (let [row (content-one #{"agent:content:read"}
+ {:items [{:type "document" :id doc-id}] :include ["comments"]})]
+ (is (nil? (:error row)))
+ (is (= 1 (count (:comments row))))))
+ (testing "GHY-4159: in a mixed batch the section applies to the document and is skipped for the question"
+ (let [[doc question] (content-results {:items [{:type "document" :id doc-id}
+ {:type "question" :id card-id}]
+ :include ["comments"]})]
+ (is (nil? (:error doc)))
+ (is (seq (:comments doc)))
+ (is (nil? (:error question)))
+ (is (nil? (:comments question))))))))
+
+(deftest get-content-document-comments-serializer-fallback-test
+ (testing "GHY-4159: on the flattened-text fallback read, threads come back unanchored under
+ comments — absence of anchors means unknown, never orphaned"
+ (mt/with-temp [:model/Document {doc-id :id} {:document {:type "doc"
+ :content [{:type "mysteryBlock"
+ :attrs {:_id "m-1"}
+ :content [{:type "text" :text "odd"}]}]}
+ :content_type "application/json+vnd.prose-mirror"}
+ :model/Comment _ {:target_id doc-id
+ :child_target_id "m-1"
+ :content (comment-content "still here")}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "document" :id doc-id}] :include ["comments"]})]
+ (is (nil? (:error row)))
+ (testing "the body is omitted rather than degraded: content_markdown is the key
+ document_write takes as a whole-body rewrite, so returning flattened prose
+ under it makes a read-modify-write silently drop the unrenderable block"
+ (is (nil? (:content_markdown row)))
+ (is (string? (:content_markdown_unavailable row))))
+ (is (= [{:child_target_id "m-1" :thread-texts ["still here"]}]
+ (mapv #(-> (select-keys % [:child_target_id :anchor])
+ (assoc :thread-texts (mapv :text (:thread %))))
+ (:comments row))))
+ (is (nil? (:orphaned_comments row))))))))
+
+(deftest get-content-unrenderable-body-is-not-a-destructive-round-trip-test
+ (testing "a document whose body holds a block with no Markdown form never returns text under
+ content_markdown. document_write applies that key as a whole-body rewrite, and the
+ flattened prose prose-mirror/ast->text produces drops headings, card embeds and layout
+ containers — so echoing it back would replace a multi-block document with a single
+ paragraph and orphan every anchored thread, while reporting success."
+ (mt/with-temp [:model/Document {doc-id :id}
+ {:document {:type "doc"
+ :content [{:type "heading"
+ :attrs {:level 1 :_id "h-1"}
+ :content [{:type "text" :text "Q3 revenue"}]}
+ {:type "mysteryBlock"
+ :attrs {"_id" "m-1"}}
+ {:type "cardEmbed"
+ :attrs {"id" 118 "_id" "c-1"}}]}
+ :content_type "application/json+vnd.prose-mirror"}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "document" :id doc-id}]})]
+ (is (nil? (:error row))
+ "the read still succeeds — an unrenderable body is not an error")
+ (is (nil? (:content_markdown row))
+ "the key document_write rewrites from must be absent, not degraded")
+ (is (string? (:content_markdown_unavailable row))
+ "and the caller is told why, rather than being handed a lossy body")
+ (testing "nothing in the response is the flattened prose under any key"
+ (is (not (contains? (set (vals row)) "Q3 revenue")))))))))
+
+(defn- deeply-nested-ast
+ "A prose-mirror body nested `n` levels deep."
+ [n]
+ {:type "doc"
+ :content [(reduce (fn [inner i]
+ {:type "blockquote"
+ :attrs {:_id (str "bq-" i)}
+ :content [inner]})
+ {:type "paragraph"
+ :attrs {:_id "leaf"}
+ :content [{:type "text" :text "buried"}]}
+ (range n))]})
+
+(deftest get-content-deepest-storable-document-still-serializes-test
+ (testing "the app DB's JSON nesting ceiling sits below the serializer's, so any document that can
+ be read back is shallow enough to render as Markdown. This is why a deeply nested body
+ is a write-path concern only: the storage layer refuses a document around 600 levels
+ deep, while serializing does not run out of stack until roughly 2000. The margin is
+ load-bearing — if the JSON limit were ever raised, reads could start hitting a
+ StackOverflowError, which is an Error and so escapes the per-item `catch Exception`
+ that keeps one bad document from sinking a whole batch."
+ (mt/with-temp [:model/Document {doc-id :id} {:document (deeply-nested-ast 400)
+ :content_type "application/json+vnd.prose-mirror"}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "document" :id doc-id}]})]
+ (is (nil? (:error row)))
+ (testing "rendered as real Markdown, not the flattened-text fallback"
+ (is (str/includes? (str (:content_markdown row)) "> buried"))))))
+ (testing "past that ceiling the write does not succeed, so no such document exists to read"
+ ;; Throwable, not Exception: which mechanism stops the write depends on how much stack the
+ ;; running thread has. The JSON nesting limit raises an ordinary exception, but on a smaller
+ ;; stack — CI's parallel test threads, say — a recursive walk over the body can overflow
+ ;; first, and a StackOverflowError is an Error. Either outcome satisfies what this pins,
+ ;; which is that the write does not land; asserting one of them made the test
+ ;; environment-dependent.
+ (is (thrown? Throwable
+ (mt/with-temp [:model/Document _ {:document (deeply-nested-ast 600)
+ :content_type "application/json+vnd.prose-mirror"}]
+ nil))))))
+
+(defn- migrate-notification-to-dashboard!
+ "Repoint a payload-less notification row to :notification/dashboard via raw SQL, bypassing the
+ model lifecycle — which validates a schema (and a create fn) that has no branch for dashboard
+ payloads. Those rows only ever arrive by migration, so this stands in for that history. The
+ row must carry no payload_id, so the before-delete dispatch is never exercised at teardown."
+ [notif-id]
+ (t2/query-one {:update :notification
+ :set {:payload_type "notification/dashboard"}
+ :where [:= :id notif-id]}))
+
+(deftest get-content-subscription-migrated-notification-test
+ (testing "GHY-4140: a subscription migrated to the notification API reads by numeric id"
+ (mt/with-temp [:model/Notification {notif-id :id} {:payload_type :notification/card
+ :creator_id (mt/user->id :crowberto)
+ :active true}]
+ (migrate-notification-to-dashboard! notif-id)
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "subscription" :id notif-id}]
+ :response_format "detailed"})]
+ (is (nil? (:error row)))
+ (is (= "notification/dashboard" (:payload_type row))))))))
+
+(deftest get-content-subscription-denied-pulse-does-not-fall-through-test
+ (testing "GHY-4140: an unreadable Pulse must not fall through to a Notification that happens to
+ share its numeric id — that would hand back a different entity than was requested,
+ across the permission boundary"
+ ;; The Pulse takes the notification's id explicitly, so both temps keep their real ids for
+ ;; teardown while sharing one integer across the two id spaces.
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Notification {notif-id :id} {:payload_type :notification/card
+ :creator_id (mt/user->id :rasta)
+ :active true}
+ :model/Pulse {pulse-id :id} {:id notif-id
+ :name "Private"
+ :dashboard_id dash-id
+ :collection_id coll-id
+ :creator_id (mt/user->id :crowberto)}]
+ (migrate-notification-to-dashboard! notif-id)
+ (mt/with-non-admin-groups-no-collection-perms coll-id
+ (mt/with-test-user :rasta
+ (let [row (content-one {:items [{:type "subscription" :id pulse-id}]
+ :response_format "detailed"})]
+ (is (some? (:error row))
+ "an unreadable pulse must produce not-found, never another entity's content")
+ (is (not= "notification/dashboard" (:payload_type row)))))))))
+
+(deftest get-content-include-mixed-batch-test
+ (testing "GHY-4140: include sections apply to the items whose type supports them and are
+ silently skipped for the rest, so the advertised mixed-type batch works"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {}
+ :model/Card {card-id :id} {:dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (let [[dash question] (content-results {:items [{:type "dashboard" :id dash-id}
+ {:type "question" :id card-id}]
+ :include ["definition" "layout"]})]
+ (testing "the dashboard gets layout and is not failed by the question-only section"
+ (is (nil? (:error dash)))
+ (is (some? (:layout dash)))
+ (is (nil? (:definition dash))))
+ (testing "the question gets definition and is not failed by the dashboard-only section"
+ (is (nil? (:error question)))
+ (is (some? (:definition question)))
+ (is (nil? (:layout question)))))))))
+
+(deftest get-content-definition-include-per-type-test
+ (testing "GHY-4140: every type declaring a `definition` section actually produces one. Each
+ builder swallows its own failures and the section is simply omitted when it returns
+ nil, so a broken exporter looks exactly like a type that has nothing to export."
+ (testing "measure — the aggregation clause"
+ (mt/with-temp [:model/Measure {id :id} {:name "M1"
+ :table_id (mt/id :venues)
+ :creator_id (mt/user->id :rasta)
+ :definition (measure-definition (lib/count))}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "measure" :id id}] :include ["definition"]})]
+ (is (nil? (:error row)))
+ (is (some? (:definition row)) "the definition section is present")
+ (is (= "count" (-> row :definition first first))
+ "and carries the stored aggregation")))))
+ (testing "segment — the filter clauses"
+ (mt/with-temp [:model/Segment {id :id} {:name "S1"
+ :table_id (mt/id :venues)
+ :definition {:filter [:= [:field-id (mt/id :venues :price)] 2]}}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "segment" :id id}] :include ["definition"]})]
+ (is (nil? (:error row)))
+ (is (some? (:definition row)) "the definition section is present")
+ (is (= "=" (-> row :definition first first))
+ "and carries the stored filter")))))
+ (testing "transform — the source, with its query serialized"
+ (mt/with-premium-features #{:transforms-basic}
+ (mt/with-temp-env-var-value! [mb-transforms-enabled true]
+ (mt/with-temp [:model/Transform {id :id} {:name "t1"
+ :source {:type :query
+ :query {:database (mt/id)
+ :type "query"
+ :query {:source-table (mt/id :venues)}}}
+ :target {:type :table
+ :schema (t2/select-one-fn :schema :model/Table :id (mt/id :venues))
+ :name "t1_out"}}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "transform" :id id}] :include ["definition"]})]
+ (is (nil? (:error row)))
+ (is (some? (:definition row)) "the definition section is present")
+ (is (= (mt/id) (-> row :definition :query :database))
+ "and the query round-trips as the numeric-id MBQL 5 shape")))))))))
+
+(deftest get-content-include-unknown-for-every-item-test
+ (testing "GHY-4140: a section no item in the batch supports is a tool-level teaching error,
+ so a typo never silently returns nothing"
+ (mt/with-temp [:model/Card {card-id :id} {:dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (let [error (content-error {:items [{:type "question" :id card-id}] :include ["layout"]})]
+ (is (re-find #"does not apply to type question" error))
+ (is (re-find #"available for: dashboard, document" error)))))))
+
+(deftest get-content-settings-include-test
+ (testing "GHY-4511: a question's stored visualization_settings read back — through the
+ `visualization_settings` include, through `detailed`, and as a `fields` path. Without a read-back
+ an agent cannot check a goal line, a series binding or a hidden column it just wrote."
+ (let [settings {:graph.show_goal true :graph.goal_value 50000}]
+ (mt/with-temp [:model/Card {card-id :id} {:type :question
+ :display :line
+ :dataset_query (venues-count-query)
+ :visualization_settings settings}]
+ (mt/with-test-user :crowberto
+ (testing "the concise shape alone still leaves the blob out"
+ (is (nil? (:visualization_settings
+ (content-one {:items [{:type "question" :id card-id}]})))))
+ (testing "the include adds it to the concise shape"
+ (is (= settings (:visualization_settings
+ (content-one {:items [{:type "question" :id card-id}]
+ :include ["visualization_settings"]})))))
+ (testing "detailed carries it"
+ (is (= settings (:visualization_settings
+ (content-one {:items [{:type "question" :id card-id}]
+ :response_format "detailed"})))))
+ (testing "and `visualization_settings` is a valid fields path"
+ (is (= {:visualization_settings settings}
+ (content-one {:items [{:type "question" :id card-id
+ :fields ["visualization_settings"]}]})))))))
+ (testing "a card with nothing stored answers {} — an omitted section would read as
+ \"not available\" rather than \"not set\""
+ (mt/with-temp [:model/Card {card-id :id} {:type :model :dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (is (= {} (:visualization_settings
+ (content-one {:items [{:type "model" :id card-id}]
+ :include ["visualization_settings"]})))))))))
+
+(deftest get-content-named-field-with-no-value-answers-null-test
+ (testing "GHY-4511: a `fields` path the card has no value for comes back null. The compact
+ projection drops nils, so an empty object was the only answer either way and a
+ caller could not tell an unset cache_ttl from a field get_content cannot read."
+ (mt/with-temp [:model/Card {unset-id :id} {:dataset_query (venues-query)}
+ :model/Card {set-id :id} {:dataset_query (venues-query) :cache_ttl 100}]
+ (mt/with-test-user :crowberto
+ (is (= {:cache_ttl nil}
+ (content-one {:items [{:type "question" :id unset-id :fields ["cache_ttl"]}]})))
+ (is (= {:cache_ttl 100}
+ (content-one {:items [{:type "question" :id set-id :fields ["cache_ttl"]}]})))))))
+
+(deftest get-content-dimensions-include-does-not-write-test
+ (testing "GHY-4140: the dimensions include computes on read but never persists, so the tool's
+ readOnlyHint holds — unlike GET /api/metric/:id, which syncs to the DB"
+ (mt/with-temp [:model/Card {metric-id :id} {:type :metric
+ :dataset_query (venues-count-query)}]
+ (mt/with-test-user :crowberto
+ (let [dims-before (t2/select-one-fn :dimensions :model/Card :id metric-id)
+ row (content-one {:items [{:type "metric" :id metric-id}] :include ["dimensions"]})]
+ (is (nil? (:error row)))
+ (is (contains? row :dimensions)
+ "the dimensions section is present")
+ (is (seq (:dimensions row))
+ "a count metric over venues yields at least one groupable dimension")
+ (is (= dims-before (t2/select-one-fn :dimensions :model/Card :id metric-id))
+ "the read persisted nothing to the metric's dimensions column"))))))
+
+(deftest get-content-document-read-does-not-log-a-view-test
+ (testing "GHY-4140: `get_content` declares readOnlyHint, so a document read must not record a
+ view. `documents/get-document` publishes `:event/document-read` by default, which bumps
+ `view_count`, stamps `last_viewed_at`, writes a view_log row, and pushes the document
+ onto the caller's recently-viewed list — filling a user's recents with an agent's reads."
+ (mt/with-temp [:model/Document {doc-id :id}
+ {:document {:type "doc"
+ :content [{:type "paragraph"
+ :content [{:type "text" :text "hello"}]}]}
+ :content_type "application/json+vnd.prose-mirror"
+ :view_count 0}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "document" :id doc-id}]})]
+ (is (nil? (:error row)))
+ (is (re-find #"hello" (:content_markdown row))
+ "the read still returns the body")))
+ (is (= 0 (t2/select-one-fn :view_count :model/Document doc-id))
+ "and left view_count alone"))))
+
+(deftest get-content-dimensions-respects-a-curated-metric-test
+ (testing "GHY-4140: a metric whose dimensions were curated keeps them authoritative on read, the way
+ GET /api/metric/:id does. Reconciling a metric the MEASURE way — which is what
+ compute-dimensions did for every entity type — re-adds a dimension its owner deliberately
+ removed, and mints a fresh random id for every computed pair with no persisted mapping, so
+ two reads of an unchanged metric disagree."
+ (mt/with-temp [:model/Card {metric-id :id} {:type :metric
+ :database_id (mt/id)
+ :table_id (mt/id :venues)
+ :dataset_query (venues-count-query)}]
+ ;; Curate through the persisted set, not through `get_content`'s output: the tool returns the
+ ;; encoded wire shape the endpoints return, which the model's `:dimensions` transform will not
+ ;; take back. Reading the fixture out of the tool under test would also make this test agree
+ ;; with whatever shape the tool happens to emit.
+ (metrics/sync-dimensions! :metadata/metric metric-id)
+ (let [seeded (t2/select-one-fn :dimensions :model/Card :id metric-id)]
+ (is (seq seeded) "the metric must seed at least one dimension for this to prove anything")
+ (t2/update! :model/Card metric-id {:dimensions (vec (take 1 seeded))})
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "metric" :id metric-id}] :include ["dimensions"]})
+ again (content-one {:items [{:type "metric" :id metric-id}] :include ["dimensions"]})]
+ (is (= 1 (count (:dimensions row)))
+ "the curated set is not auto-extended back to every computed pair")
+ (is (= (:dimensions row) (:dimensions again))
+ "and two reads of an unchanged metric agree — no freshly minted ids")))))))
+
+(defn- rest-dimensions
+ "The `dimensions`/`dimension_mappings` pair `GET /api/<route>/:id` returns."
+ [route id]
+ (select-keys (mt/user-http-request :crowberto :get 200 (str route "/" id))
+ [:dimensions :dimension_mappings]))
+
+(defn- mcp-dimensions
+ "The same pair from `get_content`'s `dimensions` include."
+ [type id]
+ (select-keys (mt/with-test-user :crowberto
+ (content-one {:items [{:type type :id id}] :include ["dimensions"]}))
+ [:dimensions :dimension_mappings]))
+
+(defn- without-generated-ids
+ "`dimensions` with the generated dimension ids stripped. An entity whose dimensions have never
+ been persisted mints a fresh random id per computed pair, so two independent reads of one
+ legitimately disagree on ids (and on the `lib/uuid`s in the mapping targets keyed to them) while
+ every other part of the shape must still match."
+ [pair]
+ (mapv #(dissoc % :id) (:dimensions pair)))
+
+(defn- without-clause-uuids
+ "`pair` with the MBQL `:lib/uuid` clause identifiers stripped. A mapping target rebuilt by
+ `reconcile-dimensions-and-mappings` — the path measures take on every load — carries the same
+ field ref under a freshly minted clause uuid each time, so the uuids differ between two reads
+ that agree on everything that identifies the column."
+ [pair]
+ (walk/postwalk #(cond-> % (map? %) (dissoc :lib/uuid)) pair))
+
+(deftest get-content-dimensions-match-the-rest-endpoint-test
+ (testing "GHY-4140: the `dimensions` include documents itself as returning the same
+ `dimensions`/`dimension_mappings` pair `GET /api/metric/:id` and `GET /api/measure/:id`
+ return, but nothing ever compared the two. Each block reads through MCP BEFORE REST:
+ a REST read seeds and persists dimensions as a side effect, so reading it first would
+ paper over any divergence on the not-yet-seeded path."
+ (testing "a metric nobody has opened yet"
+ (mt/with-temp [:model/Card {metric-id :id} {:name "Venue count"
+ :type :metric
+ :database_id (mt/id)
+ :table_id (mt/id :venues)
+ :dataset_query (venues-count-query)}]
+ (let [mcp (mcp-dimensions "metric" metric-id)
+ rest (rest-dimensions "metric" metric-id)]
+ (testing "names its keys the way the endpoint does, not in the internal kebab shape"
+ (is (= (into (sorted-set) (mapcat keys) (:dimensions rest))
+ (into (sorted-set) (mapcat keys) (:dimensions mcp)))))
+ (testing "reports the seeded set — own-table and explicitly-joined columns — rather than
+ every FK-reachable column"
+ (is (= (sort (map :name (:dimensions rest)))
+ (sort (map :name (:dimensions mcp))))))
+ (testing "and every dimension matches but for the ids neither side has persisted yet"
+ (is (= (without-generated-ids rest)
+ (without-generated-ids mcp)))))))
+ (testing "a metric with a dimension whose column disappeared"
+ (mt/with-temp [:model/Card {metric-id :id} {:name "Venue count"
+ :type :metric
+ :database_id (mt/id)
+ :table_id (mt/id :venues)
+ :dataset_query (venues-count-query)}]
+ ;; Seed, then retarget one mapping at a column of an unrelated table so the next sync marks
+ ;; its dimension `:status/orphaned` — the setup `metabase.metrics.api-dimension-test` uses.
+ (metrics/sync-dimensions! :metadata/metric metric-id)
+ (let [{:keys [dimensions dimension_mappings]} (t2/select-one :model/Card :id metric-id)
+ orphan-id (:id (first dimensions))]
+ (t2/update! :model/Card metric-id
+ {:dimension_mappings (mapv #(cond-> %
+ (= orphan-id (:dimension-id %))
+ (assoc-in [:target 2] (mt/id :users :name)))
+ dimension_mappings)})
+ (metrics/sync-dimensions! :metadata/metric metric-id)
+ (let [mcp (mcp-dimensions "metric" metric-id)
+ rest (rest-dimensions "metric" metric-id)]
+ (testing "drops it, because the endpoint drops it unless asked for it"
+ (is (not (contains? (into #{} (map :id) (:dimensions mcp)) orphan-id))))
+ (testing "and the pair matches outright"
+ (is (= rest mcp)))))))
+ (testing "a measure"
+ (mt/with-temp [:model/Measure {measure-id :id} {:name "M1"
+ :table_id (mt/id :venues)
+ :creator_id (mt/user->id :crowberto)
+ :definition (measure-definition (lib/count))}]
+ ;; Seed first so the generated dimension ids are persisted and both reads reconcile against
+ ;; the same set — this block is here for the encoded wire shape, not the unseeded path.
+ (metrics/sync-dimensions! :metadata/measure measure-id)
+ (let [mcp (mcp-dimensions "measure" measure-id)
+ rest (rest-dimensions "measure" measure-id)]
+ (testing "the pair matches outright"
+ (is (= (without-clause-uuids rest)
+ (without-clause-uuids mcp)))))))))
+
+(deftest question-projection-is-canonical-test
+ (testing "GHY-4140: there is one :question projection, carrying get_content's enrichments, so
+ loading this tool cannot silently reshape what browse_collection projects. A future
+ competing lean registration would drop these keys and fail here."
+ (let [catalog (set (projections/catalog :question))]
+ (is (contains? catalog "query_summary"))
+ (is (contains? catalog "template_tags"))
+ (is (contains? catalog "source_card_id")))
+ (testing "the concise projection compacts nils rather than emitting them"
+ (is (= {:id 1 :name "Q"}
+ (projections/project :question :concise {:id 1 :name "Q" :description nil})))))
+ (testing "the same holds for the projections metric_write and document_write share with this tool —
+ each had a competing registration whose winner was decided by load order"
+ (is (contains? (set (projections/catalog :metric)) "query_summary"))
+ (is (contains? (set (projections/catalog :document)) "content_markdown"))))
+
+(deftest get-content-subscription-fields-covers-notification-shape-test
+ (testing "GHY-4140: the subscription fields catalog covers the notification-backed shape, not
+ just the pulse shape — both are reachable under type subscription, so handlers.* must
+ validate as a fields path"
+ (mt/with-temp [:model/Notification {notif-id :id} {:payload_type :notification/card
+ :creator_id (mt/user->id :crowberto)
+ :active true}]
+ (migrate-notification-to-dashboard! notif-id)
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "subscription"
+ :id notif-id
+ :fields ["handlers.channel_type"]}]})]
+ (is (nil? (:error row))
+ "handlers.* is a valid fields path for a notification-backed subscription"))))))
+
+(deftest question-template-tags-read-from-either-stored-shape-test
+ (testing "template_tags surface for both stored query shapes, keyed by name, so the read round-trips
+ through question_write regardless of which surface created the card"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [tag {:id "0f8266e0-5df9-4b95-a6d9-fea1e4a4c3ff"
+ :name "min"
+ :display-name "Min"
+ :type :number}]
+ (testing "legacy shape: a name-keyed map under [:native :template-tags]"
+ (mt/with-temp [:model/Card card {:dataset_query {:database (mt/id)
+ :type :native
+ :native {:query "SELECT 1 WHERE x > {{min}}"
+ :template-tags {"min" tag}}}
+ :query_type :native}]
+ (is (=? {:min {:name "min" :type "number"}}
+ (:template_tags (content-one {:items [{:type "question" :id (:id card)}]}))))))
+ (testing "pMBQL shape: a tag vector on the native stage (what question_write stores)"
+ (mt/with-temp [:model/Card card {:dataset_query {:lib/type :mbql/query
+ :database (mt/id)
+ :stages [{:lib/type :mbql.stage/native
+ :native "SELECT 1 WHERE x > {{min}}"
+ :template-tags [tag]}]}
+ :query_type :native}]
+ (is (=? {:min {:name "min" :type "number"}}
+ (:template_tags (content-one {:items [{:type "question" :id (:id card)}]}))))))))))
+
+(defn- native-card-query
+ "A stored native `:dataset_query` over the test database, in the legacy shape."
+ [sql]
+ {:database (mt/id) :type :native :native {:query sql}})
+
+(deftest native-question-summary-shows-the-query-head-test
+ (testing "GHY-4518: a native question's query_summary is the head of its own query text. Lib's
+ native-stage display name is the placeholder \"Native query\", which tells a caller
+ reading the row nothing about what the card does."
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "the SQL itself, collapsed onto one line"
+ (mt/with-temp [:model/Card {card-id :id}
+ {:query_type :native
+ :dataset_query (native-card-query "select date_trunc('month', placed_at)\n from orders\n group by 1")}]
+ (is (= "SQL: select date_trunc('month', placed_at) from orders group by 1"
+ (:query_summary (content-one {:items [{:type "question" :id card-id}]}))))))
+ (testing "a long query is truncated to a bounded head, marked with an ellipsis"
+ (let [sql (str "select " (str/join ", " (repeat 100 "a_fairly_long_column_name")) " from orders")]
+ (mt/with-temp [:model/Card {card-id :id}
+ {:query_type :native :dataset_query (native-card-query sql)}]
+ (let [summary (:query_summary (content-one {:items [{:type "question" :id card-id}]}))]
+ (is (str/starts-with? summary "SQL: select a_fairly_long_column_name"))
+ (is (str/ends-with? summary "…"))
+ (is (< (count summary) 320)
+ "the summary stays a summary — a whole query belongs in include: definition")))))
+ (testing "an MBQL question keeps the Lib description"
+ (mt/with-temp [:model/Card {card-id :id} {:dataset_query (venues-count-query)}]
+ (let [summary (:query_summary (content-one {:items [{:type "question" :id card-id}]}))]
+ (is (some? summary))
+ (is (not (str/starts-with? summary "SQL: ")))))))))
+
+(deftest native-question-summary-still-withholds-unreadable-source-cards-test
+ (testing "GHY-4518 must not reopen GHY-4510: a native query names its source card in a template
+ tag, so the SQL head goes behind the same gate the Lib description sits behind."
+ (mt/with-temp [:model/Collection {locked-id :id} {}
+ :model/Card {secret-id :id} {:collection_id locked-id
+ :name "SECRET-SourceCard-NORTHWIND"
+ :dataset_query (venues-query)}]
+ (mt/with-temp [:model/Card {wrapper-id :id}
+ {:query_type :native
+ :dataset_query {:database (mt/id)
+ :type :native
+ :native {:query "select * from {{#card}}"
+ :template-tags
+ {"card" {:id "3f3c6e10-1bbb-4a2e-9b6e-2a2d3c4e5f60"
+ :name "card"
+ :display-name "card"
+ :type :card
+ :card-id secret-id}}}}}]
+ (mt/with-non-admin-groups-no-collection-perms locked-id
+ (testing "an admin, who can read the source, gets the SQL head"
+ (mt/with-test-user :crowberto
+ (is (str/starts-with? (:query_summary (content-one {:items [{:type "question" :id wrapper-id}]}))
+ "SQL: select * from"))))
+ (testing "a caller who cannot read the source gets no summary at all"
+ (mt/with-test-user :rasta
+ (let [row (content-one {:items [{:type "question" :id wrapper-id}]})]
+ (is (nil? (:error row)) "the wrapper itself is readable")
+ (is (nil? (:query_summary row)))))))))))
+
+(deftest question-carries-its-database-name-test
+ (testing "GHY-4518: a question read names its database, so turning `database_id` into a name does
+ not cost a second search call"
+ (mt/with-temp [:model/Card {card-id :id} {:dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (let [row (content-one {:items [{:type "question" :id card-id}]})]
+ (is (= (t2/select-one-fn :name :model/Database :id (mt/id)) (:database_name row)))
+ (is (= (mt/id) (:database_id row))
+ "the id stays — the name is additional, not a replacement"))))))
+
+(deftest get-content-not-found-parity-across-types-test
+ (testing "the not-found collapse holds for every type, not just question: a nonexistent id and an
+ existing-but-unreadable one are indistinguishable apart from the id. Each type has its
+ own fetch fn, so parity on one proves nothing about the others.
+
+ Snippet is not in the loop: snippets live in the `snippets` collection namespace rather
+ than under the restricted collection, so this fixture cannot make one unreadable."
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:collection_id coll-id :dataset_query (venues-query)}
+ :model/Card {model-id :id} {:collection_id coll-id :type :model
+ :dataset_query (venues-query)}
+ :model/Dashboard {dash-id :id} {:collection_id coll-id}
+ :model/Document {doc-id :id} {:collection_id coll-id
+ :document {:type "doc" :content []}}]
+ (mt/with-non-admin-groups-no-collection-perms coll-id
+ (mt/with-test-user :rasta
+ (doseq [[type existing-id] [["question" card-id]
+ ["model" model-id]
+ ["dashboard" dash-id]
+ ["document" doc-id]
+ ["collection" coll-id]]]
+ (testing type
+ (let [unreadable (:error (content-one {:items [{:type type :id existing-id}]}))
+ missing (:error (content-one {:items [{:type type :id 999999999}]}))]
+ (is (some? unreadable) "an unreadable entity is an error, not a silent success")
+ (is (some? missing) "a nonexistent id is an error")
+ (is (= (str/replace unreadable (str existing-id) "ID")
+ (str/replace missing "999999999" "ID"))
+ (str "the two messages must differ only by the id, or the error text tells the "
+ "caller which ids exist. unreadable=" (pr-str unreadable)
+ " missing=" (pr-str missing)))))))))))
+
+(deftest get-content-reads-archived-content-test
+ (testing "archived (trashed) content is readable rather than hidden — an agent asked to restore
+ something has to be able to read it first — and the read reports the archived state so
+ the agent is not misled into treating it as live."
+ (mt/with-temp [:model/Card {card-id :id} {:name "Trashed Q" :archived true
+ :dataset_query (venues-query)}
+ :model/Collection {coll-id :id} {:name "Trashed Coll" :archived true}
+ :model/Document {doc-id :id} {:name "Trashed Doc" :archived true
+ :document {:type "doc" :content []}}]
+ (mt/with-test-user :crowberto
+ (doseq [[type id label] [["question" card-id "Trashed Q"]
+ ["collection" coll-id "Trashed Coll"]
+ ["document" doc-id "Trashed Doc"]]]
+ (testing type
+ (let [row (content-one {:items [{:type type :id id}]})]
+ (is (nil? (:error row)) "archived content reads rather than 404ing")
+ (is (= label (:name row)) "and comes back identified")
+ (is (true? (:archived row))
+ "the archived flag is reported — a read that omitted it would present trashed
+ content as live"))))))
+ (testing "a live entity of the same type reports archived false, so the flag above is not
+ constant-true"
+ (mt/with-temp [:model/Card {card-id :id} {:name "Live Q" :dataset_query (venues-query)}]
+ (mt/with-test-user :crowberto
+ (is (false? (:archived (content-one {:items [{:type "question" :id card-id}]})))))))))
+
+(deftest get-content-numeric-string-id-test
+ (testing "GHY-4498: a numeric id serialized as a JSON string reads the same row as the integer,
+ including for the types that have no entity_id column"
+ (notification.tu/with-card-notification
+ [notification {:card {:dataset_query (venues-query)}
+ :notification {:creator_id (mt/user->id :crowberto)}
+ :handlers []}]
+ (mt/with-temp [:model/Card {card-id :id} {:name "numeric string id card"}]
+ (mt/with-test-user :crowberto
+ (testing "a question"
+ (let [row (content-one {:items [{:type "question" :id (str card-id)}]})]
+ (is (nil? (:error row)))
+ (is (= card-id (:id row)))))
+ (testing "an alert, which is numeric-only"
+ (let [row (content-one {:items [{:type "alert" :id (str (:id notification))}]})]
+ (is (nil? (:error row)))
+ (is (= (:id notification) (:id row)))))
+ (testing "a string that only looks numeric is still rejected"
+ (is (re-find #"numeric id"
+ (:error (content-one {:items [{:type "alert" :id "0"}]}))))))))))
diff --git a/test/metabase/mcp/v2/tools/dashboard_test.clj b/test/metabase/mcp/v2/tools/dashboard_test.clj
new file mode 100644
index 00000000000..83175f06bde
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/dashboard_test.clj
@@ -0,0 +1,445 @@
+(ns metabase.mcp.v2.tools.dashboard-test
+ "Contract tests for the `dashboard_write` v2 MCP tool, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised for
+ free. The op grammar itself is covered by `metabase.mcp.v2.dashboard-ops-test`; this suite
+ pins the tool's contract, permission inheritance, and dry-run behavior on top of it."
+ (:require
+ [clojure.test :refer :all]
+ [metabase.collections.models.collection :as collection]
+ [metabase.dashboards.write :as dashboards.write]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the tool the assertions below drive.
+ [metabase.mcp.v2.tools.dashboard :as tools.dashboard]
+ [metabase.permissions.core :as perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.test :as mt]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(comment tools.dashboard/keep-me)
+
+(defn- call-tool!
+ [user scopes tool args]
+ (mt/with-current-user (if (keyword? user) (mt/user->id user) user)
+ (registry/call-tool scopes nil tool args)))
+
+(defn- tool-result
+ [{:keys [result error]}]
+ (when error
+ (throw (ex-info (str "tool call rejected: " (:message error)) {:error error})))
+ (when (:isError result)
+ (throw (ex-info (str "tool call failed: " (-> result :content first :text))
+ {:result result})))
+ (-> result :content first :text json/decode+kw))
+
+(defn- tool-error
+ [{:keys [result error]}]
+ (cond
+ error (:message error)
+ (:isError result) (-> result :content first :text)
+ :else (throw (ex-info "expected a tool error, got success" {:result result}))))
+
+(defn- wire
+ [x]
+ (-> x json/encode json/decode+kw))
+
+(deftest create-dashboard-test
+ (testing "GHY-4147: method create makes a dashboard and returns it in concise projection form"
+ (mt/with-model-cleanup [:model/Dashboard]
+ (let [result (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "create" :name "Sales"
+ :description "Quarterly numbers"})))]
+ (is (pos-int? (:id result)))
+ (is (= "Sales" (:name result)))
+ (testing "concise projection keys only"
+ (is (= #{:id :name :description :tabs :parameters :dashcards}
+ (into #{} (keys result)))))))))
+
+(deftest create-collection-target-test
+ (mt/with-model-cleanup [:model/Dashboard]
+ (let [create! (fn [args]
+ (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire (merge {:method "create"} args)))))]
+ (testing "GHY-4218: an omitted collection_id saves to the caller's personal collection"
+ (is (= (:id (collection/user->personal-collection (mt/user->id :crowberto)))
+ (t2/select-one-fn :collection_id :model/Dashboard
+ :id (:id (create! {:name "dashboard-test personal"}))))))
+ (testing "GHY-4218: collection_id \"root\" still saves to the root collection"
+ (is (nil? (t2/select-one-fn :collection_id :model/Dashboard
+ :id (:id (create! {:name "dashboard-test root" :collection_id "root"}))))))
+ (testing "GHY-4218: an explicit collection_id is unaffected"
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (is (= coll-id
+ (t2/select-one-fn :collection_id :model/Dashboard
+ :id (:id (create! {:name "dashboard-test explicit"
+ :collection_id coll-id}))))))))))
+
+(deftest create-requires-name-test
+ (testing "GHY-4147: create without a name is a teaching error, not a schema dump"
+ (is (re-find #"`name` is required"
+ (tool-error (call-tool! :crowberto nil "dashboard_write" (wire {:method "create"})))))))
+
+(deftest update-requires-id-test
+ (testing "GHY-4147: update without an id is a teaching error"
+ (is (re-find #"`id` is required"
+ (tool-error (call-tool! :crowberto nil "dashboard_write" (wire {:method "update"})))))))
+
+(deftest create-with-ops-in-one-call-test
+ (testing "GHY-4147: create accepts ops, so a dashboard and its cards land in a single call"
+ (mt/with-model-cleanup [:model/Dashboard]
+ (mt/with-temp [:model/Card card {:name "Revenue"}]
+ (let [result (tool-result
+ (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "create" :name "Sales"
+ :ops [{:op "add_card" :id -1 :card_id (:id card)}]})))]
+ (is (= 1 (count (:dashcards result))))
+ (is (= (:id card) (get-in result [:dashcards 0 :card :id])))
+ (testing "the dashcard got a real id, not the temp one"
+ (is (pos-int? (get-in result [:dashcards 0 :id])))))))))
+
+(deftest create-with-a-bad-op-writes-nothing-test
+ (testing "GHY-4147: a create whose ops fail leaves no dashboard behind — otherwise the agent sees
+ an error, retries, and ends up with a pile of empty dashboards"
+ (mt/with-model-cleanup [:model/Dashboard]
+ (mt/with-temp [:model/Card card {}]
+ (let [before (t2/count :model/Dashboard)
+ err (tool-error (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "create" :name "Sales"
+ :ops [{:op "add_card" :id -1 :card_id (:id card)}
+ {:op "remove" :dashcard_id 999999}]})))]
+ (is (re-find #"op 1" err))
+ (is (= before (t2/count :model/Dashboard))))))))
+
+(deftest create-rolls-back-when-the-second-save-fails-test
+ (testing "GHY-4501: `create` with ops writes the row, then applies the ops in a second save. A
+ failure in that second save must take the row with it — otherwise the agent sees an
+ error, is told to retry, and leaves a pile of empty dashboards behind. The pre-compile
+ above catches a bad OP; it cannot catch a save that fails for any other reason, which is
+ what happened in the field."
+ (mt/with-model-cleanup [:model/Dashboard]
+ (mt/with-temp [:model/Card card {}]
+ (let [before (t2/count :model/Dashboard)]
+ ;; Fail only the real save: the pre-compile runs validate-only and never gets here.
+ (mt/with-dynamic-fn-redefs [dashboards.write/update-dashboard!
+ (fn [& _] (throw (ex-info "boom" {})))]
+ (is (some? (tool-error (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "create" :name "Sales"
+ :ops [{:op "add_card" :id -1 :card_id (:id card)}]}))))
+ "the call reports an error"))
+ (is (= before (t2/count :model/Dashboard))
+ "and leaves no dashboard behind"))))))
+
+(deftest ops-are-atomic-test
+ (testing "GHY-4147: a batch with a bad op writes nothing — the error names the op index"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}
+ :model/Card card {}]
+ (let [err (tool-error (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :ops [{:op "add_card" :id -1 :card_id (:id card)}
+ {:op "remove" :dashcard_id 999999}]})))]
+ (is (re-find #"op 1" err))
+ (is (zero? (t2/count :model/DashboardCard :dashboard_id (:id dash))))))))
+
+(deftest validate-only-writes-nothing-test
+ (testing "GHY-4147: validate_only returns the would-be layout without touching the database"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales" :description "Quarterly numbers"}
+ :model/Card card {:name "Revenue"}]
+ (let [args {:method "update" :id (:id dash)
+ :ops [{:op "add_card" :id -1 :card_id (:id card)}]}
+ dry (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire (assoc args :validate_only true))))]
+ (is (= 1 (count (:dashcards dry))))
+ (is (zero? (t2/count :model/DashboardCard :dashboard_id (:id dash))))
+ (testing "the dry run's shape matches a real response, so a caller can read it the same way"
+ (let [real (tool-result (call-tool! :crowberto nil "dashboard_write" (wire args)))]
+ (is (= (into #{} (keys real)) (into #{} (keys dry))))
+ (is (= (into #{} (keys (first (:dashcards real))))
+ (into #{} (keys (first (:dashcards dry))))))))))))
+
+(deftest validate-only-reports-the-replacement-card-test
+ (testing "a dry run of replace_card must name the NEW card: the projection prefers the hydrated `:card` over
+ `:card_id`, so a stale one would report the replace as a no-op and an agent validating before
+ committing would see the wrong thing"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}
+ :model/Card old {:name "Old revenue"}
+ :model/Card new-c {:name "New revenue"}
+ :model/DashboardCard dc {:dashboard_id (:id dash) :card_id (:id old)}]
+ (let [args {:method "update" :id (:id dash)
+ :ops [{:op "replace_card" :dashcard_id (:id dc) :card_id (:id new-c)}]}
+ dry (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire (assoc args :validate_only true))))
+ real (tool-result (call-tool! :crowberto nil "dashboard_write" (wire args)))]
+ (is (= {:id (:id new-c) :name "New revenue"}
+ (-> dry :dashcards first :card)))
+ (is (= (-> real :dashcards first :card)
+ (-> dry :dashcards first :card))
+ "the dry run and the real save must agree")))))
+
+(deftest patch-dashcard-accepts-json-parameter-mappings-test
+ (testing "`parameter_mappings` is advertised as patchable, and a mapping arrives as raw JSON with string
+ clause heads. Without the same target coercion `wire_parameter` does, every such patch failed
+ validation with \"should be :dimension\" — a documented key that could never be used."
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}
+ :model/Card card {:name "Revenue"}
+ :model/DashboardCard dc {:dashboard_id (:id dash) :card_id (:id card)}]
+ (let [result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :ops [{:op "patch_dashcard" :dashcard_id (:id dc)
+ :patch {:parameter_mappings
+ [{:parameter_id "p1"
+ :card_id (:id card)
+ :target ["dimension" ["field" (mt/id :venues :price) nil]]}]}}]}))]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (=? [{:parameter_id "p1" :target [:dimension [:field (mt/id :venues :price) nil]]}]
+ (t2/select-one-fn :parameter_mappings :model/DashboardCard :id (:id dc))))))))
+
+(deftest entity-id-is-accepted-test
+ (testing "GHY-4147: `id` accepts a 21-character entity_id as well as a numeric id"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}]
+ (let [result (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:entity_id dash)
+ :description "Updated"})))]
+ (is (= (:id dash) (:id result)))
+ (is (= "Updated" (:description result)))))))
+
+(deftest archived-round-trip-test
+ (testing "GHY-4147: archived true trashes and false restores — the only removal path"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}]
+ (call-tool! :crowberto nil "dashboard_write" (wire {:method "update" :id (:id dash) :archived true}))
+ (is (true? (t2/select-one-fn :archived :model/Dashboard :id (:id dash))))
+ (call-tool! :crowberto nil "dashboard_write" (wire {:method "update" :id (:id dash) :archived false}))
+ (is (false? (t2/select-one-fn :archived :model/Dashboard :id (:id dash)))))))
+
+(deftest write-permission-is-inherited-test
+ (testing "GHY-4147: a user who cannot write the dashboard gets an error and nothing changes"
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection coll {}
+ :model/Dashboard dash {:name "Sales" :collection_id (:id coll)}]
+ (is (some? (tool-error (call-tool! :rasta nil "dashboard_write"
+ (wire {:method "update" :id (:id dash) :name "Hacked"})))))
+ (is (= "Sales" (t2/select-one-fn :name :model/Dashboard :id (:id dash))))))))
+
+(deftest write-readback-redacts-unreadable-cards-test
+ (testing "GHY-4219: the row a write reads back is redacted like a read. Writing a dashboard needs
+ only its own collection, so a writer can hold a dashcard pointing at a card they cannot
+ read — the readback must still collapse it to an id, never leak the name."
+ (mt/with-temp [:model/Collection {open-id :id} {}
+ :model/Collection {locked-id :id} {}
+ :model/Dashboard {dash-id :id} {:name "Sales" :collection_id open-id}
+ :model/Card {hidden-card :id} {:name "Hidden" :collection_id locked-id}
+ :model/DashboardCard {hidden-dc :id} {:dashboard_id dash-id
+ :card_id hidden-card
+ :row 0 :col 0}]
+ (mt/with-non-admin-groups-no-collection-perms locked-id
+ (let [result (tool-result (call-tool! :rasta nil "dashboard_write"
+ (wire {:method "update" :id dash-id
+ :name "Renamed"})))
+ [dc] (:dashcards result)]
+ (is (= "Renamed" (:name result))
+ "the write itself succeeds — rasta can write the dashboard's own collection")
+ (is (= hidden-dc (:id dc)))
+ (is (= {:id hidden-card} (:card dc))
+ "the unreadable card comes back as an id with no name"))))))
+
+(deftest parameter-ops-accept-json-shapes-test
+ (testing "GHY-4147: a parameter's JSON-shaped properties are coerced to the shape the REST save stores"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}]
+ (let [result (tool-result
+ (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :ops [{:op "add_parameter" :parameter_id "p1" :name "Category"
+ :type "string/=" :sectionId "string"
+ :values_query_type "list" :isMultiSelect true}]})))]
+ (is (= [{:id "p1" :name "Category" :type "string/="}] (:parameters result)))
+ (testing "the stored row carries the decoded enum, as it does when the REST endpoint saves the same body"
+ (let [stored (first (t2/select-one-fn :parameters :model/Dashboard :id (:id dash)))]
+ (is (= :list (:values_query_type stored)))
+ (testing "and a slug derived from the name, so the parameter is URL-addressable"
+ (is (= "category" (:slug stored))))))))))
+
+(deftest add-parameter-requires-a-name-test
+ (testing "GHY-4147: add_parameter without a name is refused up front. A nameless parameter gets no
+ slug, which half-breaks embedding, public links and URL parameter sync, and
+ `dashboard->resolved-params` requires a non-blank name — so the failure would otherwise
+ land on read-back, after the write had already committed."
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}]
+ (let [err (tool-error (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :ops [{:op "add_parameter" :parameter_id "p1"
+ :type "string/="}]})))]
+ (is (re-find #"(?i)name" err))
+ (testing "and the dashboard is left alone"
+ (is (empty? (t2/select-one-fn :parameters :model/Dashboard :id (:id dash)))))))))
+
+(deftest update-parameter-clear-test
+ (testing "GHY-4191: `update_parameter` can remove a property it once set. Null can't say it —
+ `compact-op` strips nulls per op for the same reason the top-level boundary does — so
+ `clear` names them. A parameter is a map, so clearing removes the key outright rather
+ than storing an explicit null, which is not the same thing to the REST shape."
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}]
+ (let [param #(first (t2/select-one-fn :parameters :model/Dashboard :id (:id dash)))
+ run! (fn [ops] (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash) :ops ops}))))]
+ (run! [{:op "add_parameter" :parameter_id "p1" :name "Category" :type "string/="
+ :default ["Widget"] :sectionId "string"}])
+ (is (= ["Widget"] (:default (param))) "precondition: the default is set")
+ (testing "clearing removes the key rather than nulling it"
+ (run! [{:op "update_parameter" :parameter_id "p1" :clear ["default"]}])
+ (is (not (contains? (param) :default)))
+ (testing "and leaves the parameter's other properties alone"
+ (is (= "Category" (:name (param))))
+ (is (= "string" (:sectionId (param))))))
+ (testing "clearing alongside an ordinary set in the same op"
+ (run! [{:op "update_parameter" :parameter_id "p1" :default ["Gadget"]}])
+ (is (= ["Gadget"] (:default (param))))
+ (run! [{:op "update_parameter" :parameter_id "p1" :name "Cat" :clear ["default" "sectionId"]}])
+ (is (= "Cat" (:name (param))))
+ (is (not (contains? (param) :default)))
+ (is (not (contains? (param) :sectionId))))
+ (testing "setting and clearing the same property in one op is a contradiction"
+ (is (re-find #"both set and cleared"
+ (tool-error (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :ops [{:op "update_parameter" :parameter_id "p1"
+ :default ["X"] :clear ["default"]}]})))))
+ (testing "and the atomic save means nothing changed"
+ (is (= "Cat" (:name (param))))))))))
+
+(deftest unknown-card-is-a-teaching-error-test
+ (testing "GHY-4147: add_card referencing a card the user cannot read fails before any write"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}]
+ (is (re-find #"op 0"
+ (tool-error (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :ops [{:op "add_card" :id -1 :card_id 9999999}]}))))))))
+
+(deftest unreadable-card-is-refused-for-a-non-admin-test
+ (testing "a card that EXISTS but the caller cannot read is refused the same way a nonexistent one is, before
+ any write and without confirming it exists — the `can-read?` filter in `fetch-cards` is the only
+ thing enforcing that, and an admin-only test can never exercise it"
+ (mt/with-temp [:model/Collection {secret-id :id} {}
+ :model/Card {hidden-id :id} {:name "CONFIDENTIAL" :collection_id secret-id}
+ :model/Dashboard dash {:name "Sales"}]
+ ;; The dashboard stays in the root collection rasta can write; only the CARD is out of reach, so the
+ ;; refusal under test is the card read check rather than the dashboard's own.
+ (perms/revoke-collection-permissions! (perms-group/all-users) secret-id)
+ (doseq [[label ops] [["card_id" [{:op "add_card" :id -1 :card_id hidden-id}]]
+ ["series" [{:op "add_card" :id -1 :card_id hidden-id :series [hidden-id]}]]]]
+ (testing label
+ (let [error (tool-error (call-tool! :rasta nil "dashboard_write"
+ (wire {:method "update" :id (:id dash) :ops ops})))]
+ (is (re-find #"you can read" error))
+ (is (not (re-find #"CONFIDENTIAL" error))
+ "the refusal must not leak the card's name"))))
+ (is (zero? (t2/count :model/DashboardCard :dashboard_id (:id dash)))
+ "nothing may be written before the refusal"))))
+
+(deftest create-applies-display-attributes-test
+ (testing "GHY-4147: width and auto_apply_filters are honored on create, not silently dropped"
+ (mt/with-model-cleanup [:model/Dashboard]
+ (let [result (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "create" :name "Sales"
+ :width "full" :auto_apply_filters false})))]
+ (is (= {:width "full" :auto_apply_filters false}
+ (t2/select-one [:model/Dashboard :width :auto_apply_filters] :id (:id result))))))))
+
+(deftest null-attributes-are-dropped-at-the-boundary-test
+ (testing "GHY-4147: strict clients fill every declared property with null, and
+ the registry strips those before the handler — so a null attribute leaves
+ the stored value alone rather than reaching a NOT NULL column like `width`."
+ (mt/with-temp [:model/Dashboard dash {:name "Sales" :width "full" :auto_apply_filters false}]
+ (let [result (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :name nil :width nil
+ :auto_apply_filters nil :archived nil})))]
+ (is (= "Sales" (:name result)))
+ (is (= {:name "Sales" :width "full" :auto_apply_filters false :archived false}
+ (t2/select-one [:model/Dashboard :name :width :auto_apply_filters :archived]
+ :id (:id dash))))))))
+
+(deftest clear-list-clears-attributes-test
+ (testing "GHY-4191: `clear` names the properties to unset, which null cannot say — the boundary
+ strips nulls because strict clients flood every declared property with one."
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"
+ :description "old"
+ :collection_position 1
+ :cache_ttl 10}]
+ (testing "the named properties are unset, and unnamed ones are untouched"
+ (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :clear ["description" "cache_ttl"]})))
+ (is (= {:name "Sales" :description nil :collection_position 1 :cache_ttl nil}
+ (t2/select-one [:model/Dashboard :name :description :collection_position :cache_ttl]
+ :id (:id dash)))))
+ (testing "clearing alongside an ordinary set in the same call"
+ (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :name "Renamed" :clear ["collection_position"]})))
+ (is (= {:name "Renamed" :collection_position nil}
+ (t2/select-one [:model/Dashboard :name :collection_position] :id (:id dash)))))
+ (testing "a property that isn't clearable is refused rather than silently ignored. The
+ schema enum rejects it at the boundary and names the ones that are clearable, so
+ the handler's own check (see common-test) is only a backstop against the enum and
+ the tool's `:clearable` set drifting apart"
+ (let [err (tool-error (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :clear ["name"]})))]
+ (is (re-find #"clear" err))
+ (is (re-find #"description" err)))
+ (is (= "Renamed" (t2/select-one-fn :name :model/Dashboard :id (:id dash))))))))
+
+(deftest clearable-attributes-cannot-be-cleared-with-null-test
+ (testing "GHY-4147: the flip side of the boundary strip, pinned so it stays a decision rather
+ than a surprise. These four columns are nullable and clearing them is meaningful, but
+ null is already spoken for as \"I did not set this\", so it cannot express it — the
+ `clear` list added in GHY-4191 is how a caller says it instead."
+ (mt/with-temp [:model/Collection coll {}
+ :model/Dashboard dash {:name "Sales"
+ :description "old"
+ :collection_id (:id coll)
+ :collection_position 1
+ :cache_ttl 10}]
+ (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :description nil :collection_id nil
+ :collection_position nil :cache_ttl nil})))
+ (is (= {:description "old" :collection_id (:id coll) :collection_position 1 :cache_ttl 10}
+ (t2/select-one [:model/Dashboard :description :collection_id :collection_position :cache_ttl]
+ :id (:id dash)))))))
+
+(deftest collection-id-root-sentinel-clears-test
+ (testing "GHY-4147: `collection_id` is the one clearable attribute with an escape hatch — the
+ \"root\" sentinel resolves to nil, so a dashboard can be moved back to the top level"
+ (mt/with-temp [:model/Collection coll {}
+ :model/Dashboard dash {:name "Sales" :collection_id (:id coll)}]
+ (tool-result (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash) :collection_id "root"})))
+ (is (nil? (t2/select-one-fn :collection_id :model/Dashboard :id (:id dash)))))))
+
+(deftest add-card-with-series-test
+ (testing "GHY-4147: add_card's series cards are fetched like card_id is — the response projects
+ them by name, and a create (which dry-runs its ops first) does not blow up on them"
+ (mt/with-model-cleanup [:model/Dashboard]
+ (mt/with-temp [:model/Card base {:name "Revenue"}
+ :model/Card overlay {:name "Forecast"}]
+ (let [result (tool-result
+ (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "create" :name "Sales"
+ :ops [{:op "add_card" :id -1 :card_id (:id base)
+ :series [(:id overlay)]}]})))]
+ (is (= [{:id (:id overlay) :name "Forecast"}]
+ (get-in result [:dashcards 0 :series]))))))))
+
+(deftest unknown-series-card-is-a-teaching-error-test
+ (testing "GHY-4147: a series card the user cannot read is rejected like card_id is, rather than
+ being placed unchecked or reaching the projection unfetched"
+ (mt/with-temp [:model/Dashboard dash {:name "Sales"}
+ :model/Card card {:name "Revenue"}]
+ (is (re-find #"op 0"
+ (tool-error (call-tool! :crowberto nil "dashboard_write"
+ (wire {:method "update" :id (:id dash)
+ :ops [{:op "add_card" :id -1 :card_id (:id card)
+ :series [9999999]}]}))))))))
diff --git a/test/metabase/mcp/v2/tools/definitions_test.clj b/test/metabase/mcp/v2/tools/definitions_test.clj
new file mode 100644
index 00000000000..597297a80e1
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/definitions_test.clj
@@ -0,0 +1,749 @@
+(ns metabase.mcp.v2.tools.definitions-test
+ "Contract tests for the `segment_write` and `measure_write` v2 MCP tools, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised for
+ free. Segment/measure domain semantics (definition normalization, revision diffs, the
+ permission predicates themselves) are owned by `metabase.segments.api-test`,
+ `metabase.measures.api-test`, and the model tests; this suite pins the tools' contract on
+ top of them."
+ (:require
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the tools the assertions below drive.
+ [metabase.mcp.v2.tools.content :as tools.content]
+ [metabase.mcp.v2.tools.definitions :as tools.definitions]
+ [metabase.measures.api :as measures.api]
+ [metabase.permissions.core :as perms]
+ [metabase.segments.api :as segments.api]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(comment tools.content/keep-me tools.definitions/keep-me)
+
+;;; ------------------------------------------------- Harness ------------------------------------------------------
+
+(defn- call-tool!
+ "Drive `tool` through the real dispatch seam as `user` (test-user keyword or user id) with
+ bearer-style `scopes` (nil = internal caller, which bypasses the scope gate).
+
+ `call-tool` answers `{:result …}` once a handler ran, or `{:error …}` when the registry rejects
+ the call before dispatch. Both are presented here in the `{:isError true}` MCP shape a handler
+ error takes, so the helpers below read a refusal as a value without knowing which layer refused."
+ [user scopes tool args]
+ (mt/with-current-user (if (keyword? user) (mt/user->id user) user)
+ (let [{:keys [result error]} (registry/call-tool scopes nil tool args)]
+ (if error
+ {:isError true :content [{:type "text" :text (:message error)}]}
+ result))))
+
+(defn- tool-result
+ "Decoded success payload of a tool response; throws when the call errored, so a tool-level
+ error can never masquerade as a result."
+ [response]
+ (when (:isError response)
+ (throw (ex-info (str "tool call failed: " (-> response :content first :text))
+ {:response response})))
+ (-> response :content first :text json/decode+kw))
+
+(defn- tool-error
+ "Tool-level error text of a tool response; throws when the call succeeded, so a passing call
+ can never satisfy an error assertion."
+ [response]
+ (when-not (:isError response)
+ (throw (ex-info "expected a tool error, got success" {:response response})))
+ (-> response :content first :text))
+
+(defn- wire
+ "Round-trip a value through JSON, producing exactly the keywordized shape tool arguments have
+ after transport decoding (keyword values like :mbql/query become strings)."
+ [x]
+ (-> x json/encode json/decode+kw))
+
+(defn- venues-filter-definition
+ "A real MBQL 5 lib query on venues holding one filter, in wire shape."
+ []
+ (let [mp (mt/metadata-provider)]
+ (wire (-> (lib/query mp (lib.metadata/table mp (mt/id :venues)))
+ (lib/filter (lib/= (lib.metadata/field mp (mt/id :venues :price)) 3))))))
+
+(defn- venues-count-definition
+ "A real MBQL 5 lib query on venues holding one count aggregation, in wire shape."
+ []
+ (let [mp (mt/metadata-provider)]
+ (wire (-> (lib/query mp (lib.metadata/table mp (mt/id :venues)))
+ (lib/aggregate (lib/count))))))
+
+(defn- count-definition
+ "Hand-shaped single-aggregation MBQL 5 definition on `table-id`, as an MCP client would send it."
+ [table-id]
+ {:lib/type "mbql/query"
+ :database (mt/id)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table table-id
+ :aggregation [["count" {}]]}]})
+
+(defn- filter-definition
+ "A real MBQL 5 lib query on `table-kw` holding one filter on `field-kw`, in wire shape — the
+ segment counterpart to [[count-definition]]."
+ [table-kw field-kw]
+ (let [mp (mt/metadata-provider)]
+ (wire (-> (lib/query mp (lib.metadata/table mp (mt/id table-kw)))
+ (lib/filter (lib/= (lib.metadata/field mp (mt/id table-kw field-kw)) 3))))))
+
+(def ^:private mbql4-fragment
+ {:filter ["=" 1 1]})
+
+(defn- latest-revision-message
+ [model-name id]
+ (t2/select-one-fn :message :model/Revision
+ :model model-name :model_id id
+ {:order-by [[:id :desc]]}))
+
+(defn- read-definition!
+ "The `definition` section `get_content` returns for one item, exactly as it comes off the wire.
+ Driven through the real dispatch seam so the assertions see the shape an agent sees."
+ [type id]
+ (-> (call-tool! :crowberto nil "get_content" {:items [{:type type :id id}] :include ["definition"]})
+ tool-result
+ :results
+ first
+ :definition))
+
+(defn- venues-fk
+ "The portable FK path the external dialect names the venues table (or one of its fields) by."
+ [& field-names]
+ (into [(t2/select-one-fn :name :model/Database :id (mt/id)) "PUBLIC" "VENUES"] field-names))
+
+(defn- without-uuids
+ "Strip `lib/uuid`s, which are regenerated on every resolve and so are never equal across a
+ round-trip even when the query is."
+ [x]
+ (cond
+ (map? x) (into {} (map (fn [[k v]] [k (without-uuids v)])) (dissoc x :lib/uuid))
+ (sequential? x) (mapv without-uuids x)
+ :else x))
+
+;;; ------------------------------------------- Argument validation ------------------------------------------------
+
+(deftest ^:parallel malli-validation-test
+ (testing "GHY-4137: schema-level failures are teaching errors from the registry, not handler crashes"
+ (testing "missing method"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "segment_write" {}))
+ "Invalid arguments")))
+ (testing "a method outside the enum (there is no delete — archive instead)"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "segment_write" {:method "delete"}))
+ "Invalid arguments")))
+ (testing "an unknown key on the closed schema"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "measure_write" {:method "create" :bogus 1}))
+ "Invalid arguments")))
+ (testing "a string table_id — tables have no entity_ids, only numeric ids"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id "abc"
+ :name "x" :definition mbql4-fragment}))
+ "Invalid arguments")))))
+
+(deftest ^:parallel create-required-args-test
+ (testing "GHY-4137: each \"(create)\" field is enforced at runtime with a teaching error naming it"
+ (doseq [tool ["segment_write" "measure_write"]
+ missing [:table_id :name :definition]]
+ (testing (str tool " without " (name missing))
+ (let [args (dissoc {:method "create" :table_id (mt/id :venues) :name "x" :definition mbql4-fragment}
+ missing)]
+ (is (= (format "`%s` is required when method is \"create\"." (name missing))
+ (tool-error (call-tool! :crowberto nil tool args)))))))))
+
+(deftest ^:parallel update-required-args-test
+ (doseq [tool ["segment_write" "measure_write"]]
+ (testing tool
+ (testing "GHY-4137: update without id is a teaching error"
+ (is (= "`id` is required when method is \"update\"."
+ (tool-error (call-tool! :crowberto nil tool {:method "update" :revision_message "x"})))))
+ (testing "GHY-4137: update without revision_message is the tool's own teaching error, never the bare REST 400"
+ (is (re-find #"`revision_message` is required"
+ (tool-error (call-tool! :crowberto nil tool {:method "update" :id 13371337 :description "d"})))))
+ (testing "GHY-4137: a whitespace-only revision_message is rejected the same way"
+ (is (re-find #"`revision_message` is required"
+ (tool-error (call-tool! :crowberto nil tool {:method "update" :id 13371337 :revision_message " "}))))))))
+
+(deftest ^:parallel method-exclusive-args-test
+ (doseq [tool ["segment_write" "measure_write"]]
+ (testing tool
+ (testing "GHY-4137: update-only fields on create are rejected, so a caller never believes an ignored field took effect"
+ (doseq [[k v] {:id 1, :archived true, :revision_message "x"}]
+ (is (= (format "`%s` applies to method \"update\" only — remove it from this create call." (name k))
+ (tool-error (call-tool! :crowberto nil tool
+ {:method "create" :table_id (mt/id :venues) :name "x"
+ :definition mbql4-fragment
+ k v}))))))
+ (testing "GHY-4137: table_id on update is rejected — the server derives it from the definition"
+ (is (= "`table_id` cannot be changed on update — the server derives it from `definition`'s source table."
+ (tool-error (call-tool! :crowberto nil tool
+ {:method "update" :id 13371337 :revision_message "x"
+ :table_id (mt/id :venues)}))))))))
+
+(deftest ^:parallel blank-name-test
+ (testing "GHY-4153/GHY-4154: a whitespace-only `name` is refused. The REST endpoints these tools
+ delegate to take `ms/NonBlankString`, and a tool that inherits their checks must not be
+ laxer than they are — `[:string {:min 1}]` alone lets \" \" through."
+ (doseq [[tool definition] {"segment_write" mbql4-fragment
+ "measure_write" (count-definition (mt/id :venues))}]
+ (testing tool
+ (testing "create"
+ (is (re-find #"`name` cannot be blank"
+ (tool-error (call-tool! :crowberto nil tool
+ {:method "create" :table_id (mt/id :venues)
+ :name " "
+ :definition definition})))))
+ (testing "update — refused before the id lookup, so it reads as an argument error"
+ (is (re-find #"`name` cannot be blank"
+ (tool-error (call-tool! :crowberto nil tool
+ {:method "update" :id 13371337
+ :name " "
+ :revision_message "x"})))))))))
+
+(deftest ^:parallel invalid-id-shape-test
+ (testing "GHY-4137: an id that is neither numeric nor a 21-char entity_id teaches the two accepted shapes"
+ (is (= "Invalid id \"abc\" — pass the positive numeric id, or the 21-character entity_id from a search or list result."
+ (tool-error (call-tool! :crowberto nil "segment_write"
+ {:method "update" :id "abc" :revision_message "x"}))))))
+
+;;; ---------------------------------------------- segment_write ---------------------------------------------------
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest segment-write-lifecycle-test
+ (mt/with-model-cleanup [:model/Segment :model/Revision]
+ (let [create! (fn [name definition]
+ (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name name :definition definition})))
+ created (create! "definitions-test segment A"
+ {:filter ["=" ["field" (mt/id :venues :price) nil] 3]})]
+ (testing "GHY-4137: create from a bare MBQL 4 filter fragment succeeds and returns the stored MBQL 5 shape"
+ (is (=? {:id pos-int?
+ :entity_id string?
+ :table_id (mt/id :venues)
+ :name "definitions-test segment A"
+ :archived false}
+ created))
+ (is (= 1 (count (get-in created [:definition :stages]))))
+ (is (some? (get-in created [:definition :stages 0 :filters])))
+ (is (nil? (get-in created [:definition :filter]))
+ "the legacy fragment shape must not survive the write")
+ (is (not (contains? created :description))
+ "an unset description is omitted from the response, not null"))
+ (testing "GHY-4137: update resolves an entity_id, applies the change, and records the revision message"
+ (let [updated (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "segment_write"
+ {:method "update" :id (:entity_id created)
+ :description "price of three"
+ :revision_message "add description"}))]
+ (is (= (:id created) (:id updated)))
+ (is (= "price of three" (:description updated)))
+ (is (= "add description" (latest-revision-message "Segment" (:id created))))))
+ (testing "GHY-4137: a fragment on update is wrapped onto the segment's existing table"
+ (let [updated (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "segment_write"
+ {:method "update" :id (:id created)
+ :definition {:filter ["=" ["field" (mt/id :venues :price) nil] 4]}
+ :revision_message "loosen filter"}))]
+ (is (= (mt/id :venues) (:table_id updated)))
+ (is (= 1 (count (get-in updated [:definition :stages]))))))
+ (testing "GHY-4137: archived true trashes and archived false restores — the only removal path"
+ (is (true? (:archived (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "segment_write"
+ {:method "update" :id (:id created)
+ :archived true :revision_message "trash"})))))
+ (is (false? (:archived (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "segment_write"
+ {:method "update" :id (:id created)
+ :archived false :revision_message "restore"}))))))
+ (testing "GHY-4137: MBQL 4 full queries and MBQL 5 queries are accepted on create too"
+ (doseq [[label definition] {"legacy full query" {:database (mt/id)
+ :type "query"
+ :query {:source-table (mt/id :venues)
+ :filter ["=" ["field" (mt/id :venues :price) nil] 2]}}
+ "MBQL 5 query" (venues-filter-definition)}]
+ (testing label
+ (let [result (create! (str "definitions-test segment " label) definition)]
+ (is (= 1 (count (get-in result [:definition :stages])))))))))))
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest segment-cycle-teaching-error-test
+ (mt/with-model-cleanup [:model/Segment :model/Revision]
+ (testing "GHY-4137: a self-referencing definition surfaces the cycle as a teaching error, not an internal error"
+ (let [{:keys [id]} (tool-result (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test cycle segment"
+ :definition mbql4-fragment}))
+ msg (tool-error (call-tool! :crowberto nil "segment_write"
+ {:method "update" :id id :revision_message "cycle"
+ :definition {:filter ["segment" id]}}))]
+ (is (re-find #"cycle detected" msg))
+ (is (not= "Internal error" msg))))))
+
+;;; ---------------------------------------------- measure_write ---------------------------------------------------
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest measure-write-lifecycle-test
+ (mt/with-model-cleanup [:model/Measure :model/Revision]
+ (let [created (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "measure_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test measure A"
+ :definition (venues-count-definition)}))]
+ (testing "GHY-4137: create with a single-aggregation MBQL 5 definition succeeds"
+ (is (=? {:id pos-int?
+ :entity_id string?
+ :table_id (mt/id :venues)
+ :name "definitions-test measure A"
+ :archived false}
+ created))
+ (is (= 1 (count (get-in created [:definition :stages 0 :aggregation])))))
+ (testing "GHY-4137: update applies the change and records the revision message"
+ (let [updated (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "measure_write"
+ {:method "update" :id (:entity_id created)
+ :description "how many venues"
+ :revision_message "clarify"}))]
+ (is (= "how many venues" (:description updated)))
+ (is (= "clarify" (latest-revision-message "Measure" (:id created))))))
+ (testing "GHY-4137: a definition on a different table moves the measure — table_id is derived, not caller-set"
+ (let [updated (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "measure_write"
+ {:method "update" :id (:id created)
+ :definition (count-definition (mt/id :checkins))
+ :revision_message "move to checkins"}))]
+ (is (= (mt/id :checkins) (:table_id updated)))))
+ (testing "GHY-4137: archived true trashes and archived false restores"
+ (is (true? (:archived (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "measure_write"
+ {:method "update" :id (:id created)
+ :archived true :revision_message "trash"})))))
+ (is (false? (:archived (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} "measure_write"
+ {:method "update" :id (:id created)
+ :archived false :revision_message "restore"})))))))))
+
+(deftest ^:parallel measure-rejects-mbql4-test
+ (testing (str "GHY-4137: an MBQL 4 measure definition gets a teaching error naming the one supported "
+ "full-query shape — never a silent conversion, and never version talk the agent can't act on")
+ (let [shape-sentence #"\"lib/type\": \"mbql/query\""]
+ (testing "a bare aggregation fragment"
+ (let [msg (tool-error (call-tool! :crowberto nil "measure_write"
+ {:method "create" :table_id (mt/id :venues) :name "m"
+ :definition {:aggregation [["count"]]}}))]
+ (is (re-find shape-sentence msg))
+ (is (not (re-find #"MBQL \d" msg)))))
+ (testing "a legacy full query — rejected even though it names a source table"
+ (is (re-find shape-sentence
+ (tool-error (call-tool! :crowberto nil "measure_write"
+ {:method "create" :table_id (mt/id :venues) :name "m"
+ :definition {:database (mt/id)
+ :type "query"
+ :query {:source-table (mt/id :venues)
+ :aggregation [["count"]]}}})))))
+ (testing "the update path enforces the same rule"
+ (mt/with-temp [:model/Measure {measure-id :id} {:name "definitions-test mbql4 update"
+ :table_id (mt/id :venues)
+ :creator_id (mt/user->id :crowberto)
+ :definition {}}]
+ (is (re-find shape-sentence
+ (tool-error (call-tool! :crowberto nil "measure_write"
+ {:method "update" :id measure-id :revision_message "x"
+ :definition {:aggregation [["count"]]}})))))))))
+
+;;; --------------------------------------------- Round-tripping ---------------------------------------------------
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest segment-definition-round-trip-test
+ (testing "GHY-4153: get_content's `definition` feeds straight back into segment_write, as its description promises"
+ (mt/with-model-cleanup [:model/Segment :model/Revision]
+ (let [created (tool-result (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test round-trip segment"
+ :definition (venues-filter-definition)}))
+ read-back (read-definition! "segment" (:id created))]
+ (testing "the read is the bare clause form — an array of filter clauses, not a query map"
+ (is (vector? read-back))
+ (is (= "=" (ffirst read-back))))
+ (let [updated (tool-result (call-tool! :crowberto nil "segment_write"
+ {:method "update" :id (:id created)
+ :definition (wire read-back)
+ :revision_message "round-trip the read definition"}))]
+ (is (= (mt/id :venues) (:table_id updated))
+ "table_id is derived from the clause form's reassembly onto the segment's own table")
+ (is (= 1 (count (get-in updated [:definition :stages]))))
+ (is (= (without-uuids read-back)
+ (without-uuids (read-definition! "segment" (:id created))))
+ "the stored definition reads back identically after the round-trip"))))))
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest measure-definition-round-trip-test
+ (testing "GHY-4154: get_content's `definition` feeds straight back into measure_write"
+ (mt/with-model-cleanup [:model/Measure :model/Revision]
+ (let [created (tool-result (call-tool! :crowberto nil "measure_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test round-trip measure"
+ :definition (venues-count-definition)}))
+ read-back (read-definition! "measure" (:id created))]
+ (testing "the read is the bare clause form — a one-element array holding the aggregation"
+ (is (vector? read-back))
+ (is (= 1 (count read-back)))
+ (is (= "count" (ffirst read-back))))
+ (let [updated (tool-result (call-tool! :crowberto nil "measure_write"
+ {:method "update" :id (:id created)
+ :definition (wire read-back)
+ :revision_message "round-trip the read definition"}))]
+ (is (= (mt/id :venues) (:table_id updated)))
+ (is (= 1 (count (get-in updated [:definition :stages 0 :aggregation]))))
+ (is (= (without-uuids read-back)
+ (without-uuids (read-definition! "measure" (:id created))))
+ "the stored definition reads back identically after the round-trip"))
+ (testing "the bare clause is accepted too, not only the one-element array get_content emits"
+ (let [updated (tool-result (call-tool! :crowberto nil "measure_write"
+ {:method "update" :id (:id created)
+ :definition (wire (first read-back))
+ :revision_message "bare clause"}))]
+ (is (= 1 (count (get-in updated [:definition :stages 0 :aggregation]))))))))))
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest clause-form-create-test
+ (testing "GHY-4153/GHY-4154: create accepts the clause form, reassembling it onto table_id"
+ (mt/with-model-cleanup [:model/Segment :model/Measure :model/Revision]
+ (let [field-ref ["field" {} (venues-fk "PRICE")]
+ segment (tool-result (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test clause-form segment"
+ :definition (wire [["=" {} field-ref 3]])}))
+ measure (tool-result (call-tool! :crowberto nil "measure_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test clause-form measure"
+ :definition (wire [["count" {}]])}))]
+ (is (= (mt/id :venues) (:table_id segment)))
+ (is (= 1 (count (get-in segment [:definition :stages 0 :filters]))))
+ (is (= (mt/id :venues) (:table_id measure)))
+ (is (= 1 (count (get-in measure [:definition :stages 0 :aggregation]))))))))
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest portable-full-query-create-test
+ (testing "GHY-4153: a full query in the external dialect — what execute_query takes — is accepted as a definition"
+ (mt/with-model-cleanup [:model/Segment :model/Revision]
+ (let [created (tool-result
+ (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test portable segment"
+ :definition (wire {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (venues-fk)
+ :filters [["=" {}
+ ["field" {} (venues-fk "PRICE")]
+ 3]]}]})}))]
+ (is (= (mt/id :venues) (:table_id created)))
+ (is (= 1 (count (get-in created [:definition :stages 0 :filters]))))))))
+
+(deftest ^:parallel table-id-definition-mismatch-test
+ (testing "GHY-4153/GHY-4154: a full-query definition whose source table differs from table_id is a teaching error, not silent"
+ (testing "segment"
+ (let [msg (tool-error (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :checkins)
+ :name "definitions-test mismatch segment"
+ :definition (venues-filter-definition)}))]
+ (is (re-find #"must be the same table" msg))
+ (is (not= "Internal error" msg))))
+ (testing "measure"
+ (let [msg (tool-error (call-tool! :crowberto nil "measure_write"
+ {:method "create" :table_id (mt/id :checkins)
+ :name "definitions-test mismatch measure"
+ :definition (venues-count-definition)}))]
+ (is (re-find #"must be the same table" msg))
+ (is (not= "Internal error" msg))))))
+
+;;; ------------------------------------------ Definition validation -----------------------------------------------
+
+(deftest ^:parallel definition-validation-teaching-test
+ (testing "GHY-4137: an invalid `definition` comes back as a teaching error stating the rules a definition
+ must satisfy — never \"Internal error\" or a generic placeholder"
+ (testing "a segment definition with an aggregation"
+ (let [msg (tool-error (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test agg segment"
+ :definition {:database (mt/id)
+ :type "query"
+ :query {:source-table (mt/id :venues)
+ :aggregation [["count"]]
+ :filter ["=" 1 1]}}}))]
+ (is (str/includes? msg "a segment definition must be a single-stage query with a source table and filters"))
+ (is (not (str/includes? msg "unknown error"))
+ "the rules reach the caller instead of a placeholder")
+ (is (not= "Internal error" msg))))
+ (testing "a measure definition with two aggregations"
+ (let [definition (update-in (count-definition (mt/id :venues)) [:stages 0 :aggregation]
+ conj ["count" {}])
+ msg (tool-error (call-tool! :crowberto nil "measure_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test two aggs"
+ :definition definition}))]
+ (is (str/includes? msg "A measure definition's stages must be measure stages"))
+ (is (not= "Internal error" msg))))
+ (testing "a definition that fails MBQL normalization outright — the models would silently store {} for it"
+ (is (str/includes? (tool-error (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test garbage"
+ :definition {:database 0 :type "query" :query {:source-table 0}}}))
+ "`definition` is not a valid MBQL query")))))
+
+(deftest ^:parallel definition-shape-teaching-test
+ (testing "GHY-4153/GHY-4154: a definition in neither accepted shape names both shapes"
+ (doseq [[tool definition] {"segment_write" {:database 0 :type "query" :query {:source-table 0}}
+ "measure_write" {:not "a query"}}]
+ (testing tool
+ (let [msg (tool-error (call-tool! :crowberto nil tool
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test bad shape" :definition definition}))]
+ (is (str/includes? msg "bare clause form"))
+ (is (str/includes? msg "full single-stage"))
+ (is (not= "Internal error" msg)))))
+ (testing "an unresolvable clause array is a teaching error naming both shapes, not an internal error"
+ (let [msg (tool-error (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test bad clauses"
+ :definition [["nonsense-operator" {} 1]]}))]
+ (is (str/includes? msg "bare clause form"))
+ (is (not= "Internal error" msg))))
+ (testing "a scalar definition never reaches the handler — the schema rejects both accepted shapes' negation"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "x" :definition "not a definition"}))
+ "Invalid arguments")))))
+
+;;; ------------------------------------------------- Scopes -------------------------------------------------------
+
+(deftest ^:parallel scope-gating-test
+ (doseq [[tool scope] {"segment_write" "agent:content:write"
+ "measure_write" "agent:content:write"}
+ :let [args {:method "update" :id 13371337 :revision_message "x"}]]
+ (testing tool
+ (testing "GHY-4137: a bearer token without the write scope is refused before dispatch"
+ (is (re-find (re-pattern (str "^Insufficient scope to call tool: " tool "\\."))
+ (tool-error (call-tool! :crowberto #{"agent:content:read"} tool args)))))
+ (testing "GHY-4137: the exact scope passes the gate — the identical call reaches the id lookup"
+ (is (re-find #"not found" (tool-error (call-tool! :crowberto #{scope} tool args)))))
+ (testing "GHY-4137: the wildcard the metabot permission bucket grants passes too"
+ (is (re-find #"not found" (tool-error (call-tool! :crowberto
+ #{(str/replace scope #"write$" "*")}
+ tool args))))))))
+
+(deftest ^:parallel write-scopes-grantable-test
+ (testing "GHY-4137: a scope a tool checks must be grantable — advertised through registered-scopes"
+ (is (set/subset? #{"agent:content:write"}
+ (registry/registered-scopes))))
+ ;; GHY-4225: no assertion against the metabot permission buckets. In-app callers reach v2 through
+ ;; cookie sessions bound to the unrestricted sentinel, and OAuth tokens draw their scopes from the
+ ;; tool registry (`registered-scopes`), not from `user-metabot-perms->scopes` — so
+ ;; `agent:content:write` reaching these tools never depends on a metabot wildcard.
+ )
+
+(deftest ^:parallel tools-list-visibility-test
+ (testing "GHY-4137: each tool is visible exactly to tokens carrying its scope"
+ (doseq [[tool scope] {"segment_write" "agent:content:write"
+ "measure_write" "agent:content:write"}]
+ (is (some #(= tool (:name %)) (registry/list-tools #{scope})))
+ (is (not (some #(= tool (:name %)) (registry/list-tools #{"agent:content:read"})))))))
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest readback-requires-read-scope-test
+ (testing "GHY-4153/GHY-4154: the write echo carries the row's name and definition, so a write-only
+ token would learn the content of anything it may touch — it degrades to an ack unless the
+ token could read the row back through get_content"
+ (mt/with-model-cleanup [:model/Segment :model/Measure :model/Revision]
+ (doseq [[tool model definition] [["segment_write" :model/Segment mbql4-fragment]
+ ["measure_write" :model/Measure (count-definition (mt/id :venues))]]
+ :let [row-name (str "definitions-test readback " tool)]]
+ (testing tool
+ (let [created (tool-result (call-tool! :crowberto #{"agent:content:write"} tool
+ {:method "create" :table_id (mt/id :venues)
+ :name row-name
+ :definition definition}))]
+ (testing "create echoes an ack, not the row"
+ (is (= #{:id :note} (set (keys created))))
+ (is (re-find #"agent:content:read" (:note created))))
+ (testing "and the write still happened — the degradation is in the echo only"
+ (is (= row-name (t2/select-one-fn :name model :id (:id created)))))
+ (testing "update degrades the same way"
+ (let [updated (tool-result (call-tool! :crowberto #{"agent:content:write"} tool
+ {:method "update" :id (:id created)
+ :description "readback check"
+ :revision_message "describe it"}))]
+ (is (= #{:id :note} (set (keys updated))))
+ (is (= "readback check" (t2/select-one-fn :description model :id (:id created))))))
+ (testing "the same calls with both scopes return the full row"
+ (is (=? {:id (:id created) :name row-name :table_id (mt/id :venues) :entity_id string?}
+ (tool-result (call-tool! :crowberto #{"agent:content:write" "agent:content:read"} tool
+ {:method "update" :id (:id created)
+ :description "full echo"
+ :revision_message "describe it again"})))))))))))
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest clear-description-test
+ (testing "GHY-4153/GHY-4154: `clear` is the only way to unset a property. A null cannot carry that
+ meaning — strict clients fill every unset property with null, so the registry strips nulls
+ at the boundary and `description: null` cannot be told apart from \"didn't touch it\"."
+ (mt/with-model-cleanup [:model/Segment :model/Measure :model/Revision]
+ (doseq [[tool model definition] [["segment_write" :model/Segment mbql4-fragment]
+ ["measure_write" :model/Measure (count-definition (mt/id :venues))]]]
+ (testing tool
+ (let [created (tool-result (call-tool! :crowberto nil tool
+ {:method "create" :table_id (mt/id :venues)
+ :name (str "definitions-test clear " tool)
+ :description "set at creation"
+ :definition definition}))]
+ (is (= "set at creation" (:description created)))
+ (testing "clear nulls the column"
+ (let [updated (tool-result (call-tool! :crowberto nil tool
+ {:method "update" :id (:id created)
+ :clear ["description"]
+ :revision_message "drop the description"}))]
+ (is (nil? (t2/select-one-fn :description model :id (:id created))))
+ ;; the concise projection drops nil-valued keys, so a cleared description is absent
+ ;; from the echo rather than echoed back as null
+ (is (not (contains? updated :description)))))
+ (testing "a property this tool doesn't declare clearable is refused at the schema
+ boundary — `clear`'s enum admits only the clearable names, so `expand-clear`'s
+ own \"can't be cleared\" message is unreachable for these two tools"
+ (let [msg (tool-error (call-tool! :crowberto nil tool
+ {:method "update" :id (:id created)
+ :clear ["name"]
+ :revision_message "x"}))]
+ (is (str/starts-with? msg "Invalid arguments"))
+ (is (str/includes? msg "description"))))))))))
+
+;;; ----------------------------------------------- Permissions ----------------------------------------------------
+
+;; not ^:parallel: with-no-data-perms-for-all-users! rewrites global data perms, and rows are
+;; created through the tool under with-model-cleanup
+(deftest permission-tiers-test
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-model-cleanup [:model/Segment :model/Measure :model/Revision]
+ (mt/with-temp [:model/PermissionsGroup {group-id :id} {}
+ :model/User {analyst-id :id} {:is_data_analyst true}
+ :model/User {plain-id :id} {}
+ :model/User {blind-analyst-id :id} {:is_data_analyst true}]
+ (doseq [user-id [analyst-id plain-id]]
+ (perms/add-user-to-group! user-id group-id))
+ (perms/set-table-permission! group-id (mt/id :venues) :perms/view-data :unrestricted)
+ (perms/set-table-permission! group-id (mt/id :venues) :perms/create-queries :query-builder)
+ (let [segment-args {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test perms segment" :definition mbql4-fragment}
+ measure-args {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test perms measure"
+ :definition (count-definition (mt/id :venues))}]
+ (testing "GHY-4137: not admin-only — a data analyst with unrestricted view-data creates both"
+ (is (=? {:id pos-int?} (tool-result (call-tool! analyst-id nil "segment_write" segment-args))))
+ (is (=? {:id pos-int?} (tool-result (call-tool! analyst-id nil "measure_write" measure-args)))))
+ (testing "GHY-4137: the same table grants without the data-analyst role are a permission denial, not a not-found"
+ (is (= "You don't have permissions to do that."
+ (tool-error (call-tool! plain-id nil "segment_write"
+ (assoc segment-args :name "definitions-test denied segment")))))
+ (is (= "You don't have permissions to do that."
+ (tool-error (call-tool! plain-id nil "measure_write"
+ (assoc measure-args :name "definitions-test denied measure"))))))
+ (testing "GHY-4137: a data analyst without unrestricted view-data is denied — data analysts always read
+ table metadata, so the table resolves and the domain permission check refuses the write"
+ (is (= "You don't have permissions to do that."
+ (tool-error (call-tool! blind-analyst-id nil "segment_write"
+ (assoc segment-args :name "definitions-test blind segment")))))))))))
+
+;; not ^:parallel: with-no-data-perms-for-all-users! rewrites global data perms, and rows are
+;; created through the tool under with-model-cleanup
+(deftest table-move-permission-test
+ (testing "GHY-4153/GHY-4154: `definition` carries the row to its own source table, so an update
+ retargeting a table the caller cannot author on is denied — the write check ran against
+ the old table, and only the domain create-check covers the new one"
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-model-cleanup [:model/Segment :model/Measure :model/Revision]
+ (mt/with-temp [:model/PermissionsGroup {group-id :id} {}
+ :model/User {analyst-id :id} {:is_data_analyst true}]
+ (perms/add-user-to-group! analyst-id group-id)
+ ;; Block the database for this group first, then grant venues back. `with-no-data-perms-for-all-users!`
+ ;; only resets the All Users group, so a freshly created group's default on `checkins` is ambient
+ ;; state — and this test is only meaningful while the analyst cannot author there.
+ (perms/set-database-permission! group-id (mt/id) :perms/view-data :blocked)
+ (perms/set-table-permission! group-id (mt/id :venues) :perms/view-data :unrestricted)
+ (perms/set-table-permission! group-id (mt/id :venues) :perms/create-queries :query-builder)
+ (testing "precondition: venues is authorable and checkins is not"
+ (is (true? (perms/user-has-permission-for-table?
+ analyst-id :perms/view-data :unrestricted (mt/id) (mt/id :venues))))
+ (is (false? (perms/user-has-permission-for-table?
+ analyst-id :perms/view-data :unrestricted (mt/id) (mt/id :checkins)))))
+ (let [segment (tool-result (call-tool! analyst-id nil "segment_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test move segment"
+ :definition mbql4-fragment}))
+ measure (tool-result (call-tool! analyst-id nil "measure_write"
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test move measure"
+ :definition (count-definition (mt/id :venues))}))]
+ (testing "segment"
+ (is (= "You don't have permissions to do that."
+ (tool-error (call-tool! analyst-id nil "segment_write"
+ {:method "update" :id (:id segment)
+ :definition (filter-definition :checkins :venue_id)
+ :revision_message "move to checkins"}))))
+ (testing "and the denial actually prevented the move"
+ (is (= (mt/id :venues)
+ (t2/select-one-fn :table_id :model/Segment :id (:id segment))))))
+ (testing "measure"
+ (is (= "You don't have permissions to do that."
+ (tool-error (call-tool! analyst-id nil "measure_write"
+ {:method "update" :id (:id measure)
+ :definition (count-definition (mt/id :checkins))
+ :revision_message "move to checkins"}))))
+ (testing "and the denial actually prevented the move"
+ (is (= (mt/id :venues)
+ (t2/select-one-fn :table_id :model/Measure :id (:id measure))))))))))))
+
+;; not ^:parallel: narrows the all-users group's view-data on the temp database
+(deftest existence-oracle-test
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {table-id :id} {:db_id db-id}
+ :model/Segment {segment-id :id} {:table_id table-id}
+ :model/Measure {measure-id :id} {:name "definitions-test oracle measure"
+ :table_id table-id
+ :creator_id (mt/user->id :crowberto)
+ :definition {}}]
+ (perms/set-database-permission! (perms/all-users-group) db-id :perms/view-data :blocked)
+ (let [norm (fn [msg] (str/replace msg #"\d+" "N"))]
+ (testing "GHY-4137: an unreadable id and a nonexistent id must be indistinguishable — no existence oracle"
+ (testing "segment update"
+ (is (= (norm (tool-error (call-tool! :rasta nil "segment_write"
+ {:method "update" :id segment-id :revision_message "x"})))
+ (norm (tool-error (call-tool! :rasta nil "segment_write"
+ {:method "update" :id 13371337 :revision_message "x"}))))))
+ (testing "measure update"
+ (is (= (norm (tool-error (call-tool! :rasta nil "measure_write"
+ {:method "update" :id measure-id :revision_message "x"})))
+ (norm (tool-error (call-tool! :rasta nil "measure_write"
+ {:method "update" :id 13371337 :revision_message "x"}))))))
+ (testing "create against an unreadable vs nonexistent table"
+ (let [args {:method "create" :name "definitions-test oracle" :definition mbql4-fragment}]
+ (is (= (norm (tool-error (call-tool! :rasta nil "segment_write" (assoc args :table_id table-id))))
+ (norm (tool-error (call-tool! :rasta nil "segment_write" (assoc args :table_id 13371337))))))))))))
+
+;;; ------------------------------------------------ Redaction -----------------------------------------------------
+
+;; not ^:parallel: with-dynamic-fn-redefs on the shared domain fns
+(deftest unexpected-error-redaction-test
+ (testing "GHY-4137: an unexpected domain failure is redacted to a generic internal error — its message may embed
+ SQL or schema detail and must never reach the caller"
+ (mt/with-dynamic-fn-redefs [segments.api/create-segment!
+ (fn [_] (throw (java.sql.SQLException. "relation \"secret_accounts\" does not exist")))
+ measures.api/create-measure!
+ (fn [_] (throw (java.sql.SQLException. "relation \"secret_accounts\" does not exist")))]
+ (doseq [[tool definition] {"segment_write" mbql4-fragment
+ "measure_write" (count-definition (mt/id :venues))}]
+ (let [msg (tool-error (call-tool! :crowberto nil tool
+ {:method "create" :table_id (mt/id :venues)
+ :name "definitions-test redaction" :definition definition}))]
+ (is (= "Internal error" msg))
+ (is (not (str/includes? msg "secret_accounts"))))))))
diff --git a/test/metabase/mcp/v2/tools/document_test.clj b/test/metabase/mcp/v2/tools/document_test.clj
new file mode 100644
index 00000000000..402995c8784
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/document_test.clj
@@ -0,0 +1,769 @@
+(ns metabase.mcp.v2.tools.document-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.collections.models.collection :as collection]
+ [metabase.documents.core :as documents]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.tools.document :as v2.document]
+ [metabase.permissions.core :as perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.test :as mt]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(defn- call
+ "Invoke the document_write handler directly (unrestricted scopes) and return the decoded
+ payload map. Teaching errors surface as thrown ex-infos, matching how the registry treats
+ handler exceptions."
+ [args]
+ (-> (v2.document/document-write-tool args {:token-scopes nil})
+ (get-in [:content 0 :text])
+ json/decode+kw))
+
+(defn- orders-query
+ "A Lib query over ORDERS — a runnable `:dataset_query` for fixtures that only need the card to
+ have one. Lib rather than `mt/mbql-query`, which is deprecated since 0.61.0."
+ []
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id :orders)))))
+
+(defn- with-tool-documents
+ "Call `f` with a `created!` fn that records a payload's document id for cleanup; deletes the
+ recorded documents (with their comments and owned cards) afterward. Documents made through
+ the tool are real rows, not `with-temp` fixtures."
+ [f]
+ (let [ids (atom #{})
+ created! (fn [payload]
+ (when-let [id (:id payload)]
+ (swap! ids conj id))
+ payload)]
+ (try
+ (f created!)
+ (finally
+ (doseq [id @ids]
+ (t2/delete! :model/Comment :target_type "document" :target_id id)
+ (t2/delete! :model/Card :document_id id)
+ (t2/delete! :model/Document :id id))))))
+
+;; TODO(slice-11/content): restore once `metabase.mcp.v2.tools.content/fetch-document` lands —
+;; this test calls it via `(#'v2.content/fetch-document ...)` to compare the tool's echo against a
+;; concise get_content read. See DEC-0001 and .private/decisions in the mcp-v2-foundation sidecar.
+#_(deftest create-clones-card-test
+ (mt/with-temp [:model/Card {card-id :id} {:name "Orders card"
+ :dataset_query (orders-query)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [payload (created! (call {:method "create"
+ :name "Clone test"
+ :content_markdown (str "Intro paragraph.\n\n{% card id=" card-id " %}")}))
+ cloned-id (some-> (re-find #"\{% card id=(\d+)" (:content_markdown payload)) second parse-long)]
+ (testing "the embedded foreign card is cloned and the response shows the clone's id"
+ (is (pos-int? cloned-id))
+ (is (not= card-id cloned-id))
+ (is (= (:id payload) (t2/select-one-fn :document_id :model/Card :id cloned-id))))
+ (testing "the original card is untouched"
+ (is (nil? (t2/select-one-fn :document_id :model/Card :id card-id))))
+ (testing "get_content returns the same Markdown body the tool returned"
+ (is (= (:content_markdown payload)
+ (:content_markdown (#'v2.content/fetch-document (:id payload))))))))))))
+
+(deftest create-collection-target-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [create! (fn [args]
+ (created! (call (merge {:method "create" :content_markdown "Body."} args))))]
+ (testing "GHY-4218: an omitted collection_id saves to the caller's personal collection"
+ (is (= (:id (collection/user->personal-collection (mt/user->id :crowberto)))
+ (t2/select-one-fn :collection_id :model/Document
+ :id (:id (create! {:name "document-test personal"}))))))
+ (testing "GHY-4218: collection_id \"root\" still saves to the root collection"
+ (is (nil? (t2/select-one-fn :collection_id :model/Document
+ :id (:id (create! {:name "document-test root"
+ :collection_id "root"}))))))
+ (testing "GHY-4218: an explicit collection_id is unaffected"
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (is (= coll-id
+ (t2/select-one-fn :collection_id :model/Document
+ :id (:id (create! {:name "document-test explicit"
+ :collection_id coll-id}))))))))))))
+
+(deftest dangling-card-embed-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "a card token referencing a nonexistent card is a collapsed not-found, not a silent dangling embed"
+ (is (thrown-with-msg? Exception #"Card 992342344 not found"
+ (call {:method "create"
+ :name "Dangling"
+ :content_markdown "{% card id=992342344 %}"}))))))
+
+(deftest unreadable-card-embed-collapses-test
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:name "Hidden"
+ :collection_id coll-id
+ :dataset_query (orders-query)}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-id)
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "an unreadable card collapses into the same not-found error as a missing one"
+ (is (thrown-with-msg? Exception #"not found — it may not exist, or you may not have access"
+ (call {:method "create"
+ :name "No peeking"
+ :content_markdown (str "{% card id=" card-id " %}")})))))))
+
+(deftest edits-preserve-comment-anchors-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [payload (created! (call {:method "create"
+ :name "Edit test"
+ :content_markdown "## Heading\n\nEdit me please.\n\nLeave me alone."}))
+ doc-id (:id payload)
+ blocks (fn [] (:content (t2/select-one-fn :document :model/Document :id doc-id)))
+ id-of (fn [bs pred] (some #(when (pred %) (get-in % [:attrs "_id"])) bs))
+ before (blocks)
+ heading-id (id-of before #(= "heading" (:type %)))
+ edited-id (id-of before #(str/includes? (str (get-in % [:content 0 :text])) "Edit me"))]
+ (t2/insert! :model/Comment {:target_type "document"
+ :target_id doc-id
+ :child_target_id edited-id
+ :content {:type "doc" :content []}
+ :creator_id (mt/user->id :crowberto)})
+ (let [updated (call {:method "update"
+ :id doc-id
+ :edits [{:old_str "Edit me please." :new_str "Edited!"}]})
+ after (blocks)]
+ (testing "untouched blocks keep their node ids"
+ (is (= heading-id (id-of after #(= "heading" (:type %)))))
+ (is (some #(= "Leave me alone." (get-in % [:content 0 :text])) after)))
+ (testing "the rewritten block keeps its id, so its comment thread stays anchored"
+ (is (= edited-id (id-of after #(str/includes? (str (get-in % [:content 0 :text])) "Edited"))))
+ (is (= [] (:orphaned_comment_threads updated)))
+ (is (= [] (:changed_blocks updated))))))))))
+
+(deftest edits-report-orphans-only-for-deleted-blocks-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [payload (created! (call {:method "create"
+ :name "Delete test"
+ :content_markdown "Keep me.\n\nDelete me.\n\nKeep me too."}))
+ doc-id (:id payload)
+ blocks (:content (t2/select-one-fn :document :model/Document :id doc-id))
+ id-of (fn [pred] (some #(when (pred %) (get-in % [:attrs "_id"])) blocks))
+ doomed (id-of #(= "Delete me." (get-in % [:content 0 :text])))]
+ (t2/insert! :model/Comment {:target_type "document"
+ :target_id doc-id
+ :child_target_id doomed
+ :content {:type "doc" :content []}
+ :creator_id (mt/user->id :crowberto)})
+ (let [updated (call {:method "update"
+ :id doc-id
+ :edits [{:old_str "\n\nDelete me." :new_str ""}]})]
+ (testing "a block the edit removed reports its thread orphaned"
+ (is (= [{:child_target_id doomed :comment_count 1}]
+ (:orphaned_comment_threads updated)))
+ (is (= [{:block_id doomed :old_type "paragraph" :new_type nil}]
+ (:changed_blocks updated))))
+ (is (= "Keep me.\n\nKeep me too." (:content_markdown updated)))))))))
+
+(deftest rename-and-metadata-only-update-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [payload (created! (call {:method "create"
+ :name "Old name"
+ :content_markdown "Stable body."}))
+ doc-id (:id payload)
+ doc-before (t2/select-one-fn :document :model/Document :id doc-id)]
+ (testing "edits: [] with name renames without touching the document column"
+ (let [renamed (call {:method "update" :id doc-id :edits [] :name "New name"})]
+ (is (= "New name" (:name renamed)))
+ (is (= "Stable body." (:content_markdown renamed)))
+ (is (= doc-before (t2/select-one-fn :document :model/Document :id doc-id)))
+ (is (= [] (:orphaned_comment_threads renamed)))))
+ (testing "edits: [] with archived trashes and restores"
+ (is (true? (:archived (call {:method "update" :id doc-id :edits [] :archived true}))))
+ (is (false? (:archived (call {:method "update" :id doc-id :edits [] :archived false}))))
+ (is (= doc-before (t2/select-one-fn :document :model/Document :id doc-id)))))))))
+
+(def ^:private unrenderable-body
+ "A stored body holding a block type the Markdown serializer has no rendering for — what a
+ document written by a newer frontend, or by a REST caller (`[:document :any]`), looks like to
+ this tool."
+ {:type "doc"
+ :content [{:type "mysteryBlock" :attrs {"_id" "m1"}}
+ {:type "paragraph" :attrs {"_id" "p1"} :content [{:type "text" :text "After."}]}]})
+
+(deftest unrenderable-body-does-not-fail-a-committed-write-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [doc-id (:id (created! (call {:method "create"
+ :name "Old name"
+ :content_markdown "Stable body."})))]
+ (t2/update! :model/Document doc-id {:document unrenderable-body})
+ (testing "a metadata-only update lands and is reported as the success it is — the write
+ commits before the response is built, so a body this tool can't render must not
+ turn a completed write into a failed call"
+ (let [renamed (call {:method "update" :id doc-id :edits [] :name "New name"})]
+ (is (= "New name" (:name renamed)))
+ (is (= "New name" (t2/select-one-fn :name :model/Document :id doc-id)))))
+ (testing "content_markdown is omitted rather than degraded — the next edit's old_str is
+ matched against that exact text, so text that isn't the serialization is worse
+ than none"
+ (let [renamed (call {:method "update" :id doc-id :edits [] :name "Newer name"})]
+ (is (not (contains? renamed :content_markdown)))
+ (is (string? (:content_markdown_unavailable renamed)))))
+ (testing "an edit against a body that can't be serialized still fails, and fails before
+ writing anything — there is no current Markdown for old_str to match"
+ (is (thrown-with-msg? Exception #"Cannot serialize unknown block node type"
+ (call {:method "update" :id doc-id
+ :edits [{:old_str "After." :new_str "Changed."}]})))
+ (is (= "Newer name" (t2/select-one-fn :name :model/Document :id doc-id)))
+ (is (= unrenderable-body (t2/select-one-fn :document :model/Document :id doc-id)))))))))
+
+(deftest edit-matching-errors-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [doc-id (:id (created! (call {:method "create"
+ :name "Match test"
+ :content_markdown "beta one\n\nbeta two"})))]
+ (testing "0 matches is a teaching error"
+ (is (thrown-with-msg? Exception #"matches 0 places"
+ (call {:method "update" :id doc-id
+ :edits [{:old_str "NOPE" :new_str "x"}]}))))
+ (testing ">1 matches without replace_all is a teaching error"
+ (is (thrown-with-msg? Exception #"matches 2 places"
+ (call {:method "update" :id doc-id
+ :edits [{:old_str "beta" :new_str "x"}]}))))
+ (testing "replace_all replaces every occurrence"
+ (let [updated (call {:method "update" :id doc-id
+ :edits [{:old_str "beta" :new_str "gamma" :replace_all true}]})]
+ (is (= "gamma one\n\ngamma two" (:content_markdown updated)))))
+ (testing "a replacement containing old_str does not loop and replaces each occurrence once"
+ (let [updated (call {:method "update" :id doc-id
+ :edits [{:old_str "gamma" :new_str "gamma gamma" :replace_all true}]})]
+ (is (= "gamma gamma one\n\ngamma gamma two" (:content_markdown updated))))))))))
+
+(deftest edit-replacement-parses-markdown-test
+ (testing "replacement text is parsed as Markdown"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (doseq [[label replacement expected-markdown expected-type]
+ [["bold" "**Bold**" "**Bold**" "paragraph"]
+ ["list" "- first\n- second" "- first\n- second\n\n" "bulletList"]
+ ["code fence" "```sql\nselect 1\n```" "```sql\nselect 1\n```\n\n" "codeBlock"]]]
+ (testing label
+ (let [payload (created! (call {:method "create" :name label
+ :content_markdown "Replace me."}))
+ doc-id (:id payload)
+ old-id (-> (t2/select-one-fn :document :model/Document :id doc-id)
+ :content first :attrs (get "_id"))
+ updated (call {:method "update" :id doc-id
+ :edits [{:old_str "Replace me." :new_str replacement}]})]
+ (is (= expected-markdown (:content_markdown updated)))
+ (is (= expected-type
+ (-> (t2/select-one-fn :document :model/Document :id doc-id)
+ :content first :type)))
+ (is (= (if (= "paragraph" expected-type)
+ []
+ [{:block_id old-id :old_type "paragraph" :new_type expected-type}])
+ (:changed_blocks updated))))))
+ (testing "layout container"
+ (let [payload (created! (call {:method "create" :name "Layout"
+ :content_markdown "Replace me."}))
+ doc-id (:id payload)
+ old-id (-> (t2/select-one-fn :document :model/Document :id doc-id)
+ :content first :attrs (get "_id"))
+ updated (call {:method "update" :id doc-id
+ :edits [{:old_str "Replace me."
+ :new_str "::: flex\n::: supporting\nwords\n:::\n:::"}]})]
+ (is (str/includes? (:content_markdown updated) "::: flex"))
+ (is (= "resizeNode" (-> (t2/select-one-fn :document :model/Document :id doc-id)
+ :content first :type)))
+ (is (= [{:block_id old-id :old_type "paragraph" :new_type nil}]
+ (:changed_blocks updated))))))))))
+
+(deftest edit-inside-code-round-trips-test
+ (testing "replacement text inside code remains code content"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (testing "code span"
+ (let [payload (created! (call {:method "create" :name "Code span"
+ :content_markdown "run `ls -la` now"}))
+ updated (call {:method "update" :id (:id payload)
+ :edits [{:old_str "ls" :new_str "my_var"}]})]
+ (is (= "run `my_var -la` now" (:content_markdown updated)))))
+ (testing "fenced block"
+ (let [payload (created! (call {:method "create" :name "Fence"
+ :content_markdown "```\nls -la\n```"}))
+ updated (call {:method "update" :id (:id payload)
+ :edits [{:old_str "ls" :new_str "my_var"}]})]
+ (is (str/includes? (:content_markdown updated) "my_var -la"))
+ (is (not (str/includes? (:content_markdown updated) "my\\_var")))))
+ (testing "prose replacement is parsed as Markdown"
+ (let [payload (created! (call {:method "create" :name "Mixed"
+ :content_markdown "plain ls here"}))
+ updated (call {:method "update" :id (:id payload)
+ :edits [{:old_str "ls" :new_str "*em*"}]})]
+ (is (= "plain *em* here" (:content_markdown updated))))))))))
+
+(defn- error-text
+ "The error text a `call-tool` outcome carries, whichever way it refused: the registry rejects a
+ schema violation before dispatch as `{:error …}`, while a handler's teaching error comes back
+ from an executed call as `{:result {:isError true}}`. `nil` when the call succeeded, so a call
+ that went through can never satisfy an assertion about a refusal."
+ [{:keys [result error]}]
+ (cond
+ error (:message error)
+ (:isError result) (-> result :content first :text)))
+
+(defn- write-error
+ "The error text `document_write` returns for `args`, called through the registry rather than the
+ handler directly — the tool's own Malli schema is only applied at that seam, and these are
+ arguments the schema is meant to reject."
+ [args]
+ (error-text (registry/call-tool nil "test-session" "document_write" args)))
+
+(deftest markdown-tables-are-rejected-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [message "Markdown tables are not supported. Save the query as a question with `display: table` and embed it with {% card id=… %}."
+ table "| Table | Rows |\n|---|---|\n| users | 5,000 |"
+ created (created! (call {:method "create" :name "Table test" :content_markdown "No table"}))
+ doc-id (:id created)]
+ (is (= message (write-error {:method "create" :name "Rejected" :content_markdown table})))
+ (is (= message (write-error {:method "update" :id doc-id :content_markdown table})))
+ (is (= message (write-error {:method "update" :id doc-id
+ :edits [{:old_str "No table" :new_str table}]})))
+ (is (:id (created! (call {:method "create"
+ :name "Code example"
+ :content_markdown (str "```markdown\n" table "\n```")})))))))))
+
+(defn- written-smart-link-attrs
+ "The smartLink attrs of a document written through the tool, read back from the stored AST — the
+ `label`/`href` an editor would render. Goes through the tool rather than `md/parse` because
+ resolving those is a permission decision and so lives in the tool, not in the Markdown layer."
+ [created! body]
+ (let [payload (created! (call {:method "create" :name "smart link probe" :content_markdown body}))]
+ (->> (tree-seq :content :content (t2/select-one-fn :document :model/Document :id (:id payload)))
+ (keep #(when (= "smartLink" (:type %)) (:attrs %)))
+ vec)))
+
+(deftest smart-link-resolution-is-permission-checked-test
+ (testing "an entity token pointing at content the caller can't read resolves to nothing, so its
+ name never crosses the permission boundary — a document writer must not be able to use
+ smart links to enumerate the names of content they have no access to"
+ (mt/with-temp [:model/Collection {secret-id :id} {:name "Top Secret Collection"}
+ :model/Dashboard {hidden-id :id} {:name "CONFIDENTIAL Layoffs" :collection_id secret-id}
+ :model/Collection {open-id :id} {:name "Shared Reports"}
+ :model/Card {readable-id :id} {:name "Open Question"
+ :collection_id open-id
+ :dataset_query (orders-query)}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) secret-id)
+ (perms/grant-collection-read-permissions! (perms-group/all-users) open-id)
+ (with-tool-documents
+ (fn [created!]
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "an unreadable target is indistinguishable from a dangling id"
+ (is (= [{"entityId" hidden-id "model" "dashboard" "label" nil "href" "/"}
+ {"entityId" secret-id "model" "collection" "label" nil "href" "/"}]
+ (written-smart-link-attrs
+ created!
+ (format "{%% entity id=\"%d\" model=\"dashboard\" %%} and {%% entity id=\"%d\" model=\"collection\" %%}"
+ hidden-id secret-id)))))
+ (testing "a readable target still resolves its label and href"
+ (is (= [{"entityId" readable-id "model" "card" "label" "Open Question"
+ "href" (str "/question/" readable-id)}]
+ (written-smart-link-attrs created!
+ (format "{%% entity id=\"%d\" model=\"card\" %%}" readable-id)))))
+ (testing "user mentions resolve under the mention picker's visibility rule: a visible user"
+ (is (= [{"entityId" (mt/user->id :crowberto) "model" "user" "label" "Crowberto Corv" "href" "/"}]
+ (written-smart-link-attrs created!
+ (format "{%% entity id=\"%d\" model=\"user\" %%}"
+ (mt/user->id :crowberto))))))
+ (testing "but not a deactivated user, nor anyone but the caller under user-visibility :none —
+ :model/User has no can-read?, and resolving any id would let a document author
+ enumerate names and emails the picker would never show them"
+ (mt/with-temp [:model/User {inactive-id :id} {:first_name "Gone" :last_name "Person" :is_active false}]
+ (is (= [{"entityId" inactive-id "model" "user" "label" nil "href" "/"}]
+ (written-smart-link-attrs created!
+ (format "{%% entity id=\"%d\" model=\"user\" %%}" inactive-id))))
+ ;; `user-visibility` is gated on :email-restrict-recipients — in OSS the setting reads
+ ;; :all no matter what is stored, so without this the narrowing never happens and the
+ ;; assertion below pins the default instead of the rule.
+ (mt/with-premium-features #{:email-restrict-recipients}
+ (mt/with-temporary-setting-values [user-visibility :none]
+ (is (= [{"entityId" (mt/user->id :crowberto) "model" "user" "label" nil "href" "/"}
+ {"entityId" (mt/user->id :rasta) "model" "user" "label" "Rasta Toucan" "href" "/"}]
+ (written-smart-link-attrs created!
+ (format "{%% entity id=\"%d\" model=\"user\" %%} {%% entity id=\"%d\" model=\"user\" %%}"
+ (mt/user->id :crowberto) (mt/user->id :rasta))))))))))
+ (testing "an admin resolves what a non-admin could not"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (is (= [{"entityId" hidden-id "model" "dashboard" "label" "CONFIDENTIAL Layoffs"
+ "href" (str "/dashboard/" hidden-id)}]
+ (written-smart-link-attrs created!
+ (format "{%% entity id=\"%d\" model=\"dashboard\" %%}"
+ hidden-id)))))))))))
+
+(deftest edit-keeps-the-label-of-a-smart-link-the-editor-cannot-read-test
+ (testing "editing other text in a block must not wipe the label of a smart link pointing at
+ content the editor can't read. The `{% entity %}` token carries only id and model, so a
+ re-parsed block's link has no label until it is resolved from the row — and an editor
+ who can't read that row resolves nothing. Treating that as \"no label\" writes the blank
+ back for everyone, including the people who can see the target."
+ (mt/with-temp [:model/Collection {secret-id :id} {:name "Top Secret Collection"}
+ :model/Card {hidden-id :id} {:name "CONFIDENTIAL Revenue"
+ :collection_id secret-id
+ :dataset_query (orders-query)}
+ :model/Card {unseen-id :id} {:name "CONFIDENTIAL Headcount"
+ :collection_id secret-id
+ :dataset_query (orders-query)}
+ :model/Collection {shared-id :id} {:name "Shared Reports"}]
+ ;; `shared-id` needs no grant: a new collection is already all-users read-write, which is
+ ;; what lets rasta edit the document while the card stays out of reach.
+ (perms/revoke-collection-permissions! (perms-group/all-users) secret-id)
+ (with-tool-documents
+ (fn [created!]
+ (let [payload (mt/with-current-user (mt/user->id :crowberto)
+ (created!
+ (call {:method "create"
+ :name "Smart link label"
+ :collection_id shared-id
+ :content_markdown (str "Intro. See {% entity id=\"" hidden-id
+ "\" model=\"card\" %} for detail.")})))
+ doc-id (:id payload)
+ link-attrs (fn []
+ (->> (tree-seq :content :content
+ (t2/select-one-fn :document :model/Document :id doc-id))
+ (some #(when (= "smartLink" (:type %)) (:attrs %)))))
+ resolved {"entityId" hidden-id
+ "model" "card"
+ "label" "CONFIDENTIAL Revenue"
+ "href" (str "/question/" hidden-id)}]
+ (testing "a writer who can read the target stores its label"
+ (is (= resolved (link-attrs))))
+ (let [updated (mt/with-current-user (mt/user->id :rasta)
+ (call {:method "update" :id doc-id
+ :edits [{:old_str "Intro." :new_str "Introduction."}]}))]
+ (testing "the edit lands"
+ (is (str/starts-with? (:content_markdown updated) "Introduction.")))
+ (testing "and the link the editor never touched keeps its label and href"
+ (is (= resolved (link-attrs))))
+ (testing "without handing that editor the name they cannot read — labels live in the
+ AST, never in the Markdown, which is what makes carrying one forward safe"
+ (is (not (str/includes? (:content_markdown updated) "CONFIDENTIAL")))))
+ (testing "the fallback only keeps a label the document already had — a link the editor
+ adds to something they can't read resolves to nothing, so this cannot be used
+ to acquire a name"
+ (mt/with-current-user (mt/user->id :rasta)
+ (call {:method "update" :id doc-id
+ :edits [{:old_str "for detail."
+ :new_str (str "for detail, and {% entity id=\"" unseen-id
+ "\" model=\"card\" %} too.")}]}))
+ (is (= {"entityId" unseen-id "model" "card" "label" nil "href" "/"}
+ (->> (tree-seq :content :content
+ (t2/select-one-fn :document :model/Document :id doc-id))
+ (some #(when (= unseen-id (get-in % [:attrs "entityId"])) (:attrs %)))))))))))))
+
+(deftest smart-link-labels-are-not-resolved-by-the-markdown-layer-test
+ (testing "parse leaves label/href at their defaults — the Markdown namespace performs no lookup,
+ which is what keeps the documents module free of a permissions dependency"
+ (is (= [{"entityId" 1 "model" "dashboard" "label" nil "href" "/"}]
+ (->> (tree-seq :content :content (documents/parse "see {% entity id=\"1\" model=\"dashboard\" %}"))
+ (keep #(when (= "smartLink" (:type %)) (:attrs %)))
+ vec)))))
+
+(deftest rejected-argument-values-are-teaching-errors-test
+ (testing "an argument the tool accepts but the write path cannot use must come back as an error
+ naming the fix. Left to fall through it surfaces as the generic sanitized \"Internal
+ error\", which tells an agent nothing about what to send instead — the tool schema was
+ looser than the schema the model layer enforces."
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [doc-id (:id (created! (call {:method "create" :name "Arg validation"
+ :content_markdown "Body."})))
+ nonexistent 999999999]
+ (testing "collection_position must be a positive int — it is a 1-based pin position"
+ (are [args] (re-find #"(?i)greater than zero|positive" (str (write-error args)))
+ {:method "create" :name "x" :content_markdown "y" :collection_position 0}
+ {:method "create" :name "x" :content_markdown "y" :collection_position -1}
+ {:method "update" :id doc-id :edits [] :collection_position 0}
+ {:method "update" :id doc-id :edits [] :collection_position -3}))
+ (testing "a non-positive collection_id cannot name a collection"
+ (are [args] (re-find #"(?i)greater than zero|positive" (str (write-error args)))
+ {:method "create" :name "x" :content_markdown "y" :collection_id 0}
+ {:method "create" :name "x" :content_markdown "y" :collection_id -1}
+ {:method "update" :id doc-id :edits [] :collection_id -1}))
+ (testing "a well-formed but nonexistent collection_id is a collapsed not-found, not an
+ internal error — the shape is valid, so only a lookup can catch it"
+ (are [args] (re-find #"(?i)not found" (str (write-error args)))
+ {:method "create" :name "x" :content_markdown "y" :collection_id nonexistent}
+ {:method "update" :id doc-id :edits [] :collection_id nonexistent}))
+ (testing "values the write path can actually use are untouched"
+ (is (nil? (write-error {:method "update" :id doc-id :edits [] :collection_position 2})))
+ (is (nil? (write-error {:method "update" :id doc-id :edits [] :collection_id "root"}))))))))))
+
+(def ^:private cost-model-line
+ "A line with several occurrences of a common letter — many matches per KB, which is what makes
+ replace_all expensive: it re-serializes the whole document once per occurrence."
+ "the quick brown fox jumped over the lazy sleeping dog")
+
+(deftest replace-all-refuses-work-it-cannot-afford-test
+ (testing "replace_all costs one full re-serialization per occurrence, so its cost is
+ matches x document size. A one- or two-character old_str maximises both at once (matches
+ are bounded by document size, so a short needle grows with it), which turns an ~85-byte
+ request into minutes of single-threaded CPU on a large document. The existing iteration
+ cap does not help: it is 100 + 2 x matches, always above the number of iterations
+ actually taken, because it guards non-convergence rather than volume."
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ ;; ~64KB with ~7200 matches of "e". Sized so that carrying the rewrite out is
+ ;; unmistakably slow (~14s measured) rather than merely slower.
+ (let [big (created! (call {:method "create" :name "Costly"
+ :content_markdown (str/join "\n\n" (repeat 1200 cost-model-line))}))]
+ (testing "an over-budget replace_all is refused, naming the cost and the way forward"
+ (let [timer (u/start-timer)
+ ;; `write-error` returns nil on success, so a completed rewrite cannot be
+ ;; mistaken for a refusal — asserting against a stringified payload would pass
+ ;; vacuously, since the payload itself contains the word "content_markdown".
+ err (write-error {:method "update" :id (:id big)
+ :edits [{:old_str "e" :new_str "3" :replace_all true}]})
+ elapsed (u/since-ms timer)]
+ (is (some? err) "should be refused, not carried out")
+ (when err
+ (is (re-find #"(?i)replace_all" err))
+ (is (re-find #"content_markdown" err)
+ "should point at the single-pass alternative"))
+ ;; The guard has to price the call without performing it — one serialization, not
+ ;; one per match. Carrying this one out measures ~14s, so a 5s ceiling separates
+ ;; "refused up front" from "did the work first".
+ (is (< elapsed 5000)
+ (format "refusal should not do the work it is refusing (took %.0fms)" (double elapsed)))))
+ (testing "a realistic replace_all is well under budget and still runs"
+ (let [doc (created! (call {:method "create" :name "Modest"
+ :content_markdown (str/join "\n\n" (repeat 20 "the widget shipped"))}))
+ out (call {:method "update" :id (:id doc)
+ :edits [{:old_str "widget" :new_str "gadget" :replace_all true}]})]
+ (is (not (str/includes? (:content_markdown out) "widget")))
+ (is (= 20 (count (re-seq #"gadget" (:content_markdown out)))))))))))))
+
+(deftest edit-budget-covers-the-whole-call-test
+ (testing "the rewriting ceiling bounds one document_write call, not one edit. `edits` is an
+ unbounded list, so an allowance handed fresh to each entry is no bound at all: edits
+ that each price under the ceiling still buy an unbounded multiple of it in one request."
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ ;; ~16KB. Each `replace_all` below matches 300 times, pricing at ~4,800 — well under the
+ ;; ceiling on its own, so every one of these edits is individually legal.
+ (let [doc-id (:id (created! (call {:method "create"
+ :name "Many edits"
+ :content_markdown (str/join "\n\n" (repeat 300 cost-model-line))})))
+ stored #(:markdown (documents/serialize
+ (t2/select-one-fn :document :model/Document :id doc-id)))
+ edit (fn [old new] {:old_str old :new_str new :replace_all true})]
+ (testing "one such edit on its own is accepted"
+ (is (nil? (write-error {:method "update" :id doc-id
+ :edits [(edit "quick" "swift")]}))))
+ (let [before (stored)]
+ (testing "enough of them in a single call is refused, naming the call as the unit"
+ (let [timer (u/start-timer)
+ err (write-error {:method "update" :id doc-id
+ :edits (mapv edit
+ ["brown" "jumped" "over" "lazy" "sleeping" "dog"]
+ ["red" "leapt" "above" "idle" "dozing" "fox"])})
+ elapsed (u/since-ms timer)]
+ (is (some? err) "should be refused, not carried out")
+ (when err
+ (is (re-find #"(?i)every edit in the call" err)
+ "should say the ceiling is per call, so the agent splits rather than retries")
+ (is (re-find #"content_markdown" err)
+ "should point at the single-pass alternative"))
+ ;; The budget caps work performed: the sweep stops once it is spent, so an
+ ;; over-budget call costs about the ceiling (~600ms), never the whole request.
+ (is (< elapsed 5000)
+ (format "refusal should stop at the ceiling (took %.0fms)" (double elapsed)))))
+ (testing "a refused call leaves the stored body untouched — the reduce builds a new AST
+ and the throw lands before update-document!, so no prefix of the edits persists"
+ (is (= before (stored)))))))))))
+
+(deftest method-shape-errors-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [doc-id (:id (created! (call {:method "create"
+ :name "Shape test"
+ :content_markdown "Body."})))]
+ (testing "cross-method keys on create fail loudly"
+ (are [args re] (thrown-with-msg? Exception re (call (merge {:method "create"
+ :name "n"
+ :content_markdown "x"}
+ args)))
+ {:edits [{:old_str "a" :new_str "b"}]} #"edits only apply"
+ {:id doc-id} #"id only applies"
+ {:archived true} #"archived only applies"))
+ (testing "update requires exactly one of content_markdown | edits"
+ (is (thrown-with-msg? Exception #"not both"
+ (call {:method "update" :id doc-id
+ :content_markdown "x" :edits []})))
+ (is (thrown-with-msg? Exception #"exactly one of content_markdown"
+ (call {:method "update" :id doc-id})))))))))
+
+(deftest write-scope-is-not-a-read-scope-test
+ (testing "GHY-4217: a document body is content, so a write must not hand it back to a token whose
+ read scopes get_content would refuse. `edits: []` is the documented way to touch nothing,
+ which made it a clean read oracle over any document the caller could write to."
+ (mt/with-model-cleanup [:model/Document]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [existing (documents/create-document!
+ {:name "someone elses doc"
+ :document (documents/parse "PRE-EXISTING SECRET")
+ :collection_id nil})
+ call! (fn [scopes]
+ (-> (registry/call-tool scopes nil "document_write"
+ {:method "update" :id (:id existing) :edits []})
+ :result :content first :text))]
+ (testing "without the read scope the body is withheld, leaving the minimal ack"
+ (let [txt (call! #{"agent:content:write"})]
+ (is (not (re-find #"PRE-EXISTING SECRET" txt)))
+ (is (re-find #"agent:content:read" txt))))
+ (testing "with it, the body comes back as before — the write still reports its result"
+ (let [txt (call! #{"agent:content:write" "agent:content:read"})]
+ (is (re-find #"PRE-EXISTING SECRET" txt)))))))))
+
+(deftest clear-unsets-collection-position-test
+ (testing "GHY-4191: a null cannot mean \"unset this\" — the boundary strips nulls because strict
+ clients fill every declared property with one — so `clear` names the property instead.
+ collection_position is the only unsettable field here: collection_id has the \"root\"
+ sentinel, and name and the body are required rather than clearable."
+ (mt/with-model-cleanup [:model/Document]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [doc (documents/create-document!
+ {:name "pinned doc"
+ :document (documents/parse "body")
+ :collection_id nil
+ :collection_position 1})
+ call! (fn [args]
+ (registry/call-tool #{"agent:content:write" "agent:content:read"} nil
+ "document_write"
+ (merge {:method "update" :id (:id doc)} args)))]
+ (is (= 1 (t2/select-one-fn :collection_position :model/Document :id (:id doc)))
+ "precondition: the document is pinned")
+ (testing "a null leaves it alone, as it does everywhere else"
+ (call! {:edits [] :collection_position nil})
+ (is (= 1 (t2/select-one-fn :collection_position :model/Document :id (:id doc)))))
+ (testing "clear unsets it"
+ (call! {:edits [] :clear ["collection_position"]})
+ (is (nil? (t2/select-one-fn :collection_position :model/Document :id (:id doc)))))
+ (testing "a property outside the clearable set is refused at the boundary"
+ (let [txt (error-text (call! {:edits [] :clear ["name"]}))]
+ (is (re-find #"clear" txt))
+ (is (= "pinned doc" (t2/select-one-fn :name :model/Document :id (:id doc)))))))))))
+
+;; TODO(slice-11/content): restore once the `get_content` tool lands — this test calls it via
+;; `registry/call-tool ... "get_content"` to compare the write echo against a concise read. See
+;; DEC-0001 and .private/decisions in the mcp-v2-foundation sidecar.
+#_(deftest write-echo-and-read-name-the-body-alike-test
+ (testing "the write echo and a concise get_content read call the body `content_markdown`. They
+ used to disagree — the read said `markdown` — so an agent doing the read-modify-write
+ this tool's `edits`/`old_str` design encourages had to rename the field in between."
+ (mt/with-model-cleanup [:model/Document]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [echo (-> (registry/call-tool #{"agent:content:write" "agent:content:read"} nil
+ "document_write"
+ {:method "create" :name "shared name"
+ :content_markdown "BODY TEXT"})
+ :content first :text json/decode+kw)
+ read (-> (registry/call-tool #{"agent:content:read"} nil "get_content"
+ {:items [{:type "document" :id (:id echo)}]})
+ :content first :text json/decode+kw :results first)]
+ (is (= "BODY TEXT" (:content_markdown echo)))
+ (is (= (:content_markdown echo) (:content_markdown read)))
+ (testing "and neither side still carries the old key"
+ (is (not (contains? echo :markdown)))
+ (is (not (contains? read :markdown)))))))))
+
+(deftest ^:parallel tools-list-discoverability-test
+ (testing "a dynamically-registered client can discover and call document_write. Registration is
+ not enough on its own: the tool's scope also has to reach the DCR default grant, or the
+ client lists a tool every call then 403s on."
+ (let [grant (set (registry/registered-scopes))
+ named (fn [scopes] (some #(= "document_write" (:name %)) (registry/list-tools scopes)))]
+ (testing "its scope is in the default grant"
+ (is (contains? grant "agent:content:write")))
+ (testing "so a default-grant client sees it"
+ (is (named grant)))
+ (testing "and it is hidden from a token holding only the read scope"
+ (is (not (named #{"agent:content:read"}))))
+ (testing "the manifest carries a description and an input schema that advertises `clear`"
+ (let [tool (first (filter #(= "document_write" (:name %)) (registry/list-tools grant)))]
+ (is (seq (:description tool)))
+ (is (str/includes? (:description tool) "No Markdown tables - embed a table-display question instead."))
+ (is (get-in tool [:inputSchema :properties :clear])))))))
+
+;; Closes the inherited finding from slice 09a's review (.private/findings/slice-09a/parallel-review.md,
+;; DEC-0001): create-document!/update-document!/clone-cards-in-document! enforce permissions by
+;; docstring only, and this tool is their first direct caller. This test asserts DB state — no
+;; Document row created, no laundered Card clone persisted — rather than only the :isError status,
+;; per the review's explicit test-gap callout.
+(deftest permission-denied-write-leaves-no-db-trace-test
+ (mt/with-temp [:model/Collection {locked-id :id} {:name "Locked down"}
+ :model/Card {card-id :id} {:name "Someone else's card"
+ :collection_id locked-id
+ :dataset_query (orders-query)}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) locked-id)
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "create into a collection the caller cannot write to is refused before any row lands"
+ (let [before-doc-count (t2/count :model/Document)
+ before-card-count (t2/count :model/Card)]
+ (is (thrown? Exception
+ (call {:method "create"
+ :name "Should not exist"
+ :content_markdown "body"
+ :collection_id locked-id})))
+ (testing "no Document row was created"
+ (is (= before-doc-count (t2/count :model/Document))))
+ (testing "no card was cloned as a side effect of the refused write"
+ (is (= before-card-count (t2/count :model/Card))))))
+ (testing "update of a document the caller can read but not write is refused, and the embedded
+ foreign card is not cloned into it — a document read-check passing must not launder
+ a write the caller has no permission for. `read-only-id` is granted read-only (not
+ revoked entirely) so this isolates write-check from the read-check `get-document`
+ already runs — without the distinct grant, revoking all access would make the
+ update 404 at the read step, before write-check is ever reached."
+ (mt/with-temp [:model/Collection {read-only-id :id} {:name "Read only for rasta"}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) read-only-id)
+ (perms/grant-collection-read-permissions! (perms-group/all-users) read-only-id)
+ (mt/with-current-user (mt/user->id :crowberto)
+ (with-tool-documents
+ (fn [created!]
+ (let [payload (created! (call {:method "create"
+ :name "Owner's doc"
+ :collection_id read-only-id
+ :content_markdown "Body."}))
+ doc-id (:id payload)]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [before-card-count (t2/count :model/Card)]
+ (is (thrown? Exception
+ (call {:method "update"
+ :id doc-id
+ :content_markdown (str "See {% card id=" card-id " %}")})))
+ (testing "the document body was not modified"
+ (is (= "Body." (:markdown (documents/serialize
+ (t2/select-one-fn :document :model/Document :id doc-id))))))
+ (testing "the referenced card was not cloned"
+ (is (= before-card-count (t2/count :model/Card)))))))))))))))
diff --git a/test/metabase/mcp/v2/tools/duplicate_test.clj b/test/metabase/mcp/v2/tools/duplicate_test.clj
new file mode 100644
index 00000000000..5f641ce1b28
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/duplicate_test.clj
@@ -0,0 +1,555 @@
+(ns metabase.mcp.v2.tools.duplicate-test
+ "Contract tests for the `duplicate_content` v2 MCP tool, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, Malli validation, and teaching-error conversion are exercised for free."
+ (:require
+ [clojure.test :refer :all]
+ [metabase.collections.models.collection :as collection]
+ [metabase.documents.test-util :as documents.tu]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the tool the assertions below drive.
+ [metabase.mcp.v2.tools.duplicate :as tools.duplicate]
+ [metabase.metabot.scope :as metabot.scope]
+ [metabase.models.interface :as mi]
+ [metabase.permissions.core :as perms]
+ [metabase.test :as mt]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(comment tools.duplicate/keep-me)
+
+(defn- venues-query
+ "A Lib query over VENUES — a runnable `:dataset_query` for fixtures that only need the card to
+ have one."
+ []
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id :venues)))))
+
+(defn- call-tool!
+ ([user args] (call-tool! user nil args))
+ ([user scopes args]
+ (mt/with-current-user (mt/user->id user)
+ (registry/call-tool scopes nil "duplicate_content" args))))
+
+(defn- tool-result
+ [{:keys [result error]}]
+ (when error
+ (throw (ex-info (str "tool call rejected: " (:message error)) {:error error})))
+ (when (:isError result)
+ (throw (ex-info (str "tool call failed: " (-> result :content first :text))
+ {:result result})))
+ (-> result :content first :text json/decode+kw))
+
+(defn- tool-error
+ [{:keys [result error]}]
+ (cond
+ error (:message error)
+ (:isError result) (-> result :content first :text)
+ :else (throw (ex-info "expected a tool error, got success" {:result result}))))
+
+;;; ------------------------------------------------- question -----------------------------------------------------
+
+(deftest duplicate-question-test
+ (testing "GHY-4218: an omitted collection_id copies into the caller's personal collection, not
+ the source's own collection; the \"Copy of\" name, query, and display stay intact"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:name "Revenue by region"
+ :type :question
+ :display :bar
+ :collection_id coll-id
+ :dataset_query (venues-query)}]
+ (let [personal-id (:id (collection/user->personal-collection (mt/user->id :crowberto)))
+ result (tool-result (call-tool! :crowberto {:type "question" :id card-id}))
+ copy (t2/select-one :model/Card :id (:id result))]
+ (is (=? {:type "question" :name "Copy of Revenue by region" :collection_id personal-id}
+ result))
+ (is (not= card-id (:id result)))
+ (is (= "Copy of Revenue by region" (:name copy)))
+ (is (= personal-id (:collection_id copy)))
+ (is (= :bar (:display copy)))
+ (is (= :question (:type copy)))
+ (is (= (:dataset_query (t2/select-one :model/Card :id card-id))
+ (:dataset_query copy))))))))
+
+(deftest duplicate-question-new-name-and-collection-test
+ (testing "GHY-4151: new_name and collection_id override the defaults"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {source-coll :id} {}
+ :model/Collection {dest-coll :id} {}
+ :model/Card {card-id :id} {:name "Revenue by region"
+ :type :question
+ :collection_id source-coll
+ :dataset_query (venues-query)}]
+ (let [result (tool-result (call-tool! :crowberto {:type "question"
+ :id card-id
+ :new_name "Revenue by region (EMEA)"
+ :collection_id dest-coll}))]
+ (is (=? {:name "Revenue by region (EMEA)" :collection_id dest-coll} result))
+ (is (=? {:name "Revenue by region (EMEA)" :collection_id dest-coll}
+ (t2/select-one :model/Card :id (:id result)))))))))
+
+(deftest duplicate-question-to-root-test
+ (testing "GHY-4151: collection_id \"root\" copies into the root collection"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}]
+ (let [result (tool-result (call-tool! :crowberto {:type "question" :id card-id :collection_id "root"}))]
+ (is (nil? (:collection_id result)))
+ (is (nil? (:collection_id (t2/select-one :model/Card :id (:id result))))))))))
+
+(deftest duplicate-dashboard-question-test
+ (testing "GHY-4151: a question saved inside a dashboard becomes a normal collection question when
+ copied — a card cannot live in both a dashboard and a collection"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Dashboard {dash-id :id} {:collection_id coll-id}
+ :model/Card {card-id :id} {:name "Inline question"
+ :type :question
+ :collection_id coll-id
+ :dashboard_id dash-id
+ :dataset_query (venues-query)}]
+ (let [result (tool-result (call-tool! :crowberto {:type "question" :id card-id :collection_id coll-id}))
+ copy (t2/select-one :model/Card :id (:id result))]
+ (is (nil? (:dashboard_id copy)))
+ (is (= coll-id (:collection_id copy))))))))
+
+(deftest duplicate-document-scoped-question-test
+ (testing "GHY-4218: a question saved inside a document is refused, and no copy is written.
+ `document_id` is not placement — `mi/can-read? :model/Card` conjoins
+ `parent-document-permits?`, which short-circuits to true on a nil `document_id`, so a
+ copy that dropped the column would be readable by anyone with collection perms on the
+ destination, permanently, and would disclose material the Document's content gate
+ exists to withhold"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Document {doc-id :id} {:name "Exploration summary"
+ :collection_id coll-id
+ :document (documents.tu/text->prose-mirror-ast "Secret.")}
+ :model/Card {card-id :id} {:name "Lens-derived question"
+ :type :question
+ :collection_id coll-id
+ :document_id doc-id
+ :dataset_query (venues-query)}]
+ (is (= (format (str "Card %d is saved inside a document — duplicate the document instead, "
+ "which copies the questions saved in it.")
+ card-id)
+ (tool-error (call-tool! :crowberto {:type "question" :id card-id :collection_id coll-id}))))
+ (testing "and no ungated copy exists — asserted through the read gate itself, as a user who
+ cannot read the parent document, rather than by inspecting the returned map"
+ (is (= 1 (t2/count :model/Card :collection_id coll-id)))
+ (mt/with-non-admin-groups-no-collection-perms coll-id
+ (mt/with-current-user (mt/user->id :rasta)
+ (is (not-any? mi/can-read? (t2/select :model/Card :collection_id coll-id))))))))))
+
+(deftest duplicate-native-question-without-authoring-perms-test
+ (testing "GHY-4218: copying is not authoring. A caller who can read and run a native card but
+ lacks native query-building perms can duplicate it, matching `POST /api/card/:id/copy`
+ and `documents.models.document/clone-card!` (UXW-5037). The old
+ `check-allowed-to-create-card!` ran run-permissions on the source's own query and
+ refused with \"you do not have permissions to run its query\" — a query the caller can
+ plainly run through the source card"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:name "Native revenue"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (mt/native-query {:query "SELECT 1"})}]
+ (mt/with-no-data-perms-for-all-users!
+ (perms/set-database-permission! (perms/all-users-group) (mt/id) :perms/view-data :unrestricted)
+ (perms/set-database-permission! (perms/all-users-group) (mt/id) :perms/create-queries :no)
+ (let [result (tool-result (call-tool! :rasta {:type "question"
+ :id card-id
+ :collection_id coll-id}))]
+ (is (= "Copy of Native revenue"
+ (t2/select-one-fn :name :model/Card :id (:id result))))))))))
+
+(deftest duplicate-into-uncuratable-collection-still-refused-test
+ (testing "GHY-4218: dropping the authoring check must not drop the destination create-check —
+ copying into a collection the caller cannot curate is still refused"
+ (mt/with-temp [:model/Collection {source-coll :id} {}
+ :model/Collection {dest-coll :id} {}
+ :model/Card {card-id :id} {:name "Revenue"
+ :type :question
+ :collection_id source-coll
+ :dataset_query (venues-query)}]
+ (mt/with-non-admin-groups-no-collection-perms dest-coll
+ ;; Read but not curate: without the read grant, `resolve-collection-id` collapses an
+ ;; unreadable destination to not-found before `api/create-check` ever runs, so the
+ ;; assertion would pass on the wrong refusal and stop covering the create-check.
+ (perms/grant-collection-read-permissions! (perms/all-users-group) dest-coll)
+ (is (re-find #"(?i)permission"
+ (tool-error (call-tool! :rasta {:type "question"
+ :id card-id
+ :collection_id dest-coll}))))
+ (is (= 1 (t2/count :model/Card :name "Revenue")))))))
+
+(deftest duplicate-card-flavor-mismatch-test
+ (testing "GHY-4151: a model or metric passed as a question is a teaching error saying so, rather than
+ silently copying it as a question — the other card flavors aren't supported yet"
+ (mt/with-temp [:model/Card {card-id :id} {:type :model :dataset_query (venues-query)}]
+ (is (= (format "Card %d is a model — duplicate_content supports type \"question\" only." card-id)
+ (tool-error (call-tool! :crowberto {:type "question" :id card-id})))))))
+
+(deftest duplicate-archived-source-test
+ (testing "GHY-4151: a trashed source is refused for every type. Archived content keeps its real
+ collection_id (the trash is presentational) and neither copy path carries `:archived`
+ over, so duplicating would resurrect a live copy in the collection it was trashed from"
+ (mt/with-model-cleanup [:model/Card :model/Dashboard :model/Document]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:name "Trashed question"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}
+ :model/Dashboard {dash-id :id} {:name "Trashed dashboard" :collection_id coll-id}
+ :model/Document {doc-id :id} {:name "Trashed document"
+ :collection_id coll-id
+ :document (documents.tu/text->prose-mirror-ast "Gone.")}]
+ (doseq [[model id type] [[:model/Card card-id "question"]
+ [:model/Dashboard dash-id "dashboard"]
+ [:model/Document doc-id "document"]]]
+ (t2/update! model id {:archived true :archived_directly true})
+ (testing type
+ (is (= (format "%s %d is in the trash — restore it before duplicating." (name model) id)
+ (tool-error (call-tool! :crowberto {:type type :id id}))))))
+ ;; The calls above omit `collection_id`, so a copy that slipped past the guard would land in
+ ;; the caller's personal collection -- counting the *source* collection would pass either
+ ;; way. Count the destination, and the totals, so a resurrected copy has nowhere to hide.
+ (testing "and nothing was written"
+ (let [personal-id (:id (collection/user->personal-collection (mt/user->id :crowberto)))]
+ (doseq [model [:model/Card :model/Dashboard :model/Document]]
+ (testing model
+ (is (zero? (t2/count model :collection_id personal-id)))
+ (is (= 1 (t2/count model :collection_id coll-id)))))))))))
+
+;;; ------------------------------------------------- dashboard ----------------------------------------------------
+
+(defn- copied-dashcards
+ [dashboard-id]
+ (t2/select :model/DashboardCard :dashboard_id dashboard-id))
+
+(deftest duplicate-dashboard-shallow-test
+ (testing "GHY-4151: the default shallow copy re-uses the source's cards rather than duplicating them"
+ (mt/with-model-cleanup [:model/Dashboard :model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:name "Revenue"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}
+ :model/Dashboard {dash-id :id} {:name "Sales" :collection_id coll-id}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (let [personal-id (:id (collection/user->personal-collection (mt/user->id :crowberto)))
+ result (tool-result (call-tool! :crowberto {:type "dashboard" :id dash-id}))]
+ (is (=? {:type "dashboard" :name "Copy of Sales" :collection_id personal-id} result))
+ (is (not= dash-id (:id result)))
+ (testing "the copy's dashcards point at the original card"
+ (is (= [card-id] (map :card_id (copied-dashcards (:id result))))))
+ (testing "no card was duplicated"
+ (is (= 1 (t2/count :model/Card :name "Revenue")))))))))
+
+(deftest duplicate-dashboard-deep-test
+ (testing "GHY-4151: is_deep_copy also duplicates the dashboard's questions into the destination"
+ (mt/with-model-cleanup [:model/Dashboard :model/Card]
+ (mt/with-temp [:model/Collection {source-coll :id} {}
+ :model/Collection {dest-coll :id} {}
+ :model/Card {card-id :id} {:name "Revenue"
+ :type :question
+ :collection_id source-coll
+ :dataset_query (venues-query)}
+ :model/Dashboard {dash-id :id} {:name "Sales" :collection_id source-coll}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (let [result (tool-result (call-tool! :crowberto {:type "dashboard"
+ :id dash-id
+ :collection_id dest-coll
+ :is_deep_copy true}))
+ new-cards (map :card_id (copied-dashcards (:id result)))]
+ (is (=? {:type "dashboard" :collection_id dest-coll} result))
+ (is (= 1 (count new-cards)))
+ (is (not= [card-id] new-cards))
+ (testing "the duplicated card lands in the destination collection"
+ (is (=? {:name "Revenue" :collection_id dest-coll}
+ (t2/select-one :model/Card :id (first new-cards))))))))))
+
+(deftest duplicate-dashboard-deep-uncopied-test
+ (testing "GHY-4151: a deep copy reports cards it left behind as `uncopied`, and an unreadable one
+ is reported by id alone — the tool must not hand the agent the name or query of a card
+ the caller cannot read"
+ (mt/with-model-cleanup [:model/Dashboard :model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Collection {secret-coll :id} {}
+ :model/Card {secret-card :id} {:name "Salaries"
+ :type :question
+ :collection_id secret-coll
+ :dataset_query (venues-query)}
+ :model/Card {ok-card :id} {:name "Revenue"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}
+ :model/Dashboard {dash-id :id} {:name "Sales" :collection_id coll-id}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id secret-card}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id ok-card}]
+ (mt/with-non-admin-groups-no-collection-perms secret-coll
+ (let [result (tool-result (call-tool! :rasta {:type "dashboard"
+ :id dash-id
+ :is_deep_copy true}))]
+ (is (= [{:id secret-card}] (:uncopied result))
+ "the unreadable card must be reported by id alone — no name, no query")
+ (testing "the unreadable card is left out of the copy entirely"
+ (is (= 1 (count (copied-dashcards (:id result))))))
+ (testing "while the readable card is duplicated into the caller's personal collection —
+ a different collection from the source, so the name is not suffixed"
+ (is (= 1 (t2/count :model/Card
+ :name "Revenue"
+ :collection_id (:id (collection/user->personal-collection
+ (mt/user->id :rasta)))))))))))))
+
+(deftest duplicate-dashboard-shallow-uncopied-test
+ (testing "GHY-4218: a *shallow* copy drops unreadable cards too, and reports them. `card->decision`
+ evaluates its `:discard` branch before it ever consults `deep-copy?`, so the default
+ copy path can silently lose dashcards — the description used to promise `uncopied` only
+ for deep copies, giving an agent no reason to look at it here"
+ (mt/with-model-cleanup [:model/Dashboard :model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Collection {secret-coll :id} {}
+ :model/Card {secret-card :id} {:name "Salaries"
+ :type :question
+ :collection_id secret-coll
+ :dataset_query (venues-query)}
+ :model/Card {ok-card :id} {:name "Revenue"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}
+ :model/Dashboard {dash-id :id} {:name "Sales" :collection_id coll-id}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id secret-card}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id ok-card}]
+ (mt/with-non-admin-groups-no-collection-perms secret-coll
+ ;; No `is_deep_copy` — the documented default, and the path an agent takes unless it has a
+ ;; reason not to.
+ (let [result (tool-result (call-tool! :rasta {:type "dashboard" :id dash-id}))]
+ (is (= [{:id secret-card}] (:uncopied result))
+ "the unreadable card is reported by id alone on a shallow copy too")
+ (is (= 1 (:uncopied_count result)))
+ (testing "and it really is left out of the copy"
+ (is (= [ok-card] (map :card_id (copied-dashcards (:id result))))))))))))
+
+(deftest duplicate-uncopied-count-survives-readback-degradation-test
+ (testing "GHY-4218: a write-only token still learns the copy was partial. `:uncopied` itself must
+ not ride out — `cards-to-copy`'s `redact` reduces a card to its id only when it is
+ *unreadable*, so an archived-but-readable card keeps its real name, which would make the
+ write scope a read oracle. The scalar count carries the signal without the names"
+ (mt/with-model-cleanup [:model/Dashboard :model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Collection {secret-coll :id} {}
+ :model/Card {secret-card :id} {:name "Salaries"
+ :type :question
+ :collection_id secret-coll
+ :dataset_query (venues-query)}
+ :model/Card {ok-card :id} {:name "Revenue"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}
+ :model/Dashboard {dash-id :id} {:name "Sales" :collection_id coll-id}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id secret-card}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id ok-card}]
+ (mt/with-non-admin-groups-no-collection-perms secret-coll
+ (let [result (tool-result (call-tool! :rasta #{metabot.scope/agent-content-write}
+ {:type "dashboard" :id dash-id :is_deep_copy true}))]
+ (is (= #{:id :type :note :uncopied_count} (set (keys result))))
+ (is (= 1 (:uncopied_count result)))
+ (testing "the names of cards the token cannot read never appear"
+ (is (nil? (:uncopied result))))))))))
+
+(deftest duplicate-explicit-false-deep-copy-test
+ (testing "GHY-4218: `is_deep_copy: false` is the documented default, and the published strict
+ inputSchema marks every property required — so a strict client must send it. Rejecting
+ it refused a request the tool already serves; only an explicit `true` is wrong here"
+ (mt/with-model-cleanup [:model/Card :model/Document]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:name "Revenue"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}
+ :model/Document {doc-id :id} {:name "Notes"
+ :collection_id coll-id
+ :document (documents.tu/text->prose-mirror-ast "Hi.")}]
+ (testing "question"
+ (is (=? {:type "question" :name "Copy of Revenue"}
+ (tool-result (call-tool! :crowberto {:type "question"
+ :id card-id
+ :collection_id coll-id
+ :is_deep_copy false})))))
+ (testing "document"
+ (is (=? {:type "document" :name "Copy of Notes"}
+ (tool-result (call-tool! :crowberto {:type "document"
+ :id doc-id
+ :collection_id coll-id
+ :is_deep_copy false})))))
+ (testing "an explicit true is still a teaching error on a non-dashboard"
+ (is (= "`is_deep_copy` applies to dashboards only — omit it when duplicating a question."
+ (tool-error (call-tool! :crowberto {:type "question" :id card-id :is_deep_copy true})))))))))
+
+(deftest duplicate-dashboard-shallow-with-dashboard-questions-test
+ (testing "GHY-4151: a shallow copy of a dashboard holding dashboard questions is a teaching error
+ naming is_deep_copy"
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Dashboard {dash-id :id} {:name "Sales" :collection_id coll-id}
+ :model/Card _ {:name "Inline question"
+ :type :question
+ :collection_id coll-id
+ :dashboard_id dash-id
+ :dataset_query (venues-query)}]
+ (let [message (tool-error (call-tool! :crowberto {:type "dashboard" :id dash-id}))]
+ (is (re-find #"is_deep_copy" message))
+ (is (re-find #"questions saved inside it" message))))))
+
+(deftest duplicate-deep-copy-wrong-type-test
+ (testing "GHY-4151: is_deep_copy is dashboards-only and says so"
+ (mt/with-temp [:model/Card {card-id :id} {:type :question :dataset_query (venues-query)}]
+ (is (= "`is_deep_copy` applies to dashboards only — omit it when duplicating a question."
+ (tool-error (call-tool! :crowberto {:type "question" :id card-id :is_deep_copy true})))))))
+
+;;; -------------------------------------------------- document ----------------------------------------------------
+
+(deftest duplicate-document-test
+ (testing "GHY-4218: a document copy lands in the caller's personal collection under a \"Copy of\" name"
+ (mt/with-model-cleanup [:model/Document]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Document {doc-id :id} {:name "Q3 summary"
+ :collection_id coll-id
+ :document (documents.tu/text->prose-mirror-ast "Revenue was up.")}]
+ (let [personal-id (:id (collection/user->personal-collection (mt/user->id :crowberto)))
+ result (tool-result (call-tool! :crowberto {:type "document" :id doc-id}))
+ copy (t2/select-one :model/Document :id (:id result))]
+ (is (=? {:type "document" :name "Copy of Q3 summary" :collection_id personal-id} result))
+ (is (not= doc-id (:id result)))
+ (is (= (:document (t2/select-one :model/Document :id doc-id))
+ (:document copy))))))))
+
+(deftest duplicate-document-copies-its-cards-test
+ (testing "GHY-4151: the questions saved inside a document are copied along with it"
+ (mt/with-model-cleanup [:model/Document :model/Card]
+ (mt/with-temp [:model/Collection {source-coll :id} {}
+ :model/Collection {dest-coll :id} {}
+ :model/Document {doc-id :id} {:name "Q3 summary"
+ :collection_id source-coll
+ :document (documents.tu/text->prose-mirror-ast "Revenue was up.")}
+ :model/Card _ {:name "Inline chart"
+ :type :question
+ :collection_id source-coll
+ :document_id doc-id
+ :dataset_query (venues-query)}]
+ (let [result (tool-result (call-tool! :crowberto {:type "document"
+ :id doc-id
+ :collection_id dest-coll}))]
+ (is (=? [{:name "Inline chart" :collection_id dest-coll}]
+ (t2/select :model/Card :document_id (:id result)))))))))
+
+;;; ------------------------------------------- ids, permissions, scopes -------------------------------------------
+
+(deftest entity-id-test
+ (testing "GHY-4151: id accepts a 21-char entity_id as well as a numeric id"
+ (mt/with-model-cleanup [:model/Dashboard]
+ (mt/with-temp [:model/Dashboard {dash-id :id dash-eid :entity_id} {:name "Sales"}]
+ (let [result (tool-result (call-tool! :crowberto {:type "dashboard" :id dash-eid}))]
+ (is (not= dash-id (:id result)))
+ (is (= "Copy of Sales" (:name result)))))))
+ (testing "GHY-4151: a malformed id is a teaching error naming both accepted shapes"
+ (is (= "Invalid id \"nope\" — pass the positive numeric id, or the 21-character entity_id from a search or list result."
+ (tool-error (call-tool! :crowberto {:type "dashboard" :id "nope"}))))))
+
+(deftest unknown-type-test
+ (testing "GHY-4151: a type outside the enum is rejected by argument validation"
+ (is (re-find #"should be either"
+ (tool-error (call-tool! :crowberto {:type "collection" :id 1}))))))
+
+(deftest source-read-permission-test
+ (testing "GHY-4151: an unreadable source collapses to not-found — the response is never an existence oracle"
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}
+ :model/Dashboard {dash-id :id} {:collection_id coll-id}]
+ (is (= (format "Card %d not found — it may not exist, or you may not have access to it." card-id)
+ (tool-error (call-tool! :rasta {:type "question" :id card-id}))))
+ (is (= (format "Dashboard %d not found — it may not exist, or you may not have access to it." dash-id)
+ (tool-error (call-tool! :rasta {:type "dashboard" :id dash-id}))))))))
+
+(deftest destination-write-permission-test
+ (testing "GHY-4151: copying into a collection the caller can't curate is refused, and nothing is written"
+ (mt/with-temp [:model/Collection {source-coll :id} {}
+ :model/Collection {dest-coll :id} {}
+ :model/Card {card-id :id} {:name "Revenue"
+ :type :question
+ :collection_id source-coll
+ :dataset_query (venues-query)}]
+ (mt/with-non-admin-groups-no-collection-perms dest-coll
+ ;; A bare `:isError` cannot tell a permission refusal from a Malli failure, a not-found on
+ ;; the destination id, or an internal error sanitized to "Internal error" -- assert the
+ ;; refusal actually mentions permissions, the way every other error test here does. That
+ ;; needs the destination readable but not curatable: an unreadable one collapses to
+ ;; not-found in `resolve-collection-id` before the create-check runs.
+ (perms/grant-collection-read-permissions! (perms/all-users-group) dest-coll)
+ (is (re-find #"(?i)permission"
+ (tool-error (call-tool! :rasta {:type "question"
+ :id card-id
+ :collection_id dest-coll}))))
+ (is (= 1 (t2/count :model/Card :name "Revenue")))))))
+
+(deftest scope-test
+ (testing "GHY-4151: the tool itself requires agent:content:write"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:name "Sales"}]
+ (is (re-find #"^Insufficient scope to call tool: duplicate_content\."
+ (tool-error (call-tool! :crowberto #{metabot.scope/agent-content-read}
+ {:type "dashboard" :id dash-id}))))))
+ ;; GHY-4225 folded duplicate_content's per-type create scopes into the single
+ ;; `agent:content:write` the tool already gates on, so there is no second scope to check.
+ (testing "the tool's own write scope is all a copy needs"
+ (mt/with-model-cleanup [:model/Dashboard]
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:name "Sales"}]
+ ;; Without agent:content:read the echo degrades to the GHY-4227 ack, so the copy row is
+ ;; what proves the write landed.
+ (let [result (tool-result (call-tool! :crowberto #{metabot.scope/agent-content-write}
+ {:type "dashboard" :id dash-id}))]
+ (is (not= dash-id (:id result)))
+ (is (= "Copy of Sales" (t2/select-one-fn :name :model/Dashboard :id (:id result)))))))))
+
+(deftest readback-requires-read-scope-test
+ (testing "GHY-4227: new_name defaults to \"Copy of <source name>\", so echoing the copy's name hands
+ a write-only token the source's name — the echo degrades to an ack without agent:content:read"
+ (mt/with-model-cleanup [:model/Dashboard]
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:name "Board deck Q3"}]
+ (let [result (tool-result (call-tool! :crowberto #{metabot.scope/agent-content-write}
+ {:type "dashboard" :id dash-id}))]
+ ;; `:type` is the caller's own argument, so it survives as an ack-key; the source-derived
+ ;; `:name` and `:collection_id` do not.
+ (is (= #{:id :type :note} (set (keys result))))
+ (is (= "dashboard" (:type result)))
+ (is (re-find #"agent:content:read" (:note result)))
+ (testing "and the copy still happened"
+ (is (= "Copy of Board deck Q3"
+ (t2/select-one-fn :name :model/Dashboard :id (:id result)))))))
+ (testing "a token that could read the copy back keeps the full echo"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:name "Board deck Q4"}]
+ (is (=? {:type "dashboard" :name "Copy of Board deck Q4"}
+ (tool-result (call-tool! :crowberto #{metabot.scope/agent-content-write
+ metabot.scope/agent-content-read}
+ {:type "dashboard" :id dash-id}))))))))
+ (testing "GHY-4227: the leak is the source's name, so a caller-supplied new_name degrades too —
+ the copy's own row fields are no more readable than the source"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:name "Revenue by region"
+ :type :question
+ :collection_id coll-id
+ :dataset_query (venues-query)}]
+ (let [result (tool-result (call-tool! :crowberto #{metabot.scope/agent-content-write}
+ {:type "question" :id card-id :new_name "Mine"}))]
+ (is (= #{:id :type :note} (set (keys result))))
+ (is (= "Mine" (t2/select-one-fn :name :model/Card :id (:id result)))))))))
diff --git a/test/metabase/mcp/v2/tools/execute_sql_test.clj b/test/metabase/mcp/v2/tools/execute_sql_test.clj
new file mode 100644
index 00000000000..4a6bbc2232d
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/execute_sql_test.clj
@@ -0,0 +1,460 @@
+(ns metabase.mcp.v2.tools.execute-sql-test
+ "Contract tests for the v2 `execute_sql` tool, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised on
+ every call. Handle ownership and store-level guards are owned by
+ [[metabase.mcp.v2.common-test]]; `execute_query`'s MBQL/cursor contract by its own suite —
+ neither is re-covered here."
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer [deftest is testing use-fixtures]]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.tools.query :as tools.query]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(def ^:private sql-scope
+ #{"agent:sql:run"})
+
+(defn- call!
+ "Call `tool-name` (default `execute_sql`) through the registry dispatch seam as the
+ already-bound current user, carrying `scopes` the way a bearer token would."
+ ([session-id arguments] (call! session-id "execute_sql" arguments))
+ ([session-id tool-name arguments] (call! session-id tool-name arguments sql-scope))
+ ([session-id tool-name arguments scopes]
+ (registry/call-tool scopes session-id tool-name arguments)))
+
+(defn- dispatch-error?
+ "Whether a [[call!]] outcome is an error, at either layer: a registry-level rejection
+ (`{:error …}`, from a scope denial or an args-schema failure) or `:isError` tool content."
+ [{:keys [result error]}]
+ (boolean (or error (:isError result))))
+
+(defn- response-text
+ "The outcome's text block, or a registry-level rejection's message."
+ [{:keys [result error]}]
+ (if error (:message error) (-> result :content first :text)))
+
+(defn- payload
+ "Parse the JSON payload line of a successful response. Throws if the call errored at either
+ layer, so an error can never masquerade as an empty result."
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info "expected success, got tool error" {:outcome outcome})))
+ (-> outcome response-text str/split-lines first json/decode+kw))
+
+(defn- steering-line
+ "The steering sentence appended after the JSON payload, or nil on an unsteered response.
+ Throws on an error at either layer, for the same reason as [[payload]]."
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info "expected success, got tool error" {:outcome outcome})))
+ (second (str/split-lines (response-text outcome))))
+
+(defn- error-text
+ "The message of an errored call, at either layer. Throws if the call succeeded, so a passing
+ call can never satisfy an error assertion."
+ [outcome]
+ (when-not (dispatch-error? outcome)
+ (throw (ex-info "expected tool error, got success" {:outcome outcome})))
+ (response-text outcome))
+
+(defn- stored-query
+ "Decode the serialized query a handle stores, exactly as downstream consumers will read it."
+ [session-id user-id handle]
+ (-> (mcp.session/resolve-query-handle session-id user-id handle)
+ :encoded_query
+ u/decode-base64
+ json/decode+kw))
+
+(defn- count-value
+ "The single count cell of a `SELECT count(*) …` payload."
+ [body]
+ (-> body :rows first first))
+
+;;; ------------------------------------------------ Happy paths ---------------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-happy-path-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:database_id (mt/id)
+ :row_limit 3
+ :sql "SELECT ID, TOTAL FROM ORDERS ORDER BY ID"})
+ body (payload result)]
+ (testing "rows arrive in the dataset shape, capped at row_limit, with a minted handle"
+ (is (= 3 (:returned body)))
+ (is (= 3 (count (:rows body))))
+ (is (true? (:truncated body)))
+ (is (string? (:query_handle body)))
+ (is (= ["ID" "TOTAL"] (mapv :name (:cols body)))))
+ (testing "response cols carry only the wire projection — no internal metadata keys"
+ (doseq [col (:cols body)]
+ (is (string? (:base_type col)))
+ (is (empty? (dissoc col :name :base_type :display_name :effective_type))
+ "any other key is internal metadata leaking onto the wire")))
+ (testing "a truncated page steers to narrowing the SQL — SQL results never mint a cursor"
+ (is (not (contains? body :next_cursor)))
+ (is (= (str "returned 3 rows, more available — narrow the SQL (add filters/aggregation), "
+ "raise `row_limit` (max 2000), or page with `ORDER BY <unique key>` + "
+ "`WHERE <key> > <last value returned>`")
+ (steering-line result)))
+ (is (not (str/includes? (steering-line result) "export"))
+ "no export tool exists in v2 — steering at one sends the agent after an affordance it does not have"))
+ (testing "the response is text-only; there is no structuredContent channel to diverge from it"
+ (is (nil? (:structuredContent result))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-truncation-signal-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:database_id (mt/id)
+ :row_limit 100
+ :sql "SELECT ID FROM ORDERS ORDER BY ID LIMIT 5"})
+ body (payload result)]
+ (testing "a page under row_limit is not truncated and carries no steering line"
+ (is (= 5 (:returned body)))
+ (is (false? (:truncated body)))
+ (is (nil? (steering-line result))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-exact-fill-is-not-truncated-test
+ (testing "a result whose size exactly equals row_limit is complete, not truncated — the tool
+ fetches one row past the limit so truncation is observed rather than inferred from a
+ full page. Mis-reporting it would steer the agent to narrow SQL that was already
+ right, and execute_sql mints no cursor that could correct the mistake."
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:database_id (mt/id)
+ :row_limit 5
+ :sql "SELECT ID FROM ORDERS ORDER BY ID LIMIT 5"})
+ body (payload result)]
+ (is (= 5 (:returned body)))
+ (is (= 5 (count (:rows body))))
+ (is (false? (:truncated body)))
+ (is (nil? (steering-line result))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-probe-row-not-served-test
+ (testing "the extra row fetched to detect truncation is dropped, never served: a truncated
+ page holds exactly row_limit rows and stops at the row_limit'th value"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ body (payload (call! sid {:database_id (mt/id)
+ :row_limit 3
+ :sql "SELECT ID FROM ORDERS ORDER BY ID LIMIT 10"}))]
+ (is (= 3 (:returned body)))
+ (is (true? (:truncated body)))
+ (is (= [[1] [2] [3]] (:rows body))))))))
+
+;;; --------------------------------------------- Template tag values ----------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-template-tag-binding-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ count-sql "SELECT count(*) AS C FROM ORDERS WHERE TOTAL > {{min_total}}"
+ full-count (count-value (payload (call! sid {:database_id (mt/id)
+ :sql "SELECT count(*) AS C FROM ORDERS"})))]
+ (testing "a numeric value binds as a numeric parameter and filters rows"
+ (is (= full-count (count-value (payload (call! sid {:database_id (mt/id)
+ :sql count-sql
+ :template_tag_values {:min_total -1e9}})))))
+ (is (zero? (count-value (payload (call! sid {:database_id (mt/id)
+ :sql count-sql
+ :template_tag_values {:min_total 1e9}}))))))
+ (testing "an injection-shaped string binds as a parameter value, never spliced into the SQL"
+ ;; bound as a value it fails the numeric comparison's typing; spliced it would have
+ ;; returned the full count
+ (is (str/starts-with? (error-text (call! sid {:database_id (mt/id)
+ :sql count-sql
+ :template_tag_values {:min_total "0 OR 1=1"}}))
+ "Query failed:")))
+ (testing "a boolean value binds as a boolean parameter"
+ (is (zero? (count-value (payload (call! sid {:database_id (mt/id)
+ :sql "SELECT count(*) AS C FROM ORDERS WHERE {{flag}}"
+ :template_tag_values {:flag false}}))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-template-tag-teaching-errors-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))]
+ (testing "a value naming no {{tag}} in the SQL is a teaching error listing the tags that exist"
+ (let [msg (error-text (call! sid {:database_id (mt/id)
+ :sql "SELECT count(*) AS C FROM ORDERS WHERE TOTAL > {{min_total}}"
+ :template_tag_values {:nope 1}}))]
+ (is (str/includes? msg "No {{nope}} template tag"))
+ (is (str/includes? msg "Tags found: min_total"))))
+ (testing "with no tags in the SQL at all, the error says so"
+ (is (str/includes? (error-text (call! sid {:database_id (mt/id)
+ :sql "SELECT 1"
+ :template_tag_values {:nope 1}}))
+ "Tags found: none")))
+ (testing "snippet tags cannot be populated — they splice server-side SQL text"
+ (is (str/includes? (error-text (call! sid {:database_id (mt/id)
+ :sql "SELECT * FROM ORDERS WHERE {{snippet: my filter}}"
+ :template_tag_values {(keyword "snippet: my filter") "x"}}))
+ "snippet-reference tag")))
+ (testing "card-reference tags cannot be populated — they splice server-side SQL text"
+ (is (str/includes? (error-text (call! sid {:database_id (mt/id)
+ :sql "SELECT * FROM {{#123-some-card}}"
+ :template_tag_values {(keyword "#123-some-card") "x"}}))
+ "card-reference tag")))))))
+
+;;; -------------------------------------------------- Prompt ------------------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-prompt-rides-the-handle-test
+ (testing "the user's original request is stored with a SQL-minted handle, so visualize_query can
+ surface it in the feedback flow exactly as it does for execute_query handles — the tool
+ description advertises these handles as visualize-ready, so dropping the prompt would
+ silently degrade every SQL-derived chart"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ uid (mt/user->id :crowberto)
+ ;; the raw store accessor, not common/resolve-query-handle! — that one re-runs the
+ ;; native-query guard and refuses SQL handles by design (see the handle-contract test)
+ handle-prompt (fn [body]
+ (:prompt (mcp.session/resolve-query-handle sid uid (:query_handle body))))]
+ (testing "on the execute path"
+ (is (= "show me the first orders"
+ (handle-prompt (payload (call! sid {:database_id (mt/id)
+ :sql "SELECT ID FROM ORDERS ORDER BY ID"
+ :row_limit 2
+ :prompt "show me the first orders"}))))))
+ (testing "and on the validate_only path, which exists to stage SQL for exactly that flow"
+ (is (= "stage this for a chart"
+ (handle-prompt (payload (call! sid {:database_id (mt/id)
+ :sql "SELECT 1"
+ :validate_only true
+ :prompt "stage this for a chart"}))))))
+ (testing "an omitted prompt stores nil rather than failing the call"
+ (is (nil? (handle-prompt (payload (call! sid {:database_id (mt/id)
+ :sql "SELECT 1"})))))))))))
+
+;;; ------------------------------------------------ validate_only -------------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-validate-only-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ uid (mt/user->id :crowberto)]
+ (testing "validate_only mints a handle without executing — even unrunnable SQL is accepted"
+ (let [sql "SELECT FROM WHERE kaboom"
+ result (call! sid {:database_id (mt/id) :sql sql :validate_only true})
+ body (payload result)]
+ (is (= {:returned 0 :truncated false} (select-keys body [:returned :truncated])))
+ (is (not (contains? body :rows)))
+ (is (not (contains? body :cols)))
+ (is (str/includes? (response-text result) "not executed"))
+ (testing "the handle stores the SQL verbatim"
+ (is (= sql (-> (stored-query sid uid (:query_handle body)) :stages first :native))))))
+ (testing "the handle carries bound template-tag values, so a later run reproduces this one"
+ (let [result (call! sid {:database_id (mt/id)
+ :sql "SELECT count(*) AS C FROM ORDERS WHERE TOTAL > {{min_total}}"
+ :template_tag_values {:min_total 7}
+ :validate_only true})
+ stored (stored-query sid uid (:query_handle (payload result)))]
+ (is (= [{:type "number" :target ["variable" ["template-tag" "min_total"]] :value 7}]
+ (:parameters stored)))
+ (is (= "number" (-> stored :stages first :template-tags first :type)))))))))
+
+;;; ---------------------------------------------- MBQL-expressible hint -------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-mbql-hint-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ sql "SELECT PRODUCT_ID, count(*) FROM ORDERS GROUP BY PRODUCT_ID"
+ hint @#'tools.query/mbql-hint]
+ (testing "an MBQL-expressible aggregate carries the hint on both the execute and validate_only paths"
+ (is (= hint (:hint (payload (call! sid {:database_id (mt/id) :sql sql})))))
+ (is (= hint (:hint (payload (call! sid {:database_id (mt/id) :sql sql :validate_only true}))))))
+ (testing "other SQL carries no hint key at all"
+ (is (not (contains? (payload (call! sid {:database_id (mt/id) :sql "SELECT ID FROM ORDERS ORDER BY ID LIMIT 5"}))
+ :hint))))))))
+
+(deftest ^:parallel mbql-expressible-sql?-test
+ (let [expressible? #'tools.query/mbql-expressible-sql?]
+ (testing "plain aggregates, with joins/having/order/limit and trailing semicolon, are expressible"
+ (is (true? (expressible? "SELECT status, count(*) FROM orders GROUP BY status")))
+ (is (true? (expressible? (str "select o.status, count(*) from orders o join products p on p.id = o.product_id "
+ "where o.total > 10 group by o.status having count(*) > 5 order by 2 desc limit 10;")))))
+ (testing "keywords inside string literals and comments do not disqualify"
+ (is (true? (expressible? "SELECT status, count(*) FROM orders WHERE note = 'with over (' GROUP BY status")))
+ (is (true? (expressible? "-- with\nSELECT status, count(*) FROM orders /* over ( */ GROUP BY status"))))
+ (testing "no GROUP BY, CTEs, window functions, set ops, subselects, template tags, and multiple statements are not"
+ (is (false? (expressible? "SELECT id FROM orders ORDER BY id")))
+ (is (false? (expressible? "WITH t AS (SELECT status FROM orders) SELECT status, count(*) FROM t GROUP BY status")))
+ (is (false? (expressible? "SELECT status, count(*) OVER () FROM orders GROUP BY status")))
+ (is (false? (expressible? "SELECT status, count(*) FROM orders GROUP BY status UNION SELECT 'x', 0")))
+ (is (false? (expressible? "SELECT status, count(*) FROM (SELECT * FROM orders) o GROUP BY status")))
+ (is (false? (expressible? "SELECT status, count(*) FROM orders WHERE {{status}} GROUP BY status")))
+ (is (false? (expressible? "SELECT status, count(*) FROM orders GROUP BY status; DROP TABLE x"))))
+ (testing "GHY-4363: a long literal or an unbalanced quote must not blow the stack"
+ ;; the literal-blanking regex used to be `'(?:[^']|'')*'`, an alternation under a quantifier,
+ ;; which java.util.regex compiles to one stack frame per character consumed. A single
+ ;; unterminated quote — an ordinary agent typo — made it backtrack across the whole query and
+ ;; throw StackOverflowError, which is an Error and so escapes the tool's Exception handler.
+ ;; the point of each of these is that it RETURNS rather than throwing; the particular
+ ;; verdict is incidental
+ (is (true? (expressible? (str "select x from t where note = '" (apply str (repeat 8000 \x))
+ "' group by x"))))
+ (is (false? (expressible? (str "select * from t where a = 'abc and b = "
+ (apply str (repeat 8000 \y))))))
+ (is (true? (expressible? (str "SELECT status, count(*) FROM orders WHERE note = '"
+ (apply str (repeat 8000 \z))
+ "' GROUP BY status")))))))
+
+;;; ---------------------------------------------------- Gates -----------------------------------------------------
+
+;; not ^:parallel: mt/with-temporary-setting-values on the shared kill-switch setting
+(deftest execute-sql-kill-switch-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temporary-setting-values [mcp-execute-sql-enabled false]
+ (let [sid (str (random-uuid))]
+ (testing "the kill switch refuses execution and names the setting that re-enables it"
+ (is (str/includes? (error-text (call! sid {:database_id (mt/id) :sql "SELECT 1"}))
+ "mcp-execute-sql-enabled")))
+ (testing "validate_only is refused identically — it is not a kill-switch bypass"
+ (is (str/includes? (error-text (call! sid {:database_id (mt/id) :sql "SELECT 1" :validate_only true}))
+ "mcp-execute-sql-enabled")))
+ (testing "no handle is minted on either refused path"
+ (is (zero? (t2/count :model/McpQueryHandle :mcp_session_id sid))))))))
+
+;; not ^:parallel: rebinds the shared data-perms graph
+(deftest execute-sql-native-permission-test
+ (let [args {:database_id (mt/id) :sql "SELECT count(*) AS C FROM ORDERS"}]
+ (testing "a user who can browse the database but lacks native permission gets the permission error"
+ (mt/with-all-users-data-perms-graph! {(mt/id) {:view-data :unrestricted
+ :create-queries :query-builder}}
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))]
+ (is (str/includes? (error-text (call! sid args))
+ "permission to run native queries"))
+ (testing "validate_only is refused identically, and neither path mints a handle"
+ (is (str/includes? (error-text (call! sid (assoc args :validate_only true)))
+ "permission to run native queries"))
+ (is (zero? (t2/count :model/McpQueryHandle :mcp_session_id sid))))))))
+ (testing "granting native permission makes the identical call succeed"
+ (mt/with-all-users-data-perms-graph! {(mt/id) {:view-data :unrestricted
+ :create-queries :query-builder-and-native}}
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [body (payload (call! (str (random-uuid)) args))]
+ (is (= 1 (:returned body))))))))))
+
+;; not ^:parallel: rebinds the shared data-perms graph
+(deftest execute-sql-existence-collapse-test
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ normalize #(str/replace % #"\d+" "<id>")
+ denied (error-text (call! sid {:database_id (mt/id) :sql "SELECT 1"}))
+ missing (error-text (call! sid {:database_id Integer/MAX_VALUE :sql "SELECT 1"}))]
+ (testing "an unreadable database and a nonexistent one yield string-identical not-found errors"
+ (is (= (normalize denied) (normalize missing)))
+ (is (str/includes? denied "not found")))
+ (testing "the refused validate_only path mints no handle"
+ (error-text (call! sid {:database_id (mt/id) :sql "SELECT 1" :validate_only true}))
+ (is (zero? (t2/count :model/McpQueryHandle :mcp_session_id sid))))))))
+
+;; not ^:parallel: mt/with-temporary-setting-values and rebound data perms
+(deftest execute-sql-gate-status-codes-test
+ (let [gate-ex-data (fn [database-id]
+ (try
+ (#'tools.query/check-execute-sql-gates! database-id)
+ nil
+ (catch clojure.lang.ExceptionInfo e (ex-data e))))]
+ ;; the user binding sits inside each perms block: binding it once around all three would
+ ;; freeze the per-user permissions cache before the perms macros change the graph
+ (testing "the kill switch refuses with a 403"
+ (mt/with-temporary-setting-values [mcp-execute-sql-enabled false]
+ (mt/with-current-user (mt/user->id :rasta)
+ (is (= 403 (:status-code (gate-ex-data (mt/id))))))))
+ (testing "an invisible database is a 404, whether it exists or not"
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-current-user (mt/user->id :rasta)
+ (is (= 404 (:status-code (gate-ex-data (mt/id)))))
+ (is (= 404 (:status-code (gate-ex-data Integer/MAX_VALUE)))))))
+ (testing "a browsable database without native permission is a 403"
+ (mt/with-all-users-data-perms-graph! {(mt/id) {:view-data :unrestricted
+ :create-queries :query-builder}}
+ (mt/with-current-user (mt/user->id :rasta)
+ (is (= 403 (:status-code (gate-ex-data (mt/id))))))))))
+
+;;; ------------------------------------------------ Handle contract -----------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-handle-rejected-by-execute-query-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ handle (:query_handle (payload (call! sid {:database_id (mt/id)
+ :sql "SELECT 1"
+ :validate_only true})))]
+ (testing "execute_query refuses an execute_sql handle and steers back to execute_sql"
+ (is (= "Native queries are not supported here; use execute_sql instead."
+ (error-text (call! sid "execute_query" {:query_handle handle}
+ #{"agent:query:run"})))))))))
+
+;;; ---------------------------------------------------- Scope -----------------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-sql-scope-test
+ (testing "the tool's scope is advertised, so a token can actually be granted it"
+ (is (contains? (registry/registered-scopes) "agent:sql:run")))
+ (testing "scope gating holds on both surfaces: tools/list and tools/call"
+ (let [listed-names #(into #{} (map :name) (registry/list-tools %))]
+ (is (contains? (listed-names sql-scope) "execute_sql"))
+ (is (not (contains? (listed-names #{"agent:query:run"}) "execute_sql")))))
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [sid (str (random-uuid))
+ args {:database_id (mt/id) :sql "SELECT 1"}]
+ (testing "a token holding only execute_query's scope cannot call execute_sql"
+ (is (str/includes? (error-text (call! sid "execute_sql" args #{"agent:query:run"}))
+ "Insufficient scope")))
+ (testing "the identical call succeeds with the SQL-execute scope"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (is (= 1 (:returned (payload (call! sid args))))))))))
+
+;;; ------------------------------------------------- Validation ---------------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup guards against a validation bug minting handles
+(deftest execute-sql-argument-validation-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))]
+ (testing "row_limit above the cap is a validation error naming the argument"
+ (is (str/includes? (error-text (call! sid {:database_id (mt/id)
+ :sql "SELECT 1"
+ :row_limit 2001}))
+ "row_limit")))
+ (testing "sql is required"
+ (is (str/includes? (error-text (call! sid {:database_id (mt/id)}))
+ "sql")))))))
+
+(deftest ^:parallel value->tag-type-test
+ (testing "template-tag types are derived from the JSON value type"
+ (is (= :number (#'tools.query/value->tag-type 1)))
+ (is (= :number (#'tools.query/value->tag-type 1.5)))
+ (is (= :boolean (#'tools.query/value->tag-type true)))
+ (is (= :boolean (#'tools.query/value->tag-type false)))
+ (is (= :text (#'tools.query/value->tag-type "x")))))
diff --git a/test/metabase/mcp/v2/tools/learn_test.clj b/test/metabase/mcp/v2/tools/learn_test.clj
new file mode 100644
index 00000000000..07374a2a634
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/learn_test.clj
@@ -0,0 +1,129 @@
+(ns metabase.mcp.v2.tools.learn-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ ;; every tool namespace, so the pointer sweep below sees every registered description
+ [metabase.mcp.v2.api]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.skills :as skills]
+ [metabase.mcp.v2.tools.learn :as learn]))
+
+(set! *warn-on-reflection* true)
+
+(comment learn/keep-me)
+
+(defn- call
+ [args]
+ (:result (registry/call-tool nil (str (random-uuid)) "learn" args)))
+
+(defn- text-of
+ [result]
+ (-> result :content first :text))
+
+(deftest ^:parallel catalog-test
+ (testing "learn() lists every pack with its description"
+ (let [result (call {})]
+ (is (not (:isError result)) (text-of result))
+ (doseq [topic (skills/topics)]
+ (is (str/includes? (text-of result) topic))))))
+
+(deftest ^:parallel every-pack-loads-test
+ (testing "learn(topic) returns each pack's whole SKILL.md, frontmatter included"
+ (doseq [topic (skills/topics)]
+ (let [result (call {:topic topic})]
+ (is (not (:isError result)) (text-of result))
+ (is (str/starts-with? (text-of result) "---")
+ (str topic " should start with skill frontmatter"))
+ (is (str/includes? (text-of result) (str "name: " topic)))))))
+
+(deftest ^:parallel references-load-test
+ (testing "every reference a pack declares is fetchable by name"
+ (doseq [topic (skills/topics)
+ ref (skills/reference-names topic)]
+ (let [result (call {:topic topic :reference ref})]
+ (is (not (:isError result)) (text-of result))
+ (is (pos? (count (text-of result)))))))
+ (testing "a skill with references names them in its footer"
+ (is (str/includes? (text-of (call {:topic "query-dialect"})) "operators"))))
+
+(deftest ^:parallel pack-size-budget-test
+ (testing "no SKILL.md exceeds the pack size budget (roughly 6k tokens)"
+ (doseq [topic (skills/topics)]
+ (is (< (count (skills/skill-text topic)) 24000)
+ (str topic " exceeds the SKILL.md size budget")))))
+
+(deftest ^:parallel unknown-topic-and-reference-test
+ (testing "an unknown topic is a teaching error listing what exists"
+ (let [result (call {:topic "nope"})]
+ (is (:isError result))
+ (is (str/includes? (text-of result) "query-dialect"))))
+ (testing "an unknown reference is a teaching error naming the topic's references"
+ (let [result (call {:topic "query-dialect" :reference "nope"})]
+ (is (:isError result))
+ (is (str/includes? (text-of result) "operators"))))
+ (testing "a reference without a topic is a teaching error"
+ (let [result (call {:reference "operators"})]
+ (is (:isError result))
+ (is (str/includes? (text-of result) "topic")))))
+
+(deftest ^:parallel examples-speak-the-v2-dialect-test
+ (testing "packs never teach the CLI/REST dialects the v2 tools don't accept"
+ (doseq [topic (skills/topics)
+ :let [text (str (skills/skill-text topic)
+ (str/join (map #(skills/reference-text topic %)
+ (skills/reference-names topic))))]
+ leaked ["mb card" "mb dashboard" "mb query" "mb skills" "mb uuid" "--profile" "--dry-run"]]
+ (testing (str topic " must not mention " (pr-str leaked))
+ (is (not (str/includes? text leaked)))))))
+
+(defn- tool-descriptions
+ "Every registered tool's description. `nil` token-scopes sees the whole surface."
+ []
+ (keep :description (registry/list-tools nil)))
+
+(defn- learn-description
+ []
+ (->> (registry/list-tools nil)
+ (filter #(= "learn" (:name %)))
+ first
+ :description))
+
+(deftest ^:parallel catalog-reaches-the-tool-description-test
+ (testing "the learn description names every pack and reference — it is the catalog a client
+ that never calls learn() sees, and nothing else ties it to skills/packs, so a new
+ pack lands in the registry while the advertised catalog silently omits it"
+ (let [description (learn-description)]
+ (is (some? description) "the learn tool is registered")
+ (doseq [topic (skills/topics)]
+ (is (str/includes? description topic)
+ (str topic " is in skills/packs but missing from the learn tool description")))
+ (doseq [topic (skills/topics)
+ ref (skills/reference-names topic)]
+ (is (str/includes? description ref)
+ (str "reference " ref " of " topic " is missing from the learn tool description"))))))
+
+(def ^:private learn-pointer-re
+ "Matches learn(\"topic\") and learn(\"topic\", \"reference\") as they read at runtime. Excluding
+ `<` from both names skips the `learn(\"<topic>\", \"<name>\")` placeholders the skill footer
+ and the tool descriptions spell out — a real pack or reference name never contains one."
+ #"learn\(\"([^\"<]+)\"(?:,\s*\"([^\"<]+)\")?\)")
+
+(deftest ^:parallel learn-pointers-resolve-test
+ (testing "every learn(...) pointer in a tool description or pack body names a topic and
+ reference that exist — renaming a pack otherwise leaves pointers aimed at nothing,
+ and the model only finds out by calling learn() and getting a teaching error"
+ (let [pack-texts (concat (map skills/skill-text (skills/topics))
+ (for [topic (skills/topics)
+ ref (skills/reference-names topic)]
+ (skills/reference-text topic ref)))
+ pointers (for [text (concat (tool-descriptions) pack-texts)
+ match (re-seq learn-pointer-re (str text))]
+ match)
+ topics (set (skills/topics))]
+ (is (seq pointers) "the sweep found pointers — an empty sweep would pass vacuously")
+ (doseq [[whole topic ref] pointers]
+ (is (contains? topics topic)
+ (str whole " names a topic that does not exist"))
+ (when ref
+ (is (contains? (set (skills/reference-names topic)) ref)
+ (str whole " names a reference that does not exist")))))))
diff --git a/test/metabase/mcp/v2/tools/metric_test.clj b/test/metabase/mcp/v2/tools/metric_test.clj
new file mode 100644
index 00000000000..14284ceb5ea
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/metric_test.clj
@@ -0,0 +1,611 @@
+(ns metabase.mcp.v2.tools.metric-test
+ "Contract tests for the `metric_write` v2 MCP tool, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised for
+ free. A metric is a Card of type `metric`, so the card write/permission stack itself is owned
+ by `metabase.queries.*` and the metric shape rule by `metabase.lib.query`; this suite pins the
+ tool's own contract on top of them: the `definition` query sources, the shape gate's teaching
+ errors, and the refusal to retype a question into a metric."
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.api.macros.scope :as scope]
+ [metabase.collections.models.collection :as collection]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the tool the assertions below drive.
+ [metabase.mcp.v2.tools.metric :as tools.metric]
+ [metabase.permissions.core :as perms]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(comment tools.metric/keep-me)
+
+;;; ------------------------------------------------- Harness ------------------------------------------------------
+
+(defn- call-tool!
+ "Drive `tool` through the real dispatch seam as `user` (test-user keyword or user id) with
+ bearer-style `scopes` (nil = internal caller, which bypasses the scope gate). `session-id` is
+ fresh per call unless the caller threads one through, so query handles are scoped like a real
+ client's."
+ ([user scopes tool args] (call-tool! user scopes tool args (str (random-uuid))))
+ ([user scopes tool args session-id]
+ (mt/with-current-user (if (keyword? user) (mt/user->id user) user)
+ (registry/call-tool scopes session-id tool args))))
+
+(defn- tool-result
+ "Decoded success payload of a tool response; throws when the call errored, so a tool-level
+ error can never masquerade as a result."
+ [{:keys [result error]}]
+ (when error
+ (throw (ex-info (str "tool call rejected: " (:message error)) {:error error})))
+ (when (:isError result)
+ (throw (ex-info (str "tool call failed: " (-> result :content first :text))
+ {:result result})))
+ (-> result :content first :text json/decode+kw))
+
+(defn- tool-error
+ "Tool-level error text of a tool response; throws when the call succeeded, so a passing call
+ can never satisfy an error assertion."
+ [{:keys [result error]}]
+ (cond
+ error (:message error)
+ (:isError result) (-> result :content first :text)
+ :else (throw (ex-info "expected a tool error, got success" {:result result}))))
+
+(defn- wire
+ "Round-trip a value through JSON, producing exactly the keywordized shape tool arguments have
+ after transport decoding (keyword values like :mbql/query become strings)."
+ [x]
+ (-> x json/encode json/decode+kw))
+
+(def ^:private write-scope
+ "The single scope metric_write is gated on, create and update alike — matching segment_write and
+ measure_write rather than question_write's create/update split. resource:read rides along so
+ these tests get full responses back; without it the tool answers with the GHY-4217 minimal ack."
+ #{"agent:content:write" "agent:content:read"})
+
+;;; ------------------------------------------------ Definitions ---------------------------------------------------
+
+(defn- orders-fk
+ "The portable FK path the external dialect names the orders table (or one of its fields) by."
+ [& field-names]
+ (into [(t2/select-one-fn :name :model/Database :id (mt/id)) "PUBLIC" "ORDERS"] field-names))
+
+(defn- mbql5-definition
+ "A hand-shaped single-stage MBQL 5 definition on orders, defaulting to one count aggregation and
+ overlaying `stage-clauses` onto that stage — as an MCP client sends it: numeric source table,
+ an options map on every clause."
+ [& {:as stage-clauses}]
+ (wire {:lib/type "mbql/query"
+ :database (mt/id)
+ :stages [(merge {:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :orders)
+ :aggregation [["count" {}]]}
+ stage-clauses)]}))
+
+(defn- count-definition
+ "The canonical valid metric: one stage, exactly one aggregation, no breakout."
+ []
+ (mbql5-definition))
+
+(defn- orders-query
+ "A Lib query over ORDERS — a runnable `:dataset_query` for card fixtures that only need the card
+ to have one."
+ []
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id :orders)))))
+
+(defn- orders-count-query
+ "[[orders-query]] plus the single count aggregation that makes it a valid metric."
+ []
+ (lib/aggregate (orders-query) (lib/count)))
+
+(defn- lib-count-definition
+ "The same metric built through lib rather than by hand, so the tool is proven against a query
+ that carries every `:lib/type` and uuid a lib-produced query does."
+ []
+ (wire (orders-count-query)))
+
+(defn- portable-count-definition
+ "The same metric in the portable external dialect — FK path source, named field refs — which is
+ what `execute_query` takes and `get_content` returns."
+ []
+ (wire {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (orders-fk)
+ :aggregation [["count" {}]]}]}))
+
+(defn- temporal-breakout-definition
+ "One aggregation plus a single date breakout — the other shape a metric is allowed to have."
+ []
+ (mbql5-definition :breakout [["field" {:temporal-unit "month"} (mt/id :orders :created_at)]]))
+
+;;; ------------------------------------------- Argument validation ------------------------------------------------
+
+(deftest ^:parallel malli-validation-test
+ (testing "GHY-4146: schema-level failures are teaching errors from the registry, not handler crashes"
+ (testing "missing method"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "metric_write" {}))
+ "Invalid arguments")))
+ (testing "a method outside the enum (there is no delete — archive instead)"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "metric_write" {:method "delete"}))
+ "Invalid arguments")))
+ (testing "an unknown key on the closed schema"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "metric_write" {:method "create" :bogus 1}))
+ "Invalid arguments")))
+ (testing "a non-map definition never reaches the handler"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "metric_write"
+ {:method "create" :name "x" :definition "not a query"}))
+ "Invalid arguments")))
+ (testing "card_type is not an argument — a metric_write call always writes a metric"
+ (is (str/starts-with? (tool-error (call-tool! :crowberto nil "metric_write"
+ {:method "create" :name "x" :card_type "question"
+ :definition (count-definition)}))
+ "Invalid arguments")))))
+
+(deftest ^:parallel create-required-args-test
+ (testing "GHY-4146: `name` is enforced at create with a teaching error naming it"
+ (is (= "`name` is required when method is \"create\"."
+ (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :definition (count-definition)})))))
+ (testing "GHY-4146: create with no query source names both sources"
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test no source"}))]
+ (is (str/includes? msg "definition"))
+ (is (str/includes? msg "query_handle"))))
+ (testing "GHY-4146: create with both query sources is a teaching error, not a silent precedence rule"
+ (is (re-find #"exactly one"
+ (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test two sources"
+ :definition (count-definition)
+ :query_handle (str (random-uuid))}))))))
+
+(deftest ^:parallel update-required-args-test
+ (testing "GHY-4146: update without id is a teaching error"
+ (is (= "`id` is required when method is \"update\"."
+ (tool-error (call-tool! :crowberto write-scope "metric_write" {:method "update" :name "x"})))))
+ (testing "GHY-4146: an id that is neither numeric nor a 21-char entity_id teaches the two accepted shapes"
+ (is (= "Invalid id \"abc\" — pass the positive numeric id, or the 21-character entity_id from a search or list result."
+ (tool-error (call-tool! :crowberto write-scope "metric_write" {:method "update" :id "abc"})))))
+ (testing "GHY-4146: create-only fields on update are rejected, so a caller never believes an ignored field took effect"
+ (is (= "`archived` applies to method \"update\" only — remove it from this create call."
+ (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "x" :archived true
+ :definition (count-definition)}))))))
+
+;;; ---------------------------------------------- Create / update -------------------------------------------------
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest metric-write-lifecycle-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (let [created (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "create"
+ :name "metric-test lifecycle"
+ :description "how many orders"
+ :collection_id coll-id
+ :definition (count-definition)}))]
+ (testing "GHY-4146: create returns the metric's concise read shape plus a portable id and a link"
+ (is (=? {:id pos-int?
+ :entity_id string?
+ :name "metric-test lifecycle"
+ :description "how many orders"
+ :type "metric"
+ :collection_id coll-id
+ :archived false
+ :display "scalar"
+ :url string?}
+ created))
+ (is (str/includes? (:url created) (str "/metric/" (:id created)))
+ "the url points at the metric, not the generic question route"))
+ (testing "GHY-4146: the row really is a metric card, not a question"
+ (is (= :metric (t2/select-one-fn :type :model/Card :id (:id created)))))
+ (testing "GHY-4146: update resolves an entity_id and applies only the fields passed"
+ (let [updated (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id (:entity_id created)
+ :name "metric-test renamed"}))]
+ (is (= (:id created) (:id updated)))
+ (is (= "metric-test renamed" (:name updated)))
+ (is (= "how many orders" (:description updated))
+ "an untouched field is not wiped by a partial update")))
+ (testing "GHY-4146: the definition can be swapped for another valid metric shape"
+ (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id (:id created)
+ :definition (temporal-breakout-definition)}))
+ (is (= 1 (count (get-in (t2/select-one-fn :dataset_query :model/Card :id (:id created))
+ [:stages 0 :breakout])))))
+ (testing "round-2 review: swapping the definition refreshes result_metadata rather than
+ leaving it stale — `queries/update-card!` writes through Card's `before-update`
+ hook, which recomputes result_metadata whenever `dataset_query` changes"
+ (let [before-metadata (t2/select-one-fn :result_metadata :model/Card :id (:id created))
+ _ (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id (:id created)
+ :definition (mbql5-definition
+ :aggregation [["sum" {} (mt/id :orders :total)]]
+ :breakout [["field" {:temporal-unit "month"} (mt/id :orders :created_at)]])}))
+ after-metadata (t2/select-one-fn :result_metadata :model/Card :id (:id created))]
+ (is (not= before-metadata after-metadata))
+ (is (= 2 (count after-metadata))
+ "one breakout column plus one aggregation column")
+ (is (some #(= "sum" (:lib/original-name %)) after-metadata))))
+ (testing "GHY-4146: archived true trashes and archived false restores — the only removal path"
+ (is (true? (:archived (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id (:id created) :archived true})))))
+ (is (false? (:archived (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id (:id created) :archived false}))))))))))
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest create-collection-target-test
+ (mt/with-model-cleanup [:model/Card]
+ (let [create! (fn [args]
+ (tool-result (call-tool! :crowberto write-scope "metric_write"
+ (merge {:method "create" :definition (count-definition)} args))))]
+ (testing "GHY-4146: omitted collection_id saves to the caller's personal collection"
+ (let [personal-id (:id (collection/user->personal-collection (mt/user->id :crowberto)))]
+ (is (= personal-id
+ (t2/select-one-fn :collection_id :model/Card
+ :id (:id (create! {:name "metric-test personal"})))))))
+ (testing "GHY-4146: collection_id \"root\" saves to the root collection"
+ (is (nil? (t2/select-one-fn :collection_id :model/Card
+ :id (:id (create! {:name "metric-test root" :collection_id "root"}))))))
+ (testing "GHY-4146: collection_position pins the metric"
+ (is (= 1 (:collection_position
+ (t2/select-one [:model/Card :collection_position]
+ :id (:id (create! {:name "metric-test pinned"
+ :collection_id "root"
+ :collection_position 1}))))))))))
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest update-moves-collection-test
+ (testing "GHY-4146: collection_id on update moves the metric"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (let [created (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test move"
+ :collection_id "root"
+ :definition (count-definition)}))]
+ (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id (:id created) :collection_id coll-id}))
+ (is (= coll-id (t2/select-one-fn :collection_id :model/Card :id (:id created)))))))))
+(deftest non-temporal-breakout-is-a-valid-metric-test
+ (testing "a non-temporal grouping is a valid metric. It was rejected until #76623 (\"Add Metric
+ Dimensions\") relaxed lib/can-save? from \"at most one date-or-datetime breakout\" to
+ \"at most one breakout\" — pinned here so the tool tracks the upstream rule rather than
+ re-deriving a stricter one."
+ (mt/with-model-cleanup [:model/Card]
+ (let [result (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test quantity grouping"
+ :definition (mbql5-definition
+ :breakout [["field" {} (mt/id :orders :quantity)]])}))]
+ (is (pos-int? (:id result)))
+ (is (= "metric" (:type result)))))))
+
+;;; ------------------------------------------------- Display ------------------------------------------------------
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest create-display-test
+ (testing "GHY-4146: `display` on create is persisted, so a metric with a grouping is not stuck as a
+ single number. The tool accepts a breakout, so hard-coding scalar (as it did) rendered
+ `count by month` unfixably wrong through MCP; agent-api's create_metric took a display."
+ (mt/with-model-cleanup [:model/Card]
+ (let [created (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "create"
+ :name "metric-test display line"
+ :display "line"
+ :definition (temporal-breakout-definition)}))]
+ (is (= :line (t2/select-one-fn :display :model/Card :id (:id created))))
+ (is (= "line" (:display created))
+ "the write echo confirms the display that was written"))))
+ (testing "GHY-4146: an omitted `display` still defaults to scalar — pinned so the default can't drift"
+ (mt/with-model-cleanup [:model/Card]
+ (let [created (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "create"
+ :name "metric-test display default"
+ :definition (count-definition)}))]
+ (is (= :scalar (t2/select-one-fn :display :model/Card :id (:id created))))
+ (is (= "scalar" (:display created))
+ "the echo surfaces the defaulted display, which the caller never named")))))
+
+(deftest ^:parallel update-display-test
+ (testing "GHY-4146: `display` on update rewrites an existing metric's visualization"
+ (mt/with-temp [:model/Card {metric-id :id} {:type :metric
+ :display :scalar
+ :dataset_query (orders-count-query)}]
+ (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id metric-id :display "bar"}))
+ (is (= :bar (t2/select-one-fn :display :model/Card :id metric-id))))))
+
+(deftest ^:parallel display-rejects-unknown-value-test
+ (testing "GHY-4146: a display outside the accepted set is rejected at the schema layer, so an
+ LLM-invented value is a teaching error rather than junk persisted on the card"
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test bad display"
+ :display "potato"
+ :definition (count-definition)}))]
+ (is (str/starts-with? msg "Invalid arguments"))
+ (is (str/includes? msg "display"))
+ (is (not (str/includes? msg "disallowed key"))
+ "rejected because the value is outside the accepted set, not because `display` is unknown"))))
+
+;;; --------------------------------------------- Metric shape gate ------------------------------------------------
+
+(deftest ^:parallel metric-shape-teaching-test
+ (testing "GHY-4146: a query that isn't a valid metric is a teaching error naming the rule, never an internal error"
+ (doseq [[label definition]
+ {"no aggregation" (wire {:lib/type "mbql/query"
+ :database (mt/id)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :orders)}]})
+ "two aggregations" (mbql5-definition :aggregation [["count" {}] ["count" {}]])
+ "two breakouts" (mbql5-definition
+ :breakout [["field" {:temporal-unit "month"} (mt/id :orders :created_at)]
+ ["field" {:temporal-unit "year"} (mt/id :orders :created_at)]])
+ "more than one stage" (wire {:lib/type "mbql/query"
+ :database (mt/id)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :orders)
+ :aggregation [["count" {}]]}
+ {:lib/type "mbql.stage/mbql"}]})}]
+ (testing label
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name (str "metric-test " label)
+ :definition definition}))]
+ (is (re-find #"exactly one aggregation" msg))
+ (is (re-find #"at most one grouping" msg))
+ (is (not= "Internal error" msg)))))))
+
+;; not ^:parallel: creates a row through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest update-shape-gate-test
+ (testing "GHY-4146: the shape gate runs on update too, and a rejected update leaves the metric untouched"
+ (mt/with-model-cleanup [:model/Card]
+ (let [created (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test update gate"
+ :collection_id "root"
+ :definition (count-definition)}))
+ before (t2/select-one-fn :dataset_query :model/Card :id (:id created))
+ msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id (:id created)
+ :definition (mbql5-definition
+ :aggregation [["count" {}] ["count" {}]])}))]
+ (is (re-find #"exactly one aggregation" msg))
+ (is (= before (t2/select-one-fn :dataset_query :model/Card :id (:id created))))))))
+
+(deftest ^:parallel invalid-definition-teaching-test
+ (testing "GHY-4146: a definition that isn't a well-formed query is a teaching error, not an internal error"
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test garbage"
+ :definition {:not "a query"}}))]
+ (is (str/includes? msg "definition"))
+ (is (not= "Internal error" msg)))))
+
+(deftest ^:parallel empty-definition-teaching-test
+ (testing "GHY-4146: an empty `definition` map — what a strict client sends when it fills every declared
+ property — is a teaching error, not an internal error"
+ (testing "create"
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test empty definition"
+ :definition {}}))]
+ (is (str/includes? msg "definition"))
+ (is (not= "Internal error" msg))))
+ (testing "update"
+ (mt/with-temp [:model/Card {metric-id :id} {:type :metric :dataset_query (orders-count-query)}]
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id metric-id :definition {}}))]
+ (is (str/includes? msg "definition"))
+ (is (not= "Internal error" msg)))))))
+
+;;; ---------------------------------------------- Query sources ---------------------------------------------------
+
+;; not ^:parallel: creates rows through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest definition-dialects-test
+ (testing "GHY-4146: every dialect an agent can hold a metric query in is accepted"
+ (mt/with-model-cleanup [:model/Card]
+ (doseq [[label definition] {"hand-shaped MBQL 5" (count-definition)
+ "a lib-produced MBQL 5 query" (lib-count-definition)
+ "the portable external dialect execute_query takes"
+ (portable-count-definition)}]
+ (testing label
+ (let [created (tool-result (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name (str "metric-test " label)
+ :collection_id "root"
+ :definition definition}))]
+ (is (= :metric (t2/select-one-fn :type :model/Card :id (:id created))))
+ (is (= (mt/id :orders)
+ (get-in (t2/select-one-fn :dataset_query :model/Card :id (:id created))
+ [:stages 0 :source-table]))
+ "the stored query names its source by numeric id whichever dialect it arrived in")))))))
+
+;; DEFERRED to the query tool PR (needs tools/query): `mint-handle!` + `query-handle-source-test`
+;; — the GHY-4146 build-then-save flow (execute_query validate_only mints a handle, metric_write
+;; saves it). Restore both from mcp-v2-foundation when execute_query lands.
+
+(deftest ^:parallel unknown-query-handle-test
+ (testing "GHY-4146: an expired or unknown handle teaches the recovery, rather than failing opaquely"
+ (is (re-find #"run the query again"
+ (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test bad handle"
+ :query_handle (str (random-uuid))}))))))
+
+(deftest ^:parallel native-definition-rejected-test
+ (testing "GHY-4146: a native (SQL) query can't be a metric — the error names question_write as the way to save it"
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test native"
+ :definition (wire {:lib/type "mbql/query"
+ :database (mt/id)
+ :stages [{:lib/type "mbql.stage/native"
+ :native "SELECT count(*) FROM orders"}]})}))]
+ (is (str/includes? msg "question_write"))
+ (is (not= "Internal error" msg)))))
+
+(deftest ^:parallel nested-native-definition-rejected-test
+ (testing "a native stage anywhere in the definition (native + an appended MBQL stage) is refused
+ with the metric-specific message, not the generic can't-be-saved one — the whole-tree
+ native check, not just lib/native-only-query? (review round 1)"
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test nested native"
+ :definition (wire {:lib/type "mbql/query"
+ :database (mt/id)
+ :stages [{:lib/type "mbql.stage/native"
+ :native "SELECT * FROM orders"}
+ {:lib/type "mbql.stage/mbql"
+ :aggregation [["count" {}]]}]})}))]
+ (is (str/includes? msg "question_write"))
+ (is (not= "Internal error" msg)))))
+
+;;; --------------------------------------------- Round-tripping ---------------------------------------------------
+
+;; DEFERRED to the content tool PR (needs tools/content): `write-echo-omits-only-query-summary-test`,
+;; `read-definition!`, and `definition-round-trip-test` — the echo-vs-concise-read parity pin and the
+;; GHY-4146 get_content→metric_write definition round-trip. Restore from mcp-v2-foundation when
+;; get_content lands.
+
+;;; ---------------------------------------------- Card-type guard -------------------------------------------------
+
+(deftest ^:parallel update-rejects-non-metric-card-test
+ (testing "GHY-4146: metric_write refuses to retype a question or model — the error names the tool that owns it"
+ (doseq [card-type [:question :model]]
+ (mt/with-temp [:model/Card {card-id :id} {:type card-type
+ :name "metric-test not a metric"
+ :dataset_query (orders-query)}]
+ (testing (name card-type)
+ (let [msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id card-id :name "nope"}))]
+ (is (str/includes? msg "question_write"))
+ (is (str/includes? msg (name card-type)))
+ (is (= "metric-test not a metric" (t2/select-one-fn :name :model/Card :id card-id))
+ "the card is untouched")))))))
+
+;;; ----------------------------------------------- Permissions ----------------------------------------------------
+
+(deftest ^:parallel update-not-found-test
+ (testing "GHY-4146: an update against a nonexistent id is a not-found teaching error"
+ (is (re-find #"not found"
+ (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id 13371337 :name "x"}))))))
+
+;; not ^:parallel: revokes the all-users group's permissions on the temp collection
+(deftest existence-oracle-test
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {metric-id :id} {:type :metric
+ :collection_id coll-id
+ :dataset_query (orders-count-query)}]
+ (perms/revoke-collection-permissions! (perms/all-users-group) coll-id)
+ (let [norm (fn [msg] (str/replace msg #"\d+" "N"))]
+ (testing "GHY-4146: an unreadable id and a nonexistent id must be indistinguishable — no existence oracle"
+ (is (= (norm (tool-error (call-tool! :rasta write-scope "metric_write"
+ {:method "update" :id metric-id :name "x"})))
+ (norm (tool-error (call-tool! :rasta write-scope "metric_write"
+ {:method "update" :id 13371337 :name "x"})))))))))
+
+(deftest create-runs-the-permission-stack-test
+ (testing "GHY-4146: `check-allowed-to-create-card!` is what stops a caller saving a metric into a collection
+ they cannot curate, or over a query they cannot run. `create-card!` performs no check of its own,
+ so deleting that line would let both through — and every other create test here runs as an admin,
+ for whom the checks are vacuous."
+ (mt/with-model-cleanup [:model/Card]
+ (testing "a collection the caller cannot curate is refused, and nothing is written"
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (perms/revoke-collection-permissions! (perms/all-users-group) coll-id)
+ (is (some? (tool-error (call-tool! :rasta write-scope "metric_write"
+ {:method "create" :name "Perm probe"
+ :collection_id coll-id
+ :definition (count-definition)}))))
+ (is (zero? (t2/count :model/Card :name "Perm probe")))))
+ (testing "a query the caller has no data permission to run is refused"
+ (mt/with-no-data-perms-for-all-users!
+ (is (some? (tool-error (call-tool! :rasta write-scope "metric_write"
+ {:method "create" :name "Perm probe 2"
+ :definition (count-definition)}))))
+ (is (zero? (t2/count :model/Card :name "Perm probe 2"))))))))
+
+;;; ------------------------------------------------- Scopes -------------------------------------------------------
+
+(deftest ^:parallel scope-gating-test
+ (testing "GHY-4146: a bearer token without the write scope can't call the tool at all"
+ (is (re-find #"^Insufficient scope to call tool: metric_write\."
+ (tool-error (call-tool! :crowberto #{"agent:content:read"} "metric_write"
+ {:method "update" :id 13371337 :name "x"})))))
+ (testing "GHY-4146: the one write scope covers update as well as create — there is no second method-level gate"
+ (is (re-find #"not found"
+ (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "update" :id 13371337 :name "x"})))))
+ (testing "GHY-4146: v1's create/update scopes do not reach the v2 tool, which gates on agent:content:write"
+ (is (re-find #"^Insufficient scope to call tool: metric_write\."
+ (tool-error (call-tool! :crowberto #{"agent:metric:create" "agent:metric:update"} "metric_write"
+ {:method "update" :id 13371337 :name "x"})))))
+ ;; GHY-4225: the metabot permission wildcards no longer bear on v2. In-app callers reach
+ ;; v2 through cookie sessions bound to the unrestricted sentinel, and OAuth tokens draw
+ ;; their scopes from the tool registry (`registered-scopes`), not from
+ ;; `user-metabot-perms->scopes` — so the old wildcard coupling was already vestigial here.
+ )
+
+(deftest ^:parallel metric-write-scope-registered-test
+ (testing "GHY-4146: the scope the tool checks is grantable — advertised through registered-scopes"
+ (is (contains? (registry/registered-scopes) "agent:content:write"))))
+
+(deftest ^:parallel tools-list-visibility-test
+ (testing "GHY-4146: the tool is visible exactly to tokens carrying its write scope"
+ (is (some #(= "metric_write" (:name %)) (registry/list-tools write-scope)))
+ (is (not (some #(= "metric_write" (:name %)) (registry/list-tools #{"agent:content:read"}))))))
+
+;;; ------------------------------------------------ Round-2 review ------------------------------------------------
+
+(deftest ^:parallel destructive-hint-test
+ (testing "round-2 review: archived true trashes the metric, so destructiveHint must be true —
+ matching collection_write, whose archived:true has the same effect"
+ (is (true? (:destructiveHint
+ (:annotations (first (filter #(= "metric_write" (:name %))
+ (registry/list-tools write-scope)))))))))
+
+;; not ^:parallel: creates a row through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest text-only-response-test
+ (testing "round-2 review: metric_write has no outputSchema and no concrete structuredContent
+ consumer, so it follows the stack's text-only convention like collection_write"
+ (is (nil? (:outputSchema (first (filter #(= "metric_write" (:name %))
+ (registry/list-tools write-scope))))))
+ (mt/with-model-cleanup [:model/Card]
+ (let [response (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test text-only"
+ :collection_id "root"
+ :definition (count-definition)})]
+ (is (nil? (:structuredContent response)))))))
+
+;; not ^:parallel: creates a row through the tool; with-model-cleanup's id watermark is not parallel-safe
+(deftest create-with-id-rejected-test
+ (testing "round-2 review: `id` on a create call is rejected rather than silently ignored, so a
+ caller can't mistake a successful create for an edit of the id it passed"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Card {existing-id :id} {:type :metric :dataset_query (orders-count-query)}]
+ (let [before-name (t2/select-one-fn :name :model/Card :id existing-id)
+ msg (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test id on create"
+ :id existing-id
+ :definition (count-definition)}))]
+ (is (= "`id` applies to method \"update\" only — remove it from this create call." msg))
+ (is (= before-name (t2/select-one-fn :name :model/Card :id existing-id))
+ "the existing card named by id must be untouched"))))))
+
+(deftest ^:parallel collection-position-rejects-non-positive-test
+ (testing "round-2 review: collection_position must be positive — downstream reconciliation and
+ REST both declare PositiveInt, so 0 and negatives are teaching errors here rather than
+ an internal error or silently-wrong arithmetic"
+ (doseq [bad-position [0 -1]]
+ (is (str/starts-with? (tool-error (call-tool! :crowberto write-scope "metric_write"
+ {:method "create" :name "metric-test bad position"
+ :definition (count-definition)
+ :collection_position bad-position}))
+ "Invalid arguments")))))
+
+(deftest ^:parallel internal-caller-bypasses-scopes-test
+ (testing "GHY-4146: a cookie-session caller (the unrestricted sentinel) is not scope-gated"
+ (is (re-find #"not found"
+ (tool-error (call-tool! :crowberto #{::scope/unrestricted} "metric_write"
+ {:method "update" :id 13371337 :name "x"}))))))
diff --git a/test/metabase/mcp/v2/tools/parameters_test.clj b/test/metabase/mcp/v2/tools/parameters_test.clj
new file mode 100644
index 00000000000..798990001b8
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/parameters_test.clj
@@ -0,0 +1,925 @@
+(ns metabase.mcp.v2.tools.parameters-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.tools.parameters :as parameters]
+ [metabase.parameters.chain-filter :as chain-filter]
+ [metabase.parameters.custom-values :as custom-values]
+ [metabase.parameters.dashboard :as parameters.dashboard]
+ [metabase.parameters.field.search-values-query :as search-values-query]
+ [metabase.permissions.core :as perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.permissions.test-util :as perms.test-util]
+ [metabase.query-processor :as qp]
+ [metabase.query-processor.parameters.dates :as params.dates]
+ [metabase.test :as mt]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(defn- call-params
+ "Invoke get_parameter_values through the registry — the same seam the JSON-RPC route uses, so
+ scope gating and argument validation are exercised. `token-scopes` of nil means an internal
+ caller, which satisfies every scope check."
+ ([args] (call-params nil args))
+ ([token-scopes args]
+ (registry/call-tool token-scopes "test-session" "get_parameter_values" args)))
+
+(defn- success-text
+ "The text block of a successful response. Throws when the registry rejected the call before
+ dispatch, so a rejection can never masquerade as a result."
+ [{:keys [result error]}]
+ (when error
+ (throw (ex-info (str "get_parameter_values was rejected before dispatch: " (:message error))
+ {:error error})))
+ (when (:isError result)
+ (throw (ex-info (str "get_parameter_values returned a tool-level error: "
+ (-> result :content first :text))
+ {:result result})))
+ (-> result :content first :text))
+
+(defn- params-text
+ ([args] (params-text nil args))
+ ([token-scopes args] (success-text (call-params token-scopes args))))
+
+(defn- params-result
+ "The decoded JSON payload of a successful call — the first line of the text block, since a
+ steering line may follow it."
+ ([args] (params-result nil args))
+ ([token-scopes args]
+ (-> (params-text token-scopes args) str/split-lines first json/decode+kw)))
+
+(defn- params-error
+ "The error text of a rejected call, registry-level (scope, argument validation) and tool-level
+ (teaching error) alike. Throws when the call succeeded, so a passing call can never satisfy an
+ error assertion."
+ ([args] (params-error nil args))
+ ([token-scopes args]
+ (let [{:keys [result error]} (call-params token-scopes args)]
+ (cond
+ error (:message error)
+ (:isError result) (-> result :content first :text)
+ :else (throw (ex-info "expected a tool error, got success" {:result result}))))))
+
+(defn- steering-line
+ "The sentence appended after the JSON payload, or nil when the response is the whole story."
+ [args]
+ (second (str/split-lines (params-text args))))
+
+;;; --------------------------------------------------- Fixtures ---------------------------------------------------
+
+(defn- table-query
+ "A Lib query over `table-id` — a runnable `:dataset_query` for fixtures that only need the card
+ to have one."
+ [table-id]
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp table-id))))
+
+(defn- do-with-fixtures
+ [f]
+ (mt/with-temp
+ [:model/Card {source-card-id :id} {:database_id (mt/id)
+ :table_id (mt/id :categories)
+ :dataset_query (table-query (mt/id :categories))}
+ :model/Dashboard {dash-id :id :as dashboard}
+ {:name "Venues"
+ :parameters [{:name "Category Name" :slug "category_name" :id "_CATEGORY_NAME_" :type "category"}
+ {:name "Price" :slug "price" :id "_PRICE_" :type "category"}
+ {:name "Static Category"
+ :slug "static_category"
+ :id "_STATIC_"
+ :type "category"
+ :values_source_type "static-list"
+ :values_source_config {:values ["African" "American" "Asian"]}}
+ {:name "Static Category label"
+ :slug "static_category_label"
+ :id "_STATIC_LABEL_"
+ :type "category"
+ :values_source_type "static-list"
+ :values_source_config {:values [["African" "Af"] ["American" "Am"] ["Asian" "As"]]}}
+ {:name "Card Category"
+ :slug "card_category"
+ :id "_CARD_"
+ :type "category"
+ :values_source_type "card"
+ :values_source_config {:card_id source-card-id :value_field (mt/$ids $categories.name)}}
+ ;; Wired to no dashcard at all, so nothing can supply it values.
+ {:name "Unmapped" :slug "unmapped" :id "_UNMAPPED_" :type "category"}]}
+ :model/Card {card-id :id} {:database_id (mt/id)
+ :table_id (mt/id :venues)
+ :dataset_query (table-query (mt/id :venues))}
+ :model/DashboardCard _ {:card_id card-id
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_CATEGORY_NAME_"
+ :card_id card-id
+ :target [:dimension (mt/$ids venues $category_id->categories.name)]}
+ {:parameter_id "_PRICE_"
+ :card_id card-id
+ :target [:dimension (mt/$ids venues $price)]}
+ {:parameter_id "_STATIC_"
+ :card_id card-id
+ :target [:dimension (mt/$ids venues $category_id->categories.name)]}
+ {:parameter_id "_STATIC_LABEL_"
+ :card_id card-id
+ :target [:dimension (mt/$ids venues $category_id->categories.name)]}
+ {:parameter_id "_CARD_"
+ :card_id card-id
+ :target [:dimension (mt/$ids venues $category_id->categories.name)]}]}
+ ;; A native question whose {{name}} field filter is its only parameter — the target: "question"
+ ;; path resolves it through the card's template tags.
+ :model/Card native-card {:name "Categories by name"
+ :database_id (mt/id)
+ :query_type :native
+ :dataset_query {:database (mt/id)
+ :type :native
+ :native {:query "SELECT COUNT(*) FROM categories WHERE {{name}}"
+ :template-tags {"name" {:name "name"
+ :display-name "Name"
+ :id "_CARD_NAME_"
+ :type :dimension
+ :dimension [:field (mt/id :categories :name) nil]
+ :widget-type :string/=}}}}}]
+ (f {:dashboard dashboard
+ :native-card native-card})))
+
+(defmacro ^:private with-fixtures [[binding] & body]
+ `(mt/with-full-data-perms-for-all-users!
+ (do-with-fixtures (fn [~binding] ~@body))))
+
+;;; ---------------------------------------------------- Tests -----------------------------------------------------
+
+(deftest dashboard-values-test
+ (testing "GHY-4141: a field-backed dashboard parameter returns its column's values"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [{:keys [values returned has_more_values]}
+ (params-result {:target "dashboard" :id (:id dashboard) :parameter_id "_CATEGORY_NAME_"
+ :limit 3})]
+ (is (= [["African"] ["American"] ["Artisan"]] values))
+ (is (= 3 returned))
+ (is (true? has_more_values)))))))
+
+(deftest constraints-value-must-not-name-a-column-test
+ (testing "a constraints value shaped like a field reference is refused, not compiled into one"
+ ;; Reported by galdre on #81245; this is his repro. The caller below can READ the dashboard and may
+ ;; see the data, but holds `:perms/create-queries :no` — it can author no query at all, asserted
+ ;; before the attack. `*param-values-query*` deliberately relaxes that gate so filter values still
+ ;; load, which is exactly what made a smuggled clause dangerous: `[["field" <id> nil]]` was compiled
+ ;; as a field reference rather than bound as a literal, so the server evaluated
+ ;; `WHERE VENUES.PRICE = VENUES.CATEGORY_ID` and handed back the matching rows — data this caller
+ ;; cannot query, from a column it never named.
+ (mt/with-temp
+ [:model/Collection collection {}
+ :model/Dashboard {dash-id :id}
+ {:collection_id (:id collection)
+ :parameters [{:name "Venue Name" :slug "venue_name" :id "_NAME_" :type "category"}
+ {:name "Price" :slug "price" :id "_PRICE_" :type "category"}]}
+ :model/Card {card-id :id} {:collection_id (:id collection)
+ :database_id (mt/id)
+ :table_id (mt/id :venues)
+ :dataset_query (table-query (mt/id :venues))}
+ :model/DashboardCard _ {:card_id card-id
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_NAME_"
+ :card_id card-id
+ :target [:dimension (mt/$ids venues $name)]}
+ {:parameter_id "_PRICE_"
+ :card_id card-id
+ :target [:dimension (mt/$ids venues $price)]}]}]
+ (perms.test-util/with-restored-data-perms!
+ (perms/grant-collection-read-permissions! (perms-group/all-users) collection)
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/view-data :unrestricted)
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/create-queries :no)
+ (mt/with-test-user :rasta
+ (let [category-id (mt/id :venues :category_id)
+ base {:target "dashboard" :id dash-id :parameter_id "_NAME_" :limit 1000}]
+ (testing "precondition: the caller cannot run a query of its own against VENUES"
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"You do not have permissions to run this query"
+ (qp/process-query (table-query (mt/id :venues))))))
+ (let [unconstrained (:values (params-result base))]
+ (testing "anti-vacuity control: the call reaches the warehouse and a literal narrows it"
+ (is (= 100 (count unconstrained)))
+ (let [literal (:values (params-result (assoc base :constraints {:_PRICE_ 2})))]
+ (is (seq literal))
+ (is (< (count literal) (count unconstrained)))))
+ (testing "an id-shaped field reference is refused"
+ (is (string? (params-error (assoc base :constraints
+ {:_PRICE_ [["field" category-id nil]]})))))
+ (testing "a name-shaped field reference is refused, so no field id is needed to exploit it"
+ (is (string? (params-error (assoc base :constraints
+ {:_PRICE_ [["field" {"base-type" "type/Integer"} "CATEGORY_ID"]]})))))
+ (testing "a reference to a column hidden as sensitive is refused"
+ (mt/with-temp-vals-in-db :model/Field category-id {:visibility_type :sensitive}
+ (is (string? (params-error (assoc base :constraints
+ {:_PRICE_ [["field" category-id nil]]}))))))
+ (testing "an arithmetic expression over a column is refused"
+ (is (string? (params-error (assoc base :constraints
+ {:_PRICE_ [["+" ["field" category-id nil] 1]]})))))
+ (testing "a :value clause is refused"
+ (is (string? (params-error (assoc base :constraints
+ {:_PRICE_ [["value" 2 {"base-type" "type/Integer"}]]})))))
+ (testing "a literal constraint still works, so the refusal is shape-based rather than blanket"
+ (is (seq (:values (params-result (assoc base :constraints {:_PRICE_ 2})))))))))))))
+
+(deftest dashboard-values-entity-id-test
+ (testing "GHY-4141: id accepts a 21-char entity_id as well as a numeric id"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (is (= (params-result {:target "dashboard" :id (:id dashboard) :parameter_id "_STATIC_"})
+ (params-result {:target "dashboard" :id (:entity_id dashboard) :parameter_id "_STATIC_"})))))))
+
+(deftest limit-and-offset-test
+ (testing "GHY-4141: limit/offset page the value list, and a truncated page says so"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [args {:target "dashboard" :id (:id dashboard) :parameter_id "_CATEGORY_NAME_" :limit 2}]
+ (testing "the first page names both ways out: narrowing and the next offset"
+ (is (= [["African"] ["American"]] (:values (params-result args))))
+ (is (re-find #"narrow with `query`, or continue with `offset: 2`" (steering-line args))))
+ (testing "offset continues where the page left off"
+ (is (= [["Artisan"] ["Asian"]]
+ (:values (params-result (assoc args :offset 2)))))))))))
+
+(deftest last-page-test
+ (testing "GHY-4141: a page that reaches the end of the list carries no steering line"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [args {:target "dashboard" :id (:id dashboard) :parameter_id "_STATIC_"}]
+ (is (= {:values [["African"] ["American"] ["Asian"]]
+ :returned 3
+ :has_more_values false}
+ (params-result args)))
+ (is (nil? (steering-line args))))))))
+
+(deftest offset-past-end-test
+ (testing "GHY-4141: an offset past the end returns nothing and says how many values there are"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [args {:target "dashboard" :id (:id dashboard) :parameter_id "_STATIC_" :offset 10}]
+ (is (= {:values [] :returned 0 :has_more_values false} (params-result args)))
+ (is (re-find #"No values at offset 10 — 3 available" (steering-line args))))))))
+
+(deftest static-list-test
+ (testing "GHY-4141: static-list parameters return their configured values, with labels when configured"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (is (= [["African"] ["American"] ["Asian"]]
+ (:values (params-result {:target "dashboard" :id (:id dashboard) :parameter_id "_STATIC_"}))))
+ (is (= [["African" "Af"] ["American" "Am"] ["Asian" "As"]]
+ (:values (params-result {:target "dashboard" :id (:id dashboard) :parameter_id "_STATIC_LABEL_"}))))))))
+
+(deftest card-source-test
+ (testing "GHY-4141: a card-sourced parameter runs its source card"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (is (= [["African"] ["American"] ["Artisan"]]
+ (:values (params-result {:target "dashboard" :id (:id dashboard) :parameter_id "_CARD_"
+ :limit 3}))))))))
+
+(deftest source-capped-test
+ (testing "GHY-4141: when the source itself caps the value list, the response says so even on a full page"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (binding [custom-values/*max-rows* 3]
+ (let [args {:target "dashboard" :id (:id dashboard) :parameter_id "_CARD_"}]
+ (is (true? (:has_more_values (params-result args))))
+ (is (re-find #"holds more values than it will return; narrow with `query`" (steering-line args))))
+ (testing "and a page shorter than the capped list still reads as a floor"
+ (is (re-find #"Returned 2 of at least 3"
+ (steering-line {:target "dashboard" :id (:id dashboard)
+ :parameter_id "_CARD_" :limit 2})))))))))
+
+(deftest offset-past-end-of-capped-list-test
+ (testing "GHY-4141: past the end of a source-capped list the steering line stays a floor — naming a
+ flat total would contradict the has_more_values the payload still carries, and would read
+ as an exhausted list when the source holds more"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (binding [custom-values/*max-rows* 3]
+ (let [args {:target "dashboard" :id (:id dashboard) :parameter_id "_CARD_" :offset 10}]
+ (is (true? (:has_more_values (params-result args))))
+ (is (re-find #"narrow with `query`" (steering-line args)))
+ (is (not (re-find #"3 available" (steering-line args))))))))))
+
+(deftest query-search-test
+ (testing "GHY-4141: query narrows the value list on both targets"
+ (with-fixtures [{:keys [dashboard native-card]}]
+ (mt/with-test-user :rasta
+ (is (= [["Steakhouse"]]
+ (:values (params-result {:target "dashboard" :id (:id dashboard)
+ :parameter_id "_CATEGORY_NAME_" :query "Steak"}))))
+ (is (= [["Steakhouse"]]
+ (:values (params-result {:target "question" :id (:id native-card)
+ :parameter_id "_CARD_NAME_" :query "Steak"}))))
+ (testing "a search that returned everything it found does not claim more exist — the strict
+ question path counts its own rows, so reporting a floor of `true` for every query
+ would tell the agent to keep narrowing a list it already has in full"
+ (let [args {:target "question" :id (:id native-card)
+ :parameter_id "_CARD_NAME_" :query "Steak"}]
+ (is (false? (:has_more_values (params-result args))))
+ (is (nil? (steering-line args)))))))))
+
+(deftest blank-query-test
+ (testing "GHY-4141: a whitespace-only query is a teaching error on both targets — the backends
+ reject it as a non-blank string, and uninstrumented it would match nothing at all"
+ (with-fixtures [{:keys [dashboard native-card]}]
+ (mt/with-test-user :rasta
+ (is (re-find #"`query` .* blank"
+ (params-error {:target "dashboard" :id (:id dashboard)
+ :parameter_id "_CATEGORY_NAME_" :query " "})))
+ (is (re-find #"`query` .* blank"
+ (params-error {:target "question" :id (:id native-card)
+ :parameter_id "_CARD_NAME_" :query " "})))))))
+
+(deftest question-values-test
+ (testing "GHY-4141: target \"question\" resolves a card's parameters, including native template tags"
+ (with-fixtures [{:keys [native-card]}]
+ (mt/with-test-user :rasta
+ (let [{:keys [values has_more_values]}
+ (params-result {:target "question" :id (:id native-card) :parameter_id "_CARD_NAME_" :limit 3})]
+ (is (= [["African"] ["American"] ["Artisan"]] values))
+ (is (true? has_more_values)))))))
+
+(deftest valueless-question-parameter-test
+ (testing "GHY-4141: a question parameter with neither a values source nor a field behind it returns an
+ empty list rather than an error — `card-param-values` answers nil here, which its own output
+ schema rejects under dev/test instrumentation"
+ (mt/with-temp [:model/Card {card-id :id}
+ {:name "Free text"
+ :database_id (mt/id)
+ :query_type :native
+ :dataset_query {:database (mt/id)
+ :type :native
+ :native {:query "SELECT 1 WHERE 1 = {{x}}"
+ :template-tags {"x" {:name "x"
+ :display-name "X"
+ :id "_X_"
+ :type :text}}}}}]
+ (mt/with-test-user :rasta
+ (let [args {:target "question" :id card-id :parameter_id "_X_"}]
+ (is (= {:values [] :returned 0 :has_more_values false} (params-result args)))
+ (is (re-find #"No values" (steering-line args))))))))
+
+(deftest constraints-test
+ (testing "GHY-4141: constraints chain-filter this parameter against another filter's selection"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (is (= [["Japanese"] ["Steakhouse"]]
+ (:values (params-result {:target "dashboard"
+ :id (:id dashboard)
+ :parameter_id "_CATEGORY_NAME_"
+ :constraints {:_PRICE_ 4}}))))))))
+
+(deftest constraints-rejected-for-questions-test
+ (testing "GHY-4141: constraints with target \"question\" is a teaching error naming the right target"
+ (with-fixtures [{:keys [native-card]}]
+ (mt/with-test-user :rasta
+ (let [error (params-error {:target "question" :id (:id native-card)
+ :parameter_id "_CARD_NAME_" :constraints {:_PRICE_ 4}})]
+ (is (re-find #"constraints" error))
+ (is (re-find #"target: \"dashboard\"" error)))))))
+
+(deftest unknown-constraint-key-test
+ (testing "GHY-4141: a constraints key that isn't a dashboard parameter is rejected, not silently dropped"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [error (params-error {:target "dashboard"
+ :id (:id dashboard)
+ :parameter_id "_CATEGORY_NAME_"
+ :constraints {:_NOPE_ 4}})]
+ (is (re-find #"no parameter \"_NOPE_\"" error))
+ (is (re-find #"_PRICE_ \(Price\)" error)))))))
+
+(deftest unresolvable-constraint-key-test
+ (testing "GHY-4141: a constraints key that exists but resolves to no queryable field is rejected —
+ chain filtering silently drops such a key (unmapped, or mapped only via field-refs or a
+ SQL text variable), handing back unnarrowed values the agent believes were filtered"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [error (params-error {:target "dashboard"
+ :id (:id dashboard)
+ :parameter_id "_CATEGORY_NAME_"
+ :constraints {:_UNMAPPED_ "anything"}})]
+ (is (re-find #"_UNMAPPED_" error))
+ (is (re-find #"queryable field" error)))))))
+
+(deftest constraints-rejected-for-valued-target-test
+ (testing "GHY-4141: constraints against a target whose values come from a static list (or card) are
+ rejected — that value source never consults the chain-filter constraints, so applying them
+ would be a silent no-op"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [error (params-error {:target "dashboard"
+ :id (:id dashboard)
+ :parameter_id "_STATIC_"
+ :constraints {:_PRICE_ 4}})]
+ (is (re-find #"fixed list or a card" error)))))))
+
+(deftest unknown-parameter-id-test
+ (testing "GHY-4141: an unknown parameter_id names the parameters that do exist"
+ (with-fixtures [{:keys [dashboard native-card]}]
+ (mt/with-test-user :rasta
+ (let [error (params-error {:target "dashboard" :id (:id dashboard) :parameter_id "_NOPE_"})]
+ (is (re-find #"dashboard has no parameter \"_NOPE_\"" error))
+ (is (re-find #"_CATEGORY_NAME_ \(Category Name\)" error)))
+ (let [error (params-error {:target "question" :id (:id native-card) :parameter_id "_NOPE_"})]
+ (is (re-find #"question has no parameter \"_NOPE_\"" error))
+ (is (re-find #"_CARD_NAME_" error)))))))
+
+(deftest unmapped-parameter-test
+ (testing "GHY-4141: a dashboard filter wired to no card returns an empty value list — the same answer
+ target \"question\" gives for a parameter with nothing behind it, rather than an error"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [args {:target "dashboard" :id (:id dashboard) :parameter_id "_UNMAPPED_"}]
+ (is (= {:values [] :returned 0 :has_more_values false} (params-result args)))
+ (is (re-find #"No values" (steering-line args))))))))
+
+(defn- tool-manifest-entry
+ []
+ (some #(when (= "get_parameter_values" (:name %)) %) (registry/list-tools nil)))
+
+(defn- tool-description
+ []
+ (:description (tool-manifest-entry)))
+
+(defn- arg-description
+ "The description a client sees for one argument, dug out of the published inputSchema rather than
+ the Malli source — that string is what reaches the model."
+ [arg]
+ (->> (get-in (tool-manifest-entry) [:inputSchema :properties arg :oneOf])
+ (some :description)))
+
+(deftest offset-description-test
+ (testing "GHY-4141: the offset description names the source cap and points at query — an agent paging
+ a long list can't reach past the cap, and nothing else in the schema says so"
+ (is (re-find #"1000" (arg-description :offset)))
+ (is (re-find #"`query`" (arg-description :offset)))))
+
+(deftest date-parameter-range-test
+ (testing "GHY-4519: a column-backed date parameter answers with the span its column covers and the
+ grammar to write a value in, rather than paging out the column's distinct dates"
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Date" :slug "date" :id "_DATE_" :type "date/all-options"}]}
+ :model/Card {card-id :id} {:database_id (mt/id)
+ :table_id (mt/id :checkins)
+ :dataset_query (table-query (mt/id :checkins))}
+ :model/DashboardCard _ {:card_id card-id
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_DATE_"
+ :card_id card-id
+ :target [:dimension (mt/$ids checkins $date)]}]}]
+ (mt/with-test-user :rasta
+ (let [{:keys [kind distinct_dates accepts values] lo :min hi :max}
+ (params-result {:target "dashboard" :id dash-id :parameter_id "_DATE_"})]
+ (testing "the range replaces the value list outright"
+ (is (= "date" kind))
+ (is (nil? values)))
+ (testing "min and max are the column's real dates, written in the same YYYY-MM-DD the
+ accepts grammar asks for — a value carrying a time part would contradict it"
+ (is (re-matches #"\d{4}-\d{2}-\d{2}" lo))
+ (is (re-matches #"\d{4}-\d{2}-\d{2}" hi))
+ (is (neg? (compare lo hi))))
+ (testing "the count covers the whole column rather than one page of it"
+ (is (= 618 distinct_dates)))
+ (testing "accepts is the grammar to build a value from — templates, not sample dates,
+ which are what min and max are for"
+ (is (= ["YYYY-MM-DD" "YYYY-MM-DD~YYYY-MM-DD" "past30days" "thisyear"] accepts)))))))))
+
+(deftest date-parameter-with-static-list-keeps-its-list-test
+ (testing "GHY-4519: a date parameter whose values come from a static list keeps that list — those
+ dates are a curated set to pick from, not a span to write a value inside"
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Date"
+ :slug "date"
+ :id "_DATE_"
+ :type "date/single"
+ :values_source_type "static-list"
+ :values_source_config {:values ["2024-01-01" "2024-06-01"]}}]}]
+ (mt/with-test-user :rasta
+ (let [{:keys [kind values]} (params-result {:target "dashboard" :id dash-id
+ :parameter_id "_DATE_"})]
+ (is (nil? kind))
+ (is (= [["2024-01-01"] ["2024-06-01"]] values))))))))
+
+(deftest date-range-past-the-list-cap-test
+ (testing "GHY-4519: max is the column's real last date even when the column holds far more distinct
+ values than a value list would return. This is why the range is aggregated rather than
+ folded out of the fetched values: listing stops at `parameters.dashboard/result-limit` and
+ values arrive ascending, so the list's last value is the 1000th-earliest. orders.created_at
+ holds ~18.7k distinct values, and its 1000th lands in Feb 2019 — more than a year short of
+ the column's true max, which a caller would have filtered against"
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Created" :slug "created" :id "_CREATED_" :type "date/all-options"}]}
+ :model/Card {card-id :id} {:database_id (mt/id)
+ :table_id (mt/id :orders)
+ :dataset_query (table-query (mt/id :orders))}
+ :model/DashboardCard _ {:card_id card-id
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_CREATED_"
+ :card_id card-id
+ :target [:dimension (mt/$ids orders $created_at)]}]}]
+ (mt/with-test-user :rasta
+ (let [{:keys [distinct_dates] hi :max} (params-result {:target "dashboard" :id dash-id
+ :parameter_id "_CREATED_"})
+ capped (:values (chain-filter/chain-filter (mt/id :orders :created_at) nil
+ :limit parameters.dashboard/result-limit))]
+ (testing "the count is the whole column, well past what a list would return"
+ (is (< parameters.dashboard/result-limit distinct_dates)))
+ (testing "and max is the column's last date, not where the capped list stopped"
+ (is (= "2020-04-19" hi))
+ (is (not= hi (#'parameters/->day (ffirst (take-last 1 capped))))))))))))
+
+(deftest date-range-honors-constraints-test
+ (testing "GHY-4519: the range narrows under chain-filter constraints, so a caller that asked for the
+ dates available alongside another filter's selection isn't handed the whole column's span —
+ the reason the range is built from chain filtering's own query rather than a plain
+ aggregation over the column"
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Date" :slug "date" :id "_DATE_" :type "date/all-options"}
+ {:name "Price" :slug "price" :id "_PRICE_" :type "category"}]}
+ :model/Card {card-id :id} {:database_id (mt/id)
+ :table_id (mt/id :checkins)
+ :dataset_query (table-query (mt/id :checkins))}
+ :model/DashboardCard _ {:card_id card-id
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_DATE_"
+ :card_id card-id
+ :target [:dimension (mt/$ids checkins $date)]}
+ {:parameter_id "_PRICE_"
+ :card_id card-id
+ :target [:dimension (mt/$ids checkins $venue_id->venues.price)]}]}]
+ (mt/with-test-user :rasta
+ (let [whole (params-result {:target "dashboard" :id dash-id :parameter_id "_DATE_"})
+ narrowed (params-result {:target "dashboard" :id dash-id :parameter_id "_DATE_"
+ :constraints {:_PRICE_ 4}})]
+ (is (< (:distinct_dates narrowed) (:distinct_dates whole)))
+ (is (neg? (compare (:min whole) (:min narrowed))))))))))
+
+(deftest date-range-rejects-query-test
+ (testing "GHY-4519: `query` searches a list of values by text, and a range is two dates and a
+ grammar — applying it silently would hand back the column's whole span as though it had
+ been narrowed, so it is a teaching error naming what to do instead"
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Date" :slug "date" :id "_DATE_" :type "date/all-options"}]}
+ :model/Card {card-id :id} {:database_id (mt/id)
+ :table_id (mt/id :checkins)
+ :dataset_query (table-query (mt/id :checkins))}
+ :model/DashboardCard _ {:card_id card-id
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_DATE_"
+ :card_id card-id
+ :target [:dimension (mt/$ids checkins $date)]}]}]
+ (mt/with-test-user :rasta
+ (let [msg (params-error {:target "dashboard" :id dash-id :parameter_id "_DATE_"
+ :query "2013"})]
+ (is (re-find #"no list for `query` to search" msg))
+ (is (re-find #"`accepts`" msg))))))))
+
+(deftest every-advertised-date-form-parses-test
+ (testing "GHY-4519: every form in `accepts` actually parses as a date filter. This is the one claim
+ in the response the caller acts on directly, and nothing else ties it to the decoders —
+ advertising a form the QP no longer understands would send every date filter into a
+ teaching error"
+ (mt/with-test-user :rasta
+ (doseq [template @#'parameters/date-accepts
+ :let [value (str/replace template "YYYY-MM-DD" "2024-05-15")]]
+ (testing (pr-str value)
+ (is (some? (params.dates/date-string->filter value (mt/id :checkins :date)))))))))
+
+(deftest date-parameter-description-test
+ (testing "GHY-4141: the description must not promise that date parameters return none"
+ (is (not (re-find #"Date and free-text parameters have no value list" (tool-description)))))
+ (testing "GHY-4519: nor that they hand back the column's distinct dates"
+ (is (not (re-find #"returns the column's distinct dates" (tool-description))))))
+
+(deftest permissions-test
+ (testing "GHY-4141: a caller who can't read the dashboard or card gets the collapsed not-found"
+ (mt/with-temp [:model/Collection collection {}
+ :model/Dashboard {dash-id :id} {:collection_id (:id collection)
+ :parameters [{:name "S"
+ :slug "s"
+ :id "_S_"
+ :type "category"
+ :values_source_type "static-list"
+ :values_source_config {:values ["a"]}}]}
+ :model/Card {card-id :id} {:collection_id (:id collection)
+ :dataset_query (table-query (mt/id :venues))}]
+ (mt/with-non-admin-groups-no-collection-perms collection
+ (mt/with-test-user :rasta
+ (is (re-find #"Dashboard .* not found"
+ (params-error {:target "dashboard" :id dash-id :parameter_id "_S_"})))
+ (is (re-find #"Card .* not found"
+ (params-error {:target "question" :id card-id :parameter_id "_S_"}))))))))
+
+(deftest constraint-not-join-reachable-test
+ (testing "GHY-4141: a constraint whose field has no FK join path to the target is rejected, not
+ silently dropped — chain filtering would ignore it and return unnarrowed values the
+ caller believes were filtered"
+ (mt/with-full-data-perms-for-all-users!
+ ;; The target (categories.name in test-data) and the constraint (places.name in the separate
+ ;; places-cam-likes database) share no FK graph — `add-filters` can't join across databases and
+ ;; silently drops the constraint. `filterable-field-ids` returns empty for this pair (verified),
+ ;; so the reachability check must reject it. Loading places-cam-likes first registers that DB.
+ (mt/dataset places-cam-likes
+ (let [places-name-id (mt/id :places :name)]
+ (mt/with-temp
+ [:model/Card {places-card :id} {:database_id (mt/id)
+ :table_id (mt/id :places)
+ :dataset_query (table-query (mt/id :places))}]
+ (mt/dataset test-data
+ (mt/with-temp
+ [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Category Name" :slug "category_name" :id "_CATEGORY_NAME_" :type "category"}
+ {:name "Place" :slug "place" :id "_PLACE_" :type "category"}]}
+ :model/Card {venues-card :id} {:database_id (mt/id)
+ :table_id (mt/id :venues)
+ :dataset_query (table-query (mt/id :venues))}
+ :model/DashboardCard _ {:card_id venues-card
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_CATEGORY_NAME_"
+ :card_id venues-card
+ :target [:dimension (mt/$ids venues $category_id->categories.name)]}]}
+ :model/DashboardCard _ {:card_id places-card
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_PLACE_"
+ :card_id places-card
+ :target [:dimension [:field places-name-id nil]]}]}]
+ (mt/with-test-user :rasta
+ (is (re-find #"no join path"
+ (params-error {:target "dashboard" :id dash-id :parameter_id "_CATEGORY_NAME_"
+ :constraints {:_PLACE_ "x"}}))
+ "cross-database non-joinable constraint must be rejected")
+ (testing "the target's own field is still fetchable without constraints"
+ (is (seq (:values (params-result {:target "dashboard" :id dash-id
+ :parameter_id "_CATEGORY_NAME_"}))))))))))))))
+
+(deftest param-values-without-table-perms-test
+ (testing "GHY-4141: a caller with collection read but NO data-query permission on the underlying
+ table still gets a field-backed parameter's values — the *param-values-query* relaxation
+ is the whole reason this tool takes content-read scope rather than a query scope"
+ (mt/with-temp
+ [:model/Collection collection {}
+ :model/Dashboard {dash-id :id}
+ {:collection_id (:id collection)
+ :parameters [{:name "Category Name" :slug "category_name" :id "_CATEGORY_NAME_" :type "category"}]}
+ :model/Card {card-id :id} {:collection_id (:id collection)
+ :database_id (mt/id)
+ :table_id (mt/id :venues)
+ :dataset_query (table-query (mt/id :venues))}
+ :model/DashboardCard _ {:card_id card-id
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_CATEGORY_NAME_"
+ :card_id card-id
+ :target [:dimension (mt/$ids venues $category_id->categories.name)]}]}]
+ ;; Grant collection read, but revoke create-queries on the database — so the caller can't author
+ ;; an ad-hoc query, yet the parameter-values path (bound *param-values-query* true, which relaxes
+ ;; exactly the create-queries/Field-read gate while still enforcing view-data) still returns
+ ;; values. If the tool stopped binding that var, this test would flip to a permission error.
+ ;; `with-restored-data-perms!` snapshots + reinstates DataPermissions in a finally — with-temp
+ ;; restores rows, not perms, so without this the All Users create-queries revocation would leak
+ ;; into every later test in the JVM.
+ (perms.test-util/with-restored-data-perms!
+ (perms/grant-collection-read-permissions! (perms-group/all-users) collection)
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/view-data :unrestricted)
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/create-queries :no)
+ (mt/with-test-user :rasta
+ (let [{:keys [values]} (params-result {:target "dashboard" :id dash-id
+ :parameter_id "_CATEGORY_NAME_" :limit 3})]
+ (is (= [["African"] ["American"] ["Artisan"]] values)
+ "filter values come back despite the caller having no table query permission")))))))
+
+(deftest date-range-without-table-perms-test
+ (testing "GHY-4519: the range holds the same permission posture as the value list. It runs a
+ different query shape — an aggregation rather than a breakout — under the same
+ *param-values-query* relaxation, so a caller with collection read and no data-query
+ permission must still get it. If the range path stopped binding that var, or the
+ relaxation stopped covering an aggregation, this flips to a permission error"
+ (mt/with-temp
+ [:model/Collection collection {}
+ :model/Dashboard {dash-id :id}
+ {:collection_id (:id collection)
+ :parameters [{:name "Date" :slug "date" :id "_DATE_" :type "date/all-options"}]}
+ :model/Card {card-id :id} {:collection_id (:id collection)
+ :database_id (mt/id)
+ :table_id (mt/id :checkins)
+ :dataset_query (table-query (mt/id :checkins))}
+ :model/DashboardCard _ {:card_id card-id
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_DATE_"
+ :card_id card-id
+ :target [:dimension (mt/$ids checkins $date)]}]}]
+ (perms.test-util/with-restored-data-perms!
+ (perms/grant-collection-read-permissions! (perms-group/all-users) collection)
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/view-data :unrestricted)
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/create-queries :no)
+ (mt/with-test-user :rasta
+ (let [{:keys [kind] lo :min hi :max} (params-result {:target "dashboard" :id dash-id
+ :parameter_id "_DATE_"})]
+ (is (= "date" kind))
+ (is (= "2013-01-03" lo) "the range comes back despite the caller having no table query permission")
+ (is (= "2015-12-29" hi))))))))
+
+(deftest scope-gate-test
+ (testing "GHY-4141: the tool requires agent:content:read"
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (is (re-find #"Insufficient scope"
+ (params-error #{"agent:sql:run"}
+ {:target "dashboard" :id (:id dashboard) :parameter_id "_STATIC_"})))
+ (is (= [["African"] ["American"] ["Asian"]]
+ (:values (params-result #{"agent:content:read"}
+ {:target "dashboard" :id (:id dashboard) :parameter_id "_STATIC_"}))))))))
+
+;;; ------------------------------------- C1: the question path must not lie -------------------------------------
+
+(defn- do-with-people-name-card!
+ "A native question whose sole parameter (`_PN_`) is a `{{name}}` field filter on `people.name` — a column with
+ more than the 1000-row field-search cap of distinct values, so the field-backed question path exercises the cap."
+ [f]
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp [:model/Card {card-id :id}
+ {:name "People by name"
+ :database_id (mt/id)
+ :query_type :native
+ :dataset_query {:database (mt/id)
+ :type :native
+ :native {:query "SELECT COUNT(*) FROM people WHERE {{name}}"
+ :template-tags {"name" {:name "name"
+ :display-name "Name"
+ :id "_PN_"
+ :type :dimension
+ :dimension [:field (mt/id :people :name) nil]
+ :widget-type :string/=}}}}}]
+ (mt/with-test-user :rasta
+ (f card-id)))))
+
+(deftest question-cap-is-a-floor-test
+ (testing "GHY-4141: a field-backed question parameter whose column has more distinct values than the 1000-row
+ field-search cap reports has_more_values true and steers toward `query` — the underlying
+ search-values-from-field-id hardcodes has_more_values false at the cap, which would tell the agent a
+ truncated list is the whole column"
+ (do-with-people-name-card!
+ (fn [card-id]
+ (let [args {:target "question" :id card-id :parameter_id "_PN_" :limit 1000}
+ {:keys [returned has_more_values]} (params-result args)]
+ (is (= 1000 returned) "the fetch fills the 1000-row cap")
+ (is (true? has_more_values) "and the cap is reported as a floor, not a complete set")
+ (is (re-find #"narrow with `query`" (steering-line args))
+ "with a steering line telling the agent to narrow rather than trust the list as exhaustive"))))))
+
+(deftest question-fetch-error-is-not-empty-values-test
+ (testing "GHY-4141: a fetch error on the field-backed question path surfaces as a tool error, NOT an empty value
+ list — search-values swallows the Throwable into [], which the tool would otherwise render as
+ {values [] has_more_values false} + \"No values available\", telling the agent the column is empty when
+ the fetch actually failed (the dashboard path re-throws; the question path must not diverge)"
+ (do-with-people-name-card!
+ (fn [card-id]
+ (with-redefs [search-values-query/search-values-query
+ (fn [& _] (throw (ex-info "simulated warehouse timeout" {:simulated true})))]
+ (let [error (params-error {:target "question" :id card-id :parameter_id "_PN_"})]
+ (is (re-find #"[Ee]rror" error) "the failure is reported as an error")
+ (is (not (re-find #"No values available" error))
+ "and never as the no-values-available steering line")))))))
+
+;;; --------------------------- I2: the constraint check must match what chain-filter runs ---------------------------
+
+(deftest remapped-target-constraint-verdict-matches-fetch-test
+ (testing "GHY-4141: on a Field->Field-remapped target (category_id->categories.name, the fixture's common case) the
+ join-path check's verdict matches what chain-filter actually does — it accepts the price constraint AND
+ that constraint genuinely narrows the values (a check that accepted a silently-dropped constraint would
+ return the same values with and without it)"
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp
+ [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Category Name" :slug "category_name" :id "_CATEGORY_NAME_" :type "category"}
+ {:name "Price" :slug "price" :id "_PRICE_" :type "category"}]}
+ :model/Card {vc :id} {:database_id (mt/id) :table_id (mt/id :venues) :dataset_query (table-query (mt/id :venues))}
+ :model/DashboardCard _ {:card_id vc
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_CATEGORY_NAME_" :card_id vc
+ :target [:dimension (mt/$ids venues $category_id->categories.name)]}
+ {:parameter_id "_PRICE_" :card_id vc
+ :target [:dimension (mt/$ids venues $price)]}]}]
+ (mt/with-test-user :rasta
+ (let [base {:target "dashboard" :id dash-id :parameter_id "_CATEGORY_NAME_"}
+ unnarrowed (:values (params-result base))
+ narrowed (:values (params-result (assoc base :constraints {:_PRICE_ 4})))]
+ (is (= [["Japanese"] ["Steakhouse"]] narrowed)
+ "the check accepts the constraint and it narrows to price=4's categories")
+ (is (not= (count unnarrowed) (count narrowed))
+ "which is a real narrowing — the accepted constraint was not silently dropped")))))))
+
+(deftest multi-field-target-constraint-intersection-test
+ (testing "GHY-4141: for a multi-field target the constraint must be reachable from EVERY target field, not just one.
+ _MULTI_ is mapped to categories.name (which price reaches via venues) AND people.name (which it does not).
+ The fetch runs a chain-filter per field and unions values, so accepting the constraint would apply it on
+ the categories run but silently drop it on the people run, leaking every unnarrowed person name into the
+ result. The check must reject."
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp
+ [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Multi" :slug "multi" :id "_MULTI_" :type "category"}
+ {:name "Price" :slug "price" :id "_PRICE_" :type "category"}]}
+ :model/Card {venues-card :id} {:database_id (mt/id) :table_id (mt/id :venues) :dataset_query (table-query (mt/id :venues))}
+ :model/Card {people-card :id} {:database_id (mt/id) :table_id (mt/id :people) :dataset_query (table-query (mt/id :people))}
+ ;; _MULTI_ reaches price only through the venues card; the people card's run cannot.
+ :model/DashboardCard _ {:card_id venues-card
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_MULTI_" :card_id venues-card
+ :target [:dimension (mt/$ids venues $category_id->categories.name)]}
+ {:parameter_id "_PRICE_" :card_id venues-card
+ :target [:dimension (mt/$ids venues $price)]}]}
+ :model/DashboardCard _ {:card_id people-card
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_MULTI_" :card_id people-card
+ :target [:dimension (mt/$ids people $name)]}]}]
+ (mt/with-test-user :rasta
+ (testing "the constraint reachable from only some target fields is rejected, not silently applied"
+ (let [error (params-error {:target "dashboard"
+ :id dash-id
+ :parameter_id "_MULTI_"
+ :constraints {:_PRICE_ 4}})]
+ (is (re-find #"_PRICE_" error))
+ (is (re-find #"silently ignore it" error))))
+ (testing "and without any constraint the multi-field target still returns its values"
+ (is (seq (:values (params-result {:target "dashboard" :id dash-id :parameter_id "_MULTI_"}))))))))))
+
+(deftest unparseable-date-constraint-test
+ (testing "GHY-4141: a constraint on a temporal field whose value isn't a date string chain filtering can parse is
+ rejected, not silently dropped. `chain-filter/add-filter` takes a date branch for a string value on a
+ temporal field and catches a parse failure into `nil`, dropping that filter — so the fetch returns
+ unnarrowed values the agent believes were filtered. This is the same silent-drop class as the unmapped
+ and unreachable cases, reached through the value rather than the field."
+ (mt/with-full-data-perms-for-all-users!
+ (mt/with-temp
+ [:model/Dashboard {dash-id :id}
+ {:parameters [{:name "Venue" :slug "venue" :id "_VENUE_" :type "category"}
+ {:name "Date" :slug "date" :id "_DATE_" :type "date/all-options"}]}
+ :model/Card {checkins-card :id} {:database_id (mt/id)
+ :table_id (mt/id :checkins)
+ :dataset_query (table-query (mt/id :checkins))}
+ :model/DashboardCard _ {:card_id checkins-card
+ :dashboard_id dash-id
+ :parameter_mappings [{:parameter_id "_VENUE_" :card_id checkins-card
+ :target [:dimension (mt/$ids checkins $venue_id)]}
+ {:parameter_id "_DATE_" :card_id checkins-card
+ :target [:dimension (mt/$ids checkins $date)]}]}]
+ (mt/with-test-user :rasta
+ (let [base {:target "dashboard" :id dash-id :parameter_id "_VENUE_"}]
+ (testing "an unparseable date value is rejected"
+ (let [error (params-error (assoc base :constraints {:_DATE_ "sometime last spring"}))]
+ (is (re-find #"_DATE_" error))
+ (is (re-find #"date" error))))
+ (testing "a parseable date range is still accepted, and genuinely narrows"
+ (let [unnarrowed (:values (params-result base))
+ narrowed (:values (params-result (assoc base :constraints
+ {:_DATE_ "2015-01-01~2015-01-31"})))]
+ (is (seq narrowed) "the constrained fetch still returns values")
+ (is (< (count narrowed) (count unnarrowed))
+ "and fewer than the unconstrained fetch — the accepted constraint was applied")))))))))
+
+(deftest constraints-with-query-test
+ (testing "GHY-4141: constraints and `query` narrow together — the search runs inside the chain-filtered set rather
+ than over the whole column. This is the tool's only route through `chain-filter-search` with constraints
+ (and the `*allow-implicit-uuid-field-remapping*` binding the search path pins), and neither
+ constraints-test nor query-search-test reaches it."
+ (with-fixtures [{:keys [dashboard]}]
+ (mt/with-test-user :rasta
+ (let [base {:target "dashboard" :id (:id dashboard) :parameter_id "_CATEGORY_NAME_"}]
+ (testing "both narrowings apply"
+ (is (= [["Steakhouse"]]
+ (:values (params-result (assoc base :query "Steak" :constraints {:_PRICE_ 4}))))))
+ (testing "a value matching the query but excluded by the constraint is absent — the constraint is not
+ dropped just because a query is also present"
+ (is (= [["African"]] (:values (params-result (assoc base :query "African"))))
+ "African is a real category, so the query alone finds it")
+ (is (= [] (:values (params-result (assoc base :query "African" :constraints {:_PRICE_ 4}))))
+ "but no price-4 venue is African, so the chain-filtered search excludes it")))))))
+
+(deftest no-match-for-query-blames-the-query-test
+ (testing "GHY-4141: when a `query` matches nothing the steering line must name the query as the reason. The
+ generic zero-values sentence offers only causes the agent can't act on — empty source, sandboxed away,
+ free-text filter — and reads as \"this parameter is broken\" when the actual recovery is to search for
+ something else. Both targets, since both reach the same line."
+ (with-fixtures [{:keys [dashboard native-card]}]
+ (mt/with-test-user :rasta
+ (doseq [args [{:target "dashboard" :id (:id dashboard) :parameter_id "_CATEGORY_NAME_" :query "zzzznope"}
+ {:target "question" :id (:id native-card) :parameter_id "_CARD_NAME_" :query "zzzznope"}]]
+ (testing (:target args)
+ (is (= {:values [] :returned 0 :has_more_values false} (params-result args)))
+ (let [line (steering-line args)]
+ (is (re-find #"zzzznope" line)
+ "the line quotes the search that found nothing")
+ (is (not (re-find #"source may be empty" line))
+ "and doesn't offer causes that can't explain a failed search"))))))))
diff --git a/test/metabase/mcp/v2/tools/query_test.clj b/test/metabase/mcp/v2/tools/query_test.clj
new file mode 100644
index 00000000000..ad0b3beafcf
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/query_test.clj
@@ -0,0 +1,1035 @@
+(ns metabase.mcp.v2.tools.query-test
+ "Contract tests for the v2 `execute_query` tool (GHY-4142), driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised on
+ every call. Keyset-cursor mechanics (tiebreaker choice, boundary predicates, bail-out and
+ refusal conditions) are owned by [[metabase.mcp.v2.query-test]]; here paging is exercised
+ only through the tool's public cursor contract."
+ (:require
+ [clojure.set :as set]
+ [clojure.string :as str]
+ [clojure.test :refer [deftest is testing use-fixtures]]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.tools.content]
+ [metabase.mcp.v2.tools.query :as tools.query]
+ [metabase.query-processor.core :as qp]
+ [metabase.test :as mt]
+ [metabase.test.data.interface :as tx]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+;; required for its side effect: registering `get_content`, which the definition round-trip drives.
+(comment metabase.mcp.v2.tools.content/keep-me)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(def ^:private execute-scope
+ #{"agent:query:run"})
+
+(defn- call!
+ "Call `execute_query` through the registry dispatch seam as the already-bound current user,
+ with the execute scope. Mints a query handle on every successful call. Returns the whole
+ dispatch outcome: `{:result <mcp content>}` for anything that reached the handler,
+ `{:error {:code .. :message ..}}` for a registry-level rejection (scope denial, args-schema
+ failure)."
+ [session-id arguments]
+ (registry/call-tool execute-scope session-id "execute_query" arguments))
+
+(defn- dispatch-error?
+ "Whether a [[call!]] outcome is an error, at either layer."
+ [{:keys [result error]}]
+ (boolean (or error (:isError result))))
+
+(defn- response-text
+ "The outcome's text block, or a registry-level rejection's message."
+ [{:keys [result error]}]
+ (if error (:message error) (-> result :content first :text)))
+
+(defn- payload
+ "Parse the JSON payload line of a successful execute_query response. Throws if the call
+ errored at either layer, so an error can never masquerade as an empty result."
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info "expected success, got tool error" {:outcome outcome})))
+ (-> outcome response-text str/split-lines first json/decode+kw))
+
+(defn- steering-line
+ "The steering sentence appended after the JSON payload, or nil on an unsteered response.
+ Throws on an error at either layer, for the same reason as [[payload]]."
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info "expected success, got tool error" {:outcome outcome})))
+ (second (str/split-lines (response-text outcome))))
+
+(defn- error-text
+ "The message of an errored call, at either layer. Throws if the call succeeded, so a passing
+ call can never satisfy an error assertion."
+ [outcome]
+ (when-not (dispatch-error? outcome)
+ (throw (ex-info "expected tool error, got success" {:outcome outcome})))
+ (response-text outcome))
+
+(defn- table-name-ref
+ "The `[database schema table]` portable name array for a test-data table."
+ [table-kw]
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ table (lib.metadata/table mp (mt/id table-kw))]
+ [(:name (lib.metadata/database mp)) (:schema table) (:name table)]))
+
+(defn- field-name-ref
+ [table-kw field-kw]
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ field (lib.metadata/field mp (mt/id table-kw field-kw))]
+ ["field" {} (conj (table-name-ref table-kw) (:name field))]))
+
+(defn- orders-query
+ "A fresh portable MBQL 5 query over ORDERS, optionally with extra stage clauses merged in."
+ ([] (orders-query nil))
+ ([stage-extra]
+ {:lib/type "mbql/query"
+ :stages [(merge {:lib/type "mbql.stage/mbql"
+ :source-table (table-name-ref :orders)}
+ stage-extra)]}))
+
+(defn- orders-card-query
+ "A Lib query over ORDERS for a card fixture's stored `:dataset_query`. Distinct from
+ [[orders-query]], which builds the tool-input shape a caller sends rather than a stored query."
+ []
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))]
+ (lib/query mp (lib.metadata/table mp (mt/id :orders)))))
+
+(defn- col-index
+ [cols col-name]
+ (some (fn [[i c]] (when (= (:name c) col-name) i)) (map-indexed vector cols)))
+
+(defn- row-ids
+ [{:keys [cols rows]}]
+ (let [idx (col-index cols "ID")]
+ (mapv #(nth % idx) rows)))
+
+(tx/defdataset big-ids
+ "Key values straddling the JS-safe integer boundary, 2^53-1 = 9007199254740991. Every
+ execute_query run carries `js-int-to-string?`, which renders anything past that boundary as a
+ STRING rather than a number, so these rows exercise a cursor boundary that arrives as text
+ while the column it is compared against stays numeric. The first two rows sit at or below the
+ boundary and page as ordinary numbers; the rest cross it."
+ [["big_ids"
+ [{:field-name "big_id" :base-type :type/BigInteger}]
+ [[9007199254740989]
+ [9007199254740991]
+ [9007199254740993]
+ [9007199254740995]
+ [9007199254740997]
+ [9007199254741001]]]])
+
+;;; ------------------------------------------------ Happy paths ---------------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest execute-query-happy-path-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:query (orders-query {:filters [["<=" {} (field-name-ref :orders :id) 3]]})})
+ body (payload result)]
+ (testing "GHY-4142: a fresh query returns rows, cols, and counts, and mints a query_handle"
+ (is (= 3 (:returned body)))
+ (is (= 3 (count (:rows body))))
+ (is (false? (:truncated body)))
+ (is (string? (:query_handle body)))
+ (is (= [1 2 3] (sort (row-ids body)))))
+ (testing "GHY-4142: an un-truncated page carries no cursor and no steering line"
+ (is (nil? (:next_cursor body)))
+ (is (nil? (steering-line result))))
+ (testing "GHY-4142: response cols carry only the wire projection — no internal metadata keys"
+ (is (seq (:cols body)))
+ (doseq [col (:cols body)]
+ (is (string? (:name col)))
+ (is (string? (:base_type col)))
+ (is (empty? (dissoc col :name :base_type :display_name :effective_type))
+ "any other key is internal metadata leaking onto the wire")))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest query-handle-rerun-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ args {:query (orders-query {:filters [["<=" {} (field-name-ref :orders :id) 3]]})}
+ first-body (payload (call! sid args))]
+ (testing "GHY-4142: re-running a returned query_handle serves exactly the rows the original call served"
+ (let [rerun-body (payload (call! sid {:query_handle (:query_handle first-body)}))]
+ (is (= (:rows first-body) (:rows rerun-body)))
+ (is (string? (:query_handle rerun-body)))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest validate-only-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:query (orders-query {:limit 3})
+ :validate_only true})
+ body (payload result)]
+ (testing "GHY-4142: validate_only mints a handle without executing"
+ (is (= 0 (:returned body)))
+ (is (false? (:truncated body)))
+ (is (string? (:query_handle body)))
+ (is (nil? (:rows body)))
+ (is (str/includes? (response-text result) "Query validated, not executed")))
+ (testing "GHY-4142: the affordance the message names works — the minted handle executes the validated query"
+ (let [run-body (payload (call! sid {:query_handle (:query_handle body)}))]
+ (is (= 3 (:returned run-body)))))))))
+
+;;; ------------------------------------------------ Cursor paging -------------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest cursor-steering-affordance-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:query (orders-query) :row_limit 5})
+ body (payload result)]
+ (testing "GHY-4142: a truncated page reports it and steers to the cursor"
+ (is (= 5 (:returned body)))
+ (is (true? (:truncated body)))
+ (is (string? (:next_cursor body)))
+ (is (str/includes? (steering-line result) "continue with `cursor`")))
+ (testing "GHY-4142: obeying the steering hint makes progress — the cursor serves the next page, same size, no overlap"
+ ;; row_limit sizes a cursor page like any other: the cursor carries the boundary, not
+ ;; the page size, so a chain that wants a fixed size passes it on every call.
+ (let [next-body (payload (call! sid {:cursor (:next_cursor body) :row_limit 5}))]
+ (is (= 5 (:returned next-body)))
+ (is (empty? (set/intersection (set (row-ids body)) (set (row-ids next-body)))))
+ (is (< (apply max (row-ids body)) (apply min (row-ids next-body)))
+ "the second page starts strictly past the first page's boundary")))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest cursor-paging-property-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ page-size 5
+ n-pages 4
+ ids (loop [args {:query (orders-query) :row_limit page-size}, acc [], pages 0]
+ (let [body (payload (call! sid args))
+ acc' (into acc (row-ids body))]
+ (if (or (>= (inc pages) n-pages) (not (:next_cursor body)))
+ acc'
+ (recur {:cursor (:next_cursor body) :row_limit page-size} acc' (inc pages)))))]
+ (testing "GHY-4142: paging by cursor yields strictly increasing, distinct PKs — no row skipped, none repeated"
+ (is (= (* page-size n-pages) (count ids)))
+ (is (apply < ids))
+ (is (= (count ids) (count (distinct ids)))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest query-limit-bounds-the-cursor-chain-test
+ ;; The query's own :limit bounds the whole result set, not each page. Paging must spend it down
+ ;; and stop, never reapply it per page and run off the end of what the caller asked for.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))]
+ (testing "GHY-4142: a query exhausted by its own limit is complete, not truncated"
+ (let [body (payload (call! sid {:query (orders-query {:limit 3})}))]
+ (is (= 3 (:returned body)))
+ (is (false? (:truncated body)))
+ (is (nil? (:next_cursor body))
+ "a cursor here would page past row 3 — rows the caller's limit excluded")))
+ (testing "GHY-4142: a limit larger than row_limit pages, but only up to the limit"
+ (let [ids (loop [args {:query (orders-query {:limit 12}) :row_limit 5}, acc [], pages 0]
+ (let [body (payload (call! sid args))
+ acc' (into acc (row-ids body))]
+ (if (or (>= pages 5) (not (:next_cursor body)))
+ acc'
+ (recur {:cursor (:next_cursor body) :row_limit 5} acc' (inc pages)))))]
+ (is (= 12 (count ids)) "the chain serves exactly the 12 rows the query asked for")
+ (is (= (count ids) (count (distinct ids))))
+ (is (apply < ids))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest exact-fill-is-not-truncated-test
+ ;; Companion to query-limit-bounds-the-cursor-chain-test, which pins the same property when the
+ ;; query's own :limit is what runs out. Here nothing but the result set itself is exhausted:
+ ;; PRODUCTS has exactly 4 categories, so a 4-row page at row_limit 4 is complete. The tool
+ ;; fetches one row past row_limit, so truncation is observed rather than inferred from a full
+ ;; page — inferring it would mint a cursor whose next page is always empty.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (table-name-ref :products)
+ :aggregation [["count" {}]]
+ :breakout [(field-name-ref :products :category)]}]}]
+ (testing "GHY-4142: a result set exactly filling row_limit is complete, not truncated"
+ (let [result (call! sid {:query query :row_limit 4})
+ body (payload result)]
+ (is (= 4 (:returned body)))
+ (is (false? (:truncated body)))
+ (is (nil? (:next_cursor body))
+ "a cursor here would page onto an empty result")
+ (is (nil? (steering-line result)))))
+ (testing "GHY-4142: one row short of the same result set still pages"
+ (let [body (payload (call! sid {:query query :row_limit 3}))]
+ (is (= 3 (:returned body)))
+ (is (true? (:truncated body)))
+ (is (some? (:next_cursor body)))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest fan-out-join-refuses-cursor-test
+ ;; Companion to the refusal contract in metabase.mcp.v2.query-test: at the tool surface a
+ ;; truncated fan-out page must be an explicit dead end — truncated with no next_cursor,
+ ;; steered to narrowing — never a cursor that would page with silent gaps.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ mp (lib-be/application-database-metadata-provider (mt/id))
+ p-id (lib.metadata/field mp (mt/id :products :id))
+ o-pid (lib.metadata/field mp (mt/id :orders :product_id))
+ joined (-> (lib/query mp (lib.metadata/table mp (mt/id :products)))
+ (lib/join (lib/join-clause (lib.metadata/table mp (mt/id :orders))
+ [(lib/= p-id o-pid)])))
+ handle (v2.queries/mint-query-handle! sid (mt/user->id :rasta)
+ (v2.queries/encode-serialized-query
+ (lib/prepare-for-serialization joined)))
+ ;; row_limit, not an embedded :limit — a query the caller limited to 5 rows that
+ ;; returns 5 is complete, and the truncation this pins has to come from the page cap.
+ result (call! sid {:query_handle handle :row_limit 5})
+ body (payload result)]
+ (testing "GHY-4142: a truncated fan-out join page is an explicit dead end, not a gapped cursor"
+ (is (= 5 (:returned body)))
+ (is (true? (:truncated body)))
+ (is (nil? (:next_cursor body)))
+ (is (str/includes? (steering-line result) "narrow the query"))
+ (testing "the dead end names an affordance that exists"
+ (is (str/includes? (steering-line result) "raise `row_limit`"))
+ (is (not (str/includes? (steering-line result) "export"))
+ "no export tool exists in v2 — steering at one sends the agent after an affordance it does not have"))
+ (testing "and does not suggest paging by hand — a keyset over a fan-out join is exactly
+ the gapped pagination this dead end exists to prevent, so the hint execute_sql
+ gives must not leak onto the MBQL path"
+ (is (not (str/includes? (steering-line result) "ORDER BY")))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest aggregated-query-cursor-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ agg-args {:query (orders-query {:aggregation [["count" {}]]
+ :breakout [(field-name-ref :orders :user_id)]
+ :order-by [["asc" {} (field-name-ref :orders :user_id)]]})
+ :row_limit 5}
+ body (payload (call! sid agg-args))]
+ (testing "GHY-4142: a truncated aggregated page pages through an appended-stage cursor"
+ (is (= 5 (:returned body)))
+ (is (true? (:truncated body)))
+ (is (string? (:next_cursor body)))
+ (let [uid-idx (col-index (:cols body) "USER_ID")
+ next-body (payload (call! sid {:cursor (:next_cursor body)}))]
+ ;; The aggregated cursor carries no embedded page size (an in-stage limit would cut
+ ;; the base set pre-aggregation), so the next page sizes by its own row_limit.
+ (is (pos? (:returned next-body)))
+ (is (< (apply max (map #(nth % uid-idx) (:rows body)))
+ (apply min (map #(nth % uid-idx) (:rows next-body))))
+ "the second page of groups starts strictly past the first page's boundary")))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest non-unique-projection-refuses-cursor-test
+ ;; GHY-4363: a projection with no unique key has no total order. The full-tuple tiebreaker ties
+ ;; on every duplicate row, and a strictly-past-the-boundary keyset then skips every row tied
+ ;; with the boundary. PRODUCTS holds 200 rows across 4 categories, so a CATEGORY-only
+ ;; projection that minted a cursor would serve 4 pages, drop 180 rows, and report itself
+ ;; complete — the exact silent gap the cursor contract exists to prevent.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (table-name-ref :products)
+ :fields [(field-name-ref :products :category)]}]}
+ result (call! sid {:query query :row_limit 5})
+ body (payload result)]
+ (testing "GHY-4363: a projection without a unique key is an explicit dead end, not a cursor"
+ (is (= 5 (:returned body)))
+ (is (true? (:truncated body)))
+ (is (nil? (:next_cursor body)))
+ (is (not (str/includes? (steering-line result) "continue with `cursor`"))
+ "offering a cursor affordance with no cursor would strand the agent")
+ (is (str/includes? (steering-line result) "narrow the query")))
+ (testing "GHY-4363: projecting the PK alongside restores the cursor — the refusal is about uniqueness, not about `fields`"
+ (let [with-pk (assoc-in query [:stages 0 :fields]
+ [(field-name-ref :products :id)
+ (field-name-ref :products :category)])
+ pk-body (payload (call! sid {:query with-pk :row_limit 5}))]
+ (is (true? (:truncated pk-body)))
+ (is (string? (:next_cursor pk-body)))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest aggregated-cursor-chain-continues-past-the-appended-stage-test
+ ;; GHY-4363: page 1 of an aggregated chain appends a stage to carry the keyset, so every later
+ ;; page reads a query whose LAST stage is that appended one — unaggregated, with no projected
+ ;; PK. The uniqueness proof has to look back through it to the aggregating stage; a proof that
+ ;; only inspects the last stage kills the chain at page 2.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ page-size 3
+ n-pages 4
+ uids (loop [args {:query (orders-query {:aggregation [["count" {}]]
+ :breakout [(field-name-ref :orders :user_id)]
+ :order-by [["asc" {} (field-name-ref :orders :user_id)]]})
+ :row_limit page-size}
+ acc []
+ pages 0]
+ (let [body (payload (call! sid args))
+ idx (col-index (:cols body) "USER_ID")
+ acc' (into acc (map #(nth % idx) (:rows body)))]
+ (if (or (>= (inc pages) n-pages) (not (:next_cursor body)))
+ acc'
+ (recur {:cursor (:next_cursor body) :row_limit page-size} acc' (inc pages)))))]
+ (testing "GHY-4363: an aggregated chain keeps paging past the appended stage, with no gaps or repeats"
+ (is (= (* page-size n-pages) (count uids)))
+ (is (apply < uids) "strictly increasing => no boundary repeats and no groups skipped")
+ (is (= (count uids) (count (distinct uids)))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest large-integer-boundary-paging-test
+ ;; GHY-4363: the cursor boundary is read straight out of the row that was served, and
+ ;; `js-int-to-string?` has already turned any integer past 2^53-1 into a string by then — so the
+ ;; minted predicate really does compare a numeric column against a string literal. It compiles
+ ;; correctly only because the query processor re-types it on the way in:
+ ;; `wrap-value-literals` gives the bare literal the column's effective type and
+ ;; `auto-parse-filter-values` parses it back to a bigint, both above the driver layer, so every
+ ;; driver sees a number. That dependency is invisible from the cursor code and nothing else
+ ;; pins it — pin it here, across the threshold, in one exact chain.
+ (mt/dataset big-ids
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (table-name-ref :big_ids)
+ :order-by [["asc" {} (field-name-ref :big_ids :big_id)]]}]}
+ seen (loop [args {:query query :row_limit 2}, acc [], pages 0]
+ (let [body (payload (call! sid args))
+ idx (col-index (:cols body) "BIG_ID")
+ acc' (into acc (map #(nth % idx) (:rows body)))]
+ (if (or (>= pages 10) (not (:next_cursor body)))
+ acc'
+ (recur {:cursor (:next_cursor body) :row_limit 2} acc' (inc pages)))))]
+ (testing "GHY-4363: every row is served exactly once across a boundary that crosses 2^53"
+ ;; compared as strings: the rows below the boundary come back as numbers and the ones
+ ;; past it as strings, which is the whole point.
+ (is (= ["9007199254740989" "9007199254740991" "9007199254740993"
+ "9007199254740995" "9007199254740997" "9007199254741001"]
+ (mapv str seen)))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest remapped-column-paging-test
+ ;; The remap middleware injects a display column into every row (PEOPLE.NAME beside
+ ;; ORDERS.USER_ID), so the row no longer matches the projection position for position.
+ ;; next-page-query has to drop the injected columns before reading the boundary; misalignment
+ ;; would read some other column's value and page from a boundary that was never served.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-column-remappings [orders.user_id people.name]
+ (let [sid (str (random-uuid))
+ ordered-by (fn [field-kw]
+ {:query (orders-query {:order-by [["asc" {} (field-name-ref :orders field-kw)]]})
+ :row_limit 5})]
+ (testing "GHY-4142: a remapped column in the projection doesn't defeat the boundary read — the cursor still pages"
+ (let [body (payload (call! sid (ordered-by :id)))]
+ (is (true? (:truncated body)))
+ (is (string? (:next_cursor body)))
+ (let [next-body (payload (call! sid {:cursor (:next_cursor body) :row_limit 5}))]
+ (is (empty? (set/intersection (set (row-ids body)) (set (row-ids next-body))))
+ "an overlap would mean the boundary was read from the wrong row position")
+ (is (< (apply max (row-ids body)) (apply min (row-ids next-body)))))))
+ (testing "GHY-4142: ordering by the remapped column mints no cursor — the middleware sorts by display value while the keyset predicate compares raw ones"
+ (let [body (payload (call! sid (ordered-by :user_id)))]
+ (is (true? (:truncated body)))
+ (is (nil? (:next_cursor body))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest row-limit-caps-the-page-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))]
+ (testing "GHY-4142: row_limit caps a query that would otherwise return the whole table"
+ (let [body (payload (call! sid {:query (orders-query) :row_limit 7}))]
+ (is (= 7 (:returned body)))
+ (is (= 7 (count (:rows body))))
+ (is (true? (:truncated body)))))
+ (testing "GHY-4142: the query's own limit binds when it is the smaller of the two"
+ (let [body (payload (call! sid {:query (orders-query {:limit 2}) :row_limit 7}))]
+ (is (= 2 (:returned body)))
+ (is (false? (:truncated body)))))
+ (testing "GHY-4142: an unbounded query with no row_limit is capped at the default, not run to completion"
+ (let [body (payload (call! sid {:query (orders-query)}))]
+ (is (= 100 (:returned body)))
+ (is (true? (:truncated body)))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest prompt-rides-the-cursor-chain-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ uid (mt/user->id :rasta)
+ body (payload (call! sid {:query (orders-query)
+ :row_limit 5
+ :prompt "show me all orders"}))]
+ (testing "GHY-4142: a cursor minted without its own prompt keeps the original request for the feedback flow"
+ (is (= "show me all orders"
+ (:prompt (v2.queries/resolve-query-handle! sid uid (:next_cursor body)))))
+ (is (= "show me all orders"
+ (:prompt (v2.queries/resolve-query-handle! sid uid (:query_handle body))))))))))
+
+;;; ------------------------------------------------ Teaching errors -----------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest cursor-page-handle-carries-no-page-boundary-test
+ ;; GHY-4363: a cursor page's stored query embeds the keyset boundary it resumed from — that is
+ ;; how paging works at all. But the handle the response hands back is what `question_write`
+ ;; saves and what the UI visualizes, and a boundary is a scroll position, not part of the
+ ;; question: saving page 3 must save "orders", never "orders from row 4171 onward". The cursor
+ ;; keeps its boundary; the handle does not.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ stored (fn [handle]
+ (:query (v2.queries/resolve-query-handle! sid (mt/user->id :rasta) handle)))
+ page1 (payload (call! sid {:query (orders-query) :row_limit 5}))
+ page2 (payload (call! sid {:cursor (:next_cursor page1) :row_limit 5}))
+ page3 (payload (call! sid {:cursor (:next_cursor page2) :row_limit 5}))]
+ (testing "the chain really did resume from a boundary — otherwise this pins nothing"
+ (is (< (apply max (row-ids page1)) (apply min (row-ids page3)))))
+ (testing "GHY-4363: the deep page's handle carries no page boundary"
+ (is (empty? (:filters (last (:stages (stored (:query_handle page3))))))))
+ (testing "GHY-4363: so re-running it serves the question from the top, not the page again"
+ (let [rerun (payload (call! sid {:query_handle (:query_handle page3)}))]
+ (is (= (row-ids page1) (vec (take 5 (row-ids rerun)))))))
+ (testing "GHY-4363: a filter the caller wrote is part of the question and survives"
+ (let [f1 (payload (call! sid {:query (orders-query {:filters [[">" {} (field-name-ref :orders :id) 100]]})
+ :row_limit 5}))
+ f2 (payload (call! sid {:cursor (:next_cursor f1) :row_limit 5}))
+ fs (:filters (last (:stages (stored (:query_handle f2)))))]
+ (is (= 1 (count fs)) "the caller's clause, and only it")
+ (is (= ">" (ffirst fs)))))))))
+
+(deftest ^:parallel input-exclusivity-test
+ ;; Error paths mint nothing, so these calls go straight through registry/call-tool and stay
+ ;; ^:parallel; the minting tests above use the call! helper plus model cleanup instead.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ expected "Pass exactly one of query | query_handle | cursor"]
+ (testing "GHY-4142: no query input at all is a teaching error naming the three options"
+ (is (str/starts-with? (error-text (registry/call-tool execute-scope sid "execute_query" {}))
+ expected)))
+ (testing "GHY-4142: two query inputs at once is the same teaching error"
+ (is (str/starts-with? (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query (orders-query)
+ :query_handle "some-handle"}))
+ expected)))
+ (testing "GHY-4142: the teaching error is a 400, not a downstream 500"
+ (let [e (try
+ (tools.query/execute-query {} {:session-id sid})
+ (catch Exception e e))]
+ (is (= 400 (:status-code (ex-data e)))))))))
+
+(deftest ^:parallel native-query-rejection-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))]
+ (testing "GHY-4142: a native stage is rejected up front with the execute_sql steer"
+ (is (= "Native queries are not supported here; use execute_sql instead."
+ (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/native"
+ :native "SELECT 1"}]}}))))))))
+
+(deftest ^:parallel row-limit-validation-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))]
+ (doseq [bad [0 2001]]
+ (testing (format "GHY-4142: row_limit %d fails schema validation with a teaching-style message" bad)
+ (let [text (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query (orders-query) :row_limit bad}))]
+ (is (str/starts-with? text "Invalid arguments"))
+ (is (str/includes? text "row_limit"))))))))
+
+;;; --------------------------------------------- Handles and security ---------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest handle-existence-collapse-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ foreign-handle (v2.queries/mint-query-handle! sid (mt/user->id :crowberto)
+ (v2.queries/encode-serialized-query
+ (orders-query {:limit 1})))
+ fetch-error (fn [handle]
+ (mt/with-current-user (mt/user->id :rasta)
+ (error-text (call! sid {:query_handle handle}))))]
+ (testing "GHY-4142: another user's real handle and a nonexistent handle yield string-identical errors — no existence oracle"
+ (let [nonexistent-msg (fetch-error (str (random-uuid)))
+ foreign-msg (fetch-error foreign-handle)]
+ (is (= nonexistent-msg foreign-msg))
+ (is (= "Query handle not found — it may have expired; run the query again." foreign-msg))))
+ (testing "GHY-4142: the cursor path collapses identically"
+ (is (= (mt/with-current-user (mt/user->id :rasta)
+ (error-text (call! sid {:cursor foreign-handle})))
+ (mt/with-current-user (mt/user->id :rasta)
+ (error-text (call! sid {:cursor (str (random-uuid))})))))))))
+
+(deftest ^:parallel scope-gating-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))]
+ (testing "GHY-4142: a token without the execute scope is denied before dispatch"
+ ;; A scope denial is a JSON-RPC error, not `isError` tool content — nothing reaches the handler.
+ (let [{:keys [error]} (registry/call-tool #{"agent:content:read"} sid "execute_query" {})]
+ (is (re-find #"^Insufficient scope to call tool: execute_query\." (:message error)))))
+ (testing "GHY-4142: the identical call with the execute scope reaches the handler (positive control)"
+ ;; It fails input validation — proof it got past the scope gate without minting anything.
+ (is (str/starts-with? (error-text (registry/call-tool execute-scope sid "execute_query" {}))
+ "Pass exactly one of"))))))
+
+(deftest ^:parallel scope-advertisement-test
+ (testing "GHY-4142: the execute scope is grantable — advertised via registered-scopes"
+ (is (contains? (registry/registered-scopes) "agent:query:run")))
+ (testing "GHY-4142: tools/list visibility follows the scope on both sides"
+ (is (some #(= "execute_query" (:name %)) (registry/list-tools #{"agent:query:run"})))
+ (is (not (some #(= "execute_query" (:name %)) (registry/list-tools #{"agent:content:read"})))))
+ (testing "GHY-4142: the tool advertises itself read-only"
+ (let [tool (first (filter #(= "execute_query" (:name %)) (registry/list-tools nil)))]
+ (is (true? (get-in tool [:annotations :readOnlyHint]))))))
+
+;;; --------------------------------------------- Numeric-id dialect -----------------------------------------------
+
+(defn- numeric-orders-query
+ "A fresh MBQL 5 query over ORDERS in the numeric-id dialect, optionally with extra stage
+ clauses merged in."
+ ([] (numeric-orders-query nil))
+ ([stage-extra]
+ {:lib/type "mbql/query"
+ :stages [(merge {:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :orders)}
+ stage-extra)]}))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest numeric-ids-happy-path-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:query (numeric-orders-query
+ {:filters [["<=" {} ["field" {} (mt/id :orders :id)] 3]]})})
+ body (payload result)]
+ (testing "a numeric-id query body executes and mints a query_handle"
+ (is (= 3 (:returned body)))
+ (is (string? (:query_handle body)))
+ (is (= [1 2 3] (sort (row-ids body)))))
+ (testing "the minted handle re-runs the same query"
+ (is (= [1 2 3] (sort (row-ids (payload (call! sid {:query_handle (:query_handle body)})))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest numeric-ids-implicit-join-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:query (numeric-orders-query
+ {:aggregation [["count" {}]]
+ :breakout [["field" {} (mt/id :products :category)]]})})
+ body (payload result)]
+ (testing "a numeric field ref on an FK-related table gets its implicit join wired by repair"
+ (is (= 4 (:returned body)))
+ (is (some #(= "CATEGORY" (:name %)) (:cols body))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest numeric-ids-validate-only-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ result (call! sid {:query (numeric-orders-query {:limit 2})
+ :validate_only true})
+ body (payload result)]
+ (testing "validate_only accepts the numeric dialect and mints a handle without executing"
+ (is (= 0 (:returned body)))
+ (is (string? (:query_handle body))))
+ (testing "the handle then executes the validated query"
+ (is (= 2 (:returned (payload (call! sid {:query_handle (:query_handle body)}))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest numeric-source-card-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-temp [:model/Card card {:dataset_query (lib/limit (orders-card-query) 5)}]
+ (let [sid (str (random-uuid))
+ result (call! sid {:query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-card (:id card)
+ :limit 2}]}})
+ body (payload result)]
+ (testing "a numeric source-card id resolves to the saved card"
+ (is (= 2 (:returned body)))))))))
+
+(deftest ^:parallel numeric-unknown-table-teaching-error-test
+ ;; Error paths mint nothing — call through registry/call-tool directly, like the other
+ ;; ^:parallel error-path tests above.
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table 999999999}]}}))]
+ (testing "an unknown numeric table id is a teaching error steering to browse_data"
+ (is (str/includes? msg "No table found with id 999999999"))
+ (is (str/includes? msg "browse_data"))))))
+
+(deftest ^:parallel error-hints-name-v2-tools-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ mp (lib-be/application-database-metadata-provider (mt/id))
+ db (:name (lib.metadata/database mp))]
+ (testing "a name-resolution miss steers to browse_data, never to the v1 read_resource surface"
+ (let [msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table [db "PUBLIC" "NO_SUCH_TABLE"]}]}}))]
+ (is (str/includes? msg "No table found matching portable FK"))
+ (is (str/includes? msg "browse_data"))
+ (is (not (str/includes? msg "read_resource")))
+ (is (not (str/includes? msg "metabase://"))))))))
+
+;;; -------------------------------- Numeric metric / measure / segment refs ---------------------------------------
+
+;; The numeric-id dialect documents `["measure", {}, 7]`, `["segment", {}, 3]` and
+;; `["metric", {}, 42]`, but nothing in the PR exercises them. These pin the happy path and
+;; the unknown-id recovery message, which is the one an agent that guessed an id actually reads.
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest numeric-measure-ref-executes-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-temp [:model/Measure {measure-id :id}
+ {:name "query-test order count"
+ :table_id (mt/id :orders)
+ :creator_id (mt/user->id :crowberto)
+ :definition {:lib/type :mbql/query
+ :database (mt/id)
+ :stages [{:lib/type :mbql.stage/mbql
+ :source-table (mt/id :orders)
+ :aggregation [[:count {:lib/uuid (str (random-uuid))}]]}]}}]
+ (let [sid (str (random-uuid))
+ body (payload (call! sid {:query (numeric-orders-query
+ {:aggregation [["measure" {} measure-id]]})}))]
+ (testing "a numeric measure ref executes"
+ (is (= 1 (:returned body)))
+ (is (pos-int? (ffirst (:rows body))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest numeric-segment-ref-executes-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-temp [:model/Segment {segment-id :id}
+ {:name "query-test first three orders"
+ :table_id (mt/id :orders)
+ :creator_id (mt/user->id :crowberto)
+ :definition {:lib/type :mbql/query
+ :database (mt/id)
+ :stages [{:lib/type :mbql.stage/mbql
+ :source-table (mt/id :orders)
+ :filters [[:<= {:lib/uuid (str (random-uuid))}
+ [:field {:lib/uuid (str (random-uuid))}
+ (mt/id :orders :id)]
+ 3]]}]}}]
+ (let [sid (str (random-uuid))
+ body (payload (call! sid {:query (numeric-orders-query
+ {:filters [["segment" {} segment-id]]})}))]
+ (testing "a numeric segment ref executes and filters"
+ (is (= 3 (:returned body)))
+ (is (= [1 2 3] (sort (row-ids body))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest numeric-metric-ref-executes-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-temp [:model/Card {metric-id :id}
+ {:type :metric
+ :name "query-test order count metric"
+ :dataset_query (lib/aggregate (orders-card-query) (lib/count))}]
+ (let [sid (str (random-uuid))
+ body (payload (call! sid {:query (numeric-orders-query
+ {:aggregation [["metric" {} metric-id]]})}))]
+ (testing "a numeric metric (card) ref executes"
+ (is (= 1 (:returned body)))
+ (is (pos-int? (ffirst (:rows body))))))))))
+
+;; An id the agent guessed is echoed back to it, so it has to survive the round trip verbatim.
+;; `tru` formats a bare number through MessageFormat, which applies locale digit grouping and
+;; turns 999999999 into "999,999,999" — an id the agent cannot retry with. The v2 unknown-table
+;; error already guards this by passing `(str table-id)`; these three paths do not.
+(deftest ^:parallel numeric-unknown-measure-teaching-error-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query (numeric-orders-query
+ {:aggregation [["measure" {} 999999999]]})}))]
+ (testing "the unknown id is echoed verbatim, not locale-grouped"
+ (is (str/includes? msg "999999999"))
+ (is (not (str/includes? msg "999,999,999"))))
+ (testing "and the message steers to the v2 discovery tool"
+ (is (str/includes? msg "browse_data"))
+ (is (not (str/includes? msg "read_resource")))))))
+
+(deftest ^:parallel numeric-unknown-segment-teaching-error-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query (numeric-orders-query
+ {:filters [["segment" {} 999999999]]})}))]
+ (testing "the unknown id is echoed verbatim, not locale-grouped"
+ (is (str/includes? msg "999999999"))
+ (is (not (str/includes? msg "999,999,999"))))
+ (testing "and the message steers to the v2 discovery tool"
+ (is (str/includes? msg "browse_data"))
+ (is (not (str/includes? msg "read_resource")))))))
+
+(deftest ^:parallel numeric-unknown-metric-teaching-error-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query (numeric-orders-query
+ {:aggregation [["metric" {} 999999999]]})}))]
+ (testing "the unknown id is echoed verbatim, not locale-grouped"
+ (is (str/includes? msg "999999999"))
+ (is (not (str/includes? msg "999,999,999"))))
+ (testing "and the message steers the agent at a v2 tool, never v1's read_resource"
+ (is (or (str/includes? msg "search") (str/includes? msg "browse_data")))
+ (is (not (str/includes? msg "read_resource")))))))
+
+;; Field refs are the highest-traffic numeric ref in the new dialect, so the unknown-field-id
+;; message is the one an agent hits most often after guessing.
+(deftest ^:parallel numeric-unknown-field-teaching-error-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query (numeric-orders-query
+ {:filters [[">" {} ["field" {} 999999999] 0]]})}))]
+ (testing "the unknown field id is echoed verbatim, not locale-grouped"
+ (is (str/includes? msg "999999999"))
+ (is (not (str/includes? msg "999,999,999"))))
+ (testing "and the message steers to the v2 discovery tool"
+ (is (str/includes? msg "browse_data"))
+ (is (not (str/includes? msg "read_resource")))))))
+
+;; The pipeline states the miss; this surface supplies the recovery sentence. These assert the
+;; two halves actually meet — a v2 caller gets v2 vocabulary and never v1's.
+(deftest ^:parallel recovery-hints-reach-the-agent-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query (numeric-orders-query
+ {:filters [[">" {} ["field" {} 999999999] 0]]})}))]
+ (testing "the base statement and this surface's hint arrive as one message"
+ (is (str/includes? msg "No field found with id 999999999."))
+ (is (str/includes? msg "browse_data")))
+ (testing "and never v1's vocabulary"
+ (is (not (str/includes? msg "read_resource")))
+ (is (not (str/includes? msg "metabase://")))))))
+
+(deftest ^:parallel uri-in-source-table-hint-is-v2-flavored-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table "metabase://metric/76"}]}}))]
+ (testing "the URI rejection carries v2's numeric-id recovery, not v1's portable_entity_id one"
+ (is (str/includes? msg "does not accept URIs"))
+ (is (str/includes? msg "aggregation"))
+ (is (not (str/includes? msg "portable_entity_id")))))))
+
+;;; --------------------------------------- Schema failures and dialect round-trips --------------------------------
+
+;;; GHY-4313. `:query` stays an open `[:map]` at the registry boundary on purpose: the dialect
+;;; `execute_query` accepts is the union of the numeric-id and portable-name forms *plus* the
+;;; repair layer's forgiveness, which no single lib schema describes. What these pin down instead
+;;; is the two properties a strict schema was meant to buy — a structural failure teaches rather
+;;; than stonewalls, and the shapes the tool documents keep working.
+
+(deftest ^:parallel schema-invalid-query-names-the-offending-path-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ msg (error-text (registry/call-tool execute-scope sid "execute_query"
+ {:query (numeric-orders-query {:limit "ten"})}))]
+ (testing "a structurally invalid query is refused with the path and the expectation, not a bare verdict"
+ (is (str/includes? msg "limit"))
+ (is (str/includes? msg "should be an integer"))
+ (is (str/includes? msg "stages")))
+ (testing "and never as an opaque internal failure"
+ (is (not (str/includes? msg "Internal error")))))))
+
+(deftest ^:parallel schema-failure-locates-the-offending-stage-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql" :source-table (mt/id :orders)}
+ {:lib/type "mbql.stage/mbql" :fields "not-a-list"}]}
+ msg (error-text (registry/call-tool execute-scope sid "execute_query" {:query query}))]
+ (testing "the failing stage is named by index — a model editing a multi-stage query needs to know which one"
+ (is (str/includes? msg "1"))
+ (is (str/includes? msg "fields"))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest repair-forgiven-shortcuts-still-execute-test
+ (testing "GHY-4313: the shortcuts the repair layer exists to forgive are not schema failures"
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))]
+ (testing "a stage that omits lib/type still runs"
+ (is (= 1 (:returned (payload (call! sid {:query {:lib/type "mbql/query"
+ :stages [{:source-table (mt/id :orders)
+ :limit 1}]}}))))))
+ (testing "a clause written without its options map still runs"
+ (is (= 1 (:returned (payload (call! sid {:query (numeric-orders-query
+ {:aggregation [["count"]]})})))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest documented-dialect-example-executes-test
+ (testing "GHY-4313: the worked example in the execute_query tool description runs as written"
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [body (payload (call! (str (random-uuid))
+ {:query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :orders)
+ :aggregation [["count" {}]]
+ :breakout [["field"
+ {:temporal-unit "month"}
+ (mt/id :orders :created_at)]]}]}
+ :row_limit 5}))]
+ (is (pos? (:returned body))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest definition-round-trip-executes-test
+ (testing "GHY-4313: get_content's `definition` output is accepted back as `query` verbatim, as the tool docs promise"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-temp [:model/Card card {:dataset_query (lib/limit (orders-card-query) 5)}]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ content (registry/call-tool #{"agent:content:read"} sid "get_content"
+ {:items [{:type "question" :id (:id card)}]
+ :include ["definition"]})
+ definition (-> content response-text json/decode+kw
+ :results first :definition)]
+ (is (some? definition) "get_content returned no definition to round-trip")
+ (is (pos? (:returned (payload (call! sid {:query definition :row_limit 5})))))))))))
+
+;;; ------------------------------------------- QP input whitelist -------------------------------------------------
+
+;;; GHY-4313: the QP only ever sees the keys MCP forwards
+;;; ([[metabase.mcp.v2.tools.query/query-passthrough-keys]]). A fresh `query` is additionally
+;;; rejected outright by the closed `:metabase.lib.schema/query`, but the handle path skips that
+;;; schema — `resolve-query-handle!` checks only that stages are non-empty and the last one has a
+;;; positive limit, and `POST /drills` stores a caller-supplied query verbatim. So an unknown key
+;;; genuinely reaches the execution boundary there, and these drive the tool through a stored
+;;; handle and assert on what reaches the query processor. The QP itself is stubbed, so nothing but
+;;; the boundary's own filtering can account for a key's absence.
+
+(def ^:private fake-qp-result
+ "The minimum a stubbed `process-query` has to return for the tool to finish a page."
+ {:status :completed
+ :data {:cols [{:name "ID" :base_type :type/BigInteger :display_name "ID"}]
+ :rows [[1]]}})
+
+(defn- capture-qp-query!
+ "Call `execute_query` with `arguments`, stubbing the QP so nothing executes, and return the
+ query map that reached [[metabase.query-processor.core/process-query]]. Throws if the tool
+ returned an error, so a rejected call can never look like a stripped key."
+ [arguments]
+ (let [captured (atom nil)]
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-dynamic-fn-redefs [qp/process-query (fn [query]
+ (reset! captured query)
+ fake-qp-result)]
+ (let [outcome (call! (str (random-uuid)) arguments)]
+ (when (dispatch-error? outcome)
+ (throw (ex-info "expected success, got tool error" {:outcome outcome})))))))
+ (or @captured
+ (throw (ex-info "process-query was never called" {:arguments arguments})))))
+
+(defn- pk-ordered-orders-query
+ "An ORDERS query already ordered by its PK, merged with `extra`. Its row order is total, so
+ [[metabase.mcp.v2.query/with-total-order]] passes it through as-is — what is stored is what
+ reaches the QP."
+ [extra]
+ (merge (numeric-orders-query {:limit 1
+ :order-by [["asc" {} ["field" {} (mt/id :orders :id)]]]})
+ {:database (mt/id)}
+ extra))
+
+(defn- stored-handle!
+ "Mint a query handle over `stored` for rasta. The handle path skips the representations
+ pipeline, so the stored query reaches the execution boundary with the keys it was minted with."
+ [session-id stored]
+ (mt/with-current-user (mt/user->id :rasta)
+ (v2.queries/mint-query-handle! session-id (mt/user->id :rasta)
+ (v2.queries/encode-serialized-query stored))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest query-info-never-reaches-the-qp-test
+ (testing "GHY-4313: a query's own :info never reaches the QP — MCP alone attributes the execution"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ handle (stored-handle! sid (pk-ordered-orders-query {:info {:card-id 999}}))
+ {:keys [info]} (capture-qp-query! {:query_handle handle})]
+ (is (not (contains? info :card-id)))
+ (is (= (mt/user->id :rasta) (:executed-by info)))
+ (is (= :agent (:context info)))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest caller-middleware-never-reaches-the-qp-test
+ (testing "GHY-4313: the caller cannot set query :middleware — MCP alone chooses the QP options"
+ (let [{:keys [middleware]} (capture-qp-query!
+ {:query (assoc (numeric-orders-query {:limit 1})
+ :middleware {:ignore-cached-results? true})})]
+ (is (not (contains? middleware :ignore-cached-results?)))
+ (is (true? (:js-int-to-string? middleware))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest unknown-caller-key-never-reaches-the-qp-test
+ (testing "GHY-4313: a top-level key MCP does not pass through is dropped before the QP sees the query"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ handle (stored-handle! sid (pk-ordered-orders-query {:evil "x"}))
+ captured (capture-qp-query! {:query_handle handle})]
+ (is (not (contains? captured :evil)))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest unknown-caller-key-rejected-on-the-fresh-path-test
+ (testing "GHY-4313: an unknown top-level key on a fresh `query` is rejected outright, not silently accepted"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-current-user (mt/user->id :rasta)
+ (is (str/includes? (error-text (call! (str (random-uuid))
+ {:query (assoc (numeric-orders-query {:limit 1}) :evil "x")}))
+ ":evil"))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest query-shape-still-reaches-the-qp-test
+ (testing "GHY-4313: the query itself survives the whitelist — the QP runs what the caller asked for"
+ (let [captured (capture-qp-query! {:query (numeric-orders-query {:limit 1})})]
+ (is (= :mbql/query (:lib/type captured)))
+ (is (= (mt/id) (:database captured)))
+ (is (= 1 (count (:stages captured))))
+ (is (= (mt/id :orders) (get-in captured [:stages 0 :source-table])))
+ (is (= 1 (get-in captured [:stages 0 :limit]))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest stored-parameters-still-reach-the-qp-test
+ (testing "GHY-4313: a stored query's :parameters survive the whitelist — bound values ride the handle"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ params [{:type "number/=" :target ["variable" ["template-tag" "n"]] :value 1}]
+ handle (stored-handle! sid (pk-ordered-orders-query {:parameters params}))]
+ (is (= params (:parameters (capture-qp-query! {:query_handle handle}))))))))
diff --git a/test/metabase/mcp/v2/tools/question_test.clj b/test/metabase/mcp/v2/tools/question_test.clj
new file mode 100644
index 00000000000..b2589f54460
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/question_test.clj
@@ -0,0 +1,1013 @@
+(ns metabase.mcp.v2.tools.question-test
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.api.common :as api]
+ [metabase.api.macros.scope :as scope]
+ [metabase.collections.models.collection :as collection]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.tools.question :as v2.question]
+ [metabase.permissions.core :as perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.queries.core :as queries]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(comment v2.question/keep-me)
+
+(defn- call-tool
+ "Dispatch a v2 tool and hand back the MCP content, whether the handler produced it or the
+ registry refused before dispatch. [[registry/call-tool]] returns `{:result …}` or `{:error …}`;
+ a registry refusal is an error the caller sees as a failed tool call just the same, so it is
+ rendered into the same `{:isError true :content …}` shape the assertions here read."
+ [scopes session-id tool-name args]
+ (let [{:keys [result error]} (registry/call-tool scopes session-id tool-name args)]
+ (or result
+ {:isError true
+ :content [{:type "text" :text (:message error)}]})))
+
+(defn- orders-query
+ "A Lib query over ORDERS — a runnable `:dataset_query` for fixtures that only need the card to
+ have one."
+ []
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id :orders)))))
+
+(deftest resolve-query-source-exactly-one-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "zero sources is a teaching error"
+ (is (thrown-with-msg? Exception #"exactly one"
+ (#'v2.question/resolve-query-source {} nil nil))))
+ (testing "two sources is a teaching error"
+ (is (thrown-with-msg? Exception #"exactly one"
+ (#'v2.question/resolve-query-source
+ {:query {:database (mt/id) :stages [{}]}
+ :native {:database_id (mt/id) :sql "SELECT 1"}} nil nil))))
+ (testing "native builds a native dataset_query"
+ (let [q (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id) :sql "SELECT 1"}} nil nil)]
+ (is (=? {:stages [{:lib/type :mbql.stage/native :native "SELECT 1"}]} q))))))
+
+(defn- tag-by-name
+ "Template tags are stored on the pMBQL stage as a vector (not a map keyed by name — see
+ `metabase.lib.schema.template-tag/template-tags`), so tests look up by `:name`."
+ [q tag-name]
+ (some #(when (= tag-name (:name %)) %) (get-in q [:stages 0 :template-tags])))
+
+(deftest template-tag-field-id-is-numeric-only-test
+ (testing "a dimension tag's `field_id` takes a numeric field id and nothing else. The docs used to advertise a
+ 21-char entity_id too, but `metabase_field.entity_id` was dropped by migration and `:model/Field`
+ is not in the eid-translation map, so a string could only ever fail — as a sanitized \"Internal
+ error\", for an input the published inputSchema said was valid."
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "create" :name "Tag probe"
+ :native {:database_id (mt/id)
+ :sql "SELECT * FROM VENUES WHERE PRICE = {{d}}"
+ :template_tags {"d" {:type "dimension" :widget_type "number/="
+ :field_id "AbCdEfGhIjKlMnOpQrStU"}}}})
+ text (-> result :content first :text)]
+ (is (:isError result))
+ (is (not (re-find #"(?i)internal error" text))
+ "the schema rejects it with a teaching error rather than failing deep in the insert")))))
+
+(deftest native-template-tags-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "a supplied tag not present in the SQL is a teaching error"
+ (is (thrown-with-msg? Exception #"\{\{missing\}\}"
+ (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT 1"
+ :template_tags {"missing" {:type "number"}}}} nil nil))))
+ (testing "a typed tag present in the SQL is applied"
+ (let [q (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE total > {{min_total}}"
+ :template_tags {"min_total" {:type "number"}}}} nil nil)]
+ (is (= :number (:type (tag-by-name q "min_total"))))))
+ (testing "a dimension tag without a widget_type is a teaching error"
+ (is (thrown-with-msg? Exception #"dimension template tag requires a widget_type"
+ (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE {{d}}"
+ :template_tags {"d" {:type "dimension"
+ :field_id (mt/id :orders :total)}}}} nil nil))))
+ (testing "a dimension tag with a field_id and widget type is applied"
+ (let [field-id (mt/id :orders :total)
+ q (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE {{d}}"
+ :template_tags {"d" {:type "dimension"
+ :field_id field-id
+ :widget_type "number/="}}}} nil nil)]
+ (is (=? {:type :dimension
+ :widget-type :number/=
+ :dimension [:field {} field-id]}
+ (tag-by-name q "d")))))))
+
+(deftest native-template-tags-teaching-errors-carry-the-contract-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "a dimension tag without a field_id names field_id and embeds the tag shape"
+ (is (thrown-with-msg? Exception #"(?s)requires a field_id.*template_tags is a map keyed by \{\{tag\}\} name"
+ (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE {{d}}"
+ :template_tags {"d" {:type "dimension"
+ :widget_type "number/="}}}} nil nil))))
+ (testing "an unknown tag type names the valid types and embeds the tag shape"
+ (is (thrown-with-msg? Exception #"(?s)temporal-unit.*learn\(\"native-parameters\"\)"
+ (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE {{d}}"
+ :template_tags {"d" {:type "widget"}}}} nil nil))))))
+
+(deftest native-template-tags-more-kinds-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "a boolean raw variable is applied"
+ (let [q (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT 1 WHERE {{flag}}"
+ :template_tags {"flag" {:type "boolean"}}}} nil nil)]
+ (is (= :boolean (:type (tag-by-name q "flag"))))))
+ (testing "a temporal-unit tag takes a field_id and no widget_type"
+ (let [field-id (mt/id :orders :created_at)
+ q (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE {{unit}}"
+ :template_tags {"unit" {:type "temporal-unit" :field_id field-id}}}} nil nil)]
+ (is (=? {:type :temporal-unit :dimension [:field {} field-id]}
+ (tag-by-name q "unit")))))))
+
+(deftest native-template-tags-read-shape-round-trip-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "the kebab-case shape get_content emits — display-name, widget-type, a legacy dimension ref — is accepted verbatim"
+ (let [field-id (mt/id :orders :total)
+ q (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE {{d}}"
+ :template_tags {"d" {:type "dimension"
+ :id "0f8266e0-5df9-4b95-a6d9-fea1e4a4c3ff"
+ :name "d"
+ (keyword "display-name") "Total"
+ (keyword "widget-type") "number/="
+ :dimension ["field" field-id nil]}}}} nil nil)]
+ (is (=? {:type :dimension
+ :display-name "Total"
+ :widget-type :number/=
+ :dimension [:field {} field-id]}
+ (tag-by-name q "d")))))
+ (testing "reference tags — a snippet as get_content emits it — are accepted and ignored, so a card using one round-trips"
+ (let [q (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE {{min}} > 0 AND {{snippet: base}}"
+ :template_tags {"min" {:type "number" :display_name "Min"}
+ (keyword "snippet: base") {:type "snippet"
+ :name "snippet: base"
+ (keyword "snippet-name") "base"
+ (keyword "display-name") "Snippet: base"}}}} nil nil)]
+ (is (= :number (:type (tag-by-name q "min"))))
+ (is (= :snippet (:type (tag-by-name q "snippet: base"))))))
+ (testing "an MBQL 5 dimension ref (options second, id third) also yields the field"
+ (let [field-id (mt/id :orders :total)
+ q (#'v2.question/resolve-query-source
+ {:native {:database_id (mt/id)
+ :sql "SELECT * FROM orders WHERE {{d}}"
+ :template_tags {"d" {:type "dimension"
+ (keyword "widget-type") "number/="
+ :dimension ["field" {} field-id]}}}} nil nil)]
+ (is (=? {:dimension [:field {} field-id]}
+ (tag-by-name q "d")))))))
+
+(deftest create-question-happy-path-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [args {:method "create"
+ :name "Agent Q"
+ :query {:database (mt/id)
+ :stages [{:source-table (mt/id :orders)}]}}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write" args)]
+ (is (not (:isError result)) (-> result :content first :text))
+ (let [card-id (:id (:structuredContent result))]
+ (is (int? card-id))
+ (is (= "Agent Q" (t2/select-one-fn :name :model/Card :id card-id)))
+ (is (= :question (t2/select-one-fn :type :model/Card :id card-id))))))))
+
+(defn- mint-handle-via-execute!
+ "Mint a query_handle for `query` the way `execute_query` does — straight into the handle store,
+ reproducing the exact round-trip (pMBQL → JSON → string-valued map) the save path must survive.
+ Deferred-tests ledger: `execute_query` itself lands in the query PR (GHY-4363); when it does,
+ route this through `registry/call-tool` with `:validate_only true` so the whole tool path is
+ exercised, not just the store."
+ [session-id query]
+ ;; a real minted handle always carries :database — the execute pipeline guarantees it
+ (v2.queries/mint-query-handle! session-id api/*current-user-id*
+ (v2.queries/encode-serialized-query
+ (merge {:database (mt/id)} query))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest create-question-via-query-handle-test
+ (mt/with-model-cleanup [:model/Card :model/McpQueryHandle]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [sid (str (random-uuid))
+ handle (mint-handle-via-execute!
+ sid
+ {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :orders)
+ :aggregation [["count" {}]]
+ :breakout [["field" {:temporal-unit "month"}
+ (mt/id :orders :created_at)]]}]})
+ result (call-tool #{"agent:content:write"} sid "question_write"
+ {:method "create" :name "From Handle" :query_handle handle})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (let [card-id (:id (:structuredContent result))]
+ (is (int? card-id))
+ (is (=? {:lib/type :mbql/query
+ :stages [{:lib/type :mbql.stage/mbql
+ :aggregation [[:count {}]]}]}
+ (t2/select-one-fn :dataset_query :model/Card :id card-id))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest create-question-via-native-query-handle-test
+ (mt/with-model-cleanup [:model/Card :model/McpQueryHandle]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "a native handle — the shape execute_sql mints — is gated exactly like the native
+ source. A handle is not proof the SQL gates were spent: `construct_native_query`
+ mints under agent:sql:construct and never consults the kill switch, and a handle
+ resolves on core_session.user_id, so any credential of that user can spend one
+ minted by any other."
+ (let [mp (mt/metadata-provider)
+ mint! (fn [sid]
+ (v2.queries/mint-query-handle!
+ sid (mt/user->id :crowberto)
+ (v2.queries/encode-serialized-query
+ (lib/prepare-for-serialization (lib/native-query mp "SELECT 1")))))]
+ (testing "the content write scope alone is refused, and nothing is written"
+ (let [sid (str (random-uuid))
+ result (call-tool #{"agent:content:write"} sid "question_write"
+ {:method "create" :name "From SQL Handle"
+ :query_handle (mint! sid)})]
+ (is (:isError result))
+ (is (str/includes? (-> result :content first :text) "agent:sql:run"))
+ (is (zero? (t2/count :model/Card :name "From SQL Handle")))))
+ (testing "with agent:sql:run it saves, and the native query round-trips"
+ (let [sid (str (random-uuid))
+ result (call-tool #{"agent:content:write" "agent:sql:run"} sid "question_write"
+ {:method "create" :name "From SQL Handle" :query_handle (mint! sid)})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (=? {:stages [{:lib/type :mbql.stage/native :native "SELECT 1"}]}
+ (t2/select-one-fn :dataset_query :model/Card
+ :id (:id (:structuredContent result)))))))
+ (testing "the kill switch covers the handle route too"
+ (mt/with-temporary-setting-values [mcp-execute-sql-enabled false]
+ (let [sid (str (random-uuid))
+ result (call-tool #{"agent:content:write" "agent:sql:run"} sid "question_write"
+ {:method "create" :name "Killed Handle Q" :query_handle (mint! sid)})]
+ (is (:isError result))
+ (is (str/includes? (-> result :content first :text) "mcp-execute-sql-enabled"))
+ (is (zero? (t2/count :model/Card :name "Killed Handle Q")))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest update-via-native-query-handle-is-gated-test
+ (testing "the update path stores the resolved query the same way create does, so a native handle
+ must pass the same two gates there — otherwise swapping a question's query is a second
+ route to storing raw SQL without them"
+ (mt/with-model-cleanup [:model/Card :model/McpQueryHandle]
+ (mt/with-temp [:model/Card {card-id :id} {:dataset_query (orders-query)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [mp (mt/metadata-provider)
+ mint! (fn [sid]
+ (v2.queries/mint-query-handle!
+ sid (mt/user->id :crowberto)
+ (v2.queries/encode-serialized-query
+ (lib/prepare-for-serialization (lib/native-query mp "SELECT 1")))))]
+ (testing "refused on the content write scope alone, and the stored query is untouched"
+ (let [sid (str (random-uuid))
+ result (call-tool #{"agent:content:write"} sid "question_write"
+ {:method "update" :id card-id :query_handle (mint! sid)})]
+ (is (:isError result))
+ (is (str/includes? (-> result :content first :text) "agent:sql:run"))
+ (is (not= :mbql.stage/native
+ (get-in (t2/select-one-fn :dataset_query :model/Card :id card-id)
+ [:stages 0 :lib/type])))))
+ (testing "allowed with agent:sql:run"
+ (let [sid (str (random-uuid))
+ result (call-tool #{"agent:content:write" "agent:sql:run"} sid "question_write"
+ {:method "update" :id card-id :query_handle (mint! sid)})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (=? {:stages [{:lib/type :mbql.stage/native :native "SELECT 1"}]}
+ (t2/select-one-fn :dataset_query :model/Card :id card-id)))))))))))
+
+(deftest create-question-name-required-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [result (call-tool #{"agent:content:write"} nil "question_write"
+ {:method "create" :query {:database (mt/id) :stages [{}]}})]
+ (is (:isError result))
+ (is (re-find #"`name` is required" (-> result :content first :text))))))
+
+(deftest create-question-collection-target-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [base-args {:method "create"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}}]
+ (testing "collection_id: \"root\" saves to the root collection"
+ (let [result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write"
+ (assoc base-args :name "Agent Q root" :collection_id "root"))]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (nil? (t2/select-one-fn :collection_id :model/Card
+ :id (:id (:structuredContent result)))))))
+ (testing "omitted collection_id saves to the caller's personal collection"
+ (let [personal-id (:id (collection/user->personal-collection (mt/user->id :crowberto)))
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write"
+ (assoc base-args :name "Agent Q personal"))]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= personal-id (t2/select-one-fn :collection_id :model/Card
+ :id (:id (:structuredContent result)))))))))))
+
+(defn- create-model-result-metadata
+ "Create a model card via the tool with `extra-args` merged in, returning its persisted
+ `result_metadata`."
+ [extra-args]
+ (let [base-args {:method "create" :card_type "model"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write"
+ (merge base-args extra-args))]
+ (is (not (:isError result)) (-> result :content first :text))
+ (t2/select-one-fn :result_metadata :model/Card :id (:id (:structuredContent result)))))
+
+(deftest create-model-with-column-metadata-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [baseline (create-model-result-metadata {:name "Agent Model Baseline"})
+ result-metadata (create-model-result-metadata
+ {:name "Agent Model"
+ :column_metadata [{:name "TOTAL" :display_name "Total $" :semantic_type "type/Currency"}]})
+ by-name (into {} (map (juxt :name identity)) result-metadata)]
+ (testing "every query column is present, not just the annotated one"
+ (is (= (count baseline) (count result-metadata))))
+ (testing "the annotated column carries the override plus its real (non-fake) base_type"
+ (is (=? {:display_name "Total $" :semantic_type :type/Currency :base_type :type/Float}
+ (get by-name "TOTAL"))))
+ (testing "a non-annotated column is still present with its real base_type"
+ (is (=? {:base_type :type/BigInteger}
+ (get by-name "ID"))))))))
+
+(deftest create-model-with-unknown-column-metadata-name-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [args {:method "create"
+ :card_type "model"
+ :name "Agent Model Bad Column"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}
+ :column_metadata [{:name "NOT_A_REAL_COLUMN" :display_name "whoops"}]}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write" args)]
+ (is (:isError result))
+ (is (re-find #"\"NOT_A_REAL_COLUMN\" is not in the query results"
+ (-> result :content first :text))))))
+
+(deftest create-native-model-with-column-metadata-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "column_metadata on a native-source model is a teaching error, not a bogus \"not in results\" error"
+ (let [args {:method "create"
+ :card_type "model"
+ :name "Native Model With CM"
+ :native {:database_id (mt/id) :sql "SELECT * FROM orders"}
+ :column_metadata [{:name "TOTAL" :display_name "Total $"}]}
+ result (call-tool #{"agent:content:write" "agent:sql:run"} (str (random-uuid))
+ "question_write" args)]
+ (is (:isError result))
+ (is (re-find #"column_metadata isn't supported for models built from a native \(SQL\) query"
+ (-> result :content first :text)))))
+ (testing "a native-source model without column_metadata still creates fine"
+ (let [args {:method "create"
+ :card_type "model"
+ :name "Native Model No CM"
+ :native {:database_id (mt/id) :sql "SELECT * FROM orders"}}
+ result (call-tool #{"agent:content:write" "agent:sql:run"} (str (random-uuid))
+ "question_write" args)]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= :model (t2/select-one-fn :type :model/Card :id (:id (:structuredContent result))))))))))
+
+(deftest create-dashboard-question-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Dashboard dash {:collection_id nil}]
+ (let [args {:method "create"
+ :name "Dash Q"
+ :dashboard_id (:id dash)
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write" args)]
+ (is (not (:isError result)) (-> result :content first :text))
+ (let [card-id (:id (:structuredContent result))]
+ (is (= (:id dash) (t2/select-one-fn :dashboard_id :model/Card :id card-id)))))))))
+
+(deftest create-dashboard-question-model-type-rejected-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Dashboard dash {:collection_id nil}]
+ (let [args {:method "create"
+ :card_type "model"
+ :name "Dash Model"
+ :dashboard_id (:id dash)
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write" args)]
+ (is (:isError result))
+ (is (re-find #"Invalid dashboard-internal card" (-> result :content first :text)))))))
+
+(deftest create-dashboard-question-collection-id-exclusivity-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Dashboard dash {:collection_id nil}
+ :model/Collection coll {}]
+ (let [args {:method "create"
+ :name "Dash Q Both"
+ :dashboard_id (:id dash)
+ :collection_id (:id coll)
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write" args)]
+ (is (:isError result))
+ (is (re-find #"Pass either collection_id or dashboard_id, not both"
+ (-> result :content first :text)))))))
+
+(deftest create-dashboard-question-nonexistent-numeric-id-test
+ (testing "a numeric dashboard_id with no matching row is a clean not-found, not a raw FK
+ violation surfacing as an internal error (GHY-4352)"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [args {:method "create"
+ :name "Dash Q Bad Numeric Id"
+ :dashboard_id 999999999
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write" args)]
+ (is (:isError result))
+ (is (re-find #"Dashboard 999999999 not found"
+ (-> result :content first :text)))))))
+
+(deftest create-dashboard-question-existence-does-not-leak-test
+ (testing "GHY-4443: a dashboard the caller cannot read and a dashboard that does not exist must be
+ indistinguishable. Reading the row without a read check and letting the later write check
+ answer makes the first a 403 and the second a 404, which is an existence oracle: a token
+ scoped to one collection could enumerate every dashboard id on the instance."
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Dashboard {dash-id :id} {:collection_id coll-id}]
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-id)
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [args-for (fn [dashboard-id]
+ {:method "create"
+ :name "Existence probe"
+ :dashboard_id dashboard-id
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}})
+ unreadable (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write"
+ (args-for dash-id))
+ missing (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write"
+ (args-for 999999999))]
+ (is (:isError unreadable))
+ (is (:isError missing))
+ (is (= (str/replace (-> missing :content first :text) #"999999999" "<id>")
+ (str/replace (-> unreadable :content first :text) (re-pattern (str dash-id)) "<id>"))
+ "the refusal for an unreadable dashboard must read exactly like the one for a missing dashboard"))))))
+
+;;; ------------------------------------------------------ Update --------------------------------------------------
+
+(deftest update-question-rename-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Card card {:name "Before" :dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card) :description "new desc"})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= "new desc" (t2/select-one-fn :description :model/Card :id (:id card))))))))
+
+(deftest write-echoes-visualization-settings-test
+ (testing "GHY-4511: question_write echoes visualization_settings, so a chart write is
+ verifiable from its own response instead of a second get_content"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "an update that sets them"
+ (mt/with-temp [:model/Card card {:name "Chart" :display :line :dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card)
+ :visualization_settings {"graph.show_goal" true
+ "graph.goal_value" 50000}})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= {:graph.show_goal true :graph.goal_value 50000}
+ (:visualization_settings (:structuredContent result)))))))
+ (testing "and an update that leaves them alone still reports what is stored"
+ (mt/with-temp [:model/Card card {:name "Chart"
+ :display :line
+ :dataset_query (orders-query)
+ :visualization_settings {"graph.goal_value" 10}}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card) :description "d"})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= {:graph.goal_value 10}
+ (:visualization_settings (:structuredContent result)))))))
+ (testing "a card with nothing stored echoes {}"
+ (mt/with-model-cleanup [:model/Card]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "create" :name "Plain"
+ :query {:database (mt/id)
+ :stages [{:source-table (mt/id :orders)}]}})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= {} (:visualization_settings (:structuredContent result))))))))))
+
+(deftest ^:parallel semantic-type-accepts-relation-types-test
+ (testing "type/PK and type/FK are relation types (not Semantic/*), accepted by the column schema and named
+ in the tool's own examples, so the check must let them through"
+ (is (= :type/PK (#'v2.question/check-semantic-type! "type/PK")))
+ (is (= :type/FK (#'v2.question/check-semantic-type! "type/FK")))
+ (is (= :type/Currency (#'v2.question/check-semantic-type! "type/Currency")))
+ (is (thrown-with-msg? Exception #"Invalid semantic_type" (#'v2.question/check-semantic-type! "type/Nope")))))
+
+(deftest update-by-entity-id-test
+ (testing "an update addressed by the card's 21-character entity_id resolves to the numeric id everywhere
+ downstream — the save-cycle graph and the readback select, not just the write check"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Card card {:name "By eid" :dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update"
+ :id (:entity_id card)
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}
+ :name "By eid, renamed"})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= (:id card) (:id (:structuredContent result))))
+ (is (= "By eid, renamed" (t2/select-one-fn :name :model/Card :id (:id card)))))))))
+
+(deftest update-checks-permissions-before-inferring-metadata-test
+ (testing "on update, result-metadata inference (whose teaching errors name the columns it found) runs only
+ after the permission check on the new query — otherwise a caller could learn the columns of a
+ table they cannot run, one guessed column_metadata name at a time"
+ (mt/with-temp [:model/Card card {:name "Mine" :creator_id (mt/user->id :rasta) :dataset_query (orders-query)}]
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update"
+ :id (:id card)
+ ;; a different table than the stored query's, so this is a query
+ ;; modification and the run-permission check applies to it
+ :query {:database (mt/id) :stages [{:source-table (mt/id :venues)}]}
+ :column_metadata [{:name "NOT_A_COLUMN" :description "guess"}]})
+ text (-> result :content first :text)]
+ (is (:isError result))
+ (is (not (re-find #"not in the query results" text))
+ "the column-name teaching error must not be reachable without run permission on the query")))))))
+
+(deftest update-column-metadata-only-checks-run-permission-test
+ (testing "GHY-4352: a column_metadata-only update still infers result metadata over the *stored* query, so
+ it must check run permission on that query. `check-allowed-to-update-card!` checks the query
+ only when the query itself changes, so with no `query` in the patch nothing checks it, and the
+ inference teaching error names the query's real columns to a caller who cannot run it."
+ (mt/with-temp [:model/Card card {:name "Mine" :creator_id (mt/user->id :rasta) :dataset_query (orders-query)}]
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update"
+ :id (:id card)
+ :column_metadata [{:name "NOT_A_COLUMN" :description "guess"}]})
+ text (-> result :content first :text)]
+ (is (:isError result))
+ (is (not (re-find #"not in the query results" text))
+ "the column-name teaching error must not be reachable without run permission on the query")))))))
+
+(deftest update-column-metadata-only-writes-nothing-without-run-permission-test
+ (testing "GHY-4352: the same update with a column name that really is in the query is refused too, and
+ writes no result_metadata — run permission on the query is what REST checks before accepting
+ result_metadata, and annotating a card is not a way around it."
+ (mt/with-temp [:model/Card card {:name "Mine" :creator_id (mt/user->id :rasta) :dataset_query (orders-query)}]
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-current-user (mt/user->id :rasta)
+ (is (:isError (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update"
+ :id (:id card)
+ :column_metadata [{:name "TOTAL" :description "the total"}]})))))
+ ;; the card is born with inferred result_metadata (the model's insert hook populates it), so the
+ ;; assertion is that the caller's annotation never landed, not that the column is empty.
+ (is (not-any? #(= "the total" (:description %))
+ (t2/select-one-fn :result_metadata :model/Card :id (:id card)))
+ "a refused update leaves the card's stored column annotations untouched"))))
+
+(deftest update-retype-to-model-normalizes-display-test
+ (testing "retyping a question to a model forces `display` to table, as `PUT /api/card/:id` does
+ (see `model-card-test` in the card REST suite). Not cosmetic: the query processor
+ branches on `(= :pivot (:display card))` to run the pivot QP, so a pivot question
+ retyped to a model would keep returning pivoted data. The model editor only ever offers
+ table and list, so a chart display on a model is unreachable through the app."
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "a chart display is normalized away"
+ (mt/with-temp [:model/Card {card-id :id} {:display :bar :dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :card_type "model"})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= :table (t2/select-one-fn :display :model/Card :id card-id))))))
+ (testing "pivot — the display that changes what the query processor returns"
+ (mt/with-temp [:model/Card {card-id :id} {:display :pivot :dataset_query (orders-query)}]
+ (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :card_type "model"})
+ (is (= :table (t2/select-one-fn :display :model/Card :id card-id)))))
+ (testing "a display passed in the same call is normalized too, as REST does. (REST leaves an
+ explicit `list` alone, but this tool's display enum has no `list`, so that carve-out
+ is unreachable here — the schema refuses it before the handler runs.)"
+ (mt/with-temp [:model/Card {card-id :id} {:display :bar :dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :card_type "model" :display "line"})]
+ (is (not (:isError result)) (-> result :content first :text)))
+ (is (= :table (t2/select-one-fn :display :model/Card :id card-id))))
+ (mt/with-temp [:model/Card {card-id :id} {:display :bar :dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :card_type "model" :display "list"})]
+ (is (not (:isError result)) (-> result :content first :text)))
+ (is (= :list (t2/select-one-fn :display :model/Card :id card-id))
+ "an explicit list survives the normalization — the model list view is a real choice")))
+ (testing "a model can be created directly in the list view"
+ (mt/with-model-cleanup [:model/Card]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "create" :name "List model" :card_type "model"
+ :display "list"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= :list (t2/select-one-fn :display :model/Card
+ :id (:id (:structuredContent result))))))))
+ (testing "a card that stays a question keeps its display"
+ (mt/with-temp [:model/Card {card-id :id} {:display :bar :dataset_query (orders-query)}]
+ (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :name "renamed"})
+ (is (= :bar (t2/select-one-fn :display :model/Card :id card-id))))))))
+
+(deftest update-archive-restore-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Card card {:archived false :dataset_query (orders-query)}]
+ (let [archive-result (call-tool #{::scope/unrestricted} nil "question_write" {:method "update" :id (:id card) :archived true})]
+ (is (not (:isError archive-result)) (-> archive-result :content first :text)))
+ (is (true? (t2/select-one-fn :archived :model/Card :id (:id card))))
+ (let [restore-result (call-tool #{::scope/unrestricted} nil "question_write" {:method "update" :id (:id card) :archived false})]
+ (is (not (:isError restore-result)) (-> restore-result :content first :text)))
+ (is (false? (t2/select-one-fn :archived :model/Card :id (:id card)))))))
+
+(deftest update-not-found-collapses-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [result (call-tool #{::scope/unrestricted} nil "question_write"
+ {:method "update" :id 999999999 :name "x"})]
+ (is (:isError result))
+ (is (re-find #"not found" (-> result :content first :text))))))
+
+(deftest update-question-swap-query-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Card card {:dataset_query (orders-query)}]
+ (let [new-query {:database (mt/id) :stages [{:source-table (mt/id :products)}]}
+ result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card) :query new-query})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (=? {:stages [{:source-table (mt/id :products)}]}
+ (t2/select-one-fn :dataset_query :model/Card :id (:id card))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest update-question-swap-query-via-query-handle-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Card card {:dataset_query (orders-query)}]
+ (let [sid (str (random-uuid))
+ handle (mint-handle-via-execute!
+ sid
+ {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :products)}]})
+ result (call-tool #{::scope/unrestricted} sid "question_write"
+ {:method "update" :id (:id card) :query_handle handle})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (=? {:stages [{:source-table (mt/id :products)}]}
+ (t2/select-one-fn :dataset_query :model/Card :id (:id card)))))))))
+
+(deftest update-model-column-metadata-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [baseline (create-model-result-metadata {:name "Update Model Baseline"})
+ create-result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write"
+ {:method "create" :card_type "model"
+ :name "Update Model"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}})
+ card-id (:id (:structuredContent create-result))
+ update-result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id
+ :column_metadata [{:name "TOTAL" :display_name "Total $"
+ :semantic_type "type/Currency"}]})
+ result-metadata (t2/select-one-fn :result_metadata :model/Card :id card-id)
+ by-name (into {} (map (juxt :name identity)) result-metadata)]
+ (is (not (:isError update-result)) (-> update-result :content first :text))
+ (testing "every query column is still present, not just the annotated one"
+ (is (= (count baseline) (count result-metadata))))
+ (testing "the annotated column carries the override plus its real (non-fake) base_type"
+ (is (=? {:display_name "Total $" :semantic_type :type/Currency :base_type :type/Float}
+ (get by-name "TOTAL"))))
+ (testing "a non-annotated column is still present with its real base_type, unmodified"
+ (is (=? {:base_type :type/BigInteger}
+ (get by-name "ID"))))))))
+
+(deftest update-model-column-metadata-preserves-prior-overrides-test
+ (testing "a second partial column_metadata update keeps overrides set by an earlier one (GHY-4145)"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [create-result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write"
+ {:method "create" :card_type "model"
+ :name "Iteratively Annotated Model"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}})
+ card-id (:id (:structuredContent create-result))
+ annotate! (fn [column_metadata]
+ (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :column_metadata column_metadata}))]
+ ;; first annotate TOTAL, then — in a separate call that never mentions TOTAL — annotate ID
+ (is (not (:isError (annotate! [{:name "TOTAL" :display_name "Total $" :semantic_type "type/Currency"}]))))
+ (is (not (:isError (annotate! [{:name "ID" :display_name "Order ID"}]))))
+ (let [by-name (into {} (map (juxt :name identity))
+ (t2/select-one-fn :result_metadata :model/Card :id card-id))]
+ (testing "the newly annotated column carries its override"
+ (is (=? {:display_name "Order ID"} (get by-name "ID"))))
+ (testing "the earlier override survives the second update rather than being wiped"
+ (is (=? {:display_name "Total $" :semantic_type :type/Currency}
+ (get by-name "TOTAL"))))))))))
+
+(deftest update-model-column-metadata-explicit-null-clears-override-test
+ (testing "an explicit null semantic_type clears a previously-set override, not just an omitted key (GHY-4352)"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [create-result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write"
+ {:method "create" :card_type "model"
+ :name "Clearable Override Model"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}
+ :column_metadata [{:name "TOTAL" :semantic_type "type/Currency"}]})
+ card-id (:id (:structuredContent create-result))
+ clear-result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id
+ :column_metadata [{:name "TOTAL" :semantic_type nil}]})]
+ (is (not (:isError clear-result)) (-> clear-result :content first :text))
+ (let [by-name (into {} (map (juxt :name identity))
+ (t2/select-one-fn :result_metadata :model/Card :id card-id))]
+ (is (nil? (:semantic_type (get by-name "TOTAL"))))))))))
+
+(deftest create-model-column-metadata-invalid-semantic-type-test
+ (testing "an unrecognized semantic_type is a teaching error, not a sanitized internal error (GHY-4352)"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [args {:method "create" :card_type "model"
+ :name "Bad Semantic Type Model"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}
+ :column_metadata [{:name "TOTAL" :semantic_type "Currency"}]}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write" args)]
+ (is (:isError result))
+ (is (re-find #"Invalid semantic_type \"Currency\""
+ (-> result :content first :text)))))))
+
+(deftest create-model-column-metadata-invalid-visibility-type-test
+ (testing "an out-of-enum visibility_type is rejected at the args schema"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [args {:method "create" :card_type "model"
+ :name "Bad Visibility Type Model"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}
+ :column_metadata [{:name "TOTAL" :visibility_type "bogus"}]}
+ result (call-tool #{"agent:content:write"} (str (random-uuid)) "question_write" args)]
+ (is (:isError result))
+ (is (re-find #"visibility_type"
+ (-> result :content first :text)))))))
+
+(deftest update-move-question-into-dashboard-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection dash-coll {}
+ :model/Dashboard dash {:collection_id (:id dash-coll)}
+ :model/Card card {:dataset_query (orders-query) :collection_id nil}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card) :dashboard_id (:id dash)})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (= (:id dash) (t2/select-one-fn :dashboard_id :model/Card :id (:id card))))
+ (testing "the card's collection follows the dashboard's, matching create"
+ (is (= (:id dash-coll) (t2/select-one-fn :collection_id :model/Card :id (:id card))))))))))
+
+(deftest update-move-archived-question-into-dashboard-force-restores-test
+ (testing "moving an already-archived card into a dashboard force-restores it, matching REST (GHY-4352)"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection dash-coll {}
+ :model/Dashboard dash {:collection_id (:id dash-coll)}
+ :model/Card card {:archived true :archived_directly true :dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card) :dashboard_id (:id dash)})]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (=? {:archived false
+ :archived_directly false
+ :dashboard_id (:id dash)
+ :collection_id (:id dash-coll)}
+ (t2/select-one [:model/Card :archived :archived_directly :dashboard_id :collection_id] :id (:id card))))))))))
+
+(deftest update-move-into-dashboard-while-archiving-refused-test
+ (testing "archived:true and dashboard_id together are refused rather than persisting a card
+ that's simultaneously trashed and a dashboard's internal question (GHY-4352)"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection dash-coll {}
+ :model/Dashboard dash {:collection_id (:id dash-coll)}
+ :model/Card card {:archived false :dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card) :dashboard_id (:id dash) :archived true})]
+ (is (:isError result))
+ (is (re-find #"Can't move a card into a dashboard while also archiving it"
+ (-> result :content first :text)))
+ (testing "the card is untouched"
+ (is (=? {:archived false :dashboard_id nil}
+ (t2/select-one [:model/Card :archived :dashboard_id] :id (:id card))))))))))
+
+(deftest update-nonexistent-numeric-dashboard-id-test
+ (testing "a numeric dashboard_id with no matching row is a clean not-found on update too (GHY-4352)"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Card card {:dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card) :dashboard_id 999999999})]
+ (is (:isError result))
+ (is (re-find #"Dashboard 999999999 not found"
+ (-> result :content first :text)))
+ (testing "the card is untouched"
+ (is (nil? (t2/select-one-fn :dashboard_id :model/Card :id (:id card))))))))))
+
+(deftest update-dashboard-id-collection-exclusivity-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Dashboard dash {:collection_id nil}
+ :model/Collection coll {}
+ :model/Card card {:dataset_query (orders-query)}]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card)
+ :dashboard_id (:id dash) :collection_id (:id coll)})]
+ (is (:isError result))
+ (is (re-find #"Pass either collection_id or dashboard_id, not both"
+ (-> result :content first :text)))
+ (testing "the card is untouched"
+ (is (nil? (t2/select-one-fn :dashboard_id :model/Card :id (:id card)))))))))
+
+(deftest update-move-into-dashboard-requires-destination-write-test
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-temp [:model/Collection coll-a {}
+ :model/Collection coll-b {}
+ :model/Dashboard dash-b {:collection_id (:id coll-b)}
+ :model/Card card {:dataset_query (orders-query) :collection_id (:id coll-a)}]
+ ;; Read but not write on the destination: the caller can see the dashboard, so the read check
+ ;; in `resolve-dashboard!` passes and the *write* requirement on the dashboard's collection is
+ ;; what refuses — which is what this test exists to prove. Revoking read too would collapse the
+ ;; refusal into the not-found that
+ ;; `create-dashboard-question-existence-does-not-leak-test` covers, and this assertion would
+ ;; pass for the wrong reason.
+ (perms/revoke-collection-permissions! (perms-group/all-users) coll-b)
+ (perms/grant-collection-read-permissions! (perms-group/all-users) coll-b)
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id (:id card) :dashboard_id (:id dash-b)})]
+ (is (:isError result))
+ (is (re-find #"You don't have permissions to do that"
+ (-> result :content first :text)))
+ (testing "the card is untouched"
+ (is (nil? (t2/select-one-fn :dashboard_id :model/Card :id (:id card))))))))))
+
+;;; ---------------------------------------------- Card-type guard -------------------------------------------------
+
+(defn- count-metric-query
+ "A single-aggregation query over ORDERS — a valid `:dataset_query` for a `:metric` fixture."
+ []
+ (lib/aggregate (orders-query) (lib/count)))
+
+(deftest ^:parallel update-rejects-metric-card-test
+ (testing "GHY-4327: question_write refuses a card that isn't a question or model, so it can neither
+ retype a metric nor store a native query on one"
+ (mt/with-temp [:model/Card {card-id :id} {:type :metric
+ :name "question-test not a question"
+ :dataset_query (count-metric-query)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "a field update is refused, naming the card's type and the tool that owns it"
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :name "nope"})
+ msg (-> result :content first :text)]
+ (is (:isError result))
+ (is (str/includes? msg "metric_write"))
+ (is (str/includes? msg "metric"))))
+ (testing "a card_type that would retype the metric is refused, not honored"
+ (is (:isError (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :card_type "question"}))))
+ (testing "storing a native query on the metric is refused rather than corrupting it"
+ (is (:isError (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id
+ :native {:database_id (mt/id) :sql "SELECT 1"}}))))
+ (testing "the card is untouched"
+ (is (=? {:type :metric :name "question-test not a question"}
+ (t2/select-one [:model/Card :type :name] :id card-id))))))))
+
+;; not ^:parallel: with-redefs
+(deftest update-save-check-uses-the-stored-card-type-test
+ (testing "GHY-4327: the save check sees the stored card's type, not the caller's omitted card_type"
+ (mt/with-temp [:model/Card {card-id :id} {:type :model :dataset_query (orders-query)}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [seen (atom ::unset)
+ original queries/check-card-can-be-saved!]
+ (with-redefs [queries/check-card-can-be-saved! (fn [query card-type]
+ (reset! seen card-type)
+ (original query card-type))]
+ (let [result (call-tool #{::scope/unrestricted} (str (random-uuid)) "question_write"
+ {:method "update" :id card-id :name "renamed"})]
+ (is (not (:isError result)) (-> result :content first :text))))
+ (is (= :model @seen)))))))
+
+(deftest native-source-requires-the-sql-scope-test
+ (testing "an inline `native` source stores raw SQL that run_saved_question then executes, so it is
+ execute_sql's capability and needs execute_sql's own scope — the content write scope
+ alone would reproduce raw SQL for a token the operator never granted it to"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [write-only #{"agent:content:write"}
+ with-sql #{"agent:content:write" "agent:sql:run"}
+ create-args {:method "create" :name "Native Q"
+ :native {:database_id (mt/id) :sql "SELECT 1"}}]
+ (testing "create with only the write scope is refused, naming the missing scope"
+ (let [result (call-tool write-only (str (random-uuid)) "question_write" create-args)]
+ (is (:isError result))
+ (is (re-find #"agent:sql:run" (-> result :content first :text)))
+ (is (zero? (t2/count :model/Card :name "Native Q")))))
+ (testing "the identical call goes through once the token carries the SQL scope"
+ (let [result (call-tool with-sql (str (random-uuid)) "question_write" create-args)]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (=? {:stages [{:lib/type :mbql.stage/native :native "SELECT 1"}]}
+ (t2/select-one-fn :dataset_query :model/Card
+ :id (:id (:structuredContent result)))))))
+ (testing "update is gated too — swapping a stored MBQL query for SQL stores the same capability"
+ (mt/with-temp [:model/Card card {:dataset_query (orders-query)}]
+ (let [update-args {:method "update" :id (:id card)
+ :native {:database_id (mt/id) :sql "SELECT 2"}}
+ refused (call-tool write-only (str (random-uuid)) "question_write" update-args)]
+ (is (:isError refused))
+ (is (re-find #"agent:sql:run" (-> refused :content first :text)))
+ (is (=? {:stages [{:lib/type :mbql.stage/mbql}]}
+ (t2/select-one-fn :dataset_query :model/Card :id (:id card))))
+ (testing "and goes through with the SQL scope"
+ (let [ok (call-tool with-sql (str (random-uuid)) "question_write" update-args)]
+ (is (not (:isError ok)) (-> ok :content first :text))
+ (is (=? {:stages [{:lib/type :mbql.stage/native :native "SELECT 2"}]}
+ (t2/select-one-fn :dataset_query :model/Card :id (:id card))))))))))))))
+
+(deftest inline-query-with-a-native-stage-is-gated-like-the-native-source-test
+ (testing "an inline `query` carrying a native stage resolves to raw SQL just like the `native`
+ source, so it must pass the same execute_sql gates — otherwise the `query` source is a
+ back door around the scope + kill switch (GHY-4352 review)"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [write-only #{"agent:content:write"}
+ with-sql #{"agent:content:write" "agent:sql:run"}
+ ;; a native stage smuggled through the inline `query` arg rather than the `native` arg
+ native-inline {:method "create" :name "Backdoor Q"
+ :query {:database (mt/id)
+ :stages [{:native "SELECT 1"}]}}]
+ (testing "the write scope alone is refused, naming the missing SQL scope"
+ (let [result (call-tool write-only (str (random-uuid)) "question_write" native-inline)]
+ (is (:isError result))
+ (is (re-find #"agent:sql:run" (-> result :content first :text)))
+ (is (zero? (t2/count :model/Card :name "Backdoor Q")))))
+ (testing "the identical call goes through with the SQL scope, storing the native query"
+ (let [result (call-tool with-sql (str (random-uuid)) "question_write" native-inline)]
+ (is (not (:isError result)) (-> result :content first :text))
+ (is (=? {:stages [{:lib/type :mbql.stage/native :native "SELECT 1"}]}
+ (t2/select-one-fn :dataset_query :model/Card :id (:id (:structuredContent result)))))))
+ (testing "a plain inline MBQL query is unaffected — still creatable with the write scope only"
+ (let [result (call-tool write-only (str (random-uuid)) "question_write"
+ {:method "create" :name "Plain MBQL Q"
+ :query {:database (mt/id)
+ :stages [{:source-table (mt/id :orders)}]}})]
+ (is (not (:isError result)) (-> result :content first :text)))))))))
+
+;; not ^:parallel: mt/with-temporary-setting-values on the shared kill-switch setting
+(deftest native-source-honors-the-execute-sql-kill-switch-test
+ (testing "the mcp-execute-sql-enabled kill switch must cover every path that stores raw SQL, or
+ question_write plus run_saved_question rebuilds execute_sql on an instance where an
+ admin turned it off"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temporary-setting-values [mcp-execute-sql-enabled false]
+ (let [result (call-tool #{"agent:content:write" "agent:sql:run"} (str (random-uuid))
+ "question_write"
+ {:method "create" :name "Killed Native Q"
+ :native {:database_id (mt/id) :sql "SELECT 1"}})]
+ (is (:isError result))
+ (is (str/includes? (-> result :content first :text) "mcp-execute-sql-enabled"))
+ (is (zero? (t2/count :model/Card :name "Killed Native Q")))))))))
+
+(deftest write-response-respects-read-scope-test
+ (testing "GHY-4217: without agent:resource:read the response is a minimal ack — the write scope
+ must not double as a read scope"
+ (mt/with-model-cleanup [:model/Card]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [args {:method "create" :name "Ack Q"
+ :query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}}
+ acked (:structuredContent (call-tool #{"agent:content:write"}
+ (str (random-uuid)) "question_write" args))]
+ (is (pos-int? (:id acked)))
+ (is (re-find #"agent:content:read" (:note acked)))
+ (is (not (contains? acked :name)))
+ (testing "with the read scope the full response comes back"
+ (let [full (:structuredContent (call-tool #{"agent:content:write" "agent:content:read"}
+ (str (random-uuid)) "question_write"
+ (assoc args :name "Full Q")))]
+ (is (= "Full Q" (:name full))))))))))
+
+(deftest question-write-scopes-registered-test
+ (testing "the unified write scope flows into the OAuth surface"
+ (let [scopes (set (registry/registered-scopes))]
+ (is (contains? scopes "agent:content:write")))))
diff --git a/test/metabase/mcp/v2/tools/run_saved_question_test.clj b/test/metabase/mcp/v2/tools/run_saved_question_test.clj
new file mode 100644
index 00000000000..b0a47d7acac
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/run_saved_question_test.clj
@@ -0,0 +1,383 @@
+(ns metabase.mcp.v2.tools.run-saved-question-test
+ "Contract tests for the v2 `run_saved_question` tool, through the same
+ [[metabase.mcp.v2.registry/call-tool]] seam the JSON-RPC route uses, so scope gating,
+ nil-arg stripping, Malli validation, and teaching-error conversion are exercised on every
+ call. `execute_query` keyset-cursor semantics live in `metabase.mcp.v2.query-test`; QP
+ parameter-substitution semantics are the query processor's own suites — this one pins the
+ tool contract: what the model receives."
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer [deftest is testing use-fixtures]]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.v2.registry :as registry]
+ ;; registers the run_saved_question tool for the call-tool seam below; aliased for the
+ ;; direct unit test of the private `check-parameter-value!`
+ [metabase.mcp.v2.tools.query :as tools.query]
+ [metabase.permissions.core :as perms]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(defn- call-run-saved-question
+ ([args] (call-run-saved-question nil args))
+ ([token-scopes args]
+ (registry/call-tool token-scopes (str (random-uuid)) "run_saved_question" args)))
+
+(defn- dispatch-error?
+ "Whether a [[call-run-saved-question]] outcome is an error, at either layer: a registry-level
+ rejection (`{:error …}`, from a scope denial or an args-schema failure) or `:isError` tool
+ content."
+ [{:keys [result error]}]
+ (boolean (or error (:isError result))))
+
+(defn- response-text
+ "The outcome's text block, or a registry-level rejection's message."
+ [{:keys [result error]}]
+ (if error (:message error) (-> result :content first :text)))
+
+(defn- tool-result
+ "The decoded JSON payload of a successful call, with the steering line (the text after the
+ JSON block) under `::steering`. Throws when the call errored — an error can never masquerade
+ as an empty result."
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info (str "Tool call errored: " (response-text outcome)) {:outcome outcome})))
+ (let [[payload steering] (str/split (response-text outcome) #"\n" 2)]
+ (assoc (json/decode+kw payload) ::steering steering)))
+
+(defn- tool-error
+ "The error text of a failed call, at either layer. Throws when the call succeeded — a success
+ can never satisfy an error-path assertion."
+ [outcome]
+ (when-not (dispatch-error? outcome)
+ (throw (ex-info "Expected a tool error but the call succeeded" {:outcome outcome})))
+ (response-text outcome))
+
+(def ^:private cat-tag-id "aaaaaaaa-bbbb-cccc-dddd-000000000001")
+
+(defn- variable-card
+ "A native card with a `{{cat}}` text variable tag over PRODUCTS."
+ [card-name]
+ {:name card-name
+ :dataset_query (mt/native-query
+ {:query "SELECT ID, CATEGORY FROM PRODUCTS WHERE CATEGORY = {{cat}} ORDER BY ID"
+ :template-tags {"cat" {:id cat-tag-id
+ :name "cat"
+ :display-name "Category"
+ :type :text}}})})
+
+(defn- plain-card
+ "A parameterless native card over PRODUCTS (200 rows)."
+ [card-name]
+ {:name card-name
+ :dataset_query (mt/native-query {:query "SELECT ID, CATEGORY FROM PRODUCTS ORDER BY ID"})})
+
+(deftest ^:parallel run-parameterless-card-test
+ (testing "a parameterless card runs by numeric id: dataset shape, row_limit cap, truncation steering, and no query_handle"
+ (mt/with-temp [:model/Card {card-id :id} (plain-card "rsq parameterless")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [payload (tool-result (call-run-saved-question {:id card-id :row_limit 5}))]
+ (is (= 5 (:returned payload)))
+ (is (= 5 (count (:rows payload))))
+ (is (true? (:truncated payload)))
+ (is (= "returned 5 rows, more available — narrow with `parameters`, or raise `row_limit` (max 2000)"
+ (::steering payload)))
+ (is (= ["ID" "CATEGORY"] (map :name (:cols payload))))
+ (is (every? (every-pred :name :base_type :display_name) (:cols payload)))
+ (testing "this tool mints no handle and no cursor"
+ (is (nil? (:query_handle payload)))
+ (is (nil? (:next_cursor payload)))))))))
+
+(deftest ^:parallel run-complete-result-not-truncated-test
+ (testing "a result that fits under row_limit reports truncated: false and carries no steering line"
+ (mt/with-temp [:model/Card {card-id :id} (plain-card "rsq complete")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [payload (tool-result (call-run-saved-question {:id card-id :row_limit 500}))]
+ (is (= 200 (:returned payload)))
+ (is (false? (:truncated payload)))
+ (is (nil? (::steering payload))))))))
+
+(deftest ^:parallel exact-fit-result-not-truncated-test
+ (testing "a result that fills row_limit exactly is complete, not truncated — truncation is observed, not inferred"
+ (mt/with-temp [:model/Card {card-id :id} (plain-card "rsq exact fit")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [payload (tool-result (call-run-saved-question {:id card-id :row_limit 200}))]
+ (is (= 200 (:returned payload)))
+ (is (false? (:truncated payload)))
+ (is (nil? (::steering payload))))))))
+
+(deftest ^:parallel entity-id-parity-test
+ (testing "the same card by entity_id returns the same rows as by numeric id"
+ (mt/with-temp [:model/Card {card-id :id card-eid :entity_id} (plain-card "rsq eid parity")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [by-num (tool-result (call-run-saved-question {:id card-id :row_limit 5}))
+ by-eid (tool-result (call-run-saved-question {:id card-eid :row_limit 5}))]
+ (is (= 21 (count card-eid)))
+ (is (= (:rows by-num) (:rows by-eid))))))))
+
+(deftest ^:parallel parameters-by-slug-and-id-test
+ (testing "a parameter value is addressable by slug or by the parameter's id, with identical results"
+ (mt/with-temp [:model/Card {card-id :id} (variable-card "rsq by slug and id")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [by-slug (tool-result (call-run-saved-question
+ {:id card-id :parameters [{:id "cat" :value "Widget"}]}))
+ by-id (tool-result (call-run-saved-question
+ {:id card-id :parameters [{:id cat-tag-id :value "Widget"}]}))
+ by-key (tool-result (call-run-saved-question
+ {:id card-id :parameters [{:slug "cat" :value "Widget"}]}))]
+ (is (pos? (:returned by-slug)))
+ (is (= ["Widget"] (distinct (map second (:rows by-slug)))))
+ (is (= (:rows by-slug) (:rows by-id) (:rows by-key)))
+ (testing "an empty parameters array is the parameterless call"
+ (mt/with-temp [:model/Card {plain-id :id} (plain-card "rsq empty params")]
+ (is (= (:returned (tool-result (call-run-saved-question {:id plain-id})))
+ (:returned (tool-result (call-run-saved-question {:id plain-id :parameters []}))))))))))))
+
+(deftest ^:parallel client-target-ignored-security-test
+ ;; The target-swap injection surface from the task spec: `enrich-parameters-from-card`
+ ;; merges the client parameter last, so a client :target passed through verbatim would let
+ ;; a caller repoint a filter at an arbitrary field. The tool must forward only the stored
+ ;; :target and :type.
+ (testing "a client-supplied :target and :type in a parameter have no effect on which field is filtered"
+ (mt/with-temp [:model/Card {card-id :id}
+ {:name "rsq target swap"
+ :dataset_query (mt/native-query
+ {:query "SELECT ID, CATEGORY FROM PRODUCTS WHERE {{cat_ff}} ORDER BY ID"
+ :template-tags {"cat_ff" {:id "bbbbbbbb-0000-0000-0000-000000000001"
+ :name "cat_ff"
+ :display-name "Category"
+ :type :dimension
+ :widget-type :string/=
+ :dimension [:field (mt/id :products :category) nil]}}})}]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [clean (tool-result (call-run-saved-question
+ {:id card-id :parameters [{:id "cat_ff" :value ["Widget" "Gadget"]}]}))
+ swapped (tool-result (call-run-saved-question
+ {:id card-id
+ :parameters [{:id "cat_ff"
+ :value ["Widget" "Gadget"]
+ :type "number/="
+ :target ["dimension" ["field" (mt/id :products :rating) nil]]}]}))]
+ (is (= #{"Widget" "Gadget"} (set (map second (:rows clean)))))
+ (is (= (:rows clean) (:rows swapped))
+ "the injected target must not repoint the filter at RATING"))))))
+
+(deftest ^:parallel unknown-parameter-teaching-error-test
+ (testing "an unknown parameter id/slug is a teaching error naming the card's valid parameter ids and slugs"
+ (mt/with-temp [:model/Card {card-id :id} (variable-card "rsq unknown param")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [message (tool-error (call-run-saved-question
+ {:id card-id :parameters [{:id "nope" :value 1}]}))]
+ (is (str/includes? message "Unknown parameter \"nope\""))
+ (is (str/includes? message cat-tag-id))
+ (is (str/includes? message "(slug \"cat\")")))))))
+
+(deftest ^:parallel parameter-without-id-teaching-error-test
+ (testing "a parameter entry with neither id nor slug is a teaching error naming the required keys"
+ (mt/with-temp [:model/Card {card-id :id} (variable-card "rsq missing id")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (is (= "Each parameter needs an `id` — the parameter's id or slug — and a `value`."
+ (tool-error (call-run-saved-question
+ {:id card-id :parameters [{:value "Widget"}]}))))))))
+
+(deftest ^:parallel wrong-value-type-teaching-error-test
+ (testing "a value whose JSON type can't satisfy the parameter's stored type is a teaching error naming value, parameter, and expectation"
+ (mt/with-temp [:model/Card {card-id :id}
+ {:name "rsq number tag"
+ :dataset_query (mt/native-query
+ {:query "SELECT ID FROM PRODUCTS WHERE RATING > {{min_rating}}"
+ :template-tags {"min_rating" {:id "cccccccc-0000-0000-0000-000000000001"
+ :name "min_rating"
+ :display-name "Min rating"
+ :type :number}}})}]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [message (tool-error (call-run-saved-question
+ {:id card-id :parameters [{:id "min_rating" :value "abc"}]}))]
+ (is (str/includes? message "Invalid value \"abc\""))
+ (is (str/includes? message "\"min_rating\""))
+ (is (str/includes? message "expected a number")))
+ (testing "a numeric string satisfies a number parameter"
+ (is (map? (tool-result (call-run-saved-question
+ {:id card-id :parameters [{:id "min_rating" :value "4.5"}]})))))))))
+
+(defn- mbql-dimension-param-card
+ "A plain MBQL question over PRODUCTS with a declared filter-widget parameter targeting the
+ CATEGORY field — the case v1 and the first cut of this tool refused."
+ [card-name]
+ {:name card-name
+ :dataset_query (lib/query (mt/metadata-provider)
+ (lib.metadata/table (mt/metadata-provider) (mt/id :products)))
+ :parameters [{:id "p1"
+ :slug "cat_dim"
+ :name "Category"
+ :type :string/=
+ :target [:dimension [:field (mt/id :products :category) nil]]}]})
+
+(deftest ^:parallel mbql-dimension-parameter-filters-test
+ (testing "a saved question's declared MBQL filter-widget parameter runs and filters, addressable by id or slug"
+ (mt/with-temp [:model/Card {card-id :id} (mbql-dimension-param-card "rsq mbql param")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [category-col (fn [payload]
+ (let [i (first (keep-indexed #(when (= "CATEGORY" (:name %2)) %1)
+ (:cols payload)))]
+ (distinct (map #(nth % i) (:rows payload)))))
+ by-id (tool-result (call-run-saved-question
+ {:id card-id :parameters [{:id "p1" :value ["Widget"]}]}))
+ by-slug (tool-result (call-run-saved-question
+ {:id card-id :parameters [{:id "cat_dim" :value ["Widget"]}]}))]
+ (is (pos? (:returned by-id)))
+ (is (= ["Widget"] (category-col by-id))
+ "the dimension parameter must filter CATEGORY to the supplied value")
+ (is (= (:rows by-id) (:rows by-slug))))))))
+
+(deftest ^:parallel mbql-dimension-parameter-target-ignored-security-test
+ (testing "a client-supplied :target on an MBQL dimension parameter cannot repoint the filter at another field"
+ (mt/with-temp [:model/Card {card-id :id} (mbql-dimension-param-card "rsq mbql target swap")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [clean (tool-result (call-run-saved-question
+ {:id card-id :parameters [{:id "cat_dim" :value ["Widget"]}]}))
+ swapped (tool-result (call-run-saved-question
+ {:id card-id
+ :parameters [{:id "cat_dim"
+ :value ["Widget"]
+ :type "number/="
+ :target ["dimension" ["field" (mt/id :products :rating) nil]]}]}))]
+ (is (pos? (:returned clean)))
+ (is (= (:rows clean) (:rows swapped))
+ "the injected target must not repoint the filter from CATEGORY to RATING"))))))
+
+;; not ^:parallel: calls the `!`-named (but pure) `check-parameter-value!` directly, which the
+;; parallel-test linter bars as potentially destructive.
+(deftest value-type-family-check-test
+ ;; Exercises `check-parameter-value!` directly across every type family: the tool path in
+ ;; `wrong-value-type-teaching-error-test` only reaches the `number` branch, and constructing a
+ ;; card whose stored parameter type lands on `boolean`/`date`/`temporal-unit` is fiddly and
+ ;; couples the test to widget-type derivation. The checker is pure, so drive it as data.
+ (let [check #'tools.query/check-parameter-value!]
+ (testing "each family accepts JSON types that satisfy it and rejects those that cannot"
+ (doseq [[param-type accepted rejected]
+ [[:number/= [5 5.5 "5" "-3.2e4"] ["abc" true]]
+ [:number [7 "7"] ["nope"]]
+ [:boolean [true false "true" "false"] ["yes" 1]]
+ [:date/single ["2020-01-01"] [5 true]]
+ [:temporal-unit ["month"] [5]]
+ ;; default branch: any string, number, or boolean scalar
+ [:string/= ["Widget" 5 true] [{:x 1}]]]]
+ (testing (str param-type)
+ (doseq [v accepted]
+ (is (nil? (check {:type param-type :slug "p"} v))
+ (str "should accept " (pr-str v))))
+ (doseq [v rejected]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Invalid value"
+ (check {:type param-type :slug "p"} v))
+ (str "should reject " (pr-str v)))))))
+ (testing "one bad element rejects the whole multi-value array, naming that element"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Invalid value \"abc\""
+ (check {:type :number :slug "n"} [1 "abc"]))))
+ (testing "a structured value can never satisfy any family — no MBQL fragment reaches a filter"
+ ;; The second injection surface after target: the value position. Even for the permissive
+ ;; string family, a keyword, map, or nested-vector element is rejected, so a value cannot
+ ;; smuggle a field ref or clause into the filter it feeds.
+ (doseq [v [:keyword
+ {:x 1}
+ [["field" 1 nil]]
+ [:field 1 nil]]]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Invalid value"
+ (check {:type :string/= :slug "p"} v))
+ (str "should reject structured value " (pr-str v)))))))
+
+(deftest ^:parallel structured-value-rejected-at-schema-test
+ (testing "a non-scalar parameter value is rejected by the args schema, not swallowed as an internal error"
+ ;; Defense in depth with `check-parameter-value!`: the tightened `:value` schema stops a
+ ;; structured value (map, nested vector) at the boundary, so it can never reach the filter.
+ ;; A boundary rejection is a caller-facing "Invalid arguments" teaching error — the opposite
+ ;; of the opaque "Internal error" a value that slipped through to the QP would produce.
+ (mt/with-temp [:model/Card {card-id :id} (variable-card "rsq structured value")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (doseq [bad-value [{:x 1} [["field" 1 nil]]]]
+ (let [message (tool-error (call-run-saved-question
+ {:id card-id :parameters [{:id "cat" :value bad-value}]}))]
+ (is (str/includes? message "Invalid arguments")
+ (str "should reject structured value " (pr-str bad-value)))
+ (is (not= "Internal error" message))))))))
+
+;; not ^:parallel: mutates the permission graph for the temp collection.
+(deftest not-found-and-unreadable-collapse-test
+ (testing "an unreadable card and a nonexistent id yield string-identical errors — no existence oracle"
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "rsq hidden collection"}
+ :model/Card {hidden-id :id} (assoc (plain-card "rsq hidden card")
+ :collection_id coll-id)]
+ (perms/revoke-collection-permissions! (perms/all-users-group) coll-id)
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [normalize #(str/replace %1 (str %2) "<id>")
+ unreadable (tool-error (call-run-saved-question {:id hidden-id}))
+ missing (tool-error (call-run-saved-question {:id 999999999}))]
+ (is (= (normalize unreadable hidden-id)
+ (normalize missing 999999999))))))))
+
+(deftest ^:parallel scope-gating-test
+ (mt/with-temp [:model/Card {card-id :id} (plain-card "rsq scope")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "a token without agent:query:execute is refused"
+ (is (re-find #"^Insufficient scope to call tool: run_saved_question\."
+ (tool-error (call-run-saved-question #{"agent:metadata:read"} {:id card-id})))))
+ (testing "the identical call succeeds once the token carries the scope"
+ (is (pos? (:returned (tool-result (call-run-saved-question #{"agent:query:run"}
+ {:id card-id :row_limit 5})))))))))
+
+(deftest ^:parallel row-limit-validation-test
+ (mt/with-temp [:model/Card {card-id :id} (plain-card "rsq row limit")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "row_limit above the 2000 cap is a schema-level teaching error"
+ (is (str/includes? (tool-error (call-run-saved-question {:id card-id :row_limit 3000}))
+ "row_limit: should be at most 2000")))
+ (testing "an id that is neither numeric nor a 21-char entity_id is a teaching error"
+ (is (= "Invalid id \"garbage\" — pass the positive numeric id, or the 21-character entity_id from a search or list result."
+ (tool-error (call-run-saved-question {:id "garbage"}))))))))
+
+(deftest ^:parallel pivot-card-row-cap-test
+ ;; `process-query-for-card` routes a `:display :pivot` card through
+ ;; `qp.pivot/run-pivot-query`, which replaces the injected `:max-results` constraints with
+ ;; its own pivot ceiling — without the tool-layer cap, a pivot card returns its full pivot
+ ;; row set (hundreds of rows) with `truncated: false` and no steering.
+ (testing "a pivot-display card is still capped at row_limit and reports truncation"
+ (mt/with-temp [:model/Card {card-id :id}
+ {:name "rsq pivot"
+ :display :pivot
+ :dataset_query (-> (lib/query (mt/metadata-provider)
+ (lib.metadata/table (mt/metadata-provider) (mt/id :products)))
+ (lib/aggregate (lib/count))
+ (lib/breakout (lib.metadata/field (mt/metadata-provider) (mt/id :products :category)))
+ (lib/breakout (lib.metadata/field (mt/metadata-provider) (mt/id :products :vendor))))
+ :visualization_settings {:pivot_table.column_split
+ {:rows ["CATEGORY"]
+ :columns ["VENDOR"]
+ :values ["count"]}}}]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [payload (tool-result (call-run-saved-question {:id card-id :row_limit 5}))]
+ (is (= 5 (:returned payload)))
+ (is (= 5 (count (:rows payload))))
+ (is (true? (:truncated payload)))
+ (is (some? (::steering payload))))))))
+
+(deftest ^:parallel numeric-string-id-parity-test
+ (testing "GHY-4498: Claude Desktop sends every value of an int-or-string param as a JSON string,
+ so a numeric card id arrives as \"16211\" and must run the same card as the integer"
+ (mt/with-temp [:model/Card {card-id :id} (plain-card "rsq numeric string id")]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [by-num (tool-result (call-run-saved-question {:id card-id :row_limit 5}))
+ by-str (tool-result (call-run-saved-question {:id (str card-id) :row_limit 5}))]
+ (is (= (:rows by-num) (:rows by-str))))))))
+
+(deftest ^:parallel non-id-string-still-rejected-test
+ (testing "GHY-4498: only the exact shape of a numeric id is coerced — every other string keeps
+ going through entity_id validation"
+ (mt/with-current-user (mt/user->id :rasta)
+ (doseq [bad ["0" "-1" "016211" "1.0" "not-an-id"]]
+ (is (str/includes? (tool-error (call-run-saved-question {:id bad})) "entity_id")
+ (str "expected " (pr-str bad) " to be rejected"))))))
diff --git a/test/metabase/mcp/v2/tools/search_test.clj b/test/metabase/mcp/v2/tools/search_test.clj
new file mode 100644
index 00000000000..c439e36dd51
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/search_test.clj
@@ -0,0 +1,596 @@
+(ns metabase.mcp.v2.tools.search-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.activity-feed.core :as activity-feed]
+ [metabase.activity-feed.models.recent-views :as recent-views]
+ [metabase.mcp.v2.tools.search :as tools.search]
+ [metabase.metabot.tools.search :as metabot.search]
+ [metabase.permissions.core :as perms]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private add-collection-paths
+ #'tools.search/add-collection-paths)
+
+(def ^:private validate-filters!
+ #'tools.search/validate-filters!)
+
+(def ^:private validate-modes!
+ #'tools.search/validate-modes!)
+
+(def ^:private resolve-collection-filter
+ #'tools.search/resolve-collection-filter)
+
+(def ^:private engine-results
+ #'tools.search/engine-results)
+
+(defn- path-for
+ "`:collection_path` that `user` sees for a row contained in `collection-id`."
+ [user collection-id]
+ (mt/with-current-user (mt/user->id user)
+ (:collection_path (first (add-collection-paths [{:collection {:id collection-id}}])))))
+
+(deftest ^:parallel rv-model-type-maps-invert-losslessly-test
+ (testing "GHY-4137: rv-model->type is the inverse of type->rv-model — the inversion must not
+ collapse two types onto one recent-views model, so the two maps have equal counts"
+ (is (= (count @#'tools.search/type->rv-model)
+ (count @#'tools.search/rv-model->type)))))
+
+(deftest collection-path-omits-unreadable-ancestors-test
+ (testing "GHY-4137: collection_path must not name ancestors the caller can't read — the path is a
+ breadcrumb and follows effective-ancestors semantics, where an unreadable middle
+ collection is dropped rather than hiding the whole path"
+ (mt/with-temp [:model/Collection a {:name "Alpha"}
+ :model/Collection b {:name "Bravo" :location (format "/%d/" (:id a))}
+ :model/Collection c {:name "Charlie" :location (format "/%d/%d/" (:id a) (:id b))}]
+ (let [all-users (perms/all-users-group)]
+ (perms/grant-collection-read-permissions! all-users a)
+ (perms/revoke-collection-permissions! all-users b)
+ (perms/grant-collection-read-permissions! all-users c)
+ (testing "an admin, who can read every ancestor, sees the full path"
+ (is (= "Alpha/Bravo/Charlie" (path-for :crowberto (:id c)))))
+ (testing "a user who cannot read Bravo never sees its name"
+ (is (= "Alpha/Charlie" (path-for :rasta (:id c)))))))))
+
+;; not ^:parallel: the kondo deftest lint treats the `!` suffix of `validate-filters!` as
+;; destructive, though it only validates and throws
+(deftest snippet-type-is-exclusive-test
+ (testing "GHY-4137: snippets are served by a separate listing and paged separately, so mixing
+ them with engine-backed types silently dropped snippets on a full page and repeated
+ them on an underfilled one. The combination is a teaching error instead."
+ (testing "snippet alone is fine"
+ (is (some? (validate-filters! {:type ["snippet"]}))))
+ (testing "engine types alone are fine"
+ (is (some? (validate-filters! {:type ["question" "dashboard"]}))))
+ (testing "no type at all is fine"
+ (is (some? (validate-filters! {}))))
+ (testing "snippet alongside another type names the offending types and how to split the call"
+ (let [e (is (thrown-with-msg? clojure.lang.ExceptionInfo
+ #"cannot be combined with other types"
+ (validate-filters! {:type ["question" "snippet"]})))]
+ (is (re-find #"question" (ex-message e))
+ "the error should name what to move to the other call"))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo
+ #"cannot be combined with other types"
+ (validate-filters! {:type ["snippet" "dashboard" "table"]}))))
+ (testing "the teaching error is a 400, not a server error"
+ (is (= 400 (:status-code (ex-data (try (validate-filters! {:type ["question" "snippet"]})
+ (catch clojure.lang.ExceptionInfo e e)))))))))
+
+;; not ^:parallel: the kondo deftest lint treats the `!` suffix of `validate-filters!` as
+;; destructive, though it only validates and throws
+(deftest semantic-queries-against-snippets-is-teaching-error-test
+ (testing "GHY-4137: snippets aren't in the search index — snippet-rows substring-matches names
+ against term_queries and semantic_queries alike, so a natural-language semantic_queries
+ entry essentially never hits a name and silently returns an empty page the agent reads
+ as \"no such snippets\". A teaching error instead of a guaranteed-empty search."
+ (testing "semantic_queries with type: [\"snippet\"] is rejected"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"semantic_queries cannot search snippets"
+ (validate-filters! {:type ["snippet"] :semantic_queries ["customer lifetime value"]}))))
+ (testing "term_queries with type: [\"snippet\"] is unaffected — substring matching works for keywords"
+ (is (some? (validate-filters! {:type ["snippet"] :term_queries ["cltv"]}))))
+ (testing "snippet alone, with no queries at all, is unaffected"
+ (is (some? (validate-filters! {:type ["snippet"]}))))
+ (testing "semantic_queries without type: [\"snippet\"] is unaffected — it reaches the engine, which supports it"
+ (is (some? (validate-filters! {:semantic_queries ["customer lifetime value"]}))))
+ (testing "the teaching error is a 400"
+ (is (= 400 (:status-code (ex-data (try (validate-filters! {:type ["snippet"] :semantic_queries ["x"]})
+ (catch clojure.lang.ExceptionInfo e e)))))))))
+
+;; not ^:parallel: the kondo deftest lint treats the `!` suffix of `validate-filters!` as
+;; destructive, though it only validates and throws
+(deftest collection-id-root-is-inert-test
+ (testing "GHY-4137: collection_id \"root\" is documented as \"no scoping\" and resolves to nil, so
+ it must not trip the collection teaching errors the way a real collection id does"
+ (testing "\"root\" passes every check a real collection id would fail"
+ (is (some? (validate-filters! {:type ["database"] :collection_id "root"}))
+ "collectionless type + root: no error")
+ (is (some? (validate-filters! {:type ["table"] :collection_id "root"}))
+ "table + root (no Library feature): no error")
+ (is (some? (validate-filters! {:type ["snippet"] :collection_id "root"}))
+ "snippet + root: no error")
+ (is (some? (validate-filters! {:recent true :collection_id "root"}))
+ "recents + root: no error"))
+ (testing "a real collection id still errors where it genuinely can't apply"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"don't live in collections"
+ (validate-filters! {:type ["database"] :collection_id "someEntityId01234567_"})))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"cannot filter snippets"
+ (validate-filters! {:type ["snippet"] :collection_id "someEntityId01234567_"})))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"recent: true supports only the type filter"
+ (validate-filters! {:recent true :collection_id "someEntityId01234567_"}))))))
+
+;; not ^:parallel: with-premium-features rebinds a global, and the `!` in validate-filters! trips
+;; the kondo deftest lint
+(deftest table-collection-id-requires-library-feature-test
+ (testing "GHY-4137: filtering tables by a real collection_id requires the Library feature; on an
+ instance without it the combination is a teaching error, but \"root\" stays inert"
+ (mt/with-premium-features #{}
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"requires the Library feature"
+ (validate-filters! {:type ["table"] :collection_id "someEntityId01234567_"}))
+ "no Library feature + real collection id: error")
+ (is (some? (validate-filters! {:type ["table"] :collection_id "root"}))
+ "\"root\" is inert even without the Library feature"))
+ (mt/with-premium-features #{:library}
+ (is (some? (validate-filters! {:type ["table"] :collection_id "someEntityId01234567_"}))
+ "with the Library feature, table + collection id is allowed"))))
+
+;; not ^:parallel: the `!` in validate-filters! trips the kondo deftest lint
+(deftest collection-scoping-accepts-numeric-id-test
+ (testing "GHY-4137: collection_id may be a numeric id, not only a string entity_id — a numeric id
+ counts as scoping"
+ (testing "validate-filters! trips the collectionless error for a numeric id on a collectionless type"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"don't live in collections"
+ (validate-filters! {:type ["database"] :collection_id 5}))))
+ (testing "resolve-collection-filter resolves a real numeric collection id behind the read check"
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (is (= coll-id (resolve-collection-filter coll-id))))))))
+
+;; not ^:parallel: the `!` in validate-filters! trips the kondo deftest lint
+(deftest transform-collection-id-is-teaching-error-test
+ (testing "GHY-4137: the search index doesn't record a transform's collection, so type:[transform]
+ with a collection_id can only ever return an empty page — a teaching error instead of a
+ silent empty result the agent would read as \"no transforms here\""
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"collection_id cannot filter transforms"
+ (validate-filters! {:type ["transform"] :collection_id "someEntityId01234567_"})))
+ (testing "transform without a collection_id is fine"
+ (is (some? (validate-filters! {:type ["transform"]}))))
+ (testing "\"root\" collection_id stays inert for transforms"
+ (is (some? (validate-filters! {:type ["transform"] :collection_id "root"}))))))
+
+;; not ^:parallel: the `!` in validate-filters! trips the kondo deftest lint
+(deftest archived-non-archivable-type-is-teaching-error-test
+ (testing "GHY-4137: table, database, and transform have no archived state, so archived: true with
+ any of them guarantees an empty page — the engine silently drops the type. Teach instead."
+ (doseq [t ["table" "database" "transform"]]
+ (testing t
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"no archived state"
+ (validate-filters! {:type [t] :archived true})))))
+ (testing "archivable types are unaffected"
+ (is (some? (validate-filters! {:type ["question" "dashboard"] :archived true}))))
+ (testing "archived: false is fine even for the non-archivable types"
+ (is (some? (validate-filters! {:type ["table"] :archived false}))))
+ (testing "no archived filter at all is fine"
+ (is (some? (validate-filters! {:type ["table"]}))))))
+
+;; not ^:parallel: with-premium-features rebinds a global, and the `!` in validate-filters! trips
+;; the kondo deftest lint
+(deftest omitted-type-narrows-and-discloses-filter-incompatibility-test
+ (testing "GHY-4137/I5: created_by/collection_id/archived are only checked against types the caller
+ named explicitly — when type is omitted, the search runs against every engine type, and
+ the engine silently drops whichever ones don't support the filter with no error and no
+ signal. Naming a type explicitly that doesn't support the filter is still a teaching
+ error; an omitted type narrows to the supporting types instead and discloses it, so the
+ natural unscoped call (e.g. created_by: \"me\" with no type) still returns results."
+ (testing "created_by with no type: narrows to creator-indexing types and discloses it, does not throw"
+ (let [{:keys [types disclosures]} (validate-filters! {:created_by "me"})]
+ (is (= ["action" "dashboard" "document" "measure" "metric" "model" "question"] types))
+ (is (= 1 (count disclosures)))
+ (is (re-find #"created_by narrowed the search to" (first disclosures)))
+ (is (re-find #"collection, database, segment, table, transform don't index a creator" (first disclosures)))))
+ (testing "collection_id with no type: narrows to collection-dwelling types and discloses it, does not throw"
+ ;; Features pinned: without :library the table exclusion is disclosed too, so the count
+ ;; would otherwise depend on the token the suite happens to run under.
+ (mt/with-premium-features #{:library}
+ (let [{:keys [types disclosures]} (validate-filters! {:collection_id "someEntityId01234567_"})]
+ (is (not (contains? (set types) "database")))
+ (is (not (contains? (set types) "measure")))
+ (is (not (contains? (set types) "segment")))
+ (is (= 2 (count disclosures))
+ "the collectionless types, plus transform (no collection in the index)")
+ (is (every? #(re-find #"collection_id narrowed the search to" %) disclosures)))))
+ (testing "archived: true with no type: narrows to archivable types and discloses it, does not throw"
+ (let [{:keys [types disclosures]} (validate-filters! {:archived true})]
+ (is (not (contains? (set types) "table")))
+ (is (not (contains? (set types) "database")))
+ (is (not (contains? (set types) "transform")))
+ (is (= 1 (count disclosures)))
+ (is (re-find #"archived: true narrowed the search to" (first disclosures)))))
+ (testing "created_by with a type set that is entirely creator-supporting is unaffected — no narrowing"
+ (is (= {:types nil :disclosures []}
+ (validate-filters! {:created_by "me" :type ["question" "dashboard"]}))))
+ (testing "naming an incompatible type explicitly is still a teaching error, not a silent narrow"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"created_by only applies to types that index a creator"
+ (validate-filters! {:created_by "me" :type ["database"]})))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"don't live in collections"
+ (validate-filters! {:collection_id "someEntityId01234567_" :type ["database"]})))
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"no archived state"
+ (validate-filters! {:archived true :type ["table"]}))))
+ (testing "an explicit-type teaching error still names the offending type"
+ (is (re-find #"Remove database from type"
+ (try (validate-filters! {:created_by "me" :type ["database"]})
+ (catch clojure.lang.ExceptionInfo e (ex-message e))))))
+ (testing "the explicit-type teaching error is a 400"
+ (is (= 400 (:status-code (ex-data (try (validate-filters! {:created_by "me" :type ["database"]})
+ (catch clojure.lang.ExceptionInfo e e)))))))))
+
+(deftest omitted-type-discloses-oss-table-collection-exclusion-test
+ (testing "GHY-4137/P7: the engine's collection filter drops `table` outright when the Library
+ feature is absent (search/filter.clj's ::collection-hierarchy clause). With an explicit
+ type: [\"table\"] that is already a teaching error, but with type omitted the exclusion
+ was silent — precisely the undisclosed narrowing this namespace promises never to rely
+ on. It must be narrowed and disclosed like any other unsupported combination."
+ (mt/with-premium-features #{}
+ (let [{:keys [types disclosures]} (validate-filters! {:collection_id "someEntityId01234567_"})]
+ (is (not (contains? (set types) "table"))
+ "table is narrowed out, not left in for the engine to drop quietly")
+ (is (some #(re-find #"Library feature" %) disclosures)
+ "and the caller is told why")
+ (is (not (contains? (set types) "transform"))
+ "transform has no collection in the index, so the engine drops it from a
+ collection-scoped search too — same silent narrowing, same disclosure")
+ (is (some #(re-find #"transform isn't recorded with a collection" %) disclosures))
+ (is (contains? (set types) "question")
+ "sanity: collection-dwelling types are untouched, so this isn't an empty-set pass")))
+ (testing "with the Library feature, tables stay in scope and nothing is disclosed about them"
+ (mt/with-premium-features #{:library}
+ (let [{:keys [types disclosures]} (validate-filters! {:collection_id "someEntityId01234567_"})]
+ (is (contains? (set types) "table"))
+ (is (not (some #(re-find #"Library feature" %) disclosures)))
+ (is (not (contains? (set types) "transform"))
+ "the Library feature says nothing about transforms — they stay narrowed"))))
+ (testing "\"root\" is inert — it scopes nothing, so it must not trip the table narrowing"
+ (mt/with-premium-features #{}
+ (is (= {:types nil :disclosures []}
+ (validate-filters! {:collection_id "root" :type ["table"]})))))))
+
+(deftest multi-filter-disclosures-name-the-final-type-set-test
+ (testing "GHY-4137/P5: when two filters each narrow an omitted type, every disclosure must name
+ the search's FINAL type set. Each message used to be built from the full engine surface
+ minus only its own exclusions, so a later disclosure advertised types an earlier filter
+ had already removed — telling the model the search covered ground it did not."
+ (let [{:keys [types disclosures]} (validate-filters! {:created_by "me" :archived true})
+ final-types "action, dashboard, document, measure, metric, model, question"]
+ (is (= ["action" "dashboard" "document" "measure" "metric" "model" "question"] types)
+ "sanity: both filters narrow, so this exercises the multi-narrowing path")
+ (is (= 2 (count disclosures)))
+ (testing "every disclosure names exactly the final set, not its own private subtraction"
+ (doseq [d disclosures]
+ (is (= final-types (second (re-find #"narrowed the search to (.+?) —" d))) d)))
+ (testing "each disclosure still explains why its own filter excluded what it did"
+ (is (some #(re-find #"collection, database, segment, table, transform don't index a creator" %)
+ disclosures))
+ (is (some #(re-find #"database, table, transform have no archived state" %)
+ disclosures))))))
+
+(deftest snippet-rows-does-not-load-content-test
+ (testing "GHY-4137: snippet-rows must not pull the SQL body (:content) into the heap — it needs
+ only id/name/description for output and :collection_id for the can-read? check"
+ (let [captured (atom nil)]
+ (with-redefs [t2/select (fn [model & _] (reset! captured model) [])]
+ (#'tools.search/snippet-rows [] false))
+ (is (vector? @captured)
+ "the select is column-scoped (a [model & cols] vector), not the bare model keyword")
+ (let [cols (set (rest @captured))]
+ (is (contains? cols :collection_id) "collection_id is selected — can-read? consults it")
+ (is (not (contains? cols :content)) "the SQL body column is not selected")))))
+
+(deftest snippet-rows-are-permission-filtered-test
+ (testing "GHY-4137: `mi/can-read?` in snippet-rows is the ONLY permission check on snippet results —
+ snippets are not in the search index, so nothing upstream filters them. In OSS that check is
+ native-query permission on any database; without it every agent:content:read caller would see
+ every snippet name and description in the instance."
+ (mt/with-temp [:model/NativeQuerySnippet _ {:name "mcp-perm-probe-snippet" :content "WHERE 1=1"}]
+ (testing "a caller with native-query permission sees it"
+ (mt/with-test-user :crowberto
+ (is (some #(= "mcp-perm-probe-snippet" (:name %))
+ (#'tools.search/snippet-rows [] false)))))
+ (testing "a caller without it sees nothing — and the name never crosses the boundary"
+ (mt/with-no-data-perms-for-all-users!
+ (mt/with-test-user :rasta
+ (let [rows (#'tools.search/snippet-rows [] false)]
+ (is (not (some #(= "mcp-perm-probe-snippet" (:name %)) rows))))))))))
+
+;; not ^:parallel: the `!` in validate-modes! trips the kondo deftest lint
+(deftest query-limits-test
+ (testing "GHY-4137: each query list is length-capped and each query is char-bounded, so one call
+ can't fan out into hundreds of concurrent searches — the MCP throttler counts requests,
+ not the queries inside one"
+ (testing "more than 10 term_queries is a teaching error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"at most 10"
+ (validate-modes! {:term_queries (vec (repeat 11 "x"))} true false))))
+ (testing "more than 10 semantic_queries is a teaching error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"at most 10"
+ (validate-modes! {:semantic_queries (vec (repeat 11 "x"))} true false))))
+ (testing "exactly 10 per list is allowed"
+ (is (some? (validate-modes! {:term_queries (vec (repeat 10 "x"))
+ :semantic_queries (vec (repeat 10 "y"))} true false))))
+ (testing "a query longer than 500 characters is a teaching error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"at most 500 characters"
+ (validate-modes! {:term_queries [(apply str (repeat 501 "a"))]} true false))))
+ (testing "a 500-character query is allowed"
+ (is (some? (validate-modes! {:term_queries [(apply str (repeat 500 "a"))]} true false))))))
+
+;; not ^:parallel: the `!` in validate-modes! trips the kondo deftest lint
+(deftest blank-query-is-rejected-test
+ (testing "GHY-4137: a whitespace-only query passes the {:min 1} schema, but Postgres treats a
+ blank search string as match-all — so a blank query silently becomes an unscoped
+ listing. It is a teaching error instead."
+ (testing "a whitespace-only term query is rejected"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"blank|empty"
+ (validate-modes! {:term_queries [" "]} true false))))
+ (testing "a whitespace-only semantic query is rejected"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"blank|empty"
+ (validate-modes! {:semantic_queries ["\t"]} true false))))
+ (testing "a blank query mixed with a real one is still rejected — it would broaden the whole call"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"blank|empty"
+ (validate-modes! {:term_queries ["sales" " "]} true false))))
+ (testing "a real query with incidental surrounding whitespace is fine"
+ (is (some? (validate-modes! {:term_queries [" sales "]} true false))))
+ (testing "the teaching error is a 400"
+ (is (= 400 (:status-code (ex-data (try (validate-modes! {:term_queries [" "]} true false)
+ (catch clojure.lang.ExceptionInfo e e)))))))))
+
+(deftest resolve-collection-filter-delegates-sentinels-test
+ (testing "GHY-4137: resolve-collection-filter delegates sentinel handling to
+ common/resolve-collection-id instead of a local set — so \"trash\" gets its specific
+ teaching error rather than a generic invalid-id, and nil/\"root\" still mean no scoping"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "\"trash\" is the specific teaching error"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"not a valid collection here"
+ (resolve-collection-filter "trash"))))
+ (testing "nil and \"root\" resolve to nil (no scoping)"
+ (is (nil? (resolve-collection-filter nil)))
+ (is (nil? (resolve-collection-filter "root")))))))
+
+;; not ^:parallel: the `!` in validate-modes! trips the kondo deftest lint
+(deftest filters-only-redirects-to-browse-test
+ (testing "GHY-4137: a call with filters but no query is a listing, not a search — the search tool
+ now redirects it to the browse_* tools rather than running a query-less engine search
+ (whose order is arbitrary without a relevance anchor and whose total is ranking-capped)"
+ (testing "a collection listing routes to browse_collection with that id"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"browse_collection\(id: "
+ (validate-modes! {:type ["dashboard"] :collection_id "someEntityId01234567_"} false true))))
+ (testing "a snippet listing routes to the snippets namespace"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"namespace: \"snippets\""
+ (validate-modes! {:type ["snippet"]} false true))))
+ (testing "a transform listing routes to the transforms namespace"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"namespace: \"transforms\""
+ (validate-modes! {:type ["transform"]} false true))))
+ (testing "a created_by listing routes to browse_collection with created_by"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"created_by"
+ (validate-modes! {:created_by "me"} false true))))
+ (testing "an archived listing routes to the trash"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"trash"
+ (validate-modes! {:archived true} false true))))
+ (testing "a data-source listing routes to browse_data"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"browse_data"
+ (validate-modes! {:type ["table"]} false true))))
+ (testing "a search that carries a query plus filters is not redirected"
+ (is (some? (validate-modes! {:term_queries ["sales"] :type ["dashboard"]} true true))))
+ (testing "the redirect is a 400 teaching error"
+ (is (= 400 (:status-code (ex-data (try (validate-modes! {:type ["dashboard"]} false true)
+ (catch clojure.lang.ExceptionInfo e e)))))))))
+
+(defn- nothing-to-search?
+ "True when the search handler rejects `args` with the \"Nothing to search for\" teaching error.
+ A non-matching failure (e.g. the engine's \"No current user\") means validation was passed."
+ [args]
+ (try
+ (tools.search/search-tool args {:token-scopes #{"agent:content:read"}})
+ false
+ (catch clojure.lang.ExceptionInfo e
+ (boolean (re-find #"Nothing to search for" (ex-message e))))))
+
+(deftest ^:parallel collection-id-root-alone-is-empty-request-test
+ (testing "GHY-4137: \"root\" is inert everywhere — as the *only* argument it scopes nothing, so
+ the request has no query and no real filter and is rejected as empty rather than
+ listing the entire instance"
+ (is (nothing-to-search? {:collection_id "root"}))
+ (is (nothing-to-search? {}) "sanity: a truly empty request is also rejected"))
+ (testing "\"root\" combined with a real query is a valid search — it passes validation"
+ (is (not (nothing-to-search? {:collection_id "root" :term_queries ["sales"]}))))
+ (testing "\"root\" with only a filter is a browse redirect, not a query-less search"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"browse_"
+ (tools.search/search-tool {:collection_id "root" :type ["dashboard"]}
+ {:token-scopes #{"agent:content:read"}})))))
+
+(deftest engine-results-reports-total-test
+ (testing "GHY-4137: engine-results reports the engine's total for every search, including a
+ superuser transform search — transforms are no longer dropped by a post-filter, so
+ the total is accurate and is not suppressed"
+ (with-redefs [metabot.search/search (fn [_ctx] (with-meta [{:id 1 :type "question"}] {:total 30}))]
+ (mt/with-test-user :crowberto
+ (is (= 30 (:total (engine-results {} ["question" "transform"] nil 20 0))))
+ (is (= 30 (:total (engine-results {} ["question" "dashboard"] nil 20 0))))))))
+
+(deftest collection-row-path-omits-unreadable-ancestors-test
+ (testing "GHY-4137: a collection row builds its path from its own :location — that path must
+ also omit unreadable ancestors"
+ (mt/with-temp [:model/Collection a {:name "Alpha"}
+ :model/Collection b {:name "Bravo" :location (format "/%d/" (:id a))}
+ :model/Collection c {:name "Charlie" :location (format "/%d/%d/" (:id a) (:id b))}]
+ (let [all-users (perms/all-users-group)
+ path-of (fn [user coll]
+ (mt/with-current-user (mt/user->id user)
+ (:collection_path (first (add-collection-paths [(select-keys coll [:id :location])])))))]
+ (perms/grant-collection-read-permissions! all-users a)
+ (perms/revoke-collection-permissions! all-users b)
+ (perms/grant-collection-read-permissions! all-users c)
+ (is (= "Alpha/Bravo" (path-of :crowberto c)))
+ (is (= "Alpha" (path-of :rasta c)))))))
+
+(deftest collection-path-for-readable-ancestors-test
+ (testing "a fully readable chain is unaffected by the permission filter"
+ (mt/with-temp [:model/Collection a {:name "Alpha"}
+ :model/Collection b {:name "Bravo" :location (format "/%d/" (:id a))}]
+ (perms/grant-collection-read-permissions! (perms/all-users-group) a)
+ (perms/grant-collection-read-permissions! (perms/all-users-group) b)
+ (is (= "Alpha/Bravo" (path-for :rasta (:id b)))))))
+
+(def ^:private recents-page
+ #'tools.search/recents-page)
+
+(deftest recents-without-a-type-returns-every-tracked-model-test
+ (testing "GHY-4137: `recent: true` with no `type` lists every tracked model. `recents-page` maps
+ an absent `type` to an empty `:models` vector, which `get-recents` passes to `do-query`
+ — where `(when (seq db-models) ...)` omits the model filter entirely rather than
+ filtering to nothing. Pinned because the empty-vector-means-everything step is invisible
+ at this call site: tightening it into a real `IN ()` would silently return no recents."
+ (mt/with-temp [:model/Card {card-id :id} {:name "Recent Card"}
+ :model/Dashboard {dash-id :id} {:name "Recent Dashboard"}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-model-cleanup [:model/RecentViews]
+ (activity-feed/update-users-recent-views! (mt/user->id :crowberto) :model/Card card-id :view)
+ (activity-feed/update-users-recent-views! (mt/user->id :crowberto) :model/Dashboard dash-id :view)
+ (let [{:keys [rows]} (recents-page {} :concise 50 0)
+ ids (set (map :id rows))]
+ (is (contains? ids card-id) "the card is listed with no type filter")
+ (is (contains? ids dash-id) "the dashboard is listed with no type filter")))))))
+
+(deftest recents-total-is-a-floor-test
+ (testing "GHY-4137: RecentViews retains at most 20 rows per user per model per context
+ ([[metabase.activity-feed.models.recent-views/*recent-views-stored-per-user-per-model*]])
+ and silently drops unreadable/inconsistent rows, so `recents-page`'s `:total` (the size
+ of that already-capped, already-filtered set) is a lower bound on how much the user has
+ actually viewed — never an exact count. The engine branch already marks its total a floor
+ for the analogous reason (the ranking-limit cap); the recents branch must match."
+ ;; A fresh temp user, so no other test sharing the app db can have viewed anything as this user —
+ ;; recents are per-user, so an isolated user makes the count deterministic under parallel CI.
+ (mt/with-temp [:model/User {uid :id} {}]
+ (mt/with-model-cleanup [:model/Card :model/RecentViews]
+ ;; One more card than the per-model cap, so the cap binds regardless of anything else.
+ (let [card-ids (mapv (fn [i]
+ (t2/insert-returning-pk!
+ :model/Card {:name (str "recents-floor-" i)
+ :database_id (mt/id)
+ :creator_id uid
+ :type :question
+ :dataset_query {}
+ :display :table
+ :visualization_settings {}}))
+ (range 21))
+ cap @#'recent-views/*recent-views-stored-per-user-per-model*]
+ (mt/with-current-user uid
+ (doseq [id card-ids]
+ (activity-feed/update-users-recent-views! uid :model/Card id :view))
+ (testing "recents-page: total is capped at the per-model retention limit even though 21 were viewed"
+ (is (= cap (:total (recents-page {} :concise 10 0)))
+ "total equals the retention cap, not the 21 actually viewed"))
+ (testing "the tool response marks the total as a floor — \"at least\", not an exact count"
+ (let [content (tools.search/search-tool {:recent true :limit 10}
+ {:token-scopes #{"agent:content:read"}})
+ text (-> content :content first :text)]
+ (is (re-find (re-pattern (str "\"total\":" cap)) text))
+ (is (re-find (re-pattern (str "Returned 10 of at least " cap)) text)
+ "the steering line must not assert the total is exact — this user viewed 21 cards")))))))))
+
+(deftest recents-floor-line-renders-at-default-limit-test
+ (testing "I6: at the DEFAULT limit (20), a user at the per-model retention cap gets a page that
+ arithmetically looks whole — returned == total == 20 — so the ordinary truncation-line
+ (which only fires when offset+limit < total) stays silent. Without a dedicated floor
+ line the response reads \"total\":20,\"returned\":20 as an exact, exhausted count, when
+ the user may have viewed far more than 20 and can never page past the cap. A prior fix
+ covered this only at limit: 10, where the arithmetic truncation still fires normally."
+ (mt/with-temp [:model/User {uid :id} {}]
+ (mt/with-model-cleanup [:model/Card :model/RecentViews]
+ (let [card-ids (mapv (fn [i]
+ (t2/insert-returning-pk!
+ :model/Card {:name (str "recents-floor-default-" i)
+ :database_id (mt/id)
+ :creator_id uid
+ :type :question
+ :dataset_query {}
+ :display :table
+ :visualization_settings {}}))
+ (range 21))
+ cap @#'recent-views/*recent-views-stored-per-user-per-model*]
+ (mt/with-current-user uid
+ (doseq [id card-ids]
+ (activity-feed/update-users-recent-views! uid :model/Card id :view))
+ ;; No :limit passed — exercises the tool's own default (20), matching the cap exactly.
+ (let [content (tools.search/search-tool {:recent true} {:token-scopes #{"agent:content:read"}})
+ text (-> content :content first :text)]
+ (is (re-find (re-pattern (str "\"returned\":" cap ",\"total\":" cap)) text)
+ "sanity: the page is arithmetically full at the default limit")
+ (is (re-find (re-pattern (str "Returned " cap " of at least " cap)) text)
+ "the floor line must still render even though the page looks exhaustive")
+ (is (re-find #"narrow with `type`" text)
+ "recents can't be paged past the cap, so it steers to narrowing, not an offset")
+ (is (not (re-find #"offset:" text))
+ "no offset is offered — there is nothing stored beyond the cap to page to"))))))))
+
+;; not ^:parallel: the `!` in validate-filters! trips the kondo deftest lint, and with-redefs stubs
+;; a shared var
+(deftest omitted-type-filter-narrows-instead-of-hard-failing-test
+ (testing "I5: created_by/collection_id/archived with NO type is the most natural unscoped call
+ (\"find my stuff\") — a prior fix widened the compatibility check to the full engine
+ type set for this case but hard-failed the call instead of narrowing it, breaking the
+ common case. The fix narrows to the supporting types and discloses it instead.
+ metabot.search/search is stubbed (as in engine-results-reports-total-test) so this
+ exercises validate-filters!'s narrowed :types actually reaching the engine call — not
+ just validate-filters! in isolation — without depending on a materialized search index."
+ (testing "created_by: \"me\" with no type reaches the engine with the narrowed types, returns
+ results, and discloses the narrowing"
+ (let [captured-entity-types (atom nil)]
+ (with-redefs [metabot.search/search (fn [{:keys [entity-types]}]
+ (reset! captured-entity-types entity-types)
+ (with-meta [{:id 1 :type "question" :name "My I5 Card"}]
+ {:total 1}))]
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [content (tools.search/search-tool {:term_queries ["I5"] :created_by "me"}
+ {:token-scopes #{"agent:content:read"}})
+ text (-> content :content first :text)]
+ (is (not (:isError content)) "the call must not 400")
+ (is (= #{"action" "dashboard" "document" "measure" "metric" "model" "question"}
+ (set @captured-entity-types))
+ "the engine only received the creator-indexing types")
+ (is (re-find #"\"name\":\"My I5 Card\"" text))
+ (is (re-find #"created_by narrowed the search to" text)
+ "the narrowing is disclosed in the response text"))))))
+ (testing "collection_id with no type reaches the engine with the narrowed types and discloses it"
+ (let [captured-entity-types (atom nil)]
+ (with-redefs [metabot.search/search (fn [{:keys [entity-types]}]
+ (reset! captured-entity-types entity-types)
+ (with-meta [] {:total 0}))]
+ (mt/with-temp [:model/Collection {coll-id :id} {}]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [content (tools.search/search-tool {:term_queries ["I5"] :collection_id coll-id}
+ {:token-scopes #{"agent:content:read"}})
+ text (-> content :content first :text)]
+ (is (not (:isError content)) "the call must not 400")
+ (is (not (contains? (set @captured-entity-types) "database")))
+ (is (not (contains? (set @captured-entity-types) "measure")))
+ (is (not (contains? (set @captured-entity-types) "segment")))
+ (is (re-find #"collection_id narrowed the search to" text))))))))
+ (testing "archived: true with no type reaches the engine with the narrowed types, does not 400"
+ (let [captured-entity-types (atom nil)]
+ (with-redefs [metabot.search/search (fn [{:keys [entity-types]}]
+ (reset! captured-entity-types entity-types)
+ (with-meta [] {:total 0}))]
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [content (tools.search/search-tool {:term_queries ["x"] :archived true}
+ {:token-scopes #{"agent:content:read"}})
+ text (-> content :content first :text)]
+ (is (not (:isError content)) "the call must not 400")
+ (is (not (contains? (set @captured-entity-types) "table")))
+ (is (not (contains? (set @captured-entity-types) "database")))
+ (is (not (contains? (set @captured-entity-types) "transform")))
+ (is (re-find #"archived: true narrowed the search to" text)))))))
+ (testing "naming an incompatible type explicitly is still a teaching error, and names the offending type"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"Remove database from type"
+ (tools.search/search-tool {:term_queries ["x"] :type ["database"] :created_by "me"}
+ {:token-scopes #{"agent:content:read"}})))))))
diff --git a/test/metabase/mcp/v2/tools/subscription_test.clj b/test/metabase/mcp/v2/tools/subscription_test.clj
new file mode 100644
index 00000000000..794258b721e
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/subscription_test.clj
@@ -0,0 +1,998 @@
+(ns metabase.mcp.v2.tools.subscription-test
+ "Contract tests for the `subscription_write` v2 MCP tool, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised for
+ free."
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [metabase.channel.settings :as channel.settings]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the tool the assertions below drive.
+ [metabase.mcp.v2.tools.subscription :as tools.subscription]
+ [metabase.test :as mt]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(comment tools.subscription/keep-me)
+
+(defn- call-tool!
+ "Returns the whole dispatch outcome: `{:result <mcp content>}` for anything that reached the
+ handler, `{:error {:code .. :message ..}}` for a registry-level rejection (scope denial,
+ args-schema failure)."
+ [user scopes args]
+ (mt/with-current-user (if (keyword? user) (mt/user->id user) user)
+ (registry/call-tool scopes nil "subscription_write" args)))
+
+(defn- dispatch-error?
+ "Whether a [[call-tool!]] outcome is an error, at either layer."
+ [{:keys [result error]}]
+ (boolean (or error (:isError result))))
+
+(defn- response-text
+ "The outcome's text block, or a registry-level rejection's message."
+ [{:keys [result error]}]
+ (if error (:message error) (-> result :content first :text)))
+
+(defn- tool-result
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info (str "tool call failed: " (response-text outcome)) {:outcome outcome})))
+ (-> outcome response-text json/decode+kw))
+
+(defn- tool-error
+ [outcome]
+ (when-not (dispatch-error? outcome)
+ (throw (ex-info "expected a tool error, got success" {:outcome outcome})))
+ (response-text outcome))
+
+(defn- wire
+ "Round-trip through JSON, as the JSON-RPC transport does, so tests can't pass shapes a real
+ client could never send."
+ [x]
+ (-> x json/encode json/decode+kw))
+
+(defn- pulse-channels
+ [pulse-id]
+ (t2/select :model/PulseChannel :pulse_id pulse-id))
+
+(defn- with-slack
+ "Run `thunk` with a configured Slack whose cache holds `#data-team`."
+ [thunk]
+ (mt/with-dynamic-fn-redefs [channel.settings/slack-configured? (constantly true)
+ channel.settings/slack-cached-channels-and-usernames
+ (constantly {:channels [{:display-name "#data-team" :name "data-team" :id "C123"}]})]
+ (thunk)))
+
+;;; ------------------------------------------------- create -------------------------------------------------------
+
+(deftest create-subscription-test
+ (testing "GHY-4156: create schedules a dashboard for delivery and returns the subscription"
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {:name "Revenue"}
+ :model/Dashboard {dash-id :id} {:name "Sales KPIs"}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (let [result (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "daily" :schedule_hour 9}})))]
+ (is (pos-int? (:id result)))
+ (is (= dash-id (:dashboard_id result)))
+ (testing "the subscription is named for the dashboard it delivers"
+ (is (= "Sales KPIs" (:name result))))
+ (testing "concise subscription projection keys only"
+ (is (= #{:id :name :dashboard_id :channels :cards :skip_if_empty :archived :creator_id}
+ (into #{} (keys result)))))
+ (testing "one email channel on the requested schedule"
+ (is (= [{:channel_type "email" :schedule_type "daily" :schedule_hour 9}]
+ (mapv #(select-keys % [:channel_type :schedule_type :schedule_hour])
+ (:channels result)))))
+ (testing "the caller is the default recipient — a subscription with nobody on it is useless"
+ (is (= [(mt/user->id :crowberto)]
+ (mapv :id (-> result :channels first :recipients))))))))))
+
+(deftest create-assembles-cards-from-dashcards-test
+ (testing "GHY-4156: the server assembles the pulse's card list from the dashboard's dashcards,
+ so the agent never has to enumerate them — virtual cards (text, headings) are skipped"
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-1 :id} {:name "Revenue"}
+ :model/Card {card-2 :id} {:name "Costs"}
+ :model/Dashboard {dash-id :id} {:name "Sales KPIs"}
+ :model/DashboardCard {dc-1 :id} {:dashboard_id dash-id :card_id card-1 :row 0 :col 0}
+ :model/DashboardCard {dc-2 :id} {:dashboard_id dash-id :card_id card-2 :row 1 :col 0}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id nil :row 2 :col 0
+ :visualization_settings {:virtual_card {:display "text"}
+ :text "hello"}}]
+ (let [result (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}})))]
+ (is (= [card-1 card-2] (mapv :id (:cards result))))
+ (testing "each pulse card is tied to the dashcard it came from, so the send renders the
+ dashboard's layout rather than bare cards"
+ (is (= #{dc-1 dc-2}
+ (t2/select-fn-set :dashboard_card_id :model/PulseCard :pulse_id (:id result))))))))))
+
+(deftest create-on-an-empty-dashboard-is-a-teaching-error-test
+ (testing "GHY-4156: a dashboard with no cards can't be subscribed to — the pulse API requires at
+ least one card, and the bare 400 doesn't say why"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {:name "Empty"}]
+ (is (re-find #"no cards"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}}))))))))
+
+(deftest create-requires-dashboard-id-test
+ (testing "GHY-4156: create without a dashboard_id is a teaching error, not a schema dump"
+ (is (re-find #"`dashboard_id` is required"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :schedule {:schedule_type "hourly"}})))))))
+
+(deftest create-requires-schedule-test
+ (testing "GHY-4156: create without a schedule is a teaching error"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {}]
+ (is (re-find #"`schedule` is required"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create" :dashboard_id dash-id}))))))))
+
+(deftest update-requires-id-test
+ (testing "GHY-4156: update without an id is a teaching error"
+ (is (re-find #"`id` is required"
+ (tool-error (call-tool! :crowberto nil (wire {:method "update"})))))))
+
+(deftest create-with-explicit-recipients-test
+ (testing "GHY-4156: recipients accept both user ids and raw email addresses, the two shapes the
+ pulse channel stores differently (a recipient row vs. details.emails)"
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {:name "Sales KPIs"}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (let [result (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "daily" :schedule_hour 8}
+ :recipients [(mt/user->id :rasta) "[email protected]"]})))
+ channel (first (pulse-channels (:id result)))]
+ (is (= [(mt/user->id :rasta)]
+ (t2/select-fn-vec :user_id :model/PulseChannelRecipient :pulse_channel_id (:id channel))))
+ (is (= ["[email protected]"] (get-in channel [:details :emails])))
+ (testing "the stored `details.emails` doesn't reach the caller: it's the internal home for
+ recipients who aren't Metabase users, and `recipients` already lists them, so
+ echoing it would name the same person twice in two shapes"
+ (is (= [{:email "[email protected]"} {:id (mt/user->id :rasta) :email "[email protected]"}]
+ (-> result :channels first :recipients)))
+ (is (nil? (-> result :channels first :details)))))))))
+
+(deftest create-slack-subscription-test
+ (testing "GHY-4156: channel \"slack\" resolves the channel name against Slack's cache and stores
+ the display name, which is what the sender reads"
+ (with-slack
+ (fn []
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {:name "Sales KPIs"}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (let [result (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "daily" :schedule_hour 8}
+ :channel "slack"
+ :slack_channel "data-team"})))
+ channel (first (pulse-channels (:id result)))]
+ (is (= :slack (:channel_type channel)))
+ (is (= "#data-team" (get-in channel [:details :channel])))
+ (is (= "C123" (get-in channel [:details :channel_id]))
+ "the sender prefers the id over the name so delivery survives a channel rename"))))))))
+
+(deftest slack-channel-is-required-for-slack-test
+ (testing "GHY-4156: channel \"slack\" without slack_channel is a teaching error, not a channel
+ that silently delivers nowhere"
+ (with-slack
+ (fn []
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (is (re-find #"slack_channel"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :channel "slack"}))))))))))
+
+(deftest unknown-slack-channel-is-a-teaching-error-test
+ (testing "GHY-4156: a Slack channel name Metabase can't see is rejected up front — the send
+ would otherwise fail silently, long after the tool reported success"
+ (with-slack
+ (fn []
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (is (re-find #"nowhere"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :channel "slack"
+ :slack_channel "does-not-exist"}))))))))))
+
+(deftest slack-not-configured-is-a-teaching-error-test
+ (testing "GHY-4156: asking for Slack delivery on an instance with no Slack integration names the fix"
+ (mt/with-dynamic-fn-redefs [channel.settings/slack-configured? (constantly false)]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (is (re-find #"Slack is not connected"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :channel "slack"
+ :slack_channel "data-team"})))))))))
+
+(deftest recipients-are-rejected-for-slack-test
+ (testing "GHY-4156: a Slack channel has no recipient list — passing one would be silently dropped"
+ (with-slack
+ (fn []
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (is (re-find #"recipients"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :channel "slack"
+ :slack_channel "data-team"
+ :recipients ["[email protected]"]}))))))))))
+
+(deftest empty-recipients-is-a-teaching-error-test
+ (testing "GHY-4156: an empty recipient list is the email analogue of an unresolvable Slack
+ channel — the subscription would deliver nowhere, so say so rather than scheduling it"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (is (re-find #"nobody"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :recipients []})))))
+ (testing "and on update, where it would empty a list that currently has people on it"
+ (is (re-find #"nobody"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id :recipients []})))))
+ (is (= [(mt/user->id :rasta)]
+ (t2/select-fn-vec :user_id :model/PulseChannelRecipient :pulse_channel_id pc-id)))))))
+
+(deftest recipients-are-validated-test
+ (testing "GHY-4329: a recipient that is neither an email address nor an active user's id is a
+ teaching error — the same check `alert_write` applies, so a typo comes back as a
+ sentence instead of landing in the channel as a malformed row"
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (testing "a string that isn't an email address"
+ (is (re-find #"neither a user id nor an email address"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :recipients ["data-team"]}))))))
+ (testing "a user id nobody has — named as the id it is, rather than surfacing as the FK
+ violation the insert would otherwise be"
+ (is (re-find #"No active user with id 13371337"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :recipients [13371337]}))))))
+ (testing "on update too, and the stored recipients are left alone"
+ (is (re-find #"neither a user id nor an email address"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id
+ :recipients ["ops at example.com"]})))))
+ (is (= [(mt/user->id :rasta)]
+ (t2/select-fn-vec :user_id :model/PulseChannelRecipient :pulse_channel_id pc-id)))
+ (is (empty? (:emails (t2/select-one-fn :details :model/PulseChannel :id pc-id)))))))))
+
+;;; ------------------------------------------------ schedules -----------------------------------------------------
+
+(deftest incomplete-schedules-are-teaching-errors-test
+ (testing "GHY-4156: the pulse channel's schedule validation is an assertion — every incomplete
+ schedule reaches the caller as a sentence naming the missing field instead"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (are [schedule pattern]
+ (re-find pattern
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule schedule}))))
+ {:schedule_type "daily"} #"schedule_hour"
+ {:schedule_type "weekly" :schedule_hour 9} #"schedule_day"
+ {:schedule_type "monthly" :schedule_hour 9} #"schedule_frame"
+ {:schedule_type "monthly" :schedule_hour 9
+ :schedule_frame "mid" :schedule_day "mon"} #"schedule_day"))))
+
+(deftest monthly-schedule-test
+ (testing "GHY-4156: a monthly schedule stores frame and day — \"the first Monday of the month\""
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (let [result (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "monthly"
+ :schedule_hour 9
+ :schedule_frame "first"
+ :schedule_day "mon"}})))]
+ (is (= {:schedule_type :monthly :schedule_hour 9 :schedule_frame :first :schedule_day "mon"}
+ (-> (first (pulse-channels (:id result)))
+ (select-keys [:schedule_type :schedule_hour :schedule_frame :schedule_day])))))))))
+
+;;; ------------------------------------------------ parameters ----------------------------------------------------
+
+(deftest create-with-parameters-test
+ ;; `enable-dashboard-subscription-filters?` is `(and config/ee-available? (has-feature? ...))`, so
+ ;; on an OSS build the feature reads false whatever the token says and the call fails on the
+ ;; feature refusal instead. Guard the whole body out, as `redaction_test` does for the same reason.
+ (mt/when-ee-evailable
+ (testing "GHY-4156: parameters make a filtered subscription — only {id, value} is stored, and the
+ dashboard's own definition of that parameter is merged in at send time"
+ (mt/with-premium-features #{:dashboard-subscription-filters}
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {:parameters [{:id "cat" :name "Category"
+ :type "string/=" :slug "category"}]}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (let [result (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :parameters [{:id "cat" :value "Gadget"}]})))]
+ (is (= [{:id "cat" :value "Gadget"}]
+ (t2/select-one-fn :parameters :model/Pulse :id (:id result)))))))))))
+
+(deftest parameters-need-the-subscription-filters-feature-test
+ (testing "without the dashboard-subscription-filters feature the send-time merge is the OSS no-op, so the
+ values would be stored and then ignored — refuse rather than report a filter that never applies"
+ (mt/with-premium-features #{}
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {:parameters [{:id "cat" :name "Category"
+ :type "string/=" :slug "category"}]}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (is (re-find #"dashboard-subscription-filters"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :parameters [{:id "cat" :value "Gadget"}]})))))
+ (testing "a subscription with no parameters is unaffected"
+ (is (some? (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}})))))))))))
+
+(deftest unknown-parameter-id-is-a-teaching-error-test
+ ;; Same OSS guard as `create-with-parameters-test` above: the feature getter is gated on
+ ;; `config/ee-available?`, which `with-premium-features` cannot flip.
+ (mt/when-ee-evailable
+ (testing "GHY-4156: a parameter id the dashboard doesn't have would be stored and then silently
+ ignored at send time, so it's rejected up front with the ids that do exist"
+ ;; `resolve-parameters` refuses any `parameters` at all without this feature, and that check runs
+ ;; first — without it the call fails on the feature, never reaching the unknown-id check this pins.
+ (mt/with-premium-features #{:dashboard-subscription-filters}
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {:parameters [{:id "cat" :name "Category"
+ :type "string/=" :slug "category"}]}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (let [err (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}
+ :parameters [{:id "nope" :value "x"}]})))]
+ (is (re-find #"nope" err))
+ (is (re-find #"cat" err))))))))
+
+;;; ------------------------------------------------- update -------------------------------------------------------
+
+(deftest email-channel-keeps-its-details-and-refuses-slack-channel-test
+ (testing "an email subscription's stored details (attach PDF, attachment-only) survive an edit that does
+ not mention them, and slack_channel is refused rather than silently ignored on an email target"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}
+ :model/Pulse {pulse-id :id} {:name "PDF weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15
+ :details {:include_pdf true}}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update"
+ :id pulse-id
+ :schedule {:schedule_type "daily" :schedule_hour 7}})))
+ (is (true? (:include_pdf (t2/select-one-fn :details :model/PulseChannel :id pc-id)))
+ "a schedule-only edit must not erase the channel's format details")
+ (testing "slack_channel on an email target is a teaching error, not a silent no-op"
+ (is (re-find #"slack_channel"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id :slack_channel "data-team"})))))
+ (is (= :email (t2/select-one-fn :channel_type :model/PulseChannel :id pc-id))))
+ (testing "and on create, where the channel defaults to email"
+ (is (re-find #"slack_channel"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "daily" :schedule_hour 9}
+ :slack_channel "data-team"})))))))))
+
+(deftest update-schedule-patches-the-existing-channel-test
+ (testing "GHY-4156: changing the schedule edits the subscription's channel in place — a
+ rebuilt channel would drop its recipients and re-register its send trigger"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update"
+ :id pulse-id
+ :schedule {:schedule_type "weekly" :schedule_hour 7
+ :schedule_day "fri"}})))
+ (let [channels (pulse-channels pulse-id)]
+ (is (= 1 (count channels)))
+ (is (= pc-id (:id (first channels))))
+ (is (= {:schedule_type :weekly :schedule_hour 7 :schedule_day "fri"}
+ (select-keys (first channels) [:schedule_type :schedule_hour :schedule_day])))
+ (testing "recipients the caller didn't mention are left alone"
+ (is (= [(mt/user->id :rasta)]
+ (t2/select-fn-vec :user_id :model/PulseChannelRecipient :pulse_channel_id pc-id))))))))
+
+(deftest update-recipients-test
+ (testing "GHY-4156: recipients on update replace the channel's list — the tool has no
+ add/remove verbs, so the list the caller sends is the list that ends up stored"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update"
+ :id pulse-id
+ :recipients [(mt/user->id :lucky)]})))
+ (is (= [(mt/user->id :lucky)]
+ (t2/select-fn-vec :user_id :model/PulseChannelRecipient :pulse_channel_id pc-id))))))
+
+(deftest update-adds-a-second-channel-test
+ (testing "GHY-4156: naming a channel type the subscription doesn't have yet adds it, leaving the
+ existing one alone — the same subscription can go to email and Slack"
+ (with-slack
+ (fn []
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update"
+ :id pulse-id
+ :channel "slack"
+ :slack_channel "data-team"
+ :schedule {:schedule_type "hourly"}})))
+ (is (= #{:email :slack} (into #{} (map :channel_type) (pulse-channels pulse-id)))))))))
+
+(deftest update-without-a-channel-on-a-multi-channel-subscription-test
+ (testing "GHY-4156: with more than one channel the tool can't guess which to edit, so it asks
+ rather than picking one or flattening the subscription to a single channel"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :slack
+ :details {:channel "#x"}
+ :schedule_type :daily :schedule_hour 15}]
+ (is (re-find #"`channel`"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update"
+ :id pulse-id
+ :schedule {:schedule_type "hourly"}}))))))))
+
+(deftest update-archived-round-trip-test
+ (testing "GHY-4156: archived true pauses the subscription and false resumes it — the only
+ removal path, matching how the product pauses subscriptions"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (is (true? (:archived (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id :archived true}))))))
+ (is (true? (t2/select-one-fn :archived :model/Pulse :id pulse-id)))
+ (tool-result (call-tool! :crowberto nil (wire {:method "update" :id pulse-id :archived false})))
+ (is (false? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))))
+
+(deftest archived-subscriptions-stay-paused-test
+ (testing "GHY-4156: a Pulse encodes \"archived\" by disabling its channels, and the channel write
+ lands after the Pulse write — so a channel edit in the same call, or any edit to an
+ already-archived subscription, must not leave a channel enabled. An enabled channel
+ re-registers the send trigger and the subscription keeps delivering from the trash."
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannel {sc-id :id} {:pulse_id pulse-id :channel_type :slack
+ :details {:channel "#ops"}
+ :schedule_type :daily :schedule_hour 15}]
+ (testing "archiving and editing a channel in one call disables every channel"
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update"
+ :id pulse-id
+ :archived true
+ :channel "email"
+ :schedule {:schedule_type "weekly" :schedule_hour 7
+ :schedule_day "fri"}})))
+ (testing "including the channel that only rode along"
+ (is (= [false false]
+ (mapv :enabled (sort-by :id [(t2/select-one :model/PulseChannel :id pc-id)
+ (t2/select-one :model/PulseChannel :id sc-id)]))))))
+ (testing "a later schedule-only edit doesn't quietly resume it"
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update"
+ :id pulse-id
+ :channel "email"
+ :schedule {:schedule_type "hourly"}})))
+ (is (true? (t2/select-one-fn :archived :model/Pulse :id pulse-id)))
+ (is (false? (t2/select-one-fn :enabled :model/PulseChannel :id pc-id))))
+ (testing "unarchiving re-enables the channels"
+ (tool-result (call-tool! :crowberto nil (wire {:method "update" :id pulse-id :archived false})))
+ (is (true? (t2/select-one-fn :enabled :model/PulseChannel :id pc-id)))))))
+
+(deftest unarchiving-while-editing-a-channel-re-enables-it-test
+ (testing "GHY-4156: `archived` false alongside a channel edit resumes delivery — the channel
+ write must not restore the disabled state the Pulse write just cleared"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)
+ :archived true}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :enabled false
+ :schedule_type :daily :schedule_hour 15}]
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update"
+ :id pulse-id
+ :archived false
+ :schedule {:schedule_type "weekly" :schedule_hour 7
+ :schedule_day "fri"}})))
+ (is (false? (t2/select-one-fn :archived :model/Pulse :id pulse-id)))
+ (is (true? (t2/select-one-fn :enabled :model/PulseChannel :id pc-id))))))
+
+(deftest update-skip-if-empty-test
+ (testing "GHY-4156: skip_if_empty suppresses the send when the dashboard has no results"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)
+ :skip_if_empty false}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (is (true? (:skip_if_empty
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id :skip_if_empty true})))))))))
+
+(deftest update-leaves-cards-alone-test
+ (testing "GHY-4156: an update that doesn't mention cards leaves the pulse's card list untouched —
+ the card list is assembled once, at create"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (tool-result (call-tool! :crowberto nil (wire {:method "update" :id pulse-id :skip_if_empty true})))
+ (is (= [card-id] (t2/select-fn-vec :card_id :model/PulseCard :pulse_id pulse-id))))))
+
+(deftest entity-id-is-accepted-test
+ (testing "GHY-4156: `id` accepts a 21-character entity_id as well as a numeric id"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse pulse {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id (:id pulse) :card_id card-id}
+ :model/PulseChannel _ {:pulse_id (:id pulse) :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (is (= (:id pulse)
+ (:id (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id (:entity_id pulse)
+ :skip_if_empty true})))))))))
+
+(deftest dashboard-id-accepts-entity-id-test
+ (testing "GHY-4156: `dashboard_id` accepts an entity_id, like every other id argument in v2"
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard dash {:name "Sales KPIs"}
+ :model/DashboardCard _ {:dashboard_id (:id dash) :card_id card-id}]
+ (is (= (:id dash)
+ (:dashboard_id (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id (:entity_id dash)
+ :schedule {:schedule_type "hourly"}}))))))))))
+
+;;; ------------------------------------------------ permissions ---------------------------------------------------
+
+(deftest alerts-are-not-subscriptions-test
+ (testing "GHY-4156: an alert lives in the same id space as subscriptions but is a different
+ concept with its own tool — targeting one collapses to not-found"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Alert" :alert_condition "rows"
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}]
+ (is (re-find #"not found"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id :archived true}))))))))
+
+(deftest update-requires-write-permission-test
+ (testing "GHY-4156: a non-admin can only edit subscriptions they created — someone else's is
+ readable (they're a recipient) but not writable, and nothing changes"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (is (re-find #"not found"
+ (tool-error (call-tool! :rasta nil
+ (wire {:method "update" :id pulse-id :archived true}))))
+ "the refusal must be the collapsed not-found, not a distinguishable 403 — rasta is a
+ recipient, so a 403 here would tell subscriptions she is a target of apart from ids
+ she knows nothing about")
+ (is (false? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))))
+
+(deftest update-is-write-checked-before-it-computes-anything-test
+ (testing "GHY-4217: `mi/can-read?` on a subscription is (or superuser? creator? recipient?), a
+ weaker gate than can-write?, so everything update! does before the pulse API's own
+ write check would otherwise run for a mere recipient. Being on the recipient list must
+ buy nothing: not the dashboard's parameter vocabulary, not user existence, not the
+ channel topology — and every rejection must be the same collapsed not-found an
+ unrelated id gets, so the responses can't be walked into an existence oracle."
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:collection_id coll-id}
+ :model/Dashboard {dash-id :id} {:collection_id coll-id
+ :parameters [{:id "secret_param" :name "Department"
+ :type "string/=" :slug "department"}]}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}
+ :model/Pulse {pulse-id :id} {:name "Confidential weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (let [unrelated-id (inc (or (t2/select-one-pk :model/Pulse {:order-by [[:id :desc]]}) 0))
+ baseline (tool-error (call-tool! :rasta nil
+ (wire {:method "update" :id unrelated-id :archived true})))]
+ (testing "an unknown parameter id does not disclose the dashboard's parameter vocabulary"
+ (let [err (tool-error (call-tool! :rasta nil
+ (wire {:method "update" :id pulse-id
+ :parameters [{:id "zzz" :value 1}]})))]
+ (is (not (re-find #"secret_param" err)))
+ (is (re-find #"not found" err))))
+ (testing "a recipient id does not disclose whether that user exists and is active"
+ (is (re-find #"not found"
+ (tool-error (call-tool! :rasta nil
+ (wire {:method "update" :id pulse-id
+ :recipients [Integer/MAX_VALUE]}))))))
+ (testing "the rejection is byte-identical to the one an id she knows nothing about gets"
+ (is (= (str/replace baseline (str unrelated-id) "<id>")
+ (str/replace (tool-error (call-tool! :rasta nil
+ (wire {:method "update" :id pulse-id :archived true})))
+ (str pulse-id) "<id>"))))
+ (is (false? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))))))
+
+(deftest a-schedule-field-the-type-ignores-is-a-teaching-error-test
+ (testing "the pulse channel writer nils out a schedule field the type doesn't read, so
+ {hourly, schedule_hour 9} would deliver 24 times a day while the call reports success.
+ Kept in step with alert_write, which refuses the same shapes."
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (doseq [[schedule ignored] [[{:schedule_type "hourly" :schedule_hour 9} "schedule_hour"]
+ [{:schedule_type "daily" :schedule_hour 9
+ :schedule_day "mon"} "schedule_day"]
+ [{:schedule_type "weekly" :schedule_hour 9 :schedule_day "mon"
+ :schedule_frame "first"} "schedule_frame"]]]
+ (testing (pr-str schedule)
+ ;; `tool-error` throws on an unexpected success, which would abort the whole doseq and
+ ;; report only the first regressed schedule type. Read the outcome directly so each
+ ;; case is asserted independently.
+ (let [outcome (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule schedule}))
+ err (response-text outcome)]
+ (is (dispatch-error? outcome) "the surplus field must be refused, not silently dropped")
+ (is (re-find (re-pattern ignored) err))
+ (is (re-find #"would be ignored" err)))))
+ (testing "an explicit null is an omission, not a request, so it is not refused"
+ (is (some? (tool-result (call-tool! :crowberto nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"
+ :schedule_hour nil}}))))))))))
+
+(deftest slack-channel-keeps-its-details-on-repoint-test
+ (testing "the pulse-channel update rewrites :details wholesale, so repointing a Slack
+ subscription has to merge onto what is stored — otherwise include_pdf set in the app is
+ erased and the next send silently drops the PDF"
+ (with-slack
+ (fn []
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}
+ :model/Pulse {pulse-id :id} {:name "Slack weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :slack
+ :schedule_type :daily :schedule_hour 15
+ :details {:channel "#old-team"
+ :channel_id "COLD999"
+ :include_pdf true}}]
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id :slack_channel "data-team"})))
+ (let [details (t2/select-one-fn :details :model/PulseChannel :id pc-id)]
+ (is (= "#data-team" (:channel details)))
+ (is (true? (:include_pdf details))
+ "the format details the app set must survive a repoint")
+ (is (= "C123" (:channel_id details))
+ "the stale channel_id must be replaced by the new channel's, not left behind")))))))
+
+(deftest create-requires-dashboard-read-permission-test
+ (testing "GHY-4156: subscribing to a dashboard you can't read is refused — a subscription would
+ otherwise be a channel for exfiltrating its contents"
+ (mt/with-non-admin-groups-no-root-collection-perms
+ (mt/with-temp [:model/Collection {coll-id :id} {}
+ :model/Card {card-id :id} {:collection_id coll-id}
+ :model/Dashboard {dash-id :id} {:collection_id coll-id}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (is (some? (tool-error (call-tool! :rasta nil
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}})))))
+ (is (zero? (t2/count :model/Pulse :dashboard_id dash-id)))))))
+
+(deftest query-execute-scope-gates-deferred-execution-test
+ (testing "a subscription is a scheduled run of the dashboard's questions with results delivered,
+ so a token that can't execute queries in-session can't schedule it either — the send
+ happens later, tokenlessly, under the creator's permissions. Mirrors alert_write."
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {:name "Sales KPIs"}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (let [write-only #{"agent:delivery:write"}]
+ (testing "create with only the write scope is refused, naming the missing scope"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}}))))))
+ (testing "redirecting delivery with only the write scope is refused"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only
+ (wire {:method "update" :id pulse-id
+ :recipients ["[email protected]"]}))))))
+ (testing "but pausing with only the write scope still works — the kill switch must never
+ need more scope than the thing it kills (the response is the GHY-4217 ack, so
+ the effect is asserted from the database)"
+ (is (= pulse-id (:id (tool-result (call-tool! :crowberto write-only
+ (wire {:method "update" :id pulse-id
+ :archived true}))))))
+ (is (true? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))))))
+
+;; TODO(slice-17/query): restore when the execute_sql/query tool lands and registers agent:query:run.
+;; The live scope-gating assertions stay in the test above; only this grantability check needs the
+;; query tool present in the registry.
+#_(deftest query-execute-scope-is-grantable-test
+ (testing "the scope the gate needs is grantable — it reaches the default DCR grant as
+ execute_query's own scope, so a client holding the default grant can satisfy the gate"
+ (is (contains? (registry/registered-scopes) "agent:query:run"))))
+
+(deftest restoring-and-rescheduling-gate-on-query-execute-test
+ (testing "restoring a trashed subscription starts the sends again, and a new schedule changes how
+ often they happen — both commit the scheduler to running the dashboard's questions, so
+ both need the execute scope. Only trashing stays free: a kill switch must never need
+ more scope than the thing it kills"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {:name "Sales KPIs"}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (let [write-only #{"agent:delivery:write"}
+ with-exec #{"agent:delivery:write" "agent:query:run"}]
+ (testing "trashing needs no execute scope"
+ (is (= pulse-id (:id (tool-result (call-tool! :crowberto write-only
+ (wire {:method "update" :id pulse-id
+ :archived true}))))))
+ (is (true? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))
+ (testing "restoring it is refused, naming the missing scope, and it stays trashed"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only
+ (wire {:method "update" :id pulse-id :archived false})))))
+ (is (true? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))
+ (testing "with the execute scope the restore goes through"
+ (is (= pulse-id (:id (tool-result (call-tool! :crowberto with-exec
+ (wire {:method "update" :id pulse-id
+ :archived false}))))))
+ (is (false? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))
+ (testing "raising a daily subscription to hourly is refused, and the schedule is untouched"
+ (is (re-find #"agent:query:run"
+ (tool-error (call-tool! :crowberto write-only
+ (wire {:method "update" :id pulse-id
+ :schedule {:schedule_type "hourly"}})))))
+ (is (= [:daily] (mapv :schedule_type (pulse-channels pulse-id)))))
+ (testing "and goes through with the execute scope"
+ (is (= pulse-id (:id (tool-result (call-tool! :crowberto with-exec
+ (wire {:method "update" :id pulse-id
+ :schedule {:schedule_type "hourly"}}))))))
+ (is (= [:hourly] (mapv :schedule_type (pulse-channels pulse-id)))))))))
+
+(deftest scope-gates-the-tool-test
+ (testing "GHY-4156: a token without the subscribe scope can't call the tool at all"
+ (mt/with-temp [:model/Dashboard {dash-id :id} {}]
+ (is (re-find #"Insufficient scope"
+ (tool-error (call-tool! :crowberto #{"agent:content:read"}
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}}))))))))
+
+(deftest one-write-scope-covers-both-methods-test
+ (testing "GHY-4156: `agent:delivery:write` gates both methods, and the v1 `agent:dashboard:subscribe`
+ no longer reaches the v2 tool (it stays declared because MCP v1's own subscription tools
+ still use it)"
+ (mt/with-model-cleanup [:model/Pulse]
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {:name "Sales KPIs"}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (let [write-scope #{"agent:delivery:write"}]
+ (testing "create"
+ ;; create additionally needs query:execute (it establishes scheduled execution);
+ ;; the write scope under test still gates the method itself.
+ (is (pos-int? (:id (tool-result (call-tool! :crowberto (conj write-scope "agent:query:run")
+ (wire {:method "create"
+ :dashboard_id dash-id
+ :schedule {:schedule_type "hourly"}})))))))
+ (testing "update"
+ ;; the bare write scope gets the GHY-4217 ack back, so assert the effect from the db
+ (is (= pulse-id (:id (tool-result (call-tool! :crowberto write-scope
+ (wire {:method "update" :id pulse-id
+ :archived true}))))))
+ (is (true? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))
+ (testing "the v1 subscribe scope alone is refused, and nothing changes"
+ (is (re-find #"Insufficient scope"
+ (tool-error (call-tool! :crowberto #{"agent:dashboard:subscribe"}
+ (wire {:method "update" :id pulse-id
+ :archived false})))))
+ (is (true? (t2/select-one-fn :archived :model/Pulse :id pulse-id)))))))))
+
+(deftest null-args-are-dropped-at-the-boundary-test
+ (testing "GHY-4156: strict clients fill every declared property they aren't setting with null;
+ those are stripped before the handler, so an update that means to change one field
+ doesn't clobber the rest — in particular the channel is left entirely alone"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)
+ :skip_if_empty false}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel {pc-id :id} {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pc-id
+ :user_id (mt/user->id :rasta)}]
+ (tool-result (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id :skip_if_empty true
+ :schedule nil :channel nil :slack_channel nil
+ :recipients nil :parameters nil :archived nil})))
+ (is (true? (t2/select-one-fn :skip_if_empty :model/Pulse :id pulse-id)))
+ (is (= {:schedule_type :daily :schedule_hour 15}
+ (select-keys (first (pulse-channels pulse-id)) [:schedule_type :schedule_hour])))
+ (is (= [(mt/user->id :rasta)]
+ (t2/select-fn-vec :user_id :model/PulseChannelRecipient :pulse_channel_id pc-id)))
+ (is (false? (t2/select-one-fn :archived :model/Pulse :id pulse-id))))))
+
+(deftest update-with-nothing-to-change-is-a-teaching-error-test
+ (testing "GHY-4156: an update naming no field at all is the agent losing track of what it meant
+ to change — say so rather than reporting success for a write that never happened"
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :email
+ :schedule_type :daily :schedule_hour 15}]
+ (is (re-find #"Nothing to update"
+ (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id}))))))))
+
+(deftest webhook-channel-is-a-teaching-error-test
+ (testing "a subscription whose only channel is a webhook (`:http`, a real PulseChannel type this
+ tool cannot edit) must be refused with a teaching error. `target-channel-type` derives
+ the channel from the existing one when there is exactly one, so \"http\" reaches
+ `build-channel` — whose `case` covers only email and slack and would otherwise throw a
+ bare IllegalArgumentException the agent can do nothing with."
+ (mt/with-temp [:model/Card {card-id :id} {}
+ :model/Dashboard {dash-id :id} {}
+ :model/Pulse {pulse-id :id} {:name "Weekly" :dashboard_id dash-id
+ :creator_id (mt/user->id :crowberto)}
+ :model/PulseCard _ {:pulse_id pulse-id :card_id card-id}
+ :model/PulseChannel _ {:pulse_id pulse-id :channel_type :http
+ :schedule_type :daily :schedule_hour 15}]
+ (let [err (tool-error (call-tool! :crowberto nil
+ (wire {:method "update" :id pulse-id
+ :schedule {:schedule_type "hourly"}})))]
+ (testing "the message names the channel and what the tool does support"
+ (is (re-find #"(?i)webhook|http" err))
+ (is (re-find #"(?i)email" err)))
+ (testing "it is a teaching error, not a leaked class name"
+ (is (not (re-find #"IllegalArgumentException|No matching clause" err))))))))
diff --git a/test/metabase/mcp/v2/tools/transform_test.clj b/test/metabase/mcp/v2/tools/transform_test.clj
new file mode 100644
index 00000000000..8c69781a2e1
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/transform_test.clj
@@ -0,0 +1,874 @@
+(ns metabase.mcp.v2.tools.transform-test
+ "Contract tests for the `transform_write` v2 MCP tool, driven through
+ [[metabase.mcp.v2.registry/call-tool]] — the same seam the JSON-RPC route uses — so scope
+ gating, nil-arg stripping, Malli validation, and teaching-error conversion are exercised for
+ free. The transform write/permission stack itself is owned by `metabase.transforms.*`; this
+ suite pins the tool's own contract on top of it: the query sources, the target patch, the two
+ shapes it refuses to author (python sources, incremental targets), and the readback gate."
+ (:require
+ [clojure.test :refer :all]
+ [metabase.driver :as driver]
+ [metabase.lib.core :as lib]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ ;; Registers the :transform projection the write echo projects through.
+ [metabase.mcp.v2.tools.content :as tools.content]
+ [metabase.mcp.v2.tools.transform :as tools.transform]
+ [metabase.models.interface :as mi]
+ [metabase.permissions.models.data-permissions :as data-perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util.json :as json]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db))
+
+;; TODO(slice-17/query): re-add tools.query/keep-me when the query tool lands.
+(comment tools.content/keep-me tools.transform/keep-me)
+
+;;; ------------------------------------------------- Harness ------------------------------------------------------
+
+(def ^:private write-scopes
+ "The scope transform_write is gated on, plus the one reading a transform back demands — without
+ it the tool answers with the GHY-4217 minimal ack instead of the row."
+ #{"agent:content:write" "agent:content:read"})
+
+(defn- call-tool!
+ "Drive `tool` through the real dispatch seam as `user` with bearer-style `scopes` (nil = internal
+ caller, which bypasses the scope gate). `session-id` is fresh per call unless the caller threads
+ one through, so query handles are scoped like a real client's.
+
+ `call-tool` answers `{:result …}` once a handler ran, or `{:error …}` when the registry rejects
+ the call before dispatch. Both are presented here in the `{:isError true}` MCP shape a handler
+ error takes, so the helpers below read a refusal as a value without knowing which layer refused."
+ ([user scopes tool args] (call-tool! user scopes tool args (str (random-uuid))))
+ ([user scopes tool args session-id]
+ (mt/with-current-user (mt/user->id user)
+ (let [{:keys [result error]} (registry/call-tool scopes session-id tool args)]
+ (if error
+ {:isError true :content [{:type "text" :text (:message error)}]}
+ result)))))
+
+(defn- write!
+ "Call `transform_write` as an admin holding the write and read-back scopes."
+ ([args] (write! :crowberto write-scopes args))
+ ([user scopes args] (call-tool! user scopes "transform_write" args)))
+
+(defn- tool-result
+ "Decoded success payload of a tool response; throws when the call errored, so a tool-level
+ error can never masquerade as a result."
+ [response]
+ (when (:isError response)
+ (throw (ex-info (str "tool call failed: " (-> response :content first :text))
+ {:response response})))
+ (-> response :content first :text json/decode+kw))
+
+(defn- tool-error
+ "Tool-level error text of a tool response; throws when the call succeeded, so a passing call
+ can never satisfy an error assertion."
+ [response]
+ (when-not (:isError response)
+ (throw (ex-info "expected a tool error, got success" {:response response})))
+ (-> response :content first :text))
+
+(defmacro ^:private with-transforms
+ "Turn on the transforms feature and its setting. The transform read/write checks gate on both
+ before the superuser bypass, so without them every transform collapses to not-found."
+ [& body]
+ `(mt/with-premium-features #{:transforms-basic}
+ (mt/with-temp-env-var-value! [~'mb-transforms-enabled true]
+ ~@body)))
+
+(defmacro ^:private with-target-db-support
+ "Claim `:transforms/table` for whatever driver the test database runs on. The REST create/update
+ check stack demands the feature of the target database, and H2 — which this suite deliberately
+ stays on, so the mcp module keeps out of the driver-test set — doesn't declare it.
+
+ Touches the test database first, to force the driver namespace to load outside the `with-redefs`:
+ the redef swaps a multimethod var for a plain fn, and a driver loading inside that extent would
+ hit `defmethod` on something it can't cast, taking the whole suite's database down with it. Only
+ reachable when this namespace runs first in a JVM, which is exactly how it runs alone."
+ [& body]
+ `(let [_# (mt/db)
+ orig# driver/database-supports?]
+ (with-redefs [driver/database-supports? (fn [driver# feature# database#]
+ (or (= feature# :transforms/table)
+ (orig# driver# feature# database#)))]
+ ~@body)))
+
+(defn- venues-schema []
+ (t2/select-one-fn :schema :model/Table :id (mt/id :venues)))
+
+(defn- venues-query
+ "A legacy-MBQL query over venues, the shape a transform's `definition` carries."
+ []
+ {:database (mt/id) :type "query" :query {:source-table (mt/id :venues)}})
+
+(defn- query-definition []
+ {:type "query" :query (venues-query)})
+
+(defn- temp-transform-defaults
+ "A stored query transform writing to `table-name`."
+ [table-name]
+ {:name "existing"
+ :source {:type :query :query (venues-query)}
+ :target {:type :table :schema (venues-schema) :name table-name}})
+
+;;; -------------------------------------------------- Create ------------------------------------------------------
+
+(deftest transform-write-create-test
+ (testing "GHY-4240: create stores the query transform and echoes the concise read projection"
+ (with-transforms
+ (with-target-db-support
+ (let [result (tool-result (write! {:method "create"
+ :name "Gadget products"
+ :description "Only the gadgets"
+ :definition (query-definition)
+ :target {:name "mcp_gadget_products" :schema (venues-schema)}}))
+ stored (t2/select-one :model/Transform :id (:id result))]
+ (try
+ (testing "the echo carries the read projection plus the ids and url a follow-up call needs"
+ (is (= "Gadget products" (:name result)))
+ (is (= "Only the gadgets" (:description result)))
+ (is (= "mbql" (:source_type result)))
+ (is (= {:type "table" :schema (venues-schema) :name "mcp_gadget_products" :database (mt/id)}
+ (:target result)))
+ (is (= [] (:tag_ids result)))
+ (is (string? (:entity_id result)))
+ (is (re-find #"/data-studio/transforms/\d+$" (:url result))))
+ (testing "and the transform is really stored"
+ (is (some? stored))
+ (is (= :mbql (:source_type stored)))
+ (is (= (mt/user->id :crowberto) (:creator_id stored))))
+ (finally
+ (t2/delete! :model/Transform :id (:id result)))))))))
+
+(defn- native-definition
+ "An inline definition carrying raw SQL — the shape an agent that can write content but may not
+ author SQL must not be able to store."
+ []
+ {:type "query" :query {:database (mt/id) :type "native" :native {:query "SELECT 1 AS x"}}})
+
+;; not ^:parallel: mt/with-temporary-setting-values on the shared kill-switch setting
+(deftest transform-write-native-definition-gates-test
+ (testing "an inline native `definition` passes execute_sql's two gates — the agent:sql:run scope and the
+ mcp-execute-sql-enabled kill switch — because a stored native transform is raw SQL the runner
+ later executes against the warehouse; accepting it under the content write scope alone would
+ rebuild execute_sql, with a warehouse write on top, without either gate"
+ (with-transforms
+ (with-target-db-support
+ (let [args {:method "create"
+ :name "Native gadget"
+ :definition (native-definition)
+ :target {:name "mcp_native_gadget" :schema (venues-schema)}}
+ stored? #(pos? (t2/count :model/Transform :name "Native gadget"))]
+ (try
+ (testing "the content write scope alone is refused, naming the missing SQL scope"
+ (let [response (write! :crowberto write-scopes args)]
+ (is (re-find #"agent:sql:run" (tool-error response)))
+ (is (not (stored?)))))
+ (testing "with the SQL scope, the kill switch still refuses"
+ (mt/with-temporary-setting-values [mcp-execute-sql-enabled false]
+ (let [response (write! :crowberto (conj write-scopes "agent:sql:run") args)]
+ (is (re-find #"mcp-execute-sql-enabled" (tool-error response)))
+ (is (not (stored?))))))
+ (testing "with the SQL scope and the switch on, the native transform is stored"
+ (let [result (tool-result (write! :crowberto (conj write-scopes "agent:sql:run") args))]
+ (is (= "native" (:source_type result)))
+ (is (= :native (t2/select-one-fn :source_type :model/Transform :id (:id result))))))
+ (testing "a plain MBQL definition is unaffected: the content write scope alone still creates it"
+ (let [result (tool-result (write! :crowberto write-scopes
+ (assoc args :name "Plain gadget"
+ :definition (query-definition)
+ :target {:name "mcp_plain_gadget" :schema (venues-schema)})))]
+ (is (= "mbql" (:source_type result)))))
+ (finally
+ (t2/delete! :model/Transform :name [:in ["Native gadget" "Plain gadget"]]))))))))
+
+(deftest transform-write-create-runs-the-permission-check-test
+ (testing "GHY-4240: `api/create-check` is the only thing between a caller and a transform on a database
+ they have no transforms/native-write permission for — `transforms/create-transform!` performs no
+ check of its own. Every other test here runs as :crowberto, for whom the check is vacuous, so
+ deleting the line would leave the suite green."
+ (with-transforms
+ (with-target-db-support
+ (mt/with-no-data-perms-for-all-users!
+ (let [args {:method "create"
+ :name "Perm probe transform"
+ :definition (query-definition)
+ :target {:name "mcp_perm_probe" :schema (venues-schema)}}]
+ (is (some? (tool-error (write! :rasta write-scopes args))))
+ (is (zero? (t2/count :model/Transform :name "Perm probe transform"))
+ "nothing is written when the check refuses")))))))
+
+(deftest transform-write-create-required-args-test
+ (testing "GHY-4240: the create-only requirements are teaching errors naming the missing field"
+ (with-transforms
+ (is (re-find #"`name` is required when method is \"create\""
+ (tool-error (write! {:method "create" :definition (query-definition)
+ :target {:name "x" :schema (venues-schema)}}))))
+ (is (re-find #"`target` is required when method is \"create\""
+ (tool-error (write! {:method "create" :name "x" :definition (query-definition)}))))
+ (testing "and a target without a name is caught before anything is written"
+ (is (re-find #"`target.name` is required"
+ (tool-error (write! {:method "create" :name "x" :definition (query-definition)
+ :target {:schema (venues-schema)}}))))))))
+
+(deftest transform-write-query-source-test
+ (testing "GHY-4240: exactly one query source, named in both directions"
+ (with-transforms
+ (testing "neither"
+ (is (re-find #"Pass the transform's query"
+ (tool-error (write! {:method "create" :name "x"
+ :target {:name "y" :schema (venues-schema)}})))))
+ (testing "both"
+ (let [error (tool-error (write! {:method "create"
+ :name "x"
+ :definition (query-definition)
+ :query_handle (str (random-uuid))
+ :target {:name "y" :schema (venues-schema)}}))]
+ (is (re-find #"exactly one query source" error)))))))
+
+(deftest transform-write-refuses-shapes-it-cannot-author-test
+ (testing "GHY-4240: a source kind the tool can't author is refused, not silently degraded"
+ (with-transforms
+ (testing "a python definition"
+ (let [error (tool-error (write! {:method "create"
+ :name "x"
+ :definition {:type "python"
+ :body "def transform(): pass"
+ :source-tables []
+ :source-database (mt/id)}
+ :target {:name "y" :schema (venues-schema)}}))]
+ (is (re-find #"python transform" error))
+ (is (re-find #"query transforms only" error))))
+ (testing "an incremental loading strategy on the source"
+ (let [error (tool-error (write! {:method "create"
+ :name "x"
+ :definition (assoc (query-definition)
+ :source-incremental-strategy
+ {:type "checkpoint"})
+ :target {:name "y" :schema (venues-schema)}}))]
+ (is (re-find #"source-incremental-strategy" error))))
+ (testing "a bare query passed as the definition — legacy MBQL wears the same two keys a source
+ map does, so it has to be caught by name rather than failing on the inner query"
+ (is (re-find #"is a query, not a transform source"
+ (tool-error (write! {:method "create"
+ :name "x"
+ :definition (venues-query)
+ :target {:name "y" :schema (venues-schema)}})))))
+ (testing "and a definition with no recognizable type at all"
+ (is (re-find #"`definition.type` is nil"
+ (tool-error (write! {:method "create"
+ :name "x"
+ :definition {:query (venues-query)}
+ :target {:name "y" :schema (venues-schema)}}))))))))
+
+(deftest transform-write-target-conflict-test
+ (testing "GHY-4240: a target table that already exists is refused, and the error names it"
+ (with-transforms
+ (with-target-db-support
+ (let [table-name (t2/select-one-fn :name :model/Table :id (mt/id :venues))
+ error (tool-error (write! {:method "create"
+ :name "clobber"
+ :definition (query-definition)
+ :target {:name table-name :schema (venues-schema)}}))]
+ (is (re-find #"already exists" error))
+ (is (re-find (re-pattern table-name) error)))))))
+
+;; TODO(query-track/execute_sql): restore when the execute_sql tool lands — this test mints a
+;; query handle via `call-tool! ... "execute_sql"`, which isn't registered yet. (an execute_sql handle -> native transform)
+#_(deftest transform-write-query-handle-source-test
+ (testing "GHY-4240: an execute_sql handle saves as a native transform — the agent's write-SQL-then-save flow"
+ (with-transforms
+ (with-target-db-support
+ (let [session-id (str (random-uuid))
+ handle (-> (call-tool! :crowberto nil "execute_sql"
+ {:database_id (mt/id) :sql "SELECT 1 AS n" :validate_only true}
+ session-id)
+ tool-result
+ :query_handle)
+ result (tool-result (call-tool! :crowberto write-scopes "transform_write"
+ {:method "create"
+ :name "from a handle"
+ :query_handle handle
+ :target {:name "mcp_from_handle" :schema (venues-schema)}}
+ session-id))]
+ (is (string? handle) "execute_sql mints a handle on validate_only")
+ (try
+ (is (= "native" (:source_type result)))
+ (is (= "mcp_from_handle" (-> result :target :name)))
+ (finally
+ (t2/delete! :model/Transform :id (:id result)))))))))
+
+;;; ----------------------------------------------- Query handles --------------------------------------------------
+
+(defn- mint-handle!
+ "Mint a query_handle for `serialized-query` straight into the handle store, the way an execute
+ tool does — reproducing the pMBQL → JSON → string-valued map round-trip the save path has to
+ survive. Deferred-tests ledger: when the `execute_sql`/`execute_query` tools land, the
+ `#_`-disabled tests in this namespace cover the same ground through the whole tool path; these
+ stay as the store-level pin, so the handle branch is never left uncovered."
+ [session-id serialized-query]
+ (v2.queries/mint-query-handle! session-id (mt/user->id :crowberto)
+ (v2.queries/encode-serialized-query serialized-query)))
+
+(defn- venues-handle-query
+ "The serialized MBQL 5 an execute_query handle carries — `:database` included, which the execute
+ pipeline guarantees and `resolve-target` reads to derive the target database."
+ []
+ {:lib/type "mbql/query"
+ :database (mt/id)
+ :stages [{:lib/type "mbql.stage/mbql" :source-table (mt/id :venues)}]})
+
+(defn- native-handle-query
+ "The serialized native query an `execute_sql` handle carries."
+ []
+ (lib/prepare-for-serialization (lib/native-query (mt/metadata-provider) "SELECT 1 AS n")))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest transform-write-create-from-query-handle-test
+ (testing "GHY-4240: a query_handle is the other query source — the agent runs a query, then saves
+ exactly what ran, without restating the query"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-model-cleanup [:model/Transform :model/McpQueryHandle]
+ (let [session-id (str (random-uuid))
+ handle (mint-handle! session-id (venues-handle-query))
+ result (tool-result (call-tool! :crowberto write-scopes "transform_write"
+ {:method "create"
+ :name "From a handle"
+ :query_handle handle
+ :target {:name "mcp_from_handle" :schema (venues-schema)}}
+ session-id))
+ stored (t2/select-one :model/Transform :id (:id result))]
+ (is (= "mbql" (:source_type result)))
+ (testing "the handle's query is what got stored, normalized to what a transform holds"
+ (is (= (mt/id :venues) (-> stored :source :query :stages first :source-table))))
+ (testing "and the target follows the handle's database"
+ (is (= {:type "table" :schema (venues-schema) :name "mcp_from_handle" :database (mt/id)}
+ (:target result))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest transform-write-native-query-handle-test
+ (testing "GHY-4240: a native handle — the shape execute_sql mints — saves as a native transform, and
+ deliberately does NOT re-demand the agent:sql:run scope: minting the handle already passed
+ that gate and the kill switch, so re-checking here would make execute_sql's own handles
+ unsaveable. Contrast transform-write-native-definition-gates-test, where an inline native
+ `definition` has passed no gate yet and so must pass both."
+ (with-transforms
+ (with-target-db-support
+ (mt/with-model-cleanup [:model/Transform :model/McpQueryHandle]
+ (let [session-id (str (random-uuid))
+ handle (mint-handle! session-id (native-handle-query))
+ result (tool-result (call-tool! :crowberto write-scopes "transform_write"
+ {:method "create"
+ :name "From a SQL handle"
+ :query_handle handle
+ :target {:name "mcp_from_sql_handle" :schema (venues-schema)}}
+ session-id))]
+ (is (= "native" (:source_type result)))
+ (is (= :native (t2/select-one-fn :source_type :model/Transform :id (:id result))))
+ (testing "and the SQL that ran is the SQL that got stored"
+ (is (= "SELECT 1 AS n"
+ (-> (t2/select-one-fn :source :model/Transform :id (:id result))
+ :query :stages first :native))))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest transform-write-update-from-query-handle-test
+ (testing "GHY-4240: a query_handle works on update too, so an agent can re-run a query and save the
+ corrected version over an existing transform — which here also retypes it mbql -> native"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_handle_swap")]
+ (let [session-id (str (random-uuid))
+ handle (mint-handle! session-id (native-handle-query))
+ result (tool-result (call-tool! :crowberto write-scopes "transform_write"
+ {:method "update" :id id :query_handle handle}
+ session-id))]
+ (is (= "native" (:source_type result)))
+ (is (= :native (t2/select-one-fn :source_type :model/Transform :id id)))
+ (testing "and the fields the call didn't name are untouched"
+ (is (= "mcp_handle_swap" (-> result :target :name)))
+ (is (= (venues-schema) (-> result :target :schema)))))))))))
+
+(deftest transform-write-unknown-query-handle-test
+ (testing "GHY-4240: a handle the caller doesn't own (or that has expired) is a teaching error naming
+ the recovery, not the sanitized internal error a raw lookup miss would produce"
+ (with-transforms
+ (with-target-db-support
+ (let [error (tool-error (write! {:method "create"
+ :name "no such handle"
+ :query_handle (str (random-uuid))
+ :target {:name "mcp_no_handle" :schema (venues-schema)}}))]
+ (is (re-find #"Query handle not found" error))
+ (is (re-find #"run the query again" error))
+ (is (zero? (t2/count :model/Transform :name "no such handle"))))))))
+
+;;; ------------------------------------------- Collections and tags -----------------------------------------------
+
+(deftest transform-write-collection-id-test
+ (testing "GHY-4240: `collection_id` files the transform in a transform folder, on create and on update.
+ Transform folders are collections in the :transforms namespace, so an ordinary collection is
+ refused — pinned here because the refusal comes from a layer below this tool."
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Collection {folder :id} {:name "Transforms folder" :namespace :transforms}
+ :model/Collection {folder2 :id} {:name "Other folder" :namespace :transforms}
+ :model/Collection {ordinary :id} {:name "Ordinary folder"}]
+ (testing "create files it where it's told"
+ (let [result (tool-result (write! {:method "create"
+ :name "Filed transform"
+ :definition (query-definition)
+ :target {:name "mcp_filed" :schema (venues-schema)}
+ :collection_id folder}))]
+ (try
+ (is (= folder (:collection_id result)))
+ (is (= folder (t2/select-one-fn :collection_id :model/Transform :id (:id result))))
+ (testing "and update moves it"
+ (let [moved (tool-result (write! {:method "update" :id (:id result) :collection_id folder2}))]
+ (is (= folder2 (:collection_id moved)))))
+ (testing "while \"root\" puts it at the top of the transforms tree"
+ (let [rooted (tool-result (write! {:method "update" :id (:id result) :collection_id "root"}))]
+ (is (nil? (:collection_id rooted)))
+ (is (nil? (t2/select-one-fn :collection_id :model/Transform :id (:id result))))))
+ (finally
+ (t2/delete! :model/Transform :id (:id result))))))
+ (testing "a collection that isn't a transform folder is refused, and nothing is written"
+ (let [error (tool-error (write! {:method "create"
+ :name "Misfiled transform"
+ :definition (query-definition)
+ :target {:name "mcp_misfiled" :schema (venues-schema)}
+ :collection_id ordinary}))]
+ (is (re-find #"(?i)namespace" error))
+ (is (zero? (t2/count :model/Transform :name "Misfiled transform")))))
+ (testing "and a collection id that resolves to nothing is the shared not-found error"
+ (is (re-find #"not found"
+ (tool-error (write! {:method "create"
+ :name "Nowhere transform"
+ :definition (query-definition)
+ :target {:name "mcp_nowhere" :schema (venues-schema)}
+ :collection_id 999999999}))))))))))
+
+(deftest transform-write-tag-ids-test
+ (testing "GHY-4240: `tag_ids` replaces the whole list — jobs select transforms by tag, so a tag that
+ silently fails to attach is a transform a schedule never runs"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/TransformTag {tag1 :id} {:name "mcp-tag-1"}
+ :model/TransformTag {tag2 :id} {:name "mcp-tag-2"}]
+ (let [result (tool-result (write! {:method "create"
+ :name "Tagged transform"
+ :definition (query-definition)
+ :target {:name "mcp_tagged" :schema (venues-schema)}
+ :tag_ids [tag1]}))
+ id (:id result)]
+ (try
+ (testing "create attaches them"
+ (is (= [tag1] (:tag_ids result))))
+ (testing "update replaces the list rather than adding to it"
+ (is (= [tag2] (:tag_ids (tool-result (write! {:method "update" :id id :tag_ids [tag2]}))))))
+ (testing "and [] clears it"
+ (is (= [] (:tag_ids (tool-result (write! {:method "update" :id id :tag_ids []}))))))
+ (finally
+ (t2/delete! :model/Transform :id id)))))))))
+
+(deftest transform-write-unknown-tag-ids-test
+ (testing "GHY-4240: a tag id that names no tag is refused rather than dropped on the floor. The shared
+ write filters unknown ids out silently, so \"replaces the current list\" would quietly mean
+ \"replaces it with a shorter one\" — and the tag a job selects on is exactly the one whose
+ absence goes unnoticed until the schedule doesn't fire."
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/TransformTag {tag1 :id} {:name "mcp-tag-live"}]
+ (testing "on create, naming the id that doesn't exist"
+ (let [error (tool-error (write! {:method "create"
+ :name "Badly tagged"
+ :definition (query-definition)
+ :target {:name "mcp_bad_tag" :schema (venues-schema)}
+ :tag_ids [tag1 999999999]}))]
+ (is (re-find #"999999999" error))
+ (is (zero? (t2/count :model/Transform :name "Badly tagged"))
+ "and nothing is written")))
+ (testing "and on update, where the stored tags are left alone"
+ ;; `:tag_ids` is a hydration key over the join table, not a column, so the association is
+ ;; made directly rather than passed to the insert.
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_bad_tag_update")
+ :model/TransformTransformTag _ {:transform_id id :tag_id tag1 :position 0}]
+ (let [error (tool-error (write! {:method "update" :id id :tag_ids [999999999]}))]
+ (is (re-find #"999999999" error))
+ (is (= [tag1] (:tag_ids (t2/hydrate (t2/select-one :model/Transform :id id)
+ :transform_tag_ids))))))))))))
+
+(defn- venues-fk
+ "The portable FK path the external dialect names the venues table by."
+ []
+ [(t2/select-one-fn :name :model/Database :id (mt/id)) (venues-schema) "VENUES"])
+
+(deftest transform-write-portable-definition-test
+ (testing "GHY-4240: a `definition` in the older name-based dialect resolves on input, as the
+ accepted-shapes sentence every source error ends with promises. Only the numeric-id
+ dialect had a test, so nothing held that sentence to the code."
+ (with-transforms
+ (with-target-db-support
+ (let [result (tool-result (write! {:method "create"
+ :name "Portable source"
+ :definition {:type "query"
+ :query {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (venues-fk)}]}}
+ :target {:name "mcp_portable" :schema (venues-schema)}}))]
+ (try
+ (testing "the FK path resolved to the numeric id the transform stores"
+ (is (= (mt/id :venues)
+ (-> (t2/select-one-fn :source :model/Transform :id (:id result))
+ :query :stages first :source-table))))
+ (testing "and the target database follows the resolved query"
+ (is (= (mt/id) (-> result :target :database))))
+ (finally
+ (t2/delete! :model/Transform :id (:id result)))))))))
+
+(deftest transform-write-accepted-shapes-names-both-dialects-test
+ (testing "GHY-4240: the sentence every source-shape error ends with is what teaches the agent how to
+ retry, so it has to name both dialects the tool actually resolves — it once said
+ \"either\" and then listed one"
+ (with-transforms
+ (let [error (tool-error (write! {:method "create"
+ :name "x"
+ :definition {:query (venues-query)}
+ :target {:name "y" :schema (venues-schema)}}))]
+ (is (re-find #"numeric-id dialect" error))
+ (is (re-find #"name-based dialect" error))
+ (is (not (re-find #"either the same numeric-id dialect execute_query takes\." error))
+ "the truncated form, with `either` promising an alternative it never gives")))))
+
+;;; -------------------------------------------------- Update ------------------------------------------------------
+
+(deftest transform-write-update-swaps-source-test
+ (testing "GHY-4240: an update carrying a `definition` replaces the stored query and leaves everything
+ else — the read-modify-write flow the definition round-trip exists for"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (assoc (temp-transform-defaults "mcp_swap")
+ :description "unchanged")]
+ (let [result (tool-result (write! {:method "update" :id id
+ :definition {:type "query"
+ :query {:database (mt/id) :type "query"
+ :query {:source-table (mt/id :checkins)}}}}))
+ stored (t2/select-one :model/Transform :id id)]
+ (is (= "mbql" (:source_type result)))
+ (testing "the new query really landed, normalized to what the transform stores"
+ (is (= (mt/id :checkins)
+ (-> stored :source :query :stages first :source-table))))
+ (testing "and the fields the call didn't name are untouched"
+ (is (= "unchanged" (:description result)))
+ (is (= "mcp_swap" (-> result :target :name)))
+ (is (= (venues-schema) (-> result :target :schema))))
+ (testing "the target's database follows the query being stored, not the one it replaced —
+ a stale database in the echo is one the transform does not write, and passing that
+ echo back unchanged would be refused by the target/query database check"
+ (is (= (mt/id) (-> result :target :database)))
+ (is (= (mt/id) (-> stored :target :database)))
+ (testing "so the echoed target round-trips"
+ (let [again (tool-result (write! {:method "update" :id id :target (:target result)}))]
+ (is (= (mt/id) (-> again :target :database))))))))))))
+
+(deftest transform-write-update-source-database-swap-retargets-test
+ (testing "GHY-4240: swapping the source to a query on a different database moves the target's database
+ with it, even though the call names no `target`. The target database is derived from the
+ query rather than authored, so a target left pointing at the old database names one the
+ transform does not write — and the echo carrying it is then refused on the way back in by
+ the target/query database check, dead-ending the read-modify-write this tool is built on."
+ (with-transforms
+ (with-target-db-support
+ (let [orig-db (mt/id)
+ orig-venues (mt/id :venues)
+ orig-schema (venues-schema)]
+ (mt/with-temp-copy-of-db
+ (let [other-db (mt/id)]
+ (is (not= orig-db other-db) "the copy really is a second database")
+ (mt/with-temp [:model/Transform {id :id}
+ {:name "db swap"
+ :source {:type :query
+ :query {:database orig-db :type "query"
+ :query {:source-table orig-venues}}}
+ :target {:type :table :schema orig-schema :name "mcp_db_swap"}}]
+ (let [result (tool-result (write! {:method "update" :id id
+ :definition {:type "query"
+ :query {:database other-db :type "query"
+ :query {:source-table (mt/id :venues)}}}}))
+ stored (t2/select-one :model/Transform :id id)]
+ (testing "the echoed target names the database the transform now writes"
+ (is (= other-db (-> result :target :database))))
+ (testing "and so does the stored one — the echo is not a prettier view of a stale row"
+ (is (= other-db (-> stored :target :database))))
+ (testing "so the echoed target can be passed straight back, as read-modify-write does"
+ (let [again (tool-result (write! {:method "update" :id id :target (:target result)}))]
+ (is (= other-db (-> again :target :database)))))
+ (testing "while the parts of the target the call never named are left alone"
+ (is (= "mcp_db_swap" (-> result :target :name)))
+ (is (= orig-schema (-> result :target :schema)))))))))))))
+
+;; TODO(query-track/execute_sql): restore when the execute_sql tool lands — this test mints a
+;; query handle via `call-tool! ... "execute_sql"`, which isn't registered yet. (a query_handle on update)
+#_(deftest transform-write-update-swaps-source-from-handle-test
+ (testing "GHY-4240: a query_handle works on update too, so an agent can re-run execute_sql and save the
+ corrected SQL over an existing transform — which also retypes it from mbql to native"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_swap_handle")]
+ (let [session-id (str (random-uuid))
+ handle (-> (call-tool! :crowberto nil "execute_sql"
+ {:database_id (mt/id) :sql "SELECT 2 AS n" :validate_only true}
+ session-id)
+ tool-result
+ :query_handle)
+ result (tool-result (call-tool! :crowberto write-scopes "transform_write"
+ {:method "update" :id id :query_handle handle}
+ session-id))]
+ (is (= "native" (:source_type result)))
+ (is (= :native (:source_type (t2/select-one :model/Transform :id id))))))))))
+
+(deftest transform-write-update-patches-target-test
+ (testing "GHY-4240: a target rename keeps the schema — update patches the stored target, it doesn't replace it"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_before")]
+ (let [result (tool-result (write! {:method "update" :id id
+ :target {:name "mcp_after"}}))]
+ (is (= "mcp_after" (-> result :target :name)))
+ (is (= (venues-schema) (-> result :target :schema)))
+ (is (= "table" (-> result :target :type)))))))))
+
+(deftest transform-write-target-round-trips-test
+ (testing "GHY-4240: the target a read (or a previous write) hands back can be passed straight back in.
+ `type` and `database` are derived rather than authored, but they are on every target an
+ agent ever sees, so refusing them at the schema boundary breaks read-modify-write."
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_roundtrip")]
+ (let [echoed (:target (tool-result (write! {:method "update" :id id :description "touch"})))]
+ (is (= #{:type :schema :name :database} (set (keys echoed)))
+ "the echo carries the derived keys the input schema therefore has to tolerate")
+ (let [after (:target (tool-result (write! {:method "update" :id id
+ :target (assoc echoed :name "mcp_roundtrip2")})))]
+ (is (= "mcp_roundtrip2" (:name after)))
+ (is (= (venues-schema) (:schema after)))
+ (is (= (mt/id) (:database after))))))))))
+
+(deftest transform-write-target-tolerates-nested-nulls-test
+ (testing "GHY-4240: nulls are only stripped at the top level, so a strict client's fully-populated
+ `target` arrives with nulls inside it — those must read as \"didn't touch it\" and not
+ clear the stored schema"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_nested_nulls")]
+ (let [after (:target (tool-result (write! {:method "update" :id id
+ :target {:name "mcp_nested_nulls2"
+ :schema nil
+ :type nil
+ :database nil
+ :target-incremental-strategy nil}})))]
+ (is (= "mcp_nested_nulls2" (:name after)))
+ (is (= (venues-schema) (:schema after)))))))))
+
+(deftest transform-write-target-refuses-unauthorable-type-test
+ (testing "GHY-4240: a target type this tool can't author is a teaching error naming it, not a
+ schema rejection the agent can't act on"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_bad_type")]
+ (let [error (tool-error (write! {:method "update" :id id
+ :target {:name "mcp_bad_type" :type "table-incremental"}}))]
+ (is (re-find #"`target.type`" error))
+ (is (re-find #"table-incremental" error)))
+ (testing "as is an incremental strategy on the target"
+ (let [error (tool-error (write! {:method "update" :id id
+ :target {:name "mcp_bad_type"
+ :target-incremental-strategy {:type "append"}}}))]
+ (is (re-find #"target-incremental-strategy" error)))))))))
+
+(deftest transform-write-target-refuses-foreign-database-test
+ (testing "GHY-4240: the target database follows the query, so a `target.database` that disagrees is
+ refused rather than silently ignored"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_foreign_db")]
+ (let [error (tool-error (write! {:method "update" :id id
+ :target {:name "mcp_foreign_db" :database (inc (mt/id))}}))]
+ (is (re-find #"`target.database`" error))
+ (is (re-find #"follows the query" error))))))))
+
+(deftest transform-write-update-target-conflict-test
+ (testing "GHY-4240: renaming onto a table that already exists is refused on update with the same
+ teaching error create gives — REST only reports \"A table with that name already exists.\",
+ which names neither the table nor the fix"
+ (with-transforms
+ (with-target-db-support
+ (let [table-name (t2/select-one-fn :name :model/Table :id (mt/id :venues))]
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_conflict")]
+ (let [error (tool-error (write! {:method "update" :id id :target {:name table-name}}))]
+ (is (re-find #"already exists" error))
+ (is (re-find (re-pattern table-name) error))
+ (is (re-find #"Pick a different `target.name`" error))))
+ (testing "but a target that isn't moving is left alone, so a transform that has already built
+ its own output table stays editable"
+ ;; The source reads a different table than the target writes: a transform reading and
+ ;; writing the same table is a self-cycle, refused before the target check it is here
+ ;; to exercise ever runs.
+ (mt/with-temp [:model/Transform {id :id}
+ (assoc (temp-transform-defaults table-name)
+ :source {:type :query
+ :query {:database (mt/id) :type "query"
+ :query {:source-table (mt/id :checkins)}}})]
+ (let [result (tool-result (write! {:method "update" :id id
+ :description "touched"
+ :target {:name table-name}}))]
+ (is (= "touched" (:description result)))
+ (is (= table-name (-> result :target :name)))))))))))
+
+(deftest transform-write-update-fields-test
+ (testing "GHY-4240: only the fields passed change, and `clear` unsets description"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (assoc (temp-transform-defaults "mcp_fields")
+ :description "before")]
+ (let [renamed (tool-result (write! {:method "update" :id id :name "after"}))]
+ (is (= "after" (:name renamed)))
+ (is (= "before" (:description renamed)))
+ (is (= "mcp_fields" (-> renamed :target :name))))
+ (let [cleared (tool-result (write! {:method "update" :id id :clear ["description"]}))]
+ (is (nil? (:description cleared)))
+ (is (nil? (t2/select-one-fn :description :model/Transform :id id)))))))))
+
+(deftest transform-write-update-needs-something-to-do-test
+ (testing "GHY-4240: an update naming no field is a teaching error, not a silent no-op write"
+ (with-transforms
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_noop")]
+ (is (re-find #"Nothing to update" (tool-error (write! {:method "update" :id id}))))))))
+
+(deftest transform-write-update-refuses-incremental-target-test
+ (testing "GHY-4240: an incremental target is left alone rather than downgraded to a full rebuild"
+ (with-transforms
+ (mt/with-temp [:model/Transform {id :id}
+ (assoc (temp-transform-defaults "mcp_incremental")
+ :target {:type "table-incremental"
+ :schema (venues-schema)
+ :name "mcp_incremental"
+ :target-incremental-strategy {:type "append"}})]
+ (let [error (tool-error (write! {:method "update" :id id :target {:name "mcp_renamed"}}))]
+ (is (re-find #"table-incremental target" error))
+ (is (re-find #"omit `target`" error)))
+ (testing "including when the agent passes the stored target back verbatim, which is how it
+ would actually arrive — the refusal has to survive the round-trip shape"
+ (let [error (tool-error (write! {:method "update" :id id
+ :target {:name "mcp_renamed"
+ :schema (venues-schema)
+ :type "table-incremental"
+ :target-incremental-strategy {:type "append"}}}))]
+ (is (re-find #"table-incremental target" error))))))))
+
+(deftest transform-write-update-refuses-incremental-source-test
+ (testing "GHY-4240: replacing the query of an incrementally-loading transform would drop the strategy
+ off its source, so the update is refused rather than silently degrading it to a full read"
+ (with-transforms
+ (with-target-db-support
+ (let [strategy {:type "checkpoint" :checkpoint-filter-field-id (mt/id :venues :id)}]
+ (mt/with-temp [:model/Transform {id :id}
+ (assoc-in (temp-transform-defaults "mcp_checkpoint")
+ [:source :source-incremental-strategy] strategy)]
+ (let [error (tool-error (write! {:method "update" :id id :definition (query-definition)}))]
+ (is (re-find #"loads incrementally \(checkpoint\)" error))
+ (is (re-find #"omit `definition`" error)))
+ (testing "and the stored strategy is untouched"
+ (is (= strategy (:source-incremental-strategy
+ (t2/select-one-fn :source :model/Transform :id id)))))
+ (testing "while an update that leaves the source alone still goes through"
+ (is (= "renamed" (:name (tool-result (write! {:method "update" :id id :name "renamed"}))))))))))))
+
+(deftest transform-write-update-refuses-python-transform-test
+ (testing "GHY-4240: addressing a python transform with this tool refuses rather than retyping it"
+ (mt/with-premium-features #{:transforms-basic :transforms-python}
+ (mt/with-temp-env-var-value! [mb-transforms-enabled true]
+ (mt/with-temp [:model/Transform {id :id}
+ {:name "py"
+ :source {:type :python
+ :body "def transform(): pass"
+ :source-tables []
+ :source-database (mt/id)}
+ :target {:type :table :schema (venues-schema) :name "mcp_py_out"}}]
+ (let [error (tool-error (write! {:method "update" :id id :name "renamed"}))]
+ (is (re-find #"is a python transform" error))
+ (is (re-find #"query transforms only" error))))))))
+
+(deftest transform-write-update-runs-the-permission-check-test
+ (testing "GHY-4240: the update path's counterpart to
+ `transform-write-create-runs-the-permission-check-test`, which is the suite's only other
+ non-admin test. `write-check` covers the transform AS STORED; the caller's `definition`
+ then names its own database and is resolved with no permission check of its own, so the
+ gates on the new state have to run before `check-target-move!` opens a warehouse
+ connection to it. Otherwise a data analyst holding transforms permission on the
+ transform's own database — enough to pass `write-check` — gets \"does table X exist?\"
+ answered for a database they hold nothing on, one call per guess.
+
+ `driver/table-exists?` is redefined to record whether it ran, so the ordering is asserted
+ directly: with the gates ordered after `check-target-move!` this test fails on `probed`."
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Database {other-db-id :id} {:engine :h2 :name "MCP perm probe DB"}
+ :model/Transform {id :id} (temp-transform-defaults "mcp_update_perm_probe")]
+ (mt/with-data-analyst-role! (mt/user->id :rasta)
+ (mt/with-restored-data-perms!
+ ;; Transforms permission on the transform's own database only — never on other-db-id.
+ (data-perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/view-data :unrestricted)
+ (data-perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/create-queries :query-builder)
+ (data-perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/transforms :yes)
+ (testing "the stored transform is writable, so the refusal below is about the named database"
+ (is (mt/with-current-user (mt/user->id :rasta)
+ (mi/can-write? (t2/select-one :model/Transform :id id)))))
+ (let [probed (atom false)]
+ (with-redefs [driver/table-exists? (fn [& _] (reset! probed true) false)]
+ (let [args {:method "update"
+ :id id
+ :definition {:type "query" :query {:database other-db-id :type "query"
+ :query {:source-table (mt/id :venues)}}}
+ :target {:name "mcp_update_perm_probe_moved" :schema (venues-schema)}}
+ error (tool-error (write! :rasta write-scopes args))]
+ (is (false? @probed)
+ "no warehouse connection is opened to a database the caller was never authorized against")
+ (is (string? error))
+ (is (= "mcp_update_perm_probe"
+ (t2/select-one-fn #(get-in % [:target :name]) :model/Transform :id id))
+ "and nothing is written when the check refuses")))))))))))
+
+(deftest transform-write-not-found-test
+ (testing "GHY-4240: an unresolvable id collapses to the shared not-found error"
+ (with-transforms
+ (is (re-find #"not found" (tool-error (write! {:method "update" :id 999999999 :name "x"})))))))
+
+;;; --------------------------------------------------- Scopes -----------------------------------------------------
+
+(deftest transform-write-scope-gate-test
+ (testing "GHY-4240: the tool is unreachable without agent:content:write"
+ (with-transforms
+ (is (re-find #"Insufficient scope"
+ (tool-error (write! :crowberto #{"agent:content:read"}
+ {:method "update" :id 1 :name "x"}))))
+ (testing "and the scope it declares is one the registry actually knows"
+ (is (contains? (registry/registered-scopes) "agent:content:write"))))))
+
+(deftest transform-write-readback-requires-read-scopes-test
+ (testing "GHY-4240: a write scope alone doesn't double as a read scope — the echo degrades to an ack"
+ (with-transforms
+ (with-target-db-support
+ (mt/with-temp [:model/Transform {id :id} (temp-transform-defaults "mcp_readback")]
+ (let [result (tool-result (write! :crowberto #{"agent:content:write"}
+ {:method "update" :id id :name "renamed"}))]
+ (is (= #{:id :url :note} (set (keys result))))
+ (is (re-find #"agent:content:read" (:note result)))
+ (testing "and the write still happened"
+ (is (= "renamed" (t2/select-one-fn :name :model/Transform :id id))))))))))
diff --git a/test/metabase/mcp/v2/tools/visualize_test.clj b/test/metabase/mcp/v2/tools/visualize_test.clj
new file mode 100644
index 00000000000..7a1619a9396
--- /dev/null
+++ b/test/metabase/mcp/v2/tools/visualize_test.clj
@@ -0,0 +1,420 @@
+(ns metabase.mcp.v2.tools.visualize-test
+ "Contract tests for the v2 MCP Apps tools `visualize_query` and `render_drill_through`
+ (GHY-4157), driven through [[metabase.mcp.v2.registry/call-tool]] — the same seam the
+ JSON-RPC route uses — so scope gating, the MCP-Apps extension gate, nil-arg stripping,
+ Malli validation, and teaching-error conversion are exercised on every call.
+
+ The load-bearing v2 change from v1 is that neither tool puts query data in the model's
+ context: the response carries a `query_handle` the iframe resolves out of band. Several
+ tests below pin that absence directly."
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer [deftest is testing use-fixtures]]
+ ;; `mcp.core/all-scopes` reads the agent-api's defendpoint metadata, so the namespace has to be
+ ;; loaded for `resource-scopes-are-advertised-test` to see it (nothing else here pulls it in).
+ [metabase.agent-api.api]
+ [metabase.lib-be.core :as lib-be]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.mcp.core :as mcp.core]
+ [metabase.mcp.session :as mcp.session]
+ [metabase.mcp.ui-resource :as mcp.ui-resource]
+ [metabase.mcp.v2.queries :as v2.queries]
+ [metabase.mcp.v2.registry :as registry]
+ [metabase.mcp.v2.resources :as v2.resources]
+ [metabase.mcp.v2.tools.visualize]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.test.http-client :as client]
+ [metabase.util :as u]
+ [metabase.util.json :as json]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(def ^:private viz-scopes
+ #{"agent:query:run"})
+
+(def ^:private mcp-ui-client
+ "A client that advertises the MCP Apps UI extension. Both tools are gated on it."
+ {:supports-mcp-ui? true})
+
+(defn- call!
+ ([tool-name session-id arguments]
+ (call! tool-name session-id arguments mcp-ui-client))
+ ([tool-name session-id arguments options]
+ (registry/call-tool viz-scopes session-id tool-name arguments options)))
+
+(defn- dispatch-error?
+ "Whether a [[call!]] outcome is an error, at either layer: a registry rejection before
+ dispatch, or a handler that set `:isError`."
+ [{:keys [result error]}]
+ (boolean (or error (:isError result))))
+
+(defn- response-text
+ "The outcome's text block, or a registry-level rejection's message."
+ [{:keys [result error]}]
+ (if error (:message error) (-> result :content first :text)))
+
+(defn- payload
+ "The `structuredContent` of a successful response. Throws if the tool errored, so a
+ tool-level error can never masquerade as an empty payload."
+ [outcome]
+ (when (dispatch-error? outcome)
+ (throw (ex-info "expected success, got tool error" {:outcome outcome})))
+ (-> outcome :result :structuredContent))
+
+(defn- error-text
+ "The message of a tool-level error. Throws if the call succeeded, so a passing call can
+ never satisfy an error assertion."
+ [outcome]
+ (when-not (dispatch-error? outcome)
+ (throw (ex-info "expected tool error, got success" {:outcome outcome})))
+ (response-text outcome))
+
+(defn- orders-query
+ "A portable MBQL 5 query over the sample Orders table."
+ []
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))
+ table (lib.metadata/table mp (mt/id :orders))]
+ {:lib/type "mbql/query"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table [(:name (lib.metadata/database mp)) (:schema table) (:name table)]
+ :limit 5}]}))
+
+(defn- mint-mbql-handle!
+ [session-id user-id]
+ (let [mp (lib-be/application-database-metadata-provider (mt/id))]
+ (v2.queries/mint-query-handle!
+ session-id user-id
+ (v2.queries/encode-serialized-query
+ (lib/prepare-for-serialization
+ (lib/query mp (lib.metadata/table mp (mt/id :orders))))))))
+
+;;; ---------------------------------------------- visualize_query -------------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest visualize-query-handle-passthrough-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ handle (mint-mbql-handle! sid (mt/user->id :rasta))
+ body (payload (call! "visualize_query" sid {:query_handle handle}))]
+ (testing "GHY-4157: a supplied handle is reused as-is rather than re-minted — the stored query is unchanged"
+ (is (= handle (:query_handle body))))
+ (testing "GHY-4157: the query itself never reaches the model — only the handle does"
+ ;; Asserted as the absence of query data, not as an exact key set. Pinning
+ ;; `#{:query_handle}` pinned one side of a two-sided contract: it passed while the
+ ;; iframe, which needs a key it can resolve, rendered a permanent spinner.
+ (is (not (contains? body :query)))
+ (is (not (str/includes? (response-text (call! "visualize_query" sid {:query_handle handle}))
+ "source-table"))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest visualize-query-fresh-query-mints-handle-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ uid (mt/user->id :rasta)
+ body (payload (call! "visualize_query" sid {:query (orders-query)
+ :prompt "show me orders"}))]
+ (testing "GHY-4157: an inline query mints a handle instead of echoing the query back"
+ (is (string? (:query_handle body)))
+ (is (not (contains? body :query))))
+ (testing "GHY-4157: the minted handle resolves to the query that was visualized"
+ (let [{:keys [query prompt]} (v2.queries/resolve-query-handle! sid uid (:query_handle body))]
+ (is (some? (get-in query [:stages 0 :source-table])))
+ (testing "and carries the prompt for the visualization feedback flow"
+ (is (= "show me orders" prompt)))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest visualize-query-rejects-display-test
+ ;; `display` was accepted, enum-validated and echoed, but no renderer ever read it, and
+ ;; `mcp_query_handle` has no column to carry it — so on the documented preferred path (mint by
+ ;; `query`, then re-visualize by `query_handle`) the chart type was silently lost. Rather than
+ ;; advertise a knob that does nothing, the argument is gone until it can be honored end to end.
+ ;; GHY-4451 restores it; that work must delete this test rather than route around it.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ handle (mint-mbql-handle! sid (mt/user->id :rasta))]
+ (testing "GHY-4157: display is rejected outright, not accepted and dropped"
+ (is (str/includes? (error-text (call! "visualize_query" sid {:query_handle handle
+ :display "bar"}))
+ "Invalid arguments")))
+ (testing "GHY-4157: the payload carries the handle and nothing that pretends to be a chart type"
+ (is (not (contains? (payload (call! "visualize_query" sid {:query_handle handle}))
+ :display))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest visualize-query-accepts-native-handle-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ mp (lib-be/application-database-metadata-provider (mt/id))
+ handle (v2.queries/mint-query-handle!
+ sid (mt/user->id :rasta)
+ (v2.queries/encode-serialized-query
+ (lib/prepare-for-serialization
+ (lib/native-query mp "SELECT 1 AS n"))))]
+ (testing "GHY-4157: an execute_sql handle is visualizable — native results are charts too"
+ (is (= handle (:query_handle (payload (call! "visualize_query" sid {:query_handle handle}))))))))))
+
+(deftest visualize-query-input-exclusivity-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))]
+ (testing "GHY-4157: neither input names both affordances"
+ (let [message (error-text (call! "visualize_query" sid {}))]
+ (is (str/includes? message "exactly one"))
+ (is (str/includes? message "query_handle"))
+ (is (str/includes? message "query"))))
+ (testing "GHY-4157: both inputs is a teaching error, not a silent precedence rule"
+ (is (str/includes? (error-text (call! "visualize_query" sid {:query (orders-query)
+ :query_handle (str (random-uuid))}))
+ "exactly one"))))))
+
+(deftest visualize-query-rejects-inline-native-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [sid (str (random-uuid))
+ mp (lib-be/application-database-metadata-provider (mt/id))]
+ (testing "GHY-4157: inline `query` is MBQL 5 only, matching execute_query — SQL arrives by handle"
+ (is (dispatch-error? (call! "visualize_query" sid
+ {:query (lib/prepare-for-serialization
+ (lib/native-query mp "SELECT 1 AS n"))})))))))
+
+(deftest visualize-query-unknown-handle-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "GHY-4157: an unknown handle names the recovery path"
+ (is (str/includes? (error-text (call! "visualize_query" (str (random-uuid))
+ {:query_handle (str (random-uuid))}))
+ "run the query again")))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest visualize-query-handle-is-user-scoped-test
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ handle (mt/with-current-user (mt/user->id :crowberto)
+ (mint-mbql-handle! sid (mt/user->id :crowberto)))]
+ (testing "GHY-4157: another user's handle is not resolvable — the handle is not a bearer credential"
+ (mt/with-current-user (mt/user->id :rasta)
+ (is (dispatch-error? (call! "visualize_query" sid {:query_handle handle}))))))))
+
+;;; -------------------------------------------- render_drill_through ----------------------------------------------
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest render-drill-through-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ handle (mint-mbql-handle! sid (mt/user->id :rasta))
+ body (payload (call! "render_drill_through" sid {:query_handle handle}))]
+ (testing "GHY-4157: the drill handle the iframe minted is echoed for the iframe to resolve"
+ (is (= {:query_handle handle} body)))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest render-drill-through-accepts-iframe-minted-handle-test
+ ;; The iframe mints drill handles from the SDK's `dataset_query` (legacy MBQL 4: no `:stages`),
+ ;; not from the serialized shape v2's execute tools mint. Resolving these through the execute
+ ;; path's guards would reject every real drill-through, so both UI tools read the store raw.
+ (mt/with-current-user (mt/user->id :rasta)
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [sid (str (random-uuid))
+ legacy-query {:type "query" :database (mt/id) :query {:source-table (mt/id :orders)}}
+ handle (v2.queries/mint-query-handle!
+ sid (mt/user->id :rasta)
+ (u/encode-base64 (json/encode legacy-query)))]
+ (testing "GHY-4157: a drill handle carrying the iframe's legacy dataset_query renders"
+ (is (= {:query_handle handle}
+ (payload (call! "render_drill_through" sid {:query_handle handle})))))
+ (testing "GHY-4157: and the same handle is visualizable directly"
+ (is (= {:query_handle handle}
+ (payload (call! "visualize_query" sid {:query_handle handle})))))))))
+
+(deftest render-drill-through-unknown-handle-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "GHY-4157: an unknown drill handle is a teaching error, not an empty visualization"
+ (is (str/includes? (error-text (call! "render_drill_through" (str (random-uuid))
+ {:query_handle (str (random-uuid))}))
+ "not found")))))
+
+(deftest render-drill-through-requires-handle-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "GHY-4157: query_handle is required — the tool never runs a query of its own"
+ (is (str/includes? (error-text (call! "render_drill_through" (str (random-uuid)) {}))
+ "Invalid arguments")))))
+
+;;; ------------------------------------------------ Client gating -------------------------------------------------
+
+(deftest mcp-app-ui-extension-gating-test
+ (testing "GHY-4157: MCP Apps tools are hidden from clients that cannot render an iframe.
+ Asserted per-tool rather than by set equality: the UI tools share `agent:query:run`
+ with the execute tools, so the granting scope lists more than these two."
+ (let [visible (fn [options] (set (map :name (registry/list-tools viz-scopes options))))
+ with-ui (visible {:supports-mcp-ui? true})
+ no-ui (visible {:supports-mcp-ui? false})]
+ (doseq [tool-name ["visualize_query" "render_drill_through"]]
+ (testing tool-name
+ (is (contains? with-ui tool-name))
+ (is (not (contains? no-ui tool-name)))))))
+ (testing "GHY-4157: calling one from an incapable client says what the client is missing"
+ (mt/with-current-user (mt/user->id :rasta)
+ (let [message (error-text (call! "visualize_query" (str (random-uuid))
+ {:query_handle (str (random-uuid))}
+ {:supports-mcp-ui? false}))]
+ (is (str/includes? message "MCP Apps UI"))
+ (is (str/includes? message "text/html;profile=mcp-app"))))))
+
+(deftest scope-gating-test
+ (mt/with-current-user (mt/user->id :rasta)
+ (testing "GHY-4157: the MCP Apps tools are scope-gated — a token without `agent:query:run` is
+ refused before the handle is ever looked up. Rendering a chart is what running a query
+ looks like on screen, so they share the execute tools' scope rather than carrying one
+ of their own."
+ (doseq [tool-name ["visualize_query" "render_drill_through"]]
+ (testing tool-name
+ (is (str/includes? (-> (registry/call-tool #{"agent:content:read"} (str (random-uuid))
+ tool-name {:query_handle (str (random-uuid))}
+ mcp-ui-client)
+ response-text)
+ "Insufficient scope")))))))
+
+;;; ------------------------------------------------- Manifest -----------------------------------------------------
+
+(deftest ui-tool-manifest-test
+ (let [by-name (into {} (map (juxt :name identity))
+ (registry/list-tools viz-scopes mcp-ui-client))]
+ (testing "GHY-4157: each UI tool points the host at the iframe shell it renders into"
+ (is (= v2.resources/visualize-query-uri
+ (get-in by-name ["visualize_query" :_meta :ui :resourceUri])))
+ (is (= v2.resources/render-drill-through-uri
+ (get-in by-name ["render_drill_through" :_meta :ui :resourceUri]))))
+ (testing "GHY-4157: distinct resource URIs — a host that dedupes mounted iframes by URI would drop the second"
+ (is (not= v2.resources/visualize-query-uri v2.resources/render-drill-through-uri)))
+ (testing "GHY-4157: the published output schema documents the handle the iframe resolves"
+ (is (= [:query_handle]
+ (get-in by-name ["render_drill_through" :outputSchema :required])))
+ (is (contains? (get-in by-name ["visualize_query" :outputSchema :properties]) :query_handle)))))
+
+(deftest tool-and-resource-scopes-agree-test
+ (testing "GHY-4157: the scope that calls a tool is the scope that reads the iframe it renders — a token holding one always holds the other"
+ (mt/with-current-user (mt/user->id :rasta)
+ (doseq [[tool-name uri] {"visualize_query" v2.resources/visualize-query-uri
+ "render_drill_through" v2.resources/render-drill-through-uri}]
+ (let [scope (v2.resources/resource-scope uri)
+ only-this #{scope}]
+ (is (some? scope) (str uri " is registered with a scope"))
+ (testing (str tool-name " is listed to a token holding only its resource scope")
+ (is (contains? (set (map :name (registry/list-tools only-this mcp-ui-client)))
+ tool-name)))
+ (testing (str tool-name " is callable by that same token")
+ ;; An unknown handle: the call gets past scope and extension gating to the handle
+ ;; lookup, which is the point — a scope rejection would read "Insufficient scope".
+ (is (not (str/includes? (-> (registry/call-tool only-this (str (random-uuid)) tool-name
+ {:query_handle (str (random-uuid))}
+ mcp-ui-client)
+ response-text)
+ "Insufficient scope"))))
+ (testing (str tool-name " can read the shell it points at")
+ (is (= :ok (:status (mcp.ui-resource/with-fallback-template
+ (v2.resources/read-resource uri only-this {})))))))))))
+
+;;; ------------------------------------------------- Resources ----------------------------------------------------
+
+(deftest resource-scopes-are-advertised-test
+ (testing "GHY-4157: every v2 resource scope is in the OAuth grant — one a client can't request is a shell it could never read"
+ (let [advertised (set (mcp.core/all-scopes))]
+ (doseq [scope (v2.resources/resource-scopes)]
+ (is (contains? advertised scope) scope)))))
+
+(deftest resources-scope-gating-test
+ (testing "GHY-4157: resources/list only shows shells the token can read"
+ (is (= #{v2.resources/visualize-query-uri v2.resources/render-drill-through-uri}
+ (set (map :uri (:resources (v2.resources/list-resources viz-scopes))))))
+ (testing "GHY-4250: the v0.62 per-shell leaves went out with the v1 resources they gated, so a
+ still-live token carrying one unlocks nothing — a bare grant matches only itself"
+ (is (empty? (:resources (v2.resources/list-resources #{"agent:viz:mcp-ui:query"}))))
+ (is (empty? (:resources (v2.resources/list-resources #{"agent:viz:mcp-ui:drill-through"})))))
+ (is (empty? (:resources (v2.resources/list-resources #{"agent:content:read"})))))
+ (testing "GHY-4157: reading a shell without its scope is denied, not served"
+ (is (= :scope-denied (:status (v2.resources/read-resource v2.resources/visualize-query-uri
+ #{"agent:content:read"} {}))))
+ (is (= :not-found (:status (v2.resources/read-resource "ui://metabase/nope.html"
+ viz-scopes {}))))))
+
+(deftest resource-read-renders-iframe-shell-test
+ (mcp.ui-resource/with-fallback-template
+ (testing "GHY-4157: the shell carries the scoped UI credential the iframe authenticates with"
+ (let [result (v2.resources/read-resource v2.resources/visualize-query-uri
+ viz-scopes
+ {:ui-credential "test-ui-credential"
+ :session-id "test-session-id"})
+ {:keys [text mimeType _meta]} (first (:contents result))]
+ (is (= :ok (:status result)))
+ (is (= "text/html;profile=mcp-app" mimeType))
+ (is (str/includes? text (json/encode "test-ui-credential")))
+ (testing "and the host gets the sandbox CSP block it needs to render it"
+ (is (contains? (:ui _meta) :csp))
+ (is (true? (get-in _meta [:ui :prefersBorder]))))))
+ (testing "GHY-4157: the two shells hash differently — a CDN that dedupes by body would drop one"
+ (let [render (fn [uri] (-> (v2.resources/read-resource uri viz-scopes {}) :contents first :text))]
+ (is (not= (render v2.resources/visualize-query-uri)
+ (render v2.resources/render-drill-through-uri)))))))
+
+;;; ------------------------------------------ End-to-end contract -------------------------------------------------
+
+;; The other tests in this namespace stop at `registry/call-tool`'s return map — one side of a
+;; two-sided contract. That is why a suite this size stayed green while both tools rendered a
+;; permanent spinner: nothing asserted the emitted payload was one the iframe could act on.
+;;
+;; This test walks the whole loop instead: mint a handle, call the tool, then resolve the handle the
+;; tool returned over the same credential-authenticated route the iframe uses. It fails if the
+;; resolve endpoint is deleted, if the allowlist entry that admits it is removed, or if the tool
+;; stops emitting the key the iframe reads.
+
+(def ^:private ui-app-payload-keys
+ "The keys `useMcpApp.tsx` destructures out of `structuredContent`. `query` is v1's inline shape;
+ `query_handle` is v2's. The iframe short-circuits unless it finds one of them, so a payload
+ carrying neither renders nothing at all."
+ #{:query :query_handle})
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest visualize-query-payload-resolves-over-the-callback-route-test
+ (testing "GHY-4157: the handle visualize_query emits is resolvable by the iframe that receives it"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [user-id (mt/user->id :crowberto)]
+ (mt/with-current-user user-id
+ (let [sid (str (random-uuid))
+ minted (mint-mbql-handle! sid user-id)
+ body (payload (call! "visualize_query" sid {:query_handle minted}))
+ credential (mcp.session/issue-ui-credential sid user-id #{"agent:query:run"})]
+ (testing "the payload names a query in a shape the iframe reads"
+ (is (seq (filter (set (keys body)) ui-app-payload-keys))
+ (str "structuredContent has no key useMcpApp.tsx acts on: " (pr-str (keys body)))))
+ (testing "and resolving that handle over the callback route yields the query"
+ (let [{:keys [status body]}
+ (client/client-full-response
+ :get 200 (str "embed-mcp/queries/" (:query_handle body))
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential
+ "mcp-session-id" sid}}})]
+ (is (= 200 status))
+ (is (string? (:query body))
+ "the iframe needs a base64 query to build a card from")))))))))
+
+;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
+(deftest render-drill-through-payload-resolves-over-the-callback-route-test
+ (testing "GHY-4157: a drill handle survives the round trip the iframe makes"
+ (mt/with-model-cleanup [:model/McpQueryHandle]
+ (let [user-id (mt/user->id :crowberto)]
+ (mt/with-current-user user-id
+ (let [sid (str (random-uuid))
+ ;; The shape `POST /api/embed-mcp/drills` mints: legacy dataset_query, no prompt.
+ drill (mcp.session/store-handle! sid user-id "ZW5jb2RlZA==")
+ body (payload (call! "render_drill_through" sid {:query_handle drill}))
+ credential (mcp.session/issue-ui-credential sid user-id #{"agent:query:run"})]
+ (is (= drill (:query_handle body)))
+ (is (=? {:status 200 :body {:query "ZW5jb2RlZA=="}}
+ (client/client-full-response
+ :get 200 (str "embed-mcp/queries/" (:query_handle body))
+ {:request-options {:headers {"x-metabase-mcp-ui-auth" credential
+ "mcp-session-id" sid}}})))))))))
diff --git a/test/metabase/mcp/v2/write_test.clj b/test/metabase/mcp/v2/write_test.clj
new file mode 100644
index 00000000000..7ecd73bfe86
--- /dev/null
+++ b/test/metabase/mcp/v2/write_test.clj
@@ -0,0 +1,99 @@
+(ns metabase.mcp.v2.write-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.api.macros.scope :as api.scope]
+ [metabase.mcp.v2.write :as v2.write]))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private row
+ {:id 1 :name "Orders over time" :bookmarked true})
+
+(deftest ^:parallel readback-grants-full-row-test
+ (testing "a token holding every read scope gets the row unchanged"
+ (is (= row
+ (v2.write/readback #{"agent:content:read"} ["agent:content:read"] row [:bookmarked])))))
+
+(deftest ^:parallel readback-degrades-without-read-scope-test
+ (testing "a token missing the read scope gets id + ack-keys + a note, and never the row's other keys"
+ (let [result (v2.write/readback #{"agent:content:write"} ["agent:content:read"] row [:bookmarked])]
+ (is (= #{:id :note :bookmarked} (set (keys result)))
+ "name must not survive the degradation")
+ (is (true? (:bookmarked result))
+ "an ack-key the caller supplied survives")
+ (is (re-find #"agent:content:read" (:note result))
+ "the note names the missing scope"))))
+
+(deftest ^:parallel readback-refuses-empty-read-scopes-test
+ (testing "an empty read-scopes is refused rather than silently skipping the gate — `missing` would be
+ empty and the ungated row would come back looking exactly like a gate that passed"
+ (doseq [empty-scopes [[] nil]]
+ (testing (pr-str empty-scopes)
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"at least one read scope"
+ (v2.write/readback #{"agent:content:write"} empty-scopes row [:bookmarked])))))))
+
+(deftest ^:parallel readback-unrestricted-callers-get-the-row-test
+ (testing "the unrestricted sentinel and nil token-scopes (internal callers) both read back in full"
+ (is (= row (v2.write/readback #{::api.scope/unrestricted} ["agent:content:read"] row [:bookmarked])))
+ (is (= row (v2.write/readback nil ["agent:content:read"] row [:bookmarked])))))
+
+(deftest ^:parallel readback-note-pluralizes-test
+ (testing "one missing scope reads `scope`, several read `scopes`, and all are named"
+ (let [one (v2.write/readback #{} ["agent:content:read"] row nil)
+ many (v2.write/readback #{} ["agent:content:read" "agent:metadata:read"] row nil)]
+ (is (re-find #"the agent:content:read scope this token" (:note one)))
+ (is (re-find #"agent:content:read and agent:metadata:read scopes this" (:note many))))))
+
+(deftest ^:parallel readback-ack-key-absent-from-row-test
+ (testing "an ack-key the row doesn't carry is dropped rather than added as nil"
+ (let [result (v2.write/readback #{} ["agent:content:read"] {:id 1 :name "n"} [:bookmarked])]
+ (is (= #{:id :note} (set (keys result)))))))
+
+(deftest ^:parallel dispatch-write-test
+ (let [entry {:create-required [:name]}]
+ (testing "create enforces (create)-required fields"
+ (is (= [:create {:name "X"}] (v2.write/dispatch-write entry {:method "create" :name "X"})))
+ (is (thrown-with-msg? Exception #"`name` is required"
+ (v2.write/dispatch-write entry {:method "create"}))))
+ (testing "update requires id"
+ (is (= [:update 3 {:name "Y"}]
+ (v2.write/dispatch-write entry {:method "update" :id 3 :name "Y"})))
+ (is (thrown-with-msg? Exception #"`id` is required"
+ (v2.write/dispatch-write entry {:method "update"}))))
+ (testing "an unknown method is a teaching error"
+ (is (thrown-with-msg? Exception #"create.*update"
+ (v2.write/dispatch-write entry {:method "delete"}))))))
+
+(deftest ^:parallel dispatch-write-clear-test
+ (testing "GHY-4191: `clear` expands to explicit nils, the only way to say \"unset this\" — a null
+ can't, since the boundary strips nulls that strict clients flood every property with"
+ (let [entry {:create-required [:name] :clearable #{:description :cache_ttl}}]
+ (testing "a cleared property arrives as a present nil, which the update paths read as \"set to nil\""
+ (let [[_ _ args] (v2.write/dispatch-write entry {:method "update" :id 3 :clear ["description"]})]
+ (is (contains? args :description))
+ (is (nil? (:description args)))
+ (is (not (contains? args :clear)))))
+ (testing "clearing several at once, alongside an ordinary set"
+ (is (= [:update 3 {:name "Y" :description nil :cache_ttl nil}]
+ (v2.write/dispatch-write entry {:method "update" :id 3 :name "Y"
+ :clear ["description" "cache_ttl"]}))))
+ (testing "a property that isn't clearable is refused, and the message names what is"
+ (is (thrown-with-msg? Exception #"`name` can't be cleared. This tool can clear: cache_ttl, description"
+ (v2.write/dispatch-write entry {:method "update" :id 3 :clear ["name"]}))))
+ (testing "setting and clearing the same property in one call is a contradiction"
+ (is (thrown-with-msg? Exception #"both set and cleared"
+ (v2.write/dispatch-write entry {:method "update" :id 3
+ :description "x" :clear ["description"]}))))
+ (testing "clear is update-only — a new object has nothing set to clear"
+ (is (thrown-with-msg? Exception #"applies to method \"update\" only"
+ (v2.write/dispatch-write entry {:method "create" :name "X"
+ :clear ["description"]}))))
+ (testing "an empty or absent clear is a no-op, and never leaves :clear on the args"
+ (is (= [:update 3 {:name "Y"}]
+ (v2.write/dispatch-write entry {:method "update" :id 3 :name "Y" :clear []})))
+ (is (= [:create {:name "X"}]
+ (v2.write/dispatch-write entry {:method "create" :name "X" :clear []})))))
+ (testing "a tool declaring nothing clearable says so rather than listing an empty set"
+ (is (thrown-with-msg? Exception #"no clearable properties"
+ (v2.write/dispatch-write {:create-required []}
+ {:method "update" :id 3 :clear ["description"]}))))))
diff --git a/test/metabase/measures/api_test.clj b/test/metabase/measures/api_test.clj
index 36fff189aee..5aea9d6468d 100644
--- a/test/metabase/measures/api_test.clj
+++ b/test/metabase/measures/api_test.clj
@@ -2,6 +2,7 @@
"Tests for /api/measure endpoints."
{:clj-kondo/config '{:linters {:deprecated-var {:exclude {metabase.test.data/mbql-query {:namespaces [metabase.measures.api-test]}}}}}}
(:require
+ [clojure.string :as str]
[clojure.test :refer :all]
[metabase.api.response :as api.response]
[metabase.lib-be.core :as lib-be]
@@ -117,10 +118,14 @@
(testing "an updated definition must still be a valid MBQL query with a source table"
(mt/with-temp [:model/Measure {:keys [id]} {:table_id (mt/id :venues)
:definition (mbql5-measure-definition (mt/id :venues) (mt/id :venues :price))}]
- (is (=? {:errors {:definition some?}}
- (mt/user-http-request :crowberto :put 400 (str "measure/" id)
- {:revision_message "no more source table"
- :definition {}})))))
+ (let [response (mt/user-http-request :crowberto :put 400 (str "measure/" id)
+ {:revision_message "no more source table"
+ :definition {}})]
+ (is (=? {:errors {:definition some?}} response))
+ ;; The schema's own rule has to render, wherever malli files it. It used to be a
+ ;; `deferred-tru` under `:error/message`, which malli could not stringify, so the reason
+ ;; never reached the caller at all.
+ (is (str/includes? (pr-str response) "measure definition must have a source table")))))
(testing "a definition that moves the Measure to another table keeps table_id in sync"
(mt/with-temp [:model/Measure {:keys [id]} {:table_id (mt/id :venues)
:definition (mbql5-measure-definition (mt/id :venues) (mt/id :venues :price))}]
diff --git a/test/metabase/metabot/tools/construct_numeric_permissions_test.clj b/test/metabase/metabot/tools/construct_numeric_permissions_test.clj
new file mode 100644
index 00000000000..fc7b10fc4e7
--- /dev/null
+++ b/test/metabase/metabot/tools/construct_numeric_permissions_test.clj
@@ -0,0 +1,478 @@
+(ns metabase.metabot.tools.construct-numeric-permissions-test
+ "Permission-boundary tests for the numeric-id dialect (GHY-4410).
+
+ `construct_representations_test` runs against a mock metadata provider with `api/read-check`
+ and `api/query-check` stubbed to allow-all, which is right for testing resolution but cannot
+ observe enforcement. These tests use a real application database and a real unprivileged user,
+ so a missing check shows up as a leak rather than as a passing stub.
+
+ The invariant under test: on the numeric-id surface, an LLM-authored integer must denote
+ something this query may actually reference — a card the caller can read, a table in the
+ query's own database, a column the warehouse exposes — and must fail closed, and quietly, when
+ it does not. The portable dialect gets all of that from resolving names through a
+ database-scoped provider; the numeric dialect has to ask for it explicitly."
+ (:require
+ [clojure.test :refer [deftest is testing]]
+ [metabase.api.common :as api]
+ [metabase.collections.models.collection :as collection]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.metabot.db :as metabot.db]
+ [metabase.metabot.tools.construct :as construct]
+ [metabase.metabot.tools.shared.content-store :as shared.content-store]
+ [metabase.models.interface :as mi]
+ [metabase.models.serialization.resolve :as serdes.resolve]
+ [metabase.models.serialization.resolve.mp :as resolve.mp]
+ [metabase.permissions.core :as perms]
+ [metabase.permissions.models.permissions-group :as perms-group]
+ [metabase.permissions.test-util :as perms.test-util]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(defn- count-query
+ "A trivial `venues` count, built with Lib rather than the deprecated `mt/mbql-query`."
+ []
+ (let [mp (mt/metadata-provider)]
+ (-> (lib/query mp (lib.metadata/table mp (mt/id :venues)))
+ (lib/aggregate (lib/count)))))
+
+(defn- victim-query
+ "The unreadable card's query. The named expression and the aggregation are the point: both
+ produce result columns whose names appear nowhere in the caller's own request, so a leak of
+ this card's columns is unmistakable in an assertion."
+ []
+ (let [mp (mt/metadata-provider)
+ base (lib/query mp (lib.metadata/table mp (mt/id :venues)))
+ price (lib.metadata/field mp (mt/id :venues :price))
+ category (lib.metadata/field mp (mt/id :venues :category_id))]
+ (-> base
+ (lib/expression "SecretMargin" (lib/* (lib/ref price) 3))
+ (lib/aggregate (lib/count))
+ (lib/breakout (lib/ref category))
+ (as-> q (lib/breakout q (lib/expression-ref q "SecretMargin"))))))
+
+(defn- unreadable-card-thunk
+ "Run `f` with a card in crowberto's personal collection — which rasta cannot read — bound to
+ its id. The card carries a named expression and an aggregation so a column-name leak is
+ unmistakable in the assertion."
+ [f]
+ (let [victim-coll-id (:id (collection/user->personal-collection (mt/user->id :crowberto)))]
+ (mt/with-temp [:model/Card victim {:collection_id victim-coll-id
+ :database_id (mt/id)
+ :dataset_query (victim-query)}]
+ (f (:id victim)))))
+
+(defn- attempt-as-rasta
+ "Run `query` through the pipeline as rasta on the numeric-id surface, returning a map
+ describing the outcome rather than throwing."
+ [query]
+ (mt/with-current-user (mt/user->id :rasta)
+ (binding [serdes.resolve/*numeric-ids-allowed?* true]
+ (try
+ ;; Discard the resolved query: it is a large nested map and these tests only care
+ ;; whether the call was permitted.
+ (construct/execute-representations-query query)
+ {:outcome :resolved}
+ (catch clojure.lang.ExceptionInfo e
+ {:outcome :threw
+ :status (:status-code (ex-data e))
+ :error (:error (ex-data e))
+ :available (:available (ex-data e))
+ ;; Bounded: some pipeline messages embed a whole humanized schema explanation, which
+ ;; is large enough to blow the regex engine's stack when scanned for leaked names.
+ :message (let [m (or (ex-message e) "")]
+ (subs m 0 (min 400 (count m))))})))))
+
+(defn- db-name [] (t2/select-one-fn :name :model/Database :id (mt/id)))
+
+(deftest numeric-source-card-later-stage-is-read-checked-test
+ (testing (str "GHY-4410: a numeric `source-card` on a stage after the first must be read-checked.\n"
+ "`resolve-database-id-from-first-stage` only ever looks at stages[0], so before the\n"
+ "fix this reached repair's cross-stage column inference unchecked and reported the\n"
+ "card's column names — including an author-invented expression name — back to a\n"
+ "caller with no access to it.")
+ (mt/with-premium-features #{}
+ (unreadable-card-thunk
+ (fn [victim-id]
+ (let [result (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql" :source-table (mt/id :venues)}
+ {:lib/type "mbql.stage/mbql"
+ :source-card victim-id
+ :fields [["field" {} "zzz_not_a_column"]]}]})]
+ (is (= :threw (:outcome result))
+ "an unreadable card must not resolve")
+ (is (= 400 (:status result))
+ "denied as a plain not-found — see unreadable-and-missing-card-are-indistinguishable-test")
+ (is (= :unknown-card-id (:error result)))
+ (testing "no column of the unreadable card is reported, in ex-data or in the message"
+ (is (nil? (:available result)))
+ (doseq [leaked ["SecretMargin" "CATEGORY_ID" "count"]]
+ (is (not (re-find (re-pattern leaked) (:message result)))
+ (str "message must not name the card's column " leaked))))))))))
+
+(deftest numeric-source-card-alongside-source-table-is-read-checked-test
+ (testing (str "GHY-4410: `source-table` and `source-card` on the SAME first stage. The `cond` in\n"
+ "`resolve-database-id-from-first-stage` takes the `source-table` branch, so the card\n"
+ "never reaches that function's read check — the check has to live on the resolution\n"
+ "path itself, not in the database-id lookup.")
+ (mt/with-premium-features #{}
+ (unreadable-card-thunk
+ (fn [victim-id]
+ (let [result (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :venues)
+ :source-card victim-id
+ :fields [["field" {} "zzz_not_a_column"]]}]})]
+ (is (= :threw (:outcome result)))
+ (is (= 400 (:status result)))
+ (is (= :unknown-card-id (:error result)))
+ (is (nil? (:available result)))))))))
+
+(deftest numeric-source-card-readable-resolves-through-the-store-test
+ (testing (str "the check is not over-broad: a card the caller CAN read resolves through the same\n"
+ "read-checked store that denies an unreadable one.\n\n"
+ "Asserted at the store/resolver layer rather than end-to-end. End-to-end, the\n"
+ "success path runs `permissions.util/PathSchema` (a `mu/defn` return schema, so\n"
+ "dev/test only) on top of the already-deep pipeline call chain; java.util.regex\n"
+ "recurses once per quantifier iteration, and the combined depth overflows the\n"
+ "stack. Pre-existing and unrelated to this fix — the same `read-check` outside the\n"
+ "pipeline succeeds — so this pins the behavior that matters without depending on\n"
+ "it. Only the success path reaches there; the denial tests above are unaffected.")
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Card readable {:collection_id nil
+ :database_id (mt/id)
+ :dataset_query (count-query)}]
+ (mt/with-current-user (mt/user->id :rasta)
+ (binding [serdes.resolve/*numeric-ids-allowed?* true]
+ (is (some? (resolve.mp/card-by-id shared.content-store/default-store (:id readable)))
+ "a readable card must come back from the read-checked store")))))))
+
+(deftest numeric-source-card-unreadable-is-denied-by-the-store-test
+ (testing (str "the mirror of the test above, at the same layer: the read-checked store is what\n"
+ "turns an unreadable card into a denial, which is why routing the numeric branch\n"
+ "through it is the fix.")
+ (mt/with-premium-features #{}
+ (unreadable-card-thunk
+ (fn [victim-id]
+ (mt/with-current-user (mt/user->id :rasta)
+ (binding [serdes.resolve/*numeric-ids-allowed?* true]
+ (is (nil? (resolve.mp/card-by-id shared.content-store/default-store victim-id))
+ (str "an unreadable card must come back as nil from the read-checked store — "
+ "the denial is collapsed there so callers cannot tell it from a missing id")))))))))
+
+;;; ============================================================
+;;; Numeric ids must denote something this query may reference
+;;; ============================================================
+
+(deftest numeric-source-table-from-another-database-is-rejected-test
+ (testing (str "a numeric `source-table` pulling a table from a DIFFERENT database into a query\n"
+ "must not resolve.\n\n"
+ "The interesting case is a MIXED query, which is why this uses a join: when the only\n"
+ "source is the foreign table, `resolve-database-id-from-first-stage` simply builds the\n"
+ "provider for that table's own database and the query is consistently about database\n"
+ "B — no boundary crossed. The bug is a query rooted in database A that reaches into B.\n\n"
+ "The portable path gets this for free: `find-table` compares the FK's db name to the\n"
+ "provider's and throws. A bare id skips that, and `api/query-check` does not close the\n"
+ "gap — it asks whether the caller may query that table, never whether the table belongs\n"
+ "to this query's database.")
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Database other {:engine :h2 :name "OtherDB-xdb-test"}
+ :model/Table other-tbl {:db_id (:id other) :name "OTHER_TBL" :active true}]
+ (let [result (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :venues)
+ :joins [{:lib/type "mbql/join"
+ :alias "j"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (:id other-tbl)}]
+ :conditions [["=" {}
+ ["field" {} (mt/id :venues :id)]
+ ["field" {} (mt/id :venues :id)]]]}]}]})]
+ (is (= :threw (:outcome result))
+ "a foreign-database table must not resolve")
+ (is (= :unknown-table-id (:error result))
+ "and it is reported as an unresolvable reference, not as a permission failure"))))))
+
+(deftest foreign-database-table-is-never-permission-checked-test
+ (testing (str "the security property behind the test above, asserted directly: a table id from\n"
+ "another database must never reach `api/query-check`.\n\n"
+ "This is the assertion that actually pins the fix. The query is refused either way —\n"
+ "downstream resolution fails on a table its provider cannot see — but WHERE it is\n"
+ "refused decides whether a permission check ever ran against a foreign row. Handing\n"
+ "such an id to `query-check` asks 'may this user query table N?' with no reference to\n"
+ "the query's own database, so it answers yes for anyone with access to the other\n"
+ "database, and the refusal downstream becomes incidental rather than a boundary.")
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Database other {:engine :h2 :name "OtherDB-qcheck-test"}
+ :model/Table other-tbl {:db_id (:id other) :name "OTHER_TBL" :active true}]
+ (let [checked (atom [])
+ orig api/query-check]
+ (with-redefs [api/query-check (fn [& args]
+ (swap! checked conj (vec args))
+ (apply orig args))]
+ (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :venues)
+ :joins [{:lib/type "mbql/join"
+ :alias "j"
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (:id other-tbl)}]
+ :conditions [["=" {}
+ ["field" {} (mt/id :venues :id)]
+ ["field" {} (mt/id :venues :id)]]]}]}]}))
+ (is (not (contains? (set (map second @checked)) (:id other-tbl)))
+ (str "query-check must never see the foreign table id " (:id other-tbl)
+ "; it was called with " (pr-str @checked))))))))
+
+(deftest numeric-field-id-for-sensitive-column-is-rejected-test
+ (testing (str "a numeric field id naming a `:sensitive` column must not resolve. `metadata-spec->\n"
+ "honey-sql` drops its visibility filter for by-id lookups (`active-only?` is\n"
+ "`(not (or id-set name-set))`), which is right for trusted callers asking for a\n"
+ "specific row and wrong for an agent-authored id — the portable dialect cannot name\n"
+ "these columns at all, because they are absent from the by-name fetch.")
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Field sensitive {:table_id (mt/id :venues)
+ :name "SSN"
+ :base_type :type/Text
+ :database_type "VARCHAR"
+ :visibility_type "sensitive"
+ :active true}]
+ (let [result (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :venues)
+ :fields [["field" {} (:id sensitive)]]}]})]
+ (is (= :threw (:outcome result))
+ "a sensitive column must not be referenceable by id")
+ (is (not (re-find #"SSN" (or (:message result) "")))
+ "and the rejection must not echo the column's name back"))))))
+
+(deftest numeric-field-id-for-inactive-column-is-rejected-test
+ (testing "the same holds for an inactive column, which the warehouse no longer has"
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Field gone {:table_id (mt/id :venues)
+ :name "DROPPED_COL"
+ :base_type :type/Text
+ :database_type "VARCHAR"
+ :active false}]
+ (let [result (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :venues)
+ :fields [["field" {} (:id gone)]]}]})]
+ (is (= :threw (:outcome result))))))))
+
+(deftest numeric-source-table-existence-is-not-an-oracle-test
+ (testing (str "GHY-4410: a table the caller has no data access to must be reported exactly as one\n"
+ "that does not exist. `resolve-database-id-from-first-stage` runs before any\n"
+ "permission check — it is what decides which database the provider is for — so\n"
+ "without a read check there, a bare `t2/select-one` answers \"exists\" for a table in\n"
+ "a database the caller cannot touch, and the id argument becomes a way to enumerate\n"
+ "table ids instance-wide.\n\n"
+ "Note the perms have to be revoked at the DATA level: collection permissions do not\n"
+ "gate warehouse tables, so `with-non-admin-groups-no-root-collection-perms` leaves\n"
+ "`mi/can-read?` on a Table returning true.")
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Database other {:engine :h2 :name "OtherDB-oracle-test"}
+ :model/Table other-tbl {:db_id (:id other) :name "SECRET_TBL" :active true}]
+ (perms.test-util/with-no-data-perms-for-all-users!
+ ;; keep the query's own database usable so we are testing the *other* database's table,
+ ;; not a blanket denial
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/view-data :unrestricted)
+ (perms/set-database-permission! (perms-group/all-users) (mt/id) :perms/create-queries :query-builder)
+ (let [forbidden (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql" :source-table (:id other-tbl)}]})
+ nonexistent (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql" :source-table 999999999}]})]
+ (testing "both are refused"
+ (is (= :threw (:outcome forbidden)))
+ (is (= :threw (:outcome nonexistent))))
+ (testing "and they are indistinguishable — same status, and neither names the table"
+ (is (= (:status nonexistent) (:status forbidden)))
+ (is (not (re-find #"SECRET_TBL" (or (:message forbidden) "")))))))))))
+
+;;; ============================================================
+;;; Follow-ups from review (crisptrutski)
+;;; ============================================================
+
+(deftest numeric-field-id-in-two-element-form-is-checked-test
+ (testing (str "a numeric field id written as `[\"field\", 42]` — no options map — must be\n"
+ "collected and checked like the three-element form. Repair inserts the options map\n"
+ "later, so at collection time the target is still in slot 1; checking only slot 2\n"
+ "let this shape reach resolution unchecked.")
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Field sensitive {:table_id (mt/id :venues)
+ :name "SSN_TWO_SLOT"
+ :base_type :type/Text
+ :database_type "VARCHAR"
+ :visibility_type "sensitive"
+ :active true}]
+ (let [result (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :venues)
+ :fields [["field" (:id sensitive)]]}]})]
+ (is (= :threw (:outcome result))
+ "the two-element form must not slip past the referenceability check")
+ (is (not (re-find #"SSN_TWO_SLOT" (or (:message result) "")))
+ "and the rejection must not echo the column name"))))))
+
+(deftest sensitive-parent-hides-its-children-test
+ (testing (str "a visible child of a `:sensitive` parent must not be referenceable. A JSON column\n"
+ "unfolds into children carrying their own visibility, so checking only the named\n"
+ "field would let an ordinary-looking child reach inside a column the warehouse\n"
+ "marked unqueryable.")
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Field parent {:table_id (mt/id :venues)
+ :name "PAYLOAD"
+ :base_type :type/JSON
+ :database_type "JSON"
+ :visibility_type "sensitive"
+ :active true}
+ :model/Field child {:table_id (mt/id :venues)
+ :parent_id (:id parent)
+ :name "ssn"
+ :base_type :type/Text
+ :database_type "VARCHAR"
+ :active true}]
+ (let [result (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :venues)
+ :fields [["field" {} (:id child)]]}]})]
+ (is (= :threw (:outcome result))
+ "a child of a sensitive parent must be refused even though the child itself is visible")
+ (is (not (re-find #"PAYLOAD|ssn" (or (:message result) "")))
+ "and neither the parent nor the child is named back"))))))
+
+(deftest unreadable-and-missing-card-are-indistinguishable-test
+ (testing (str "a numeric `source-card` the caller cannot read must be reported exactly as one\n"
+ "that does not exist. Content ids are sequential and easy to guess, so a status-code\n"
+ "difference (403 for hidden vs 400 for absent) is an existence oracle. The collapse\n"
+ "lives in the read-checked store, so it covers cards, measures and segments at once.")
+ (mt/with-premium-features #{}
+ (unreadable-card-thunk
+ (fn [victim-id]
+ (let [forbidden (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql" :source-card victim-id}]})
+ missing (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql" :source-card 999999999}]})]
+ (testing "both are refused"
+ (is (= :threw (:outcome forbidden)))
+ (is (= :threw (:outcome missing))))
+ (testing "with the same status and the same error key"
+ (is (= (:status missing) (:status forbidden))
+ (str "status differed: missing=" (:status missing) " forbidden=" (:status forbidden)))
+ (is (= (:error missing) (:error forbidden))
+ (str "error key differed: missing=" (:error missing) " forbidden=" (:error forbidden))))))))))
+
+(deftest readable-table-lookup-passes-a-full-row-to-can-read-test
+ (testing (str "`readable-active-table-database-id` must hand `mi/can-read?` the whole Table row.\n\n"
+ "`can-read?` for a Table is polymorphic over the instance: its published-collection\n"
+ "branch reads `:is_published` and `:collection_id` (warehouse_schema/models/table.clj,\n"
+ "via `perms/can-access-via-collection?`). Selecting only `:id`/`:db_id` — as this fn\n"
+ "first did — makes that branch evaluate against absent keys, so a user whose access\n"
+ "comes through a published collection is told the table does not exist. Asserting on\n"
+ "the row the predicate receives pins the bug directly, without needing the EE\n"
+ "implementation (OSS `can-access-via-collection?` is a constant `false`).")
+ (mt/with-premium-features #{}
+ (let [seen (atom nil)]
+ (with-redefs [mi/can-read? (fn [row] (reset! seen row) true)]
+ (metabot.db/readable-active-table-database-id (mt/id :venues)))
+ (is (some? @seen) "can-read? should have been called")
+ (doseq [k [:id :db_id :is_published :collection_id]]
+ (is (contains? @seen k)
+ (str "the row handed to can-read? is missing " k
+ ", so any permission branch reading it silently fails")))))))
+
+;;; ============================================================
+;;; Second review round: the oracle via query-check, and scoped content
+;;; ============================================================
+
+(deftest metadata-only-table-is-not-an-oracle-via-query-check-test
+ (testing (str "GHY-4410: `mi/can-read?` is strictly weaker than `mi/can-query?` for a Table —\n"
+ "only `can-read?` has the `manage-table-metadata :yes` disjunct. So a metadata-only\n"
+ "user passes `visible-table` and the first-stage lookup, then lands on\n"
+ "`api/query-check`. A bare 403 there confirms the table exists, is active, and is in\n"
+ "this database — the same oracle the first-stage lookup already closes, one step\n"
+ "further along. The denial must look like a missing id instead.")
+ (mt/with-premium-features #{}
+ (let [deny-query-check (fn deny
+ ([obj] obj)
+ ([entity id] (deny entity id nil))
+ ([entity id & _]
+ (if (= entity :model/Table)
+ (throw (ex-info "You don't have permissions to do that."
+ {:status-code 403}))
+ {:model entity :id id})))]
+ (with-redefs [api/query-check deny-query-check]
+ (let [forbidden (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql" :source-table (mt/id :venues)}]})
+ nonexistent (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql" :source-table 999999999}]})]
+ (testing "both refused"
+ (is (= :threw (:outcome forbidden)))
+ (is (= :threw (:outcome nonexistent))))
+ (testing "and indistinguishable — same status and same error key"
+ (is (= 400 (:status forbidden))
+ (str "a query-check denial on a numeric ref must not surface as 403: "
+ (pr-str forbidden)))
+ (is (= (:status nonexistent) (:status forbidden)))
+ (is (= (:error nonexistent) (:error forbidden))))))))))
+
+(deftest numeric-measure-and-segment-reach-query-check-test
+ (testing (str "GHY-4410: a `[\"segment\" {} 43]` clause names neither a table nor a field, so\n"
+ "before this fix it matched no branch of `node-table-fks` and the table it is scoped\n"
+ "to never reached `api/query-check` at all. Read-check alone is not equivalent:\n"
+ "`mi/can-read?` on Segment delegates to the Table's `can-read?`, which is weaker than\n"
+ "`can-query?`.\n\n"
+ "The segment lives on a DIFFERENT table than the stage's `source-table`, so the\n"
+ "assertion cannot be satisfied by the source table's own check — that is what makes\n"
+ "this test able to fail.")
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/Segment {segment-id :id} {:table_id (mt/id :checkins)
+ :definition {}}]
+ (let [checked (atom [])
+ record (fn rec
+ ([obj] obj)
+ ([entity id] (rec entity id nil))
+ ([entity id & _] (swap! checked conj [entity id]) {:model entity :id id}))]
+ (with-redefs [api/query-check record]
+ (attempt-as-rasta
+ {:lib/type "mbql/query"
+ :database (db-name)
+ :stages [{:lib/type "mbql.stage/mbql"
+ :source-table (mt/id :venues)
+ :filters [["segment" {} segment-id]]}]}))
+ (let [seen (set (map second @checked))]
+ (is (contains? seen (mt/id :checkins))
+ (str "the segment's own table (checkins) must reach query-check; saw "
+ (pr-str @checked)))
+ (is (not= seen #{(mt/id :venues)})
+ "seeing only the source table means the segment ref was never collected")))))))
diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.clj
index 0da10894974..3a9d749116f 100644
--- a/test/metabase/metabot/tools/construct_representations_test.clj
+++ b/test/metabase/metabot/tools/construct_representations_test.clj
@@ -17,9 +17,13 @@
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
[metabase.lib.test-util :as lib.tu]
+ [metabase.mcp.v2.recovery-hints :as v2-hints]
+ [metabase.metabot.db :as metabot.db]
[metabase.metabot.tools.construct :as construct]
[metabase.metabot.tools.entity-details :as entity-details]
+ [metabase.metabot.tools.recovery-hints :as v1-hints]
[metabase.models.interface :as mi]
+ [metabase.models.serialization.resolve :as serdes.resolve]
[metabase.models.serialization.resolve.mp :as resolve.mp]))
(set! *warn-on-reflection* true)
@@ -362,10 +366,14 @@
(is (= "metric" (:entity-type d)))
(is (= "76" (:entity-id d)))
(is (= "metabase://metric/76" (:source-table d)))
- (is (re-find #"aggregation" (ex-message e))
- "message should point at aggregation-clause recovery")
- (is (re-find #"base_table_fully_qualified_name" (ex-message e))
- "message should name the attribute the LLM needs to look up on the metric")))))
+ (testing "the recovery sentence is the caller's, so the throw carries only the facts to build it"
+ (is (= "`source-table:` does not accept URIs like `metabase://metric/76`." (ex-message e)))
+ (is (re-find #"aggregation" (v1-hints/recovery-hint d))
+ "v1's table points at aggregation-clause recovery")
+ (is (re-find #"base_table_fully_qualified_name" (v1-hints/recovery-hint d))
+ "v1's table names the attribute the LLM looks up on the metric")
+ (is (re-find #"aggregation" (v2-hints/recovery-hint d))
+ "v2's table points at aggregation-clause recovery too, in its own vocabulary"))))))
(testing "question / model URI - hint points at `source-card:`"
(doseq [t ["question" "model" "card"]]
(try
@@ -378,8 +386,10 @@
(let [d (ex-data e)]
(is (= :uri-in-source-table (:error d)))
(is (= t (:entity-type d)))
- (is (re-find #"source-card" (ex-message e))
- (str "message for " t " should point at source-card:")))))))
+ (is (re-find #"source-card" (v1-hints/recovery-hint d))
+ (str "v1 hint for " t " points at source-card:"))
+ (is (re-find #"source-card" (v2-hints/recovery-hint d))
+ (str "v2 hint for " t " points at source-card:")))))))
(testing "table URI - hint points at portable FK form"
(try
(construct/resolve-database-id-from-first-stage
@@ -391,7 +401,8 @@
(let [d (ex-data e)]
(is (= :uri-in-source-table (:error d)))
(is (= "table" (:entity-type d)))
- (is (re-find #"portable FK" (ex-message e)))))))))
+ (is (re-find #"portable FK" (v1-hints/recovery-hint d)))
+ (is (re-find #"numeric table id" (v2-hints/recovery-hint d)))))))))
(deftest execute-representations-query-unknown-db-in-source-table-test
(testing (str "Post step-14-follow-up the first stage's `source-table[0]` is the sole source\n"
@@ -1065,6 +1076,338 @@
(is (= "TOTAL" (nth field-ref 2)))
(is (= "type/Float" (get opts "base-type"))))))))
+;;; ============================================================
+;;; Numeric-id dialect — accepted on the MCP v2 surface, rejected on the default (v1) surface
+;;; ============================================================
+
+(defmacro ^:private with-v2-surface
+ "Run `body` with numeric ids accepted, the way
+ `metabase.mcp.v2.common/execute-representations-query` binds it for the v2 dialect."
+ [& body]
+ `(binding [serdes.resolve/*numeric-ids-allowed?* true]
+ ~@body))
+
+(deftest numeric-ids-rejected-on-default-surface-test
+ (testing "the v1 surface keeps the portable-only contract: a numeric field id is a teaching error"
+ (with-mp-and-stubs!
+ (fn []
+ (try
+ (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "filters" [["=" {} ["field" {} 100] 0]]}]}))
+ (is false "expected throw")
+ (catch clojure.lang.ExceptionInfo e
+ (let [d (ex-data e)]
+ (is (true? (:agent-error? d)))
+ (is (= :numeric-field-id (:error d))))))))))
+
+(deftest numeric-source-rejected-on-default-surface-test
+ (testing "the v1 surface does not recognize a numeric source-table as a source at all"
+ (try
+ (construct/resolve-database-id-from-first-stage
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql" "source-table" 10}]})
+ (is false "expected throw")
+ (catch clojure.lang.ExceptionInfo e
+ (is (= :missing-source-in-first-stage (:error (ex-data e))))))))
+
+(deftest numeric-ids-resolve-on-v2-surface-test
+ (testing "on the MCP v2 surface a fully numeric query body resolves like the portable one"
+ (with-mp-and-stubs!
+ (fn []
+ (with-v2-surface
+ (let [result (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" 10
+ "aggregation" [["count" {}]]
+ "filters" [[">" {} ["field" {} 101] 0]]}]}))
+ q (get-in result [:structured-output :query])]
+ (is (= :mbql/query (:lib/type q)))
+ (is (= 1 (:database q)))
+ (is (= 10 (get-in q [:stages 0 :source-table])))
+ (testing "the numeric field ref survives resolution and gets its base-type stamped"
+ (let [filter-ref (nth (get-in q [:stages 0 :filters 0]) 2)]
+ (is (= [:field 101] [(first filter-ref) (nth filter-ref 2)]))
+ (is (= :type/Float (get-in filter-ref [1 :base-type])))))))))))
+
+(deftest numeric-implicit-join-resolves-on-v2-surface-test
+ (testing "repair auto-wires `source-field` for a numeric field ref on an FK-related table"
+ (with-mp-and-stubs!
+ (fn []
+ (with-v2-surface
+ (let [result (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" 10
+ "aggregation" [["count" {}]]
+ "breakout" [["field" {} 201]]}]}))
+ q (get-in result [:structured-output :query])
+ breakout-ref (get-in q [:stages 0 :breakout 0])]
+ (is (= 201 (nth breakout-ref 2)))
+ (is (= 102 (get-in breakout-ref [1 :source-field]))
+ "the FK column from ORDERS to PRODUCTS is filled in, same as for a portable ref")))))))
+
+(deftest with-recovery-hint-preserves-original-as-cause-test
+ (testing (str "`with-recovery-hint` rebuilds the ex-info with the ORIGINAL exception as its\n"
+ "cause, so the throw-site stack trace survives — not the original's own cause,\n"
+ "which would drop the frame where the agent error was actually raised.")
+ (let [original (ex-info "boom" {:agent-error? true :error :unknown-database})
+ hinted (#'construct/with-recovery-hint original (constantly "do the thing"))]
+ (testing "message carries the hint"
+ (is (= "boom do the thing" (ex-message hinted))))
+ (testing "the original exception is the direct cause (not its cause, which is nil here)"
+ (is (identical? original (ex-cause hinted)))))))
+
+(defn- with-recording-query-check!
+ "Run `f`, recording every `[model id]` pair passed to `api/query-check`. Returns the set of
+ `:model/Table` ids that were checked."
+ [f]
+ (let [checked (atom [])
+ record (fn ([obj] obj)
+ ([entity id] (swap! checked conj [entity id]) {:model entity :id id})
+ ([entity id & _] (swap! checked conj [entity id]) {:model entity :id id}))]
+ (with-redefs [lib-be/application-database-metadata-provider (fn [_] mp)
+ construct/resolve-database-id-from-first-stage (fn [_] 1)
+ api/read-check record
+ api/query-check record]
+ (f))
+ (into #{} (comp (filter (fn [[m _]] (= m :model/Table))) (map second)) @checked)))
+
+(deftest numeric-field-ref-permission-checks-fk-target-table-test
+ (testing (str "a bare numeric field ref on an FK-related table is permission-checked on that\n"
+ "table before repair — the numeric surface must not bypass the check the portable\n"
+ "form gets. Without collecting the numeric field id, `api/query-check` would never\n"
+ "see the FK-target table, and a sandboxed user could break out by an id on a table\n"
+ "they have no data perms for.")
+ (with-v2-surface
+ (let [tables (with-recording-query-check!
+ (fn []
+ (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" 10
+ "aggregation" [["count" {}]]
+ "breakout" [["field" {} 201]]}]}))))]
+ (testing "the source table (ORDERS, 10) is checked"
+ (is (contains? tables 10)))
+ (testing "the FK-target table the numeric field lives on (PRODUCTS, 20) is checked"
+ (is (contains? tables 20)))))))
+
+(deftest numeric-field-ref-permission-check-blocks-forbidden-fk-target-test
+ (testing (str "when data perms on the FK-target table are denied, the numeric field ref surfaces\n"
+ "the 403 during the pre-repair check — the query never reaches repair's implicit-join\n"
+ "auto-wire, so no `source-field` path for the forbidden table is exported to the agent.")
+ (with-v2-surface
+ (let [deny-table-20 (fn deny
+ ([obj] obj)
+ ([entity id] (deny entity id nil))
+ ([entity id & _]
+ (if (and (= entity :model/Table) (= id 20))
+ (throw (ex-info "You don't have permissions to do that." {:status-code 403}))
+ {:model entity :id id})))]
+ (with-redefs [lib-be/application-database-metadata-provider (fn [_] mp)
+ construct/resolve-database-id-from-first-stage (fn [_] 1)
+ api/read-check deny-table-20
+ api/query-check deny-table-20]
+ (try
+ (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" 10
+ "aggregation" [["count" {}]]
+ "breakout" [["field" {} 201]]}]}))
+ (is false "expected a throw, got a resolved query (permission bypass)")
+ (catch clojure.lang.ExceptionInfo e
+ ;; Numeric refs collapse a query-check denial to the same not-found a missing id
+ ;; gets, so the status cannot be used to probe for tables. What this test guards is
+ ;; unchanged: the denial stops resolution before repair's implicit-join auto-wire.
+ (is (= 400 (:status-code (ex-data e))))
+ (is (= :unknown-table-id (:error (ex-data e)))))))))))
+
+;;; ----- numeric `source-card:` -----------------------------------------------------------
+
+(defn- numeric-card-source
+ "A v2-dialect first stage sourcing `card-id` by bare numeric id."
+ [card-id]
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql" "source-card" card-id}]})
+
+(defn- with-stubbed-card!
+ "Run `f` with `metabot.db/card` serving only card 500, and `api/read-check` bound to
+ `read-check`. Stubs the model lookup rather than the content store: the numeric
+ `source-card` branch resolves the database id straight off the card row, before any
+ metadata provider or resolver exists."
+ [read-check f]
+ (with-redefs [metabot.db/card (fn [id] (when (= id 500) {:id 500 :database_id 1}))
+ api/read-check read-check]
+ (f)))
+
+(deftest numeric-source-card-resolves-database-id-test
+ (testing "on the v2 surface a bare numeric `source-card:` resolves to the card's database id"
+ (with-v2-surface
+ (with-stubbed-card! allow-read-check
+ (fn []
+ (is (= 1 (construct/resolve-database-id-from-first-stage (numeric-card-source 500)))))))))
+
+(deftest numeric-source-card-is-read-checked-test
+ (testing "the numeric `source-card:` branch read-checks the card it resolves"
+ (with-v2-surface
+ (let [checked (atom [])]
+ (with-stubbed-card! (fn [obj] (swap! checked conj obj) obj)
+ (fn []
+ (construct/resolve-database-id-from-first-stage (numeric-card-source 500))))
+ (is (= [{:id 500 :database_id 1}] @checked)
+ "the resolved card row is handed to api/read-check")))))
+
+(deftest numeric-source-card-denied-never-yields-database-id-test
+ (testing "a numeric `source-card:` the user cannot read never yields the database id"
+ (with-v2-surface
+ (with-stubbed-card! (fn [_] (throw (ex-info "You don't have permissions to do that."
+ {:status-code 403})))
+ (fn []
+ (try
+ (construct/resolve-database-id-from-first-stage (numeric-card-source 500))
+ (is false "expected a throw, got a resolved database id (permission bypass)")
+ (catch clojure.lang.ExceptionInfo e
+ ;; Collapsed to not-found, not 403: an unreadable card and an absent one must be
+ ;; indistinguishable, or the status code probes for hidden cards. The check still
+ ;; runs — that is what this test guards.
+ (is (= :unknown-card-id (:error (ex-data e)))))))))))
+
+(deftest numeric-source-card-read-checked-without-current-user-test
+ (testing (str "the read check does not depend on `api/*current-user-id*` being bound.\n"
+ "A user-less caller must fail closed like any other: guarding the check on a\n"
+ "bound user makes the numeric branch fail OPEN, while its portable sibling\n"
+ "(`tools.u/get-card-by-entity-id`) read-checks unconditionally.")
+ (with-v2-surface
+ (binding [api/*current-user-id* nil]
+ (with-stubbed-card! (fn [_] (throw (ex-info "You don't have permissions to do that."
+ {:status-code 403})))
+ (fn []
+ (try
+ (construct/resolve-database-id-from-first-stage (numeric-card-source 500))
+ (is false "expected a throw, got a resolved database id (permission bypass)")
+ (catch clojure.lang.ExceptionInfo e
+ ;; The point here is that the check RUNS with no bound user; the denial is
+ ;; collapsed to not-found like every other one.
+ (is (= :unknown-card-id (:error (ex-data e))))))))))))
+
+(deftest numeric-source-card-unknown-id-surfaces-agent-error-test
+ (testing (str "a numeric `source-card:` naming no card surfaces `:unknown-card-id`, not a 404 — "
+ "the numeric-specific key, since a numeric miss and a portable-entity_id miss want "
+ "different recovery advice")
+ (with-v2-surface
+ (with-stubbed-card! allow-read-check
+ (fn []
+ (try
+ (construct/resolve-database-id-from-first-stage (numeric-card-source 999))
+ (is false "expected throw")
+ (catch clojure.lang.ExceptionInfo e
+ (let [d (ex-data e)]
+ (is (true? (:agent-error? d)))
+ (is (= :unknown-card-id (:error d)))
+ (is (= 999 (:card-id d)))))))))))
+
+;;; ----- numeric `source-table:` that resolves to nothing ----------------------------------
+
+(deftest numeric-source-table-unknown-id-surfaces-agent-error-test
+ (testing (str "a numeric `source-table:` naming no active table surfaces `:unknown-table-id`,\n"
+ "distinct from the portable form's `:unknown-table` — the two want different\n"
+ "recovery vocabulary, so the keys must not be collapsed.")
+ (with-v2-surface
+ (with-redefs [metabot.db/readable-active-table-database-id (fn [_] nil)]
+ (try
+ (construct/resolve-database-id-from-first-stage
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql" "source-table" 999}]})
+ (is false "expected throw")
+ (catch clojure.lang.ExceptionInfo e
+ (let [d (ex-data e)]
+ (is (true? (:agent-error? d)))
+ (is (= :unknown-table-id (:error d)))
+ (is (= 999 (:table-id d)))
+ (testing "the id renders without locale digit grouping"
+ (is (str/includes? (ex-message e) "999"))))))))))
+
+;;; ----- recovery-hint passthrough ---------------------------------------------------------
+
+(deftest with-recovery-hint-passthrough-test
+ (testing "an error is returned unchanged when there is no hint to add"
+ (let [original (ex-info "boom" {:agent-error? true :error :unknown-database})]
+ (testing "no recovery-hint function at all"
+ (is (identical? original (#'construct/with-recovery-hint original nil))))
+ (testing "a recovery-hint function with nothing to say about this error"
+ (is (identical? original (#'construct/with-recovery-hint original (constantly nil))))))))
+
+(deftest portable-dialect-still-resolves-on-v2-surface-test
+ (testing "surface isolation: the identical portable query resolves under both surfaces"
+ (with-mp-and-stubs!
+ (fn []
+ (let [q (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "aggregation" [["count" {}]]}]})
+ strip-run-specific
+ (fn [query]
+ (walk/postwalk (fn [node]
+ (cond-> node (map? node) (dissoc :lib/uuid :lib/metadata)))
+ query))
+ v1 (get-in (construct/execute-representations-query q) [:structured-output :query])
+ v2 (with-v2-surface
+ (get-in (construct/execute-representations-query q) [:structured-output :query]))]
+ (is (= 10 (get-in v1 [:stages 0 :source-table])))
+ (is (= (strip-run-specific v1) (strip-run-specific v2))))))))
+
+(deftest v2-surface-error-hints-name-v2-tools-test
+ (testing "resolution errors under the v2 surface steer to browse_data/search, never read_resource"
+ (with-mp-and-stubs!
+ (fn []
+ (with-v2-surface
+ (try
+ (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "NOPE"]
+ "aggregation" [["count" {}]]}]})
+ {:recovery-hint v2-hints/recovery-hint})
+ (is false "expected throw")
+ (catch clojure.lang.ExceptionInfo e
+ (is (= :unknown-table (:error (ex-data e))))
+ (is (re-find #"browse_data" (ex-message e)))
+ (is (not (re-find #"read_resource|metabase://" (ex-message e)))))))))))
+
+(deftest numeric-aggregation-index-ref-in-order-by-v2-test
+ (testing (str "`[aggregation, {}, <index>]` composes with numeric field refs: the repair pass\n"
+ "rewrites it to the canonical UUID-keyed form, so the agent never authors a lib/uuid")
+ (with-mp-and-stubs!
+ (fn []
+ (with-v2-surface
+ (let [result (construct/execute-representations-query
+ (query-data
+ {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" 10
+ "aggregation" [["sum" {} ["field" {} 101]]
+ ["count" {}]]
+ "breakout" [["field" {} 102]]
+ "order-by" [["desc" {} ["aggregation" {} 0]]]}]}))
+ q (get-in result [:structured-output :query])
+ agg-uuid (get-in q [:stages 0 :aggregation 0 1 :lib/uuid])
+ order-ref (get-in q [:stages 0 :order-by 0 2])]
+ (is (string? agg-uuid))
+ (is (= :aggregation (first order-ref)))
+ (is (= agg-uuid (nth order-ref 2)))))))))
+
;;; ============================================================
;;; Metric aggregations end-to-end: YoY growth via metric + offset
;;; ============================================================
@@ -1175,6 +1518,11 @@
"Metric123_456DefGhI78")
(def ^:private mock-db-id
+ "Must not exist as a `metabase_database` row. `mp-metric` composes two mocks, and a
+ `ComposedMetadataProvider` extends `CachedMetadataProvider` — so `resolve.mp/table-candidates`
+ treats it as app-DB-backed once the app DB is up and resolves portable FKs against the app DB
+ rather than this provider. With db id 1 that found the real Sample Database's ORDERS, which has
+ no CAMPAIGN_ID, and the failure surfaced only once another namespace had booted the app DB."
Integer/MAX_VALUE)
(def ^:private mp-metric-base
@@ -1266,8 +1614,9 @@
(deftest metric-joined-breakout-without-join-errors-actionably-test
(testing (str "A consumer query that OMITS the join (bare breakout on CAMPAIGNS.NAME) is NOT "
- "silently repaired: it errors :no-fk-path with an actionable message that points the "
- "LLM at the metric's dimensions resource for the exact join to add (BOT-1612).")
+ "silently repaired: it errors :no-fk-path with an actionable message that explains "
+ "the explicit join. The `metabase://` metric-dimensions URI is surface-specific "
+ "vocabulary, so it lives in the v1 recovery-hint, not the base message (BOT-1612).")
(with-joined-metric-mp-and-stubs!
(fn []
(try
@@ -1278,15 +1627,18 @@
"stages" [{"lib/type" "mbql.stage/mbql"
"source-table" ["Sample" "PUBLIC" "ORDERS"]
"aggregation" [["metric" {} metric-eid]]
- "breakout" [["field" {} ["Sample" "PUBLIC" "CAMPAIGNS" "NAME"]]]}]}))
+ "breakout" [["field" {} ["Sample" "PUBLIC" "CAMPAIGNS" "NAME"]]]}]})
+ {:recovery-hint v1-hints/recovery-hint})
(is false "expected throw")
(catch clojure.lang.ExceptionInfo e
(let [d (ex-data e)]
(is (= :no-fk-path (:error d)))
(is (:agent-error? d))
- (testing "message is actionable: explains the explicit join and points at the metric resource"
- (is (str/includes? (ex-message e) "joins:"))
- (is (str/includes? (ex-message e) "metabase://metric"))))))))))
+ (testing "base message is actionable and surface-neutral: explains the explicit join, no URI"
+ (is (str/includes? (ex-message e) "joins:")))
+ (testing "the v1 recovery-hint carries the `metabase://` metric-dimensions vocabulary"
+ (is (str/includes? (ex-message e) "metabase://metric"))
+ (is (str/includes? (v1-hints/recovery-hint d) "metabase://metric"))))))))))
(deftest metric-details-surfaced-artifacts-round-trip-test
(testing (str "END-TO-END: the join AND the per-dimension reference that `metric-details` surfaces "
diff --git a/test/metabase/metabot/tools/search_test.clj b/test/metabase/metabot/tools/search_test.clj
index 7f250a24a7d..0d41d828e6a 100644
--- a/test/metabase/metabot/tools/search_test.clj
+++ b/test/metabase/metabot/tools/search_test.clj
@@ -12,8 +12,10 @@
[metabase.permissions.core :as perms]
[metabase.permissions.models.permissions-group :as perms-group]
[metabase.search.core :as search-core]
+ [metabase.search.engine :as search.engine]
[metabase.search.test-util :as search.tu]
[metabase.test :as mt]
+ [metabase.transforms.feature-gating :as transforms.gating]
[metabase.util :as u]
[toucan2.core :as t2]))
@@ -157,6 +159,32 @@
;; Item 99 appears in all 5 lists at position 2, so should rank very high
(is (= 99 (:id (first result)))))))
+(deftest multi-query-total-is-deduped-not-summed-test
+ (testing "under multi-query fusion, :total is the size of the deduped fused set, not the sum of
+ per-query counts — the real reciprocal-rank-fusion feeds search-results, so an item
+ appearing in both queries is counted once"
+ (mt/with-test-user :rasta
+ (with-redefs [perms/impersonated-user? (fn [] false)
+ perms/sandboxed-user? (fn [] false)
+ ;; default engine only, so both queries run through the same ranked-fn* branch
+ search.engine/active-engines (constantly [:search.engine/appdb])
+ search.engine/disjunction (fn [_ terms] terms)
+ ;; two queries, overlapping on item 1 (in both) — union is {1 2 3}, sum is 4
+ search-core/ranked-results (fn [context]
+ (if (= (:search-string context) "a")
+ [{:id 1 :model "card" :name "Shared"}
+ {:id 2 :model "card" :name "OnlyA"}]
+ [{:id 1 :model "card" :name "Shared"}
+ {:id 3 :model "card" :name "OnlyB"}]))
+ ;; the real search-results is app-db-bound; stand in with a faithful passthrough
+ ;; that reports total over the (already fused + deduped) ranking it is handed.
+ search-core/search-results (fn [_ctx _model-set ranked]
+ {:data (vec ranked) :total (count ranked)})]
+ (let [results (search/search {:term-queries ["a" "b"] :entity-types ["question"] :limit 10})]
+ ;; three distinct items survive fusion; total counts them once, not 2+2=4
+ (is (= 3 (:total (meta results))))
+ (is (= #{1 2 3} (set (map :id results)))))))))
+
(deftest ^:parallel postprocess-search-result-test
(testing "table result postprocessing"
(let [result {:model "table"
@@ -370,16 +398,16 @@
perms/sandboxed-user? (fn [] false)
api/*current-user-id* 1]
(testing ":search-native-query is included in context when true"
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (is (true? (:search-native-query context)))
- {:data []})]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [context]
+ (is (true? (:search-native-query context)))
+ [])]
(search/search {:term-queries ["test"]
:entity-types ["card"]
:search-native-query true})))
(testing ":search-native-query is not included in context when nil or false"
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (is (not (contains? context :search-native-query)))
- {:data []})]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [context]
+ (is (not (contains? context :search-native-query)))
+ [])]
(search/search {:term-queries ["test"]
:entity-types ["card"]
:search-native-query false})
@@ -395,9 +423,9 @@
api/*current-user-id* 1]
(testing "nlq-search-tool with no entity_types searches only table/model/metric/question"
(let [captured (atom nil)]
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (reset! captured (:models context))
- {:data []})]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [context]
+ (reset! captured (:models context))
+ [])]
(search/nlq-search-tool {:keyword_queries ["x"]}))
(is (= #{"table" "dataset" "metric" "card"} @captured))
(is (not (contains? @captured "dashboard")))
@@ -405,30 +433,30 @@
(is (not (contains? @captured "database")))))
(testing "sql-search-tool with no entity_types searches only table/model"
(let [captured (atom nil)]
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (reset! captured (:models context))
- {:data []})]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [context]
+ (reset! captured (:models context))
+ [])]
(search/sql-search-tool {:keyword_queries ["x"] :database_id 1}))
(is (= #{"table" "dataset"} @captured))))
(testing "general search includes documents in its default entity types"
(let [captured (atom nil)]
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (reset! captured (:models context))
- {:data []})]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [context]
+ (reset! captured (:models context))
+ [])]
(search/search-tool {:keyword_queries ["x"]}))
(is (contains? @captured "document"))))
(testing "agent-supplied entity_types narrow the default allowed set"
(let [captured (atom nil)]
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (reset! captured (:models context))
- {:data []})]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [context]
+ (reset! captured (:models context))
+ [])]
(search/nlq-search-tool {:keyword_queries ["x"] :entity_types ["metric"]}))
(is (= #{"metric"} @captured))))
(testing "NLQ search accepts document and dashboard destination types"
(let [captured (atom nil)]
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (reset! captured (:models context))
- {:data []})]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [context]
+ (reset! captured (:models context))
+ [])]
(search/nlq-search-tool {:keyword_queries ["plan"]
:entity_types ["document" "dashboard"]}))
(is (= #{"document" "dashboard"} @captured))))))))
@@ -441,16 +469,20 @@
api/*current-user-id* 1]
(testing "default limit is 10 when not provided"
(let [captured (atom nil)]
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (reset! captured (:limit-int context))
- {:data []})]
+ ;; limit/offset moved out of the per-query ranked-results context into the single
+ ;; paginate step, so the limit assertion now reads the search-results context.
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [_] [])
+ search-core/search-results (fn [context _ _]
+ (reset! captured (:limit-int context))
+ {:data [] :total 0})]
(search/search-tool {:keyword_queries ["x"]}))
(is (= 10 @captured))))
(testing "explicit limit is honored"
(let [captured (atom nil)]
- (mt/with-dynamic-fn-redefs [search-core/search (fn [context]
- (reset! captured (:limit-int context))
- {:data []})]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results (fn [_] [])
+ search-core/search-results (fn [context _ _]
+ (reset! captured (:limit-int context))
+ {:data [] :total 0})]
(search/search-tool {:keyword_queries ["x"] :limit 25}))
(is (= 25 @captured))))
(testing "limit above 50 is rejected by schema validation"
@@ -523,7 +555,35 @@
{:id 1 :type "dashboard" :name "Unrelated dashboard"}]]
(is (= [{:id document-id :type "document" :name "Existing document" :can_write true}
{:id 1 :type "dashboard" :name "Unrelated dashboard"}]
- (#'search/validate-and-enrich-documents results))))))))
+ (#'search/validate-and-enrich-documents false results))))))))
+
+(deftest archived-document-hits-survive-an-archived-search-test
+ (testing "GHY-4137: the staleness check must validate document hits against the archived set the
+ search actually asked for. With a hardcoded `:archived false`, every archived document
+ was dropped from the page while `:total` still counted it — an empty page no offset
+ could ever reach."
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Document {archived-id :id} {:name "Archived doc" :archived true}
+ :model/Document {active-id :id} {:name "Active doc" :archived false}]
+ (testing "an archived hit survives an archived search"
+ (is (= [archived-id]
+ (map :id (#'search/validate-and-enrich-documents
+ true
+ [{:id archived-id :type "document" :name "Archived doc"}])))))
+ (testing "an active hit is stale for an archived search"
+ (is (= []
+ (#'search/validate-and-enrich-documents
+ true
+ [{:id active-id :type "document" :name "Active doc"}]))))
+ (testing "the active search is unchanged: active survives, archived is stale"
+ (is (= [active-id]
+ (map :id (#'search/validate-and-enrich-documents
+ false
+ [{:id active-id :type "document" :name "Active doc"}]))))
+ (is (= []
+ (#'search/validate-and-enrich-documents
+ false
+ [{:id archived-id :type "document" :name "Archived doc"}]))))))))
(deftest enrich-with-collection-descriptions-test
(mt/with-premium-features #{:content-verification}
@@ -706,6 +766,87 @@
:base_table_schema
:base_table_portable_fk])))))))))
+(deftest confined-collection-is-not-overridable-test
+ (testing "an embedded metabot (and the nlq profile) is confined to its own collection — that is a
+ containment boundary, not a default. An explicit collection-id, which the v2 search tool
+ passes from a caller-supplied filter, must not widen or relocate the search outside that
+ collection."
+ (mt/with-test-user :crowberto
+ (mt/with-temp [:model/Collection {confined-id :id} {:name "Bot's collection"}
+ :model/Collection {elsewhere-id :id} {:name "Somewhere else"}
+ :model/Metabot {metabot-eid :entity_id} {:name "confined bot"
+ :collection_id confined-id}]
+ (let [collection-for (fn [search-args]
+ (let [captured (atom ::unset)]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results
+ (fn [context]
+ (reset! captured (:collection context))
+ [])]
+ (search/search (merge {:term-queries ["anything"]
+ :entity-types ["dashboard"]
+ :profile-id "nlq"
+ :metabot-id metabot-eid}
+ search-args)))
+ @captured))]
+ (testing "with no collection-id, the metabot's own collection scopes the search"
+ (is (= confined-id (collection-for {}))))
+ (testing "an explicit collection-id elsewhere cannot escape the confinement"
+ (is (= confined-id (collection-for {:collection-id elsewhere-id}))))
+ (testing "an unconfined metabot still honours an explicit collection-id"
+ (mt/with-temp [:model/Metabot {open-eid :entity_id} {:name "open bot" :collection_id nil}]
+ (is (= elsewhere-id (collection-for {:metabot-id open-eid
+ :collection-id elsewhere-id}))))))))))
+
+(deftest transform-visibility-is-superuser-only-test
+ (testing "this pipeline dropped remove-unreadable-transforms and relies instead on the transform
+ search spec's `:visibility :superuser`. Pin the narrowing: the engine is asked for
+ transforms when the caller is a superuser, and never when they are not. If this goes red,
+ the removed post-filter is load-bearing again.
+ The visibility rule itself is covered by metabase.search.filter-test."
+ ;; Two environment inputs are pinned rather than inherited, because leaving either to the ambient
+ ;; environment is what made this test pass on H2 while failing on the MySQL/MariaDB EE shards —
+ ;; there the positive control failed, so every assertion here was proving nothing.
+ ;;
+ ;; 1. The transform source types: the in-place engine drops transform for EVERYONE when
+ ;; `enabled-transform-source-types` is empty ((empty? enabled-types) (disj "transform") in
+ ;; search/in_place/filter.clj) — a gate the appdb path has no equivalent of. This is pinned by
+ ;; redefining `transforms.gating/enabled-source-types`, the single seam search/impl.clj reads it
+ ;; from, rather than by writing the `transforms-enabled` setting. Writing that setting would
+ ;; outlive this test: `with-temporary-setting-values` restores by writing back whatever
+ ;; `setting/get` returned at capture time, so a setting that was UNSET on entry comes back
+ ;; explicitly set, permanently defeating the `if-some` fallback in its getter for every later
+ ;; test in the JVM.
+ ;; 2. The engine: appdb and in-place gate transforms by different code, and MySQL/MariaDB fall
+ ;; back to in-place because the app DB cannot hold the search index. Running both here means
+ ;; the shard's engine choice can no longer decide whether this test means anything.
+ (mt/with-premium-features #{:transforms-basic}
+ (mt/with-dynamic-fn-redefs [transforms.gating/enabled-source-types (constantly #{"native" "mbql" "python"})]
+ (search.tu/with-appdb-search-and-legacy-search
+ ;; `api/*is-superuser?*` is bound explicitly rather than inferred from the test user, which
+ ;; resolves it through a SELECT on the shared user row. Both engines read exactly this var
+ ;; to gate transforms, and pinning it is what the assertion is about: that this pipeline
+ ;; propagates the caller's superuser status, not where that status came from.
+ (let [models-for (fn [superuser?]
+ (let [captured (atom nil)]
+ (mt/with-test-user :crowberto
+ (binding [api/*is-superuser?* superuser?]
+ (mt/with-dynamic-fn-redefs [search-core/ranked-results
+ (fn [context]
+ (reset! captured (:models context))
+ [])]
+ (search/search {:term-queries ["anything"]
+ :entity-types ["transform" "dashboard"]}))))
+ @captured))]
+ (testing "a superuser's search reaches the engine with transforms in scope"
+ (let [models (models-for true)]
+ (is (contains? models "transform"))
+ (is (contains? models "dashboard")
+ "sanity: the positive control really did reach the engine")))
+ (testing "a non-superuser's search never asks the engine for transforms"
+ (let [models (models-for false)]
+ (is (not (contains? models "transform")))
+ (is (contains? models "dashboard")
+ "sanity: the other requested type is unaffected, so this isn't an empty-set pass")))))))))
(deftest remove-unreadable-transforms-test
(testing "remove-unreadable-transforms correctly filters transforms based on source database access"
(mt/with-premium-features #{:transforms-basic}
diff --git a/test/metabase/metabot/tools/shared/content_store_test.clj b/test/metabase/metabot/tools/shared/content_store_test.clj
index cae67b24e64..ddca1c9bd55 100644
--- a/test/metabase/metabot/tools/shared/content_store_test.clj
+++ b/test/metabase/metabot/tools/shared/content_store_test.clj
@@ -165,7 +165,11 @@
(deftest suppressing-the-audit-trail-still-checks-every-method-test
(testing (str "with `*audit-refusals?*` bound off, every method (including the audited "
"`-by-entity-id` ones and an `audited-by-id?` store) still admits a readable "
- "row and still 403s an unreadable one, without going through `api/read-check`")
+ "row and still refuses an unreadable one, without going through `api/read-check`.\n\n"
+ "A refusal shows up differently per method by design: `-by-entity-id` 403s, and "
+ "`-by-id` comes back nil so a guessable id cannot be used to probe for hidden "
+ "content — see `collapses-read-check-403-for-numeric-lookups-test`. Both are the "
+ "check having run, which is what this asserts.")
(let [row (stub-row {:opaque :marker})]
(doseq [audited-by-id? [false true]]
(let [store (record-store {:card row :measure-eid row :segment-eid row
@@ -179,40 +183,56 @@
(binding [*stub-can-read?* true]
(is (= row (lookup gated arg))))
(binding [*stub-can-read?* false]
- (try
- (lookup gated arg)
- (is false "expected throw")
- (catch clojure.lang.ExceptionInfo e
- (is (= 403 (:status-code (ex-data e)))))))))))))))
+ (if (int? arg)
+ (is (nil? (lookup gated arg))
+ "a -by-id refusal collapses rather than throwing")
+ (try
+ (lookup gated arg)
+ (is false "expected throw")
+ (catch clojure.lang.ExceptionInfo e
+ (is (= 403 (:status-code (ex-data e))))))))))))))))
-(deftest propagates-read-check-403-test
- (testing "if read-check throws (403), the entity-id (import-direction) branch propagates the exception unchanged"
+(deftest collapses-read-check-403-for-numeric-lookups-test
+ (testing (str "a read-check denial on a NUMERIC-id lookup comes back as nil rather than
+ propagating the 403; an entity_id lookup still throws.\n\n"
+ "Callers translate nil into their own `:unknown-…` error, which is what a missing\n"
+ "id already produces — so \"exists but you may not read it\" and \"does not exist\"\n"
+ "are indistinguishable to the caller. Letting the 403 escape made the status code\n"
+ "an existence oracle for sequential, easily-guessed content ids. The store is the\n"
+ "single chokepoint every content lookup passes through, so the collapse lives here.")
(let [row {:opaque :marker}
store (record-store {:card row})
gated (shared.content-store/read-checked store)]
(mt/with-dynamic-fn-redefs [api/read-check (fn [_]
(throw (ex-info "Forbidden" {:status-code 403})))]
(binding [api/*current-user-id* 1]
- (try
- (resolve.mp/card-by-entity-id gated "x")
- (is false "expected throw")
- (catch clojure.lang.ExceptionInfo e
- (is (= 403 (:status-code (ex-data e))))))))))
- (testing "if can-read? is false, the by-id (export-direction) branch throws a 403 via check-403"
- (let [row (stub-row {:opaque :marker})
- store (record-store {:card-id row :measure-id row :segment-id row})
- gated (shared.content-store/read-checked store)]
- (mt/with-dynamic-fn-redefs [api/read-check (fn [& _]
- (is false "api/read-check ran on a -by-id lookup"))]
- (binding [api/*current-user-id* 1
- *stub-can-read?* false]
- (doseq [lookup [resolve.mp/card-by-id resolve.mp/measure-by-id resolve.mp/segment-by-id]]
+ (testing "numeric-id lookups collapse the denial to nil"
+ (doseq [lookup [resolve.mp/card-by-id resolve.mp/measure-by-id]]
+ (is (nil? (lookup gated 1)))))
+ (testing "entity_id lookups keep the 403 — a NanoID is not guessable, so there is no
+ oracle to close, and callers depend on the accurate status"
(try
- (lookup gated 1)
- (is false "expected throw")
+ (resolve.mp/card-by-entity-id gated "x")
+ (is false "expected the 403 to propagate for an entity_id lookup")
(catch clojure.lang.ExceptionInfo e
(is (= 403 (:status-code (ex-data e))))))))))))
+(deftest non-403-exceptions-still-propagate-test
+ (testing (str "only the 403 is collapsed. A read-check failing for any other reason is a real\n"
+ "error, not a permission answer, and must not be reported as \"not found\".")
+ (let [row {:opaque :marker}
+ store (record-store {:card row :card-id row})
+ ;; the audited store, so `api/read-check` is the call that runs on a `-by-id` lookup
+ gated (shared.content-store/read-checked store true)]
+ (mt/with-dynamic-fn-redefs [api/read-check (fn [_]
+ (throw (ex-info "Boom" {:status-code 500})))]
+ (binding [api/*current-user-id* 1]
+ (try
+ (resolve.mp/card-by-id gated 1)
+ (is false "expected the 500 to propagate")
+ (catch clojure.lang.ExceptionInfo e
+ (is (= 500 (:status-code (ex-data e)))))))))))
+
;;; ============================================================
;;; Suppression at the repair call site
;;; ============================================================
@@ -341,10 +361,15 @@
(testing "a user who can read the source Card gets its entity_id"
(mt/with-current-user (mt/user->id :crowberto)
(is (= entity-id (export!)))))
- (testing "a user who cannot read the source Card's collection gets a 403, not the entity_id"
+ (testing "a user who cannot read the source Card's collection does NOT get its entity_id"
+ ;; The denial now surfaces as the resolver's own not-found error rather than a 403 —
+ ;; the store collapses the two so the status cannot be used to probe for hidden cards.
+ ;; What matters here is unchanged: the entity_id does not leak.
(mt/with-current-user (mt/user->id :rasta)
(try
- (export!)
- (is false "expected throw")
+ (let [result (export!)]
+ (is (not= entity-id result)
+ "an unreadable card's entity_id must never be exported"))
(catch clojure.lang.ExceptionInfo e
- (is (= 403 (:status-code (ex-data e))))))))))))
+ (is (= 400 (:status-code (ex-data e))))
+ (is (= :unknown-card-id (:error (ex-data e))))))))))))
diff --git a/test/metabase/metabot/tools/slackbot_query_test.clj b/test/metabase/metabot/tools/slackbot_query_test.clj
index 4799e83cd50..3fc5bf0c9b4 100644
--- a/test/metabase/metabot/tools/slackbot_query_test.clj
+++ b/test/metabase/metabot/tools/slackbot_query_test.clj
@@ -19,6 +19,7 @@
[malli.json-schema :as mjs]
[metabase.metabot.agent.streaming :as streaming]
[metabase.metabot.tools.construct :as construct]
+ [metabase.metabot.tools.recovery-hints :as recovery-hints]
[metabase.metabot.tools.slackbot-query :as slackbot-query]
[metabase.test :as mt]
[metabase.test.data.users :as test.users]
@@ -97,10 +98,12 @@
"execute-representations-query, wraps the result in an adhoc_viz data part\n"
"with the provided title + display, and returns structured-output + instructions.")
(let [captured-query (atom nil)
+ captured-opts (atom :not-called)
fake-query {:lib/type :mbql/query :database 1 :stages [{:source-table 10}]}]
(with-repr-stub!
- (fn [external-query]
+ (fn [external-query & [opts]]
(reset! captured-query external-query)
+ (reset! captured-opts opts)
{:structured-output {:query-id "q-1"
:query fake-query
:result-columns []}
@@ -117,6 +120,10 @@
:display "bar"})]
(testing "external-query passed through verbatim"
(is (= query-input @captured-query)))
+ (testing "the v1 recovery-hint fn is threaded into the pipeline as `:recovery-hint`"
+ ;; Guards F1's regression class: without this, dropping the `:recovery-hint` arg from
+ ;; the caller would leave every stubbed test green while agent errors lose their hint.
+ (is (= recovery-hints/recovery-hint (:recovery-hint @captured-opts))))
(testing "structured-output is returned upstream"
(is (= "q-1" (get-in result [:structured-output :query-id])))
(is (= fake-query (get-in result [:structured-output :query]))))
@@ -137,7 +144,7 @@
"include them with nil values) but the link is still built and returned.")
(let [fake-query {:lib/type :mbql/query :database 1 :stages [{:source-table 10}]}]
(with-repr-stub!
- (fn [_external-query]
+ (fn [_external-query & _]
{:structured-output {:query-id "q-x"
:query fake-query
:result-columns []}
@@ -162,7 +169,7 @@
"returns `{:output <message>}` so the message reaches the LLM verbatim -\n"
"no stack trace, no data-parts.")
(with-repr-stub!
- (fn [_external-query]
+ (fn [_external-query & _]
(throw (ex-info "Unknown database: `Sample`. Use the exact database name as reported by search / read_resource."
{:agent-error? true
:status-code 400
@@ -184,7 +191,7 @@
"`Failed to construct notebook query: ...` prefix. Protects the LLM from\n"
"leaking internal stack-trace-style messages.")
(with-repr-stub!
- (fn [_external-query]
+ (fn [_external-query & _]
(throw (RuntimeException. "something went sideways")))
(fn []
(let [result (slackbot-query/slackbot-construct-notebook-query-tool
diff --git a/test/metabase/metabot/tools_test.clj b/test/metabase/metabot/tools_test.clj
index d950ac12aac..4394256d2c6 100644
--- a/test/metabase/metabot/tools_test.clj
+++ b/test/metabase/metabot/tools_test.clj
@@ -144,7 +144,7 @@
(let [query-captured (atom nil)
chart-called (atom nil)]
(mt/with-dynamic-fn-redefs [construct/execute-representations-query
- (fn [external-query]
+ (fn [external-query & _opts]
(reset! query-captured external-query)
{:structured-output {:query-id "q-1"
:query {:database 1}
@@ -182,7 +182,7 @@
"Run `construct_notebook_query` with `execute-representations-query` throwing `e`, and return
the `:output` the LLM would see."
[e]
- (mt/with-dynamic-fn-redefs [construct/execute-representations-query (fn [_] (throw e))]
+ (mt/with-dynamic-fn-redefs [construct/execute-representations-query (fn [_ _] (throw e))]
(:output (binding [shared/*profile-id* :nlq]
(agent-tools/construct-notebook-query-tool
{:query {:lib/type "mbql/query" :stages []}
diff --git a/test/metabase/models/serialization/resolve/mp_test.clj b/test/metabase/models/serialization/resolve/mp_test.clj
index df3b227a3b8..58cd2af5d8a 100644
--- a/test/metabase/models/serialization/resolve/mp_test.clj
+++ b/test/metabase/models/serialization/resolve/mp_test.clj
@@ -784,3 +784,80 @@
(is (true? (:agent-error? d)))
(is (= :cross-database-card (:error d)))
(is (= 999 (:card-database-id d)))))))))
+
+;;; ============================================================
+;;; Numeric `source-card` — the read-check chokepoint (GHY-4410)
+;;; ============================================================
+
+(deftest ^:parallel import-fk-card-by-numeric-id-happy-path-test
+ (testing "on a numeric-id surface, a bare card id resolves to itself through the content store"
+ (binding [resolve/*numeric-ids-allowed?* true]
+ (let [store (map-content-store {"someEntityId12345678x" {:id 4242 :database_id 1}})
+ ir (resolve.mp/import-resolver mp-simple store)]
+ (is (= 4242 (resolve/import-fk ir 4242 'Card)))))))
+
+(deftest ^:parallel import-fk-card-by-numeric-id-consults-the-store-test
+ (testing (str "GHY-4410: the numeric branch must go THROUGH the content store, because the\n"
+ "agent-facing store is `read-checked` — that lookup is the permission check. A\n"
+ "store that returns nil (what `read-checked` yields for a card the caller cannot\n"
+ "read) must surface :unknown-card-id, never fall through to the card.")
+ (binding [resolve/*numeric-ids-allowed?* true]
+ (let [;; empty store == the read-checked store's answer for a forbidden card
+ ir (resolve.mp/import-resolver mp-simple (map-content-store {}))]
+ (try
+ (resolve/import-fk ir 4242 'Card)
+ (is false "expected throw — a numeric id that the store denies must not resolve")
+ (catch clojure.lang.ExceptionInfo e
+ (let [d (ex-data e)]
+ (is (true? (:agent-error? d)))
+ (is (= :unknown-card-id (:error d)))
+ (is (= 4242 (:card-id d))))))))))
+
+(deftest ^:parallel import-fk-card-by-numeric-id-cross-database-test
+ (testing "the numeric branch carries the same cross-database guard as the portable one"
+ (binding [resolve/*numeric-ids-allowed?* true]
+ (let [store (map-content-store {"someEntityId12345678y" {:id 99 :database_id 999}})
+ ir (resolve.mp/import-resolver mp-simple store)]
+ (try
+ (resolve/import-fk ir 99 'Card)
+ (is false "expected throw")
+ (catch clojure.lang.ExceptionInfo e
+ (let [d (ex-data e)]
+ (is (true? (:agent-error? d)))
+ (is (= :cross-database-card (:error d)))
+ (is (= 999 (:card-database-id d))))))))))
+
+(deftest ^:parallel import-fk-numeric-consults-store-for-every-content-model-test
+ (testing (str "GHY-4410 follow-up: the numeric branch must cover EVERY content model, not just\n"
+ "Card. A numeric metric / segment / measure ref reaches the resolver by the same\n"
+ "route a numeric `source-card` does, and the store lookup is the permission check —\n"
+ "so a model that skipped it would let an unreadable one through unchecked.\n"
+ "An empty store stands in for what `read-checked` returns when the caller may not\n"
+ "read the row.")
+ (binding [resolve/*numeric-ids-allowed?* true]
+ (let [ir (resolve.mp/import-resolver mp-simple (map-content-store {}))]
+ (testing "Card (also the model metric refs resolve through)"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"No saved question or model found with id"
+ (resolve/import-fk ir 4242 'Card))))
+ (testing "Measure"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"No measure found with id"
+ (resolve/import-fk ir 4242 'Measure))))
+ (testing "Segment"
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"No segment found with id"
+ (resolve/import-fk ir 4242 'Segment))))))))
+
+(deftest ^:parallel import-mbql-routes-numeric-content-refs-through-the-store-test
+ (testing (str "the same, one level up: `import-mbql`'s clause branches matched `portable-id?`,\n"
+ "which is string-only, so a numeric metric / segment / measure ref fell through\n"
+ "every branch and was never resolved at all — never reaching the store, never\n"
+ "read-checked. They now share one `content-ref?` guard, so no branch can be\n"
+ "forgotten.")
+ (binding [resolve/*numeric-ids-allowed?* true]
+ (let [ir (resolve.mp/import-resolver mp-simple (map-content-store {}))]
+ (doseq [[label clause] {"metric" [:metric {} 4242]
+ "segment" [:segment {} 4242]
+ "measure" [:measure {} 4242]}]
+ (testing (str "a numeric " label " ref is resolved (and so permission-checked)")
+ (is (thrown? clojure.lang.ExceptionInfo
+ (resolve/import-mbql ir {:stages [{:aggregation [clause]}]}))
+ (str "a numeric " label " ref must not pass through unresolved"))))))))
diff --git a/test/metabase/oauth_server/api_test.clj b/test/metabase/oauth_server/api_test.clj
index 2efef55f795..207f43ce82f 100644
--- a/test/metabase/oauth_server/api_test.clj
+++ b/test/metabase/oauth_server/api_test.clj
@@ -2,6 +2,7 @@
(:require
[clojure.string :as str]
[clojure.test :refer [deftest is testing use-fixtures]]
+ [metabase.mcp.core :as mcp]
[metabase.oauth-server.api.oauth :as api.oauth]
[metabase.oauth-server.core :as oauth-server]
[metabase.test :as mt]
@@ -36,7 +37,8 @@
(is (nil? (:id_token_signing_alg_values_supported response)))))))
(deftest protected-resource-metadata-test
- (testing "the canonical and legacy MCP paths each advertise themselves as the OAuth protected resource (RFC 9728)"
+ (testing "each MCP path advertises *itself* as the OAuth protected resource (RFC 9728), so a strict
+ client connecting via an alias sees a resource value matching the URL it hit"
(mt/with-temporary-setting-values [site-url "http://localhost:3000"]
(doseq [path ["/api/metabase-mcp" "/api/mcp"]]
(testing path
@@ -48,6 +50,22 @@
:scopes_supported sequential?}
response))))))))
+(deftest protected-resource-metadata-advertises-its-own-scopes-test
+ (testing "every protected-resource endpoint, including the bare one, advertises the scope set belonging
+ to the `:resource` it names. A client reads `scopes_supported` here and requests exactly those;
+ advertising another path's set hands it a token that authorizes nothing on the resource it asked
+ about, with an empty `tools/list` and no in-product way to widen the grant afterwards. Asserted
+ against the `:resource` in the response rather than the URL requested, so the two cannot drift."
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (doseq [url [".well-known/oauth-protected-resource"
+ ".well-known/oauth-protected-resource/api/metabase-mcp"
+ ".well-known/oauth-protected-resource/api/mcp"]]
+ (testing url
+ (let [response (mt/user-http-request :crowberto :get 200 url)
+ resource-path (str/replace (:resource response) "http://localhost:3000" "")]
+ (is (= (set (oauth-server/mcp-resource-scopes resource-path))
+ (set (:scopes_supported response))))))))))
+
(deftest protected-resource-metadata-bare-path-test
(testing "GET /.well-known/oauth-protected-resource (no resource suffix) serves JSON advertising the canonical resource (BOT-1617)"
(mt/with-temporary-setting-values [site-url "http://localhost:3000"]
@@ -56,7 +74,14 @@
(is (=? {:resource "http://localhost:3000/api/metabase-mcp"
:authorization_servers ["http://localhost:3000"]
:bearer_methods_supported ["header"]}
- response))))))
+ response))
+ (testing "the bare path is the one clients probe, so its scope set must be the one the resource it
+ names actually accepts -- the canonical path reaches the v2 surface, so it advertises
+ the scopes v2's tools gate on and none of the retired per-entity agent-API scopes"
+ (is (= (set (oauth-server/mcp-resource-scopes (mcp/mcp-canonical-path)))
+ (set (:scopes_supported response))))
+ (is (contains? (set (:scopes_supported response)) "agent:content:read"))
+ (is (not (contains? (set (:scopes_supported response)) "agent:question:create"))))))))
(deftest discovery-endpoint-rebuilds-on-site-url-change-test
(testing "Discovery advertises endpoints for the *current* site-url, even after it changes (BOT-1617)"
@@ -1118,3 +1143,163 @@
"Raw script tags must not appear in the consent page")
(is (str/includes? body "&lt;script&gt;")
"Script tags should be HTML-escaped"))))))
+
+;;; ----------------------------------- RFC 8707 resource narrowing -----------------------------------
+
+(defn- extract-hidden-field
+ "Extract an arbitrary hidden form field's value from the consent page HTML."
+ [field-name body]
+ (second (re-find (re-pattern (str "name=\"" field-name "\"[^>]*value=\"([^\"]*)\"")) body)))
+
+(deftest authorize-narrows-scope-to-mcp-resource-test
+ (testing "an RFC 8707 `resource` indicator naming the MCP surface narrows the grant to the
+ scopes that surface accepts, so the consent screen asks for what the token can actually
+ be used for rather than everything the client registered"
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (t2/with-transaction [_conn nil {:rollback-only true}]
+ (let [wide "agent:content:read agent:question:create agent:sql:execute"
+ ;; the v2 path: the aliases still reach v1, whose tools gate on the agent-API scopes
+ mcp-uri (str "http://localhost:3000" (mcp/mcp-canonical-path))
+ client-id (:client_id (create-test-client!
+ {:scopes ["agent:content:read" "agent:question:create"
+ "agent:sql:execute"]}))
+ consent-resp (mt/user-http-request-full-response
+ :crowberto :get 200 "oauth/authorize"
+ :client_id client-id
+ :redirect_uri "https://example.com/callback"
+ :response_type "code"
+ :scope wide
+ :resource mcp-uri
+ :state "test-state")
+ body (:body consent-resp)
+ shown-scope (extract-hidden-field "scope" body)]
+ (testing "the v2 scope survives and the agent-API-only scopes are gone"
+ (is (= "agent:content:read" shown-scope))
+ (is (not (str/includes? body "agent:question:create")))
+ (is (not (str/includes? body "agent:sql:execute"))))
+ (testing "approving the narrowed request still verifies — narrowing happens before the
+ params are signed, so the consent form round-trips intact"
+ (let [response (form-post-decision!
+ :crowberto
+ {:approved "true"
+ :csrf_token (extract-csrf-token-from-consent body)
+ :params_sig (extract-params-sig-from-consent body)
+ :client_id client-id
+ :redirect_uri "https://example.com/callback"
+ :response_type "code"
+ :scope shown-scope
+ :resource mcp-uri
+ :state "test-state"}
+ 302
+ :csrf-cookie (extract-csrf-cookie consent-resp))]
+ (is (str/includes? (get-in response [:headers "Location"]) "code="))))
+ (testing "a client cannot re-widen the scope on the way back: the signature covers the
+ narrowed params, so posting the original wide scope is rejected as tampering"
+ (let [response (form-post-decision!
+ :crowberto
+ {:approved "true"
+ :csrf_token (extract-csrf-token-from-consent body)
+ :params_sig (extract-params-sig-from-consent body)
+ :client_id client-id
+ :redirect_uri "https://example.com/callback"
+ :response_type "code"
+ :scope wide
+ :resource mcp-uri
+ :state "test-state"}
+ 403
+ :csrf-cookie (extract-csrf-cookie consent-resp))]
+ (is (= "params_tampered" (get-in response [:body :error]))))))))))
+
+(deftest authorize-legacy-mcp-client-can-request-v2-scopes-test
+ (testing (str "GHY-4343: a client that registered against a shipped v0.60-v0.63 release snapshotted only the "
+ "pre-v2 per-entity agent scopes, and `validate-scope` rejects any requested scope absent from that "
+ "snapshot. Because `/oauth/authorize` validates before narrowing, a user forced to re-authorize was "
+ "answered a 400 `invalid_request` JSON body rendered raw in their browser tab - the manual recovery "
+ "path was broken too. `WidenDynamicOAuthClientScopesForMcpV2` unions the six v2 scopes into every "
+ "dynamically registered client's snapshot so the request validates and reaches consent.")
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (t2/with-transaction [_conn nil {:rollback-only true}]
+ (let [legacy-scopes ["agent:question:create" "agent:sql:construct" "agent:viz:mcp-ui:query"]
+ v2-scopes ["agent:content:read" "agent:content:write" "agent:query:run"
+ "agent:sql:run" "agent:delivery:write" "agent:resource:read"]
+ requested (str/join " " v2-scopes)
+ client (create-test-client! {:scopes legacy-scopes
+ :registration_type "dynamic"})
+ client-id (:client_id client)
+ authorize! (fn [expected-status]
+ (mt/user-http-request-full-response
+ :crowberto :get expected-status "oauth/authorize"
+ :client_id client-id
+ :redirect_uri "https://example.com/callback"
+ :response_type "code"
+ :scope requested
+ :state "test-state"))]
+ (testing "before widening, the six v2 scopes are refused against the legacy snapshot"
+ (is (= "invalid_request" (:error (:body (authorize! 400))))))
+ ;; Apply what the migration applies. The change class itself is exercised against the changelog in
+ ;; `metabase.app-db.custom-migrations-test`; what this test owns is the authorize consequence.
+ (t2/update! :model/OAuthClient {:client_id client-id}
+ {:scopes (into legacy-scopes v2-scopes)})
+ (testing "after widening, the same request reaches the consent page instead of a raw 400"
+ (let [response (authorize! 200)
+ body (:body response)]
+ (is (str/includes? (get-in response [:headers "Content-Type"]) "text/html")
+ "the user sees a consent page, not a JSON error body rendered in their browser tab")
+ (is (str/includes? body "agent:content:read")
+ "and the six v2 scopes are what they are consenting to"))))))))
+
+(deftest authorize-rejects-fully-narrowed-scope-test
+ (testing "when every requested scope is one the named resource does not accept, answer RFC 6749
+ `invalid_scope` rather than dropping the parameter. Dropping it renders a consent screen
+ listing no permissions and mints a zero-scope token: a handshake that looks successful and
+ yields an empty `tools/list`, with nothing telling the operator the resource rejected what
+ was asked for and no in-product way to widen the grant afterwards."
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (t2/with-transaction [_conn nil {:rollback-only true}]
+ (let [client-id (:client_id (create-test-client!
+ {:scopes ["agent:question:create" "agent:sql:execute"]}))
+ response (mt/user-http-request-full-response
+ :crowberto :get 400 "oauth/authorize"
+ :client_id client-id
+ ;; both are v1-only: the v2 resource accepts neither
+ :scope "agent:question:create agent:sql:execute"
+ :redirect_uri "https://example.com/callback"
+ :response_type "code"
+ :resource (str "http://localhost:3000" (mcp/mcp-canonical-path))
+ :state "test-state")]
+ (is (= "invalid_scope" (get-in response [:body :error]))))))))
+
+(deftest authorize-without-scope-still-renders-consent-test
+ (testing "a client that sends no `scope` at all is not the same case as one whose scopes were all
+ narrowed away -- narrowing answers nil for both, and only the first may drop the parameter.
+ This pins that the `invalid_scope` branch above did not swallow the no-scope request."
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (t2/with-transaction [_conn nil {:rollback-only true}]
+ (let [client-id (:client_id (create-test-client! {:scopes ["agent:content:read"]}))]
+ (is (mt/user-http-request :crowberto :get 200 "oauth/authorize"
+ :client_id client-id
+ :redirect_uri "https://example.com/callback"
+ :response_type "code"
+ :resource (str "http://localhost:3000" (mcp/mcp-canonical-path))
+ :state "test-state")))))))
+
+(deftest mb-full-client-can-still-authorize-test
+ (testing "removing `mb:full` from the advertised sets must not break a first-party client that
+ registered with it explicitly. That works only because oidc-provider validates a
+ requested scope against the client's own registered `:scopes`, never against the
+ provider's `:scopes-supported` -- which feeds the discovery document alone. Pinning the
+ dependency here: if that ever changes, un-advertising a scope silently starts rejecting
+ the clients that legitimately hold it."
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (t2/with-transaction [_conn nil {:rollback-only true}]
+ (let [client-id (:client_id (create-test-client! {:scopes [oauth-server/full-access-scope]}))]
+ (testing "the scope is advertised nowhere"
+ (is (not (contains? (set (oauth-server/supported-scopes)) oauth-server/full-access-scope)))
+ (is (not (contains? (set (oauth-server/default-grant-scopes)) oauth-server/full-access-scope))))
+ (testing "yet the consent screen still renders for a client registered with it"
+ (is (mt/user-http-request :crowberto :get 200 "oauth/authorize"
+ :client_id client-id
+ :redirect_uri "https://example.com/callback"
+ :response_type "code"
+ :scope oauth-server/full-access-scope
+ :state "test-state"))))))))
diff --git a/test/metabase/oauth_server/core_test.clj b/test/metabase/oauth_server/core_test.clj
index 03ec9ebf041..cc545974e25 100644
--- a/test/metabase/oauth_server/core_test.clj
+++ b/test/metabase/oauth_server/core_test.clj
@@ -1,20 +1,124 @@
(ns metabase.oauth-server.core-test
(:require
+ [clojure.string :as str]
[clojure.test :refer [deftest is testing use-fixtures]]
- ;; Loaded for its load-time side effects: it registers the agent API endpoints, from which
- ;; `get-provider` derives the provider's supported scopes (see [[metabase.mcp.core/all-scopes]]).
+ ;; load-bearing: the advertised scope sets are derived from the agent-api routes and the v2 tool
+ ;; registry, so both must be loaded for these assertions to see the real surface
[metabase.agent-api.api]
+ [metabase.mcp.core :as mcp]
+ [metabase.mcp.v2.api :as v2.api]
[metabase.oauth-server.core :as oauth-server]
[metabase.oauth-server.test-util :as oauth-server.tu]
[metabase.test :as mt]
[oidc-provider.store :as oidc.store]
[toucan2.core :as t2]))
+(comment metabase.agent-api.api/keep-me)
+
(use-fixtures :each (fn [thunk]
(oauth-server/reset-provider!)
(thunk)
(oauth-server/reset-provider!)))
+(deftest mb-full-is-advertised-nowhere-test
+ (testing "GHY-4226: `mb:full` grants full user-equivalent REST access, and advertising it put that
+ in front of every client reading discovery metadata. It is now absent from all three
+ advertised sets and from the default DCR grant, so no client is led toward it and none
+ can request it without having registered for it explicitly."
+ (is (not (contains? (set (oauth-server/supported-scopes)) "mb:full")))
+ (is (not (contains? (set (oauth-server/mcp-resource-scopes (mcp/mcp-canonical-path))) "mb:full")))
+ (is (not (contains? (set (oauth-server/mcp-resource-scopes (mcp/mcp-canonical-path))) "mb:full")))
+ (is (not (contains? (set (oauth-server/default-grant-scopes)) "mb:full")))))
+
+(deftest default-grant-covers-everything-advertised-test
+ (testing "GHY-4226: the DCR default is a ceiling, and clients derive what to request from
+ discovery metadata rather than from what they registered with. A scope we advertise but
+ do not register for is therefore not a narrower grant — it is an `invalid_scope`
+ rejection at /authorize for any client that asks for everything advertised, which is
+ what Claude and ChatGPT both do.
+
+ Iterated over every endpoint path rather than over the sets `default-grant-scopes` is
+ built from: asserting a set covers the sets it is defined as the union of cannot fail.
+ The per-path arities are the ones a client actually meets, and the v1 aliases are inside
+ the ceiling only incidentally today, because `all-scopes` also feeds `supported-scopes`."
+ (let [ceiling (set (oauth-server/default-grant-scopes))]
+ (doseq [path (mcp/mcp-endpoint-paths)]
+ (testing path
+ (is (empty? (remove ceiling (oauth-server/mcp-resource-scopes path))))))
+ (testing "and the authorization-server metadata set"
+ (is (empty? (remove ceiling (oauth-server/supported-scopes))))))))
+
+(deftest v2-default-ask-covers-the-surface-and-is-requestable-test
+ (testing "the v2 401 challenge asks an uninstructed client for every scope the surface accepts, and
+ nothing else. Asking for less does not degrade gracefully: `list-tools` filters by token
+ scopes, so an unasked-for write scope removes those tools from `tools/list` entirely, with
+ no in-product way for the user to request them afterwards."
+ (is (= (set (oauth-server/mcp-resource-scopes (mcp/mcp-canonical-path)))
+ (set @#'v2.api/default-ask-scopes))
+ "the ask and the accepted set are the same — a scope in one but not the other is a bug in whichever moved")
+ (testing "every asked scope is inside the ceiling, or the ask itself would be rejected"
+ (let [ceiling (set (oauth-server/default-grant-scopes))]
+ (doseq [scope @#'v2.api/default-ask-scopes]
+ (testing scope
+ (is (contains? ceiling scope))))))
+ (testing "GHY-4226: the wider agent-API scopes stay out — asking for the surface is not asking for the REST API"
+ (doseq [scope ["mb:full" "agent:question:create" "agent:timelines:write"]]
+ (testing scope
+ (is (not (contains? (set @#'v2.api/default-ask-scopes) scope))))))))
+
+(deftest advertised-scopes-are-distinct-test
+ (testing "GHY-4151: `scopes_supported` is a set of scope strings (RFC 8414), so no scope may be
+ advertised twice.
+
+ Asserted on the sources rather than on the output. Every advertised set is built through
+ a `sorted-set`, which makes the output distinct by construction no matter what goes in --
+ so counting the result can never fail. What can go wrong is upstream: the same scope
+ declared in both `v2-surface-scopes` and a v1 resource scope list, which the sorted-set
+ silently swallows."
+ (doseq [path (mcp/mcp-endpoint-paths)]
+ (testing path
+ (let [scopes (oauth-server/mcp-resource-scopes path)]
+ (is (= (count (distinct scopes)) (count scopes))
+ (str "duplicate scopes: "
+ (->> scopes frequencies (filter (fn [[_ n]] (> n 1))) (map key) sort vec))))))
+ (testing "the v2 surface literal has no duplicates of its own"
+ (is (= (count (distinct (mcp/v2-scopes))) (count (mcp/v2-scopes)))))))
+
+(deftest rationalized-scopes-are-in-the-default-grant-test
+ (testing "GHY-4225: the five v2 scopes must all reach the default grant a dynamically-registered
+ client receives, or the tool surface advertises capabilities no such client can use.
+ (This replaces a check on `agent:document:create`, which duplicate_content required
+ until GHY-4225 collapsed the per-type create scopes into `agent:content:write`.)"
+ (let [granted (set (oauth-server/default-grant-scopes))]
+ (doseq [scope ["agent:content:read" "agent:content:write" "agent:query:run"
+ "agent:sql:run" "agent:delivery:write"]]
+ (testing scope
+ (is (contains? granted scope)))))))
+
+(deftest mcp-resource-advertises-only-the-mcp-surface-test
+ (testing "RFC 9728 metadata answers \"what does *this* resource accept\". Every MCP endpoint path now
+ reaches the same v2 surface, so each advertises the rationalized scopes its tool registry
+ gates on and none of the agent-API per-entity scopes. While v1 was still served the aliases
+ that reached it had to advertise the wider set; with v1 retired that would list per-entity
+ scopes on a consent screen for tools that no longer exist."
+ (doseq [path (mcp/mcp-endpoint-paths)]
+ (testing path
+ (let [mcp (set (oauth-server/mcp-resource-scopes path))]
+ (testing "the rationalized scopes are advertised"
+ (doseq [scope ["agent:content:read" "agent:content:write" "agent:query:run"
+ "agent:sql:run" "agent:delivery:write"]]
+ (testing scope
+ (is (contains? mcp scope)))))
+ (testing "agent-API per-entity scopes are not"
+ (doseq [scope ["agent:collection:create" "agent:dashboard:create" "agent:dashboard:update"
+ "agent:metric:create" "agent:metric:update" "agent:question:create"
+ "agent:query:construct" "agent:query:execute" "agent:sql:construct"]]
+ (testing scope
+ (is (not (contains? mcp scope)))))))))
+ (testing "every path answers the same set, since every path reaches the same surface"
+ (is (= 1 (count (set (map (comp set oauth-server/mcp-resource-scopes)
+ (mcp/mcp-endpoint-paths)))))))))
+
(deftest get-provider-test
(testing "get-provider returns a Provider instance"
(mt/with-temporary-setting-values [site-url "http://localhost:3000"]
@@ -48,3 +152,170 @@
(testing "returns nil once the client row is gone — token must not outlive its client"
(t2/delete! :model/OAuthClient :client_id client-id)
(is (nil? (oauth-server/resolve-access-token token))))))))))
+
+;;; ----------------------------------- RFC 8707 resource narrowing -----------------------------------
+
+(deftest narrow-scope-to-resource-test
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (let [mcp-uri "http://localhost:3000/api/metabase-mcp"
+ v1-uri "http://localhost:3000/api/mcp"
+ scopes #(set (some-> % (str/split #"\s+")))]
+ (testing "an alias narrows to the same surface — every MCP path reaches it now, so a
+ per-entity scope no tool gates on is dropped rather than carried into the grant"
+ (let [narrowed (scopes (oauth-server/narrow-scope-to-resource
+ [v1-uri]
+ "agent:content:read agent:question:create agent:sql:execute agent:query:run"))]
+ (is (not (contains? narrowed "agent:question:create")))
+ (is (not (contains? narrowed "agent:sql:execute")))
+ (is (contains? narrowed "agent:content:read"))
+ (is (contains? narrowed "agent:query:run"))))
+ (testing "an indicator naming the MCP resource drops scopes that surface does not accept"
+ (let [narrowed (scopes (oauth-server/narrow-scope-to-resource
+ [mcp-uri]
+ "agent:content:read agent:question:create agent:sql:execute agent:query:run"))]
+ (is (= #{"agent:content:read" "agent:query:run"} narrowed))))
+ (testing "every scope the surface advertises survives narrowing — otherwise the resource doc would
+ advertise a scope its own consent flow strips"
+ (let [advertised (oauth-server/mcp-resource-scopes "/api/metabase-mcp")]
+ (is (= (set advertised)
+ (scopes (oauth-server/narrow-scope-to-resource
+ [mcp-uri] (str/join " " advertised)))))))
+ (testing "GHY-4226: `mb:full` is dropped like any other scope the surface does not accept. A
+ client naming the MCP resource wants a token for that surface, which accepts none of
+ the REST API that scope unlocks."
+ (is (= #{"agent:content:read"}
+ (scopes (oauth-server/narrow-scope-to-resource
+ [mcp-uri] "mb:full agent:content:read agent:question:create"))))
+ (testing "and it is the only thing requested, nothing survives"
+ (is (nil? (oauth-server/narrow-scope-to-resource [mcp-uri] "mb:full")))))
+ (testing "GHY-4250: every alias narrows, not just the canonical path — a client that connected
+ through an alias was handed that path as its resource identifier, so recognizing
+ only the canonical one would silently hand it the wide consent screen. Each narrows to
+ what its OWN surface accepts: the v2 path to the v2 set, the aliases (still v1 until the
+ switchover) to v1's, which is why `mb:full` goes everywhere but `agent:question:create`
+ survives only where a v1 tool can still use it."
+ (doseq [path ["/api/metabase-mcp" "/api/mcp"]]
+ (testing path
+ (let [narrowed (oauth-server/narrow-scope-to-resource
+ [(str "http://localhost:3000" path)]
+ "mb:full agent:content:read agent:question:create")]
+ (is (not (str/includes? narrowed "mb:full")))
+ (is (str/includes? narrowed "agent:content:read"))
+ ;; Every path reaches v2, so none of them accept the agent-API per-entity scopes.
+ (is (not (str/includes? narrowed "agent:question:create")))))))
+ (testing "no indicator, or one naming a different resource, leaves the scope alone"
+ (let [wide "agent:content:read agent:question:create"]
+ (is (= wide (oauth-server/narrow-scope-to-resource nil wide)))
+ (is (= wide (oauth-server/narrow-scope-to-resource [] wide)))
+ (is (= wide (oauth-server/narrow-scope-to-resource
+ ["http://localhost:3000/api/agent"] wide)))))
+ (testing "nil rather than an empty scope when nothing survives, so the caller drops the
+ parameter instead of sending a blank one"
+ (is (nil? (oauth-server/narrow-scope-to-resource [mcp-uri] "agent:question:create"))))
+ (testing "blank and missing scopes stay absent rather than becoming an empty parameter"
+ (doseq [blank [nil "" " "]]
+ (testing (pr-str blank)
+ (is (nil? (oauth-server/narrow-scope-to-resource [mcp-uri] blank)))
+ (is (nil? (oauth-server/narrow-scope-to-resource nil blank))))))
+ (testing "narrowing only ever removes — a client cannot gain a scope it did not request"
+ (let [requested "agent:content:read agent:question:create mb:full"]
+ (is (every? (scopes requested)
+ (scopes (oauth-server/narrow-scope-to-resource [mcp-uri] requested)))))))))
+
+(deftest narrow-scope-to-resource-canonicalization-test
+ (testing "resource indicators are compared canonically, not byte-for-byte. Clients disagree on
+ trailing slashes, case, and default ports -- a live Claude Code bug appends a trailing
+ slash via WHATWG URL -- and a mismatch silently skips narrowing, handing the caller the
+ wide consent screen. RFC 3986 makes scheme and host case-insensitive and the default
+ port elidable; the path is neither."
+ (let [wide "agent:content:read agent:question:create"
+ narrowed "agent:content:read"]
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (doseq [indicator ["http://localhost:3000/api/metabase-mcp"
+ "http://localhost:3000/api/metabase-mcp/"
+ "HTTP://LOCALHOST:3000/api/metabase-mcp"
+ "http://LocalHost:3000/api/metabase-mcp/"]]
+ (testing (str "matches " (pr-str indicator))
+ (is (= narrowed (oauth-server/narrow-scope-to-resource [indicator] wide))))))
+ (testing "the default port is elidable in both directions"
+ (mt/with-temporary-setting-values [site-url "https://example.com"]
+ (doseq [indicator ["https://example.com/api/metabase-mcp"
+ "https://example.com:443/api/metabase-mcp"]]
+ (testing (str "matches " (pr-str indicator))
+ (is (= narrowed (oauth-server/narrow-scope-to-resource [indicator] wide))))))
+ (mt/with-temporary-setting-values [site-url "http://example.com"]
+ (is (= narrowed (oauth-server/narrow-scope-to-resource
+ ["http://example.com:80/api/metabase-mcp"] wide)))))
+ (testing "canonicalization does not make unrelated resources match"
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (doseq [indicator ["http://localhost:3000/api/metabase-mcp/extra"
+ "http://localhost:3000/API/METABASE-MCP/V2"
+ "http://localhost:3001/api/metabase-mcp"
+ "https://localhost:3000/api/metabase-mcp"
+ "http://evil.example.com/api/metabase-mcp"
+ "not-a-uri"]]
+ (testing (str "leaves scope alone for " (pr-str indicator))
+ (is (= wide (oauth-server/narrow-scope-to-resource [indicator] wide))))))))))
+
+(deftest narrow-scope-to-resource-multiple-indicators-test
+ (testing "RFC 8707 allows several `resource` indicators, and a token has to work against each, so the
+ accepted set is the UNION of what the named resources accept. Every MCP path now reaches the
+ same v2 surface, so the union is that one surface's set however many paths are named -- and a
+ per-entity scope no surface accepts is never re-admitted by naming more of them."
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (let [canonical "http://localhost:3000/api/metabase-mcp"
+ alias1 "http://localhost:3000/api/mcp"
+ wide "mb:full agent:content:read agent:question:create agent:sql:execute"
+ scopes #(set (some-> % (str/split #"\s+")))]
+ (testing "one indicator each: every path narrows to the v2 surface"
+ (doseq [indicator [canonical alias1]]
+ (testing indicator
+ (let [narrowed (scopes (oauth-server/narrow-scope-to-resource [indicator] wide))]
+ (is (contains? narrowed "agent:content:read"))
+ (is (not (contains? narrowed "agent:question:create")))
+ (is (not (contains? narrowed "agent:sql:execute")))))))
+ (testing "naming several paths together is the same union, in either order"
+ (doseq [indicators [[canonical alias1] [alias1 canonical]]]
+ (testing (pr-str indicators)
+ (let [narrowed (scopes (oauth-server/narrow-scope-to-resource indicators wide))]
+ (is (contains? narrowed "agent:content:read"))
+ (is (not (contains? narrowed "agent:question:create")))))))
+ (testing "the union never re-admits a scope no named surface accepts"
+ (doseq [indicators [[canonical] [alias1] [canonical alias1] [alias1 canonical]]]
+ (testing (pr-str indicators)
+ (is (not (contains? (scopes (oauth-server/narrow-scope-to-resource indicators wide))
+ "mb:full"))))))))))
+
+(deftest narrow-scope-to-resource-bare-string-test
+ (testing "a lone indicator may arrive as a bare string -- the endpoint schema allows one. `keep` over a
+ String iterates characters, none of which canonicalize, so an un-normalized argument would skip
+ narrowing entirely and hand back the wide scope. Narrowing must not depend on the caller having
+ vectorized."
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (let [uri "http://localhost:3000/api/metabase-mcp"
+ wide "mb:full agent:content:read agent:question:create"]
+ (is (= (oauth-server/narrow-scope-to-resource [uri] wide)
+ (oauth-server/narrow-scope-to-resource uri wide)))
+ (is (= "agent:content:read" (oauth-server/narrow-scope-to-resource uri wide)))))))
+
+(deftest narrow-scope-to-resource-underscore-host-test
+ (testing "`java.net.URI/getHost` is nil for a host it considers non-conformant -- notably one containing an
+ underscore, which is routine for Docker Compose and internal k8s service names, and which
+ Metabase's own `u/url?` accepts as a Site URL. Reading the host alone made canonicalization
+ return nil on such an instance, so no indicator ever matched and narrowing was disabled
+ instance-wide, silently."
+ (mt/with-temporary-setting-values [site-url "http://metabase_internal:3000"]
+ (let [v2 "http://metabase_internal:3000/api/metabase-mcp"
+ wide "mb:full agent:content:read agent:question:create"]
+ (is (= "agent:content:read" (oauth-server/narrow-scope-to-resource [v2] wide))
+ "narrowing still applies when the Site URL host contains an underscore")))
+ (testing "canonicalization keeps the properties it had for conformant hosts"
+ (mt/with-temporary-setting-values [site-url "http://localhost:3000"]
+ (let [wide "agent:content:read agent:question:create"
+ narrowed "agent:content:read"]
+ (testing "userinfo is still stripped rather than compared"
+ (is (= narrowed (oauth-server/narrow-scope-to-resource
+ ["http://user:pass@localhost:3000/api/metabase-mcp"] wide))))
+ (testing "host case is still folded and the default port still elided"
+ (is (= narrowed (oauth-server/narrow-scope-to-resource
+ ["HTTP://LocalHost:3000/api/metabase-mcp"] wide)))))))))
diff --git a/test/metabase/parameters/mapping_targets_test.clj b/test/metabase/parameters/mapping_targets_test.clj
new file mode 100644
index 00000000000..9dea468ce46
--- /dev/null
+++ b/test/metabase/parameters/mapping_targets_test.clj
@@ -0,0 +1,146 @@
+(ns metabase.parameters.mapping-targets-test
+ "Tests for enumerating the parameter mapping targets a card exposes — the backend counterpart of
+ the frontend's getParameterMappingOptions."
+ (:require
+ [clojure.test :refer :all]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.parameters.mapping-targets :as mapping-targets]
+ [metabase.parameters.params :as params]
+ [metabase.test :as mt]))
+
+(set! *warn-on-reflection* true)
+
+(defn- venues-query
+ "A Lib query selecting everything from `venues`."
+ []
+ (let [mp (mt/metadata-provider)]
+ (lib/query mp (lib.metadata/table mp (mt/id :venues)))))
+
+(deftest mbql-card-exposes-filterable-columns-test
+ (testing "GHY-4147: an MBQL card's targets are its filterable columns, as dimension clauses"
+ (mt/with-temp [:model/Card card {:dataset_query (venues-query)}]
+ (let [targets (mapping-targets/valid-targets card {:id "p1" :type "string/="})]
+ (is (seq targets))
+ (is (every? #(= :dimension (first (:target %))) targets))
+ (is (contains? (set (map :column-name targets)) "NAME"))))))
+
+(deftest dimension-targets-carry-a-stage-number-test
+ (testing "GHY-4147: dimension targets carry {:stage-number 0} — without it they resolve wrong on
+ multi-stage queries"
+ (mt/with-temp [:model/Card card {:dataset_query (venues-query)}]
+ (let [targets (mapping-targets/valid-targets card {:id "p1" :type "string/="})]
+ (is (every? #(= {:stage-number 0} (nth (:target %) 2 nil)) targets))))))
+
+(deftest target-for-field-test
+ (testing "GHY-4147: target-for-field finds the target resolving to a specific field"
+ (mt/with-temp [:model/Card card {:dataset_query (venues-query)}]
+ (let [target (mapping-targets/target-for-field card {:id "p1" :type "number/="} (mt/id :venues :price))]
+ (is (= :dimension (first target)))
+ (testing "and it round-trips through the codebase's own target resolver"
+ (is (= (mt/id :venues :price)
+ (params/param-target->field-id target card))))))))
+
+(deftest target-for-field-returns-nil-when-absent-test
+ (testing "GHY-4147: a field the card does not expose yields nil, so the caller can teach"
+ (mt/with-temp [:model/Card card {:dataset_query (venues-query)}]
+ (is (nil? (mapping-targets/target-for-field card
+ {:id "p1" :type "string/="}
+ (mt/id :users :name)))))))
+
+(deftest native-card-exposes-template-tags-test
+ (testing "GHY-4147: a native card's targets are its template tags, typed by tag kind"
+ (mt/with-temp [:model/Card card {:dataset_query
+ (mt/native-query
+ {:query "SELECT * FROM VENUES WHERE PRICE = {{price}}"
+ :template-tags {"price" {:id "t1" :name "price"
+ :display-name "Price"
+ :type :number}}})}]
+ (let [targets (mapping-targets/valid-targets card {:id "p1" :type "number/="})]
+ (is (= [[:variable [:template-tag "price"]]] (mapv :target targets)))))))
+
+(deftest native-dimension-tag-test
+ (testing "GHY-4147: a native dimension tag is a dimension target, not a variable"
+ (mt/with-temp [:model/Card card {:dataset_query
+ (mt/native-query
+ {:query "SELECT * FROM VENUES WHERE {{cat}}"
+ :template-tags {"cat" {:id "t2" :name "cat"
+ :display-name "Cat"
+ :type :dimension
+ :widget-type :string/=
+ :dimension [:field (mt/id :venues :name) nil]}}})}]
+ (let [targets (mapping-targets/valid-targets card {:id "p1" :type "string/="})]
+ (is (= [[:dimension [:template-tag "cat"]]] (mapv :target targets)))))))
+
+(deftest incompatible-parameter-type-yields-no-targets-test
+ (testing "GHY-4147: a date parameter finds no target on a card exposing only a number variable"
+ (mt/with-temp [:model/Card card {:dataset_query
+ (mt/native-query
+ {:query "SELECT * FROM VENUES WHERE PRICE = {{price}}"
+ :template-tags {"price" {:id "t1" :name "price"
+ :display-name "Price"
+ :type :number}}})}]
+ (is (empty? (mapping-targets/valid-targets card {:id "p1" :type "date/all-options"}))))))
+
+(deftest malformed-stored-query-yields-no-targets-test
+ (testing "a card whose stored query is malformed yields no targets rather than throwing — the
+ docstring's 'never throws' guarantee covers normalization, not just column enumeration"
+ (doseq [dataset-query ["SELECT * FROM VENUES WHERE PRICE = {{price}}"
+ [:native "SELECT 1"]]]
+ (let [card {:id 4321 :dataset_query dataset-query}]
+ (is (= [] (mapping-targets/valid-targets card {:id "p1" :type "string/="}))
+ (str "valid-targets on " (pr-str dataset-query)))
+ (is (nil? (mapping-targets/target-for-field card {:id "p1" :type "string/="} 1))
+ (str "target-for-field on " (pr-str dataset-query)))))))
+
+(def ^:private tagged-native-card
+ {:id 9
+ :dataset_query
+ {:database 1
+ :type :native
+ :native {:query "SELECT 1 WHERE {{cat}} AND total > {{min}} /* {{unit}} {{snippet: base}} */"
+ :template-tags
+ {"cat" {:id "u1" :name "cat" :display-name "Category" :type :dimension
+ :dimension [:field 18 nil] :widget-type :string/=}
+ "min" {:id "u2" :name "min" :display-name "Min" :type :number}
+ "unit" {:id "u3" :name "unit" :display-name "Unit" :type :temporal-unit
+ :dimension [:field 22 nil]}
+ "snippet: base" {:id "u4" :name "snippet: base" :display-name "base" :type :snippet
+ :snippet-name "base"}}}}})
+
+(deftest template-tag-types-test
+ (testing "the stored tags map to their type keywords, one malformed snippet tag notwithstanding"
+ (is (= {"cat" :dimension "min" :number "unit" :temporal-unit "snippet: base" :snippet}
+ (mapping-targets/template-tag-types tagged-native-card))))
+ (testing "a card with no native query has no tags"
+ (is (= {} (mapping-targets/template-tag-types {:dataset_query {:database 1 :type :query :query {}}})))
+ (is (= {} (mapping-targets/template-tag-types {})))))
+
+(deftest target-for-tag-test
+ (testing "field-filter and temporal-unit tags take a :dimension target, raw variables a :variable one"
+ (is (= [:dimension [:template-tag "cat"]] (mapping-targets/target-for-tag "cat" :dimension)))
+ (is (= [:dimension [:template-tag "unit"]] (mapping-targets/target-for-tag "unit" :temporal-unit)))
+ (is (= [:variable [:template-tag "min"]] (mapping-targets/target-for-tag "min" :number)))
+ (is (= [:variable [:template-tag "flag"]] (mapping-targets/target-for-tag "flag" :boolean))))
+ (testing "reference tags cannot back a parameter"
+ (is (nil? (mapping-targets/target-for-tag "snippet: base" :snippet)))
+ (is (nil? (mapping-targets/target-for-tag "#42" :card)))))
+
+(deftest wireable-target-template-tags-test
+ (let [parameter {:id "p1" :type "string/="}]
+ (testing "a template-tag target is wireable when the tag exists and the clause head matches its kind"
+ (is (true? (mapping-targets/wireable-target? tagged-native-card parameter [:dimension [:template-tag "cat"]])))
+ (is (true? (mapping-targets/wireable-target? tagged-native-card parameter [:variable [:template-tag "min"]]))))
+ (testing "a kind mismatch, a missing tag, and a reference tag are all unwireable"
+ (is (false? (mapping-targets/wireable-target? tagged-native-card parameter [:variable [:template-tag "cat"]])))
+ (is (false? (mapping-targets/wireable-target? tagged-native-card parameter [:dimension [:template-tag "min"]])))
+ (is (false? (mapping-targets/wireable-target? tagged-native-card parameter [:dimension [:template-tag "ghost"]])))
+ (is (false? (mapping-targets/wireable-target? tagged-native-card parameter [:variable [:template-tag "snippet: base"]]))))))
+
+(deftest wireable-target-dimension-refs-test
+ (testing "a field-ref dimension target is wireable exactly when the card exposes that field"
+ (mt/with-temp [:model/Card card {:dataset_query (venues-query)}]
+ (let [parameter {:id "p1" :type "string/="}
+ name-field-id (mt/id :venues :name)]
+ (is (true? (mapping-targets/wireable-target? card parameter [:dimension [:field name-field-id nil]])))
+ (is (false? (mapping-targets/wireable-target? card parameter [:dimension [:field Integer/MAX_VALUE nil]])))))))
diff --git a/test/metabase/pulse/broken_subscriptions_test.clj b/test/metabase/pulse/broken_subscriptions_test.clj
new file mode 100644
index 00000000000..6c187cc6d37
--- /dev/null
+++ b/test/metabase/pulse/broken_subscriptions_test.clj
@@ -0,0 +1,124 @@
+(ns metabase.pulse.broken-subscriptions-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.pulse.broken-subscriptions :as pulse.broken-subscriptions]
+ [metabase.pulse.models.pulse :as models.pulse]
+ [metabase.test :as mt]))
+
+(deftest broken-subscription-data-logic-test
+ (testing "Ensure underlying logic of fixing broken pulses works (#30100)"
+ (let [{param-id :id :as param} {:name "Source"
+ :slug "source"
+ :id "_SOURCE_PARAM_ID_"
+ :type :string/=}]
+ (mt/dataset test-data
+ (mt/with-temp
+ [:model/Card {card-id :id} {:name "Native card"
+ :database_id (mt/id)
+ :dataset_query {:database (mt/id)
+ :type :query
+ :query {:source-table (mt/id :people)}}
+ :type :model}
+ :model/Dashboard {dash-id :id} {:name "My Awesome Dashboard"}
+ :model/DashboardCard {dash-card-id :id} {:dashboard_id dash-id
+ :card_id card-id}
+ ;; Broken pulse
+ :model/Pulse {bad-pulse-id :id
+ :as bad-pulse} {:name "Bad Pulse"
+ :dashboard_id dash-id
+ :creator_id (mt/user->id :trashbird)
+ :parameters [(assoc param :value ["Twitter", "Facebook"])]}
+ :model/PulseCard _ {:pulse_id bad-pulse-id
+ :card_id card-id
+ :dashboard_card_id dash-card-id}
+ :model/PulseChannel {pulse-channel-id :id} {:channel_type :email
+ :pulse_id bad-pulse-id
+ :enabled true}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pulse-channel-id
+ :user_id (mt/user->id :rasta)}
+ :model/PulseChannelRecipient _ {:pulse_channel_id pulse-channel-id
+ :user_id (mt/user->id :crowberto)}
+ ;; Broken slack pulse
+ :model/Pulse {bad-slack-pulse-id :id} {:name "Bad Slack Pulse"
+ :dashboard_id dash-id
+ :creator_id (mt/user->id :trashbird)
+ :parameters [(assoc param :value ["LinkedIn"])]}
+ :model/PulseCard _ {:pulse_id bad-slack-pulse-id
+ :card_id card-id
+ :dashboard_card_id dash-card-id}
+ :model/PulseChannel _ {:channel_type :slack
+ :pulse_id bad-slack-pulse-id
+ :details {:channel "#my-channel"}
+ :enabled true}
+ ;; Non broken pulse
+ :model/Pulse {good-pulse-id :id} {:name "Good Pulse"
+ :dashboard_id dash-id
+ :creator_id (mt/user->id :trashbird)}
+ :model/PulseCard _ {:pulse_id good-pulse-id
+ :card_id card-id
+ :dashboard_card_id dash-card-id}
+ :model/PulseChannel {good-pulse-channel-id :id} {:channel_type :email
+ :pulse_id good-pulse-id
+ :enabled true}
+ :model/PulseChannelRecipient _ {:pulse_channel_id good-pulse-channel-id
+ :user_id (mt/user->id :rasta)}
+ :model/PulseChannelRecipient _ {:pulse_channel_id good-pulse-channel-id
+ :user_id (mt/user->id :crowberto)}]
+ (testing "We can identify the broken parameter ids"
+ (is (=? [{:archived false
+ :name "Bad Pulse"
+ :creator_id (mt/user->id :trashbird)
+ :id bad-pulse-id
+ :parameters
+ [{:name "Source" :slug "source" :id "_SOURCE_PARAM_ID_" :type "string/=" :value ["Twitter" "Facebook"]}]
+ :dashboard_id dash-id}
+ {:archived false
+ :name "Bad Slack Pulse"
+ :creator_id (mt/user->id :trashbird)
+ :id bad-slack-pulse-id
+ :parameters [{:name "Source"
+ :slug "source"
+ :id "_SOURCE_PARAM_ID_"
+ :type "string/="
+ :value ["LinkedIn"]}],
+ :dashboard_id dash-id}]
+ ;; `broken-pulses` doesn't order its results, so sort them for a stable comparison
+ (sort-by :id (#'pulse.broken-subscriptions/broken-pulses dash-id {param-id param})))))
+ (testing "We can gather all needed data regarding broken params"
+ (let [bad-pulses (mapv
+ #(update % :affected-users (partial sort-by :email))
+ (sort-by :pulse-id (#'pulse.broken-subscriptions/broken-subscription-data dash-id {param-id param})))
+ bad-pulse-ids (set (map :pulse-id bad-pulses))]
+ (testing "We only detect the bad pulse and not the good one"
+ (is (true? (contains? bad-pulse-ids bad-pulse-id)))
+ (is (false? (contains? bad-pulse-ids good-pulse-id))))
+ (is (=? [{:pulse-creator {:email "[email protected]"}
+ :dashboard-creator {:email "[email protected]"}
+ :pulse-id bad-pulse-id
+ :pulse-name "Bad Pulse"
+ :dashboard-id dash-id
+ :bad-parameters [{:name "Source" :value ["Twitter" "Facebook"]}]
+ :dashboard-name "My Awesome Dashboard"
+ :affected-users [{:notification-type :email
+ :recipient "Crowberto Corv"}
+ {:notification-type :email
+ :recipient "Rasta Toucan"}]}
+ {:pulse-creator {:email "[email protected]"}
+ :affected-users [{:notification-type :slack
+ :recipient "#my-channel"}]
+ :dashboard-creator {:email "[email protected]"}
+ :pulse-id bad-slack-pulse-id
+ :pulse-name "Bad Slack Pulse"
+ :dashboard-id dash-id
+ :bad-parameters [{:name "Source"
+ :slug "source"
+ :id "_SOURCE_PARAM_ID_"
+ :type "string/="
+ :value ["LinkedIn"]}]
+ :dashboard-name "My Awesome Dashboard"}]
+ bad-pulses))))
+ (testing "Pulse can be archived"
+ (testing "Pulse starts as unarchived"
+ (is (false? (:archived bad-pulse))))
+ (testing "Pulse is now archived"
+ (is (true? (:archived (models.pulse/update-pulse! {:id bad-pulse-id :archived true})))))))))))
diff --git a/test/metabase/query_processor/middleware/measures_test.clj b/test/metabase/query_processor/middleware/measures_test.clj
index 5601b37ccfa..89ec34968a2 100644
--- a/test/metabase/query_processor/middleware/measures_test.clj
+++ b/test/metabase/query_processor/middleware/measures_test.clj
@@ -4,6 +4,7 @@
[mb.hawk.assert-exprs.approximately-equal]
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
+ [metabase.lib.options :as lib.options]
[metabase.lib.test-metadata :as meta]
[metabase.lib.test-util :as lib.tu]
[metabase.query-processor.middleware.measures :as measures]))
@@ -77,6 +78,19 @@
(is (=? {:stages [{:aggregation [[:sum {:display-name "My Custom Name"} some?]]}]}
(adjust query))))))
+(deftest ^:parallel measure-with-name-override-test
+ (testing "name from measure clause options is preserved (GHY-4517) so later stages can reference the column"
+ (let [[_measure mp] (mock-measure 1 (basic-sum-measure-query))
+ measure-meta (lib.metadata/measure mp 1)
+ query (-> (lib/query mp (meta/table-metadata :products))
+ (lib/aggregate (lib.options/update-options (lib/ref measure-meta)
+ assoc :name "revenue")))]
+ (is (=? {:stages [{:aggregation [[:sum {:name "revenue"} some?]]}]}
+ (adjust query)))
+ (testing "and shows up as the returned column's name"
+ (is (= ["revenue"]
+ (map :name (lib/returned-columns (adjust query)))))))))
+
(deftest ^:parallel multiple-measures-in-query-test
(testing "Multiple measures in a query all expand"
(let [[_measure1 mp] (mock-measure 1 (basic-sum-measure-query))
diff --git a/test/metabase/query_processor/middleware/metrics_test.clj b/test/metabase/query_processor/middleware/metrics_test.clj
index dd85ef27db3..ae6acf27f9a 100644
--- a/test/metabase/query_processor/middleware/metrics_test.clj
+++ b/test/metabase/query_processor/middleware/metrics_test.clj
@@ -172,6 +172,17 @@
:aggregation [[:avg {} [:field {} (meta/id :products :rating)]]]}]}
(adjust query)))))
+(deftest ^:parallel metric-with-name-override-test
+ (testing "name from the metric clause options is preserved (GHY-4517) so later stages can reference the column"
+ (let [[source-metric mp] (mock-metric)
+ query (-> (lib/query mp (meta/table-metadata :products))
+ (lib/aggregate (lib.options/update-options (lib/ref (lib.metadata/metric mp (:id source-metric)))
+ assoc :name "avg_rating")))]
+ (is (=? {:stages [{:aggregation [[:avg {:name "avg_rating"} some?]]}]}
+ (adjust query)))
+ (is (= ["avg_rating"]
+ (map :name (lib/returned-columns (adjust query))))))))
+
(deftest ^:parallel adjust-aggregation-metric-ref-test
(let [[source-metric mp] (mock-metric)
query (-> (lib/query mp (meta/table-metadata :products))