@enfyra/mcp-server 0.1.69 → 0.1.71

package/dist/lib/mcp-example-permissions-rls.js

@@ -0,0 +1,210 @@
+export const permissionsRlsExamples = {
+    title: 'Route permissions, guards, field permissions, column rules, and RLS',
+    useWhen: 'Use when securing routes or shaping what fields a user can read/write.',
+    examples: [
+        {
+            name: 'Audit and grant authenticated route access',
+            code: `audit_route_access({
+  path: "/orders",
+  roleName: "user",
+  methods: ["GET", "POST"]
+})
+
+ensure_route_access({
+  path: "/orders",
+  roleName: "user",
+  methods: ["GET", "POST"],
+  description: "Authenticated users can list and create their own orders.",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
+})`,
+            notes: [
+                'Start with the security boundary: choose public/private methods, role or user route access, owner/tenant scope, and field exposure before writing handler or UI logic.',
+                'Use route permissions for authenticated access. The tool resolves role and method ids, validates the route available methods, merges existing methods, and reloads routes.',
+                'Handlers or pre-hooks must still enforce owner or tenant scope; route permission only lets the request pass RoleGuard.',
+                'Use publicMethods only for anonymous public access.',
+            ],
+        },
+        {
+            name: 'Make a read-only route public',
+            code: `public_route_methods({
+  path: "/articles",
+  methods: ["GET"],
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
+})`,
+            notes: [
+                'Use public_route_methods instead of raw enfyra_route updates; the tool resolves method ids and validates that GET is available.',
+                'publicMethods controls anonymous route access. Route permissions are not for public access.',
+                'Route permissions apply when the method is not public.',
+            ],
+        },
+        {
+            name: 'Rate limit anonymous requests by IP',
+            code: `ensure_route_rate_limit({
+  path: "/newsletter_signup",
+  methods: ["POST"],
+  scope: "ip",
+  maxRequests: 10,
+  perSeconds: 60,
+  description: "Limit anonymous signup attempts by client IP.",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
+})
+
+inspect_route({ path: "/newsletter_signup" })
+
+test_rest_endpoint({
+  method: "POST",
+  path: "/newsletter_signup",
+  body: { email: "test@example.com" }
+})`,
+            notes: [
+                'Use ensure_route_rate_limit for request throttling so the built-in guard engine enforces the limit.',
+                'Use scope "ip" for anonymous/public route protection because no user is available yet.',
+                'Inspect and test after creation so the final behavior is verified through the actual REST route.',
+            ],
+        },
+        {
+            name: 'Rate limit authenticated users',
+            code: `ensure_route_rate_limit({
+  path: "/projects",
+  methods: ["POST"],
+  scope: "user",
+  maxRequests: 3,
+  perSeconds: 3600,
+  description: "Authenticated users can create at most 3 projects per hour.",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
+})`,
+            notes: [
+                'User-scoped limits automatically use post_auth because the server only has user id after auth and RoleGuard.',
+                'This does not grant access; users still need route permissions or a public method to reach the route.',
+                'Use ensure_guard only for advanced guard trees such as IP allowlists/blacklists or composed AND/OR guard rules.',
+            ],
+        },
+        {
+            name: 'Restrict an admin-only route to office IPs',
+            code: `ensure_guard({
+  name: "Admin reports office allowlist",
+  path: "/admin/reports",
+  methods: ["GET", "POST"],
+  position: "pre_auth",
+  isEnabled: false,
+  description: "Only office network IPs can reach admin reports.",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
+  rules: JSON.stringify([
+    {
+      type: "ip_whitelist",
+      config: { ips: ["203.0.113.10", "198.51.100.0/24"] }
+    }
+  ])
+})`,
+            notes: [
+                'Create risky allowlists disabled first, then inspect the saved guard before enabling it.',
+                'IP list configs use ips; exact IPv4 addresses and IPv4 CIDR ranges are supported.',
+                'An allowlist is an additional gate, not a replacement for route permissions.',
+            ],
+        },
+        {
+            name: 'Column rule for email format',
+            code: `ensure_column_rule({
+  tableName: "enfyra_user",
+  columnName: "email",
+  ruleType: "format",
+  value: JSON.stringify({ v: "email" }),
+  message: "Please enter a valid email address",
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
+})`,
+            notes: [
+                'Column rules validate canonical POST/PATCH body payloads.',
+                'The rule value payload uses the { v: ... } shape; do not pass ruleConfig.',
+                'Use column rules before writing custom validation code when the rule is simple.',
+            ],
+        },
+        {
+            name: 'Field permission condition',
+            code: `ensure_field_permission({
+  tableName: "project",
+  columnName: "internal_notes",
+  action: "read",
+  effect: "allow",
+  roleName: "user",
+  condition: JSON.stringify({
+    owner: { id: { _eq: "@USER.id" } }
+  }),
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>"
+})`,
+            notes: [
+                'Field permissions are for field-level access.',
+                'Use route/pre-hook filters for row-level access.',
+            ],
+        },
+        {
+            name: 'Admin menu and extension permission gates',
+            code: `<template>
+  <section class="space-y-4">
+    <PermissionGate :condition="canReadReports">
+      <template #default>
+        <div class="flex items-center justify-between gap-3">
+          <h2 class="text-lg font-semibold">Reports</h2>
+
+          <PermissionGate :condition="canCreateReport">
+            <UButton icon="i-lucide-plus" label="Create report" @click="openCreate = true" />
+          </PermissionGate>
+        </div>
+
+        <div v-for="report in reports" :key="report.id" class="rounded-lg border p-4">
+          <NuxtLink :to="\`/reports/\${report.id}\`" class="font-medium">
+            {{ report.title }}
+          </NuxtLink>
+
+          <div class="mt-3 flex gap-2">
+            <PermissionGate :condition="canUpdateReport">
+              <UButton icon="i-lucide-pencil" variant="outline" label="Edit" @click="openEdit(report)" />
+            </PermissionGate>
+
+            <PermissionGate :condition="canDeleteReport">
+              <UButton icon="i-lucide-trash-2" color="error" variant="outline" label="Delete" @click="openDelete(report)" />
+            </PermissionGate>
+          </div>
+        </div>
+      </template>
+
+      <template #fallback>
+        <EmptyState title="No access" description="You do not have permission to view reports." />
+      </template>
+    </PermissionGate>
+  </section>
+</template>
+
+<script setup>
+const { checkPermissionCondition } = usePermissions()
+
+const canReadReports = computed(() => checkPermissionCondition({
+  or: [
+    { route: '/reports', methods: ['GET'] },
+    { route: '/report', methods: ['GET'] }
+  ]
+}))
+
+const canCreateReport = computed(() => checkPermissionCondition({
+  or: [{ route: '/report', methods: ['POST'] }]
+}))
+
+const canUpdateReport = computed(() => checkPermissionCondition({
+  or: [{ route: '/report', methods: ['PATCH'] }]
+}))
+
+const canDeleteReport = computed(() => checkPermissionCondition({
+  or: [{ route: '/report', methods: ['DELETE'] }]
+}))
+</script>`,
+            notes: [
+                'This is menu/extension visibility, not row-level RLS.',
+                'Set enfyra_menu.permission on every sensitive admin menu. Example for /reports: { or: [{ route: "/reports", methods: ["GET"] }, { route: "/report", methods: ["GET"] }] }.',
+                'Admin pages are sensitive. Use permission gates by default, not as an optional polish step.',
+                'Menus should only be visible when the user has at least GET permission for the page route or backing data route.',
+                'Inside the extension, gate each action by its own route/method: GET for page visibility, POST for create/flow-trigger buttons, PATCH for normal record edits, DELETE for native delete routes.',
+                'Server route permissions remain mandatory; UI gates are for clear operator UX and least-privilege surfaces.',
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=mcp-example-permissions-rls.js.map

package/dist/lib/mcp-example-permissions-rls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-example-permissions-rls.js","sourceRoot":"","sources":["../../src/lib/mcp-example-permissions-rls.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,sBAAsB,GAAG;IAClC,KAAK,EAAE,qEAAqE;IAC5E,OAAO,EAAE,wEAAwE;IACjF,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,4CAA4C;YAClD,IAAI,EAAE;;;;;;;;;;;;GAYX;YACK,KAAK,EAAE;gBACL,wKAAwK;gBACxK,4KAA4K;gBAC5K,wHAAwH;gBACxH,qDAAqD;aACtD;SACF;QACD;YACE,IAAI,EAAE,+BAA+B;YACrC,IAAI,EAAE;;;;GAIX;YACK,KAAK,EAAE;gBACL,iIAAiI;gBACjI,6FAA6F;gBAC7F,wDAAwD;aACzD;SACF;QACD;YACE,IAAI,EAAE,qCAAqC;YAC3C,IAAI,EAAE;;;;;;;;;;;;;;;;GAgBX;YACK,KAAK,EAAE;gBACL,qGAAqG;gBACrG,wFAAwF;gBACxF,kGAAkG;aACnG;SACF;QACD;YACE,IAAI,EAAE,gCAAgC;YACtC,IAAI,EAAE;;;;;;;;GAQX;YACK,KAAK,EAAE;gBACL,8GAA8G;gBAC9G,uGAAuG;gBACvG,iHAAiH;aAClH;SACF;QACD;YACE,IAAI,EAAE,4CAA4C;YAClD,IAAI,EAAE;;;;;;;;;;;;;;GAcX;YACK,KAAK,EAAE;gBACL,0FAA0F;gBAC1F,mFAAmF;gBACnF,8EAA8E;aAC/E;SACF;QACD;YACE,IAAI,EAAE,8BAA8B;YACpC,IAAI,EAAE;;;;;;;GAOX;YACK,KAAK,EAAE;gBACL,2DAA2D;gBAC3D,2EAA2E;gBAC3E,iFAAiF;aAClF;SACF;QACD;YACE,IAAI,EAAE,4BAA4B;YAClC,IAAI,EAAE;;;;;;;;;;GAUX;YACK,KAAK,EAAE;gBACL,+CAA+C;gBAC/C,kDAAkD;aACnD;SACF;QACD;YACE,IAAI,EAAE,2CAA2C;YACjD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAyDJ;YACF,KAAK,EAAE;gBACL,uDAAuD;gBACvD,4KAA4K;gBAC5K,6FAA6F;gBAC7F,kHAAkH;gBAClH,gMAAgM;gBAChM,6GAA6G;aAC9G;SACF;KACF;CACF,CAAC"}

package/dist/lib/mcp-example-queries-deep.d.ts

@@ -0,0 +1,9 @@
+export declare const queriesDeepExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};

package/dist/lib/mcp-example-queries-deep.js

@@ -0,0 +1,220 @@
+export const queriesDeepExamples = {
+    title: 'REST queries, filters, meta counts, and deep relation fetches',
+    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',
+            code: `query_table({
+  tableName: "enfyra_user",
+  fields: ["id", "email"],
+  filter: { email: { _contains: "@example.com" } },
+  limit: 10
+})`,
+            notes: [
+                'Always pass fields when you need more than ids; query_table without fields intentionally returns only the primary key.',
+                'Use inspect_table first when you do not know valid column names or relation propertyName values.',
+                'Use count_records when only the count is needed.',
+                'When the user asks for all matching rows, pass all: true instead of choosing an arbitrary page size such as 30 or 50.',
+            ],
+        },
+        {
+            name: 'List current user conversations through RLS',
+            code: `query_table({
+  tableName: "chat_conversation",
+  fields: ["id", "kind", "title", "lastMessage.id", "lastMessage.text", "lastMessage.createdAt"],
+  all: true
+})`,
+            notes: [
+                'Use a conversation read pre-hook/RLS boundary so the route only returns conversations visible to @USER.',
+                'lastMessage is a relation to chat_message; do not duplicate preview fields on chat_conversation.',
+                'all: true tells MCP to send REST limit=0 and load all matching conversation rows.',
+                'This is a small bounded user inbox example. For larger inventories, prefer pagination even when RLS scopes the records.',
+                'Do not fetch messages for every conversation on initial list load; load messages after selecting a conversation.',
+            ],
+        },
+        {
+            name: 'Fetch one record by id',
+            code: `find_one_record({
+  tableName: "post",
+  id: "123",
+  fields: ["id", "title", "createdAt"]
+})
+
+// REST equivalent after inspecting metadata primary key:
+GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
+            notes: [
+                'There is no dynamic GET /<table>/<id> route.',
+                'Prefer MCP find_one_record because it resolves the primary key from live metadata.',
+                'If writing raw REST, inspect metadata first and use the real primary key field; do not assume id on every backend.',
+            ],
+        },
+        {
+            name: 'Count without loading all rows',
+            code: `query_table({
+  tableName: "chat_message_read",
+  fields: ["id"],
+  limit: 1,
+  meta: "filterCount",
+  filter: {
+    member: { id: { _eq: "<currentUserId>" } },
+    isRead: { _eq: false }
+  }
+})`,
+            notes: [
+                'Use meta=totalCount with no filter and meta=filterCount with a filter.',
+                'MCP count_records wraps this pattern for simple counts.',
+                'Do not fetch all rows only to count them.',
+            ],
+        },
+        {
+            name: 'Relation fields without deep',
+            code: `query_table({
+  tableName: "order",
+  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.',
+                'Treat order/customer as placeholders; the transferable idea is "show parent rows with a few scalar relation fields".',
+                'Do not add deep when fields alone can express the relation data you need.',
+            ],
+        },
+        {
+            name: 'Exclude large generated fields',
+            code: `query_table({
+  tableName: "enfyra_route_handler",
+  fields: ["-compiledCode"],
+  limit: 20
+})
+
+query_table({
+  tableName: "post",
+  fields: ["id", "-author.avatar"],
+  deep: {
+    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({
+  tableName: "order",
+  fields: ["id", "total"],
+  deep: {
+    items: {
+      fields: "id,quantity,product",
+      sort: "-createdAt",
+      limit: 20,
+      deep: {
+        product: { fields: "id,name,price" }
+      }
+    }
+  }
+})`,
+            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.',
+                'Use fields, never _fields, inside deep relation options.',
+                '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.',
+                'Support tickets and messages are illustrative. Apply this when a parent list must be ordered by child recency or child volume.',
+                'The aggregate field must be a real published, non-encrypted scalar field on the related table for user-facing APIs.',
+                'Do not use _max, _min, or _count on private relations or unpublished fields unless the endpoint intentionally exposes that fact.',
+                '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.
+GET /enfyra/integrations?filter={"api_token":{"_eq":"plaintext-token"}}
+
+// Good: store a separate non-secret lookup hash if lookup is needed.
+create_columns({
+  globalRulesAckKey: "<globalRulesAckKey from get_enfyra_required_knowledge>",
+  items: [
+    {
+      tableId: "<integrations_table_id>",
+      name: "api_token_lookup_sha256",
+      type: "varchar",
+      isNullable: false,
+      isPublished: false
+    }
+  ]
+})
+
+// In the create/update handler or pre-hook, hash plaintext before it is encrypted.
+if (@BODY.api_token) {
+  @BODY.api_token_lookup_sha256 = await @HELPERS.$crypto.sha256(@BODY.api_token)
+}
+
+// Lookup by the hash, never by the encrypted field.
+const lookup = await @HELPERS.$crypto.sha256(@BODY.api_token)
+const found = await #integrations.find({
+  filter: { api_token_lookup_sha256: { _eq: lookup } },
+  limit: 1
+})`,
+            notes: [
+                'isEncrypted values are encrypted at rest and decrypted after select.',
+                'Do not filter, sort, or deep-filter by encrypted fields.',
+                'Use a separate deterministic non-secret hash/lookup column when the product needs secret-derived lookup.',
+                'Do not ask clients to submit enc:v1: ciphertext.',
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=mcp-example-queries-deep.js.map

package/dist/lib/mcp-example-queries-deep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-example-queries-deep.js","sourceRoot":"","sources":["../../src/lib/mcp-example-queries-deep.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAC/B,KAAK,EAAE,+DAA+D;IACtE,OAAO,EAAE,+HAA+H;IACxI,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,8CAA8C;YACpD,IAAI,EAAE;;;;;GAKX;YACK,KAAK,EAAE;gBACL,wHAAwH;gBACxH,kGAAkG;gBAClG,kDAAkD;gBAClD,uHAAuH;aACxH;SACF;QACD;YACE,IAAI,EAAE,6CAA6C;YACnD,IAAI,EAAE;;;;GAIX;YACK,KAAK,EAAE;gBACL,yGAAyG;gBACzG,kGAAkG;gBAClG,mFAAmF;gBACnF,yHAAyH;gBACzH,kHAAkH;aACnH;SACF;QACD;YACE,IAAI,EAAE,wBAAwB;YAC9B,IAAI,EAAE;;;;;;;yEAO2D;YACjE,KAAK,EAAE;gBACL,8CAA8C;gBAC9C,oFAAoF;gBACpF,oHAAoH;aACrH;SACF;QACD;YACE,IAAI,EAAE,gCAAgC;YACtC,IAAI,EAAE;;;;;;;;;GASX;YACK,KAAK,EAAE;gBACL,wEAAwE;gBACxE,yDAAyD;gBACzD,2CAA2C;aAC5C;SACF;QACD;YACE,IAAI,EAAE,8BAA8B;YACpC,IAAI,EAAE;;;;;;;;;;GAUX;YACK,KAAK,EAAE;gBACL,8FAA8F;gBAC9F,+HAA+H;gBAC/H,sHAAsH;gBACtH,2EAA2E;aAC5E;SACF;QACD;YACE,IAAI,EAAE,gCAAgC;YACtC,IAAI,EAAE;;;;;;;;;;;;;;;;;;GAkBX;YACK,KAAK,EAAE;gBACL,+IAA+I;gBAC/I,0IAA0I;gBAC1I,4EAA4E;gBAC5E,kIAAkI;aACnI;SACF;QACD;YACE,IAAI,EAAE,6BAA6B;YACnC,IAAI,EAAE;;;;;;;;;;;;;GAaX;YACK,KAAK,EAAE;gBACL,uGAAuG;gBACvG,yHAAyH;gBACzH,wFAAwF;gBACxF,+EAA+E;gBAC/E,8LAA8L;gBAC9L,+HAA+H;gBAC/H,4CAA4C;gBAC5C,uEAAuE;gBACvE,0DAA0D;gBAC1D,kFAAkF;aACnF;SACF;QACD;YACE,IAAI,EAAE,+CAA+C;YACrD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;iCAsBmB;YACzB,KAAK,EAAE;gBACL,sJAAsJ;gBACtJ,wFAAwF;gBACxF,gIAAgI;gBAChI,qHAAqH;gBACrH,kIAAkI;gBAClI,4FAA4F;gBAC5F,2IAA2I;aAC5I;SACF;QACD;YACE,IAAI,EAAE,wCAAwC;YAC9C,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BX;YACK,KAAK,EAAE;gBACL,sEAAsE;gBACtE,0DAA0D;gBAC1D,0GAA0G;gBAC1G,kDAAkD;aACnD;SACF;KACF;CACF,CAAC"}

package/dist/lib/mcp-example-schema-relations.d.ts

@@ -0,0 +1,9 @@
+export declare const schemaRelationsExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};

package/dist/lib/mcp-example-schema-relations.js

@@ -0,0 +1,148 @@
+export const schemaRelationsExamples = {
+    title: 'Tables, columns, relations, cascade, and indexes',
+    useWhen: 'Use when creating or changing persisted data models.',
+    examples: [
+        {
+            name: 'Bulk schema creation with one-item-or-many arrays',
+            code: `// 0. First call get_schema_design_context and get_enfyra_required_knowledge.
+// 1. create_tables is always native-array-shaped. One table = one item.
+create_tables({
+  globalRulesAckKey: "<globalRulesAckKey>",
+  items: [
+    {
+      name: "app_lookup",
+      columns: [
+        { name: "name", type: "varchar", isNullable: false },
+        { name: "slug", type: "varchar", isNullable: false },
+        { name: "description", type: "text", isNullable: true }
+      ],
+      uniques: [["slug"]]
+    },
+    {
+      name: "app_primary_record",
+      columns: [
+        { name: "title", type: "varchar", isNullable: false },
+        { name: "summary", type: "text", isNullable: true },
+        { name: "amount", type: "float", isNullable: false, defaultValue: "0" },
+        { name: "status", type: "varchar", isNullable: false, defaultValue: "draft" },
+        { name: "metadata", type: "simple-json", isNullable: true }
+      ],
+      relations: [
+        { propertyName: "lookup", type: "many-to-one", targetTable: "app_lookup", isNullable: true, onDelete: "SET NULL" },
+        { propertyName: "owner", type: "many-to-one", targetTable: "enfyra_user", isNullable: false, onDelete: "CASCADE" }
+      ],
+      indexes: [["status", "createdAt"], ["lookup", "status"]]
+    },
+    {
+      name: "app_participation",
+      columns: [
+        { name: "status", type: "varchar", isNullable: false, defaultValue: "active" },
+        { name: "score", type: "float", isNullable: false, defaultValue: "0" }
+      ],
+      relations: [
+        { propertyName: "record", type: "many-to-one", targetTable: "app_primary_record", isNullable: false, onDelete: "CASCADE" },
+        { propertyName: "actor", type: "many-to-one", targetTable: "enfyra_user", isNullable: false, onDelete: "CASCADE" }
+      ],
+      uniques: [["record", "actor"]],
+      indexes: [["status", "createdAt"]]
+    }
+  ]
+})
+
+// 2. create_records is also native-array-shaped. One row = one item.
+create_records({
+  tableName: "app_primary_record",
+  globalRulesAckKey: "<globalRulesAckKey>",
+  records: [
+    {
+      title: "<display title>",
+      amount: 29.99,
+      status: "active",
+      lookup: "<app_lookup_id>",
+      owner: "<enfyra_user_id>"
+    }
+  ]
+})`,
+            notes: [
+                'All mutation tools are plural envelopes. Pass native arrays, with one item in the array for a single mutation.',
+                'create_tables creates tables/columns first, then creates requested relations after all batch tables exist, so target table ordering is handled by the tool.',
+                'Do not declare id, _id, createdAt, or updatedAt columns; Enfyra manages them automatically.',
+                'When a unique/index group uses relation propertyName values, declare those relations in the same table item or add the constraint later with update_tables after the relations exist.',
+                'Use live column types from get_schema_design_context. Prefer float for decimal-like money/ratings unless live metadata explicitly supports decimal.',
+                'Do not create lookupId, owner_id, actorId, or recordIds scalar fields for normalized relationships. Use relations and write relation propertyName values.',
+                'A unique pair such as record+actor already creates the indexed unique lookup; keep those fields out of indexes.',
+            ],
+        },
+        {
+            name: 'Bulk add columns and relations after initial schema',
+            code: `create_columns({
+  globalRulesAckKey: "<globalRulesAckKey>",
+  items: [
+    {
+      tableId: "<enfyra_user_table_id>",
+      name: "emailVerifiedAt",
+      type: "datetime",
+      isNullable: true,
+      isPublished: true
+    },
+    {
+      tableId: "<integration_secret_table_id>",
+      name: "value",
+      type: "text",
+      isNullable: false,
+      isPublished: false,
+      isEncrypted: true
+    }
+  ]
+})
+
+create_relations({
+  globalRulesAckKey: "<globalRulesAckKey>",
+  items: [
+    {
+      sourceTableId: "chat_conversation",
+      targetTableId: "chat_message",
+      propertyName: "lastMessage",
+      type: "many-to-one",
+      isNullable: true,
+      onDelete: "SET NULL"
+    }
+  ]
+})`,
+            notes: [
+                'create_columns/create_relations run items sequentially through the schema queue.',
+                'Use relation property names only. Never provide fkCol, sourceColumn, targetColumn, or junction column names.',
+                'Use inversePropertyName only when a concrete parent detail/deep/count/sort use case needs the reverse traversal.',
+                'Use isEncrypted=true for encryption at rest. Add isUpdatable=false separately only when the field should be immutable.',
+            ],
+        },
+        {
+            name: 'Bulk update and destructive preview',
+            code: `update_tables({
+  globalRulesAckKey: "<globalRulesAckKey>",
+  items: [
+    { tableId: "<table_id>", graphqlEnabled: true },
+    { tableId: "<settings_table_id>", isSingleRecord: true }
+  ]
+})
+
+// Destructive tools preview first.
+delete_columns({
+  items: [{ tableId: "<table_id>", columnId: "<column_id>" }]
+})
+
+// Apply only after explicit user approval.
+delete_columns({
+  globalRulesAckKey: "<globalRulesAckKey>",
+  confirm: true,
+  items: [{ tableId: "<table_id>", columnId: "<column_id>" }]
+})`,
+            notes: [
+                'update_tables/update_columns/update_records reject ambiguous duplicate ids where applicable and run sequentially.',
+                'delete_tables/delete_columns/delete_relations/delete_records return previews unless confirm=true.',
+                'Schema tools serialize internally; do not parallelize schema mutation tool calls.',
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=mcp-example-schema-relations.js.map

package/dist/lib/mcp-example-schema-relations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-example-schema-relations.js","sourceRoot":"","sources":["../../src/lib/mcp-example-schema-relations.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACnC,KAAK,EAAE,kDAAkD;IACzD,OAAO,EAAE,sDAAsD;IAC/D,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,mDAAmD;YACzD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DX;YACK,KAAK,EAAE;gBACL,gHAAgH;gBAChH,6JAA6J;gBAC7J,6FAA6F;gBAC7F,uLAAuL;gBACvL,qJAAqJ;gBACrJ,2JAA2J;gBAC3J,iHAAiH;aAClH;SACF;QACD;YACE,IAAI,EAAE,qDAAqD;YAC3D,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCX;YACK,KAAK,EAAE;gBACL,kFAAkF;gBAClF,8GAA8G;gBAC9G,kHAAkH;gBAClH,wHAAwH;aACzH;SACF;QACD;YACE,IAAI,EAAE,qCAAqC;YAC3C,IAAI,EAAE;;;;;;;;;;;;;;;;;;GAkBX;YACK,KAAK,EAAE;gBACL,mHAAmH;gBACnH,mGAAmG;gBACnG,mFAAmF;aACpF;SACF;KACF;CACF,CAAC"}

package/dist/lib/mcp-example-websocket.d.ts

@@ -0,0 +1,9 @@
+export declare const websocketExamples: {
+    title: string;
+    useWhen: string;
+    examples: {
+        name: string;
+        code: string;
+        notes: string[];
+    }[];
+};