@enfyra/mcp-server 0.0.64 → 0.0.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.64",
+  "version": "0.0.65",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -445,6 +445,39 @@ GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
           'Do not invent deep keys like members unless members is a relation on that table.',
         ],
       },
+      {
+        name: 'Sort parent rows by child relation aggregates',
+        code: `query_table({
+  tableName: "cloud_support_tickets",
+  fields: [
+    "id",
+    "subject",
+    "status",
+    "project.id",
+    "project.name"
+  ],
+  sort: "-_max(messages.createdAt),-createdAt",
+  limit: 25,
+  deep: JSON.stringify({
+    messages: {
+      fields: "id,authorKind,body,createdAt",
+      sort: "-createdAt",
+      limit: 3
+    }
+  })
+})
+
+// Other parent aggregate sorts:
+// sort=-_count(messages)
+// sort=_min(messages.createdAt)`,
+        notes: [
+          'Use _max(relation.field) for latest-child ordering, _min(relation.field) for earliest-child ordering, and _count(relation) for child-count ordering.',
+          'Aggregate sort helpers only work on direct one-to-many or many-to-many list relations.',
+          'The aggregate field must be a real non-encrypted scalar field on the related table.',
+          'Do not use raw sort=-messages.createdAt for parent ordering; it is ambiguous and rejected.',
+          'deep.messages.sort only orders the loaded message rows inside each ticket, so keep parent sort and child pagination as separate concerns.',
+        ],
+      },
       {
         name: 'Encrypted fields are not lookup fields',
         code: `// Bad: api_token is isEncrypted=true, so filter/sort cannot use it.

package/src/lib/mcp-instructions.js

@@ -241,6 +241,8 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Use **`discover_query_capabilities`** before building non-trivial filters/deep queries. It returns supported filter operators, field-permission condition operators, deep shape/rules, table columns/relations, table primary key, route paths, and examples.',
     '- Full filter operators: `_eq`, `_neq`, `_gt`, `_gte`, `_lt`, `_lte`, `_in`, `_not_in`, `_nin`, `_contains`, `_starts_with`, `_ends_with`, `_between`, `_is_null`, `_is_not_null`, `_and`, `_or`, `_not`.',
     '- Field permission condition DSL is narrower and does not support `_contains`, `_starts_with`, `_ends_with`, or `_between`.',
+    '- Root `sort` accepts local fields such as `-createdAt` plus direct list-relation aggregate helpers: `_count(relationName)`, `_max(relationName.fieldName)`, and `_min(relationName.fieldName)`. Use `-_max(messages.createdAt)` to order parent rows by the latest child row. The relation must be direct `one-to-many` or `many-to-many`, and the aggregate field must be a non-encrypted scalar field on the related table.',
+    '- Raw dotted to-many sort such as `messages.createdAt` is invalid for parent ordering. `deep: { messages: { sort: "-createdAt" } }` sorts the loaded child rows inside each parent only; it does not sort the parent list.',
     '- Deep shape: `{ relationName: { fields?, filter?, sort?, limit?, page?, deep? } }`. Relation keys are relation `propertyName`, not physical FK columns.',
     '- Use dotted relation fields such as `owner.email` or `lastMessage.text` when the caller only needs basic related record fields. Use `deep` when relation loading needs query options such as `filter`, `sort`, `limit`, `page`, or nested `deep`. Do not use `deep` for simple relation-id filters, one-row lookup, counts, or large child collections that should be loaded separately with pagination.',
     '- Deep validation rejects unknown relation keys, unknown subkeys, `limit` on many-to-one/one-to-one, and invalid dotted sort through many-side relations.',

package/src/mcp-server-entry.mjs

@@ -654,7 +654,7 @@ server.tool(
       queryParams: {
         fields: 'Comma-separated scalar/relation fields. Relations use relation propertyName, not physical FK column names.',
         filter: 'JSON object using operators above. Relation filters use nested relation propertyName objects.',
-        sort: 'Field name or -field. Dotted relation sort is constrained by relation type and deep validation.',
+        sort: 'Local field or -field. For direct one-to-many/many-to-many parent ordering, use _count(relation), _max(relation.field), or _min(relation.field); raw dotted to-many sort is invalid.',
         page: '1-based page.',
         limit: 'Page size.',
         meta: 'Request metadata/counts where supported.',
@@ -668,6 +668,7 @@ server.tool(
           'Unknown deep entry keys are invalid.',
           'limit on many-to-one/one-to-one relations is invalid.',
           'Dotted sort through one-to-many/many-to-many is invalid.',
+          'Deep sort orders rows inside the related collection only; use root aggregate sort helpers when parent rows must be ordered by child values.',
           'Nested deep is recursively validated.',
           'Field permissions may rewrite filters/sorts and sanitize post-query results.',
         ],