@centrali-io/centrali-mcp 5.5.1 → 6.1.0

package/README.md

@@ -90,7 +90,7 @@ After connecting, call `describe_centrali` first — it returns the full capabil
 | `describe_records` | Schema reference for record operations (filters, sorting, pagination, expand) |
 | `describe_search` | Schema reference for full-text search |
 | `describe_compute` | Compute function reference (input contract, secrets, async execution, api object) |
-| `describe_smart_queries` | Smart query reference (parameterized queries, variables) |
+| `describe_saved_queries` | Saved-query schema reference (parameterized queries, variables) |
 | `describe_orchestrations` | Orchestration reference (multi-step workflows, encrypted params) |
 | `describe_insights` | Anomaly insights reference |
 | `describe_validation` | Data validation reference |
@@ -154,19 +154,113 @@ After connecting, call `describe_centrali` first — it returns the full capabil
 | `invoke_endpoint` | Call a sync compute endpoint by path (returns response inline) |
 | `remove_allowed_domain` | Remove a domain from the allowlist |
 
-### Saved Queries (a.k.a. Smart Queries)
+### Saved Queries
 
-Saved queries store a canonical `QueryDefinition` plus optional variables. Tool names keep the `_smart_query` suffix for backwards compatibility, but inputs and outputs are the canonical shape.
+Saved queries store a canonical `QueryDefinition` plus optional variables and an optional multi-collection `joins[]` clause.
 
 | Tool | Description |
 |------|-------------|
