@centrali-io/centrali-mcp 5.3.0 → 5.5.0

package/src/tools/smart-queries.ts

@@ -2,23 +2,42 @@ 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 below stay as `*_smart_query` to keep existing AI assistant
+// configurations working — renaming would break public clients. Internally
+// they route through `sdk.savedQueries.*` (the canonical namespace) and
+// accept canonical query bodies.
+
+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'.
+
+Variables are referenced as '{{varName}}' inside operator values; the engine infers the variable list from the placeholders in the body. Callers pass concrete values via the 'variables' arg on execute_smart_query / test_smart_query. Example:
+  {
+    "where": { "data.status": { "eq": "{{statusFilter}}" } },
+    "sort": [{ "field": "createdAt", "direction": "desc" }],
+    "page": { "limit": 100 }
+  }
+
+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.`;
+
 export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "list_smart_queries",
-    "List smart queries. Smart queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by collection record slug.",
+    "List saved (a.k.a. smart) queries. Saved queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by collection record slug.",
     {
       recordSlug: z
         .string()
         .optional()
         .describe(
-          "Filter by collection record slug. If omitted, lists all smart queries in the workspace"
+          "Filter by collection record slug. If omitted, lists all saved queries in the workspace"
         ),
     },
     async ({ recordSlug }) => {
       try {
         const result = recordSlug
-          ? await sdk.smartQueries.list(recordSlug)
-          : await sdk.smartQueries.listAll();
+          ? await sdk.savedQueries.list(recordSlug)
+          : await sdk.savedQueries.listAll();
         return {
           content: [
             { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -29,7 +48,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
           content: [
             {
               type: "text",
-              text: formatError(error, "listing smart queries"),
+              text: formatError(error, "listing saved queries"),
             },
           ],
           isError: true,
@@ -38,25 +57,25 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "execute_smart_query",
-    "Execute a smart query by ID and return the results. Smart queries can have parameterized variables using {{variableName}} syntax.",
+    "Execute a saved query by ID and return the canonical { data, meta } envelope. Saved queries can declare variables referenced as '{{varName}}' inside operator values.",
     {
       recordSlug: z
         .string()
         .describe("The collection's record slug the query belongs to"),
-      queryId: z.string().describe("The smart query ID (UUID) to execute"),
+      queryId: z.string().describe("The saved query ID (UUID) to execute"),
       variables: z
-        .record(z.string(), z.string())
+        .record(z.string(), z.any())
         .optional()
         .describe(
-          "Variables to substitute in the query (key-value pairs matching {{variableName}} placeholders)"
+          "Variables to substitute (key-value pairs matching '{{varName}}' placeholders). Values must match the variable's declared type."
         ),
     },
     async ({ recordSlug, queryId, variables }) => {
       try {
         const options = variables ? { variables } : undefined;
-        const result = await sdk.smartQueries.execute(
+        const result = await sdk.savedQueries.execute(
           recordSlug,
           queryId,
           options
@@ -71,7 +90,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
           content: [
             {
               type: "text",
-              text: formatError(error, `executing smart query '${queryId}'`),
+              text: formatError(error, `executing saved query '${queryId}'`),
             },
           ],
           isError: true,
@@ -80,16 +99,16 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "get_smart_query",
-    "Get a smart query by ID. Returns the full query definition including filters, sort, and variable declarations.",
+    "Get a saved query by ID. Returns the full query definition including canonical 'where', 'sort', 'page', 'select', and variable declarations.",
     {
       recordSlug: z.string().describe("The collection's record slug the query belongs to"),
-      queryId: z.string().describe("The smart query ID (UUID)"),
+      queryId: z.string().describe("The saved query ID (UUID)"),
     },
     async ({ recordSlug, queryId }) => {
       try {
-        const result = await sdk.smartQueries.get(recordSlug, queryId);
+        const result = await sdk.savedQueries.get(recordSlug, queryId);
         return {
           content: [
             { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -100,7 +119,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
           content: [
             {
               type: "text",
-              text: formatError(error, `getting smart query '${queryId}'`),
+              text: formatError(error, `getting saved query '${queryId}'`),
             },
           ],
           isError: true,
@@ -109,23 +128,27 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "create_smart_query",
-    "Create a new smart query for a collection. Smart queries are reusable, parameterized queries with filter, sort, and variable support.",
+    `Create a new saved query for a collection.
+
+${CANONICAL_QUERY_DEFINITION_HINT}`,
     {
       recordSlug: z.string().describe("The collection's record slug to create the query for"),
-      name: z.string().describe("Display name for the smart query"),
+      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("The query definition object with where, sort, limit, select, join, etc."),
+        .describe(
+          "Canonical inner QueryDefinition (without 'resource'). Use 'where', 'text', 'sort', 'page', 'select'. Variables are inferred from '{{varName}}' placeholders inside operator values."
+        ),
     },
     async ({ recordSlug, name, description, queryDefinition }) => {
       try {
         const input: Record<string, any> = { name, queryDefinition };
         if (description !== undefined) input.description = description;
 
-        const result = await sdk.smartQueries.create(recordSlug, input as any);
+        const result = await sdk.savedQueries.create(recordSlug, input as any);
         return {
           content: [
             { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -136,7 +159,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
           content: [
             {
               type: "text",
-              text: formatError(error, `creating smart query '${name}' for '${recordSlug}'`),
+              text: formatError(error, `creating saved query '${name}' for '${recordSlug}'`),
             },
           ],
           isError: true,
@@ -145,18 +168,20 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "update_smart_query",
-    "Update an existing smart query. Only include the fields you want to change.",
+    `Update an existing saved query. Only include the fields you want to change.
+
+${CANONICAL_QUERY_DEFINITION_HINT}`,
     {
       recordSlug: z.string().describe("The collection's record slug the query belongs to"),
-      queryId: z.string().describe("The smart query ID (UUID) to update"),
+      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 query definition object"),
+        .describe("Updated canonical inner QueryDefinition (without 'resource')."),
     },
     async ({ recordSlug, queryId, name, description, queryDefinition }) => {
       try {
@@ -165,7 +190,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
         if (description !== undefined) input.description = description;
         if (queryDefinition !== undefined) input.queryDefinition = queryDefinition;
 
-        const result = await sdk.smartQueries.update(recordSlug, queryId, input as any);
+        const result = await sdk.savedQueries.update(recordSlug, queryId, input as any);
         return {
           content: [
             { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -176,7 +201,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
           content: [
             {
               type: "text",
-              text: formatError(error, `updating smart query '${queryId}'`),
+              text: formatError(error, `updating saved query '${queryId}'`),
             },
           ],
           isError: true,
@@ -185,21 +210,21 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "delete_smart_query",
-    "Delete a smart query by ID.",
+    "Delete a saved query by ID.",
     {
       recordSlug: z.string().describe("The collection's record slug the query belongs to"),
-      queryId: z.string().describe("The smart query ID (UUID) to delete"),
+      queryId: z.string().describe("The saved query ID (UUID) to delete"),
     },
     async ({ recordSlug, queryId }) => {
       try {
-        await sdk.smartQueries.delete(recordSlug, queryId);
+        await sdk.savedQueries.delete(recordSlug, queryId);
         return {
           content: [
             {
               type: "text",
-              text: `Smart query '${queryId}' deleted from '${recordSlug}'.`,
+              text: `Saved query '${queryId}' deleted from '${recordSlug}'.`,
             },
           ],
         };
@@ -208,7 +233,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
           content: [
             {
               type: "text",
-              text: formatError(error, `deleting smart query '${queryId}'`),
+              text: formatError(error, `deleting saved query '${queryId}'`),
             },
           ],
           isError: true,
@@ -217,25 +242,27 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "test_smart_query",
-    "Test execute a query definition without saving it. Useful for validating query syntax and previewing results before creating a smart query.",
+    `Test execute a query definition without saving it. Useful for validating syntax and previewing results before creating a saved query.
+
+${CANONICAL_QUERY_DEFINITION_HINT}`,
     {
       recordSlug: z.string().describe("The collection's record slug to test against"),
       queryDefinition: z
         .record(z.string(), z.any())
-        .describe("The query definition to test (where, sort, limit, select, etc.)"),
+        .describe("Canonical inner QueryDefinition to test (without 'resource')."),
       variables: z
-        .record(z.string(), z.string())
+        .record(z.string(), z.any())
         .optional()
-        .describe("Optional variables to substitute in the query"),
+        .describe("Optional variables to substitute."),
     },
     async ({ recordSlug, queryDefinition, variables }) => {
       try {
         const input: Record<string, any> = { queryDefinition };
         if (variables !== undefined) input.variables = variables;
 
-        const result = await sdk.smartQueries.test(recordSlug, input as any);
+        const result = await sdk.savedQueries.test(recordSlug, input as any);
         return {
           content: [
             { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -246,7 +273,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
           content: [
             {
               type: "text",
-              text: formatError(error, `test-executing smart query for '${recordSlug}'`),
+              text: formatError(error, `test-executing saved query for '${recordSlug}'`),
             },
           ],
           isError: true,

package/tests/records.translator.test.cjs

@@ -0,0 +1,177 @@
+/**
+ * Legacy 5.4.0 → canonical translator tests for `query_records`.
+ *
+ * Runs against the built `dist/` so we exercise the same module the published
+ * package ships. Uses Node's built-in `node:test` runner — no jest/ts-node
+ * needed. Wire via `npm test` (`tsc && node --test tests/`).
+ */
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { _internal } = require("../dist/tools/records.js");
+
+const { translateQueryRecordsArgs, parseLegacyFilters, parseLegacySort } = _internal;
+
+test("canonical args pass through unchanged", () => {
+    const out = translateQueryRecordsArgs({
+        resource: "orders",
+        where: { "data.status": { eq: "open" } },
+        page: { limit: 50 },
+    });
+    assert.deepEqual(out, {
+        resource: "orders",
+        definition: {
+            resource: "orders",
+            where: { "data.status": { eq: "open" } },
+            page: { limit: 50 },
+        },
+    });
+});
+
+test("full 5.4.0 legacy shape translates", () => {
+    const out = translateQueryRecordsArgs({
+        recordSlug: "orders",
+        filters: { "data.status": "open", "data.price[gte]": 100 },
+        sort: "-createdAt",
+        pageSize: 50,
+        page: 2,
+    });
+    assert.deepEqual(out, {
+        resource: "orders",
+        definition: {
+            resource: "orders",
+            where: {
+                and: [
+                    { "data.status": { eq: "open" } },
+                    { "data.price": { gte: 100 } },
+                ],
+            },
+            sort: [{ field: "createdAt", direction: "desc" }],
+            page: { limit: 50, offset: 50 },
+        },
+    });
+});
+
+test("filters: $-prefixed operator alias", () => {
+    const out = translateQueryRecordsArgs({
+        recordSlug: "orders",
+        filters: { "data.amount[$gte]": 100 },
+    });
+    assert.deepEqual(out.definition.where, { "data.amount": { gte: 100 } });
+});
+
+test("filters: single condition omits 'and' wrapping", () => {
+    const out = translateQueryRecordsArgs({
+        recordSlug: "orders",
+        filters: { "data.status": "open" },
+    });
+    assert.deepEqual(out.definition.where, { "data.status": { eq: "open" } });
+});
+
+test("filters + canonical where merge under 'and'", () => {
+    const out = translateQueryRecordsArgs({
+        resource: "orders",
+        where: { "data.region": { eq: "us-east" } },
+        filters: { "data.status": "open" },
+    });
+    assert.deepEqual(out.definition.where, {
+        and: [
+            { "data.region": { eq: "us-east" } },
+            { "data.status": { eq: "open" } },
+        ],
+    });
+});
+
+test("dateWindow: from + to → and(gte, lte)", () => {
+    const out = translateQueryRecordsArgs({
+        recordSlug: "orders",
+        dateWindow: { field: "createdAt", from: "2026-01-01", to: "2026-04-01" },
+    });
+    assert.deepEqual(out.definition.where, {
+        and: [
+            { createdAt: { gte: "2026-01-01" } },
+            { createdAt: { lte: "2026-04-01" } },
+        ],
+    });
+});
+
+test("dateWindow: from-only → single gte (no 'and')", () => {
+    const out = translateQueryRecordsArgs({
+        recordSlug: "orders",
+        dateWindow: { field: "createdAt", from: "2026-01-01" },
+    });
+    assert.deepEqual(out.definition.where, { createdAt: { gte: "2026-01-01" } });
+});
+
+test("dateWindow: to-only → single lte (no 'and')", () => {
+    const out = translateQueryRecordsArgs({
+        recordSlug: "orders",
+        dateWindow: { field: "createdAt", to: "2026-04-01" },
+    });
+    assert.deepEqual(out.definition.where, { createdAt: { lte: "2026-04-01" } });
+});
+
+test("expand: comma-list → include array; empty → omit", () => {
+    const ok = translateQueryRecordsArgs({
+        recordSlug: "orders",
+        expand: "customer,product",
+    });
+    assert.deepEqual(ok.definition.include, [
+        { relation: "customer" },
+        { relation: "product" },
+    ]);
+
+    const empty = translateQueryRecordsArgs({ recordSlug: "orders", expand: "" });
+    assert.equal(empty.definition.include, undefined);
+
+    const allEmpty = translateQueryRecordsArgs({ recordSlug: "orders", expand: ",,," });
+    assert.equal(allEmpty.definition.include, undefined);
+});
+
+test("sort: multi-sort comma-separated mixes asc/desc", () => {
+    assert.deepEqual(parseLegacySort("name,-createdAt"), [
+        { field: "name", direction: "asc" },
+        { field: "createdAt", direction: "desc" },
+    ]);
+});
+
+test("page without pageSize defaults to limit 50", () => {
+    const out = translateQueryRecordsArgs({ recordSlug: "orders", page: 3 });
+    assert.deepEqual(out.definition.page, { limit: 50, offset: 100 });
+});
+
+test("pageSize without page → limit only", () => {
+    const out = translateQueryRecordsArgs({ recordSlug: "orders", pageSize: 25 });
+    assert.deepEqual(out.definition.page, { limit: 25 });
+});
+
+test("includeTotal silently dropped (meta.total always returned)", () => {
+    const out = translateQueryRecordsArgs({ recordSlug: "orders", includeTotal: true });
+    assert.deepEqual(out.definition, { resource: "orders" });
+});
+
+test("includeDeleted: true throws clear error (no silent privacy regression)", () => {
+    assert.throws(
+        () => translateQueryRecordsArgs({ recordSlug: "orders", includeDeleted: true }),
+        /includeDeleted.*not supported in Phase 1/,
+    );
+});
+
+test("missing both resource and recordSlug throws", () => {
+    assert.throws(
+        () => translateQueryRecordsArgs({ filters: { "data.x": 1 } }),
+        /resource.*recordSlug/,
+    );
+});
+
+test("parseLegacyFilters: hostile inputs return undefined, no crash", () => {
+    assert.equal(parseLegacyFilters(null), undefined);
+    assert.equal(parseLegacyFilters(undefined), undefined);
+    assert.equal(parseLegacyFilters([]), undefined);
+    assert.equal(parseLegacyFilters("string"), undefined);
+    assert.equal(parseLegacyFilters(42), undefined);
+});
+
+test("resource takes precedence over recordSlug", () => {
+    const out = translateQueryRecordsArgs({ resource: "canonical", recordSlug: "legacy" });
+    assert.equal(out.resource, "canonical");
+});