The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Inline malli refs and flatten root anyOf in MCP tool schemas (#71457)
Edward Pagetd8bb291939a6
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.cljindex ad79597f516..459bf3074bf 100644--- a/src/metabase/agent_api/api.clj+++ b/src/metabase/agent_api/api.clj@@ -577,7 +577,13 @@For metrics, supports: filters, group_by (aggregation is defined by the metric)."{:scope "agent:query:construct":tool {:name "construct_query"- :description "Construct a query against a Metabase table or metric. Returns an opaque query string that can be executed with execute_query."+ :description (str "Construct a query against a Metabase table or metric. "+ "Returns an opaque query string that can be executed with execute_query.\n\n"+ "For table queries: provide table_id. "+ "Supports filters, fields, aggregations, group_by, order_by, and limit.\n\n"+ "For metric queries: provide metric_id. "+ "Supports only filters and group_by (aggregation is defined by the metric).\n\n"+ "Provide either table_id or metric_id, not both."):annotations {:read-only? true :idempotent? true}}}[_route-params_query-params@@ -643,7 +649,13 @@:tool {:name "query":description (str "Query a Metabase table or metric. Returns results with column metadata. ""If more rows are available, the response includes a continuation_token — "- "pass it back to get the next page.")}}+ "pass it back to get the next page.\n\n"+ "For table queries: provide table_id. "+ "Supports filters, fields, aggregations, group_by, order_by, and limit.\n\n"+ "For metric queries: provide metric_id. "+ "Supports only filters and group_by (aggregation is defined by the metric).\n\n"+ "For pagination: provide only continuation_token from a previous response.\n\n"+ "Provide exactly one of table_id, metric_id, or continuation_token.")}}[_route-params_query-paramsbody :- ::query-request]diff --git a/src/metabase/api/macros/defendpoint/tools_manifest.clj b/src/metabase/api/macros/defendpoint/tools_manifest.cljindex f05a1186def..19d5ea1582e 100644--- a/src/metabase/api/macros/defendpoint/tools_manifest.clj+++ b/src/metabase/api/macros/defendpoint/tools_manifest.clj@@ -13,12 +13,64 @@[clojure.string :as str][malli.core :as mc][malli.json-schema :as mjs]+ [malli.util :as mut][metabase.api.macros :as api.macros][metabase.util :as u][metabase.util.malli.registry :as mr]))(set! *warn-on-reflection* true)+(defn- merge-with-optional-keys+ "Build a `:merge` schema from `schemas`, making all map entries optional.+ Non-map children (e.g. `:enum`, `:string`) are left as-is since `mut/optional-keys`+ only works on map-like schemas (`:map`, `:merge`, etc.)."+ [props schemas options]+ (mc/into-schema :merge props+ (mapv (fn [child]+ (if (mc/-entry-schema? (mc/deref-all child))+ (mut/optional-keys child)+ child))+ schemas)+ options))++(defn- inline-malli-refs+ "Walk a malli schema, replacing all registered-schema refs with their dereferenced content+ and simplifying composite schemas into `:merge` for LLM-compatible JSON Schema output.++ Transformations:+ - Registered-schema refs → dereferenced content (no `$ref`/`$defs` in JSON Schema)+ - `:and` → `:merge` (eliminates `allOf` — merges the `[:map {:encode/...}]` pattern)+ - `:or` → `:merge` with all entries optional (eliminates `anyOf` — union of all branches)+ - `:multi` → `:merge` with all entries optional (eliminates conditional dispatch)+ - Cyclic refs → `:any` (fallback for recursive schemas)++ Malli's `::mc/walked-refs` tracking prevents infinite recursion on cyclic schemas."+ [schema]+ (mc/walk+ schema+ (fn [node _path children _options]+ (cond+ (mc/-ref-schema? node)+ (let [child (first children)]+ (if (mc/schema? child)+ child+ (mc/schema :any)))++ (= :and (mc/type node))+ (mc/into-schema :merge (mc/properties node) children (mc/options node))++ (= :or (mc/type node))+ (merge-with-optional-keys (mc/properties node) children (mc/options node))++ (= :multi (mc/type node))+ (merge-with-optional-keys (dissoc (mc/properties node) :dispatch)+ (mapv (fn [[_k _props schema]] schema) children)+ (mc/options node))++ :else+ (mc/into-schema (mc/type node) (mc/properties node) children (mc/options node))))+ {::mc/walk-refs true ::mc/walk-schema-refs true}))+(defn- prefer-tool-descriptions"Pre-process a malli schema so that `:tool/description` takes precedence over `:description`before JSON Schema generation, since `mjs/transform` only reads `:description`."@@ -35,56 +87,13 @@(mc/into-schema (mc/type node) props children (mc/options node))node)))))-(def ^:private sanitize-replacements- {"~1" "_SLASH_"- "!" "_BANG_"- "=" "_EQ_"- "<" "_LT_"- ">" "_GT_"- "*" "_STAR_"- "+" "_PLUS_"- "/" "_SLASH_"})--(def ^:private sanitize-pattern- (re-pattern (str/join "|" (map #(java.util.regex.Pattern/quote %) (keys sanitize-replacements)))))--(defn- sanitize-def-name- "Sanitize a definition name for use in JSON Schema `$defs`."- [s]- (str/replace s sanitize-pattern sanitize-replacements))--(defn- sanitize-ref [ref-str]- (str/replace ref-str #"#/\$defs/(.+)"- (fn [[_ def-name]]- (str "#/$defs/" (sanitize-def-name def-name)))))--(defn- walk-sanitize-refs- "Recursively walk a JSON Schema structure (maps and vectors) and apply [[sanitize-ref]]- to every `:$ref` value. This ensures nested `$ref`s inside `oneOf`, `anyOf`, definitions, etc.- are properly sanitized."- [schema]- (cond- (map? schema) (into {} (map (fn [[k v]]- (if (= k :$ref)- [k (sanitize-ref v)]- [k (walk-sanitize-refs v)])))- schema)- (vector? schema) (mapv walk-sanitize-refs schema)- :else schema))-(defn malli->json-schema- "Transform a malli schema to JSON Schema, collecting any `$defs` into `definitions-acc`.- Returns the JSON Schema with `$ref` values sanitized and `:definitions` stripped."- [definitions-acc malli-schema]- (let [jss (mjs/transform (prefer-tool-descriptions malli-schema)- {::mjs/definitions-path "#/$defs/"})- defs (:definitions jss)]- (when (seq defs)- (swap! definitions-acc- into- (map (fn [[k v]] [(sanitize-def-name k) (walk-sanitize-refs v)]))- defs))- (walk-sanitize-refs (dissoc jss :definitions))))+ "Transform a malli schema to JSON Schema with all refs inlined (no `$ref` or `$defs`).+ First inlines all malli registered-schema refs, then applies tool-description preferences,+ then transforms to JSON Schema."+ [malli-schema]+ (let [prepared (-> malli-schema inline-malli-refs prefer-tool-descriptions)]+ (mjs/transform prepared)))(def ^:private annotation-key-mapping{:read-only? :readOnlyHint@@ -118,9 +127,9 @@(defn- schema->properties-and-required"Extract `:properties` and `:required` from a malli schema's JSON Schema.Returns nil if the schema is nil or doesn't have `:properties` (e.g., `:or`/`:oneOf`)."- [defs malli-schema]+ [malli-schema](when malli-schema- (let [jss (malli->json-schema defs malli-schema)]+ (let [jss (malli->json-schema malli-schema)](when (:properties jss)(select-keys jss [:properties :required])))))@@ -129,14 +138,14 @@Route params are always required. For body schemas that aren't simple maps (e.g. `:or`),the full JSON Schema is used directly. If route/query/body share a property name,later sources (body > query > route) take precedence."- [defs form]- (let [route-parts (schema->properties-and-required defs (get-in form [:params :route :schema]))- query-parts (schema->properties-and-required defs (get-in form [:params :query :schema]))+ [form]+ (let [route-parts (schema->properties-and-required (get-in form [:params :route :schema]))+ query-parts (schema->properties-and-required (get-in form [:params :query :schema]))body-schema (get-in form [:params :body :schema])- body-parts (schema->properties-and-required defs body-schema)+ body-parts (schema->properties-and-required body-schema);; If the body schema doesn't yield properties (e.g. :or), use its full JSON Schemabody-full (when (and body-schema (nil? body-parts))- (malli->json-schema defs body-schema))+ (malli->json-schema body-schema))all-props (merge (:properties route-parts)(:properties query-parts)(:properties body-parts))@@ -151,12 +160,12 @@(defn- response-schema->json-schema"Convert an endpoint's response schema to JSON Schema for the tools manifest."- [defs response-schema]+ [response-schema](when response-schema(let [resolved (mr/resolve-schema response-schema)content (or (-> resolved mc/properties :openapi/response-schema)response-schema)]- (malli->json-schema defs content))))+ (malli->json-schema content))))(defn- route-path->endpoint-path"Convert Clout-style route path (`:id`) to curly-brace path (`{id}`)."@@ -165,7 +174,7 @@(defn endpoint->tool-definition"Convert a single endpoint info + prefix to a tool definition map."- [defs prefix {:keys [form]}]+ [prefix {:keys [form]}](let [method (:method form)route-path (get-in form [:route :path])tool-md (get-in form [:metadata :tool])@@ -174,8 +183,8 @@description (or (:description tool-md)(:docstr form))full-path (str prefix (route-path->endpoint-path route-path))- input-schema (merge-input-schemas defs form)- resp-schema (response-schema->json-schema defs (:response-schema form))+ input-schema (merge-input-schemas form)+ resp-schema (response-schema->json-schema (:response-schema form))annotations (infer-annotations method (:annotations tool-md))task-support (:task-support tool-md)scope (get-in form [:metadata :scope])]@@ -208,17 +217,19 @@"Generate a tools manifest from all `:tool`-annotated endpoints.`namespace-prefixes` is a map of `{ns-symbol \"/api/agent\"}` — each namespace symbol maps- to the URL prefix its endpoints are served under."+ to the URL prefix its endpoints are served under.++ All malli registered-schema refs are inlined before JSON Schema generation, so tool schemas+ never contain `$ref` or `$defs`. Root-level `anyOf` (from malli `:or` body schemas) is+ flattened into a single merged object for LLM client compatibility."[namespace-prefixes]- (let [defs (atom (sorted-map))- tools (into []+ (let [tools (into [](mapcat (fn [[ns-sym prefix]](for [[_k endpoint] (api.macros/ns-routes ns-sym):when (get-in endpoint [:form :metadata :tool])]- (endpoint->tool-definition defs prefix endpoint))))+ (endpoint->tool-definition prefix endpoint))))namespace-prefixes)](check-tool-uniqueness tools)- (cond-> {:$schema "https://json-schema.org/draft/2020-12/schema"- :version "1.0.0"- :tools (sort-by :name tools)}- (seq @defs) (assoc :$defs @defs))))+ {:$schema "https://json-schema.org/draft/2020-12/schema"+ :version "1.0.0"+ :tools (sort-by :name tools)}))diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.cljindex 85710123284..774c32d7869 100644--- a/src/metabase/mcp/tools.clj+++ b/src/metabase/mcp/tools.clj@@ -4,7 +4,6 @@(:require[clojure.core.async :as a][clojure.string :as str]- [clojure.walk :as walk][metabase.agent-api.api :as agent-api][metabase.api.common :as api][metabase.api.macros.defendpoint.tools-manifest :as tools-manifest]@@ -36,34 +35,6 @@(generate-manifest)@manifest-delay))-(defn- collect-refs- "Walk a JSON Schema and return a set of def names referenced via $ref."- [schema]- (let [refs (volatile! #{})]- (walk/postwalk- (fn [x]- (when-let [ref (and (map? x) (:$ref x))]- (when-let [[_ def-name] (re-matches #"#/\$defs/(.+)" ref)]- (vswap! refs conj def-name)))- x)- schema)- @refs))--(defn- referenced-defs- "Return the subset of `all-defs` transitively referenced from `schema`."- [schema all-defs]- (loop [to-visit (collect-refs schema)- visited #{}- result {}]- (if-let [def-name (first to-visit)]- (if (visited def-name)- (recur (disj to-visit def-name) visited result)- (let [def-schema (get all-defs def-name)]- (recur (into (disj to-visit def-name) (when def-schema (collect-refs def-schema)))- (conj visited def-name)- (cond-> result def-schema (assoc def-name def-schema)))))- result)))-(defn- scope-matches?"Does `token-scopes` grant access to a tool with the given `tool-scope`?- nil token-scopes → always matches (internal callers)@@ -84,24 +55,15 @@(defn list-tools"Return the tool definitions suitable for MCP `tools/list` responses.- Inlines referenced `$defs` into each tool's `inputSchema` so that `$ref` pointers resolve.When `token-scopes` is provided, only tools whose scope matches are included."[token-scopes]- (let [{:keys [tools $defs]} (manifest)]+ (let [{:keys [tools]} (manifest)](into [](comp (filter #(scope-matches? token-scopes (:scope %)))(map (fn [tool]- (let [input (:inputSchema tool)- used (when (and (seq $defs) input)- (referenced-defs input $defs))]- (cond-> {:name (:name tool)- :description (:description tool)- :inputSchema (cond-> input- ;; the root object of an MCP tool inputSchema MUST be an- ;; "object" malli.json-schema rightly doesn't set type: "object"- ;; on a :or schema.- (not (:type input)) (assoc :type "object"))}- (seq used) (update :inputSchema assoc :$defs used))))))+ {:name (:name tool)+ :description (:description tool)+ :inputSchema (:inputSchema tool)})))tools)))(defn- build-tool-indexdiff --git a/test/metabase/api/macros/defendpoint/tools_manifest_test.clj b/test/metabase/api/macros/defendpoint/tools_manifest_test.cljindex e06e86f0a69..4a31ea9ab4d 100644--- a/test/metabase/api/macros/defendpoint/tools_manifest_test.clj+++ b/test/metabase/api/macros/defendpoint/tools_manifest_test.clj@@ -1,7 +1,6 @@(ns metabase.api.macros.defendpoint.tools-manifest-test(:require[clojure.test :refer :all]- [clojure.walk][metabase.api.macros :as api.macros][metabase.api.macros.defendpoint.tools-manifest :as tools-manifest][metabase.util.malli.registry :as mr])@@ -30,57 +29,61 @@(deftest ^:parallel prefer-tool-descriptions-test(testing "tool/description replaces description in JSON schema output"- (let [defs (atom (sorted-map))- jss (tools-manifest/malli->json-schema- defs- [:map [:id [:int {:description "Internal ID"- :tool/description "The ID of the saved question"}]]])]+ (let [jss (tools-manifest/malli->json-schema+ [:map [:id [:int {:description "Internal ID"+ :tool/description "The ID of the saved question"}]]])](is (= "The ID of the saved question"(get-in jss [:properties :id :description])))))(testing "schemas without tool/description keep original description"- (let [defs (atom (sorted-map))- jss (tools-manifest/malli->json-schema- defs- [:map [:id [:int {:description "Internal ID"}]]])]+ (let [jss (tools-manifest/malli->json-schema+ [:map [:id [:int {:description "Internal ID"}]]])](is (= "Internal ID"(get-in jss [:properties :id :description]))))))(mr/def ::ref-target-a [:enum "x" "y"])(mr/def ::ref-target-b [:map [:nested ::ref-target-a]])-(deftest ^:parallel nested-ref-sanitization-test- (testing "All $ref values are sanitized, including nested ones inside oneOf/definitions"- (let [defs (atom (sorted-map))- ;; [:or ...] produces oneOf in JSON Schema, each branch may have its own $ref- jss (tools-manifest/malli->json-schema defs [:or ::ref-target-a ::ref-target-b])]- ;; The top-level schema should be an anyOf (malli :or → anyOf) with $ref entries- (is (contains? jss :anyOf))- ;; Every $ref anywhere in the output must use sanitized names (no raw / characters after #/$defs/)- (let [all-refs (atom [])]- (clojure.walk/postwalk- (fn [x]- (when (and (map-entry? x) (= (key x) :$ref))- (swap! all-refs conj (val x)))- x)- jss)- (is (seq @all-refs) "should have found $ref entries")- (doseq [ref @all-refs]- (is (not (re-find #"#/\$defs/.*/" ref))- (str "$ref should not contain unsanitized /: " ref))))- ;; Also check that definitions stored in defs have sanitized nested $refs- (doseq [[_def-name def-val] @defs]- (clojure.walk/postwalk- (fn [x]- (when (and (map-entry? x) (= (key x) :$ref))- (is (not (re-find #"#/\$defs/.*/" (val x)))- (str "$ref in definition should not contain unsanitized /: " (val x))))- x)- def-val)))))+(deftest ^:parallel inline-malli-refs-test+ (testing "registered schema refs are inlined in JSON Schema output"+ (let [jss (tools-manifest/malli->json-schema [:map [:nested ::ref-target-a]])]+ (is (= {:type "object"+ :properties {:nested {:type "string" :enum ["x" "y"]}}+ :required [:nested]}+ jss))+ (is (not (contains? jss :definitions)))+ (is (not (re-find #"\$ref" (pr-str jss))))))+ (testing "nested registered refs are fully inlined"+ (let [jss (tools-manifest/malli->json-schema [:map [:item ::ref-target-b]])]+ (is (= {:type "string" :enum ["x" "y"]}+ (get-in jss [:properties :item :properties :nested])))+ (is (not (re-find #"\$ref" (pr-str jss)))))))++(deftest ^:parallel and-or-flattening-test+ (testing ":and produces flat object (no allOf)"+ (let [jss (tools-manifest/malli->json-schema+ [:and [:map [:a :int]] [:map [:b :string]]])]+ (is (= "object" (:type jss)))+ (is (= #{:a :b} (set (keys (:properties jss)))))+ (is (not (contains? jss :allOf)))))+ (testing ":or produces flat object with no required (no anyOf)"+ (let [jss (tools-manifest/malli->json-schema+ [:or [:map [:a :int]] [:map [:b :string]]])]+ (is (= "object" (:type jss)))+ (is (= #{:a :b} (set (keys (:properties jss)))))+ (is (not (contains? jss :anyOf)))+ (is (nil? (:required jss))+ "all entries should be optional after :or → :merge")))+ (testing ":and with encode map pattern produces flat object"+ (let [jss (tools-manifest/malli->json-schema+ [:and [:map [:x :int] [:y {:optional true} :string]]+ [:map {:encode/foo identity}]])]+ (is (= "object" (:type jss)))+ (is (= #{:x :y} (set (keys (:properties jss)))))+ (is (= [:x] (:required jss))))))(deftest ^:parallel endpoint->tool-definition-test(testing "Basic endpoint conversion"- (let [defs (atom (sorted-map))- form {:method :get+ (let [form {:method :get:route {:path "/v1/table/:id"}:params {:route {:binding '{:keys [id]}:schema [:map [:id :int]]}}@@ -88,7 +91,7 @@:docstr "Get a table.":metadata {:tool {:name "get_table"}}:body '(nil)}- result (tools-manifest/endpoint->tool-definition defs "/api/agent" {:form form})]+ result (tools-manifest/endpoint->tool-definition "/api/agent" {:form form})](is (= {:name "get_table":description "Get a table.":endpoint {:method "GET" :path "/api/agent/v1/table/{id}"}@@ -103,8 +106,7 @@result))))(testing "Scope is included when metadata has :scope"- (let [defs (atom (sorted-map))- form {:method :get+ (let [form {:method :get:route {:path "/v1/table/:id"}:params {:route {:binding '{:keys [id]}:schema [:map [:id :int]]}}@@ -112,17 +114,16 @@:metadata {:scope "agent:table:read":tool {:name "get_table"}}:body '(nil)}- result (tools-manifest/endpoint->tool-definition defs "/api/agent" {:form form})]+ result (tools-manifest/endpoint->tool-definition "/api/agent" {:form form})](is (= "agent:table:read" (:scope result)))))(testing "Scope is omitted when metadata has no :scope"- (let [defs (atom (sorted-map))- form {:method :get+ (let [form {:method :get:route {:path "/v1/test"}:docstr "Test endpoint.":metadata {:tool {:name "test_no_scope"}}:body '(nil)}- result (tools-manifest/endpoint->tool-definition defs "/api/test" {:form form})]+ result (tools-manifest/endpoint->tool-definition "/api/test" {:form form})](is (nil? (:scope result))))));; This test verifies the full pipeline with actual defendpoint endpoints.@@ -220,11 +221,26 @@(is (= 6 (count (:tools manifest))))(is (= (mapv :name (:tools manifest))(sort (mapv :name (:tools manifest))))- "tools should be sorted by name")))+ "tools should be sorted by name")+ (is (not (contains? manifest :$defs))+ "manifest should not have top-level $defs")))++(deftest ^:parallel refs-are-inlined-in-manifest-test+ (testing "malli->json-schema with :or produces flat object, no $ref or anyOf"+ (let [jss (tools-manifest/malli->json-schema [:or ::ref-target-a ::ref-target-b])]+ (is (= "object" (:type jss)))+ (is (not (contains? jss :anyOf)))+ (is (not (re-find #"\$ref" (pr-str jss))))))+ (testing "generate-tools-manifest output has no $ref or $defs anywhere"+ (let [manifest (test-manifest)+ as-str (pr-str manifest)]+ (is (not (re-find #"\$ref" as-str))+ "manifest should contain no $ref after inlining")+ (is (not (contains? manifest :$defs))+ "manifest should not have top-level $defs"))))-;; NOTE: simple registered schemas like ::test-status are inlined by malli-;; rather than producing $defs/$ref. $defs generation is exercised by the-;; real agent API endpoints which use complex recursive schemas.+;; NOTE: all registered-schema refs are inlined at the malli level before+;; JSON Schema generation, so no tool schema ever contains $ref or $defs.(deftest ^:parallel generate-tools-manifest-get-with-route-params-test(is (= {:name "test_get_thing"diff --git a/test/metabase/mcp/api_test.clj b/test/metabase/mcp/api_test.cljindex 4bafdbf8992..6c807470539 100644--- a/test/metabase/mcp/api_test.clj+++ b/test/metabase/mcp/api_test.clj@@ -347,19 +347,19 @@(is (true? (:isError result)))(is (str/includes? (:text (first (:content result))) "Missing required path parameter")))))-(deftest tools-list-defs-inlined-test- (testing "tools with $ref in inputSchema have $defs inlined"+(deftest tools-list-no-refs-test+ (testing "tool inputSchemas have no $ref, no $defs, and root type is always object"(let [tools (mcp.tools/list-tools nil)](doseq [tool tools]- (let [schema (:inputSchema tool)- refs (into #{} (map second) (re-seq #"#/\$defs/([A-Za-z0-9._-]+)" (pr-str schema)))]- (when (seq refs)- (testing (str (:name tool) " has $defs for all $ref targets")- (is (map? (:$defs schema))- (str (:name tool) " is missing $defs"))- (doseq [def-name refs]- (is (contains? (:$defs schema) def-name)- (str (:name tool) " missing def: " def-name))))))))))+ (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")))))))))(deftest tools-call-execute-query-test(testing "execute_query returns a streaming response captured as MCP text content"