@centrali-io/centrali-mcp 5.4.0 → 5.5.0

package/README.md

@@ -115,7 +115,7 @@ After connecting, call `describe_centrali` first — it returns the full capabil
 ### Records
 | Tool | Description |
 |------|-------------|
-| `query_records` | Query records with filters, sorting, pagination |
+| `query_records` | Query records using the canonical Centrali query language (POST /records/query). Accepts a `QueryDefinition` body (`where`, `text`, `sort`, `page`, `select`). |
 | `get_record` | Get a single record by ID |
 | `get_records_by_ids` | Get multiple records by IDs |
 | `create_record` | Create a new record |
@@ -154,16 +154,19 @@ After connecting, call `describe_centrali` first — it returns the full capabil
 | `invoke_endpoint` | Call a sync compute endpoint by path (returns response inline) |
 | `remove_allowed_domain` | Remove a domain from the allowlist |
 
-### Smart Queries
+### Saved Queries (a.k.a. Smart Queries)
+
+Saved queries store a canonical `QueryDefinition` plus optional variables. Tool names keep the `_smart_query` suffix for backwards compatibility, but inputs and outputs are the canonical shape.
+
 | Tool | Description |
 |------|-------------|
-| `list_smart_queries` | List smart queries, optionally by collection |
-| `get_smart_query` | Get a smart query by ID |
-| `create_smart_query` | Create a reusable parameterized query |
-| `update_smart_query` | Update a smart query |
-| `delete_smart_query` | Delete a smart query |
-| `execute_smart_query` | Execute a smart query with optional variables |
-| `test_smart_query` | Test a query definition without saving |
+| `list_smart_queries` | List saved queries, optionally by collection |
+| `get_smart_query` | Get a saved query by ID |
+| `create_smart_query` | Create a reusable parameterized query (canonical body) |
+| `update_smart_query` | Update a saved query (canonical body) |
+| `delete_smart_query` | Delete a saved query |
+| `execute_smart_query` | Execute a saved query with optional variables |
+| `test_smart_query` | Test a canonical query definition without saving |
 
 ### Orchestrations
 | Tool | Description |

package/dist/tools/_register.d.ts

@@ -19,6 +19,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 declare function registerTool<Args>(server: McpServer, name: string, description: string, schema: ZodRawShape, handler: (args: Args) => Promise<ToolResult>): void;
 export declare function formatError(error: unknown, context: string): string;

package/dist/tools/_register.js