-| `list_smart_queries` | List saved queries, optionally by collection |
-| `get_smart_query` | Get a saved query by ID |
-| `create_smart_query` | Create a reusable parameterized query (canonical body) |
-| `update_smart_query` | Update a saved query (canonical body) |
-| `delete_smart_query` | Delete a saved query |
-| `execute_smart_query` | Execute a saved query with optional variables |
-| `test_smart_query` | Test a canonical query definition without saving |
+| `list_saved_queries` | List saved queries, optionally by collection |
+| `get_saved_query` | Get a saved query by ID |
+| `create_saved_query` | Create a reusable parameterized query (canonical body) |
+| `update_saved_query` | Update a saved query (canonical body) |
+| `delete_saved_query` | Delete a saved query |
+| `execute_saved_query` | Execute a saved query with optional variables |
+| `test_saved_query` | Test a canonical query definition without saving |
+
+**Typed parameter discovery → execute.** Saved queries authored with typed parameters expose their parameter shape through `describe_saved_queries` (schema reference) and `get_saved_query` / `list_saved_queries` (per-row `variables` declarations). The expected discover-then-execute flow:
+
+1. **Discover schema** (one-shot) — `describe_saved_queries` returns the `QueryVariableDefinition` shape (`type`, `required?`, `default?`, `description?`) and the supported `VariableType` union (`string` | `number` | `boolean` | `datetime` | `id` | `{ array: T }` | `{ reference: collectionSlug }`).
+2. **Discover the query** — `get_saved_query` returns the row including `variables`. Read each entry to learn what to bind. The canonical response includes `queryDefinition.resource` (always equal to the row's `recordSlug`):
+   ```json
+   {
+     "id": "…",
+     "name": "Monthly revenue",
+     "recordSlug": "orders",
+     "queryDefinition": {
+       "resource": "orders",
+       "where": { "and": [
+         { "data.month": { "eq": "${month}" } },
+         { "data.region": { "eq": "${region}" } }
+       ]},
+       "sort": [{ "field": "data.amount", "direction": "desc" }],
+       "page": { "limit": 100 }
+     },
+     "variables": {
+       "month":  { "type": "datetime", "required": true, "description": "Month bucket (UTC)" },
+       "region": { "type": "string",   "required": true }
+     }
+   }
+   ```
+3. **Execute typed** — pass concrete values via `execute_saved_query`'s `variables` arg. The server validates each value against its declared type (no coercion — `"123"` will not be accepted for a `number` declaration) and then substitutes. `datetime` accepts an ISO-8601 string:
+   ```json
+   {
+     "recordSlug": "orders",
+     "queryId": "…",
+     "variables": { "month": "2026-04-01T00:00:00Z", "region": "us-east" }
+   }
+   ```
+   Typed errors surface as `variable_type_mismatch`, `missing_required_variable`, or `extra_variable`. Untyped (legacy) rows have `variables: null` and accept any keys; values are stringified before substitution. The untyped fallback is also taken by post-backfill rows (canonical body, no declarations yet) until an author promotes them.
+
+The MCP `test_saved_query` tool intentionally does **not** expose `variableDeclarations` — its dry-run path falls back to legacy string substitution and does not enforce typed declarations. Round-trip via `create_saved_query` + `execute_saved_query` to validate typed parameters end-to-end.
+
+**Multi-collection joins.** Saved queries support an optional `joins[]` clause inside `queryDefinition` (max 4 entries). Each entry joins another collection to the primary record set:
+
+```json
+{
+  "resource": "orders",
+  "where": { "data.status": { "eq": "open" } },
+  "joins": [
+    {
+      "foreignSlug": "customers",
+      "localField": "data.customerId",
+      "foreignField": "id",
+      "joinType": "left",
+      "select": ["id", "data.name", "data.email"],
+      "alias": "customer"
+    }
+  ],
+  "sort": [{ "field": "createdAt", "direction": "desc" }],
+  "page": { "limit": 50 }
+}
+```
+
+Constraints (validated by `@centrali/query`):
+
+- `joinType` must be `'inner'` or `'left'` — `'right'` and `'full'` are rejected by the executor with `unsupported_clause`.
+- `text` and `joins` cannot appear in the same query (`unsupported_combination`).
+- Aliases (or implicit `foreignSlug`) must be unique within `joins[]` (`duplicate_join_alias`).
+- Cap of 4 entries (`joins_length_exceeded`).
+- `localField` may use `<priorAlias>.<field>` to chain a join through an earlier alias.
+
+`execute_saved_query` returns `{ rows, meta, fields }`. Each entry in `rows` carries joined data under a top-level `_joined` key:
+
+```json
+{
+  "rows": [
+    {
+      "id": "order-123",
+      "data": { "status": "open" },
+      "_joined": {
+        "customer": { "id": "cust-1", "data": { "name": "Acme" } }
+      }
+    }
+  ],
+  "meta": { "limit": 50, "offset": 0, "total": 1 },
+  "fields": [{ "name": "id" }, { "name": "data" }, { "name": "_joined" }]
+}
+```
+
+LEFT joins surface `null` for unmatched rows.
+
+**Authorization (SECURITY DEFINER, locked 2026-05-04).** Saved queries are author-bound — the AUTHOR's permissions define what the query can read; the executor only needs an `execute` check on the saved-query resource at runtime.
+
+- **Author time** (`create_saved_query` / `update_saved_query` / `test_saved_query`): the caller must hold `records:list` on the primary collection AND on every collection referenced in `joins[]`. The data service returns 403 if any access is missing.
+- **Execute time** (`execute_saved_query`): only `execute` on the saved-query resource is checked; there is no per-collection re-check, and field-level redaction follows the author's permissions, not the executor's. Secret-masking still applies unconditionally.
+
+AI assistants should not propose saved queries (or join chains) against collections the **author** can't read — execute will succeed for less-privileged callers, but authoring will fail.
+
+**Reserved clauses.** Saved-query create/update/test surfaces reject `text` (full-text search) and `include` (relation expansion) with 422 `unsupported_clause`. Those clauses are available on the ad-hoc `POST /records/query` surface only — don't author saved queries that use them.
 
 ### Orchestrations
 | Tool | Description |

package/dist/index.js

@@ -17,7 +17,7 @@ const structures_js_1 = require("./tools/structures.js");
 const records_js_1 = require("./tools/records.js");
 const search_js_1 = require("./tools/search.js");
 const compute_js_1 = require("./tools/compute.js");
-const smart_queries_js_1 = require("./tools/smart-queries.js");
+const saved_queries_js_1 = require("./tools/saved-queries.js");
 const orchestrations_js_1 = require("./tools/orchestrations.js");
 const insights_js_1 = require("./tools/insights.js");
 const validation_js_1 = require("./tools/validation.js");
@@ -73,7 +73,7 @@ function main() {
         (0, records_js_1.registerRecordTools)(server, sdk, baseUrl, workspaceId);
         (0, search_js_1.registerSearchTools)(server, sdk);
         (0, compute_js_1.registerComputeTools)(server, sdk, baseUrl, workspaceId);
-        (0, smart_queries_js_1.registerSmartQueryTools)(server, sdk);
+        (0, saved_queries_js_1.registerSavedQueryTools)(server, sdk);
         (0, orchestrations_js_1.registerOrchestrationTools)(server, sdk);
         (0, insights_js_1.registerInsightTools)(server, sdk);
         (0, validation_js_1.registerValidationTools)(server, sdk);

package/dist/tools/compute.js

@@ -379,7 +379,7 @@ function registerComputeTools(server, sdk, centraliUrl, workspaceId) {
         triggerMetadata: zod_1.z
             .record(zod_1.z.string(), zod_1.z.any())
             .optional()
-            .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' }. All trigger types accept params: a dictionary of static values passed to the function as triggerParams. Mark any secret with { value: 'plaintext', encrypt: true } to store it AES-256-GCM-encrypted at rest; it arrives as plaintext in triggerParams at execution time."),
+            .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: { path } where path is a URL-safe slug (e.g. 'stripe-webhook'); the trigger is reachable at `<api-host>/data/workspace/<workspaceSlug>/api/v1/http-trigger/<path>`. Optional native HMAC signature verification (no crypto in the function body): the **recommended path** is { validateSignature: true, provider: 'svix' | 'stripe' | 'slack' | 'github' | 'shopify', signingSecret } — the `provider` shortcut wires every wire-format detail (header names, signed-value format, digest encoding, secret encoding) from a built-in preset. Covers Svix (Clerk, Resend, Loops, OpenAI, Brex), Stripe, Slack, GitHub, Shopify out of the box. **Advanced**: any preset field can be overridden, or the preset can be skipped entirely by supplying the raw knobs directly — { validateSignature: true, signingSecret, signatureHeaderName, signatureIdHeaderName?, timestampHeaderName?, timestampExtractionPattern?, extractionPattern?, hmacAlgorithm?, hmacEncoding?, secretEncoding?, encoding?, payloadFormat? }. Defaults when no provider: hmacAlgorithm 'sha256', hmacEncoding 'base64', extractionPattern '^(?:v1,)?(.+)$', secretEncoding 'raw'; built-in 5-minute replay tolerance. Two-step setup recommended: (1) create the trigger with just { path } and optionally { provider } — the public URL is `<api-host>/data/workspace/<ws>/api/v1/http-trigger/<path>`; (2) register that URL with the webhook provider; (3) when the provider issues the signing secret, call update_trigger with validateSignature: true + signingSecret. Providers will not give a signing secret until they have the URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' | 'svix' | 'stripe' | 'slack' | 'github' | 'shopify', secret? } — provider-named modes are HMAC verification with the matching preset (auth.secret is the colocated signing secret; legacy `mode: 'hmac'` keeps its single-header body-only behaviour for back-compat). All trigger types accept params: a dictionary of static values passed to the function as triggerParams. Mark any secret with { value: 'plaintext', encrypt: true } to store it AES-256-GCM-encrypted at rest; it arrives as plaintext in triggerParams at execution time."),
         enabled: zod_1.z.boolean().optional().describe("Whether the trigger is enabled (default: true)"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ name, functionId, executionType, description, triggerMetadata, enabled }) {
         try {

package/dist/tools/describe.js

@@ -90,16 +90,16 @@ function registerDescribeTools(server) {
                                 ],
                             },
                             smart_queries: {
-                                summary: "Reusable, parameterized queries defined in the console. Support {{variable}} substitution.",
-                                describeWith: "describe_smart_queries",
+                                summary: "Reusable, parameterized queries defined in the console. Support typed '${variable}' substitution and multi-collection joins (up to 4 joined collections per query).",
+                                describeWith: "describe_saved_queries",
                                 tools: [
-                                    "list_smart_queries",
-                                    "get_smart_query",
-                                    "create_smart_query",
-                                    "update_smart_query",
-                                    "delete_smart_query",
-                                    "execute_smart_query",
-                                    "test_smart_query",
+                                    "list_saved_queries",
+                                    "get_saved_query",
+                                    "create_saved_query",
+                                    "update_saved_query",
+                                    "delete_saved_query",
+                                    "execute_saved_query",
+                                    "test_saved_query",
                                 ],
                             },
                             orchestrations: {
@@ -845,6 +845,33 @@ function registerDescribeTools(server) {
                                 triggerMetadata_examples: {
                                     "event-driven": { eventType: "record_created", recordSlug: "orders" },
                                     scheduled: { scheduleType: "cron", cronExpression: "0 9 * * *", timezone: "America/New_York" },
+                                    "http-trigger_url_shape": "Public URL: <api-host>/data/workspace/<workspaceSlug>/api/v1/http-trigger/<path>. The path is supplied by the caller in triggerMetadata.path and must be URL-safe. The URL is NOT returned in the create_trigger / get_trigger response — derive it from the workspaceSlug + path.",
+                                    "http-trigger_setup_flow": "Webhook signing secrets are chicken-and-egg: providers issue the secret only AFTER you give them a URL. Recommended flow — (1) create_trigger with { path, provider, validateSignature: true } and NO signingSecret — the trigger is created in a pending state with a stable URL; (2) register that URL in the provider's dashboard; (3) once the provider returns the signing secret, call update_trigger with signingSecret set. Until step 3 lands, the trigger rejects every request with 'HMAC signing secret not configured for this endpoint' — that's the desired safe default during URL-registration.",
+                                    "http-trigger_provider_shortcut": {
+                                        _note: "Recommended — one preset wires every wire-format detail. Use this for Svix (Clerk, Resend, Loops, OpenAI, Brex), Stripe, Slack, GitHub, Shopify. Override individual fields only if a provider's scheme has drifted (e.g. custom hmacAlgorithm).",
+                                        path: "clerk-webhook",
+                                        validateSignature: true,
+                                        provider: "svix",
+                                        signingSecret: "whsec_…",
+                                    },
+                                    "http-trigger_advanced_raw": {
+                                        _note: "Skip the preset for full manual control — useful for non-standard schemes the built-in providers don't cover. Every field maps 1:1 to the runtime SignatureMetadata interface.",
+                                        path: "custom-webhook",
+                                        validateSignature: true,
+                                        signingSecret: "whsec_…",
+                                        signatureHeaderName: "x-custom-signature",
+                                        timestampHeaderName: "x-custom-timestamp",
+                                        extractionPattern: "^v1,(.+)$",
+                                        hmacAlgorithm: "sha256",
+                                        hmacEncoding: "base64",
+                                        secretEncoding: "prefixed-base64",
+                                    },
+                                    endpoint_provider_shortcut: {
+                                        _note: "Provider-named endpoint auth mode + colocated secret. Equivalent to mode: 'hmac' + triggerMetadata.provider — the service layer normalises auth.secret onto triggerMetadata.signingSecret at create/update time.",
+                                        path: "stripe-events",
+                                        allowedMethods: ["POST"],
+                                        auth: { mode: "stripe", secret: "whsec_…" },
+                                    },
                                     endpoint: { path: "create-order", allowedMethods: ["POST"], timeoutMs: 10000, auth: { mode: "bearer" } },
                                 },
                             },
@@ -985,30 +1012,84 @@ function registerDescribeTools(server) {
             ],
         });
     }));
