@centrali-io/centrali-mcp 5.5.1 → 6.0.0

package/src/tools/saved-queries.ts

@@ -0,0 +1,497 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import { z } from "zod";
+import { registerTool, formatError } from "./_register.js";
+
+// Tool names use the canonical `*_saved_query` form (CEN-1198 rename:
+// "Smart Queries" → "Saved Queries"). Internally they route through
+// `sdk.savedQueries.*` and accept canonical query bodies. The legacy
+// `*_saved_query` MCP names were dropped before any external consumer
+// shipped — there is no compatibility window.
+
+const CANONICAL_QUERY_DEFINITION_HINT = `Canonical QueryDefinition body (saved queries store the inner shape — 'resource' is filled in from the collection slug arg).
+
+Field paths use dotted strings ('data.status'); operators (no '$' prefix): eq, ne, gt, gte, lt, lte, in, nin, contains, startsWith, endsWith, hasAny, hasAll, exists. Boolean trees use 'and', 'or', 'not'.
+
+Optional clauses authors can include in saved queries: 'where', 'sort', 'page', 'select', and 'joins' (multi-collection joins — see JOINS_HINT below). The 'text' (full-text search) and 'include' (relation expansion) clauses are reserved on saved-query create/update/test surfaces and currently fail with 422 unsupported_clause — they are available on the ad-hoc 'POST /records/query' surface only. Don't author saved queries that use them.
+
+Variables are referenced as '\${varName}' inside operator values; declare their types via the 'variables' arg (see VARIABLE_DECLARATION_HINT). On execute_saved_query the server validates each concrete value against the saved query's declarations by JS typeof — there is no coercion, so e.g. '"123"' is rejected for a 'number' declaration; 'datetime' accepts an ISO-8601 string (typed errors: 'variable_type_mismatch', 'missing_required_variable', 'extra_variable'). test_saved_query is unwired for typed dry-run — it falls back to legacy string substitution, so type validation only happens once the query is saved and executed. Example:
+  {
+    "where": { "data.status": { "eq": "\${statusFilter}" } },
+    "sort": [{ "field": "createdAt", "direction": "desc" }],
+    "page": { "limit": 100 }
+  }
+
+Legacy '{{varName}}' placeholders still work on pre-Phase-4 (untyped) saved queries during the deprecation window — every value is stringified before substitution. New saved queries should declare typed 'variables' and use '\${varName}'.
+
+Do NOT use legacy '\$'-prefixed operators ('\$eq', '\$gte', …). The data service still translates them server-side during the deprecation window, but new saved queries must author canonical operators.`;
+
+const JOINS_HINT = `Optional 'joins[]' clause — saved queries may join up to 4 additional collections to the primary record set. Each entry has shape:
+  {
+    "foreignSlug": "<collection slug>",        // required — literal, no \${var} placeholders
+    "localField":  "data.customerId",          // field on primary OR '<priorAlias>.<field>' to chain — literal
+    "foreignField": "id",                      // field on the joined table — literal
+    "joinType": "inner" | "left" | "right" | "full",  // required — see availability note below
+    "select": ["data.name", "data.email"],     // optional projection on the joined row
+    "alias": "customer"                        // optional; defaults to foreignSlug. REQUIRED when joining the same foreignSlug twice. Must not equal the primary 'resource' or "_joined". Literal.
+  }
+
+Cap: 4 joins per query (JOINS_MAX_LENGTH).
+
+Field reference rules:
+  - 'localField' / 'foreignField' use 'data.<field>' for JSONB-side properties; 'id', 'createdAt', and other top-level columns may be referenced bare.
+  - In a chained join, 'localField' may use '<alias>.<field>' to reference a prior join's row (e.g. 'customer.data.regionId').
+
+Identifier slots are LITERAL ONLY: 'foreignSlug', 'localField', 'foreignField', 'alias', and 'joinType' cannot contain '\${var}' placeholders. This mirrors standard SQL — parameter binding applies to values, never identifiers. Author-time auth reads the persisted body, so allowing placeholders here would let an executor rebind the join shape at runtime and bypass authorization.
+
+JoinType availability:
+  - 'inner' and 'left' are always available.
+  - 'right' and 'full' are gated server-side by the 'DATA_QUERY_OUTER_JOINS_ENABLED' env flag. When disabled, the executor returns 'unsupported_clause' on those join types. Default for the initial production rollout is disabled — coordinate with ops before authoring queries that depend on RIGHT or FULL OUTER.
+
+Constraints:
+  - 'text' and 'joins' are mutually exclusive in the same query — combining them is rejected with 'unsupported_combination'.
+  - 'include' and 'joins' are mutually exclusive — combining them is rejected with 'unsupported_combination'.
+  - Aliases (or foreignSlugs when alias is omitted) must be unique within 'joins[]'; duplicates fail with 'duplicate_join_alias'.
+  - Aliases must not collide with the primary 'resource' or the reserved key "_joined" — also surfaced as 'duplicate_join_alias'.
+  - Exceeding 4 entries fails with 'joins_length_exceeded'.
+
+Authorization: the caller needs 'records:list' on the primary collection AND on every joined collection. The data service enforces this server-side at author time; the LLM should not propose joins to collections the user can't read.
+
+Response shape: each row's joined data lands under a top-level '_joined' key in the row, namespaced by alias:
+  { "id": "...", "data": { ... }, "_joined": { "customer": { "id": "...", "data": { ... } } | null } }
+
+For LEFT joins with no joined-side match, the alias entry is null. For RIGHT and FULL OUTER joins, rows where the PRIMARY side has no match emit as phantom-primary rows: every primary column is null and the joined side carries the unmatched-foreign data:
+  { "id": null, "data": null, ..., "_joined": { "customer": { "id": "...", "data": { ... } } } }
+
+This is symmetric SQL semantics — the row exists, one side is missing. Consumers detect phantom rows by 'id === null'.`;
+
+const VARIABLE_DECLARATION_HINT = `Optional typed parameter declarations for '\${var}' placeholders in the query body. Each entry is keyed by the variable name and has shape:
+  { type, required?, default?, description? }
+Where 'type' is one of:
+  - 'string' | 'number' | 'boolean' | 'datetime' | 'id'
+  - { array: <innerType> }                              (e.g. { array: 'string' })
+  - { reference: '<collectionSlug>' }                   (e.g. { reference: 'orders' })
+When provided, every '\${var}' placeholder in the query body must be declared, and execute-time values are validated against these types by JS typeof (no coercion). Pass 'null' on update_saved_query to clear declarations and revert to untyped string substitution.`;
+
+/**
+ * Canonical placeholders use `${var}`. Any string value inside the query
+ * containing a placeholder produces a referenced-variable name. Used for
+ * best-effort client-side validation in execute_saved_query so the AI gets
+ * a tighter error before round-tripping to the server.
+ */
+function extractCanonicalVariableNames(definition: unknown): Set<string> {
+    const names = new Set<string>();
+    const re = /\$\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}/g;
+    const visit = (node: unknown): void => {
+        if (node == null) return;
+        if (typeof node === "string") {
+            for (const match of node.matchAll(re)) names.add(match[1]);
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const item of node) visit(item);
+            return;
+        }
+        if (typeof node === "object") {
+            for (const value of Object.values(node as Record<string, unknown>)) visit(value);
+        }
+    };
+    visit(definition);
+    return names;
+}
+
+export function registerSavedQueryTools(server: McpServer, sdk: CentraliSDK) {
+    registerTool<any>(server,
+        "list_saved_queries",
+        "List saved (a.k.a. smart) queries. Saved queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by collection record slug. Each row includes a 'variables' map (typed parameter declarations) when the query was authored with Phase 4 typed parameters.",
+        {
+            recordSlug: z
+                .string()
+                .optional()
+                .describe(
+                    "Filter by collection record slug. If omitted, lists all saved queries in the workspace"
+                ),
+        },
+        async ({ recordSlug }) => {
+            try {
+                const result = recordSlug
+                    ? await sdk.savedQueries.list(recordSlug)
+                    : await sdk.savedQueries.listAll();
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result.data, null, 2) },
+                    ],
+                };
+            } catch (error: unknown) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatError(error, "listing saved queries"),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    registerTool<any>(server,
+        "execute_saved_query",
+        `Execute a saved query by ID and return a { rows, meta, fields } envelope.
+
+Saved queries can declare variables referenced as '\${varName}' inside operator values. Pass concrete values via 'variables' — they are validated against the saved query's typed declarations by JS typeof (no coercion; see get_saved_query → 'variables' for the declared shape). Type mismatches surface clear errors from the server (e.g. 'variable_type_mismatch', 'missing_required_variable').
+
+Multi-join responses: when the saved query declares 'joins[]', each row in 'rows' carries a top-level '_joined' object keyed by join alias — 'rows[i]._joined': { '<alias>': <joinedRow> | null }. Aliases default to the joined collection's slug; LEFT joins surface 'null' for rows with no match. RIGHT and FULL OUTER joins (when enabled via 'DATA_QUERY_OUTER_JOINS_ENABLED') additionally surface PHANTOM-PRIMARY rows where the primary side has no match — every primary column is null and consumers detect them by 'rows[i].id === null'.`,
+        {
+            recordSlug: z
+                .string()
+                .describe("The collection's record slug the query belongs to"),
+            queryId: z.string().describe("The saved query ID (UUID) to execute"),
+            variables: z
+                .record(z.string(), z.any())
+                .optional()
+                .describe(
+                    "Values bound to the saved query's '\${varName}' placeholders. Keys must match the declared variables on the saved query; types are validated server-side by JS typeof — no coercion (typed Phase-4 queries) or stringified (legacy untyped queries)."
+                ),
+        },
+        async ({ recordSlug, queryId, variables }) => {
+            try {
+                // Best-effort client-side validation: fetch the saved query
+                // first so we can flag unknown / missing variables before the
+                // server round-trip. Server-side validation is still
+                // authoritative for type coercion and `variable_type_mismatch`.
+                let declared: Record<string, any> | null | undefined;
+                let referencedNames: Set<string> | undefined;
+                try {
+                    const fetched = await sdk.savedQueries.get(recordSlug, queryId);
+                    const row: any = fetched.data ?? {};
+                    declared = (row.variables ?? null) as Record<string, any> | null;
+                    referencedNames = extractCanonicalVariableNames(row.queryDefinition ?? row.query ?? {});
+                } catch {
+                    // Permission/network blip — skip preflight and let the
+                    // execute call surface the canonical error.
+                }
+
+                if (declared && typeof declared === "object") {
+                    const declaredKeys = new Set(Object.keys(declared));
+                    const provided = variables ?? {};
+                    const extras = Object.keys(provided).filter((k) => !declaredKeys.has(k));
+                    if (extras.length > 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text:
+                                        `Error executing saved query '${queryId}': unknown variable(s) ` +
+                                        extras.map((e) => `'${e}'`).join(", ") +
+                                        `. Declared variables: ${Object.keys(declared).join(", ") || "(none)"}.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const missing = Object.entries(declared)
+                        .filter(([name, def]: [string, any]) => def?.required === true && !(name in provided) && def?.default === undefined)
+                        .map(([name]) => name);
+                    if (missing.length > 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text:
+                                        `Error executing saved query '${queryId}': missing required variable(s) ` +
+                                        missing.map((m) => `'${m}'`).join(", ") + ".",
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                } else if (referencedNames && referencedNames.size > 0) {
+                    // Untyped (legacy) query that still references placeholders
+                    // — flag if no values supplied at all, but don't gate on
+                    // unknown keys because legacy substitution accepts extras.
+                    const provided = variables ?? {};
+                    const missing = Array.from(referencedNames).filter((n) => !(n in provided));
+                    if (missing.length > 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text:
+                                        `Error executing saved query '${queryId}': query references variable(s) ` +
+                                        missing.map((m) => `'${m}'`).join(", ") +
+                                        " but no values were provided. Pass them via the 'variables' arg.",
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+
+                const options = variables ? { variables } : undefined;
+                const result = await sdk.savedQueries.execute(
+                    recordSlug,
+                    queryId,
+                    options
+                );
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result.data, null, 2) },
+                    ],
+                };
+            } catch (error: unknown) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatError(error, `executing saved query '${queryId}'`),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    registerTool<any>(server,
+        "get_saved_query",
+        "Get a saved query by ID. Returns the full row including canonical 'queryDefinition' (where/sort/page/select/joins), the typed 'variables' declarations (when declared), and audit fields. ('text' and 'include' are reserved on saved-query surfaces — saved queries authored before that constraint may still carry them, but they cannot be re-saved.) Multi-join queries surface their joined-collection chain via 'queryDefinition.joins[]' — each entry shows the foreignSlug, fields, joinType, and optional alias/select.",
+        {
+            recordSlug: z.string().describe("The collection's record slug the query belongs to"),
+            queryId: z.string().describe("The saved query ID (UUID)"),
+        },
+        async ({ recordSlug, queryId }) => {
+            try {
+                const result = await sdk.savedQueries.get(recordSlug, queryId);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result.data, null, 2) },
+                    ],
+                };
+            } catch (error: unknown) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatError(error, `getting saved query '${queryId}'`),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    registerTool<any>(server,
+        "create_saved_query",
+        `Create a new saved query for a collection.
+
+Authorization (SECURITY DEFINER, locked 2026-05-04): saved queries are first-class resources and behave like SQL views — the AUTHOR's permissions define what the query can read; the executor only needs permission to invoke. At AUTHOR time (this call), the caller must hold 'records:list' on the primary collection AND on every collection referenced via 'joins[]'. The data service enforces this server-side and returns 403 if any access is missing. At EXECUTE time (execute_saved_query), only an 'execute' check on the saved-query resource runs — there is no per-collection re-check, and field-level redaction follows the author's permissions, not the executor's. Don't propose queries against collections the user can't read.
+
+${CANONICAL_QUERY_DEFINITION_HINT}
+
+${JOINS_HINT}
+
+${VARIABLE_DECLARATION_HINT}`,
+        {
+            recordSlug: z.string().describe("The collection's record slug to create the query for"),
+            name: z.string().describe("Display name for the saved query"),
+            description: z.string().optional().describe("Optional description"),
+            queryDefinition: z
+                .record(z.string(), z.any())
+                .describe(
+                    "Canonical inner QueryDefinition (without 'resource'). Supported clauses: 'where', 'sort', 'page', 'select', 'joins'. Reference variables as '\${varName}' inside operator values. 'joins' (max 4) enables multi-collection joins — see tool description for the JoinClause shape, identifier-literal rules, and joinType availability ('inner' / 'left' always; 'right' / 'full' gated by 'DATA_QUERY_OUTER_JOINS_ENABLED'). Reserved on this surface (saved queries) and rejected with 422 unsupported_clause: 'text' (full-text search) and 'include' (relation expansion) — they're available on the ad-hoc 'POST /records/query' surface only."
+                ),
+            variables: z
+                .record(z.string(), z.any())
+                .optional()
+                .describe(
+                    "Typed parameter declarations keyed by variable name. Shape: { type, required?, default?, description? }. type: 'string'|'number'|'boolean'|'datetime'|'id' | { array: T } | { reference: 'collectionSlug' }. When provided, every '\${var}' in queryDefinition must be declared."
+                ),
+        },
+        async ({ recordSlug, name, description, queryDefinition, variables }) => {
+            try {
+                const input: Record<string, any> = { name };
+                if (description !== undefined) input.description = description;
+                if (variables !== undefined) {
+                    // Typed declarations require the canonical create path,
+                    // which expects a full QueryDefinition (including
+                    // 'resource'). `recordSlug` is the URL-level source of
+                    // truth for the target collection — apply it last so a
+                    // caller-supplied `queryDefinition.resource` cannot
+                    // silently retarget the create.
+                    input.query = { ...(queryDefinition as object), resource: recordSlug };
+                    input.variables = variables;
+                } else {
+                    // No typed declarations — keep the legacy slug-based path
+                    // for back-compat with pre-Phase-4 callers.
+                    input.queryDefinition = queryDefinition;
+                }
+
+                const result = await sdk.savedQueries.create(recordSlug, input as any);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result.data, null, 2) },
+                    ],
+                };
+            } catch (error: unknown) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatError(error, `creating saved query '${name}' for '${recordSlug}'`),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    registerTool<any>(server,
+        "update_saved_query",
+        `Update an existing saved query. Only include the fields you want to change.
+
+Authorization (SECURITY DEFINER): saved queries follow author-bound permissions — the author's privileges define what the query can read; the executor only needs an 'execute' check on the saved-query resource. When updating 'queryDefinition' to add or change 'joins[]' (or change the primary 'resource'), this call requires 'records:list' on the primary collection AND every newly-referenced joined collection at AUTHOR time. The data service enforces this server-side and returns 403 if any access is missing. At EXECUTE time (execute_saved_query) there is no per-collection re-check, and field-level redaction follows the author's permissions, not the executor's.
+
+${CANONICAL_QUERY_DEFINITION_HINT}
+
+${JOINS_HINT}
+
+${VARIABLE_DECLARATION_HINT}`,
+        {
+            recordSlug: z.string().describe("The collection's record slug the query belongs to"),
+            queryId: z.string().describe("The saved query ID (UUID) to update"),
+            name: z.string().optional().describe("Updated display name"),
+            description: z.string().optional().describe("Updated description"),
+            queryDefinition: z
+                .record(z.string(), z.any())
+                .optional()
+                .describe("Updated canonical inner QueryDefinition (without 'resource'). Supported clauses: 'where', 'sort', 'page', 'select', 'joins' (max 4 — see tool description). Reserved on this surface (saved queries) and rejected with 422 unsupported_clause: 'text' (full-text search) and 'include' (relation expansion) — they're available on the ad-hoc 'POST /records/query' surface only."),
+            variables: z
+                .union([z.record(z.string(), z.any()), z.null()])
+                .optional()
+                .describe(
+                    "Replace the typed parameter declarations. Pass 'null' to clear declarations and revert the query to untyped string substitution. Omit to leave existing declarations untouched. Setting this routes through the canonical update path."
+                ),
+        },
+        async ({ recordSlug, queryId, name, description, queryDefinition, variables }) => {
+            try {
+                const input: Record<string, any> = {};
+                if (name !== undefined) input.name = name;
+                if (description !== undefined) input.description = description;
+
+                if (variables !== undefined) {
+                    // Canonical update: requires `query` (with resource) when
+                    // queryDefinition is also being updated; otherwise just
+                    // ship the variables change. Apply `resource` last so a
+                    // caller-supplied `queryDefinition.resource` cannot trip
+                    // the server's "resource cannot change on update" guard.
+                    if (queryDefinition !== undefined) {
+                        input.query = { ...(queryDefinition as object), resource: recordSlug };
+                    }
+                    input.variables = variables;
+                } else if (queryDefinition !== undefined) {
+                    input.queryDefinition = queryDefinition;
+                }
+
+                const result = await sdk.savedQueries.update(recordSlug, queryId, input as any);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result.data, null, 2) },
+                    ],
+                };
+            } catch (error: unknown) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatError(error, `updating saved query '${queryId}'`),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    registerTool<any>(server,
+        "delete_saved_query",
+        "Delete a saved query by ID.",
+        {
+            recordSlug: z.string().describe("The collection's record slug the query belongs to"),
+            queryId: z.string().describe("The saved query ID (UUID) to delete"),
+        },
+        async ({ recordSlug, queryId }) => {
+            try {
+                await sdk.savedQueries.delete(recordSlug, queryId);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Saved query '${queryId}' deleted from '${recordSlug}'.`,
+                        },
+                    ],
+                };
+            } catch (error: unknown) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatError(error, `deleting saved query '${queryId}'`),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    registerTool<any>(server,
+        "test_saved_query",
+        `Test execute a query definition without saving it. Useful for validating canonical syntax and previewing results before creating a saved query.
+
+${CANONICAL_QUERY_DEFINITION_HINT}
+
+${JOINS_HINT}
+
+Typed dry-run is not yet wired on the server: '/saved-queries/test' resolves '\${var}' placeholders via legacy string substitution and does not honor typed 'variableDeclarations'. Use create_saved_query + execute_saved_query (or update_saved_query) to validate typed parameters end-to-end.`,
+        {
+            recordSlug: z.string().describe("The collection's record slug to test against"),
+            queryDefinition: z
+                .record(z.string(), z.any())
+                .describe("Canonical inner QueryDefinition to test (without 'resource'). Supported clauses: 'where', 'sort', 'page', 'select', 'joins' (max 4 — see tool description). Reserved on this surface (saved-query test) and rejected with 422 unsupported_clause: 'text' and 'include' — they're available on the ad-hoc 'POST /records/query' surface only."),
+            variables: z
+                .record(z.string(), z.any())
+                .optional()
+                .describe("Optional runtime values bound to '\${var}' placeholders. Substituted via legacy string substitution on the test path (every value is stringified)."),
+        },
+        async ({ recordSlug, queryDefinition, variables }) => {
+            try {
+                const input: Record<string, any> = { queryDefinition };
+                if (variables !== undefined) input.variables = variables;
+
+                const result = await sdk.savedQueries.test(recordSlug, input as any);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result.data, null, 2) },
+                    ],
+                };
+            } catch (error: unknown) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatError(error, `test-executing saved query for '${recordSlug}'`),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+}
+
+// Exposed for tests
+export const _internal = { extractCanonicalVariableNames };