@@ -14,6 +14,15 @@ exports.formatError = formatError;
  *
  * 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`.
  */
 function registerTool(server, name, description, schema, handler) {
     server.tool(name, description, schema, handler);

package/dist/tools/describe.js

@@ -585,14 +585,14 @@ function registerDescribeTools(server) {
         });
     }));
     // ── Records ────────────────────────────────────────────────────────
-    (0, _register_js_1.registerTool)(server, "describe_records", "Get the schema reference for Centrali record operations. Explains filter syntax, sort syntax, pagination, expand, and the data. prefix convention.", {}, () => __awaiter(this, void 0, void 0, function* () {
+    (0, _register_js_1.registerTool)(server, "describe_records", "Get the schema reference for Centrali record operations. Explains the canonical QueryDefinition body used by query_records, the operator vocabulary, sort/page/select clauses, and the data. prefix convention.", {}, () => __awaiter(this, void 0, void 0, function* () {
         return ({
             content: [
                 {
                     type: "text",
                     text: JSON.stringify({
                         domain: "Records",
-                        description: "Records are rows of data stored in collections. All custom field values live under the 'data' namespace.",
+                        description: "Records are rows of data stored in collections. All custom field values live under the 'data' namespace. The query_records tool accepts a canonical QueryDefinition body; the underlying engine (POST /records/query) is shared with the SDK, console, compute, and Pages.",
                         record_shape: {
                             id: "UUID — auto-generated",
                             collectionId: "UUID — the collection this record belongs to",
@@ -603,71 +603,82 @@ function registerDescribeTools(server) {
                             updatedBy: "UUID — user who last updated",
                             isDeleted: "boolean — true if soft-deleted",
                         },
-                        filter_syntax: {
-                            description: "Filters are passed as key-value pairs. Keys use the 'data.' prefix for custom fields and bracket notation for operators.",
-                            examples: {
-                                "Exact match": { "data.status": "active" },
-                                "Greater than": { "data.price[gt]": 100 },
-                                "Less than or equal": { "data.age[lte]": 30 },
-                                "Not equal": { "data.type[ne]": "draft" },
-                                "In list": { "data.category[in]": "electronics,books" },
-                                "Not in list": { "data.status[nin]": "deleted,archived" },
-                                "Contains (text)": { "data.name[contains]": "john" },
-                                "Starts with": { "data.email[startswith]": "admin" },
-                                "Ends with": { "data.domain[endswith]": ".com" },
-                            },
-                            operators: [
-                                "eq (default, no bracket needed)",
-                                "ne (not equal)",
-                                "gt (greater than)",
-                                "gte (greater than or equal)",
-                                "lt (less than)",
-                                "lte (less than or equal)",
-                                "in (comma-separated list)",
-                                "nin (not in comma-separated list)",
-                                "contains (substring match)",
-                                "startswith (prefix match)",
-                                "endswith (suffix match)",
+                        query_definition: {
+                            description: "Canonical QueryDefinition shape passed to query_records. Field paths are dotted strings ('data.status', 'data.customer.email'). Each FieldCondition uses exactly one operator (no '$' prefix).",
+                            shape: {
+                                resource: "string — collection slug",
+                                where: "WhereExpression — FieldConditionMap | { and: [...] } | { or: [...] } | { not: ... }",
+                                text: "{ query: string, fields?: string[], typoTolerance?: boolean }",
+                                sort: "[{ field: string, direction: 'asc' | 'desc' }]",
+                                page: "{ limit: number, offset?: number } | { limit: number, cursor?: string }",
+                                select: "{ fields: string[] }",
+                                include: "[{ relation: string }] — relation expansion (collection-defined relations)",
+                            },
+                        },
+                        operators: {
+                            description: "Field operators. Use exactly one per FieldCondition.",
+                            list: [
+                                "eq — equal",
+                                "ne — not equal",
+                                "gt — greater than",
+                                "gte — greater than or equal",
+                                "lt — less than",
+                                "lte — less than or equal",
+                                "in — value in array",
+                                "nin — value not in array",
+                                "contains — substring match",
+                                "startsWith — prefix match",
+                                "endsWith — suffix match",
+                                "hasAny — array field has any of these",
+                                "hasAll — array field has all of these",
+                                "exists — boolean: field is set",
                             ],
+                            boolean_tree: ["and", "or", "not"],
                         },
-                        sort_syntax: {
-                            description: "Sort by a single field. Prefix with '-' for descending order.",
-                            examples: {
-                                "Ascending by date": "createdAt",
-                                "Descending by date": "-createdAt",
-                                "By custom field asc": "data.name",
-                                "By custom field desc": "-data.price",
+                        examples: {
+                            "Exact match": { "data.status": { eq: "active" } },
+                            "Greater than": { "data.price": { gt: 100 } },
+                            "Boolean tree": {
+                                and: [
+                                    { "data.status": { eq: "open" } },
+                                    { or: [{ "data.amount": { gte: 100 } }, { "data.priority": { eq: "high" } }] },
+                                ],
                             },
-                        },
-                        pagination: {
-                            page: "1-indexed page number (default: 1)",
-                            pageSize: "Records per page (default: 50, max: 500)",
-                            response_includes: "total, page, pageSize, totalPages in the response metadata",
-                        },
-                        expand: {
-                            description: "Comma-separated list of reference field names to expand (join). Returns the full referenced record instead of just the ID.",
-                            example: "expand: 'customer,product'",
-                        },
-                        dateWindow: {
-                            description: "Date range filter. Restricts results to records where a date field falls within a given range. Both 'from' and 'to' are optional (open-ended ranges allowed).",
-                            shape: {
-                                field: "string — date field to filter on (e.g., 'createdAt', 'updatedAt', or a custom date field)",
-                                from: "string? — ISO 8601 lower bound (inclusive)",
-                                to: "string? — ISO 8601 upper bound (inclusive)",
+                            "Date window": {
+                                and: [
+                                    { createdAt: { gte: "2024-03-01T00:00:00Z" } },
+                                    { createdAt: { lte: "2024-03-31T23:59:59Z" } },
+                                ],
                             },
-                            examples: {
-                                "Last 30 days": { field: "createdAt", from: "2024-03-01T00:00:00Z" },
-                                "Specific range": { field: "updatedAt", from: "2024-01-01T00:00:00Z", to: "2024-03-31T23:59:59Z" },
+                            "Sort + page": {
+                                sort: [{ field: "createdAt", direction: "desc" }],
+                                page: { limit: 50 },
                             },
+                            "Projection": { select: { fields: ["id", "data.status", "data.amount"] } },
+                            "Full-text search": { text: { query: "urgent shipping", fields: ["data.notes"] } },
                         },
-                        includeDeleted: {
-                            description: "Set to true to include soft-deleted records in the results (default: false). Alias: includeArchived, all.",
+                        response_envelope: {
+                            description: "All canonical queries return { data, meta }.",
+                            shape: {
+                                data: "T[]",
+                                meta: {
+                                    limit: "number",
+                                    offset: "number? (offset mode)",
+                                    cursor: "string? (cursor mode)",
+                                    nextCursor: "string?",
+                                    hasMore: "boolean?",
+                                    total: "number? (when computable; depends on executor)",
+                                    processingTimeMs: "number?",
+                                    mode: "'filter' | 'search' | 'hybrid'",
+                                },
+                            },
                         },
-                        includeTotal: {
-                            description: "Set to true to include the total record count in response metadata (default: false).",
+                        page_defaults: {
+                            limit_default: 50,
+                            limit_max: 500,
                         },
                         upsert: {
-                            description: "Atomic create-or-update. Provide 'match' fields to find existing record and 'data' for the full record body.",
+                            description: "Atomic create-or-update via upsert_record. Provide 'match' fields to find an existing record and 'data' for the full record body.",
                             example: {
                                 match: { sku: "WIDGET-001" },
                                 data: { sku: "WIDGET-001", name: "Widget", price: 9.99 },
@@ -677,6 +688,7 @@ function registerDescribeTools(server) {
                         tips: [
                             "Always use the 'data.' prefix when filtering on custom fields",
                             "System fields (id, createdAt, updatedAt) don't need the 'data.' prefix",
+                            "Each FieldCondition must use exactly one operator — '{ eq: 1, ne: 2 }' is rejected",
                             "Use upsert_record for idempotent imports — it won't create duplicates",
                             "Soft-deleted records can be restored with restore_record",
                             "Use get_records_by_ids for batch lookups (more efficient than individual get_record calls)",
@@ -974,73 +986,77 @@ function registerDescribeTools(server) {
         });
     }));
     // ── Smart Queries ──────────────────────────────────────────────────
-    (0, _register_js_1.registerTool)(server, "describe_smart_queries", "Get the schema reference for Centrali smart queries. Explains parameterized queries, variable substitution, and execution.", {}, () => __awaiter(this, void 0, void 0, function* () {
+    (0, _register_js_1.registerTool)(server, "describe_smart_queries", "Get the schema reference for Centrali saved (a.k.a. smart) queries. Explains the canonical QueryDefinition body, variable substitution, and execution.", {}, () => __awaiter(this, void 0, void 0, function* () {
         return ({
             content: [
                 {
                     type: "text",
                     text: JSON.stringify({
-                        domain: "Smart Queries",
-                        description: "Smart queries are reusable, parameterized queries defined in the Centrali console. They allow complex filtering and aggregation logic to be saved and executed with variable substitution.",
-                        smart_query_shape: {
+                        domain: "Saved Queries (a.k.a. Smart Queries)",
+                        description: "Saved queries are reusable, parameterized queries defined in the Centrali console. They store a canonical QueryDefinition plus optional variable declarations and are executed under the caller's permissions. Tool names retain the `_smart_query` suffix for backwards compatibility.",
+                        saved_query_shape: {
                             id: "UUID",
                             name: "string — display name",
                             recordSlug: "string — the collection this query targets",
                             description: "string | null",
-                            query: "object — the query definition with filters, sort, fields, and aggregations",
-                            variables: "object[] — declared variables with name, type, and default values",
+                            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.",
                         },
+                        query_definition_reference: "Use describe_records for the full QueryDefinition shape, operator vocabulary, and examples.",
                         variable_syntax: {
-                            description: "Variables use double-brace syntax: {{variableName}}. When executing, pass a variables object to substitute values.",
-                            example: {
-                                query_filter: {
-                                    "data.status": "{{status}}",
-                                    "data.amount[gte]": "{{minAmount}}",
-                                },
-                                execution_variables: {
-                                    status: "active",
-                                    minAmount: "1000",
+                            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.",
+                            example_query_definition: {
+                                where: {
+                                    and: [
+                                        { "data.status": { eq: "{{statusFilter}}" } },
+                                        { "data.amount": { gte: "{{minAmount}}" } },
+                                    ],
                                 },
+                                sort: [{ field: "createdAt", direction: "desc" }],
+                                page: { limit: 100 },
+                            },
+                            example_execution_variables: {
+                                statusFilter: "active",
+                                minAmount: 1000,
                             },
-                            note: "Variable values are always passed as strings — the query engine handles type coercion",
+                            note: "Pass values via the 'variables' arg on execute_smart_query / test_smart_query. Values are substituted before the engine validates the query.",
                         },
                         crud_tools: {
                             get_smart_query: {
-                                description: "Get a smart query by ID, including its full definition",
+                                description: "Get a saved query by ID, including its full canonical definition",
                                 required_params: ["recordSlug", "queryId"],
                             },
                             create_smart_query: {
-                                description: "Create a new smart query for a collection",
+                                description: "Create a new saved query for a collection",
                                 required_params: ["recordSlug", "name", "queryDefinition"],
                                 optional_params: ["description"],
                                 queryDefinition_example: {
-                                    where: { status: { "$eq": "active" } },
+                                    where: { "data.status": { eq: "active" } },
                                     sort: [{ field: "createdAt", direction: "desc" }],
-                                    limit: 100,
+                                    page: { limit: 100 },
                                 },
                             },
                             update_smart_query: {
-                                description: "Update an existing smart query. Partial updates supported.",
+                                description: "Update an existing saved query. Partial updates supported.",
                                 required_params: ["recordSlug", "queryId"],
                                 optional_params: ["name", "description", "queryDefinition"],
                             },
                             delete_smart_query: {
-                                description: "Delete a smart query by ID",
+                                description: "Delete a saved query by ID",
                                 required_params: ["recordSlug", "queryId"],
                             },
                             test_smart_query: {
-                                description: "Test execute a query definition without saving it. Preview results before creating.",
+                                description: "Test execute a canonical query definition without saving it. Preview results before creating.",
                                 required_params: ["recordSlug", "queryDefinition"],
                                 optional_params: ["variables"],
                             },
                         },
                         tips: [
                             "Use list_smart_queries to discover available queries (optionally filter by collection slug)",
-                            "Smart queries return the same result shape as query_records",
-                            "Variables are defined when creating the query in the console — check the query's variables array to see what's expected",
-                            "Prefer smart queries over ad-hoc query_records filters for complex/reusable logic",
-                            "Use test_smart_query to validate query syntax and preview results before saving",
-                            "Use create_smart_query to save reusable queries that can be executed with execute_smart_query",
+                            "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",
+                            "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', …)",
                         ],
                     }, null, 2),
                 },

package/dist/tools/records.d.ts

@@ -1,3 +1,38 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
+declare function parseLegacyFilters(filters: unknown): unknown;
+declare function parseLegacySort(sort: string): Array<{
+    field: string;
+    direction: "asc" | "desc";
+}>;
+type QueryRecordsArgs = {
+    resource?: string;
+    recordSlug?: string;
+    where?: unknown;
+    text?: unknown;
+    sort?: unknown;
+    page?: unknown;
+    pageSize?: number;
+    select?: unknown;
+    include?: unknown;
+    filters?: Record<string, unknown>;
+    expand?: string;
+    dateWindow?: {
+        field: string;
+        from?: string;
+        to?: string;
+    };
+    includeDeleted?: boolean;
+    includeTotal?: boolean;
+};
+declare function translateQueryRecordsArgs(args: QueryRecordsArgs): {
+    resource: string;
+    definition: Record<string, unknown>;
+};
+export declare const _internal: {
+    translateQueryRecordsArgs: typeof translateQueryRecordsArgs;
+    parseLegacyFilters: typeof parseLegacyFilters;
+    parseLegacySort: typeof parseLegacySort;
+};
 export declare function registerRecordTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string): void;
+export {};