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
Fix issues with Codex MCP search + query pagination/row limit semantics (#72741)
Noah Moss892d4468ef8b
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.cljindex f57613ec13a..6f2a4eddae6 100644--- a/src/metabase/agent_api/api.clj+++ b/src/metabase/agent_api/api.clj@@ -10,6 +10,7 @@[metabase.api.macros.scope :as scope][metabase.api.routes.common :as api.routes.common][metabase.auth-identity.core :as auth-identity]+ [metabase.lib.core :as lib][metabase.lib.schema.id :as lib.schema.id][metabase.metabot.core :as metabot][metabase.metabot.tools.construct :as metabot-construct]@@ -35,14 +36,19 @@30)(def ^:private ^:const default-query-row-limit- "Default row limit for table queries when no limit is specified."+ "Default row cap when :limit is omitted from a table query request."200)-(def ^:private ^:const max-query-row-limit- "Hard cap on rows returned by the combined query endpoint, keeping result sets lean for LLM context windows.- Agents can paginate via continuation tokens for more."+(def ^:private ^:const page-size+ "Rows returned per page when paginating the combined query endpoint via continuation tokens.+ Also used as the query processor's per-call row constraint."200)+(def ^:private ^:const max-total-row-limit+ "Ceiling on the user-requested :limit for the combined query endpoint. Agents can paginate+ through up to this many rows across pages."+ 2000)+;;; ---------------------------------------------------- Helpers ------------------------------------------------------(defn- check-tool-result@@ -293,6 +299,25 @@:field-id field-id:limit (or (request/limit) default-field-values-limit)})))+(defn- coerce-query-list+ "Defensive coercion for `/v1/search`'s query arguments. Some MCP clients (notably+ Codex) serialize array args through a string layer, so a caller that intended to+ send `[\"orders\"]` may actually send `\"[\\\"orders\\\"]\"`. Accept either shape:+ an array is returned as-is; a string that parses as a JSON array of non-blank+ strings is unwrapped; any other string is treated as a single-element query."+ [v]+ (cond+ (nil? v) nil+ (sequential? v) v+ (string? v) (or (try+ (let [parsed (json/decode+kw v)]+ (when (and (sequential? parsed)+ (every? #(and (string? %) (not (str/blank? %))) parsed))+ parsed))+ (catch Exception _ nil))+ [v])+ :else v))+(api.macros/defendpoint :post "/v1/search" :- ::search-response"Search for tables and metrics.@@ -300,18 +325,24 @@Reciprocal Rank Fusion when both query types are provided."{:scope metabot/agent-search:tool {:name "search"- :description "Search for tables and metrics in Metabase. Use term_queries for keyword search or semantic_queries for natural language search."+ :description (str "Search for tables and metrics in Metabase. "+ "Use term_queries for keyword search or semantic_queries for natural language search. "+ "Both arguments are arrays of strings, for example term_queries: [\"orders\", \"revenue\"]."):annotations {:read-only? true}}}[_route-params_query-params{term-queries :term_queriessemantic-queries :semantic_queries}:- [:map- [:term_queries {:optional true} [:maybe [:sequential ms/NonBlankString]]]- [:semantic_queries {:optional true} [:maybe [:sequential ms/NonBlankString]]]]]+ [:term_queries {:optional true+ :tool/description "Keyword search queries as an array of strings, for example [\"orders\", \"revenue\"]."}+ [:maybe [:or [:sequential ms/NonBlankString] ms/NonBlankString]]]+ [:semantic_queries {:optional true+ :tool/description "Natural-language search queries as an array of strings, for example [\"how much revenue did we make\"]."}+ [:maybe [:or [:sequential ms/NonBlankString] ms/NonBlankString]]]]](let [results (metabot-search/search- {:term-queries (or term-queries [])- :semantic-queries (or semantic-queries [])+ {:term-queries (or (coerce-query-list term-queries) [])+ :semantic-queries (or (coerce-query-list semantic-queries) []):entity-types ["table" "metric"]:limit (or (request/limit) 50)})]{:data results@@ -339,19 +370,23 @@rejected here."#{"table" "card" "dataset" "metric"})-(defn- evaluate-program-for-execution- "Resolve a program's source entity, evaluate the program via agent-lib, and return a- plain MBQL 5 query map. The JSON round-trip strips lib metadata so the query can be- serialized into a continuation token."+(defn- evaluate-program-to-live-query+ "Resolve a program's source entity, evaluate the program via agent-lib, and return+ the live lib query (with lib metadata attached)."[program](let [source-type (get-in program [:source :type])](api/check (contains? allowed-program-source-types source-type)[400 (str "top-level program source must be one of: "(str/join ", " (sort allowed-program-source-types)))]))(let [source-entity (metabot-construct/program-source->source-entity (:source program))- result (metabot-construct/execute-program source-entity nil program)- pmbql (get-in result [:structured-output :query])]- (json/decode+kw (json/encode pmbql))))+ result (metabot-construct/execute-program source-entity nil program)]+ (get-in result [:structured-output :query])))++(defn- evaluate-program-for-execution+ "Evaluate a program and return a plain MBQL 5 query map suitable for serialization+ into a continuation token and execution by the QP."+ [program]+ (lib/prepare-for-serialization (evaluate-program-to-live-query program)))(api.macros/defendpoint :post "/v2/construct-query" :- ::construct-query-response"Construct an MBQL query from a structured agent-lib program.@@ -379,28 +414,62 @@;;; ------------------------------------------------- Combined Query -------------------------------------------------(defn- generate-continuation-token- "Build a base64-encoded continuation token containing the query and next-page pagination info."- [query-map limit page]+ "Build a base64-encoded continuation token carrying the query and next-page pagination info.+ :limit is the user's total row cap across all pages, not the per-page size."+ [query-map total-limit page](-> {:query query-map- :pagination {:limit limit :page (inc page)}}+ :pagination {:limit total-limit :page (inc page)}}json/encodeu/encode-base64))(defn- decode-continuation-token- "Decode a base64-encoded continuation token into {:query ... :pagination ...}."+ "Decode a base64-encoded continuation token into {:query ... :pagination ...}.+ The token is client-supplied, so sanity-check the pagination ints to turn+ garbage into a 400 rather than a downstream 500. This is robustness, not a+ security boundary — a caller can always issue a fresh program to run any+ query they want."[token]- (-> token u/decode-base64 json/decode+kw))--(defn- query-page-size- "Determine the per-page row limit for an evaluated MBQL 5 query, taking the- user-supplied limit (from the last stage) when present and capping at the- combined query endpoint's hard maximum."- [query-map]- (let [user-limit (-> query-map :stages last :limit)]- (min (or user-limit default-query-row-limit) max-query-row-limit)))+ (let [decoded (-> token u/decode-base64 json/decode+kw)+ {:keys [limit page]} (:pagination decoded)]+ (api/check (and (int? limit) (pos? limit))+ [400 "Invalid continuation token: limit must be a positive integer"])+ (api/check (and (int? page) (pos? page))+ [400 "Invalid continuation token: page must be a positive integer"])+ decoded))++(defn- total-row-limit+ "The user's requested :limit, defaulted when absent and capped at the combined+ endpoint's hard maximum. This is the app-level total-row budget enforced across+ paginated responses; each page's QP-level cap comes from `:page.items`, which+ `remaining-page-rows` clamps to respect this total."+ [live-query]+ (min (or (lib/current-limit live-query) default-query-row-limit)+ max-total-row-limit))++(defn- rows-before-page+ "Total rows consumed by the pages preceding `page`. Single source of truth for+ the page-size * (page - 1) arithmetic used by both sizing and pagination-exit."+ [page]+ (* (dec page) page-size))++(defn- remaining-page-rows+ "Rows to request for this page, respecting the user's total cap.+ Returns at most page-size, and never more than remaining rows under the cap."+ [total-limit page]+ (max 0 (min page-size (- total-limit (rows-before-page page)))))++(defn- more-pages-available?+ "True when this page was filled to its requested size *and* the total cap still+ has room for more rows — i.e. we should emit a continuation token."+ [page total-limit rows-returned items]+ (and (= rows-returned items)+ (< (rows-before-page (inc page)) total-limit)))(defn- apply-page-to-query- "Apply :page clause to the last stage of a MBQL 5 query map."+ "Set `:page` on the last stage of a serialized MBQL 5 query map. Operates on the+ plain-map form because the continuation-token path only has that shape available —+ rehydrating to a live lib query here would require a metadata provider we don't+ currently plumb through the token."[query-map page items](let [stages (:stages query-map)last-idx (dec (count stages))]@@ -416,11 +485,12 @@:context :agent})))(defn- prepare-combined-query- "Apply the tighter row cap used by the combined query endpoint."+ "Apply the tighter row cap used by the combined query endpoint. Each page is bounded+ by page-size; the user's total-limit is enforced separately via pagination."[query](assoc (prepare-agent-query query)- :constraints {:max-results max-query-row-limit- :max-results-bare-rows max-query-row-limit}))+ :constraints {:max-results page-size+ :max-results-bare-rows page-size}))(mr/def ::query-request"Request body for /v2/query. Accepts either a structured program or a continuation_token."@@ -429,6 +499,19 @@[:continuation [:map [:continuation_token ms/NonBlankString]]][:program ::program-request]])+(defn- initial-page-state+ "Normalize the two /v2/query entry points into a single {:query :total-limit :page}+ shape. A fresh program evaluates the user's program and computes a total-row budget+ from its `:limit`; a continuation token carries that state from a prior response."+ [body]+ (if-let [token (:continuation_token body)]+ (let [{:keys [query pagination]} (decode-continuation-token token)]+ {:query query :total-limit (:limit pagination) :page (:page pagination)})+ (let [live-query (evaluate-program-to-live-query body)]+ {:query (lib/prepare-for-serialization live-query)+ :total-limit (total-row-limit live-query)+ :page 1})))+(api.macros/defendpoint :post "/v2/query":- (streaming-response/streaming-response-schema ::query-response)"Execute a structured program and stream the results, with continuation-token pagination.@@ -447,13 +530,9 @@[_route-params_query-paramsbody :- ::query-request]- (let [{:keys [query limit page]}- (if-let [token (:continuation_token body)]- (let [{:keys [query pagination]} (decode-continuation-token token)]- {:query query :limit (:limit pagination) :page (:page pagination)})- (let [query (evaluate-program-for-execution body)]- {:query query :limit (query-page-size query) :page 1}))- mbql5-with-page (apply-page-to-query query page limit)]+ (let [{:keys [query total-limit page]} (initial-page-state body)+ items (remaining-page-rows total-limit page)+ mbql5-with-page (apply-page-to-query query page items)](qp.streaming/streaming-response[rff :api](qp/process-query@@ -462,8 +541,8 @@rff(fn [result](assoc result :continuation_token- (when (= (:row_count result) limit)- (generate-continuation-token query limit page)))))))))+ (when (more-pages-available? page total-limit (:row_count result) items)+ (generate-continuation-token query total-limit page)))))))));;; ------------------------------------------------- Execute Query --------------------------------------------------diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.cljindex d0dcdf9f61e..f63243f2ee2 100644--- a/src/metabase/mcp/tools.clj+++ b/src/metabase/mcp/tools.clj@@ -77,6 +77,38 @@(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."+ [response]+ (let [{msg :message :keys [specific-errors errors error]} (:body response)+ 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+ :else (str "Agent API error: " (:status response)))))+;;; ------------------------------------------------- Tool Dispatch -------------------------------------------------(defn- text-content@@ -121,7 +153,11 @@(deliver result (if (instance? StreamingResponse resp-body)(capture-streaming-response resp-body)response)))- (fn [error] (deliver result {:status 500 :body {:message (ex-message error)}}))))+ (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.@@ -143,9 +179,7 @@(text-content (:body response)):else- (error-content (or (some-> response :body :message)- (some-> response :body :error)- (str "Agent API error: " (:status response))))))))+ (error-content (extract-error-message response))))))(defn- interpolate-path"Replace `{param}` placeholders in `path` with values from `arguments`.diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.cljindex 6c4a6d95adf..497e9f9e749 100644--- a/test/metabase/agent_api/api_test.clj+++ b/test/metabase/agent_api/api_test.clj@@ -6,6 +6,7 @@[environ.core :as env][java-time.api :as t][medley.core :as m]+ [metabase.agent-api.api :as agent-api.api][metabase.agent-api.settings :as agent-api.settings][metabase.lib.core :as lib][metabase.lib.metadata :as lib.metadata]@@ -230,6 +231,22 @@(mt/user-http-request :rasta :post 200 "agent/v1/search"{:term_queries ["AgentSearchTestTable"]}))))))))+(deftest coerce-query-list-test+ (let [coerce #'agent-api.api/coerce-query-list]+ (testing "arrays pass through unchanged"+ (is (= ["orders" "revenue"] (coerce ["orders" "revenue"]))))+ (testing "nil stays nil"+ (is (nil? (coerce nil))))+ (testing "a bare string becomes a single-element list"+ (is (= ["orders"] (coerce "orders"))))+ (testing "a JSON-stringified array of strings is unwrapped"+ (is (= ["orders" "revenue"] (coerce "[\"orders\", \"revenue\"]"))))+ (testing "JSON arrays with non-string elements are not unwrapped — they fall back to a literal single query so that downstream :sequential NonBlankString validation is never bypassed"+ (is (= ["[1, 2]"] (coerce "[1, 2]")))+ (is (= ["[\"\"]"] (coerce "[\"\"]"))))+ (testing "non-JSON strings become a single-element list"+ (is (= ["not json ["] (coerce "not json ["))))))+(defn- decode-query"Decode a base64-encoded query response to a Clojure map, then normalize it so lib functions work."[response]@@ -376,7 +393,7 @@(:measures table))))))))(deftest combined-query-test- (testing "Returns results for a table query"+ (testing "Returns results for a table query that fits in a single page"(let [table-id (mt/id :orders)field-id (visible-field-id table-id "ID")response (mt/user-http-request :rasta :post 202 "agent/v2/query"@@ -385,27 +402,29 @@["limit" 5]]})](is (=? {:status "completed":row_count 5- :continuation_token string?+ :continuation_token nil?:data {:cols sequential?:rows (fn [rows] (= 5 (count rows)))}}response))))- (testing "Continuation token returns next page of results"- (let [table-id (mt/id :orders)- field-id (visible-field-id table-id "ID")- page1 (mt/user-http-request :rasta :post 202 "agent/v2/query"- {:source {:type "table" :id table-id}- :operations [["order-by" ["field" field-id]]- ["limit" 5]]})- page2 (mt/user-http-request :rasta :post 202 "agent/v2/query"- {:continuation_token (:continuation_token page1)})]- (is (=? {:row_count 5+ (testing "Continuation token returns next page of results when the total limit exceeds the page size"+ (let [table-id (mt/id :orders)+ field-id (visible-field-id table-id "ID")+ page-size 200+ total-rows 250+ page1 (mt/user-http-request :rasta :post 202 "agent/v2/query"+ {:source {:type "table" :id table-id}+ :operations [["order-by" ["field" field-id]]+ ["limit" total-rows]]})+ page2 (mt/user-http-request :rasta :post 202 "agent/v2/query"+ {:continuation_token (:continuation_token page1)})]+ (is (=? {:row_count page-size:continuation_token string?- :data {:rows (fn [rows] (= 5 (count rows)))}}+ :data {:rows (fn [rows] (= page-size (count rows)))}}page1))- (is (=? {:row_count 5- :continuation_token string?- :data {:rows (fn [rows] (= 5 (count rows)))}}+ (is (=? {:row_count (- total-rows page-size)+ :continuation_token nil?+ :data {:rows (fn [rows] (= (- total-rows page-size) (count rows)))}}page2))(is (not= (get-in page1 [:data :rows])(get-in page2 [:data :rows]))@@ -418,13 +437,33 @@{:source {:type "table" :id (mt/id :orders)}:operations [["aggregate" ["count"]]]}))))- (testing "Constraint cap limits results to 200 rows"+ (testing "Per-page cap limits a single page to 200 rows even when the total limit is higher"(is (=? {:status "completed":row_count (fn [n] (<= n 200))}(mt/user-http-request :rasta :post 202 "agent/v2/query"{:source {:type "table" :id (mt/id :orders)}:operations [["limit" 1000]]})))))+(defn- make-continuation-token [pagination]+ (-> {:query {:database (mt/id) :stages [{:source-table (mt/id :orders)}]}+ :pagination pagination}+ json/encode+ u/encode-base64))++(deftest continuation-token-validation-test+ (testing "Malformed pagination ints in a continuation token produce a 400, not a 500.+ This is robustness — the token isn't a trust boundary, since a caller can+ always issue a fresh program."+ (doseq [[label pagination] [["zero limit" {:limit 0 :page 1}]+ ["negative limit" {:limit -10 :page 1}]+ ["non-integer limit" {:limit "lots" :page 1}]+ ["zero page" {:limit 200 :page 0}]+ ["negative page" {:limit 200 :page -1}]+ ["non-integer page" {:limit 200 :page "next"}]]]+ (testing label+ (mt/user-http-request :rasta :post 400 "agent/v2/query"+ {:continuation_token (make-continuation-token pagination)})))))+(deftest combined-query-metric-test(mt/with-temp [:model/Card metric {:name "Test Metric":type :metricdiff --git a/test/metabase/mcp/api_test.clj b/test/metabase/mcp/api_test.cljindex 6cc8452cc54..f30c5f94879 100644--- a/test/metabase/mcp/api_test.clj+++ b/test/metabase/mcp/api_test.clj@@ -181,7 +181,27 @@(testing "each tool has a description and inputSchema"(doseq [tool tools](is (string? (:description tool)))- (is (map? (:inputSchema 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]))))))))(deftest ping-test(testing "ping returns empty result"@@ -234,6 +254,33 @@(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)))))))