@enfyra/mcp-server 0.0.62 → 0.0.63

package/package.json

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

package/src/lib/mcp-examples.js

@@ -249,7 +249,7 @@ create_column({
   },
   'queries-deep': {
     title: 'REST queries, filters, meta counts, and deep relation fetches',
-    useWhen: 'Use when fetching records, filtering by relations, loading nested data, or counting efficiently.',
+    useWhen: 'Use when fetching records, filtering by relations, loading nested relation data in the same request, or counting efficiently.',
     examples: [
       {
         name: 'Minimal MCP query then explicit detail query',
@@ -310,14 +310,33 @@ GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
         ],
       },
       {
-        name: 'Deep relation query',
+        name: 'Relation fields without deep',
         code: `query_table({
   tableName: "order",
-  fields: ["id", "total", "customer"],
+  fields: [
+    "id",
+    "total",
+    "customer.id",
+    "customer.email",
+    "customer.displayName"
+  ],
+  limit: 20
+})`,
+        notes: [
+          'Use fields with dotted relation paths when you only need scalar fields from related records.',
+          'This is enough for simple many-to-one or one-to-one relation display such as owner.email, customer.name, or lastMessage.text.',
+          'Do not add deep when fields alone can express the relation data you need.',
+        ],
+      },
+      {
+        name: 'Deep relation query options',
+        code: `query_table({
+  tableName: "order",
+  fields: ["id", "total"],
   deep: JSON.stringify({
-    customer: { fields: "id,email,displayName" },
     items: {
       fields: "id,quantity,product",
+      sort: "-createdAt",
       limit: 20,
       deep: {
         product: { fields: "id,name,price" }
@@ -326,6 +345,11 @@ GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
   })
 })`,
         notes: [
+          'Use deep when relation loading needs query options such as filter, sort, limit, page, or nested deep.',
+          'Deep is mainly useful for controlled child collections or nested relation fetches, not for basic related-field display.',
+          'Do not use deep just to filter by a relation id; use a normal relation filter instead.',
+          'Do not use deep for counts; use count_records or meta=filterCount/totalCount.',
+          'Do not deep-load large child collections without an explicit limit/page. For heavy screens, fetch the parent list first, then load the selected child collection separately with pagination.',
           'Use query_table deep for normal MCP reads; use test_rest_endpoint only when you need a custom raw URL or route behavior test.',
           'deep keys must be relation property names.',
           'Allowed deep options are fields, filter, sort, limit, page, and deep.',

package/src/lib/mcp-instructions.js

@@ -240,6 +240,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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`.',
     '- 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.',
     '- To count records over REST, do not fetch full rows. Use MCP **`count_records`**, or call `GET /<table>?fields=id&limit=1&meta=totalCount` without filter and read `meta.totalCount`; with a filter use `meta=filterCount` and read `meta.filterCount`.',
     '- In custom dynamic code, use the same lightweight pattern: `const result = await @REPOS.main.find({ fields: "id", limit: 1, meta: filter ? "filterCount" : "totalCount", ...(filter ? { filter } : {}) }); const count = filter ? result.meta?.filterCount : result.meta?.totalCount;`.',