package/tests/savedQueriesRouting.test.cjs

@@ -0,0 +1,148 @@
+/**
+ * Regression tests for `registerSavedQueryTools` request shaping.
+ *
+ * Covers:
+ *   - create / update inject `resource` from the URL `recordSlug` and
+ *     override any caller-supplied `queryDefinition.resource` (otherwise
+ *     a tool call could silently retarget the saved query to a different
+ *     collection, or trip the server's "resource cannot change on update"
+ *     guard).
+ *   - test_saved_query no longer ships `variableDeclarations` to the
+ *     server (the canonical `/saved-queries/test` route does not honor
+ *     typed dry-run today; advertising it would be a lie).
+ *
+ * Uses a hand-rolled fake `McpServer` + `CentraliSDK` so we can assert
+ * exactly what `sdk.savedQueries.*` was called with.
+ */
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { registerSavedQueryTools } = require("../dist/tools/saved-queries.js");
+
+function makeFakeServer() {
+    const handlers = new Map();
+    return {
+        handlers,
+        tool: (name, _desc, _schema, handler) => {
+            handlers.set(name, handler);
+        },
+    };
+}
+
+function makeFakeSdk() {
+    const calls = [];
+    return {
+        calls,
+        savedQueries: {
+            create: async (recordSlug, input) => {
+                calls.push({ method: "create", recordSlug, input });
+                return { data: { id: "fake-id", recordSlug, ...input } };
+            },
+            update: async (recordSlug, queryId, input) => {
+                calls.push({ method: "update", recordSlug, queryId, input });
+                return { data: { id: queryId, recordSlug, ...input } };
+            },
+            test: async (recordSlug, input) => {
+                calls.push({ method: "test", recordSlug, input });
+                return { data: [] };
+            },
+            get: async (recordSlug, queryId) => {
+                calls.push({ method: "get", recordSlug, queryId });
+                throw new Error("no preflight in routing tests");
+            },
+            execute: async (recordSlug, queryId, options) => {
+                calls.push({ method: "execute", recordSlug, queryId, options });
+                return { data: { result: [] } };
+            },
+        },
+    };
+}
+
+function setup() {
+    const server = makeFakeServer();
+    const sdk = makeFakeSdk();
+    registerSavedQueryTools(server, sdk);
+    return { server, sdk };
+}
+
+test("create: recordSlug overrides caller-supplied queryDefinition.resource", async () => {
+    const { server, sdk } = setup();
+    const handler = server.handlers.get("create_saved_query");
+    await handler({
+        recordSlug: "orders",
+        name: "Active Orders",
+        queryDefinition: {
+            resource: "wrong-collection",
+            where: { "data.status": { eq: "${status}" } },
+        },
+        variables: { status: { type: "string", required: true } },
+    });
+    const call = sdk.calls.find((c) => c.method === "create");
+    assert.ok(call, "expected create call");
+    assert.equal(call.input.query.resource, "orders");
+    // The whole-object spread keeps the rest of the body intact.
+    assert.deepEqual(call.input.query.where, { "data.status": { eq: "${status}" } });
+    assert.deepEqual(call.input.variables, { status: { type: "string", required: true } });
+});
+
+test("create: legacy path used when no variables declared", async () => {
+    const { server, sdk } = setup();
+    const handler = server.handlers.get("create_saved_query");
+    await handler({
+        recordSlug: "orders",
+        name: "Legacy",
+        queryDefinition: { where: { "data.status": { eq: "open" } } },
+    });
+    const call = sdk.calls.find((c) => c.method === "create");
+    assert.ok(call.input.queryDefinition, "legacy field present");
+    assert.equal(call.input.query, undefined, "no canonical query field");
+});
+
+test("update: recordSlug overrides caller-supplied queryDefinition.resource", async () => {
+    const { server, sdk } = setup();
+    const handler = server.handlers.get("update_saved_query");
+    await handler({
+        recordSlug: "orders",
+        queryId: "qid-123",
+        queryDefinition: {
+            resource: "wrong-collection",
+            where: { "data.status": { eq: "${status}" } },
+        },
+        variables: { status: { type: "string" } },
+    });
+    const call = sdk.calls.find((c) => c.method === "update");
+    assert.ok(call, "expected update call");
+    assert.equal(call.input.query.resource, "orders");
+});
+
+test("update: variables-only edit ships {variables} without query", async () => {
+    const { server, sdk } = setup();
+    const handler = server.handlers.get("update_saved_query");
+    await handler({
+        recordSlug: "orders",
+        queryId: "qid-123",
+        variables: null,
+    });
+    const call = sdk.calls.find((c) => c.method === "update");
+    assert.equal(call.input.query, undefined, "no canonical query rewrite");
+    assert.equal(call.input.variables, null, "variables cleared");
+});
+
+test("test_saved_query: never ships variableDeclarations (server doesn't honor it yet)", async () => {
+    const { server, sdk } = setup();
+    const handler = server.handlers.get("test_saved_query");
+    await handler({
+        recordSlug: "orders",
+        queryDefinition: { where: { "data.status": { eq: "${status}" } } },
+        variables: { status: "open" },
+        // Even if a stale client passes variableDeclarations, the MCP
+        // schema doesn't declare it, so the handler never sees it. This
+        // assertion is defense-in-depth: ensure no code path forwards it.
+        variableDeclarations: { status: { type: "string", required: true } },
+    });
+    const call = sdk.calls.find((c) => c.method === "test");
+    assert.equal(call.input.variableDeclarations, undefined);
+    // Stays on the legacy slug-based test endpoint (no canonical `query`).
+    assert.equal(call.input.query, undefined);
+    assert.ok(call.input.queryDefinition);
+});