@centrali-io/centrali-mcp 5.4.0 → 5.5.0

package/dist/tools/records.js

@@ -12,10 +12,163 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._internal = void 0;
 exports.registerRecordTools = registerRecordTools;
 const axios_1 = __importDefault(require("axios"));
 const zod_1 = require("zod");
 const _register_js_1 = require("./_register.js");
+// ── Legacy 5.4.0 query_records translator (Sunset 2026-10-28) ──────────────
+//
+// 5.4.0 MCP clients call query_records with:
+//   { recordSlug, filters: { 'data.x[gte]': 1 }, sort: '-createdAt',
+//     page: 2, pageSize: 50, expand: 'customer', dateWindow: {...},
+//     includeDeleted, includeTotal }
+//
+// Canonical (Phase 1) accepts:
+//   { resource, where, sort: [{field, direction}], page: { limit, offset } }
+//
+// We accept BOTH on the wire and rewrite legacy → canonical before calling the
+// SDK, matching the data-service contract promise of long-lived legacy reads.
+const LEGACY_OP_MAP = {
+    $eq: "eq", $ne: "ne", $gt: "gt", $gte: "gte", $lt: "lt", $lte: "lte",
+    $in: "in", $nin: "nin", $contains: "contains",
+    $startsWith: "startsWith", $endsWith: "endsWith", $exists: "exists",
+    eq: "eq", ne: "ne", gt: "gt", gte: "gte", lt: "lt", lte: "lte",
+    in: "in", nin: "nin", contains: "contains",
+    startswith: "startsWith", endswith: "endsWith",
+    hasany: "hasAny", hasall: "hasAll",
+};
+let legacyWarned = false;
+function warnLegacyOnce() {
+    if (!legacyWarned) {
+        legacyWarned = true;
+        console.warn("[centrali-mcp] query_records called with the legacy 5.4.0 schema " +
+            "(recordSlug/filters/sort:string/pageSize). It still works but will be " +
+            "removed after 2026-10-28. Migrate to: { resource, where, " +
+            "sort: [{field,direction}], page: { limit, offset } }.");
+    }
+}
+function parseLegacyFilters(filters) {
+    var _a, _b;
+    if (filters == null || typeof filters !== "object" || Array.isArray(filters)) {
+        return undefined;
+    }
+    const conditions = [];
+    for (const [rawKey, value] of Object.entries(filters)) {
+        const m = rawKey.match(/^(.+?)\[\$?([a-zA-Z]+)\]$/);
+        if (m) {
+            const [, field, op] = m;
+            const canonOp = (_b = (_a = LEGACY_OP_MAP[op]) !== null && _a !== void 0 ? _a : LEGACY_OP_MAP[op.toLowerCase()]) !== null && _b !== void 0 ? _b : op;
+            conditions.push({ [field]: { [canonOp]: value } });
+        }
+        else {
+            conditions.push({ [rawKey]: { eq: value } });
+        }
+    }
+    if (conditions.length === 0)
+        return undefined;
+    if (conditions.length === 1)
+        return conditions[0];
+    return { and: conditions };
+}
+function parseLegacySort(sort) {
+    return sort
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => s.startsWith("-")
+        ? { field: s.slice(1), direction: "desc" }
+        : { field: s, direction: "asc" });
+}
+function dateWindowToWhere(dw) {
+    const conds = [];
+    if (dw.from !== undefined)
+        conds.push({ [dw.field]: { gte: dw.from } });
+    if (dw.to !== undefined)
+        conds.push({ [dw.field]: { lte: dw.to } });
+    if (conds.length === 0)
+        return undefined;
+    if (conds.length === 1)
+        return conds[0];
+    return { and: conds };
+}
+function translateQueryRecordsArgs(args) {
+    var _a, _b;
+    const isLegacy = args.recordSlug !== undefined ||
+        args.filters !== undefined ||
+        typeof args.sort === "string" ||
+        typeof args.page === "number" ||
+        args.pageSize !== undefined ||
+        args.expand !== undefined ||
+        args.dateWindow !== undefined ||
+        args.includeDeleted !== undefined ||
+        args.includeTotal !== undefined;
+    if (isLegacy)
+        warnLegacyOnce();
+    const resource = (_a = args.resource) !== null && _a !== void 0 ? _a : args.recordSlug;
+    if (!resource) {
+        throw new Error("query_records requires either `resource` (canonical) or `recordSlug` (legacy)");
+    }
+    // POST /records/query Phase 1 has no soft-delete plumbing — silently dropping
+    // `includeDeleted: true` would be a privacy regression vs 5.4.0 GET behavior
+    // (caller asks for tombstones, gets only live rows). Surface a clear error.
+    if (args.includeDeleted === true) {
+        throw new Error("query_records `includeDeleted: true` is not supported in Phase 1. " +
+            "Use the GET /records/slug/:rs endpoint with ?includeDeleted=true until Phase 2 lands.");
+    }
+    const definition = { resource };
+    const whereParts = [];
+    if (args.where !== undefined)
+        whereParts.push(args.where);
+    if (args.filters !== undefined) {
+        const fw = parseLegacyFilters(args.filters);
+        if (fw !== undefined)
+            whereParts.push(fw);
+    }
+    if (args.dateWindow !== undefined) {
+        const dw = dateWindowToWhere(args.dateWindow);
+        if (dw !== undefined)
+            whereParts.push(dw);
+    }
+    if (whereParts.length === 1)
+        definition.where = whereParts[0];
+    else if (whereParts.length > 1)
+        definition.where = { and: whereParts };
+    if (args.text !== undefined)
+        definition.text = args.text;
+    if (args.sort !== undefined) {
+        definition.sort = typeof args.sort === "string" ? parseLegacySort(args.sort) : args.sort;
+    }
+    if (args.page !== undefined || args.pageSize !== undefined) {
+        if (typeof args.page === "object" && args.page !== null) {
+            definition.page = args.page;
+        }
+        else {
+            const limit = (_b = args.pageSize) !== null && _b !== void 0 ? _b : 50;
+            const pageNum = typeof args.page === "number" ? args.page : 1;
+            const offset = (pageNum - 1) * limit;
+            definition.page = offset > 0 ? { limit, offset } : { limit };
+        }
+    }
+    if (args.select !== undefined)
+        definition.select = args.select;
+    if (args.include !== undefined) {
+        definition.include = args.include;
+    }
+    else if (args.expand !== undefined) {
+        const relations = args.expand
+            .split(",")
+            .map((s) => ({ relation: s.trim() }))
+            .filter((r) => r.relation.length > 0);
+        if (relations.length > 0)
+            definition.include = relations;
+    }
+    // `includeTotal` is dropped — `meta.total` is always returned for offset
+    // pagination on POST /records/query. `includeDeleted` is rejected above.
+    return { resource, definition };
+}
+// Exposed for tests
+exports._internal = { translateQueryRecordsArgs, parseLegacyFilters, parseLegacySort };
 /**
  * Ensures the SDK has a valid token.
  */
