@centrali-io/centrali-mcp 5.5.1 → 6.0.0

package/tests/typedVariables.test.cjs

@@ -0,0 +1,113 @@
+/**
+ * Phase 4 / WS5 — typed `${var}` placeholder helpers.
+ *
+ * Covers:
+ *   - records.ts:    `substituteCanonicalVariables` (client-side templating
+ *                    for ad-hoc `query_records`).
+ *   - saved-queries.ts: `extractCanonicalVariableNames` (used in
+ *                    `execute_saved_query` for best-effort preflight).
+ */
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { _internal: recordsInternal } = require("../dist/tools/records.js");
+const { _internal: savedInternal } = require("../dist/tools/saved-queries.js");
+
+const { substituteCanonicalVariables } = recordsInternal;
+const { extractCanonicalVariableNames } = savedInternal;
+
+test("substitute: whole-string placeholder round-trips typed value", () => {
+    const out = substituteCanonicalVariables(
+        { where: { "data.tags": { in: "${tags}" } } },
+        { tags: ["red", "blue"] },
+    );
+    assert.deepEqual(out, { where: { "data.tags": { in: ["red", "blue"] } } });
+});
+
+test("substitute: mixed-string placeholder stringifies inline", () => {
+    const out = substituteCanonicalVariables(
+        { where: { "data.label": { eq: "prefix-${suffix}" } } },
+        { suffix: 42 },
+    );
+    assert.deepEqual(out, { where: { "data.label": { eq: "prefix-42" } } });
+});
+
+test("substitute: walks nested arrays and boolean trees", () => {
+    const out = substituteCanonicalVariables(
+        {
+            where: {
+                and: [
+                    { "data.status": { eq: "${status}" } },
+                    { "data.amount": { gte: "${minAmount}" } },
+                ],
+            },
+        },
+        { status: "open", minAmount: 100 },
+    );
+    assert.deepEqual(out, {
+        where: {
+            and: [
+                { "data.status": { eq: "open" } },
+                { "data.amount": { gte: 100 } },
+            ],
+        },
+    });
+});
+
+test("substitute: missing variable throws missing_required_variable", () => {
+    assert.throws(
+        () => substituteCanonicalVariables(
+            { where: { "data.id": { eq: "${recordId}" } } },
+            {},
+        ),
+        /missing_required_variable: recordId/,
+    );
+});
+
+test("substitute: leaves non-placeholder strings untouched", () => {
+    const out = substituteCanonicalVariables(
+        { where: { "data.status": { eq: "open" } } },
+        { irrelevant: "x" },
+    );
+    assert.deepEqual(out, { where: { "data.status": { eq: "open" } } });
+});
+
+test("substitute: handles null / numbers / booleans without recursion", () => {
+    const out = substituteCanonicalVariables(
+        { where: { "data.score": { gte: 0 } }, page: { limit: 50 } },
+        {},
+    );
+    assert.deepEqual(out, { where: { "data.score": { gte: 0 } }, page: { limit: 50 } });
+});
+
+test("extract: collects unique variable names across the body", () => {
+    const out = extractCanonicalVariableNames({
+        where: {
+            and: [
+                { "data.status": { eq: "${statusFilter}" } },
+                { "data.amount": { gte: "${minAmount}" } },
+                { "data.tags": { in: "${tags}" } },
+            ],
+        },
+        sort: [{ field: "${sortField}", direction: "desc" }],
+    });
+    assert.deepEqual(
+        Array.from(out).sort(),
+        ["minAmount", "sortField", "statusFilter", "tags"],
+    );
+});
+
+test("extract: ignores legacy {{var}} placeholders (Phase 4 = '${var}' only)", () => {
+    const out = extractCanonicalVariableNames({
+        where: { "data.status": { eq: "{{statusFilter}}" } },
+    });
+    assert.equal(out.size, 0);
+});
+
+test("extract: handles bodies with no placeholders", () => {
+    const out = extractCanonicalVariableNames({
+        where: { "data.status": { eq: "open" } },
+        page: { limit: 100 },
+    });
+    assert.equal(out.size, 0);
+});

package/dist/tools/smart-queries.d.ts

@@ -1,3 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CentraliSDK } from "@centrali-io/centrali-sdk";
-export declare function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK): void;

package/dist/tools/smart-queries.js

