@enfyra/mcp-server 0.0.64 → 0.0.66

package/package.json

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

package/src/lib/mcp-examples.js

@@ -213,13 +213,13 @@ window.location.href = url.toString()`,
     }
   ]),
   indexes: JSON.stringify([
-    ["conversation", "createdAt"],
-    ["sender", "createdAt"]
+    ["conversation", "createdAt"]
   ])
 })`,
         notes: [
           'Use user_definition as the user table.',
           'Do not add inverse relations on user_definition unless the user explicitly asks.',
+          'createdAt, updatedAt, and custom date/datetime/timestamp fields already get auto-generated single-field indexes; add only compound indexes needed by hot filters.',
           'Do not provide physical FK column names; Enfyra derives them.',
         ],
       },
@@ -270,6 +270,7 @@ window.location.href = url.toString()`,
 })`,
         notes: [
           'Unread is per user and per message; do not put global read state on conversation.',
+          'readAt is a datetime field and gets its own auto index; the explicit indexes here are compound unread lookup indexes.',
           'For chat-list UX, default to a boolean unread dot instead of exact counts.',
         ],
       },
@@ -445,6 +446,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

@@ -84,6 +84,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- MCP **`create_table` supports creating columns and relations in the same call**: pass `columns` and `relations` as JSON arrays. Use `create_relation` only when adding a relation to an existing table later.',
     '- MCP **`create_table` supports `isSingleRecord` directly**. Set `isSingleRecord: true` in the create call for settings/config tables that should keep only one record; do not create first and then patch only for this flag.',
     '- MCP **`create_table` and `update_table` support `indexes` and `uniques`** as JSON arrays of logical field groups. Use compound indexes for hot filters and unread/read state, e.g. `indexes: [["member","isRead","conversation"],["conversation","member","isRead"]]` and `uniques: [["message","member"]]`. Relation property names are allowed; Enfyra resolves them to physical FK columns for SQL and Mongo.',
+    '- Enfyra auto-generates single-field indexes for `createdAt`, `updatedAt`, and scalar time columns with type `date`, `datetime`, or `timestamp`. SQL appends `id` as the stable tie-breaker, and Mongo appends `_id`. Do not add duplicate single-field indexes for these time fields; add explicit compound indexes only when a hot query combines the time field with other filters such as status, owner, tenant, or relation fields.',
     '- MCP **`create_table` does not accept `alias`**. Do not invent or send alias during table creation; default route/schema behavior is based on `name`. Use `update_table` later only when alias truly needs to change.',
     '- In `create_table.relations`, each relation uses `targetTable` (table id or `{id}`), `type`, `propertyName`, optional `inversePropertyName` or `mappedBy`, `isNullable`, `onDelete`, and `description`. The target table must already exist.',
     '- **Use `user_definition` as the only user table.** Do not create app-specific user/profile mapping tables such as `chat_profile`, `app_user`, `customer_user`, or tables that only mirror/link Enfyra users. If an app needs extra user fields or user relations, add columns/relations directly on `user_definition`.',
@@ -241,6 +242,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.',
         ],