@centrali-io/centrali-mcp 5.3.0 → 5.5.0

package/src/tools/describe.ts

@@ -621,9 +621,9 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Records ────────────────────────────────────────────────────────
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "describe_records",
-    "Get the schema reference for Centrali record operations. Explains filter syntax, sort syntax, pagination, expand, and the data. prefix convention.",
+    "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.",
     {},
     async () => ({
       content: [
@@ -633,7 +633,7 @@ export function registerDescribeTools(server: McpServer) {
             {
               domain: "Records",
               description:
-                "Records are rows of data stored in collections. All custom field values live under the 'data' namespace.",
+                "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",
@@ -644,77 +644,85 @@ export function registerDescribeTools(server: McpServer) {
                 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)",
-                ],
-              },
-              sort_syntax: {
+              query_definition: {
                 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",
+                  "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)",
                 },
               },
-              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: {
+              operators: {
                 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'",
+                  "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"],
               },
-              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)",
+              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" } }] },
+                  ],
                 },
-                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" },
+                "Date window": {
+                  and: [
+                    { createdAt: { gte: "2024-03-01T00:00:00Z" } },
+                    { createdAt: { lte: "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.",
+                  "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 },
@@ -724,6 +732,7 @@ export function registerDescribeTools(server: McpServer) {
               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)",
@@ -1054,9 +1063,9 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Smart Queries ──────────────────────────────────────────────────
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "describe_smart_queries",
-    "Get the schema reference for Centrali smart queries. Explains parameterized queries, variable substitution, and execution.",
+    "Get the schema reference for Centrali saved (a.k.a. smart) queries. Explains the canonical QueryDefinition body, variable substitution, and execution.",
     {},
     async () => ({
       content: [
@@ -1064,71 +1073,75 @@ export function registerDescribeTools(server: McpServer) {
           type: "text",
           text: JSON.stringify(
             {
-              domain: "Smart Queries",
+              domain: "Saved Queries (a.k.a. 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: {
+                "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",
+                  "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,