@centrali-io/centrali-mcp 5.5.0 → 6.0.0

package/src/tools/describe.ts

@@ -91,16 +91,16 @@ export function registerDescribeTools(server: McpServer) {
                 },
                 smart_queries: {
                   summary:
-                    "Reusable, parameterized queries defined in the console. Support {{variable}} substitution.",
-                  describeWith: "describe_smart_queries",
+                    "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: {
@@ -1061,11 +1061,11 @@ export function registerDescribeTools(server: McpServer) {
     })
   );
 
-  // ── Smart Queries ──────────────────────────────────────────────────
+  // ── Saved Queries ──────────────────────────────────────────────────
 
   registerTool<any>(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.",
+    "describe_saved_queries",
+    "Get the schema reference for Centrali saved queries. Explains the canonical QueryDefinition body, variable substitution, and execution.",
     {},
     async () => ({
       content: [
@@ -1073,27 +1073,91 @@ export function registerDescribeTools(server: McpServer) {
           type: "text",
           text: JSON.stringify(
             {
-              domain: "Saved Queries (a.k.a. Smart Queries)",
+              domain: "Saved 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.",
+                "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.",
+                  "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.",
+                "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" } },
+                  },
+                },
+              },
               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.",
+                  "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" }],
@@ -1103,45 +1167,70 @@ export function registerDescribeTools(server: McpServer) {
                   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,
@@ -1714,12 +1803,12 @@ export function registerDescribeTools(server: McpServer) {
                 "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.",
@@ -1816,7 +1905,7 @@ export function registerDescribeTools(server: McpServer) {
                   "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.",
@@ -1837,7 +1926,7 @@ export function registerDescribeTools(server: McpServer) {
                     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/src/tools/records.ts

@@ -182,8 +182,66 @@ function translateQueryRecordsArgs(args: QueryRecordsArgs): {
   return { resource, definition };
 }
 
+/**
+ * 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.
+ */
+function substituteCanonicalVariables(
+  node: unknown,
+  values: Record<string, unknown>
+): unknown {
+  if (node == null) return node;
+  if (typeof node === "string") {
+    const wholeRe = /^\s*\$\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\s*$/;
+    const wholeMatch = node.match(wholeRe);
+    if (wholeMatch) {
+      const name = wholeMatch[1];
+      if (!(name in values)) {
+        throw new Error(`missing_required_variable: ${name}`);
+      }
+      return values[name];
+    }
+    return node.replace(/\$\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}/g, (_match, name: string) => {
+      if (!(name in values)) {
+        throw new Error(`missing_required_variable: ${name}`);
+      }
+      const v = values[name];
+      return v == null ? "" : String(v);
+    });
+  }
+  if (Array.isArray(node)) {
+    return node.map((item) => substituteCanonicalVariables(item, values));
+  }
+  if (typeof node === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+      out[k] = substituteCanonicalVariables(v, values);
+    }
+    return out;
+  }
+  return node;
+}
+
 // Exposed for tests
-export const _internal = { translateQueryRecordsArgs, parseLegacyFilters, parseLegacySort };
+export const _internal = {
+  translateQueryRecordsArgs,
+  parseLegacyFilters,
+  parseLegacySort,
+  substituteCanonicalVariables,
+};
 /**
  * Ensures the SDK has a valid token.
  */
@@ -261,6 +319,8 @@ Example body:
     "select": { "fields": ["id", "data.status", "data.amount"] }
   }
 
+Templating: any string operator value may reference '\${variableName}' placeholders; pass concrete values via the 'variables' arg and the placeholders are substituted before the query hits the engine. When a string is exactly one placeholder ('\${ids}'), the value passes through untyped (so arrays / numbers / booleans round-trip without stringification).
+
 Returns the canonical { data, meta } envelope. 'select', 'text', and 'include' are all accepted by the engine.`,
     {
       // Canonical fields (Phase 1)
@@ -301,9 +361,22 @@ Returns the canonical { data, meta } envelope. 'select', 'text', and 'include' a
         .optional()
         .describe("Field projection. Example: { fields: ['id', 'data.status'] }."),
       include: z
-        .array(z.object({ relation: z.string() }))
+        .array(
+          z
+            .object({
+              relation: z.string(),
+              where: z.any().optional(),
+              select: z
+                .object({ fields: z.array(z.string()) })
+                .optional(),
+              include: z.any().optional(),
+            })
+            .passthrough(),
+        )
         .optional()
-        .describe("Relation expansion. Each entry names a relation declared on the collection."),
+        .describe(
+          "Relation expansion. Each entry names a relation declared on the collection and may carry an optional `where` (filter on the included rows in the target's namespace), `select` (projection on the attached row), and recursive `include` children."
+        ),
 
       // Legacy 5.4.0 fields — accepted, translated to canonical, removed after 2026-10-28
       recordSlug: z
@@ -342,13 +415,25 @@ Returns the canonical { data, meta } envelope. 'select', 'text', and 'include' a
         .boolean()
         .optional()
         .describe("[Deprecated 2026-10-28] Ignored — `meta.total` is always returned for offset pagination."),
+
+      // Templating
+      variables: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe(
+          "Values bound to '\${varName}' placeholders inside string operator values. Substituted client-side before the query hits the engine. Whole-string placeholders ('\${ids}') round-trip the typed value without stringification."
+        ),
     },
     async (args) => {
       let resource = "<unknown>";
       try {
-        const translated = translateQueryRecordsArgs(args as QueryRecordsArgs);
+        const { variables, ...rest } = args as QueryRecordsArgs & { variables?: Record<string, unknown> };
+        const translated = translateQueryRecordsArgs(rest as QueryRecordsArgs);
         resource = translated.resource;
-        const result = await sdk.records.query(resource, translated.definition as any);
+        const finalDefinition = variables
+          ? (substituteCanonicalVariables(translated.definition, variables) as Record<string, unknown>)
+          : translated.definition;
+        const result = await sdk.records.query(resource, finalDefinition as any);
         return {
           content: [
             { type: "text", text: JSON.stringify(result, null, 2) },