@enfyra/mcp-server 0.0.71 → 0.0.72

package/README.md

@@ -186,6 +186,8 @@ Use this block in any host-specific `mcp.json` / `mcpServers` merge (adjust env
 
 Schema and script tools include safety guards for LLM callers: generic record mutations validate request fields against live metadata, script-backed records must validate `sourceCode` before save through `/admin/script/validate` and fail closed if validation is unavailable, relation metadata rejects physical FK/junction inputs, custom routes reject `mainTableId` unless the path is the canonical table route, schema tools serialize table/column/relation changes, and destructive deletes require `confirm=true` after returning a preview.
 
+Read tools use Enfyra's `fields` parameter directly. Passing explicit includes such as `fields=id,email` returns only those fields, while any `-field` token switches that scope to exclude mode. For example, `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode`. Nested exclusions work with dotted fields and `deep`, such as `fields=-owner.avatar` or `deep.owner.fields=-avatar`.
+
 Quick checklist for a new LLM using Enfyra MCP: discover the live system first, inspect the specific table/route, load the matching example category, mutate with explicit fields and relation property names, validate or test scripts/routes before relying on them, re-read the saved row when mutation output is summarized, and preview destructive operations before confirming.
 
 Use `update_script_source` when updating existing long script-backed records such as `flow_step_definition`, `route_handler_definition`, hook tables, websocket scripts, GraphQL scripts, or bootstrap scripts. It accepts raw `sourceCode` directly, validates the source, and saves `sourceCode`/`scriptLanguage` without requiring the caller to manually JSON-escape the full script. Use generic `update_record` for small record patches or patches that include non-script metadata fields.

package/package.json

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

package/src/lib/mcp-examples.js

@@ -419,6 +419,34 @@ GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
           'Do not add deep when fields alone can express the relation data you need.',
         ],
       },
+      {
+        name: 'Exclude large generated fields',
+        code: `query_table({
+  tableName: "route_handler_definition",
+  fields: ["-compiledCode"],
+  limit: 20
+})
+
+query_table({
+  tableName: "post",
+  fields: ["id", "-author.avatar"],
+  deep: JSON.stringify({
+    comments: {
+      fields: "-compiledCode,-author.avatar",
+      limit: 10,
+      deep: {
+        author: { fields: "-avatar" }
+      }
+    }
+  })
+})`,
+        notes: [
+          'Use fields=-compiledCode when reading script-backed records; sourceCode is the editable contract and compiledCode is generated by the server.',
+          'Any -field token switches that fields scope to exclude mode, so fields=id,-compiledCode returns all readable fields except compiledCode.',
+          'Dotted exclusions and deep relation fields use the same exclude-mode rule.',
+          'Excluded fields and relations must exist in metadata; typos should fail instead of silently returning large or sensitive fields.',
+        ],
+      },
       {
         name: 'Deep relation query options',
         code: `query_table({

package/src/lib/mcp-instructions.js

@@ -244,6 +244,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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.',
+    '- Field selection has two modes per query scope. Include mode is the default: `fields=id,email,owner.name` returns only those fields. If any token starts with `-`, that scope switches to exclude mode: `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode` because positive tokens are ignored in exclude mode. Dotted exclusions such as `fields=-owner.avatar` and nested deep fields such as `deep: { owner: { fields: "-avatar" } }` also switch that scope to exclude mode. Unknown excluded fields/relations are request errors, so inspect metadata before excluding guessed names.',
     '- 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.',