-    // ── Smart Queries ──────────────────────────────────────────────────
-    (0, _register_js_1.registerTool)(server, "describe_smart_queries", "Get the schema reference for Centrali saved (a.k.a. smart) queries. Explains the canonical QueryDefinition body, variable substitution, and execution.", {}, () => __awaiter(this, void 0, void 0, function* () {
+    // ── Saved Queries ──────────────────────────────────────────────────
+    (0, _register_js_1.registerTool)(server, "describe_saved_queries", "Get the schema reference for Centrali saved queries. Explains the canonical QueryDefinition body, variable substitution, and execution.", {}, () => __awaiter(this, void 0, void 0, function* () {
         return ({
             content: [
                 {
                     type: "text",
                     text: JSON.stringify({
-                        domain: "Saved Queries (a.k.a. Smart Queries)",
-                        description: "Saved queries are reusable, parameterized queries defined in the Centrali console. They store a canonical QueryDefinition plus optional variable declarations and are executed under the caller's permissions. Tool names retain the `_smart_query` suffix for backwards compatibility.",
+                        domain: "Saved Queries",
+                        description: "Saved queries are reusable, parameterized queries defined in the Centrali console. They store a canonical QueryDefinition plus optional typed variable declarations and follow SECURITY DEFINER auth — the AUTHOR's permissions define what the query can read; the executor only needs an 'execute' check on the saved-query resource.",
                         saved_query_shape: {
                             id: "UUID",
                             name: "string — display name",
                             recordSlug: "string — the collection this query targets",
                             description: "string | null",
-                            queryDefinition: "object — canonical QueryDefinition (without 'resource' — filled in from recordSlug). Variables are referenced as '{{varName}}' placeholders inside operator values; the engine infers them from the body.",
+                            queryDefinition: "object — canonical QueryDefinition (without 'resource' — filled in from recordSlug). Supports 'where', 'sort', 'page', 'select', and a multi-collection 'joins[]' clause (max 4). 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. Variables are referenced as '${varName}' placeholders inside operator values.",
+                            variables: "Record<string, QueryVariableDefinition> | null — typed parameter declarations. Present on Phase 4 saved queries; null/absent on legacy untyped rows. See 'variable_declarations' below.",
+                        },
+                        query_definition_reference: "Use describe_records for the full QueryDefinition shape, operator vocabulary, and examples. Saved queries support 'where', 'sort', 'page', 'select', and a multi-collection 'joins[]' clause (see 'joins' below). Saved queries do NOT support 'text' or 'include' on this surface — those land on ad-hoc 'POST /records/query'.",
+                        joins: {
+                            description: "Multi-collection joins. Saved queries may include up to 4 joined collections (JOINS_MAX_LENGTH = 4). Each side is sourced from a tenancy-filtered subquery before the join, so wrong-tenant rows can never participate. Combining 'text' and 'joins' is rejected with 'unsupported_combination'; combining 'include' and 'joins' is also rejected with 'unsupported_combination'.",
+                            cap: 4,
+                            join_clause_shape: {
+                                foreignSlug: "string — the joined collection's record slug. LITERAL ONLY: '${var}' placeholders rejected (identifiers must be literal under SECURITY DEFINER auth).",
+                                localField: "string — field on primary; bare names ('id') target top-level columns, dotted ('data.customerId') targets JSONB. Chained joins may use '<priorAlias>.<field>' to reference a prior join's row. LITERAL ONLY: no '${var}' placeholders.",
+                                foreignField: "string — field on the joined collection (same dotted-vs-bare rules as localField). LITERAL ONLY: no '${var}' placeholders.",
+                                joinType: "'inner' | 'left' | 'right' | 'full' — required, no default. INNER and LEFT are always available. RIGHT and FULL OUTER are gated server-side by the 'DATA_QUERY_OUTER_JOINS_ENABLED' env flag; when off the executor returns 'unsupported_clause'. LITERAL ONLY: no '${var}' placeholders.",
+                                select: "string[] (optional) — projection on the joined row; defaults to all readable fields",
+                                alias: "string (optional) — logical alias used in '_joined[alias]' on response rows and as the 'priorAlias' for chained joins. Defaults to foreignSlug. REQUIRED when joining the same foreignSlug more than once in the same query. Must NOT equal the primary 'resource' or '_joined' (validator rejects with 'duplicate_join_alias'). LITERAL ONLY: no '${var}' placeholders.",
+                            },
+                            authorization: "SECURITY DEFINER (author-bound). Saved queries follow the SQL-view pattern — the AUTHOR's permissions define what the query can read; the executor only needs an 'execute' check on the saved-query resource at runtime. At AUTHOR time (create / update / test) the caller needs 'records:list' on the primary collection AND every collection referenced in 'joins[]'; the data service returns 403 if any access is missing. At EXECUTE time there is no per-collection re-check, and field-level redaction follows the author's permissions, not the executor's. AI assistants should not propose joined queries against collections the user can't read.",
+                            error_codes: [
+                                "joins_length_exceeded — more than 4 join entries",
+                                "duplicate_join_alias — same alias appears twice, OR alias equals primary 'resource', OR alias equals reserved '_joined'",
+                                "unsupported_combination — 'text' + 'joins', or 'include' + 'joins'",
+                                "unsupported_clause — joinType is 'right' or 'full' and 'DATA_QUERY_OUTER_JOINS_ENABLED' is off",
+                                "invalid_query — '${var}' placeholder in any identifier slot (foreignSlug / localField / foreignField / alias / joinType)",
+                            ],
+                            response_shape: "execute_saved_query returns '{ rows, meta, fields }'. Each entry in 'rows' carries '_joined': { [alias]: <joinedRow> | null } at the top level. LEFT and FULL joins surface 'null' for the joined alias when there is no match (phantom-foreign). RIGHT and FULL joins additionally surface PHANTOM-PRIMARY rows where the primary side has no match — every primary column ('id', 'data', 'createdAt', ...) is null and the joined alias carries the unmatched-foreign data. Consumers detect phantom rows by 'rows[i].id === null'.",
+                            example: {
+                                resource: "orders",
+                                where: { "data.status": { eq: "open" } },
+                                joins: [
+                                    {
+                                        foreignSlug: "customers",
+                                        localField: "data.customerId",
+                                        foreignField: "id",
+                                        joinType: "left",
+                                        select: ["id", "data.name", "data.email"],
+                                        alias: "customer",
+                                    },
+                                    {
+                                        foreignSlug: "regions",
+                                        localField: "customer.data.regionId",
+                                        foreignField: "id",
+                                        joinType: "inner",
+                                        alias: "region",
+                                    },
+                                ],
+                                sort: [{ field: "createdAt", direction: "desc" }],
+                                page: { limit: 50 },
+                            },
+                            example_response_row: {
+                                id: "order-123",
+                                data: { status: "open", amount: 99.99 },
+                                createdAt: "2026-04-01T00:00:00Z",
+                                _joined: {
+                                    customer: { id: "cust-1", data: { name: "Acme", email: "a@b.co" } },
+                                    region: { id: "reg-1", data: { code: "us-east" } },
+                                },
+                            },
                         },
-                        query_definition_reference: "Use describe_records for the full QueryDefinition shape, operator vocabulary, and examples.",
                         variable_syntax: {
-                            description: "Variables use double-brace syntax: '{{variableName}}'. They appear inside operator values; the engine infers the variable list from the body and resolves substitutions at execution time. There is no separate variable declaration — placeholders in the QueryDefinition are the source of truth.",
+                            description: "Phase 4 canonical syntax: '${variableName}'. Placeholders appear inside operator values; the server resolves substitutions and (when the row carries 'variables' declarations) validates each value against its declared type by JS typeof — there is no server-side coercion, so '\"123\"' is rejected for a 'number' declaration. 'datetime' accepts an ISO-8601 string. Legacy '{{varName}}' placeholders still work on pre-Phase-4 untyped rows during the deprecation window — every value is stringified before substitution. New saved queries should declare typed 'variables' and use '${varName}'.",
                             example_query_definition: {
                                 where: {
                                     and: [
-                                        { "data.status": { eq: "{{statusFilter}}" } },
-                                        { "data.amount": { gte: "{{minAmount}}" } },
+                                        { "data.status": { eq: "${statusFilter}" } },
+                                        { "data.amount": { gte: "${minAmount}" } },
                                     ],
                                 },
                                 sort: [{ field: "createdAt", direction: "desc" }],
@@ -1018,45 +1099,67 @@ function registerDescribeTools(server) {
                                 statusFilter: "active",
                                 minAmount: 1000,
                             },
-                            note: "Pass values via the 'variables' arg on execute_smart_query / test_smart_query. Values are substituted before the engine validates the query.",
+                            note: "Pass values via the 'variables' arg on execute_saved_query — the server validates against the saved query's declarations by JS typeof (no coercion; typed errors: 'variable_type_mismatch', 'missing_required_variable', 'extra_variable'). test_saved_query is unwired for typed dry-run today: it falls back to legacy string substitution and does not enforce typed declarations. Round-trip via create_saved_query + execute_saved_query for typed validation.",
+                        },
+                        variable_declarations: {
+                            description: "Each entry in the saved query's 'variables' map declares a typed parameter slot. Authors set this on create_saved_query / update_saved_query; the executor uses it to validate runtime values by JS typeof (no coercion).",
+                            shape: {
+                                type: "VariableType — 'string' | 'number' | 'boolean' | 'datetime' | 'id' | { array: VariableType } | { reference: '<collectionSlug>' }",
+                                required: "boolean (optional) — when true, the value must be supplied at execute time (or a 'default' must be set)",
+                                default: "scalar (optional) — used when the caller omits the value",
+                                description: "string (optional) — surfaced in tool descriptions and AI prompts",
+                            },
+                            example: {
+                                statusFilter: { type: "string", required: true, description: "Order status to filter by" },
+                                minAmount: { type: "number", default: 0 },
+                                since: { type: "datetime", required: true },
+                                customerIds: { type: { array: "id" } },
+                                ownerRef: { type: { reference: "users" } },
+                            },
+                            clearing_declarations: "Pass 'variables: null' on update_saved_query to clear declarations and revert the query to untyped string substitution.",
                         },
                         crud_tools: {
-                            get_smart_query: {
-                                description: "Get a saved query by ID, including its full canonical definition",
+                            get_saved_query: {
+                                description: "Get a saved query by ID, including its full canonical definition and typed 'variables' declarations.",
                                 required_params: ["recordSlug", "queryId"],
                             },
-                            create_smart_query: {
-                                description: "Create a new saved query for a collection",
+                            create_saved_query: {
+                                description: "Create a new saved query for a collection. When 'variables' is provided, the canonical create path is used and every '${var}' in queryDefinition must be declared.",
                                 required_params: ["recordSlug", "name", "queryDefinition"],
-                                optional_params: ["description"],
+                                optional_params: ["description", "variables"],
                                 queryDefinition_example: {
-                                    where: { "data.status": { eq: "active" } },
+                                    where: { "data.status": { eq: "${statusFilter}" } },
                                     sort: [{ field: "createdAt", direction: "desc" }],
                                     page: { limit: 100 },
                                 },
+                                variables_example: {
+                                    statusFilter: { type: "string", required: true },
+                                },
                             },
-                            update_smart_query: {
-                                description: "Update an existing saved query. Partial updates supported.",
+                            update_saved_query: {
+                                description: "Update an existing saved query. Partial updates supported. Pass 'variables: null' to clear typed declarations.",
                                 required_params: ["recordSlug", "queryId"],
-                                optional_params: ["name", "description", "queryDefinition"],
+                                optional_params: ["name", "description", "queryDefinition", "variables"],
                             },
-                            delete_smart_query: {
+                            delete_saved_query: {
                                 description: "Delete a saved query by ID",
                                 required_params: ["recordSlug", "queryId"],
                             },
-                            test_smart_query: {
-                                description: "Test execute a canonical query definition without saving it. Preview results before creating.",
+                            test_saved_query: {
+                                description: "Test execute a canonical query definition without saving it. Note: typed 'variableDeclarations' dry-run is not yet wired on the server — use create_saved_query + execute_saved_query to validate typed parameters end-to-end.",
                                 required_params: ["recordSlug", "queryDefinition"],
                                 optional_params: ["variables"],
                             },
                         },
                         tips: [
-                            "Use list_smart_queries to discover available queries (optionally filter by collection slug)",
-                            "Saved queries return the same canonical { data, meta } envelope as query_records",
-                            "Variables are declared when creating the query — read the query's 'variables' field to see what's expected",
+                            "Use list_saved_queries to discover available queries (optionally filter by collection slug); each row's 'variables' field tells you what to pass",
+                            "execute_saved_query returns a { rows, meta, fields } envelope; joined data lives under 'rows[i]._joined' (LEFT/FULL surface 'null' under unmatched aliases; RIGHT/FULL also surface phantom-primary rows where rows[i].id === null and the joined alias carries the foreign-side data). The ad-hoc query_records tool returns the canonical { data, meta } shape — they are not interchangeable",
+                            "Read the saved query's 'variables' map for type, required-ness, default, and description before calling execute_saved_query",
                             "Prefer saved queries over ad-hoc query_records filters for reusable logic",
-                            "Use test_smart_query to validate canonical syntax and preview results before saving",
-                            "DO NOT author new saved queries with legacy '$'-prefixed operators ('$eq', '$gte', …). The data service still translates them server-side during the deprecation window, but new saved queries must use canonical operators ('eq', 'gte', …)",
+                            "test_saved_query previews canonical syntax + result rows but does not yet enforce typed declarations server-side — round-trip via create + execute_saved_query for typed validation",
+                            "DO NOT author new saved queries with legacy '$'-prefixed operators ('$eq', '$gte', …) or '{{var}}' placeholders. Both still translate during the deprecation window, but new saved queries must use canonical operators ('eq', 'gte', …) and '${var}' placeholders.",
+                            "For multi-collection reporting, use 'joins[]' (see top-level 'joins' field) — up to 4 joined collections; joinType is 'inner' | 'left' | 'right' | 'full' (RIGHT/FULL gated server-side by 'DATA_QUERY_OUTER_JOINS_ENABLED' — coordinate with ops if you need them). Joined rows arrive under '_joined[alias]' on each primary row. Identifiers ('foreignSlug', 'localField', 'foreignField', 'alias', 'joinType') are literal-only — no '${var}' placeholders. 'text' and 'joins' cannot be combined; 'include' and 'joins' cannot be combined either.",
+                            "Before authoring a join, confirm the user has 'records:list' on every joined collection — saved queries run under SECURITY DEFINER and the data service enforces author-time auth on the primary + every join.",
                         ],
                     }, null, 2),
                 },
@@ -1540,12 +1643,12 @@ function registerDescribeTools(server) {
                             "Set access policy with set_page_access_policy before publishing if you need auth",
                             "Use variable bindings on data sources to scope data dynamically — bind to URL params, auth context, record context, or static defaults",
                             "For list→detail navigation: set useQueryParams:true on navigate-to-page actions, then bind the detail page's data source variables to { source: 'url', param: 'id' }. Use config.paramMapping to rename fields if source and target use different names (e.g., { requestId: 'id' })",
-                            "For user-scoped views (e.g., My Approvals): bind a variable to { source: 'auth', field: 'userId' } and use a smart query with {{assigneeId}}",
+                            "For user-scoped views (e.g., My Approvals): bind a variable to { source: 'auth', field: 'userId' } and use a smart query with '${assigneeId}'",
                         ],
                         multi_page_pattern: {
                             description: "How to build a list→detail app with scoped related data",
                             steps: [
-                                "1. Create a smart query with {{variables}} for the detail page's related data (e.g., filter by {{requestId}})",
+                                "1. Create a smart query with '${variables}' for the detail page's related data (e.g., filter by '${requestId}')",
                                 "2. Create a list page with a data-table block and a navigate-to-page action: set config.useQueryParams:true, paramConfig: { source:'row', mode:'selected', selectedFields:['id'] }",
                                 "3. Create a detail page with: (a) a record-card block with mode:'single' and variables: { id: { source:'url', param:'id' } }, (b) a related-list block with dataSource type:'query', ref:smartQueryId, variables: { requestId: { source:'url', param:'id' } }",
                                 "4. Publish both pages. Clicking a row on the list navigates to /ws/detail-slug?id=rowId, and the detail page scopes all blocks to that ID.",
@@ -1617,7 +1720,7 @@ function registerDescribeTools(server) {
                             filterableColumns: "string[] | null — which columns users can filter on (for data-table blocks)",
                         },
                         data_source_shape: {
-                            type: "'structure' | 'query' — 'structure' fetches collection records directly, 'query' executes a smart query with {{variable}} substitution",
+                            type: "'structure' | 'query' — 'structure' fetches collection records directly, 'query' executes a smart query with '${variable}' substitution",
                             ref: "string — the collection ID (for structure) or smart query ID (for query) — UUID",
                             mode: "'list' | 'single' | 'aggregate' — optional. 'single' fetches one record (detail pages), 'list' fetches paginated records, 'aggregate' computes metrics",
                             recordSlug: "string | undefined — the collection's record slug for direct resolution (avoids an extra lookup). Recommended for structure type.",
@@ -1638,7 +1741,7 @@ function registerDescribeTools(server) {
                                     static: "{ source: 'static', value: 'literalValue' } — a hardcoded default",
                                 },
                                 behavior: {
-                                    query_type: "For type:'query' — resolved variables substitute into smart query {{placeholders}} before execution",
+                                    query_type: "For type:'query' — resolved variables substitute into smart query '${placeholders}' before execution",
                                     structure_type: "For type:'structure' — resolved variables become equality filters on the collection. IMPORTANT: the variable name 'id' is special — it matches the system record UUID (used for single-record fetch by ID). ALL OTHER variable names filter against user data fields and are automatically prefixed with 'data.' (e.g., variable 'requestId' filters on data.requestId in the JSONB column). System columns like createdAt, updatedAt, status do NOT get the data. prefix.",
                                     unresolved: "If any variable cannot be resolved, the block returns an empty result with a variableError message — NEVER unfiltered data",
                                     detail_page_pattern: "For a detail page: use variables: { id: { source: 'url', param: 'id' } } on the primary record-card block to fetch by system ID. For related-list blocks, use the actual data field name (e.g., variables: { requestId: { source: 'url', param: 'id' } }) — this filters related records where data.requestId matches the URL param. The 'id' variable fetches a record BY its UUID; other variable names filter records WHERE a field equals the value.",

package/dist/tools/records.d.ts

@@ -29,10 +29,29 @@ declare function translateQueryRecordsArgs(args: QueryRecordsArgs): {
     resource: string;
     definition: Record<string, unknown>;
 };
+/**
+ * Client-side `${var}` substitution for ad-hoc `query_records`. MCP agents
+ * often template queries (e.g. `${userId}` from prior tool output) — this
+ * helper resolves those placeholders before sending the body to the
+ * canonical `/records/query` endpoint, which has no native variable
+ * substitution.
+ *
+ * Behavior:
+ *   - Replaces every `${name}` occurrence inside string values.
+ *   - When the entire string is a single placeholder (e.g. `"${ids}"`), the
+ *     value is replaced with the typed value as-is so arrays / numbers /
+ *     booleans round-trip without being stringified.
+ *   - Throws `Error("missing_required_variable: <name>")` when a placeholder
+ *     references a variable that wasn't supplied — the caller surfaces the
+ *     same code the executor uses for typed saved queries (contract §10).
+ *   - Walks objects + arrays recursively; leaves non-strings untouched.
+ */
+declare function substituteCanonicalVariables(node: unknown, values: Record<string, unknown>): unknown;
 export declare const _internal: {
     translateQueryRecordsArgs: typeof translateQueryRecordsArgs;
     parseLegacyFilters: typeof parseLegacyFilters;
     parseLegacySort: typeof parseLegacySort;
+    substituteCanonicalVariables: typeof substituteCanonicalVariables;
 };
 export declare function registerRecordTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string): void;
 export {};