@@ -25,7 +178,7 @@ function ensureToken(sdk) {
         if (token)
             return token;
         try {
-            yield sdk.queryRecords("__noop__", { limit: 1 });
+            yield sdk.records.query("__noop__", { resource: "__noop__", page: { limit: 1 } });
         }
         catch ( /* token refresh side effect */_a) { /* token refresh side effect */ }
         return sdk.getToken();
@@ -55,7 +208,7 @@ function createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug) {
         if (isAuthError && !originalRequest._hasRetried) {
             originalRequest._hasRetried = true;
             try {
-                yield sdk.queryRecords("__noop__", { limit: 1 });
+                yield sdk.records.query("__noop__", { resource: "__noop__", page: { limit: 1 } });
             }
             catch ( /* token refresh side effect */_c) { /* token refresh side effect */ }
             const token = sdk.getToken();
@@ -69,55 +222,98 @@ function createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug) {
     return client;
 }
 function registerRecordTools(server, sdk, centraliUrl, workspaceId) {
-    (0, _register_js_1.registerTool)(server, "query_records", "Query records from a collection with optional filters, sorting, pagination, and date range filtering. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100). Use dateWindow for date range queries.", {
-        recordSlug: zod_1.z
+    (0, _register_js_1.registerTool)(server, "query_records", `Query records from a collection using the canonical Centrali query language (POST /records/query).
+
+The body is a QueryDefinition. Field paths use dotted strings ('data.status', 'data.customer.email'); the field operators (no '$' prefix) are: eq, ne, gt, gte, lt, lte, in, nin, contains, startsWith, endsWith, hasAny, hasAll, exists. Boolean trees use 'and', 'or', 'not'.
+
+Example body:
+  {
+    "where": {
+      "and": [
+        { "data.status": { "eq": "open" } },
+        { "data.amount": { "gte": 100 } }
+      ]
+    },
+    "sort": [{ "field": "createdAt", "direction": "desc" }],
+    "page": { "limit": 50 },
+    "select": { "fields": ["id", "data.status", "data.amount"] }
+  }
+
+Returns the canonical { data, meta } envelope. 'select', 'text', and 'include' are all accepted by the engine.`, {
+        // Canonical fields (Phase 1)
+        resource: zod_1.z
             .string()
-            .describe("The collection's record slug (e.g., 'orders')"),
-        filters: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.any())
             .optional()
-            .describe("Filter object with keys like 'data.fieldName' or 'data.fieldName[operator]'. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith, hasAny, hasAll"),
+            .describe("Collection slug to query (e.g. 'orders'). Required unless legacy `recordSlug` is provided."),
+        where: zod_1.z
+            .any()
+            .optional()
+            .describe("WhereExpression — either a FieldConditionMap ({ 'data.status': { eq: 'open' } }) or a boolean tree ({ and: [...] } | { or: [...] } | { not: ... }). Each FieldCondition must use exactly one operator."),
+        text: zod_1.z
+            .object({
+            query: zod_1.z.string().describe("Search string"),
+            fields: zod_1.z.array(zod_1.z.string()).optional().describe("Restrict to these fields"),
+            typoTolerance: zod_1.z.boolean().optional(),
+        })
+            .optional()
+            .describe("Full-text search clause. Routes to the search executor when set."),
         sort: zod_1.z
+            .any()
+            .optional()
+            .describe("Canonical: array of { field, direction: 'asc'|'desc' }. Legacy: string '-createdAt' (deprecated, translated automatically)."),
+        page: zod_1.z
+            .any()
+            .optional()
+            .describe("Canonical: { limit, offset|cursor }. Legacy: page number (deprecated; combine with `pageSize`)."),
+        select: zod_1.z
+            .object({
+            fields: zod_1.z.array(zod_1.z.string()).describe("Field paths to return"),
+        })
+            .optional()
+            .describe("Field projection. Example: { fields: ['id', 'data.status'] }."),
+        include: zod_1.z
+            .array(zod_1.z.object({ relation: zod_1.z.string() }))
+            .optional()
+            .describe("Relation expansion. Each entry names a relation declared on the collection."),
+        // Legacy 5.4.0 fields — accepted, translated to canonical, removed after 2026-10-28
+        recordSlug: zod_1.z
             .string()
             .optional()
-            .describe("Sort field with optional '-' prefix for descending (e.g., '-createdAt')"),
-        page: zod_1.z.number().optional().describe("Page number (1-indexed, default: 1)"),
+            .describe("[Deprecated 2026-10-28] Legacy alias for `resource`."),
+        filters: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.any())
+            .optional()
+            .describe("[Deprecated 2026-10-28] Legacy filter map (e.g. { 'data.status': 'open', 'data.price[lte]': 100 }). Translated to `where`."),
         pageSize: zod_1.z
             .number()
             .optional()
-            .describe("Records per page (default: 50, max: 500)"),
+            .describe("[Deprecated 2026-10-28] Legacy page size. Translated to `page.limit`."),
         expand: zod_1.z
             .string()
             .optional()
-            .describe("Comma-separated reference fields to expand (e.g., 'customer,product')"),
+            .describe("[Deprecated 2026-10-28] Comma-separated relation names (e.g. 'customer,product'). Translated to `include`."),
         dateWindow: zod_1.z
             .object({
-            field: zod_1.z.string().describe("Date field to filter on (e.g., 'createdAt', 'updatedAt')"),
-            from: zod_1.z.string().optional().describe("ISO 8601 lower bound (inclusive)"),
-            to: zod_1.z.string().optional().describe("ISO 8601 upper bound (inclusive)"),
+            field: zod_1.z.string(),
+            from: zod_1.z.string().optional(),
+            to: zod_1.z.string().optional(),
         })
             .optional()
-            .describe("Date range filter. Restricts results to records where the specified date field falls within the given range."),
+            .describe("[Deprecated 2026-10-28] Date range filter. Translated to `where` with gte/lte."),
         includeDeleted: zod_1.z
             .boolean()
             .optional()
-            .describe("Include soft-deleted records (default: false)"),
+            .describe("[Deprecated 2026-10-28] Ignored — POST /records/query does not surface deleted rows in Phase 1."),
         includeTotal: zod_1.z
             .boolean()
             .optional()
-            .describe("Include total record count in response metadata (default: false)"),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, filters, sort, page, pageSize, expand, dateWindow, includeDeleted, includeTotal }) {
+            .describe("[Deprecated 2026-10-28] Ignored — `meta.total` is always returned for offset pagination."),
+    }, (args) => __awaiter(this, void 0, void 0, function* () {
+        let resource = "<unknown>";
         try {
-            const params = Object.assign(Object.assign({}, filters), { sort,
-                page,
-                pageSize,
-                expand,
-                dateWindow,
-                includeDeleted,
-                includeTotal });
-            // Remove undefined values
-            Object.keys(params).forEach((key) => params[key] === undefined && delete params[key]);
-            const result = yield sdk.queryRecords(recordSlug, params);
+            const translated = translateQueryRecordsArgs(args);
+            resource = translated.resource;
+            const result = yield sdk.records.query(resource, translated.definition);
             return {
                 content: [
                     { type: "text", text: JSON.stringify(result, null, 2) },
@@ -129,7 +325,7 @@ function registerRecordTools(server, sdk, centraliUrl, workspaceId) {
                 content: [
                     {
                         type: "text",
-                        text: (0, _register_js_1.formatError)(error, `querying records from '${recordSlug}'`),
+                        text: (0, _register_js_1.formatError)(error, `querying records from '${resource}'`),
                     },
                 ],
                 isError: true,

package/dist/tools/smart-queries.js

@@ -12,17 +12,33 @@ 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 smart queries. Smart queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by collection record slug.", {
+    (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 smart queries in the workspace"),
+            .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.smartQueries.list(recordSlug)
-                : yield sdk.smartQueries.listAll();
+                ? yield sdk.savedQueries.list(recordSlug)
+                : yield sdk.savedQueries.listAll();
             return {
                 content: [
                     { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -34,26 +50,26 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: (0, _register_js_1.formatError)(error, "listing smart queries"),
+                        text: (0, _register_js_1.formatError)(error, "listing saved queries"),
                     },
                 ],
                 isError: true,
             };
         }
     }));
-    (0, _register_js_1.registerTool)(server, "execute_smart_query", "Execute a smart query by ID and return the results. Smart queries can have parameterized variables using {{variableName}} syntax.", {
+    (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 smart query ID (UUID) to execute"),
+        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.string())
+            .record(zod_1.z.string(), zod_1.z.any())
             .optional()
-            .describe("Variables to substitute in the query (key-value pairs matching {{variableName}} placeholders)"),
+            .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.smartQueries.execute(recordSlug, queryId, options);
+            const result = yield sdk.savedQueries.execute(recordSlug, queryId, options);
             return {
                 content: [
                     { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -65,19 +81,19 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: (0, _register_js_1.formatError)(error, `executing smart query '${queryId}'`),
+                        text: (0, _register_js_1.formatError)(error, `executing saved query '${queryId}'`),
                     },
                 ],
                 isError: true,
             };
         }
     }));
-    (0, _register_js_1.registerTool)(server, "get_smart_query", "Get a smart query by ID. Returns the full query definition including filters, sort, and variable declarations.", {
+    (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 smart query ID (UUID)"),
+        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.smartQueries.get(recordSlug, queryId);
+            const result = yield sdk.savedQueries.get(recordSlug, queryId);
             return {
                 content: [
                     { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -89,26 +105,28 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: (0, _register_js_1.formatError)(error, `getting smart query '${queryId}'`),
+                        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 smart query for a collection. Smart queries are reusable, parameterized queries with filter, sort, and variable support.", {
+    (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 smart query"),
+        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("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."),
     }, (_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.smartQueries.create(recordSlug, input);
+            const result = yield sdk.savedQueries.create(recordSlug, input);
             return {
                 content: [
                     { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -120,22 +138,24 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: (0, _register_js_1.formatError)(error, `creating smart query '${name}' for '${recordSlug}'`),
+                        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 smart query. Only include the fields you want to change.", {
+    (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 smart query ID (UUID) to update"),
+        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 query definition object"),
+            .describe("Updated canonical inner QueryDefinition (without 'resource')."),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, queryId, name, description, queryDefinition }) {
         try {
             const input = {};
@@ -145,7 +165,7 @@ function registerSmartQueryTools(server, sdk) {
                 input.description = description;
             if (queryDefinition !== undefined)
                 input.queryDefinition = queryDefinition;
-            const result = yield sdk.smartQueries.update(recordSlug, queryId, input);
+            const result = yield sdk.savedQueries.update(recordSlug, queryId, input);
             return {
                 content: [
                     { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -157,24 +177,24 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: (0, _register_js_1.formatError)(error, `updating smart query '${queryId}'`),
+                        text: (0, _register_js_1.formatError)(error, `updating saved query '${queryId}'`),
                     },
                 ],
                 isError: true,
             };
         }
     }));
-    (0, _register_js_1.registerTool)(server, "delete_smart_query", "Delete a smart query by ID.", {
+    (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 smart query ID (UUID) to delete"),
+        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.smartQueries.delete(recordSlug, queryId);
+            yield sdk.savedQueries.delete(recordSlug, queryId);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Smart query '${queryId}' deleted from '${recordSlug}'.`,
+                        text: `Saved query '${queryId}' deleted from '${recordSlug}'.`,
                     },
                 ],
             };
@@ -184,28 +204,30 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: (0, _register_js_1.formatError)(error, `deleting smart query '${queryId}'`),
+                        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 query syntax and previewing results before creating a smart query.", {
+    (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("The query definition to test (where, sort, limit, select, etc.)"),
+            .describe("Canonical inner QueryDefinition to test (without 'resource')."),
         variables: zod_1.z
-            .record(zod_1.z.string(), zod_1.z.string())
+            .record(zod_1.z.string(), zod_1.z.any())
             .optional()
-            .describe("Optional variables to substitute in the query"),
+            .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.smartQueries.test(recordSlug, input);
+            const result = yield sdk.savedQueries.test(recordSlug, input);
             return {
                 content: [
                     { type: "text", text: JSON.stringify(result.data, null, 2) },
@@ -217,7 +239,7 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: (0, _register_js_1.formatError)(error, `test-executing smart query for '${recordSlug}'`),
+                        text: (0, _register_js_1.formatError)(error, `test-executing saved query for '${recordSlug}'`),
                     },
                 ],
                 isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",
@@ -13,6 +13,7 @@
   },
   "scripts": {
     "build": "tsc --project tsconfig.json",
+    "test": "npm run build && node --test 'tests/**/*.test.cjs'",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -24,7 +25,7 @@
   "author": "Blueinit",
   "license": "ISC",
   "dependencies": {
-    "@centrali-io/centrali-sdk": "^5.4.0",
+    "@centrali-io/centrali-sdk": "^5.5.0",
     "@modelcontextprotocol/sdk": "^1.28.0"
   },
   "devDependencies": {

package/src/tools/_register.ts

@@ -18,6 +18,15 @@ export type ToolResult = {
  *
  * Call sites annotate the arg shape explicitly via the `Args` generic so the
  * handler body stays fully type-safe.
+ *
+ * CEN-1099 / CEN-1186 — re-investigated when query tool inputs were tightened
+ * to the canonical `QueryDefinition` shape (small, finite). Direct
+ * `server.tool(...)` still trips `TS2589 Type instantiation is excessively
+ * deep and possibly infinite` against the smaller schema, so this wrapper
+ * stays. Repro:
+ *   import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ *   server.tool("x", "x", { resource: z.string() }, async (a) => ({ content: [] }));
+ *   // → TS2589 from `ShapeOutput` over `ZodRawShape`.
  */
 export function registerTool<Args>(
   server: McpServer,