@@ -1,249 +0,0 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerSmartQueryTools = registerSmartQueryTools;
-const zod_1 = require("zod");
-const _register_js_1 = require("./_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.`;
-function registerSmartQueryTools(server, sdk) {
-    (0, _register_js_1.registerTool)(server, "list_smart_queries", "List saved (a.k.a. smart) queries. Saved queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by collection record slug.", {
-        recordSlug: zod_1.z
-            .string()
-            .optional()
-            .describe("Filter by collection record slug. If omitted, lists all saved queries in the workspace"),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug }) {
-        try {
-            const result = recordSlug
-                ? yield sdk.savedQueries.list(recordSlug)
-                : yield sdk.savedQueries.listAll();
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify(result.data, null, 2) },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: (0, _register_js_1.formatError)(error, "listing saved queries"),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }));
-    (0, _register_js_1.registerTool)(server, "execute_smart_query", "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: zod_1.z
-            .string()
-            .describe("The collection's record slug the query belongs to"),
-        queryId: zod_1.z.string().describe("The saved query ID (UUID) to execute"),
-        variables: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.any())
-            .optional()
-            .describe("Variables to substitute (key-value pairs matching '{{varName}}' placeholders). Values must match the variable's declared type."),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, queryId, variables }) {
-        try {
-            const options = variables ? { variables } : undefined;
-            const result = yield sdk.savedQueries.execute(recordSlug, queryId, options);
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify(result.data, null, 2) },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: (0, _register_js_1.formatError)(error, `executing saved query '${queryId}'`),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }));
-    (0, _register_js_1.registerTool)(server, "get_smart_query", "Get a saved query by ID. Returns the full query definition including canonical 'where', 'sort', 'page', 'select', and variable declarations.", {
-        recordSlug: zod_1.z.string().describe("The collection's record slug the query belongs to"),
-        queryId: zod_1.z.string().describe("The saved query ID (UUID)"),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, queryId }) {
-        try {
-            const result = yield sdk.savedQueries.get(recordSlug, queryId);
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify(result.data, null, 2) },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: (0, _register_js_1.formatError)(error, `getting saved query '${queryId}'`),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }));
-    (0, _register_js_1.registerTool)(server, "create_smart_query", `Create a new saved query for a collection.
-
-${CANONICAL_QUERY_DEFINITION_HINT}`, {
-        recordSlug: zod_1.z.string().describe("The collection's record slug to create the query for"),
-        name: zod_1.z.string().describe("Display name for the saved query"),
-        description: zod_1.z.string().optional().describe("Optional description"),
-        queryDefinition: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.any())
-            .describe("Canonical inner QueryDefinition (without 'resource'). Use 'where', 'text', 'sort', 'page', 'select'. Variables are inferred from '{{varName}}' placeholders inside operator values."),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, name, description, queryDefinition }) {
-        try {
-            const input = { name, queryDefinition };
-            if (description !== undefined)
-                input.description = description;
-            const result = yield sdk.savedQueries.create(recordSlug, input);
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify(result.data, null, 2) },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: (0, _register_js_1.formatError)(error, `creating saved query '${name}' for '${recordSlug}'`),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }));
-    (0, _register_js_1.registerTool)(server, "update_smart_query", `Update an existing saved query. Only include the fields you want to change.
-
-${CANONICAL_QUERY_DEFINITION_HINT}`, {
-        recordSlug: zod_1.z.string().describe("The collection's record slug the query belongs to"),
-        queryId: zod_1.z.string().describe("The saved query ID (UUID) to update"),
-        name: zod_1.z.string().optional().describe("Updated display name"),
-        description: zod_1.z.string().optional().describe("Updated description"),
-        queryDefinition: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.any())
-            .optional()
-            .describe("Updated canonical inner QueryDefinition (without 'resource')."),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, queryId, name, description, queryDefinition }) {
-        try {
-            const input = {};
-            if (name !== undefined)
-                input.name = name;
-            if (description !== undefined)
-                input.description = description;
-            if (queryDefinition !== undefined)
-                input.queryDefinition = queryDefinition;
-            const result = yield sdk.savedQueries.update(recordSlug, queryId, input);
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify(result.data, null, 2) },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: (0, _register_js_1.formatError)(error, `updating saved query '${queryId}'`),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }));
-    (0, _register_js_1.registerTool)(server, "delete_smart_query", "Delete a saved query by ID.", {
-        recordSlug: zod_1.z.string().describe("The collection's record slug the query belongs to"),
-        queryId: zod_1.z.string().describe("The saved query ID (UUID) to delete"),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, queryId }) {
-        try {
-            yield sdk.savedQueries.delete(recordSlug, queryId);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Saved query '${queryId}' deleted from '${recordSlug}'.`,
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: (0, _register_js_1.formatError)(error, `deleting saved query '${queryId}'`),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }));
-    (0, _register_js_1.registerTool)(server, "test_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: zod_1.z.string().describe("The collection's record slug to test against"),
-        queryDefinition: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.any())
-            .describe("Canonical inner QueryDefinition to test (without 'resource')."),
-        variables: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.any())
-            .optional()
-            .describe("Optional variables to substitute."),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, queryDefinition, variables }) {
-        try {
-            const input = { queryDefinition };
-            if (variables !== undefined)
-                input.variables = variables;
-            const result = yield sdk.savedQueries.test(recordSlug, input);
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify(result.data, null, 2) },
-                ],
-            };
-        }
-        catch (error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: (0, _register_js_1.formatError)(error, `test-executing saved query for '${recordSlug}'`),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }));
-}

package/src/tools/smart-queries.ts

@@ -1,284 +0,0 @@
-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,
-    "list_smart_queries",
-    "List saved (a.k.a. smart) queries. Saved queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by collection record slug.",
-    {
-      recordSlug: z
-        .string()
-        .optional()
-        .describe(
-          "Filter by collection record slug. If omitted, lists all saved queries in the workspace"
-        ),
-    },
-    async ({ recordSlug }) => {
-      try {
-        const result = recordSlug
-          ? await sdk.savedQueries.list(recordSlug)
-          : await sdk.savedQueries.listAll();
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(result.data, null, 2) },
-          ],
-        };
-      } catch (error: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatError(error, "listing saved queries"),
-            },
-          ],
-          isError: true,
-        };
-      }
-    }
-  );
-
-  registerTool<any>(server,
-    "execute_smart_query",
-    "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 saved query ID (UUID) to execute"),
-      variables: z
-        .record(z.string(), z.any())
-        .optional()
-        .describe(
-          "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.savedQueries.execute(
-          recordSlug,
-          queryId,
-          options
-        );
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(result.data, null, 2) },
-          ],
-        };
-      } catch (error: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatError(error, `executing saved query '${queryId}'`),
-            },
-          ],
-          isError: true,
-        };
-      }
-    }
-  );
-
-  registerTool<any>(server,
-    "get_smart_query",
-    "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 saved query ID (UUID)"),
-    },
-    async ({ recordSlug, queryId }) => {
-      try {
-        const result = await sdk.savedQueries.get(recordSlug, queryId);
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(result.data, null, 2) },
-          ],
-        };
-      } catch (error: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatError(error, `getting saved query '${queryId}'`),
-            },
-          ],
-          isError: true,
-        };
-      }
-    }
-  );
-
-  registerTool<any>(server,
-    "create_smart_query",
-    `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 saved query"),
-      description: z.string().optional().describe("Optional description"),
-      queryDefinition: z
-        .record(z.string(), z.any())
-        .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.savedQueries.create(recordSlug, input as any);
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(result.data, null, 2) },
-          ],
-        };
-      } catch (error: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatError(error, `creating saved query '${name}' for '${recordSlug}'`),
-            },
-          ],
-          isError: true,
-        };
-      }
-    }
-  );
-
-  registerTool<any>(server,
-    "update_smart_query",
-    `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 saved query ID (UUID) to update"),
-      name: z.string().optional().describe("Updated display name"),
-      description: z.string().optional().describe("Updated description"),
-      queryDefinition: z
-        .record(z.string(), z.any())
-        .optional()
-        .describe("Updated canonical inner QueryDefinition (without 'resource')."),
-    },
-    async ({ recordSlug, queryId, name, description, queryDefinition }) => {
-      try {
-        const input: Record<string, any> = {};
-        if (name !== undefined) input.name = name;
-        if (description !== undefined) input.description = description;
-        if (queryDefinition !== undefined) input.queryDefinition = queryDefinition;
-
-        const result = await sdk.savedQueries.update(recordSlug, queryId, input as any);
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(result.data, null, 2) },
-          ],
-        };
-      } catch (error: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatError(error, `updating saved query '${queryId}'`),
-            },
-          ],
-          isError: true,
-        };
-      }
-    }
-  );
-
-  registerTool<any>(server,
-    "delete_smart_query",
-    "Delete a saved query by ID.",
-    {
-      recordSlug: z.string().describe("The collection's record slug the query belongs to"),
-      queryId: z.string().describe("The saved query ID (UUID) to delete"),
-    },
-    async ({ recordSlug, queryId }) => {
-      try {
-        await sdk.savedQueries.delete(recordSlug, queryId);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Saved query '${queryId}' deleted from '${recordSlug}'.`,
-            },
-          ],
-        };
-      } catch (error: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatError(error, `deleting saved query '${queryId}'`),
-            },
-          ],
-          isError: true,
-        };
-      }
-    }
-  );
-
-  registerTool<any>(server,
-    "test_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("Canonical inner QueryDefinition to test (without 'resource')."),
-      variables: z
-        .record(z.string(), z.any())
-        .optional()
-        .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.savedQueries.test(recordSlug, input as any);
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(result.data, null, 2) },
-          ],
-        };
-      } catch (error: unknown) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatError(error, `test-executing saved query for '${recordSlug}'`),
-            },
-          ],
-          isError: true,
-        };
-      }
-    }
-  );
-}